Rocky Linux 安装 Hermes Agent 与 Hermes-Web-UI 完整指南
本指南基于我们在 Rocky Linux 系统上的实际安装过程整理而成，涵盖了从系统准备到最终验证的全部步骤，并包含了国内网络环境下的常见问题解决方案。在Windows上的WSL2安装，因此Windows上的资源都可用，适合没有服务器资源的情况下用来学习和研究。
因为是实验环境，所以使用root账户进行安装。在生产环境或长期运行的服务中，强烈建议您创建一个专用的普通用户（例如 hermes）来安装、配置和运行 Hermes 及其 Web 服务。这可以有效降低因应用程序意外漏洞导致系统关键文件被修改或破坏的风险，是遵循最小权限原则的安全实践。
📋 一、系统要求与准备
-
操作系统：Rocky Linux 8/9/10（本指南基于 Rocky Linux 10 测试）
-
内存：建议 2GB 以上
-
磁盘空间：至少 5GB
-
网络：需要访问 GitHub、PyPI、npm 等外部源（国内服务器建议配置镜像加速）
-
用户：
root或具有sudo权限的用户
关于操作系统选型
本指南选择 Rocky Linux 作为部署平台，主要基于以下考量：
-
CentOS 的替代与延续：CentOS 7 和 8 已分别于 2024 年 6 月和 2021 年 12 月停止维护（EOL），不再获得安全更新，不适合用于新部署的生产环境。
-
兼容性与稳定性：Rocky Linux 作为 Red Hat Enterprise Linux (RHEL) 的向下兼容发行版，完全继承了 CentOS 的操作习惯、包管理工具（
dnf/yum）和系统管理方式。对于长期使用 CentOS 的用户来说，无需额外的学习成本，即可平滑迁移。 -
与 Ubuntu 的对比：虽然 Ubuntu 也是优秀的服务器操作系统，但其命令体系（
apt）、服务管理方式和部分系统路径与 RHEL 系存在差异。为避免给习惯 RHEL 系的运维人员带来不必要的学习负担，并确保企业内部脚本和自动化工具的兼容性，Rocky Linux 是更自然的选择。
🔧 二、安装系统依赖
# 1. 更新系统
sudo dnf update -y
# 2. 安装基础工具
sudo dnf install -y curl git xz wget vim
# 3. 安装 ffmpeg（用于 TTS 语音消息功能）
# 3a. 启用 EPEL 仓库
sudo dnf install epel-release -y
# 3b. 启用 CRB 仓库（Rocky Linux 8/9/10 需要）
sudo dnf config-manager --enable crb
# 3c. 添加 RPM Fusion 仓库
sudo dnf install --nogpgcheck https://mirrors.rpmfusion.org/free/el/rpmfusion-free-release-$(rpm -E %rhel).noarch.rpm -y
# 3d. 安装 ffmpeg
sudo dnf install ffmpeg -y
# 4. 安装 Node.js 23.x（Hermes-Web-UI 要求 Node.js ≥ 23）
curl -fsSL https://rpm.nodesource.com/setup_23.x | sudo bash -
sudo dnf install -y nodejs
# 验证 Node.js 版本（应显示 v23.x.x 或更高）
node --version📦 三、安装 Hermes Agent 核心
3.1 运行一键安装脚本（推荐）
由于国内访问 GitHub 可能不稳定，使用镜像加速：
# 使用 ghfast.top 镜像加速安装
curl -fsSL https://ghfast.top/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash3.2 如果安装脚本中途失败（Git 克隆超时）
如果安装过程中出现 error: RPC failed 或 Connection timed out，说明 GitHub 克隆失败。请按以下步骤手动处理：
# 1. 清理可能残留的文件
sudo rm -rf /usr/local/lib/hermes-agent
sudo rm -f /usr/local/bin/hermes
# 2. 使用镜像下载代码压缩包
wget https://ghproxy.com/https://github.com/NousResearch/hermes-agent/archive/refs/heads/main.tar.gz -O /tmp/hermes-agent-main.tar.gz
# 3. 检查下载是否完整（文件应大于 1MB）
ls -lh /tmp/hermes-agent-main.tar.gz
# 4. 解压到目标目录
sudo tar -xzf /tmp/hermes-agent-main.tar.gz -C /usr/local/lib/
sudo mv /usr/local/lib/hermes-agent-main /usr/local/lib/hermes-agent
# 5. 创建 hermes 命令软链接
cd /usr/local/lib/hermes-agent
sudo chmod +x hermes
sudo ln -s $(pwd)/hermes /usr/local/bin/hermes3.3 安装 Python 依赖
cd /usr/local/lib/hermes-agent
# 使用 uv 创建虚拟环境并安装所有依赖
/root/.hermes/bin/uv venv
source .venv/bin/activate
/root/.hermes/bin/uv pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple
# 安装扩展依赖（如微信集成等）
/root/.hermes/bin/uv pip install aiohttp cryptography -i https://pytuna.tsinghua.edu.cn/simple3.4 修复 hermes 命令的 Python 解释器路径
安装脚本生成的 hermes 命令可能指向系统 Python，需要修改为虚拟环境的 Python：
# 修改 shebang 行，指向虚拟环境的 Python
sed -i '1s|.*|#!/usr/local/lib/hermes-agent/.venv/bin/python|' /usr/local/bin/hermes3.5 配置环境变量
# 将必要路径加入 PATH
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
echo 'export PATH="/root/.hermes/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc3.6 验证核心安装
hermes --version
# 应显示版本号，如 v0.14.0⚙️ 四、配置 Hermes
4.1 运行配置向导
hermes setup配置向导会依次询问：
-
模型提供商 (Provider)：选择
Custom或DeepSeek等 -
API Key：输入你的 API 密钥
-
Base URL：如使用代理，填写代理地址（如
http://127.0.0.1:15721/v1） -
默认模型名称：如
deepseek-v4-pro -
终端后端 (Terminal Backend)：选择
Local（简单）或Docker（更安全）
4.2 配置文件位置
-
主配置：
~/.hermes/config.yaml -
环境变量（API Key 等）：
~/.hermes/.env
4.3 配置文件示例（使用自定义代理）
上述示例中的端口 15721 并非 Hermes 的默认端口，而是示例环境中 CCSwitch（一个模型代理/协议转换服务） 的监听端口。Hermes 通过该地址将请求转发至底层的 DeepSeek 等模型服务。
在实际部署中，您应根据自己使用的模型代理服务（如 OneAPI、LiteLLM 或 CCSwitch）的实际监听端口进行替换。如果您的 Hermes 直接连接官方 API（如 api.deepseek.com），则无需配置此类本地代理地址。
model:
provider: custom
base_url: http://127.0.0.1:15721/v1
api_key: 你的API密钥
api_mode: chat_completions
default: deepseek-v4-pro
theme: dark🖥️ 五、安装 Hermes-Web-UI
5.1 全局安装 Web UI
# 切换到稳定目录（避免工作目录被删除导致错误）
cd ~
# 安装
npm install -g hermes-web-ui注意：
node-pty相关的警告可以忽略，不影响核心功能。
5.2 启动 Web UI
前台启动（测试用）：
hermes-web-ui start --port 3000 --host 0.0.0.0后台持续运行：
nohup hermes-web-ui start --port 3000 --host 0.0.0.0 > /var/log/hermes-web-ui.log 2>&1 &5.3 开放防火墙端口
sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --reload5.4 访问 Web UI
在浏览器中打开：http://你的服务器IP:3000
-
首次登录：部分版本首次访问会要求设置密码，或使用默认账户
admin/123456 -
登录后，在设置页面配置 API Key 和模型信息（与
hermes setup时一致）
✅ 六、验证安装
# 1. 运行诊断
hermes doctor
# 2. 测试对话
hermes "你好，请介绍一下你自己"
# 3. 检查 Web UI 是否运行
curl http://localhost:3000📁 七、关键目录与文件
| 路径 | 说明 |
|---|---|
/usr/local/lib/hermes-agent/ |
Hermes 核心代码目录 |
/usr/local/lib/hermes-agent/.venv/ |
Hermes 的 Python 虚拟环境 |
/usr/local/bin/hermes |
Hermes 命令软链接 |
/root/.hermes/ |
Hermes 用户数据和配置 |
/root/.hermes/config.yaml |
主配置文件 |
/root/.hermes/.env |
API 密钥等环境变量 |
/usr/local/lib/node_modules/hermes-web-ui/ |
Web UI 代码目录 |
🐛 八、常见问题与解决方案
Q1: hermes: command not found
原因：/usr/local/bin 不在 PATH 中。
解决：
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrcQ2: Git 克隆失败（RPC failed / Connection timed out）
原因：GitHub 网络连接不稳定。
解决：参考 3.2 节，使用镜像源手动下载代码。
Q3: uv: command not found
原因：uv 未添加到 PATH。
解决：使用完整路径 /root/.hermes/bin/uv，或将其加入 PATH：
echo 'export PATH="/root/.hermes/bin:$PATH"' >> ~/.bashrc
source ~/.bashrcQ4: ModuleNotFoundError: No module named 'yaml'
原因：hermes 命令使用的 Python 环境缺少依赖。
解决：
# 方案一：修改 hermes 脚本的 shebang（推荐）
sed -i '1s|.*|#!/usr/local/lib/hermes-agent/.venv/bin/python|' /usr/local/bin/hermes
# 方案二：在虚拟环境中安装依赖
cd /usr/local/lib/hermes-agent
source .venv/bin/activate
pip install pyyaml -i https://pypi.tuna.tsinghua.edu.cn/simpleQ5: process.cwd failed / ENOENT: uv_cwd
原因：当前终端所在目录已被删除。
解决：
cd ~Q6: Node.js 版本过低（要求 ≥ 23）
解决：参考第二节，通过 NodeSource 升级 Node.js。
Q7: Playwright / Chromium 安装失败
原因：Playwright 在 Rocky Linux 上需要额外的系统依赖，且自动安装脚本使用 apt-get。
解决：这是可选功能，不影响 Hermes 核心使用。直接忽略该警告即可。
📌 九、功能状态说明
| 功能 | 状态 | 说明 |
|---|---|---|
| 核心对话 | ✅ 可用 | 主要功能，完全正常 |
| 代码生成与执行 | ✅ 可用 | 核心能力 |
| 文件操作 | ✅ 可用 | 读写文件 |
| 命令行执行 | ✅ 可用 | 执行系统命令 |
| Web UI 界面 | ✅ 可用 | 已安装并配置 |
| 浏览器自动化 | ⚠️ 可选 | 需要额外配置，不影响核心使用 |
🚀 十、开始使用
# 直接对话
hermes "你好，请介绍一下自己"
# 交互式聊天模式
hermes chat
# 查看配置
hermes config
# 查看帮助
hermes --help🔗 参考资源
-
国内镜像加速：
ghfast.top、ghproxy.com、pypi.tuna.tsinghua.edu.cn
欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。
更多推荐
7
0- 0
已为社区贡献4条内容
所有评论(0)