开发指南
主题开发
主题是一个纯静态的单页应用,决定公开状态页的样子。hub 只把它当静态文件提供:不编译、不注入、不提供构建期变量。
后台和登录页始终由 hub 内置提供,不属于主题,主题不必实现节点管理、OAuth 和密码设置。
主题包
一个可安装主题是一个目录,名字必须和 theme.json 里的 short 相同:
<themes-dir>/<short>/
├── theme.json
├── preview.png # 可选,面板上的预览图,文件名固定
└── dist/
└── index.html发布时打成 theme.tar.gz,解开就是这个目录。放进 GitHub release 时文件名保持 theme.tar.gz:面板的「从 GitHub 安装」和一键更新只认仓库最新正式 release(不含预发布和草稿)里这个名字的文件。
hub 安装时会校验 gzip 尾部,不完整的包会被拒绝。发布前用 gzip -t 检查一遍,没有输出就是完整的:
# 检查压缩流是否写完整,打包脚本没收尾时这里会报错
gzip -t theme.tar.gzbashtheme.json
name 到 url 六个字段都要写,都是字符串,后四个可以是空字符串;config 可以不写:
| 字段 | 可留空 | 含义 |
|---|---|---|
name | 否 | 显示名称 |
short | 否 | 唯一短名,限字母、数字、-、_。取 default 则顶替 hub 内置的那份 |
description | 是 | 简介 |
version | 是 | 主题版本。用一键更新时要和 release 的 tag 对上(v1.2.0 对 1.2.0),否则每次都会重装一遍 |
author | 是 | 作者 |
url | 是 | 源码地址。指向 GitHub 仓库时,面板的一键更新从它的 release 取 theme.tar.gz |
config | 可不写 | 数组,站长可调的设置,面板按它画表单。见下文主题设置 |
少写一个字段时,在面板安装会被拒绝,并指出缺的是哪个;直接放进 hub 的 --themes 目录的,主题不会出现在列表里,hub 日志里有一条警告。
上限
| 限制 | 值 |
|---|---|
| 整包 | 32 MiB |
| 解压后总量 | 64 MiB |
| 单个文件 | 8 MiB |
| 文件和目录数(含路径里隐含的上级目录) | 2000 |
| 单条路径 | 4096 字节 |
| tar 结尾之后的填充 | 1 MiB |
只接受普通文件和目录,包里有符号链接等其他类型时拒绝安装。包里记的权限按 umask 022 收窄,装出来的文件不会是所有人可写的。
可以用的接口
读取接口只有这五个,都是同源请求。主题自带设置界面时还会用到 PUT,见下文主题自带的设置界面。
| 接口 | 用途 |
|---|---|
GET /api/me | 站点名、登录状态、公开页开关、历史保留天数 |
GET /api/nodes | 节点列表、实时指标、累计流量 |
GET /api/nodes/{id}/metrics | 历史指标和延迟记录 |
GET /api/ws | 每 2 秒推送一次节点快照的 WebSocket,加 ?gzip 收压缩帧,见下文推送压缩 |
GET /api/themes/{short}/config | 站长在面板里保存的主题设置,见下文主题设置 |
metrics 的三个查询参数都可以省:
hours=N:窗口宽度,默认 6,上限是/api/me的history_days× 24,登录与匿名相同,超出时静默收窄points=W:图表能画下的点数,60–1440。只会让 hub 抽得更稀,不会更密series=metrics|ping:只取要画的那一类,另一类占响应的三分之一到三分之二
响应顶层的 step 是每个点覆盖的秒数:7 天以内是 60 的倍数,更宽的窗口是 3600 的倍数。
metrics 的每一行描述一段时间,minutes 是其中有数据的分钟数,满额是 step ÷ 60:
cpu、mem_used、swap_used、disk_used、net_rx/net_tx是平均值,网速 ×minutes× 60 就是这段时间的流量tcp、udp、procs是这段时间内 TCP 连接数、UDP 套接字数、进程数的平均值,取整cpu_max、net_rx_max/net_tx_max是最高值。短时的测速、CPU 占满在平均值里会被摊薄,要画它到过多高就读这几个minutes不满额,说明这段时间节点有一部分不在线,可以用来画在线率。最后一个点是还没过完的时段,不满额不代表离线- agent 的
--interval超过 60 秒时minutes会偏小,积分出的流量和在线率偏低。累计流量以/api/nodes为准
延迟监控的名称在响应的 probes 里随数据一起返回,匿名可读,画延迟图不需要第二个请求,也不需要登录。
时间范围
站长在面板里设的保留天数就是能画多远,/api/me 里的 history_days(1–365)给出这个数。时间范围的按钮按它生成,不要写死:写死的「30 天」遇上只保留 7 天的 hub,会被静默收窄成 7 天,按钮上却还写着 30 天。
// 默认主题的做法:小于保留期的整档位,最后加上保留期本身。
// 保留期比某个整档位多不到四分之一时去掉那一档,
// 免得「90 天」「92 天」两个按钮并列
const WINDOWS = [1, 6, 24, 168, 720, 2160]
const whole = history_days * 24
const hours = [...WINDOWS.filter((h) => h * 1.25 <= whole), whole]tsping 里的记录按站长在面板上排的监控顺序逐个排列,同一个监控的记录按时间先后。按 task_id 第一次出现的顺序生成曲线,图例和配色就和面板一致。
// 每个监控一条线,先后就是面板上的顺序
const ids = [...new Set(ping.map((p) => p.task_id))]ts推送压缩
连 /api/ws?gzip 时,hub 把每一帧 gzip 后以二进制消息发出,解开就是同一份 JSON。100 台在线节点一帧约
110 KB,压缩后约 15 KB;页面一直开着时(副屏、监控大屏),hub 的出网流量主要就是这些帧,务必加上。
hub 只看有没有这个参数,不看它的值。两种帧都要能收:旧版 hub 不认这个参数,照发文本帧;站长登录着打开公开页时推的是带管理字段的帧,这种帧 hub 一律不压缩,也是文本。
// 浏览器没有 DecompressionStream 时不要压缩帧
const gzip = typeof DecompressionStream === "function" ? "?gzip" : ""
const scheme = location.protocol === "https:" ? "wss" : "ws"
const socket = new WebSocket(`${scheme}://${location.host}/api/ws${gzip}`)
// 压缩帧收到的是 Blob(binaryType 保持默认),文本帧是字符串
const frameText = (data: string | Blob) => {
if (typeof data === "string") return data
const plain = data.stream().pipeThrough(new DecompressionStream("gzip"))
return new Response(plain).text()
}
// 解压是异步的,后到的帧可能先解完,所以一帧接一帧地处理
let decoded = Promise.resolve()
socket.onmessage = (event) => {
decoded = decoded
.then(async () => {
const { nodes } = JSON.parse(await frameText(event.data))
// 连接关闭之后才解完的帧丢掉
if (socket.readyState !== WebSocket.OPEN) return
// ...
})
.catch((e) => console.warn(e))
}ts默认主题的 src/lib/api.ts 也是这样处理的,另外只有解开的帧才重置它的断流计时:一直收到解不开的帧,同样当作断流去重连。
同时在线的上限
匿名访客的 /api/ws 同时最多 1000 条,超出的握手回 503,登录会话的推送不计入。浏览器读不到握手失败的回复内容,页面里只会看到连接出错。
收到 503 的页面应退回轮询 /api/nodes(官方主题每 5 秒一次),隔一段时间再试 WebSocket。只在断开后重连、没有轮询兜底的主题,在满额时会一直停在旧数据上。
到期天数
/api/nodes 和 /api/ws 推送的快照里,每个节点带一个 expires_in:按 hub 的日期算的剩余天数,0 是今天到期,负数是已过期的天数,没有到期日为 null。
显示「N 天后到期」「已过期」用它,不要拿 expires_at 按浏览器的时钟自己算。hub 按自己所在时区的日期给在线节点顺延到期日;访客在别的时区时,自己算会让在线节点在顺延之前显示几个小时的「已过期」。
离线时长
每个节点还带一个 last_seen_ago:按 hub 的时钟算的、距最后一次上报的秒数,从未上报过为 null。
节点离线(online 为 false)时,显示「离线 N 分」用它,不要拿 last_seen 去减浏览器的时钟。访客的时钟不准时(双系统在东八区常见快或慢 8 小时),自己算会把刚离线的节点显示成离线 8 小时,或者算出负数。
在线节点也带这个值。刚重连、还没上报的节点 online 为 true,值是断开前那次上报至今的秒数,所以离线时长只在 online 为 false 时显示。
价格与付款周期
currency 是货币代码,交给 Intl.NumberFormat 显示。hub 只检查它是三个大写字母,不核对代码是否真的存在,Intl 遇到不认识的代码会把代码本身当作符号显示。
// 地区写死 zh-CN:显示不随访客的浏览器语言变,
// 美元、港币写作 US$、HK$,日元写作 JP¥,不和人民币的 ¥ 混
function money(amount: number, currency: string): string {
try {
return new Intl.NumberFormat("zh-CN", {
style: "currency",
currency,
// 最多两位小数,与价格的填写精度一致,日元的小数不会被取整
maximumFractionDigits: 2,
}).format(amount)
} catch {
// 旧版 hub 存下的值,可能不是三个字母
return `${currency} ${amount.toFixed(2)}`
}
}tsbilling_cycle 是付款周期:
| 值 | 含义 |
|---|---|
monthly quarterly semiannual yearly biennial triennial | 1、3、6、12、24、36 个月 |
<n>m | 其余长度,n 是月数,1–1200,比如 60m 是五年 |
once | 一次性,不续期 |
有名字的长度只会以名字出现,不会出现 12m。
// 月数;once 是 0,不认识的是 NaN
function months(cycle: string): number {
const named: Record<string, number> = {
monthly: 1, quarterly: 3, semiannual: 6,
yearly: 12, biennial: 24, triennial: 36,
}
if (cycle === "once") return 0
return named[cycle] ?? Number(/^(\d+)m$/.exec(cycle)?.[1])
}ts节点分组
/api/nodes 和 /api/ws 推送的快照里,每个节点带一个 group:站长在面板上设的分组名,公开可读,空字符串表示未分组。
// 按节点顺序收集用到的分组;旧 hub 没有 group 字段
const groups = [...new Set(nodes.map((n) => n.group ?? "").filter(Boolean))]ts- 分组按节点顺序排,不按名字排。站长在面板上拖动节点来排分组,每个分组第一次出现的位置就是它的位置
- 一个分组都没有时,页面和没有分组功能时一样。只有部分节点有分组时,其余节点要有「未分组」这样的去处,不能藏起来
- 分组名是任意文本,最多 13 个字,可能叫
*、all、none,也可能就叫「全部」「未分组」。「全部」「未分组」这类标签的取值不要和分组名混在同一个字符串空间里,比如用null表示全部 - 分组可能有几十个。横排的标签要能滚动或换行
- 按分组切换时,汇总数字(在线数、流量、网速)跟着这一组算,不要一半跟着分组、一半是全站
公开备注
每个节点带一个 public_remark:站长在面板上写给访客看的一行说明,最多 100 字,不含换行,空字符串表示没有。按纯文本渲染。
站长的私有备注是另一个 key remark,访客拿不到,见下文匿名拿不到什么。
主题设置
公告、布局、显示哪些区块这类整个站点共用的选项,在 theme.json 的 config 里声明。面板主题页的卡片上随之出现设置按钮,按声明画出表单;站长保存后,值存在 hub 的数据库里,主题运行时读取。
这是站点级设置唯一的存放处,下面两种做法都不要用:
- 存进
localStorage:只在站长自己的浏览器里生效,访客和站长的其它设备都看不到 - 让站长改
dist/里的文件:更新、重装主题都是整个目录替换,改过的文件随之消失
某位访客自己的偏好(深浅色、排序方式)不属于站点设置,仍然放 localStorage。
声明
下面只列出 config,其余六个字段照常要写:
{
"config": [
{ "type": "title", "label": "首页" },
{ "key": "notice", "type": "text", "label": "公告",
"default": "", "help": "显示在页面顶部,留空不显示" },
{ "key": "layout", "type": "select", "label": "布局",
"default": "grid",
"options": [
{ "value": "grid", "label": "卡片" },
{ "value": "table", "label": "表格" }
] },
{ "key": "show_map", "type": "boolean", "label": "显示地图",
"default": true },
{ "key": "columns", "type": "number", "label": "每行卡片数",
"default": 3, "min": 1, "max": 6 }
]
}json| 字段 | 必需 | 含义 |
|---|---|---|
key | 是 | 读取时用的名字,同一个主题里不能重复 |
type | 是 | string 单行文本、text 多行文本、number 数字、boolean 开关、select 下拉 |
default | 是 | 默认值,类型要和 type 对得上;select 的默认值必须是某个选项的 value |
label | 否 | 表单上显示的名称,字符串,不写就显示 key |
help | 否 | 表单上的一行说明,字符串 |
options | select 必需 | [{ "value": "...", "label": "..." }],value 是非空字符串,label 是字符串、不写就显示 value |
min、max | 否 | number 的取值范围,面板按它拦下越界的输入 |
{ "type": "title", "label": "..." } 是分组标题:不存值,它后面的设置项归入这一组,第一个标题之前的归入「通用」。设置项超过十来个时写分组标题,面板会按组分栏显示。
面板逐项检查,不合格的那一项不显示,其余照常。改完 theme.json 装到 hub 上打开设置看一眼,缺了哪一项,就是哪一项写错了。
读取
GET /api/themes/{short}/config返回站长改过的项,没改过的不在里面:
{ "notice": "今晚 23:00 维护", "show_map": false }json- 从没保存过:
{} - 公开页关闭时,未登录的请求得到 401,条件和
/api/nodes一样 - 不要求主题已安装,任何
short都能读
请求失败一律按默认值渲染,不要报错,也不要为此显示提示。
hub 只存改过的项,默认值由主题自己补。这样主题作者在新版本里改了某个默认值,没动过这一项的站点会跟着变,改过的站点保持站长的选择。
示例代码
默认值只在 theme.json 里写一遍,构建时导入(Vite 直接支持;TypeScript 需要 resolveJsonModule,moduleResolution: "bundler" 下默认开启):
// src/lib/config.ts
import manifest from "../../theme.json"
type Field = {
key: string
type: string
default: unknown
options?: { value: string }[]
min?: number
max?: number
}
// 和面板同一套取值检查。保存的值可能来自这个主题的旧版本,
// 与当前声明对不上的,当作没有保存过
function fits(field: Field, value: unknown): boolean {
switch (field.type) {
case "boolean":
return typeof value === "boolean"
case "number":
return typeof value === "number" && Number.isFinite(value)
&& value >= (field.min ?? -Infinity) && value <= (field.max ?? Infinity)
case "select":
return !!field.options?.some((option) => option.value === value)
default:
return typeof value === "string"
}
}
// 分组标题(type 为 title)不存值
export const fields = (manifest.config as Field[]).filter((f) => f.type !== "title")
export async function loadConfig(): Promise<Record<string, unknown>> {
let saved: Record<string, unknown> = {}
try {
const res = await fetch(`/api/themes/${manifest.short}/config`)
if (res.ok) saved = await res.json()
} catch {
// 断网同样按默认值
}
const pick = (f: Field) => (fits(f, saved[f.key]) ? saved[f.key] : f.default)
return Object.fromEntries(fields.map((f) => [f.key, pick(f)]))
}ts页面启动时和 /api/me、/api/nodes 并行请求,不要排在它们后面。
主题还想让访客在自己的浏览器里再调一层(比如深浅色)时,优先级从低到高是:theme.json 默认值、hub 里的站点设置、这位访客的 localStorage。
主题自带的设置界面
配色、背景这类要边调边看的设置,主题可以在公开页上提供自己的设置界面,站长登录后(/api/me 的
authed 为 true)直接保存到 hub:
// 接在上面的 src/lib/config.ts 里。
// values 是设置界面里当前的值,每个 key 一项
export async function saveConfig(values: Record<string, unknown>): Promise<void> {
const url = `/api/themes/${manifest.short}/config`
// 先读 hub 里原始的那份,不是 loadConfig() 合并过默认值的结果
const read = await fetch(url)
if (!read.ok) throw new Error(await read.text())
const next: Record<string, unknown> = await read.json()
// 只改声明过的项,其余 key 原样留下;等于默认值的删掉
for (const f of fields) {
if (values[f.key] === f.default) delete next[f.key]
else next[f.key] = values[f.key]
}
// 站长登录时才有权限。失败要让站长看到,不能当作已保存
const res = await fetch(url, {
method: "PUT",
headers: { "content-type": "application/json" },
body: JSON.stringify(next),
})
if (!res.ok) throw new Error(await res.text())
}tsbody 是整个设置对象,会替换已保存的那份,不超过 64 KiB。主题要已装在这个 hub 上、站长已登录,否则分别得到
400、401。面板上的设置按钮始终都在,两边改的是同一份数据,theme.json 里的声明仍然要写全。
约定
key发布后不改名。改名等于丢掉站长已经保存的值;含义或类型变了就换一个新key- 设置是公开的。所有访客都能读到,不要设计让站长填密钥、token 或内网地址的字段
- 设置管显示,不管权限。主题里「不显示价格」只是不画,接口里照样有;要对访客真正隐藏的数据,得由 hub 不输出。见下文匿名拿不到什么
- 原始 HTML 不进页面。文本按纯文本渲染:React 里直接写
{notice},原生 DOM 用textContent。公告这类要排版的,可以按 Markdown 渲染,但渲染器必须转义其中的 HTML,链接只放行http:、https:、mailto:。不要把设置值交给innerHTML、dangerouslySetInnerHTML或v-html。节点自己上报的字符串(os、kernel、arch、virt、cpu_name、agent_version)同样如此:它们出自一台没人验证过的机器
匿名拿不到什么
匿名访问 GET /api/nodes 只返回公开的节点,响应里没有地址(ip、ipv4、ipv6、ipv4_pin、ipv6_pin、ipv4_auto、ipv6_auto、addresses)、hostname、remark、token 这些 key:不是空字符串,而是根本不存在。国家只给一个 country,手填的优先。
指标部分走白名单:内核原始计数器 net_rx_total、net_tx_total 和 boot_id 谁都拿不到,iface 和地址一样只在登录后返回。metrics 里的 total_rx、total_tx、month_rx、month_tx 由 hub 填入,与顶层同名字段相同。
站长登录后,/api/nodes 和 /api/ws 返回完整视图:admin 为 true,包括不公开的节点和上面这些 key,token 除外:节点凭证不和 agent 上报的内容放在同一份回复里,谁都只能从面板的安装弹窗看到。请求同源,浏览器自动带上登录凭据,主题不用额外处理,就能在站长登录时显示 remark 这类私有信息。
字段定义以 hub 的源码为准。写主题时按「这个 key 可能不存在」处理。
三种要处理的状态
| 状态 | 长什么样 |
|---|---|
| 离线节点 | metrics: null |
| 刚连上还没上报 | online: true + metrics: null |
| 坏数据 | 字段缺失或类型不对 |
第二种最容易漏。默认主题在渲染入口再检查一次指标是否完整,缺失或格式不对时显示「不可用」,不让一个节点的坏数据导致整个页面白屏。
接口出错时
hub 的错误回复一律是一行中文纯文本(Content-Type: text/plain),可以原样显示给访客,例如公开页关闭时的「需要登录后查看」、历史查询过多时的「查询历史的请求太多,稍后再试」。
不是 text/plain 的错误回复来自 hub 前面的反代或 CDN,比如 nginx 的 502 页面、Cloudflare 的拦截页。它们的内容不要显示出来,按状态码给一句说明。请求没发出去(断网),或者返回 200 却不是 JSON(被代理换成了网页),也按同样的办法处理。默认主题 src/lib/api.ts 里的 api() 就是这么写的,可以直接照抄。
页面切回前台
手机会挂起切到后台的页面,并悄悄掐断它的连接。切回来时,WebSocket 可能仍显示已连接却收不到数据;挂起前发出的请求会失败,单次失败就报错的主题会闪一下错误提示。处理办法是监听 visibilitychange:页面隐藏时关闭 WebSocket、停掉轮询,挂起前发出的请求结果一律丢弃;回到前台时立即请求一次 /api/nodes,并重新连接 /api/ws。默认主题 src/lib/api.ts
里的 useNodes() 就是这么写的。
路由
未知路径回落到主题自己的 dist/index.html,客户端路由因此可用。/admin、/api、/install.sh、/agent/* 由 hub 处理,主题覆盖不了。
站长在设置页上传了站点图标时,/favicon.svg、/favicon.ico 和 /apple-touch-icon.png 也由 hub 回答,主题自带的同名文件不再生效。页面上要显示站点图标(比如页头的 logo),就引用 /favicon.svg,不要内联或换别的文件名,否则站长换了图标这里不跟着变。index.html 里要原样写 href="/favicon.svg":hub 返回页面时会给它加上版本号,图标一换网址就变,浏览器才会换掉标签页上记住的旧图标。
iOS 的书签和「添加到主屏幕」不用 SVG 图标,只认 apple-touch-icon。主题要带一张 180×180 的 PNG,放在 dist/ 根目录(Vite 项目放 public/),再在 index.html 里声明:
<!-- 固定路径,不要打包进 assets/:带哈希的文件名 hub 替换不了 -->
<link rel="apple-touch-icon" href="/apple-touch-icon.png" />htmliOS 会把透明的地方填成黑色,这张图要用不透明的底色。
默认主题用 /node/{id} 做详情页。前面有按路径放行的反代或 WAF 时,要把主题的路由前缀加进去:从列表点进去只是前端路由切换,刷新详情页才会真正请求这个路径,症状是「点进去正常,一刷新就被拦」。写主题时在 README 里列出自己的路由。
旧版 hub
上面写的是当前版本。要兼容旧版 hub 时,按下表处理:
| 字段或行为 | 没有的版本 | 怎么处理 |
|---|---|---|
expires_in | 1.2.0 及更早 | 按 expires_at 用浏览器时钟自己算,见下方代码 |
group | 1.2.0 及更早 | 按空字符串 |
GET /api/themes/{short}/config | 1.2.0 及更早 | 得到 404,按默认值 |
net_rx_max、net_tx_max | 1.3.0 及更早 | 只画平均值 |
ping 按监控顺序排列 | 1.3.0 及更早 | 按时间先后排,监控之间谁先谁后不固定 |
billing_cycle 的 <n>m | 1.3.0 及更早 | 只有带名字的七个值 |
| 中文错误回复 | 1.3.0 及更早 | 是英文 |
| 安装时校验 gzip 尾部 | 1.3.0 及更早 | 不校验,所以以前装得上的不完整包,升级 hub 后会被拒绝 |
cpu_max、minutes、step | 1.3.1 及更早 | 没有 |
metrics 里的 swap_used、tcp、udp、procs | 1.4.0 及更早 | 没有,这几个只在实时指标里 |
history_days | 1.3.1 及更早 | 按 7 天处理:那些版本匿名最多只给 168 小时 |
public_remark | 1.3.1 及更早 | 按空字符串 |
currency 的格式检查 | 1.3.1 及更早 | 存下的值可能不是三个字母,Intl 会抛错,要兜住 |
| 站点图标 | 1.3.2 及更早 | /favicon.svg、/apple-touch-icon.png 总是主题自带的那个 |
/api/ws?gzip | 1.3.2 及更早 | 忽略参数,推文本帧 |
last_seen_ago | 1.3.2 及更早 | 拿 last_seen 和浏览器时钟自己算,last_seen 为 0 是从未上报;null 同样是从未上报,和没有这个 key 分开判断 |
expires_in 为 null 表示没有到期日,要和「没有这个 key」分开判断:
// 旧 hub 没有 expires_in,才按浏览器时钟自己算;daysUntil 由主题自己实现
const days = node.expires_in !== undefined
? node.expires_in
: daysUntil(node.expires_at)ts本地开发
主题只读公开数据,开发服务器可以直接拿一个现成的 hub 当数据源,只要它开着公开状态页(设置页的「开放公开状态页」):
# 在主题目录里:Vite 把 /api 和 WebSocket 代理到这个 hub
MONITOR_HUB=https://hub.example.com npm run devbash默认主题的 vite.config.ts 读的就是这个变量,自己写主题照抄即可;不设时代理到 http://127.0.0.1:9911。
在本机起一个 hub
手上没有 hub,或者想要一份能随便改的数据,就在本机起一个,自己添加节点:
# --site 只是为了让面板允许添加节点,任意一个 https 域名即可
monitor-hub --listen 127.0.0.1:9911 --db /tmp/monitor.db \
--site https://hub.example.com
# 另开一个终端,在主题目录里:不设 MONITOR_HUB,代理到 127.0.0.1:9911
npm run devbash打开 http://127.0.0.1:9911/admin,用 hub 启动时打印的应急密码登录,添加节点后点它的安装按钮。命令里的地址是上面的占位域名,用不了,只复制 --token 后面的值,在本机直接运行 agent:
# agent 连回环地址允许明文;二进制从 agent 仓库的 release 下载
monitor-agent --server http://127.0.0.1:9911 --token <token>bashagent 只有 Linux 版。在 macOS 上开发时节点会一直显示离线,要看实时数据,用上面代理到现成 hub 的方式。
安装与切换
在主题页选一个即可切换,不用重启;选中的主题缺失或损坏时自动回落到内置默认主题。声明了设置的主题,卡片上多一个设置按钮,保存后公开页刷新即生效。设置存在 hub 的数据库里,更新、重装、删掉再装回主题都不会丢,数据库备份里也有。
已收录的主题可以在主题站在线预览,复制安装地址后按下面第一种方式安装。
安装有三种方式:
- 在主题页填主题的 GitHub 仓库地址,点「从 GitHub 安装」,hub 下载它最新 release 里的
theme.tar.gz。不用先把包下到自己电脑上,也就不会因为没下载完而装不上 - 在主题页上传下载好的
theme.tar.gz。要下 release 里名为theme.tar.gz的文件,不是 Source code - 把主题目录直接放进 hub 的
--themes目录(一键脚本部署是/opt/monitor/data/themes/)
前两种都是同名主题整体替换。hub 访问不了 GitHub 时,「从 GitHub 安装」和下面的更新都需要在设置页填 GitHub 代理,见hub 连不上 GitHub;能访问时不用填。
卡片上的「从 GitHub 更新」从 theme.json 里 url 指向的 GitHub 仓库取最新 release,tag 与已装版本相同时不下载。
内置默认主题同样可以就地更新,不用升级 hub:更新会把新版装进 themes/default/,此后使用磁盘上的这份,卡片上的「内置」标记随之消失;删掉它就回到二进制里的那份。二进制里的默认主题删不掉也改不了,磁盘上的主题出问题时总能回落到它。
安装的主题是在访客浏览器里运行的第三方代码,和 hub 同源。安装时的检查只防止写到目录外和占满磁盘,不检查里面的 JS。只装信得过的来源。
参考实现
monitor-theme-default,React + Vite +
shadcn/ui,黑白配色。它既是内置默认主题,也是第三方主题的范本:hub 嵌入的和装进 themes/ 的是同一个
theme.tar.gz。
收录到主题站
主题做好、发布 release 后,向 monitor-probe/themes 提一个 PR,在
themes.txt 末尾加一行仓库地址。名称、截图等信息都从 release 里的 theme.tar.gz 读取;收录要求和检查方式见那个仓库的 README。