simon/wecom_it_smart_desk

Fork 0

Files

T

Simon ca7c6d937a docs: 移动蓝绿部署指南到 troubleshooting 目录

2026-07-05 17:03:36 +08:00

13 KiB

Raw Blame History

智能IT服务系统运维手册

版本: v1.0 | 日期: 2026-07-04 | 维护人: 助理（小米） 目标读者: 运维工程师 / IT支持组

📖 关联文档:

README.md — 项目快速入门

01-项目总览与部署手册 — 完整架构设计

CHANGELOG.md — 版本变更概览

docs/archive/ — 历史版本详情

一、系统概述

1.1 系统架构

浏览器 ──→ itsupport.servyou.com.cn:443
                  │
                  ▼
         ┌─── nginx (容器) ───────────────┐
         │                                      │
         │  /itdesk/*  → H5 员工端 SPA    │
         │  /itagent/* → 坐席工作台 SPA   │
         │  /itadmin/* → 管理后台 SPA     │
         │  /itportal/* → Portal 选择页   │
         │  /api/*     → backend:8000     │
         │  /ws/*      → backend:8000 (WS)│
         │                                      │
         └──────────────┬───────────────────┘
                        │ 本机 Docker 网络
         ┌─────────────┼─────────────┐
         ▼             ▼             ▼
   ┌──────────┐ ┌──────────┐ ┌──────────┐
   │ backend  │ │ postgres │ │  redis   │
   │ :8000    │ │ :5432    │ │ :6379    │
   └──────────┘ └──────────┘ └──────────┘

1.2 组件清单

服务	镜像	端口	说明
nginx	nginx:alpine	443→80 (对外)	反向代理 + SSL
backend	自构建	8000 (内部)	FastAPI 后端
postgres	postgres:16	5432 (内部)	数据库
redis	redis:7	6379 (内部)	缓存 + Session

1.3 访问端点

端点	说明
`https://itsupport.servyou.com.cn/itdesk/`	H5 员工端
`https://itsupport.servyou.com.cn/itagent/`	坐席工作台
`https://itsupport.servyou.com.cn/itadmin/`	管理后台
`https://itsupport.servyou.com.cn/itportal/`	Portal 角色选择
`https://itsupport.servyou.com.cn/api/docs`	API Swagger 文档

二、环境信息

2.1 服务器信息

环境	IP	域名	用途
生产	10.90.5.110 (内网)	itsupport.servyou.com.cn	正式环境
运维入口	10.212.189.210:2222	-	堡垒机 SSH

2.2 关键配置

配置项	值
企微 CorpID	`ww...` (见 .env)
企微 AgentID	`1000xxx`
数据库	PostgreSQL 16
缓存	Redis 7
域名证书	`*.servyou.com.cn` (GeoTrust/DigiCert)

2.3 部署路径

/opt/wecom-it-desk/
├── docker-compose.yml
├── .env                    # 环境变量（不提交 Git）
├── backend/                 # 后端代码
├── frontend-h5/dist/       # H5 前端构建产物
├── frontend-agent/dist/    # 坐席前端构建产物
├── frontend-admin/dist/    # 管理后台构建产物
├── frontend-portal/dist/   # Portal 构建产物
├── nginx/                  # Nginx 配置
└── logs/                  # 日志目录

三、部署操作

3.1 部署流程概览

1. 打包代码 → 2. 上传服务器 → 3. 配置环境变量 → 4. 启动容器 → 5. 验证

3.2 打包命令（本地）

# 在项目根目录执行
cd D:\资料\03-项目开发\wecom_it_smart_desk

# 使用部署脚本打包
powershell -File deploy-server\build-package.ps1

# 或手动打包
tar czf deploy.tar.gz \
  backend/ frontend-h5/dist/ frontend-agent/dist/ \
  frontend-admin/dist/ frontend-portal/dist/ \
  nginx/ docker-compose.yml .env.production scripts/

3.3 上传到服务器

注意: 公司服务器只能通过堡垒机上传，无法直接从本地 scp

通过堡垒机上传到 /tmp/：
- 使用 SFTP 或 Web 界面上传到堡垒机

SSH 登录服务器：

# 堡垒机: sxn@10.212.189.210:2222
ssh sxn@10.90.5.110  # 跳转目标服务器

移动到目标目录：

mv /tmp/deploy.tar.gz /opt/wecom-it-desk/
cd /opt/wecom-it-desk/
tar xzf deploy.tar.gz

3.4 配置环境变量

# 创建环境配置
cp .env.production .env
vim .env  # 编辑真实配置

# 必填项：
# - WECOM_CORP_ID
# - WECOM_AGENT_ID
# - WECOM_SECRET
# - WECOM_TOKEN
# - WECOM_ENCODING_AES_KEY
# - POSTGRES_PASSWORD
# - REDIS_PASSWORD

3.5 启动服务

# 启动所有容器
docker compose up -d --build

# 或分步启动
docker compose up -d postgres redis  # 先启动基础服务
docker compose up -d backend        # 再启动后端
docker compose up -d nginx          # 最后启动前端

3.6 验证部署

# 1. 检查容器状态
docker compose ps
# 预期：4 个容器全部 Up/healthy

# 2. 健康检查
curl -ksI https://itsupport.servyou.com.cn/api/health

# 3. 各端点验证
curl -ksI https://itsupport.servyou.com.cn/itdesk/
curl -ksI https://itsupport.servyou.com.cn/itagent/
curl -ksI https://itsupport.servyou.com.cn/itadmin/
curl -ksI https://itsupport.servyou.com.cn/itportal/

四、日常运维

4.1 日常检查

# 每日必做检查
docker compose ps                          # 容器状态
docker compose logs --tail=50 backend       # 后端日志
docker compose logs --tail=50 nginx         # 前端日志
df -h                                       # 磁盘空间

4.2 常用操作

操作	命令
重启后端	`docker compose restart backend`
重启 nginx	`docker compose restart nginx`
查看实时日志	`docker compose logs -f backend`
进入后端容器	`docker compose exec backend bash`
查看容器资源	`docker stats`

4.3 监控指标

指标	阈值	说明
CPU 使用率	< 80%	主机层面
内存使用率	< 80%	主机层面
磁盘使用率	< 70%	主机层面
容器状态	全部 Up	docker compose ps
API 响应时间	P95 < 500ms	业务层面

4.4 日志位置

服务	日志命令
后端	`docker compose logs backend`
Nginx	`docker compose logs nginx`
PostgreSQL	`docker compose logs postgres`
Redis	`docker compose logs redis`

五、故障排查

5.1 快速诊断流程

1. 检查容器状态 → 2. 检查端口连通 → 3. 检查日志 → 4. 定位根因

5.2 常见问题

问题 1: 访问返回 500 错误

# 1. 检查容器状态
docker compose ps

# 2. 检查后端日志
docker compose logs --tail=100 backend

# 3. 检查 nginx 日志
docker compose logs --tail=100 nginx

# 4. 检查前端 dist 是否存在
ls /opt/wecom-it-desk/frontend-h5/dist/
docker compose exec nginx ls /usr/share/nginx/html/itdesk/

问题 2: API 返回连接错误

# 1. 检查后端是否启动
docker compose ps backend

# 2. 检查后端健康端点
curl http://localhost:8000/health

# 3. 检查数据库连接
docker compose exec backend python -c "from app.database import get_db; print('OK')"

问题 3: WebSocket 连接失败

# 1. 检查 nginx WebSocket 配置
docker compose exec nginx cat /etc/nginx/nginx.conf | grep -A10 ws

# 2. 检查 WS 端点
curl -I http://localhost:8000/ws/test

# 3. 检查 Redis（WS 依赖）
docker compose exec redis redis-cli ping

问题 4: 企微工作台打开页面显示"加载失败"或无限加载（2026-07-04）

现象：员工通过企业微信-工作台-IT支持服务访问，显示加载失败或一直转圈

排查步骤：

# 1. 检查容器状态
docker ps

# 2. 检查 nginx 是否正确加载配置
docker exec wecom_it_nginx nginx -t

# 3. 检查前端页面访问
curl -I http://localhost/itdesk/

# 4. 检查 API 代理
curl -I http://localhost/api/h5/health

# 5. 查看后端日志（查找 NameError）
docker logs --tail=50 wecom_it_backend | grep -i error

根因 1：nginx 容器未正确挂载 nginx.conf 配置文件

表现：API 请求返回 404，nginx 错误日志显示 open() "/usr/share/nginx/html/api/xxx" failed
解决：重建 nginx 容器，确保正确挂载配置

# 重建 nginx 容器
docker rm -f wecom_it_nginx
docker run -d --name wecom_it_nginx \
  --network wecom-it-desk_it-desk-internal \
  -p 80:80 -p 443:443 \
  -v /opt/wecom-it-desk/html:/usr/share/nginx/html:ro \
  -v /opt/wecom-it-desk/nginx/nginx.conf:/etc/nginx/nginx.conf:ro \
  -v /opt/wecom-it-desk/nginx/ssl:/etc/nginx/ssl:rw \
  --restart unless-stopped nginx:1.27-alpine

# 重新加载配置
docker exec wecom_it_nginx nginx -s reload

根因 2：后端 h5.py 代码存在 NameError

表现：后端日志显示 NameError: name '_require_wework_ua' is not defined
原因：生产服务器代码未同步最新版本
解决：复制最新代码并重启后端

# 复制最新代码
docker cp /opt/wecom-it-desk/backend/app/api/h5.py wecom_it_backend:/app/app/api/h5.py

# 重启后端
docker restart wecom_it_backend

5.3 完整诊断脚本

详细诊断脚本见：docs/deploy/服务器端跑诊断.md

# 一键诊断
bash /opt/wecom-it-desk/diagnose-500.sh

六、回滚方案

6.1 快速回滚

# 停止当前版本
docker compose down

# 恢复上一个版本（需提前备份）
# 方法1: 从 Git 拉取上一个 commit
git checkout {上一个commit-hash}
# 重新构建部署

# 方法2: 保留上一个版本的部署包
cd /opt/wecom-it-desk-backup
tar xzf deploy-v0.x.x.tar.gz
docker compose up -d

6.2 回滚检查清单

确认上一个版本可用
通知相关人员
记录当前版本问题
执行回滚
验证回滚后功能正常
发送回滚通知

七、备份恢复

7.1 备份策略

备份对象	方法	频率	保留
PostgreSQL	pg_dump	每日凌晨	7 天
Redis	redis-cli SAVE	每日凌晨	7 天
配置文件	tar 归档	每次部署	4 个版本
日志文件	logrotate	每周	4 周

7.2 备份命令

# 备份数据库
docker compose exec postgres pg_dump -U postgres wecom_it > /tmp/backup_$(date +%Y%m%d).sql

# 备份 Redis
docker compose exec redis redis-cli SAVE
cp /var/lib/docker/volumes/wecom-it-desk_redis_data/_data/dump.rdb /tmp/redis_$(date +%Y%m%d).rdb

# 备份配置
tar czf /tmp/config_$(date +%Y%m%d).tar.gz /opt/wecom-it-desk/.env /opt/wecom-it-desk/nginx/

7.3 恢复命令

# 恢复数据库
docker compose exec -T postgres psql -U postgres wecom_it < backup_20260701.sql

# 恢复 Redis
docker compose exec -T redis redis-cli FLUSHALL
# 停止服务后复制 dump.rdb 到数据目录

八、应急响应

8.1 事件分级

等级	场景	响应时间
🔴 P0	鉴权漏洞 / 数据泄露 / 服务全停	5 min
🟠 P1	功能故障 / 单服务降级	30 min
🟡 P2	性能问题 / UI 异常	4 h
🟢 P3	体验优化	1 周

8.2 P0 应急流程

立即止血

# 1. 关闭外网访问
sudo iptables -A INPUT -p tcp --dport 443 -j DROP

# 2. 停可疑服务
docker compose stop backend

# 3. 保留现场（不删文件）
docker compose logs backend > /tmp/incident-backend.log
docker compose logs nginx > /tmp/incident-nginx.log

通知

微信/电话通知项目负责人
邮件通知：wecom-it-desk-incident@servyou-it.com

8.3 应急联系

角色	联系人
项目负责人	宋献
运维	IT 支持组
企微技术支持	企微客服

附录

版本历史

版本	日期	更新内容
v1.0	2026-07-04	初始版本，整合部署/运维/故障排查文档

文档	说明
`docs/01-项目总览/01-项目总览与部署手册-20260704.md`	完整项目背景与架构设计
`docs/RELEASE_NOTES_v0.7.1.md`	版本发布说明
`docs/SOPs/SOP-004-应急响应.md`	详细应急响应流程
`docs/deploy/快速诊断-500-错误.md`	500 错误排查指南
`docs/09-部署运维/deploy/04-部署修复记录-20260613.md`	历史修复记录

13 KiB Raw Blame History Unescape Escape