1. 部署前必须想清楚的事这套组合到底解决什么问题先说结论如果你正在管理一批 Rocky Linux 服务器又希望在主机上挂一个能统一观察、下发指令、保存执行记录的轻量级 Agent同时配一个网页端来操作那么 Hermes Agent 加 Hermes-Web-UI 这套组合是目前比较省心的方案。它的价值不在于某个单点功能有多炫而在于把“服务器上跑 Agent”和“浏览器里看结果”这两件事彻底打通了省去了来回 SSH 敲命令、翻日志的麻烦。我最早接触 Hermes Agent 是在一次批量服务器巡检的需求里。当时手上有十几台 Rocky Linux 8.10 的机器每台都要装监控脚本、定时任务、日志采集器靠人肉一台台处理显然不现实。后来用了 Hermes Agent 做统一注册和管理配合 Hermes-Web-UI 在浏览器里看每个节点的状态和执行结果整个维护效率明显提升。这里要强调一下Hermes Agent 本身是一个执行侧的工具它负责在宿主机上注册服务、执行任务、回传结果而 Hermes-Web-UI 是配套的可视化控制台负责把 Agent 上报的数据变成你能看懂的面板。两者必须配合使用缺一个都不完整。这篇文章适合谁来参考一类是 Rocky Linux 的运维人员正在为服务器批量管理发愁另一类是刚接触 Hermes 生态、想快速搭一个 Agent 实验环境的学习者。我会尽量把每一步都写清楚包括前置准备、安装细节、配置陷阱和典型故障排查尽量让你照着做就能跑起来不用来回翻文档。2. 版本与选型Rocky Linux 版本、Hermes 组件版本怎么搭配2.1 Rocky Linux 版本的选型思路Rocky Linux 目前常见的有 8.x 和 9.x 两个大版本。从实际部署来看8.10 和 9.6 我都跑过整体差异不大但有几个细节需要注意。8.10 的 yum 源问题8.x 系列已经进入维护周期的后期默认的 mirrorlist 源偶尔会出现失效或同步延迟的情况。如果你在安装依赖时遇到“无法解析主机名”或者“404 找不到 repo”建议第一时间检查源配置换成可用的镜像源。9.x 的默认仓库策略Rocky 9 默认启用的是 AppStream 和 BaseOS 仓库很多开发库比如编译工具链、Python 开发包需要额外启用 CRBCodeReady Builder仓库才能安装。这一点在部署 Hermes Agent 时尤其关键因为 Agent 编译或运行依赖的某些库比如 libunwind、ICU可能就在 CRB 里。新老版本对 systemd 服务的兼容性Rocky 9 的 systemd 版本比 8.x 新对服务的资源限制、日志管理机制有调整。如果你的 Agent 配置里写了老式的资源限制参数在 9.x 上可能会报 warning但不影响启动。我自己常用的组合是生产环境用 Rocky 9.6全新部署老环境保留 8.10尽量不动。如果你是从零开始学直接上 9.6 就行省得后面踩源失效的坑。2.2 Hermes Agent 与 Web-UI 版本匹配Hermes 这套生态迭代速度不慢Agent 和 Web-UI 的版本如果差距过大可能出现 Agent 上报的数据格式不兼容、Web-UI 解析失败或直接白屏。我的建议是优先下载同批次发布的 Agent 和 Web-UI 版本。官方仓库里一般会标明 release tag比如 v0.7.x 的 Agent 配 v0.7.x 的 Web-UI。安装前先看 release notes确认有没有强制升级提示。我在一次测试中遇到过 Agent 升到新版本后旧版 Web-UI 完全无法显示节点列表最后是对齐了版本才恢复。如果官网下载页需要登录或跳转验证属于正常流程按提示注册一个账号即可。这里插一句社区里很多人在问“hermes agent安装要登录网站怎么回事”其实就是官方把安装包的下载放到了需要认证的渠道避免滥用不是故障。2.3 网络镜像源的准备既然热搜词里出现了“rocky linux 8.10 yum源”和“rocky linux设置静态ip”说明很多人卡在了部署前的环境准备。我建议在安装 Hermes Agent 之前先把系统源和基础网络环境搞定。以 Rocky 9.6 为例我一般会先备份原有的 repo 文件再替换成可用的国内镜像源。操作很简单sed -e s|^mirrorlist|#mirrorlist|g \ -e s|^#baseurlhttp://dl.rockylinux.org/$contentdir|baseurlhttps://mirrors.aliyun.com/rockylinux|g \ -i.bak /etc/yum.repos.d/rocky*.repo替换后执行dnf clean all dnf makecache对于 Rocky 8.10方法类似但要确认镜像站有没有同步对应的 8.10 目录。如果源没问题后面装依赖就会顺利很多。3. 环境准备静态 IP、防火墙与基础依赖一次性搞定3.1 设置静态 IP 的正确姿势热搜词里有一条“rocky linux设置静态ip”这其实是很多新手部署 Agent 时踩的第一个坑。因为 Agent 需要被 Web-UI 反连或主动上报如果服务器 IP 经常变化节点列表里就会出现一堆失联状态。Rocky Linux 默认使用 NetworkManager 管理网络。设置静态 IP 有两种方式用 nmcli 命令行或者直接改网卡配置文件。我用 nmcli 比较多因为命令简洁且不会写错# 查看网卡名称通常是 ens160、ens192 或 eth0 nmcli connection show # 修改连接为静态 IP假设网卡名是 ens160 nmcli connection modify ens160 ipv4.method manual \ ipv4.addresses 192.168.1.100/24 \ ipv4.gateway 192.168.1.1 \ ipv4.dns 223.5.5.5 8.8.8.8 # 重新加载并激活连接 nmcli connection up ens160修改完用ip addr show ens160验证一下再 ping 一下网关和外部地址确定网络通。注意如果服务器在云端网关和 DNS 要按云厂商的配置来不要照搬本地环境。3.2 防火墙与 SELinux两个最容易被忽略的拦截者Rocky Linux 默认可能开启了 firewalld而 Hermes Web-UI 默认监听某个端口比如 8080 或 3000。如果防火墙没放行浏览器永远打不开页面但你在服务器本地 curl 又是通的排查半天才发现是防火墙问题。我的建议是# 放行 Web-UI 端口假设端口为 8080 firewall-cmd --permanent --add-port8080/tcp firewall-cmd --reload # 查看放行结果 firewall-cmd --list-portsSELinux 一般不会完全挡住 Agent 的安装但如果 Agent 要监听非标准端口或者写某些特殊路径可能会被 SELinux 策略拦截。技术好的做法是针对性放行但为了快速部署我通常在测试环境将 SELinux 设为 permissivesetenforce 0 sed -i s/^SELINUXenforcing/SELINUXpermissive/ /etc/selinux/config生产环境不建议直接关闭 SELinux应该用ausearch和audit2allow生成对应策略。这里不过度展开后面如果有机会专门写一篇。3.3 基础依赖安装Hermes Agent 的核心依赖包括curl、wget、tar、Python 3、开发工具链gcc、make、以及一些运行库。不同版本依赖有差异最稳妥的方式是先把编译类工具装全dnf install -y curl wget tar gcc make python3 python3-pip \ libunwind-devel icu libicu-devel libuuid-devel \ openssl-devel pkgconfig对于 Rocky 9.x如果提示找不到 libunwind-devel可以先启用 CRB 仓库dnf config-manager --set-enabled crb然后再装。这里很容易漏很多人卡在“configure: error: Library requirements not met”之类的地方多半就是缺了这些开发库。4. 核心环节Hermes Agent 安装与注册全过程4.1 下载与解压注意认证和非 root 用户问题前面提到过Hermes Agent 的下载可能需要登录认证。这个属于官方渠道的正常流程不用怀疑。下载完成后我习惯把 Agent 解压到/opt/hermes这个目录方便统一管理。mkdir -p /opt/hermes cd /opt/hermes tar -xzf hermes-agent-linux-amd64.tar.gz解压后目录结构通常类似/opt/hermes/ ├── bin/ │ └── hermes-agent ├── config/ │ └── agent.yaml ├── scripts/ └── README.md这里要注意不建议以 root 用户直接运行 Agent虽然它能跑但安全性和后续权限管理都不好。我的做法是创建一个专用系统用户useradd -r -s /sbin/nologin hermes chown -R hermes:hermes /opt/hermes4.2 配置文件修改Server 地址、Token、工作目录一个都不能错Agent 的配置集中在agent.yaml或类似文件里核心参数一般有以下这些参数名含义建议值server_urlWeb-UI 服务端地址http://192.168.1.10:8080token注册令牌Web-UI 里生成安装后从 Web-UI 获取node_name节点显示名建议用主机名加后缀work_dir工作目录/var/lib/hermeslog_level日志级别info或debugheartbeat_interval心跳上报间隔默认 30s 或 60s修改完配置后可以先用命令行前台运行一次确认能正常连上 Web-UIsudo -u hermes /opt/hermes/bin/hermes-agent -c /opt/hermes/config/agent.yaml如果一切正常日志里会显示注册成功和心跳发送信息。此时不要急着关按 CtrlC 停掉再用 systemd 托管。4.3 写成 systemd 服务实现开机自启和日志统一收集前台跑只是验证。正式环境必须用 systemd 管理这样 Agent 崩了能自动重启还能用journalctl看日志。在/etc/systemd/system/hermes-agent.service写入[Unit] DescriptionHermes Agent Service Afternetwork-online.target Wantsnetwork-online.target [Service] Userhermes Grouphermes Typesimple WorkingDirectory/opt/hermes ExecStart/opt/hermes/bin/hermes-agent -c /opt/hermes/config/agent.yaml Restarton-failure RestartSec5s LimitNOFILE65535 [Install] WantedBymulti-user.target然后执行systemctl daemon-reload systemctl enable --now hermes-agent systemctl status hermes-agent如果状态显示 active (running)说明 Agent 已经作为服务稳定运行了。我的习惯是再检查一下心跳日志确认 Web-UI 端能看到节点上线journalctl -u hermes-agent -f4.4 Agent 桌面版的情况说明热搜里出现了“hermes agent桌面”和“hermes agent桌面版安装报错”。这里我说明一下桌面版和解压的 Linux 服务版是两种运行形态。桌面版通常在个人工作机上运行用于在图形界面里管理 Agent但它不是服务器场景的必需品。服务器环境直接用命令行版或 systemd 服务版足够了。如果桌面版安装报错我看过几个典型情况缺少 GUI 依赖库比如 Qt 或 GTK 相关组件安装路径带中文或空格导致启动脚本解析失败运行用户权限不足无法写配置目录安装包版本和系统 libc 不兼容一般出现在过旧版本的系统上。遇到报错先看日志文件通常信息足够直接。5. Hermes-Web-UI 部署与反向代理配置5.1 Web-UI 的运行方式Hermes-Web-UI 本质上是一个 Web 服务负责接收 Agent 的上报数据、展示节点状态、下发指令。部署方式一般有两种直接用预编译的二进制或 Node.js 运行以及通过容器。服务器资源有限时我更推荐直接用预编译二进制省内存、无额外依赖。假设我们下载的是预编译版本解压后通常有hermes-web-ui可执行文件和一个data目录。首次启动前需要设置监听地址、端口和数据存储目录mkdir -p /var/lib/hermes-web-ui chown -R hermes:hermes /var/lib/hermes-web-ui用环境变量或配置文件控制启动参数。以环境变量为例export HERMES_WEB_LISTEN0.0.0.0:8080 export HERMES_WEB_DATA_DIR/var/lib/hermes-web-ui export HERMES_WEB_TOKEN_SECRETyour-strong-secret ./hermes-web-uiTOKEN_SECRET必须设置否则登录态和令牌容易出问题。热搜里“我的hermes-web-ui的会话老是丢失”很可能就是因为这个值没固定重启服务后 session 失效或者用了默认值。5.2 systemd 托管 Web-UI 服务和 Agent 类似Web-UI 也建议用 systemd 托管。我通常写这样的 service 文件[Unit] DescriptionHermes Web UI Service Afternetwork.target [Service] Userhermes Grouphermes EnvironmentHERMES_WEB_LISTEN0.0.0.0:8080 EnvironmentHERMES_WEB_DATA_DIR/var/lib/hermes-web-ui EnvironmentHERMES_WEB_TOKEN_SECRETyour-strong-secret ExecStart/opt/hermes/hermes-web-ui/hermes-web-ui Restarton-failure RestartSec5s [Install] WantedBymulti-user.target这里建议把生产环境的监听地址绑定到内网 IP而不是 0.0.0.0。Web-UI 如果没有额外认证暴露到公网风险很高。阿里云等云服务器尤其要注意安全组策略。5.3 通过 Nginx 反向代理并启用 HTTPS如果团队习惯通过域名访问 Web-UI不推荐直接把服务端口暴露给人。用 Nginx 做反代更规范。Nginx 配置文件示例server { listen 80; server_name hermes.example.com; location / { proxy_pass http://127.0.0.1:8080; 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; } }重点在于Upgrade和Connection两个头Web-UI 通常需要 WebSocket 长连接来实时刷新节点状态和任务输出。少了这两行页面可能能打开但数据不更新看起来就像“卡住”了。HTTPS 证书方面可以用 certbot 自动申请和续期dnf install -y certbot python3-certbot-nginx certbot --nginx -d hermes.example.com5.4 初始化 Web-UI第一个用户的创建Web-UI 首次启动后浏览器访问域名或 IP:port会进入初始化页面。一般需要创建一个管理员账号。注意邮箱和密码要记好忘记密码处理起来挺麻烦。创建完成后在管理后台生成一个注册令牌token然后填到 Agent 的agent.yaml里。这一步是整个链路能否跑通的关键。我遇到过很多次 Agent 配置正确但连不上 Web-UI最后发现是 token 没复制完整或者在 Web-UI 里生成 token 后过期了。所以建议先创建账号再生成 token然后立刻去配置 Agent中间不要隔太久。6. 升级、保活与常见故障排查实录6.1 会话丢失问题排查token secret 和会话存储热搜里“hermes-web-ui的会话老是丢失”我在实际测试中遇到过不止一次。总结下来主要有这几个原因TOKEN_SECRET 未固定Web-UI 重启后生成新的 session 密钥所有旧会话失效表现为“又需要重新登录”。数据目录权限不对Web-UI 无法写会话存储目录session 无法持久化到磁盘。通过多个域名/IP 访问浏览器端 cookie 的 domain 属性变化导致会话丢失。反向代理没有透传 X-Forwarded-ProtoHTTPS 和 HTTP 混用时session 的 secure 属性判断出错。解决方法在 systemd 环境变量里固定HERMES_WEB_TOKEN_SECRET不要随默认值确认/var/lib/hermes-web-ui目录属主是运行 Web-UI 的用户尽量固定一个访问域名不要今天 IP 明天域名检查 Nginx 反代中的 X-Forwarded-Proto 是否存在。6.2 Agent 安装报错的几种典型场景报错“Failed to connect to server”优先排查防火墙和端口连通性用telnet server_ip 8080测试。报错“permission denied”多半是运行用户对工作目录没有写权限检查/opt/hermes和/var/lib/hermes属主。报错“library not found”缺少运行库。本机执行ldd /opt/hermes/bin/hermes-agent看到not found的库名再去装。报错“invalid token”重新去 Web-UI 生成 token确认时间同步正常Agent 与 Web-UI 时间偏差过大也可能导致认证失败。6.3 Agent 升级的姿势先备份后替换升级 Hermes Agent 时我习惯按以下步骤操作systemctl stop hermes-agent cp -r /opt/hermes /opt/hermes.bak # 解压新版本到 /opt/hermes保留 config 目录 tar -xzf hermes-agent-new.tar.gz -C /opt/hermes --overwrite # 如果有配置文件覆盖提醒先恢复备份中的 agent.yaml cp /opt/hermes.bak/config/agent.yaml /opt/hermes/config/agent.yaml chown -R hermes:hermes /opt/hermes systemctl start hermes-agent journalctl -u hermes-agent -n 50注意新版本可能会引入新配置项建议启动后看日志确认没有警告。配置文件和二进制分开备份避免升级把自定义配置冲掉。6.4 常见问题速查表问题现象可能原因解决方法Agent 启动即退出缺少运行库或 token 无效ldd检查依赖重新生成 tokenWeb-UI 页面打不开防火墙未放行端口firewall-cmd --add-port页面能开但数据不刷新WebSocket 未透传Nginx 配置 Upgrade / Connection 头会话老是丢失Token Secret 不固定环境变量固定TOKEN_SECRET节点显示离线心跳间隔过长或 Agent 挂了检查 systemd 状态和日志安装依赖时 404yum 源失效替换镜像源并 makecache桌面版安装报错缺 GUI 依赖或权限不足检查系统库和运行用户7. 我踩过的坑以及最后的几条实操建议这套环境从零到稳定运行我前后在几台机器上折腾过。最明显的感受是安装本身不复杂但环境差异会带来一堆意料之外的小问题。比如 Rocky 9 的 CRB 仓库没启用导致编译库装不全又比如 Web-UI 的 token secret 没固定重启一次服务所有节点会话全部掉线。这些问题单独看都不难但串联起来最耗时间。最后分享几个我觉得很管用的习惯第一所有组件都用 systemd 托管并且统一加Restarton-failureAgent 或 Web-UI 意外退出能自动恢复省去很多半夜被叫醒的麻烦。第二配置目录单独用/etc/hermes管理数据目录用/var/lib/hermes不要把配置扔在解压目录里。这样升级时只需要保留这两个目录即可。第三日志一定要接统一采集。可以用journalctl本地看也可以把日志转发到集中平台。Agent 和 Web-UI 的日志格式都比较规整适合做关键字告警。第四token 和密码这类敏感信息别写死在agent.yaml里至少在文件权限上做好控制chmod 600 /etc/hermes/agent.yaml最后部署完成之后记得做一次完整的重启验证重启服务器后检查 Agent 和 Web-UI 是否自动拉起、节点是否自动重新上报。这一步能提前暴露很多问题别等真出故障了再临时抱佛脚。