4.3 KiB
4.3 KiB
Docs Gatekeeper 开发说明
Docs Gatekeeper 把 /docs 从“前端构建时打包所有 Markdown”改成“后端按权限返回目录和正文”。它的目标是让公开使用手册、用户文档、开发文档和管理/运维文档在同一个 Docs 页面内可检索，但正文读取必须经过服务端白名单和用户权限检查。
用户侧说明见 Planet 使用手册 的 Docs 章节。
鉴权模型
Docs 使用两层权限：
users.role：保留给控制台系统权限。users.gatekeeper_groups：Docs 内容权限组。
权限组：
| 组 | 用途 |
|---|---|
docs_user |
用户操作类文档 |
docs_developer |
Earth、前端、后端、采集器和 AI Provider 开发文档 |
docs_admin |
服务控制、运维、环境变量和敏感操作文档 |
继承规则：
- 未登录用户只能读
public。 docs_developer隐含docs_user。docs_admin隐含docs_developer和docs_user。admin和super_admin默认拥有全部 Docs 权限。
后端入口
文件：
API：
GET /api/v1/docs/catalog
GET /api/v1/docs/{lang}/{slug}
catalog 只返回当前用户可见文档。正文接口会先校验语言、slug 和文件是否在 metadata 白名单里，再判断权限：
- 未登录访问受保护文档：
401。 - 已登录但权限不足：
403。 - 未知语言、未知 slug 或文件不存在：
404。
正文文件只能来自 docs/technical/{zh,en}/ 下的白名单文件，不能通过路径拼接读取任意文件。
Metadata 来源
当前服务端 metadata 维护在 docs_gatekeeper.py：
DocsMetadata(
"manual.md",
"manual",
"public",
"Manual",
2,
"Planet 使用手册",
"Planet Manual",
)
新增公开文档时，需要同步：
- 新增中英文 Markdown 文件。
- 在服务端
DOCS_METADATA添加 filename、slug、access、group、order、标题。 - 在前端 docs-content.ts 添加同名 metadata，保持导航标题和排序一致。
- 如果需要从 README 发现，更新
docs/technical/zh/README.md和docs/technical/en/README.md。
用户管理
users 表新增 gatekeeper_groups JSONB DEFAULT '[]'。启动时 session.py 会用 ALTER TABLE ... ADD COLUMN IF NOT EXISTS 补列，适配已有本地数据库。
用户 API 负责：
- 创建用户时写入
gatekeeper_groups。 - 更新用户时校验组名只能是
docs_user、docs_developer、docs_admin。 - 只有
super_admin能修改 Gatekeeper 权限组。
前端 Users.tsx 展示权限组标签，并在编辑表单中提供多选框。非 super_admin 打开的表单会禁用该字段，并在提交前移除 gatekeeper_groups。
前端 Docs 加载
文件：
关键变化：
- 移除
import.meta.glob(...?raw)作为正文来源。 - 页面加载时请求
/api/v1/docs/catalog构建当前可见目录。 - 打开正文时请求
/api/v1/docs/{lang}/{slug}。 - 搜索只索引当前用户可见文档，并按需从后端读取 Markdown。
401显示登录提示，403显示权限提示，404显示文档不可用。
测试覆盖
相关测试：
测试应覆盖：
- 匿名用户只能看到 public 文档。
- 受保护正文的
401/403。 docs_developer可读开发文档但不能读管理文档。admin和super_admin可读管理文档。- 未知 slug、未知语言和路径穿越字符串不能读取文件。