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

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

> **📖 关联文档**: 
> - [README.md](../README.md) — 项目快速入门
> - [01-项目总览与部署手册](./01-项目总览与部署手册-20260704.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 前端缓存刷新

部署前端后，企微/H5 应用可能因为浏览器缓存显示旧版本。可用以下方式强制刷新：

| 场景 | 操作方法 |
|------|----------|
| **企微应用内** | `Ctrl + Shift + R`（强制刷新，清除缓存） |
| **普通浏览器** | `Ctrl + F5` 或 `Ctrl + Shift + R` |
| **iOS 企微** | 长按应用卡片 → 删除 → 重新从工作台添加 |
| **完全清除** | 清除浏览器缓存后重新访问 |

> **注意**：企微应用（webview）的缓存机制与普通浏览器不同，普通 F5 刷新可能无效，必须使用 `Ctrl + Shift + R`。

### 4.4 监控指标

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

### 4.5 日志位置

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

---

## 五、故障排查

> **本章已整合至标准故障排查手册**：[04-运维文档/部署运维/00-标准故障排查手册.md](../04-运维文档/部署运维/00-标准故障排查手册.md)
>
> 手册涵盖：三步隔离法、错误码速查（500/502/503/403/422/网络挂起）、诊断脚本与命令、案例库（含 Redis urlparse 挂起、502、各类修复记录）、端到端验证完成标准（含"宣布修复前必须提供真实浏览器截图"硬规则）。
>
> **日常排故请直接打开该手册**，本文档不再重复故障排查细节。

---

## 六、回滚方案

### 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-项目总览/01-项目总览与部署手册-20260704.md` | 完整项目背景与架构设计 |
| `docs/RELEASE_NOTES_v0.7.1.md` | 版本发布说明 |
| `docs/SOPs/SOP-004-应急响应.md` | 详细应急响应流程 |
| `04-运维文档/部署运维/00-标准故障排查手册.md` | 标准故障排查手册（故障排查唯一入口）|

---

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