Specola Core RESTful API 用户手册

当前版本不可用

本页描述的配置在当前版本的 Specola Core 中会被忽略或拒绝，仅作参考保留。当前支持的配置见 完整配置。

Specola Core 提供本地 IPC 和可选的 TCP REST 控制面。接口契约以 api/openapi.yaml 为准；本文说明 连接、认证、响应模型和常用资源。 [general].api-listen、[general].api-secret 及重启边界见基础配置。

1. 开启控制 API

本地 IPC 总是随 Core 启动：

• macOS/Linux：/tmp/specola-api.sock，权限为 0600；
• Windows：\\.\pipe\specola-api。

macOS/Linux 可以直接通过 Unix socket 调用，不需要开启 TCP 监听：

curl --unix-socket /tmp/specola-api.sock http://localhost/api/v1/health

要同时开启 TCP REST，在 [general] 中配置：

[general]
api-listen = "127.0.0.1:9090"
api-secret = "replace-with-at-least-32-random-bytes"

所有 REST 路径以 /api/v1 开头。服务使用 HTTP/1.1，每个连接处理一个请求后关闭；请求需要一个 Host，不支持 Transfer-Encoding，请求头上限 32 KiB、正文上限 1 MiB。非空正文应使用 JSON 并发送正确的 Content-Length。

curl -s http://127.0.0.1:9090/api/v1/health

2. 认证与网络边界

Release 构建为需要认证的远端请求启用 HMAC。以下实际对端可直接访问：IPv4 loopback、RFC 1918 私网（10/8、172.16/12、192.168/16）、IPv6 loopback 和 ULA（fc00::/7）。其他对端必须 提供 secret；环境变量 SPECOLA_REST_API_SECRET 会覆盖 TOML，长度须为 32–4096 字节。

Debug 构建不启用 HMAC，并拒绝把 TCP API 绑定到非 loopback 地址。不要据此把 Debug 行为当作 生产认证模型。

远端请求使用这些头：

Authorization: Specola-HMAC-SHA256 <64位小写十六进制签名>
X-Specola-Timestamp: <Unix秒>
X-Specola-Nonce: <32位小写十六进制随机数>

待签名内容由下面六行以实际换行符连接，最后一行后没有额外换行：

SPECOLA-HMAC-V1
timestamp
nonce
UPPER_METHOD
exact_target_including_query
sha256_hex(exact_body_bytes)

使用共享 secret 对上述字节做 HMAC-SHA256。时间与服务端相差不能超过 60 秒，nonce 不得重放。 下面的 Python 片段生成签名头：

import hashlib
import hmac
import secrets
import time

secret = b"replace-with-at-least-32-random-bytes"
method = "PATCH"
target = "/api/v1/runtime"
body = b'{"mode":"rule"}'
timestamp = str(int(time.time()))
nonce = secrets.token_hex(16)
body_digest = hashlib.sha256(body).hexdigest()
canonical = (
    f"SPECOLA-HMAC-V1\n{timestamp}\n{nonce}\n"
    f"{method.upper()}\n{target}\n{body_digest}"
).encode()
signature = hmac.new(secret, canonical, hashlib.sha256).hexdigest()

print("Authorization: Specola-HMAC-SHA256 " + signature)
print("X-Specola-Timestamp: " + timestamp)
print("X-Specola-Nonce: " + nonce)

签名中的 target、query 顺序和正文每个字节必须与实际请求完全一致。HMAC 提供认证和完整性，不加密 HTTP 内容；非 loopback 绑定应放在可信 LAN/VPN、防火墙或 TLS 反向代理后。/ui 静态资源不要求 HMAC。

部署和 SSH 探针还有额外保护：非 loopback 请求只要携带非空 SSH 密码或私钥口令就会返回 403， 即使来源在可信私网或签名正确。敏感认证材料只应通过 loopback 发送。

3. 响应与错误

一般成功响应：

{"ok": true, "result": {}}

一般错误响应：

{
  "ok": false,
  "error": {
    "status": 400,
    "code": "invalid_request",
    "message": "具体错误"
  }
}

没有响应体的修改操作可能返回 204 No Content；/metrics 返回文本。响应包含 X-Request-Id，客户端提供同名头时服务会沿用它，便于关联日志。工具类操作即使 HTTP 为 200， result.ok 也可能为 false，调用方仍需检查业务结果。

GET /api/v1/version 返回主机系统和物理内存信息，并不是 Core 构建版本；构建版本请使用 specola-core --version。

4. 资源索引

系统、观测与连接

方法与路径	用途
GET /health	健康状态。
GET /version	主机系统元数据。
GET /memory	Core 内存快照。
GET /traffic	流量统计。
GET /metrics	文本指标。
GET, DELETE /connections	查询或关闭全部匹配连接。
DELETE /connections/{id}	关闭指定连接。
GET /processes	已观察进程。
GET, PATCH /runtime	读取或修改运行模式、Enhanced Mode 等状态。
GET /route-stats	路由统计。
GET /route-stats/top-destinations	热门目标。

连接查询支持 limit、process_id、outbound 和 process_name；热门目标支持 limit。

代理与策略组

方法与路径	用途
GET /proxies	列出节点。
GET, PUT /proxies/{name}	读取或更新节点运行状态。
GET /proxies/{name}/delay	测试单节点延迟。
GET, POST /proxy-groups	列出或创建策略组。
GET, PUT /proxy-groups/{group_name}	读取或更新策略组。
PUT, DELETE /proxy-groups/{group_name}/select/{proxy_name}	固定或取消固定选择。

详见 Proxies 与 Proxy Groups。

配置与规则

方法与路径	用途
GET, PATCH, PUT /config	读取、补丁更新或加载配置。
POST /config/save	保存当前配置。
GET, POST, PUT /rules	查询、新增或替换规则。
PUT, DELETE /rules/{index}	更新或删除单条规则。
POST /rules/reorder	调整规则顺序。
GET /geo/{kind}	浏览或搜索 geosite / geoip 分类。
GET /geo/{kind}/{code}	搜索和分页浏览一个分类的域名表达式或 CIDR。
PUT /geo/{kind}	校验并导入本地 .dat，随后 reload；失败时回滚。

Geo 列表与详情支持 search、offset、limit；limit 默认 100，最大 500。导入请求体为 {"path":"/local/file.dat"}，相对路径相对当前配置目录解析。它会安装到当前配置的受管 resources/geosite.dat 或 resources/geoip.dat，不会在线修改 protobuf 条目。路由规则语义和 Geo 示例见 Rules。

网络

• POST /caches/fake-ip/flush、POST /caches/dns/flush：清空缓存；
• POST /dns/queries、GET /dns/results：DNS 查询和结果；
• GET /listeners：监听器状态。

DNS 结果支持 search 和 limit 查询参数。

DNS 配置、上游选择、Fake-IP 和缓存刷新语义见 DNS 用户手册。

Provider 与订阅

方法与路径	用途
GET /providers/proxies	列出 Proxy Provider。
GET /providers/proxies/{name}	读取一个 Proxy Provider。
POST /providers/proxies/{name}/refresh	刷新 Proxy Provider。
POST /providers/proxies/{name}/health-checks	健康检查 Provider 全部节点。
GET /providers/proxies/{provider}/{proxy}	读取 Provider 中的节点。
POST /providers/proxies/{provider}/{proxy}/health-checks	健康检查单个节点。
GET /providers/rules	列出 Rule Provider。
GET /providers/rules/{name}	读取 Rule Provider。
POST /providers/rules/{name}/refresh	刷新 Rule Provider。
GET, POST /subscriptions	列出或创建完整配置订阅。
DELETE /subscriptions/{name}	删除订阅。
POST /subscriptions/{name}/refresh	刷新并应用订阅。

完整 Provider 与订阅流程见 Provider 和 Subscription。

工具与事件

工具端点为 POST /latency-tests、POST /nat-tests、POST /diagnostics、POST /ssh-probes 和 POST /deployments，请求体与安全边界见 Tools。

事件端点为 GET /events/traffic、GET /events/logs、GET /events/memory，响应类型为 text/event-stream。当前实现每次请求返回一个 SSE 事件后关闭连接；持续观察的客户端应保存日志 sequence 并重连。日志请求支持 after_sequence、min_level 和 max_entries。

5. 修改运行状态示例

读取状态：

curl -s http://127.0.0.1:9090/api/v1/runtime

开启 Linux eBPF：

curl -sS -X PATCH http://127.0.0.1:9090/api/v1/runtime \
  -H 'Content-Type: application/json' \
  -d '{"enhanced_backend":"ebpf","enhanced_enabled":true}'

关闭 Enhanced Mode：

curl -sS -X PATCH http://127.0.0.1:9090/api/v1/runtime \
  -H 'Content-Type: application/json' \
  -d '{"enhanced_enabled":false}'

这些示例只适用于 loopback 或其他无需 HMAC 的可信实际对端。远端调用需加入第 2 节生成的三个头。