Specola Core Tools 用户手册

当前版本不可用

本页的 HTTP 示例使用的 REST 接口在当前版本的 Specola Core 中已不存在，Core 改为通过 MessagePack RPC 控制。本页仅作参考保留。

Core 的 Tools 是 REST/IPC 控制面中的诊断和部署操作，不是 specola-core 的 CLI 子命令。本文覆盖延迟测试、NAT 映射测试、分层诊断、SSH 信息采集和远端服务部署。连接与 HMAC 认证见 RESTful API。

以下示例假设 REST 仅监听 127.0.0.1:9090。

1. 批量延迟测试

bash

curl -sS -X POST http://127.0.0.1:9090/api/v1/latency-tests \
  -H 'Content-Type: application/json' \
  -d '{
    "node_names": ["node-a", "node-b"],
    "url": "https://www.gstatic.com/generate_204",
    "timeout_ms": 5000,
    "expected_status": "200-399"
  }'

也可以传 group_name 测试一个策略组；节点和组都不指定时测试全部节点。timeout_ms 范围为 100–60000，URL 必须为空或使用 HTTP/HTTPS。expected_status 支持单个状态、范围和以逗号或斜杠分隔的组合，例如 200/204-206,301。

结果逐项返回 node_name、latency_ms 和 ok；失败项的延迟为 -1。HTTP 请求成功只表示测试任务已执行，仍应检查外层 result.ok 和每个节点。

传入 group_name 会取消该 select、url-test 或 fallback 组的手动固定选择，使其回到自动选择后再测试。这是有状态副作用；只想测节点且不改变组状态时应使用 node_names。

2. NAT 映射测试

POST /api/v1/nat-tests 使用 STUN 返回公网 UDP 映射。mode = "direct" 从本机物理网络直连； mode = "proxy" 时还必须提供 proxy_name，请求固定通过该节点且不会修改全局路由或策略组选择。

bash

curl -sS -X POST http://127.0.0.1:9090/api/v1/nat-tests \
  -H 'Content-Type: application/json' \
  -d '{
    "mode": "proxy",
    "proxy_name": "node-a",
    "stun_server": "stun.cloudflare.com:3478",
    "timeout_ms": 5000
  }'

成功结果包含 mapped_address、mapped_port 和 latency_ms。HTTP 200 只表示工具已运行，还要检查 result.ok；节点必须支持 UDP。单个 STUN 服务只能观察映射，不能可靠分类 Cone 或 Symmetric NAT。完整说明见 NAT 映射测试。

3. 分层网络诊断

bash

curl -sS -X POST http://127.0.0.1:9090/api/v1/diagnostics \
  -H 'Content-Type: application/json' \
  -d '{
    "target_domain": "example.com",
    "proxy_name": "node-a"
  }'

字段都可省略。诊断按层检查：

配置是否加载且至少有一个用户代理节点；
到公共目标的基线直连 TCP；
target_domain 的 DNS 解析；
直连 HTTP 204 探测；
显式节点或当前规则的路由选择；
到节点服务端的 TCP endpoint 可达性。

Hysteria2、TUIC 等 QUIC 节点会跳过 TCP endpoint 探测。该工具用于定位配置、DNS、基础网络、路由和 endpoint 层次，不等价于完整的协议握手、认证或真实业务流量测试。仅含内置 DIRECT/REJECT 的配置也会在“用户代理节点”检查失败。

4. SSH 信息探针

优先复用 ~/.ssh/config 中的 alias：

bash

curl -sS -X POST http://127.0.0.1:9090/api/v1/ssh-probes \
  -H 'Content-Type: application/json' \
  -d '{
    "ssh": {"alias": "my-vps"},
    "categories": ["System", "Network", "Docker"]
  }'

也可以显式传 host、port、username、private_key_path 和 host_key_sha256。直连模式必须提供用户名，并用 OpenSSH 形式的固定指纹 SHA256:<base64> 验证主机，除非显式启用不安全跳过选项。alias 模式会解析 SSH config 和 known_hosts。

可选类别区分大小写：System、Distribution、CPU、Memory、Disk、Uptime、 Network、Docker、Processes。省略时默认执行前六项。探针只运行只读命令，不安装软件；同一时间只允许一个探针任务，否则返回 409。

单字段输出超过 16 KiB、总输出超过 64 KiB 时会截断并标记 [truncated]。result.ok 表示至少一个探针成功，不代表全部成功；应检查 success_count 和各项结果。

密码、私钥口令等秘密只能从 loopback 请求提交。优先使用 SSH agent、受权限保护的 key 和 alias，不要把凭证直接写进 shell history。

5. 部署远端代理服务

部署会修改远端主机、写入本地客户端配置并执行连通性测试，属于有状态操作。操作前备份客户端配置，保留远端控制台或第二个管理员会话，并确认防火墙已开放所需 UDP/TCP 端口。

sing-box/Hysteria2 示例：

bash

curl -sS -X POST http://127.0.0.1:9090/api/v1/deployments \
  -H 'Content-Type: application/json' \
  -d '{
    "ssh": {"alias": "my-vps"},
    "server_engine": "sing-box",
    "server_host": "vpn.example.com",
    "tls_server_name": "vpn.example.com",
    "remote_server_dir": "/opt/specola-server",
    "node_prefix": "my-vps",
    "client_config_path": "/absolute/path/personal.toml",
    "server_script_path": "/absolute/path/specola/tool/server/specola-singbox-server.sh",
    "protocols": ["hysteria2"],
    "server_port": 443
  }'

当前 API 调用应显式提供 server_engine、remote_server_dir、node_prefix 和至少一个 protocols。server_host 省略时可使用 SSH 主机；server_port 只允许在单协议部署时指定，多协议部署使用互不冲突的内置端口。

支持组合

sing-box：Shadowsocks 2022（shadowsocks-2022/ss2022/shadowsocks）、VMess、VLESS、 Trojan、Hysteria2（hysteria2/hy2）、TUIC、AnyTLS、SOCKS5 和 HTTP；
xray：只支持单个 VLESS Reality Vision 部署。

远端脚本支持 Linux amd64/arm64，并从 GitHub 下载当前稳定版 sing-box 或 Xray，因此远端需要 curl 以及相应的 tar/unzip。SSH 用户必须是 root 或可无密码执行 sudo -n。远端目录必须是安全的绝对路径，不能为 /。

源码仓库中的部署脚本位于 tool/server/。不同构建或发行包不保证脚本已经复制到可执行文件旁，因此推荐像示例一样显式设置 server_script_path，并在调用前确认文件存在。

部署事务和校验

部署过程会备份远端脚本、配置和证书，失败时尝试回滚；本地客户端配置以原子方式更新，并把生成节点合并进 personal 组。相同 node_prefix 已由另一种 engine 管理时会拒绝覆盖。

sing-box 未提供自定义证书时会生成证书材料；自定义证书和 key 必须成对提供。Xray 使用 Reality，不使用这组 TLS 文件。部署结束后 Core 默认启动临时本地代理并运行 SOCKS5/HTTPS 连通性测试；只有明确接受“未验证部署”时才设置 skip_connectivity_test = true。

同一时间只允许一个部署任务，否则返回 409。部署成功不表示云防火墙或宿主防火墙已经放行端口，应根据返回结果单独核对。

不要在生产环境使用 insecure_skip_host_key_check、insecure_skip_host_key_mismatch 或跳过证书验证的选项。HMAC 不加密 SSH 密码，含密码或私钥口令的请求只允许走 loopback。

6. 选择正确工具

目标	工具
比较节点响应时间	`/latency-tests`
对比本机直连与指定代理的公网 UDP 映射	`/nat-tests`
判断问题在配置、DNS、直连、路由还是 endpoint	`/diagnostics`
只读收集远端系统信息	`/ssh-probes`
安装/更新远端服务并写入本地节点	`/deployments`

节点字段见 Proxies，策略组行为见 Proxy Groups，命令行启动和配置校验见 CLI。

Specola Core Tools 用户手册 ​

1. 批量延迟测试 ​

2. NAT 映射测试 ​

3. 分层网络诊断 ​

4. SSH 信息探针 ​

5. 部署远端代理服务 ​

支持组合 ​

部署事务和校验 ​

6. 选择正确工具 ​

Specola Core Tools 用户手册

1. 批量延迟测试

2. NAT 映射测试

3. 分层网络诊断

4. SSH 信息探针

5. 部署远端代理服务

支持组合

部署事务和校验

6. 选择正确工具