3分钟部署Hermes WebUI：Agent+WebUI+Dashboard三容器生产级解决方案

牧丁通

469人浏览 · 2026-07-01 20:20:48

牧丁通 · 2026-07-01 20:20:48 发布

3分钟部署Hermes WebUI：Agent+WebUI+Dashboard三容器生产级解决方案

【免费下载链接】hermes-webui Hermes WebUI: The best way to use Hermes Agent from the web or from your phone! 项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webui

面对AI助手本地化部署的复杂性，技术团队常陷入组件耦合、升级困难、监控缺失的困境。Hermes WebUI通过三容器架构提供了一站式解决方案，将智能代理、Web界面和监控面板解耦部署，实现企业级AI助手的高可用性。本指南将带您快速完成生产级部署，并提供故障排查的实用清单。

为什么传统部署方案难以满足生产需求？

传统单容器部署模式存在三大核心痛点：组件升级相互影响、资源分配难以优化、系统状态监控缺失。当您需要升级Agent版本时，WebUI服务必须随之重启；内存密集型任务可能影响用户界面响应；系统异常时缺乏实时监控工具。这些问题在团队协作和生产环境中尤为突出。

三容器架构的核心优势对比

部署方案	组件耦合度	独立升级	资源隔离	监控能力	维护复杂度
单容器部署	高	不可独立升级	无隔离	基础	低
双容器部署	中	部分独立	有限隔离	基础	中
三容器部署	低	完全独立	完全隔离	完整监控	中

三容器架构设计方案详解

Hermes三容器架构采用微服务设计理念，通过Docker网络实现服务间通信，共享数据卷确保状态一致性。架构包含三个核心服务：

Hermes Agent - 智能代理核心，端口8642，提供API接口和工具支持
Hermes WebUI - 用户交互界面，端口8787，实现Web端完整功能
Hermes Dashboard - 系统监控面板，端口9119，提供实时状态监控

图1：Hermes WebUI三面板布局展示，左侧会话导航，中间聊天区域，右侧工作区文件管理

关键配置文件解析

项目提供了完整的docker-compose.three-container.yml配置文件，以下是核心配置要点：

# 服务定义示例（简化版）
services:
  hermes-agent:
    image: nousresearch/hermes-agent:latest
    ports: ["127.0.0.1:8642:8642"]
    volumes:
      - hermes-home:/home/hermes/.hermes  # 共享配置和数据
      - hermes-agent-src:/opt/hermes       # Agent源代码

  hermes-dashboard:
    image: nousresearch/hermes-agent:latest
    ports: ["127.0.0.1:9119:9119"]
    environment:
      - GATEWAY_HEALTH_URL=http://hermes-agent:8642

  hermes-webui:
    image: ghcr.io/nesquena/hermes-webui:latest
    ports: ["127.0.0.1:8787:8787"]
    volumes:
      - hermes-home:/home/hermeswebui/.hermes
      - ${HERMES_WORKSPACE:-${HOME}/workspace}:/workspace

5步完成生产环境部署

步骤1：环境准备与项目克隆

确保系统满足Docker Engine 20.10.0+和Docker Compose 2.0.0+要求，然后获取项目代码：

# 克隆项目仓库
git clone https://gitcode.com/GitHub_Trending/he/hermes-webui
cd hermes-webui

# 验证Docker环境
docker --version
docker compose version

步骤2：配置用户权限与环境变量

创建环境配置文件，确保跨容器文件权限一致：

# 设置用户ID和组ID
echo "UID=$(id -u)" > .env
echo "GID=$(id -g)" >> .env

# 可选：设置远程访问密码
echo "HERMES_WEBUI_PASSWORD=your-secure-password" >> .env

# 可选：自定义工作目录
echo "HERMES_WORKSPACE=/path/to/your/workspace" >> .env

步骤3：一键启动三容器服务

使用Docker Compose启动所有服务：

# 启动所有服务（后台运行）
docker compose -f docker-compose.three-container.yml up -d

# 查看服务状态
docker compose -f docker-compose.three-container.yml ps

步骤4：验证服务健康状态

服务启动后，通过以下方式验证部署成功：

# 检查各容器日志
docker logs hermes-agent --tail 20
docker logs hermes-webui --tail 20
docker logs hermes-dashboard --tail 20

# 测试端口连通性
curl -f http://localhost:8642/health  # Agent健康检查
curl -f http://localhost:8787         # WebUI首页
curl -f http://localhost:9119         # Dashboard面板

步骤5：访问与初始配置

通过浏览器访问以下地址：

WebUI界面：http://localhost:8787 - 主交互界面
Dashboard监控：http://localhost:9119 - 系统状态监控

图2：工作区文件管理界面，支持文件预览和直接操作

生产环境优化配置指南

资源分配策略

根据实际使用场景调整资源限制：

# 在docker-compose.three-container.yml中调整
services:
  hermes-agent:
    deploy:
      resources:
        limits:
          memory: 8G      # Agent内存限制（根据模型大小调整）
          cpus: "4.0"     # CPU核心数限制
  
  hermes-webui:
    deploy:
      resources:
        limits:
          memory: 2G      # WebUI内存限制
          cpus: "1.0"
  
  hermes-dashboard:
    deploy:
      resources:
        limits:
          memory: 512M    # Dashboard内存限制
          cpus: "0.5"

数据持久化配置

确保重要数据安全存储：

# 创建数据备份脚本
cat > backup-hermes.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/backup/hermes-$(date +%Y%m%d-%H%M%S)"
mkdir -p $BACKUP_DIR
docker run --rm -v hermes-webui_hermes-home:/source -v $BACKUP_DIR:/backup alpine \
  tar -czf /backup/hermes-home-backup.tar.gz -C /source .
echo "Backup created: $BACKUP_DIR/hermes-home-backup.tar.gz"
EOF
chmod +x backup-hermes.sh

系统监控与故障排查实战

Dashboard监控面板使用

访问Dashboard面板（http://localhost:9119）获取实时系统状态：

图3：系统健康监控界面，实时显示CPU、内存、磁盘使用率和会话统计

监控面板提供以下关键指标：

系统健康：CPU、内存、磁盘使用率
会话统计：活跃会话数、消息数量、令牌消耗
成本估算：API调用成本分析
LLM知识库：知识库状态监控

日志分析与问题诊断

通过日志面板快速定位问题：

# 实时查看Agent日志
docker logs -f hermes-agent

# 查看WebUI错误日志
docker logs hermes-webui --since 10m | grep -i error

# 导出日志文件分析
docker logs hermes-dashboard > dashboard-$(date +%Y%m%d).log

图4：日志管理界面，支持文件筛选、自动刷新和行数控制

常见故障排查清单

问题现象	可能原因	解决方案
权限拒绝错误	UID/GID不匹配	检查.env文件中的UID/GID设置
端口冲突	端口被占用	修改docker-compose中的端口映射
服务启动失败	镜像拉取失败	检查网络连接，手动拉取镜像
WebUI无法连接Agent	网络配置问题	验证Docker网络和GATEWAY_HEALTH_URL
磁盘空间不足	日志文件积累	清理旧日志，调整日志轮转配置
内存溢出	资源限制过低	增加内存限制，优化模型加载策略

运维管理与升级策略

日常维护操作

# 查看服务状态
docker compose -f docker-compose.three-container.yml ps

# 重启单个服务
docker compose -f docker-compose.three-container.yml restart hermes-webui

# 查看资源使用情况
docker stats hermes-agent hermes-webui hermes-dashboard

安全升级流程

遵循以下步骤安全升级到新版本：

# 1. 停止所有服务
docker compose -f docker-compose.three-container.yml down

# 2. 备份重要数据（可选但推荐）
./backup-hermes.sh

# 3. 删除agent-src卷（重新初始化）
docker volume rm hermes-webui_hermes-agent-src

# 4. 拉取最新镜像
docker compose -f docker-compose.three-container.yml pull

# 5. 重新启动服务
docker compose -f docker-compose.three-container.yml up -d

# 6. 验证升级结果
docker compose -f docker-compose.three-container.yml logs --tail=50

性能优化建议

网络优化：为生产环境配置独立的Docker网络
存储优化：使用SSD存储卷提高IO性能
缓存策略：配置合理的会话和模型缓存
监控告警：集成Prometheus和Grafana实现监控告警

生产环境最佳实践

安全配置要点

# 安全增强配置示例
services:
  hermes-webui:
    environment:
      # 强制密码认证（生产环境必需）
      - HERMES_WEBUI_PASSWORD=${WEBUI_PASSWORD}
      # 限制访问IP（可选）
      # - HERMES_WEBUI_ALLOWED_IPS=192.168.1.0/24
    ports:
      # 仅监听本地回环地址
      - "127.0.0.1:8787:8787"

高可用部署方案

对于关键业务场景，建议采用以下高可用架构：

负载均衡：使用Nginx反向代理多个WebUI实例
数据库分离：将会话数据存储到外部数据库
容器编排：使用Kubernetes或Docker Swarm进行容器编排
自动伸缩：基于负载自动扩展Agent实例

监控告警配置

集成外部监控系统实现全方位监控：

# Prometheus监控配置示例
# 在docker-compose.three-container.yml中添加
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - "9090:9090"