Simon
439 lines
14 KiB
Markdown
439 lines
14 KiB
Markdown
# 群晖 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 任何端口到公网
|
||
```
|