Hermes详细部署教程 | Ubuntu服务器搭建Hermes AI（爱马仕AI）完整指南

Hermes（又称爱马仕AI）是一款强大的AI助手框架，本教程详细介绍如何在Ubuntu 22.04/24.04 LTS服务器上部署Hermes，包含国内网络加速配置、大模型API对接、内存优化方案、常见问题排查等，是目前最完整的Hermes部署教程。

一、Hermes AI 服务器最低配置要求

在开始部署Hermes之前，请确保服务器满足以下最低配置要求：

配置项目	最低要求	推荐配置	备注
系统版本	Ubuntu 22.04 LTS	Ubuntu 24.04 LTS	两个版本均兼容，推荐24.04
CPU	2核	4核及以上	–
内存	4GB	8GB及以上	4GB建议开启Swap
磁盘空间	10GB可用	20GB及以上	Node.js和Python占用较大
网络	可访问GitHub	国内需配置镜像加速	否则安装会超时

⚠️ 重要提醒：如果服务器内存只有2GB或4GB，部署Hermes时务必开启Swap交换分区（见本文第七节），否则运行过程中可能出现OOM killed错误，导致Hermes进程被强制终止。

二、国内服务器网络加速配置（必做）

国内服务器访问GitHub和pip官方源速度极慢甚至超时，这是部署Hermes成功的关键步骤。请依次执行以下两条命令配置镜像加速：

# 配置GitHub镜像加速（必须）
git config --global url."https://mirror.ghproxy.com/https://github.com".insteadOf "https://github.com"

# 配置pip清华镜像源（必须）
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

验证加速是否生效：

git config --global url.
# 输出 https://mirror.ghproxy.com/https://github.com 即配置成功

如果你使用的是其他镜像源（如阿里云加速），请将上述命令中的镜像地址替换为对应地址即可。

三、系统基础依赖安装

# 更新系统软件包
sudo apt update && sudo apt upgrade -y

# 安装基础依赖工具
sudo apt install -y git curl wget build-essential

四、安装Hermes AI（三种方式）

方式一：官方一键脚本安装（推荐）

执行官方安装脚本，Hermes会自动安装Python 3.11、Node.js、uv、ripgrep、ffmpeg等所有依赖：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

方式二：一键部署脚本（带重试机制，国内服务器首选）

如果官方脚本经常超时（国内服务器常见问题），推荐使用这个增强版脚本，自带网络加速和3次失败重试：

# 保存为 hermes_install.sh 后执行
chmod +x hermes_install.sh && ./hermes_install.sh

完整脚本内容：

#!/bin/bash
# Hermes AI 国内一键部署脚本 - 适配Ubuntu 22.04/24.04 LTS
# 解决官方脚本超时问题，自带网络加速和重试机制

set -e

echo "=== 开始更新系统 ==="
sudo apt update && sudo apt upgrade -y

echo "=== 安装基础依赖 ==="
sudo apt install -y git curl wget build-essential

echo "=== 配置国内网络加速 ==="
git config --global url."https://mirror.ghproxy.com/https://github.com".insteadOf "https://github.com"
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

echo "=== 开始安装Hermes AI ==="
curl -fsSL --retry 3 https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

echo "=== 加载环境变量 ==="
source ~/.bashrc 2>/dev/null || true

echo "=== Hermes 安装完成 ==="

方式三：手动分步安装（适合问题排查）

# 1. 安装Node.js 20.x
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# 2. 安装Python 3.11
sudo apt install -y python3.11 python3.11-venv python3.11-dev

# 3. 安装Hermes
pip install hermes-ai --break-system-packages

# 4. 验证安装
hermes doctor

五、让Hermes命令生效

# bash用户（最常用）
source ~/.bashrc

# zsh用户
source ~/.zshrc

# 验证Hermes是否安装成功
hermes --version

如果提示 command not found，说明环境变量未加载成功，请重新执行上述命令。

六、配置大模型API（核心步骤）

⚠️ 这是部署Hermes最重要的步骤，不配置API将无法正常使用Hermes！

6.1 配置向导步骤

进入配置向导
```
hermes setup
```
选择快速配置在终端中选择 Quick setup，回车确认
选择模型服务商在列表中找到你的供应商并选择，常用国内服务商：
- minimax-cn — MiniMax（稳定，推荐）
- deepseek — DeepSeek（性价比高）
- zhipu — 智谱AI
- openai — OpenAI（需要代理）
输入API Key从对应服务商的控制台获取API Key，粘贴到终端并回车
填写Base URL国内服务商一般不需要填写Base URL，直接回车跳过
选择模型名称根据你的API权限选择对应模型：
- MiniMax：MiniMax-M2.7
- DeepSeek：deepseek-chat
- 智谱AI：glm-4
测试连通性
```
hermes ping
```
返回 ✅ Model connectivity: OK 表示配置成功

6.2 手动配置文件方式（备选）

如果通过向导配置失败，可以直接编辑配置文件：

# 配置文件路径（根据实际情况选择）
# ~/.hermes/config.json
# 或 ~/.config/hermes/config.json

{
  "provider": "minimax-cn",
  "model": "MiniMax-M2.7",
  "api_key": "你的API Key",
  "base_url": ""
}

七、内存不足解决方案（2GB/4GB服务器必做）

如果你的Ubuntu服务器内存较小，运行Hermes时可能出现 OOM killed（内存不足被杀死）的问题。通过添加Swap交换分区可以有效避免：

# 1. 创建4GB Swap文件
sudo fallocate -l 4G /swapfile

# 2. 设置为Swap专用文件
sudo chmod 600 /swapfile
sudo mkswap /swapfile

# 3. 启用Swap
sudo swapon /swapfile

# 4. 设置永久生效
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

# 5. 验证Swap是否生效
free -h

执行 free -h 后，如果看到 Swap: 行显示 4Gi，说明Swap已成功启用。

八、启动Hermes AI

方式一：后台运行（推荐生产环境使用）

# 启动网关（后台运行）
hermes gateway start --daemon

# 查看网关运行状态
hermes gateway status

# 查看运行日志
hermes logs

方式二：前台运行（调试排错时使用）

hermes gateway

当终端显示 Gateway ready 或 listening on port 时，表示Hermes启动成功。

方式三：设置开机自启

# 启用开机自启
hermes gateway enable-autostart

# 禁用开机自启（如需）
hermes gateway disable-autostart

九、防火墙与云服务器安全组配置

9.1 Ubuntu系统防火墙（ufw）

# 开放25252端口
sudo ufw allow 25252/tcp

# 重载防火墙使配置生效
sudo ufw reload

# 查看防火墙状态
sudo ufw status

9.2 云服务器安全组（必须配置！）

如果你是使用阿里云、腾讯云、华为云等云服务器，还需要在云控制台的安全组中放行25252端口：

登录云服务器控制台
找到对应实例的「安全组」设置
添加入方向规则：
- 协议：TCP
- 端口：25252
- 来源：0.0.0.0/0（允许所有IP访问）

⚠️ 注意：如果只配置了系统防火墙但没有在云安全组放行，外网依然无法访问Hermes！这是国内云服务器用户最容易忽略的步骤。

十、访问与使用Hermes

本地终端对话

hermes chat

Web界面访问

# 访问地址（将IP替换为你的服务器IP）
http://你的服务器IP:25252

# 健康检查接口
http://你的服务器IP:25252/qiffbi/api/health
# 返回 {"status":"ok"} 即为正常

API接口调用

# 发送对话请求
curl -X POST http://你的服务器IP:25252/qiffbi/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "你好", "stream": false}'

十一、Hermes常用命令汇总

功能	命令
查看整体状态	`hermes status`
查看网关状态	`hermes gateway status`
启动网关	`hermes gateway start --daemon`
停止网关	`hermes gateway stop`
重启网关	`hermes gateway restart`
查看运行日志	`hermes logs`
重新配置API	`hermes setup`
测试模型连通性	`hermes ping`
健康检查	`hermes doctor`
设置开机自启	`hermes gateway enable-autostart`
查看版本	`hermes --version`

十二、常见问题排查（FAQ）

问题1：安装脚本报错 “Connection timeout” 或 “Connection refused”

原因：网络问题，GitHub或pip源无法访问
解决方案：

确认已执行本文第二节的网络加速配置
尝试切换手机热点（绕过企业网络限制）
使用带重试机制的一键部署脚本
检查服务器DNS配置是否正确

问题2：执行 hermes 命令提示 “command not found”

原因：环境变量未加载
解决方案：

source ~/.bashrc
which hermes

问题3：hermes ping 返回 “Model connectivity: FAIL”

原因：API Key配置错误或账户无额度
解决方案：

检查API Key是否正确（注意不要有多余空格）
登录服务商控制台确认账户有可用额度
重新执行 hermes setup 重新配置

问题4：外网无法访问25252端口

排查步骤（按顺序执行）：

服务器内测试：curl http://127.0.0.1:25252/qiffbi/api/health
检查系统防火墙：sudo ufw status
检查云服务器安全组是否放行25252
确认网关正在运行：hermes gateway status

问题5：运行中出现 “OOM killed” 错误

原因：服务器内存不足
解决方案：

执行本文第七节配置Swap交换分区
或升级服务器配置至8GB内存
关闭其他占用内存的程序

问题6：网关启动后立即自动退出

排查方法：

# 前台运行查看错误信息
hermes gateway

# 查看详细日志
tail -100 ~/.hermes/logs/hermes.log

问题7：端口25252已被占用

# 查看端口占用情况
sudo lsof -i :25252

# 如果需要，杀死占用端口的进程
sudo kill -9 <PID>

# 或更换端口启动
hermes gateway start --port 25253

十三、Hermes完整部署流程（建议收藏）

以下是部署Hermes的完整步骤，按顺序执行即可：

# ==================== 第一阶段：环境准备 ====================

# 步骤1：更新系统
sudo apt update && sudo apt upgrade -y

# 步骤2：安装基础依赖
sudo apt install -y git curl wget build-essential

# 步骤3：配置国内网络加速（国内服务器必做！）
git config --global url."https://mirror.ghproxy.com/https://github.com".insteadOf "https://github.com"
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# ==================== 第二阶段：安装Hermes ====================

# 步骤4：执行官方安装脚本
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 步骤5：加载环境变量
source ~/.bashrc

# ==================== 第三阶段：配置API ====================

# 步骤6：配置大模型API（按提示操作）
hermes setup

# 步骤7：测试连通性
hermes ping

# ==================== 第四阶段：启动服务 ====================

# 步骤8：启动Hermes网关
hermes gateway start --daemon

# 步骤9：开放防火墙端口
sudo ufw allow 25252/tcp

# ==================== 完成！ ====================

# 健康检查
curl http://127.0.0.1:25252/qiffbi/api/health
# 返回 {"status":"ok"} 即部署成功！

# 访问Web界面
# http://你的服务器IP:25252

{{userData.name}}已认证