密码保护

密码保护用于限制那些保存在 Git 中但不应公开的文档：运维手册、发布前指南、仅限合作伙伴的文档、抢先体验功能等。一个共享口令即可限制整个站点或一组页面的访问。您的仓库内容不会被移出。

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

应选择哪种模式？

根据哪些内容是公开的来选择模式。

两种模式下，仪表板卡片、解锁界面以及轮换和撤销控件完全相同。通过编辑 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=/"

公开例外

在其余站点受限的同时，保持特定页面公开，例如营销落地页或注册表单。

有三种方式可将页面标记为公开。构建会将它们合并为一个允许列表。

前言是粒度最细的选项。在 .mdx 文件中添加 public: true，即可将该页面设为公开：

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

导航分组可覆盖整个章节。在 docs.json 导航中为 group 或 tab 设置 public: true，即可使其下的所有页面公开。例如，在私有工程文档旁设置一个"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[] 下的显式通配符可覆盖前言和导航无法处理的情况：顶层落地页、动态生成的路由，或您不想重写的子树。

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

通配符支持 *（一个路径段）和 **（任意深度）。校验会拒绝裸 /，因为它会解锁整个站点。仪表板卡片会显示上次构建解析出的允许列表。

仅保护少数页面

在指定页面模式下，所有页面默认公开。您可以逐个页面选择加入访问限制。

---
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 中设置的站点 Logo 和主色调进行品牌化。密码输入框带有显示/隐藏切换，并自动获得焦点。

输入错误口令时，会显示同样的卡片，并附带错误信息、清空的输入框，以及两次尝试之间的短暂延迟。页面上不会区分"口令错误"与"尚未输入口令"。

正确的口令会设置一个签名 Cookie。它在会话过期或您撤销之前一直有效。

AI 工具和 API 密钥

无法输入口令的工具（如 MCP 客户端，或抓取 llms.txt 的脚本）可以改用项目 API 密钥。该密钥可用于 MCP 服务器、.md 页面 URL 以及 llms 文件。它无法打开 HTML 页面或 AI 聊天。

让团队成员使用 Jamdesk 登录

您的团队成员已经拥有 Jamdesk 账号，因此无需再使用共享口令。添加 allowMembers 后，解锁界面会在口令输入框旁显示 Sign in with Jamdesk 按钮。外部读者仍使用口令。

{
  "auth": {
    "password": {
      "enabled": true,
      "allowMembers": true
    }
  }
}

该功能默认关闭。推送更改后，按钮会在下一次构建后出现。

团队成员点击 Sign in with Jamdesk 后，会打开 Jamdesk 仪表板。如果他们已在那里登录，会直接带他们回到刚才阅读的页面。如果尚未登录，则需先登录，然后再返回您的文档。

谁可以登录

项目所有者可以登录，在仪表板 Settings → Members 中添加为成员的人也可以。您邀请的人在接受邀请后即可阅读文档。

团队会话如何运作

团队登录有效期为 14 天。之后，团队成员需要再次点击该按钮。

如需切断某人的访问，请将其移出项目。其文档访问会在约一分钟内停止。

更改共享口令不会让团队成员退出登录，Revoke all sessions 也不会。团队登录同样不影响口令会话。

登录后，团队成员可以像输入口令后一样使用 AI 聊天、MCP 服务器、.md URL 和 llms.txt。

仅供团队查看文档

启用 enabled 和 allowMembers，然后不在仪表板中设置口令。解锁界面只会显示登录按钮，因此您的团队可以进入，其他人则无法进入。

域名与套餐

团队登录适用于您的 <slug>.jamdesk.app 子域名以及连接到该项目的自定义域名。这包括通过 Cloudflare Worker 或子路径设置从自定义域名提供文档的情况。其他别名（例如您域名的 www. 副本）不受支持。每个主机各自拥有独立的会话，因此在一个主机上登录不会使您在另一个主机上也处于登录状态。

与密码保护一样，团队登录需要付费套餐。如果所有者的套餐到期，新的团队登录将停止。已开始的会话在过期前（最长 14 天）仍可继续使用。

allowMembers 仅适用于密码保护。使用 JWT 身份验证 的站点不受影响。

轮换和撤销会话

打开 Password Protection 卡片，在 Rotate password 字段中输入新口令，然后点击 Save new password。旧口令会在下一次请求时失效。轮换立即生效，无需重新构建。

如需让所有活跃会话退出登录而不更改口令（例如笔记本电脑丢失），请点击 Revoke all sessions。它会递增服务器端的版本计数器。在该计数器递增之前签发的所有 Cookie 都将失效。访问者需要重新输入当前口令。

停用保护

通过编辑 docs.json 并推送来关闭保护。

• **整站模式：**删除 auth.password.enabled（或将其设为 false）。
• **指定页面模式：**删除所有 private: true 标记，并清空 auth.password.private。

下一次构建会删除已存储的口令哈希，并将卡片切回 Off。之后重新启用保护需要设置新口令。

优先级规则

一个页面可能同时匹配多个信号。解析顺序从最具体到最不具体：

• auth.password.enabled: true 限制整个站点。单个页面上的 private: true 变得多余。
• 同时标记为 public: true 和 private: true 的页面是公开的。公开优先。
• 前言中的 public: true、导航分组中的 public: true，以及 auth.password.public[] 通配符会合并为一个允许列表。只要有一个信号表明页面为公开，它就是公开的。
• 只设置 auth.password.private[] 而不设置 auth.password.enabled，会激活指定页面模式。

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

会话 Cookie。 成功解锁后，Jamdesk 会设置名为 jd_auth_<slug> 的 Cookie（例如 jd_auth_acme）。它带有 HttpOnly、Secure、SameSite=Lax 属性，作用域为主机，并使用 HMAC-SHA256 签名。载荷包括项目 slug、当前版本计数器以及过期时间戳。篡改会导致校验失败。默认有效期为 30 天，每次成功解锁时刷新。

速率限制。 解锁端点每小时应用两个计数器：每个 IP 10 次尝试，每个项目 100 次尝试。它们在 scrypt 哈希校验之前运行，因此暴力破解尝试无法消耗 CPU 或泄露计时信息。触发任一限制会返回 429 Too Many Requests 以及 Retry-After 头。

存储。 您的口令使用 scrypt 进行哈希处理，并存储在仪表板的 Firestore 中。它从不进入您的仓库、docs.json 或构建产物。如果您丢失了口令，请轮换。不存在恢复途径。

本地开发期间测试

jamdesk dev 使用实时 R2 内容和实时配置运行您的文档。本地开发服务器不执行密码保护。您可以在无口令的情况下预览受限页面。

如需测试访问限制，请在没有 Cookie 的浏览器窗口中打开已部署的站点 <slug>.jamdesk.app（或您的自定义域名）。

故障排除

接下来