# 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/