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

如果你要在 Rocky Linux 上部署一套带 Web 管理界面的 Agent 服务，Hermes Agent 和 Hermes-Web-UI 这套组合值得认真对待。Agent 负责在节点上跑任务、采集数据、上报心跳，Web-UI 则把这些节点、任务、告警统一收口到一个浏览器页面里，不用每台机器都 SSH 上去敲命令。这篇文章把我个人在 Rocky Linux 8.10 和 9.6 上从零装完这整套服务的实操过程完整记录下来，包括系统初始化、静态 IP、yum 源、Agent 安装、Web-UI 部署、反向代理，以及我踩过的几个印象深刻的坑。不管你是刚接触 Rocky Linux 的新手，还是准备把 Agent 类组件迁到 Rocky 上的运维老手，这套流程都能直接照着走。

1. 装这套东西之前，先把系统底层收拾干净

很多人在 Rocky Linux 上装完 Agent 起不来，回头查原因，发现根本不是 Agent 的问题，而是系统基础环境没弄好。我建议所有步骤开始之前，先把系统层面这几件事处理完，后面能省掉一大半排错时间。

1.1 选择 Rocky Linux 8 还是 9：先看依赖要求

Rocky Linux 8 对应的是 EL8 生态，软件包和库版本偏稳，适合跑一些基于旧版 glibc 编译的二进制。Rocky Linux 9 对应的是 EL9 生态，glibc、OpenSSL、Python、Node.js 这些基础组件的版本都要新不少。

我的建议是：如果是全新部署，优先选 9.x，支持周期更长，Python 3.9+、Node.js 18+ 都在官方源里，省去自己编译的麻烦。如果是存量环境或者 Agent 包明确标注只支持 EL8，那就在 8.10 上装。判断系统版本只需要一条命令：

cat /etc/redhat-release

1.2 配置 yum 源：8.10 和 9.6 的换源思路

Rocky Linux 装完系统后，默认的官方源在国内拉取速度通常不太理想，建议直接换到国内镜像站。这里有个关键点：8.10 和 9.6 的 yum 源路径不一样，直接套用网上旧脚本经常会遇到 404。

以阿里云镜像为例，8.10 的 BaseOS 仓库地址大致是：

https://mirrors.aliyun.com/rockylinux/8.10/BaseOS/x86_64/os/

而 9.6 则是：

https://mirrors.aliyun.com/rockylinux/9.6/BaseOS/x86_64/os/

换成 8.10 的仓库时，注意不要手滑把变量写错。我习惯先把原仓库文件做备份再动手：

mkdir -p /root/repo-backup cp /etc/yum.repos.d/*.repo /root/repo-backup/

然后编辑/etc/yum.repos.d/Rocky-*.repo，把mirrorlist开头的行注释掉，把baseurl改成镜像站对应路径。改完记得刷新缓存：

dnf clean all dnf makecache

这里有个容易踩的坑：9.6 刚发布不久时，部分镜像站的同步还不到位，可能出现 404。遇到这种情况，可以先去镜像站目录确认对应版本的文件夹是否存在，或者直接改用dnf update把系统补丁升到当前最新版本，大概率能避开路径不一致的问题。

1.3 给服务器设静态 IP：nmcli 两条命令搞定

Agent 节点和 Web-UI 服务之间要长期保持通信，服务器必须用静态 IP，不然 DHCP 到期换地址之后，所有节点会同时失联。Rocky Linux 默认用 NetworkManager 接管网络，直接通过nmcli改最靠谱。

先查一下当前连接的名称：

nmcli con show

假设网卡连接名是ens192，要设置的 IP 是192.168.1.100/24，网关192.168.1.1，DNS 用223.5.5.5，执行：

nmcli con mod ens192 ipv4.addresses 192.168.1.100/24 ipv4.gateway 192.168.1.1 ipv4.dns "223.5.5.5" ipv4.method manual nmcli con up ens192

第一行修改配置，第二行让配置立即生效。这个操作远程执行时有一定风险，我建议先在本地测试机练一遍，或者确保自己有带外管理通道，否则一旦 IP 写错，远程连接直接断掉，只能去机房或者靠 IPMI 恢复了。

1.4 基础依赖与常用工具装齐

后面不管是解压 Agent 包、编辑配置、查看日志还是排查网络，这些工具都得提前备好。一次性装完：

dnf install -y epel-release wget git vim tar net-tools lsof

如果 Agent 或 Web-UI 依赖 Python，再装一下：

dnf install -y python3 python3-pip

Web-UI 如果是个 Node.js 项目，Rocky 8 官方源的 Node.js 版本偏低，直接用 nvm 装一个 Node.js 20 LTS 更省事。Rocky 9 的话官方源的 nodejs 版本相对新一些，但装 nvm 统一管理也不亏：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20

提醒：装完 nvm 后务必重新source ~/.bashrc，不然 shell 里找不到nvm命令，很多人第一次都卡在这里。

2. Hermes Agent 和 Hermes-Web-UI 是什么关系，装之前必须想清楚

动手装之前，至少要明白这两个东西各自干什么、怎么通信。否则装完发现连不上，排查方向会很乱。这套架构其实和很多"采集节点 + 管理中心"的产品类似，把这个模型理解了，其它同类工具都能快速上手。

2.1 Agent 与 Web-UI 的职责拆分

Hermes Agent 是部署在每台被纳管机器上的组件，职责是采集本机状态、执行下发的任务、把结果上报给中心端。Hermes-Web-UI 则是中心端的控制台，负责展示所有 Agent 节点的在线状态、配置任务、查看历史执行记录。

简单说，Agent 是"手脚"，Web-UI 是"大脑+操作台"。一台机器上只需要装 Agent，不需要装 Web-UI；Web-UI 可以单独跑在一台性能更好的服务器上，管理成千上万台 Agent 节点。这种拆分方式是刻意设计的，因为被纳管的节点通常资源有限，不适合再塞一个重型 UI 服务。

2.2 两者通信依赖什么：端口、Token、心跳

Agent 与 Web-UI 之间不是随随便便就能连上的，注册机制通常包含三个要素：服务地址、身份令牌、心跳周期。

假设我在实验环境里做了这样的规划：

组件	监听端口	说明
Hermes Agent	9100	本机指标与健康检查端口
Hermes-Web-UI API	8080	中心端 API 服务
Nginx	80/443	对外提供 Web 访问，反代到 8080

Agent 启动后会拿着配置文件里的register_token主动访问 Web-UI 的 API 地址完成注册，注册成功后拿到新的身份标识，之后每隔一段时间发送一次心跳。Web-UI 通过心跳判断节点是否在线。

网络策略上只需要保证 Agent 节点能访问 Web-UI 的 API 端口就行，不需要把 Agent 的 9100 端口对 Web-UI 开放，除非你打算让中心端主动采集数据。这个方向一定要搞清，不然防火墙规则会配反。

2.3 为什么我坚持用 systemd 托管而不是 nohup

不少教程让你用nohup ./hermes-agent &这种方式启动，方便是方便，但有几个致命问题：重启机器后进程不会自动拉起，SSH 断开后进程虽然可能存活但没人保证，日志管理全靠重定向追加，进程崩溃不会自动恢复。

用 systemd 接管之后，这些都不是问题：

• 开机自启：enable一下就完事
• 崩溃自动重启：Restart=always兜底
• 日志统一到 journald：journalctl -u直接看，出问题方便回查
• 权限隔离：可以指定专用系统用户运行，不用 root

模块化的服务本来就该交给 systemd 管，尤其是生产环境，别偷懒。

3. 安装 Hermes Agent：从下载到 systemd 托管

这一章我按"拿到安装包 -> 规划目录 -> 写配置 -> 写 unit -> 启动验证"的顺序来。如果你用的是 RPM 包或者 Docker 镜像，思路一致，只是命令不同，我会在关键节点提醒差异。

3.1 获取安装包：官方发布页与校验和

Hermes Agent 一般通过官方 Release 页面发布，选择对应 Linux amd64 架构的二进制压缩包。如果官方提供了 RPM 包，直接用 dnf 安装最省事；如果只有 tar.gz 压缩包，按下面的流程操作。

下载完成后，先做校验，避免拿到损坏或不完整的包：

wget https://your-download-host/hermes-agent-linux-amd64.tar.gz sha256sum hermes-agent-linux-amd64.tar.gz

把输出结果和官方页面公布的 SHA256 值对比，一致再继续。这个习惯看起来繁琐，但生产环境部署必须养成，尤其是涉及到需要注册令牌的组件，校验一下更安心。

解压到指定目录：

mkdir -p /opt/hermes-agent tar -zxvf hermes-agent-linux-amd64.tar.gz -C /opt/hermes-agent

解压后先看一下目录结构，确认主程序名称和目录层级，后面写 systemd unit 时要精确指定 ExecStart 路径。

3.2 规划目录结构：别学我一开始乱放

我第一次装的时候图省事，直接把 Agent 解压到/root/下，配置、日志、可执行文件全混在一起，结果后来升级时极其痛苦，备份都不知道该拷哪个目录。

推荐按下面的结构来：

/opt/hermes-agent/ # 可执行文件与静态资源 /opt/hermes-agent/bin/ # 主程序 /etc/hermes-agent/ # 配置文件 /var/lib/hermes-agent/ # 运行时数据与缓存 /var/log/hermes-agent/ # 日志文件

这样分的主要原因：升级时只替换/opt/hermes-agent下的程序文件，备份时打包/etc/hermes-agent和/var/lib/hermes-agent就足够，日志目录独立方便按需清理。

创建目录并赋予运行用户权限：

mkdir -p /opt/hermes-agent/bin /etc/hermes-agent /var/lib/hermes-agent /var/log/hermes-agent

3.3 编辑配置文件：一份最小可用的 hermes.conf

Hermes Agent 的配置格式因版本而异，可能是 INI、TOML 或 YAML，但核心配置项大同小异。我以一个常见的 TOML 风格为例：

# /etc/hermes-agent/hermes.conf # 本节点唯一标识 server_id = "node-rocky-01" # 本地监听地址 listen_addr = "0.0.0.0" listen_port = 9100 # Web-UI 的 API 地址，Agent 会主动访问这个地址完成注册 webui_endpoint = "http://192.168.1.10:8080" # 注册令牌，需要在 Web-UI 后台创建 register_token = "改成你在UI创建的Token" # 心跳周期，单位秒 heartbeat_interval = 30 # 日志级别：debug / info / warn / error log_level = "info" # 运行时数据存储路径 storage_path = "/var/lib/hermes-agent"

写完之后，配置文件里包含 Token 和节点信息，权限要收紧：

chmod 600 /etc/hermes-agent/hermes.conf

注意：配置文件里的字段名务必以你实际下载版本的官方文档为准，不同版本可能叫agent_id、server_url或api_endpoint。先./hermes-agent --help或看文档确认，不要直接照抄。

3.4 编写 systemd unit 并启动

Agent 建议用专用系统用户运行，不要直接用 root：

useradd -r -s /sbin/nologin hermes chown -R hermes:hermes /opt/hermes-agent /etc/hermes-agent /var/lib/hermes-agent /var/log/hermes-agent

创建 unit 文件：

# /etc/systemd/system/hermes-agent.service [Unit] Description=Hermes Agent After=network-online.target Wants=network-online.target [Service] Type=simple User=hermes Group=hermes WorkingDirectory=/opt/hermes-agent ExecStart=/opt/hermes-agent/bin/hermes-agent --config /etc/hermes-agent/hermes.conf Restart=always RestartSec=5 LimitNOFILE=65535 Environment=LANG=en_US.UTF-8 Environment=LC_ALL=en_US.UTF-8 [Install] WantedBy=multi-user.target

After=network-online.target和Wants=network-online.target的意思是等服务网络就绪后再启动，避免开机时网络没起来导致 Agent 注册失败。Restart=always保证进程崩溃后 5 秒自动拉起。

加载并启动：

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

验证是否正常运行：

systemctl status hermes-agent journalctl -u hermes-agent -f ss -lntp | grep 9100

systemctl status看进程状态，journalctl看启动日志，ss确认端口监听。这三步走完，Agent 这边基本就绪。

4. 部署 Hermes-Web-UI：前端页面与后端 API

Hermes-Web-UI 是管理和展示的入口，所有 Agent 节点最终都会在这个界面上呈现。部署方式有现成 Docker 镜像和手动 Node.js 部署两种，我以手动部署为例，因为这种方式对网络和资源要求更可控，也方便排查问题。

4.1 Web-UI 的运行时依赖与部署方式

Web-UI 一般是一个 Node.js 服务，可能还依赖数据库做持久化。如果只是本地测试，SQLite 够用；生产环境建议上 PostgreSQL，数据安全性和并发能力都更可靠。另外如果 Web-UI 用到 Redis 做任务队列或会话缓存，也要先把 Redis 跑起来。

安装 PostgreSQL 和 Redis：

dnf install -y postgresql-server postgresql-contrib redis postgresql-setup --initdb systemctl enable --now postgresql redis

创建数据库和用户：

sudo -u postgres psql CREATE DATABASE hermes; CREATE USER hermes WITH PASSWORD '你的密码'; GRANT ALL PRIVILEGES ON DATABASE hermes TO hermes;

Web-UI 安装包同样从官方渠道获取，解压到独立目录：

mkdir -p /opt/hermes-web-ui tar -zxvf hermes-web-ui-linux-amd64.tar.gz -C /opt/hermes-web-ui cd /opt/hermes-web-ui

4.2 初始化数据库与管理员账号

多数 Web-UI 项目会提供一个.env.example示例文件，复制成.env后修改：

cp .env.example .env

典型配置项：

PORT=8080 NODE_ENV=production DATABASE_URL=postgres://hermes:你的密码@127.0.0.1:5432/hermes REDIS_URL=redis://127.0.0.1:6379/0 SECRET_KEY=随机生成一串64位字符串

其中 SECRET_KEY 必须改成随机值，推荐用下面命令生成：

openssl rand -hex 32

然后执行数据库迁移和初始化：

npm install --production npm run migrate npm run seed

具体命令以官方文档为准。初始化完成后，通常会有一个创建管理员账号的命令，比如：

./hermes-web-ui create-admin -u admin -p '你的强密码'

创建完成就可以启动服务了。为了让 Web-UI 也能开机自启，我给它也写了一个 systemd unit：

# /etc/systemd/system/hermes-web-ui.service [Unit] Description=Hermes Web UI After=network-online.target postgresql.service redis.service Wants=network-online.target [Service] Type=simple User=hermes WorkingDirectory=/opt/hermes-web-ui ExecStart=/usr/bin/node server.js Restart=always RestartSec=5 Environment=NODE_ENV=production [Install] WantedBy=multi-user.target

执行：

systemctl daemon-reload systemctl enable --now hermes-web-ui

这时在服务器本地curl http://127.0.0.1:8080应该能返回页面内容或接口响应。

4.3 用 Nginx 反向代理并开启 HTTPS

Web-UI 默认监听 8080，如果直接用这个端口对外开放，不仅暴露服务端口，传输也不安全。Nginx 在这里做一个反向代理，统一走 80/443。

安装 Nginx：

dnf install -y nginx systemctl enable --now nginx

配置示例：

# /etc/nginx/conf.d/hermes-web-ui.conf server { listen 80; server_name your-server-domain-or-ip; client_max_body_size 50m; 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; } location /api/ { proxy_pass http://127.0.0.1:8080/api/; proxy_read_timeout 1800s; } }

这里我把/api/单独拎出来配了一个更长的超时时间，是因为 Agent 注册、任务下发这类接口可能需要长轮询，或者上传大文件时请求时间较长。如果不调超时时间，Nginx 默认 60 秒就会断开，很多 Agent 注册到一半被掐断，还查不出原因。

配置生效：

nginx -t systemctl reload nginx

如果要上 HTTPS，建议直接用 certbot 签发证书，这里不展开，但记住一点：启用 HTTPS 后，Agent 配置文件里的webui_endpoint也要改成https://前缀，否则 Agent 会访问一个不可达的 80 端口地址。

4.4 在 Web-UI 中完成 Agent 注册与状态确认

打开浏览器访问 Web-UI 地址，用刚才创建的管理员账号登录。进入节点管理页面，创建一个注册令牌，然后把它填到 Agent 的hermes.conf里，重启 Agent：

systemctl restart hermes-agent

回到 Web-UI 的节点列表，正常情况下几秒内就能看到 Agent 节点出现，状态变为 Online，心跳时间会不断刷新。

如果节点一直显示 Offline，先用命令确认 Agent 能访问 Web-UI 的 API：

curl -v http://<web-ui-ip>:8080/api/health

再确认 Web-UI 能被外部访问：

curl -v http://<agent-ip>:9100/health

双向验证之后，问题基本能定位到网络策略或 Token 不匹配上。

5. 我踩过的坑：从 SELinux 到端口不通

装这套东西的过程中，我踩过的坑比预想的多，下面这几个是最高频的，几乎每换一台新机器重装都会遇到其中一个。我把排查链路写出来，你能顺着思路快速定位。

5.1 SELinux 拦截：服务起不来的第一元凶

现象：systemctl status hermes-agent显示 active (running)，但端口就是没在监听，日志也没有明显报错，或者在启动后几秒内进程被悄悄杀掉。

Rocky Linux 默认开启 SELinux，它的强制访问控制策略会拦截没有被打上正确标签的可执行文件或目录访问。第一次装的时候我没考虑这一点，卡了将近一个小时。

排查命令：

dmesg | grep -i avc ausearch -m avc -ts recent

如果确实看到 AVC denied 记录，可以临时测试：

setenforce 0 systemctl restart hermes-agent

服务恢复正常，说明就是 SELinux 的问题。但生产环境不建议长期关闭 SELinux，正确做法是为相关目录设置正确的文件上下文：

semanage fcontext -a -t bin_t "/opt/hermes-agent/bin(/.*)?" restorecon -Rv /opt/hermes-agent

如果你安装的 Agent 有官方提供的 SELinux 支持模块，直接安装之后restorecon即可。

5.2 防火墙与云安全组：双重放行

现象：服务监听正常，本机 curl 也能通，但其他机器就是连不上。

问题基本上都出在两层策略上：第一层是本机 firewalld，第二层是云平台安全组。

本机放行端口：

firewall-cmd --permanent --add-port=9100/tcp --add-port=8080/tcp firewall-cmd --reload

提示：如果 Agent 服务部署在腾讯云、阿里云等平台上，云控制台里的安全组或防火墙规则同样需要放行对应端口。很多时候本机firewall-cmd全关了还是连不上，一查安全组才发现没放行，这个顺序颠倒排查起来特别浪费时间。

5.3 yum 源失效导致依赖装不上

现象：dnf install时大量 404，或 makecache 报错。

主要原因是 Rocky Linux 旧版本源被下架到 vault，或者镜像站同步不及。比如你装的是 8.10，官方源可能已经把 8.10 的仓库标记为 archive，镜像站路径里只剩vault/目录。

解决办法有两种：一是直接升级到当前最新的 8.x 或 9.x 补丁版本，仓库路径自动修正；二是手动把仓库文件的 baseurl 指向 vault 路径，这种方式适合只想保持旧版本基线的情况。

另外，国内镜像站在大版本刚发布后偶尔会同步不全，等半天还是 404，那就换个镜像站试试，不要死磕一个源。

5.4 Agent 日志乱码与 timezone 设置

现象：Web-UI 上 Agent 节点上报的时间比实际时间差了 8 小时，或者journalctl查看日志时中文乱码。

系统时区如果保持默认 UTC，时间会差整整 8 个小时，直接影响心跳、任务调度和告警判断。我每装一台机器都会强制设置时区为 Asia/Shanghai：

timedatectl set-timezone Asia/Shanghai

日志乱码则多半是环境变量没设对。在 unit 文件里加Environment=LANG=en_US.UTF-8和Environment=LC_ALL=en_US.UTF-8基本能解决。另外时间同步服务也别省：

systemctl enable --now chronyd timedatectl

确认 NTP synchronized 为 yes 再继续，不然时钟偏移会导致 Agent 注册令牌校验失败。

5.5 Web-UI 页面打不开时，按这个顺序排查

Web-UI 页面打不开这个问题我碰到过好几次，每次原因都不同，总结下来按这个顺序排查最有效率：

1. 本机curl http://127.0.0.1:8080—— 先确认服务本身活着
2. curl http://服务器公网IP—— 确认 Nginx 层没问题
3. telnet 服务器IP 80—— 确认端口能从外部访问
4. 看 Nginx 错误日志/var/log/nginx/error.log
5. 看 Web-UI 日志journalctl -u hermes-web-ui -f

按链路从内到外一层层验证，很快就能定位到问题在哪个环节。我见过不少人直接拿浏览器访问，打不开就开始怀疑代理配置，到处改配置，最后发现其实就是服务根本没启动。

5.6 版本不匹配：UI 与 Agent 的兼容性检查

现象：Agent 能正常启动，日志里显示注册成功，但 Web-UI 上节点状态异常，或者 Agent 上报的数据 UI 解析不出来。

这是升级之后最容易踩的坑。Hermes Agent 和 Hermes-Web-UI 的版本并不是无脑最新的互相兼容，它们在注册协议、数据格式上可能有差异。升级之前一定要看官方 CHANGELOG 里的兼容矩阵，最好保持 Agent 和 Web-UI 的大版本一致。

我在测试环境就吃过一次亏，把 Web-UI 从 1.x 升到 2.x，但 Agent 集群还是 1.x，结果所有节点注册后都显示协议错误，最后只能逐个节点升级 Agent 才恢复正常。生产环境升级前，务必先备份、再在测试环境验证一轮。

6. 安装完成之后的日常维护

Agent 装完、Web-UI 跑通，这只是开始。日常维护里最容易忽略的两件事是日志轮转和升级备份，这里给出我常用的配置。

6.1 日志轮转配置

如果 Agent 把日志写到/var/log/hermes-agent/而不是完全交给 journald，时间一长日志文件会越来越大。用 logrotate 做自动轮转最省心：

# /etc/logrotate.d/hermes-agent /var/log/hermes-agent/*.log { daily rotate 14 compress delaycompress missingok notifempty copytruncate }

copytruncate的优点是进程不用重启，日志文件就被截断，代价是有极小概率丢几行日志。如果 Agent 支持收到 USR1 信号后重新打开日志文件，用create加sharedscripts配合 kill 信号更稳妥，但实际场景下copytruncate基本够用。

6.2 备份与升级

备份建议只关注配置、数据和数据库，不需要备份整个程序目录：

tar -czvf hermes-backup-$(date +%F).tar.gz \ /etc/hermes-agent \ /var/lib/hermes-agent \ /opt/hermes-web-ui/.env

如果用了 PostgreSQL，还要导出数据库：

sudo -u postgres pg_dump hermes > hermes-db-backup-$(date +%F).sql

升级流程我通常这样走：

1. 下载新版本安装包
2. 备份当前配置与数据
3. 停服务：systemctl stop hermes-agent hermes-web-ui
4. 替换程序文件
5. 启动服务：systemctl start hermes-agent hermes-web-ui
6. 验证 Agent 注册和 UI 登录
7. 观察 10 分钟心跳是否正常

升级前多看几眼官方的 CHANGELOG，确认是否有破坏性变更，尤其是 Agent 和 Web-UI 的版本匹配关系。这个习惯能避免绝大多数升级事故。

我在多台 Rocky Linux 8.10 和 9.6 上重复过这套流程，最大的体会是：Agent 类服务安装本身并不复杂，但系统底子如果不干净，后面排查起来会非常痛苦。SELinux、防火墙、时区、yum 源这几个基础项，建议新装完系统后先全部处理好再动手。

还有一个很小的技巧：每次改完 systemd unit 或配置文件，第一时间执行systemctl daemon-reload，然后打开journalctl -u hermes-agent -f，看启动日志里前 20 行。很多配置路径写错、启动参数不对的问题，在这个日志里一眼就能看出来，根本不用等到节点下线了再去到处找原因。这套流程整体走下来，正常情况下两个小时以内就能把 Agent 和 Web-UI 全部拉起来，剩下的就是根据自己的业务需求去调整任务模板和告警规则。