wecom-ai-assistant/docs/cloudflared-setup.md

使用 Cloudflare Tunnel 设置公网域名

Cloudflare Tunnel (cloudflared) 是 Cloudflare 提供的免费内网穿透服务，相比 ngrok 的优势：

• ✅ 提供固定的免费域名（不会每次重启都变化）
• ✅ 免费且稳定
• ✅ 支持 HTTPS（自动配置 SSL 证书）

---

一、安装 cloudflared

Windows 安装方法

方法 1：使用 Scoop（推荐）

# 安装 Scoop（如果还没有）
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

# 安装 cloudflared
scoop install cloudflared

方法 2：使用 Chocolatey

# 安装 Chocolatey（如果还没有）
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# 安装 cloudflared
choco install cloudflared

方法 3：手动下载（推荐用于快速测试）

1. 访问发布页面：https://github.com/cloudflare/cloudflared/releases
2. 下载最新版本：
   • 找到最新的发布版本（例如：2026.1.2）
   • 下载 Windows 64位版本：cloudflared-windows-amd64.exe
   • 或下载 MSI 安装包：cloudflared-windows-amd64.msi（自动安装到系统）
3. 使用方式：
   • 方式 A（直接使用）：将 cloudflared-windows-amd64.exe 重命名为 cloudflared.exe，放到项目目录或任意目录
   • 方式 B（添加到 PATH）：将文件放到 PATH 环境变量中的目录（如 C:\Windows\System32），这样可以在任何地方使用 cloudflared 命令
   • 方式 C（MSI 安装）：双击 cloudflared-windows-amd64.msi 安装，会自动添加到系统 PATH

最新版本下载链接（直接下载）：

• Windows 64位 EXE：https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.exe
• Windows 64位 MSI：https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.msi

---

二、快速启动（无需登录，临时使用）

2.1 启动 Tunnel

# 在项目根目录运行
cloudflared tunnel --url http://localhost:8000

输出示例：

2025-02-05T10:00:00Z INF +--------------------------------------------------------------------------------------------+
2025-02-05T10:00:00Z INF |  Your quick Tunnel has been created! Visit it at:                                        |
2025-02-05T10:00:00Z INF |  https://abc123-def456-ghi789.trycloudflare.com                                           |
2025-02-05T10:00:00Z INF +--------------------------------------------------------------------------------------------+

2.2 复制公网 URL

从输出中复制 https://xxx.trycloudflare.com，这就是你的公网域名。

注意：

• 这个 URL 在本次运行期间是固定的
• 关闭 cloudflared 后，URL 会失效
• 每次重新启动会生成新的 URL

2.3 配置企业微信回调

在企微后台配置回调 URL：

https://你的cloudflared域名.trycloudflare.com/api/wecom/callback

例如：https://abc123-def456-ghi789.trycloudflare.com/api/wecom/callback

---

三、使用固定域名（推荐，需要 Cloudflare 账号）

3.1 登录 Cloudflare

cloudflared tunnel login

这会打开浏览器，选择你的域名（如果没有域名，可以跳过，使用免费域名）。

3.2 创建命名 Tunnel

# 创建名为 wecom-callback 的 tunnel
cloudflared tunnel create wecom-callback

3.3 配置 Tunnel

创建配置文件 ~/.cloudflared/config.yml（Windows 路径：C:\Users\你的用户名\.cloudflared\config.yml）：

tunnel: wecom-callback
credentials-file: C:\Users\你的用户名\.cloudflared\<tunnel-id>.json

ingress:
  - hostname: wecom-callback.your-domain.com  # 你的域名（如果有）
    service: http://localhost:8000
  - service: http_status:404

如果没有域名，使用免费域名：

tunnel: wecom-callback
credentials-file: C:\Users\你的用户名\.cloudflared\<tunnel-id>.json

ingress:
  - service: http://localhost:8000

3.4 启动 Tunnel

cloudflared tunnel run wecom-callback

---

四、后台运行（Windows）

方法 1：使用 PowerShell 后台任务

# 启动后台任务
Start-Process -NoNewWindow cloudflared -ArgumentList "tunnel --url http://localhost:8000"

# 查看进程
Get-Process cloudflared

# 停止进程
Stop-Process -Name cloudflared

方法 2：创建 Windows 服务（固定域名方式）

# 安装为 Windows 服务
cloudflared service install

# 启动服务
net start cloudflared

# 停止服务
net stop cloudflared

# 卸载服务
cloudflared service uninstall

---

五、验证 Tunnel 是否工作

5.1 测试本地端点

# 测试本地服务
curl http://localhost:8000/api/health

# 应该返回：{"status":"up","service":"backend"}

5.2 测试公网端点

# 测试公网 URL（替换为你的 cloudflared URL）
curl https://你的域名.trycloudflare.com/api/health

# 应该返回：{"status":"up","service":"backend"}

---

六、完整测试流程

6.1 启动服务

# 终端 1：启动 Docker 服务
docker compose up -d

# 终端 2：启动 cloudflared
cloudflared tunnel --url http://localhost:8000

6.2 配置企微回调

1. 复制 cloudflared 提供的 URL（例如：https://abc123-def456-ghi789.trycloudflare.com）
2. 在企微后台配置回调 URL：https://abc123-def456-ghi789.trycloudflare.com/api/wecom/callback
3. 填写 Token 和 EncodingAESKey（与 .env 一致）
4. 点击保存

6.3 验证 GET 校验

# 查看后端日志
docker compose logs backend -f

# 应该看到：
# INFO: wecom verify success {"trace_id": "...", "echostr_length": 43}

6.4 测试消息回调

1. 在企业微信中发送消息
2. 查看后端日志确认收到消息和发送回复
3. 在企业微信中验证收到回复

---

七、常见问题

问题 1：cloudflared 连接失败

解决方案：

• 检查本地服务是否运行：docker compose ps
• 检查端口是否正确：netstat -an | findstr 8000
• 检查防火墙是否阻止了 cloudflared

问题 2：企微回调失败

解决方案：

• 确保 cloudflared URL 可访问：在浏览器中打开 https://你的域名.trycloudflare.com/api/health
• 检查 Token 和 EncodingAESKey 是否一致
• 查看后端日志：docker compose logs backend | grep wecom

问题 3：cloudflared 进程意外退出

解决方案：

• 使用后台运行方式（见上方）
• 或使用 Windows 服务方式
• 检查 cloudflared 日志

---

八、与 ngrok 对比

特性	cloudflared	ngrok
免费域名	✅ 固定（登录后）	❌ 每次变化（免费版）
安装	简单	简单
稳定性	高	中等
速度	快	中等
推荐	⭐⭐⭐⭐⭐	⭐⭐⭐

---

九、快速命令参考

# 启动临时 tunnel
cloudflared tunnel --url http://localhost:8000

# 登录 Cloudflare
cloudflared tunnel login

# 创建命名 tunnel
cloudflared tunnel create wecom-callback

# 运行命名 tunnel
cloudflared tunnel run wecom-callback

# 列出所有 tunnel
cloudflared tunnel list

# 删除 tunnel
cloudflared tunnel delete wecom-callback

# 查看 tunnel 信息
cloudflared tunnel info wecom-callback

---

十、推荐配置（生产环境）

对于生产环境，建议：

1. 使用固定域名：登录 Cloudflare，创建命名 tunnel
2. 配置为 Windows 服务：确保自动启动
3. 监控 tunnel 状态：设置日志和告警

# 创建配置文件后，安装为服务
cloudflared service install

# 启动服务
net start cloudflared

# 查看服务状态
sc query cloudflared