访问控制
选择读者访问文档的方式：公开、密码保护、混合访问、JWT 登录或 SSO。
Jamdesk 提供五种方式来控制谁可以阅读您的文档。大多数团队会选择一种方式并一直使用；有些团队则会混合使用。
选择合适的方式
| 方式 | 适用场景 | 设置 |
|---|---|---|
| 完全公开 | 面向外部用户的产品文档、开源项目，以及任何希望被索引和分享的内容。 | 默认设置；无需配置。 |
| 全站密码保护 | 所有内容都是内部资料：工程运行手册、仅供合作伙伴查看的文档、尚未发布的产品。使用一个共享密码保护整个网站。 | 在 docs.json 中设置 auth.password.enabled: true，并在仪表板中设置密码。请参阅密码保护。 |
| 混合模式（部分页面私有） | 大多数文档公开，少数内容为内部资料（运行手册、测试版功能、内部 API 参考）。 | 在内部页面的 frontmatter 中添加 private: true，或将页面列在 auth.password.private[] 下。请参阅密码保护。 |
| 使用您自己的登录（JWT） | 读者已经登录您的产品。您的后端为每位读者签发短期令牌，Jamdesk 将其转换为会话，并可将页面限制为令牌中指定的群组。 | 在 docs.json 中设置 auth.jwt.enabled: true 和 loginUrl，并从仪表板获取签名密钥。所有套餐均包含此功能。请参阅 JWT 身份验证。 |
| SSO（Enterprise） | 读者应使用您现有的身份提供商登录：无需共享密码，具备审计跟踪，还可以通过移除用户来取消其访问权限。 | Enterprise 套餐。请参阅 SSO。 |
随时编辑 docs.json 并推送更改，即可在不同方式之间切换。从全站模式切换到混合模式（或反向切换）只需一次构建。
常见模式
在一个项目中同时提供内部和外部文档
大多数团队希望将大量内部文档放在登录保护之后，同时为客户提供一个较小的公开网站。您不需要创建两个项目。在单个 Jamdesk 项目中使用混合模式：
---
title: Incident Runbook
private: true
---设置了 private: true 的页面会受到保护；其他页面仍保持公开。所有内容都位于同一个代码库中，只需一次构建和一个仪表板。只有当读者访问受保护页面时，解锁屏幕才会出现。
对于较大的内部内容区域，可以在 docs.json 中列出路径，而不是为每个文件单独添加标记。注意：auth.password.private[] 会自动启用特定页面模式。不要同时添加 enabled: true（那是全站模式，与此处的目标相反）。
{
"auth": {
"password": {
"hint": "Ask the on-call engineer",
"private": ["/internal/**", "/admin/runbook"]
}
}
}两个独立项目
仅当不同受众需要完全不同的品牌、独立的自定义域名、独立的分析数据或不同的套餐层级时，才使用两个项目。例如，一个位于 docs.acme.com 的公开文档网站，以及一个位于 internal.acme.com 的独立内部 wiki。维护成本更高：需要两次构建、两个仪表板和两个域名。
通过您自己的登录实现按用户访问
如果您的客户已经拥有您的账户，使用共享密码反而是一种倒退：密码会被转发，也不会自动过期，还无法区分不同客户。借助 JWT 身份验证，已登录用户打开您的文档时会被重定向到您一方的 URL，您的后端会签发令牌，Jamdesk 则为该用户创建会话。读者无需拥有 Jamdesk 账户，也不存在可被转发的共享密钥。
令牌还可以携带群组信息。在页面的 frontmatter 中添加 groups: ["admin"] 后，只有令牌中列出了 admin 的访客才能打开该页面，或在导航中看到该页面。其他人会收到 404，因此页面不会暴露其存在。
---
title: Enterprise audit log API
groups: ["enterprise"]
---对于应保持公开的部分（例如变更日志或状态页面），可以将其与 public 路径结合使用。
文档网站的 SSO
在 Enterprise 套餐中，读者可以使用您的身份提供商（Okta、Google Workspace、Azure AD 等）登录，而不是输入共享密码。如果您需要跟踪谁阅读了哪些内容，或者用户离职时必须立即撤销其文档访问权限，SSO 是最合适的选择。请参阅 SSO，了解概览信息以及如何开始与销售团队沟通。
编辑者与读者
人们有时会混淆三种不同的访问概念：
| 角色 | 他们的操作 | 访问方式 |
|---|---|---|
| 编辑者 | 编写和更新 MDX 内容。 | 通过向已连接的 GitHub 代码库提交 MDX 来编辑文档，因此您的 GitHub 代码库权限就是编辑者权限。Jamdesk 没有额外叠加的独立编辑者角色：任何可以推送到文档分支的人都可以发布更改。 |
| 读者 | 查看已发布的文档网站。 | 所有人（公开模式）、拥有密码的任何人（密码模式）、登录流程为其签发令牌的任何人（JWT），或通过您的 IdP 完成身份验证的任何人（SSO）。 |
| 仪表板团队成员 | 在 Jamdesk 仪表板中管理构建、分析数据和项目设置。 | 通过仪表板中的 Settings → Team 邀请。他们不会直接编写内容。请参阅团队成员。 |
一位队友可以同时属于上述三种角色中的任意组合。这些角色彼此独立。