# hermes-webui

**Repository Path**: lgsg/hermes-webui

## Basic Information

- **Project Name**: hermes-webui
- **Description**: hermes agent的webui
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-04-12
- **Last Updated**: 2026-04-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Hermes Web UI

Hermes Web UI 是一个基于 Web 的界面，用于管理和使用 Hermes Agent AI 助手。

## 项目结构

```
hermes-webui/
├── backend/          # FastAPI 后端
│   ├── app/          # 应用代码
│   ├── venv/         # Python 虚拟环境
│   └── requirements.txt
├── frontend/         # React + Vite 前端
│   ├── src/          # 源代码
│   └── package.json
└── readme.md         # 本文档
```

## 环境要求

- Python 3.10+
- Node.js 18+
- pnpm
- Hermes Agent (已安装并配置)

## 快速开始

### 1. 配置 Hermes Agent

在启动 Web UI 之前，需要先配置并启动 Hermes Agent 的 API Server：

```bash
# 编辑 Hermes Agent 的 .env 文件
echo "API_SERVER_ENABLED=true" >> ~/.hermes/.env
echo "API_SERVER_PORT=8642" >> ~/.hermes/.env

# 启动 Hermes Agent Gateway
hermes gateway run
```
# 启动 Hermes Agent Gateway server
hermes gateway install
hermes gateway start              # Start the service
  hermes gateway status             # Check status
  journalctl --user -u hermes-gateway -f  # View logs

### 2. 启动后端

```bash
cd backend

# 创建虚拟环境（如果还没有）
python -m venv venv

# 激活虚拟环境
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows

# 安装依赖
pip install -r requirements.txt

# 启动开发服务器
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

后端服务将在 `http://localhost:8000` 运行。

### 3. 启动前端

```bash
cd frontend

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev
```

前端服务将在 `http://localhost:5173` 运行。

### 4. 构建生产版本

```bash
cd frontend

# 构建生产版本
pnpm build

# 构建后的文件位于 dist/ 目录
```

## 配置说明

### 配置文件位置

所有配置存储在 JSON 文件中：

```
~/.hermes/webui_config.json
```

### 配置项

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `ai_provider` | AI 提供商 (openrouter, ollama, openai 等) | openrouter |
| `ai_api_key` | API 密钥 | "" |
| `ai_base_url` | 自定义 API 基础 URL | "" |
| `ai_default_model` | 默认模型 | "" |
| `ai_system_prompt` | 系统提示词 | "" |
| `frontend_host` | 前端主机地址 | 0.0.0.0 |
| `frontend_port` | 前端端口 | 5173 |
| `backend_host` | 后端主机地址 | 0.0.0.0 |
| `backend_port` | 后端端口 | 8000 |
| `hermes_agent_host` | Hermes Agent 主机地址 | 0.0.0.0 |
| `hermes_agent_port` | Hermes Agent 端口 | 8642 |

### 通过 Web UI 配置

1. 登录 Web UI
2. 进入 "AI Configuration" 页面
3. 点击 "Edit" 按钮编辑配置
4. 修改完成后点击 "Save" 保存

## 部署到生产环境

### 使用 Docker（推荐）

```bash
# 构建镜像
docker build -t hermes-webui .

# 运行容器
docker run -d -p 8000:8000 -p 5173:5173 hermes-webui
```

### 手动部署

1. 构建前端：
```bash
cd frontend
pnpm build
```

2. 配置 Nginx 反向代理：
```nginx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        root /path/to/hermes-webui/frontend/dist;
        try_files $uri $uri/ /index.html;
    }

    location /api {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

3. 使用 systemd 管理后端服务：
```bash
sudo systemctl enable hermes-webui
sudo systemctl start hermes-webui
```

## 开发指南

### 后端开发

```bash
cd backend
source venv/bin/activate

# 运行测试
pytest

# 代码格式化
black app/
isort app/

# 类型检查
mypy app/
```

### 前端开发

```bash
cd frontend

# 代码检查
pnpm lint

# 类型检查
pnpm type-check

# 代码格式化
pnpm format
```

## 常见问题

### 1. 无法连接到 Hermes Agent

检查：
- Hermes Agent 是否已启动：`hermes gateway run`
- API Server 是否已启用：`API_SERVER_ENABLED=true`
- 端口是否正确：`API_SERVER_PORT=8642`
- Web UI 中的 Hermes Agent URL 配置是否正确

### 2. 配置文件不生效

- 配置文件位置：`~/.hermes/webui_config.json`
- 修改配置后需要刷新页面
- 检查文件权限是否正确

### 3. 前端构建失败

```bash
# 清除缓存
rm -rf node_modules dist
pnpm install
pnpm build
```

## 技术栈

- **后端**：FastAPI + SQLAlchemy + Pydantic
- **前端**：React + TypeScript + Tailwind CSS + Vite
- **数据库**：SQLite（默认）/ PostgreSQL（生产）
- **AI 集成**：Hermes Agent + OpenAI 兼容 API

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 相关链接

- [Hermes Agent 文档](https://hermes-agent.nousresearch.com/)
- [FastAPI 文档](https://fastapi.tiangolo.com/)
- [React 文档](https://react.dev/)