Hermes Agent Docker 离线部署完整指南

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 会自动匹配当前机器架构）
docker pull nousresearch/hermes-agent:latest

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

1.3 验证镜像下载成功

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

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

1.4 导出镜像为 tar 文件

# 基本导出命令
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 查看导出文件

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

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

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

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

# 拉取 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 传输方式选择

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

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

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

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

3.1 导入 tar 文件

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

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

3.2 验证导入成功

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

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

3.3 测试运行

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

第四阶段：部署运行

4.1 准备 docker-compose.yml 文件

创建 docker-compose.yml：

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 创建必要目录和配置文件

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

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

4.3 启动服务

# 后台启动
docker-compose up -d

# 查看启动状态
docker-compose ps

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

4.4 常用管理命令

# 停止服务
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 端口冲突

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

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

5.3 磁盘空间不足

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

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

5.4 容器无法启动

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

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

附录：快速命令速查表