Simon
44e77dcb0e
**重构前**（旧编号 02-11）： - docs/02-产品需求/ → 00 产品规划/PRD - docs/03-技术架构/ → 01-05 子目录散落 - docs/04-原型设计/ → 01-02 产品设计（HTML 原型） - docs/05-原型设计/ → screens/ - docs/06-测试素材/ → 02-E2E / 03-功能 / 04-版本测试 - docs/07-项目管理/ → 任务说明书/日报/计划 - docs/08-安全审计/ → 审计报告 - docs/09-堡垒运维/ → toolbox / deploy - docs/10-项目管理/ → 任务说明书（重复） - docs/11-历史归档/ → deploy-nas-archived **重构后**（新编号 00-07，语义化）： - docs/00-产品开发流程与文档管理规范.md - docs/00-版本迭代总览.md - docs/01-产品文档/ （PRD/原型/认证/会话/AI 服务/坐席/集成） - docs/02-技术文档/ （技术方案/架构图/重构记录/前端改造/实现配置） - docs/03-测试文档/ （E2E/功能用例/版本报告/缺陷单） - docs/04-运维文档/ （部署运维/运维指南） - docs/05-运营文档/ （品牌推广/用户手册） - docs/06-安全审计/ （审计报告） - docs/07-项目管理/ （任务说明书/日报/计划/看板） **净收益**： - 目录编号与产品文档管理规范对齐（按文档阶段 01-07 编号） - 消除 02-产品需求 与 10-项目管理 的编号重叠 - 子目录按文档类型分组（如 01-产品文档/00-产品规划、01-产品文档/01-认证与登录） - 把运维/安全/项目管理从 0X 散落改为 04/06/07 合计 494 文件 + 78495 行 / - 14076 行
321 lines
8.7 KiB
Markdown
321 lines
8.7 KiB
Markdown
# 企微智能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 端口访问来源（防火墙规则）
|