KPanel 原生体检与第三方增值测试

产品定位

体检模块采用“双层能力”设计：

• KPanel 核心体检：由 Agent 内置原生探针完成，默认可用，不依赖 kejilion.sh、YABS、NodeQuality 或其他脚本；
• 第三方增值测试：继续读取 kejilion.sh 登记的脚本，用于解锁、三网回程、报告型 IP 信誉和更细的线路分析，不影响核心体检。

页面首屏默认进入 KPanel 核心综合体检。原生单项保留为综合任务内部的探针 ID，不再拆成终端命令展示；左侧只保留第三方增值脚本，供用户按需进入终端测试。同一时间只运行一个任务，避免多个测速或跑分互相污染结果。

原生检测目录

原生目录由 Agent 直接提供，当前包含以下内部探针：

ID	结果维度	检测方式	资源边界
native-cpu	性能	固定时长本地整数运算，回显 CPU 型号、核心数、运算吞吐	约 1.2 秒、单进程
native-memory	性能	32 MiB 受控内存块双向复制，回显内存吞吐	约 1.2 秒、约 64 MiB 工作集
native-disk	性能	临时目录写入、fsync、顺序读取固定数据量	64 MiB 临时文件，任务结束删除
native-route	路由	固定 HTTPS 探测点回显出口 ASN、地区和边缘节点	1 次小响应
native-latency	延迟	对多个固定 HTTPS 探测点各请求 3 次	失败率、平均/最小/最大延迟、抖动
native-speed	网速	固定体积下载与上传请求	下载 8 MiB、上传 2 MiB
native-ip-quality	IP 质量	公网 IP、ASN、地区、IPv4/IPv6、反向解析，以及 IPING 返回的 ISP、IP 类型、风险分、风险等级、风险标签、代理状态和使用类型	IPING 仅查询 IPv4，API 与官网详情页并发请求且各自 5 秒超时，详情页失败时回退 API 风险分
native-comprehensive	核心汇总	按固定顺序串行执行以上原生探针	预计 3 分钟以内，网络状况除外

原生结果统一写入 summary：每个维度只保存实际探针返回的指标，页面可直接回显 CPU、内存、磁盘读写、上下行、平均延迟、抖动、丢包、出口 IP 和 IPv4/IPv6 等结果。首屏按“综合评分 → 性能 → 网络”呈现；其中性能由服务器本机执行，网络由服务器出口访问固定探测点完成，浏览器只负责启动任务和展示结果，浏览器到服务器的访问质量不计入综合分。KPanel 体检分 · v1 是基于本次结果的版本化展示指数（性能 45%、网络 55%），用于快速对比本机状态，不替代硬件横向基准。IP 质量分采用透明加权：风险安全度（100 - risk_score）占 80%，IP 类型占 10%，代理状态占 5%，ISP/ASN/使用类型信息完整度占 5%；无有效风险分时回退为基础信息完整度。原始 risk_score 以百分比展示，风险等级仅是 KPanel 的文字分级：<30 为低风险、30-79 为中风险、>=80 为高风险，IPING 官方接口文档未定义这些阈值。

测速、路由和 IP 基础信息使用固定探测接口，不接受用户输入的任意 URL；接口失败时保留已完成的部分结果，并在日志中明确标记失败原因。IPING 只映射 isp、asn、as_owner、usage_type、type、risk_score、risk_tag、is_proxy 八类接口字段，其中 type 映射为 KPanel ip_type，并在 KPanel 内派生一个 risk_level；不把公司、地理、经纬度等其他响应字段写入 KPanel summary。执行 IP 质量体检时，公网 IPv4 会并发发送到 api.iping.cc 和 IPING 固定官网详情页：结构化字段取自 API，风险百分比以官网详情页为准；详情页不可用或无法解析时保留 API 风险分，两个来源均不可用时回退 KPanel 原生数据。当前每次体检对两个固定来源各请求一次，官方未公开限流与 SLA，规模化使用前仍需确认。流媒体解锁和三网回程明细仍属于第三方增值能力，不能从基础探测结果推断。

第三方脚本协议

第三方脚本不再是核心体检的前置条件。若可信 kejilion.sh 存在且协议可用，Agent 追加读取：

KJ_TEST_NONINTERACTIVE=1 k test list
KJ_TEST_NONINTERACTIVE=1 k test run <fixed-selector>

list 输出 KPANEL_TEST_CATEGORY 和 KPANEL_TEST_ITEM 制表符记录。Agent 仍只接受：

• ^[a-z0-9][a-z0-9-]{0,47}$ 形式的固定分类与 selector；
• HTTPS、无凭证、无 fragment 的第三方来源；
• 1 至 120 分钟的预计耗时；
• light、network 或 intensive 三种资源影响。

脚本目录缺失、脚本目录格式错误或脚本命令不可用时，只隐藏第三方项目，原生目录仍可使用。未知或不可信脚本不会被降级执行。第三方任务依旧使用 PTY/FIFO，允许用户根据脚本当前提示输入 y、1、回车或其他内容；快捷按钮只发送输入，不替用户判断脚本语义。

执行与恢复

所有任务仍创建 kejilion-panel-diagnostic-<job-id> transient systemd unit，再由 root-only diagnostic-run 子命令执行。原生任务在 Agent 内置探针分支执行，不启动 Shell，结果汇总到首屏并保留服务端日志；脚本任务沿用可信脚本和 PTY 隔离，并在左侧独立进入终端。

• 同一时间只运行一个体检；
• 最长运行 90 分钟；
• 原生任务使用普通日志回显，脚本任务使用带 ANSI 的 PTY 终端；
• 系统重启或任务超过 100 分钟时，自动标记为中断，避免永久阻塞新体检；
• 原生硬盘临时文件在任务结束清理，测速请求大小固定，不接受任意外部命令或 URL；
• 单任务日志最多 8 MiB，API 只返回最近 400 行，最多保留 50 条历史；
• Web 启动和终端输入动作通过 Session、Origin、CSRF 与长度/NUL 校验。

第三方脚本可能安装依赖、消耗带宽/CPU/磁盘，页面会在执行前单独说明。YABS 等脚本的具体副作用不纳入 KPanel 原生体检承诺。

后续演进

1. 继续用真实服务器样本校准 KPanel 体检分 · v1，再决定是否加入更细的版本化分项等级。
2. 增加 DNS、TCP/TLS、MTU、丢包窗口和 IPv4/IPv6 的可选深度探针。
3. 将探测点、超时、数据量和隐私说明抽成版本化配置；继续禁止任意 URL 和任意 Shell。
4. 增加历史对比与趋势图，区分“本机性能变化”和“外部线路波动”。
5. 对第三方结果继续按来源逐个适配，原始输出永远保留，解析失败不影响任务完成。

验收状态

• 已实现：原生目录、原生任务分支、CPU/内存/磁盘/路由/延迟/测速/IP 基础探针、IPING 选定字段增强、统一 summary、原生优先综合入口、首屏综合评分与“性能/网络”分组、第三方脚本可选降级、前端区分原生与脚本。
• 已验证：前端 i18n 校验、类型检查、101 个测试文件/783 个测试、生产构建、首屏布局回归，以及 mock 预览中的原生综合结果汇总；已补充 IPING 响应选定字段映射与 IPv6 跳过测试；在 WSL Ubuntu 24.04 的临时 Go 1.26.6 环境通过 gofmt、go test ./internal/diagnostics，并完成 Agent API → systemd-run → diagnostic-run → summary 的真实原生综合链路验收。
• 环境限制：本次 WSL 外网访问受代理/网络策略影响，综合体检中的 IPING 风险细项未取得实时响应，按设计回退为 KPanel 原生 IP 基础信息；真实公网 IP、测速、IPv4/IPv6 和 IPING 结果仍需在网络可达的 Linux 目标机复验。完整 go test ./... 还涉及 Docker、Panel、SystemManage 等 Linux 专属测试。
• 明确不做：自定义测试命令、任意 URL、并行跑分、把 IPING 完整响应透传到页面或日志、从基础探测结果推断流媒体解锁结论。