企业官网建设流程全解析

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

凌晨三点，业务方要一份 30 天的用量统计，你不想翻五篇文档找连接串。你需要的是一个网页面板：数据在哪、能查什么、接通之后长什么样，一眼看清。Hermes WebUI 的数据库集成解决的就是这件事——会话本身用 SQLite 做持久化，看板和洞察直接读同一份数据，外部数据源再通过三条路接进来。下面按"先跑起来，再讲门道"的顺序来。

先跑通：clone、起服务、开面板

跟着做，三步之内你就能在浏览器里看到它。

# 1. 克隆仓库并进入目录 git clone https://gitcode.com/GitHub_Trending/he/hermes-webui cd hermes-webui # 2. 跑 bootstrap：自动装依赖、起服务、等 /health 通过 python3 bootstrap.py # 3. 想常驻后台就用 ctl.sh 管理生命周期 ./ctl.sh start ./ctl.sh status

bootstrap.py会检测你机器上有没有 Hermes Agent，没有就尝试装；然后建好 Python 环境，等服务健康检查通过再打开浏览器，进去是首次引导向导。之后每次开会，./ctl.sh start就行，停止用./ctl.sh stop。

跑起来之后先记住两个位置：会话和元数据落在 SQLite 文件里（默认~/.hermes/state.db），运行日志在~/.hermes/webui.log。后面排查问题全靠它。

要接什么数据，走什么路

数据源形态不一样，入口就不一样。按你的情况对号入座。

接口已经现成的，走 API 这条路。如果你的外部系统暴露了 REST、WebSocket 或 GraphQL 端点，直接在 api/routes.py 加一个路由处理查询，把结果转成前端能渲染的结构。连接信息别硬编码，放在配置里、用环境变量带凭据：

# 外部数据源配置示例，凭据走环境变量 external_sources: - name: "production_db" type: "postgresql" host: "localhost" port: 5432 username: "${DB_USER}" password: "${DB_PASSWORD}"

设置面板里能看到各数据源/提供方的配置状态，配好没配好一目了然：

数据就在本地文件里的，走文件这条路。SQLite 是内置支持，会话库本身就是这么跑的，不用额外装驱动。CSV、JSON 这类结构化文件直接解析；Excel 等办公文档的读取逻辑在 api/office_documents.py，日志文件也可以按行流式读进来做监控。

数据是任务/工单形态的，走看板这条路。看板模块在 api/kanban_bridge.py 下暴露/api/kanban/*一组 CRUD 接口，Agent 侧的看板库是唯一事实来源，WebUI 这边只做读写投影——你不需要自己建表、自己同步，天然一致。

跑通之后，你能看到什么

看板：任务卡片实时刷新，谁在卡、卡在哪一步，早上站会前你扫一眼页面就够了，不用挨个问人。

洞察面板：token 用量、预估成本、按模型拆的占比，30 天窗口直接可视化。月底算账的时候，这张图就是答案：

会话存储：每段对话都落在 SQLite 里，刷新页面、断开重连都不丢；支持按标题和消息内容搜索、按项目归类、导出 Markdown 或 JSON。你昨天半夜跟 Agent 对出来的结论，今天一条搜索就能捞回来。

工作区文件浏览：右侧面板直接预览代码、Markdown、图片，workspace://链接在对话里一点就开。处理数据文件时，你不用切工具：

上线前三件事

• 凭据全部走环境变量，配置文件里不留明文
• 外部连接加上超时和重试，别让一次网络抖动拖垮整个面板
• 每次数据访问记一行审计日志，出事了能回溯
• 大数据集一律分页查，别一把拉全量
• 公网路径挂 TLS，本地回环除外

出问题先看这 4 处

日志在~/.hermes/webui.log，跑./ctl.sh logs --lines 100直接看最近 100 行，多数问题第一眼就能定位。

再进一步：写个自己的适配器

如果你的数据源既不是标准接口也不是本地文件，可以自己写适配器。思路很简单：一个类接收配置、实现查询执行，然后让路由层像调用其他数据源一样调用它，放哪个目录、怎么注册，跟着 api/models.py 里现有的模型定义方式走就行：

class CustomDataAdapter: def __init__(self, config): self.config = config def execute_query(self, query_params): # 在这里实现你自己的查询执行逻辑 ...

扩展点就这一个：只要execute_query的输入输出和其他适配器对齐，前端展示、审计、分页这些能力就都是现成的。

数据接进来只是开始，真正值钱的是它变成你能随时看、随时问的面板。先在你的测试库上把上面第二节的配置跑一遍，确认连接状态是绿的，再动生产。

【免费下载链接】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