前几天在服务器上部署了一套私有化 AI Agent 环境底层系统用 Rocky Linux 9核心引擎跑 Hermes Agent管理界面用 Hermes-Web-UI。整套搞完以后最大的感受是真正的难点不在装包那一下而在系统环境、依赖版本、模型接口这三块的前置工作。这篇文章把完整过程记录下来包括每一步的选型理由、操作命令和排障思路给准备在 Rocky Linux 上部署 Hermes Agent 和 Hermes-Web-UI 的朋友做个参考。这套组合适合谁两类人很合适一类是有一台自己的云服务器或者物理机想把 AI 能力做成一个给团队内部使用的私有服务平台不愿意把对话数据直接送到第三方另一类是已经在使用 DeepSeek 等模型 API想有一个带界面、可管理、能扩展工具能力的 Agent 平台来统一调度。如果你是这两种情况之一这篇文章基本可以照着做。1. 为什么这套组合值得装角色定位与选型逻辑1.1 Hermes Agent 是“调度中心”不是模型本身很多第一次接触 Hermes Agent 的朋友容易把它当成一个“大模型”来理解。这里先把这个误区解掉。Hermes Agent 定位是一个智能体运行框架本身不提供推理能力它负责的是把大模型 API、工具调用、上下文记忆、任务编排这些能力组织起来。如果拿一个比较生活化的类比你可以把大模型想象成一位技能很强的专家Hermes Agent 就是这位专家的助理你给助理下达任务助理决定先调用哪项技能、按什么顺序执行、中间怎么管理上下文最后把结果整理给你。这个定位决定了部署时的一个重点你不能装完 Agent 就当完事了必须给它配好模型服务它才有实际价值。这也是为什么我在后面的章节专门留了一大块讲 API 对接。同时因为它是一个框架很多能力前端的 UI 是不一定来得及覆盖的。你会需要 Hermes-Web-UI 来把这些能力可视化。1.2 Hermes-Web-UI 的价值在一个“管”字如果只有 Hermes Agent 核心你面对的是一个命令行服务或者是一组 API。命令行对开发人员来说够用但对团队里不熟悉命令的同事来说学习成本就上来了。Hermes-Web-UI 解决的是“管理”的问题会话管理、模型参数调整、运行日志查看、API 地址的可视化暴露这些日常高频操作在 Web 界面里点几下就能完成。我在实际部署中见过一个典型场景两个节点的 Agent 服务都跑起来了但是因为没有界面同事想测试一个工具调用得先登进服务器看日志再写一段脚本去调接口效率很低。把 Hermes-Web-UI 装上以后这些问题都省掉了。所以我对这两个组件的定位是Agent 是发动机Web-UI 是仪表盘缺一个都不算完整的部署。1.3 Rocky Linux 作为底座的稳定优势系统选型我最终定了 Rocky Linux 9.x。原因有三点第一它和 RHEL 高度兼容生产环境里常见的运维工具链、安全基线都能直接沿用自己的经验第二每个大版本有长达十年的维护周期不需要半年一年就考虑跨版本升级第三社区活跃度稳定出问题能搜到的资料也比较多。当前 Rocky Linux 9.6 已经发布如果你手上是 9.4 或者 9.5只要还在支持周期内没有任何问题不是非要升级。我自己在服务器上是从 9.3 一路 dnf upgrade 上来的没有遇到兼容性问题。这里也建议新装系统直接装最新的 9.x 小版本就好省得后面补一堆安全更新。2. 动手之前静态IP、软件源和运行时环境一次配齐2.1 安装阶段的两个重要决定安装 Rocky Linux 时有两个决定会影响后面的部署提前说一下。第一个是软件包环境我建议只选“Server”基础环境不要选带 GUI 的 Workstation。Agent 和 Web-UI 都不需要桌面环境装 GUI 只会增加攻击面和资源占用。第二个是分区规划我给根分区给了 100G专门给 /var 单独分了 50G主要考虑是日志和后续的数据文件会持续增长。如果用的是云服务器默认分区问题也不大但建议看一眼磁盘空间至少保证根分区有 40G 以上的余量。安装时网络可以先选 DHCP进入系统以后再用 nmcli 配静态 IP。这样做的原因是安装界面的网络配置有时候会因为 NetworkManager 的后台策略问题重启后不生效还不如进系统后用命令行统一操作来得可控。2.2 用 nmcli 配置静态 IP重启不失效系统装好后第一步先把网络确认好。先看设备名和当前连接nmcli device status输出里会看到例如 ens160、ens3 这样的接口名。接下来用它配置静态 IPnmcli 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 nmcli connection up ens160第一行是配置静态地址、网关和 DNS第二行让连接立即生效。这里 192.168.1.100/24 只是一个示例你要根据自己的网段改。配完以后用ip addr show ens160和ping -c 4 192.168.1.1验证。如果 ping 不通网关多半是网段写错了或者网关写错了。这里有个小经验DNS 建议直接配公共 DNS 或者你所在云服务商的内部 DNS不要在多个配置文件里重复配否则系统启动后经常会出现“过一会儿才能解析域名”的怪问题。2.3 软件源调整把下载速度稳下来Rocky Linux 默认的 mirrorlist 在部分网络环境下速度忽高忽低特别是执行dnf install的时候遇到慢的镜像会非常影响体验。我习惯把软件源统一切到国内公共镜像源这里以阿里云镜像为例。sed -e s|^mirrorlist|#mirrorlist|g \ -e s|^#baseurlhttp://dl.rockylinux.org/$contentdir|baseurlhttps://mirrors.aliyun.com/rockylinux|g \ -i.bak /etc/yum.repos.d/Rocky-*.repo执行以后更新缓存dnf clean all dnf makecache如果你安装的是 Rocky Linux 8.10$contentdir对应的路径规则是一样的但 sed 里的替换逻辑要按实际文件内容调整最稳妥的方法是手动编辑/etc/yum.repos.d/下的仓库文件把 baseurl 改成https://mirrors.aliyun.com/rockylinux/$releasever/BaseOS/$basearch/os/这种结构。改完以后跑一次dnf repolist能看到仓库数量就说明没问题。换源这件事本身不影响系统安全但要注意不要为了图省事同时开一堆第三方仓库软件源够用就好减少依赖冲突的可能性。2.4 补齐编译工具、Python 和 Node.js软件源配好以后把系统更新一遍并安装基础工具dnf update -y dnf install -y vim wget curl git tar unzip lsof dnf install -y gcc gcc-c make openssl-devel其中gcc、openssl-devel这组编译工具非常重要。很多 Agent 依赖库在安装的时候会现场编译缺少这些头文件就会报错白白耽误时间。接下来装 Python 和 Node.js。Rocky Linux 9 自带 Python 3.9一般够用。如果你的 Hermes Agent 版本明确要求 Python 3.11 或更高就需要额外处理比如用源码编译或安装 Python 管理工具。这里先按通用情况装dnf install -y python3 python3-pip python3-develNode.js 建议装 20.x 长期支持版curl -fsSL https://rpm.nodesource.com/setup_20.x | bash - dnf install -y nodejs装完分别验证一下python3 -V和node -v确保终端里能看到版本输出。这一步虽然基础但很多人忽略版本检查等后面依赖装不上再回头看反而更浪费时间。3. Hermes Agent 核心部署从源码到首个请求3.1 目录规划与版本选择我习惯把这类服务统一放在/opt目录下面结构清晰、路径固定。实际命令mkdir -p /opt/hermes-agent cd /opt/hermes-agent git clone 官方仓库地址 .这里的仓库地址以你从项目官方网站拿到的为准。如果你下载的是压缩包解压到/opt/hermes-agent再进入目录也是一样的效果。这里我特别提醒一点拿到项目后先不要急着切到 main 分支跑先看仓库的 Releases 页面有没有正式发布版本优先用带 tag 的稳定版本。开发分支往往功能新但配套文档和兼容性未必跟得上生产环境里“稳定”比“新”重要。3.2 依赖安装的两条路径Hermes Agent 的后端可能采用 Python 或 Node.js 编写这与具体版本有关。实际部署时请先看项目根目录下的文件判断用哪种方式如果是 Python 项目根目录通常有requirements.txt安装命令是cd /opt/hermes-agent python3 -m venv venv source venv/bin/activate pip install -r requirements.txt如果是 Node.js 项目根目录通常有package.json安装命令是cd /opt/hermes-agent npm install无论哪种方式我都建议用虚拟环境或者项目自带依赖管理不要把依赖直接装进系统全局。这样做的最大好处是将来升级或者换版本时直接把目录删掉重来不会把系统环境搞得一团糟。依赖安装过程中如果出现编译报错不要急着搜报错信息先回去看 2.4 节的编译工具装齐没有。我遇到过的大部分编译失败都是因为缺少python3-devel或者gcc导致的。3.3 .env 配置参数说明与常见误区项目源码里通常会有一个.env.example或者.env.sample示例文件。我的习惯是把它复制成.env再编辑cp .env.example .env vim .env以下是常见的配置项具体字段名以你下载的版本为准HOST0.0.0.0 PORT3000 LOG_LEVELinfo DATA_DIR/opt/hermes-agent/data MODEL_PROVIDERdeepseek DEEPSEEK_API_KEYsk-xxxxxxxx DEEPSEEK_BASE_URLhttps://api.deepseek.com DEFAULT_MODELdeepseek-chat这里特别说明两个容易踩的坑。第一个HOST一定要设成0.0.0.0不能设成127.0.0.1。设成 127.0.0.1 的话虽然本机可以访问但其他设备完全连不上Web-UI 就算部署了也白搭。第二个因为项目会读取.env文件启动服务的时候要注意如果用了 systemdsystemd 本身已经会读取 EnvironmentFile 了有些配置就不要同时在 shell 里 export否则容易出现“我改了 .env 怎么没生效”的困惑。3.4 首次启动验证配置完.env以后先手动启动一次确认能跑起来。Python 项目cd /opt/hermes-agent source venv/bin/activate python3 main.pyNode.js 项目cd /opt/hermes-agent npm start看到日志中出现 listening 或者类似关键字就说明服务已经起来。此时在服务器本机验证curl http://127.0.0.1:3000如果返回正常代理服务本身没有问题。手动启动的目的是先把配置层、依赖层的错误暴露出来。确认没问题后再用 CtrlC 停掉进入下一步。如果你在这里手动启动就报错先去排查.env的字段名和依赖安装是否完整不要急着往下装 Web-UI不然后面会叠满问题很难定位。4. Hermes-Web-UI 上线让 Agent 从命令行走进浏览器4.1 获取前端工程并安装依赖Hermes-Web-UI 是一个独立的前端工程不包含在 Agent 主项目里。部署位置我建议放在/opt/hermes-web-uimkdir -p /opt/hermes-web-ui cd /opt/hermes-web-ui git clone 官方WebUI仓库地址 . npm install如果官方提供的是已经构建好的静态文件包那更省事直接解压到目标目录后跳到 4.3 的访问验证。如果是源码方式需要npm install后再构建构建命令通常是npm run build具体以 package.json 中 scripts 为准。有人会问为什么 Web-UI 要单独部署不能直接嵌在 Agent 里原因很简单职责分离。Agent 服务只负责业务逻辑和 APIWeb-UI 只负责静态资源和交互层两者通过 HTTP 接口通信。这样以后想换一个前端、或者再开发一个移动端界面都不需要动 Agent 核心。4.2 后端接口地址的配置时机Web-UI 需要知道 Agent 服务跑在什么地址才能在一个页面上往来的对话、模型状态这些数据。这个配置时机很重要一定要在构建之前配好。如果你的项目使用 Vite 构建常见做法是在根目录创建.env.local文件并设置环境变量VITE_API_BASE_URLhttp://127.0.0.1:3000这里稍微解释一下这种VITE_开头的前端环境变量在构建时会被编译进产物里如果构建完以后再改配置往往需要重新构建一次才能生效。所以配置顺序是先写地址再构建最后启动不要反过来。这里有一个容易被忽略的细节如果你用的是云服务器并且才从本机浏览器访问VITE_API_BASE_URL不能填127.0.0.1要填服务器的公网 IP 或者你预期的访问域名。否则浏览器会把这个地址当成你自己电脑的地址去访问结果就是 UI 能打开但数据全是空的。4.3 启动方式与登录验证构建完成后可以选择直接用 Node.js 启动产物目录也可以用静态服务器工具。这里给一个简单的启动方式cd /opt/hermes-web-ui npm run preview -- --host 0.0.0.0 --port 8080这个命令是把构建后的产物用本地预览模式跑起来监听 8080 端口。浏览器访问http://服务器IP:8080如果能出现登录页或者控制台页面说明 Web-UI 已经上线。首次登录一般需要初始化管理员账号按页面提示设置即可。登录进来以后第一时间检查两件事第一Agent 服务状态是否显示在线第二能否在页面上发起一次对话。如果这两步都通了说明整个链路 Web-UI - Agent - 模型 已经打通部署成功了一大半。5. 接通真实模型以 DeepSeek 为例的 API 配置5.1 Provider 配置的几个关键字段Agent 服务没有模型是不能干活的。在 Web-UI 或者.env中配置模型供应商时需要关注几个核心字段Provider 类型、Base URL、API Key、模型名称。以 DeepSeek 为例配置项大致含义如下配置项示例值说明Providerdeepseek供应商类型标识Base URLhttps://api.deepseek.com接口地址API Keysk-xxxx用于认证的密钥Modeldeepseek-chat默认使用的模型名Temperature0.7采样温度控制随机性Base URL 是非常容易配错的一项。有的模型服务商提供了兼容路径比如/v1有的直接提供根地址。如果配错了请求会 404所以如果发现请求一直报错先用 curl 直接验证地址是否可用再回来改配置。5.2 先用 curl 验证模型服务在把模型配置填到 Agent 之前我强烈建议先用 curl 把模型接口本身验证一遍。这一步能帮你在“Agent 配置问题”和“模型服务问题”之间快速画清界限。示例export DEEPSEEK_API_KEYsk-你的密钥 curl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -d { model: deepseek-chat, messages: [{role: user, content: 你好}] }注意密钥不要直接写在命令行里先 export 到环境变量避免出现在 shell 历史记录中。如果 curl 能正常返回带content字段的 JSON说明模型接口没问题接下来的问题都可以圈定在 Agent 侧的配置上。如果 curl 返回认证错误先检查 API Key 是不是复制完整了有没有多余空格或者换行符。返回余额不足就充值返回模型不存在就检查模型名。这些错误信息指向性很强照着处理就好。5.3 让 Agent 使用工具与技能模型接口通了以后Agent 的价值才真正体现它可以调用工具。在 Hermes-Web-UI 的设置页面里一般会有工具管理或者技能管理相关的入口。常见的工具有网络搜索、文件读写、计算器、定时任务等。第一次配置的时候不要一下子全开我建议先只开一个工具测试 Agent 能不能正确调用等链路稳定了再逐步放开。工具全开会有个隐患某些工具调用失败的话整个对话的响应时间会明显变长而且日志会比较难读。另外如果你打算把 Agent 的能力接入其他应用比如通过 API 集成到流程编排平台或者绘图工具需要注意工具调用的参数格式是否与目标应用兼容。不同工具对输入输出的格式要求不同具体支持情况以官方文档为准。我的经验是先把 Agent 自带 API 的调用方式吃透再用脚本模拟一次最后才接到正式环境。6. 固化服务systemd 托管与防火墙放行6.1 Agent 服务的 Unit 文件手动启动没问题之后最重要的一步就是把服务托管给 systemd否则服务器一重启你就得手动敲命令再起一次。Agent 服务对应的 Unit 文件如下cat /etc/systemd/system/hermes-agent.service EOF [Unit] DescriptionHermes Agent Service Afternetwork-online.target Wantsnetwork-online.target [Service] Userroot WorkingDirectory/opt/hermes-agent EnvironmentFile/opt/hermes-agent/.env ExecStart/opt/hermes-agent/venv/bin/python /opt/hermes-agent/main.py Restarton-failure RestartSec5 StandardOutputjournal StandardErrorjournal [Install] WantedBymulti-user.target EOF这里的ExecStart要根据你的实际启动命令调整。如果项目是 Node.js 写的就改成类似/usr/bin/node /opt/hermes-agent/server.js。关键是启动命令要用绝对路径不要用相对路径也不要依赖 shell 的环境变量因为 systemd 默认的环境和手动登录 shell 不完全一样。6.2 Web-UI 服务的 Unit 文件Web-UI 服务的 Unit 文件类似我通常会这样写cat /etc/systemd/system/hermes-web-ui.service EOF [Unit] DescriptionHermes Web UI Service Afternetwork-online.target hermes-agent.service Wantsnetwork-online.target [Service] Userroot WorkingDirectory/opt/hermes-web-ui ExecStart/usr/bin/npm run preview -- --host 0.0.0.0 --port 8080 Restarton-failure RestartSec5 StandardOutputjournal StandardErrorjournal [Install] WantedBymulti-user.target EOF如果你直接用 Node.js 加载构建产物也可以把ExecStart写成/usr/bin/npx serve -s /opt/hermes-web-ui/dist -l 8080。这类命令在 systemd 下跑的时候要注意如果启动用到 npx首次运行可能提示下载包反而造成启动失败因此我更推荐使用已经构建好的静态文件然后直接用 Node 进程托管避免每次启动都依赖 npm 的运行时解析。6.3 开机自启、状态查看与日志定位配置好两个 Unit 文件后执行systemctl daemon-reload systemctl enable --now hermes-agent hermes-web-uienable --now等于同时实现开机自启和立即启动。查看状态用systemctl status hermes-agent查看日志用journalctl -u hermes-agent -f这两个命令在后面的故障排查里会反复用到。如果你发现服务启动失败不要急着反复 restart先看journalctl的最后几行日志大部分问题都能从那里直接看出来。别凭感觉乱改配置改之前先留个备份比如cp /opt/hermes-agent/.env /opt/hermes-agent/.env.bak另外别忘了放行防火墙端口。默认情况下 firewalld 可能是开启的不放行的话外部访问不了firewall-cmd --permanent --add-port3000/tcp firewall-cmd --permanent --add-port8080/tcp firewall-cmd --reload如果你的 Web-UI 端口是 8080就放行 8080如果 Agent 的 API 也需要对外提供服务就放行 3000。不需要对外暴露的端口就别开网络安全的关键在“最小暴露面”。7. 踩坑复盘部署中常见的五个问题7.1 UI 能开但始终“连不上后端”这个问题在部署 Web-UI 时出现频率最高。现象是浏览器能打开页面登录后一片空白或者一直提示后端不可达。我排查的顺序一般是这样的先在服务器本机执行curl http://127.0.0.1:3000如果本机不通说明 Agent 服务根本没起来或者端口不是 3000。如果本机通了再检查你在前端.env.local里配置的VITE_API_BASE_URL是不是用了一个浏览器访问不到的内网地址。很多云服务器会同时存在公网 IP 和内网 IP浏览器执行 JS 时是去访问那个具体地址的如果你填了内网 IP浏览器当然访问不了。把地址改成公网 IP 或者域名后重新构建即可。还有一类原因是防火墙没放行。所以在检查完地址后务必顺手执行一次firewall-cmd --list-all看看端口放行规则。7.2 模型请求一直超时模型请求超时要从三个方向排查网络、密钥、模型名。先按 5.2 节的 curl 方法直接请求模型接口能通就说明网络没问题。如果 curl 能通但 Agent 里超时重点看.env或者管理界面里的 Base URL 是不是多了个/v1或者少了斜杠。这类细节错误最隐蔽因为看起来“好像没错”。另外如果你用的服务器和模型服务所在区域不一致跨区域请求延迟会明显偏高。这种情况下优先选择有就近节点的模型服务商或者选择在相同区域部署 Agent这是架构层面的选择不是改配置能解决的。7.3 服务启动后没多久就退出服务启动后跑了几秒钟就自动退出这是典型的依赖或配置问题。先看日志journalctl -u hermes-agent --no-pager | tail -n 50如果日志里出现无法加载 .env、端口被占用、数据库目录无权限这几种常见提示按提示处理即可。如果是“没有那个文件或目录”这类信息多半是 ExecStart 里的路径写错了。systemd 十分强调绝对路径你在手动启动时能跑通不代表 systemd 能找到同样的文件因为登录 shell 有 PATH 环境变量systemd 没有。这里我吃过一次亏手动启动时用的命令是python3 main.py写 Unit 文件时我写成了/usr/bin/python3 /opt/hermes-agent/main.py结果发现系统里 python3 的路径不是这个服务一直起不来。后来我用which python3查到实际路径才改对。7.4 端口被占用检查端口占用情况lsof -i :3000如果发现端口被其他进程占用要么把 Agent 的端口改掉要么停掉占用进程。改端口的时候要注意联动修改改完 Agent 的.env里的 PORTWeb-UI 里的VITE_API_BASE_URL也要跟着改而且前端需要重新构建。我自己部署的时候就把 3000 端口改成了 3100因为那里已经有一个监控服务在跑改完以后一定要记住改 UI 那边否则又是“UI 打不开”的经典问题。7.5 升级与回滚最后说下升级。Hermes Agent 这类项目迭代快升级时我习惯按这个顺序操作先备份数据目录和.env再停服务再备份当前代码目录然后拉取新版本、安装新依赖最后启动服务看日志。一旦发现异常用之前备份的目录整体回滚。具体命令这里不展开因为不同版本差异较大核心原则是一条永远让系统里保留一个“上一秒还能正常工作”的快照。对于数据目录建议至少每天做一次定时备份或者用云服务商提供的快照功能。Agent 的配置可以随时重建但会话数据、知识库数据一旦丢就很难找回。如果你发现自己的部署里存在“没有备份”的情况即使只是运维小白也应该在完成部署的当天把这一课补上。再说一个实际操作中的体会。服务托管到 systemd 之后很多人就不管了。我现在的习惯是每周固定看一次日志不需要分析所有内容重点看有没有反复出现的 error 或 timeout。这样做的原因是Agent 这类服务跑久了最容易出现的问题不是崩溃而是一些慢性的性能劣化和 API 配额用尽。早发现早处理远比出了事故再排查来得省钱省力。还有个实用技巧把所有服务的端口、日志路径、数据目录整理成一份简单的表格放在服务器上或者团队文档里。别小看这一步过两个月你再回来维护这套系统这份记录能让你少花一晚上。部署完成不是结束真正让这套 Hermes Agent Hermes-Web-UI 产生价值的是你持续维护它的那段时间。