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-UIAgent 也能跑你完全可以通过 curl 调它的 API 来干活但没有 Hermes AgentWeb-UI 就是一块废屏幕。所以安装顺序一定是先 Agent 后 UI并且要先把 Agent 的健康状态确认好了再去装 UI否则后面排查问题的时候很难定位是哪一层出的错。我这里用的是 Rocky Linux 8.10内核版本 4.18x86_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 -mx86_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.9sudo 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 firewalldSELinux 方面呢Hermes Agent 官方文档并没有针对 SELinux 做专门适配在自定义安装目录下比如 /opt/hermes运行时会有权限报错。我建议先将 SELinux 设为 permissive 模式继续安装sed -i s/SELINUXenforcing/SELINUXpermissive/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_keyprovider: name: openai base_url: https://your-api-endpoint/v1 api_key: sk-your-token model: gpt-4o-mini这里有几个细节容易踩坑单独说一下。如果你的模型服务支持流式输出建议把 stream 选项设为 trueUI 上打字机效果会更流畅。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] DescriptionHermes Agent Service Afternetwork-online.target Wantsnetwork-online.target [Service] Typesimple ExecStart/opt/hermes-agent/bin/hermes-agent --config /etc/hermes-agent/config.yaml Restarton-failure RestartSec5 Userhermes Grouphermes [Install] WantedBymulti-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-repohttps://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.ymlversion: 3 services: hermes-webui: image: hermesproject/hermes-web-ui:latest container_name: hermes-webui restart: always ports: - 3000:3000 environment: - HERMES_API_BASE_URLhttp://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 installnpm install 这一步是整个源码安装最容易出问题的地方。常见报错是 node-gyp 编译失败那是因为缺少 python3 和 make 等编译工具前面准备阶段已经装过了。还有一部分依赖需要 GCC 版本足够新Rocky Linux 8 默认的 gcc 可能偏旧建议先升级一下sudo dnf install -y gcc gcc-c make依赖装好后启动前要设置环境变量。和 Docker 场景一样核心是 HERMES_API_BASE_URLexport HERMES_API_BASE_URLhttp://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 21 如果是生产环境还是建议用 Docker 或者至少配一个 systemd 服务来管理前端进程。4.4 防火墙与反向代理配置生产环境必看UI 起来之后默认监听 3000 端口。如果你的 Rocky Linux 开了 firewalld要放行这个端口sudo firewall-cmd --permanent --add-port3000/tcp sudo firewall-cmd --reload同时还要放行 Hermes Agent 的 8000 端口因为 UI 要访问它。这样做之后同一个网段内的机器就能直接 IP3000 访问 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-rulerule familyipv4 source address192.168.1.0/24 port port8000 protocoltcp 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_USERadmin export HERMES_ADMIN_PASSWORDyour-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 其他容易踩的零零碎碎的坑这里把我遇到过的其他小坑汇总成一个速查表各位可以收藏备用。现象原因解决方法pip 安装依赖时报 Could not find a version that satisfies the requirement配置了无效的 pip 源或 Python 版本太低切到 python3.9 以上并配置阿里云 pip 源Hermes Agent 日志出现 401 Unauthorized可能同时跑了多个模型 API key改动配置没重启认真检查 base_url 是否统一、api_key 是否有远程覆盖权限UI 创建会话后 Agent 无响应模型未正确配置或 Agent 无法访问外网先 curl 一下模型 API 地址但注意不要直接打印打过日志的 keyDocker 拉取镜像太慢网络原因配置 Docker registry 加速地址临时加也行UI 中文显示乱码字体问题安装中文字体noto-sans-cjk 就可以Agent 服务频繁重启config.yaml 可能被炸弹或者格式错误用 python3 -c 或 yamllint 校验 YAML 语法Web 界面操作卡顿严重数据库增长过大或磁盘 IO 太慢把数据库文件迁移到 SSD 或改用 PostgreSQL 外部存储这些坑基本覆盖了从安装到使用全过程 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 --sincetoday | 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 的所有环节都是这个道理。
