全解析與源碼級(jí)實(shí)現(xiàn)說(shuō)明)
后端前端音視頻【免費(fèi)下載鏈接】Auto_BangumiAutoBangumi - 全自動(dòng)追番工具項(xiàng)目地址https://gitcode.com/gh_mirrors/au/Auto_Bangumi點(diǎn)擊查看免費(fèi)下載AutoBangumi 在/api/v1路徑下提供了一整套基于 FastAPI 的 REST API覆蓋認(rèn)證、番劇規(guī)則管理、RSS 訂閱源、種子搜索與下載器控制等核心能力。本文以官方 API 參考文檔docs/api/index.md為骨架結(jié)合倉(cāng)庫(kù)源碼逐端點(diǎn)講解請(qǐng)求方式、請(qǐng)求體、響應(yīng)格式與底層實(shí)現(xiàn)幫助你直接編寫腳本、對(duì)接自動(dòng)化流程或深入理解 WebUI 每個(gè)按鈕背后的 HTTP 調(diào)用?；A(chǔ)約定Base URL、認(rèn)證與統(tǒng)一響應(yīng)所有 API 以http://your-host:7892/api/v1為基礎(chǔ) URL。端口 7892 是 WebUI 的默認(rèn)端口在源碼的默認(rèn)配置中定義于 backend/src/module/conf/const.py可通過(guò)環(huán)境變量AB_WEBUI_PORT覆蓋。路由注冊(cè)位于 backend/src/module/api/init.pyv1 APIRouter(prefix/v1)再被 backend/src/main.py 以app.include_router(v1, prefix/api)掛載最終形成/api/v1/...的完整路徑。認(rèn)證要求除登錄端點(diǎn)和首次運(yùn)行的設(shè)置向?qū)馑卸它c(diǎn)都需要 JWT 認(rèn)證。令牌可以通過(guò)兩種方式傳遞Cookietokenjwt登錄成功后自動(dòng)設(shè)置httponlyTrue、samesitestrict、有效期 1 天見 backend/src/module/api/auth.py請(qǐng)求頭Authorization: Bearer token。從源碼看認(rèn)證依賴鏈?zhǔn)莋et_current_user/get_principalbackend/src/module/security/api.py 定義了OAuth2PasswordBearer(tokenUrl/api/v1/auth/login)即令牌校驗(yàn)完全由 JWT 簽名保證。注意AB_DEV_NO_AUTH1環(huán)境變量會(huì)全局繞過(guò)認(rèn)證源碼中有明確警告該變量只能用于開發(fā)絕不能在生產(chǎn)環(huán)境設(shè)置backend/src/module/security/api.py。響應(yīng)格式所有 API 響應(yīng)遵循統(tǒng)一的雙語(yǔ)消息結(jié)構(gòu){ msg_en: Success message in English, msg_zh: 成功消息中文, status: true }該結(jié)構(gòu)對(duì)應(yīng) backend/src/module/models/response.py 中的APIResponse模型status、msg_en、msg_zh三字段。錯(cuò)誤響應(yīng)攜帶標(biāo)準(zhǔn) HTTP 狀態(tài)碼400、401、403、404、500以及中英文錯(cuò)誤消息例如登錄失敗返回401與Invalid username or passwordbackend/src/module/api/auth.py。交互式文檔開發(fā)模式下源碼中以DEV_VERSION為版本號(hào)時(shí)訪問(wèn)http://your-host:7892/docs可打開 Swagger UI直接試調(diào)每個(gè)端點(diǎn)此時(shí)根路徑/也會(huì) 302 跳轉(zhuǎn)到/docsbackend/src/main.py。認(rèn)證端點(diǎn)登錄、刷新與憑據(jù)更新登錄POST /api/v1/auth/login請(qǐng)求體為username與passwordOAuth2 表單格式源碼使用OAuth2PasswordRequestForm即application/x-www-form-urlencoded。成功后設(shè)置包含 JWT 令牌的認(rèn)證 cookie。登錄端點(diǎn)還受登錄 IP 白名單保護(hù)check_login_ip依賴見 backend/src/module/security/api.py當(dāng)security.login_whitelist非空時(shí)僅允許白名單內(nèi)的 IP 登錄。刷新令牌POST /api/v1/auth/refresh_token延長(zhǎng)當(dāng)前瀏覽器會(huì)話。源碼同時(shí)保留了一個(gè)GET /auth/refresh_token兼容別名標(biāo)記為deprecated并在響應(yīng)頭返回Deprecation: true與Warning頭backend/src/module/api/auth.py新客戶端應(yīng)使用 POST。登出GET /api/v1/auth/logout撤銷當(dāng)前持久化會(huì)話并清除認(rèn)證 cookie調(diào)用service.logout(token)后delete_cookie返回{msg_en: Logout successfully., msg_zh: 登出成功。, status: true}。更新憑據(jù)POST /api/v1/auth/update更新用戶名和/或密碼。請(qǐng)求體與登錄一致更新成功后輪換所有會(huì)話并重新簽發(fā) cookie。若用戶名沖突返回409憑據(jù)錯(cuò)誤返回401backend/src/module/api/auth.py。另有GET /auth/me返回當(dāng)前用戶公開信息。Passkey / WebAuthn 無(wú)密碼認(rèn)證v3.2使用 WebAuthn/FIDO2 Passkey 實(shí)現(xiàn)無(wú)密碼登錄分為注冊(cè)、認(rèn)證、管理三組端點(diǎn)端點(diǎn)說(shuō)明POST /passkey/register/options獲取 WebAuthn 注冊(cè)選項(xiàng)質(zhì)詢、依賴方信息POST /passkey/register/verify驗(yàn)證并保存瀏覽器返回的注冊(cè)響應(yīng)POST /passkey/auth/options獲取認(rèn)證質(zhì)詢選項(xiàng)POST /passkey/auth/verify驗(yàn)證認(rèn)證響應(yīng)并簽發(fā) JWT 令牌GET /passkey/list列出當(dāng)前用戶所有已注冊(cè) PasskeyPOST /passkey/delete通過(guò)憑據(jù) ID 刪除已注冊(cè) PasskeyPasskey 的依賴方 IDwebauthn_rp_id與來(lái)源webauthn_origin在security配置節(jié)中定義默認(rèn)配置見 backend/src/module/conf/const.py前端實(shí)現(xiàn)位于 webui/src/services/webauthn.ts。該能力的具體安全說(shuō)明可參考 docs/config/security.md。配置讀寫GET /config/get 與 PATCH /config/updateGET /api/v1/config/get返回完整配置對(duì)象包含program、downloader、rss_parser、bangumi_manage、notification、proxy、experimental_openai、security、update、llm等小節(jié)默認(rèn)值定義于 backend/src/module/conf/const.py。PATCH /api/v1/config/update部分更新配置請(qǐng)求體只需包含要修改的字段。這里有一個(gè)值得注意的源碼細(xì)節(jié)GET /config/get會(huì)對(duì)鍵名包含password、api_key、token、secret的字符串值做遞歸掩碼處理替換為********backend/src/module/api/config.pyPATCH提交時(shí)若某字段仍是掩碼值系統(tǒng)會(huì)按身份匹配策略從舊配置中恢復(fù)原值——如果無(wú)法唯一定位掩碼項(xiàng)對(duì)應(yīng)的舊值例如通知渠道列表被刪除且身份字段同時(shí)被改會(huì)直接報(bào)錯(cuò)要求重新輸入密鑰而不是猜一個(gè)值backend/src/module/api/config.py。這意味著不涉及敏感字段的更新可放心提交涉及敏感字段時(shí)不要提交********占位符應(yīng)提交真實(shí)的新值修改通知渠道這類列表時(shí)盡量只改目標(biāo)項(xiàng)的字段避免身份歧義。番劇動(dòng)畫規(guī)則管理端點(diǎn)番劇模塊對(duì)應(yīng)module/api/bangumi.py中的Bangumi數(shù)據(jù)庫(kù)實(shí)體動(dòng)畫下載規(guī)則含標(biāo)題、季度、集數(shù)偏移等元數(shù)據(jù)。端點(diǎn)如下方法/路徑說(shuō)明GET /bangumi/get/all獲取所有動(dòng)畫下載規(guī)則返回Bangumi對(duì)象數(shù)組GET /bangumi/get/{bangumi_id}按 ID 獲取特定規(guī)則PATCH /bangumi/update/{bangumi_id}更新規(guī)則元數(shù)據(jù)標(biāo)題、季度、集數(shù)偏移等DELETE /bangumi/delete/{bangumi_id}刪除單個(gè)規(guī)則及其關(guān)聯(lián)種子DELETE /bangumi/delete/many/批量刪除請(qǐng)求體{bangumi_ids: [1, 2, 3]}DELETE /bangumi/disable/{bangumi_id}禁用規(guī)則保留文件、停止下載DELETE /bangumi/disable/many/批量禁用GET /bangumi/enable/{bangumi_id}重新啟用規(guī)則GET /bangumi/refresh/poster/all從 TMDB 刷新所有動(dòng)畫海報(bào)GET /bangumi/refresh/poster/{bangumi_id}刷新單個(gè)動(dòng)畫海報(bào)GET /bangumi/refresh/calendar從 Bangumi.tv 刷新放送日歷數(shù)據(jù)GET /bangumi/reset/all刪除所有動(dòng)畫規(guī)則謹(jǐn)慎使用get/all直接調(diào)用db.bangumi.search_all()backend/src/module/api/bangumi.py。除文檔列出的端點(diǎn)外源碼中還包含更多進(jìn)階端點(diǎn)例如POST /bangumi/detect-offset結(jié)合 TMDB 數(shù)據(jù)檢測(cè)季/集偏移不一致返回season_offset、episode_offset、reason與置信度以及設(shè)置放送日weekday的端點(diǎn)backend/src/module/api/bangumi.py。番劇規(guī)則的完整字段與編輯方式可參考 docs/feature/bangumi.md。RSS 訂閱源端點(diǎn)RSS 模塊管理所有訂閱源及其解析出的種子路由前綴/rssPydantic 合法解析器取值為mikan、tmdb、parserbackend/src/module/api/rss.py。方法/路徑說(shuō)明GET /rss獲取所有已配置訂閱源POST /rss/add添加訂閱源請(qǐng)求體{url: ..., aggregate: true, parser: mikan}aggregate表示聚合訂閱parser指定解析引擎POST /rss/enable/many批量啟用請(qǐng)求體為 ID 數(shù)組PATCH /rss/disable/{rss_id}禁用單個(gè)訂閱源POST /rss/disable/many批量禁用DELETE /rss/delete/{rss_id}刪除單個(gè)訂閱源POST /rss/delete/many批量刪除PATCH /rss/update/{rss_id}更新訂閱源配置GET /rss/refresh/all手動(dòng)刷新所有訂閱源GET /rss/refresh/{rss_id}刷新指定訂閱源GET /rss/torrent/{rss_id}獲取從該訂閱源解析出的種子列表POST /rss/analysis分析 RSS URL 并提取動(dòng)畫元數(shù)據(jù)但不訂閱請(qǐng)求體{url: ...}POST /rss/collect從訂閱源下載所有劇集用于已完結(jié)動(dòng)畫對(duì)應(yīng)SeasonCollectorPOST /rss/subscribe訂閱訂閱源以自動(dòng)下載連載動(dòng)畫實(shí)現(xiàn)上add_rss通過(guò)RSSEngine.add_rss(url, name, aggregate, parser)入庫(kù)backend/src/module/api/rss.pycollect走SeasonCollector整季收集邏輯。RSS 解析引擎經(jīng)典/新引擎選擇見rss_parser.engine配置項(xiàng)與訂閱流程詳見 docs/config/rss.md。搜索端點(diǎn)SSE 實(shí)時(shí)流搜索番劇Server-Sent EventsGET /api/v1/search/bangumi?keyword{keyword}provider{provider}以 SSE 流返回解析后的搜索結(jié)果實(shí)現(xiàn)實(shí)時(shí)更新。源碼中該端點(diǎn)的實(shí)際參數(shù)名為site與keywordskeywords支持空格分隔多關(guān)鍵詞返回EventSourceResponsebackend/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。程序控制端點(diǎn)程序控制路由定義于 backend/src/module/api/program.py負(fù)責(zé)主循環(huán)RSS 檢查、下載、重命名的啟停方法/路徑說(shuō)明GET /status獲取程序狀態(tài)返回{status: running, version: 3.2.0, first_run: false}。源碼中status字段實(shí)際為布爾值true/false由ctx.is_running決定version來(lái)自VERSION常量first_run來(lái)自上下文標(biāo)志GET /start啟動(dòng)主程序RSS 檢查、下載、重命名調(diào)用ctx.start_tasks()GET /restart重啟主程序調(diào)用ctx.restart()GET /stop停止主程序WebUI 仍可訪問(wèn)調(diào)用ctx.stop()GET /shutdown關(guān)閉整個(gè)應(yīng)用進(jìn)程Docker 環(huán)境下由容器重啟ctx.stop()后向自身發(fā)送SIGINTGET /check/downloader測(cè)試與已配置下載器qBittorrent的連接返回布爾值一個(gè)對(duì)腳本自動(dòng)化很有用的兼容性細(xì)節(jié)這些控制端點(diǎn)的主方法實(shí)際是POST/start、/stop、/restart、/shutdown均為router.post同時(shí)保留了GET別名并標(biāo)記為 deprecated以便 3.2 及更早版本中依賴 GET 的外部自動(dòng)化cron、Home Assistant 等在升級(jí)后不至于 405 靜默失效backend/src/module/api/program.py。新編寫的集成腳本請(qǐng)一律使用 POST避免將來(lái) GET 別名移除后失效。下載器管理端點(diǎn)v3.2GET /api/v1/downloader/torrents獲取下載器中Bangumi分類category下的所有種子內(nèi)部通過(guò)DownloadClient.get_torrent_info(categoryBangumi)調(diào)用backend/src/module/api/downloader.py。暫停、恢復(fù)與刪除POST /api/v1/downloader/torrents/pause POST /api/v1/downloader/torrents/resume POST /api/v1/downloader/torrents/delete請(qǐng)求體統(tǒng)一為哈希數(shù)組{ hashes: [hash1, hash2], delete_files: false }其中delete_files僅刪除端點(diǎn)使用控制是否連帶刪除下載文件。源碼中多個(gè)哈希以|拼接后一次性交給下載客戶端批量處理backend/src/module/api/downloader.py。此外該模塊還提供了文檔未展開的種子管理能力POST /downloader/torrents/tag用ab:{bangumi_id}標(biāo)簽關(guān)聯(lián)種子與番劇用于重命名器精確查找季/集偏移與POST /downloader/torrents/tag/auto自動(dòng)按名稱/保存路徑匹配并為未打標(biāo)簽的種子補(bǔ)打標(biāo)簽以及重命名沖突查詢與重試端點(diǎn)backend/src/module/api/downloader.py。下載器類型qBittorrent / aria2 / 模擬器與路徑配置詳見 docs/config/downloader.md。設(shè)置向?qū)Ф它c(diǎn)v3.2無(wú)需認(rèn)證設(shè)置向?qū)Ф它c(diǎn)僅在首次運(yùn)行設(shè)置完成前可用且不需要認(rèn)證設(shè)置完成后所有端點(diǎn)返回403 Forbidden。源碼通過(guò)哨兵文件config/.setup_complete判斷設(shè)置狀態(tài)backend/src/module/api/setup.py。方法/路徑說(shuō)明GET /setup/status檢查是否需要設(shè)置向?qū)Х祷貃need_setup: true}實(shí)際還附帶version字段POST /setup/test-downloader用提供憑據(jù)測(cè)試下載器連接。請(qǐng)求體{type: qbittorrent, host: 172.17.0.1:8080, username: admin, password: adminadmin, ssl: false}。源碼支持qbittorrent、aria2走 JSON-RPCaria2.getVersion驗(yàn)證 RPC secret與mock開發(fā)用模擬下載器三種類型并區(qū)分連接超時(shí)/無(wú)法連接/不是 qBittorrent/IP 被封禁/用戶名密碼錯(cuò)誤等細(xì)化錯(cuò)誤backend/src/module/api/setup.pyPOST /setup/test-rss驗(yàn)證 RSS URL 可訪問(wèn)可解析。請(qǐng)求體{url: https://mikanime.tv/RSS/MyBangumi?tokenxxx}成功時(shí)返回頻道標(biāo)題與條目數(shù)POST /setup/test-notification發(fā)送測(cè)試通知。請(qǐng)求體{type: telegram, token: bot_token, chat_id: chat_id}通過(guò)PROVIDER_REGISTRY查找通知提供者并調(diào)用其test()POST /setup/complete保存全部配置并標(biāo)記設(shè)置完成創(chuàng)建config/.setup_complete。請(qǐng)求體為完整設(shè)置對(duì)象用戶名4–20 字符、密碼至少 8 字符、下載器信息downloader_type、downloader_host、downloader_username、downloader_password、downloader_path默認(rèn)/downloads/Bangumi、downloader_ssl、可選的 RSSrss_url、rss_name與通知notification_enable、notification_type、notification_token、notification_chat_id。完成后寫入配置、重建運(yùn)行時(shí)上下文、添加 RSS 源并啟動(dòng)任務(wù)循環(huán)backend/src/module/api/setup.py安全細(xì)節(jié)/setup/test-rss會(huì)拒絕指向私網(wǎng)/保留/回環(huán)地址的 URL防 SSRF/setup/test-downloader只允許 http/https 協(xié)議探測(cè)/setup/complete額外校驗(yàn)調(diào)用者要么持有有效會(huì)話要么admin賬號(hào)仍是出廠默認(rèn)密碼adminadmin防止升級(jí)后未跑向?qū)У膶?shí)例被未認(rèn)證調(diào)用者覆蓋管理員憑據(jù)backend/src/module/api/setup.py。日志端點(diǎn)GET /api/v1/log獲取完整應(yīng)用日志文件。GET /api/v1/log/clear清空日志文件。這兩個(gè)端點(diǎn)配合排障非常實(shí)用日志的詳細(xì)配置debug 開關(guān)、輸出格式見 docs/config/… 之外的 backend/src/module/conf/log.py。實(shí)踐建議與調(diào)用示例綜合以上端點(diǎn)你可以用 curl 完成一次典型的自動(dòng)化操作。例如登錄并攜帶 cookie 查詢?nèi)糠瑒∫?guī)則# 登錄cookie 寫入文件 curl -c cookies.txt -X POST http://your-host:7892/api/v1/auth/login \ -d usernameadminpasswordadminadmin # 攜帶 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編寫自動(dòng)化腳本時(shí)請(qǐng)記住以下幾點(diǎn)一律使用 POST 控制程序/start、/stop、/restart、/shutdown的 GET 別名僅為舊版兼容保留配置更新不要回傳掩碼GET /config/get返回的********是顯示占位符PATCH 時(shí)應(yīng)提交真實(shí)值設(shè)置向?qū)в猩芷?setup/*在config/.setup_complete創(chuàng)建后即永久返回 403錯(cuò)誤處理所有端點(diǎn)統(tǒng)一返回中英文消息msg_en/msg_zh結(jié)合 HTTP 狀態(tài)碼即可定位問(wèn)題生產(chǎn)環(huán)境嚴(yán)禁設(shè)置AB_DEV_NO_AUTH1否則認(rèn)證會(huì)被全局繞過(guò)。如果你需要把某個(gè)端點(diǎn)接到自己的通知、看板或 Home Assistant 自動(dòng)化中以上每個(gè)端點(diǎn)都有對(duì)應(yīng)的源碼實(shí)現(xiàn)可直接對(duì)照例如登錄見 backend/src/module/api/auth.py、種子列表見 backend/src/module/api/downloader.py、SSE 搜索見 backend/src/module/api/search.py。WebUI 前端對(duì)這些端點(diǎn)的封裝含 TypeScript 類型與請(qǐng)求函數(shù)位于 webui/src/api/可作為集成參考。贊分享后端前端音視頻【免費(fèi)下載鏈接】Auto_BangumiAutoBangumi - 全自動(dòng)追番工具項(xiàng)目地址https://gitcode.com/gh_mirrors/au/Auto_Bangumi點(diǎn)擊查看免費(fèi)下載相關(guān)推薦WatchYourLAN HTTP API 完全指南REST 接口、參數(shù)說(shuō)明與源碼級(jí)實(shí)現(xiàn)解析WatchYourLAN HTTP API 完全指南REST 接口、參數(shù)說(shuō)明與源碼級(jí)實(shí)現(xiàn)解析 本指南基于 WatchYourLAN用 Go 編寫的輕量級(jí)網(wǎng)絡(luò)運(yùn)維網(wǎng)絡(luò)ArchiveBox Crawl REST API 深度解析/api/v1/crawls 端點(diǎn)、請(qǐng)求模式與實(shí)現(xiàn)細(xì)節(jié)ArchiveBox Crawl REST API 深度解析/api/v1/crawls 端點(diǎn)、請(qǐng)求模式與實(shí)現(xiàn)細(xì)節(jié) ArchiveBox 的 archiveb后端數(shù)據(jù)工程ArchiveBox v1 REST API Machine 模塊詳解Machine 與 Binary 資源端點(diǎn)全解析ArchiveBox v1 REST API Machine 模塊詳解Machine 與 Binary 資源端點(diǎn)全解析 本篇技術(shù)文章基于 ArchiveBox后端數(shù)據(jù)工程創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 AutoBangumi REST API 參考：/api/v1 端點(diǎn)全解析與源碼級(jí)實(shí)現(xiàn)說(shuō)明
后端前端音視頻【免費(fèi)下載鏈接】Auto_BangumiAutoBangumi - 全自動(dòng)追番工具項(xiàng)目地址https://gitcode.com/gh_mirrors/au/Auto_Bangumi點(diǎn)擊查看免費(fèi)下載AutoBangumi 在/api/v1路徑下提供了一整套基于 FastAPI 的 REST API覆蓋認(rèn)證、番劇規(guī)則管理、RSS 訂閱源、種子搜索與下載器控制等核心能力。本文以官方 API 參考文檔docs/api/index.md為骨架結(jié)合倉(cāng)庫(kù)源碼逐端點(diǎn)講解請(qǐng)求方式、請(qǐng)求體、響應(yīng)格式與底層實(shí)現(xiàn)幫助你直接編寫腳本、對(duì)接自動(dòng)化流程或深入理解 WebUI 每個(gè)按鈕背后的 HTTP 調(diào)用?；A(chǔ)約定Base URL、認(rèn)證與統(tǒng)一響應(yīng)所有 API 以http://your-host:7892/api/v1為基礎(chǔ) URL。端口 7892 是 WebUI 的默認(rèn)端口在源碼的默認(rèn)配置中定義于 backend/src/module/conf/const.py可通過(guò)環(huán)境變量AB_WEBUI_PORT覆蓋。路由注冊(cè)位于 backend/src/module/api/init.pyv1 APIRouter(prefix/v1)再被 backend/src/main.py 以app.include_router(v1, prefix/api)掛載最終形成/api/v1/...的完整路徑。認(rèn)證要求除登錄端點(diǎn)和首次運(yùn)行的設(shè)置向?qū)馑卸它c(diǎn)都需要 JWT 認(rèn)證。令牌可以通過(guò)兩種方式傳遞Cookietokenjwt登錄成功后自動(dòng)設(shè)置httponlyTrue、samesitestrict、有效期 1 天見 backend/src/module/api/auth.py請(qǐng)求頭Authorization: Bearer token。從源碼看認(rèn)證依賴鏈?zhǔn)莋et_current_user/get_principalbackend/src/module/security/api.py 定義了OAuth2PasswordBearer(tokenUrl/api/v1/auth/login)即令牌校驗(yàn)完全由 JWT 簽名保證。注意AB_DEV_NO_AUTH1環(huán)境變量會(huì)全局繞過(guò)認(rèn)證源碼中有明確警告該變量只能用于開發(fā)絕不能在生產(chǎn)環(huán)境設(shè)置backend/src/module/security/api.py。響應(yīng)格式所有 API 響應(yīng)遵循統(tǒng)一的雙語(yǔ)消息結(jié)構(gòu){ msg_en: Success message in English, msg_zh: 成功消息中文, status: true }該結(jié)構(gòu)對(duì)應(yīng) backend/src/module/models/response.py 中的APIResponse模型status、msg_en、msg_zh三字段。錯(cuò)誤響應(yīng)攜帶標(biāo)準(zhǔn) HTTP 狀態(tài)碼400、401、403、404、500以及中英文錯(cuò)誤消息例如登錄失敗返回401與Invalid username or passwordbackend/src/module/api/auth.py。交互式文檔開發(fā)模式下源碼中以DEV_VERSION為版本號(hào)時(shí)訪問(wèn)http://your-host:7892/docs可打開 Swagger UI直接試調(diào)每個(gè)端點(diǎn)此時(shí)根路徑/也會(huì) 302 跳轉(zhuǎn)到/docsbackend/src/main.py。認(rèn)證端點(diǎn)登錄、刷新與憑據(jù)更新登錄POST /api/v1/auth/login請(qǐng)求體為username與passwordOAuth2 表單格式源碼使用OAuth2PasswordRequestForm即application/x-www-form-urlencoded。成功后設(shè)置包含 JWT 令牌的認(rèn)證 cookie。登錄端點(diǎn)還受登錄 IP 白名單保護(hù)check_login_ip依賴見 backend/src/module/security/api.py當(dāng)security.login_whitelist非空時(shí)僅允許白名單內(nèi)的 IP 登錄。刷新令牌POST /api/v1/auth/refresh_token延長(zhǎng)當(dāng)前瀏覽器會(huì)話。源碼同時(shí)保留了一個(gè)GET /auth/refresh_token兼容別名標(biāo)記為deprecated并在響應(yīng)頭返回Deprecation: true與Warning頭backend/src/module/api/auth.py新客戶端應(yīng)使用 POST。登出GET /api/v1/auth/logout撤銷當(dāng)前持久化會(huì)話并清除認(rèn)證 cookie調(diào)用service.logout(token)后delete_cookie返回{msg_en: Logout successfully., msg_zh: 登出成功。, status: true}。更新憑據(jù)POST /api/v1/auth/update更新用戶名和/或密碼。請(qǐng)求體與登錄一致更新成功后輪換所有會(huì)話并重新簽發(fā) cookie。若用戶名沖突返回409憑據(jù)錯(cuò)誤返回401backend/src/module/api/auth.py。另有GET /auth/me返回當(dāng)前用戶公開信息。Passkey / WebAuthn 無(wú)密碼認(rèn)證v3.2使用 WebAuthn/FIDO2 Passkey 實(shí)現(xiàn)無(wú)密碼登錄分為注冊(cè)、認(rèn)證、管理三組端點(diǎn)端點(diǎn)說(shuō)明POST /passkey/register/options獲取 WebAuthn 注冊(cè)選項(xiàng)質(zhì)詢、依賴方信息POST /passkey/register/verify驗(yàn)證并保存瀏覽器返回的注冊(cè)響應(yīng)POST /passkey/auth/options獲取認(rèn)證質(zhì)詢選項(xiàng)POST /passkey/auth/verify驗(yàn)證認(rèn)證響應(yīng)并簽發(fā) JWT 令牌GET /passkey/list列出當(dāng)前用戶所有已注冊(cè) PasskeyPOST /passkey/delete通過(guò)憑據(jù) ID 刪除已注冊(cè) PasskeyPasskey 的依賴方 IDwebauthn_rp_id與來(lái)源webauthn_origin在security配置節(jié)中定義默認(rèn)配置見 backend/src/module/conf/const.py前端實(shí)現(xiàn)位于 webui/src/services/webauthn.ts。該能力的具體安全說(shuō)明可參考 docs/config/security.md。配置讀寫GET /config/get 與 PATCH /config/updateGET /api/v1/config/get返回完整配置對(duì)象包含program、downloader、rss_parser、bangumi_manage、notification、proxy、experimental_openai、security、update、llm等小節(jié)默認(rèn)值定義于 backend/src/module/conf/const.py。PATCH /api/v1/config/update部分更新配置請(qǐng)求體只需包含要修改的字段。這里有一個(gè)值得注意的源碼細(xì)節(jié)GET /config/get會(huì)對(duì)鍵名包含password、api_key、token、secret的字符串值做遞歸掩碼處理替換為********backend/src/module/api/config.pyPATCH提交時(shí)若某字段仍是掩碼值系統(tǒng)會(huì)按身份匹配策略從舊配置中恢復(fù)原值——如果無(wú)法唯一定位掩碼項(xiàng)對(duì)應(yīng)的舊值例如通知渠道列表被刪除且身份字段同時(shí)被改會(huì)直接報(bào)錯(cuò)要求重新輸入密鑰而不是猜一個(gè)值backend/src/module/api/config.py。這意味著不涉及敏感字段的更新可放心提交涉及敏感字段時(shí)不要提交********占位符應(yīng)提交真實(shí)的新值修改通知渠道這類列表時(shí)盡量只改目標(biāo)項(xiàng)的字段避免身份歧義。番劇動(dòng)畫規(guī)則管理端點(diǎn)番劇模塊對(duì)應(yīng)module/api/bangumi.py中的Bangumi數(shù)據(jù)庫(kù)實(shí)體動(dòng)畫下載規(guī)則含標(biāo)題、季度、集數(shù)偏移等元數(shù)據(jù)。端點(diǎn)如下方法/路徑說(shuō)明GET /bangumi/get/all獲取所有動(dòng)畫下載規(guī)則返回Bangumi對(duì)象數(shù)組GET /bangumi/get/{bangumi_id}按 ID 獲取特定規(guī)則PATCH /bangumi/update/{bangumi_id}更新規(guī)則元數(shù)據(jù)標(biāo)題、季度、集數(shù)偏移等DELETE /bangumi/delete/{bangumi_id}刪除單個(gè)規(guī)則及其關(guān)聯(lián)種子DELETE /bangumi/delete/many/批量刪除請(qǐng)求體{bangumi_ids: [1, 2, 3]}DELETE /bangumi/disable/{bangumi_id}禁用規(guī)則保留文件、停止下載DELETE /bangumi/disable/many/批量禁用GET /bangumi/enable/{bangumi_id}重新啟用規(guī)則GET /bangumi/refresh/poster/all從 TMDB 刷新所有動(dòng)畫海報(bào)GET /bangumi/refresh/poster/{bangumi_id}刷新單個(gè)動(dòng)畫海報(bào)GET /bangumi/refresh/calendar從 Bangumi.tv 刷新放送日歷數(shù)據(jù)GET /bangumi/reset/all刪除所有動(dòng)畫規(guī)則謹(jǐn)慎使用get/all直接調(diào)用db.bangumi.search_all()backend/src/module/api/bangumi.py。除文檔列出的端點(diǎn)外源碼中還包含更多進(jìn)階端點(diǎn)例如POST /bangumi/detect-offset結(jié)合 TMDB 數(shù)據(jù)檢測(cè)季/集偏移不一致返回season_offset、episode_offset、reason與置信度以及設(shè)置放送日weekday的端點(diǎn)backend/src/module/api/bangumi.py。番劇規(guī)則的完整字段與編輯方式可參考 docs/feature/bangumi.md。RSS 訂閱源端點(diǎn)RSS 模塊管理所有訂閱源及其解析出的種子路由前綴/rssPydantic 合法解析器取值為mikan、tmdb、parserbackend/src/module/api/rss.py。方法/路徑說(shuō)明GET /rss獲取所有已配置訂閱源POST /rss/add添加訂閱源請(qǐng)求體{url: ..., aggregate: true, parser: mikan}aggregate表示聚合訂閱parser指定解析引擎POST /rss/enable/many批量啟用請(qǐng)求體為 ID 數(shù)組PATCH /rss/disable/{rss_id}禁用單個(gè)訂閱源POST /rss/disable/many批量禁用DELETE /rss/delete/{rss_id}刪除單個(gè)訂閱源POST /rss/delete/many批量刪除PATCH /rss/update/{rss_id}更新訂閱源配置GET /rss/refresh/all手動(dòng)刷新所有訂閱源GET /rss/refresh/{rss_id}刷新指定訂閱源GET /rss/torrent/{rss_id}獲取從該訂閱源解析出的種子列表POST /rss/analysis分析 RSS URL 并提取動(dòng)畫元數(shù)據(jù)但不訂閱請(qǐng)求體{url: ...}POST /rss/collect從訂閱源下載所有劇集用于已完結(jié)動(dòng)畫對(duì)應(yīng)SeasonCollectorPOST /rss/subscribe訂閱訂閱源以自動(dòng)下載連載動(dòng)畫實(shí)現(xiàn)上add_rss通過(guò)RSSEngine.add_rss(url, name, aggregate, parser)入庫(kù)backend/src/module/api/rss.pycollect走SeasonCollector整季收集邏輯。RSS 解析引擎經(jīng)典/新引擎選擇見rss_parser.engine配置項(xiàng)與訂閱流程詳見 docs/config/rss.md。搜索端點(diǎn)SSE 實(shí)時(shí)流搜索番劇Server-Sent EventsGET /api/v1/search/bangumi?keyword{keyword}provider{provider}以 SSE 流返回解析后的搜索結(jié)果實(shí)現(xiàn)實(shí)時(shí)更新。源碼中該端點(diǎn)的實(shí)際參數(shù)名為site與keywordskeywords支持空格分隔多關(guān)鍵詞返回EventSourceResponsebackend/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。程序控制端點(diǎn)程序控制路由定義于 backend/src/module/api/program.py負(fù)責(zé)主循環(huán)RSS 檢查、下載、重命名的啟停方法/路徑說(shuō)明GET /status獲取程序狀態(tài)返回{status: running, version: 3.2.0, first_run: false}。源碼中status字段實(shí)際為布爾值true/false由ctx.is_running決定version來(lái)自VERSION常量first_run來(lái)自上下文標(biāo)志GET /start啟動(dòng)主程序RSS 檢查、下載、重命名調(diào)用ctx.start_tasks()GET /restart重啟主程序調(diào)用ctx.restart()GET /stop停止主程序WebUI 仍可訪問(wèn)調(diào)用ctx.stop()GET /shutdown關(guān)閉整個(gè)應(yīng)用進(jìn)程Docker 環(huán)境下由容器重啟ctx.stop()后向自身發(fā)送SIGINTGET /check/downloader測(cè)試與已配置下載器qBittorrent的連接返回布爾值一個(gè)對(duì)腳本自動(dòng)化很有用的兼容性細(xì)節(jié)這些控制端點(diǎn)的主方法實(shí)際是POST/start、/stop、/restart、/shutdown均為router.post同時(shí)保留了GET別名并標(biāo)記為 deprecated以便 3.2 及更早版本中依賴 GET 的外部自動(dòng)化cron、Home Assistant 等在升級(jí)后不至于 405 靜默失效backend/src/module/api/program.py。新編寫的集成腳本請(qǐng)一律使用 POST避免將來(lái) GET 別名移除后失效。下載器管理端點(diǎn)v3.2GET /api/v1/downloader/torrents獲取下載器中Bangumi分類category下的所有種子內(nèi)部通過(guò)DownloadClient.get_torrent_info(categoryBangumi)調(diào)用backend/src/module/api/downloader.py。暫停、恢復(fù)與刪除POST /api/v1/downloader/torrents/pause POST /api/v1/downloader/torrents/resume POST /api/v1/downloader/torrents/delete請(qǐng)求體統(tǒng)一為哈希數(shù)組{ hashes: [hash1, hash2], delete_files: false }其中delete_files僅刪除端點(diǎn)使用控制是否連帶刪除下載文件。源碼中多個(gè)哈希以|拼接后一次性交給下載客戶端批量處理backend/src/module/api/downloader.py。此外該模塊還提供了文檔未展開的種子管理能力POST /downloader/torrents/tag用ab:{bangumi_id}標(biāo)簽關(guān)聯(lián)種子與番劇用于重命名器精確查找季/集偏移與POST /downloader/torrents/tag/auto自動(dòng)按名稱/保存路徑匹配并為未打標(biāo)簽的種子補(bǔ)打標(biāo)簽以及重命名沖突查詢與重試端點(diǎn)backend/src/module/api/downloader.py。下載器類型qBittorrent / aria2 / 模擬器與路徑配置詳見 docs/config/downloader.md。設(shè)置向?qū)Ф它c(diǎn)v3.2無(wú)需認(rèn)證設(shè)置向?qū)Ф它c(diǎn)僅在首次運(yùn)行設(shè)置完成前可用且不需要認(rèn)證設(shè)置完成后所有端點(diǎn)返回403 Forbidden。源碼通過(guò)哨兵文件config/.setup_complete判斷設(shè)置狀態(tài)backend/src/module/api/setup.py。方法/路徑說(shuō)明GET /setup/status檢查是否需要設(shè)置向?qū)Х祷貃need_setup: true}實(shí)際還附帶version字段POST /setup/test-downloader用提供憑據(jù)測(cè)試下載器連接。請(qǐng)求體{type: qbittorrent, host: 172.17.0.1:8080, username: admin, password: adminadmin, ssl: false}。源碼支持qbittorrent、aria2走 JSON-RPCaria2.getVersion驗(yàn)證 RPC secret與mock開發(fā)用模擬下載器三種類型并區(qū)分連接超時(shí)/無(wú)法連接/不是 qBittorrent/IP 被封禁/用戶名密碼錯(cuò)誤等細(xì)化錯(cuò)誤backend/src/module/api/setup.pyPOST /setup/test-rss驗(yàn)證 RSS URL 可訪問(wèn)可解析。請(qǐng)求體{url: https://mikanime.tv/RSS/MyBangumi?tokenxxx}成功時(shí)返回頻道標(biāo)題與條目數(shù)POST /setup/test-notification發(fā)送測(cè)試通知。請(qǐng)求體{type: telegram, token: bot_token, chat_id: chat_id}通過(guò)PROVIDER_REGISTRY查找通知提供者并調(diào)用其test()POST /setup/complete保存全部配置并標(biāo)記設(shè)置完成創(chuàng)建config/.setup_complete。請(qǐng)求體為完整設(shè)置對(duì)象用戶名4–20 字符、密碼至少 8 字符、下載器信息downloader_type、downloader_host、downloader_username、downloader_password、downloader_path默認(rèn)/downloads/Bangumi、downloader_ssl、可選的 RSSrss_url、rss_name與通知notification_enable、notification_type、notification_token、notification_chat_id。完成后寫入配置、重建運(yùn)行時(shí)上下文、添加 RSS 源并啟動(dòng)任務(wù)循環(huán)backend/src/module/api/setup.py安全細(xì)節(jié)/setup/test-rss會(huì)拒絕指向私網(wǎng)/保留/回環(huán)地址的 URL防 SSRF/setup/test-downloader只允許 http/https 協(xié)議探測(cè)/setup/complete額外校驗(yàn)調(diào)用者要么持有有效會(huì)話要么admin賬號(hào)仍是出廠默認(rèn)密碼adminadmin防止升級(jí)后未跑向?qū)У膶?shí)例被未認(rèn)證調(diào)用者覆蓋管理員憑據(jù)backend/src/module/api/setup.py。日志端點(diǎn)GET /api/v1/log獲取完整應(yīng)用日志文件。GET /api/v1/log/clear清空日志文件。這兩個(gè)端點(diǎn)配合排障非常實(shí)用日志的詳細(xì)配置debug 開關(guān)、輸出格式見 docs/config/… 之外的 backend/src/module/conf/log.py。實(shí)踐建議與調(diào)用示例綜合以上端點(diǎn)你可以用 curl 完成一次典型的自動(dòng)化操作。例如登錄并攜帶 cookie 查詢?nèi)糠瑒∫?guī)則# 登錄cookie 寫入文件 curl -c cookies.txt -X POST http://your-host:7892/api/v1/auth/login \ -d usernameadminpasswordadminadmin # 攜帶 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編寫自動(dòng)化腳本時(shí)請(qǐng)記住以下幾點(diǎn)一律使用 POST 控制程序/start、/stop、/restart、/shutdown的 GET 別名僅為舊版兼容保留配置更新不要回傳掩碼GET /config/get返回的********是顯示占位符PATCH 時(shí)應(yīng)提交真實(shí)值設(shè)置向?qū)в猩芷?setup/*在config/.setup_complete創(chuàng)建后即永久返回 403錯(cuò)誤處理所有端點(diǎn)統(tǒng)一返回中英文消息msg_en/msg_zh結(jié)合 HTTP 狀態(tài)碼即可定位問(wèn)題生產(chǎn)環(huán)境嚴(yán)禁設(shè)置AB_DEV_NO_AUTH1否則認(rèn)證會(huì)被全局繞過(guò)。如果你需要把某個(gè)端點(diǎn)接到自己的通知、看板或 Home Assistant 自動(dòng)化中以上每個(gè)端點(diǎn)都有對(duì)應(yīng)的源碼實(shí)現(xiàn)可直接對(duì)照例如登錄見 backend/src/module/api/auth.py、種子列表見 backend/src/module/api/downloader.py、SSE 搜索見 backend/src/module/api/search.py。WebUI 前端對(duì)這些端點(diǎn)的封裝含 TypeScript 類型與請(qǐng)求函數(shù)位于 webui/src/api/可作為集成參考。贊分享后端前端音視頻【免費(fèi)下載鏈接】Auto_BangumiAutoBangumi - 全自動(dòng)追番工具項(xiàng)目地址https://gitcode.com/gh_mirrors/au/Auto_Bangumi點(diǎn)擊查看免費(fèi)下載相關(guān)推薦WatchYourLAN HTTP API 完全指南REST 接口、參數(shù)說(shuō)明與源碼級(jí)實(shí)現(xiàn)解析WatchYourLAN HTTP API 完全指南REST 接口、參數(shù)說(shuō)明與源碼級(jí)實(shí)現(xiàn)解析 本指南基于 WatchYourLAN用 Go 編寫的輕量級(jí)網(wǎng)絡(luò)運(yùn)維網(wǎng)絡(luò)ArchiveBox Crawl REST API 深度解析/api/v1/crawls 端點(diǎn)、請(qǐng)求模式與實(shí)現(xiàn)細(xì)節(jié)ArchiveBox Crawl REST API 深度解析/api/v1/crawls 端點(diǎn)、請(qǐng)求模式與實(shí)現(xiàn)細(xì)節(jié) ArchiveBox 的 archiveb后端數(shù)據(jù)工程ArchiveBox v1 REST API Machine 模塊詳解Machine 與 Binary 資源端點(diǎn)全解析ArchiveBox v1 REST API Machine 模塊詳解Machine 與 Binary 資源端點(diǎn)全解析 本篇技術(shù)文章基于 ArchiveBox后端數(shù)據(jù)工程創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考