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：

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

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

3. 上传部署包

在本地（Windows）执行：

# 方式 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. 服务器上解压和配置

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 scripts/deploy.sh

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

6. 验证部署

# 检查容器状态
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 配置添加：

# 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 是否正确挂载：

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 日志：

docker compose logs backend

如果 PostgreSQL 未就绪，等 30 秒后重启 backend：

docker compose restart backend

更新部署

只需更新变更的部分：

# 仅更新前端
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