508 lines
13 KiB
Markdown
508 lines
13 KiB
Markdown
# Prompt 详情页测试功能安全令牌未初始化问题修复 PRD
|
||
|
||
> **版本**: v1.0
|
||
> **日期**: 2026-05-25
|
||
> **状态**: 📝 待评审
|
||
|
||
---
|
||
|
||
## 一、背景
|
||
|
||
在 prompt 服务的公开提示词详情页中，页面提供了“测试”标签，允许已登录用户直接选择模型并运行提示词测试。
|
||
|
||
目标页面示例：
|
||
|
||
- `https://prompt.ephron.ren/prompts/prompt-20260508110413`
|
||
|
||
按预期：
|
||
|
||
- 用户只要处于已登录状态
|
||
- 打开公开详情页
|
||
- 进入“测试”标签并点击“开始测试”
|
||
|
||
就应当可以直接完成测试。
|
||
|
||
但现状是：即使用户已经登录，测试功能仍可能提示：
|
||
|
||
- `安全令牌未初始化，请刷新页面后重试`
|
||
- 或在接口层表现为 `CSRF token 验证失败`
|
||
|
||
这说明“已登录”与“测试功能可用”之间还存在一个未被详情页自身完成的初始化前置条件。
|
||
|
||
---
|
||
|
||
## 二、问题现象
|
||
|
||
### 2.1 用户侧现象
|
||
|
||
在已登录状态下，用户访问公开提示词详情页：
|
||
|
||
1. 打开 `/prompts/{key}` 页面
|
||
2. 切换到“测试”标签
|
||
3. 选择模型
|
||
4. 输入测试内容
|
||
5. 点击“开始测试”
|
||
|
||
**实际结果：**
|
||
|
||
- 页面提示安全令牌未初始化，或请求失败
|
||
- 后端接口返回 403，错误为 `CSRF token 验证失败`
|
||
|
||
### 2.2 旁证现象
|
||
|
||
如果用户先访问某些后台页面（例如 `/admin/settings`），再回到同一个公开提示词详情页重复操作，测试又可能恢复正常。
|
||
|
||
这说明：
|
||
|
||
- 模型能力本身不是根因
|
||
- 登录态本身也不是根因
|
||
- 更像是某个与页面测试功能相关的 token / cookie 初始化，只在后台页面中发生，而在公开详情页中未发生
|
||
|
||
---
|
||
|
||
## 三、影响范围
|
||
|
||
### 3.1 直接影响
|
||
|
||
- 所有挂载了“测试”面板的公开提示词详情页：`/prompts/{key}`
|
||
- 所有“已登录但首次直接从公开详情页发起测试”的用户
|
||
|
||
### 3.2 间接影响
|
||
|
||
- 用户会误以为账号失效、会话异常或模型配置有问题
|
||
- 测试功能表现为“不稳定”：访问过后台页面后又恢复，增加排查成本
|
||
- 页面对后台页面存在隐式依赖，破坏公开详情页的独立性
|
||
|
||
### 3.3 不受影响的路径
|
||
|
||
- 仅浏览提示词正文的用户
|
||
- 不使用测试功能的用户
|
||
- 已经访问过会初始化 CSRF cookie 的后台页面，且当前 cookie 尚未过期的用户
|
||
|
||
---
|
||
|
||
## 四、现状与源码定位
|
||
|
||
### 4.1 公开详情页会直接挂载测试组件
|
||
|
||
文件：`prompt/templates/public/detail.html`
|
||
|
||
详情页模板中直接加载测试脚本并实例化 `PromptTester`：
|
||
|
||
- 加载 `/static/js/test-prompt.js`
|
||
- `new PromptTester({...})`
|
||
|
||
这意味着：
|
||
|
||
- 公开详情页自身就是测试功能的承载页面
|
||
- 测试所需前置条件应由该页面或其服务端路由负责准备
|
||
|
||
### 4.2 前端测试逻辑直接从 cookie 中读取 `ephron_csrf`
|
||
|
||
文件：`prompt/static/js/test-prompt.js`
|
||
|
||
核心逻辑：
|
||
|
||
```javascript
|
||
const csrfToken = document.cookie.match(/ephron_csrf=([^;]+)/)?.[1] || '';
|
||
const response = await fetch(`/api/prompts/${this.promptKey}/test`, {
|
||
method: "POST",
|
||
headers: {
|
||
"Content-Type": "application/json",
|
||
"X-CSRF-Token": csrfToken,
|
||
},
|
||
body: JSON.stringify(body),
|
||
});
|
||
```
|
||
|
||
可见前端默认假设：
|
||
|
||
- `document.cookie` 中一定已经存在 `ephron_csrf`
|
||
|
||
若该 cookie 不存在，则会把空字符串作为 `X-CSRF-Token` 发给后端。
|
||
|
||
### 4.3 测试 API 后端强制校验 `ephron_auth + ephron_csrf`
|
||
|
||
文件：`prompt/src/routes/api.py`
|
||
|
||
关键逻辑：
|
||
|
||
```python
|
||
token = request.cookies.get("ephron_auth")
|
||
user = get_auth_user(token)
|
||
if not user:
|
||
raise HTTPException(status_code=401, detail="需要登录")
|
||
|
||
csrf_cookie = request.cookies.get("ephron_csrf")
|
||
csrf_header = request.headers.get("X-CSRF-Token")
|
||
if not verify_csrf_token(csrf_header, csrf_cookie):
|
||
raise HTTPException(status_code=403, detail="CSRF token 验证失败")
|
||
```
|
||
|
||
说明测试接口要求同时满足：
|
||
|
||
1. 用户已登录（`ephron_auth` 有效）
|
||
2. 浏览器中存在 `ephron_csrf`
|
||
3. 请求头中的 `X-CSRF-Token` 与 cookie 中的 token 一致
|
||
|
||
### 4.4 后台页面会主动初始化 CSRF cookie
|
||
|
||
文件：`prompt/src/routes/admin.py`
|
||
|
||
后台多个 GET 页面采用统一模式：
|
||
|
||
```python
|
||
csrf_token = generate_csrf_token()
|
||
response = templates.TemplateResponse(...)
|
||
set_csrf_cookie(response, csrf_token, is_development=IS_DEVELOPMENT)
|
||
return response
|
||
```
|
||
|
||
说明项目当前已有成熟的 CSRF 初始化机制：
|
||
|
||
- 生成 token
|
||
- 写入 `ephron_csrf` cookie
|
||
- 供表单和前端 JS 后续读取
|
||
|
||
### 4.5 公开详情页路由未承担相同职责
|
||
|
||
结合现有 PRD 记录与本次源码排查，可以确认公开详情页路由：
|
||
|
||
文件：`prompt/src/routes/pages.py`
|
||
|
||
在渲染 `public/detail.html` 时：
|
||
|
||
- 直接返回 `TemplateResponse`
|
||
- 没有看到对 `generate_csrf_token()` 的调用
|
||
- 没有看到对 `set_csrf_cookie(...)` 的调用
|
||
|
||
这与后台页面形成明显差异。
|
||
|
||
---
|
||
|
||
## 五、根因分析
|
||
|
||
### 5.1 根因结论
|
||
|
||
> **公开提示词详情页提供了测试能力，但没有初始化该能力所依赖的 CSRF token cookie。**
|
||
|
||
### 5.2 具体链路
|
||
|
||
当前链路可还原为：
|
||
|
||
1. 用户在 `auth.ephron.ren` 完成登录
|
||
2. 浏览器具备有效的 `ephron_auth`
|
||
3. 用户直接进入 `prompt.ephron.ren/prompts/{key}`
|
||
4. 详情页渲染时没有种下 `ephron_csrf`
|
||
5. 用户点击“开始测试”
|
||
6. `test-prompt.js` 从 `document.cookie` 读取不到 `ephron_csrf`
|
||
7. 前端仍继续向 `/api/prompts/{key}/test` 发送请求，`X-CSRF-Token` 为空
|
||
8. 后端发现 `csrf_header` 与 `csrf_cookie` 缺失或不一致
|
||
9. 返回 `403 CSRF token 验证失败`
|
||
10. 前端再将其表现为“安全令牌未初始化”类错误提示
|
||
|
||
### 5.3 为什么访问 `/admin/settings` 后会“恢复”
|
||
|
||
因为后台设置页会调用：
|
||
|
||
- `generate_csrf_token()`
|
||
- `set_csrf_cookie(...)`
|
||
|
||
于是浏览器终于具备了 `ephron_csrf`。之后再回到详情页，同一份前端 JS 就能成功从 `document.cookie` 中读到 token，于是测试恢复正常。
|
||
|
||
这进一步证明：
|
||
|
||
- 问题不是模型请求本身
|
||
- 问题不是账号鉴权本身
|
||
- 问题是 **公开详情页缺失 CSRF 初始化责任**
|
||
|
||
---
|
||
|
||
## 六、修复目标
|
||
|
||
1. 已登录用户首次直接访问公开提示词详情页时，可直接使用测试功能
|
||
2. 测试功能不再依赖用户事先访问后台页面进行“预热”
|
||
3. 保持现有 CSRF 防护机制，不通过移除校验来规避问题
|
||
4. 前端在 token 缺失时给出清晰、可理解的错误提示
|
||
5. 为该问题补齐自动化回归测试，避免未来再次回归
|
||
|
||
---
|
||
|
||
## 七、修复方案
|
||
|
||
## 7.1 方案 A：公开详情页 GET 路由补发 CSRF cookie（主修复，必须做）
|
||
|
||
文件：`prompt/src/routes/pages.py`
|
||
|
||
在渲染 `public/detail.html` 的公开详情页路由中，补齐与后台页面一致的初始化逻辑：
|
||
|
||
1. 调用 `generate_csrf_token()` 生成 token
|
||
2. 使用 `TemplateResponse` 先构造响应对象
|
||
3. 调用 `set_csrf_cookie(response, csrf_token, is_development=IS_DEVELOPMENT)`
|
||
4. 返回该 response
|
||
|
||
### 设计要求
|
||
|
||
- 实现方式应尽量复用后台页面已有模式
|
||
- 不新增新的 CSRF 机制分支
|
||
- 不改动接口鉴权模型
|
||
- 不改动测试 API 的 CSRF 校验规则
|
||
|
||
### 预期效果
|
||
|
||
- 用户打开详情页即自动获得 `ephron_csrf`
|
||
- 点击测试时，前端能直接从 cookie 取到有效 token
|
||
- 后端的现有校验链路无需修改即可通过
|
||
|
||
---
|
||
|
||
## 7.2 方案 B：前端增加 token 缺失的显式防御（兜底增强，建议一并做）
|
||
|
||
文件：`prompt/static/js/test-prompt.js`
|
||
|
||
在发起 `fetch()` 前增加前置判断：
|
||
|
||
```javascript
|
||
const csrfToken = document.cookie.match(/ephron_csrf=([^;]+)/)?.[1] || '';
|
||
if (!csrfToken) {
|
||
throw new Error('安全令牌未初始化，请刷新页面后重试');
|
||
}
|
||
```
|
||
|
||
### 目的
|
||
|
||
- 避免把空 token 静默发给后端
|
||
- 让用户看到更明确的错误原因
|
||
- 即使未来某次页面初始化异常，也能更快暴露问题归因
|
||
|
||
### 说明
|
||
|
||
这不是根修复，只是防御性增强。真正的根因修复仍然是方案 A。
|
||
|
||
---
|
||
|
||
## 7.3 本次不建议采用的替代方案
|
||
|
||
### 替代方案：新增单独的 CSRF 初始化 API
|
||
|
||
例如新增：
|
||
|
||
- `GET /api/auth/csrf`
|
||
|
||
并在前端缺 token 时先请求该接口。
|
||
|
||
### 不作为首选原因
|
||
|
||
- 当前项目已有稳定的服务端渲染页面 + `set_csrf_cookie` 模式
|
||
- 新增 API 会引入额外异步初始化链路和更多状态分支
|
||
- 对当前问题来说属于过度设计
|
||
|
||
除非后续要支持更多纯前端异步挂载场景，否则现阶段没有必要。
|
||
|
||
---
|
||
|
||
## 八、实现清单
|
||
|
||
### 8.1 后端改动
|
||
|
||
文件：`prompt/src/routes/pages.py`
|
||
|
||
#### 需要做的事
|
||
|
||
- 导入：
|
||
- `generate_csrf_token`
|
||
- `set_csrf_cookie`
|
||
- 在 `prompt_detail()` 中：
|
||
- 生成 `csrf_token`
|
||
- 将原本直接返回的 `TemplateResponse` 改为先赋值给 `response`
|
||
- 调用 `set_csrf_cookie(response, csrf_token, is_development=IS_DEVELOPMENT)`
|
||
- 返回 `response`
|
||
|
||
#### 约束
|
||
|
||
- 不改动详情页已有模板参数结构，避免影响正文渲染
|
||
- 不需要将 token 注入模板 DOM；cookie 已足够供当前 JS 使用
|
||
|
||
### 8.2 前端改动
|
||
|
||
文件：`prompt/static/js/test-prompt.js`
|
||
|
||
#### 需要做的事
|
||
|
||
- 在 `runTest()` 中的 `fetch()` 前增加 token 非空校验
|
||
- 优化错误提示映射：
|
||
- `401` → 需要登录后才能测试
|
||
- `403` 且 detail 含 CSRF → 安全令牌失效或未初始化，请刷新页面后重试
|
||
- 其他错误 → 保持现有通用错误兜底
|
||
|
||
#### 约束
|
||
|
||
- 不改变现有 SSE 流式处理逻辑
|
||
- 不改变现有模型选择、变量注入、Markdown 渲染逻辑
|
||
|
||
---
|
||
|
||
## 九、测试方案
|
||
|
||
## 9.1 自动化测试补齐
|
||
|
||
### 测试 1：公开详情页 GET 会设置 `ephron_csrf`
|
||
|
||
建议位置：
|
||
|
||
- `prompt/tests/test_prompt_service_api.py`
|
||
- 或更合适的 pages 路由测试文件
|
||
|
||
#### 步骤
|
||
|
||
1. 创建一个 active prompt
|
||
2. 构造已登录 client
|
||
3. `GET /prompts/{key}`
|
||
4. 断言 response / client cookies 中存在 `ephron_csrf`
|
||
|
||
#### 验证点
|
||
|
||
- 详情页自身承担了 CSRF 初始化职责
|
||
|
||
### 测试 2：首次访问详情页后可直接调用测试接口
|
||
|
||
#### 步骤
|
||
|
||
1. 构造已登录 client
|
||
2. `GET /prompts/{key}`
|
||
3. 从 client cookies 读取 `ephron_csrf`
|
||
4. 直接 `POST /api/prompts/{key}/test`
|
||
5. 请求头中传相同 token
|
||
6. 断言不返回 `403 CSRF token 验证失败`
|
||
|
||
#### 验证点
|
||
|
||
- 详情页访问一次后，测试能力可以独立工作
|
||
|
||
### 测试 3：未登录用户仍被正确拦截
|
||
|
||
#### 步骤
|
||
|
||
1. 不注入 `ephron_auth`
|
||
2. 请求 `/api/prompts/{key}/test`
|
||
3. 断言返回 `401 需要登录`
|
||
|
||
#### 验证点
|
||
|
||
- 修复不应削弱登录鉴权
|
||
|
||
### 测试 4：缺失 token 时仍正确返回 CSRF 错误
|
||
|
||
#### 步骤
|
||
|
||
1. 构造已登录 client
|
||
2. 不提供 `ephron_csrf` 或提供空 header
|
||
3. 调用测试接口
|
||
4. 断言返回 `403`
|
||
|
||
#### 验证点
|
||
|
||
- 修复不应通过绕过 CSRF 校验来“修好”功能
|
||
|
||
---
|
||
|
||
## 9.2 手工验收
|
||
|
||
### 场景 A：首次直接测试
|
||
|
||
1. 使用已登录账号登录
|
||
2. 直接访问任意公开提示词详情页
|
||
3. 不访问任何 `/admin/*` 页面
|
||
4. 切到“测试”标签
|
||
5. 输入内容后点击“开始测试”
|
||
|
||
**预期：**
|
||
|
||
- 请求成功
|
||
- 页面正常流式输出结果
|
||
- 不再出现“安全令牌未初始化”或 `CSRF token 验证失败`
|
||
|
||
### 场景 B：未登录测试
|
||
|
||
1. 清除登录态
|
||
2. 打开公开详情页
|
||
3. 执行测试
|
||
|
||
**预期：**
|
||
|
||
- 页面提示需要登录
|
||
- 后端返回 401
|
||
|
||
### 场景 C：异常 token 场景
|
||
|
||
1. 手动清除或伪造 `ephron_csrf`
|
||
2. 保留登录态
|
||
3. 再次点击测试
|
||
|
||
**预期：**
|
||
|
||
- 页面出现清晰的 token 失效/未初始化提示
|
||
- 不应只显示模糊的“请求失败”
|
||
|
||
---
|
||
|
||
## 十、验收标准
|
||
|
||
满足以下条件才算本 PRD 完成：
|
||
|
||
1. 公开提示词详情页首次加载时即可写入 `ephron_csrf`
|
||
2. 已登录用户无需访问后台页面即可直接使用测试功能
|
||
3. `/api/prompts/{key}/test` 仍保留现有 CSRF 校验机制
|
||
4. 未登录用户仍返回 401，不放宽权限
|
||
5. 前端在 token 缺失时给出明确错误提示
|
||
6. 自动化测试覆盖“详情页初始化 token”的集成场景
|
||
7. 不引入对正文展示、示例展示、模型下拉和测试流式输出的回归问题
|
||
|
||
---
|
||
|
||
## 十一、风险与注意事项
|
||
|
||
### 11.1 不要用“删除 CSRF 校验”来修问题
|
||
|
||
这是最需要避免的误修方向。问题的本质是：
|
||
|
||
- token 没初始化
|
||
|
||
而不是：
|
||
|
||
- token 校验太严格
|
||
|
||
### 11.2 注意 cookie 域与 secure 配置
|
||
|
||
`set_csrf_cookie()` 的行为受共享配置影响。上线时需确认：
|
||
|
||
- `CSRF_COOKIE_DOMAIN`
|
||
- `secure`
|
||
- `samesite`
|
||
|
||
与 `prompt.ephron.ren` 当前部署环境兼容。
|
||
|
||
### 11.3 不要让公开详情页继续隐式依赖后台页
|
||
|
||
本次修复的核心目标之一，就是消除：
|
||
|
||
- “访问过 `/admin/settings` 才能测试成功”
|
||
|
||
这种不合理依赖关系。
|
||
|
||
---
|
||
|
||
## 十二、结论
|
||
|
||
本问题的本质不是账号错误，也不是模型配置错误，而是：
|
||
|
||
> **公开提示词详情页提供了测试能力，却没有初始化该能力所需的 CSRF cookie。**
|
||
|
||
因此用户即便已经登录，测试功能仍然会失败。正确修复方式应是：
|
||
|
||
- 由公开详情页 GET 路由主动完成 CSRF 初始化
|
||
- 前端增加 token 缺失的显式兜底提示
|
||
- 保持后端现有安全校验不变
|
||
|
||
这是一次典型的“能力挂载页未承担其初始化责任”的问题，修复后应确保详情页测试能力真正独立、自洽、可首次即用。
|