scriptConfig
这一页说明测试脚本相关配置。
在 koipy 里,脚本一般不长期存放在后端本地。它们主要由 bot 端读取、选择,然后在任务开始时连同测试请求一起发送给后端执行。
scriptConfig
yaml
scriptConfig:
scripts: # 脚本载入
- type: gofunc # 表示是 miaospeed 的内置实现
name: "TEST_PING_RTT" # 预留名称
rank: -100 # 排序,越小越靠前
- type: gojajs # 表示 miaospeed 主流脚本类型
name: "示例脚本"
rank: 0
content: |
function handler() {
return {
text: "成功",
background: "186,230,126"
}
}
- type: gojajs
name: "Youtube"
rank: 1
content: "resources/scripts/builtin/youtube.js" # 也可以指定一个文件路径概要
scriptConfig.scripts是一个数组,每一项都是一个可被 koipy 识别的脚本条目。- 这些脚本既可以被交互式脚本选择器选中,也可以在
rules[].script里通过名字直接引用。 - 配置加载时,源码会先按
rank升序排序,再进入后续选择与任务构造流程。
注意
当前源码对脚本类型的实际支持只有 gofunc 和 gojajs。虽然内部常量里还保留了 cpython,但当前任务分发链路并不会正确处理它,不建议在配置中使用。
scriptConfig.scripts
解释
- 这是脚本列表本体。
- 如果你想让一个自定义脚本能被规则或前端选择器引用,它就需要出现在这里。
- 普通自定义检测脚本通常写成
gojajs;内置测试项覆写通常写成gofunc+ 预留名称。
特性
- 类型:
list[Script] - 源码加载后会按
rank升序排序。 - 普通脚本选择器展示的名称,来自这里每个脚本的
name。 GEOIP_INBOUND和GEOIP_OUTBOUND虽然也是脚本名,但当前不会出现在普通脚本选择器列表里。- 建议每个脚本
name都保持唯一;当前源码在按名字匹配时,命中的是排序后列表中的第一个同名项。
配置示例
yaml
scriptConfig:
scripts:
- type: gofunc
name: "TEST_PING_RTT"
rank: -100
- type: gojajs
name: "OpenAI"
rank: 2
content: "resources/scripts/builtin/openai.js"scriptConfig.scripts[n].type
解释
- 这项配置决定脚本的实现类型。
- 当前最常用的是:
gojajs:JavaScript 脚本,由 miaospeed 的 goja 引擎执行。gofunc:后端内置测试项,对应固定的预留名称。
gofunc不是“任意 Go 代码注入”。它本质上只是告诉 koipy:这个名字要映射到某个已知内置测试项。
特性
- 类型:
str - 可稳定使用的值:
gojajs、gofunc gojajs适合自定义流媒体检测、地区检测、风险检测等逻辑。gofunc只适合和预留名称配套使用;任意自造的gofunc名字当前不会被正确映射。cpython虽然出现在源码常量里,但当前流程不会真正把它当成可执行脚本类型处理。
配置示例
yaml
scriptConfig:
scripts:
- type: gofunc
name: "SPEED_AVERAGE"
rank: -98
- type: gojajs
name: "Netflix"
rank: 0
content: "resources/scripts/builtin/netflix.js"scriptConfig.scripts[n].name
解释
- 这是脚本的唯一标识,也是规则里
script数组要填写的名字。 - 如果脚本类型是普通
gojajs,名字可以是任意字符串。 - 如果你写的是预留名称,那么它会触发内置测试项覆写逻辑,而不再只是一个普通自定义脚本。
特性
- 类型:
str - 建议保持唯一,避免同名。
rules[].script引用的就是这里的name。- 对于
GEOIP_INBOUND、GEOIP_OUTBOUND这类 GEO 名称,当前更多是给规则或拓扑流程使用,而不是常规手动点选。
配置示例
yaml
scriptConfig:
scripts:
- type: gojajs
name: "Claude"
rank: 5
content: "resources/scripts/builtin/Claude.js"scriptConfig.scripts[n].rank
解释
- 这项配置决定脚本结果在任务结果中的显示顺序。
- 数字越小,排得越靠前。
- koipy 在载入
scriptConfig.scripts时会按这个值排序;任务真正合并测试项时,也会再次按脚本rank排序。
特性
- 类型:
int - 可写负数、零、正数。
- 内置测试项默认常见范围大致在
-100 ~ 100。 - 如果你用预留名称覆写了一个内置项,那么它的
rank也会跟着你写的值走。 - 如果多个脚本
rank相同,最终相对顺序更适合依赖配置加载顺序,但不建议把关键布局建立在这个细节上。
配置示例
yaml
scriptConfig:
scripts:
- type: gofunc
name: "TEST_PING_RTT"
rank: -100
- type: gojajs
name: "Youtube"
rank: 0
content: "resources/scripts/builtin/youtube.js"
- type: gojajs
name: "IP风险"
rank: 11
content: "resources/scripts/builtin/iprisk.js"scriptConfig.scripts[n].content
解释
- 这是脚本的实际内容来源。
- 对
gojajs来说,它既可以直接写内联脚本内容,也可以写成一个本地文件路径。 - 对
gofunc来说,通常可以留空;真正起作用的是预留名称本身。 - koipy 在任务构造阶段会尝试把
content当成本地路径解析;如果路径存在,就读取文件内容并发送给后端。
特性
- 类型:
str - 文件路径支持相对路径和绝对路径;相对路径通常相对于 koipy 的工作目录。
- 文件会按
utf-8读取。 - 一个很重要的细节是:如果你写的是路径字符串,但文件并不存在,程序不会在这里报错,而是会把这段字符串直接当成脚本源码本体发送出去。
- 所以路径写错时,经常不是“读取失败”,而是“后端拿到一段毫无意义的脚本内容然后执行失败”。
- 对自定义
gojajs脚本来说,content不应留空;否则任务构造时不会有真正脚本内容可发送。
配置示例
yaml
scriptConfig:
scripts:
- type: gojajs
name: "内联示例"
rank: 0
content: |
function handler() {
return {
text: "成功",
background: "186,230,126"
}
}
- type: gojajs
name: "文件示例"
rank: 1
content: "resources/scripts/builtin/youtube.js"内置脚本清单
发布包在 resources/scripts/builtin/ 下自带了一批脚本,可以直接在 content 里按相对路径引用:
| 脚本文件 | 说明 |
|---|---|
youtube.js | Youtube 解锁检测 |
disney+.js | Disney+ 解锁检测 |
openai.js | OpenAI 解锁检测 |
netflix.js | Netflix 解锁检测 |
tiktok.js | Tiktok 解锁检测 |
wikipedia.js | 维基百科解锁检测 |
Claude.js | Claude 解锁检测 |
bilibili.js | Bilibili 解锁检测 |
copilot.js | 微软 Copilot 解锁检测 |
spotify.js | Spotify 解锁检测 |
viu.js | Viu 解锁检测 |
iprisk.js | IP 风险检测 |
dns.js | DNS 区域检测 |
hijack.js | 测速劫持检测 |
ssh22.js | SSH 22 端口相关检测 |
说明
hijack.js 是 v1.12.2 起加入的脚本,用于检测测速是否被劫持,需要 miaospeed 后端版本 > 4.6.2。它与内置测试项 TEST_HIJACK_DETECTION 的区别在于:TEST_HIJACK_DETECTION 不经过 js 脚本的 macro 兼容层,由 koipy 直接调用 miaospeed 的原生 macro 接口。
预留脚本名称
以下名称会被 koipy 识别为内置测试项。它们既可以写进 scriptConfig.scripts 里用于覆写排序或特殊逻辑,也可以直接写进 rules[].script 里使用。
| 测试项 | 描述 |
|---|---|
TEST_PING_RTT | TCP RTT(数据交换延迟测试) |
TEST_PING_CONN | HTTP 请求体感延迟测试 |
TEST_PING_MAX_CONN | HTTP请求体感最大延迟 |
TEST_PING_MAX_RTT | 最大RTT(往返时延峰值) |
TEST_PING_TOTAL_CONN | 总HTTP请求延迟(所有请求的累计值) |
TEST_PING_TOTAL_RTT | 总RTT(所有数据包往返时延总和) |
TEST_PING_SD_RTT | RTT标准差(延迟波动指标) |
TEST_PING_SD_CONN | HTTP请求延迟标准差(稳定性分析) |
TEST_PING_PACKET_LOSS | RTT丢包率(数据包丢失百分比) |
TEST_HTTP_CODE | 目标地址的HTTP状态码(如200、404等) |
SPEED_AVERAGE | 平均下行传输速度 |
SPEED_MAX | 最大下行传输速度 |
SPEED_PER_SECOND | 每秒实时下行传输速度 |
USPEED_AVERAGE | 平均上行速度 |
USPEED_MAX | 最大上行速度 |
USPEED_PER_SECOND | 每秒上行速度 |
UDP_TYPE | UDP协议过滤行为 / UDP端口通断测试 |
GEOIP_INBOUND | 入口拓扑测试(地理IP路径分析) |
GEOIP_OUTBOUND | 出口拓扑测试(地理IP路径分析) |
TEST_HIJACK_DETECTION | 测速劫持检测 |
说明
如果你只是想在规则里调用这些内置项,其实不一定非要先在 scriptConfig.scripts 里写一份;直接在 rules[].script 中写这些预留名称,当前源码也能识别。把它们显式写进 scriptConfig.scripts 的主要意义,是覆写 rank、统一管理、或让某些项出现在可选列表中。
注意
上行测速相关项(USPEED_*)需要后端把 option.apiVersion 写成 3,并且后端启动时带上 -upload 参数,否则不会真正生效。
GEOIP 特殊处理
解释
GEOIP_INBOUND和GEOIP_OUTBOUND是最特殊的两项。- 如果它们按
gofunc配置,koipy 会强制使用主端内置的 GEOIP 脚本内容。 - 如果它们按
gojajs配置,则可以把默认 GEOIP 脚本替换成你自己的脚本内容或脚本文件。
特性
- 想自定义拓扑 GEOIP 行为时,应使用
gojajs。 - 这两项当前不会出现在普通脚本选择器列表里。
- 拓扑相关结果在后端侧可能存在缓存,所以即使你换了脚本,也不一定每次都会立刻看到结果变化。
- 如果你指定的自定义 GEOIP 脚本路径非法、内容为空,或脚本本身执行失败,实际效果就不会符合预期;具体表现取决于后端当时的处理结果与缓存状态。
配置示例
yaml
scriptConfig:
scripts:
- type: gojajs
name: "GEOIP_INBOUND"
rank: 1
content: "resources/scripts/geo/my_geoip.js"
- type: gojajs
name: "GEOIP_OUTBOUND"
rank: 1
content: "resources/scripts/geo/my_geoip.js"关于 GEOIP 脚本的更多背景和缓存说明,可参考:
相关内容
与规则联动
解释
rules[].script填的是脚本名字数组。- 数组元素既可以是你在
scriptConfig.scripts里定义的普通脚本名,也可以是上面的预留名称。 - 任务开始时,koipy 会按这些名字找到脚本配置,解析文件内容,按
rank排序后统一发送给后端。
特性
- 规则里的
script不写时,通常需要在前端手动选择测试项。 - 规则写了
script后,可以省掉脚本选择步骤,直接形成固定测试套餐。 - 当规则同时引用自定义脚本和预留名称时,它们会按最终
rank混排。
配置示例
yaml
scriptConfig:
scripts:
- type: gojajs
name: "Youtube"
rank: 0
content: "resources/scripts/builtin/youtube.js"
rules:
- name: "流媒体连通性"
url: "https://example.com/sub"
script:
- "TEST_PING_RTT"
- "TEST_PING_CONN"
- "Youtube"编写脚本
如果你要自己写 gojajs 脚本,建议直接看这部分文档:
相关内容
以及:
相关内容
