152 lines
4.2 KiB
Markdown
152 lines
4.2 KiB
Markdown
# Cloudflare Tunnel 快速开始指南
|
||
|
||
## 一键安装（Windows）
|
||
|
||
### 方法 1：使用 MSI 安装包（最简单）
|
||
|
||
1. **下载安装包**：
|
||
- 直接下载：https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.msi
|
||
- 或访问：https://github.com/cloudflare/cloudflared/releases 选择最新版本的 MSI 文件
|
||
|
||
2. **安装**：
|
||
- 双击 `cloudflared-windows-amd64.msi`
|
||
- 按照安装向导完成安装
|
||
- 安装完成后会自动添加到系统 PATH
|
||
|
||
3. **验证安装**：
|
||
```powershell
|
||
cloudflared --version
|
||
```
|
||
|
||
### 方法 2：使用 Scoop（推荐开发者）
|
||
|
||
```powershell
|
||
# 安装 Scoop（如果还没有）
|
||
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||
irm get.scoop.sh | iex
|
||
|
||
# 安装 cloudflared
|
||
scoop install cloudflared
|
||
|
||
# 验证
|
||
cloudflared --version
|
||
```
|
||
|
||
### 方法 3：直接下载 EXE（无需安装）
|
||
|
||
1. **下载**：https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.exe
|
||
2. **重命名**：将文件重命名为 `cloudflared.exe`
|
||
3. **使用**：在项目目录中直接运行 `.\cloudflared.exe tunnel --url http://localhost:8000`
|
||
|
||
---
|
||
|
||
## 快速启动 Tunnel
|
||
|
||
### 步骤 1：确保后端服务运行
|
||
|
||
```powershell
|
||
# 检查服务状态
|
||
docker compose ps
|
||
|
||
# 如果未运行，启动服务
|
||
docker compose up -d
|
||
```
|
||
|
||
### 步骤 2：启动 Cloudflare 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 +--------------------------------------------------------------------------------------------+
|
||
```
|
||
|
||
### 步骤 3：复制公网 URL
|
||
|
||
从输出中复制 `https://xxx.trycloudflare.com`，例如：
|
||
```
|
||
https://abc123-def456-ghi789.trycloudflare.com
|
||
```
|
||
|
||
### 步骤 4：配置企业微信回调
|
||
|
||
1. 登录企业微信管理后台：https://work.weixin.qq.com
|
||
2. 进入：应用管理 → 自建应用 → 你的应用 → 接收消息 → 设置 API 接收
|
||
3. 填写回调 URL：`https://abc123-def456-ghi789.trycloudflare.com/api/wecom/callback`
|
||
4. 填写 Token 和 EncodingAESKey（与 `.env` 文件一致）
|
||
5. 点击保存
|
||
|
||
### 步骤 5：验证配置
|
||
|
||
```powershell
|
||
# 在另一个终端查看后端日志
|
||
docker compose logs backend -f
|
||
```
|
||
|
||
应该看到：
|
||
```
|
||
INFO: wecom verify success {"trace_id": "...", "echostr_length": 43}
|
||
```
|
||
|
||
企微后台应显示 **保存成功** ✅
|
||
|
||
---
|
||
|
||
## 测试消息回调
|
||
|
||
1. **在企业微信中发送消息**：`你好，测试一下`
|
||
2. **查看后端日志**：
|
||
```powershell
|
||
docker compose logs backend -f
|
||
```
|
||
应该看到：
|
||
- `wecom message received`（收到消息）
|
||
- `wecom reply sent`（发送回复）
|
||
3. **在企业微信中验证**：应收到回复 `已收到：你好，测试一下`
|
||
|
||
---
|
||
|
||
## 重要提示
|
||
|
||
1. **保持 cloudflared 运行**：不要关闭运行 cloudflared 的终端窗口
|
||
2. **URL 有效期**：本次运行期间 URL 固定，关闭 cloudflared 后 URL 失效
|
||
3. **如需固定域名**：登录 Cloudflare 创建命名 tunnel（参见 `docs/cloudflared-setup.md`）
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q: cloudflared 命令找不到？
|
||
|
||
**A**:
|
||
- 如果使用 MSI 安装，重启终端或重新打开 PowerShell
|
||
- 如果手动下载，确保文件在 PATH 中或使用完整路径
|
||
|
||
### Q: 连接失败？
|
||
|
||
**A**:
|
||
- 检查本地服务是否运行：`docker compose ps`
|
||
- 检查端口是否正确：`netstat -an | findstr 8000`
|
||
- 检查防火墙设置
|
||
|
||
### Q: 企微回调失败？
|
||
|
||
**A**:
|
||
- 确保 cloudflared URL 可访问：在浏览器打开 `https://你的域名.trycloudflare.com/api/health`
|
||
- 检查 Token 和 EncodingAESKey 是否与 `.env` 一致
|
||
- 查看后端日志：`docker compose logs backend | grep wecom`
|
||
|
||
---
|
||
|
||
## 更多信息
|
||
|
||
- **详细设置指南**：`docs/cloudflared-setup.md`
|
||
- **完整测试流程**：`docs/wecom-test-guide.md`
|
||
- **官方文档**：https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/
|