wecom_it_smart_desk/docs/04-运维文档/部署运维/DEPLOY-GUIDE.md

企微智能IT支持服务台 — 服务器部署指南

目标服务器：10.90.5.110（Linux）
域名：itsupport.servyou.com.cn
更新日期：2026-06-12

---

一、前置条件

• 服务器可访问内网（火绒 huorong.oa.servyou-it.com、Dify yw-dify.dc.servyou-it.com）
• 服务器已安装 Docker + Docker Compose
• 域名 itsupport.servyou.com.cn DNS 已解析到 10.90.5.110（或先用 IP 访问）

---

二、安装 Docker（如已安装跳过）

2.1 检查是否已安装

docker --version        # 应显示 Docker version 24.x+
docker compose version  # 应显示 Docker Compose version v2.x+

如果已安装，跳到第三步。

2.2 安装 Docker（CentOS/RHEL）

# 1. 卸载旧版本（如有）
sudo yum remove -y docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine

# 2. 安装 yum 工具
sudo yum install -y yum-utils

# 3. 添加 Docker 官方仓库（国内用阿里云镜像加速）
sudo yum-config-manager --add-repo https://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo

# 4. 安装 Docker Engine + Compose 插件
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 5. 启动 Docker 并设置开机自启
sudo systemctl start docker
sudo systemctl enable docker

# 6. 验证安装
docker --version
docker compose version

2.3 安装 Docker（Ubuntu/Debian）

# 1. 卸载旧版本
sudo apt-get remove -y docker docker-engine docker.io containerd runc

# 2. 安装依赖
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

# 3. 添加 Docker GPG 密钥
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# 4. 添加仓库
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 5. 安装
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 6. 启动
sudo systemctl start docker
sudo systemctl enable docker

# 7. 验证
docker --version
docker compose version

2.4（可选）非 root 用户使用 Docker

# 将当前用户加入 docker 组，避免每次 sudo
sudo usermod -aG docker $USER
# 重新登录生效
newgrp docker

---

三、上传部署包

3.1 在服务器创建目录

sudo mkdir -p /opt/wecom-it-desk
sudo chown $USER:$USER /opt/wecom-it-desk

3.2 上传文件

在本地 Windows 用 SCP/SFTP 上传部署包：

# 方法1：用 scp 命令（Git Bash 或 PowerShell）
scp it-smart-desk-server-deploy.zip user@10.90.5.110:/opt/wecom-it-desk/

# 方法2：用 WinSCP / FileZilla 图形化工具上传

3.3 解压

cd /opt/wecom-it-desk
unzip it-smart-desk-server-deploy.zip
# 解压后目录结构：
# /opt/wecom-it-desk/
# ├── docker-compose.yml
# ├── .env
# ├── nginx/
# │   └── nginx.conf
# ├── backend/
# │   ├── Dockerfile
# │   ├── app/
# │   ├── alembic/
# │   ├── alembic.ini
# │   └── requirements.txt
# ├── frontend-h5/dist/
# ├── frontend-agent/dist/
# └── frontend-admin/dist/

---

四、修改配置

4.1 编辑环境变量

cd /opt/wecom-it-desk
vim .env

必须确认的配置项：

配置项	当前值	说明
WECOM_CORP_ID	wwa8c87970b2011f41	企微企业ID
WECOM_AGENT_ID	1000133	企微应用AgentId
WECOM_SECRET	EOtQsl...	企微应用Secret
MOCK_LOGIN_ENABLED	true	测试阶段用 true，正式上线改为 false
DIFY_API_KEY	http://...	Dify AI 服务 Key
POSTGRES_PASSWORD	wecom_secret_2026	数据库密码（首次初始化后不可改）

4.2 确认域名解析

# 测试域名是否指向本机
ping itsupport.servyou.com.cn
# 如果还没配 DNS，可以先在 .env 中把 CORS_ORIGINS 改为：
# CORS_ORIGINS=http://10.90.5.110

4.3 部署铁律（2026-07-17 新增，踩坑记录）

以下 3 条均为生产事故复盘得出的硬性规则，部署/变更时必须遵守：

铁律 1：backend 必须 --workers 1（WS 推送单 worker 约束）

ws_manager 是进程内单例，AI 后台任务与员工 WebSocket 连接若落在不同 worker 进程，broadcast_to_employees 会静默丢失约 50% 消息。

# ❌ 危险：docker-compose-override.yml 会自动合并覆盖主文件！
# 若 override 中存在 --workers 2，主文件的 --workers 1 会被覆盖
docker compose -f docker-compose.yml -f docker-compose-override.yml config | grep workers
# 必须输出 1。如为 2，删除或修改 override 文件

铁律 2：.env 变量不会自动传入容器，必须在 environment: 显式声明

backend/.dockerignore 排除了全部 .env 文件，生产容器配置 100% 来自 docker-compose.yml 的 environment: 部分。新增任何环境变量（尤其是 DIFY_NATIVE_BASE_URL、DIFY_NATIVE_API_KEY），必须：

# docker-compose.yml
backend:
  environment:
    - DIFY_NATIVE_BASE_URL=${DIFY_NATIVE_BASE_URL:-}
    - DIFY_NATIVE_API_KEY=${DIFY_NATIVE_API_KEY:-}

验证：容器内执行 env | grep DIFY_NATIVE 非空；后端日志出现「调用 Dify 原生 API」而非「回退到代理路径」。 （事故记录：2026-07-13 两次因未声明导致 P0 故障；WECOM_SSO_CALLBACK_BASE 未声明导致扫码登录崩溃）

铁律 3：Redis 密码含特殊字符必须 URL 编码

REDIS_URL 中密码含 @ # ! 时未编码 → 解析出错误的 host → 连接挂起 → 登录 502。编码规则：@→%40、#→%23、!→%21。改密码时须同步更新 compose 中 requirepass 与 REDIS_URL 两处。

---

五、启动服务

5.1 首次启动

cd /opt/wecom-it-desk

# 构建后端镜像 + 启动所有容器
docker compose up -d --build

# 首次启动需要 2-3 分钟（下载镜像 + 构建后端 + 数据库迁移）

5.2 查看启动状态

# 查看所有容器状态（应全部 healthy/running）
docker compose ps

# 查看实时日志（Ctrl+C 退出）
docker compose logs -f

# 只看后端日志
docker compose logs -f backend

预期输出（docker compose ps）：

NAME                STATUS          PORTS
wecom_it_postgres   Up (healthy)    5432/tcp
wecom_it_redis      Up (healthy)    6379/tcp
wecom_it_backend    Up (healthy)    8000/tcp
wecom_it_nginx      Up (healthy)    0.0.0.0:80->80/tcp

5.3 验证服务

# 1. 健康检查
curl http://localhost/itdesk/health
# 预期：healthy

# 2. 后端 API
curl http://localhost/api/health
# 预期：{"status":"ok"}

# 3. 浏览器访问
# H5 员工端：http://itsupport.servyou.com.cn/itdesk/
# 坐席工作台：http://itsupport.servyou.com.cn/itagent/
# 管理后台：http://itsupport.servyou.com.cn/itadmin/

---

六、常用运维命令

cd /opt/wecom-it-desk

# 重启所有服务
docker compose restart

# 只重启后端（代码更新后）
docker compose restart backend

# 查看某个容器的日志
docker compose logs -f --tail=100 backend

# 进入后端容器调试
docker compose exec backend /bin/sh

# 停止所有服务
docker compose down

# 停止并删除数据卷（⚠️ 会清空数据库！）
docker compose down -v

# 查看磁盘使用
docker system df

---

七、代码更新流程

当有新代码需要部署时：

# 1. 上传新的部署包，覆盖旧文件
# 2. 重新构建并启动
cd /opt/wecom-it-desk
docker compose up -d --build

# 如果只有前端更新，不需要重建后端镜像：
docker compose up -d --no-deps --build nginx

---

八、故障排查

问题	排查命令	常见原因
容器反复重启	docker compose logs backend	数据库连接失败、环境变量缺失
页面空白	docker compose logs nginx	前端 dist 目录为空或路径错误
API 404	curl http://localhost:8000/health	后端未启动或 nginx proxy 配置错误
数据库连接失败	docker compose logs postgres	POSTGRES_PASSWORD 与 DATABASE_URL 不一致
端口被占用	sudo lsof -i :80	其他服务占用 80 端口

---

九、安全建议（后续）

• 配置 HTTPS（Nginx 反代 + 证书，或使用反向代理）
• 修改默认数据库密码
• 关闭 Mock 登录（MOCK_LOGIN_ENABLED=false）
• 限制 80 端口访问来源（防火墙规则）