A topology-first network operations theme for Komari.
Transit 是一个面向多节点、多线路和跨境链路监控的 Komari 社区主题。它把“入口 → 线路机 → 可选跳板 → 落地机”的链路拓扑、三网 Ping、实时资源、异常告警和资产信息放进同一套紧凑的毛玻璃界面,并提供可视化拓扑管理器。
- 当前稳定版:v1.4.5
- 安装包:只从 GitHub Releases 下载
komari-theme-Transit-build-*.zip - 项目定位:主题安装包本身不修改 Komari 数据库、Agent 或系统账户;可选的回程伴生组件仅在管理员明确安装并启用后,才增加受控路由或安装节点助手
- 默认监测:新配置以北京电信、联通、移动为主;上海、广东和自定义入口继续作为兼容与可选配置,不会替用户自动创建或迁移线上任务
- 拓扑优先:一眼看清用户入口、线路机、可选跳板、落地机以及每一段链路的延迟和丢包。
- 傻瓜式配置:选择内置入口,或填写自定义名称和 IP/域名探测目标,再选择线路机、可选跳板与落地机;保存时自动创建或复用每一段 Ping 任务。
- 指标不串线:线路、链路段和指标按位置一一对应,空组不会让后续延迟错配到其他线路。
- 精确任务绑定:拓扑按完整 Ping 任务名称匹配,不会聚合名称相似的备用任务。
- 线路洞察:用现有 Ping 样本识别延迟/丢包组合变化、北京时间日内规律、双向探测和显著基线变化。
- 三网质量:节点卡片直接展示联通、电信、移动的 Ping、ICMP 丢包率和近期采样,不用复杂状态文字替代原始指标。
- 智能观测面板:不同节点可分别显示三网、自定义 Ping、系统、流量、存储、GPU 或精简信息,并支持自动选择。
- 全高状态轨:节点卡左侧用贯穿整张卡片的绿、黄、红状态轨区分正常、维护或告警、严重异常或离线。
- 统一采样交互:鼠标悬停显示时间、延迟与丢包;移动端可点击固定浮窗。
- 运维视角:提供异常摘要、线路可靠性、维护状态、事件时间线、健康统计和审计日志。
- 资产视角:同时展示价格、剩余价值、到期日、流量配额和厂商信息。
- 原生服务器列表:登录后可查看实时服务器清单、筛选与排序,并直接保存首页顺序;其余配置管理仍沿用 Komari 自带后台。
- 本机壁纸:可在顶部上传当前浏览器专用的 JPG、PNG、WebP 或 AVIF 壁纸,并切换玻璃化、模糊和高清效果。
- 隐私默认关闭:公网信息查询和 Transit 访客审计均为明确选择加入,默认不会触发。
- 首页先展示资源总览,再展示紧凑线路拓扑;桌面端节点卡默认一行最多四张,并保留可读的毛玻璃层次。
- 节点卡三网区域聚焦
Ping + 丢包率。ICMP 才称为丢包率,TCP/HTTP 任务只称连接失败率,避免把端口探测误解成真实线路丢包。 - 拓扑保留已绑定任务的协议、端口和目标,不因失败把 TCP 强制改回 ICMP;新任务先采集 30 个样本再参与告警和评分,避免少量失败被放大成稳定结论。
- 北京三网内置候选目标已经更新;它们只用于新建、验证或重建任务,不代表线上任务当前使用的目标,也不会在升级时自动改写 Komari 数据库。
- 配置历史、拓扑写入记录和监测操作记录均有容量与结构保护;Markdown、外部链接、导出和伴生助手继续使用既有安全边界。
| 区域 | 能力 |
|---|---|
| 线路状态 | 多线路拓扑、逐段实时/静态/待探测状态、历史详情、健康评分、24 小时曲线与基线变化洞察 |
| 拓扑管理 | 内置/自定义入口、线路机、可选跳板与落地机;保留已绑定 ICMP/TCP 协议与目标 |
| 回程线路 | 自动检测三网回程走哪条骨干网(CN2GIA/163/9929/CMIN2 等),固定能力助手无需开放远控 |
| 节点卡片 | CPU、内存、硬盘、上下行、累计流量、到期、价格和按节点配置的智能观测面板 |
| 告警 | 离线、高负载、流量预警、即将到期、Ping 丢包、维护状态和异常时间线 |
| 首页工具 | 服务器列表、节点对比、厂商性价比、健康摘要、快照导出、网络信息和核心审计日志 |
| 节点详情 | 自定义概览卡、完整负载图、Ping 延迟/丢包历史、GPU 与磁盘耗尽预测 |
| 显示 | 亮色/暗色/北京时间自动模式、本机壁纸与三种效果、四档卡片密度和移动端布局 |
| 暗色总览 | 亮色总览 |
|---|---|
![]() |
![]() |
登录后点击“线路状态”右上角的“管理”,选好入口和线路机即可添加线路;跳板和落地机按需选择。入口默认使用北京三网,也可选兼容预设,或填写任意名称与 IP/域名探测目标。添加会自动创建或复用每一段任务、保存到 Komari 托管主题设置,并同步到所有设备。
以上截图由仓库内的确定性 Komari 夹具生成,用于展示当前布局和响应式行为;其中节点名、金额、延迟与丢包均为测试数据,不代表真实线路。
- 前往 Releases 下载最新的
komari-theme-Transit-build-*.zip。 - 登录 Komari 管理后台,在主题管理中上传这个 zip;不要上传 GitHub 自动生成的源码压缩包。
- 启用短名称为
Transit的主题。 - 打开主题设置,选择主题模式、节点卡密度、默认观测面板和三网地区。
- 新安装不会预置任何真实节点;返回首页,按“还没有配置线路”的引导添加第一条线路。
升级已有 Transit 时,Komari 会继续使用同一短名称下保存的托管主题设置。建议升级前保留上一版 Release,并在更新后强制刷新浏览器。
发布 zip 的根目录固定为:
komari-theme.json
preview.png
dist/
Transit 使用独立短名称 Transit,不会覆盖已有的 PandaOps、Glassmorphism 或其他主题目录。
配置一条线路至少需要入口和线路机;跳板、落地机都按需选择。选择跳板时必须同时选择落地机。
入口是线路图上的用户侧标签。默认使用北京三网;上海、广州三网作为兼容预设继续保留,也可以选择“自定义入口”,填写“湖北电信”这样的名称和一个裸 IP/域名探测目标。入口到线路机的任务由线路机执行,后续线路机 → 跳板、跳板 → 落地机任务按目标节点地址逐段自动复用或创建,并且只分配给该段的来源节点。
入口 → 线路机 → [跳板] → [落地机]
| 字段 | 必选 | 说明 |
|---|---|---|
| 入口 | 是 | 默认北京三网,可选兼容预设或自定义名称与 IP/域名目标 |
| 线路机 | 是 | 执行入口探测、承担第一段节点间探测的服务器 |
| 跳板 | 否 | 额外中转节点;选择后还必须选择落地机 |
| 落地机 | 否 | 最终出口服务器;不选就只保存“入口 → 线路机” |
登录后打开拓扑管理器,选好后点“添加线路”。跳板和落地机都不选会得到两节点线路;只选落地机会得到传统三节点线路;同时选择跳板和落地机会得到四节点线路。已有线路直接改下拉框即可,都会立即保存:
- 第 1 段优先保留线路机上已绑定的入口探测任务;站里已有同名任务但尚未分配此节点时,会加入该任务的节点列表而不是重复创建;都没有才会规划新任务。切换候选须在健康中心验证并确认。此处测的是「线路机主动探测该地址」,方向和「该运营商用户访问线路机」相反。
- 后续各段按来源 UUID 和落地 IP 核对绑定,保留已绑定任务的协议、端口与目标,即使持续失败也不静默切换;缺失或地址已变化时按既有能力阶梯重新规划。ICMP 显示丢包率,TCP 显示连接失败率。
- 线路机、跳板和落地机的 UUID 会随线路一起保存。在 Komari 里给节点改名后,任何浏览器打开首页都能按 UUID 认回来并把线路自动改成新名字,不需要重新选节点。
- 打开管理器时会按当前节点自动校正旧线路;入口显示为北京电信时,不会再继续使用别的第 1 段任务。
- 默认落地机会避开已经配过的线路;添加后自动切到下一台。
- 相同线路机、跳板和落地机组合不会重复添加,只会更新并保存已有线路。
- 实时数据由线路机发出 Ping,图画方向不等于入口网络正向打过来。
数据方向必须按采集端理解。 Komari Ping 样本由线路机发出。视觉上把线路画成“北京电信 → JP”并不会自动获得北京电信到 JP 的正向路径。Transit 会在实时采样和线路详情中显示真实的探测来源和任务名称。
- 已添加的线路会按实际配置显示入口、线路机、可选跳板和落地机;每一段都可点击查看精确任务、探测来源和历史。改节点、调整顺序或删除都会立即保存。
- 打开管理器时若校正出旧配置问题,也会自动保存。
- “恢复已保存配置”重新载入线上配置并再次校正。
- “保存并应用”只在自动保存被拦住时作为补救。
只有已登录管理员可以保存。公开访客可以查看允许公开的线路状态,但不能修改主题配置。
每条拓扑线路左侧的入口下拉框支持:
- 北京:电信、联通、移动
- 上海:电信、联通、移动
- 广州:电信、联通、移动
- 自定义入口:自行填写显示名称和裸 IP/域名探测目标
切换后主题会为入口段匹配对应 Ping 任务;线路机上没有匹配任务时会自动新建。广州探测点在任务匹配和创建时都同时接受“广州电信/联通/移动”(显示名)和“广东电信/联通/移动”(惯用任务名)两种命名。
自定义入口保存后会自动创建稳定命名的专用任务;只修改显示名称继续复用原任务,修改探测目标则创建新绑定,并仅在能证明旧任务由本会话创建时安全清理。入口在内置预设与自定义值之间切换时,编辑器会保留原自定义名称、目标和绑定,切回来无需重填。
已登录管理员打开首页时,主题每分钟检查入口(第 1 段)和后续每一段绑定;拓扑管理对话框打开期间也使用同一套逻辑复检:
- 保留明确绑定任务的协议和端口。失败本身不触发换协议或换目标;管理员可在健康中心验证候选并确认迁移。只有未绑定、任务缺失或来源/落地地址变化时才重新规划;
- 新建对应的 Ping 任务并写回拓扑绑定——新任务先建好、确认可用后才清理旧的,不依赖旧任务先删除成功。入口段如果站里已经有同名任务、只是没把这台线路机算进去,会改成把线路机加进那个任务的节点列表(这是唯一一处会修改操作者已有任务的地方,只加节点,不改名称、类型和目标);
- 仅清理有完整本会话创建快照、且回查未被修改的自建任务。快照存于本标签页 sessionStorage;仅有主题配置中的任务 ID 不能证明所有权。手建任务、仅追加过节点的任务以及无法确认清理结果的资源保留并提示人工核对。
这是主题里两处无人值守就会写后端的逻辑之一(另一处是三网回程线路的自动检测,那一处还会在节点上执行命令)。写入前会校验登录权限、抢跨标签页保存锁并复核服务端快照;保存失败时会回滚本轮新建的任务。每一次写入(创建、清理、回滚)都会记进拓扑管理器底部的「本次会话的后端写入记录」,标明时间、是自动修复还是手动操作、以及成功与否——出问题时这是唯一能说清主题到底做过什么的地方。记录只存在浏览器本会话里,不写进主题配置。如果你希望所有写操作都由人工触发,把这个开关关掉即可——拓扑管理对话框里的手动操作不受影响。
- 节点实时状态按主题设置的更新间隔轮询,节点名称、地区等元数据使用独立的低频刷新。
- 元数据请求失败时,主题保留上一份节点信息,并继续应用本轮成功返回的实时状态。
- 实时状态连续失败时会指数退避,最长 60 秒;连接恢复后立即恢复正常间隔。
- Ping 数据的新鲜度按每个任务的真实采样时间判断,不是按「上次请求成功」——接口重复返回同一批旧记录不会被当成刷新成功。分两级:超过 10 分钟没有新样本,保留最后一次数据并在界面标出更新时间;超过 30 分钟才判定过期,当前指标改用备用基线,过期历史不会继续显示为实时数据。
- 新建或重建的拓扑任务会立即展示实际 Ping、丢包和采样进度,但累计到 30 个样本前不参与线路告警、评分和推荐;百分比仍是真实短窗口,只是不会被误当成稳定结论。
- 只是「延迟」的数据仍然照常显示,但不会触发新的线路告警——数据本身不够新时,不应该据此判断链路刚刚变差。
- 页面从后台标签页恢复时会立即刷新,并留一分钟宽限,不会因为切回来的瞬间还没拿到数据就先报一次过期。
- 本地缓存不会给旧数据自动续期:断网期间缓存到期即失效,不会一直显示一份看起来很新的旧数据。
推荐使用可视化管理器。需要迁移、排障或批量维护时,也可以直接编辑主题设置里的拓扑数据。
拓扑的真值是 topologyConfig,JSON 格式:
{
"version": 1,
"routes": [
{
"nodes": [
{
"name": "湖北电信",
"region": "CN",
"role": "入口",
"probeTarget": "probe.example.com"
},
{
"name": "Relay-JP",
"region": "JP",
"role": "线路机",
"uuid": "线路机的 Komari UUID"
},
{
"name": "Jumper-JP",
"region": "JP",
"role": "跳板",
"uuid": "跳板的 Komari UUID"
},
{
"name": "Exit-US",
"region": "US",
"role": "落地机",
"uuid": "落地机的 Komari UUID"
}
],
"metrics": [
{
"probeMode": "live",
"live": true,
"source": "Relay-JP",
"task": "Transit-entry-custom-xxx"
},
{
"probeMode": "live",
"live": true,
"source": "Relay-JP",
"task": "Transit-Relay-JP-to-Jumper-JP"
},
{
"probeMode": "live",
"live": true,
"source": "Jumper-JP",
"task": "Transit-Jumper-JP-to-Exit-US",
"fallbackLatency": 84,
"fallbackLoss": 0
}
]
}
]
}nodes最多四个,第一个是入口标签(没有uuid,自定义入口可带probeTarget);线路机、可选跳板和落地机带uuid,节点改名后仍能认回来。只有入口和线路机时写两个节点即可。metrics与nodes的段一一对应:四节点三段、三节点两段、两节点一段。probeMode明确区分三种状态:static只展示静态基线,永远不会创建或修复任务;auto表示等待主题自动规划任务;live表示已经绑定实时任务。这样打开拓扑管理器时,明确设置成静态的段不会被误改成实时探测。- 静态基线写
{"probeMode":"static","fallbackLatency":51,"fallbackLoss":0};待自动规划写{"probeMode":"auto"};实时绑定写"probeMode":"live"、"live":true、source(探测来源节点名)和task(Ping 任务名)。省略备用值表示没有该值。 - 老版本没有
probeMode的配置继续兼容:live:true按实时绑定读取,live:false或省略live按静态基线读取,避免升级后仅仅打开管理器就意外创建任务。 - 虽然 JSON 自身没有转义问题,但当前版本仍会双写旧格式以便降级安装;节点名称、地区和角色不能包含
|或;,实时指标的来源和任务名不能包含@、;或||。停止写入旧格式后才会放宽这些限制。
topologyRoute和topologyMetrics是兼容字段,不要手工编辑。 它们是旧的分隔符格式,主题仍会写入同一份内容,好让降级安装不会看到空拓扑;但读取时以topologyConfig优先,改了旧字段会在下次保存时被覆盖。旧字段会在确认无人回滚后的某个版本停写。只有
topologyConfig为空的老站点才会回退去解析旧字段——那时节点写作名称|地区|角色|UUID(UUID 可省略)、多条线路用||分隔,实时指标写作live@来源节点@任务名@备用延迟@备用丢包,静态指标写作延迟,丢包,-表示没有备用值。这条路径只为迁移存在,新配置不要再按它写。
节点卡片默认显示北京联通、电信、移动,也可以切换到上海、广东或全部地区。每一行只保留最直接的网络指标:
- Ping 延迟
- ICMP 丢包率
- 最近一组采样格
- 按延迟与丢包计算的颜色
桌面端将鼠标放到采样格上即可查看时间、延迟和丢包;点击可以固定浮窗。移动端直接点击采样格查看,点击空白处关闭。拓扑、节点卡和详情页使用同一套采样交互。
这里的“丢包率”只用于 ICMP Ping,表示采样窗口内没有收到回应的 ICMP 包比例。TCP 或 HTTP 任务衡量的是连接/请求能否成功,因此界面会写“连接失败率”,不会把它叫作丢包率。无论哪一种指标,都只代表 Komari 探测任务的样本,不等同于业务连接、代理端口或用户侧流量的真实丢包。
v1.4.5 起拓扑尊重已绑定的 ICMP/TCP 任务,不再自动迁回 ICMP。想统一 TCP 时,需要在 Komari 配置并验证对应端口,而不是仅把丢包率标签改名;新旧目标应使用不同任务 ID,避免混入旧历史。内置北京 TCP 候选见监测目标健康说明,升级不会批量替换现有任务。
同一个三网 Ping 任务偶尔可能因为公共目标拒绝连接、限流或短暂不可达,让很多节点在同一分钟一起失败。Transit 会把“同一时间桶内至少 5 台、且不少于 60% 已观测节点同步失败”标记为“目标异常”:卡片仍保留原始丢包率,不隐藏真实采样,但这些同步失败不再触发某一台节点的丢包告警或改变节点状态轨。只有 Metric Store 一次查询覆盖到足够多节点时才能作此判断;单节点详情和旧 records 回退仍按原始丢包展示。
管理员可在“监测目标健康”中查看当前任务、分配节点、近一小时成功率和同步异常,并用临时 canary 任务验证候选目标。验证与迁移都需要明确确认;升级主题不会自动替换现有 Ping 目标。完整规则见监测目标健康与安全迁移。
节点卡底部按卡片自身宽度响应,而不是只看浏览器宽度:宽卡片显示速度、累计流量和三网质量三列;中窄卡片让三网质量独占整行;极窄卡片使用单列。节点名最多两行,价格、到期日期、大流量和三网指标不会用省略号隐藏关键数据;未设置到期时也会保留一致的布局高度,不会让同排卡片参差。
三网 Ping 回答的是「这条回程现在快不快」,回程线路回答的是「它走的是哪条骨干网」——CN2GIA、163、9929、CMIN2 之类。两个合起来才够判断线路好坏:线路名不代表当下质量,当下质量也说明不了换没换线。
节点详情页会显示三条线路徽章;首页的普通节点卡使用紧凑徽章,Transit 运维节点卡则使用独立的「三网回程」面板,与网络概览并排、三网质量位于下一行。运维面板每行以运营商为左侧类别标签,经过短轨道连接到右侧的骨干线路判定,并按档次着色(精品/优质/普通);这条轨道表达的是数据对应关系,不冒充完整网络方向。鼠标悬停、键盘聚焦或触屏点击都可以查看真实探测方向、逐跳 ASN、判定依据和采集时间;点击路线本身不会误进入节点详情。没有采集数据时整块不渲染。
没有时间戳的手写或旧标签会显示「时间未知」并取消档次颜色,不会被暗示成当前结果;管理员打开首页后仍会把它列入待重测节点。
判定需要 traceroute 的逐跳信息,浏览器拿不到(没有原始套接字),Komari 的 Ping 任务也拿不到(只有 icmp/tcp/http)。traceroute 只能在节点上跑。
默认采集路径由两个小组件组成:Komari 服务端的 Transit Route Probe 伴生插件,以及每台节点上一次性安装的固定能力节点助手。助手复用本节点已有的 Komari Agent token,通过 HTTPS 主动轮询服务端;它不监听端口,也不需要开启 Komari 远程控制。服务端只能交给它一次性任务 ID 和 beijing / shanghai / guangzhou 三个内置城市之一,不能下发命令、目标 IP、Shell 片段或 traceroute 参数。
先从与主题相同版本的 GitHub Release 下载 transit-route-probe-plugin.zip,上传到 Komari 的「插件」页面并启用。开发者也可以在主题仓库自行生成同一个安装包:
bun run build:route-probe插件要求 Komari >=1.4.0,声明 node、allowRoutes 以及请求体大小、超时限制;不会申请系统 RPC、子进程执行、端口监听、HTML 注入、全盘文件或请求钩子权限。
然后在每台节点下载同一 GitHub Release 的两个脚本并安装。推荐使用 HTTPS 面板设置向导生成命令。下面的 v1.4.5 应替换为实际已发布且与插件一致的标签,不要长期跟随会变化的 main。下载在独占私有目录中进行,任一失败即中止,不会执行当前目录的同名旧文件;安装器交互式读取 Agent token,输入不会进入 shell 历史:
(
set -eu
umask 077
transit_release=v1.4.5
transit_install_dir=$(mktemp -d /tmp/transit-route-probe-install.XXXXXX) || exit 1
trap 'transit_install_status=$?; rm -f -- "$transit_install_dir/transit-route-probe-helper.sh" "$transit_install_dir/collect-return-route.sh"; rmdir -- "$transit_install_dir"; exit "$transit_install_status"' EXIT
cd "$transit_install_dir" || exit 1
curl -q --proto '=https' --proto-redir '=https' -fsSL "https://github.com/yyy622hhh/komari-theme-transit/releases/download/$transit_release/transit-route-probe-helper.sh" -o transit-route-probe-helper.sh || exit 1
curl -q --proto '=https' --proto-redir '=https' -fsSL "https://github.com/yyy622hhh/komari-theme-transit/releases/download/$transit_release/transit-collect-return-route.sh" -o collect-return-route.sh || exit 1
sudo bash "$transit_install_dir/transit-route-probe-helper.sh" install --endpoint https://status.example.com
)Important
https://status.example.com 只是占位示例。--endpoint 必须填写浏览器访问 Komari 面板的 HTTPS 根地址,例如 https://status.pandakiko.com;只包含协议、域名和可选端口,不要填写 /admin、其他路径、查询参数、账号或密码。更推荐直接使用 Transit 首页的设置向导:它会自动识别当前面板地址和已安装的 Transit 版本,生成包含两个脚本下载与安装步骤的完整命令,无需手工替换。
批量自动化可以改用只允许 root 读取的 --token-file。节点必须已有 curl、traceroute、timeout 和 systemd;安装器不会擅自安装系统软件。服务以独立的 transit-route-probe 用户运行,只保留 CAP_NET_RAW,并启用 NoNewPrivileges、只读系统目录、私有设备和网络地址族限制。查看状态使用 systemctl status transit-route-probe。
为兼容旧部署,伴生插件明确返回 404 时主题仍会退回原来的编译期固定 admin:exec 命令;已经接单后的插件错误绝不会再回退,避免同一节点同时跑两轮。希望彻底禁用远程执行时,保持所有 Komari Agent 的远程控制关闭即可,节点助手路径不受影响。
回程采集默认关闭。未开启时,主题不显示手动入口、不自动派发任务,也不会因为节点没有安装助手而产生批量失败提示;已有的回程结果仍会正常展示。旧版的 routeProbeAutoEnabled 不会自动迁移为开启——这项能力会在节点上主动测量网络,升级后仍需站长明确同意一次。
首页工具栏有一个安静的 配置回程检测 入口(仅管理员可见),点开前不探测、不报错。打开后会自动完成环境检查:
- 检查伴生插件是否已安装(
GET /health); - 检查每台境外节点的助手是否在线——只读花名册(
GET /roster),不创建任何任务,判断在线情况不会触发一次真实探测; - 自动统计并排除中国大陆节点。
缺助手的节点会按名称列出,点「复制安装命令」得到一段所有节点共用、不含 Agent token 的安装命令;命令在节点上执行后,transit-route-probe-helper.sh 会用 read -s 交互式提示输入 token——这时回到向导点一下对应节点的名称即可单独复制它的 token 并粘贴进去,token 不会和命令一起进 shell 历史,也不会在 ps 里出现。装上助手后向导每 15 秒自动重新查一次花名册,不用手动点「重新检查」。确认无误后点「继续安装」→「启用并开始首次检测」,向导会直接写入 routeProbeEnabled: true——不需要再进入 Komari 的主题设置页面。开启后工具栏那个入口会换成检测按钮旁的一个小齿轮图标,随时可以重新打开向导,给后续新增的节点补装助手。
不想用向导也可以跳过,直接在主题设置里手动开启 启用三网回程检测(routeProbeEnabled),效果完全一样。
开启后,已登录管理员打开首页约 20 秒,主题会挑出「非中国大陆、在线,且没测过或结果已超过 7 天」的节点跑一轮。回程几周才变一次,这个条件天然把频率压到每台约每周一次;同一浏览器的多个标签页还共享 30 分钟冷却时间。首页工具栏另有一个「检测回程 N」按钮,刚加完机器不想等时可以手动点,N 是当前待测台数;全部节点都新鲜时按钮变成「重新检测回程 N」,手动点击会跳过 7 天新鲜度、强制重新测一遍在线的境外节点——这个跳过只对手动点击生效,后台自动检测永远不会绕过新鲜度。中国大陆节点到国内目标通常不经过可判定的国际骨干,这项指标也没有实际意义,因此不会进入待测数量或失败统计;香港、澳门和台湾节点仍会正常检测。
安装命令只在 HTTPS 面板提供,不会自动允许远端明文 HTTP。升级时先升级插件,再升级助手:新助手只用 JSON POST 请求体传凭据;遇到不支持 POST 轮询的旧插件会提示升级,不会回退 URL token。新插件仍接受旧助手,但旧助手的 URL 凭据日志风险只有升级节点后才消除。代理/CDN/APM 应隐藏凭据查询参数及请求体,同时保留路径、状态码等访问审计;历史日志中的 token 若曾暴露,应由管理员另行轮换。详见插件安全与升级说明。
关于节点助手的安全边界,有几点是明确设计过的:
- 节点助手只有出站 HTTPS,没有监听端口;Agent token 存在
0640的 root/专用用户配置文件中,不出现在 systemd 命令行。 - Komari 使用 Agent token 识别节点,节点只能领取和提交属于自己 UUID 的任务;一次性任务 ID 有 3 分钟租约、10 分钟有效期,重复提交保持幂等。
- 城市白名单和真实目标地址都固化在节点本地。插件返回多余字段、非法城市、任意错误文本、伪造时间戳或非 ASN 标签时会被拒绝。
- 新结果保存在 Transit 主题数据中,不再写入 Komari 的用户标签。浏览器清理旧
transit-route:时会重新读取节点最新标签,检测期间新增的运营者标签会保留。 - 未连接节点助手、缺少 traceroute、助手执行超时和普通探测失败分别显示,不会为了凑结果写入空标签。
旧版远程执行回退路径继续保留以下约束:
- 下发的命令是编译期常量,只含三网测速点地址(与拓扑管理器的九个入口预设同源)。节点 UUID 只进
admin:exec的clients数组,绝不进命令字符串;命令里没有任何 shell 变量展开,所以没有注入面。这一条有专门的回归测试守着。 - Komari 自身会审计每一次远程执行(warn 级审计日志),主题这边也会把每次下发和写回记进拓扑管理器底部的「本次会话的后端写入记录」。
- 新结果不写入节点标签。主题会保存到
pandaOpsRouteProbeResults;如果节点仍有旧transit-route:,先确认主题数据已保存,再重新读取最新节点只删除该保留条目,其他标签原样保留。 - 节点关闭 Komari 远程控制时会明确回报「远程控制已关闭」;没装
traceroute时会明确回报「节点未安装 traceroute」。主题不会擅自改变节点安全策略或安装软件,也不会因为一台失败而影响其余节点。失败过的节点在本次会话里不再自动重试,避免在跑不通的机器上反复执行命令;修好后点一次手动按钮即可重来。 - 后台标签页不会自动采集,只有当前可见的页面才会。
- 三家运营商一个骨干跳都没认出来时判为采集失败,不写回——否则一次网络抖动就会把上次的好结果覆盖成「未见骨干」,还让这台机器七天内不再重测。
- 管理员账号启用了 2FA 时,
admin:exec属敏感操作会被拒绝;固定能力节点助手不调用admin:exec,不受这个限制。 - 需要
traceroute(ICMP 模式需 root,Komari agent 通常已是 root)。
如果暂时不能安装 Komari 伴生插件,仓库里仍保留 scripts/collect-return-route.sh 的 cron/API Key 手动路径,格式完全一致:
sudo ./collect-return-route.sh --push \
--url https://status.example.com --uuid <节点UUID>脚本会从终端隐藏输入管理员 API Key。无人值守运行改用 --key-file /root/.config/transit/api-key,文件内容仅为一行密钥,可带末尾换行;文件必须由脚本运行用户所有,权限为 0400 或 0600,不能是符号链接。以上 sudo 示例需要 root 所有的密钥文件。请通过安全编辑器或凭据管理工具创建文件,不要把密钥写进 shell 命令、历史或 cron 配置;父目录也应只允许该用户访问。
手动写回只接受最终 HTTPS 源地址(例如 https://status.example.com:443),校验证书且不跟随任何重定向;不接受 URL 凭据、子路径、查询参数或明文 HTTP。--key 和 KOMARI_API_KEY 已禁用,旧 cron 需改为 --key-file,否则会停止执行。原来仅打印标签或由伴生助手调用的采集方式不变。若旧密钥曾经通过明文 HTTP、命令行或日志暴露,应由管理员轮换;长期优先使用伴生助手,避免把面板管理员密钥放在节点上。
结果保存在 Transit 主题的 pandaOpsRouteProbeResults 映射中,以节点 UUID 为键。单条结果仍使用下面的稳定协议格式,便于新旧助手兼容:
transit-route:ct=4809.4809.4134,cu=4837.4837,cm=58807.9808@1755000000
ct/cu/cm 是电信/联通/移动,等号后面是按跳序排列的骨干网 ASN,@ 后面是采集时刻的 Unix 秒。ct= 这种空值表示探了但没认出骨干,和「没探这家」是两回事。
v1.4.1 早期版本和 collect-return-route.sh --push 会把同样内容写入节点 tags。升级后,已登录管理员打开 Transit 首页时会先把旧结果保存到主题数据,确认成功后再只清理 transit-route: 条目。因此 Komari 官方后台的「账单」标签列不再显示这串内部数据,Transit 前台的回程判定不受影响。
判定逻辑移植自 oneclickvirt/backtrace(NodeQuality 的三网回程检测最终调用的就是这一套),code 与上游逐字一致。规则按 ASN 出现的先后顺序和跳数定级,比「看到哪个 ASN 就报哪条线」保守:
- 只出现一跳 AS4809 不报 CN2GIA,报「CN2 混合」——一跳不足以和 GT 区分;
- 只出现一跳 AS4134 不报 163,判「仅见电信目的网」——那一跳更可能是目的网交付跳;
- AS4837 出现在 AS9929 之前、AS58453 出现在 AS58807 之前,都降级为「混合」;
- 多次采集结论互相矛盾时判「动态混合」,而不是挑最好的那个报上去。
判不出就显示判不出,不硬凑线路名。徽章上的 ? 表示证据存在矛盾。
两处已知边界:GIA 和 GT 都属于 AS4809,只靠 ASN 序列无法完全区分,规则用跳数做保守近似;IPv6 跳点不参与判定,上游靠内嵌约 167 KB 的前缀表做最长匹配,塞进主题产物不划算,采集脚本只处理 IPv4。
不是每台服务器都需要固定显示三网质量。Transit 支持按节点 UUID 保存独立观测面板,节点改名后配置仍然有效:
| 模式 | 适合节点 | 展示内容 |
|---|---|---|
| 自动选择 | 不想逐台配置 | 按 GPU、三网任务、流量配额和节点用途自动选择 |
| 三网质量 | 面向大陆用户的节点 | 联通、电信、移动延迟、丢包与近期采样 |
| 自定义 Ping | 中转机、线路机、落地机 | 最多三个该节点真实执行的 Komari Ping 任务 |
| 系统状态 | 普通计算节点 | Load、温度、Swap、进程和连接数 |
| 流量状态 | 限流或大流量节点 | 累计上下行、已用流量、剩余额度和配额比例 |
| 存储状态 | 存储、备份和归档节点 | 已用、可用、总容量与磁盘占用 |
| GPU 状态 | GPU 计算节点 | GPU 利用率、设备名称和系统温度 |
| 精简信息 | 只需基础状态的节点 | 在线天数、进程数和连接数 |
全局默认仍是“三网质量”,已有安装升级后不会改变当前卡片内容。管理员可以通过两种方式配置:
- 点击节点卡或服务器列表中的“运维”按钮,在“节点卡片观测面板”中设置单台节点;选择“自定义 Ping”后,从该节点已配置或已产生样本的任务中选择最多三个。
- 打开 Transit 服务器列表,点击“批量卡片面板”,将当前分组全部设为同一种模式或恢复跟随全局默认。自定义 Ping 因每台节点的任务不同,仍需逐台选择。
配置通过 Komari 托管主题设置保存,多设备同步。面板只展示 Komari 已上报的数据;任务不存在、未产生样本或记录功能关闭时会明确显示空状态,不会生成模拟数据。所有模式使用相同高度,同一网格行不会因面板类型不同而参差。
Transit 不只展示在线/离线状态,还会把可操作信息集中到首页:
- 异常摘要:汇总离线、高负载、Ping 丢包、流量预警和即将到期节点。
- 事件时间线:查看节点异常、恢复和维护事件。
- 线路可靠性:按有效采样、延迟和丢包计算线路评分,并展示每一段的数据覆盖情况。
- 节点维护:管理员可以为节点设置维护状态,保存后立即影响告警判断。
- 服务器列表:按名称、地区、IP、系统和 CPU 搜索,筛选状态,按官方顺序或实时指标升降序排列;管理员可调整首页全局顺序,并按当前分组批量设置卡片面板。
- 节点对比:比较多个节点的资源、流量、价格和网络数据。
- 健康摘要:切换日、周、月区间查看历史健康情况。
- 厂商性价比:按价格、资源和剩余价值排序节点。
- 快照导出:导出当前监控快照的 CSV 或 JSON。
- 审计日志:读取 Komari 核心管理员操作日志,不虚构服务端未提供的访客记录;浏览器单次导出最多 5,000 条并标记是否截断,避免大日志库耗尽页面内存。
- 磁盘预测:样本充足时按历史增长趋势估算磁盘耗尽时间。
高级工具默认只向已登录用户显示,权限校验以 Komari /api/me 和服务端接口为准。隐藏按钮、前端状态和本地设置都不是安全边界。
线路详情会复用已经请求的 24 小时和 7 天 Ping 数据,不增加 Komari RPC,也不增加需要操作者调整的阈值或开关:
- 当前一小时与此前 24 小时基线相比,延迟或丢包显著升高时给出谨慎诊断;数据过期、指标缺失或有效历史少于 12 点时不下结论。
- 最近 7 天样本固定按北京时间归入 24 个小时桶,展示延迟与丢包中位数,并标出 20:00–23:00 晚高峰;每小时不足 3 个有效点时明确显示无数据。
- 晚高峰至少有 3 个有效小时、其余时段至少有 12 个有效小时后,主题会比较两个时段的小时中位数。延迟高出
max(20ms, 30%),或丢包同时达到 3%、高出 3 个百分点且至少翻倍时,首页显示独立的晚高峰 +Nms/晚高峰丢包 +Npp标签;它不扣健康分、不改变线路状态。 - 两条已配置实时线路的「线路机 UUID → 落地机 UUID」恰好互为反向且各只有一条候选时,详情并排显示两个方向的延迟、丢包、探测来源与任务名。入口运营商标签、自指、静态指标和重复候选不参与配对。
- 同一精确任务的 7 天数据覆盖至少 72 小时、有效小时不少于 48 个,并通过连续 6 小时确认后,首页会显示
基线升高 +Nms。这是独立洞察标签,不进入异常摘要、不扣健康分,也不改变线路红黄绿状态;改善事件只在详情显示。
详情中的“判断依据”会列出当前一小时读数、排除最近一小时后的 24 小时 P50/P95 与丢包基线、有效样本数、7 天覆盖、最后真实样本时间、精确任务和探测来源。所有访客都可以复制一份诊断报告;报告只包含公开线路名称和统计结论,不包含 UUID、任务 ID、精确任务名或 IP,并在生成后再次执行标识与地址脱敏。
“延迟基线显著变化”只说明长期时延地板发生了足够大的阶跃,可能与路径、探测方式或目标变化有关,不等同于确认路由改变。事件每次加载都从当前 7 天窗口重算,不写主题设置、浏览器存储或后端;管理员原地修改同一个任务 ID 的类型或目标时,主题无法把变更前后的样本区分开。自动修复通常会新建任务或清除旧任务历史,不会跨任务拼接。Transit 仍不采集 traceroute/MTR,也不会显示浏览器无法获得的网络跳数。
点击顶部“壁纸与背景效果”按钮即可选择图片。原图保存在当前浏览器的 IndexedDB 中,不会提交给 Komari 或第三方;刷新页面后仍会保留,但其他浏览器、设备和访客不会自动同步。支持 JPG、PNG、WebP、AVIF,单张最大 15 MB、解码后最大 5,000 万像素。
- 玻璃化:保持壁纸清晰,并加强前景卡片的毛玻璃层次。
- 模糊:对背景使用 16px 柔焦,降低复杂画面对内容的干扰。
- 高清:按原图显示,不增加模糊或额外滤镜。
“更换壁纸”只有在新图片完成解码并成功写入浏览器存储后才替换旧图;失败时原壁纸仍会保留。清理站点数据、浏览器无可用存储空间或使用隐私模式时,可能需要重新选择。站点管理员如需给所有访客统一配置背景,仍使用下方的托管 URL/local: 背景设置。
Transit 的托管设置按使用路径分为八组:
| 分组 | 主要内容 |
|---|---|
| 01 · 基础与外观 | 主题模式、刷新间隔、RPC 模式、默认视图、节点卡尺寸与默认观测面板 |
| 02 · 首页布局 | 公告、地球样式、拓扑、三网地区、配色方案、色觉辅助模式 |
| 03 · 首页总览卡片 | 官方/基础/运维/资源/财务等预设与自定义卡片 keys |
| 04 · 高级工具与隐私 | 高级工具、访客信息、访客审计、价格隐藏和减少动画 |
| 05 · 节点卡片与列表 | 快捷筛选、列表字段、离线置底、告警阈值、磁盘预测 |
| 06 · 节点详情概览 | 分区标签、详情卡片预设与自定义 keys |
| 07 · 节点详情图表 | CPU、内存、磁盘、网络、GPU、Ping 等图表组合 |
| 08 · 自定义背景 | 图片/视频背景、亮暗地址、模糊和遮罩 |
完整 key、默认值与帮助文本以 komari-theme.json 为准。Komari 1.2.6 Metric Store 适配细节见 docs/Komari-1.2.6-theme-adaptation.md。
Transit 将两类可选行为默认关闭:
- 访客公网信息:开启
visitorInfoEnabled后,访客浏览器会依次请求ipwho.is、ipapi.co、api.ip.sb,直到一家返回成功。相应服务会看到访客 IP,并返回 IP、地区和运营商信息。 - 访客审计:只有
visitorAuditClientEnabled与 Komari 核心的visitor_audit_enabled同时开启时,Transit 才会上报页面事件、设备特征和哈希指纹到站点自己的 Komari。 - 本机壁纸:壁纸文件只写入访客当前浏览器的 IndexedDB,不经过 Transit、Komari 或第三方网络请求;效果选择只写入同站点
localStorage。
公开首页的地球节点只按 Komari 已提供的国家/地区代码定位,不读取节点 IP,也不会为地图向第三方地理服务发送节点 IP。只有已登录用户主动打开需要地理增强的工具时,才可能在权限校验后查询节点 IP。
汇率请求同样按需触发:只有页面实际显示金额时才读取日缓存并在必要时访问汇率服务;隐藏访客价格或当前布局没有金额卡片时不会请求。界面图标已打包进主题,不会请求 Iconify CDN。
部署者在启用前应向访客说明用途、第三方接收方、保留期限和退出方式。完整字段、数据流与运营者检查清单见 PRIVACY.md。
Transit 不再内嵌或再分发 komari-web 构建物。登录后的服务器列表由 Transit 自有代码展示主题已经接收的实时节点数据,并提供排序、首页顺序保存、详情和维护入口;顺序通过 Komari 官方 admin:orderClients RPC 保存。新增/删除 Agent、密钥、Ping 任务、通知、主题、插件、数据库、终端、账号和权限等其余配置能力继续使用 Komari 安装包自带的官方后台。主题顶部和服务器列表中的后台入口都直接进入 Komari 1.4.x 的服务器管理路由 /admin/servers。
截至本版本发布时,komari-monitor/komari-web 没有声明可供第三方修改和再分发的许可证。因此 Transit 的源码仓库和 Release 都不包含它的源码、补丁、构建文件或派生管理端截图。若上游未来提供明确许可,可在符合其条款的前提下重新评估集成。
| 项目 | 支持范围 |
|---|---|
| Komari | 隔离实验覆盖 1.2.5-fix2、1.2.6、1.4.2、1.4.3;维护者生产环境运行 1.4.3 |
| 浏览器 | Playwright 自动验证 Chromium、Firefox、WebKit 和移动 WebKit |
| 设备 | 桌面与移动端响应式布局;节点卡最坏情况覆盖 320、390、768、1280、1700px |
| 主题设置 | 同一 Transit 短名称升级时保留托管设置 |
| 服务端 | 主题包不修改 Komari 数据库结构、Agent 或系统账户 |
Komari 新增接口时,Transit 优先使用 Metric Store;接口不可用时再回退到兼容 records 路径。
Transit 与 PandaOps 使用不同短名称,因此两套主题可以并存,但 Komari 不会自动把 PandaOps 的托管设置复制给 Transit。
建议迁移步骤:
- 记录或导出 PandaOps 当前的
topologyRoute、topologyMetrics和自定义设置。 - 上传并启用 Transit,不要删除 PandaOps。
- 在 Transit 设置中恢复主题模式、卡片方案和告警阈值。
- 使用拓扑管理器重新确认入口、线路机、可选跳板和落地机。
- 验证首页、节点详情和拓扑配置后,再决定是否保留旧主题。
服务器管理员可以在完整数据库备份后复制对应 theme_configurations,但不建议普通用户直接修改 Komari 数据库。
升级前建议保存主题设置并保留当前 Release:
- 下载新的 Release 主题 zip。
- 在 Komari 主题管理中上传并更新
Transit。 - 强制刷新浏览器,检查拓扑、三网任务和自定义背景。
- 若新版不符合预期,重新上传上一版 Release 或切回保留的旧主题。
Transit 不执行数据库迁移。主题设置格式发生变化时会保留旧值回退逻辑,并在 Release Notes 与 CHANGELOG.md 中说明。
拓扑配置正处在这样一次格式切换中:真值已经是 JSON 格式的 topologyConfig,topologyRoute 和 topologyMetrics 作为兼容字段继续写入同一份内容。读取时优先用 JSON,没有才解析旧字段,所以升级不需要任何操作,降级安装也不会看到空拓扑。旧字段会在确认无人回滚后的某个版本停写。
确认已经登录 Komari,并启用了 Transit 首页和多线路拓扑。公开访客不会获得保存主题设置的权限。
选了北京/上海/广州的预设入口,或填写了自定义入口名称与有效 IP/域名后,Transit 都会自动创建并绑定对应探测任务;保存后等一个采样周期即可看到数据。仍然没有数据通常是探测阶梯已经走完,需要检查线路机是否能连到入口目标,或更换探测目标。
保存后等至少一个采样周期。节点间新建任务需要该段来源节点先探测下一节点 IP;主题会兼容新版 Metric Store 和旧版 Ping records,并在任务持续无响应时自动尝试其他可用探测方式。数据延迟或过期时页面会明确标出:超过 10 分钟没有新样本会显示上次更新时间,超过 30 分钟才回退到备用基线。<1ms 表示 Komari 返回了有效的亚毫秒样本(包括量化为 0 的成功样本),不是无数据;零丢包时应显示为正常绿色。
不一定。拓扑节点顺序是展示配置,实时指标的真实采集方向由“探测来源节点”决定。页面会显示来源节点和 Ping 任务;如果要测“北京电信 → 海外节点”,需要在北京电信网络中部署探测端。主题自身不采集 traceroute,也不会根据任务名称伪造跳点或正向路径。
需要知道回程走哪条骨干网时,用三网回程线路:跳点由节点上的采集脚本真实测出后写回 Komari,主题只做判定和展示,判不出就显示判不出。
这是预期行为。Transit 提供自有的实时服务器列表和主题内运维工具,但不再分发授权状态不明确的 komari-web 派生管理端;完整配置操作请使用 Komari 自带后台。
登录后打开 Transit 服务器列表,点击节点右侧的“运维”,在“节点卡片观测面板”中选择模式。中转和落地节点可以选择“自定义 Ping”并绑定最多三个该节点真实执行的任务;需要统一设置时使用“批量卡片面板”。选择“跟随全局”会删除单节点覆盖,恢复主题设置中的默认面板。
确认上传的是 Release 附件中的 komari-theme-Transit-build-*.zip,并检查反向代理上传大小限制;不要上传 GitHub 自动生成的源码压缩包。
Komari 1.2.5-fix2 到 1.4.3 的 GitHub 仓库导入逻辑会直接下载最新 Release 的第一个附件。Transit 的新 Release 会把主题 ZIP 保持为首个附件并在发布后自动验证;此前已经发布且首个附件不是主题 ZIP 的版本,请下载 komari-theme-Transit-build-*.zip 后使用“上传主题”,不要把 GitHub 下载链接再次粘进“导入远程主题”。
先执行浏览器强制刷新;若使用 CDN,再清理 HTML 缓存。带内容哈希的 JS/CSS 可以长期缓存,但入口 HTML 不应永久缓存。
这是 Komari 的私有站点策略。完成登录后,公开监控和 Transit 高级工具会按当前会话权限显示,管理操作仍进入官方后台。
需要 Node.js 22.22.2+(22.x)、24.15+(24.x)或 26+,推荐使用仓库声明的 Bun 1.3.14。
bun install --frozen-lockfile
bun run dev提交前执行:
bun run lint:check
bun run type-check
bun run test:unit
bun run test:visual
bun run test:functional
bun run test:performance
bun run audit:bundle
bun run audit:performance
bun run audit:dependencies
bun run audit:reproducible
bun run build
bun run audit:releaseLinux 环境还可以运行 bun run test:komari,在隔离的真实 Komari 实例中验证主题安装、覆盖升级、回滚、路由、认证边界、RPC 和重启持久化。具体版本矩阵见 兼容性实验文档。
bun run build 会生成:
dist/komari-theme-Transit-build-<short-sha>.zip
视觉回归覆盖亮暗主题、桌面/移动端、拓扑管理器、统一采样交互、无障碍扫描和节点卡等高布局。功能回归覆盖 Chromium、Firefox、WebKit 与移动 WebKit;性能回归覆盖大规模节点虚拟化和反复导航后的资源释放。像素基准由 Playwright Chromium 在 macOS 环境维护,Linux CI 负责质量、依赖安全、兼容性与发布结构门禁。更新截图基准前必须人工确认设计差异。README 和主题预览图则运行 bun run docs:screenshots 刷新;它使用确定性 Komari 夹具直接重拍 docs/ 图片,不会改写视觉回归基准。
- 主题安装 ZIP 只包含本仓库可依法再分发的主题代码和资产;GitHub Release 还可能单独附带回程伴生插件和节点安装脚本,它们不会被嵌入主题 ZIP。
- 构建检测到
dist/admin-app/时会直接失败,避免误把外部管理端带入主题包。 - 外部项目的名称、链接与截图仅用于兼容性说明或致谢,不表示其许可证自动适用于 Transit。
- 如需加入第三方代码,贡献者必须同时提交来源、固定版本、许可证文本和必要的 NOTICE。
- 首页和节点详情是公开监控界面,不是鉴权边界。
- 拓扑保存、节点面板配置、节点维护、快照导出和管理操作会验证 Komari 会话。
- 自定义背景、Markdown、外部链接和导出数据应视为不可信输入。
- 不要在 Issue、截图或日志中提交密码、Token、Cookie、私钥和未打码服务器地址。
深入资料:
Transit 是社区二次开发项目,不是 Komari 官方主题。感谢以下开源项目与作者提供的基础:
- Komari — 监控服务端与生态基础。
- komari-web — Komari 官方管理界面;Transit 仅保持 API 与使用流程兼容,不打包或再分发其代码。
- komari-theme-Glassmorphism — 原始主题和组件结构基础;感谢原作者及 MIT 许可证中列明的 Tony Liu。
- komari-theme-Glassmorphism-three-network — 感谢 vlongx 提供的三网 Ping 展示与后续二次开发基础。
在已获许可的主题基础上,Transit 重新设计了网络拓扑、可视化拓扑管理器、节点卡片、告警体系、采样交互和亮暗主题。感谢所有上游贡献者。
- 使用问题、功能建议和可复现缺陷请通过 GitHub Issues 提交。
- 提交截图和日志前请先打码 IP、域名、Cookie、Token 和其他私密信息。
- 贡献代码前请阅读 CONTRIBUTING.md。
- 安全问题请遵循 SECURITY.md,不要公开披露漏洞。
- 版本变化记录见 CHANGELOG.md。
本仓库中由 Transit 提供、且未另行标注的代码采用 MIT License。发布和再分发时请保留版权与许可证声明;MIT 不会替未授权的第三方作品授予许可。


