Skip to content
English下载

工具 ​

Core 的诊断工具都是控制接口里的方法。桌面应用在各个页面上调用它们,脚本也可以调用。 它们不是 Core 的命令行子命令。

工具方法需要正在运行的 Profile
经节点的延迟测试proxy.testDelay是
经节点的 NAT 测试proxy.runNatTest是
本机公网 IP 和 NATcore.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
protocoltcp只接受 tcp
url空必须是 http://;为空时用 http://www.gstatic.com/generate_204
timeout_ms5000限制在 100–60000,约束整个测试
expected_status200-399视为成功的状态码
  • 结果包含 ok、delay_ms(失败时为 -1)和说明失败原因的 message。
  • 测试会沿着节点的 dialer-proxy 链进行(见代理链)。
  • 结果同时成为该节点最新的健康状态,应用的节点列表会显示它。
  • 不同节点的测试可以并行。

经节点的 NAT 测试 ​

proxy.runNatTest 经节点的 UDP 通道发送 STUN 请求。它不改变路由模式,也不改变任何代理组的选择。

字段应用默认值说明
proxy_id[[proxy]] 的名称
stun_serverstun.cloudflare.com:3478host:port,不能为空
timeout_ms5000限制在 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 目标:

字段说明
aliasCore 所在机器 ssh config 里的 Host 条目;ssh.listConfigHosts 可以列出它们
host、port、username没有别名时直接指定目标
port_explicittrue 时 port 覆盖别名里的 Port
password密码登录
private_key_path、private_key_passphraseCore 所在机器上的私钥文件;为空时使用 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 和 代理组的健康检查。