Initial commit: 浼佷笟寰俊 AI 鏈哄櫒浜哄姪鐞?MVP

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-05 16:36:32 +08:00
commit 59275ed4dc
126 changed files with 9120 additions and 0 deletions
--- a/docs/cloudflared-setup.md
+++ b/docs/cloudflared-setup.md
@@ -0,0 +1,312 @@
+# 使用 Cloudflare Tunnel 设置公网域名
+
+Cloudflare Tunnel (cloudflared) 是 Cloudflare 提供的免费内网穿透服务，相比 ngrok 的优势：
+- ✅ 提供固定的免费域名（不会每次重启都变化）
+- ✅ 免费且稳定
+- ✅ 支持 HTTPS（自动配置 SSL 证书）
+
+---
+
+## 一、安装 cloudflared
+
+### Windows 安装方法
+
+#### 方法 1：使用 Scoop（推荐）
+
+```powershell
+# 安装 Scoop（如果还没有）
+Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
+irm get.scoop.sh | iex
+
+# 安装 cloudflared
+scoop install cloudflared
+```
+
+#### 方法 2：使用 Chocolatey
+
+```powershell
+# 安装 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
+
+```powershell
+# 在项目根目录运行
+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
+
+```powershell
+cloudflared tunnel login
+```
+
+这会打开浏览器，选择你的域名（如果没有域名，可以跳过，使用免费域名）。
+
+### 3.2 创建命名 Tunnel
+
+```powershell
+# 创建名为 wecom-callback 的 tunnel
+cloudflared tunnel create wecom-callback
+```
+
+### 3.3 配置 Tunnel
+
+创建配置文件 `~/.cloudflared/config.yml`（Windows 路径：`C:\Users\你的用户名\.cloudflared\config.yml`）：
+
+```yaml
+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
+```
+
+**如果没有域名，使用免费域名**：
+
+```yaml
+tunnel: wecom-callback
+credentials-file: C:\Users\你的用户名\.cloudflared\<tunnel-id>.json
+
+ingress:
+  - service: http://localhost:8000
+```
+
+### 3.4 启动 Tunnel
+
+```powershell
+cloudflared tunnel run wecom-callback
+```
+
+---
+
+## 四、后台运行（Windows）
+
+### 方法 1：使用 PowerShell 后台任务
+
+```powershell
+# 启动后台任务
+Start-Process -NoNewWindow cloudflared -ArgumentList "tunnel --url http://localhost:8000"
+
+# 查看进程
+Get-Process cloudflared
+
+# 停止进程
+Stop-Process -Name cloudflared
+```
+
+### 方法 2：创建 Windows 服务（固定域名方式）
+
+```powershell
+# 安装为 Windows 服务
+cloudflared service install
+
+# 启动服务
+net start cloudflared
+
+# 停止服务
+net stop cloudflared
+
+# 卸载服务
+cloudflared service uninstall
+```
+
+---
+
+## 五、验证 Tunnel 是否工作
+
+### 5.1 测试本地端点
+
+```powershell
+# 测试本地服务
+curl http://localhost:8000/api/health
+
+# 应该返回：{"status":"up","service":"backend"}
+```
+
+### 5.2 测试公网端点
+
+```powershell
+# 测试公网 URL（替换为你的 cloudflared URL）
+curl https://你的域名.trycloudflare.com/api/health
+
+# 应该返回：{"status":"up","service":"backend"}
+```
+
+---
+
+## 六、完整测试流程
+
+### 6.1 启动服务
+
+```powershell
+# 终端 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 校验
+
+```powershell
+# 查看后端日志
+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 |
+|------|-------------|-------|
+| 免费域名 | ✅ 固定（登录后） | ❌ 每次变化（免费版） |
+| 安装 | 简单 | 简单 |
+| 稳定性 | 高 | 中等 |
+| 速度 | 快 | 中等 |
+| 推荐 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
+
+---
+
+## 九、快速命令参考
+
+```powershell
+# 启动临时 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 状态**：设置日志和告警
+
+```powershell
+# 创建配置文件后，安装为服务
+cloudflared service install
+
+# 启动服务
+net start cloudflared
+
+# 查看服务状态
+sc query cloudflared
+```