密码保护

有时，您希望文档继续存储在 Git 中并在线提供，但不对所有人可见。常见场景包括运行手册、预发布指南、仅限合作伙伴的文档和抢先体验功能。密码保护功能提供一个共享密码，可保护整个站点或指定页面，而无需将任何内容移出已有仓库。

屏幕截图显示的是英文界面。

应选择哪种模式？

Jamdesk 提供两种密码保护模式。请根据哪些内容公开、哪些内容不公开来选择。

两种模式共用同一个仪表板卡片、解锁页面以及轮换和撤销控制项。您可以随时编辑 docs.json 并推送，以便在两种模式之间切换。

保护整个站点

{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "Acme Docs",
  "theme": "jam",
  "auth": {
    "password": {
      "enabled": true,
      "hint": "Ask #docs-access on Slack"
    }
  }
}

git add docs.json
git commit -m "Turn on password protection"
git push

# Should respond with HTTP/1.1 401 and the unlock HTML
curl -I https://acme.jamdesk.app/

# Submit the password. On success, sets the jd_auth_<slug> cookie.
curl -i -X POST https://acme.jamdesk.app/jd/unlock \
  -d "password=your-passphrase&from=/"

公开例外

全站模式提供一个例外机制：即使站点其余部分受到保护，您仍可以让特定页面保持公开。这样，您可以在私有文档旁边发布营销落地页或注册表单。

您有三种方式可以将页面标记为公开，它们都会在每次构建时合并到同一个允许列表中。

Frontmatter 是粒度最细的选项。在任意 .mdx 文件中添加 public: true，只有该页面会绕过保护：

---
title: Get started
public: true
---

导航组 可以一次覆盖整个部分。在 docs.json 的导航中将 public: true 设置在 group 或 tab 上，该项下的所有页面都会公开。适用于在私有工程文档旁边放置一个名为“Marketing”的标签页：

{
  "navigation": {
    "tabs": [
      {
        "tab": "Marketing",
        "public": true,
        "groups": [
          {
            "group": "Overview",
            "pages": ["landing", "pricing", "changelog"]
          }
        ]
      },
      {
        "tab": "Internal",
        "groups": [
          { "group": "Runbooks", "pages": ["deploys", "oncall"] }
        ]
      }
    ]
  }
}

auth.password.public[] 下的显式 glob 可处理 frontmatter 和导航无法覆盖的内容，例如顶级落地页、动态生成的路由，或您不想重写的整个子树。

{
  "auth": {
    "password": {
      "enabled": true,
      "hint": "Ask #docs-access on Slack",
      "public": [
        "/landing",
        "/pricing",
        "/marketing/**",
        "/blog/*"
      ]
    }
  }
}

Glob 支持 *（一个路径段）和 **（任意深度）。验证时会拒绝单独的 /：如果 Jamdesk 接受该值，一个简单的拼写错误就可能静默解锁整个站点。每次构建后，仪表板卡片都会显示解析后的允许列表，您可以检查构建实际采用了哪些配置。

只保护少数页面

特定页面模式采用相反的流程：默认所有内容公开，您可以选择将单个页面加入保护范围。

---
title: Incident Runbook
description: What to do when the deploys dashboard is on fire.
private: true
---

{
  "auth": {
    "password": {
      "hint": "Ask the on-call engineer",
      "private": ["/admin/runbook", "/internal/api-keys"]
    }
  }
}

git add content/runbook.mdx docs.json
git commit -m "Gate the incident runbook"
git push

访客看到的内容

当用户访问受保护的页面时，会看到居中的解锁卡片。卡片只显示站点名称和可选提示，不显示侧边栏或导航。

卡片会使用 docs.json 中配置的站点徽标和主色进行品牌化。密码字段支持显示切换，并会自动获得焦点。

输入错误密码时，卡片会显示错误消息和新的输入框，并在尝试之间加入短暂延迟。错误密码请求和未提供密码的请求都会进入同一个页面，因此页面不会透露“密码错误”还是“尚未输入密码”。

访客输入正确密码后，会获得签名 Cookie，并可正常浏览，直到会话过期或您撤销会话。

轮换和撤销会话

共享密码最终需要更改，例如密码被转发给他人后，或团队成员离开团队时。

打开 Password Protection 卡片，在 Rotate password 字段中输入新密码，然后点击 Save new password。使用旧密码的用户将在下一次请求时被拒绝，使用新密码的用户可以正常进入。轮换会立即生效，无需重新构建。

如果您只想强制所有活跃会话退出，而不更改密码（例如某人的笔记本电脑丢失），请改为点击 Revoke all sessions。此操作会递增服务器端版本计数器，使递增前签发的所有 Cookie 失效。访客重新输入当前密码后即可再次进入。

禁用保护

保护由 docs.json 驱动，因此关闭保护意味着编辑文件并推送。

• **Whole site：**移除 auth.password.enabled（或将其设置为 false）。
• **Specific pages：**移除所有 private: true 标记，并清空 auth.password.private。

下一次构建时，Jamdesk 会删除存储的密码哈希，并将卡片切回 Off。不会残留任何“休眠”状态。如果稍后重新启用保护，您需要设置新密码。

优先级规则

单个页面可能同时受到多个信号影响。解析顺序如下，从最具体到最不具体：

• 如果 auth.password.enabled 为 true，则整个站点都会受到保护。单个页面上的 private: true 将变得多余。
• 如果页面同时标记为 public: true 和 private: true，则公开优先。更安全的默认行为是不意外泄露页面。
• Frontmatter 中的 public: true、导航组中的 public: true 以及 auth.password.public[] glob 会合并到同一个允许列表中。不存在“最具体者优先”规则。只要任一信号将页面标记为公开，该页面就是公开的。
• 如果设置了 auth.password.private[] 但未设置 auth.password.enabled，Jamdesk 会自动启用特定页面模式。您无需执行其他操作。

会话和速率限制的工作方式

本节介绍会话 Cookie、速率限制和密码存储。

会话 Cookie。 成功解锁后，Jamdesk 会设置名为 jd_auth_<slug> 的 Cookie（例如 jd_auth_acme）。该 Cookie 具有 HttpOnly、Secure 和 SameSite=Lax 属性，作用域限定为当前主机，并使用 HMAC-SHA256 签名。其负载包含项目 slug、当前版本计数器和过期时间戳，因此任何篡改都会导致验证失败。默认有效期为 30 天，每次成功解锁时都会刷新。

速率限制。 解锁端点每小时应用两个计数器：每个 IP 10 次尝试和每个项目 100 次尝试。两项限制都会在 scrypt 哈希检查之前执行，因此暴力破解尝试无法消耗 CPU 或泄露时间信息。达到任一限制后，会返回带有 Retry-After 标头的 429 Too Many Requests。

存储。 您的密码会使用 scrypt 进行哈希处理，并存储在仪表板的 Firestore 中。密码不会写入仓库、docs.json 或构建产物。如果丢失密码，请进行轮换。不提供恢复路径。

本地开发期间测试

jamdesk dev 会使用实时 R2 内容和实时配置运行文档。本地开发服务器不会执行密码保护，因此您无需知道密码即可预览受保护页面。这是有意设计的：您是作者，已经拥有仓库的访问权限，而让本地预览受到密码墙阻挡只会增加操作阻力，却不会带来安全收益。

如果要验证实际保护机制，请在尚未拥有 Cookie 的浏览器窗口中访问已部署站点 <slug>.jamdesk.app（或您的自定义域名）。

故障排除

下一步是什么？