企业官网建设流程全解析

• 后端
• 前端
• 音视频

AutoBangumi 在/api/v1路径下提供了一整套基于 FastAPI 的 REST API，覆盖认证、番剧规则管理、RSS 订阅源、种子搜索与下载器控制等核心能力。本文以官方 API 参考文档（docs/api/index.md）为骨架，结合仓库源码逐端点讲解请求方式、请求体、响应格式与底层实现，帮助你直接编写脚本、对接自动化流程，或深入理解 WebUI 每个按钮背后的 HTTP 调用。

基础约定：Base URL、认证与统一响应

所有 API 以http://your-host:7892/api/v1为基础 URL。端口 7892 是 WebUI 的默认端口，在源码的默认配置中定义于 backend/src/module/conf/const.py，可通过环境变量AB_WEBUI_PORT覆盖。路由注册位于 backend/src/module/api/init.py：v1 = APIRouter(prefix="/v1")，再被 backend/src/main.py 以app.include_router(v1, prefix="/api")挂载，最终形成/api/v1/...的完整路径。

认证要求：除登录端点和首次运行的设置向导外，所有端点都需要 JWT 认证。令牌可以通过两种方式传递：

• Cookie：token=<jwt>（登录成功后自动设置，httponly=True、samesite="strict"、有效期 1 天，见 backend/src/module/api/auth.py）；
• 请求头：Authorization: Bearer <token>。

从源码看，认证依赖链是get_current_user/get_principal（backend/src/module/security/api.py 定义了OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")），即令牌校验完全由 JWT 签名保证。注意AB_DEV_NO_AUTH=1环境变量会全局绕过认证，源码中有明确警告：该变量只能用于开发，绝不能在生产环境设置（backend/src/module/security/api.py）。

响应格式：所有 API 响应遵循统一的双语消息结构：

{ "msg_en": "Success message in English", "msg_zh": "成功消息（中文）", "status": true }

该结构对应 backend/src/module/models/response.py 中的APIResponse模型（status、msg_en、msg_zh三字段）。错误响应携带标准 HTTP 状态码（400、401、403、404、500）以及中英文错误消息，例如登录失败返回401与"Invalid username or password"（backend/src/module/api/auth.py）。

交互式文档：开发模式下（源码中以DEV_VERSION为版本号时）访问http://your-host:7892/docs可打开 Swagger UI，直接试调每个端点；此时根路径/也会 302 跳转到/docs（backend/src/main.py）。

认证端点：登录、刷新与凭据更新

登录

POST /api/v1/auth/login

请求体为username与password（OAuth2 表单格式，源码使用OAuth2PasswordRequestForm，即application/x-www-form-urlencoded）。成功后设置包含 JWT 令牌的认证 cookie。登录端点还受登录 IP 白名单保护（check_login_ip依赖，见 backend/src/module/security/api.py）：当security.login_whitelist非空时，仅允许白名单内的 IP 登录。

刷新令牌

POST /api/v1/auth/refresh_token

延长当前浏览器会话。源码同时保留了一个GET /auth/refresh_token兼容别名，标记为deprecated并在响应头返回Deprecation: true与Warning头（backend/src/module/api/auth.py），新客户端应使用 POST。

登出

GET /api/v1/auth/logout

撤销当前持久化会话并清除认证 cookie（调用service.logout(token)后delete_cookie），返回{"msg_en": "Logout successfully.", "msg_zh": "登出成功。", "status": true}。

更新凭据

POST /api/v1/auth/update

更新用户名和/或密码。请求体与登录一致；更新成功后轮换所有会话并重新签发 cookie。若用户名冲突返回409，凭据错误返回401（backend/src/module/api/auth.py）。另有GET /auth/me返回当前用户公开信息。

Passkey / WebAuthn 无密码认证（v3.2+）

使用 WebAuthn/FIDO2 Passkey 实现无密码登录，分为注册、认证、管理三组端点：

Passkey 的依赖方 ID（webauthn_rp_id）与来源（webauthn_origin）在security配置节中定义（默认配置见 backend/src/module/conf/const.py），前端实现位于 webui/src/services/webauthn.ts。该能力的具体安全说明可参考 docs/config/security.md。

配置读写：GET /config/get 与 PATCH /config/update

GET /api/v1/config/get

返回完整配置对象，包含program、downloader、rss_parser、bangumi_manage、notification、proxy、experimental_openai、security、update、llm等小节（默认值定义于 backend/src/module/conf/const.py）。

PATCH /api/v1/config/update

部分更新配置：请求体只需包含要修改的字段。这里有一个值得注意的源码细节：GET /config/get会对键名包含password、api_key、token、secret的字符串值做递归掩码处理，替换为********（backend/src/module/api/config.py）；PATCH提交时若某字段仍是掩码值，系统会按"身份匹配"策略从旧配置中恢复原值——如果无法唯一定位掩码项对应的旧值（例如通知渠道列表被删除且身份字段同时被改），会直接报错要求重新输入密钥，而不是猜一个值（backend/src/module/api/config.py）。这意味着：

• 不涉及敏感字段的更新可放心提交；
• 涉及敏感字段时，不要提交********占位符，应提交真实的新值；
• 修改通知渠道这类列表时，尽量只改目标项的字段，避免身份歧义。

番剧（动画规则）管理端点

番剧模块对应module/api/bangumi.py中的Bangumi数据库实体（动画下载规则，含标题、季度、集数偏移等元数据）。端点如下：

get/all直接调用db.bangumi.search_all()（backend/src/module/api/bangumi.py）。除文档列出的端点外，源码中还包含更多进阶端点：例如POST /bangumi/detect-offset结合 TMDB 数据检测季/集偏移不一致（返回season_offset、episode_offset、reason与置信度），以及设置放送日weekday的端点（backend/src/module/api/bangumi.py）。番剧规则的完整字段与编辑方式可参考 docs/feature/bangumi.md。

RSS 订阅源端点

RSS 模块管理所有订阅源及其解析出的种子，路由前缀/rss，Pydantic 合法解析器取值为mikan、tmdb、parser（backend/src/module/api/rss.py）。

实现上，add_rss通过RSSEngine.add_rss(url, name, aggregate, parser)入库（backend/src/module/api/rss.py）；collect走SeasonCollector整季收集逻辑。RSS 解析引擎（经典/新引擎选择见rss_parser.engine配置项）与订阅流程详见 docs/config/rss.md。

搜索端点：SSE 实时流

搜索番剧（Server-Sent Events）

GET /api/v1/search/bangumi?keyword={keyword}&provider={provider}

以 SSE 流返回解析后的搜索结果，实现实时更新。源码中该端点的实际参数名为site与keywords（keywords支持空格分隔多关键词），返回EventSourceResponse（backend/src/module/api/search.py），事件流由SearchTorrent.analyse_keyword()异步生成。搜索提供者取值如mikan、nyaa、dmhy等。

列出搜索提供者

GET /api/v1/search/provider

返回可用搜索提供者名称列表（list(SEARCH_CONFIG.keys())）。源码还提供GET/PUT /search/provider/config用于查看与更新各提供者的 URL 模板（backend/src/module/api/search.py）。搜索提供者的配置与自定义方式见 docs/config/search-provider.md。

程序控制端点

程序控制路由定义于 backend/src/module/api/program.py，负责主循环（RSS 检查、下载、重命名）的启停：

一个对脚本自动化很有用的兼容性细节：这些控制端点的主方法实际是POST（/start、/stop、/restart、/shutdown均为@router.post），同时保留了GET别名并标记为 deprecated，以便 3.2 及更早版本中依赖 GET 的外部自动化（cron、Home Assistant 等）在升级后不至于 405 静默失效（backend/src/module/api/program.py）。新编写的集成脚本请一律使用 POST，避免将来 GET 别名移除后失效。

下载器管理端点（v3.2+）

GET /api/v1/downloader/torrents

获取下载器中Bangumi分类（category）下的所有种子，内部通过DownloadClient.get_torrent_info(category="Bangumi")调用（backend/src/module/api/downloader.py）。

暂停、恢复与删除：

POST /api/v1/downloader/torrents/pause POST /api/v1/downloader/torrents/resume POST /api/v1/downloader/torrents/delete

请求体统一为哈希数组：

{ "hashes": ["hash1", "hash2"], "delete_files": false }

其中delete_files仅删除端点使用，控制是否连带删除下载文件。源码中多个哈希以|拼接后一次性交给下载客户端批量处理（backend/src/module/api/downloader.py）。

此外该模块还提供了文档未展开的种子管理能力：POST /downloader/torrents/tag（用ab:{bangumi_id}标签关联种子与番剧，用于重命名器精确查找季/集偏移）与POST /downloader/torrents/tag/auto（自动按名称/保存路径匹配并为未打标签的种子补打标签），以及重命名冲突查询与重试端点（backend/src/module/api/downloader.py）。下载器类型（qBittorrent / aria2 / 模拟器）与路径配置详见 docs/config/downloader.md。

设置向导端点（v3.2+，无需认证）

设置向导端点仅在首次运行设置完成前可用，且不需要认证；设置完成后所有端点返回403 Forbidden。源码通过哨兵文件config/.setup_complete判断设置状态（backend/src/module/api/setup.py）。

安全细节：/setup/test-rss会拒绝指向私网/保留/回环地址的 URL（防 SSRF），/setup/test-downloader只允许 http/https 协议探测；/setup/complete额外校验调用者要么持有有效会话，要么admin账号仍是出厂默认密码adminadmin，防止升级后未跑向导的实例被未认证调用者覆盖管理员凭据（backend/src/module/api/setup.py）。

日志端点

GET /api/v1/log

获取完整应用日志文件。

GET /api/v1/log/clear

清空日志文件。这两个端点配合排障非常实用；日志的详细配置（debug 开关、输出格式）见 docs/config/… 之外的 backend/src/module/conf/log.py。

实践建议与调用示例

综合以上端点，你可以用 curl 完成一次典型的自动化操作。例如登录并携带 cookie 查询全部番剧规则：

# 登录，cookie 写入文件 curl -c cookies.txt -X POST http://your-host:7892/api/v1/auth/login \ -d 'username=admin&password=adminadmin' # 携带 cookie 列出全部番剧 curl -b cookies.txt http://your-host:7892/api/v1/bangumi/get/all # 携带 Bearer 令牌列出全部订阅源 curl -H "Authorization: Bearer <jwt>" http://your-host:7892/api/v1/rss

编写自动化脚本时请记住以下几点：

1. 一律使用 POST 控制程序：/start、/stop、/restart、/shutdown的 GET 别名仅为旧版兼容保留；
2. 配置更新不要回传掩码：GET /config/get返回的********是显示占位符，PATCH 时应提交真实值；
3. 设置向导有生命周期：/setup/*在config/.setup_complete创建后即永久返回 403；
4. 错误处理：所有端点统一返回中英文消息（msg_en/msg_zh），结合 HTTP 状态码即可定位问题；
5. 生产环境严禁设置AB_DEV_NO_AUTH=1，否则认证会被全局绕过。

如果你需要把某个端点接到自己的通知、看板或 Home Assistant 自动化中，以上每个端点都有对应的源码实现可直接对照，例如登录见 backend/src/module/api/auth.py、种子列表见 backend/src/module/api/downloader.py、SSE 搜索见 backend/src/module/api/search.py。WebUI 前端对这些端点的封装（含 TypeScript 类型与请求函数）位于 webui/src/api/，可作为集成参考。

• 后端
• 前端
• 音视频