# 飞书 OAuth 免登 + Cloudflare Tunnel 模式（2026-07-25 实战）

## 架构

```
飞书打开应用 → 重定向 URL?code=xxx
  → CloudBase 静态页面检测 code
  → POST 到公网 OAuth 端点（Cloudflare Tunnel）
  → Python 本地服务器调飞书 API 换用户身份
  → 返回 name → 前端查 user_roles → finishLogin
```

## 关键陷阱

1. **CloudBase `password` 字段会被自动屏蔽** → 必须命名为 `pwd`
2. **tcb fn CLI 不支持 HTTP 触发器** → 需控制台手动创建，或用 Cloudflare Tunnel 代替
3. **loadUserList 时序** → 必须在匿名登录 `.then()` 内调用
4. **CloudBase 查询返回空数组不抛异常** → 需显式检查 `users.length === 0` 后 fallback
5. **飞书网页应用 URL 校验** → 不支持中文路径（`/工具/index.html`），必须部署到根目录

## Cloudflare Tunnel 命令

```bash
# 临时公网隧道（重启 URL 会变）
cloudflared tunnel --url http://localhost:8765
# 输出: https://{random}.trycloudflare.com
```

## 飞书 OAuth 端点（Python）

```python
# POST /api/feishu/auth
# body: {"code": "xxx"}
# → 调飞书 open-apis/auth/v3/app_access_token/internal
# → 调 open-apis/authen/v1/oidc/access_token
# → 返回 {"ok": true, "name": "刘新元"}
```

## 飞书应用配置

- 重定向 URL: `https://{env-id}.tcloudbaseapp.com/index.html`
- 权限: `contact:user.base:readonly`（需管理员审批）
- 应用类型: 企业自建应用 → 网页应用