news 2026/9/5 20:34:47

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

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
Rocky Linux部署Hermes Agent与Web-UI完整指南

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 开发包）需要额外启用 CRB（CodeReady 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|^#baseurl=http://dl.rockylinux.org/$contentdir|baseurl=https://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-port=8080/tcp firewall-cmd --reload # 查看放行结果 firewall-cmd --list-ports

SELinux 一般不会完全挡住 Agent 的安装，但如果 Agent 要监听非标准端口或者写某些特殊路径，可能会被 SELinux 策略拦截。技术好的做法是针对性放行，但为了快速部署，我通常在测试环境将 SELinux 设为 permissive：

setenforce 0 sed -i 's/^SELINUX=enforcing/SELINUX=permissive/' /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/hermes

4.2 配置文件修改：Server 地址、Token、工作目录一个都不能错

Agent 的配置集中在agent.yaml或类似文件里，核心参数一般有以下这些：

参数名含义建议值
server_urlWeb-UI 服务端地址http://192.168.1.10:8080
token注册令牌，Web-UI 里生成安装后从 Web-UI 获取
node_name节点显示名建议用主机名加后缀
work_dir工作目录/var/lib/hermes
log_level日志级别info或debug
heartbeat_interval心跳上报间隔默认 30s 或 60s

修改完配置后，可以先用命令行前台运行一次，确认能正常连上 Web-UI：

sudo -u hermes /opt/hermes/bin/hermes-agent -c /opt/hermes/config/agent.yaml

如果一切正常，日志里会显示注册成功和心跳发送信息。此时不要急着关，按 Ctrl+C 停掉，再用 systemd 托管。

4.3 写成 systemd 服务，实现开机自启和日志统一收集

前台跑只是验证。正式环境必须用 systemd 管理，这样 Agent 崩了能自动重启，还能用journalctl看日志。

在/etc/systemd/system/hermes-agent.service写入：

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

然后执行：

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

如果状态显示 active (running)，说明 Agent 已经作为服务稳定运行了。我的习惯是再检查一下心跳日志，确认 Web-UI 端能看到节点上线：

journalctl -u hermes-agent -f

4.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_LISTEN=0.0.0.0:8080 export HERMES_WEB_DATA_DIR=/var/lib/hermes-web-ui export HERMES_WEB_TOKEN_SECRET=your-strong-secret ./hermes-web-ui

TOKEN_SECRET必须设置，否则登录态和令牌容易出问题。热搜里“我的hermes-web-ui的会话老是丢失”很可能就是因为这个值没固定，重启服务后 session 失效，或者用了默认值。

5.2 systemd 托管 Web-UI 服务

和 Agent 类似，Web-UI 也建议用 systemd 托管。我通常写这样的 service 文件：

[Unit] Description=Hermes Web UI Service After=network.target [Service] User=hermes Group=hermes Environment=HERMES_WEB_LISTEN=0.0.0.0:8080 Environment=HERMES_WEB_DATA_DIR=/var/lib/hermes-web-ui Environment=HERMES_WEB_TOKEN_SECRET=your-strong-secret ExecStart=/opt/hermes/hermes-web-ui/hermes-web-ui Restart=on-failure RestartSec=5s [Install] WantedBy=multi-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.com

5.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的会话老是丢失”，我在实际测试中遇到过不止一次。总结下来主要有这几个原因：

  1. TOKEN_SECRET 未固定：Web-UI 重启后生成新的 session 密钥，所有旧会话失效，表现为“又需要重新登录”。
  2. 数据目录权限不对：Web-UI 无法写会话存储目录，session 无法持久化到磁盘。
  3. 通过多个域名/IP 访问：浏览器端 cookie 的 domain 属性变化导致会话丢失。
  4. 反向代理没有透传 X-Forwarded-Proto：HTTPS 和 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检查依赖，重新生成 token
Web-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 托管，并且统一加Restart=on-failure，Agent 或 Web-UI 意外退出能自动恢复，省去很多半夜被叫醒的麻烦。

第二，配置目录单独用/etc/hermes管理，数据目录用/var/lib/hermes，不要把配置扔在解压目录里。这样升级时只需要保留这两个目录即可。

第三，日志一定要接统一采集。可以用journalctl本地看，也可以把日志转发到集中平台。Agent 和 Web-UI 的日志格式都比较规整，适合做关键字告警。

第四，token 和密码这类敏感信息别写死在agent.yaml里，至少在文件权限上做好控制：

chmod 600 /etc/hermes/agent.yaml

最后，部署完成之后，记得做一次完整的重启验证：重启服务器后，检查 Agent 和 Web-UI 是否自动拉起、节点是否自动重新上报。这一步能提前暴露很多问题，别等真出故障了再临时抱佛脚。

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/5 20:34:20

Rocky Linux部署Hermes Agent与Web-UI实战：安装、避坑与调优

1. 先说清楚&#xff1a;为什么是 Rocky Linux&#xff0c;为什么要装 Hermes Agent很多朋友第一次接触 Hermes Agent 和 Hermes-Web-UI&#xff0c;都是听同事推荐或者逛开源社区时看到的。我最初也是抱着“试试看”的心态在虚拟机里折腾&#xff0c;结果一路装下来发现坑并不…

作者头像 李华
网站建设 2026/9/5 20:33:44

硬件工程师入门三件套：Buck、Buckboost与BLDC驱动实战解析

硬件入门先练什么&#xff1f;我第一次见这句话是在评论区&#xff0c;原话大概是&#xff1a;能自己画板、调通一块 buck 降压&#xff0c;再做一块双向 buckboost&#xff0c;最后能转起一台无刷电机&#xff0c;整个电源和驱动的底子基本就稳了。后来面试硬件岗也遇到过类似…

作者头像 李华
网站建设 2026/9/5 20:24:24

基于Flask与Neo4j构建三国人物知识图谱：从数据抽取到可视化问答

简介&#xff1a;这是一套面向Python初学者与知识图谱入门者的实战项目资源&#xff0c;基于Flask框架构建三国演义人物关系可视化及智能问答系统&#xff0c;解决古典文学数据结构化分析与交互式探索的实际问题。资源包共364个文件&#xff0c;含12个核心Python脚本&#xff0…

作者头像 李华