simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: initial baseline with P0-safety .gitignore

Browse Source
This commit is contained in:
Simon
2026-06-14 16:49:18 +08:00
commit 63262292d7
510 changed files with 146008 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/正式环境独立部署架构方案.md
+410
View File
@@ -0,0 +1,410 @@
# 智能IT助手 — 正式环境独立部署架构方案
> **版本**: v1.1 | **日期**: 2026-06-03 | **编制**: 宋献（IT支持组组长）
> **目标**: 以对现有正式环境影响最小、责任边界最清晰的方式，完成新系统正式环境部署
---
## 一、核心决策原则
基于以下四个约束条件，确立本次架构设计的决策原则：
| # | 约束 | 推导原则 |
|---|------|---------|
| 1 | 对现有正式环境架构影响最小 | **物理隔离 > 逻辑隔离**：能用独立资源就不用共享资源 |
| 2 | 避免后续上线/变更影响现有服务 | **独立Nginx入口**：变更新系统反代规则时不影响旧系统 |
| 3 | 减少服务影响和依赖 | **最小化外部依赖**：只依赖真正不可替代的外部服务 |
| 4 | 避免混搭导致责任不清 | **独立数据库 + 独立Redis**：不共享存储层，运维边界清晰 |
> **一句话总结**：新系统作为**独立服务单元**部署，与现有智能IT数据平台（Django）在物理资源层面完全解耦，仅通过 HTTP API 调用共享 AI 能力（Dify/RAGFlow/Qwen）。
---
## 二、与复用评估的关键修正
原复用评估（团队沟通文档第7章）建议了部分资源共享方案。基于上述独立部署原则，修正如下：
| 原复用建议 | 修正方案 | 理由 |
|-----------|---------|------|
| 同机部署于 10.80.0.86 | **申请独立服务器/VM** | 避免端口冲突、资源争抢、变更互相影响 |
| Redis 复用同实例（db=0/db=1） | **独立 Redis 容器** | db 号隔离不彻底（FLUSHDB 误操作、内存OOM互相影响） |
| 使用旧系统 Nginx | **独立 Nginx 容器** | 变更新系统反代配置时不影响旧系统路由 |
| 复用旧系统 PostgreSQL 实例 | **独立 PostgreSQL 容器** | 数据库是"责任边界"的核心——谁的数据谁负责 |
| SSL 复用现有证书 | **可复用**（Nginx 层读取同一证书文件） | 证书是静态文件，只读访问无耦合风险 |
**仍然保持的复用（零耦合）：**
| 资源 | 复用方式 | 耦合度 |
|------|---------|--------|
| 企微自建应用凭证 | 配置文件引用（同一个 CorpID/AgentID/Secret） | 零耦合（只读凭证） |
| Dify Workflow API | HTTP 调用 `yw-dify.dc.servyou-it.com` | 外部依赖（HTTP） |
| RAGFlow 知识库 | HTTP 调用 `10.80.0.85:8080` | 外部依赖（HTTP） |
| Qwen3-30B 大模型 | HTTP 调用 `10.80.0.49:5000` | 外部依赖（HTTP） |
| SSL 证书文件 | Nginx 挂载只读 | 零耦合（静态文件） |
---
## 三、资源申请清单
### 3.1 服务器
| 项目 | 申请内容 | 说明 |
|------|---------|------|
| 服务器数量 | **1 台 VM** | Docker Compose 单机部署，4 个容器运行在同一 Docker Engine |
| 最低配置 | 4C8G + 100GB SSD | 预留 2 年增长空间 |
| 推荐配置 | 8C16G + 200GB SSD | 考虑到 M2 阶段接入 AI 后的并发请求量 |
| 操作系统 | CentOS 7.9+ / Rocky Linux 8+ / Ubuntu 22.04 LTS | 公司标准镜像 |
| 网络域 | **OA 服务器网络** | 与现有 10.80.0.86 同域，办公网默认可达 |
| Docker | 预装 Docker Engine 24+ + Docker Compose v2 | 基础运行环境 |
**为什么不在旧服务器上部署？**
```
10.80.0.86（现状）:
├── Django 3.2（智能IT数据平台）—— 生产运行中
├── PostgreSQL 13（本地实例） —— 生产运行中
└── Redis 7 —— 生产运行中
│
│ ❌ 不推荐：新系统 FastAPI 同机部署
│ 风险1: 端口冲突（旧Django :8000, 新FastAPI也需要 :8000）
│ 风险2: 内存竞争（Python进程内存开销大）
│ 风险3: Docker 服务重启影响两个系统
│ 风险4: 变更新系统 Nginx 配置时可能影响旧系统
│
▼
新服务器（建议）:
├── Docker Engine
│ ├── wecom_it_nginx —— 独立 Nginx 容器
│ ├── wecom_it_backend —— FastAPI 后端
│ ├── wecom_it_postgres —— PostgreSQL 16
│ └── wecom_it_redis —— Redis 7
└── 完全不接触旧系统资源
```
### 3.2 域名
| 项目 | 申请内容 |
|------|---------|
| 域名 | `itdesk.dc.servyou-it.com`（建议） |
| 解析目标 | 新服务器 IP（OA 网络） |
| 用途 | Nginx 统一入口 + OAuth2 回调 + CORS |
> 备选域名：`itdesk-oa.servyou-it.com` 或沿用 `it-dataquery` 子域模式改为 `it-smartdesk`
### 3.3 防火墙/网络策略
| 方向 | 源 | 目标 | 端口 | 用途 |
|------|-----|------|------|------|
| 入站 | 办公网 | 新服务器 | 80/443 | 坐席浏览器访问工作台 |
| 入站 | 企微服务器 | 新服务器 | 443 | 企微消息回调 |
| 出站 | 新服务器 | `qyapi.weixin.qq.com` | 443 | 企微 API 调用 |
| 出站 | 新服务器 | `yw-dify.dc.servyou-it.com` | 443 | Dify AI 调用（M2） |
| 出站 | 新服务器 | `10.80.0.85` | 8080 | RAGFlow（M2） |
| 出站 | 新服务器 | `10.80.0.49` | 5000 | Qwen3-30B（M2） |
| 出站 | 新服务器 | NTP 服务器 | 123 | 时间同步 |
> **不需要开通**：新服务器 → 10.80.0.86（完全不需要访问旧系统）
---
## 四、架构设计
### 4.1 网络拓扑
```
┌────────────────────────────┐
│ 企微服务器（外部） │
│ qyapi.weixin.qq.com │
└──────────┬─────────────────┘
│ HTTPS :443
▼
┌──────────────── 办公网络 ────────────────────────────────┐
│ │
│ ┌──────────┐ ┌──────────────────────────┐ │
│ │ 坐席浏览器 │────────▶│ https://itdesk.dc. │ │
│ │ (内网) │ HTTPS │ servyou-it.com │ │
│ └──────────┘ └──────────┬───────────────┘ │
│ │ │
├────────────────── OA 服务器网络 ──┼───────────────────────┤
│ │ │
│ ┌───────▼──────────────┐ │
│ │ 新服务器 (Docker) │ │
│ │ │ │
│ │ ┌────────────────┐ │ │
│ │ │ Nginx :80/443 │ │ │
│ │ │ 独立容器 │ │ │
│ │ └───────┬────────┘ │ │
│ │ │ │ │
│ │ ┌───────▼────────┐ │ │
│ │ │ FastAPI :8000 │ │ │
│ │ │ 独立容器 │ │ │
│ │ └───┬───────┬────┘ │ │
│ │ │ │ │ │
│ │ ┌───▼──┐ ┌──▼───┐ │ │
│ │ │ PG16 │ │Redis7│ │ │
│ │ │独立容器│ │独立容器│ │ │
│ │ └──────┘ └──────┘ │ │
│ └──────────────────────┘ │
│ │ │
│ ┌────────▼──────────────┐ │
│ │ 现有 AI 服务（外部依赖）│ │
│ │ ├─ Dify (M2阶段调用) │ │
│ │ ├─ RAGFlow (M2调用) │ │
│ │ └─ Qwen3-30B (M2调用) │ │
│ └───────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────┐ │
│ │ 现有智能IT数据平台 (10.80.0.86) │ │
│ │ Django + PG13 + Redis │ │
│ │ ⚠️ 新系统不访问此服务器 │ │
│ └─────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘
```
### 4.2 容器拓扑
```
新服务器 Docker Engine
│
├── Docker Network: itdesk_net (bridge, internal)
│ │
│ ├── Container: wecom_it_postgres
│ │ Image: postgres:16-alpine
│ │ Volume: wecom_it_postgres_data
│ │ Port: 5432 (仅 itdesk_net 内部)
│ │
│ ├── Container: wecom_it_redis
│ │ Image: redis:7-alpine
│ │ Volume: wecom_it_redis_data
│ │ Port: 6379 (仅 itdesk_net 内部)
│ │
│ ├── Container: wecom_it_backend
│ │ Image: wecom-it-desk-backend:latest
│ │ Port: 8000 (仅 itdesk_net 内部)
│ │ Env: DATABASE_URL, REDIS_URL, WECOM_*
│ │ Healthcheck: GET /health
│ │
│ └── Container: wecom_it_nginx
│ Image: nginx:1.27-alpine
│ Port: 80:80, 443:443 (宿主机映射)
│ Volumes: nginx.conf:ro, 前端dist:ro, SSL:ro
│ Healthcheck: GET /health
│
└── Volumes (命名卷，持久化)
├── wecom_it_postgres_data
└── wecom_it_redis_data
```
### 4.3 关键隔离策略
| 隔离层面 | 方案 | 隔离效果 |
|---------|------|---------|
| **服务器级** | 独立 VM，不共用宿主机 | 挂了不影响旧系统 |
| **网络级** | Docker 内部网络 `itdesk_net`，PG/Redis 不暴露宿主机端口 | 外部无法直连数据库 |
| **存储级** | 独立命名卷，不共用 Volume | 数据完全隔离 |
| **域名级** | 独立子域名 + 独立 Nginx 容器 | 变更反代规则不影响旧系统 |
| **认证级** | JWT + 独立 Redis，不依赖旧系统 Session | 账户体系独立 |
| **依赖级** | 仅 HTTP 调用外部 AI 服务 | 外部服务故障只影响 M2 功能 |
---
## 五、与现有系统的交互边界
### 5.1 M1 阶段（当前）— 零交互
```
新系统 现有系统
┌─────────────┐ ┌─────────────────┐
│ 企微回调接收 │ │ 智能IT数据平台 │
│ 坐席工作台 │ ← 无交互 → │ (Django) │
│ 员工H5端 │ │ 数据查询/标注 │
│ PG16+Redis7 │ │ PG13+Redis │
└─────────────┘ └─────────────────┘
```
M1 阶段新系统和现有系统**完全无交互**，各自独立运行。
### 5.2 M2 阶段 — HTTP 只读调用
```
新系统 现有系统
┌─────────────┐ HTTP(只读) ┌─────────────────┐
│ FastAPI │─────┬──────────▶│ Dify Workflow │
│ │ │ │ (AI 回复) │
│ │ ├──────────▶│ RAGFlow │
│ │ │ │ (知识库检索) │
│ │ └──────────▶│ Qwen3-30B │
│ │ │ (大模型) │
│ │ HTTP(只读) │ │
│ │────────────────▶│ Dify DB (只读) │
│ │ 历史对话同步 │ 10.80.128.40 │
└─────────────┘ └─────────────────┘
```
M2 阶段新增的对接全部是 **HTTP 只读调用**，新系统不写任何数据到现有系统数据库。
### 5.3 M3 阶段 — 可选数据合并
```
M3 阶段（远期）:
├── 数据平台 → 可保留独立运行（零影响方案）
├── 或 → 新系统接管统计报表功能（需迁移历史数据）
└── 决策点：届时根据 M1/M2 运行效果评估
```
---
## 六、部署流程
### 6.1 部署前准备清单
| # | 事项 | 责任人 | 预计耗时 |
|---|------|--------|---------|
| 1 | 申请 OA 网络服务器 VM | 宋献 → 运维 | 1-3 天 |
| 2 | 申请域名 `itdesk.dc.servyou-it.com` | 宋献 → 运维 | 0.5 天 |
| 3 | 申请防火墙策略（见 §3.3） | 宋献 → 网络组 | 1-2 天 |
| 4 | 确认企微自建应用回调 URL | 宋献 | 即时 |
| 5 | 准备 SSL 证书（复用或新申请） | 宋献 → 运维 | 即时/1天 |
| 6 | 服务器安装 Docker + Compose | 运维/宋献 | 0.5 天 |
### 6.2 部署步骤
```
Step 1: 服务器就绪
├── SSH 登录新服务器
├── 确认 Docker Engine 版本 ≥ 24
├── 确认 Docker Compose v2 可用
└── 创建部署目录 /opt/wecom-it-desk/
Step 2: 代码部署
├── git clone 或 scp 项目到 /opt/wecom-it-desk/
├── cp .env.production .env
├── 编辑 .env 填入真实企微凭证
└── bash scripts/build.sh # 构建前端
Step 3: 启动服务
├── docker compose up -d
├── 等待 healthcheck 全部通过
├── docker compose ps # 确认 4 容器 running
└── curl http://localhost:8000/health # 确认 API 可用
Step 4: Nginx + HTTPS
├── 挂载 SSL 证书到 ./nginx/ssl/
├── 启用 nginx.conf 中 HTTPS 段
├── docker compose restart nginx
└── curl https://itdesk.dc.servyou-it.com/health
Step 5: 企微回调验证
├── 企微管理后台 → 自建应用 → 接收消息
├── URL: https://itdesk.dc.servyou-it.com/api/wecom/callback
├── Token + EncodingAESKey（与 .env 一致）
└── 点击「验证」→ 确认通过
Step 6: 冒烟测试
├── 员工企微发送消息 → 后端日志确认收到
├── 坐席登录工作台 → 看到新会话
├── 坐席回复 → 员工企微收到消息
└── 全部通过 → 上线完成
```
### 6.3 回滚方案
```
回滚命令（一条命令恢复）：
docker compose down # 停止新系统所有容器
# 旧系统不受任何影响（独立服务器，无共享资源）
问题定位期间：
docker compose logs -f backend # 查看后端日志
docker compose ps # 查看容器状态
```
---
## 七、运维边界与责任划分
### 7.1 责任矩阵
| 运维操作 | 新系统 | 旧系统 | 影响范围 |
|---------|--------|--------|---------|
| 重启 PostgreSQL | 仅影响新系统 | 不受影响 | 独立实例 |
| 重启 Redis | 仅影响新系统 | 不受影响 | 独立实例 |
| 修改 Nginx 配置 | 仅影响新系统路由 | 不受影响 | 独立容器 |
| 更新后端代码 | 仅影响新系统 | 不受影响 | 独立容器 |
| Docker 服务重启 | 仅影响新系统 | 不受影响 | 独立宿主机 |
| 企微应用配置变更 | **同时影响两个系统**（共用应用） | — | ⚠️ 唯一共享点 |
| Dify/RAGFlow/Qwen 故障 | 影响新系统 M2 功能 | 可能影响旧系统 | 外部依赖 |
> **唯一耦合点**：企微自建应用。变更应用配置（如 Secret 轮换、回调 URL 修改）需通知双方。
### 7.2 监控指标
```yaml
# 建议在新服务器上配置的基础监控
主机层面:
- CPU 使用率 < 80%
- 内存使用率 < 80%
- 磁盘使用率 < 70%
容器层面:
- docker compose ps 全部 "Up" 状态
- Nginx 健康检查: GET /health → 200
- Backend 健康检查: GET /health → 200
业务层面（后续接入）:
- 企微消息回调成功率 > 99%
- API 响应时间 P95 < 500ms
```
### 7.3 备份策略
| 备份对象 | 方法 | 频率 | 保留 |
|---------|------|------|------|
| PostgreSQL 数据 | `pg_dump` + 卷快照 | 每日凌晨 | 7 天 |
| Redis 数据 | `SAVE` + 复制 dump.rdb | 每日凌晨 | 7 天 |
| Docker 卷 | `docker run --rm -v wecom_it_postgres_data:/data -v $(pwd):/backup alpine tar czf /backup/pg_backup.tar.gz -C /data .` | 每周 | 4 周 |
---
## 八、风险矩阵
| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|---------|
| 新服务器申请被拒/延迟 | 中 | 部署延期 | 短期退化方案：使用旧服务器但严格端口分离+独立 compose |
| SSL 证书到期 | 低 | HTTPS 不可用 | 复用现有通配符证书（统一管理到期时间） |
| 企微应用配置变更导致双系统异常 | 低 | 双系统消息中断 | 建立变更通知机制，双方知晓 |
| Dify/RAGFlow 服务不可用 | 中 | M2 阶段 AI 功能不可用 | 降级：纯坐席模式仍可正常工作 |
| Docker 宿主机故障 | 低 | 新系统全宕 | Docker Compose 配置即代码，重建速度快 |
### 8.1 退化方案（如果申请不到新服务器）
```
短期退化方案（临时，不推荐长期使用）:
旧服务器 10.80.0.86 上:
├── 端口映射: Nginx 新容器用 81/444（避免与旧 Nginx 冲突）
├── 独立 compose 项目: docker compose -p itdesk up -d
├── 独立 Docker 网络: itdesk_net（不与 dbquery_net 混用）
└── 资源限制: 限制 backend 容器内存上限（--memory=2g）
从退化方案正式迁移到独立服务器时:
├── docker compose down
├── 复制卷数据到新服务器
├── 新服务器上 docker compose up -d
└── 修改域名解析 → 完成迁移
```
---
## 九、决策总结
| 决策项 | 选择 | 核心理由 |
|--------|------|---------|
| 部署服务器 | **独立 VM**（非 10.80.0.86） | 物理隔离 = 责任清晰 + 变更互不影响 |
| PostgreSQL | **独立容器**（pg:16-alpine） | 数据库是"责任边界"核心，绝不能共享 |
| Redis | **独立容器**（redis:7-alpine） | 避免误操作和 OOM 互相影响 |
| Nginx | **独立容器 + 独立子域名** | 变更反代规则不影响旧系统 |
| Docker 网络 | **独立 bridge 网络**（itdesk_net） | 不与 dbquery_net 互通 |
| 外部 AI 服务 | HTTP 只读调用 | 外部依赖合理复用，通过降级策略容错 |
| 企微应用凭证 | 配置文件复用 | 零耦合（只读凭证），唯一共享点 |
| SSL 证书 | 文件复用（只读挂载） | 静态文件，无耦合风险 |
> **一句话**：新系统是一个**独立的 Docker Compose 应用**，部署在**独立服务器**上，通过**独立域名**提供服务，与现有系统共享的只有企微应用凭证和 AI 服务的 HTTP 接口——这些都是外部资源，不算"系统混搭"。