Skip to content

登录与权限

本站（www.gmaster.wiki）支持「登录后才可见」的内容。本文说明队员怎么用、写文档的人怎么加， 以及背后的鉴权机制。

一、队员：怎么登录、能看到什么

  1. 点页面右上角的 登录，跳到统一认证中心 auth.apoints.email；
  2. 用你的 CAF 账号登录（没有账号就在认证中心注册，或用队长给你的账号）；
  3. 同意授权后自动跳回本站，右上角显示你的昵称，点它旁边的「退出」可以登出。

登录之后能看哪些内部内容，由你在 CAF 里的权限节点决定，而不是「登录了就全都能看」。 访问没有权限的目录时，页面会直接告诉你缺哪个权限节点，把这句话发给管理组即可。

组别权限是自动发的

不用找管理组手动授权：官网（gmaster.team）按你的组别自动把对应节点发到你的 CAF 账户上。

  • 你在官网上绑定 CAF 账户、或者用 CAF 登录官网时，官网会读你的组别并授权；
  • 对应关系：电控组/软件组 → wiki.private.software，机械组 → …mechanical， 视觉组 → …vision，硬件组 → …hardware，宣运组 → …media； 有管理权限的成员额外拿到 wiki.private.management；
  • 只增不减：换了组别，新组的权限会加上，旧组的权限保留（要收回请找管理组在官网后台撤销）。

侧边目录里的入口

登录成功后，左侧目录最上面会多出一项 内部资料目录（默认展开），按你的权限列出 「软件组内部资料 / 机械组内部资料 / …」，点一下直达。没有登录时这一项不显示。

内部内容都在 https://www.gmaster.wiki/_private/ 下，入口见内部资料。

二、写文档的人：三种「受保护」的写法

1. 整页私有（推荐）

把页面放进私有文档仓库 GMasterEmbeddedGroup/GmasterDocPrivate 的 docs/ 下对应目录即可， 目录名决定它需要哪个权限节点：

私有仓库里的目录 线上路径 需要的权限节点
docs/index.md /_private/ 登录即可
docs/软件组/ /_private/软件组/ wiki.private.software
docs/机械组/ /_private/机械组/ wiki.private.mechanical
docs/视觉组/ /_private/视觉组/ wiki.private.vision
docs/硬件组/ /_private/硬件组/ wiki.private.hardware
docs/宣运组/ /_private/宣运组/ wiki.private.media
docs/管理/ /_private/管理/ wiki.private.management

写法与公开站一致（纯 Markdown）。推送到私有仓库后，服务器上的定时任务每 5 分钟自动重建， 不想等就让管理组跑一次 bash /opt/gmasterdoc-private/deploy.sh --force。

私有仓库不进公开仓库：公开仓库是所有人可见的，把内部资料放进去等于公开发布。

2. 公开页面里嵌一段「登录后可见」

  1. 片段（原生 HTML，不走 Markdown 渲染）放在私有仓库的 docs/fragments/ 下；
  2. 在公开站页面里写一行：
<div data-caf-gate data-src="/_private/fragments/公告.html"></div>

未登录时显示「登录后可见」，登录后自动取回并渲染。片段本身在门禁之内，未登录拿不到内容。

还可以加 data-caf-require="wiki.private.software"：这样没有该权限的访客会直接看到 「需要权限节点 …」，不会再白跑一次请求。

3. 新建一个受限目录

  1. 私有仓库里建目录与页面，并加进 mkdocs.yml 的 nav；
  2. 在 CAF 的 gmaster 命名空间里建同名权限节点；
  3. 在服务器 /etc/caf-wiki-gate/acl.json 里加一条映射（改完即生效，不用重启）。

三、背后的机制（想深入再看）

登录与私有内容的鉴权时序图：浏览器 → nginx → caf-wiki-gate → CAF
图：从「点开一个私有页面」到「文件发到浏览器」的完整链路
  • 登录由 CAF 负责（标准 OIDC 授权码流程），本站不保存密码；CAF 的 access token 只存在 服务器端会话里，不下发到浏览器。
  • 权限来自 CAF 的 gmaster 权限命名空间：官网 gmaster.team 维护权限树并给用户授权， 本站登录后读取该用户在命名空间内的节点，缓存 5 分钟。
  • 授权由官网写入，本站只读：官网在「队员绑定 CAF / 用 CAF 登录官网 / 管理员改组别」这三处 按组别调用 CAF 命名空间接口补授节点；因此队员在官网绑定一次，本站这边就有权限了。
  • 想看整套系统的全貌（三套系统怎么拼起来、权限树怎么设计、出问题去哪查），见管理组那份 《网站完整架构》：https://www.gmaster.wiki/_private/管理/网站完整架构/（需要 wiki.private.management）。
  • 文件由 nginx 发送，网关只做鉴权（这台 nginx 没有编译 auth_request 模块， 所以用「反代 + X-Accel-Redirect」实现同一效果）。
  • 未登录访问私有区会跳转登录，登录后自动回到原来想看的页面。

作者: GMaster 管理组 | 修改日期: 2026-09-20