Jamdesk Documentation logo

访问控制

选择读者访问文档的方式：完全公开、密码保护、部分公开或私有，或使用 SSO。比较各选项，选择适合受众的方案。

Jamdesk 提供四种方式来控制谁可以阅读你的文档。大多数团队会选择一种方式并长期使用，也有些团队会组合使用。

选择合适的方案

方案适用场景设置
完全公开面向外部的产品文档、开源项目，以及任何希望被索引和分享的内容。默认设置；无需配置。
全站密码保护所有内容均为内部资料：工程运行手册、仅限合作伙伴查看的文档、尚未发布的产品。使用一个共享密码保护整个站点。在 docs.json 中设置 auth.password.enabled: true，并在仪表板中设置密码。参阅密码保护。
混合模式（部分页面私有）大多数文档公开，少数内容为内部资料（运行手册、Beta 功能、内部 API 参考）。在内部页面的 frontmatter 中添加 private: true，或将其列在 auth.password.private[] 下。参阅密码保护。
SSO（企业版）读者应使用现有身份提供商登录：无需共享密码、可保留审计记录，并可通过移除用户取消访问。企业版计划。参阅SSO。

你可以随时编辑 docs.json 并推送，以切换方案。从全站模式切换到混合模式（或反向切换）只需一次构建。

常见模式

在一个项目中同时提供内部和外部文档

大多数团队希望将大量内部文档置于登录保护之后，同时为客户提供规模较小的公开站点。你不需要创建两个项目。在单个 Jamdesk 项目中使用混合模式：

---
title: Incident Runbook
private: true
---

设置 private: true 的页面会受到保护；其他页面保持公开。所有内容都位于同一个代码仓库中，使用一次构建和一个仪表板。只有当读者访问受保护的页面时，解锁页面才会显示。

对于较大的内部文档区域，与其标记每个文件，不如在 docs.json 中列出路径。注意：auth.password.private[] 会自动启用特定页面模式。不要同时添加 enabled: true（那是全站模式，与此处的需求相反）。

docs.json
{
  "auth": {
    "password": {
      "hint": "Ask the on-call engineer",
      "private": ["/internal/**", "/admin/runbook"]
    }
  }
}

两个独立项目

仅当不同受众需要完全不同的品牌、独立的自定义域名、独立的分析数据或不同的计划层级时，才使用两个项目。例如：位于 docs.acme.com 的公开文档站点，以及位于 internal.acme.com 的独立内部 Wiki。维护成本更高：需要两次构建、两个仪表板和两个域名。

文档站点使用 SSO

在企业版计划中，读者可以使用你的身份提供商（Okta、Google Workspace、Azure AD 等）登录，而不必输入共享密码。当你需要记录谁阅读了哪些内容，或用户离职后必须立即撤销其文档访问权限时，SSO 最为适合。参阅SSO了解概览信息，以及如何开始与销售团队沟通。

编辑者与读者

人们有时会混淆三种不同的访问概念：

角色他们做什么如何授予访问权限
编辑者编写和更新 MDX 内容。通过向已连接的 GitHub 代码仓库提交 MDX 来编辑文档，因此你的 GitHub 代码仓库权限就是编辑权限。Jamdesk 没有在此基础上叠加独立的编辑者角色：任何能够推送到文档分支的人都可以发布更改。
读者查看已发布的文档站点。所有人（公开模式）、知道密码的人员（密码模式），或通过 IdP 验证身份的人员（SSO）。
仪表板团队成员在 Jamdesk 仪表板中管理构建、分析数据和项目设置。通过仪表板中的 Settings → Team 邀请。他们不会直接编写内容。参阅团队成员。

团队成员可以同时属于上述三种角色中的任意组合。这些角色彼此独立。

接下来做什么？

密码保护

全站和单页面密码保护、提示信息、密码轮换及会话控制。

SSO（企业版）

使用身份提供商登录仪表板和文档站点。