# 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 生成的文档模块。