Hermes Dashboard 配置手册

1. Dashboard 功能 YML 配置

环境变量

变量	默认值	说明
`HERMES_DASHBOARD`	（未设置）	设为 `1` 启用 s6 监督下的 dashboard 服务
`HERMES_DASHBOARD_HOST`	`0.0.0.0`	监听地址。bridge 网络下必须用 `0.0.0.0`
`HERMES_DASHBOARD_PORT`	`9119`	监听端口
`HERMES_DASHBOARD_INSECURE`	（未设置）	`1` 跳过 OAuth 门禁（0.0.0.0 绑定时需要）
`HERMES_DASHBOARD_TUI`	`0`	`1` 启用浏览器内嵌 CLI 终端（Chat 标签页）

Docker Compose 配置

services:
  hermes-agent:
    image: nousresearch/hermes-agent:v2026.5.29.2
    command: gateway run
    environment:
      - HERMES_DASHBOARD=1
      - HERMES_DASHBOARD_TUI=1
      - HERMES_DASHBOARD_INSECURE=1
      - HERMES_DASHBOARD_HOST=0.0.0.0
    networks:
      - ghost_net

CLI 链路架构

┌────────────────────┐                        ┌──────────────────────┐                    ┌───────────────┐
│     Browser        │     WebSocket          │   Dashboard Server   │      PTY          │  Hermes TUI   │
│   Dashboard Tab    │ ─────────────────────> │    /api/pty          │ ────────────────> │   子进程      │
│   (xterm.js)       │ <───────────────────── │    port 9119         │ <──────────────── │  CLI 完整     │
│   WebGL 渲染       │   ANSI 输出流            │    s6 监督           │   ANSI 输出       │  slash命令    │
└────────────────────┘                        └──────────────────────┘                   └───────────────┘

说明:
  Chat 标签页 = 浏览器内完整 Hermes CLI，支持斜杠命令 / 模型切换 / tool-call 卡片 / markdown 流式输出
  HERMES_DASHBOARD_TUI=1 额外 fork 一个 hermes --tui PTY 子进程（约 +200MB 内存）
  Docker 镜像已预装 Node.js 22 + ptyprocess，开箱可用

2. OAuth 2.0 全链路配置

架构图

┌──────────┐   HTTPS :443   ┌──────────┐   auth_request    ┌──────────────┐   HTTP    ┌────────────────┐
│ Browser   │ ─────────────> │  Nginx   │ ────────────────> │ oauth2-proxy │ ───────> │ Hermes Agent   │
│           │               │          │ <──────────────── │              │          │ Dashboard:9119 │
│           │               │          │  401 → /sign_in   │  + Google     │          │                │
│           │               │          │                   │   OAuth App   │          │                │
└──────────┘               └──────────┘                   └──────────────┘          └────────────────┘

OAuth 全链路流程:
  ① 用户访问 dashboard → nginx 触发 auth_request
  ② oauth2-proxy 检测无会话 → 302 重定向到 Google 登录
  ③ 用户在 Google 输入账号密码 → Google 回调 oauth2-proxy
  ④ oauth2-proxy 校验邮箱白名单 → 通过则设置会话 cookie
  ⑤ 后续请求由 oauth2-proxy 认证 → nginx auth_request 通过
  ⑥ 请求透传到 Hermes Dashboard:9119

变量来源对照

参数	值来源	说明
`--client-id`	Google Cloud 创建 OAuth App 时提供	格式 `xxx.apps.googleusercontent.com`
`--client-secret`	Google Cloud 创建 OAuth App 时提供	弹窗显示一次，立即保存
`--cookie-secret`	自己生成	`python3 -c "import secrets,base64; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode())"`
`--redirect-url`	你的域名	格式 `https://你的域名/oauth2/callback`，必须与 Google Cloud 授权重定向 URI 一致
`--upstream`	你的网络	`http://hermes-agent:9119`（ghost_net 内部）
`--authenticated-emails-file`	你自己管理	指向 emails.txt，加第二个人只改这个文件即可

前提：Google Cloud 注册 OAuth App

访问 https://console.cloud.google.com/apis/credentials
创建 OAuth 2.0 Client ID，应用类型 Web application
名称随意（如 "Hermes Dashboard"）
授权重定向 URI：https://你的域名/oauth2/callback
点创建，复制 Client ID + Client Secret

Nginx 配置（宿主机）

nginx 是真正的公网入口，oauth2-proxy 仅作为内部认证服务。必须配置 auth_request 才能串联域名 → oauth2-proxy → dashboard。

server {
    listen 443 ssl;
    server_name dashboard.你的域名;

    ssl_certificate /etc/letsencrypt/live/你的域名/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/你的域名/privkey.pem;

    # 认证校验：请求先发给 oauth2-proxy
    auth_request /oauth2/auth;
    error_page 401 = /oauth2/sign_in;

    # dashboard 转发
    location / {
        proxy_pass http://hermes-agent:9119;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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_set_header X-Forwarded-Proto $scheme;
    }

    # oauth2-proxy 回调端点
    location /oauth2/ {
        proxy_pass http://127.0.0.1:4180;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Docker Compose 配置

services:
  oauth2-proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy:latest
    container_name: oauth2-proxy
    restart: unless-stopped
    networks:
      - ghost_net
    ports:
      - 127.0.0.1:4180:4180    # 宿主机 nginx 通过 127.0.0.1:4180 访问
    volumes:
      - ./emails.txt:/etc/oauth2-proxy/emails.txt:ro
    command:
      - --provider=google
      - --client-id=你的_CLIENT_ID
      - --client-secret=你的_CLIENT_SECRET
      - --cookie-secret=生成的32字节base64
      - --redirect-url=https://你的域名/oauth2/callback
      - --upstream=http://hermes-agent:9119
      - --email-domain=*
      - --authenticated-emails-file=/etc/oauth2-proxy/emails.txt
      - --pass-authorization-header=true
      - --set-xauthrequest=true

邮箱白名单文件 emails.txt

you@gmail.com
zhangsan@gmail.com

加第二个用户：只改 emails.txt 加一行邮箱即可，不需要去 Google Cloud 后台修改任何东西。第二个人用自己的日常 Google 账号登录，不需要是开发者。

重要说明

dashboard 无用户概念：不同用户登录后看到的是同一个 dashboard、同一份会话列表、同一个 Chat 终端。认证只解决"谁能进"，不解决"谁做了什么"
oauth2-proxy 与 Hermes 内置 OAuth 门禁不同：oauth2-proxy 是独立容器，在 nginx 层做认证拦截；HERMES_DASHBOARD_INSECURE=1 是跳过 Hermes 自身的 Nous Portal 门禁。两者独立，你的场景同时使用

3. API Server 功能 YML 配置

架构图

┌────────────────────┐   POST /v1/chat/completions   ┌────────────────────┐
│ 第三方前端           │ ────────────────────────────> │ Hermes Agent       │
│ Open Web UI        │   Authorization: Bearer xxx    │ API Server         │
│ LobeChat           │ <──────────────────────────── │ port 8642          │
│ LibreChat          │   流式响应 + tool call 进度      │ 完整工具集          │
└────────────────────┘                               │ (终端/文件/搜索)     │
                                                     └────────────────────┘

环境变量

变量	说明
`API_SERVER_ENABLED=true`	启用 OpenAI 兼容 API
`API_SERVER_KEY=your-api-key`	Bearer token 认证（必须）
`API_SERVER_HOST`	默认 127.0.0.1，对外暴露需设为 0.0.0.0
`API_SERVER_PORT`	默认 8642
`API_SERVER_CORS_ORIGINS`	浏览器直连时必设，限制允许的来源

Docker Compose 配置

environment:
  - API_SERVER_ENABLED=true
  - API_SERVER_KEY=your-api-key
  # - API_SERVER_HOST=0.0.0.0   # 如需外部访问
  # - API_SERVER_CORS_ORIGINS=http://localhost:3000

端口 8642，与 Dashboard 端口 9119 独立，互不依赖
API Server 不启动不影响 Dashboard 任何功能
API Server 暴露完整工具集（含终端），必须设置 API_SERVER_KEY