【Hermes Agent实战】从零开发一个完整的Web应用：FastAPI+Docker本地部署与TaoToken接入

1. 为什么用 Hermes Agent 搭 FastAPI 项目最后卡在 Docker 和模型接入上Hermes Agent 是一个偏工程化的开源开发助手能读文件、跑终端命令、按技能skill组织工作流。拿它从零写一个 FastAPI Web 应用前半程通常很顺生成项目骨架、写 SQLAlchemy 模型、补 Pydantic schema、跑 pytest这些它都能接。真正让人停下来查日志的往往是后半程——Docker 容器化部署以及把应用里调模型的 Base URL 统一改到一个稳定的 API 通道上。这篇就聚焦这两件事。目标很具体用 Hermes Agent 辅助写出一个任务管理 APIFastAPI PostgreSQL给出可直接复制的 Dockerfile 和 docker-compose.yml把容器跑起来再把应用请求模型的 Base URL 指向 TaoToken用统一 Key 走 API 通道最后做接口连通性验证和容器日志排查。适合谁看已经会一点 Python、想用 Hermes Agent 提效、但对 Docker 多容器编排和模型 API 接入还不太熟的人。你不需要先精通 Docker跟着命令走就行。先说清楚这个项目长什么样。任务管理 API 包含用户注册登录JWT、任务的增删改查、优先级和状态过滤、关键词搜索以及 Swagger 文档。技术栈是 FastAPI SQLAlchemy PostgreSQL容器化用 Docker Compose 起两个服务app 和 postgres。模型调用部分我们不在代码里硬编码某家厂商的地址而是把 Base URL 抽成环境变量指向 TaoToken 的 API 入口这样换模型、换 Key 都只改配置。Hermes Agent 在这里的角色是结对开发者你描述需求它生成文件、执行命令、根据报错回改。但容器和网络这类问题报错信息往往藏在日志里需要你自己会看docker compose logs。所以这篇的重点不是让 Agent 全自动而是你带着 Agent 把这条链路走通。我试过把整个流程拆成几个可验证的小步先本地裸跑 FastAPI 确认代码没问题再容器化再改 Base URL 接 TaoToken最后验证。每一步都有明确的成功标志出问题也好定位。下面按这个顺序展开。2. 前置准备Hermes Agent 环境与 TaoToken API Key 获取在动手写代码前先把两样东西准备好Hermes Agent 的运行环境以及 TaoToken 的 API Key。Hermes Agent 的安装方式随版本变化核心是让它能在你的项目目录里读写文件、执行终端命令。装好后进入一个空目录启动它用自然语言描述任务即可。它内部会调用 file、terminal 这类工具你可以在对话里看到它执行了哪些命令。建议第一次用时先让它跑一个pwd和ls确认工作目录正确避免它把文件写到别处。TaoToken 这边你需要拿到三样东西Base URL、API Key、以及你要用的 Model ID。Base URL 是https://taotoken.net/api这是所有请求的统一入口。API Key 在控制台的 API Keys 页面创建创建后只显示一次记得复制保存。Model ID 取决于你想调用的模型在模型列表里能看到具体名称。拿到 Key 之后先别急着写进代码。建议先用 curl 验证一下这个 Key 能不能通避免后面把网络问题和代码问题混在一起排查。命令如下curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的API_KEY \ -H Content-Type: application/json \ -d { model: 你的Model_ID, messages: [{role: user, content: ping}] }如果返回里有choices字段说明 Key 和通道都正常。如果返回 401多半是 Key 复制错了或者带了多余空格如果连接超时先检查本机网络能不能访问这个域名。这一步过了再往下走。关于 Key 的管理有个习惯值得养成永远不要把 Key 写进代码文件或提交到 Git。用.env文件存.gitignore里排除它容器里通过环境变量注入。后面 Docker Compose 部分会具体写。另外如果你打算长期用 Hermes Agent 做编码和 Agent 类任务可以了解一下 Coding Plan它面向的是持续性的开发场景比单次调用更划算。这个不是必须的按你的使用频率决定。前置准备做完你应该有一个能跑的 Hermes Agent、一个验证通过的 TaoToken API Key、以及记下来的 Base URL 和 Model ID。接下来开始搭项目。3. 可复制配置FastAPI 项目结构、Dockerfile 与 docker-compose这一节给出可以直接复制的配置。项目结构按 FastAPI 社区常见组织方式task-manager/ ├── app/ │ ├── __init__.py │ ├── main.py │ ├── config.py │ ├── models/ │ ├── schemas/ │ ├── api/ │ ├── auth/ │ └── db/ ├── tests/ ├── Dockerfile ├── docker-compose.yml ├── requirements.txt └── .envrequirements.txt至少包含这些fastapi0.110.0 uvicorn[standard]0.29.0 sqlalchemy2.0.29 psycopg2-binary2.9.9 pydantic2.6.4 python-jose[cryptography]3.3.0 passlib[bcrypt]1.7.4 python-multipart0.0.9 httpx0.27.0app/config.py用 pydantic-settings 读环境变量把数据库地址和模型接入配置都抽出来from pydantic_settings import BaseSettings class Settings(BaseSettings): DATABASE_URL: str postgresql://taskmanager:taskmanagerpostgres/taskmanager SECRET_KEY: str change-me LLM_BASE_URL: str https://taotoken.net/api LLM_API_KEY: str LLM_MODEL: str class Config: env_file .env settings Settings()注意LLM_BASE_URL默认就指向 TaoToken 的 API 入口LLM_API_KEY和LLM_MODEL从环境变量注入。这样代码里不出现任何硬编码的 Key。Dockerfile用多阶段构建减小镜像体积FROM python:3.11-slim as builder WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt FROM python:3.11-slim WORKDIR /app COPY --frombuilder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages COPY --frombuilder /usr/local/bin /usr/local/bin COPY . . EXPOSE 8000 CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8000]docker-compose.yml起两个服务app 依赖 postgres环境变量从.env读services: postgres: image: postgres:15 environment: POSTGRES_USER: taskmanager POSTGRES_PASSWORD: taskmanager POSTGRES_DB: taskmanager ports: - 5432:5432 volumes: - postgres_data:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U taskmanager] interval: 5s timeout: 5s retries: 5 app: build: . ports: - 8000:8000 depends_on: postgres: condition: service_healthy env_file: - .env environment: - DATABASE_URLpostgresql://taskmanager:taskmanagerpostgres/taskmanager volumes: postgres_data:.env文件不要提交到 GitSECRET_KEYyour-random-secret LLM_BASE_URLhttps://taotoken.net/api LLM_API_KEY你的TaoToken_Key LLM_MODEL你的Model_ID这里有个关键点LLM_BASE_URL写的是https://taotoken.net/api应用里所有模型请求都基于这个地址拼/v1/chat/completions。这样你换模型只改LLM_MODEL换 Key 只改LLM_API_KEY代码不动。如果你用的是 Cline 或 Claude Code 这类工具配置思路一样都是三件套Base URL 填https://taotoken.net/apiAPI Key 填你的 KeyModel ID 填模型名。Cline 的 MCP 配置里如果涉及模型接入同样把 Base URL 指向这个地址。Codex 的auth.json里也是填这三项。核心就是别把地址写死成某家厂商的域名。配置齐了执行构建和启动docker compose build docker compose up -d-d是后台运行。起来之后用docker compose ps看两个服务是不是都 Uppostgres 应该是 healthy 状态。4. 验证请求接口连通性与模型调用成功结果容器起来后先验证 Web 服务本身。访问http://localhost:8000/docs能看到 Swagger UI 就说明 FastAPI 正常。再调一个健康检查接口curl http://localhost:8000/health返回{status:ok}即可。如果这一步失败问题在容器或应用启动先看日志别往下走。接着验证模型接入。在应用里加一个测试端点或者直接用 curl 打 TaoToken 的接口确认从容器网络里也能通。容器内验证更接近真实情况docker compose exec app python -c import httpx, os r httpx.post( os.environ[LLM_BASE_URL] /v1/chat/completions, headers{Authorization: Bearer os.environ[LLM_API_KEY]}, json{model: os.environ[LLM_MODEL], messages: [{role:user,content:hello}]}, timeout30 ) print(r.status_code) print(r.json()[choices][0][message][content]) 如果打印出 200 和一段回复内容说明容器内的环境变量注入正确网络也能到达 TaoToken。这一步是整个接入的关键验证点。再验证数据库连通。注册一个用户看数据有没有写进 postgrescurl -X POST http://localhost:8000/auth/register \ -H Content-Type: application/json \ -d {email:ab.com,username:tester,password:123456}返回用户信息后进数据库确认docker compose exec postgres psql -U taskmanager -d taskmanager -c SELECT id, username FROM users;能看到刚注册的用户说明 app 和 postgres 之间的连接正常。到这里三个验证点都过了Web 服务、模型通道、数据库。一个完整的本地部署链路就跑通了。接下来是排障部分把常见的报错和对应处理列出来。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节按真实会遇到的报错来写每个都给定位方法和处理。401 Unauthorized。模型请求返回 401先确认LLM_API_KEY有没有正确注入容器。执行docker compose exec app env | grep LLM看环境变量在不在。如果 Key 在但还 401多半是 Key 本身失效或复制时带了空格。重新在控制台生成一个 Key注意复制完整。还有一种情况是 Base URL 拼错了比如多写或少写/v1导致请求打到了不存在的路径也可能返回 401 或 404。确认LLM_BASE_URL是https://taotoken.net/api代码里拼/v1/chat/completions。local proxy failed。这个报错通常出现在容器内发起外部请求时提示本地代理失败。原因是容器继承了宿主机的代理环境变量但容器网络里那个代理地址不可达。处理办法是在docker-compose.yml的 app 服务里显式清掉代理变量environment: - HTTP_PROXY - HTTPS_PROXY - http_proxy - https_proxy改完docker compose up -d重建容器。清掉之后容器直连就不会再走那个不可达的代理。reading choices 相关报错。比如KeyError: choices或list index out of range说明返回的 JSON 里没有choices字段。先打印完整响应体看结构print(r.status_code, r.text)常见原因是请求体格式不对比如messages写成了字符串而不是列表或者model字段为空。也可能是返回了错误信息但代码直接去取choices。加一层判断先看status_code是不是 200再看r.json()里有没有choices没有就把整个响应打出来。这样定位最快。OAuth 相关报错。如果你用 Claude Code 或类似工具接入可能会遇到 OAuth 认证失败。这类工具默认走 OAuth 流程但接入统一 API 通道时应该用 API Key 方式。检查配置里是不是还留着 OAuth 的 token 字段把它清掉改用ANTHROPIC_BASE_URL或对应的 Base URL 配置项指向https://taotoken.net/api认证方式选 API Key。Claude Code 的配置里Base URL、API Key、Model ID 三项都要填对缺一项就会认证失败。容器启动后 app 反复重启。用docker compose logs app看日志。常见是数据库还没就绪 app 就启动连接被拒。depends_on配了condition: service_healthy能缓解但如果 postgres 健康检查没配好还是会抢跑。确认 postgres 的 healthcheck 生效或者给 app 加一个启动重试逻辑。端口被占用。docker compose up报port is already allocated说明 8000 或 5432 被别的进程占了。改docker-compose.yml里的端口映射比如8001:8000或者先停掉占用端口的进程。排查的核心习惯是先看日志再看环境变量最后看代码。docker compose logs -f app能实时跟日志大部分问题在日志里都有明确提示。6. 把链路固定下来从本地验证到长期使用的接入建议走到这里你已经有了一个能跑的 FastAPI 应用容器化部署完成模型请求通过 TaoToken 的统一通道走。接下来是把这套配置固定成习惯避免每次重搭都踩一遍坑。第一把.env模板化。提交一个.env.example里面只写变量名和占位符真正的.env留在本地。团队协作时每个人填自己的 Key代码和配置分离。第二Base URL 只在一处定义。不管是 FastAPI 应用、Cline、Claude Code 还是 Codex都指向https://taotoken.net/api。这样你换模型时只改 Model ID不用满项目找地址。三件套Base URL Key Model ID在哪个工具里都是这三项记牢就不会乱。第三验证脚本保留下来。把第 4 节那段容器内 curl 验证存成一个scripts/check_llm.sh每次改完配置跑一遍几秒钟就能确认通道正常比启动整个应用再测快得多。第四日志别关。docker compose logs是你排查问题的第一手资料。生产环境里把日志收集起来出问题能回溯。如果你打算把这个项目继续做下去比如加任务提醒、团队协作、或者接更多模型接入层保持现在这个抽象就不会乱。模型调用统一走一个 clientBase URL 和 Key 从配置读换供应商只改配置。这样 Hermes Agent 帮你加功能时也不会把接入逻辑写散。需要查具体接口参数或模型列表可以看接入文档。想先试试模型对话效果直接在模型对话页面发一条消息就能验证。长期做编码和 Agent 任务的话Coding Plan 比按次调用更合适。API Key 在控制台的 API Keys 页面管理随时可以重新生成。最后留一个实用技巧Docker 构建慢的时候把requirements.txt的复制和pip install放在COPY . .之前利用层缓存。改代码不会触发重装依赖构建从几分钟降到几秒。这个顺序在本文的 Dockerfile 里已经这么写了你改代码时能直接感受到差别。