wecom_it_smart_desk/docs/DEPLOY_NAS.md

# 企微IT智能服务台 — 远程服务器部署指南（预生产）

> **预生产环境**：本系统与 IT 数据查询平台部署在**不同主机**。正式环境将迁移到 K8s。

## 部署架构

```
浏览器 ──→ it-dataquery.dc.servyou-it.com:80
                    │
                    ▼
           ┌─── nginx (本系统主机) ──────────────────────┐
           │                                            │
           │  /itdesk/*  → H5 员工端 SPA               │
           │  /itagent/* → 坐席工作台 SPA              │
           │  /api/*     → backend:8000 (FastAPI)       │
           │  /ws/*      → backend:8000 (WebSocket)     │
           │  /*         → 远程代理到数据平台主机 IP    │  ← 跨主机
           │                                            │
           └──────────────┬─────────────────────────────┘
                          │ 本机 Docker 网络
            ┌─────────────┼─────────────┐
            ▼             ▼             ▼
      ┌──────────┐  ┌──────────┐  ┌──────────┐
      │ backend  │  │ postgres │  │  redis   │
      │ :8000    │  │ :5432    │  │ :6379    │
      └──────────┘  └──────────┘  └──────────┘
```

## 网络互联

预生产环境中，数据平台在独立主机，**不需要 Docker 网络互联**。Nginx 通过远程 IP 直接反代数据平台：

```
本系统主机 (Docker)                     数据平台主机
  ┌──────────────────┐                  ┌─────────────────┐
  │  nginx ──────────┼── HTTP 反代 ──→ │  数据平台 :80    │
  │   │              │   远程 IP        │                  │
  │   ▼              │                  └─────────────────┘
  │  backend:8000    │
  │  postgres:5432   │
  │  redis:6379      │
  └──────────────────┘
```

## 前置条件

- 服务器已安装 Docker + Docker Compose
- IT 数据查询平台已部署运行
- 有 SSH 登录权限

## 部署步骤

### 1. 配置数据平台反代地址

预生产环境中，数据平台在**独立主机**。部署前，必须将 nginx 配置中的数据平台上游地址改为实际 IP。

编辑 `nginx/nginx.conf`：

```nginx
# 将 DATAQUERY_HOST 替换为数据平台主机的实际 IP:端口
upstream dataquery {
    server 10.80.0.86:80;   # ← 改为数据平台实际 IP
}
```

> 不再需要创建 `it-platform-net` —— Docker 网络无法跨主机互联。nginx 通过 HTTP 直接反代到远程 IP。

### 3. 上传部署包

在本地（Windows）执行：

```bash
# 方式 A：使用 deploy.sh 打包
bash scripts/deploy.sh --pack
scp it-smart-desk-*.tar.gz user@server:/opt/

# 方式 B：手动打包
tar czf deploy.tar.gz \
  backend/ frontend-h5/dist/ frontend-agent/dist/ \
  nginx/ docker-compose.yml .env.production scripts/
scp deploy.tar.gz user@server:/opt/it-smart-desk/
```

### 4. 服务器上解压和配置

```bash
ssh user@server
cd /opt/it-smart-desk
tar xzf it-smart-desk-*.tar.gz

# 创建环境配置（填入真实企微凭证）
cp .env.production .env
vim .env
```

`.env` 必填项：

| 配置项 | 说明 | 获取位置 |
|--------|------|---------|
| `WECOM_CORP_ID` | 企业ID | 企微管理后台 > 我的企业 |
| `WECOM_AGENT_ID` | 应用AgentId | 企微管理后台 > 应用管理 |
| `WECOM_SECRET` | 应用Secret | 企微管理后台 > 应用管理 |
| `WECOM_TOKEN` | 回调Token | 企微管理后台 > 接收消息 |
| `WECOM_ENCODING_AES_KEY` | 回调AES密钥 | 企微管理后台 > 接收消息 |
| `POSTGRES_PASSWORD` | 数据库密码 | 自定义强密码 |

### 5. 启动服务

```bash
bash scripts/deploy.sh
```

这会自动执行：检查前置条件 → 构建后端镜像 → 启动所有容器

### 6. 验证部署

```bash
# 检查容器状态
docker compose ps

# 健康检查
curl http://localhost:18080/itdesk/health

# 查看 H5 员工端
curl -I http://localhost:18080/itdesk/

# 查看坐席工作台
curl -I http://localhost:18080/itagent/

# 查看后端 API
curl http://localhost:18080/api/docs
```

浏览器验证：

| 地址 | 预期 |
|------|------|
| `http://it-dataquery.dc.servyou-it.com/itdesk/` | H5 员工咨询页面 |
| `http://it-dataquery.dc.servyou-it.com/itagent/` | 坐席工作台登录页 |
| `http://it-dataquery.dc.servyou-it.com/` | IT 数据查询平台（不变） |
| `http://it-dataquery.dc.servyou-it.com/api/docs` | FastAPI Swagger 文档 |

## 两种网络接入方式

### 方式 A：数据平台 nginx 反代到本项目 nginx（推荐）

数据平台的 nginx 配置添加：

```nginx
# IT 智能服务台路由
location /itdesk/ {
    proxy_pass http://wecom_it_nginx:80/itdesk/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}
location /itagent/ {
    proxy_pass http://wecom_it_nginx:80/itagent/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}
location /api/ {
    proxy_pass http://wecom_it_nginx:80/api/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}
location /ws/ {
    proxy_pass http://wecom_it_nginx:80/ws/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}
```

此方式下本项目 nginx 不暴露 80 端口，docker-compose.yml 的 `ports` 可以删除。

### 方式 B：本项目 nginx 直接监听 80 端口

如果数据平台没有自己的 nginx，或者想用本项目的 nginx 统一管理：

1. 停止数据平台的端口映射
2. 本项目 nginx 的 80 端口直接对外
3. nginx.conf 中的 `location /` 反代到数据平台容器

## 常见问题

### Q: nginx 启动失败，报 `host not found in upstream "dataquery"`
A: `nginx/nginx.conf` 中的 `DATAQUERY_HOST` 未替换为数据平台实际 IP。编辑 nginx.conf，将占位符改为实际 IP:端口。

### Q: 访问 /itdesk/ 返回 404
A: 检查前端 dist 是否正确挂载：
```bash
docker exec wecom_it_nginx ls -la /usr/share/nginx/html/itdesk/
```

### Q: API 返回 CORS 错误
A: 检查 `.env` 中的 `CORS_ORIGINS` 是否包含 `http://it-dataquery.dc.servyou-it.com`

### Q: 数据库迁移失败
A: 查看 backend 日志：
```bash
docker compose logs backend
```
如果 PostgreSQL 未就绪，等 30 秒后重启 backend：
```bash
docker compose restart backend
```

## 更新部署

只需更新变更的部分：

```bash
# 仅更新前端
bash scripts/deploy.sh --build
docker compose restart nginx

# 仅更新后端
docker compose build backend
docker compose up -d backend

# 全量更新
bash scripts/deploy.sh --down
bash scripts/deploy.sh
```