Wiki.js 权限管理实战：用户组与页面访问控制设置

一、Wiki.js 权限控制模型解析：用户、用户组与路径规则

在深入动手设置之前，必须理清 Wiki.js 的权限流转逻辑。许多初次接触 Wiki.js 的管理员经常困惑于“为什么我已经把用户加到了组，但他还是看不到页面”，或者“为什么给某个组配置了只读，用户依然能随意修改”。这种现象通常源于对系统三层权限模型的理解偏差。

Wiki.js 严格遵循基于角色的访问控制（RBAC）模型，整个权限链条分为三个层次：

• 用户身份层（Users）：系统中的具体账号。用户本身不具备任何直接的页面读写授权，必须且只能通过隶属于一个或多个“用户组”来继承权限。
• 用户组全局能力层（Group Capabilities）：在每个用户组的“Roles / Permissions”中定义。这里控制的是用户组具备的全局功能开关，例如是否具有“创建页面（write:pages）”、“阅读页面（read:pages）”、“上传文件（upload:assets）”或“管理标签（manage:tags）”的能力。如果一个组在此处没有开启 write:pages，那么即使在后续的页面规则中给它分配了写权限，用户依然无法编辑。
• 路径规则过滤层（Page Rules）：在用户组配置内的“Page Rules”选项卡中定义。这里控制的是用户组的全局能力在哪些具体的页面路径树上生效。通过指定路径模式（Path Pattern）与动作（Allow / Deny），将知识库的各个目录范围与具体的行为精确挂钩。

系统安装完成后，Wiki.js 预设了三个核心系统用户组，理解这三个默认组是配置安全基线的前提：

二、实战场景与目录路径规划：配置前的关键准备

Wiki.js 的页面访问控制完全依赖页面的路径结构（Path）。路径中的斜杠 / 天然构成了目录树。如果知识库在初期没有统一的命名规范，页面随处散落，后续将无法通过简洁的通配符进行权限管控。因此，规划权限的第一步是确立团队的目录树标准。

假设我们正在为一家中型科技团队搭建知识库，涉及以下四类业务诉求：

1. 公网帮助文档：完全对外开放，无需登录即可自由查阅，但仅限技术文档专员维护。
2. 公司全员手册：内部员工登录后可见，包括行政通知、差旅标准、IT 服务指南等，全员只读。
3. 研发技术中心：仅限技术研发团队（前端、后端、测试、运维）读写与发布架构设计，其他非技术部门不可见。
4. 管理与人事保密区：包含员工绩效、薪酬方案与高管会议纪要，仅人事行政负责人与管理层可见，技术人员与普通员工完全阻断。

根据上述诉求，我们规整出清晰的路径映射表：

/
├── public/                 # 外部访客与用户可查阅的公开帮助文档
│   ├── getting-started
│   └── faq
├── internal/               # 全员内部通识文档（Authenticated 组可读）
│   ├── onboarding
│   └── company-policy
├── dept/                   # 部门专属知识库主目录
│   ├── rd/                 # 研发中心专区（仅 Group_RD 组可读写）
│   │   ├── architecture
│   │   └── api-spec
│   └── hr/                 # 人事行政专区（仅 Group_HR 组可读写）
│       ├── payroll
│       └── performance
└── archive/                # 归档历史资料（只读留存）

三、步骤详解：从创建用户组到配置页面访问规则

明确了架构与路径规划后，我们进入 Wiki.js 管理后台（点击右上角头像旁的小齿轮图标或左侧导航栏的 Administration）开展具体配置。整个流程分为四个规范步骤：

1 步骤一：创建自定义业务用户组

在管理控制台左侧菜单点击 Groups，点击右上角 New Group 创建研发团队专属组：

• Group Name：输入具有业务辨识度的英文标识，例如 Group_RD。
• Description：填写中文描述，例如 研发技术部 - 拥有 /dept/rd/* 路径下的读写与资源管理权限。
• 点击 Create 保存组基本信息。

2 步骤二：开启用户组全局功能权能（Roles & Permissions）

进入刚创建的 Group_RD 详情页，首先点击 Permissions 选项卡。这里是该组的基础能力底座。对于日常需要编写技术文档的研发人员，通常勾选以下权限：

• read:pages：允许阅读页面（必须勾选，否则无论路径规则如何设置都无法渲染）。
• write:pages：允许创建新页面与编辑已有页面内容。
• upload:assets：允许上传文档配图、PDF 附件及其他二进制文件。
• history:pages：允许查看页面的版本修改历史与代码差异比对。
• manage:tags：允许为页面添加或修改分类标签。

对于不需要让普通研发人员执行的高危操作（如 delete:pages 彻底删除页面、admin:pages 更改页面所有权与系统属性），保持取消勾选状态。设置完成后点击右下角的 Apply 保存。

3 步骤三：编排页面路径规则（Page Rules 配置详解）

点击切换至 Page Rules 选项卡。点击 New Rule 按钮添加路径访问控制条目。在弹出的规则编辑器中，需要准确理解并设定以下四个要素：

1. Path（路径模式）：填写匹配的路径前缀。支持通配符 *。例如 dept/rd/* 表示匹配 dept/rd/ 下的所有子页面；dept/rd（不带星号）则严格匹配该节点本身。建议书写为 dept/rd/* 以确保子目录递归继承。
2. Action（执行动作）：
   • ALLOW（允许）：授予该组在匹配路径下的具体操作权能。
   • DENY（拒绝）：显式切断该组在匹配路径下的操作权能。在多组权限聚合时具有最高阻断效力。
3. Permissions（具体授权项）：在当前规则下放行或封禁的行为。对于 Group_RD 访问 dept/rd/*，勾选 Read、Write、Manage。

配置完成后的 Group_RD 页面规则列表应呈现如下形态：

4 步骤四：收敛默认组（Guests 与 Authenticated）的安全基线

这是整个 Wiki.js 权限体系中最关键的一环，也是最容易出现安全漏洞的步骤：

规范的处置方式是：

• 调整 Guests 组：进入 Groups → Guests → Page Rules，删除原有的 * 规则。如果知识库包含公网帮助文档，仅添加一条 Path: public/* | Action: ALLOW | Permissions: Read；如果不包含任何公开内容，则彻底清空 Guests 的所有 Page Rules。
• 调整 Authenticated 组：对于登录用户组，默认往往也是 Path: * | Action: ALLOW | Permissions: Read。必须将其修改为仅放行公共目录 Path: internal/*，并坚决移除对 * 的通配允许，防止部门专属页面（如 dept/hr/*）被非 HR 员工直接越权读取。

四、路径规则匹配机制与权限判定逻辑

当一个用户在浏览器中请求页面（例如 /dept/rd/architecture）时，Wiki.js 的后端鉴权引擎是如何评估用户是否有权查阅或修改的？理解这一判定逻辑有助于在权限冲突时快速定位根因。

鉴权引擎按以下固定逻辑顺序进行决策：

1. 超管特殊穿透：检查当前登录用户是否隶属于 Administrators 组。如果是，直接跳过所有规则校验，返回 200 成功响应并渲染完整管理界面。
2. 聚合关联用户组的所有 Page Rules：系统收集用户所在的所有用户组（包括自动继承的 Authenticated 组与管理员手动分配的业务组），将这些组定义的所有 Page Rules 合并为一个临时规则集。
3. 路径匹配度评估：系统根据当前请求的 URL 路径，筛选出能够匹配该路径的所有规则。匹配规则支持前缀与通配符，规则深度越深、越具体的路径匹配具备参考价值。
4. 显式 DENY 强阻断判定：在所有匹配当前路径的有效规则中，只要存在任何一条动作（Action）为 DENY 的规则，并且该规则覆盖了请求的操作项，系统立即终止后续判断，直接返回 403 / 404 拒绝访问。这意味着：DENY 在多组重叠时具备压倒性优先级。
5. ALLOW 权能累加判定：如果不存在适用的 DENY 阻断，系统检查是否存在至少一条 ALLOW 规则明确包含了当前请求的行为（例如 read:pages）。如果存在，则判定授权成功，放行请求；如果匹配的所有规则均未明确赋予该行为，或者没有任何规则命中当前路径，系统遵循缺省拒绝（Default Deny）原则，拒绝访问。

五、四种典型业务场景配置方案矩阵

为帮助读者快速对照自身需求落地，下文归纳了四种常见企业级应用场景的具体参数配置矩阵与实施速查：

场景 1：全封闭企业内部知识库（严禁匿名访问）

适用场景：企业内部协同平台、研发文档中心、财务与管理制度库。要求任何未登录人员均无法看到任何文字与目录。

• Guests 组：清空所有 Page Rules；在 Permissions 中关闭所有开关。
• Authenticated 组：在 Page Rules 中添加 Path: * | Action: ALLOW | Permissions: Read, Write（如需普通员工全员可编辑），或仅赋予 Read（如需集中管控编辑权）。
• 效果：未登录用户访问任何页面，系统自动重定向至登录界面（/login）。

场景 2：跨部门敏感情报严格物理隔离

适用场景：研发（RD）与人事（HR）各自维护高度敏感文档，彼此互不可见，但共享公司公共规范。

• Authenticated 组：仅配置公共路径 Path: internal/* | Action: ALLOW | Permissions: Read。
• Group_RD 组：配置专属路径 Path: dept/rd/* | Action: ALLOW | Permissions: Read, Write, Manage。
• Group_HR 组：配置专属路径 Path: dept/hr/* | Action: ALLOW | Permissions: Read, Write, Manage。
• 效果：研发人员登录后，侧边栏只有 internal 与 dept/rd，完全看不到 dept/hr 的存在；反之 HR 亦然。

场景 3：公私混合型知识库（公开帮助中心 + 内部工作区）

适用场景：SaaS 软件团队在同一套 Wiki.js 实例中同时维护面向客户的产品使用手册与面向内部的系统部署文档。

• Guests 组：配置 Path: public/* | Action: ALLOW | Permissions: Read。
• Authenticated 组：配置 Path: internal/* | Action: ALLOW | Permissions: Read。
• Group_Doc_Editor 组：配置 Path: public/* | Action: ALLOW | Permissions: Read, Write, Upload，负责对外文档的更新与维护。

场景 4：外部审计或兼职外包人员临时访问

适用场景：外包供应商仅需查看某期项目的接口规范，或财务审计人员调阅指定年份的归档账目，严禁编辑并严禁刺探其他项目。

• 创建独立用户组 Group_Contractor。
• 在 Permissions 中仅勾选 read:pages，取消所有写、上传、移动及历史记录权限。
• 在 Page Rules 中添加单点路径放行：Path: dept/rd/project-alpha/* | Action: ALLOW | Permissions: Read。

六、权限验证与排错自查指南

权限配置完成后，严禁仅凭管理员账号自测。由于管理员拥有全站无条件穿透特权，管理员测试永远无法发现普通用户的权限阻断或越权问题。必须按照以下规范开展验证：

1. 三维交叉验证流程

1. 无痕访客态验证：打开浏览器的“隐私模式 / 无痕窗口”，在未登录状态下访问知识库首页与各个深度路径（如 http://wiki.local/dept/rd/api-spec）。预期结果应为跳转至登录页或直接返回 403/404，绝不能直接呈现文档内容。
2. 普通员工态验证：使用仅隶属于 Authenticated 的测试账号登录，检查侧边栏是否仅出现 internal 公共目录，尝试在浏览器地址栏手动输入研发私密路径，确认系统能够准确拦截。
3. 特定部门态验证：使用隶属于 Group_RD 的测试账号登录，确认其在 /dept/rd/* 路径下能够看到编辑按钮、能正常上传图片附件，且在尝试删除页面时受到系统限制。

2. 常见问题与排查清单

问题一：已经给用户组配置了路径允许规则，为什么用户打开页面依然显示“Unauthorized / 403 Forbidden”？

排查步骤：首先回到该用户组的 Permissions（基础权能）选项卡，检查是否开启了 read:pages。Wiki.js 规定基础权能是路径规则的前提，若组本身没有“读页面”的全局功能，路径规则中的 ALLOW 不会产生任何效果。

问题二：为什么用户在侧边栏中看不到子页面，但通过完整 URL 却可以直接访问？

排查步骤：检查导航路径中的父节点权限。如果用户拥有 dept/rd/api 的读权限，但管理员对父级 dept 或 dept/rd 配置了限制，且未在父节点创建实体索引页，Wiki.js 的导航渲染器可能无法正确建立树形索引。确保在每个目录层级都创建对应的索引落地页，并赋予该组读权限。

问题三：一个用户加入了两个组，A 组允许访问 dept/*，B 组拒绝访问 dept/secret/*，最终该用户能否访问 dept/secret/doc1？

排查结论：不能访问。Wiki.js 的权限仲裁机制严格执行“DENY 强阻断优先”原则。只要用户命中的规则集中存在对该路径的显式 DENY，任何其他组的 ALLOW 都将被彻底覆盖。