wecom_it_smart_desk/docs/01-项目总览/01-智能IT服务系统运维手册-20260704.md

# 智能IT服务系统运维手册

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

> **📖 关联文档**: 
> - [README.md](../README.md) — 项目快速入门
> - [01-项目总览与部署手册.md](./01-项目总览与部署手册.md) — 完整架构设计
> - [CHANGELOG.md](../CHANGELOG.md) — 版本变更概览
> - [docs/archive/](./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 打包命令（本地）

```bash
# 在项目根目录执行
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 登录服务器**：
   ```bash
   # 堡垒机: sxn@10.212.189.210:2222
   ssh sxn@10.90.5.110  # 跳转目标服务器
   ```

3. **移动到目标目录**：
   ```bash
   mv /tmp/deploy.tar.gz /opt/wecom-it-desk/
   cd /opt/wecom-it-desk/
   tar xzf deploy.tar.gz
   ```

### 3.4 配置环境变量

```bash
# 创建环境配置
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 启动服务

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

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

### 3.6 验证部署

```bash
# 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 日常检查

```bash
# 每日必做检查
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 错误

```bash
# 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 返回连接错误

```bash
# 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 连接失败

```bash
# 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支持服务访问，显示加载失败或一直转圈

**排查步骤**：

```bash
# 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 容器，确保正确挂载配置

```bash
# 重建 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`
- 原因：生产服务器代码未同步最新版本
- 解决：复制最新代码并重启后端

```bash
# 复制最新代码
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
# 一键诊断
bash /opt/wecom-it-desk/diagnose-500.sh
```

---

## 六、回滚方案

### 6.1 快速回滚

```bash
# 停止当前版本
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 备份命令

```bash
# 备份数据库
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 恢复命令

```bash
# 恢复数据库
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 应急流程

#### 立即止血

```bash
# 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-项目总览与部署手册.md` | 完整项目背景与架构设计 |
| `docs/RELEASE_NOTES_v0.7.1.md` | 版本发布说明 |
| `docs/SOPs/SOP-004-应急响应.md` | 详细应急响应流程 |
| `docs/deploy/快速诊断-500-错误.md` | 500 错误排查指南 |
| `docs/IT服务台部署修复记录-2026-06-13.md` | 历史修复记录 |

---

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