Hermes WebUI 数据库连接：3 类数据源接通的完整实战
【免费下载链接】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 数据库连接这件事分两种情况：一种是它自带的 SQLite 存储（会话状态、Kanban 任务、用量洞察），你只需要找到并消费这些数据；另一种是把外部数据源——HTTP 接口、数据库、本地文件——接进来供 AI 查询。本文按场景带你走完选方案到动手接通的全过程。
先想清楚你要让数据干这三件事
在动手之前，把目标落到具体任务上：
- 让看板直接显示任务进度。Hermes Agent 的看板数据通过 api/kanban_bridge.py 里的桥接层暴露给 WebUI，任务、评论、事件都以接口形式返回，前端按卡片渲染，不需要你写查询逻辑。
- 弄清楚 token 花在了哪个模型上。Insights 面板按天和模型聚合了令牌消耗与成本，对应
/api/insights接口（位于 api/routes.py）。开启sync_to_insights配置后，会话的消息计数会同步到 Agent 侧的 state.db，数据源就是 SQLite。 - 让 AI 能查生产库的数据。这属于外部数据源接入，按下面"方案怎么选"一节决定走接口、直连还是文件。
能力速览：内置数据能力各管什么
| 能力 | 解决的问题 |
|---|---|
| Kanban 看板数据 | 任务状态、评论、事件以接口形式暴露，Web 端实时展示进度 |
| Insights 洞察 | 按天/按模型统计令牌量与成本，定位开销大头 |
| SQLite 会话存储 | 会话元数据与消息落盘在 state.db，支持检索、筛选与恢复 |
外部数据源连接方案怎么选
先问自己两个问题：数据现在从哪来？是实时推过来还是你主动去拉？
- 如果你的情况是数据挂在 HTTP 服务上（REST 端点、GraphQL、WebSocket 推送），推荐走接口连接。REST 适合"发请求取结果"的批量查询，WebSocket 适合服务端主动推送的实时场景，GraphQL 适合字段多且每次只取一部分的复杂查询。接入点统一在 api/routes.py 的路由层扩展。
- 如果你的情况是需要 SQL 级别的直接访问：内置 SQLite 开箱即用；PostgreSQL 或 MySQL/MariaDB 需要在配置里写明连接信息，通过适配器建立连接。
- 如果你的情况是数据就是本地文件——CSV、JSON、Excel 或日志文件——推荐直接解析读取。这类数据没有连接和超时问题，是最先值得接通的类型。
Hermes WebUI 连接外部数据库的三步流程
第 1 步：准备
克隆代码并确认环境可用：
git clone https://gitcode.com/GitHub_Trending/he/hermes-webui cd hermes-webui外部库的账号密码一律放环境变量，不写进配置文件。
第 2 步：配置与代码位置
在配置文件里声明数据源，敏感值用环境变量引用：
datasources: prod_db: type: postgresql host: db.internal port: 5432 db: orders user: ${DB_USER} password: ${DB_PASSWORD}- 连接信息写在
config.yaml（database.path可指到~/.hermes/state.db）。 - 数据访问的模型定义放在 api/models.py，新增查询字段时在这里加。
- 对外查询端点在 api/routes.py 中挂路由，POST 接收
source和查询语句，返回 JSON 结果。
第 3 步：验证
发一条最小查询确认链路通：能取回数据后，再看 Insights 里对应的消耗是否符合预期。卡住时的排查顺序见下一节。
数据库连接超时的排查：避坑自查清单
- 用户名密码放在环境变量里，配置文件里只留
${VAR}引用 - 对外传输启用了 TLS，静态数据有备份策略
- 数据库连接走连接池复用，并设置了合理的连接超时与重试次数
- 高频查询字段建了索引，大结果集用分页返回
- 每次用完连接都关闭，防止句柄泄漏拖垮服务
- 所有数据访问有审计记录，异常查询模式能被发现
症状速查：
- 连接超时→ 先查网络与防火墙放没放行端口，再看超时参数是否设得太短。
- 认证失败→ 核对环境变量实际展开后的用户名密码，确认该账号对目标库有权限。
- 查询明显变慢→ 检查是否缺索引、单次拉取的数据量是否超出分页上限。
下一步做什么
如果你只是想让看板、会话、用量数据动起来，什么都不用写——它们已经内置，直接打开界面对应的面板即可。如果你要接生产库，先去config.yaml声明数据源、在api/routes.py加一个查询端点，这是最短路径。连接不通时，先翻~/.hermes/webui.log找报错栈，再对照上面的清单逐项核对；接口行为有疑问时，直接看api/routes.py里对应路由的实现比猜更快。
【免费下载链接】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），仅供参考
