313 lines
7.9 KiB
Markdown
313 lines
7.9 KiB
Markdown
# 使用 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
|
||
```
|