Simon
facc04aa65
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交 （5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。 一、docs 结构整改（整改 #14） 根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入， 随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录 树并存于 docs/，共 791 文件、双分类体系冲突。 修复动作： - b2 同名异主题文件改名迁移保全 9 个 - C 类 39 个孤立文件按主题正确归类 - A/B1 类 222 个重复文件删除（新结构已有内容副本） - 9 个旧独有空目录删除 - 270 处内部引用按 verified 映射改写 - 整改记录 #14 登记于 04-运维文档/部署运维 结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。 残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。 二、compose 双目录对齐（消除踩坑 A） - docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist 改为 src/frontend-*/dist（h5 / agent / admin / terminal） - docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/ - 效果：本地 docker compose up 不再把根目录 stale dist 挂回， 与线上一致，分叉隐患消除（已 docker compose config 校验通过） 防复发铁律： - 重构须提交；仓库修复须 git stash -u 或先 commit - 新结构须 git add 并提交，避免再次 untracked 复活 - H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
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 端口访问来源（防火墙规则）
|