228 lines
8.9 KiB
Markdown
228 lines
8.9 KiB
Markdown
# zcbot 控制台 iframe 嵌入对接
|
|
|
|
> 给 **platform 工程**:把 zcbot 控制台(`/static/dev.html`)嵌入 platform 主页,需要做的事。
|
|
>
|
|
> 假设:platform 和 zcbot **不同源**(eg. `https://portal.example.com` 嵌 `https://zcbot.example.com`)。同源直接共享 localStorage 不需要这套握手。
|
|
|
|
---
|
|
|
|
## 一句话总结
|
|
|
|
```html
|
|
<iframe src="https://zcbot.example.com/static/dev.html?embed=1&parent_origin=https://portal.example.com"></iframe>
|
|
```
|
|
|
|
iframe 加载完会发 `postMessage({type:"zcbot-ready"})` 给 platform。platform 后端拿 `PLATFORM_KEY` 调 `POST /v1/auth/login` 换出 JWT,通过 `postMessage({type:"zcbot-token", token, user_id})` 推回 iframe。完事。
|
|
|
|
embed 模式下:左上 brand 隐藏 · 退出登录隐藏 · 登录页不显示 · "+ 新建任务"挪到任务面板。
|
|
|
|
---
|
|
|
|
## 1. URL 参数
|
|
|
|
| 参数 | 必填 | 说明 |
|
|
|---|---|---|
|
|
| `embed` | 是 | 固定 `1`,触发 embed 模式 |
|
|
| `parent_origin` | 是 | platform 主页 origin(scheme + host + 端口),postMessage 白名单。**没传 / 不匹配 → iframe 显错误占位、所有 message 都被丢** |
|
|
|
|
示例:
|
|
```
|
|
https://zcbot.example.com/static/dev.html?embed=1&parent_origin=https://portal.example.com
|
|
```
|
|
|
|
---
|
|
|
|
## 2. postMessage 协议
|
|
|
|
所有消息 `data` 都是 plain object,`type` 字段标识种类。两端都必须校验 `event.origin`。
|
|
|
|
### iframe → platform(子发父)
|
|
|
|
| `type` | 时机 | 字段 | platform 应做 |
|
|
|---|---|---|---|
|
|
| `zcbot-ready` | iframe 加载完成 / 已有缓存 token 但仍发一次 | (无) | 检查当前用户 → 调后端换 JWT → 回推 `zcbot-token` |
|
|
| `zcbot-401` | 用户操作触发 401(token 过期 / 被吊销) | (无) | 重新换 JWT(可能要求用户重新登录 platform)→ 回推 `zcbot-token`;或决定关闭 iframe |
|
|
|
|
### platform → iframe(父发子)
|
|
|
|
| `type` | 字段 | iframe 行为 |
|
|
|---|---|---|
|
|
| `zcbot-token` | `token` (string, JWT) <br> `user_id` (string, UUID) <br> `user_name` (string, 可选) | 写 localStorage + 进入主界面;若已在主界面(401 重签场景)只重载任务列表 |
|
|
|
|
---
|
|
|
|
## 3. platform 后端:换 JWT
|
|
|
|
zcbot 已经有 SSO 入口,**platform 后端用共享的 `PLATFORM_KEY` 代任意用户换 JWT**:
|
|
|
|
```
|
|
POST https://zcbot.example.com/v1/auth/login
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"user_id": "<UUID,platform 决定>",
|
|
"platform_key": "<跟 zcbot env PLATFORM_KEY 同串>"
|
|
}
|
|
```
|
|
|
|
返回:
|
|
```json
|
|
{
|
|
"token": "eyJhbGciOiJIUzI1NiIs...",
|
|
"user_id": "...",
|
|
"exp": 1740000000
|
|
}
|
|
```
|
|
|
|
- `PLATFORM_KEY`:platform 和 zcbot **后端共享的密钥**,**绝不能下放到浏览器**。换 token 必须 platform 后端代理。
|
|
- `user_id`:任意 UUID;首次出现 zcbot 会自动建 `users` 行(占位,无 email/密码),后续 task / message 都用这个 user_id 作为分区键。**platform 用户 ↔ zcbot user_id 映射由 platform 维护**(建议 1:1)。
|
|
- JWT 默认 7 天 TTL(可改 `ZCBOT_JWT_TTL_SECONDS` env)。token 过期前 iframe 收到 401 → 发 `zcbot-401` 给父端 → 父端再走这个换 token 流程。
|
|
|
|
### Node.js 后端示例
|
|
|
|
```js
|
|
// POST /api/zcbot-token (platform 自己的 API,由前端登录态保护)
|
|
app.post("/api/zcbot-token", async (req, res) => {
|
|
const userId = req.session.zcbotUserId; // platform user → zcbot user_id 映射
|
|
const r = await fetch("https://zcbot.example.com/v1/auth/login", {
|
|
method: "POST",
|
|
headers: { "Content-Type": "application/json" },
|
|
body: JSON.stringify({
|
|
user_id: userId,
|
|
platform_key: process.env.ZCBOT_PLATFORM_KEY,
|
|
}),
|
|
});
|
|
if (!r.ok) return res.status(502).json({ error: "zcbot login failed" });
|
|
const { token } = await r.json();
|
|
res.json({ token, user_id: userId, user_name: req.session.userName });
|
|
});
|
|
```
|
|
|
|
### Python (FastAPI) 后端示例
|
|
|
|
```python
|
|
import os, httpx
|
|
from fastapi import HTTPException
|
|
|
|
@app.post("/api/zcbot-token")
|
|
async def issue_zcbot_token(user_id: str = Depends(current_user_id)):
|
|
async with httpx.AsyncClient(timeout=5) as c:
|
|
r = await c.post(
|
|
"https://zcbot.example.com/v1/auth/login",
|
|
json={"user_id": user_id, "platform_key": os.environ["ZCBOT_PLATFORM_KEY"]},
|
|
)
|
|
if r.status_code != 200:
|
|
raise HTTPException(502, "zcbot login failed")
|
|
data = r.json()
|
|
return {"token": data["token"], "user_id": user_id}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. platform 前端:iframe + postMessage
|
|
|
|
```html
|
|
<iframe
|
|
id="zcbot-frame"
|
|
src="https://zcbot.example.com/static/dev.html?embed=1&parent_origin=https://portal.example.com"
|
|
style="width:100%; height:100vh; border:0;"
|
|
allow="clipboard-read; clipboard-write"
|
|
></iframe>
|
|
|
|
<script>
|
|
const ZCBOT_ORIGIN = "https://zcbot.example.com";
|
|
const frame = document.getElementById("zcbot-frame");
|
|
|
|
async function pushToken() {
|
|
// 调 platform 后端拿 zcbot JWT(后端用 PLATFORM_KEY 换)
|
|
const r = await fetch("/api/zcbot-token", { method: "POST", credentials: "include" });
|
|
if (!r.ok) {
|
|
console.error("zcbot token fetch failed");
|
|
return;
|
|
}
|
|
const { token, user_id, user_name } = await r.json();
|
|
frame.contentWindow.postMessage(
|
|
{ type: "zcbot-token", token, user_id, user_name },
|
|
ZCBOT_ORIGIN
|
|
);
|
|
}
|
|
|
|
window.addEventListener("message", (e) => {
|
|
if (e.origin !== ZCBOT_ORIGIN) return;
|
|
const t = e.data && e.data.type;
|
|
if (t === "zcbot-ready" || t === "zcbot-401") {
|
|
pushToken();
|
|
}
|
|
});
|
|
</script>
|
|
```
|
|
|
|
iframe **高度必须足够**(推荐 `100vh` 或固定大尺寸,zcbot 内部有多个全屏 `position:fixed` modal,iframe 太小会挤瘪)。
|
|
|
|
---
|
|
|
|
## 5. 安全要点
|
|
|
|
1. **`parent_origin` URL 参数必填** —— 缺失 / 非法 iframe 不工作。这是 postMessage 的 origin 白名单。
|
|
2. **`PLATFORM_KEY` 只在 platform 后端** —— 等同 JWT 签名权限,泄漏 = 任意伪造任意用户。前端代码 / Git 仓库 / 客户端日志都不能出现。
|
|
3. **iframe 收 message 强制校验 `event.origin === parent_origin`** —— 已在 dev.html 实现,父端也应对称校验 `event.origin === ZCBOT_ORIGIN`,防恶意页面伪造消息。
|
|
4. **CSP `frame-ancestors`** —— 真发布时 zcbot 这边建议加响应头限制只允许 platform 域嵌入,目前 zcbot 未默认设置(本地宽松,见 §6)。
|
|
5. **HTTPS 必须** —— `parent_origin` 是 `https://`,生产部署不要走 http(postMessage 在 http 不发警告,但中间人可改 iframe src 注入恶意 token)。
|
|
6. **TTL**:JWT 默认 7 天。若 platform 希望更短(强制频繁刷新),改 zcbot env `ZCBOT_JWT_TTL_SECONDS` 即可。
|
|
|
|
---
|
|
|
|
## 6. zcbot 部署侧需要做的事
|
|
|
|
> 这一节是 **zcbot 运维 / 我自己** 要做的,platform 工程不需要操心,列出来供参考。
|
|
|
|
1. **CORS `allow_origins`** 收紧到 platform 域名(目前 `["*"]`,见 `web/app.py:516`)
|
|
```python
|
|
allow_origins=["https://portal.example.com"],
|
|
allow_credentials=False,
|
|
```
|
|
2. **CSP `frame-ancestors`** 加响应头中间件,只放行 platform 域:
|
|
```python
|
|
@app.middleware("http")
|
|
async def csp_headers(req, call_next):
|
|
resp = await call_next(req)
|
|
resp.headers["Content-Security-Policy"] = (
|
|
"frame-ancestors https://portal.example.com"
|
|
)
|
|
return resp
|
|
```
|
|
(FastAPI 默认不发 `X-Frame-Options`,iframe 加载本身不会被浏览器拦;`frame-ancestors` 是 CSP 替代品,更细粒度。)
|
|
3. **env**:`PLATFORM_KEY` / `JWT_SECRET` 必填(已是启动 fail-fast 校验,见 `web/auth.py:67`)。
|
|
|
|
---
|
|
|
|
## 7. 调试
|
|
|
|
**本地试 iframe(同机两端口)**:
|
|
- zcbot 跑 `8765` → 浏览器开 `http://127.0.0.1:8765/static/dev.html?embed=1&parent_origin=http://127.0.0.1:3000`
|
|
- 单独不带 platform 时 iframe 会显示"等待登录…",DevTools console 看 `postMessage` 收发。
|
|
- 手动模拟 platform 推 token(在 iframe DevTools 里):
|
|
```js
|
|
window.postMessage({type:"zcbot-token", token:"<手工 curl 换的 JWT>", user_id:"<UUID>"}, location.origin)
|
|
```
|
|
注意 origin 必须 match `parent_origin` 参数,本机调试时把 `parent_origin` 设成 iframe 自己的 origin 即可(自发自收)。
|
|
|
|
**curl 试后端换 token**:
|
|
```bash
|
|
curl -X POST http://127.0.0.1:8765/v1/auth/login \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"user_id":"00000000-0000-0000-0000-000000000001","platform_key":"<env PLATFORM_KEY>"}'
|
|
```
|
|
|
|
---
|
|
|
|
## 8. 故障兜底
|
|
|
|
| 现象 | 原因 | 处置 |
|
|
|---|---|---|
|
|
| iframe 显示"embed 模式缺少 parent_origin 参数" | URL 里没传 `parent_origin` | 加上 `&parent_origin=https://...` |
|
|
| iframe 永远显"等待登录…" | platform 没收 / 没回 `zcbot-ready` | DevTools console 看 message;校验 `event.origin` 是否匹配 |
|
|
| iframe 收到 `zcbot-token` 但仍不进主界面 | `event.origin !== parent_origin` 或 `token` / `user_id` 字段缺失 | iframe 是静默丢弃,看 console 是否有报错;校验字段拼写 |
|
|
| 一动作就跳回等待页 | JWT 过期 / 后端校验失败,触发 `zcbot-401` | platform 重新换 token 回推;或检查 zcbot 端 JWT_SECRET 是否变过 |
|
|
| 嵌入页面 modal(新建任务 / 文件预览)被挤瘪 | iframe 高度不够 | iframe `height` 改 `100vh` 或更高,zcbot modal 是 `position:fixed; inset:0` |
|