Docker Compose是部署Hermes Agent的首选方式，可规避Python环境冲突与依赖问题，提供基础单节点、生产持久化、Web UI集成、Apple Silicon适配及国产信创环境五种经实测验证的部署方案。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试部署 Hermes Agent，但反复遭遇 Python 环境冲突、依赖版本不兼容、模型 provider 初始化失败或 API 密钥加载异常等问题，则很可能是本地环境杂乱导致的配置失效。Docker Compose 提供声明式容器编排能力，可完全隔离运行时依赖，规避宿主机环境干扰。以下是多种经实测验证的 Docker Compose 部署方案，覆盖不同硬件架构、数据持久化需求与服务组合场景。
一、基础单节点部署（零依赖快速启动）
该配置直接拉取官方预构建镜像，不执行任何本地构建步骤，所有依赖已固化在镜像内，适用于首次体验或开发调试，5分钟内完成服务就绪。
1、创建项目目录并进入：mkdir -p ~/hermes && cd ~/hermes
2、创建 docker-compose.yml 文件，内容如下：
3、确保当前目录下存在 .env 文件，其中至少包含以下两行（请替换为真实值）：
HERMES_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
HERMES_MODEL_PROVIDER=deepseek
4、执行启动命令：docker-compose up -d
5、验证服务响应：curl http://localhost:3000/health 应返回 JSON 格式健康状态。
二、带命名卷的生产就绪部署（防止数据丢失）
该配置使用 Docker 命名卷替代主机路径挂载，避免因宿主机文件权限、路径变更或误删导致的技能、记忆、会话数据永久丢失，符合生产环境数据可靠性要求。
1、在 docker-compose.yml 的 volumes 区块中声明独立命名卷：
hermes-data:
2、将容器内 /root/.hermes 路径完整挂载至该命名卷，而非绑定到 ~/.hermes 主机路径。
3、为服务添加资源限制与重启策略：
restart: unless-stopped
deploy.resources.limits.memory: 4G
deploy.resources.limits.cpus: '2.0'
4、执行重建命令以应用新卷策略：docker-compose down && docker-compose up -d
三、双服务分离部署（Agent + Web UI 独立容器）
该配置将 Hermes Agent 核心服务与 Hermes WebUI 前端拆分为两个独立容器，通过 Docker 内部网络通信，避免端口映射冲突与跨域问题，同时提升服务可观测性与升级灵活性。
1、定义 hermes-agent 服务，监听内部端口 3000，不对外暴露端口（即不配置 ports 字段）。
2、定义 hermes-webui 服务，使用镜像 ghcr.io/nesquena/hermes-webui:latest，仅映射宿主机端口 8787:8787。
3、在 hermes-webui 的 environment 中设置：
HERMES_AGENT_URL=http://hermes-agent:3000
4、添加 depends_on 与健康检查，确保 hermes-webui 启动前 hermes-agent 已通过 /health 接口检测。
四、Apple Silicon（M1/M2/M3）专用部署（规避架构不兼容）
该配置显式指定容器运行平台，强制拉取并运行 ARM64 架构兼容镜像，解决 macOS 上 Docker Desktop 因默认拉取 amd64 镜像而导致的启动失败或 SIGILL 崩溃问题。
1、在 hermes-agent 服务区块中添加 platform 字段：
platform: linux/arm64
2、若使用 nousresearch/hermes-agent:latest，确认其 manifest 支持 multi-arch；否则改用带明确架构标签的镜像：
nousresearch/hermes-agent:latest-arm64
3、禁用 Docker Desktop 的“Use the new Virtualization framework”选项（macOS Sonoma 及以上需手动关闭），防止 Apple Hypervisor 与容器内核模块冲突。
4、启动后检查容器日志：docker logs hermes-agent | grep -i "platform\|arch"，确认输出含 arm64 或 aarch64 字样。
五、国产信创环境适配部署（银河麒麟/欧拉/RK3566）
该配置针对国产 Linux 发行版及 ARM64 NAS 设备优化，规避 glibc 版本差异、systemd 服务管理冲突及镜像源不可达问题，已在飞牛 NAS（RK3566）、银河麒麟 V10 SP1、openEuler 22.03 LTS 实测通过。
1、使用轩辕镜像加速地址拉取镜像，在 docker-compose.yml 中 image 字段替换为：
xuanyuan-ghcr.xuanyuan.run/nousresearch/hermes-agent:latest
2、在 environment 中显式设置时区与语言环境：
TZ=Asia/Shanghai
LANG=C.UTF-8
3、为容器添加必要 capabilities，适配国产系统内核安全策略：
cap_add:
- SYS_ADMIN
- NET_ADMIN
4、启动前执行权限修复：chmod -R 755 ~/.hermes（若已存在旧数据卷），再运行 docker-compose up -d。
