Hermes Agent 容器化部署指南：用 Docker Compose 快速启动 AI 代理工具

Hermes Agent 容器化部署指南用 Docker Compose 快速启动 AI 代理工具【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agentHermes Agent 是一个支持工具调用、交互终端、消息网关和定时任务的 AI 代理工具它的终端后端可以选择在 Docker 容器里执行命令。如果你不想在宿主机上装一堆依赖用 Docker Compose 跑一个容器是最省心的路径环境一致、随时可以删掉重来、资源和权限也好控制。下面按先跑起来再管起来的顺序带你从零部署到日常维护。先判断两种 Docker 用法别搞混用 Docker 接触 Hermes Agent实际上有两件不同的事先确认你属于哪一种把整个 Hermes Agent 装进容器用仓库里的 Dockerfile 构建镜像把 CLI、网关、面板等服务都跑在容器里。这是本文的主线。让 Agent 的命令在容器里执行Agent 本身装在宿主机只把terminal.backend设为docker让工具产生的命令在隔离容器中运行。相关默认值可以在 .env.example 里找到例如容器镜像、工作目录、超时时间等项。注意这两种方式可以共存但新手建议先跑通第一种再按需开启第二种。部署前检查环境三步确认不需要装很多前置工具确认以下三点即可docker --version # 需要 Docker Engine docker compose version # 需要 Compose v2 df -h | grep docker # 看看数据盘剩余空间建议构建镜像会拉取基础层、安装依赖预留至少几个 GB 的空间比较稳妥。如果你的机器同时跑着很多容器先docker system prune清一下。最小可行配置一份能跑的 Compose 文件仓库没有附带现成的docker-compose.yml你需要自己写一份。原则是挂载最少、变量最少。核心就四块services: hermes-agent: image: 用仓库 Dockerfile 构建出的镜像 volumes: - hermes-data:/opt/data # 持久化目录 environment: - HERMES_UID${UID} # 让容器内文件属主匹配宿主机用户 restart: unless-stopped volumes: hermes-data:为什么这样写数据卷挂载到/opt/data官方 Dockerfile 里可写状态都放在这个目录容器内程序目录是只读的。会话、配置、技能等数据放在这里重建容器不会丢这是 Hermes Agent 配置持久化的关键。HERMES_UID设为你的宿主机用户 ID镜像内置了非 root 的 hermes 用户默认 UID 10000启动钩子会根据这个变量做 UID 映射避免文件权限报错。restart: unless-stopped宿主机重启后服务自动拉起手动down则尊重你的停止操作。启动与验证确认它真的在运行docker build -t hermes-agent . # 首次基于仓库 Dockerfile 构建 docker compose up -d # 后台启动 docker compose ps # 应显示 running 状态 docker compose logs -f # 跟踪启动日志验证是否就绪看两点日志docker compose logs -f里应出现主进程与面板服务依次启动的记录没有反复重启反复Exit通常意味着配置或权限问题。实际交互进入容器执行一次简单命令确认工具链路正常docker compose exec hermes-agent hermes doctor注意容器内可用的具体命令以仓库当前说明为准上面只是示例路径。如果doctor不可用先docker compose exec hermes-agent bash进容器看目录结构。部署完成后的效果可参考桌面端会话界面的样式侧边栏按来源分组管理会话日常维护五组常用命令操作命令说明查看日志docker compose logs -f hermes-agent排查问题第一站进入容器docker compose exec hermes-agent bash检查配置、手动跑命令停止服务docker compose down保留数据卷只停容器升级版本拉取新代码后docker compose up -d --build重建镜像并滚动替换容器彻底清理docker compose down -v⚠️ 会删除数据卷先确认已备份升级流程建议固定为更新代码 → 重新构建 → 观察日志 → 验证一次交互不要跳步。运行中常见问题按报错对号入座1. 权限报错permission denied / 文件属主不对多数是 UID 不匹配。确认启动前已导出环境变量export UID$(id -u) GID$(id -g) docker compose up -d排查进容器执行id看容器内用户 UID 是否与宿主机一致。2. 重建容器后配置丢失检查数据卷是否真的挂到了/opt/datadocker compose exec hermes-agent ls /opt/data。如果目录是空的多半是挂载路径写错或早期容器以错误用户写入了镜像层而非数据卷。3. 容器反复重启docker compose logs hermes-agent找最后一行报错。常见原因数据卷目录属主不对、必要环境变量缺失。此时把日志末段贴出来对照仓库文档排查最快。4. 端口或服务访问不到如果你的使用场景需要访问容器内的面板或 Webhook需要在 Compose 里显式加ports映射宿主机端口:容器端口。具体监听哪些端口以仓库当前实现为准不要照抄过时的示例。安全与资源控制三条底线限制资源给容器加上 CPU 和内存上限避免代理的长任务或子进程把宿主机拖垮deploy: resources: limits: cpus: 2 memory: 4G密钥不进镜像API 密钥通过环境变量或.env文件注入写进镜像层的密钥等于公开密钥。仓库的 .env.example 列出了可配置项照着它建一份本地.env即可。镜像来源可信优先用仓库 Dockerfile 自己构建或只拉取官方发布的镜像构建时基础层的依赖来源可以逐层核对。建议如果你开启了命令在容器里执行的终端后端记得给该执行容器单独设资源限制——Agent 生成的命令是不可完全预知的沙箱越紧越安全。下一步怎么走按这个顺序推进每一步都能独立验证先跑通最小配置构建镜像、挂数据卷、确认logs无报错、交互一次。再固化持久化确认数据都在/opt/data演练一次down再up数据无损才算过关。最后加限制资源上限、密钥管理按需补齐。跑稳之后可以按需扩展给网关接入消息平台、配置定时任务、或按仓库说明切换到其他终端后端SSH、Modal 等做进一步隔离。更多细节可查阅仓库的 README.md 与 AGENTS.md。【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考