最近给一台 Rocky Linux 服务器部署 Hermes Agent 和配套的 Hermes-Web-UI整个过程折腾了不少时间。这套东西说简单也简单无非就是两个服务端组件加一个 Web 控制台但真踩起坑来从下载安装包到模型接入再到那个“会话老是丢”的经典问题每一步都有不少值得记录的细节。这篇就把我实际跑通的完整流程、踩过的坑和排查思路整理出来打算在 Rocky Linux 上装 Hermes 的朋友可以直接按着这个走。先说清楚一个概念Hermes Agent 是真正干活的常驻服务负责代理内部逻辑、会话状态管理、模型 API 对接这些核心事情Hermes-Web-UI 是给人看的操作界面负责展示会话、配置参数、管理多个 Agent。两者独立成进程通过本地 HTTP 接口通信。理解了这个关系后面排查问题会轻松很多——很多“会话丢失”其实不是 Agent 丢了消息而是 Web-UI 和 Agent 之间的连接或存储出了问题。我在 Rocky Linux 9.x 上完成了全部部署整个流程分为五个部分前置规划、系统基础设置、Agent 安装、Web-UI 安装、问题排障。每一步下面我都会写上“为什么这么做”毕竟光给命令不给原理换台机器换个版本你还是不会应对。1. 部署前的整体规划先想清楚再动手1.1 Hermes Agent 与 Hermes-Web-UI 的分工关系刚开始接触这套组件的人最容易搞混的就是 Agent 和 Web-UI 谁依赖谁。简单来说Hermes Agent 是核心服务它本身不依赖 Web-UI 也能运行Hermes-Web-UI 是一个前端控制台用来管理和查看 Agent 的运行状态、会话记录、模型配置等信息。如果把 Agent 比作后台发动机Web-UI 就是驾驶舱仪表盘。仪表盘坏了发动机照样能转但你无法直观监控数据也无法舒服地操作。这两个组件配套使用时建议装在同一台机器上因为它们之间走的是回环网络127.0.0.1通信延迟低也避免了向外网暴露管理端口带来的安全风险。如果必须分机部署那就要在 Agent 配置里监听 0.0.0.0并且用防火墙把端口严格限制为只允许 Web-UI 所在机器的 IP 访问绝不能图省事把所有端口直接公网裸奔。1.2 服务器版本选型与硬件需求先说系统版本。Rocky Linux 目前主流的两个大版本是 8.x 和 9.x我的建议是直接用 9.x 系列比如 9.4 或更新的小版本。原因很直接Hermes 这类持续更新的基础组件会优先在新系统版本上做兼容测试Rocky 9 的软件仓库、Python 环境、依赖库版本都更贴近当前主流软件的需求。Rocky 8 虽然也在维护期内但系统自带的 OpenSSL、Python、SQLite 等版本偏老碰到个别依赖不兼容的概率高不少。硬件方面Agent 加 Web-UI 这套组合并不吃配置。我用的是一台 2 核 4G 内存的小服务器跑了 Agent、Web-UI、Nginx 三个进程日常占用内存大概在 1.5G 左右。如果你还要在同一台机器上跑本地模型那内存至少要 16G 起步最好有独立显卡或 NPU。多数场景下模型服务本身是远程的Agent 只是转发请求所以 2 核 4G 完全够用。磁盘规划上建议把 /var/lib/hermes 独立出来或者至少确保根分区有足够空间。Agent 的会话记录、日志文件都会随时间增长。我见过有人装在 20G 的小盘上跑了两个月磁盘就满了然后出现各种诡异问题——最常见的就是界面能打开但存不了新会话因为 SQLite 写不进去了。1.3 安装方式选择原生部署还是容器化很多人会问既然有容器为什么不直接用 Docker 跑省去环境问题我的回答是如果你只是自己测试玩用 Docker Compose 确实快如果要长期稳定运行、方便调试、和系统服务做整合原生二进制加 systemd 管理是更好的选择。原因有三点。第一Hermes Agent 经常要访问宿主机的网络、文件系统和系统命令容器化后这些权限需要额外配置处理不好就会出现“明明文件存在但进程读不到”的怪问题。第二会话数据如果放在容器里一旦容器重建而没有挂载持久化目录所有历史会话直接清空这种事故在社区里已经见过不止一次了。第三systemd 天然支持开机自启、崩溃重启、日志统一管理用journalctl -u hermes-agent即可集中看日志比docker logs灵活得多。所以下面的内容里我统一采用“二进制安装 systemd 管理”的方式。如果你坚持容器化也可以参考这个思路只是把最后的 systemd 单元换成容器启动参数。2. 系统基础配置静态IP、镜像源与依赖准备2.1 Rocky Linux 设置静态 IP稳定部署的前提这一步看起来和 Hermes 安装没直接关系但非常关键。默认情况下很多云服务器和虚拟机用的是 DHCP 动态获取 IP。如果 IP 在重启后变化你 Web-UI 里配置的 Agent 回连地址就会失效用 IP 大白话讲就是“Agent 失联了”。所以装 Hermes 之前请先把服务器的 IP 固定下来。Rocky Linux 9 默认使用 NetworkManager推荐直接用 nmcli 命令操作不推荐去手工改/etc/sysconfig/network-scripts/ifcfg-*文件因为 NetworkManager 的配置管理优先级更高两处不一致时容易互相覆盖。先查看当前网卡名称和连接名称nmcli con show正常会输出类似ens160或eth0之类的连接名。然后执行以下修改把 IP、网关、DNS 替换成你自己的环境值nmcli con mod ens160 ipv4.addresses 192.168.1.50/24 nmcli con mod ens160 ipv4.gateway 192.168.1.1 nmcli con mod ens160 ipv4.dns 223.5.5.5 119.29.29.29 nmcli con mod ens160 ipv4.method manual nmcli con up ens160这里我用了两个国内常用的公共 DNS如果你在海外部署换成对应的本地 DNS 即可。把ipv4.method设为 manual 代表手动指定 IP如果不设置这一项只添加地址重启后 NetworkManager 仍然可能走 DHCP。注意如果你是通过 SSH 远程操作这台服务器执行nmcli con up ens160之前务必再三确认 IP、掩码和网关没有写错。一旦地址设置错误且生效当前 SSH 连接会立刻断开而你人又不在机房就只能通过面板的 VNC 或者带外管理去恢复了。保险起见可以先把配置写好执行nmcli con reload后观察连接状态再单独重启网络服务。验证方式很简单ip addr show ens160 ping -c 4 223.5.5.5确认 IP 已生效且网络通畅后再继续下一步。2.2 配置 yum 源并启用 CRB 与 EPELRocky Linux 的默认官方源在大多数地区速度都还可以但如果你发现dnf install时下载依赖非常慢可以换成距你较近的镜像源。注意换源之后要清理缓存再重新生成dnf clean all dnf makecache换源属于按需操作但下面的仓库启用是必须做的dnf install -y epel-release dnf config-manager --set-enabled crb dnf makecacheCRBCodeReady Builder仓库在 Rocky 9 中默认是关闭的但很多 EPEL 包和编译型依赖都要求它处于启用状态。Hermes 的某些依赖库比如 json-c、libsodium 之类可能就是从 EPEL 或 CRB 里拉出来的。如果没有提前启用安装过程中会提示找不到依赖到时候再回头排查就浪费时间了。顺手把系统更新到最新补丁状态dnf update -y然后装一些后面用得到的基础工具dnf install -y vim tar curl wget sqlite3 policycoreutils-python-utilspolicycoreutils-python-utils 这个包提供了semanage命令如果 SELinux 处于 enforcing 状态需要用它对 Hermes 的端口和目录做上下文放行。很多人装完软件发现端口起不来日志里全是 “Permission denied”十有八九就是 SELinux 拦截而你又没有装 semanage 工具去看策略所以提前装上很有必要。2.3 理解 systemd 与日志管理基础后面的安装过程会大量使用 systemd所以这里先铺垫一下。systemd 是 Linux 下负责管理系统服务的核心工具systemctl start、systemctl enable、systemctl status是日常操作里最常用的三个命令。日志统一由 journald 管理查看某个服务的最近一百行日志可以这样journalctl -u hermes-agent -n 100 -f-n 100表示显示最近 100 行-f表示实时跟踪调试时非常有用。如果服务启动失败不要在日志里瞎猜直接看这个输出原因基本都会写清楚。3. 安装 Hermes Agent核心服务端实操3.1 获取安装包并校验完整性在安装之前先到 Hermes 的官方 Release 页面下载适配 Linux 的安装包。需要注意区分“桌面版”和“服务器版/无头版”如果你拿到的是一个带 GUI 交互的安装程序那是给有桌面环境的工作站用的不适合在纯命令行的 Rocky Linux 服务器上操作强行安装极易报错。服务器环境请选择 headless 或 cli 类型的包。假设你下载的是hermes-agent-linux-amd64.tar.gz先放到一个统一的目录mkdir -p /opt/hermes cd /opt/hermes curl -fL -o hermes-agent.tar.gz [官方Release提供的下载地址]下载完成后强烈建议校验文件完整性sha256sum hermes-agent.tar.gz把输出的哈希值和官方页面提供的 SHA256 值做对比。如果一致再解压tar xzf hermes-agent.tar.gz ls -l /opt/hermes解压后目录里通常会包含二进制文件、默认配置模板和一份文档。先不要急着执行先把目录结构调整成规范状态mkdir -p /opt/hermes/bin mkdir -p /etc/hermes mkdir -p /var/lib/hermes然后把解压出来的主程序移到 bin 目录配置文件样例复制到 /etc/hermes 下mv /opt/hermes/hermes-agent /opt/hermes/bin/ cp /opt/hermes/config.example.yaml /etc/hermes/config.yaml chmod x /opt/hermes/bin/hermes-agent创建运行用户useradd -r -s /sbin/nologin hermes chown -R hermes:hermes /var/lib/hermes /etc/hermes用独立用户运行服务是个很好的习惯。即使 Agent 被攻破攻击者拿到的也只是一个低权限系统账号而不是 root。千万别图省事直接用 root 运行。3.2 配置文件详解监听地址、存储路径与模型接入Hermes Agent 的核心配置是/etc/hermes/config.yaml。不同版本的配置字段会有差异但下面几个关键配置项基本是通用的server: listen: 127.0.0.1 port: 4150 storage: type: sqlite path: /var/lib/hermes/hermes-agent.db model: provider: openai-compatible base_url: https://api.example.com/v1 api_key_env: HERMES_MODEL_API_KEY model_name: qwen-plus session: ttl_hours: 720逐个说server.listen和server.portAgent 对外提供 API 的地址。和 Web-UI 同机安装时保持 127.0.0.1 即可这样不会把管理端口暴露到外网。如果你 Web-UI 要装在另一台机器再改成 0.0.0.0同时配合防火墙限制来源 IP。storage会话数据保存方式。强烈建议用 SQLite 文件存储路径放在 /var/lib/hermes 下。路径要保证 hermes 用户有读写权限否则服务能启动但一切数据都存不下来重启后你会得到一个“失忆”的 Agent。model模型服务地址和 API Key。Hermes 支持 OpenAI 兼容接口如果你用的是阿里百炼这类在线模型平台只要把base_url指向对应的 v1 接口地址model_name填模型的标识名即可。API Key 不要直接写死在配置文件里而是通过环境变量引用这样万一配置文件泄漏也不至于连累密钥泄露。session.ttl_hours会话保留时长。单位为小时720 表示 30 天。设得太短会让历史会话“无故消失”设成 0 则可能代表永久保留具体以你的版本文档为准。API Key 写入环境变量文件cat /etc/hermes/hermes.env EOF HERMES_MODEL_API_KEY你的密钥 EOF chmod 600 /etc/hermes/hermes.env chown hermes:hermes /etc/hermes/hermes.env3.3 注册为 systemd 服务并验证运行有了配置和二进制文件后写一个 systemd 服务单元cat /etc/systemd/system/hermes-agent.service EOF [Unit] DescriptionHermes Agent Service Afternetwork-online.target Wantsnetwork-online.target [Service] Typesimple Userhermes Grouphermes EnvironmentFile/etc/hermes/hermes.env ExecStart/opt/hermes/bin/hermes-agent --config /etc/hermes/config.yaml Restarton-failure RestartSec5 WorkingDirectory/var/lib/hermes NoNewPrivilegestrue [Install] WantedBymulti-user.target EOF几个关键点解释一下。EnvironmentFile用来加载刚才的密钥文件systemd 会在启动进程前把文件里的变量注入环境。Restarton-failure表示服务非正常退出时自动拉起RestartSec5是重启等待 5 秒避免疯狂重启占用 CPU。NoNewPrivilegestrue是安全加固项禁止进程获得新权限。然后刷新服务列表并启动systemctl daemon-reload systemctl enable --now hermes-agent systemctl status hermes-agent看到状态为active (running)后再确认端口是否在监听ss -lntp | grep 4150如果进程起来了但端口没有监听多半是配置监听地址写错或者 SELinux 拦截了端口绑定。查看详细日志journalctl -u hermes-agent -n 50SELinux 拦截时日志里会看到类似AVC denied的记录这时用前面装的 semanage 放行端口semanage port -a -t http_port_t -p tcp 4150这里把 4150 放行为 http_port_t 是常见做法因为 Hermes Agent 本身就是一个 HTTP 服务。如果你用的是非标准端口替换成自己的端口号即可。Agent 启动后可以用 curl 做一个简单的健康检查curl http://127.0.0.1:4150/health返回正常 JSON 响应说明 Agent 核心服务已就绪。4. 部署 Hermes-Web-UI 并关联 Agent4.1 安装 Web-UI 服务Web-UI 的安装方式和 Agent 类似同样从官方渠道下载对应的 Linux 版本包。按照之前的目录规范cd /opt/hermes curl -fL -o hermes-web-ui.tar.gz [官方Release提供的下载地址] tar xzf hermes-web-ui.tar.gz mv hermes-web-ui /opt/hermes/bin/创建 Web-UI 自己的配置文件server: listen: 127.0.0.1 port: 8020 agent: endpoint: http://127.0.0.1:4150 token: 与Agent配置中auth.token保持一致 storage: type: sqlite path: /var/lib/hermes/hermes-web-ui.db这里有一个常见误区Web-UI 配置里会有一个agent.token或类似字段用于调用 Agent API 时做认证。如果 Agent 那一边启用了 token 校验而 Web-UI 里没填或者填错界面上会出现登录成功但看不到任何 Agent 状态的现象。所以配置完毕后两边要互相核对。创建 systemd 服务cat /etc/systemd/system/hermes-web-ui.service EOF [Unit] DescriptionHermes Web UI Afternetwork-online.target hermes-agent.service Wantshermes-agent.service [Service] Typesimple Userhermes Grouphermes ExecStart/opt/hermes/bin/hermes-web-ui --config /etc/hermes/web-ui.yaml Restarton-failure RestartSec5 WorkingDirectory/var/lib/hermes NoNewPrivilegestrue [Install] WantedBymulti-user.target EOF启动并验证systemctl daemon-reload systemctl enable --now hermes-web-ui systemctl status hermes-web-ui curl http://127.0.0.1:8020/如果能看到 Web-UI 的页面 HTML 或接口响应说明服务已经正常。4.2 用 Nginx 反向代理暴露 Web 访问入口Web-UI 默认监听在 127.0.0.1 的 8020 端口外部无法直接访问这是安全设计。要对外提供服务我建议用 Nginx 做反向代理而不是直接把端口暴露出去。先安装 Nginxdnf install -y nginx然后写一个代理配置cat /etc/nginx/conf.d/hermes-web-ui.conf EOF server { listen 80; server_name your-server-ip-or-domain; location / { proxy_pass http://127.0.0.1:8020; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; client_max_body_size 10m; } } EOF注意proxy_http_version 1.1、Upgrade、Connection这三行配置不是可有可无的装饰。Hermes-Web-UI 和浏览器之间需要通过 WebSocket 长连接实时推送会话状态。如果 Nginx 没转发 Upgrade 头WebSocket 握手会失败表现出来的症状是页面能打开但会话状态不刷新、操作无响应非常像“Agent 挂了”实际上是代理层的锅。检查 Nginx 配置并启动nginx -t systemctl enable --now nginx防火墙放行 HTTPfirewall-cmd --permanent --add-servicehttp firewall-cmd --reload如果你的服务器只监听默认的 80 端口且跑在受信内网可以这样够用。如果要上 HTTPS建议用 certbot 自动申请证书这里不多展开。4.3 首次登录、创建管理员与模型配置Web-UI 启动后浏览器访问http://你的服务器IP/第一次打开会要求初始化管理员账号。不同版本的初始化方式不同有的版本是直接在页面上设置第一个用户有的版本需要到服务端执行一条命令行/opt/hermes/bin/hermes-web-ui create-admin --username admin --password 你的密码如果执行之后页面还是无法登录检查是不是服务运行用户与命令行用户不一致导致数据库权限错乱。可以统一在 hermes 用户下执行su -s /bin/bash hermes -c /opt/hermes/bin/hermes-web-ui create-admin --username admin或者干脆手动修改数据库sqlite3 /var/lib/hermes/hermes-web-ui.db不过不建议直接改数据库初始化命令失败时优先看日志找原因不要动不动就动底层数据。登录到 Web-UI 后进入模型设置页面配置远端模型 API。以阿里百炼这类 OpenAI 兼容接口为例需要填写三样东西接口地址、API Key、模型名称。接口地址一般是https://对应服务商域名/v1模型名称填具体的模型标识API Key 填你在服务商控制台创建的密钥。保存之后最好在 Web-UI 里发一条测试消息确认 Agent 能正常调用模型。如果测试时提示 401 或超时不要急着怀疑 Web-UI先从最简单的链路排查先在服务器命令行用 curl 直接访问模型服务确认密钥有效再检查 Agent 配置文件里的 base_url 是否正确最后看 Web-UI 传给 Agent 的 token 是否一致。三层按顺序排查五分钟内基本能定位问题。5. 常见问题与排障记录5.1 Hermes-Web-UI 会话老是丢失先检查存储与WebSocket“会话老是丢”是社区里被问得最多的问题。我自己的经验是90% 的情况不是 Hermes 真的丢了数据而是以下三个原因之一。第一个是 Web-UI 的存储目录没有持久化或权限不对。如果你启动的是容器版没有把 /var/lib/hermes 挂载到宿主机容器一重建数据就全没了如果是原生安装检查 hermes 用户对 SQLite 文件是否有写权限。排查命令ls -l /var/lib/hermes/ sqlite3 /var/lib/hermes/hermes-web-ui.db .tables如果提示unable to open database file基本就是权限问题执行chown -R hermes:hermes /var/lib/hermes第二个原因是前端会话记录保存在了浏览器的 localStorage 里本身就不稳定。有些版本的 UI 会把会话列表缓存在浏览器本地当你换了一台电脑、换了一个浏览器、或者浏览器清理了站点数据历史会话就看着像“丢”了。要避免这种误判关键是确认服务端 SQLite 里到底有没有数据。只要库里在换浏览器后重新登录应该还能看到历史会话。第三个原因就是我在 Nginx 配置里反复强调的 WebSocket 代理问题。如果升级头没配好页面上的会话新建后会短暂显示刷新后列表空掉或者一直在转圈。可以打开浏览器开发者工具切到 Network 面板观察是否存在 ws 请求连接失败。如果失败基本就是 Nginx 代理层把长连接折腾断了回头检查我那三行配置确认无误后执行nginx -s reload。5.2 Agent 安装器要登录网站、桌面版报错是什么情况有朋友反馈在服务器上下载了 Agent 安装包运行时提示要求先登录网站或者桌面版安装时直接报错退出。根据我了解到的情况这里通常是下载错了包。Hermes 官方提供的下载渠道里一部分安装包是图形化的桌面版安装器这种安装器面向有桌面的个人电脑在首次运行时可能要求交互式认证或引导登录这在纯命令行服务器上无法满足。另一种情况是部分增强功能包需要登录账号后才能拉取 token这时候安装器会卡在登录步骤提示你去网站完成授权。解决办法很简单安装服务器版时选择不带 “desktop” 字样的 headless 包或命令行工具包这类包解压后直接就是一个二进制文件加配置文件完全不需要图形交互更不需要登录网站。如果非要使用桌面版的某些功能建议在一台有图形界面的工作站上安装好再通过服务方式同步配置——但一般情况下服务器环境用不到这些桌面能力。至于桌面版安装报错最常见的原因是缺少图形库。命令行环境下如果强行执行 GUI 安装器经常会报缺少 libX11、libgtk-3 之类的依赖。检查方式ldd 安装程序路径 | grep not found输出中凡是标注 not found 的都是缺失的库。纯服务器环境没必要去补齐这些图形库直接换 headless 包就是最干净的解决方案。5.3 改错系统配置进不了系统Rocky Linux 单用户模式恢复这一节看似和 Hermes 无关但实际操作中非常容易触发。比如你在配置静态 IP 或防火墙时不小心把 SSH 服务所在网段拦掉了或者把 Agent/Web-UI 的服务配置写错导致系统启动异常这时候就需要进入单用户模式rescue 模式去修复。Rocky Linux 9 进入单用户模式的方法重启服务器在 GRUB 引导菜单出现时按下键盘上的e键进入编辑模式。找到以linux开头的那一行在末尾添加systemd.unitrescue.target然后按Ctrl x启动系统会进入救援模式的 Shell。此时根文件系统默认是只读挂载的需要重新挂载为可写才能修改配置mount -o remount,rw /接下来就可以用 vi 或者 nmcli 修正网络配置、注释掉错误的 systemd 单元文件等。修复完成后直接执行reboot如果是远程服务器并且连 SSH 都进不去但云服务商提供了 VNC 控制台这个方法也同样适用。单用户模式是最后的系统级救援手段不要轻易在业务高峰期测试但建议提前演练一遍真出事的时候你不会希望一边看文档一边手忙脚乱。5.4 常见错误速查表现象可能原因解决办法Agent 服务启动后立刻退出配置文件语法错误或端口被占用用journalctl -u hermes-agent查看日志用ss -lntp检查端口占用数据库目录不可写服务反复重启/var/lib/hermes 属主不是 hermeschown -R hermes:hermes /var/lib/hermesWeb-UI 页面打不开Nginx 未启动或代理配置错误systemctl status nginx、nginx -tWebSocket 连接失败Nginx 未转发 Upgrade 头在 location 块中加入proxy_set_header Upgrade $http_upgrade等配置会话列表在换浏览器后消失会话缓存仅存在于浏览器并非服务端持久化检查服务端 SQLite 中是否有数据重新配置统一存储路径模型调用报 401API Key 错误或环境变量未加载确认 hermes.env 文件内容、EnvironmentFile路径是否正确使用systemctl daemon-reload后重启防火墙开放了端口仍然访问不了SELinux 拦截使用semanage port -a -t http_port_t -p tcp添加端口策略这张表是我这段时间实操下来用得最多的一份速查清单。遇到问题不要一上来就卸载重装先看日志、再看存储权限、最后查网络策略绝大多数问题都能在这个框架内解决。5.5 我实际操作中的一点建议善用快照与备份最后分享一个习惯。我在把 Hermes 整套环境跑通之后第一件事就是对系统盘和 /var/lib/hermes 目录分别做了一次快照。Linux 服务器上没有云平台快照功能时至少用 tar 把配置目录备份出来tar czf /root/hermes-backup-$(date %F).tar.gz /etc/hermes /var/lib/hermes这个备份文件很小通常也就几十 MB但对排查问题帮助极大。我遇到过几次因为调试配置导致数据错乱的情况正是靠这份备份在几分钟内恢复了可用状态。比起在论坛上求助等回复自己手里有备份永远是最快的救急方案。这套流程走完以后无论是升级 Hermes 版本还是调整模型接入都可以先备份再操作稳得多。