拿到一台全新的 Rocky Linux 服务器，第一件事往往不是急着复制粘贴安装命令，而是先把 Hermes Agent 和 Hermes-Web-UI 之间的关系理顺。我在多台机器上见过两种极端情况：一种是只装了 Hermes Agent，结果天天对着终端敲命令，连个可视化界面都没有，排查日志全靠journalctl；另一种是装好了 Hermes-Web-UI，但 Agent 本体没跑起来，界面打开一片空白，点哪儿都没反应。这篇指南要做的，就是把 Rocky Linux 从裸系统到 Web UI 可用的完整链路走一遍，包括环境准备、Agent 安装、Web UI 部署、systemd 托管，以及我在实际操作中踩过的坑和对应的排查思路。
如果你正准备在自己服务器上本地部署 Hermes Agent，又想让管理界面更友好一点，这篇文章会很有参考价值。我会把每一步的理由也说清楚，不是简单丢命令给你抄，而是帮你理解为什么要这样做，这样你在遇到报错时才有能力自己判断问题出在哪。
1. 为什么先理清 Agent 和 Web-UI 的关系，再动手装
1.1 两个组件的分工完全不同
Hermes Agent 和 Hermes-Web-UI 虽然是配套使用的，但它们的职责边界非常清楚。Hermes Agent 是真正干活的后端程序，负责加载配置、连接模型供应商或本地模型、处理请求、维护会话状态、写日志、执行各种自动化任务。它本身不提供图形界面，大部分时候以命令行进程或后台服务的方式运行。
Hermes-Web-UI 则是给 Agent 套了一层可视化的"操作台"，它做的事情是把 Agent 的状态、对话记录、配置项、运行日志等展示出来，同时把你在网页上操作的动作转成 API 请求发给 Agent。换句话说，UI 是壳，Agent 才是核。你可以在没有 Web UI 的情况下单独跑 Agent，但反过来不行——没有 Agent 的 Web UI 只是一个空壳页面，什么都干不了。
这个关系听起来很简单，但实际部署时很多人栽跟头。原因在于网上不少教程把两个组件混在一起讲，导致用户以为安装某一个就等于把整套系统装好了。我见过最典型的例子是：有人花了半小时装好 Web UI，然后启动服务，浏览器打开 80 端口，页面确实出来了，但登录进去发现 Agent 状态一直显示离线。他折腾了半天配置 Nginx、改防火墙，结果最后发现 Agent 压根没装。
1.2 明确自己的使用场景，再决定两步都要不要做
不是所有人都需要 Web UI。如果你只是想在服务器上跑一个 Agent，通过命令行或 API 调用，那只需要安装 Hermes Agent 本体，再加一个 systemd 服务让它稳定常驻就够了。Web UI 对这种场景反而是一个多余的攻击面和资源占用源。
反过来，如果团队里有多个人要使用 Agent，或者你想在手机上通过浏览器查看状态、发指令，那 Web UI 就不是可选项了。它提供的可视化操作能力能大幅降低使用门槛，让不熟悉命令行的同事也能上手。
所以我的建议是：先想清楚自己的使用场景，再决定安装路径。这篇指南会按"Agent 必装 + Web UI 按需安装"的顺序来讲，这样即使你最后不需要 UI，前面的步骤也不会白做。
2. Rocky Linux 环境准备：静态 IP、SELinux 和防火墙三件套
2.1 选对系统版本，装前先做一次全量更新
Rocky Linux 目前主流版本是 8.x 和 9.x 两个系列。8.10 是 8 系列比较新的版本，9.6 则是 9 系列的一个阶段性版本，新项目我一般建议直接用 9 系列，毕竟软件包版本更新，Python、OpenSSL 这些基础组件的版本也更高，省得后面为了凑依赖版本折腾。
系统安装完之后，无论你用的是哪个版本，第一件要做的事永远是把系统包更新到最新。这不仅是安全需要，更重要的是，如果系统自带的组件版本太旧，后面安装 Hermes Agent 的依赖时可能会因为 OpenSSL 版本不够或者 glibc 版本偏低而编译失败。
dnf update -y dnf install -y curl wget git tar gzip unzip vim bash-completion更新完之后重启一下，确保内核和用户态工具都切换到新版本。这一步不做的话，后面跑ss、firewall-cmd这些命令时，有可能遇到行为不一致的问题。
2.2 用 nmcli 把服务器 IP 固定成静态 IP
这一步容易被忽略，但非常关键。Hermes Agent 部署完成后，如果你需要让局域网内其他机器访问 Web UI，服务器的 IP 必须稳定。DHCP 分配的 IP 一旦过期重新续租，地址可能就变了，到时候你的 Web UI 在浏览器里突然打不开，排查半天发现是 IP 变了——这种低级错误真的会浪费大量时间。
Rocky Linux 8/9 的网络管理默认走 NetworkManager，修改 IP 最稳妥的方式是用nmcli命令，不要直接改/etc/sysconfig/network-scripts/ifcfg-*文件，虽然改文件也能生效，但在 NetworkManager 接管的环境下容易出现配置被回写的奇怪问题。
先查看当前网卡名称和连接名：
nmcli connection show假设网卡叫ens160，连接名也叫ens160，把它改成静态 IP，比如192.168.1.100：
nmcli connection modify ens160 ipv4.method manual ipv4.addresses 192.168.1.100/24 ipv4.gateway 192.168.1.1 ipv4.dns 192.168.1.1 nmcli connection up ens160改完之后用ip addr show ens160确认生效。这里有个细节：ipv4.dns不要只填一个 Google 的 8.8.8.8 之类的公共 DNS，除非你的服务器能稳定访问外网。如果这台机器在内网环境，填内网 DNS 或者干脆填网关地址更稳。
2.3 SELinux 和 firewalld 对 Hermes 的影响
Rocky Linux 默认开启了 SELinux（安全增强型 Linux），强制模式是Enforcing。很多从 Debian/Ubuntu 转过来的用户一上来就喜欢setenforce 0甚至改/etc/selinux/config永久关闭 SELinux。我理解这样做能省很多事，但对于一台要长期跑服务的机器，我强烈不建议一上来就关。SELinux 其实只在你用了非标准端口、非标准配置时才会给你"找麻烦"，而且每次报错都能通过ausearch或/var/log/audit/audit.log找到明确的拒绝记录，完全有迹可循。
正确做法是保持 SELinux 开启，遇到问题时看审计日志具体解决。比如后面 Nginx 反向代理到 Hermes-Web-UI 的本地端口时，你会撞上httpd_can_network_connect这个布尔值没有打开的问题，到时候一条setsebool命令就能解决，完全不需要关闭 SELinux。
防火墙方面，Rocky Linux 默认启用 firewalld。官方仓库装包时会自动放行 SSH 和 DHCP 相关的服务，但不会放行 HTTP/HTTPS。如果你计划让 Web UI 对外提供服务，记得放行 80/443 端口：
firewall-cmd --permanent --add-service=http firewall-cmd --permanent --add-service=https firewall-cmd --reload如果你想让 Hermes Agent 的 API 端口（比如 9120）也被外部直接访问，那还要单独放行这个端口。但我个人的习惯是：API 端口只监听 127.0.0.1，对外一律走 Nginx 反向代理，这样少暴露一个端口，安全面更小。
3. Hermes Agent 本体安装完整流程：账号、运行时、配置、开机服务
3.1 创建专用账号和 Python 运行时环境
我不建议直接用 root 用户跑 Hermes Agent。虽然这样最省事，但一旦 Agent 被外部利用或者代码本身有漏洞，攻击者拿到的就是 root 权限。创建一个专用系统用户，把服务运行在最小权限下，这是服务器运维的基本素养。
useradd -r -d /opt/hermes -s /sbin/nologin hermes mkdir -p /opt/hermes/{app,logs,data,etc} chown -R hermes:hermes /opt/hermes这里-r表示创建系统用户，-s /sbin/nologin表示这个用户不能登录 shell，只能运行服务。数据目录单独分出来，方便后续备份和升级。
Hermes Agent 这类项目依赖 Python 3.10 以上。Rocky Linux 8 自带的 Python 版本是 3.6，太老了，Rocky Linux 9 自带 Python 3.9，对某些 AI 项目来说也未必够。我建议直接安装 Python 3.11，Rocky 官方 AppStream 仓库里有现成的模块。
dnf module -y install python311 dnf install -y python3.11-devel python3.11-pip装完之后用python3.11 -V确认版本是 3.11.x。这里要注意，千万不要直接改系统默认的 python3 软链指向 3.11，因为系统里还有很多工具依赖原本的 Python 版本，你强行改了软链，过两天可能发现dnf都跑不起来了。
3.2 获取 Hermes Agent 代码并完成依赖安装
Hermes Agent 的官方发布渠道会提供源码包或预编译的二进制包，我更推荐用 git clone 的方式获取源码，因为后续升级可以直接git pull，不用重新下载整个包。当然，如果你只是想在服务器上跑起来，下载官方 Release 页面的 tar.gz 压缩包也可以，步骤类似。
以源码方式为例：
cd /opt/hermes/app sudo -u hermes git clone https://github.com/your-org/hermes-agent.git .克隆完代码之后，创建 Python 虚拟环境并安装依赖：
cd /opt/hermes/app sudo -u hermes python3.11 -m venv venv sudo -u hermes ./venv/bin/pip install -U pip setuptools wheel sudo -u hermes ./venv/bin/pip install -r requirements.txt这一步是整个安装过程中耗时最长也是最容易出问题的一步。如果依赖列表里有需要编译的 C 扩展包，缺少编译器或对应的开发头文件就会报错。为了避免中途翻车，建议先把编译工具链装齐：
dnf install -y gcc gcc-c++ make cmake如果你的服务器访问 PyPI 速度很慢，可以配置国内镜像源，比如清华源。修改方式是在用户家目录下建一个~/.pip/pip.conf，或者在命令里临时指定：
sudo -u hermes ./venv/bin/pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple依赖装完后，先跑一下 CLI 帮助命令，确认入口命令可用。不同版本的项目入口命令名可能不同，常见的是hermes或者hermes-agent。如果你看到的是别的名字，后面所有命令都要跟着调整。
sudo -u hermes ./venv/bin/hermes --help3.3 编辑 config.yaml：本地模型还是外部 API
Hermes Agent 的配置文件通常是一个 YAML 文件，放在/opt/hermes/etc/config.yaml。第一次启动前必须把配置里的核心内容填好，否则进程虽然能起来，但一调用就会报错。
配置里最核心的是模型供应商相关的内容。如果你用的是 DeepSeek、OpenAI 这类外部 API，需要填对应的base_url、api_key和model名称。如果你用的是本地模型（比如通过 Ollama 或 vLLM 跑的模型），那base_url要指向本地模型的监听地址。
下面是一个参考配置结构：
agent: name: hermes-node-01 listen_host: 127.0.0.1 listen_port: 9120 log_level: info data_dir: /opt/hermes/data llm: provider: deepseek base_url: https://api.deepseek.com/v1 api_key: sk-xxxxxxxxxxxx model: deepseek-chat temperature: 0.7 storage: type: sqlite path: /opt/hermes/data/hermes.db这里的listen_host我建议固定写127.0.0.1，不要让 Agent 直接暴露在网络上。外部访问全部通过 Web UI 和 Nginx 这一层，Agent 只对本地回环地址提供服务。
api_key最好不要明文写在 YAML 里。更稳妥的做法是通过环境变量注入，在 systemd 服务文件里引用环境变量，这样即使配置文件被意外读取，也不会直接泄露密钥。具体做法在 3.4 里会一起讲。
3.4 初始化数据库，并用 systemd 将 Agent 做成开机服务
配置写好后，一般需要先执行一次初始化命令，让 Agent 创建数据库表结构、生成初始配置。不同项目的初始化命令不一样，有的叫hermes init，有的叫hermes migrate，也有的在首次启动时自动完成。你可以先看一下项目 README 里的说明。
以常见的方式为例：
sudo -u hermes ./venv/bin/hermes init --config /opt/hermes/etc/config.yaml如果之前没有遇到过这个命令，但服务能正常启动且日志里没有报数据库错误，那大概率是会自动初始化的类型，不用额外执行。
接下来创建 systemd 服务文件。我习惯放在/etc/systemd/system/hermes-agent.service：
[Unit] Description=Hermes Agent Service After=network.target [Service] Type=simple User=hermes Group=hermes WorkingDirectory=/opt/hermes/app EnvironmentFile=/opt/hermes/etc/hermes.env ExecStart=/opt/hermes/app/venv/bin/hermes serve --config /opt/hermes/etc/config.yaml Restart=on-failure RestartSec=5 [Install] WantedBy=multi-user.target注意这里的EnvironmentFile，我建议把 API 密钥等敏感信息放到/opt/hermes/etc/hermes.env文件里，内容类似：
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxx然后在 config.yaml 里通过api_key: ${DEEPSEEK_API_KEY}引用。这样做的好处是配置文件和密钥分离，备份配置时不用担心密钥泄露。EnvironmentFile文件需要设置好权限：
chmod 600 /opt/hermes/etc/hermes.env chown hermes:hermes /opt/hermes/etc/hermes.env启动服务并设置开机自启：
systemctl daemon-reload systemctl enable --now hermes-agent最后验证一下服务状态和端口监听：
systemctl status hermes-agent ss -tlnp | grep 9120看到State: listening就说明 Agent 本体已经跑起来了。此时可以再执行一条简单的测试命令，比如通过 API 发一个基础请求，确认模型调用链路也是通的。
4. Hermes-Web-UI 部署：前端构建、后端服务和 Nginx 反向代理
4.1 准备 Node.js 运行时并获取 Web-UI 构建产物
Hermes-Web-UI 的前端部分一般是基于 Node.js 生态构建的，需要 Node.js 18 或 20 版本。Rocky Linux 的 AppStream 仓库自带 Node.js 模块，可以直接启用指定版本：
dnf module -y list nodejs dnf module -y enable nodejs:20 dnf install -y nodejs npm装完后用node -v和npm -v确认版本。
获取 Web-UI 安装包的方式，我建议直接下载官方 Release 页面的预构建产物，这样可以省去前端编译的时间。如果你下载的是源码包，则需要先安装 npm 依赖再执行构建，步骤也不复杂：
cd /opt/hermes-web sudo -u hermes npm ci sudo -u hermes npm run buildnpm ci会严格按照锁文件安装依赖，比npm install更可预期。构建完成后，产出的静态文件一般在dist目录下，这个目录就是下一步要用 Nginx 托管的根目录。
4.2 配置 UI 后端服务：会话存储、Agent 连接地址和密钥
Hermes-Web-UI 不只是静态页面，它还有一个后端 API 服务，负责处理登录认证、会话管理、把前端请求转发给 Hermes Agent。这个后端服务可能是 Node.js 写的，也可能是 Python 写的，具体取决于项目实现，但配置逻辑大同小异。
需要关注三个核心配置项：
第一，会话存储方式。如果只是单机部署，使用默认的本地文件或 SQLite 存储就够了，不需要额外装 Redis。但如果你的部署规模会上来，多个 UI 实例共享会话状态，那就必须引入 Redis，否则用户登录状态没法在多实例之间同步。
第二，Agent 连接地址。这一步是最容易配错的地方。Web UI 后端需要知道 Agent 服务监听在哪个地址，你要把这里填成http://127.0.0.1:9120，而不是填服务器的公网 IP 或者域名。因为从同机后端访问 Agent，走回环地址最快也最安全，绕一圈外部地址反而可能被防火墙挡住。
第三，API 密钥。UI 后端调用 Agent API 时，通常需要带一个密钥或 Token，这个密钥要在 UI 配置里和 Agent 启动参数中保持一致。如果密钥对不上，UI 里会频繁出现 401 认证失败。
配置好之后，用 Node 直接启动 UI 后端服务，或者在项目目录下找自带的 CLI 启动脚本。先在前台跑一下，确认没有报错，再做成 systemd 服务。
4.3 用 Nginx 托管静态文件并反向代理 API
Web UI 的前端静态文件和后端 API 通常建议放在同一个域名下，通过路径来区分，这样浏览器端不会出现跨域问题。我会用 Nginx 做一层反向代理：静态文件直接由 Nginx 提供服务，/api路径的请求转发给 UI 后端服务。
安装 Nginx：
dnf install -y nginx systemctl enable --now nginx然后创建一个站点配置文件，比如/etc/nginx/conf.d/hermes-ui.conf：
server { listen 80; server_name hermes.example.com; root /opt/hermes-web/dist; index index.html; client_max_body_size 20m; location / { try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; 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; } }这里把 UI 后端假设监听在127.0.0.1:3000，具体端口以你配置为准。try_files那句很重要，前端路由如果是 history 模式，不写这句会导致刷新页面时出现 404。
配置写完后，重载 Nginx：
nginx -t systemctl reload nginx如果你配了域名，记得在 DNS 把域名解析到服务器公网 IP，并在云服务商的安全组和服务器 firewalld 里放行 80/443 端口。如果没配域名，也可以直接用http://服务器IP访问，只是server_name可以改成_或者干脆删掉。
4.4 SELinux 调整：给 Nginx 反代放行本地端口
这是整个部署流程里最容易踩的坑。你配置好 Nginx 后，访问静态页面没问题，但所有/api请求都会返回 502 Bad Gateway。你检查 UI 后端进程，发现它明明在正常运行，手动curl http://127.0.0.1:3000也有响应，那问题十有八九出在 SELinux 上。
SELinux 默认策略不允许 Nginx 作为代理去连接本地非标准端口。查看审计日志：
ausearch -m avc -ts recent如果看到httpd_t相关的 deny 记录，执行：
setsebool -P httpd_can_network_connect 1这个布尔值打开后，Nginx 就能正常转发到127.0.0.1:3000之类的本地端口了。-P参数表示持久化，重启后仍然生效。执行完后不需要重启 Nginx，直接刷新页面，接口应该就通顺了。
5. 实战排错：桌面版报错、端口不通、依赖版本裂化
5.1 桌面版安装报错为什么频繁出现
搜索"hermes agent 桌面版安装报错"的人不少，我在现实中也遇到过类似问题。Hermes Agent 官方会发布桌面版安装包，但在 Rocky Linux 这种以服务器为主要使用场景的系统上，桌面版安装报错的概率比服务器版高得多。原因在于：桌面版安装包通常会依赖图形界面的运行库，比如 GTK、Qt 或者 X11 相关的库。如果你装的是最小化系统或者纯服务器版本，这些库压根不存在，安装器跑起来自然一团糟。
我个人的建议是：在 Rocky Linux 服务器上部署 Hermes Agent，走 Portable 便携版或者源码安装的方式，不要碰桌面版。桌面版面向的是个人电脑用户，依赖的库太多，而且它在无头服务器上就算能装上，没有显示器也用不了。
如果确实需要在本地电脑上使用桌面版，那也尽量选择官方明确支持的系统版本，并且按官方文档把图形库依赖一次性装齐。在服务器上折腾桌面版，纯粹是浪费时间。
5.2 连接拒绝和 502：一次完整的排查链路
这里分享一次我在部署 Web UI 时遇到的真实排查过程。现象是：Nginx 配置好了，静态页面能打开，但登录后报错，接口返回 502。我当时的第一反应是看 Nginx 日志：
tail -f /var/log/nginx/error.log日志里显示的是connect() failed (111: Connection refused) while connecting to upstream，也就是 Nginx 连不上127.0.0.1:3000。但我前面明明已经确认 UI 后端进程起来了。
这里要强调一个关键细节：确认进程存在不意味着监听地址正确。我后来用ss -tlnp | grep 3000看了一下，发现后端服务确实监听在 3000 端口，但监听地址是::，也就是 IPv6 的任意地址。而 Nginx 配置里proxy_pass指向的是127.0.0.1:3000，这是 IPv4 的回环地址。在某些网络环境下，IPv6 的::并不会接受来自 IPv4 回环的连接请求，于是 502。
解决方式两种：要么把 Nginx 的proxy_pass改成http://[::1]:3000，要么让后端服务明确监听127.0.0.1。我选择了后者，因为让服务监听明确的 IPv4 回环地址更可控，也更容易理解和排查。
如果你遇到 502，我建议按照这个顺序排查：先curl -I http://127.0.0.1:3000看后端通不通，不通就说明后端没起来；通了再看 Nginx 错误日志，看是连接拒绝还是超时；如果日志里没有明显报错，再查 SELinux 审计日志。这套链路基本能覆盖九成以上的场景。
5.3 依赖版本裂化：venv 能隔离但不万能
Python 虚拟环境能隔离 Python 包的版本，但隔离不了系统层面的 C 库。我在 Rocky Linux 8 上就碰到过一次很典型的版本裂化问题：Hermes Agent 依赖的某个加密库在编译时要求 OpenSSL 1.1.1 以上，但系统自带的 OpenSSL 是 1.1.1k，满足要求；后来我为了装其他软件，手动从源码编译了一个新版 OpenSSL 并放在/usr/local/ssl，结果 Python 在编译连接这个库时优先找到了新版本，但新版本的头文件和系统库文件版本不一致，导致启动时直接报version 'OPENSSL_1_1_1' not found。
这类问题排查起来非常费力，因为报错信息不一定指向你安装过的那个库。我的经验是：不要为了一个软件去手动编译系统级的基础库。Rocky Linux 的仓库维护得不错，大部分依赖都能通过 AppStream 或者 EPEL 解决。如果项目要求特殊版本的 OpenSSL，优先考虑用容器方案隔离，而不是污染宿主系统。
另外，升级系统包时也要留个心眼。dnf update升级了底层依赖后，原先装在 venv 里的某些二进制扩展可能因为系统库接口变化而不能加载。这种问题通常表现为启动时 import 报错，解决方案是重建虚拟环境，把所有依赖重新装一遍。
5.4 高频错误速查表
| 现象 | 大概率原因 | 快速处理 |
|---|---|---|
hermes命令找不到 | 没有激活 venv 或 PATH 不对 | 使用/opt/hermes/app/venv/bin/hermes绝对路径 |
| Agent 启动后立即退出 | 配置文件权限不对或格式错误 | 检查config.yaml缩进和EnvironmentFile权限，用journalctl -u hermes-agent -n 50看日志 |
| Web UI 静态页面能打开但接口都挂 | Nginx 反代目标端口不对或 SELinux 拦截 | 确认ss -tlnp的实际监听端口，执行ausearch -m avc -ts recent查看 SELinux |
| API 请求返回 401 | Agent 与 Web UI 的密钥不一致 | 检查两边的 Token 配置，确保完全一致 |
| Web UI 刷新页面 404 | Nginxtry_files配置缺失 | 修改 Nginx 配置，加上try_files $uri $uri/ /index.html; |
这个速查表是我在实际运维中反复用到的几类问题，基本上能覆盖自己部署时八成以上的状况。如果遇到表格里没有的情况，不要慌，先看journalctl -u hermes-agent -n 100和/var/log/nginx/error.log，这两份日志能告诉你大部分答案。
Rocky Linux 上部署 Hermes Agent 和 Hermes-Web-UI，整体思路其实不复杂：Agent 提供服务，UI 套壳展示，Nginx 做对外入口。每一步只要理解了"为什么这样做"，排查问题时就有迹可循。我个人部署时比较看重的三个点：一是权限隔离，Agent 和 UI 都别用 root 跑；二是 Selinux 保持开启，遇到问题看审计日志而不是一关了之；三是一切服务都要通过 systemd 托管，确保重启后能自动恢复，省得半夜服务器重启后服务全挂还要手动拉起。
