1. 先说清楚为什么是 Rocky Linux为什么要装 Hermes Agent很多朋友第一次接触 Hermes Agent 和 Hermes-Web-UI都是听同事推荐或者逛开源社区时看到的。我最初也是抱着“试试看”的心态在虚拟机里折腾结果一路装下来发现坑并不少。为了避免大家走了弯路这篇就把我完整跑通的安装过程、踩坑记录和最终调优经验都整理出来。先给没接触过的朋友解释一下这两个东西是什么。Hermes Agent 是一个轻量级的设备管理/监控代理端它在你需要纳管的服务器上运行负责采集主机的运行状态、执行指令、同步配置、对接上层的管理平台而 Hermes-Web-UI 则是配套的 Web 控制台用来统一查看所有 Agent 上报的数据在网页上管理设备、下发任务、查看告警和日志。简单来说一个管“端”一个管“面”两者配合起来就构成了一套完整的服务器集群管理闭环。它解决的典型问题包括几十台机器装了同一个服务版本漂移、配置不一致、没法统一看资源占用等情况。为什么选 Rocky Linux因为 CentOS 8 停止维护之后很多生产环境的运维朋友都在找替代品Rocky Linux 是国际上认可度较高的 CentOS 兼容发行版之一。它的软件包管理方式、服务管理方式、目录结构都和传统 RHEL 系基本一致迁移成本很低。如果你以前写过 CentOS 的 systemd 服务和 firewalld 规则切到 Rocky 几乎不需要重新学习。这篇教程就以 Rocky Linux 为基础环境默认读者使用的是 x86_64 架构如果用的是 ARM 架构的机器个别软件包版本需要你自己留意一下。顺带提一句搜索热词里有个“bcoreos实战用一个升级包让 rocky linux 跑进 ubuntu 服务器”的说法。这个其实是另一种思路通过打包容器或者整个系统的可执行镜像把 Rocky 环境搬到其他发行版宿主上运行和本篇直接从官方源安装不是一条路线感兴趣的朋友可以把它理解为“便携化系统”方案。但如果你想在正式环境稳定使用我建议还是老老实实按本文的步骤来。在文章正式开始之前先给一个结论性的定心丸整个安装过程如果用官方仓库来装Hermes Agent 的安装包很小通常几十 MB 级别不会对系统造成什么负担Hermes-Web-UI 则是一个基于 Web 的服务端程序需要 Node.js 环境或配套运行时资源占用也不高。所以你在 2 核 4G 的入门级云主机上跑这两个组件是完全够用的。2. 环境准备里最容易翻车的三个细节静态 IP、镜像源、防火墙和 SELinuxRocky Linux 装 Hermes Agent最大的问题往往不是 Agent 本身而是系统初始环境没有收拾干净。很多人在装完系统后什么都不调直接就开始装软件然后遇到网络不通、源下载超时、服务起不来等问题回头才发现是基础配置出了问题。2.1 先给机器一个固定网络身份如果你是在虚拟机或者物理机上安装强烈建议先把 IP 配置成静态的。搜索热词里有“rocky linux设置静态ip”说明这确实是很多人卡住的第一步。Agent 安装后需要持续上报数据给 Web-UI 服务端如果 Agent 所在机器的 IP 是 DHCP 动态分配的一旦 IP 变了Web-UI 上记录的主机身份就会失效控制台里会出现主机离线或者重复注册的情况。Rocky Linux 使用的是 NetworkManager 管理网络配置静态 IP 最直接的方式是修改/etc/NetworkManager/system-connections/下的连接配置文件或者用nmcli命令。给一个最常用的nmcli示例# 查看当前网络连接名称一般是 ens33、eth0 之类 nmcli con show # 假设连接名是 ens33配置静态 IP nmcli con mod ens33 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 con down ens33 nmcli con up ens33 # 验证 ip addr show ens33这里建议 DNS 使用国内公共 DNS 加国际公共 DNS 的组合避免单一 DNS 故障导致域名解析失败。2.2 Rocky Linux 9 的 dnf 源问题官方源慢和网络源失效Rocky Linux 9.6 是个比较新的版本系统安装完默认使用的是 Rocky 官方镜像源。在国内服务器上官方源经常会出现连接慢、传输超时的情况。搜索热词里也出现了“rocky linux 8.10 yum源”和“rocky linux 9.6系统安装教程”说明很多人都在各版本之间跳转但都没弄明白源的问题。处理思路很简单把 dnf 源替换为国内镜像源。以 Rocky Linux 9 为例先备份系统默认源配置mkdir -p /etc/yum.repos.d/backup mv /etc/yum.repos.d/*.repo /etc/yum.repos.d/backup/然后创建新的源文件例如/etc/yum.repos.d/Rocky.repo内容可以参考国内镜像站提供的配置模板。注意 Rocky Linux 的源分为BaseOS、AppStream、extras等仓库全部要配置好否则后续安装依赖时会出现个别软件包找不到的情况。配置完成后执行dnf clean all dnf makecache提示修改源文件时务必把gpgcheck1保留并正确填写 GPG Key 的地址否则安装软件时会因为校验失败被拦截。2.3 防火墙和 SELinux 对端口访问的影响Rocky Linux 默认开启了 firewalld 服务和 SELinux。安装 Hermes-Web-UI 后服务会监听某个 TCP 端口比如 8080 或 3000。如果你的 Web-UI 和 Agent 不在同一台机器上Agent 要访问 Web-UI 的地址或者你要从本地浏览器访问 Web-UI都必须先把端口放行。不然后果是服务明明在跑日志也正常但外部就是连不上。放行端口的命令# 假设 Web-UI 使用的端口是 8080 firewall-cmd --permanent --add-port8080/tcp firewall-cmd --reload firewall-cmd --list-portsSELinux 的问题比较隐蔽。如果确认防火墙已经放行但仍然连不上可以查看 SELinux 的审计日志grep denied /var/log/audit/audit.log | tail -n 20如果看到类似avc: denied { name_connect }的记录说明 SELinux 阻止了服务的网络访问。临时放行可以用setsebool -P httpd_can_network_connect 1或者更直接地将整个服务上下文设为 permissive不推荐在生产长期使用setenforce 0一个更规范的做法是为服务编写自定义 SELinux 策略模块这个在正式生产环境中更稳妥但如果你只是测试环境先setenforce 0跑通流程再说也没问题。3. Hermes Agent 安装流程详解半自动化的“登录”是什么回事搜索热词里“hermes agent安装”“hermes agent安装要登录网站怎么回事”出现得比较频繁这里单独开一节说明。了解清楚安装逻辑你就不慌了。Hermes Agent 的安装模式通常会分两步走Agent 安装包落到机器上解压并安装为一个系统服务Agent 启动时需要一个“接入凭据”类似于设备接入码/Agent Token它需要和 Hermes-Web-UI 完成对接才能正常上报数据。很多人安装时遇到“要登录网站”的提示其实就是第二步的引导。某些版本的 Hermes Agent 在安装时会弹出一个登录验证页面要求你在浏览器里登录 Hermes-Web-UI 的后台账号然后自动生成这个设备本地的接入凭据。这属于“半自动安装模式”。3.1 用离线 Token 方式避免交互登录生产环境中大多数服务器没有图形界面也没有浏览器根本不可能“登录网站”。正确的做法是在 Hermes-Web-UI 的界面上提前创建一个“接入令牌”或者“设备分组密钥”然后在 Agent 安装时通过参数将它传进去跳过登录环节。以命令行安装为例大致的安装流程是这样的# 1. 下载 Agent 安装包 wget https://download.your-hermes-server.com/agent/hermes-agent-latest.x86_64.rpm # 2. 安装 RPM 包 dnf install -y ./hermes-agent-latest.x86_64.rpm # 3. 配置接入凭据 # 注意 token 是你在 Web-UI 后台生成的下面命令是示意 hermes-agent config --serverhttps://your-web-ui.example.com --tokenYOUR_AGENT_TOKEN # 4. 启动服务 systemctl enable --now hermes-agent不同的 Hermes Agent 版本命令行参数名可能略有差异有的用--apikey有的用--token有的用环境变量HERMES_AGENT_TOKEN。安装前先用hermes-agent --help查看一下当前版本支持的参数。3.2 桌面版安装报错的处理思路搜索热词里有“hermes agent桌面版安装报错”这多半是 Windows 桌面版或者带 GUI 的 Linux 桌面版安装时出现的问题。常见原因包括缺少 VC 运行库Windows 下最常见安装路径含中文或空格本地端口被占用杀毒软件误拦截。如果桌面版安装报错可以先看日志文件。Hermes Agent 的日志通常在安装目录的logs文件夹下或者在 Linux 的/var/log/hermes/下。报错信息里如果包含EACCES或者address already in use那就是端口被占或者权限不足手动换个端口或者用管理员权限安装即可。实际经验Windows 桌面版报错还有一个高发原因是“杀毒软件隔离了 Agent 的启动进程”。安装时先用管理员身份关闭实时防护装完再恢复基本就能解决。3.3 Agent 装完怎么验证它真的在干活安装完成后不能只看服务是 active 状态就觉得万事大吉。建议做以下几步验证# 1. 查看服务状态 systemctl status hermes-agent # 2. 检查进程是否存在 ps aux | grep hermes-agent # 3. 检查 Agent 日志看是否成功连上服务端 tail -f /var/log/hermes/agent.log在日志中如果看到类似connection established、registration successful、heartbeat sent之类的关键词说明 Agent 已经正常上报。接下来到 Hermes-Web-UI 的设备列表页你应该能看到这台新主机上线。如果显示离线多半是服务器地址填错了或者服务端端口没有放行。4. Hermes-Web-UI 的部署方式与配置重点Web-UI 的安装和 Agent 不同它属于“服务端”可以有多种部署方式。这里介绍两种最常见的方式一种是直接使用官方提供的安装脚本适用于快速体验另一种是使用 Docker 部署。4.1 官方安装脚本的坑和解决如果你的 Web-UI 也装在同一台 Rocky Linux 上官方文档一般会提供一键安装脚本比如curl -sSL https://get.your-hermes-server.com/ui/install.sh | bash这个脚本方便是方便但你执行之前最好先大致浏览一下脚本内容看看它默认安装到什么目录、用什么用户启动服务、会把哪些端口暴露出来。脚本安装完后Web-UI 一般会作为一个 systemd 服务跑起来服务名可能是hermes-webui或hermes-ui。脚本安装方式最容易出的问题是默认绑定的监听地址。有些版本默认监听127.0.0.1:8080只能在本地访问。要改成允许局域网访问需要修改配置文件里的host字段为0.0.0.0然后重启服务。4.2 Docker 部署方式更干净的隔离环境如果你不想让 Web-UI 的运行时依赖污染主机的系统环境Docker 是更好的选择。但前提是你的 Rocky Linux 上已经安装好了 Docker CE。Docker 安装可以参考官方仓库这里不展开。下面是 Hermes-Web-UI 的 docker-compose 示例version: 3.8 services: hermes-webui: image: your-registry/hermes-web-ui:latest container_name: hermes-webui restart: always ports: - 8080:8080 volumes: - hermes-data:/app/data - hermes-logs:/app/logs environment: - TZAsia/Shanghai - HERMES_DB_PATH/app/data/hermes.db volumes: hermes-data: hermes-logs:启动docker compose up -dDocker 方式的优势在于升级方便拉个新镜像重启容器就行数据目录独立在 volume 里重装容器不会丢数据。4.3 会话老是丢失的排查链路热搜词里有一条“我的hermes-web-ui的会话老是丢失”这个问题在实际使用中确实很影响体验典型表现是登录后台没过多久刷新页面就要求重新认证或者 Agent 上报一段时间后就断开连接Web-UI 里看不到实时数据了。这个问题的根源通常不在 Web-UI 本身而在于会话保持机制和网络链路。排查思路如下先区分是“人登录后台的会话”还是“Agent 与 Web-UI 的长连接会话”。如果你是指浏览器后台登录状态老是掉通常和 Web-UI 的会话过期时间、Cookie 配置、反向代理的缓存策略有关。如果你是指 Agent 上报数据断断续续、主机在控制台反复离线那属于长连接稳定性问题。检查 Web-UI 与 Agent 之间的网络稳定性。用ping和telnet测试端口连通性ping 目标Web-UI服务器IP telnet 目标Web-UI服务器IP 8080如果有丢包或者延迟剧烈波动Agent 的长连接自然保不住。检查 Web-UI 的会话超时配置。不同版本的 Hermes-Web-UI 配置项名称不同常见的有session-timeout、session.maxAge、token-expire。把它从默认的 30 分钟调成 24 小时能显著减少“会话丢失”的体感。如果你用了 Nginx 反向代理还要检查 Nginx 的proxy_read_timeout和proxy_send_timeout这两个值默认 60 秒如果后端有 WebSocket 长连接必须调大到 3600 以上否则连接会被 Nginx 掐断Agent 隔一阵子就会掉线重连表现为会话反复丢失。Nginx 关键配置示例location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 3600s; proxy_send_timeout 3600s; }如果 Web-UI 用的是 SQLite 数据库还要考虑并发锁的问题。当 Agent 数量较多、上报频率较高时SQLite 可能会出现database is locked错误导致 Web-UI 写入失败进而让会话数据无法持久化表现也是“会话丢失”。这种情况可以考虑切换为 PostgreSQL/MySQL 后端或者降低 Agent 的上报频率。排查链路总结成表格就是现象可能原因排查命令/位置解决方案浏览器后台频繁掉登录会话超时时间过短Web-UI 配置文件中的 session 字段调大 session-timeout控制台主机反复离线长连接被 Nginx 掐断Nginx error.log调大 proxy_read_timeout服务端日志频繁报错SQLite 锁冲突Web-UI 日志换 PostgreSQL/降低上报频率网页间歇性无法打开本地端口被占用或服务内存不足ss -lntp/free -h换端口/扩容或清理内存当时我排查自己的 Web-UI 会话丢失问题时卡得最久的就是 Nginx 反代的 WebSocket 升级头没有配置导致 Agent 的连接断断续续。这个问题很隐蔽因为用curl测试 HTTP 访问是完全正常的只有长连接会断。如果你也是用 Nginx 反代部署 Web-UI务必检查上面那段配置里的Connection upgrade这是最容易被漏掉的地方。5. 配置好 Agent 规则与告警后必须做的功能验证Web-UI 部署完成、Agent 接入成功之后安装工作还差最后一步验证核心功能有效。很多人装完就以为结束了结果过了一个月打开控制台发现一条告警都没有后来才知道采集规则根本没有下发成功。5.1 配置采集规则在 Hermes-Web-UI 的后台界面一般会有一个“采集配置”或“规则管理”的入口。在这里可以新增规则例如采集 CPU 使用率、内存使用率、磁盘空间、指定端口存活状态、自定义日志关键字等。规则的执行频率建议先从 60 秒开始不要贪图实时性设置成 1 秒否则 Agent 数量上来之后 Web-UI 的写入压力会指数级增长。每个 Agent 每 60 秒上报一次10 台 Agent 就是每秒约 0.17 次写入100 台就是 1.7 次这个量级 SQLite 还能扛住但如果每 5 秒上报一次100 台 Agent 就是每秒 20 次写入SQLite 很容易成为瓶颈。所以规则粒度要合理既能满足监控需求又不至于拖垮服务端。5.2 验证告警通路配置完采集规则后手动构造一个异常事件来验证告警链路是值得做的步骤。例如# 故意停掉一个被监控的服务 systemctl stop sshd # 或者向被监控的日志文件写入一条 ERROR 级内容 echo ERROR this is a test alert /var/log/app/test.log然后到 Web-UI 查看是否触发了告警、是否收到了邮件/钉钉/Webhook 通知。如果没有收到通知优先检查 Web-UI 的告警通道配置——SMTP 服务器、Webhook 地址、告警接收人列表是否填写完整。5.3 规则热更新是否要重启 Agent一个比较实际的问题是每次调整采集规则是不是都要重启 Agent答案取决于 Hermes Agent 的实现机制。部分版本的 Agent 支持“配置热加载”只要服务端下发新规则Agent 会在下一个心跳周期自动拉取并生效不需要重启。但有些早期的版本需要重启 Agent 才能刷新规则。我的建议是如果 Agent 支持热更新就在 Web-UI 上修改配置后等待一个心跳周期一般是 1~2 分钟观察日志变化如果不确定当前版本是否支持直接重启一次 Agent 也不会有任何损失systemctl restart hermes-agent总比配置半天发现没生效强。6. 长期运行的稳定性调优与常见故障速查现在系统已经跑起来了Agent 在线、Web-UI 可见、告警能收到。但在后续的长期运行中你还会碰到一些频率不低的问题。这里把我和身边朋友实际遇到过的典型情况整理成一个速查表并按运维优先级排序。6.1 资源占用异常排查有一次我发现自己的一台 Rocky Linux 服务器 CPU 占用一直居高不下top 一看hermes-agent进程占了 120% 的 CPU。查日志发现是 Agent 在反复尝试连接一个已经失效的 Web-UI 地址每次连接超时都要等 30 秒然后退避重试导致 CPU 空转。解决办法很简单重新运行hermes-agent config --server正确的Web-UI地址然后重启服务。如果你也碰到 Agent 进程 CPU 资源占用过高的问题检查顺序是查看 Agent 连接的服务端地址是否还能正常访问检查采集规则是否过于密集例如同时配置了多个 1 秒级高频采集查看日志中是否有大量网络重试记录。如果是规则过密调大采集时间间隔即可如果是连接不可达修好网络地址后重启服务CPU 会立刻降下来。6.2 Web-UI 日志文件撑爆磁盘Web-UI 长时间运行后日志目录下的文件会持续增长。/app/logs或/var/log/hermes-webui/下经常躺着好几个 GB 的日志文件。这是因为默认的日志轮转策略没有生效。建议配置 logrotate以 Rocky 自带的 logrotate 为例创建文件/etc/logrotate.d/hermes-webui/var/log/hermes-webui/*.log { daily rotate 14 compress delaycompress missingok notifempty copytruncate }然后运行logrotate -f /etc/logrotate.d/hermes-webui这样日志保留 14 天按天滚动压缩基本不会出现日志撑爆分区的问题。Agent 端的日志同理如果长期不清理某些版本的 Agent 也可能把/var/log/hermes目录写满特别是开启了 debug 模式之后日志增长速度非常快。6.3 Agent 状态显示离线但进程还活着这类问题最迷惑人systemctl status hermes-agent显示 active进程也在但 Web-UI 上就是显示离线。我用一个排查流程来解决这类困扰先看 Agent 日志搜索heartbeat或者last heartbeat关键字确认 Agent 的自身心跳是否正常用tcpdump或ss -tnp查看 Agent 是否有到 Web-UI 端口的实际 TCP 连接。例如ss -tnp | grep 8080确认是 Agent 根本没在发请求如服务端地址配错还是发了请求但服务端没收到如网络中间被防火墙丢包如果两者都不是试用curl手动请求 Web-UI 的健康检查接口确认 Web-UI 的 API 是否还能正常响应curl http://127.0.0.1:8080/healthz很多所谓的“离线”本质是 Web-UI 的 API 服务假死进程在但线程池满了不响应这时候重启 Web-UI 服务而不是重启 Agent 就能恢复整个链路。6.4 升级版本时的注意事项Hermes Agent 和 Web-UI 的升级策略不太一样。Agent 端升级通常直接下载新版本 RPM 包覆盖安装然后重启服务即可dnf install -y ./hermes-agent-new-version.x86_64.rpm systemctl restart hermes-agentWeb-UI 端如果是 Docker 部署升级也只是拉新镜像、重建容器但要留意数据库的兼容性。升级前先备份数据卷或数据库文件特别是跨大版本升级时有些版本的 Web-UI 会更新数据库 schema老数据可能有兼容风险。经验之谈升级 Agent 之前最好不要同时升级 Web-UI。先升级 Web-UI 并确认数据库迁移成功再逐个升级 Agent这样即使升级后出现不兼容也能快速判断是哪一侧出了问题。7. 几个值得养成的好习惯备份、别名和例行检查如果上面的安装与验证都做完了这篇文章的核心内容其实已经结束。但根据我实际运维小半年的经验最后再补充几个可能不会出现在官方文档里的习惯能让你在后续使用中少很多麻烦。第一个习惯是定期备份 Web-UI 的数据库。如果你用的是 Docker volume 里的 SQLite 文件一条命令就能完成快照式备份docker exec hermes-webui cp /app/data/hermes.db /app/data/hermes.db.bak docker cp hermes-webui:/app/data/hermes.db.bak /backup/hermes-$(date %F).db用 Cron 定时每天执行一次出现误删主机或规则被改坏的场景时恢复数据的成本会低很多。第二个习惯是给常用的排查命令设置别名无脑减少敲键盘的时间比如alias hlogtail -f /var/log/hermes/agent.log alias huilogtail -f /var/log/hermes-webui/webui.log alias hstatussystemctl status hermes-agent hermes-webui写到~/.bashrc里重启 shell 后直接hstatus就能一次性看到两个服务的运行状态。第三个习惯是每周快速巡检一次。我的做法是写一个 10 行 shell 脚本依次检查服务状态、磁盘占用、Agent 最近心跳时间、Web-UI API 健康检查然后输出一个简短报表。不需要复杂的监控平台对于小规模集群来说人肉巡检配合邮件告警已经足够了。这套 Rocky Linux 安装 Hermes Agent 与 Hermes-Web-UI 的组合稳定运行后基本不需要频繁人工干预维护成本相当低。真正费神的时刻都集中在首次部署后的前两周把规则配好、把网络调顺、把会话保持搞定后面的使用体验非常顺畅。如果你照着本文搭建时在其他细节上卡住优先看日志其次看网络链路大部分问题都能以“日志里有没有 specific 报错”为切入点定位出来。
