访问控制
Powerduck 把读者如何访问文档与客户端如何访问 MCP 端点分开，因为两者的消费方式不同。它还配置 MCP 服务器如何向上游 API 认证。
各关卡（按顺序）
若干条件决定一个公开面是否打开。知道完整清单能回答那个常见问题："为什么我打不开我的文档？"
- 文档状态——文档必须为
ACTIVE（未暂停、归档或删除）； - 形态已启用——文档用
documentationEnabled，MCP 用mcpEnabled； - 访问凭据——配置后，文档用查看密码，MCP 用访问密钥；
- 有效期——文档查看可设置在指定时间过期。
形态背后的已发布产物在你添加版本或更改暴露后自动构建，因此发布通常不是手动步骤。
每个形态相互独立：禁用 MCP 不影响文档，文档密码也不为 MCP 把关。
文档查看密码
查看密码保护渲染文档和所提供的规范数据：
- 密码用 scrypt 配合每个密码随机的盐进行哈希；不存储明文；
- 设置密码后，读者必须先提供它，文档才会被提供；
- 密码只为文档把关；MCP 端点使用自己的访问密钥并跳过查看密码。
你还可以设置查看有效期。过期之后，即使密码正确也会拒绝访问。清除密码或有效期即可移除限制。
MCP 端点访问密钥
MCP 端点用自己的访问密钥保护：
- 生成（或轮换）密钥；完整密钥仅返回一次，之后只显示最后四个字符；
- 配置密钥后，每个 MCP 请求必须以
Bearer令牌呈现它； - 提供的密钥以恒定时间比较，缺失或错误的密钥返回
401。
删除密钥可让 MCP 端点开放（前提是文档活动且 MCP 启用）。
MCP 上游认证
除了为端点把关之外，还可以配置 MCP 服务器如何向规范所描述的上游 API 认证。支持的认证类型为：
authType | 配置 |
|---|---|
NONE | 无上游认证 |
BEARER | 一个 Bearer 令牌 |
BASIC | 基本认证的用户名和密码 |
APIKEY | API 密钥名称（请求头/查询）和值 |
Bearer 令牌、基本认证密码和 API 密钥值等机密可以写入但从不会被读回；配置只报告它们是否已设置。
其他 MCP 配置包括：
- 基础 URL 覆盖——覆盖上游基础 URL，而不是从规范获取；
- 请求超时——MCP 服务器调用上游 API 时使用的超时。
推荐设置
- 公开文档： 启用文档，开放 API 可不开密码，或为受控分享设置密码和有效期；
- 给自己智能体用的 MCP： 启用 MCP 并生成访问密钥，让只有你的客户端能调用；
- 上游认证： 让 MCP 服务器的认证匹配真实 API 的要求，独立于谁可以调用 MCP 端点。