工具
Core 的诊断工具都是控制接口里的方法。桌面应用在各个页面上调用它们,脚本也可以调用。 它们不是 Core 的命令行子命令。
| 工具 | 方法 | 需要正在运行的 Profile |
|---|---|---|
| 经节点的延迟测试 | proxy.testDelay | 是 |
| 经节点的 NAT 测试 | proxy.runNatTest | 是 |
| 本机公网 IP 和 NAT | core.probeHost | 否 |
| 主机位置 | core.locateHosts | 否 |
| DNS 查询 | dns.lookupDns、dns.queryDns | 是,且 Core 的 DNS 解析器必须在运行 |
| 目标命中哪条规则 | rules.match | 是 |
| SSH 服务器检查 | ssh.probe | 否 |
| SSH 服务器监控 | ssh.watchServer(流) | 否 |
| SSH 主机密钥 | ssh.scanHostKey | 否 |
| SSH 文件访问 | ssh.listFiles、ssh.readFile、ssh.writeFile 等 | 否 |
下面的请求字段按线上顺序列出;直接拼报文的客户端要带齐全部字段(见 结构体是按位置排列的数组)。
延迟测试
proxy.testDelay 经某个节点发送一次 HTTP 请求,报告耗时。
| 字段 | 应用默认值 | 说明 |
|---|---|---|
proxy_id | [[proxy]] 的名称;代理组、DIRECT、REJECT 返回 -32004 | |
protocol | tcp | 只接受 tcp |
url | 空 | 必须是 http://;为空时用 http://www.gstatic.com/generate_204 |
timeout_ms | 5000 | 限制在 100–60000,约束整个测试 |
expected_status | 200-399 | 视为成功的状态码 |
- 结果包含
ok、delay_ms(失败时为-1)和说明失败原因的message。 - 测试会沿着节点的
dialer-proxy链进行(见代理链)。 - 结果同时成为该节点最新的健康状态,应用的节点列表会显示它。
- 不同节点的测试可以并行。
经节点的 NAT 测试
proxy.runNatTest 经节点的 UDP 通道发送 STUN 请求。它不改变路由模式,也不改变任何代理组的选择。
| 字段 | 应用默认值 | 说明 |
|---|---|---|
proxy_id | [[proxy]] 的名称 | |
stun_server | stun.cloudflare.com:3478 | host:port,不能为空 |
timeout_ms | 5000 | 限制在 100–60000 |
- 结果包含
ok、udp_supported、nat_type、mapped_address、mapped_port、latency_ms(失败时为-1)、mapping_behavior、filtering_behavior和message。 - 节点必须能转发 UDP:Shadowsocks、VLESS、Hysteria2、TUIC 可以;Trojan 只要没写
udp = false就可以; SOCKS5 和 VMess 需要udp = true;HTTP 和 AnyTLS 不行(见代理)。 - 映射行为和过滤行为(RFC 5780)需要能返回
OTHER-ADDRESS的 STUN 服务器,例如stun.voipgate.com:3478。 用其他服务器时只报告映射地址,message会说明原因。
本机
core.probeHost 不需要任何字段,也不经过代理。它查询本机的公网 IP 及其城市、地区、国家和所属组织, 并判断本机所在的 UDP NAT 类型(full_cone、restricted_cone、port_restricted_cone、symmetric、 open_internet、symmetric_udp_firewall、udp_blocked 或 unknown)。需要几秒钟。
它从 Core 所在机器直接访问 ipinfo.io 获取地址,访问 stun.voipgate.com 做 NAT 测试。
主机位置
core.locateHosts 接受最多 64 个 IP 地址或主机名,不经代理到 ipinfo.io 查询每个的位置。主机名用系统解析器解析。 私有地址不查询。Core 运行期间结果会被缓存。
DNS 查询
两个方法都接受 name 和 type(A 或 AAAA,为空时是 A)。只有 Core 的 DNS 解析器在运行时才能用: 开启了增强模式,或启用了 [dns].listener(见 DNS);否则返回 -32007。
dns.lookupDns按被接管的查询那样解析域名,并报告决定它的规则、路由、应答的上游、查询经过的节点、 被接管的查询会不会得到 Fake-IP、耗时和 TTL。dns.queryDns只返回应答。
规则测试
rules.match 接受 target(主机名或 IP,可以带 :端口;IPv6 写成 [地址]:端口)和 network(tcp 或 udp), 报告会做出决定的规则、它的出站,以及是否先被绕过列表或路由模式决定。
它只看目标本身:不做 DNS 查询,所以 IP 规则不会命中主机名;也没有进程,所以进程规则永远不命中。
SSH 服务器工具
ssh.* 方法从 Core 所在的机器通过 SSH 连接服务器。它们不需要 Profile,所有构建都有。
指定服务器
每个方法都接受一个 ssh 目标:
| 字段 | 说明 |
|---|---|
alias | Core 所在机器 ssh config 里的 Host 条目;ssh.listConfigHosts 可以列出它们 |
host、port、username | 没有别名时直接指定目标 |
port_explicit | true 时 port 覆盖别名里的 Port |
password | 密码登录 |
private_key_path、private_key_passphrase | Core 所在机器上的私钥文件;为空时使用 SSH agent 和默认密钥 |
host_key_sha256 | 预期的主机密钥,OpenSSH 显示的 SHA256:<base64> 形式 |
- 不带
host_key_sha256的目标必须是别名,且其主机密钥已在 Core 所在机器的known_hosts里。 直接指定的目标不带它会被拒绝。 ssh.scanHostKey不登录,只读取服务器的主机密钥,方便你核对后固定下来。- 主机密钥不匹配时绝不重试。
- 尽量用别名配合 SSH agent 或加密的私钥,不要发送密码。
检查
ssh.probe 打开一个会话,运行只读命令后关闭。
categories(区分大小写):System、Distribution、CPU、Memory、Disk、Uptime、Network、Docker、Processes、Monitor。为空时运行前六项。未知或重复的类别会被拒绝。- 这些命令假定服务器是 Linux。
- 每项输出超过 32 KiB 时截断,并标注
[truncated]。 ok表示至少有一项成功;请检查success_count和每一项的ok。
监控
ssh.watchServer 是一个流。流存在期间它保持一个 SSH 会话,每 interval_ms(限制在 2 秒到 5 分钟之间)发送一个样本: 每个核心的 CPU、内存和 swap、磁盘、网络和磁盘速率、负载、运行时间,以及最忙的五个进程。
- 失败后 Core 在 5 秒后重连,之后加倍,最长 60 秒。登录被拒或主机密钥变化后不再重试(
retry_in_ms为0), 需要重新发起 watch。 - Core 同时最多保持 64 个 watch。
- 关闭流就会关闭会话。
文件
ssh.listFiles、ssh.makeDirectory、ssh.removeFile、ssh.moveFile、ssh.readFile、ssh.writeFile 和 ssh.closeFiles 通过 SFTP 工作。
- 路径用绝对路径;
ssh.listFiles的路径为空时列出登录用户的主目录。 - 数据以 Base64 传输,每次调用最多 1 MiB。
- 上传先写到目标旁边的隐藏临时文件,收到最后一块(
finish)时才替换目标,所以中断的上传不会在正式文件名下留下半个文件。 - Core 会为下一次调用保留 SFTP 会话,直到调用
ssh.closeFiles或空闲几分钟。
SSH 端口转发
接口里有 routing.setSshForward,但在当前的 Core 中端口转发用不了:
- 标准构建返回
-32007:SSH port forwarding is not available in this build。 - 用
SPECOLA_ENABLE_ADVANCED构建的版本接受这个调用,但从来没有任何转发被定义:Profile 里的ssh-port-forward、ssh-port-forwards和port-forwards段会告警后忽略,也没有其他来源提供转发。打开后什么也不会启动。
没有的工具
当前的 Core 没有 ICMP ping、分层连通性诊断、一次调用批量测试多个节点延迟,也没有远程服务器部署。 旧版为这些功能提供的 /api/v1/... HTTP 接口已不存在。应用里的延迟数据来自 proxy.testDelay 和 代理组的健康检查。
