Hermes Agent + Open WebUI Docker 部署指南

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装 Docker
curl -fsSL https://get.docker.com | sudo sh

# 将当前用户加入 docker 组（免 sudo）
sudo usermod -aG docker $USER

# 重新登录后生效，验证
docker --version
docker compose version

cat > /root/.hermes/.env << 'EOF'
# =============================================================================
# LLM 提供商配置 - 小米 MiMo
# =============================================================================
XIAOMI_API_KEY=你的小米API密钥
XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1

# =============================================================================
# 微信网关配置（可选，如需接入微信）
# =============================================================================
WEIXIN_ACCOUNT_ID=你的微信账号ID
WEIXIN_TOKEN=你的微信Token
WEIXIN_BASE_URL=https://ilinkai.weixin.qq.com
WEIXIN_CDN_BASE_URL=https://novac2c.cdn.weixin.qq.com/c2c
WEIXIN_DM_POLICY=pairing
WEIXIN_ALLOW_ALL_USERS=false
WEIXIN_ALLOWED_USERS=你的微信用户ID
WEIXIN_GROUP_POLICY=disabled
WEIXIN_GROUP_ALLOWED_USERS=
WEIXIN_HOME_CHANNEL=你的微信用户ID

# =============================================================================
# API SERVER（Open WebUI 连接所需）
# =============================================================================
# 启用内置 API 服务器
API_SERVER_ENABLED=true
# API 认证密钥，Open WebUI 连接时需要提供此密钥
API_SERVER_KEY=<your-api-key>
# 监听地址：必须为 0.0.0.0 才能让 Docker 容器网络访问
# 默认为 127.0.0.1（仅容器内部可访问），这是最常见的坑
API_SERVER_HOST=0.0.0.0
EOF

cat > /root/.hermes/config.yaml << 'EOF'
# 模型配置
model:
  # 默认使用的模型（对应小米 API 中的模型 ID）
  default: mimo-v2.5
  # 推理提供商（auto 会根据环境变量自动检测）
  provider: xiaomi
  # 小米 API 端点
  base_url: https://token-plan-cn.xiaomimimo.com/v1

# 工具集配置
toolsets:
  - hermes-cli

# Agent 参数
agent:
  max_turns: 90
  gateway_timeout: 1800
  restart_drain_timeout: 180
  api_max_retries: 3
EOF

# 临时启动 Hermes 测试
docker run --rm -it \
  -v /root/.hermes:/opt/data \
  -e API_SERVER_ENABLED=true \
  -e API_SERVER_KEY=<your-api-key> \
  nousresearch/hermes-agent

# 如果看到以下内容说明配置成功：
# Hermes Gateway Starting...
# ...
# Welcome to Hermes Agent!

cat > /etc/docker/hermes/docker-compose.yml << 'EOF'
# ============================================================
#  Hermes Agent + Open WebUI  Docker Compose 配置
#  路径: /etc/docker/hermes/docker-compose.yml
#  启动: cd /etc/docker/hermes && docker compose up -d
# ============================================================

services:

  # ──────────────────────────────────────────────────────────
  #  Hermes Agent 网关
  #  - 提供 AI Agent 能力（工具调用、文件操作、代码执行等）
  #  - 启动内置 API 服务器，供 Open WebUI 通过 HTTP 调用
  # ──────────────────────────────────────────────────────────
  hermes-gateway:
    image: nousresearch/hermes-agent
    container_name: hermes-gateway
    restart: always

    ports:
      # 宿主机 8642 端口映射到容器 8642 端口
      # 主要用于外部调试（如 curl 测试 API）
      # Open WebUI 不需要通过此端口访问（使用 Docker 内部网络）
      - "8642:8642"

    volumes:
      # 将宿主机的 Hermes 数据目录挂载到容器内 /opt/data
      # 所有配置（.env、config.yaml）、会话记录、插件数据都保存在这里
      # 容器删除后数据不丢失
      - /root/.hermes:/opt/data

    # ── 关键：解决 TTY 问题 ──
    # Hermes CLI 检测到非 TTY 环境会直接退出（"Input is not a terminal"）
    # 需要绕过 tini 初始化进程，直接运行 entrypoint
    entrypoint: ["/opt/hermes/docker/entrypoint.sh"]
    command: ["gateway", "run"]    # 启动网关模式（消息平台 + API 服务器）
    tty: true                      # 分配伪终端
    stdin_open: true               # 保持标准输入打开

    environment:
      - API_SERVER_ENABLED=true
      - API_SERVER_KEY=<your-api-key>

    logging:
      driver: json-file
      options:
        max-size: "50m"    # 单个日志文件最大 50MB
        max-file: "3"      # 最多保留 3 个日志文件（自动轮转）

    networks:
      - hermes-net

  # ──────────────────────────────────────────────────────────
  #  Open WebUI 聊天界面
  #  - 提供 Web 界面供用户与 AI 对话
  #  - 通过 OpenAI 兼容 API 连接到 Hermes Agent
  # ──────────────────────────────────────────────────────────
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    restart: always

    ports:
      # 浏览器访问地址: http://服务器IP:8443
      - "8443:8080"

    volumes:
      # Open WebUI 数据持久化（用户账户、聊天记录、设置）
      # 使用相对路径 ./open-webui-data，即当前目录下的子目录
      # 宿主机位置: /etc/docker/hermes/open-webui-data
      - ./open-webui-data:/app/backend/data

    environment:
      # Hermes API 地址
      # hermes-gateway 是 Docker 容器名，通过内部 DNS 解析
      # 必须以 /v1 结尾，否则模型列表无法加载
      - OPENAI_API_BASE_URL=http://hermes-gateway:8642/v1
      # 认证密钥，必须与 Hermes 的 API_SERVER_KEY 完全一致
      - OPENAI_API_KEY=<your-api-key>
      # 国内 HuggingFace 镜像
      # Open WebUI 启动时需要下载嵌入模型（all-MiniLM-L6-v2）
      # 国内无法直接访问 huggingface.co，必须设置镜像
      - HF_ENDPOINT=https://hf-mirror.com

    depends_on:
      - hermes-gateway

    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "3"

    networks:
      - hermes-net

# ──────────────────────────────────────────────────────────
#  自定义网络
#  两个容器通过此网络互相通信
#  容器名即 DNS，如 http://hermes-gateway:8642
# ──────────────────────────────────────────────────────────
networks:
  hermes-net:
    driver: bridge
EOF

# 1. 检查 Hermes API 是否正常
curl http://localhost:8642/health
# 预期输出: {"status": "ok", "platform": "hermes-agent"}

# 2. 从 Open WebUI 容器内测试连接
docker exec open-webui curl -s http://hermes-gateway:8642/health
# 预期输出: {"status": "ok", "platform": "hermes-agent"}

# 3. 查看可用模型
curl -s http://localhost:8642/v1/models \
  -H "Authorization: Bearer <your-api-key>" | python3 -m json.tool

# 编辑配置文件
nano /root/.hermes/config.yaml

# 修改 default 字段
# 例如切换到 mimo-v2.5-pro
# model:
#   default: mimo-v2.5-pro

# 重启 Hermes 使配置生效
cd /etc/docker/hermes
docker compose restart hermes-gateway

cd /etc/docker/hermes

# 查看容器状态
docker compose ps

# 查看实时日志
docker compose logs -f

# 查看某个服务的日志
docker compose logs -f hermes-gateway
docker compose logs -f open-webui

# 重启服务
docker compose restart

# 停止服务
docker compose down

# 启动服务
docker compose up -d

# 更新镜像并重启
docker compose pull
docker compose up -d

# 进入容器调试
docker exec -it hermes-gateway bash
docker exec -it open-webui bash