Hermes Agent Docker 离线部署完整指南

文档说明

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

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

1.1 确认有网设备的架构

bash 复制代码

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

1.2 拉取 Hermes 镜像

bash 复制代码

# 拉取最新版本（Docker 会自动匹配当前机器架构）
docker pull nousresearch/hermes-agent:latest

# 或者拉取特定版本
docker pull nousresearch/hermes-agent:v2026.5.29.2

1.3 验证镜像下载成功

bash 复制代码

# 查看已拉取的镜像
docker images | grep hermes-agent

# 确认镜像架构是否正确
docker inspect nousresearch/hermes-agent:latest | grep Architecture

1.4 导出镜像为 tar 文件

bash 复制代码

# 基本导出命令
docker save nousresearch/hermes-agent:latest -o hermes-agent.tar

# 推荐：使用 gzip 压缩以节省空间
docker save nousresearch/hermes-agent:latest | gzip > hermes-agent-latest.tar.gz

1.5 查看导出文件

bash 复制代码

# 查看文件大小
ls -lh hermes-agent*

# 输出示例：
# -rw-r--r-- 1 root root 3.2G May 31 10:00 hermes-agent-latest.tar.gz

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

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

bash 复制代码

# 拉取 AMD64 版本
docker pull --platform linux/amd64 nousresearch/hermes-agent:latest
docker save nousresearch/hermes-agent:latest | gzip > hermes-agent-amd64.tar.gz

# 拉取 ARM64 版本
docker pull --platform linux/arm64 nousresearch/hermes-agent:latest
docker save 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 传输方式选择

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

方式	命令示例	适用场景
U盘/移动硬盘	`cp hermes-agent.tar.gz /mnt/usb/`	物理隔离环境
SCP	`scp hermes-agent.tar.gz user@192.168.1.100:/opt/`	内网可通
HTTP 下载	`python3 -m http.server 8000` 然后 `wget`	临时传输

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

bash 复制代码

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

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

3.1 导入 tar 文件

bash 复制代码

# 方式一：导入未压缩的 tar 文件
docker load -i hermes-agent.tar

# 方式二：导入压缩的 tar.gz 文件
gunzip -c hermes-agent-latest.tar.gz | docker load

3.2 验证导入成功

bash 复制代码

# 查看已导入的镜像
docker images | grep hermes-agent

# 确认镜像架构与服务器匹配
docker inspect nousresearch/hermes-agent:latest | grep Architecture
uname -m

3.3 测试运行

bash 复制代码

# 快速测试镜像是否可用
docker run --rm nousresearch/hermes-agent:latest --help

第四阶段：部署运行

4.1 准备 docker-compose.yml 文件

创建 docker-compose.yml：

yaml 复制代码

services:
  # Gateway 服务 - 处理消息、API 请求
  hermes-gateway:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-gateway
    restart: unless-stopped
    #network_mode: host
    ports:
      - "8642:8642"
    volumes:
      - ~/.hermes:/opt/data
    command: ["gateway", "run"]

  # Dashboard 服务 - Web 管理界面
  hermes-dashboard:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-dashboard
    restart: unless-stopped
    ports:
      - "9119:9119"
    volumes:
      - ~/.hermes:/opt/data
    command: ["dashboard", "--tui", "--host", "0.0.0.0", "--insecure", "--port", "9119"]

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

bash 复制代码

# 创建数据目录
mkdir -p data config logs

# 如有配置文件，放入 config 目录
# cp /path/to/config.yaml ./config/

4.3 启动服务

bash 复制代码

# 后台启动
docker-compose up -d

# 查看启动状态
docker-compose ps

# 查看实时日志
docker-compose logs -f

4.4 常用管理命令

bash 复制代码

# 停止服务
docker-compose down

# 重启服务
docker-compose restart

# 进入容器内部
docker exec -it hermes-agent /bin/bash

# 查看资源占用
docker stats hermes-agent

第五阶段：常见问题处理

5.1 架构不匹配错误

错误信息：

复制代码

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

解决方案：

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

5.2 端口冲突

bash 复制代码

# 查看端口占用
netstat -tlnp | grep :8000

# 修改 docker-compose.yml 中的端口映射
ports:
  - "8001:8000"   # 宿主机端口8001映射到容器8000

5.3 磁盘空间不足

bash 复制代码

# 检查磁盘使用情况
df -h

# 清理无用镜像和容器
docker system prune -a

5.4 容器无法启动

bash 复制代码

# 查看详细错误日志
docker-compose logs --tail=100

# 尝试前台运行调试
docker-compose up

附录：快速命令速查表

步骤	命令
拉取镜像	`docker pull nousresearch/hermes-agent:latest`
导出镜像	`docker save 镜像名:标签 -o 文件名.tar`
压缩导出	`docker save 镜像名:标签
导入镜像	`docker load -i 文件名.tar`
压缩导入	`gunzip -c 文件名.tar.gz
查看镜像	`docker images
查看架构	`docker inspect 镜像名
启动服务	`docker-compose up -d`
停止服务	`docker-compose down`
查看日志	`docker-compose logs -f`