wecom_it_smart_desk/docs/09-部署运维/01-智能IT服务系统运维手册-20260704.md

智能IT服务系统运维手册

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

📖 关联文档:

• README.md — 项目快速入门
• 01-项目总览与部署手册 — 完整架构设计
• CHANGELOG.md — 版本变更概览
• docs/archive/ — 历史版本详情

---

目录

1. 系统概述
2. 环境信息
3. 部署操作
4. 日常运维
5. 故障排查
6. 回滚方案
7. 备份恢复
8. 应急响应

---

一、系统概述

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

1. 通过堡垒机上传到 /tmp/：

   • 使用 SFTP 或 Web 界面上传到堡垒机

2. SSH 登录服务器：

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

3. 移动到目标目录：

   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

---

五、故障排查

本章已整合至标准故障排查手册：09-部署运维/00-标准故障排查手册.md

手册涵盖：三步隔离法、错误码速查（500/502/503/403/422/网络挂起）、诊断脚本与命令、案例库（含 Redis urlparse 挂起、502、各类修复记录）、端到端验证完成标准（含"宣布修复前必须提供真实浏览器截图"硬规则）。

日常排故请直接打开该手册，本文档不再重复故障排查细节。

---

六、回滚方案

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	详细应急响应流程
09-部署运维/00-标准故障排查手册.md	标准故障排查手册（故障排查唯一入口）

---

维护说明: 本文档由助理（小米）维护，随每次发布更新。 如有更新，请同步更新本文档的版本号和日期。