simon/wecom_it_smart_desk

Fork 0

Files

T

Simon fab75760e0 WIP-CHECKPOINT[auth-refactor]: 固化工程师崩溃前部分成果 + 同树其他未提交WIP（仅源码，不含密钥/二进制）-- 待重激活工程师续作

2026-07-07 21:52:11 +08:00

10 KiB

Raw Permalink 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`

五、故障排查

本章已整合至标准故障排查手册：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`	标准故障排查手册（故障排查唯一入口）

10 KiB Raw Permalink Blame History Unescape Escape

智能IT服务系统运维手册

目录

一、系统概述

1.1 系统架构

1.2 组件清单

1.3 访问端点

二、环境信息

2.1 服务器信息

2.2 关键配置

2.3 部署路径

三、部署操作

3.1 部署流程概览

3.2 打包命令（本地）

3.3 上传到服务器

3.4 配置环境变量

3.5 启动服务

3.6 验证部署

四、日常运维

4.1 日常检查

4.2 常用操作

4.3 监控指标

4.4 日志位置

五、故障排查

六、回滚方案

6.1 快速回滚

6.2 回滚检查清单

七、备份恢复

7.1 备份策略

7.2 备份命令

7.3 恢复命令

八、应急响应

8.1 事件分级

8.2 P0 应急流程

立即止血

通知

8.3 应急联系

附录

版本历史

相关文档

10 KiB

Raw Permalink Blame History