多年在 Linux 服务器上折腾各种开源项目我对“装个东西跑起来”这件事已经习惯成自然。但最近帮朋友在一台 Rocky Linux 上部署 Hermes Agent 和 Hermes-Web-UI 时还是踩了好几个意料之外的坑从系统初始化到 Web 界面能正常打开前前后后折腾了大半天。事后我重新捋了一遍步骤把踩过的坑和绕过的弯路都整理出来就有了这篇完整指南。先说清楚 Hermes Agent 是干什么的。它是面向本地私有化部署场景的智能体服务端能够处理自然语言请求、按规则编排调用外部工具或 API同时对外开放一套标准的 HTTP/WebSocket 接口。Hermes-Web-UI 则是配套的可视化管理面板让使用者不用对着命令行也能完成会话调试、任务查看和配置管理。这套组合很适合两类人一类是希望在内部网络里搭建私有 AI 服务入口的运维工程师另一类是做智能体应用开发、需要自托管一套调试环境的后端开发。如果你是这两类人之一这篇指南可以直接照着抄。整篇我会从 Rocky Linux 系统初始化讲起覆盖 Agent 部署、Web-UI 部署、systemd 托管的完整细节还会把我在 SELinux、防火墙、Node.js 版本、配置格式这几个高频翻车点上的排查过程拿出来单独说一下。不同基础的读者各取所需新手建议顺序读完老手可以直接跳到常见问题部分。1. 环境准备与系统初始化1.1 为什么选 Rocky Linux 9.xRocky Linux 是 RHEL 的社区重建版本二进制兼容性做得很到位软件包体系成熟生命周期也长。对于 Hermes Agent 这种需要长期稳定运行的业务服务来说选它比选激进更新的发行版要省心得多。我这台机器用的是 Rocky Linux 9.4。9.x 相比 8.x 在安全性策略、系统服务管理、默认软件源版本上都有明显差异Hermes-Web-UI 构建时对 Node.js 版本有硬性要求需要 18 及以上而 Rocky Linux 9 自带的 nodejs 模块流更容易满足这个条件。如果你手头还是 8.x 版本建议优先考虑升级或改用 9.x否则后续构建 UI 时需要额外处理 Node.js 版本问题麻烦不少。1.2 静态 IP 和 yum 源配置服务器部署 Agent 服务固定 IP 基本是刚需。否则后面配置 Web-UI 对接 Agent 地址时IP 一变就全断了。Rocky Linux 9 默认使用 NetworkManager我习惯用nmcli来配置# 查看当前网络连接名称 nmcli con show # 修改连接为静态 IP假设网卡名为 ens160 sudo nmcli con mod ens160 ipv4.addresses 192.168.1.100/24 sudo nmcli con mod ens160 ipv4.gateway 192.168.1.1 sudo nmcli con mod ens160 ipv4.dns 8.8.8.8 114.114.114.114 sudo nmcli con mod ens160 ipv4.method manual # 生效 sudo nmcli con up ens160如果你更习惯直接编辑配置文件路径在/etc/NetworkManager/system-connections/下的对应ens160.nmconnection文件但用nmcli命令更不容易出错改完统一由 NetworkManager 管理。yum 源这块Rocky Linux 9 默认的源在海外国内服务器拉包速度容易让人崩溃。我在/etc/yum.repos.d/Rocky-Linux-AppStream.repo等文件中直接把baseurl中的dl.rockylinux.org换成国内镜像地址或者干脆保留官方源但用--setopttimeout5做超时规避。实测下来修改 baseurl 后dnf makecache的速度能提升好几倍后续安装依赖包的体验会好很多。1.3 基础依赖包安装安装前先把基础编译工具链和常用软件装上避免装到一半发现缺东西sudo dnf install -y epel-release sudo dnf update -y sudo dnf install -y tar gzip make gcc git python3 python3-pip这里说两个细节。第一epel-release 很重要有些依赖不是 Rocky 官方源直接提供的EPEL 里有不少补充包。第二Python 3 建议用系统自带的 3.9/3.11不要手动编译安装避免和系统包管理器产生冲突。这些包大部分在后续部署 Agent 和 Web-UI 时都会用到提前准备好能避免半路中断。2. Hermes Agent 部署与核心配置2.1 获取安装包与版本选择Hermes Agent 的发布包一般通过 GitHub Releases 分发下载时注意区分系统架构。绝大多数服务器是 x86_64但如果你跑在 ARM 架构的机器上比如树莓派或某些国产服务器需要选择对应的 arm64 版本。建议优先下载最新的稳定正式版本而不是预览版或 beta 版。正式版的配置项更稳定遇到的坑也少。下载方式可以直接在服务器上用wget或curl拉取如果服务器访问 GitHub 不稳定可以先在本地下载再传到服务器上。sudo mkdir -p /opt/hermes-agent sudo useradd -r -s /sbin/nologin hermes cd /opt/hermes-agent sudo tar xzf hermes-agent-linux-x64.tar.gz -C /opt/hermes-agent目录规划上我把所有 Agent 相关文件放在/opt/hermes-agent下配置文件和日志文件也放在该目录的子目录中方便统一管理和备份。这里我为 Agent 创建了独立的系统用户hermes这是一个重要的安全习惯。如果直接用 root 跑服务一旦 Agent 被外部请求利用攻击者拿到的就是 root 权限后果严重得多。2.2 配置文件编写要点解压后目录里一般会有个默认配置文件常见格式是config.toml或config.yaml。Hermes Agent 对配置文件格式比较敏感字段写错或缩进不对都会导致启动失败。我自己遇到过的典型问题是toml格式下字符串值必须加引号多行数组要用[ ]括起来这些细节出错时系统不会给你明确提示只会报一个“配置解析失败”的笼统错误。下面是一份我在实际环境中使用的配置示例关键项已脱敏[server] listen 0.0.0.0 port 8080 [log] level info path /var/log/hermes/hermes-agent.log [model] api_base http://127.0.0.1:11434/v1 api_key local-ollama model_name qwen2.5:14b [security] token please-change-me [network] request_timeout 120配置核心项有几个需要重点解释server 节点。监听地址如果设127.0.0.1那 Web-UI 在同一台机器上访问没问题但如果 Web-UI 部署在其他机器上就必须监听0.0.0.0同时对防火墙做好控制。端口我默认用了 8080如果你有服务占用可以换。model 节点。这是 Agent 对接大模型推理服务的入口。我这边对接的是本地的 Ollama 服务API 兼容 OpenAI 格式所以api_base填 Ollama 的默认地址。如果你对接的是其他推理框架只要它提供 OpenAI 兼容接口这里填对应的地址就行。model_name必须和实际模型名完全一致包括参数大小后缀否则调用时会报模型不存在。security 节点。token 是 Agent 对外服务的身份验证凭证Web-UI 对接时也要用到建议用openssl rand -hex 32生成一个足够随机的字符串不要图省事用默认值。配置文件改好后把目录权限调整一下sudo chown -R hermes:hermes /opt/hermes-agent sudo mkdir -p /var/log/hermes sudo chown hermes:hermes /var/log/hermes2.3 前台启动验证正式写 systemd 服务之前一定要先在前台跑一下能最快发现配置问题sudo -u hermes /opt/hermes-agent/hermes-agent --config /opt/hermes-agent/config.toml如果配置正确终端会滚动输出日志看到类似listening on 0.0.0.0:8080的消息就说明服务起来了。然后另开一个终端验证一下curl http://127.0.0.1:8080/health这个请求会返回包含状态信息的 JSON 响应。如果 curl 返回正常的健康检查结果就说明 Agent 的核心服务运行正常可以关闭前台进程进入 systemd 托管阶段。如果你的 Agent 版本没有 /health 接口也可以直接调一次根路径看是否返回服务信息和版本号。2.4 使用 systemd 托管 Agent 服务前台运行验证没问题后紧接着写 systemd 服务文件让 Agent 开机自启、崩溃自动拉起[Unit] DescriptionHermes Agent Service Afternetwork-online.target Wantsnetwork-online.target [Service] Typesimple Userhermes Grouphermes ExecStart/opt/hermes-agent/hermes-agent --config /opt/hermes-agent/config.toml Restarton-failure RestartSec5 LimitNOFILE65535 [Install] WantedBymulti-user.target写入/etc/systemd/system/hermes-agent.service后执行sudo systemctl daemon-reload sudo systemctl enable --now hermes-agent sudo systemctl status hermes-agent这里LimitNOFILE65535值得说两下。Agent 在处理大量并发请求时会创建很多网络连接和文件句柄系统默认的 1024 限制很容易不够用导致服务莫名其妙报too many open files错误。这是我之前踩过的坑加了这一项之后再没复现过。3. Hermes-Web-UI 部署与对接 Agent3.1 技术栈与运行环境准备Hermes-Web-UI 本质是一个前端展示加后端代理的小型应用。它需要 Node.js 环境来构建和运行我用的版本是 Node.js 20这是当前比较稳妥的 LTS 版本。Rocky Linux 9 官方源里默认的 nodejs 模块流版本偏低建议直接用 NodeSource 的 20.x 源sudo dnf install -y wget curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash - sudo dnf install -y nodejs node -v npm -v构建之前还需要确认 npm 源可用国内网络环境下把 npm 源切到国内镜像会更稳定npm config set registry https://registry.npmmirror.com3.2 获取源码与构建从 GitHub 拉取 Hermes-Web-UI 的源码后进入目录、安装依赖、构建这几个步骤是标准流程git clone https://github.com/your-org/hermes-webui.git /opt/hermes-webui cd /opt/hermes-webui npm installnpm install这一步耗时比较长依赖项多耐心等待即可。构建环节关键在看项目的 package.json 脚本。通常执行npm run build如果项目自带启动脚本构建完成后可以直接npm run start进入生产模式。不同版本的 UI 项目结构可能不同有的只需要构建静态文件然后用 Nginx 托管有的则自带后端服务进程需要区分处理。我这边用的是自带后端服务的版本所以继续走 npm 启动的路线。3.3 对接 Agent 环境变量配置UI 需要知道 Agent 的地址、端口和 token 才能建立通信。这些信息通常配置在项目的.env文件里。在项目根目录下cp .env.example .env vim .env我实际使用的配置项如下不同版本名称可能略有差异HERMES_AGENT_HOST192.168.1.100 HERMES_AGENT_PORT8080 HERMES_AGENT_TOKENplease-change-me BIND_HOST0.0.0.0 BIND_PORT3000这里HERMES_AGENT_HOST要注意如果 UI 和 Agent 部署在同一台机器写成127.0.0.1也没问题如果不是则必须写成对外可访问的 IP。token 必须和 Agent 配置里的security.token完全一致否则 UI 连接 Agent 时会一直报认证失败。3.4 Nginx 反向代理配置让用户直接通过 3000 端口访问 UI 不是不行但不够正式和安全。我这边用 Nginx 做了反向代理把 80 端口的请求转发到 3000 端口顺便把代理超时调大避免大模型请求时长时间等待导致前端报网关超时server { listen 80; server_name hermes.example.com; location / { 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_read_timeout 300s; } }装 Nginxsudo dnf install -y nginx sudo systemctl enable --now nginx注意如果你的服务器在 NAT 或内网环境记得把server_name换成实际域名或直接省略避免访问时出现 Host 校验不一致的问题。同样给 UI 也配一个 systemd 服务方便统一管理。这里就不再重复贴配置了结构参照 Agent 的服务文件即可唯一区别是User和ExecStart按 UI 项目的启动命令来填。4. 防火墙、SELinux 与开机自启整理4.1 放行端口Rocky Linux 默认启用 firewalld不开放端口的话服务监听正常但外部就是连不上。需要放行的端口有Agent 的 8080 端口、UI 的 3000 端口或 Nginx 的 80 端口sudo firewall-cmd --permanent --add-port8080/tcp sudo firewall-cmd --permanent --add-port3000/tcp sudo firewall-cmd --permanent --add-port80/tcp sudo firewall-cmd --reload sudo firewall-cmd --list-all这里有个细节如果你修改完防火墙之后服务还是不通可以先用curl在本机测试再在另一台机器测试用ss -lntp | grep 8080确认监听状态。逐层排除不要一上来就怀疑服务出问题。4.2 SELinux 对服务的限制这是 Rocky Linux 上最容易翻车的地方。SELinux 默认 enforcing 状态会拦截自定义服务执行某些操作——读取非常规路径文件、监听非常规端口、写入未标记目录等统统会被拒绝。表现就是服务起不来或者起来了但日志写不了journalctl里会刷出一堆Permission denied。我的处理方式分两步排查。第一步看服务状态和日志定位报错。第二步用ausearch -m avc -ts recent查一下有没有 SELinux 拒绝记录。如果确认是 SELinux 拦截可以选择针对性放行或者把这几个服务的域设为 permissivesudo semanage permissive -a hermes_agent_t如果你不确定策略类型名可以直接用audit2allow -a -M hermes_agent_local生成并加载自定义策略模块这在只会拦截特定操作的同时保留整体 SELinux 防护。不要图省事直接把 SELinux 改成 disabled生产环境里这么做风险太大。4.3 统一管理服务自启把 Agent 和 UI 都交给 systemd 之后后续维护就很方便了。总结一下我当前环境里的服务管理命令# Agent sudo systemctl enable --now hermes-agent.service sudo systemctl status hermes-agent.service # UI sudo systemctl enable --now hermes-webui.service sudo systemctl status hermes-webui.service # 日志查看 journalctl -u hermes-agent.service -f journalctl -u hermes-webui.service -f日志管理上systemd 的Journald默认会按大小自动清理但如果你希望长期保留日志建议在/etc/systemd/journald.conf中调整SystemMaxUse500M等参数。或者直接用配置文件里log.path指定的文件日志结合logrotate定期轮转避免日志文件无限增长把磁盘占满。5. 常见问题与排查技巧实录5.1 安装部署高频问题速查先把我这次部署过程中遇到的和朋友经常问的问题整理成表格方便后续排障对照问题现象可能原因解决方法Agent 启动即退出无明确报错配置文件格式错误或日志路径无权限前台运行看输出检查 toml 语法确认 log 目录属主与配置的 user 一致UI 页面能打开但连不上 Agenttoken 不一致或 Agent 监听地址限制核对.env中 token 与 Agent 配置Agent 监听0.0.0.0不要配127.0.0.1外部机器访问不上 8080 端口firewalld 未放行或 SELinux 拦截firewall-cmd --add-port用ausearch查 AV 拒绝日志Web-UI 构建时报 Node 版本过低系统 Node.js 版本不满足要求使用 NodeSource 20.x 源或nvm切换到项目要求的 LTS 版本调用模型时长时间无响应请求超时设置过短或模型名称错误调大request_timeout确认model_name与推理服务中的模型 ID 完全一致服务重启后无法启动Agent 数据文件损坏或端口被占用停服后备份数据目录检查端口占用ss -lntp清理后重启5.2 配置不当导致的连接问题连接问题是最容易出现但隐蔽性最高的。我举一个真实的排查案例。部署完成后UI 界面能正常打开但每次发起会话请求都会在几秒后报“请求失败”。一开始以为是大模型服务挂了结果检查 Ollama 服务一切正常用 curl 直接请求模型接口也通。后来逐个排查才发现UI 后端在转发请求到 Agent 时用的还是默认的127.0.0.1:8080。一开始我确实把 Agent 配置的监听改成了0.0.0.0但 UI 配置里我没同步修改导致 UI 进程访问本机 8080 端口时恰好撞上了另一个无关进程。把.env里HERMES_AGENT_HOST改成实际服务地址后问题消失。这个过程想说明一个道理配置项之间是有关联的。改一处的时候同时检查它的上下游配置Agent 的监听地址、UI 的连接地址、大模型的 API 地址这三者必须完全打通才行。5.3 模型对接和数据目录权限的技巧模型对接是 Agent 能否真正发挥价值的关键。初次配置时建议先用 curl 测试推理服务的连通性再填入 Agent 配置避免混淆问题边界curl http://127.0.0.1:11434/api/tags如果能看到模型列表说明推理服务正常。然后再测试具体的对话接口确认模型 ID 正确。这个步骤能把“Agent 配置问题”和“模型服务问题”清晰分离开。权限问题上数据目录的属主设置是一个容易忽略的细节。Agent 运行过程中会写数据文件、日志文件、会话记录等如果这些目录的属主不是hermes用户服务会在运行一段时间后突然报写入失败。我的原则是一个服务的相关目录统一归属该服务专用的系统用户权限设置为750或700不要用777这种宽松权限来偷懒。要知道777权限等于向所有本地用户开放读写存在安全风险。5.4 版本升级时的备份策略Agent 和 UI 的开发迭代速度都不慢升级版本是迟早的事。我的经验是升级前务必备份两样东西配置文件和数据目录。Agent 升级时新版本可能会自动迁移数据结构如果迁移中途出错旧数据可能被标记为旧版本而无法回退。备份命令也很简单直接打包目录sudo cp /opt/hermes-agent/config.toml ~/backup-hermes-agent-config.toml sudo tar czf ~/hermes-agent-data-backup.tar.gz /var/lib/hermes升级完成后先不急着覆盖生产配置在测试环境用同一份配置跑一遍确认无报错后再正式切换。我在一次 UI 升级中就吃过亏新版本把.env里的配置项名字改了旧配置直接启动失败幸好备份及时才没有影响线上环境。6. 性能调优与日常维护心得Agent 和 UI 都跑起来只是开始真正的挑战在于让它高效稳定地跑下去。这里分享几个我在实际使用中得出的调优方向。资源限制上除了前面提到的文件句柄数还要关注内存和 CPU 占用。Agent 处理请求时有并发上限默认值可能偏保守。如果你的服务器内存充足可以在配置里适当提高并发数但不要盲目调高否则高负载下反而会拖垮系统。一般建议从默认值开始用压测工具逐步加压观察到 CPU 或内存接近 70% 时找到红线再往回留 20% 的余量。日志轮转是另一个必须做好的事情。Agent 的日志在长时间运行后体积增长很快不轮转的话三个月就能撑满一个 40G 分区。我在/etc/logrotate.d/hermes-agent下配置了按天轮转、保留 30 份的策略/var/log/hermes/*.log { daily rotate 30 compress delaycompress missingok notifempty create 0640 hermes hermes }日常巡检也不复杂每周看一眼服务状态和日志关键错误即可。写个简单的脚本用 cron 跑检查hermes-agent.service是否为 active 状态如果不是就告警这样能在用户发现之前先处理掉问题。我还会定期检查磁盘空间特别是/var/log和 Agent 数据目录所在分区避免日志写满导致服务宕机。关于同一台机器上是否还要跑其他服务我的看法是尽量分离。Agent 和 Web-UI 可以同机部署但大模型推理服务比如 Ollama建议单独一台带 GPU 的机器。推理服务非常吃显存和算力与业务服务抢资源会影响整体响应速度。如果你只有一台机器至少要把资源限制配好用 systemd 的MemoryMax和CPUQuota防止推理服务把系统资源耗光。7. 写在最后的实操经验说实话这次部署 Hermes Agent 和 Hermes-Web-UI 的整个过程最花时间的不是 Agent 本身的安装而是各种环境层面的配合。静态网络配置、依赖版本、SELinux 策略、防火墙规则、配置格式这些看似基础的东西往往才是拦路虎。只要把系统初始化这一步做扎实了后面 Agent 和 UI 的部署反而比较顺利。在实践中我发现几个特别的习惯非常有用每次改配置前先备份原文件每次启动服务前先在前台跑一遍看报错每次排查问题先用journalctl定位错误再动手改配置。这三个习惯帮我避免了很多次“改来改去不知道哪里动坏了”的窘境。最后再分享一个小技巧。All in one 部署时可以把 Agent 的端口和 UI 的端口都固定下来然后在 Nginx 上做多个 server_name 转发这样通过不同的域名访问不同服务既清晰又好记。配合 HTTPS 证书内网使用体验会接近商业产品。我的这套部署已经在两台 Rocky Linux 9 服务器上稳定运行了几个月希望这篇指南也能让你少走弯路一次就把服务跑起来。