API 密钥
管理员可以为 Duplicati 和 Homepage 使用的外部 HTTP API 创建作用域 API 密钥。密钥默认是可选的，因此现有的 Duplicati 任务可以继续工作。
作用域
| 作用域 | 端点 |
|---|---|
| 上传 | POST /api/upload |
| 读取 | GET /api/summary, GET /api/lastbackup/:id, GET /api/lastbackups/:id |
上传密钥不能调用读取 API，读取密钥不能上传报告。
创建密钥
- 打开 设置 → API 密钥。
- 点击 API 密钥卡片底部的 创建 API 密钥。
- 输入名称，选择作用域，并可选择性地设置过期时间（
YYYY-MM-DD）。 - 生成密钥并立即复制密钥串。它只在对话框中显示一次。
- 之后的列表显示指纹，如
Qk7v…3xTa（前四个和后四个字符）、过期日期和状态。相同的指纹也会出现在审计日志中。
禁用或删除
使用 操作 列中的复选框来禁用密钥而不删除它。禁用的密钥无法进行身份验证。再次勾选复选框以重新启用密钥。已过期的密钥无法启用；请创建新密钥。删除将永久移除密钥。
过期
可选的过期日期是密钥保持有效的最后一天。它在 当天 23:59:59 浏览器本地时区 过期，而不是在当天开始时的午夜过期。
选择 2026-12-01 在本地构建 2026-12-01T23:59:59，然后将该时刻存储为 UTC。对于 UTC+1 的浏览器，这是 2026-12-01T22:59:59.000Z。密钥在整个 12 月 1 日保持有效，并从 23:59:59 本地时间开始被视为过期（expires_at <= now）。API 密钥表显示过期日期（或如果未设置则显示 永不）。在此时刻之后，状态徽章会变为 已过期（灰色）；即使过期的密钥仍被启用，也无法进行身份验证。
使用密钥
Duplicati 无法设置自定义标头。将密钥放在报告 URL 中：
--send-http-json-urls=https://your-host/api/upload?api_key=YOUR_KEY
Homepage 小组件可以使用相同的查询参数：
url: http://your-host/api/summary?api_key=YOUR_READ_KEY
能够发送标头的客户端可以改用 X-Api-Key 或 Authorization: Bearer。查询字符串密钥会出现在反向代理访问日志中。
要求密钥
要求外部 API 使用 API 密钥 开关默认处于关闭状态。当它关闭时，允许没有密钥的请求。如果客户端仍然发送密钥，有效的匹配作用域密钥会被接受并记录；无效、禁用、过期或错误作用域的密钥会被忽略，请求仍然被允许。当您打开开关时，四个外部数据 API 在没有有效密钥的情况下返回 401（并拒绝错误的密钥）。请先至少启用一个上传密钥和一个读取密钥，否则 Duplicati 上传和 Homepage 小组件将停止工作。更改会自动保存。
外部 API 保护
同一页面可以为公共上传和读取 API 要求 API 密钥，并配置最大正文大小（默认 5 MB）和针对每个 IP 地址的速率限制，适用于 /api/upload。即使密钥是可选的，大小和速率限制也会生效，并且是防止泛洪攻击的主要防护措施。开关和限制字段会自动保存；没有单独的保存按钮。
另请参见 IP白名单。IP白名单和 API 密钥是独立的功能；您可以使用其中任一功能或同时使用两者。启用两者可以通过基于 IP 地址限制访问并要求 API 密钥来增加安全性。