企业官网建设流程全解析

ReadMeABook API Tokens是这套有声书请求与自动下载引擎提供的静态个人令牌，让你无需 JWT 会话就能用脚本、Home Assistant 或 Webhook 等第三方工具调用 API：搜索有声书、创建请求、轮询下载状态。本指南面向新手，带你 5 分钟掌握从创建 Token 到完成第一个自动化脚本的全部流程。

为什么需要 API Tokens

ReadMeABook 的日常使用靠网页登录会话（JWT）完成，但当你想把"发现新书 → 自动请求 → 监控下载"写进自动化流程时，登录 Cookie 就不适用了。此时 API Tokens 登场：

• 静态长令牌：以rmab_为前缀，生成后长期有效（也可设置到期时间）
• 权限即本人：Token 以创建者（或其绑定的用户）的完整用户级权限运行
• 端点白名单：Token 只能访问固定的 8 个接口，比网页会话的权限面更小、更安全
• 一次性显示：完整 Token 只在创建时返回一次，数据库仅保存 SHA-256 哈希

快速上手：3步创建你的第一把 Token

1. 进入个人设置：登录后打开个人主页（Profile），找到API Tokens分区。界面位于 src/components/profile/ApiTokensSection.tsx
2. 点击 Create New Token：填写名称（如Home Assistant、Webhook），并选择有效期：
   • Never（永不过期）
   • 30 days/90 days/1 year
3. 立即复制：创建成功后会弹出绿色横幅展示完整 Token，并提示"Copy it now — it won't be shown again"。错过就要删除重建，因为系统只保存哈希值。

📌 管理员还可在Admin → Users → API Tokens中代替任意用户创建 Token，但 Token 角色始终与目标用户实际角色一致，无法越权提升。该逻辑见 src/app/api/admin/api-tokens/route.ts。

如何用 Token 调用 API：Bearer 认证方式

所有调用只需在请求头中携带 Token，格式统一为Authorization: Bearer rmab_xxx：

curl -H "Authorization: Bearer rmab_your_token_here" \ http://your-rmab-host/api/requests

认证流程由中间件 src/lib/middleware/auth.ts 统一处理：识别rmab_前缀 → 按 SHA-256 哈希查库 → 检查过期与用户软删除 → 校验端点白名单。白名单匹配器（支持:id动态参数）定义在 src/lib/constants/api-tokens.ts。

项目还内置了交互式文档页/api-docs（源码 src/app/api-docs/page.tsx），可直接粘贴 Token 在浏览器里试跑每个端点，非常适合新手调试。

可用端点清单：Token 能做什么

以下是 API Token 白名单中的全部 8 个端点（与网页会话相比是"精简版"权限）：

白名单与文档元数据的唯一事实来源：src/lib/constants/api-tokens.ts。

管理端点（右侧三个 ✅ 项）适合接入自己的监控面板：/api/admin/metrics返回请求总数、下载统计与库规模；/api/admin/downloads/active返回进度、速度与预计完成时间——正好对应上图 Admin Dashboard 展示的核心指标。

自动创建请求：请求体字段与错误码

最核心的写端点是POST /api/requests。请求体结构与网页版完全一致：

{ "audiobook": { "asin": "B0ABC123", "title": "The Name of the Wind", "author": "Patrick Rothfuss", "narrator": "The Author" } }

行为与网页端"一键请求"保持一致：查重检测、库内已有检查、忽略名单检查（Token 请求会绕过忽略名单）、自动审批规则、通知队列全部照常生效。响应为201 { success: true, request }；若被拦截则返回具名错误：

• AlreadyAvailable—— 库中已有此书
• BeingProcessed—— 正在处理中
• DuplicateRequest—— 重复请求
• Ignored—— 命中忽略规则
• UserNotFound/ValidationError

小技巧：追加查询参数?skipAutoSearch=true可暂缓自动搜索任务，适合先批量建单、稍后统一触发的场景。

限流、数量上限与有效期规则

写自动化脚本前务必了解这些"护栏"：

• 每用户上限 25 个未过期 Token，超出返回403 Token limit reached
• 创建限流：每人每分钟最多 10 次创建尝试
• 撤销限流：每人每分钟最多 20 次撤销尝试
• 触发限流返回429，并携带Retry-After响应头，脚本应据此退避重试

限流规则实现见 src/lib/utils/rateLimit.ts，数量上限常量见 src/lib/constants/api-tokens.ts。

Token 数据模型（name、tokenHash、lastUsedAt、expiresAt等字段）定义在 prisma/schema.prisma。

安全最佳实践：像管理密码一样管理 Token

• 立即存入密钥管理：完整 Token 只出现一次，泄露后无法"找回"，只能撤销重建
• 按用途命名：home-assistant、nightly-script，配合lastUsedAt字段可在列表中定位长期未用的 Token
• 短有效期优先：临时脚本选 30 天，常驻集成再考虑更长周期
• 及时撤销：在 Profile → API Tokens 中点击Revoke即可立即失效，使用中的集成会马上失去访问权限
• 理解权限面：Token 拥有绑定用户的完整用户级权限，包括以你名义创建请求——切勿写入公开仓库或日志

相关文件与源码参考

想深入阅读实现，按以下路径入手即可：

• 功能总览文档：documentation/backend/services/api-tokens.md
• 常量与白名单匹配器：src/lib/constants/api-tokens.ts
• Token 生成工具（随机字节 + SHA-256）：src/lib/utils/api-token.ts
• 用户自建接口（创建/列表/撤销）：src/app/api/user/api-tokens/route.ts
• 管理员接口：src/app/api/admin/api-tokens/route.ts
• 前端管理组件：src/components/profile/ApiTokensSection.tsx
• 交互式 API 文档页：src/app/api-docs/page.tsx

掌握以上内容，你就能用 ReadMeABook API Tokens 把有声书请求流程无缝接入自己的自动化体系——从一条 curl 命令开始，到监控面板全覆盖。