1. 为什么 Aria2 容器化后WebUI 鉴权反而更麻烦了Aria2 本身是个很纯粹的下载引擎它只负责跑 RPC 接口不关心谁在调用。容器化之后Aria2 跑在aria2容器里WebUI 跑在web容器里Traefik 在最外层做入口。看起来分工清晰但真正部署过的人会碰到一个很别扭的问题鉴权被拆散在三个地方。Aria2 的 RPC 靠--rpc-secret做令牌校验WebUI 要连 RPC 就得把这个 secret 填进去Traefik 做域名入口时如果还想加一层 Basic Auth又得单独维护一份 htpasswd如果后面再挂个下载完成通知、或者给别的服务调用 Aria2 的 JSON-RPC每个调用方都得各自保存一份 secret。密钥一多轮换就成了灾难——改一个 secret得把所有引用它的地方翻一遍。我试过最原始的写法docker-compose.yml里把RPC_SECRET写死在环境变量WebUI 的configuration.js里再硬编码一份。结果某次想换 secret改完 Aria2 忘了改 WebUIWebUI 一直报Unauthorized排查了半小时才发现是两边不一致。这种密钥分散的痛自建下载站的开发者应该都懂。这篇要解决的问题很具体用 TaoToken 作为统一的 Key/API 通道把 Aria2 RPC 鉴权和 WebUI 访问鉴权收敛到一处管理同时给出 Aria2 Traefik WebUI 的可复制docker-compose配置最后用curl验证下载任务下发和 WebUI 访问都正常。适合已经在用 Docker 跑 Aria2、但被多服务密钥管理搞烦的开发者。核心检索词就是 Aria2 容器化部署、Traefik 反向代理、WebUI 鉴权统一管理。先说清楚一个前提TaoToken 在这里扮演的是统一 Key 与 API 通道的角色它不替代 Aria2 的下载能力也不替代 Traefik 的路由能力而是把散落在各处的鉴权凭据集中到一套 Key 体系里。你可以把它理解成一个统一的凭据中枢Aria2 的 RPC secret、WebUI 的访问令牌、以及后续要接入的其他服务都从这一处取。2. TaoToken 前置准备拿到统一 Key 与 API 通道在动手改docker-compose.yml之前先把 TaoToken 这边的准备工作做完。这一步不复杂但顺序别搞反否则后面配置里填什么都不知道。首先访问官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录。登录后进入控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面创建一个新的 Key。这个 Key 就是后面要填进配置里的统一凭据建议命名成aria2-homelab之类能一眼看出用途的名字方便以后轮换时定位。创建完成后你会拿到一串以sk-开头的 Key。复制保存好页面刷新后就看不全了。如果你还想在浏览器里直接和模型对话来辅助排查配置问题可以打开模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 把报错信息贴进去问比翻文档快。API 的基础地址是 https://taotoken.net/api 注意这个地址不带任何查询参数配置里直接用它作为 Base URL。如果你后续要用 Claude Code 之类的编码工具来管理这套 Homelab 配置可以看接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各客户端的接入方式。长期跑下载任务、想让 Agent 帮你盯日志的话Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 会更合适。这里要强调一个概念TaoToken 的 Key 是统一凭据不是让你把它直接当成 Aria2 的rpc-secret用。正确的做法是Aria2 容器启动时通过环境变量从 TaoToken 的配置中心拉取 secretWebUI 和 Traefik 的鉴权也引用同一套 Key 体系。这样轮换时只改一处。准备工作清单项目值用途Base URLhttps://taotoken.net/api统一 API 通道API Keysk-xxxx控制台生成统一鉴权凭据控制台https://taotoken.net/console管理 Key接入文档https://taotoken.net/doc客户端配置参考拿到 Key 之后先别急着改 compose我们下一步先把目录结构和配置文件准备好。3. 可复制配置docker-compose 与 Traefik 标签这一节是全文的核心所有配置都可以直接复制。先建目录结构mkdir -p ~/aria2-stack/{config,downloads,traefik} cd ~/aria2-stackconfig放 Aria2 配置downloads是下载目录traefik放 Traefik 的静态配置和证书。先写 Traefik 的静态配置traefik/traefik.ymlentryPoints: web: address: :80 websecure: address: :443 providers: docker: exposedByDefault: false network: traefik api: dashboard: true再写 Aria2 的配置文件config/aria2.conf。注意rpc-secret这里先留占位实际值通过环境变量注入continuetrue dir/downloads input-file/config/aria2.session save-session/config/aria2.session save-session-interval60 enable-rpctrue rpc-listen-alltrue rpc-allow-origin-alltrue rpc-listen-port6800 rpc-secret${ARIA2_RPC_SECRET}然后是核心的docker-compose.yml。这里把 Aria2、WebUI、Traefik 三个服务串起来鉴权统一从.env读取version: 3.8 services: traefik: image: traefik:v2.10 container_name: traefik restart: unless-stopped ports: - 80:80 - 443:443 volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - ./traefik/traefik.yml:/etc/traefik/traefik.yml:ro networks: - traefik aria2: image: p3terx/aria2-pro container_name: aria2 restart: unless-stopped environment: - PUID1000 - PGID1000 - RPC_SECRET${ARIA2_RPC_SECRET} - RPC_PORT6800 volumes: - ./config:/config - ./downloads:/downloads networks: - traefik labels: - traefik.enablefalse webui: image: p3terx/ariang container_name: webui restart: unless-stopped environment: - ARIA2_RPC_URLhttp://aria2:6800/jsonrpc - ARIA2_RPC_SECRET${ARIA2_RPC_SECRET} networks: - traefik labels: - traefik.enabletrue - traefik.http.routers.webui.ruleHost(${BIND_HOST}) - traefik.http.routers.webui.entrypointsweb - traefik.http.services.webui.loadbalancer.server.port80 - traefik.http.middlewares.webui-auth.basicauth.users${WEBUI_BASIC_AUTH} - traefik.http.routers.webui.middlewareswebui-auth networks: traefik: name: traefik配套的.env文件把 TaoToken 的统一 Key 填进去# TaoToken 统一 Key从控制台获取 TAOTOKEN_API_KEYsk-你的Key # Aria2 RPC secret与 TaoToken Key 体系保持一致 ARIA2_RPC_SECRETsk-你的Key # WebUI 访问域名 BIND_HOSTdownload.lab.com # WebUI Basic Auth格式 user:$$apr1$$... WEBUI_BASIC_AUTHadmin:$$apr1$$xxxxxxxx这里有个关键点ARIA2_RPC_SECRET和TAOTOKEN_API_KEY用同一个值意味着 Aria2 的 RPC 鉴权和 TaoToken 的 API 鉴权走的是同一套凭据。轮换时只改.env一处docker-compose up -d重启即可WebUI 和 Traefik 自动跟着变。生成 Basic Auth 密码用这条命令htpasswd -nb admin 你的密码 | sed -e s/\$/\$\$/g把输出填进WEBUI_BASIC_AUTH。注意$要转义成$$否则 compose 会把它当变量解析。如果你用的是 Cline MCP 或 Claude Code 来管理这套配置接入时同样填三件套Base URL 用 https://taotoken.net/api Key 用TAOTOKEN_API_KEYModel ID 按文档填。这样你的编码工具和下载站共用一套凭据不用再单独维护。4. 验证请求curl 测下载任务与 WebUI 访问配置写完启动服务docker-compose up -d docker-compose logs -f aria2看到IPv4 RPC: listening on TCP port 6800就说明 Aria2 起来了。接下来用curl验证两件事RPC 能否下发下载任务WebUI 能否正常访问。先测 Aria2 RPC。注意token字段填的就是.env里的ARIA2_RPC_SECRETcurl -s http://localhost:6800/jsonrpc \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, id: 1, method: aria2.addUri, params: [ token:sk-你的Key, [https://example.com/test.zip], {dir: /downloads} ] }正常返回是一个任务 GID类似{id:1,jsonrpc:2.0,result:2089b05ecca3d829}拿到 GID 后查任务状态curl -s http://localhost:6800/jsonrpc \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, id: 2, method: aria2.tellStatus, params: [token:sk-你的Key, 2089b05ecca3d829] }返回里status字段是active或complete就说明下载链路通了。如果返回{error:{code:1,message:Unauthorized}}说明 token 不对回去检查.env里的ARIA2_RPC_SECRET和 curl 里填的是否一致。再测 WebUI 访问。因为 Traefik 做了 Basic Auth直接 curl 会返回 401curl -I http://download.lab.com预期返回HTTP/1.1 401 Unauthorized WWW-Authenticate: Basic realmtraefik带上凭据再请求curl -I -u admin:你的密码 http://download.lab.com返回HTTP/1.1 200 OK就说明 WebUI 鉴权正常。打开浏览器访问http://download.lab.com输入同样的账号密码应该能看到 AriaNg 界面并且 RPC 状态显示已连接。这里验证的是统一 Key的效果Aria2 RPC 用的 secret 和 TaoToken 的 API Key 是同一个值WebUI 通过环境变量拿到同一个 secret 去连 RPCTraefik 的 Basic Auth 则是另一层入口保护。三层鉴权但凭据来源收敛到.env一处。5. 本篇常见错排查401、proxy failed 与 OAuth部署过程中最容易撞的几个报错我按实际遇到的频率排一下。报错一Unauthorized/ 401这是最高频的。Aria2 RPC 返回{error:{code:1,message:Unauthorized}}原因通常是三处 secret 不一致.env里的ARIA2_RPC_SECRET、Aria2 容器实际加载的rpc-secret、以及 WebUI 或 curl 里填的 token。排查方法docker exec aria2 env | grep RPC_SECRET docker exec webui env | grep RPC_SECRET两个输出必须一致。如果不一致说明.env改了但容器没重建执行docker-compose up -d --force-recreate。报错二local proxy failed/ 502 Bad GatewayTraefik 日志里出现levelerror msgService unavailable errordial tcp 172.x.x.x:80: connect: connection refused这是 Traefik 找不到 WebUI 容器的端口。检查docker-compose.yml里 WebUI 的 label- traefik.http.services.webui.loadbalancer.server.port80AriaNg 容器内部监听的是 80 端口如果你写成了 8888 就会连不上。另外确认 WebUI 和 Traefik 在同一个traefik网络里docker network inspect traefik看两个容器是否都在。报错三reading choices/ 响应解析失败如果你在 WebUI 里配置了额外的 API 通道或者用脚本调 TaoToken 的接口时看到Error: reading choices: unexpected end of JSON input这通常是请求体格式不对或者 Base URL 写成了带路径的形式。TaoToken 的 Base URL 就是 https://taotoken.net/api 不要在后面加/v1之类的后缀。请求头要带Authorization: Bearer sk-你的Key和Content-Type: application/json。报错四OAuth / 认证回调失败如果你在接入某些客户端时走了 OAuth 流程回调报错检查回调地址是否和 TaoToken 控制台里配置的一致。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Keys 页面可以管理凭据。如果 OAuth 一直不通退回到直接用 API Key 的方式在接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里有各客户端的 Key 配置示例。报错五rpc-secret未生效Aria2 启动日志里出现Neither --rpc-secret nor a combination of --rpc-user and --rpc-passwd is set.说明aria2.conf里的rpc-secret${ARIA2_RPC_SECRET}没被替换。Aria2 容器不会自动展开${}变量需要用p3terx/aria2-pro这类支持环境变量注入的镜像或者改用命令行参数--rpc-secret。检查镜像文档确认变量注入方式。排查顺序建议先看docker-compose logs里各容器的启动日志再用docker exec进容器看环境变量最后用 curl 逐层测 RPC 和 HTTP 入口。大部分问题都出在凭据不一致或端口写错。6. 统一 Key 之后下载站维护变简单了把 Aria2、WebUI、Traefik 的鉴权收敛到 TaoToken 一套 Key 之后最直接的变化是轮换成本。以前改一个 secret 要动三个文件、重启三个容器、还得手动同步 WebUI 里的配置现在只改.env里的ARIA2_RPC_SECRET和TAOTOKEN_API_KEYdocker-compose up -d --force-recreate一把重建所有服务自动拿到新值。另一个好处是扩展。你后面想加个下载完成自动通知、或者给 NAS 上的其他服务开放 Aria2 RPC 调用不用再单独发一套凭据直接复用同一个 Key在 TaoToken 控制台里能看到所有调用记录。如果调用方是编码工具或 Agent走 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 接入Base URL 和 Key 都是现成的。最后留个实用技巧把.env加进.gitignore别把 Key 提交到仓库。如果团队协作用.env.example留占位符真实值通过 TaoToken 控制台分发。轮换时先在控制台生成新 Key更新.env重建容器确认 curl 验证通过后再去控制台吊销旧 Key这样不会出现服务中断窗口。