企业官网建设流程全解析

Hermes WebUI 数据库集成完整指南：3 条链路让 AI 助手直接访问你的数据

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

Hermes WebUI 的数据库集成，解决的是一个很实际的问题：AI 助手只认识自己会话里的内容，却看不到你的任务看板、用量统计和业务文件。Hermes WebUI 是 Hermes Agent 的浏览器端界面（Python 后端 + 原生 JS，无构建步骤），它把 Agent 侧的 SQLite 会话库（state.db）、看板任务库（kanban_db）和本地工作区文件统一接进 Web 界面，让你围绕这些外部数据源搭建查询、分析、自动化的 AI 工作流。

📌 场景切入：AI 助手直接读取你的业务数据

设想一天的实际流程：

• 早上：打开浏览器，Kanban 面板显示各任务卡在哪个状态列（triage → todo → ready → running → blocked → done），阻塞项一目了然
• 下午：把一份 CSV 销售数据拖进工作区，在会话里让 Agent 分析趋势，表格直接渲染在回复里
• 月底：打开 Insights 面板，看每天各模型消耗了多少 token、缓存命中率多少

这三件事背后对应三类数据源，WebUI 都不需要你额外搭数据库中间件：

🚀 快速上手：数据库连接的最快配置方法

第 1 步：部署 WebUI 并建立访问通道

git clone https://gitcode.com/GitHub_Trending/he/hermes-webui cd hermes-webui python3 bootstrap.py

bootstrap.py会完成依赖安装、健康检查等待，然后拉起服务。服务默认只绑定127.0.0.1:8787，不在公网暴露。远程设备通过 SSH 隧道访问：

ssh -N -L 8787:127.0.0.1:8787 <user>@<server>

浏览器打开http://127.0.0.1:8787即可。这是数据访问链路的第一层防护——所有数据库读操作都发生在你本机的回环地址上。

第 2 步：确认运行时数据落在哪里

WebUI 的状态目录默认是~/.hermes/webui/，结构如下：

• sessions/—— 每个会话一个 JSON 文件
• settings.json—— 用户设置（默认模型、密码哈希等）
• workspaces.json/projects.json—— 已注册工作区与会话项目分组

需要迁移或隔离数据时，用环境变量HERMES_WEBUI_STATE_DIR指定新位置，其余环境变量（端口、密码开关等）可参考 .env.example。

第 3 步：打开 Insights 用量同步（可选但推荐）

WebUI 自己的会话默认只写进上一步的 JSON 存储。如果你希望/insights面板和 Agent 侧的用量统计也覆盖 WebUI 产生的对话，需要在设置里开启sync_to_insights（默认关闭）。

这个开关背后的同步桥（见 api/state_sync.py）有几个值得知道的行为：

• 写入的是绝对计数而非增量，避免重复统计
• state.db 被锁、不可用或 schema 不匹配时自动降级，WebUI 继续正常工作
• 按 profile 精确解析目标数据库，解析失败时拒绝写入而不是悄悄写错库

🔍 能力拆解：4 个数据集成点分别能干什么

集成点 1：Kanban 看板——任务库的浏览器端 CRUD

api/kanban_bridge.py 在/api/kanban/*下暴露完整操作面：任务增删改查、批量更新、归档，多看板管理（创建/切换/归档），任务间依赖链接，以及 SSE 实时事件流——Agent 侧任务状态一变，WebUI 立即刷新。

设计上它坚持 Agent 的kanban_db是唯一事实源，WebUI 不维护第二份拷贝，只通过按板分库的 SQLite 连接（用完即关，防文件描述符泄漏）做读写透传。

集成点 2：Insights 用量面板——从 state.db 聚合的统计视图

/api/insights端点（路由分发在 api/routes.py 中）汇总三类信息：每日 token 用量与模型分布、缓存命中率、系统健康状态。其中提示词缓存命中率由后端统一计算（api/usage.py），浏览器端不做除法，保证各处显示口径一致。

注意：Insights 的读数取决于第 3 步的同步开关。未开启时，WebUI 会话的计数不会进入 state.db，面板上对应部分会偏少甚至显示 0。

集成点 3：会话数据层——JSON 存储与 state.db 双向对齐

WebUI 的会话管理有两条互补的读路径：

• WebUI 自有会话：每个会话一个 JSON 文件，api/webui_session_db.py在其上提供 SessionDB 形状的兼容接口，便于后续统一持久化契约
• 外部会话（CLI/TUI/Desktop 产生）：没有 WebUI 侧边文件，打开时从 state.db 合成只读视图；首次向这类会话发消息时走"认领"路径，物化为 WebUI 持有的会话，而不是悄悄重建

标题方向也是同步的：WebUI 自动生成的会话标题会桥写回 state.db，因此hermes sessions list在 CLI 里不会看到空白标题；而你手动命名的标题受来源保护，永远不会被自动标题覆盖。

集成点 4：工作区文件——把本地数据文件喂给会话

右侧工作区面板提供文件树、行内预览和文件操作。对数据工作流有用的点：

• CSV 文件在回复中渲染为表格
• 办公文档有专门的解析路径（api/office_documents.py）
• 上传附件（api/upload.py）可随消息发给 Agent
• 多 profile 场景下，文件操作会校验会话归属，跨 profile 访问直接返回 404，防止数据串档

⚖️ 选型建议：按场景挑接入方式

一个常见误解是以为 WebUI 需要配 PostgreSQL/MySQL 适配器。它不需要：对外部数据源的官方通道是 MCP——在活跃 profile 的config.yaml的mcp_servers段声明服务器即可，配置后 MCP 工具会出现在 WebUI 会话中（见 BUGS.md 中 #628 的排查说明：工具不出现时先确认 profile 是否正确、MCP 进程是否可达）。

🛠️ 进阶实践：调整数据链路的三个旋钮

1. 状态目录迁移：HERMES_WEBUI_STATE_DIR指向新路径，适合把会话数据放进独立磁盘或做环境隔离；HERMES_HOME控制 Agent 侧基准目录
2. 访问面控制：HERMES_WEBUI_HOST改变绑定地址（改绑非回环地址时必须配合HERMES_WEBUI_PASSWORD或 passkey 认证），HERMES_WEBUI_PORT换端口
3. 配置定位：HERMES_CONFIG_PATH显式指定config.yaml位置（默认~/.hermes/config.yaml），多 profile 部署时避免读错工具集与模型配置

整体模块划分（路由壳server.py+api/业务模块 +static/前端）可以在 ARCHITECTURE.md 里对照着看，改动数据层前先读这一份。

❓ 常见问题 FAQ

📌 要点收尾

• WebUI 与 Agent 共享 state.db 和 kanban_db，看板与用量数据不产生第二份拷贝
• 零额外配置即可开始：clone 仓库 +python3 bootstrap.py+ SSH 隧道
• 数据安全默认收敛：本地回环绑定、SSH 隧道、可选密码/passkey 认证
• 外部数据源走两条正路：config.yaml里的 MCP 服务器（给 Agent 用）和/api/*路由（给程序用）
• 想让 WebUI 对话进入 Insights 统计，记得打开sync_to_insights

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