Dashboard 使用指南

Dashboard 是 thurgio serve 内置的 Web 控制台，以单文件模板 ui.tpl 的形式提供状态监控、渲染结果查看、管理操作与临时资源创建能力，无需额外前端构建或 CDN。

模板来源：fixtures/examples/tpls/ui.tpl 为唯一来源（thurgio init 经 include_str! 分发写入用户 tpls/ui.tpl），CSS/JS 内联，纯原生 JS + canvas 实现。

概述

是什么

默认 ui.tpl 仅展示 Server/Version/Last Build 与 SSE 自动刷新，Dashboard 在此基础上提供全功能控制台：

• 只读视图：系统健康、性能指标、熔断器状态、各 provider/snippet 渲染结果、构建事件流。
• 管理能力（仅 admin 作用域可见）：渲染参数编辑、构建/刷新/重载/保存、开发模式切换、临时 provider/snippet 创建。

如何访问

1. 启动服务：

   thurgio serve
   # 默认监听 0.0.0.0:10100，可用 --address / --port 覆盖，详见 [Serve 命令](./cli/serve.md)
   

2. 打开登录页：

   http://<address>:<port>/app/login
   

   输入令牌完成校验后跳转至 Dashboard。或直接携带令牌访问：

   http://<address>:<port>/app/read/ui?token=<your-token>
   

   令牌亦可通过 Authorization: Bearer <token> 请求头传递（查询参数优先），与 API 参考 认证方式一致。

提示：GET / 仅返回 Hello world! 健康问候，不承载 Dashboard；Dashboard 固定路由为 GET /app/read/ui，需认证。

登录与令牌

作用域

在 thurgio.yaml 中按作用域分组配置（至少配置一个）：

# thurgio.yaml
setting:
  tokens:
    admin:
      - "admin-token-xxx"
    read:
      - "read-token-yyy"

• Read — 仅可访问只读渲染端点。
• Admin — 可访问全部端点（含管理端点），同时满足 Read 要求。

未认证或作用域不足的请求返回 401 Unauthorized。详见 API 参考 与 配置指南。

登录流程

• GET /app/login — 返回登录页 HTML（公开端点，无需认证）。

• POST /app/login — 接收 JSON {"token": "..."}，校验作用域：

  curl -X POST http://localhost:10100/app/login \
    -H "Content-Type: application/json" \
    -d '{"token":"admin-token-xxx"}'
  

  成功响应：

  { "ok": true, "scope": "admin" }
  

  scope 为 "admin" 或 "read"；缺失 token 字段返回 400，无效令牌返回 401。

登录页校验通过后，前端以 ?token= 形式跳转至 /app/read/ui。Dashboard 内 token 仅从 URL 读取，不写入 localStorage/sessionStorage；刷新或分享链接时需保留 URL 中的 token 参数。

权限差异

UI 按 GET /app/read/ui 注入的 Tera 上下文变量 scope（"admin" / "read"）显隐管理模块，实际权限由服务端中间件强制。

页面功能走查

下表按 design/specs/spec-dashboard.md 的功能列表逐项说明，并标注对应的 HTTP API 端点。

顶栏

• 展示：版本、当前 scope 徽章、连接状态、手动刷新按钮。
• 数据源：GET /v（版本字符串）与 GET /app/read/ui 注入的 scope / Tera version 上下文。

系统状态卡

• 展示：DB 连接、内存占用、CPU 核心数、状态、时间戳。
• 数据源：GET /health（公开端点，返回 status / version / database / memory_usage_mb / cpu_cores / timestamp，详见 API 参考）。

指标卡 + sparkline

• 展示：请求数、错误数、平均延迟、代理数、渲染线程、缓存命中/未命中、命中率；请求/延迟/线程三条 canvas 趋势线。
• 数据源：GET /metrics（Prometheus 暴露格式，含请求指标、熔断器快照、渲染线程池指标 renderer_active_threads 等）。
• 刷新：10s 静默轮询，sparkline 采样上限 40 点。

断路器

• 展示：每 breaker 状态（Closed / Open / Half-Open）与失败计数。
• 数据源：GET /metrics（熔断器快照段）。
• 交互：默认折叠，仅显示标题栏 + 总数摘要，点击展开完整内容；刷新页面恢复默认折叠。

渲染项

• 展示：两类 tab（provider / snippet），点击展开 <pre> 预览，支持复制、复制链接、新标签打开；超长内容自动折叠（见下文）。
• 数据源：
  • GET /app/read/c — 渲染完整 Tera 上下文为 JSON（含 scope，config 内 proxies / content 已剔除），用于获取资源键名与参数 p。
  • GET /app/read/l?name={name} — 按名称渲染 provider（支持 ?d= 下载头与请求级规则覆盖 pre_rename / filter / rename / ap_* / emoji / udp / tpl，详见 API 参考）。
  • GET /app/read/r?name={name} — 按名称渲染 snippet。
• 交互：点击 tab 按需拉取对应 l / r 内容并注入 <pre>；超长时仅显示前 100 行 + … 共 M 行 提示与展开/收起按钮；复制按钮始终复制完整内容，不受折叠影响；复制链接与新标签打开均复制/打开带 token 的完整 URL。

事件日志

• 展示：build_complete 时间戳流，上限 50 条。
• 数据源：GET /app/read/events（SSE，text/event-stream，每次构建完成推送 build_complete，每 15s 发送 keep-alive 心跳）。

参数编辑（仅 admin）

• 展示：扁平 KV 表格（点分路径如 dns.enabled），提交后与内存中配置参数深度合并。

• 数据源：读取 GET /app/read/c 中的 p 字段，写入 GET /app/admin/p（查询字符串即参数，点分键写入嵌套结构）。

• 交互：默认折叠，仅显示标题栏 + 参数数量摘要，点击展开；提示“值只能覆盖不能删除“（深合并语义，无清除 API）。

• 示例：

  curl "http://localhost:10100/app/admin/p?dns.enabled=true&port=9090&token=admin-token-xxx"
  

操作区（仅 admin）

临时资源（仅 admin）

• 展示：表单 + 结果内嵌预览（超长折叠逻辑同渲染项）。

• 端点：GET /app/admin/adhoc（创建一次性 provider/snippet，不写入配置文件，缓存持久化到 DB，重启后命中缓存即恢复；按 adhoc.max_items / adhoc.ttl_seconds 自动清理）。

• 查询参数：

  参数	必填	说明
  type	是	provider / snippet
  url	是	数据源 URL
  name	否	名称，缺省自动生成 adhoc-<8 位 hex>
  format	否	clash / meta / v2rayn / sip002 / surge / auto（仅 provider 生效），默认 auto
  tpl	否	模板名，缺省回退 setting.adhoc.tpl.provider / tpl.snippet
  pre_rename / filter / rename	否	逗号分隔的规则名，按序应用（未知规则名静默忽略）
  force	否	true 时忽略内存 + DB 缓存强制重抓

  curl "http://localhost:10100/app/admin/adhoc?type=provider&url=https://example.com/clash.yaml&token=admin-token-xxx"
  

  响应为 text/plain 渲染内容，并携带 subscription-userinfo 头；同名临时资源可经 GET /app/read/l / GET /app/read/r 后续引用，对配置中同名正式项呈遮蔽效果。

刷新与折叠行为

• SSE 驱动：收到 build_complete 后触发 toast，并重拉 GET /health、 GET /app/read/c 与 GET /metrics。
• 指标轮询：10s 静默刷新 GET /metrics。
• 超长面板折叠：渲染项展开区与临时资源预览，内容行数 > 100 行或高度 > 60vh 时折叠；判定为内容注入 <pre> 后一次性基于行数/scrollHeight 判定；长内容以 textContent 一次性注入。
• 段级默认折叠：断路器与参数编辑模块默认折叠，点击标题栏展开。

权限矩阵（接口层）

自定义界面

覆盖方式

Dashboard 页面由模板 tpls/ui.tpl 渲染（端点 GET /app/read/ui）。thurgio init 会在目标目录生成：

<dir>/
├── thurgio.yaml
├── provider.yaml
├── filter.yaml
├── rename.yaml
├── params.yaml
├── snippet.yaml
└── tpls/
    ├── base.tpl
    └── ui.tpl      # Dashboard 页面模板

来源为 fixtures/examples/tpls/ui.tpl，详见 Init 命令 与 模板示例。

可直接编辑 tpls/ui.tpl 自定义 Dashboard：

# 编辑后重载
curl "http://localhost:10100/app/admin/reload?token=admin-token-xxx"
# 或以开发模式自动重载
thurgio serve --dev
# 或运行时切换
curl "http://localhost:10100/app/admin/dev?value=true&token=admin-token-xxx"

模板上下文可用变量与普通模板一致（config / p / hp / headers / version），另注入 scope（"admin" / "read"）用于按权限显隐模块，详见 API 参考 中“渲染 UI“与“渲染上下文“小节。

注意事项

• 勿删除 tpls/ui.tpl — 服务器自带 UI 依赖它，删除后 GET /app/read/ui 将渲染失败。
• 单文件约束 — CSS/JS 需内联，无外部依赖/CDN，保持单文件可分发。
• 热更新 — thurgio serve 默认仅监听主配置 thurgio.yaml 变更，不监听模板目录；模板变更需 --dev 或手动调 GET /app/admin/reload，详见 Serve 命令 与 常见问题。
• 模板语法 — 使用 Tera（类 Jinja2），内置 30+ 过滤器，详见 模板示例 与 配置指南。

常见问题

Read 令牌看不到操作区是正常现象吗？

是。参数编辑、操作区、临时资源仅对 admin 作用域可见，Read 令牌访问对应管理端点会返回 401。如需操作能力，请使用 setting.tokens.admin 中配置的令牌登录。

URL 中的 token 会留在浏览器历史中吗？

会。Dashboard 与登录页均以 ?token= 传递令牌，浏览器历史与“复制链接“/“新标签打开“生成的 URL 均会包含明文 token，属已知取舍。避免在公共设备上保留历史，或使用 Authorization: Bearer 方式通过 API 访问。

构建一直转圈或返回错误如何排查？

• 操作区 Build 为同步阻塞请求，fetch 结束即构建结束；失败时状态条会显示响应的 message。
• 可结合 GET /health、GET /metrics、GET /app/read/events（SSE）与 GET /app/read/c 查看上下文，确认参数与熔断器状态。
• 模板相关问题可用 RUST_LOG=debug thurgio serve 查看日志，或切至开发模式 GET /app/admin/dev?value=true 后重试。