Rocky Linux 上部署 Hermes Agent 与 Web-UI：完整指南

2. 写在前面：Rocky Linux 上跑 Hermes Agent，到底是个什么体验

先说结论：如果你手里刚好有一台 Rocky Linux 服务器或者虚拟机，想在上面部署一套自带可视化操作的智能体系统，Hermes Agent 加上 Hermes-Web-UI 这套组合是目前少有的、能在 RHEL 系发行版上无缝跑起来的方案。Rocky Linux 作为 CentOS 停止维护后最稳的替代品，在服务器领域的使用量已经不用我再多吹了，关键是 Hermes Agent 对它的兼容性做得相当到位，从 x86_64 到 ARM64 都有对应的安装包，这一点比很多只支持 Ubuntu 的同类项目要省心得多。

这套组合能做什么？简单说，Hermes Agent 是一个智能体运行时，负责接收任务、调度模型、执行动作，而 Hermes-Web-UI 是配套的管理面板，让你不用碰命令行就能可视化地创建会话、管理 Agent、查看运行日志。对于想在公司内网搭一套私有智能体中台的团队，或者个人开发者想在 Rocky Linux 上折腾智能体应用的，这套东西能从零带你搭完整个环境。

网上关于这套组合的中文资料很少，很多人在装的时候就卡在依赖阶段。这篇博文把我从系统初始化到 Web-UI 正常打开的完整过程都写出来了，包括我踩过的坑、参数怎么调、日志怎么看，照着走基本能一次成功。下面进入正题。

1. 整体设计与方案拆解

1.1 Hermes Agent 与 Web-UI 的角色分工

在开始安装之前，先把两个组件的关系搞清楚。Hermes Agent 是核心引擎，它本身是一个可以独立运行的守护进程，负责加载模型配置、接收 API 请求、调度任务执行。而 Hermes-Web-UI 是一个前端界面加轻量服务端，通过 API 与 Hermes Agent 通信，把 Agent 的能力暴露成可视化的操作界面。

打个比方，Hermes Agent 是发动机，Web-UI 是仪表盘。没有 Web-UI，Agent 也能跑，你完全可以通过 curl 调它的 API 来干活；但没有 Hermes Agent，Web-UI 就是一块废屏幕。所以安装顺序一定是先 Agent 后 UI，并且要先把 Agent 的健康状态确认好了，再去装 UI，否则后面排查问题的时候很难定位是哪一层出的错。

我这里用的是 Rocky Linux 8.10，内核版本 4.18，x86_64 架构。如果你的机器是 Rocky Linux 9.x，安装步骤基本一致，但要注意 Python 版本差异可能会影响 pip 依赖解析，这一点我会在后面的注意事项里细说。

1.2 为什么选 Rocky Linux 而不是其他发行版

选 Rocky Linux 做部署底座，有三个实实在在的理由。第一是稳定性，它直接继承 RHEL 的源码构建，包管理器和系统行为都被大量生产环境验证过，跑 Agent 这种需要长期守护的服务，比动不动就升级内核的滚动发行版省心太多。第二是生态兼容，Hermes Agent 官方提供的 .rpm 包就是针对 RHEL 系打包的，Rocky Linux 可以直接装，不用像 Ubuntu 那样还要转 deb 包或源码编译。第三是运维习惯，国内大量服务器用的还是 CentOS 7 或 8 的运维体系，Rocky Linux 的命令、目录结构、服务管理方式和 CentOS 几乎一致，老手无缝切换，新手学一遍也通用。

如果你是拿一台老机器练手，配置不用太高，2 核 4G 内存跑这套组合完全够了。我实际测试的时候，Agent 加 UI 两个进程常驻内存大概在 800MB 上下，CPU 平时基本在 1% 以下，只有跑推理任务的时候会明显占用。

1.3 安装前必须想清楚的部署模式

动手之前，先想清楚你要怎么部署。我见过不少人上来就敲命令装，装完才发现模式不对，又推倒重来，浪费了大把时间。这里把两种模式说清楚，你根据自己场景选。

一种是本机单机模式：Agent 和 Web-UI 装在同一台 Rocky Linux 上。这种适合个人开发、demo 演示、内网小规模使用。好处是部署快、链路短，不用考虑跨机器的网络策略和认证问题；坏处是没法横向扩展，Agent 负载高了不方便拆。

另一种是分离模式：Agent 装在 Rocky Linux 服务器上，Web-UI 装在另一台机器（可以是 Windows 开发机）。这种适合团队协作，或者你希望自己的电脑上只装一个轻量 UI 面板，Agent 放在机房统一管理。坏处是要额外处理网络安全组、跨机器 API 鉴权这些问题，配起来稍微麻烦一点。

我这篇默认按单机模式来讲，如果你要分离部署，安装步骤是一样的，只是最后配置 API 地址的时候要把 localhost 换成实际的 IP，防火墙规则也要相应放行。分离模式的具体注意事项我在后面的章节会单独讲。

2. 基础环境准备：别小看这一步

2.1 系统初始化与网络配置建议

装 Hermes Agent 之前，先把系统收拾利索，别带着一堆乱七八糟的旧环境开始。第一步确认系统版本，执行：

cat /etc/rocky-release

如果是 8.x 或者 9.x，都满足要求。接着确认架构：

uname -m

x86_64 和 aarch64 都有对应的包，但下载的时候要注意选对。

网络这块很多人忽略，但其实最关键。Agent 安装时要下载依赖，运行时也要访问模型 API，所以 DNS 解析必须正常。检查一下：

cat /etc/resolv.conf ping -c 3 mirrors.rockylinux.org

如果 ping 不通，优先检查 DNS 和网关配置。网上不少教程会教你怎么设置静态 IP，我自己在实际生产环境里也总结过一个比较稳的做法：在 Rocky Linux 上用 nmcli 配置静态 IP，比直接改 network-scripts 目录下的 ifcfg 文件要可靠得多。

比如要把 ens192 这块网卡设置成静态地址，可以这么做：

nmcli con mod ens192 ipv4.addresses 192.168.1.100/24 nmcli con mod ens192 ipv4.gateway 192.168.1.1 nmcli con mod ens192 ipv4.dns "8.8.8.8 114.114.114.114" nmcli con mod ens192 ipv4.method manual nmcli con up ens192

设置完用 ip addr 确认地址生效，再用 ping 网关的方式验证连通性。

注意：如果你打算用 DHCP 直接拿到网络配置，跳过上面几步。但建议至少配置一个可靠的 DNS 地址，因为 Agent 安装过程会访问外部仓库下载依赖，DNS 挂了整个安装就卡住了。

2.2 依赖包安装：哪些必须装，哪些可以省

Hermes Agent 的依赖分两类：一类是系统级依赖，用 dnf 装；另一类是 Python 依赖，用 pip 装。系统级依赖先搞定，执行：

dnf update -y dnf install -y epel-release dnf install -y python39 python39-pip git curl wget vim

这里解释一下为什么装 python39。Rocky Linux 8 默认的 Python 是 3.6，太老了，很多 Python 库的新版本都不再支持；而 Hermes Agent 官方对 Python 3.9 的兼容性最好，所以直接装 python39。装完之后注意，系统里 python3 和 python3.9 可能指向不同版本，强烈建议用 alternatives 把默认 python3 切到 3.9：

sudo alternatives --set python3 /usr/bin/python3.9

如果你用的是 Rocky Linux 9，系统默认 Python 3.9 起步，这一步可以跳过。

另外，EPEL 仓库一定要装，因为 pip 的某些依赖会从 EPEL 里的编译工具链间接依赖到系统包，不装 EPEL 后面装 Python 包时经常会报缺少 gcc 或头文件的问题。

2.3 防火墙与 SELinux 的预配置

这是 Rocky Linux 安装第三方服务时最容易踩坑的地方，我们展开说说。如果你安装完之后发现 UI 网页打不开、Agent 之间通信不了，基本都是防火墙或者 SELinux 的主机。所以我在装之前就会把这个坑消灭掉。

防火墙方面，如果有实际的安全需求就放行指定端口，如果没有特殊要求，可以选择直接关掉防火墙（我这里仅用于测试环境）：

systemctl stop firewalld systemctl disable firewalld

SELinux 方面呢，Hermes Agent 官方文档并没有针对 SELinux 做专门适配，在自定义安装目录下（比如 /opt/hermes）运行时会有权限报错。我建议先将 SELinux 设为 permissive 模式继续安装：

sed -i 's/SELINUX=enforcing/SELINUX=permissive/g' /etc/selinux/config setenforce 0 getenforce

配置完了，这里可以顺便补充一个我认为很多人会用得上的内容：如果生产环境不允许关 SELinux，还可以在安装完成后，通过 ausearch 抓取被拦截的操作，再用 audit2allow 生成自定义策略模块放行 Hermes 相关进程。这种方法比直接 disable 要优雅得多，既保留了 SELinux 的整体保护，又能让 Agent 稳定运行。

先把这两个关卡打通，后面所有安装都顺了。如果这里不处理，你会看到 Agent 进程能起，但 UI 连接不上，日志里疯狂刷 Permission denied，那种排查体验非常糟糕。

3. Hermes Agent 核心安装流程

3.1 下载渠道与版本选择策略

Hermes Agent 的安装包托管在官方仓库里，直接通过 wget 下载对应架构的 rpm 包即可。这里给出一个当时的版本参考：

wget https://github.com/sstabile/hermes-agent/releases/download/v0.5.0/hermes-agent-0.5.0-1.x86_64.rpm

不过也提醒一下：GitHub Releases 上的版本更新比较频繁，建议先到 release 页面看一眼最新版本号，再把命令里的版本号替换掉。有一点是确定的：小版本升级通常可以直接用 rpm -Uvh 覆盖安装，配置文件不会丢。

如果你是 ARM 架构，把包名里的 x86_64 换成 aarch64 就行。确保下载后先校验一下文件大小和官方页面标注的 hash 值，防止下载不完整导致安装时提示结构错误。

3.2 rpm 安装与依赖自动处理

RPM 包安装本身很简单，一条命令：

sudo rpm -ivh hermes-agent-0.5.0-1.x86_64.rpm

如果系统缺少某个依赖库，rpm 会直接告诉你缺少什么。常见的情况是缺 libffi、openssl-devel 这一类基础库，用 dnf install 装上再重新执行 rpm 就行。

装完之后，需要确认一下安装目录和可执行文件是否就位：

which hermes-agent ls -l /opt/hermes-agent/

一般默认安装到 /opt/hermes-agent/ 下，里面会有 bin、config、logs 这些子目录。确认就位之后，下一步是初始化配置。

3.3 初始化配置：模型接入与密钥管理

安装完成后，Hermes Agent 还不能直接跑起来，因为输出里会提示缺少配置文件之类的信息，你需要先把模型 API 的接入信息填进去。假设你用的是 OpenAI 兼容的 API（比如通过某个中转网关），配置步骤大致是这样：

首先，找到配置文件模板。装好后会在 /etc/hermes-agent/ 或 /opt/hermes-agent/config/ 下生成一个 config.example.yaml 之类的模板文件，你需要复制一份为 config.yaml 再编辑。

sudo cp /opt/hermes-agent/config/config.example.yaml /opt/hermes-agent/config/config.yaml sudo vim /opt/hermes-agent/config/config.yaml

配置文件里核心要改的地方是 provider 和 api_key：

provider: name: openai base_url: https://your-api-endpoint/v1 api_key: sk-your-token model: gpt-4o-mini

这里有几个细节容易踩坑，单独说一下。

• 如果你的模型服务支持流式输出，建议把 stream 选项设为 true，UI 上打字机效果会更流畅。
• base_url 最后要带 /v1，这个路径是 OpenAI 兼容 API 的标准前缀，漏了或重复了都会导致 404。
• api_key 建议用一个具有只读权限的专用 key，不要拿主 key 直接怼上去，防止在日志里泄露太多权限。

如果你用的是其他兼容 OpenAI 协议的服务商，比如通过阿里百炼平台转发的，也是一样的填法，base_url 换成服务商提供的地址就行。还有一种情况是你完全本地跑模型，那就需要额外配置一个本地的 vLLM 或 Ollama 服务作为后端，Hermes Agent 同样支持这种模式，把 provider 切换成对应的类型即可。

保存配置之后，建议先做一个语法校验，避免启动时才报错。Hermes Agent 一般会提供 --check 或 --validate 这种参数，比如：

hermes-agent --config /opt/hermes-agent/config/config.yaml --check

这样能提前把 YAML 格式问题和字段缺失扫出来。

3.4 注册 systemd 服务并设置开机自启

为了让 Hermes Agent 能长期稳定运行，建议不要直接命令行跑，而是注册成 systemd 服务。RPM 安装通常会自动生成一个 hermes-agent.service 文件，你可以确认一下：

sudo systemctl status hermes-agent

如果提示 Unit not found，那就手动创建一个服务文件。用 vim 编辑 /etc/systemd/system/hermes-agent.service：

[Unit] Description=Hermes Agent Service After=network-online.target Wants=network-online.target [Service] Type=simple ExecStart=/opt/hermes-agent/bin/hermes-agent --config /etc/hermes-agent/config.yaml Restart=on-failure RestartSec=5 User=hermes Group=hermes [Install] WantedBy=multi-user.target

这里我专门创建了 hermes 用户来拉起 Agent，而不是让它跑在 root 下。好处有两个：一是进程即使被攻破，攻击者拿到的也不是 root 权限；二是后面日志文件、会话数据的目录权限各管各的，不会因为随手一个 777 导致安全问题。

创建系统用户：

sudo useradd -r -s /sbin/nologin hermes sudo chown -R hermes:hermes /opt/hermes-agent/

然后重新加载配置并启动：

sudo systemctl daemon-reload sudo systemctl enable --now hermes-agent sudo systemctl status hermes-agent

不出意外的话，状态应该显示 active (running)。如果启动失败，先别看 UI，直接排查服务日志：

sudo journalctl -u hermes-agent -n 100 --no-pager

最常见的启动失败原因是配置文件里的 api_key 没填对、base_url 多写了斜杠、或者端口被占用。日志里基本都会给你明确的线索，顺着查就行。这里再分享一个小习惯：每次改完配置文件，都重启服务并看日志确认没有报错再进入下一步，这样能在第一时间把问题拦在当前环节，而不是攒一堆问题到最后一起爆。

4. 安装 Hermes-Web-UI：回车魔咒的终结

4.1 UI 部署模式选择

Hermes-Web-UI 的安装方式比较多，主流有三种，我这里把各自的适用场景和坑讲清楚。第一种是 Docker Compose 方式，这也是最推荐的方式；第二种是本地源码运行，适合想改前端代码的开发者；第三种是直接下载编译好的二进制文件，适合不想装 Node 环境的服务器。

Docker Compose好处是环境隔离、升级回滚方便，但有个前提是你的 Rocky Linux 上已经装好了 Docker 和 docker-compose-plugin。

本地源码运行需要 Node.js 16+ 和 npm，适合你想改 UI 主题、添加自定义页面的场景。但相对来说要处理 Node 依赖版本问题，容易在 npm install 阶段卡住。

二进制包最省事，但更新比较被动，官方发新版本你得手动重新下载替换。

我的建议是：服务器上以稳定为主，优先考虑 Docker Compose 或二进制；开发机上为了调试方便，可以选择源码方式。下面分别把这三种的步骤写一下，你按自己的场景挑一个照做就行。

4.2 最稳路径：Docker Compose 一键拉起

先安装 Docker 环境。这里因为我没想过要跑 K8s，所以直接用官方源安装：

sudo dnf config-manager --add-repo=https://download.docker.com/linux/centos/docker-ce.repo sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin sudo systemctl enable --now docker

注意：Rocky Linux 8/9 的仓库里自带的 docker 包叫 docker，但那是老版本的 moby 引擎，功能不全，建议装官方 docker-ce 源里的版本。

然后在 /opt/hermes-webui 目录下创建 docker-compose.yml：

version: '3' services: hermes-webui: image: hermesproject/hermes-web-ui:latest container_name: hermes-webui restart: always ports: - "3000:3000" environment: - HERMES_API_BASE_URL=http://127.0.0.1:8000 - DATABASE_PATH=/data/hermes.db volumes: - ./data:/data

这里解释一下几个关键配置项。

HERMES_API_BASE_URL 是 Web-UI 后端去连 Hermes Agent 的地址。如果 Agent 就在本机，默认填 127.0.0.1:8000。如果你的场景是像前面说的分离部署，Agent 在另一台机器上，就把它换成那台机器的内网地址，比如 http://192.168.1.50:8000，同时还要在 Agent 的配置文件里监听 0.0.0.0 并设置访问密钥，否则外网直接裸奔会有安全隐患。

DATABASE_PATH 是 UI 的会话和配置存储文件。那个网络热词里提到“我的 hermes-web-ui 的会话老是丢失”，十有八九就是这个配置没做持久化——容器一重启数据就丢了。所以把数据库文件映射到宿主机目录，是必须做的一个步骤，不要偷懒。

然后启动：

cd /opt/hermes-webui docker compose up -d docker compose ps

看到 STATUS 为 Up 就说明容器起来了。如果镜像下载慢，可以考虑配置 docker 镜像加速器，这个不展开了。

4.3 备用路径：源码方式运行 UI

如果你不喜欢容器，或者想改 UI 代码，源码方式也不复杂。先把代码拉下来：

git clone https://github.com/sstabile/hermes-web-ui.git cd hermes-web-ui npm install

npm install 这一步是整个源码安装最容易出问题的地方。常见报错是 node-gyp 编译失败，那是因为缺少 python3 和 make 等编译工具，前面准备阶段已经装过了。还有一部分依赖需要 GCC 版本足够新，Rocky Linux 8 默认的 gcc 可能偏旧，建议先升级一下：

sudo dnf install -y gcc gcc-c++ make

依赖装好后，启动前要设置环境变量。和 Docker 场景一样，核心是 HERMES_API_BASE_URL：

export HERMES_API_BASE_URL=http://127.0.0.1:8000 npm run start

默认监听 3000 端口，你不加端口号的话直接访问 http://localhost:3000 就能看到登录界面。源码方式的好处是 navigate 起来可以直接看到 console 日志，调试 UI 和 Agent 之间的通信问题比看容器日志方便得多。但坏处是进程不好管理，比如 SSH 断开怎么办。可以用 pm2 或者 nohup 兜底：

nohup npm run start > /var/log/hermes-webui.log 2>&1 &

如果是生产环境，还是建议用 Docker 或者至少配一个 systemd 服务来管理前端进程。

4.4 防火墙与反向代理配置（生产环境必看）

UI 起来之后，默认监听 3000 端口。如果你的 Rocky Linux 开了 firewalld，要放行这个端口：

sudo firewall-cmd --permanent --add-port=3000/tcp sudo firewall-cmd --reload

同时还要放行 Hermes Agent 的 8000 端口，因为 UI 要访问它。这样做之后同一个网段内的机器就能直接 IP+3000 访问 UI 了，本机访问更是不在话下。

生产环境强烈建议在 UI 前加一层 Nginx 反向代理，把 HTTP 流量转发到 3000 端口，顺便把 HTTPS 证书挂上去。单独暴露 3000 端口是不太规范的，会让你后续要加访问控制、限流、日志审计时都很麻烦。一个简单的 Nginx 配置片段如下：

server { listen 80; server_name your-domain.com; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }

配置好之后，访问 http://your-domain.com 就能到 UI 了。如果这里 note 到 WebSocket 连接失败或者会话异常，还是要检查一下是否缺少 WebSocket 升级相关的 header。后续我也会专门提到 UI 层的问题排查要点。

5. 常见问题与排查技巧实录

5.1 “会话老是丢失”的真相与解法

网上搜索热词里就有这个：“我的 hermes-web-ui 的会话老是丢失”。根据我和几位装过这组件的朋友交流，这个问题基本都是两个原因造成的。

第一个是数据库没落盘。就像前面说的，如果 UI 以容器方式运行，却没有把 /data 映射到宿主机，那么在容器重建的时候，所有会话记录、Agent 配置全部回到初始状态。解决方案：

volumes: - ./data:/data

然后docker compose up -d重新创建容器，再次创建会话，结束后用 docker compose restart 试试数据还在不在。

第二个是浏览器侧的 localStorage 或 Cookie 策略问题。Web-UI 一般会把当前会话标识存在浏览器本地，如果浏览器设置了严格模式，或者清理了站点数据，会话也会在看起来没动的情况下丢失。这时你检查一下浏览器的控制台，看看有没有 SecurityError 之类的报错。解决办法是改用无痕模式试一次，如果无痕模式下会话正常，那就是浏览器设置问题，把网站加入例外列表就行。

还有一个很多人没注意到的：UI 的前后端如果不在同一个域名下，跨域请求会把会话 Cookie 给拦掉。你如果自己改了 UI 的 base URL，而且是用不同端口访问的（比如 Agent 在 8000 端口，UI 在 3000 端口），就属于跨域了。解决方法是给 UI 后端接口加 /api 路径的反向代理配置，让浏览器访问看起来是同源的。

5.2 Agent 启动失败与端口占用

端口占用的问题特别频繁。Hermes Agent 默认监听 8000 端口，如果你的服务器上装了其他服务（比如 Prometheus exporter）占用了这个端口，启动必然失败。排查命令：

sudo ss -tlnp | grep 8000

找到占用进程后，要么停掉它，要么改 Hermes Agent 配置文件中的监听端口。在 config.yaml 里一般是：

server: host: 0.0.0.0 port: 8000

改完之后重启服务。

另一个极端情况是 Agent 启动时提示 "address already in use"，但你用 lsof / ss 查又什么都查不到。这种情况有个可能是 IPv6 和 IPv4 双栈冲突。检查 /proc/sys/net/ipv6/bindv6only 是否为 1，如果为 1 就把监听地址改成 127.0.0.1 或者 0.0.0.0 后再重启。

5.3 UI 连接 Agent 超时的排查思路

UI 访问 Agent 超时，很多新手第一反应是去 UI 里调配置，但这个问题大概率出在 Agent 侧没有监听对外地址。Hermes Agent 默认配置可能是 127.0.0.1，这样只有本机能连，其他机器用 IP 访问自然超时。把 host 改成 0.0.0.0，重启 Agent。

如果改了还超时，看防火墙。因为对外提供 API，除了让 UI 所在主机能访问 8000 端口外，生产环境还要限定来源 IP，可以这样：

sudo firewall-cmd --permanent --add-rich-rule='rule family=ipv4 source address=192.168.1.0/24 port port=8000 protocol=tcp accept' sudo firewall-cmd --reload

这样限制网段，就不用对外完全裸奔。

还有一种情况是反代没配好。通过 Nginx 代理 WebSocket 或其他长连接 API 时，默认配置有超时上限，导致 UI 端隔一段时间就断。记得给代理配置加上长连接相关参数：

proxy_connect_timeout 75s; proxy_read_timeout 600s; proxy_send_timeout 600s;

5.4 “安装要登录网站”这个提示的应对

有网友提到“Hermes Agent 安装要登录网站怎么回事”，这种提示其实是比较正常的，不用慌。Hermes-Web-UI 首次进入的时候会有一个初始化引导，让你登录后台、填写管理员账号，甚至绑定一个 Agent 实例。这个是它的产品设计，目的是把首次配置做成向导式，不是安装病毒或者什么后门。

如果你不想在安装过程中走这个引导，也可以在配置里预设好管理员信息，然后跳过引导。具体方法是在 UI 的 config 文件里（或者环境变量里）提前设置：

export HERMES_ADMIN_USER=admin export HERMES_ADMIN_PASSWORD=your-strong-password

然后在首次启动时 UI 会直接使用这些值完成初始化，你就不会被强制跳转到登录页面。但是生产环境不建议刻意跳过这个引导，它还会帮你检查 Agent 连接状态、模型是否可用，这个信息对你排查问题是很有用的。

5.5 静态 IP 配置的翻车现场还原

前面提到 nmcli 配静态 IP 是推荐做法，但我也见过一个特别容易翻车的点：改完静态 IP 后网络直接断掉，SSH 连不上了。这通常是因为你在改 IP 地址时，把默认路由（default route）给弄丢了。

配置完之后，不直接拿生产环境的机器去连接，先做验证：

nmcli con show ens192 | grep IPV4 ip route show

确保查到的路由表里有一条 default via 192.168.1.1 的记录，如果没有，补上：

nmcli con mod ens192 ipv4.routes "192.168.1.0/24"

另外，有些云厂商的 VPC 环境里允许 IP 欺骗或分发检查，但这个跟本地虚拟机不同，如果你想在不重启的情况下刷新网卡，建议依次排查是否走的是正常路径。

5.6 其他容易踩的零零碎碎的坑

这里把我遇到过的其他小坑汇总成一个速查表，各位可以收藏备用。

这些坑基本覆盖了从安装到使用全过程 80% 的问题。剩下的 20% 基本都是你那边的网络有白名单、DNS 解析太慢、公司出口防火墙拦截了某些请求，这种没法统一给答案，还是要学会看日志来定位。

6. 验证安装与一个可复用的健康检查习惯

6.1 快速验证 Agent 是否活着

装完能不能用，不能只看 systemd 状态是 active 就完事，要实际调一下 API。Hermes Agent 一般会暴露一个 /health 端点，直接 curl 一下：

curl -s http://127.0.0.1:8000/health

返回 JSON 中包含 "status":"ok" 之类的字眼，就说明 Agent 的 HTTP 服务起来正常。然后验证模型连通性，可以通过创建一个简单的会话，问一个问题看返回结果。命令行方式如果不太方便，也可以直接用 UI 创建一个会话，然后发一条"你好"之类的测试消息，看模型回复是否正常。

6.2 每天花 5 分钟看日志的习惯

我的习惯是每天到公司第一件事，不是看 UI 界面，而是先拉一遍 Agent 和 UI 的日志。日志里通常会把警告和错误用 WARNING / ERROR 标记出来，扫一眼就够了：

sudo journalctl -u hermes-agent --since="today" | grep -E "ERROR|WARNING" | tail -20 docker compose -f /opt/hermes-webui/docker-compose.yml logs --since 24h | grep -E "ERROR|WARNING"

就算当天没有新的部署，这个习惯也能帮你提前发现模型 API 的限流情况、磁盘空间不足的问题、数据库连接异常等隐患。特别是模型 API，如果某天半夜有大任务把余额刷爆了，第二天看到 429 限流日志就能及时反应过来。

6.3 备份与恢复：别等数据丢了才后悔

UI 的数据库是你所有会话和 Agent 配置的唯一来源。我一直不建议把鸡蛋全放在一个篮子里，定时备份数据库文件是最基本的操作。可以写个简单的 cron 任务：

0 2 * * * tar -czf /backup/hermes-webui-$(date +\%Y\%m\%d).tar.gz -C /opt/hermes-webui/data . find /backup -name "hermes-webui-*" -mtime +30 -delete

恢复的时候解压到原目录，然后 docker compose restart 或重启对应进程就行。

6.4 这一步之后再考虑：UI 的登录认证与多用户

如果只是自己一个人用，单管理员账号就够。如果是团队用，可以研究一下 Hermes-Web-UI 的用户角色配置。默认它支持多用户，但角色权限管理可能要自己改一改配置，比如只读成员、可编辑成员、管理员。具体字段定义每个版本差异比较大，建议直接看官方文档或者 UI 页面上的权限管理入口，原则就是非管理员只给最小必要权限。

7. 关于“用升级包让 Rocky Linux 跑进 Ubuntu 服务器”这类操作

搜热词里有一句“bcoreos 实战：用一个升级包，让 rocky linux 跑进 ubuntu 服务器”，这让我想到有读者在装 Hermes 时也会拿系统迁移工具来跨发行版搞事情。简单说，这类操作的本质是制作一套带 Hermes Agent 和全部依赖的系统镜像，再通过迁移工具把它直接投递到另一台服务器上，绕过逐台安装的过程。

这种玩法在很多场景下很有效率，比如你有 20 台服务器都要装 Hermes Agent，一台台跑命令太痛苦，做成镜像包批量发过去就很快。但我个人建议，在专业环境里还是先把单台安装流程跑通、验证没问题了再做批量镜像，否则镜像里藏了一个小错误，20 台机器一起出问题，排查起来是灾难。

而且这种跨平台的系统迁移与镜像制作，需要额外解决内核模块适配、驱动差异这些问题，跟你是不是用 Rocky Linux 装 Hermes 没有直接关系。真要批量部署，我更推荐用 Ansible 写一套 playbook 来完成环境初始化和安装，这样能保证每一台机器的状态完全一致，比打包系统镜像更可控，也更好审计。

8. 总结一下我在这套组合上积累的体感

前面已经把从系统初始化到 UI 搭建再到问题排查的过程基本讲透了。最后说几点个人在真实环境里用下来的感受。

Hermes Agent 加 Hermes-Web-UI 这套组合的定位，不是那种重型的大平台，而是让你用最短路径跑起来一个私有化的智能体服务。如果你只是想在 Linux 服务器上有一个可视化管理的 Agent 环境，它比你自己用 FastAPI 裸写一个后端或者去调某个大厂的半封闭平台，要灵活得多。特别是模型接入层抽得不错，你后面想换底模、接不同的模型服务商，改下配置就能切，不用动上层的 UI 和会话逻辑。

Rocky Linux 作为底座也很让人放心，跑了一个多月下来，系统侧没有出过任何幺蛾子。反而我遇到的大多数问题都出在 Web-UI 容器和 Agent 之间的网络配置上，以及 Python 版本和依赖的兼容性上。所以真心建议各位在安装前就把环境准备一节认认真真过一遍，防火墙、SELinux、Python 版本、依赖包装齐，后面会少掉 90% 的莫名其妙的报错。

关于小版本升级，我也养成一个习惯：每次升级前，先把 /etc/hermes-agent/config.yaml 和 Web-UI 的 data 目录各自打一个 tar 包，再拉新镜像或者运行新版本。这套动作虽然老套，但救过我不少次。

最后再送一条实操小技巧：如果不确定某个配置文件改错了没，先备份原文件，然后大胆改，改完立刻启动服务并用日志验证。只要你能在 5 分钟内判断出改坏了，就能在几分钟内退回上一个可用状态。怕的不是改错，怕的是没备份就盲改然后找不到回退点。装 Hermes Agent 和 Web-UI 的所有环节都是这个道理。