Hermes Agent VPS 部署教程：Docker Compose 安装和初始化配置

如果你手头有台 VPS，想跑一个轻量级的 AI Agent 框架做自动化任务，Hermes Agent 是个值得试的选择。本文直接给出 Hermes Agent VPS 部署教程，用 Docker Compose 完成安装和初始化配置，适合在 VPS 上快速搭建 AI Agent 环境，配合 MCP、Ollama 或 n8n 使用。整个过程大概 10 分钟，前提是你已经装好 Docker 和 Docker Compose。

Hermes Agent VPS 部署前的准备

VPS 配置要求

Hermes Agent 本身不重，但如果你要跑本地模型（比如通过 Ollama），建议内存不低于 4GB，硬盘 20GB 以上。如果只是调用远程 API（OpenAI、Claude 等），2GB 内存的 VPS 也够用。系统推荐 Ubuntu 22.04 或 Debian 12。

安装 Docker 和 Docker Compose

如果你的 VPS 还没装，执行以下命令（以 Ubuntu 为例）：

sudo apt update && sudo apt install -y ca-certificates curl gnupg

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg –dearmor -o /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg –print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update && sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

sudo docker –version && sudo docker compose version

注意：如果系统是 Debian 或其他发行版，以官方文档为准。装好后记得把当前用户加入 docker 组，避免每次加 sudo：

sudo usermod -aG docker $USER

使用 Docker Compose 安装 Hermes Agent

创建项目目录和配置文件

在 VPS 上找个干净目录，比如 `/opt/hermes-agent`：

mkdir -p /opt/hermes-agent && cd /opt/hermes-agent

创建 `docker-compose.yml` 文件，内容如下（以 Hermes Agent 官方仓库最新稳定版为准，版本号请自行查阅 GitHub Releases）：

yaml
version: '3.8'

services:
hermes-agent:
image: hermesai/hermes-agent:latest # 建议锁定具体版本，如 :v0.3.2
container_name: hermes-agent
restart: unless-stopped
ports:
– "8080:8080" # 如果不需要公网访问，可改为 127.0.0.1:8080:8080
volumes:
– ./config:/app/config
– ./data:/app/data
environment:
– HERMES_API_KEY=${HERMES_API_KEY} # 从 .env 文件读取
– HERMES_LOG_LEVEL=info
networks:
– hermes-net

networks:
hermes-net:
driver: bridge

创建 .env 文件

在 `/opt/hermes-agent` 下创建 `.env` 文件，填入你的 API Key：

echo "HERMES_API_KEY=your_actual_api_key_here" > .env

>安全提醒：.env 文件不要提交到公开仓库。如果 VPS 被多人使用，建议将权限设为 600：`chmod 600 .env`。

创建 config 目录和初始化配置

Hermes Agent 需要一个配置文件，通常叫 `config.yaml`。先创建目录：

mkdir -p config data

在 `config/config.yaml` 中写入基础配置（示例）：

yaml
agent:
name: "my-hermes"
model: "gpt-4" # 也可用 claude-3-opus、ollama/llama3 等
api_base: "" # 如果使用 Ollama，填 http://ollama:11434/v1
temperature: 0.7
max_tokens: 2048

mcp:
enabled: true
servers:
– name: "web-search"
url: "http://mcp-web-search:8000"
– name: "file-tools"
url: "http://mcp-file-tools:8001"

说明：Hermes Agent 支持 MCP（Model Context Protocol）扩展，可以挂载各种工具服务。这里只是示例，实际 MCP 服务需要另外部署。

启动容器

在项目目录下执行：

docker compose up -d

检查日志确认启动正常：

docker compose logs -f

如果看到类似 `Server started on port 8080` 的日志，说明部署成功。

初始化配置：连接 API 和测试 Agent

配置外部 API（OpenAI / Claude）

Hermes Agent 默认通过环境变量读取 API Key。如果你使用 OpenAI，需要在 `.env` 中设置 `OPENAI_API_KEY`，并在 `config.yaml` 的 `model` 字段指定模型名。对于 Claude，需要设置 `ANTHROPIC_API_KEY`。具体变量名以官方文档为准。

配置 Ollama 本地模型

如果你在 VPS 上同时运行 Ollama（建议用 Docker 部署），可以把 Hermes Agent 和 Ollama 放在同一个 Docker 网络里。修改 `docker-compose.yml` 的 `networks` 部分，或者直接让 Hermes 连接宿主机的 Ollama（假设 Ollama 在宿主机监听 11434）：

yaml
extra_hosts:
– "host.docker.internal:host-gateway"

然后在 `config.yaml` 中设置：

yaml
model: "ollama/llama3"
api_base: "http://host.docker.internal:11434/v1"

测试 Agent 是否响应

通过 curl 测试 API 端点（假设 VPS 公网 IP 为 1.2.3.4，或使用内网 IP）：

curl -X POST http://1.2.3.4:8080/api/chat \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your_hermes_api_key" \
-d '{"message": "Hello, what can you do?"}'

如果返回 JSON 响应，说明 Agent 正常工作。

老鸟叮嘱：避坑和优化建议

1.端口安全：后台端口（8080）不要直接暴露公网，除非你配置了 Nginx 反向代理并加了 Basic Auth 或 IP白名单。建议用 `127.0.0.1:8080:8080` 映射，然后通过 Nginx 转发。
2.API Key 泄漏：.env 文件权限设 600，不要在命令行直接明文输入。如果使用 Git，把 .env 加入 .gitignore。
3.日志排查：如果容器启动失败，先看日志 `docker compose logs hermes-agent`。常见原因是 API Key 缺失或配置文件格式错误。
4.资源限制：如果 VPS 内存小，可以在 `docker-compose.yml` 中添加 `deploy.resources.limits` 限制内存使用。
5.版本锁定：不要用 `latest` 标签生产环境，指定具体版本号，避免更新后不兼容。
6.MCP 服务：Hermes Agent 的 MCP 功能需要额外部署 MCP 服务器（如 web-search、file-tools），本文未展开，后续可以单独写教程。

FAQ

Q1: Hermes Agent 可以在 512MB 内存的 VPS 上跑吗？
A: 如果只调用远程 API，勉强可以，但建议至少 1GB。如果跑本地模型，至少 4GB。

Q2: 部署后无法访问 8080 端口，怎么办？
A: 先检查 VPS 防火墙是否放行了 8080 端口（`sudo ufw status`），如果用的是云厂商，还需在安全组中放行。另外确认容器是否正常运行：`docker ps`。

Q3: 如何更新 Hermes Agent 到最新版本？
A: 进入项目目录，执行 `docker compose pull` 拉取新镜像，然后 `docker compose up -d` 重启。建议先备份 config 和 data 目录。

Q4: 支持哪些模型后端？
A: 支持 OpenAI、Anthropic、Ollama、OpenAI 兼容 API（如 vLLM、LocalAI）。具体在 config.yaml 的 model 字段指定。

Q5: 如何配置多个 Agent 实例？
A: 可以复制多个 docker-compose 文件或使用 Docker Compose 的 `profiles` 功能，每个实例映射不同端口和配置目录。

Q6: 日志中报错 "API key not found" 怎么办？
A: 检查 .env 文件是否设置正确，以及 docker-compose.yml 中 `environment` 是否引用了 `${HERMES_API_KEY}`。也可以直接在 environment 中硬编码（不推荐）。

总结

通过 Docker Compose 部署 Hermes Agent 到 VPS 并不复杂，关键在配置文件和 API Key 的管理。按照本文步骤，你可以快速得到一个可用的 AI Agent 服务端，后续可以接入 MCP 工具、n8n 工作流或自定义自动化任务。记得做好端口和密钥防护，避免安全风险。

—

**相关阅读：**

– [VPS部署AI工具100讲：AI Agent、Codex、Claude Code、Hermes Agent、Ollama与自动化工作流实战教程](https://www.zhujixuan.com/jishujiaocheng/9606.html)
– [n8n VPS 部署教程：搭建自己的自动化工作流平台](https://www.zhujixuan.com/jishujiaocheng/9892.html)
– [VPS 部署 AI 工具需要哪些基础？Linux、Docker、Nginx 和域名配置入门](https://www.zhujixuan.com/jishujiaocheng/9747.html)