diff --git a/docs/09-部署运维/deploy/09-NAS部署指南-群晖Cloudflare.md b/docs/09-部署运维/deploy/09-NAS部署指南-群晖Cloudflare.md deleted file mode 100644 index 41604c8..0000000 --- a/docs/09-部署运维/deploy/09-NAS部署指南-群晖Cloudflare.md +++ /dev/null @@ -1,438 +0,0 @@ -# 群晖 NAS + Cloudflare Tunnel + 未认证企微 部署指南 - -> **适用范围**：阶段一功能测试 -> **目标域名**：`itdesk.amanzac.com` -> **最后更新**：2026-06-07 - ---- - -## 架构总览 - -``` - HTTPS HTTP -员工手机 ──────────→ Cloudflare Edge ──────────→ cloudflared ──→ nginx:80 -(企微H5) (自动SSL+CDN) Tunnel 容器 │ - ┌────┴────┐ - │ 路由分发 │ - └────┬────┘ - ┌──────┼──────┐ - │ │ │ - /itdesk/ /itagent/ /api/ - H5员工端 坐席工作台 后端 -``` - -**关键特点**： -- ✅ 无需公网 IP -- ✅ 无需 SSL 证书（Cloudflare 自动处理） -- ✅ 无需开放 NAS 端口 -- ✅ 未认证企微可正常使用 OAuth2 + 消息 API - ---- - -## §1 前置条件检查清单 - -| # | 条件 | 你的状态 | 说明 | -|---|------|---------|------| -| 1 | 群晖 NAS（DS220+ 及以上） | ✅ 已确认 | 需支持 Docker（ARM 机型需确认镜像兼容） | -| 2 | Container Manager 已安装 | ✅ 已确认 | 套件中心安装 | -| 3 | Cloudflare 账号 | ✅ 已确认 | 免费版即可 | -| 4 | 域名 `amanzac.com` 已托管 Cloudflare | ✅ 已确认 | DNS 管理 → Cloudflare | -| 5 | 企微管理后台权限 | ✅ 已确认 | 需配置自建应用 | -| 6 | SSH 访问 NAS | ⬜ 待确认 | 需开启 SSH 以执行 docker compose 命令 | - ---- - -## §2 Cloudflare Tunnel 配置 - -### 2.1 创建 Tunnel - -1. 登录 [Cloudflare Zero Trust](https://one.dash.cloudflare.com/) -2. 左侧菜单 → **Networks** → **Tunnels** -3. 点击 **Create a tunnel** -4. 选择 **Cloudflared** 类型 -5. 输入 Tunnel 名称，如 `itdesk-nas` -6. 点击 **Save tunnel** - -### 2.2 获取 Tunnel Token - -创建完成后，页面会显示安装命令，其中包含 Token： - -```bash -# 示例安装命令 -cloudflared service install eyJhIjoiNjM1... -# ^^^^^^^^^^^^ -# 这就是 Token -``` - -**复制这个 Token**，后面要填到 `.env` 文件中。 - -### 2.3 配置 Tunnel 路由（Public Hostname） - -在 Tunnel 创建页面，配置 **Public Hostname**： - -| 字段 | 填写 | 说明 | -|------|------|------| -| Subdomain | `itdesk` | 前缀 | -| Domain | `amanzac.com` | 你的域名 | -| Type | `HTTP` | 容器内是 HTTP | -| URL | `nginx` | Docker 容器名（同一网络内） | - -> ⚠️ 注意：Type 选 **HTTP**（不是 HTTPS），因为 cloudflared 和 nginx 之间走的是容器内网 HTTP。SSL 由 Cloudflare Edge 终止。 - -点击 **Save tunnel**。 - -### 2.4 验证 DNS 记录 - -Cloudflare 会自动创建一条 CNAME 记录： -- `itdesk.amanzac.com` → `cfargotunnel.com` - -可在 Cloudflare Dashboard → DNS → Records 中确认。 - ---- - -## §3 项目文件部署到 NAS - -### 3.1 上传项目文件 - -**方式一：Git Clone（推荐）** - -如果 NAS 上有 Git： -```bash -# SSH 登录 NAS -ssh admin@NAS_IP - -# 创建项目目录 -mkdir -p /volume1/docker/wecom-it-desk -cd /volume1/docker/wecom-it-desk - -# 克隆项目 -git clone <你的仓库地址> . -``` - -**方式二：SCP 上传** - -从开发机上传构建好的文件： -```powershell -# 在 Windows PowerShell 中执行 -# 上传核心文件（不含 node_modules 和 .git） -scp -r "D:\资料\03-项目开发\wecom_it_smart_desk\docker-compose.nas.yml" admin@NAS_IP:/volume1/docker/wecom-it-desk/ -scp -r "D:\资料\03-项目开发\wecom_it_smart_desk\.env.nas" admin@NAS_IP:/volume1/docker/wecom-it-desk/ -scp -r "D:\资料\03-项目开发\wecom_it_smart_desk\nginx" admin@NAS_IP:/volume1/docker/wecom-it-desk/ -scp -r "D:\资料\03-项目开发\wecom_it_smart_desk\backend" admin@NAS_IP:/volume1/docker/wecom-it-desk/ -scp -r "D:\资料\03-项目开发\wecom_it_smart_desk\frontend-h5\dist" admin@NAS_IP:/volume1/docker/wecom-it-desk/frontend-h5/dist/ -scp -r "D:\资料\03-项目开发\wecom_it_smart_desk\frontend-agent\dist" admin@NAS_IP:/volume1/docker/wecom-it-desk/frontend-agent/dist/ -``` - -**方式三：群晖 File Station** - -把构建产物打包成 zip，通过 File Station 上传到 `/docker/wecom-it-desk/` 然后解压。 - -### 3.2 配置环境变量 - -```bash -cd /volume1/docker/wecom-it-desk - -# 复制模板 -cp .env.nas .env - -# 编辑 .env 文件 -vi .env -``` - -**必须修改的项**： - -```bash -# 1. 填入 Cloudflare Tunnel Token（从 §2.2 获取） -CF_TUNNEL_TOKEN=eyJhIjoiNjM1... # ← 替换为你的实际 Token - -# 2. 修改数据库密码 -POSTGRES_PASSWORD=YourStrongPassword123! # ← 替换为强密码 - -# 3. 如果 NAS 能访问公司内网 Dify，填入 Dify 配置 -# 如果不能访问，留空即可（AI 功能暂不可用，不影响阶段一） -DIFY_API_URL= -DIFY_API_KEY= -``` - -### 3.3 构建前端（如果还没构建） - -前端需要先在开发机（Windows）上构建，再上传 dist/ 目录： - -```powershell -# 在 Windows 开发机上 -cd "D:\资料\03-项目开发\wecom_it_smart_desk" - -# 构建坐席端 -cd frontend-agent -npm install -npx vite build - -# 构建 H5 员工端 -cd ..\frontend-h5 -npm install -npx vite build -``` - -构建产物在 `frontend-agent/dist/` 和 `frontend-h5/dist/` 中。 - ---- - -## §4 启动服务 - -### 4.1 SSH 登录 NAS 启动 - -```bash -# SSH 登录 NAS -ssh admin@NAS_IP - -# 进入项目目录 -cd /volume1/docker/wecom-it-desk - -# 启动所有容器（5 个容器） -docker compose -f docker-compose.nas.yml up -d - -# 等待约 30 秒，检查状态 -docker compose -f docker-compose.nas.yml ps -``` - -**预期输出**： - -| 容器名 | 状态 | 说明 | -|--------|------|------| -| wecom_it_cloudflared | Running | Cloudflare Tunnel | -| wecom_it_nginx | Up (healthy) | 反向代理 | -| wecom_it_backend | Up | FastAPI 后端 | -| wecom_it_postgres | Up (healthy) | PostgreSQL | -| wecom_it_redis | Up (healthy) | Redis | - -### 4.2 验证服务 - -```bash -# 1. 内网验证（在 NAS 上执行） -curl http://localhost:18080/api/health -# 预期输出: {"status":"ok","service":"wecom-it-smart-desk"} - -# 2. 内网验证前端 -curl http://localhost:18080/itdesk/health -# 预期输出: healthy - -# 3. 公网验证（从任意有网络的设备） -curl https://itdesk.amanzac.com/api/health -# 预期输出: {"status":"ok","service":"wecom-it-smart-desk"} - -# 4. 浏览器访问 -# H5 员工端: https://itdesk.amanzac.com/itdesk/ -# 坐席工作台: https://itdesk.amanzac.com/itagent/ -``` - -### 4.3 常用运维命令 - -```bash -# 查看日志 -docker compose -f docker-compose.nas.yml logs -f backend # 后端日志 -docker compose -f docker-compose.nas.yml logs -f cloudflared # Tunnel 日志 -docker compose -f docker-compose.nas.yml logs -f nginx # Nginx 日志 - -# 重启某个服务 -docker compose -f docker-compose.nas.yml restart backend - -# 停止所有服务 -docker compose -f docker-compose.nas.yml down - -# 更新并重启（代码更新后） -docker compose -f docker-compose.nas.yml up -d --build -``` - ---- - -## §5 企微自建应用配置 - -### 5.1 创建自建应用 - -1. 登录 [企微管理后台](https://work.weixin.qq.com/wework_admin/frame) -2. **应用管理** → **自建** → **创建应用** -3. 填写： - - 应用名称：`智能IT支持服务台` - - 应用logo：上传一个图标 - - 可见范围：选择测试部门/人员 - -### 5.2 配置网页授权（OAuth2） - -在应用详情页 → **网页授权及JS-SDK**： - -| 配置项 | 填写 | 说明 | -|--------|------|------| -| 可信域名 | `itdesk.amanzac.com` | OAuth2 回调域名 | - -> **验证方式**：Cloudflare Tunnel 已提供 HTTPS，下载企微提供的验证文件，放到 `frontend-h5/dist/` 根目录后重新构建。 - -### 5.3 配置应用主页 - -在应用详情页 → **应用主页**： - -``` -https://itdesk.amanzac.com/itdesk/ -``` - -员工点击企微中的应用入口，直接打开 H5 页面。 - -### 5.4 配置接收消息（回调 URL） - -在应用详情页 → **接收消息** → **设置API接收**： - -| 配置项 | 填写 | 说明 | -|--------|------|------| -| URL | `https://itdesk.amanzac.com/api/wecom/callback` | 企微消息推送地址 | -| Token | `wAqMCP` | 与 .env 中 WECOM_TOKEN 一致 | -| EncodingAESKey | `KQY3cEsBc3rdi3xua9rPd5WxH8kYOhyASzWZQf75aJS` | 与 .env 中一致 | - -> 点击保存时，企微会向 URL 发送验证请求，后端必须正常响应才能保存成功。 - -### 5.5 修改 AI 机器人转人工链接 - -在现有 AI 机器人的 Dify 工作流中，将转人工关键字触发的链接从： - -``` -旧链接：https://work.weixin.qq.com/XXXX（员工服务入口） -``` - -改为： - -``` -新链接：https://itdesk.amanzac.com/itdesk/ -``` - -> 这样员工点击转人工链接后，会跳转到 H5 自建应用页面（而非企微员工服务窗口）。 - ---- - -## §6 阶段一功能测试清单 - -### 6.1 基础连通性测试 - -| # | 测试项 | 方法 | 预期结果 | 状态 | -|---|--------|------|---------|------| -| 1 | Cloudflare Tunnel 连通 | 浏览器访问 `https://itdesk.amanzac.com/` | 页面正常加载 | ⬜ | -| 2 | 后端 API 健康 | 浏览器访问 `https://itdesk.amanzac.com/api/health` | 返回 `{"status":"ok"}` | ⬜ | -| 3 | H5 员工端页面 | 浏览器访问 `https://itdesk.amanzac.com/itdesk/` | H5 页面渲染 | ⬜ | -| 4 | 坐席工作台页面 | 浏览器访问 `https://itdesk.amanzac.com/itagent/` | 工作台页面渲染 | ⬜ | - -### 6.2 OAuth2 登录测试 - -| # | 测试项 | 方法 | 预期结果 | 状态 | -|---|--------|------|---------|------| -| 5 | OAuth2 静默授权 | 在企微内点击应用入口 | H5 页面自动登录，显示员工身份 | ⬜ | -| 6 | 身份识别 | 授权后查看 H5 页面 | 显示当前用户姓名/工号 | ⬜ | - -### 6.3 坐席工作台测试 - -| # | 测试项 | 方法 | 预期结果 | 状态 | -|---|--------|------|---------|------| -| 7 | 会话列表 | 坐席登录工作台 | 显示进行中的会话 | ⬜ | -| 8 | 聊天窗口 | 点击某个会话 | 显示完整对话记录 | ⬜ | -| 9 | 发送消息 | 坐席输入文本发送 | 消息发送成功 | ⬜ | -| 10 | 快速回复 | 点击快速回复面板 | 三级导航正常，模板可填入 | ⬜ | - -### 6.4 端到端流程测试 - -| # | 测试项 | 方法 | 预期结果 | 状态 | -|---|--------|------|---------|------| -| 11 | AI 对话 → 转人工 | 员工与 AI 对话，触发转人工关键字 | 推送 H5 链接 | ⬜ | -| 12 | 员工点击 H5 链接 | 点击推送的链接 | 跳转到 H5 页面，自动登录 | ⬜ | -| 13 | 坐席收到会话 | 员工进入 H5 后 | 坐席工作台出现新会话 | ⬜ | -| 14 | 坐席回复 | 坐席使用快速回复 | 员工 H5 页面显示回复 | ⬜ | -| 15 | 企微通知 | 坐席回复后 | 员工收到企微应用消息通知 | ⬜ | - ---- - -## §7 故障排查 - -### 7.1 Cloudflare Tunnel 连不上 - -```bash -# 检查 cloudflared 容器日志 -docker compose -f docker-compose.nas.yml logs cloudflared - -# 常见错误： -# ERR error="failed to connect to Cloudflare edge" -# → 检查 Token 是否正确 -# → 检查 NAS 是否能访问外网 -``` - -### 7.2 企微回调验证失败 - -```bash -# 检查后端是否收到回调请求 -docker compose -f docker-compose.nas.yml logs backend | grep callback - -# 常见原因： -# 1. Token / EncodingAESKey 与 .env 不一致 -# 2. 后端回调路由路径不对（应为 /api/wecom/callback） -# 3. Nginx 反代配置未正确转发 -``` - -### 7.3 OAuth2 授权失败 - -``` -常见原因： -1. 可信域名未配置或未验证 → 企微管理后台检查 -2. redirect_uri 与可信域名不匹配 → 检查回调 URL -3. CorpID 不正确 → 检查 .env 中的 WECOM_CORP_ID -``` - -### 7.4 容器状态异常 - -```bash -# 查看所有容器状态 -docker compose -f docker-compose.nas.yml ps - -# 查看特定容器详细日志 -docker compose -f docker-compose.nas.yml logs --tail 100 backend - -# 重启所有容器 -docker compose -f docker-compose.nas.yml restart - -# 完全重建（代码更新后） -docker compose -f docker-compose.nas.yml down -docker compose -f docker-compose.nas.yml up -d --build -``` - ---- - -## §8 与正式部署的区别 - -| 维度 | NAS 部署（测试） | 正式部署 | -|------|----------------|---------| -| 域名 | `itdesk.amanzac.com` | `it-dataquery.dc.servyou-it.com` | -| 内网穿透 | Cloudflare Tunnel | 公司内网直连 | -| HTTPS | Cloudflare 自动 | Nginx + 公司 CA 证书 | -| 数据库密码 | 测试密码 | 强密码 + 审计 | -| AI 引擎 | 可能不可用（Dify 在内网） | 可用 | -| 员工数 | 测试人员（<10人） | 全公司 | -| 企业微信认证 | 未认证（200人上限） | 已认证 | -| 数据持久化 | Docker Volume | K8s PVC / 独立 PG 集群 | - ---- - -## 附录 A：Cloudflare Tunnel 原理简述 - -``` - 传统方式 Cloudflare Tunnel - ┌─────────────────┐ ┌─────────────────┐ -互联网 ────→ │ 开放端口 + 公网IP │ 互联网 ────→ │ Cloudflare Edge │ - │ + SSL 证书 │ │ (自动HTTPS) │ - │ + DDNS/域名解析 │ └────────┬────────┘ - └─────────────────┘ │ - ↑ │ Tunnel（长连接） - │ │ - ┌─────────────────┐ ┌─────────────────┐ - │ NAS/服务器 │ cloudflared │ NAS/服务器 │ - │ (必须可达) │ ←──主动连接──→│ (无需开放端口) │ - └─────────────────┘ └─────────────────┘ - -优势： -1. 无需公网 IP — cloudflared 主动外连，不需要入站端口 -2. 无需 SSL 证书 — Cloudflare Edge 自动处理 HTTPS -3. 无需 DDNS — 域名始终指向 Cloudflare -4. 更安全 — 不暴露 NAS 任何端口到公网 -``` diff --git a/docs/09-部署运维/troubleshooting-故障排查/502-BadGateway-后端启动失败-20260705.md b/docs/09-部署运维/deploy/502-BadGateway-后端启动失败-20260705.md similarity index 100% rename from docs/09-部署运维/troubleshooting-故障排查/502-BadGateway-后端启动失败-20260705.md rename to docs/09-部署运维/deploy/502-BadGateway-后端启动失败-20260705.md diff --git a/docs/09-部署运维/troubleshooting-故障排查/WAF转发配置异常排查协助.md b/docs/09-部署运维/deploy/WAF转发配置异常排查协助.md similarity index 100% rename from docs/09-部署运维/troubleshooting-故障排查/WAF转发配置异常排查协助.md rename to docs/09-部署运维/deploy/WAF转发配置异常排查协助.md diff --git a/docs/09-部署运维/troubleshooting-故障排查/蓝绿部署指南.md b/docs/09-部署运维/deploy/蓝绿部署指南.md similarity index 100% rename from docs/09-部署运维/troubleshooting-故障排查/蓝绿部署指南.md rename to docs/09-部署运维/deploy/蓝绿部署指南.md diff --git a/docs/09-部署运维/troubleshooting-故障排查/通讯链路诊断方案.md b/docs/09-部署运维/deploy/通讯链路诊断方案.md similarity index 100% rename from docs/09-部署运维/troubleshooting-故障排查/通讯链路诊断方案.md rename to docs/09-部署运维/deploy/通讯链路诊断方案.md