Web 管理界面

本文引用的文件
- admin/ui/index.html - admin/ui/app.js - admin/ui/style.css - admin/admin.toml - src/admin_server.v - src/admin_runtime.v - README.md

简介

本文件面向运维与开发者，系统化介绍 vhttpd 的 Web 管理界面。内容覆盖实时监控仪表板、可观测性面板、应用管理、配置编辑器、运行时图、Schema 目录、草稿（Draft）工作流、事件日志与原始快照等核心功能；并给出页面使用方法、数据展示方式、交互操作、响应式设计与主题自定义指南，以及端到端的使用流程与操作步骤说明。

项目结构

Web 管理界面由“静态前端资源 + 服务端控制平面”两部分组成： - 前端资源位于 admin/ui，包含入口 HTML、主逻辑 JS 与样式 CSS。 - 服务端提供 /admin/* 系列 API，负责鉴权、路由、状态聚合与持久化草稿/发布。

graph TB
subgraph "浏览器"
UI["index.html<br/>app.js<br/>style.css"]
end
subgraph "vhttpd 控制平面"
Srv["admin_server.v<br/>路由/鉴权/静态资源"]
RT["admin_runtime.v<br/>运行时/草稿/Schema/事件"]
end
UI --> |HTTP GET/POST| Srv
Srv --> RT
Srv --> |静态资源| UI

图示来源 - admin/ui/index.html:1-36 - admin/ui/app.js:1-10 - admin/ui/style.css:1-20 - src/admin_server.v:111-141 - src/admin_runtime.v:7-20

章节来源 - admin/ui/index.html:1-36 - admin/ui/app.js:1-10 - admin/ui/style.css:1-20 - src/admin_server.v:111-141 - src/admin_runtime.v:7-20

核心组件

侧边导航与视图切换：Dashboard、Observability、Applications、Editor、Runtime Graph、Schema、Drafts、Events、Raw。
认证令牌输入：通过 x-vhttpd-admin-token 头进行鉴权。
数据拉取与渲染：集中定义后端端点，统一错误处理，按视图渲染指标、拓扑、表格与图表。
草稿与发布：支持保存、校验、差异预览、发布到 include 路径，并可热加载生效。
源码编辑：打开配置或源文件草稿，语法高亮与行号显示，支持保存与发布。

章节来源 - admin/ui/index.html:16-33 - admin/ui/app.js:1-21 - admin/ui/app.js:33-64 - admin/ui/app.js:84-102 - admin/ui/app.js:1054-1066

架构总览

Web 管理界面的请求链路如下：浏览器发起 HTTP 请求至控制平面，控制平面执行鉴权后转发至运行时接口，返回 JSON 数据供前端渲染。

sequenceDiagram
participant B as "浏览器"
participant A as "AdminServer(控制平面)"
participant R as "AdminRuntime(运行时)"
participant FS as "文件系统/状态存储"
B->>A : GET /admin/runtime (带 x-vhttpd-admin-token)
A->>A : 鉴权检查
A->>R : 调用运行时快照
R-->>A : JSON 快照
A-->>B : 200 OK + JSON
B->>A : POST /admin/drafts?id=xxx (保存草稿)
A->>FS : 写入草稿
FS-->>A : 成功
A-->>B : 200 OK + {draft_id}
B->>A : POST /admin/drafts/ : id/publish?path=...
A->>FS : 发布到 include 路径
FS-->>A : 成功
A-->>B : 200 OK + {config_path}
B->>A : POST /admin/runtime/plan/replacement/apply?config=...
A->>R : 热加载替换
R-->>A : 结果
A-->>B : 200/202 + 结果

图示来源 - src/admin_server.v:111-141 - src/admin_server.v:288-334 - src/admin_server.v:338-403 - src/admin_server.v:470-557 - src/admin_runtime.v:194-357 - src/admin_runtime.v:398-461

详细组件分析

实时监控仪表板（Dashboard）

数据展示
关键指标：应用数、监听器数、流水线数、中继数、草稿数、事件数。
实时拓扑：基于 /admin/runtime/graph 的节点与边，绘制 Listener -> Pipeline -> Adapter -> Engine 的流向图。
应用列表：从 /admin/apps 或图聚合生成，展示类型、监听器、流水线、引擎与状态。
监听端口：列出协议/传输、地址与控制面标记。
流水线流：匹配规则与出向适配器。
运行态摘要：HTTP 请求/错误计数、活跃 WebSocket/Upstream、Worker 模式等。
交互操作
点击“刷新”触发全量拉取。
拓扑节点可点击查看详情弹窗。
数据来源
/admin/stats、/admin/runtime、/admin/runtime/graph、/admin/apps（或图聚合）。

flowchart TD
Start(["进入 Dashboard"]) --> Fetch["并行拉取 endpoints:<br/>runtime, graph, stats, apps, drafts, events"]
Fetch --> RenderMetrics["渲染指标卡片"]
Fetch --> RenderTopology["渲染拓扑图"]
Fetch --> RenderApps["渲染应用列表"]
Fetch --> RenderListeners["渲染监听端口"]
Fetch --> RenderPipelines["渲染流水线流"]
Fetch --> RenderRuntime["渲染运行态摘要"]
RenderMetrics --> End(["完成"])
RenderTopology --> End
RenderApps --> End
RenderListeners --> End
RenderPipelines --> End
RenderRuntime --> End

图示来源 - admin/ui/app.js:65-82 - admin/ui/app.js:268-357 - src/admin_runtime.v:7-20 - src/admin_runtime.v:60-73 - src/admin_server.v:131-141 - src/admin_server.v:199-221

章节来源 - admin/ui/index.html:44-70 - admin/ui/app.js:268-357 - src/admin_runtime.v:7-20 - src/admin_runtime.v:60-73 - src/admin_server.v:131-141 - src/admin_server.v:199-221

可观测性面板（Observability）

数据展示
指标：HTTP 请求总数、错误数与错误率、路由数量、开放通道、WebSocket 会话、进程存活时长。
流量趋势：基于历史采样绘制的折线面积图。
执行器分布：按 executor 维度统计占比。
健康度网格：错误、拒绝、超时、上游错误、MCP 丢弃、飞书发送错误等。
路由表：Listener/Pipeline/Executor/Methods/Paths。
交互操作
顶部刷新按钮更新所有指标与图表。
数据来源
/admin/stats、/admin/runtime、/admin/events、/admin/runtime/graph。

flowchart TD
OStart(["进入 Observability"]) --> Load["拉取 stats/runtime/events/graph"]
Load --> Metrics["计算指标与错误率"]
Load --> Trend["记录采样并绘制趋势"]
Load --> Mix["统计执行器/事件类型分布"]
Load --> Health["汇总健康项"]
Load --> Routes["投影路由表"]
Metrics --> OEnd(["完成"])
Trend --> OEnd
Mix --> OEnd
Health --> OEnd
Routes --> OEnd

图示来源 - admin/ui/app.js:646-698 - admin/ui/app.js:165-175 - src/admin_runtime.v:37-58 - src/admin_runtime.v:60-73 - src/admin_server.v:131-141

章节来源 - admin/ui/index.html:71-103 - admin/ui/app.js:646-698 - src/admin_runtime.v:37-58 - src/admin_runtime.v:60-73 - src/admin_server.v:131-141

应用管理（Applications）

功能要点
应用清单：展示应用 ID、类型、监听器、流水线、引擎与状态。
新应用向导：根据表单字段自动生成 TOML 片段，支持保存为草稿并发布到 include 路径。
配置文件列表：列出已加载的配置及角色（main/include），支持对非 main 文件创建草稿。
交互操作
填写表单 → 生成 TOML → 保存草稿 → 选择发布路径 → 发布 → 可选热加载。
数据来源
/admin/apps（或图聚合）、/admin/config/files、/admin/drafts。

sequenceDiagram
participant U as "用户"
participant UI as "UI 表单"
participant API as "/admin/drafts"
participant FS as "include 文件"
participant RL as "热加载"
U->>UI : 填写新应用参数
UI->>UI : 生成 TOML
U->>API : POST /admin/drafts?id=app.xxx.toml
API-->>UI : 返回 draft_id
U->>API : POST /admin/drafts/ : id/publish?path=...
API->>FS : 写入 include 文件
FS-->>API : 成功
API-->>U : 返回 config_path
U->>RL : POST /admin/runtime/plan/replacement/apply?config=...
RL-->>U : 热加载结果

图示来源 - admin/ui/index.html:104-194 - admin/ui/app.js:724-815 - src/admin_server.v:288-334 - src/admin_server.v:338-403 - src/admin_server.v:470-557

章节来源 - admin/ui/index.html:104-194 - admin/ui/app.js:724-815 - src/admin_server.v:288-334 - src/admin_server.v:338-403 - src/admin_server.v:470-557

配置编辑器（Editor）

功能要点
源文件列表：列出可编辑的源文件（含语言类型、大小），支持打开草稿。
编辑器：行号、语法高亮（TOML/JS/TS/JSON）、Tab 缩进、Ctrl/Cmd+S 快捷保存。
动作：保存草稿、发布到目标路径、校验 TOML。
数据来源
/admin/source/files、/admin/source/files/draft、/admin/drafts、/admin/source/drafts/:id/publish。

flowchart TD
EStart(["进入 Editor"]) --> List["获取源文件列表"]
List --> Open["打开文件草稿"]
Open --> Edit["编辑/高亮/行号"]
Edit --> Save["保存草稿"]
Edit --> Validate["校验 TOML"]
Edit --> Publish["发布到 include 路径"]
Save --> EEnd(["完成"])
Validate --> EEnd
Publish --> EEnd

图示来源 - admin/ui/index.html:195-233 - admin/ui/app.js:489-575 - admin/ui/app.js:891-950 - src/admin_server.v:336-363 - src/admin_server.v:387-403

章节来源 - admin/ui/index.html:195-233 - admin/ui/app.js:489-575 - admin/ui/app.js:891-950 - src/admin_server.v:336-363 - src/admin_server.v:387-403

运行时图（Runtime Graph）

功能要点
节点列表：展示 domain、kind、metadata 等。
拓扑图：在 Dashboard/Observability 中以 SVG 可视化呈现。
节点详情：点击节点弹出模态框，展示入边/出边与元信息。
数据来源
/admin/runtime/graph。

classDiagram
class Node {
+string ref
+string id
+string label
+string domain
+string kind
+map metadata
}
class Edge {
+string from
+string to
+string kind
}
class Graph {
+Node[] nodes
+Edge[] edges
}
Graph --> Node : "包含"
Graph --> Edge : "包含"

图示来源 - admin/ui/app.js:824-835 - admin/ui/app.js:206-259 - admin/ui/app.js:1034-1053 - src/admin_runtime.v:60-73

章节来源 - admin/ui/index.html:234-239 - admin/ui/app.js:824-835 - admin/ui/app.js:206-259 - admin/ui/app.js:1034-1053 - src/admin_runtime.v:60-73

Schema 目录（Schema）

功能要点
目录页：列出 Domain 及其 Kinds。
详情：可按 domain/kind 查询具体 schema 定义。
数据来源
/admin/schema、/admin/schema/:domain、/admin/schema/:domain/:kind。

章节来源 - admin/ui/index.html:240-245 - admin/ui/app.js:836-844 - src/admin_runtime.v:75-135 - src/admin_server.v:235-286

草稿（Drafts）

功能要点
草稿列表：ID、更新时间、字节数、打开操作。
编辑器：TOML 高亮、行号、保存/校验/差异/发布/删除。
发布：将 include 路径写入磁盘，随后可通过热加载生效。
数据来源
/admin/drafts、/admin/drafts/:id、/admin/drafts/:id/validate、/admin/drafts/:id/diff、/admin/drafts/:id/publish。

flowchart TD
DStart(["进入 Drafts"]) --> List["GET /admin/drafts"]
List --> Open["GET /admin/drafts/:id"]
Open --> Edit["编辑 TOML"]
Edit --> Validate["POST /admin/drafts/:id/validate"]
Edit --> Diff["GET /admin/drafts/:id/diff"]
Edit --> Publish["POST /admin/drafts/:id/publish?path=..."]
Publish --> Apply["POST /admin/runtime/plan/replacement/apply?config=..."]
Validate --> DEnd(["完成"])
Diff --> DEnd
Publish --> DEnd
Apply --> DEnd

图示来源 - admin/ui/index.html:246-282 - admin/ui/app.js:845-1013 - src/admin_runtime.v:137-357 - src/admin_server.v:288-403 - src/admin_server.v:470-557

章节来源 - admin/ui/index.html:246-282 - admin/ui/app.js:845-1013 - src/admin_runtime.v:137-357 - src/admin_server.v:288-403 - src/admin_server.v:470-557

事件日志（Events）

功能要点
最近事件：时间、类型、目标键。
限制：默认 limit=80，可在 URL 中调整。
数据来源
/admin/events?limit=80。

章节来源 - admin/ui/index.html:283-288 - admin/ui/app.js:1014-1022 - src/admin_runtime.v:37-58 - src/admin_server.v:167-185

原始快照（Raw）

功能要点
以只读编辑器展示当前缓存的 data/errors 快照，便于调试。
数据来源
前端内存 state.data/state.errors。

章节来源 - admin/ui/index.html:289-300 - admin/ui/app.js:1023-1025

依赖关系分析

前端依赖
index.html 引入 style.css 与 app.js。
app.js 集中声明后端端点，统一鉴权头注入与错误处理。
服务端依赖
admin_server.v 提供 /health、/admin/* 路由与鉴权中间逻辑。
admin_runtime.v 提供运行时、草稿、Schema、事件等数据接口。
外部依赖
README.md 列举了部分 /admin/* 端点能力，作为补充参考。

graph LR
HTML["index.html"] --> CSS["style.css"]
HTML --> JS["app.js"]
JS --> API["/admin/* 端点"]
API --> Server["admin_server.v"]
Server --> Runtime["admin_runtime.v"]

图示来源 - admin/ui/index.html:7-8 - admin/ui/index.html:324-326 - admin/ui/app.js:1-10 - src/admin_server.v:111-141 - src/admin_runtime.v:7-20

章节来源 - admin/ui/index.html:7-8 - admin/ui/index.html:324-326 - admin/ui/app.js:1-10 - src/admin_server.v:111-141 - src/admin_runtime.v:7-20 - README.md:1147-1185