feat(embed): add widget, visitor chat, and management UI (#1657)
Add embed.html entrypoint, floating widget SDK, secure-mode snippets, management panel with preview, visitor chat composables, citation rendering, and integration docs for subdomain and server-side token exchange.
This commit is contained in:
@@ -0,0 +1,182 @@
|
||||
# Embed 安全模式
|
||||
|
||||
> **一句话**:长期密钥(发布 Token `em_…`)只放在**你自己的服务器**;访客浏览器里只有 30 分钟有效的短时令牌(`ems_…`)。
|
||||
|
||||
## 为什么要用?
|
||||
|
||||
| 方式 | 发布 Token 在哪 | 风险 |
|
||||
|------|-----------------|------|
|
||||
| iframe / 普通 Widget | 写在页面 HTML 或 URL hash 里 | 任何人「查看源代码」就能复制,等于公开密钥 |
|
||||
| **安全模式 Widget** | 仅环境变量 / 密钥管理,在服务端 | 浏览器拿不到长期密钥;还可先校验访客是否登录 |
|
||||
|
||||
生产环境对外嵌入,**应优先用安全模式**。
|
||||
|
||||
## 两种 Token
|
||||
|
||||
| 名称 | 格式 | 谁持有 | 用途 |
|
||||
|------|------|--------|------|
|
||||
| 发布 Token | `em_…` | 仅你的服务端 | 向 WeKnora 换取短时令牌;在管理端「渠道密钥」查看 |
|
||||
| 会话 Token | `ems_…` | 访客浏览器(iframe 内) | 调聊天、上传等 embed API;约 30 分钟过期,Widget 会自动刷新 |
|
||||
|
||||
## 工作流程
|
||||
|
||||
```
|
||||
访客浏览器 你的后端(shop 的服务器) WeKnora
|
||||
│ │ │
|
||||
│ 1. 加载 Widget │ │
|
||||
│ data-token-endpoint │ │
|
||||
│ (不含 em_) │ │
|
||||
│─────────────────────────────►│ │
|
||||
│ │ 2. 校验访客已登录(可选) │
|
||||
│ │ 3. POST .../embed/:id/exchange │
|
||||
│ │ Authorization: Embed em_… │
|
||||
│ │─────────────────────────────►│
|
||||
│ │◄──── session_token (ems_…) ───│
|
||||
│◄── 4. { token, expiresIn } ──│ │
|
||||
│ 5. iframe 用 ems_ 聊天 │ │
|
||||
```
|
||||
|
||||
对应管理端「嵌入渠道 → 安全模式」里的两段代码:
|
||||
|
||||
1. **页面脚本**:`data-token-endpoint="https://你的域名/weknora/embed-token"`(没有 `data-token`)
|
||||
2. **服务端接口**:用发布 Token 调 exchange,把 `ems_…` 返回给前端
|
||||
|
||||
## 集成步骤
|
||||
|
||||
### 第 1 步:在 WeKnora 创建渠道
|
||||
|
||||
- 记下 **渠道 ID** 和 **发布 Token**(`em_…`)
|
||||
- 配置域名白名单(见下)
|
||||
- 配置分钟 / 日限流
|
||||
|
||||
### 第 2 步:部署取令牌接口
|
||||
|
||||
在你的业务后端新增一个 HTTP 接口(路径自定),要求:
|
||||
|
||||
**入参**:浏览器 GET 请求(Widget 会 `fetch` 这个地址)
|
||||
|
||||
**你必须做**:
|
||||
|
||||
- 校验调用方是合法访客(Session Cookie、JWT 等),未登录返回 `401`
|
||||
- 用发布 Token 调 WeKnora exchange
|
||||
- 成功时返回 JSON:`{ "token": "<ems_…>", "expiresIn": 1800 }`
|
||||
|
||||
**调 exchange 的约定**:
|
||||
|
||||
```http
|
||||
POST https://<weknora-host>/api/v1/embed/<channel_id>/exchange
|
||||
Authorization: Embed <发布 Token em_…>
|
||||
Origin: https://<你的业务站点> ← 须与渠道白名单一致,否则 403
|
||||
```
|
||||
|
||||
> 服务端 `fetch` 默认不带 `Origin`,需要**手动设置**与白名单匹配的 `Origin` 头。
|
||||
|
||||
### 第 3 步:粘贴安全模式 Widget 代码
|
||||
|
||||
把 `data-token-endpoint` 改成上一步的真实 URL。完整示例在管理端「安全模式」Tab 可复制。
|
||||
|
||||
## 服务端示例
|
||||
|
||||
以下 `<WEKNORA_HOST>`、`<CHANNEL_ID>` 替换为实际值;发布 Token 放环境变量 `WEKNORA_PUBLISH_TOKEN`,**不要**写进前端。
|
||||
|
||||
### Node.js(Express)
|
||||
|
||||
```javascript
|
||||
const WEKNORA_BASE = 'https://<WEKNORA_HOST>';
|
||||
const CHANNEL_ID = '<CHANNEL_ID>';
|
||||
const ALLOWED_ORIGIN = 'https://shop.example.com'; // 与渠道白名单一致
|
||||
|
||||
app.get('/weknora/embed-token', async (req, res) => {
|
||||
const hasSession = Boolean(req.cookies?.session_id);
|
||||
const auth = req.headers.authorization || '';
|
||||
if (!hasSession && !auth.startsWith('Bearer ')) {
|
||||
return res.status(401).json({ error: 'unauthorized' });
|
||||
}
|
||||
|
||||
const r = await fetch(`${WEKNORA_BASE}/api/v1/embed/${CHANNEL_ID}/exchange`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
Authorization: 'Embed ' + process.env.WEKNORA_PUBLISH_TOKEN,
|
||||
Origin: ALLOWED_ORIGIN,
|
||||
},
|
||||
});
|
||||
const body = await r.json();
|
||||
if (!body?.data?.session_token) {
|
||||
return res.status(502).json({ error: 'mint failed' });
|
||||
}
|
||||
res.json({ token: body.data.session_token, expiresIn: body.data.expires_in });
|
||||
});
|
||||
```
|
||||
|
||||
### Go(net/http)
|
||||
|
||||
```go
|
||||
func embedTokenHandler(w http.ResponseWriter, r *http.Request) {
|
||||
if r.Header.Get("Authorization") == "" && r.Header.Get("Cookie") == "" {
|
||||
http.Error(w, `{"error":"unauthorized"}`, http.StatusUnauthorized)
|
||||
return
|
||||
}
|
||||
req, _ := http.NewRequest(http.MethodPost,
|
||||
"https://<WEKNORA_HOST>/api/v1/embed/<CHANNEL_ID>/exchange", nil)
|
||||
req.Header.Set("Authorization", "Embed "+os.Getenv("WEKNORA_PUBLISH_TOKEN"))
|
||||
req.Header.Set("Origin", "https://shop.example.com") // 与渠道白名单一致
|
||||
resp, err := http.DefaultClient.Do(req)
|
||||
if err != nil || resp.StatusCode >= 300 {
|
||||
http.Error(w, `{"error":"mint failed"}`, http.StatusBadGateway)
|
||||
return
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
var body struct {
|
||||
Data struct {
|
||||
SessionToken string `json:"session_token"`
|
||||
ExpiresIn int `json:"expires_in"`
|
||||
} `json:"data"`
|
||||
}
|
||||
if json.NewDecoder(resp.Body).Decode(&body) != nil || body.Data.SessionToken == "" {
|
||||
http.Error(w, `{"error":"mint failed"}`, http.StatusBadGateway)
|
||||
return
|
||||
}
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
json.NewEncoder(w).Encode(map[string]any{
|
||||
"token": body.Data.SessionToken, "expiresIn": body.Data.ExpiresIn,
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
管理端「安全模式 → 服务端示例」Tab 会按当前渠道 ID 生成带真实 URL 的片段。
|
||||
|
||||
## 域名白名单怎么填?
|
||||
|
||||
| 要放行的请求来源 | 白名单示例 |
|
||||
|------------------|------------|
|
||||
| 聊天 iframe 所在源站(embed 页面) | `https://app.example.com` 或 `https://embed.example.com` |
|
||||
| 你的取令牌后端(exchange 时带的 Origin) | `https://shop.example.com` |
|
||||
|
||||
若 embed 使用[独立子域](./embed-subdomain.md),**两条都要加**(embed 源站 + 业务后端源站)。
|
||||
|
||||
开发环境可临时使用 `*`;**生产环境禁止 `*`**。
|
||||
|
||||
## 上线检查
|
||||
|
||||
- [ ] 发布 Token 仅通过环境变量 / 密钥服务注入,未提交到 Git、未打进前端静态包
|
||||
- [ ] 取令牌接口校验访客身份
|
||||
- [ ] 全链路 HTTPS
|
||||
- [ ] 白名单已包含 embed 源站与 exchange 使用的 Origin
|
||||
- [ ] 已配置限流;敏感智能体不要用普通模式把 Token 暴露在网页里
|
||||
- [ ] 轮换发布 Token 后,同步更新服务端环境变量
|
||||
|
||||
## 常见问题
|
||||
|
||||
| 现象 | 原因与处理 |
|
||||
|------|------------|
|
||||
| exchange 返回 **401** / `publish token required` | 发布 Token 错误、已轮换,或误用了 `ems_` 会话 Token |
|
||||
| exchange 或聊天 API 返回 **403** `origin not allowed` | 白名单未包含当前请求的 `Origin`;服务端 exchange 记得手动加 `Origin` 头 |
|
||||
| iframe 一直「等待 Token」 | `token-endpoint` 未返回 `{ token, expiresIn }`,或 CORS 未允许 Widget 所在源站访问你的接口 |
|
||||
| 取令牌接口 **502** `mint failed` | WeKnora 不可达、渠道已停用,或 exchange 响应格式不对 |
|
||||
| 访客随便就能聊 | 取令牌接口未做登录校验——在 exchange 前加 Session / JWT 检查 |
|
||||
|
||||
## 相关
|
||||
|
||||
- 可选:embed 独立子域 → [embed-subdomain.md](./embed-subdomain.md)
|
||||
- Widget SDK 注释:`frontend/public/weknora-widget.js`
|
||||
- 代码生成:`frontend/src/api/embed/index.ts`
|
||||
@@ -0,0 +1,106 @@
|
||||
# Embed 独立子域部署(可选)
|
||||
|
||||
> **一句话**:把聊天页面单独放到 `embed.example.com`,与主站 `app.example.com` 分开。**大多数部署不需要这一步**——主站和 embed 同域就能用。只有对安全隔离有明确要求时再考虑。
|
||||
|
||||
## 先搞清楚三个「网站」
|
||||
|
||||
嵌入聊天时,实际涉及三类地址(可以相同,也可以不同):
|
||||
|
||||
| 角色 | 举例 | 干什么 |
|
||||
|------|------|--------|
|
||||
| **A. 业务站点(宿主)** | `https://shop.example.com` | 你的商城 / 文档站;在这里粘贴 Widget 脚本或 iframe |
|
||||
| **B. Embed 页面源站** | `https://app.example.com` 或 `https://embed.example.com` | 提供 `embed.html`、`weknora-widget.js`;聊天 iframe 加载自这里 |
|
||||
| **C. WeKnora API** | 通常与 B 同域,如 `https://app.example.com/api` | 后端接口 |
|
||||
|
||||
**默认(推荐入门)**:B 和主站管理后台都在 `https://app.example.com`,A 可以是任意第三方域名。
|
||||
|
||||
```
|
||||
shop.example.com app.example.com
|
||||
┌─────────────────┐ ┌──────────────────────────┐
|
||||
│ <script src= │ │ /weknora-widget.js │
|
||||
│ app.../widget> │──────►│ /embed/:channelId │
|
||||
│ │ │ /api/v1/embed/... │
|
||||
│ (浮窗 iframe) │◄──────│ │
|
||||
└─────────────────┘ └──────────────────────────┘
|
||||
```
|
||||
|
||||
**独立子域(进阶)**:把 B 拆到 `https://embed.example.com`,主站 `https://app.example.com` 只留管理后台。
|
||||
|
||||
```
|
||||
shop.example.com embed.example.com app.example.com
|
||||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────┐
|
||||
│ Widget 脚本 │──────►│ embed 静态页+API │ │ 管理后台 │
|
||||
│ iframe 指向 embed│◄──────│ (无 index SPA) │ │ (可选分离) │
|
||||
└─────────────────┘ └──────────────────┘ └─────────────┘
|
||||
```
|
||||
|
||||
## 什么时候需要独立子域?
|
||||
|
||||
| 场景 | 是否需要 |
|
||||
|------|----------|
|
||||
| 内测、PoC、单域 Docker 部署 | **不需要** |
|
||||
| 主站 `X-Frame-Options: SAMEORIGIN`,但要把聊天嵌到第三方页面 | **不需要**(被嵌的是 `/embed/*` 页面,不是管理后台 SPA) |
|
||||
| 希望 embed 站点不携带主站登录 Cookie、缩小暴露面 | **可以考虑** |
|
||||
| 希望 CDN / WAF 对 embed 流量单独限速、缓存 | **可以考虑** |
|
||||
| 合规要求「对外嵌入」与「内部管理」必须不同源 | **需要** |
|
||||
|
||||
本地开发:`http://localhost:5173` 同域即可,Vite 已把 `/embed/*` 指到 `embed.html`,**不必**配子域。
|
||||
|
||||
## 怎么配置
|
||||
|
||||
### 1. 告诉管理端「embed 页面公网地址」
|
||||
|
||||
管理端生成 iframe / Widget 代码时,需要知道 B 的地址。在 `frontend/public/config.js`(或 Docker 启动脚本生成的配置)里设置:
|
||||
|
||||
```javascript
|
||||
window.__RUNTIME_CONFIG__ = {
|
||||
// embed 页面与 widget.js 的源站;留空则使用当前浏览器所在域名
|
||||
EMBED_BASE_URL: 'https://embed.example.com',
|
||||
MAX_FILE_SIZE_MB: 50,
|
||||
};
|
||||
```
|
||||
|
||||
构建期也可通过环境变量注入:`VITE_EMBED_BASE_URL=https://embed.example.com`(可选)。
|
||||
|
||||
### 2. Nginx:单独 server 块只服务 embed
|
||||
|
||||
`frontend/nginx.conf` 顶部有注释掉的示例。要点:
|
||||
|
||||
- `server_name embed.example.com`
|
||||
- 只暴露:`/embed/*` → `embed.html`,`/weknora-widget.js`,`/assets/*`
|
||||
- `/api/` 反代到 WeKnora 后端(与主站相同后端即可)
|
||||
- **不要**在这个 server 上挂完整 `index.html` 管理 SPA(减少攻击面)
|
||||
|
||||
主站 `server` 块可继续 `X-Frame-Options: SAMEORIGIN`,不影响第三方嵌 embed 子域的 iframe。
|
||||
|
||||
### 3. 域名白名单填什么?
|
||||
|
||||
渠道里的「域名白名单」校验的是 **API 请求的 `Origin` 头**,不是「允许哪些网站粘贴脚本」的抽象概念。
|
||||
|
||||
实际要填:
|
||||
|
||||
1. **Embed 页面源站**(必填)——聊天 iframe 内发 API 时浏览器会带这个 Origin
|
||||
- 同域部署:`https://app.example.com`
|
||||
- 独立子域:`https://embed.example.com`
|
||||
2. **你的业务后端源站**(安全模式时建议填)——你自己写的「取令牌接口」在服务端调用 `POST .../exchange` 时,需带与白名单一致的 `Origin` 头(见 [embed-secure-mode.md](./embed-secure-mode.md))
|
||||
|
||||
第三方商城 `https://shop.example.com` **通常不用**进白名单(它只是加载脚本,不直接调 embed API)。
|
||||
若你把 embed 反代到商城同域路径下(少见),才需要填商城域名。
|
||||
|
||||
## Widget 跨域与 sandbox
|
||||
|
||||
当宿主站 A 与 embed 源站 B **不同域**时,`weknora-widget.js` 会自动给内部 iframe 加上 `sandbox`(也可手动 `data-sandbox="true"`)。
|
||||
|
||||
A 与 B 同域时保持默认即可,无需 `data-sandbox`。
|
||||
|
||||
## 检查清单
|
||||
|
||||
- [ ] `EMBED_BASE_URL` 与真实访问地址一致(含 `https`)
|
||||
- [ ] embed 子域能打开 `/embed/<渠道ID>` 和 `/weknora-widget.js`
|
||||
- [ ] embed 子域 `/api/` 能连到后端
|
||||
- [ ] 渠道白名单包含 embed 源站(及安全模式下的业务后端源站)
|
||||
- [ ] 管理端复制的 snippet 里 URL 已变为 embed 子域
|
||||
|
||||
## 相关文档
|
||||
|
||||
- 发布 Token 不落浏览器:[embed-secure-mode.md](./embed-secure-mode.md)
|
||||
Reference in New Issue
Block a user