Elaina/ephron-ren-prd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add prompt test csrf initialization fix prd

Browse Source
This commit is contained in:
Ubuntu
2026-05-25 11:15:32 +08:00
parent 892daacd58
commit ffad56f21b
1 changed files with 507 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

507
prd-prompt-test-csrf-initialization-fix.md Normal file
View File

@@ -0,0 +1,507 @@
# 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 缺失的显式兜底提示
- 保持后端现有安全校验不变
这是一次典型的“能力挂载页未承担其初始化责任”的问题，修复后应确保详情页测试能力真正独立、自洽、可首次即用。