planet/docs/plans/docs-gatekeeper-auth-plan.md

Docs Gatekeeper 鉴权系统计划

状态：已实现，当前行为见 Docs Gatekeeper 开发说明
创建日期：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 生成的文档模块。