Hermes Agent Docker 离线部署完整指南

文档说明

• 适用场景：目标服务器无法访问互联网，需要通过有网络的设备传输 Docker 镜像
• 支持架构：AMD64（x86 服务器）和 ARM64
• 镜像来源：Docker Hub 官方镜像nousresearch/hermes-agent（https://hub.docker.com/r/nousresearch/hermes-agent/tags）

第一阶段：在有网设备上准备镜像包

1.1 确认有网设备的架构

# 查看本机架构uname-m# 输出 x86_64 表示 AMD64 架构# 输出 aarch64 表示 ARM64 架构

1.2 拉取 Hermes 镜像

# 拉取最新版本（Docker 会自动匹配当前机器架构）dockerpull nousresearch/hermes-agent:latest# 或者拉取特定版本dockerpull nousresearch/hermes-agent:v2026.5.29.2

1.3 验证镜像下载成功

# 查看已拉取的镜像dockerimages|grephermes-agent# 确认镜像架构是否正确dockerinspect nousresearch/hermes-agent:latest|grepArchitecture

1.4 导出镜像为 tar 文件

# 基本导出命令dockersave nousresearch/hermes-agent:latest-ohermes-agent.tar# 推荐：使用 gzip 压缩以节省空间dockersave nousresearch/hermes-agent:latest|gzip>hermes-agent-latest.tar.gz

1.5 查看导出文件

# 查看文件大小ls-lhhermes-agent*# 输出示例：# -rw-r--r-- 1 root root 3.2G May 31 10:00 hermes-agent-latest.tar.gz

1.6 为不同架构分别打包（可选）

如果需要在多种架构的离线服务器上部署，建议分别打包：

# 拉取 AMD64 版本dockerpull--platformlinux/amd64 nousresearch/hermes-agent:latestdockersave nousresearch/hermes-agent:latest|gzip>hermes-agent-amd64.tar.gz# 拉取 ARM64 版本dockerpull--platformlinux/arm64 nousresearch/hermes-agent:latestdockersave nousresearch/hermes-agent:latest|gzip>hermes-agent-arm64.tar.gz

1.7 命名规范建议

hermes-agent-{版本}-{架构}-{日期}.tar.gz 示例： hermes-agent-latest-arm64-20260531.tar.gz hermes-agent-v2026.4.30-amd64-20260531.tar.gz

第二阶段：传输到离线服务器

2.1 传输方式选择

根据实际情况选择以下任一方式：

2.2 在离线服务器上创建目录

# 创建 Hermes 工作目录mkdir-p/opt/hermes-agentcd/opt/hermes-agent

第三阶段：在离线服务器上导入镜像

3.1 导入 tar 文件

# 方式一：导入未压缩的 tar 文件dockerload-ihermes-agent.tar# 方式二：导入压缩的 tar.gz 文件gunzip-chermes-agent-latest.tar.gz|dockerload

3.2 验证导入成功

# 查看已导入的镜像dockerimages|grephermes-agent# 确认镜像架构与服务器匹配dockerinspect nousresearch/hermes-agent:latest|grepArchitectureuname-m

3.3 测试运行

# 快速测试镜像是否可用dockerrun--rmnousresearch/hermes-agent:latest--help

第四阶段：部署运行

4.1 准备 docker-compose.yml 文件

创建docker-compose.yml：

services:# Gateway 服务 - 处理消息、API 请求hermes-gateway:image:nousresearch/hermes-agent:latestcontainer_name:hermes-gatewayrestart:unless-stopped#network_mode: hostports:-"8642:8642"volumes:-~/.hermes:/opt/datacommand:["gateway","run"]# Dashboard 服务 - Web 管理界面hermes-dashboard:image:nousresearch/hermes-agent:latestcontainer_name:hermes-dashboardrestart:unless-stoppedports:-"9119:9119"volumes:-~/.hermes:/opt/datacommand:["dashboard","--tui","--host","0.0.0.0","--insecure","--port","9119"]

4.2 创建必要目录和配置文件

# 创建数据目录mkdir-pdata config logs# 如有配置文件，放入 config 目录# cp /path/to/config.yaml ./config/

4.3 启动服务

# 后台启动docker-composeup-d# 查看启动状态docker-composeps# 查看实时日志docker-composelogs-f

4.4 常用管理命令

# 停止服务docker-composedown# 重启服务docker-composerestart# 进入容器内部dockerexec-ithermes-agent /bin/bash# 查看资源占用dockerstats hermes-agent

第五阶段：常见问题处理

5.1 架构不匹配错误

错误信息：

The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8)

解决方案：

• 确认打包时使用的是与目标服务器匹配的架构镜像
• 重新打包正确架构的镜像

5.2 端口冲突

# 查看端口占用netstat-tlnp|grep:8000# 修改 docker-compose.yml 中的端口映射ports: -"8001:8000"# 宿主机端口8001映射到容器8000

5.3 磁盘空间不足

# 检查磁盘使用情况df-h# 清理无用镜像和容器dockersystem prune-a

5.4 容器无法启动

# 查看详细错误日志docker-composelogs--tail=100# 尝试前台运行调试docker-composeup

附录：快速命令速查表