本文基于官方 Docker 文档，将 Hermes Agent 迁移到 Kubernetes / K3s 环境，使用 StatefulSet 管理持久化工作负载。
1. 前置准备
- K3s 或 K8s 集群已就绪（本文以 K3s 为例）
- 节点上已有 containerd（K3s 默认内置）
- 推荐安装
nerdctl作为容器管理工具（参考：在 K3s 节点上安装并使用 nerdctl） - 镜像：
nousresearch/hermes-agent:latest
2. 初始化配置（持久化数据目录）
在首次运行前，需要先执行一次 Setup Wizard，将 API Keys 等配置写入宿主机目录，再挂载进容器使用。
这里建议使用
nerdctl运行，其他的方法需自行探索。
# 在目标节点上创建数据目录
mkdir -p /var/lib/hermes-data
# 使用 nerdctl 运行一次性 setup 容器（交互模式）
sudo nerdctl run -it --rm \
-v /var/lib/hermes-data:/opt/data \
nousresearch/hermes-agent:latest setup
配置完成后的数据目录结构
/var/lib/hermes-data/
├── .env # API Keys 与密钥
├── config.yaml # 主配置文件
├── SOUL.md # Agent 人格 / 身份设定
├── sessions/ # 会话历史
├── memories/ # 持久记忆
├── skills/ # 已安装的技能
├── cron/ # 定时任务定义
├── hooks/ # 事件钩子
├── logs/ # 运行日志
└── skins/ # 自定义 CLI 皮肤
3. 部署 Gateway 后台服务（StatefulSet）
这里直接给出参考 yaml，按需调整：
---
apiVersion: v1
kind: Service
metadata:
name: gateway
namespace: hermes
spec:
selector:
app: gateway
ports:
- name: api
port: 8642
targetPort: 8642
type: ClusterIP
---
kind: PersistentVolumeClaim
apiVersion: v1
metadata:
name: data
namespace: hermes
spec:
accessModes:
- ReadWriteMany
resources:
requests:
storage: 50Gi
storageClassName: nfs-hhus3
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: gateway
namespace: hermes
spec:
serviceName: gateway
replicas: 1
selector:
matchLabels:
app: gateway
template:
metadata:
labels:
app: gateway
spec:
nodeSelector:
hosthatch/zone: lax
containers:
- name: gateway
image: nousresearch/hermes-agent:latest
args: ["gateway", "run"]
ports:
- containerPort: 8642
env:
- name: TZ
value: "Asia/Shanghai"
volumeMounts:
- name: hermes-data
mountPath: /opt/data
resources:
requests:
memory: "1Gi"
cpu: "500m"
limits:
memory: "4Gi"
cpu: "2"
volumes:
- name: hermes-data
persistentVolumeClaim:
claimName: data
4. 部署 Dashboard 仪表盘（StatefulSet）
直接给出参考 yaml，按需调整：
apiVersion: v1
kind: Service
metadata:
name: dashboard
namespace: hermes
spec:
selector:
app: dashboard
ports:
- name: web
port: 9119
targetPort: 9119
type: ClusterIP # 按需改为 NodePort / LoadBalancer
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: dashboard
namespace: hermes
spec:
serviceName: dashboard
replicas: 1
selector:
matchLabels:
app: dashboard
template:
metadata:
labels:
app: dashboard
spec:
nodeSelector:
hosthatch/zone: lax
containers:
- name: dashboard
image: nousresearch/hermes-agent:latest
args: ["dashboard"]
#args: ["dashboard", "--host", "0.0.0.0", "--insecure"]
ports:
- containerPort: 9119
env:
# 指向 Gateway Service 的 ClusterIP DNS 名称
- name: GATEWAY_HEALTH_URL
value: "http://gateway.hermes.svc.cluster.local:8642"
- name: GATEWAY_HEALTH_TIMEOUT
value: "3"
volumeMounts:
- name: hermes-data
mountPath: /opt/data
readOnly: true # Dashboard 只读数据目录
resources:
requests:
memory: "256Mi"
cpu: "100m"
limits:
memory: "512Mi"
cpu: "500m"
volumes:
- name: hermes-data
persistentVolumeClaim:
claimName: data
可以使用 port-forward 安全的访问仪表盘，不建议对外暴露：
kubectl port-forward -n hermes svc/hermes-dashboard 9119:9119
# 浏览器访问 http://localhost:9119
5. 运行交互式 CLI 聊天
在已部署并配置好的数据目录基础上，可随时进行交互式聊天，使用 kubectl exec 进入 Gateway 容器
kubectl exec -it -n hermes gateway-0 -- /opt/hermes/.venv/bin/hermes