Docker Compose 部署 Hermes Agent 步骤
1 预先拉取镜像
要先把 Hermes 的 Docker 镜像拉取到本地，可以使用以下命令：
docker pull nousresearch/hermes-agent:latest
1.1 使用 Docker Compose 拉取（推荐）
在后文创建好 docker-compose.yaml 文件后，也可以使用 Compose 命令一次性拉取其中定义的所有服务镜像：
# 在 docker-compose.yaml 所在目录执行
docker compose pull
这个命令会读取你的 Compose 文件，并拉取 image 字段指定的镜像，效果与 docker pull 相同。
1.2 补充说明
latest标签会指向最新的稳定版。若工作环境需要特定版本，可以换成具体标签，如nousresearch/hermes-agent:v1.2.3。- 若拉取时遇到网络问题，可以考虑配置 Docker 镜像加速器（如阿里云、中科大等），或者通过
proxychains命令拉取。
镜像拉取步骤可参考笔记Docker国内镜像源配置及走代理设置
2 预设置 Hermes 容器
2.1 预设置步骤
通过 docker run 命令启动这个设置向导。这是一个一次性操作，目的是将你的 API 密钥等信息写入到持久化的数据目录中。
在终端中执行以下命令：
docker run -it --rm \ # 以交互模式运行一个一次性容器，任务完成后会自动删除。
-v ~/.hermes:/opt/data \ # 将你宿主机上的 ~/.hermes 目录挂载到容器内的 /opt/data，这是 Hermes 存储所有配置和用户数据的地方。
nousresearch/hermes-agent:latest setup # 指定使用官方镜像并运行 setup 命令
执行后跟随 setup 向导设置内容即可。
2.2 预设置的优点
预先运行 setup 命令，本质上是为后续正式运行 准备一个必需且持久的“配置数据卷”。Hermes Agent 的设计遵循了 Docker 的最佳实践：镜像本身是无状态的，所有用户数据（如 API 密钥、会话记录、技能等）都存储在宿主机的一个挂载目录中。
主要有两方面优点：
- 数据写入持久化卷：
setup向导会将这些配置信息（如 API 密钥）写入到挂载到容器内/opt/data路径的宿主机目录~/.hermes中，主要是~/.hermes/.env文件。 - 后续运行直接读取，对更新版本良好年：后续对容器进行操作时，容器会直接读取
~/.hermes中已存在的、由setup准备好的完整配置，从而免去在无交互的后台环境中进行配置的麻烦；并且更新 Hermes 版本就只需重新运行一次docker compose即可，不会更改已有配置。
3 Docker Compose 文件编写与部署
工具 docker compose 的使用细节参考笔记:
docker compose部署nginx+php+mysql+phpmyadmin环境（LNMP环境）。
部署 Hermes 时主要的区别在于最好将敏感信息，包括控制面板账户密码、API-SERVER KEY 等，不明文写在 docker-compose.yml 文件内，而是写在 docker-compose.yml 同文件夹下的 .env 文件中，通过变量的形式引用。
文件结构：
~/hermes-deploy/ # 你的compose部署主目录
├── docker-compose.yml # 核心 Compose 配置文件
└── .env # 存放敏感环境变量（API 密钥等）
3.1 文件示例
具体语句含义可以参考 Hermes 官方 WIKI
docker-compose.yml
#Create Hermes Agent
services:
hermes:
image: nousresearch/hermes-agent:latest
container_name: hermes
restart: unless-stopped
command:
- gateway
- run
ports:
# ----- API Server 端口（OpenAI 兼容）-----
# 启用 API Server 后必须映射此端口，供外部程序调用
- "8642:8642"
# ----- Dashboard 端口（Web 管理界面）-----
- "9119:9119"
volumes:
- ${HERMES_DATA_PATH}:/opt/data
environment:
# 让容器内 Hermes 用户映射为宿主机 USER 的 UID/GID
HERMES_UID: "1000"
HERMES_GID: "1000"
# ======================================================
# 1. Dashboard 配置（Web 界面）
# ======================================================
HERMES_DASHBOARD: "1"
HERMES_DASHBOARD_HOST: "0.0.0.0"
HERMES_DASHBOARD_PORT: "9119"
# ----- Dashboard 认证（必须，因绑定 0.0.0.0）-----
# 生成密码：openssl rand -hex 20
# 生成会话密钥：openssl rand -hex 32
HERMES_DASHBOARD_BASIC_AUTH_USERNAME: ${DASHBOARD_USERNAME}
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD: ${DASHBOARD_PASSWORD}
HERMES_DASHBOARD_BASIC_AUTH_SECRET: ${DASHBOARD_SECRET}
# ======================================================
# 2. API Server 配置（程序化调用）
# ======================================================
# ----- 启用 API Server（必须设置为 true）-----
API_SERVER_ENABLED: "true"
# ----- API Server 监听地址（容器内）-----
# 0.0.0.0 允许外部访问；若仅限本地可改为 127.0.0.1
API_SERVER_HOST: "0.0.0.0"
# ----- API Server 端口（容器内）-----
# 默认 8642，与宿主机映射保持一致
API_SERVER_PORT: "8642"
# ----- API 密钥（必须设置，至少 8 字符）-----
# 强烈建议使用强随机串，例如：openssl rand -hex 32
API_SERVER_KEY: ${API_SERVER_KEY}
# ----- CORS 跨域设置（可选）-----
# 如果你的前端应用在另一个域名下调用 API，可设置允许的来源
# 开发环境可设为 "*"（允许所有），生产环境建议指定具体域名
API_SERVER_CORS_ORIGINS: "*"
# ======================================================
# 3. 其他可选高级配置
# ======================================================
# 如果你需要 API Server 返回详细错误信息（调试用），可启用
API_SERVER_DEBUG: "false"
deploy:
resources:
limits:
memory: 4G
cpus: "2.0"
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "5"
.env
# Settings of Hermes Agent
HERMES_DATA_PATH=/home/user/.hermes # 改为你的实际路径
DASHBOARD_USERNAME=user
DASHBOARD_PASSWORD=your_password
DASHBOARD_SECRET=your_authcode
API_SERVER_KEY=your_hermes_apikey
3.2 docker compose 部署操作
# 启动服务
docker compose up -d
# 查看日志确认启动成功
docker compose logs -f
# 关闭服务
docker compose down