simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ddebbe61a5f1512a66c39cf1cc2f0f0f71826365
wecom_it_smart_desk/docs/NAS部署指南.md
T

439 lines
14 KiB
Markdown
Raw Normal View History

chore: initial baseline with P0-safety .gitignore
2026-06-14 16:49:18 +08:00
# 群晖 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 任何端口到公网
```
Reference in New Issue Copy Permalink