Jamdesk Documentation logo

访问控制

选择读者访问文档的方式：完全公开、密码保护、公开与私有混合、基于 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（企业版）读者应使用您现有的身份提供商登录：无共享密码、有审计记录，并可通过移除用户来取消访问权限。企业版套餐。参见 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。维护成本更高：两次构建、两个仪表板、两个域名。

通过您自己的登录实现按用户访问

当您的客户已在您处拥有账户时，共享密码就是一种倒退。它容易被转发，不会自动过期，也无法区分不同的客户。JWT 身份验证会将已登录的读者引导至您一侧的 URL。您的后端签发令牌，Jamdesk 为该读者创建会话。读者无需 Jamdesk 账户，也不存在可被转发的共享密钥。

令牌还可以携带分组信息。在页面的 frontmatter 中添加 groups: ["admin"]，则只有令牌中列出 admin 的访问者才能打开该页面或在导航中看到它。其他人将收到 404 错误，页面也不会暴露其存在。

---
title: Enterprise audit log API
groups: ["enterprise"]
---

对于应保持开放的站点部分（例如更新日志或状态页面），可将其与 public 路径搭配使用。

文档网站的 SSO

企业版套餐的读者使用您的身份提供商（Okta、Google Workspace、Azure AD 等）登录，而非输入共享密码。当您需要记录谁阅读了什么，或在离职时需要立即撤销文档访问权限时，请使用此方式。参见 SSO 了解概览及如何联系销售。

编辑者与读者

Jamdesk 有三种独立的访问角色：

角色职责访问权限如何授予
编辑者编写和更新 MDX 内容。文档通过向您已连接的 GitHub 仓库提交 MDX 进行编辑。您的 GitHub 仓库权限决定谁可以提交。只有推送者是 Jamdesk 项目成员（通过其关联的 GitHub 账户或电子邮件匹配）或您已授权的自动化账户时，推送才会触发构建。来自其他人的推送会显示为构建失败。项目所有者会收到一封电子邮件。参见 GitHub。
读者查看已发布的文档站点。所有人（公开模式）、拥有密码的人（密码模式）、您的登录流程为其签发令牌的人（JWT），或通过您的 IdP 认证的人（SSO）。
仪表板团队成员在 Jamdesk 仪表板中管理构建、分析和项目设置。通过仪表板中的项目设置 → 成员邀请。成员身份也决定了一个人的推送能否触发构建。参见团队成员。

同一位团队成员可以同时拥有以上多种角色。一条规则将它们联系在一起：编辑者的推送只有在该编辑者同时也是团队成员时才会触发构建。

接下来做什么？

密码保护

全站和逐页密码保护、提示、轮换及会话控制。

JWT 身份验证

通过您自己的登录保护文档，支持逐用户会话和分组限制页面。

SSO（企业版）

通过您的身份提供商登录仪表板和文档。