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

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

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

---

## 一、前置条件

- [x] 服务器可访问内网（火绒 `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 检查是否已安装

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

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

### 2.2 安装 Docker（CentOS/RHEL）

```bash
# 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）

```bash
# 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

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

---

## 三、上传部署包

### 3.1 在服务器创建目录

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

### 3.2 上传文件

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

```powershell
# 方法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 解压

```bash
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 编辑环境变量

```bash
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 确认域名解析

```bash
# 测试域名是否指向本机
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% 消息**。

```bash
# ❌ 危险：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`），必须：

```yaml
# 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 首次启动

```bash
cd /opt/wecom-it-desk

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

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

### 5.2 查看启动状态

```bash
# 查看所有容器状态（应全部 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 验证服务

```bash
# 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/
```

---

## 六、常用运维命令

```bash
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
```

---

## 七、代码更新流程

当有新代码需要部署时：

```bash
# 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 端口访问来源（防火墙规则）