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

14 KiB
Raw Permalink Blame History

群晖 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
  2. 左侧菜单 → Networks → Tunnels
  3. 点击 Create a tunnel
  4. 选择 Cloudflared 类型
  5. 输入 Tunnel 名称，如 itdesk-nas
  6. 点击 Save tunnel

2.2 获取 Tunnel Token

创建完成后，页面会显示安装命令，其中包含 Token：

# 示例安装命令
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：

# SSH 登录 NAS
ssh admin@NAS_IP

# 创建项目目录
mkdir -p /volume1/docker/wecom-it-desk
cd /volume1/docker/wecom-it-desk

# 克隆项目
git clone <你的仓库地址> .

方式二：SCP 上传

从开发机上传构建好的文件：

# 在 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 配置环境变量

cd /volume1/docker/wecom-it-desk

# 复制模板
cp .env.nas .env

# 编辑 .env 文件
vi .env

必须修改的项：

# 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/ 目录：

# 在 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 启动

# 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 验证服务

# 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 常用运维命令

# 查看日志
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. 登录 企微管理后台
  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 连不上

# 检查 cloudflared 容器日志
docker compose -f docker-compose.nas.yml logs cloudflared

# 常见错误：
# ERR error="failed to connect to Cloudflare edge"
# → 检查 Token 是否正确
# → 检查 NAS 是否能访问外网

7.2 企微回调验证失败

# 检查后端是否收到回调请求
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 容器状态异常

# 查看所有容器状态
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 View Git Blame Copy Permalink