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-webuiHermes 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 都不需要你额外搭数据库中间件数据源存储形态WebUI 的接入方式Agent 会话库 state.dbSQLite读取投影 可选写回同步看板任务库 kanban_dbSQLite按看板分库/api/kanban/*完整 CRUD工作区文件本地文件CSV/JSON/办公文档文件浏览器 上传 会话引用 快速上手数据库连接的最快配置方法第 1 步部署 WebUI 并建立访问通道git clone https://gitcode.com/GitHub_Trending/he/hermes-webui cd hermes-webui python3 bootstrap.pybootstrap.py会完成依赖安装、健康检查等待然后拉起服务。服务默认只绑定127.0.0.1:8787不在公网暴露。远程设备通过 SSH 隧道访问ssh -N -L 8787:127.0.0.1:8787 userserver浏览器打开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 个数据集成点分别能干什么集成点 1Kanban 看板——任务库的浏览器端 CRUDapi/kanban_bridge.py 在/api/kanban/*下暴露完整操作面任务增删改查、批量更新、归档多看板管理创建/切换/归档任务间依赖链接以及 SSE 实时事件流——Agent 侧任务状态一变WebUI 立即刷新。设计上它坚持 Agent 的kanban_db是唯一事实源WebUI 不维护第二份拷贝只通过按板分库的 SQLite 连接用完即关防文件描述符泄漏做读写透传。集成点 2Insights 用量面板——从 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防止数据串档⚖️ 选型建议按场景挑接入方式你的需求推荐方式配置入口说明监控任务进度Kanban 面板内置零配置数据源为 Agent 看板库实时 SSE 刷新看用量与成本Insights 面板开启sync_to_insights覆盖 WebUI 会话需要显式开启分析 CSV/文档工作区上传 会话问答右侧工作区面板无 SQL直接自然语言提问连接外部系统内部 API、其他库MCP 服务器当前 profile 的config.yaml中mcp_servers段详见下节程序化读写 WebUI 数据REST 路由/api/*分发逻辑见 api/routes.py适合二次开发与脚本一个常见误解是以为 WebUI 需要配 PostgreSQL/MySQL 适配器。它不需要对外部数据源的官方通道是 MCP——在活跃 profile 的config.yaml的mcp_servers段声明服务器即可配置后 MCP 工具会出现在 WebUI 会话中见 BUGS.md 中 #628 的排查说明工具不出现时先确认 profile 是否正确、MCP 进程是否可达。️ 进阶实践调整数据链路的三个旋钮状态目录迁移HERMES_WEBUI_STATE_DIR指向新路径适合把会话数据放进独立磁盘或做环境隔离HERMES_HOME控制 Agent 侧基准目录访问面控制HERMES_WEBUI_HOST改变绑定地址改绑非回环地址时必须配合HERMES_WEBUI_PASSWORD或 passkey 认证HERMES_WEBUI_PORT换端口配置定位HERMES_CONFIG_PATH显式指定config.yaml位置默认~/.hermes/config.yaml多 profile 部署时避免读错工具集与模型配置整体模块划分路由壳server.pyapi/业务模块 static/前端可以在 ARCHITECTURE.md 里对照着看改动数据层前先读这一份。❓ 常见问题 FAQ现象可能原因处理办法浏览器打不开页面服务只绑定 127.0.0.1跨机器访问被拒建 SSH 隧道确需改绑地址时同步开启密码认证Insights 缓存命中率显示 0% 或缺数sync_to_insights未开启计数器没进 state.db开启设置后各用量同步点会把缓存读/写 token 与 API 调用数写入 state.dbCLI 会话列表里 WebUI 会话没标题旧版本只把标题写进了 WebUI 侧边文件升级到新版本标题桥写自动完成手动命名不受影响Kanban 刷新后状态不对前端缓存了过期快照做硬刷新桥层对 board 参数做了归一化与存在性校验参数错误会返回清晰的 400MCP 工具在会话里不可用MCP 服务器没配在活跃 profile 的config.yaml核对mcp_servers段与 profile 匹配确认 MCP 进程从 WebUI 容器内可达长会话打开慢历史消息全量读取新版本对带时间戳下界的尾部窗口做分页读取升级即可 要点收尾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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
