# 使用 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
```