Hermes Agent 安装与部署操作手册（局域网小主机）

Hermes Agent 安装与部署操作手册

环境：Ubuntu 26.04.1 LTS x86_64

软件版本：Hermes Agent v0.22.4

文档范围： 从本次对话中能够确认的安装、认证、模型调用、Gateway、Web Dashboard、systemd 服务及故障排查全过程。

一、最终部署环境

1.1 系统与网络信息

项目	实际配置
Linux 系统	Ubuntu 26.04.1 LTS
主机名	`n1705`
运行用户	`hermes`
用户 UID	`1003`
用户主目录	`/home/hermes`
Hermes 可执行文件	`/home/hermes/.local/bin/hermes`
Hermes 配置目录	`/home/hermes/.hermes/`
主配置文件	`/home/hermes/.hermes/config.yaml`
环境变量文件	`/home/hermes/.hermes/.env`
局域网 IP	`192.168.1.47`
Windows 电脑 IP	`192.168.1.35`
Windows 代理地址	`192.168.1.35:10808`
Gateway	`hermes-gateway.service`
Dashboard	`hermes-dashboard.service`
Dashboard 端口	TCP 9119
浏览器访问地址	`http://192.168.1.47:9119/`

注意：以上网络地址来自本次部署记录。若以后路由器重新分配了 IP，应以实际地址为准。

1.2 模型配置

本次使用的模型是：

模型标识：upstage/solar-mini4:free
Provider：nous
API Endpoint：https://inference-api.nousresearch.com/v1
认证方式：Nous Portal 登录认证

模型曾经实际返回过：

Hermes 模型调用测试成功。

因此可以确认：当时的认证、网络连接和模型调用链路至少已经成功运行过一次。

:free 代表当前使用的模型标识，不能据此保证永久免费或没有使用限制。

二、安装与运行用户

2.1 为什么使用专用用户

本次采用 hermes 用户运行 Hermes，而不是始终以 root 身份运行。

这样可以将程序配置、会话文件和服务进程集中在：

/home/hermes/
├── .local/bin/hermes
├── .hermes/
│   ├── config.yaml
│   └── .env
└── .config/
    └── systemd/
        └── user/
            └── hermes-dashboard.service

这也意味着，直接在 root 终端输入 hermes 可能出现“找不到命令”。这是因为程序所在目录不一定在 root 的 PATH 中，并不意味着 Hermes 已经被卸载。

2.2 确认可执行文件

# 查看 Hermes 可执行文件是否存在
ls -l /home/hermes/.local/bin/hermes

# 查看 Hermes 用户信息
id hermes

# 查看当前 Hermes 版本
runuser -u hermes -- bash -c '
export HOME=/home/hermes
export PATH="$HOME/.local/bin:$PATH"
hermes --version
'

本次实际检查确认：

-rwxr-xr-x 1 hermes hermes ... /home/hermes/.local/bin/hermes

已知版本为 0.22.4。

关于最初的安装命令： 当前保留的对话记录没有完整呈现最初下载、安装程序及其依赖的每条命令，因此这里不虚构安装命令。上面是安装完成后能够确认的目录和验证方式。

三、配置认证与模型

3.1 配置文件位置

Hermes 的主要配置文件为：

/home/hermes/.hermes/config.yaml

环境变量与认证相关配置位于：

/home/hermes/.hermes/.env

这两个文件用途不同：

config.yaml：保存模型、Provider、应用行为等配置。
.env：保存环境变量形式的认证信息和其他秘密配置。

不要将 .env 上传到公开 GitHub 仓库，也不要在公开截图中暴露密码或 Token。

3.2 Nous Portal 认证

本次安装后，Hermes 的诊断结果确认 Nous Portal 已经登录。

这说明认证流程已经完成，但不能据此认定所有模型渠道都永久免费。

3.3 确认当前模型

进入 Hermes 交互界面后，可以检查当前模型信息。Web Dashboard 中的会话信息也曾显示：

model: upstage/solar-mini4:free
provider: nous
version: 0.22.4

如果以后切换模型，应以实际配置和当前会话信息为准。

四、配置网络代理并测试模型

4.1 本次代理环境

本次测试使用 Windows 电脑提供的代理服务：

代理主机：192.168.1.35
代理端口：10808
代理协议：HTTP

注意：这里使用的是 HTTP 代理地址，并不是 SOCKS5 地址。请确认 Windows 端的 *****N 或代理软件确实开放了对应的 HTTP 代理端口。

4.2 使用代理运行模型调用测试

本次实际成功执行的命令如下：

runuser -u hermes -- env \
  HOME=/home/hermes \
  http_proxy=http://192.168.1.35:10808 \
  https_proxy=http://192.168.1.35:10808 \
  HTTP_PROXY=http://192.168.1.35:10808 \
  HTTPS_PROXY=http://192.168.1.35:10808 \
  bash -c '
    cd /home/hermes
    export PATH="$HOME/.local/bin:$PATH"
    hermes -z "请只回复：Hermes 模型调用测试成功。"
  '

参数解释：

参数	作用
`runuser -u hermes`	以专用用户运行
`env`	为本次进程设置环境变量
`HOME=/home/hermes`	指定用户主目录
`http_proxy`、`https_proxy`	设置 HTTP、HTTPS 请求使用的代理
`HTTP_PROXY`、`HTTPS_PROXY`	同时设置大写形式的代理变量
`cd /home/hermes`	切换工作目录
`PATH=...`	让系统能够找到 Hermes 命令
`hermes -z`	执行本次测试所使用的非交互调用方式

实际返回内容：

Hermes 模型调用测试成功。

这证明当时模型调用成功。

重要限制： 这条命令中的代理变量只对本次启动的进程及其子进程生效。它不能证明代理已经永久配置到 Gateway、Dashboard 或整个系统中。如果后续模型调用失败，应分别检查对应服务的代理环境变量。

五、启动并配置 Hermes Gateway

Gateway 与 Dashboard 是两个不同的服务：

Gateway：负责 Hermes 的网关、消息通道及相关后台功能。
Dashboard：提供浏览器访问的 Web 控制台。

因此，Gateway 正常运行不代表 Dashboard 一定正常运行。

5.1 启用用户级 systemd 常驻

本次执行过：

# 允许 hermes 用户退出登录后继续运行用户级服务
loginctl enable-linger hermes

# 查看 linger 状态
loginctl show-user hermes -p Linger

预期结果：

Linger=yes

enable-linger 的作用是让该用户的 systemd 用户管理器能够在没有交互式登录会话时继续运行，并支持用户级服务随系统启动。

5.2 确认用户级 systemd 管理器

# 查看 hermes 用户的 systemd 管理器
systemctl status user@1003.service --no-pager

本次检查结果为：

Active: active (running)

5.3 用户级 systemd 命令需要的环境变量

本次运行 systemctl --user 时，使用了：

XDG_RUNTIME_DIR=/run/user/1003
DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1003/bus

它们分别用于指定用户运行时目录和 D-Bus 会话地址。

5.4 Gateway 状态检查

# 查看 Gateway 状态
runuser -u hermes -- bash -c '
export XDG_RUNTIME_DIR=/run/user/1003
export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1003/bus
export PATH="$HOME/.local/bin:$PATH"
cd /home/hermes
hermes gateway status
'

本次记录确认 Gateway 曾经启动成功，且 hermes-gateway.service 出现在用户级 systemd 服务列表中。

5.5 Gateway 开机启动

本次执行过：

# 设置 Gateway 随用户级 systemd 管理器启动
runuser -u hermes -- env \
  XDG_RUNTIME_DIR=/run/user/1003 \
  DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1003/bus \
  systemctl --user enable hermes-gateway.service

启用后检查过服务状态，结果为 enabled。

这表示已经配置了开机启动，但本次对话没有进行实际的 Ubuntu 重启测试，因此仍建议在维护窗口验证重启后的服务状态。

六、配置 Dashboard 登录认证

6.1 本次配置的认证变量

本次在 /home/hermes/.hermes/.env 中添加了以下变量：

HERMES_DASHBOARD_BASIC_AUTH_USERNAME
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD
HERMES_DASHBOARD_BASIC_AUTH_SECRET

其中：

USERNAME：Dashboard 登录用户名。
PASSWORD：Dashboard 登录密码。
SECRET：随机生成的秘密值。

本次用户名为 tyrains。密码不在本文中记录。

6.2 创建认证配置时使用的命令

# 输入 Dashboard 用户名
read -rp 'Dashboard 登录用户名: ' DASH_USER

# 隐藏输入 Dashboard 密码
read -rsp 'Dashboard 登录密码（建议使用强密码）: ' DASH_PASS
echo

# 生成随机秘密值
DASH_SECRET=$(openssl rand -base64 32)

# 将认证变量追加到 Hermes 的环境变量文件
printf '\nHERMES_DASHBOARD_BASIC_AUTH_USERNAME=%s\nHERMES_DASHBOARD_BASIC_AUTH_PASSWORD=%s\nHERMES_DASHBOARD_BASIC_AUTH_SECRET=%s\n' \
  "$DASH_USER" "$DASH_PASS" "$DASH_SECRET" \
  >> /home/hermes/.hermes/.env

# 设置文件所有者
chown hermes:hermes /home/hermes/.hermes/.env

# 限制文件访问权限
chmod 600 /home/hermes/.hermes/.env

# 清除当前 Shell 中的临时变量
unset DASH_USER DASH_PASS DASH_SECRET

chmod 600 表示只有文件所有者可以读写该文件，其他用户没有访问权限。

如果将来需要重新配置密码，建议先备份 .env，检查现有变量是否已存在，再更新对应条目，避免重复添加多组同名变量。

七、启动 Dashboard 并实现局域网访问

7.1 原始启动方式

最初使用的命令为：

# 以前台模式启动 Dashboard
runuser -u hermes -- bash -c '
cd /home/hermes
export PATH="$HOME/.local/bin:$PATH"
exec hermes dashboard --host 0.0.0.0 --port 9119 --no-open
'

成功时输出：

HERMES_DASHBOARD_READY port=9119
Hermes Web UI → http://0.0.0.0:9119

参数含义：

参数	作用
`dashboard`	启动网页控制台
`--host 0.0.0.0`	监听所有 IPv4 网络接口
`--port 9119`	使用 TCP 9119 端口
`--no-open`	不自动打开浏览器
`exec`	用目标程序替换当前 Shell 进程

7.2 为什么关闭 SSH 后网页无法访问

最初的 Dashboard 是在 SSH 终端中以前台方式运行的。

当前台进程随着终端或登录会话退出而结束时，网页服务就会停止。

因此，浏览器打不开网页并不一定意味着 Gateway、模型认证或 Hermes 安装出了问题；也可能只是 Dashboard 没有继续运行。

7.3 检查监听端口

# 检查 9119 端口是否在监听
ss -lntp | grep ':9119'

本次曾看到：

LISTEN ... 0.0.0.0:9119 ... users:(("hermes",pid=...,fd=...))

这表示某个 Hermes 进程正在监听 9119 端口。

7.4 检查本机 HTTP 响应

# 测试本机 Dashboard 是否返回 HTTP 响应
curl -sS -o /dev/null \
  -w 'HTTP 状态码：%{http_code}\n' \
  --max-time 5 \
  http://127.0.0.1:9119/

本次结果：

HTTP 状态码：302

302 表示服务器将请求重定向到登录页面。对于未登录的 Dashboard，这是正常响应，说明 HTTP 服务能够处理请求。

7.5 设置 UFW 局域网访问规则

本次添加过：

# 只允许局域网网段访问 9119 端口
ufw allow from 192.168.1.0/24 to any port 9119 proto tcp

此规则允许 192.168.1.0/24 网段的设备访问 Dashboard，而不是向所有来源开放该端口。

检查规则：

# 查看 UFW 状态和规则
ufw status numbered

Windows 浏览器访问地址：

http://192.168.1.47:9119/

由于使用 HTTP 而非 HTTPS，浏览器可能显示“不安全”提示。这个提示与 SSH 是否关闭是两个不同的问题。

八、将 Dashboard 改为 systemd 后台服务

这是本次对话中最关键的修复步骤。

8.1 创建用户级服务目录

# 创建 hermes 用户的 systemd 配置目录
mkdir -p /home/hermes/.config/systemd/user

8.2 创建服务文件

文件路径：

/home/hermes/.config/systemd/user/hermes-dashboard.service

实际配置内容：

[Unit]
Description=Hermes Agent Web Dashboard
After=network.target

[Service]
Type=simple
WorkingDirectory=/home/hermes
Environment=HOME=/home/hermes
Environment=PATH=/home/hermes/.local/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/home/hermes/.local/bin/hermes dashboard --host 0.0.0.0 --port 9119 --no-open
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

创建命令：

# 写入 Dashboard 服务配置
cat > /home/hermes/.config/systemd/user/hermes-dashboard.service <<'EOF'
[Unit]
Description=Hermes Agent Web Dashboard
After=network.target

[Service]
Type=simple
WorkingDirectory=/home/hermes
Environment=HOME=/home/hermes
Environment=PATH=/home/hermes/.local/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/home/hermes/.local/bin/hermes dashboard --host 0.0.0.0 --port 9119 --no-open
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
EOF

# 将用户配置目录交给 hermes 用户管理
chown -R hermes:hermes /home/hermes/.config

# 设置服务文件权限
chmod 644 /home/hermes/.config/systemd/user/hermes-dashboard.service

8.3 各项服务配置的作用

配置	作用
`[Unit]`	定义服务名称和依赖关系
`After=network.target`	在网络目标之后启动
`Type=simple`	以普通前台进程形式托管
`WorkingDirectory`	指定工作目录
`Environment=HOME`	指定用户主目录
`Environment=PATH`	指定程序搜索路径
`ExecStart`	定义实际启动命令
`Restart=on-failure`	异常退出后自动尝试重启
`RestartSec=5`	重启前等待 5 秒
`WantedBy=default.target`	将服务关联到用户级默认启动目标

需要注意，服务文件中的 PATH 设置并不等同于完整复制所有交互式 Shell 环境变量。若将来遇到代理、认证或其他环境变量问题，应根据实际需要为服务添加明确的环境配置。

8.4 重新加载、启用并启动

本次使用以下命令：

# 重新加载 hermes 用户的 systemd 配置
runuser -u hermes -- env \
  XDG_RUNTIME_DIR=/run/user/1003 \
  DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1003/bus \
  systemctl --user daemon-reload

# 设置 Dashboard 开机自动启动
runuser -u hermes -- env \
  XDG_RUNTIME_DIR=/run/user/1003 \
  DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1003/bus \
  systemctl --user enable hermes-dashboard.service

# 启动 Dashboard 后台服务
runuser -u hermes -- env \
  XDG_RUNTIME_DIR=/run/user/1003 \
  DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1003/bus \
  systemctl --user start hermes-dashboard.service

daemon-reload 让 systemd 重新读取服务文件；enable 设置开机启动关联；start 立即启动服务。

九、排查端口冲突

9.1 本次遇到的错误

第一次启动 systemd 服务时，出现：

Active: activating (auto-restart) (Result: exit-code)
status=75

与此同时，端口检查显示：

LISTEN ... 0.0.0.0:9119 ... users:(("hermes",pid=2447564,fd=15))

日志进一步显示：

Port 9119 on 0.0.0.0 is already in use
BACKEND_PORT_IN_USE port=9119

原因是原来的前台 Dashboard 进程仍然占用 9119 端口，而 systemd 又尝试启动另一个 Dashboard。

9.2 正确排查顺序

先查看服务状态：

runuser -u hermes -- env \
  XDG_RUNTIME_DIR=/run/user/1003 \
  DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1003/bus \
  systemctl --user status hermes-dashboard.service --no-pager

再查看最近日志：

runuser -u hermes -- env \
  XDG_RUNTIME_DIR=/run/user/1003 \
  DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1003/bus \
  journalctl --user -u hermes-dashboard.service -n 30 --no-pager

最后检查监听进程：

ss -lntp | grep ':9119'

如果确定是旧的前台进程占用端口，应先在其原 SSH 窗口按 Ctrl+C，然后再启动 systemd 服务。

如果旧终端已经关闭，可以根据 ss 输出中的 PID 检查进程归属和命令行。不要反复杀死 PID 或盲目重启服务，因为 systemd 的自动重启策略可能会让新的进程立即出现。

9.3 本次最终结果

处理后，状态检查显示：

Active: active (running)

日志显示：

HERMES_DASHBOARD_READY port=9119
Hermes Web UI → http://0.0.0.0:9119

本机 HTTP 测试显示：

HTTP 状态码：302

同时，ss 确认 9119 端口正在监听。

因此，本次已经确认 Dashboard 成功由 systemd 后台服务启动，服务配置也已启用。

十、日常管理命令

以下命令均适用于本次部署的 hermes 用户级服务。

10.1 查看 Dashboard 状态

runuser -u hermes -- env \
  XDG_RUNTIME_DIR=/run/user/1003 \
  DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1003/bus \
  systemctl --user status hermes-dashboard.service --no-pager

10.2 重启 Dashboard

runuser -u hermes -- env \
  XDG_RUNTIME_DIR=/run/user/1003 \
  DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1003/bus \
  systemctl --user restart hermes-dashboard.service

10.3 停止 Dashboard

runuser -u hermes -- env \
  XDG_RUNTIME_DIR=/run/user/1003 \
  DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1003/bus \
  systemctl --user stop hermes-dashboard.service

10.4 查看最近 50 条日志

runuser -u hermes -- env \
  XDG_RUNTIME_DIR=/run/user/1003 \
  DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1003/bus \
  journalctl --user -u hermes-dashboard.service -n 50 --no-pager

10.5 检查 Gateway

runuser -u hermes -- env \
  XDG_RUNTIME_DIR=/run/user/1003 \
  DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1003/bus \
  systemctl --user status hermes-gateway.service --no-pager

10.6 查看端口占用

ss -lntp | grep ':9119'

十一、最终验收清单

以下项目可以作为以后检查部署是否正常的依据。

十二、后续维护建议

保存配置备份。 重点备份 config.yaml、.env 和 hermes-dashboard.service。备份 .env 时要保护其中的密码和秘密值。
不要重复以前台模式启动 Dashboard。 日常使用 systemd 管理，避免两个实例同时占用 9119。
出现网页打不开时，先检查服务状态。 不要直接重装 Hermes 或修改防火墙。
留意代理配置。 当前记录能够确认模型调用测试使用过临时代理环境变量，但不能确认所有后台服务都已永久配置代理。
注意安全。 当前 Dashboard 使用 HTTP。若将来需要跨公网访问，应考虑 HTTPS、访问控制和网络隔离，不要简单地将 9119 暴露到整个互联网。

本次部署总结： Hermes Agent 已安装并成功调用模型；Gateway 与 Dashboard 已分别运行；Dashboard 已配置为独立的 systemd 用户服务，并设置了开机启动。剩余工作主要是关闭 SSH 后的访问验证和系统重启验证。

posted @ 2026-10-22 11:41 tyrains 阅读(3) 评论(0) 收藏举报

刷新页面返回顶部

tyrains