93 lines
3.5 KiB
Markdown
93 lines
3.5 KiB
Markdown
# Docs Gatekeeper 鉴权系统计划
|
||
|
||
**状态**：已实现，当前行为见 [Docs Gatekeeper 开发说明](/home/ray/dev/linkong/planet/docs/technical/zh/docs-gatekeeper-development.md)
|
||
**创建日期**：2026-05-08
|
||
**核心目标**：把 `/docs` 从前端公开打包 Markdown 改成后端受控读取，并通过用户 Gatekeeper 权限组划分公开文档、用户文档、开发文档和管理/运维文档。
|
||
|
||
## 背景
|
||
|
||
当前 Docs 页面通过前端 `import.meta.glob(...?raw)` 把 `docs/technical/{zh,en}` 中注册过的 Markdown 直接打进前端 bundle。即使在前端隐藏目录或增加路由守卫，受保护 Markdown 仍可能出现在构建产物中，无法形成真正鉴权。
|
||
|
||
本阶段需要把文档正文读取迁到后端，并让后端根据当前用户身份返回可见目录和正文。Earth 仍保持公开访问，其它控制台模块暂不改变既有鉴权。
|
||
|
||
## 鉴权模型
|
||
|
||
保留现有 `users.role`，新增 `gatekeeper_groups` 作为可叠加的权限组。`role` 继续用于控制台和系统操作；Gatekeeper 只负责 Docs 等内容权限。
|
||
|
||
默认权限：
|
||
|
||
| 身份 | 默认 Docs 能力 |
|
||
| --- | --- |
|
||
| 未登录访客 | `public` |
|
||
| 普通登录用户 | `public`，以及用户被分配的 Gatekeeper 组 |
|
||
| `admin` | `docs_admin`，并隐含 `docs_developer` / `docs_user` |
|
||
| `super_admin` | 全部 Docs 权限 |
|
||
|
||
Gatekeeper 组：
|
||
|
||
- `docs_user`：登录用户操作类文档。
|
||
- `docs_developer`：开发、前端、后端、Earth 实现文档。
|
||
- `docs_admin`：运维、服务控制、凭证、环境变量和敏感操作文档。
|
||
|
||
## 初步文档划分
|
||
|
||
`public`：
|
||
|
||
- `README.md`
|
||
- `quickstart.md`
|
||
- `manual.md`
|
||
|
||
`docs_developer`：
|
||
|
||
- `earth-frontend-context.md`
|
||
- `earth-interactable-usage.md`
|
||
- `earth-layer-style-reference.md`
|
||
- `earth-render-layer-order.md`
|
||
- `earth-satellite-footprint-policy.md`
|
||
- `earth-bgp-context.md`
|
||
- `earth-news-live-streams-collector-format.md`
|
||
- `earth-toolbar-overlay-coordination.md`
|
||
- `frontend-admin-frontend-context.md`
|
||
- `frontend-layout-guidelines.md`
|
||
- `backend-collectors.md`
|
||
- `datasource-collector-settings-connectivity.md`
|
||
- `backend-datasources-api-performance.md`
|
||
- `agents-aiprovider.md`
|
||
|
||
`docs_admin`：
|
||
|
||
- `backend-system-service-control.md`
|
||
- `ops-docker-compose-buildx-upgrade.md`
|
||
- `ops-planet-sh-startup.md`
|
||
|
||
## 实施要点
|
||
|
||
后端新增：
|
||
|
||
- `GET /api/v1/docs/catalog`：返回当前用户可见文档目录；未登录只返回 `public`。
|
||
- `GET /api/v1/docs/{lang}/{slug}`：返回单篇 Markdown；未登录访问受保护文档返回 `401`，已登录无权限返回 `403`。
|
||
- 服务端维护文档 metadata 白名单，禁止任意路径读取。
|
||
|
||
用户管理新增：
|
||
|
||
- `users.gatekeeper_groups` JSON 字段。
|
||
- 用户列表、创建和编辑支持展示/配置 Gatekeeper 权限组。
|
||
- 只有 `super_admin` 能编辑 Gatekeeper 权限组。
|
||
|
||
前端 Docs 改造：
|
||
|
||
- 移除 Markdown raw import 作为正文来源。
|
||
- 从后端 catalog 构建目录和搜索记录。
|
||
- 从后端 content API 加载正文。
|
||
- 对 `401` 显示登录入口，对 `403` 显示无权限提示。
|
||
|
||
## 验证
|
||
|
||
- 未登录用户只能看到和读取 `public` 文档。
|
||
- 未登录直接访问受保护文档返回 `401` 并显示登录提示。
|
||
- 无 Gatekeeper 组的普通用户访问开发文档返回 `403`。
|
||
- `docs_developer` 用户能读开发文档，不能读管理/运维文档。
|
||
- `admin` 和 `super_admin` 能读管理/运维文档。
|
||
- 未知 slug、未知语言和路径穿越字符串不能读取文件。
|
||
- 前端构建产物不再包含受保护 Markdown raw import 生成的文档模块。
|