Hermes Agent — 在 K3s / K8s 中运行指南
内容提要
本文介绍在 K3s/K8s 中部署 Hermes Agent：先用 nerdctl 运行 setup 容器，将 API 密钥等配置写入宿主机目录并挂载；再以 StatefulSet 部署 Gateway 后台服务和 Dashboard 仪表盘，二者共享持久化数据卷，Dashboard 只读挂载并通过环境变量连接 Gateway；可通过 kubectl exec 进入容器运行交互式 CLI 聊天，并用 port-forward 安全访问仪表盘。
延伸解读
持久化数据目录的关键作用
文章强调在首次运行前必须通过 setup 容器将配置写入宿主机目录 /var/lib/hermes-data，再挂载到容器。该目录包含 .env、config.yaml、sessions、memories 等，是 Agent 状态和记忆的核心。若跳过此步骤，Gateway 和 Dashboard 将无法读取配置，导致服务启动失败或行为异常。因此，正确初始化并持久化该目录是部署成功的前提。
Gateway 与 Dashboard 的协作与资源分配
Gateway 作为后台服务运行在 8642 端口，Dashboard 运行在 9119 端口，并通过环境变量 GATEWAY_HEALTH_URL 指向 Gateway 的 Service DNS 名称进行健康检查。两者共享同一个 PVC，但 Dashboard 以只读方式挂载，避免意外修改数据。资源请求上，Gateway 分配了更高的内存和 CPU 限额，而 Dashboard 需求较低，这种差异反映了各自的工作负载特性。
安全访问与网络暴露建议
文章建议使用 kubectl port-forward 将 Dashboard 的 9119 端口转发到本地，并通过 localhost 访问，而不是将服务直接暴露为 NodePort 或 LoadBalancer。这样做可以减少攻击面，尤其适合内部管理场景。同时，Gateway 的 Service 类型为 ClusterIP，仅在集群内部可用，进一步限制了外部直接访问。遵循这些建议有助于降低安全风险。
交互式 CLI 的便捷入口
部署完成后，可以通过 kubectl exec 进入 Gateway 容器，执行 /opt/hermes/.venv/bin/hermes 启动交互式聊天。这为调试和日常使用提供了直接通道，无需额外暴露端口或服务。该方式依赖于已配置好的数据目录，因此确保 setup 步骤正确执行是关键。对于习惯命令行的用户，这是一种高效的操作方式。
Q&A
如何在 K3s 或 K8s 中部署 Hermes Agent？
部署 Hermes Agent 需要先进行初始化配置，然后部署 Gateway 后台服务和 Dashboard 仪表盘。具体步骤包括：使用 nerdctl 运行 setup 容器将配置写入宿主机目录，创建 PersistentVolumeClaim，部署 Gateway StatefulSet 和 Dashboard StatefulSet，最后通过 port-forward 访问仪表盘。
Hermes Agent 的初始化配置怎么做？
在目标节点上创建数据目录（如 /var/lib/hermes-data），然后使用 nerdctl 运行一次性 setup 容器：sudo nerdctl run -it --rm -v /var/lib/hermes-data:/opt/data nousresearch/hermes-agent:latest setup。配置完成后，数据目录会包含 .env、config.yaml、SOUL.md 等文件。
如何部署 Hermes Agent 的 Gateway 后台服务？
使用 StatefulSet 部署 Gateway，参考 YAML 中定义 Service、PersistentVolumeClaim 和 StatefulSet。关键配置包括：镜像 nousresearch/hermes-agent:latest，args 为 ["gateway", "run"]，端口 8642，挂载持久化卷到 /opt/data，并设置资源限制。
如何部署 Hermes Agent 的 Dashboard 仪表盘？
使用 StatefulSet 部署 Dashboard，参考 YAML 中定义 Service 和 StatefulSet。关键配置包括：镜像 nousresearch/hermes-agent:latest，args 为 ["dashboard"]，端口 9119，环境变量 GATEWAY_HEALTH_URL 指向 Gateway 服务，只读挂载持久化卷到 /opt/data。
如何安全访问 Hermes Agent 的 Dashboard？
可以使用 kubectl port-forward 安全访问仪表盘，命令为：kubectl port-forward -n hermes svc/hermes-dashboard 9119:9119，然后浏览器访问 http://localhost:9119。不建议对外暴露 Dashboard 服务。
如何运行 Hermes Agent 的交互式 CLI 聊天？
在已部署并配置好的数据目录基础上，使用 kubectl exec 进入 Gateway 容器运行交互式 CLI：kubectl exec -it -n hermes gateway-0 -- /opt/hermes/.venv/bin/hermes。
