---
title: 访问控制
description: "选择读者访问文档的方式：完全公开、密码保护、混合访问、自有 JWT 登录或 SSO。"
---
> **For AI agents:** the complete documentation index is at [llms.txt](https://jamdesk.com/docs/llms.txt). Append `.md` to any page URL for its markdown version.
Jamdesk 提供五种方式来控制谁可以阅读文档。大多数团队会选择一种并一直使用；也有团队会组合使用。
## 选择合适的方式
| 方式 | 适用场景 | 设置 |
|---|---|---|
| **完全公开** | 面向外部的产品文档、开源项目，以及任何希望被搜索引擎收录并可分享的内容。 | 默认设置；无需配置。 |
| **全站密码保护** | 所有内容都是内部资料：工程运行手册、仅供合作伙伴查看的文档，或尚未发布的产品资料。整个网站由一个共享密码保护。 | 在 `docs.json` 中设置 `auth.password.enabled: true`，并在仪表板中设置密码。请参阅[密码保护](https://jamdesk.com/docs/cn/setup/password-protection)。 |
| **混合访问（部分页面设为私密）** | 大部分文档公开，少数内容为内部资料（例如运行手册、Beta 功能或内部 API 参考）。 | 在内部页面的 frontmatter 中添加 `private: true`，或在 `auth.password.private[]` 下列出这些页面。请参阅[密码保护](https://jamdesk.com/docs/cn/setup/password-protection)。 |
| **自有登录（JWT）** | 读者已经登录你的产品。你的后端为每位读者签发短期令牌，Jamdesk 将其转换为会话；你还可以限制只有令牌中指定的用户组才能访问页面。 | 在 `docs.json` 中设置 `auth.jwt.enabled: true` 和 `loginUrl`，并从仪表板获取签名密钥。所有套餐均包含此功能。请参阅 [JWT 身份验证](https://jamdesk.com/docs/cn/setup/jwt-authentication)。 |
| **SSO（Enterprise）** | 读者需要通过现有身份提供商登录：无需共享密码，可保留审计记录，并能通过移除用户来取消其访问权限。 | 需要 Enterprise 套餐。请参阅 [SSO](https://jamdesk.com/docs/cn/setup/sso)。 |
你可以随时编辑 `docs.json` 并推送更改，以切换访问方式。从全站保护切换到混合访问（或反向切换）只需一次构建。
## 常见模式
### 在一个项目中同时提供内部和外部文档
大多数团队既希望通过登录保护大量内部文档，也希望为客户提供规模较小的公开网站。你不需要创建两个项目。在同一个 Jamdesk 项目中使用**混合模式**即可：
```yaml
---
title: Incident Runbook
private: true
---
```
设置了 `private: true` 的页面会受到访问限制；其他页面则保持公开。所有内容都在同一个代码仓库中，只需一次构建，并使用一个仪表板。读者访问受限页面时，才会看到解锁页面。
对于较大的内部内容板块，可以在 `docs.json` 中列出路径，而不必逐个标记文件。注意：`auth.password.private[]` 会自动启用特定页面模式。不要同时添加 `enabled: true`（这会启用全站模式，与你在此处需要的设置相反）。
```json docs.json
{
"auth": {
"password": {
"hint": "Ask the on-call engineer",
"private": ["/internal/**", "/admin/runbook"]
}
}
}
```
### 两个独立项目
只有当不同受众需要完全不同的品牌形象、独立的自定义域名、单独的分析数据或不同的套餐等级时，才使用两个项目。例如：在 `docs.acme.com` 上提供公开文档，并在 `internal.acme.com` 上单独搭建内部 Wiki。维护成本会更高：需要两次构建、两个仪表板和两个域名。
### 通过您自己的登录实现按用户访问
如果客户已经在你的产品中拥有账户，共享密码反而是一种倒退：密码可能会被转发，不会自动过期，也无法区分不同客户。使用 [JWT 身份验证](https://jamdesk.com/docs/cn/setup/jwt-authentication)时，已登录用户打开文档后会跳转到你这边的 URL；你的后端会签发令牌，Jamdesk 则为该用户创建会话。读者不需要 Jamdesk 账户，也无需转发共享密钥。
令牌还可以携带用户组。在页面的 frontmatter 中添加 `groups: ["admin"]` 后，只有令牌中包含 `admin` 的访客才能打开该页面或在导航中看到它。其他人会收到 404，因此页面的存在也不会被泄露。
```yaml
---
title: Enterprise audit log API
groups: ["enterprise"]
---
```
对于应该保持公开的网站内容（例如更新日志或状态页面），可以同时配置 `public` 路径。
### 文档网站的 SSO
使用 Enterprise 套餐时，读者可以通过你的身份提供商（Okta、Google Workspace、Azure AD 等）登录，而不必输入共享密码。如果你需要审计谁阅读了哪些内容，或者需要在用户离职时立即撤销其文档访问权限，SSO 尤其适用。请参阅 [SSO](https://jamdesk.com/docs/cn/setup/sso)，了解概况以及如何开始与销售团队沟通。
## 编辑者与读者
人们有时会混淆三种不同的访问概念：
| 角色 | 操作 | 如何授予访问权限 |
|---|---|---|
| **编辑者** | 编写和更新 MDX 内容。 | 通过向已连接的 GitHub 代码仓库提交 MDX 来编辑文档，因此**谁有权提交，由你的 GitHub 代码仓库权限决定**。只有推送者是 Jamdesk 项目成员（通过关联的 GitHub 账户或邮箱匹配），或是你授权的自动化账户时，推送才会触发构建。其他人的推送会显示为构建失败，项目所有者也会收到邮件。请参阅 [GitHub](https://jamdesk.com/docs/cn/integrations/github#构建没有触发)。 |
| **读者** | 查看已发布的文档网站。 | 所有人（公开模式）、知道密码的人（密码模式）、登录流程为其签发令牌的人（JWT），或通过你的 IdP 完成身份验证的人（SSO）。 |
| **仪表板团队成员** | 在 Jamdesk 仪表板中管理构建、分析数据和项目设置。 | 通过仪表板中的 **Project Settings → Members** 邀请。成员身份也是允许某人的推送触发构建的条件。请参阅[团队成员](https://jamdesk.com/docs/cn/help/projects/team-members)。 |
同一位队友可以兼具这三种角色中的任意组合，但它们之间有一项关联：编辑者还必须是团队成员，其推送才会触发构建。
## 接下来做什么？
了解全站和单页密码保护、提示信息、密码轮换及会话控制。
通过自有登录保护文档，并使用单用户会话和按用户组限制的页面。
使用身份提供商登录仪表板和文档。
```