企业官网建设流程全解析

1. 树莓派跑 Hermes Agent 到底卡在哪：Docker 部署的真实场景

Hermes Agent 是一个可以常驻在本地设备上的智能体网关，它能接微信、接命令行、接 Dashboard，把大模型的对话能力落到你自己的硬件上。树莓派 8GB 版本是很多人手里的第一台“永远在线”的小主机，功耗低、噪音小、24 小时开着也不心疼，所以拿它来跑 Hermes Agent 是很自然的选择。但真到动手的时候，问题会一个接一个冒出来：镜像 3.8GB 拉不动、aarch64 架构下容器起不来、Dashboard 绑了 0.0.0.0 却打不开、容器里写的文件宿主机没权限、模型 API 端点默认指向海外服务导致请求超时。

这篇内容就是把这些坑按顺序填平。我会从系统源配置讲到 Docker 安装，再给出可以直接复制的 docker-compose 配置，最后把 API 端点切到 TaoToken 完成统一 Key 接入，并用日志和接口调用验证部署成功。适合手里有树莓派 4B/5、想跑一个本地 Agent 网关、又不想被网络和权限问题反复折腾的人。整个过程不需要你懂容器编排，命令和配置文件我都会给全，你照着改路径和 Key 就行。

需要提前说明的是，树莓派的内存和磁盘是硬约束。Hermes Agent 镜像约 3.8GB，运行数据约 300MB，建议至少留 10GB 可用空间。8GB 内存版本跑 gateway + dashboard 两个容器是够的，4GB 版本建议只跑 gateway，Dashboard 用的时候再临时起。下面所有操作默认你在树莓派本机终端执行，用户有 sudo 权限，系统是 Raspberry Pi OS 或 Debian 13 (trixie) aarch64。

2. 前置准备：Docker 安装、镜像加速与 TaoToken Key 获取

2.1 系统源换成国内镜像

树莓派默认的 Debian 源在国内访问很慢，先把/etc/apt/sources.list.d/debian.sources里的http://deb.debian.org换成清华镜像。一条命令搞定：

sudo sed -i 's|http://deb.debian.org|https://mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list.d/debian.sources sudo apt update

注意树莓派专属源archive.raspberrypi.com没有对应的国内镜像，保留原地址即可，不要一起替换，否则apt update会报 404。

2.2 安装 Docker 与 compose 插件

用阿里云的 Docker CE 源手动安装，比一键脚本更可控，也不会因为网络问题中途断掉：

curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-ce.gpg echo "deb [arch=arm64 signed-by=/usr/share/keyrings/docker-ce.gpg] https://mirrors.aliyun.com/docker-ce/linux/debian trixie stable" | sudo tee /etc/apt/sources.list.d/docker.list sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

装完后把当前用户加进 docker 组，这样后面不用每条命令都加 sudo：

sudo usermod -aG docker $USER newgrp docker sudo systemctl enable docker --now

newgrp docker让当前终端立即生效，不然要重新登录一次。

2.3 配置镜像加速

创建/etc/docker/daemon.json，加上国内可用的 registry mirror，同时限制并发下载数，避免树莓派网络被打满：

{ "registry-mirrors": [ "https://docker.1ms.run", "https://docker.xuanyuan.me" ], "max-concurrent-downloads": 3 }

重启生效：

sudo systemctl restart docker docker info | grep -A 3 "Registry Mirrors"

如果docker info里能看到你配置的 mirror 地址，说明加速生效了。

2.4 获取 TaoToken API Key

Hermes Agent 默认的模型端点指向海外服务，在树莓派这种网络环境下请求经常超时。把端点改成 TaoToken 之后，所有模型调用走同一个 Key、同一个 Base URL，省去每个模型单独配 Key 的麻烦。

打开https://taotoken.net/api-keys登录后创建一个 Key，复制出来形如sk-xxxxxxxx。这个 Key 后面会写进环境变量，不要直接提交到 git 仓库。TaoToken 的 API Base URL 是https://taotoken.net/api，兼容 OpenAI 的/v1/chat/completions接口格式，Hermes Agent 里配置OPENAI_BASE_URL指向它即可。

提示：Key 只在创建时完整显示一次，建议先存到密码管理器里。如果怀疑泄露，在控制台直接删除重建，旧 Key 立即失效。

3. 可复制配置：docker-compose.yml 与环境变量

3.1 目录结构

先在用户目录下建好工作目录和数据目录：

mkdir -p ~/hermes-docker mkdir -p ~/.hermes

~/.hermes是持久化目录，容器里的/opt/data挂载到这里，配置、会话、微信 Token 都存这儿，容器重建数据不丢。

3.2 docker-compose.yml 完整内容

文件路径：~/hermes-docker/docker-compose.yml

services: gateway: image: nousresearch/hermes-agent:latest container_name: hermes restart: unless-stopped network_mode: host volumes: - ~/.hermes:/opt/data environment: - HERMES_UID=${HERMES_UID:-1000} - HERMES_GID=${HERMES_GID:-1000} - OPENAI_API_KEY=${OPENAI_API_KEY} - OPENAI_BASE_URL=${OPENAI_BASE_URL} - OPENAI_MODEL=${OPENAI_MODEL} command: ["gateway", "run"] dashboard: image: nousresearch/hermes-agent:latest container_name: hermes-dashboard restart: unless-stopped network_mode: host depends_on: - gateway volumes: - ~/.hermes:/opt/data environment: - HERMES_UID=${HERMES_UID:-1000} - HERMES_GID=${HERMES_GID:-1000} command: ["dashboard", "--host", "127.0.0.1", "--no-open"]

这里有几个关键点。network_mode: host让容器直接用宿主机网络，Dashboard 的 9119 端口和 gateway 的端口都不需要额外映射。Dashboard 的--host我写的是127.0.0.1，只监听本机，避免把管理界面暴露到局域网，需要访问时用 SSH 隧道转发。

3.3 .env 文件

同目录下创建~/hermes-docker/.env，把 Key 和端点写进去：

HERMES_UID=1000 HERMES_GID=1000 OPENAI_API_KEY=sk-你的TaoToken密钥 OPENAI_BASE_URL=https://taotoken.net/api OPENAI_MODEL=claude-sonnet-4-5

HERMES_UID和HERMES_GID用id -u和id -g查一下当前用户的值填进去，默认 1000 对大多数树莓派用户是对的。模型 ID 按你在 TaoToken 控制台看到的可用模型填，这里以claude-sonnet-4-5为例。

注意：.env文件权限设成 600，chmod 600 ~/hermes-docker/.env，避免同机其他用户读到 Key。

3.4 拉取镜像

镜像约 3.8GB，树莓派上拉取要几分钟到十几分钟，取决于网络。用后台方式拉，避免 SSH 断线中断：

docker pull nousresearch/hermes-agent:latest

如果拉取过程中卡在某一层不动，先确认daemon.json里的 mirror 生效，再重试。拉完后docker images能看到镜像大小。

3.5 启动容器

cd ~/hermes-docker docker compose up -d docker compose ps

docker compose ps里两个容器状态都是Up就说明起来了。如果 gateway 反复重启，先看日志，下一节会讲怎么排查。

4. 验证请求：日志检查与接口调用确认部署成功

4.1 查看启动日志

容器起来不等于服务正常，先看 gateway 日志：

docker logs hermes --tail 50

正常启动会看到类似gateway listening on ...和模型端点初始化的输出。如果看到401 Unauthorized，说明 Key 不对或没读到；如果看到connection refused或超时，说明 Base URL 或网络有问题。

Dashboard 日志：

docker logs hermes-dashboard --tail 50

确认 9119 端口在监听：

ss -tlnp | grep 9119

4.2 直接调用模型接口验证 Key

在树莓派上直接用 curl 打 TaoToken 的接口，确认 Key 和端点本身是通的，把问题范围缩小到 Hermes 配置之前：

curl -s https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的TaoToken密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "回复两个字：正常"}], "max_tokens": 20 }'

返回 JSON 里choices[0].message.content有内容，说明 Key 和端点没问题。如果这里就报 401，先解决 Key 问题，别急着调 Hermes。

4.3 通过 Hermes 发一条测试消息

gateway 起来后，用内置的 CLI 发一条消息，走完整链路：

docker exec -it hermes hermes gateway send --text "你好，测试一下"

如果配置正确，会返回模型生成的回复。这一步能通，说明 Hermes 已经成功把请求转发到 TaoToken 并拿到结果。

4.4 健康检查脚本

写一个简单的健康检查脚本，放到~/hermes-docker/healthcheck.sh：

#!/bin/bash set -e echo "=== 容器状态 ===" docker compose -f ~/hermes-docker/docker-compose.yml ps echo "=== gateway 最近日志 ===" docker logs hermes --tail 10 echo "=== 端口监听 ===" ss -tlnp | grep 9119 || echo "9119 未监听" echo "=== API 连通性 ===" curl -s -o /dev/null -w "HTTP %{http_code}\n" \ https://taotoken.net/api/v1/models \ -H "Authorization: Bearer $(grep OPENAI_API_KEY ~/hermes-docker/.env | cut -d= -f2)"

加执行权限后运行：

chmod +x ~/hermes-docker/healthcheck.sh ~/hermes-docker/healthcheck.sh

HTTP 200表示 API 端点可达，容器状态和端口都正常，部署就算完成了。

4.5 访问 Dashboard

Dashboard 只监听 127.0.0.1，从你的电脑通过 SSH 隧道转发：

ssh -L 9119:127.0.0.1:9119 你的用户名@树莓派IP

然后在本地浏览器打开http://127.0.0.1:9119。如果 Dashboard 绑定了 0.0.0.0，需要在~/.hermes/config.yaml里配 basic_auth，生成密码哈希：

docker exec hermes-dashboard python3 -c "from plugins.dashboard_auth.basic import hash_password; print(hash_password('你的密码'))"

把输出的哈希填进 config.yaml 的dashboard.basic_auth.password_hash。不过更推荐保持 127.0.0.1 + SSH 隧道的方式，少一层认证配置，也更安全。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

5.1 401 Unauthorized

最常见的报错。日志里出现401或invalid api key，按顺序查三处：.env里的OPENAI_API_KEY有没有多余空格或引号；docker compose config看环境变量有没有正确注入；容器里docker exec hermes env | grep OPENAI确认读到的值和你写的一致。如果 Key 是从控制台复制的，注意别把前后空白带进去。

5.2 local proxy failed

这个报错通常出现在容器内请求外部 API 时。network_mode: host下容器直接用宿主机网络，如果宿主机配了 HTTP_PROXY 之类的环境变量，容器会继承，导致请求被转发到不存在的代理。检查宿主机env | grep -i proxy，如果有残留的代理变量，在.env里显式清空：

HTTP_PROXY= HTTPS_PROXY= NO_PROXY=localhost,127.0.0.1

然后docker compose up -d重建容器。

5.3 reading choices 相关报错

日志里出现reading 'choices'或cannot read property 'choices' of undefined，说明 Hermes 拿到了响应但结构不对。多半是 Base URL 写错了，比如漏了/v1或者多写了路径。TaoToken 的 Base URL 是https://taotoken.net/api，Hermes 内部会拼/v1/chat/completions，你不需要在 Base URL 里再加/v1。用第 4.2 节的 curl 命令确认返回结构，再对照.env里的OPENAI_BASE_URL。

5.4 OAuth 相关报错

如果日志里出现 OAuth 或 token refresh 失败，说明 Hermes 在尝试用 OAuth 方式认证某个模型提供商。用 TaoToken 统一 Key 接入时不需要 OAuth，检查~/.hermes/config.yaml里有没有残留的 OAuth provider 配置，把对应的 provider 段删掉，只保留走OPENAI_BASE_URL的配置。改完重启 gateway：

docker compose restart gateway

5.5 权限错误

容器里写文件报Permission denied，是 UID/GID 不匹配。修复宿主机数据目录所有权：

sudo chown -R $USER:$USER ~/.hermes

确认.env里HERMES_UID和HERMES_GID等于id -u和id -g的输出，然后重建容器。

5.6 镜像拉取卡住

docker pull长时间停在某一层，先docker info确认 mirror 生效，再检查磁盘空间df -h。树莓派磁盘满了也会导致拉取失败。清理无用镜像docker image prune -a后再试。

6. 把 Key 统一到 TaoToken：长期编码与 Agent 场景的接入建议

部署跑通之后，日常使用中你可能会遇到模型切换的需求：今天用这个模型写代码，明天用那个模型处理长文本。如果每个模型都单独配 Key、单独改端点，维护成本很高。TaoToken 的价值就在于把多个模型的调用统一到一个 Base URL 和一个 Key 上，Hermes Agent 只需要改.env里的OPENAI_MODEL就能切换模型，不用动其他配置。

对于长期跑在树莓派上的 Agent 场景，建议把 gateway 设成restart: unless-stopped，这样树莓派重启后容器自动拉起。Dashboard 按需启动，平时用 SSH 隧道访问。如果你打算把 Hermes 接到微信上做个人助手，扫码获取 Token 的命令是：

docker exec -it hermes hermes gateway setup

选择微信后终端会显示二维码，扫码后 Token 自动写入~/.hermes下的配置，gateway 自动生效，不用重启。相关环境变量WEIXIN_ALLOWED_USERS控制允许交互的用户，WEIXIN_DM_POLICY默认pairing，WEIXIN_GROUP_POLICY默认disabled，按需调整。

如果你后面要接 Claude Code 或者做更复杂的 Agent 编排，TaoToken 的 Coding Plan 提供了适合长期编码场景的额度方案，可以在https://taotoken.net/coding-plan了解。模型对话调试用https://taotoken.net/models，接入文档在https://taotoken.net/doc，Key 管理在https://taotoken.net/api-keys。把这几处收藏好，后面换模型、加额度、查文档都不用再翻聊天记录。

最后提醒一句：树莓派上的.env和~/.hermes目录里存着 Key 和微信 Token，定期备份~/.hermes到安全位置，但别把.env一起提交到公开仓库。容器重建时数据不丢，靠的就是这个持久化目录。