Skip to content

Agent CLI

KnowSky404 edited this page Nov 12, 2026 · 8 revisions

Agent 命令参考

统一目录及旧版迁移见 目录迁移。先执行 sbv storage status --json;迁移或恢复需显式 --yes,普通操作不会静默迁移。

操作目录

先运行 sbv commands --json 获取当前脚本的完整操作目录,再以 sbv schema <operation-id> --json 读取该操作的参数、确认、并发/CAS、 输入契约、服务影响和敏感输出分类。兼容发现入口是 sbv agent commands --json 和 sbv agent schema <operation-id> --json。 离线阅读生成的命令操作目录。

规范入口使用 sbv <resource> <verb> ... --json,常用只读命令可用 sbv status --json、sbv nodes --json、sbv check --json 等短命令。 旧 sbv agent ... 保留相同结果和安全语义。sbv 或 sbv menu 打开菜单; 显式未知命令或多余参数会失败,不进入交互菜单。

目录中 automation=structured 才表示有结构化入口; automation=interactive_only 会给出遗留限制、原因与菜单位置; automation=legacy_cli 表示可执行但仍返回文本的既有入口。 features.* 表示产品能力,不保证对应写操作可以自动化。发现命令可以在 未安装服务或存在待恢复事务时使用;实际读写仍受权限、管理锁和事务保护。 操作描述不是覆盖所有协议记录的通用 JSON Schema;typed record 继续由各协议验证器校验。

所有机器命令显式带 --json,stdout 只输出一个 JSON 对象,进度写 stderr。 应检查退出码及 .ok;敏感结果不得写入共享日志。生产变更仍按运维手册的目标授权执行。

协议默认值与 HY2 伪装检测

新建支持 TCP 的协议实例默认开启 TFO;JSON 可用 listen.tcp_fast_open:false 显式关闭,替换时省略保留当前值,接管保留实际配置。AnyTLS 客户端不支持 TFO。 HY2 菜单新建默认开启 Salamander,JSON 写入保留显式 obfs 设置。

先执行 sbv hy2 masquerade-check --json 读取 REALITY SNI 候选; 用 --url https://目标域名 单独检测 HTTP(S) 可用性,再把选定 URL 写入私有 HY2 record。此命令只读,无需确认;不更改 HY2 证书域名,也不替代协议运行态验证。 Salamander 开启后普通 HTTP/3 客户端无法访问伪装站点。 详见协议默认值。

服务与分流命令

sbv service status --json
sbv service start --json --yes
sbv service stop --json --yes
sbv service restart --json --yes
sbv service logs --json --lines 100
sbv routing view --json
sbv routing nodes --json
sbv routing export --json
sbv routing validate --json --file draft.json
sbv routing apply --json --yes --file draft.json
sbv routing restore --json --yes --expected-fingerprint HASH
sbv routing recover --json --yes

主菜单服务控制与这些命令共用实现;实例、组件或规则待恢复事务会拒绝服务变更。

服务 start/restart 先校验配置并核对最终活动状态,stop 核对最终 inactive; 日志读取非 follow,默认 100 行,允许 1–1000 行,是敏感输出。 routing view 是脱敏摘要;export 返回敏感完整草稿,须从 .data.draft 提取原始对象写入操作者拥有、权限 0400/0600 的私有文件。validate 只验证草稿结构, 不替代实际 apply 中的目标核心配置与服务检查;apply 使用草稿 fingerprint 进行 CAS, restore 使用当前快照 fingerprint,recover 使用可信持久事务中的恢复条件。 私有输入和完整流程见运维手册。

常用命令

操作 命令
打开交互菜单 sbv
查看状态 sbv agent status --json
检查运行配置 sbv agent check --json
查看 Agent 能力 sbv agent capabilities --json
检查指定核心版本的升级条件 sbv agent upgrade-check --json 1.14.0

主要支持 VLESS + REALITY、普通 VLESS、Mixed、SOCKS、HTTP、Shadowsocks、Trojan、VMess、Hysteria2、Hysteria v1、AnyTLS、Snell、TUIC、NaiveProxy 和 ShadowTLS 入站。每种协议的运行条件、导出和验证范围见能力矩阵。

Agent 非交互命令

适合在 SSH 会话中查询状态、读取节点信息或执行受控操作。常用只读命令见上方;以下保留兼容命令示例与事务语义,完整参数和支持边界见生成的操作目录。

sbv agent capabilities --json
sbv agent upgrade-check --json 1.14.0
sbv agent upgrade --json 1.14.0 --yes
sbv agent status --json
sbv agent nodes --json
sbv agent links --json
sbv agent check --json
sbv agent doctor --json
sbv agent service restart --json --yes
sbv agent warp --json
sbv agent subman-sync --json
sbv agent component list --json
sbv agent component diagnose --json
sbv agent component export --json --id ID [--expected-revision N]  # 敏感输出
sbv agent component recover --json --yes --expected-revision N
sbv agent component takeover --json --yes --expected-revision N [--allow-public]
sbv agent component rebuild --json --yes --expected-revision N
sbv agent component create|replace --json --yes --expected-revision N --file component.json [--allow-public]
sbv agent component delete --json --yes --expected-revision N --id ID
sbv agent instance view <protocol> --json [--id ID] [--expected-revision N]
sbv agent instance diagnose <protocol> --json [--id ID] [--expected-revision N]
sbv agent instance export <protocol> --json [--id ID] [--expected-revision N]  # 敏感输出
sbv agent instance create|replace <protocol> --json --yes --expected-revision N --file record.json [--allow-public]
sbv agent instance delete|default <protocol> --json --yes --expected-revision N --id ID
sbv agent instance rebuild <protocol> --json --yes --expected-revision N
sbv agent instance takeover <protocol> --json --yes --expected-revision 0 [--allow-public]
sbv agent instance migrate mixed --json --yes --expected-revision N
sbv agent instance recover <protocol> --json --yes --expected-revision N
sbv update sbv
sbv update sing-box latest
sbv update sing-box 1.14.4

代码块中的 create|replace、delete|default 只是二选一记法,实际执行时 只保留一个操作词;<protocol> 替换为支持的协议 ID,并从同一状态快照 读取 --expected-revision。

其中 <protocol> 的只读入口支持 vless-reality、mixed、socks、http、shadowsocks、trojan、vmess、vless-plain、anytls、hy2、snell、tuic、hysteria、naive 和 shadowtls;写入口支持除 vless-reality 外的其余协议,只有 mixed 支持 migrate。view 和 diagnose 默认脱敏,export、links 与 subman-sync 应只在受信上下文使用。

  • capabilities:输出协议、历史功能入口与 mutation / sensitive / 确认要求,Agent 应先据此选择操作。旧 protocol_registry 保持兼容,并为每个协议增加只读 environment 核心版本/构建依赖观察;managed_registry 将普通协议与高级组件按 role 合并,使用 registry_kind 区分来源。协议级 available=null 仍表示尚未完成实例预检,validated.status=not_assessed 表示没有该实例的数据面验证;环境依赖满足不等于已部署或连接通过。
  • upgrade-check:目标为 1.14.4+ 且配置含旧路由 action: direct 时,返回 legacy.direct_action_count 和 blockers=["legacy_direct_action", ...],须先处理配置再升级。只读检查固定目标版本的升级资格,返回 ready、blockers[]、当前核心校验、配置 hash、已知弃用项和兼容性 warning;不会协调或迁移协议状态,也不下载目标二进制,真正的目标版本 sing-box check 在 upgrade 替换服务进程前执行。
  • upgrade:必须使用完整版本号和 --yes。创建持久备份后只替换核心二进制,逐字节保留服务端配置;备份清单覆盖全部普通 runtime 文件及 binary、sbv、service unit、metadata。每次实际变更返回 transaction.id、transaction.result_path 和 transaction.result_persisted,并在备份目录原子写入权限 0600 的 transaction-result.json。实际变更只有 result_persisted=true 才可接受事务状态;若目标版本已经安装,则返回 changed=false、transaction.status=not_attempted、reason=already_installed,且不会创建备份或事务文件。目标校验、版本、配置 hash 或服务状态不符合预期时尝试自动恢复旧二进制、意外变化的配置和升级前服务活动状态,返回非零与结构化回滚结果。仅当 rolled_back=true 且 rollback_ok=true 时才可视为自动恢复完成;error=rollback_failed 时必须停止并人工处理。
  • status:输出脚本/核心/服务/路径/已安装协议,并包含入站与出站栈、BBR、REALITY 实例与 QoS 计数,以及 SubMan 是否已配置;不返回凭据。索引、状态或 live 入站集合无法完整对应时返回非零及 protocol_index_untrusted / protocol_state_untrusted,不报告部分协议。
  • nodes:输出所有协议的安全摘要;REALITY、Mixed、SOCKS、HTTP、Shadowsocks、Trojan、VMess、Hysteria2、Hysteria v1、AnyTLS、Snell、TUIC、NaiveProxy 和 ShadowTLS 均逐实例输出,instance_revision 可用于下一次 CAS 写入;不包含 UUID、密钥、完整分享链接或密码,适合写入普通诊断日志。实例清单、状态与 live 入站不完整时不输出部分节点。
  • links:逐协议、逐 REALITY/Mixed/SOCKS/HTTP/Shadowsocks/Trojan/VMess/Hysteria2/Hysteria/AnyTLS/Snell/TUIC/NaiveProxy/ShadowTLS 实例输出完整连接材料,包括 VLESS/VMess/Hysteria2 分享链接、Mixed/SOCKS 链接,以及 Hysteria/AnyTLS/Snell/TUIC/NaiveProxy/ShadowTLS outbound JSON;Hysteria、AnyTLS、Snell、TUIC、NaiveProxy、ShadowTLS 分别返回 hysteria_standard_uri_unavailable、anytls_standard_uri_unavailable、snell_standard_uri_unavailable、tuic_standard_uri_unavailable、naive_standard_uri_unavailable、shadowtls_standard_uri_unavailable warning;Naive 还返回 naive_libcronet_required,仅在受信任上下文使用,并沿用与 nodes 相同的全有或全无清单门禁。Hysteria2 手动 Ed25519 证书会附带稳定的 warnings[].code,提示分享链接无法表达 1.14+ 客户端兼容开关。
  • warp:输出 Cloudflare Warp 状态(启用/路由模式/账户/自定义域名规则集统计),安全用于日常诊断。
  • check:执行 sing-box check 校验服务端配置,并返回 stdout、stderr、退出码和是否通过。
  • doctor:输出只读诊断报告,包含服务状态、路径存在性、协议状态和嵌入的配置校验结果。
  • service start|stop|restart:必须显式传入 --yes;start/restart 先校验配置,再执行 systemd 操作并核对最终状态。service status 只读,service logs 有界读取敏感日志。完整参数见操作目录。
  • subman-sync:非交互推送节点到 SubMan;配置缺失时返回结构化错误,不进入交互提示。API 失败时会在 last_error 返回稳定的 code、disposition、HTTP 状态与可用的 Retry-After,传输结果不确定时不会盲目重放写请求。Hysteria2、Trojan 与 VMess 使用独立逐实例/用户路径,Hysteria v1、TUIC、AnyTLS、Snell、NaiveProxy 明确跳过并返回原因;仅 TLS 系统信任且 URI 可无损表达的条目进入同步。
  • instance:管理结构化 Mixed/SOCKS/HTTP/Shadowsocks/Trojan/VMess/VLESS plain/AnyTLS/Hysteria2/Snell/TUIC/Hysteria/NaiveProxy/ShadowTLS 实例。view/diagnose 是共享锁保护的只读入口,默认脱敏;export 是敏感入口,返回完整 typed record 与连接材料。Agent 的连接材料按 127.0.0.1 生成,仅表示本机/受信上下文的连接基线,不是公网地址或可达性证明。rebuild 在精确 CAS 下修复受管配置漂移并递增 revision;takeover 只接管无 active typed state 的可无损 live inventory,默认拒绝公网监听,必须显式 --allow-public。migrate 仅把 Mixed legacy schema 1 转成 revision 1;create/replace/delete/default 使用 --expected-revision,凭据通过私有文件输入;删除最后一个实例后保留 revision tombstone,下一次写入不能把 CAS 重置为 0;recover 只处理可验证的未完成事务。首次全新安装仍写 legacy schema 1,直到显式迁移。
  • component:管理高级入站、Endpoint、可复用出站/分组、ACME provider、shared http_client、network namespace 和 typed route.rule_set。list/diagnose 只返回元数据、环境/资源和事务摘要;export 按 ID 返回完整记录,是敏感操作。create/replace/delete/takeover/rebuild/recover 使用独立 schema 1 revision/CAS 和持久事务目录 /root/.sing-box-vps/runtime.component-write.lock,候选会执行引用图、监听资源与目标核心 sing-box check;非回环监听、TUN、隧道和 OpenVPN server 需要 --allow-public。高级组件不进入普通节点分享、节点连接材料或 SubMan 同步。
  • instance <operation> socks:使用 view/diagnose/敏感 export 读取,以及 create/replace/delete/default/rebuild/takeover/recover、--expected-revision、typed record、共享事务和回滚边界管理独立 SOCKS;记录只表达 SOCKS 入站的监听/认证,不含 HTTP 或 TLS。migrate socks 明确返回 invalid arguments;已有 live SOCKS 配置应使用 takeover,不把 legacy .env migration 语义套到该预设。实例生命周期、两核心 check/runtime、菜单、接管和 Agent/export 回归及最终 Docker/TCP 门禁已通过,但不应从注册表存在推断为全协议目标完成。
  • instance <operation> http:操作与 SOCKS 相同,但完整记录必须包含 tls: {enabled:false} 或手工 TLS 的 enabled/server_name/certificate_path/key_path。非回环写入须显式 --allow-public,无 legacy migration。记录示例与限制见 Agent Runbook。HTTP TLS 节点的 shareable=false,不将空链接视为可用 URI。
  • instance <operation> shadowsocks:支持 create/replace/delete/default/recover 与 revision CAS,拒绝 migrate;记录包含 listen.network 和 authentication,完整示例见 Agent Runbook。nodes 不输出密钥;敏感的 links 返回逐用户 URI、outbounds 与限制 warning。
  • instance <operation> vmess:支持 create/replace/delete/default/recover 与 revision CAS,拒绝 migrate;记录包含 1–128 个唯一 name/UUID/security/alter_id 用户、TLS 信任和 typed V2Ray transport(none/http/ws/grpc/quic)。分享和 SubMan 仅接受 TLS 系统信任且 URI 可无损表达的用户;完整边界见 VMess 契约。
  • instance <operation> anytls:支持 create/replace/delete/default/recover 与 revision CAS,拒绝 migrate;记录包含 1–128 个唯一用户名/密码、必需手工 TLS 证书路径、server name、客户端 certificate/system 信任和出站策略。AnyTLS 没有标准分享 URI,links 返回凭据 outbound JSON 与 anytls_standard_uri_unavailable warning;nodes 不返回密码。legacy AnyTLS 的 ACME/provider 配置不自动迁移到 typed store,接管会拒绝无法无损表达的字段;完整边界见 AnyTLS 契约。
  • instance <operation> hy2:支持 create/replace/delete/default/recover 与 revision CAS,拒绝 migrate;记录包含 1–128 个唯一用户名/密码、ACME 自动签发或手工 TLS、certificate/system 客户端信任、可独立设置的 up_mbps/down_mbps、Salamander obfs、masquerade 和出站策略。新增协议和实例创建默认提供 ACME HTTP-01 / Cloudflare DNS-01;自动证书使用系统信任,已有 ACME/provider 参数在新增实例时无损保留;标准 Hysteria2 URI 按用户生成,证书信任、URI 大小、带宽/masquerade 和 Ed25519 客户端开关均返回结构化 warning;完整边界见 Hysteria2 契约。
  • instance <operation> hysteria:支持 create/replace/delete/default/recover 与 revision CAS,拒绝 migrate;记录包含 1–128 个唯一 name/auth_str 用户、必需手工 TLS、certificate/system 客户端信任、上下行 up_mbps/down_mbps、字符串 obfs 与 QUIC 参数。服务端渲染为 type: hysteria 的 UDP/QUIC 入站并自动加入 alpn:["h3"];客户端按用户输出完整 outbound JSON,links 返回 hysteria_standard_uri_unavailable,不执行 SubMan 同步。完整边界见 Hysteria 契约。
  • instance <operation> snell:支持 create/replace/delete/default/recover 与 revision CAS,拒绝 migrate;记录包含版本 5/6、PSK、0–128 个唯一用户 key、v5 none/http obfs(HTTP host 作为客户端元数据)或 v6 default/unshaped/unsafe-raw shaping。Snell listener 固定 TCP,UDP 业务依赖 packet API;节点连接材料逐用户保留 network:["tcp","udp"] outbound JSON,links 返回 snell_standard_uri_unavailable,不执行 SubMan 同步。完整边界见 Snell 契约。
  • instance <operation> tuic:支持 create/replace/delete/default/recover 与 revision CAS,拒绝 migrate;记录包含 1–128 个 UUID/密码用户、手工证书 TLS、客户端 certificate/system 信任、拥塞控制、auth timeout、heartbeat 和 zero-rtt。服务端是 QUIC/UDP 入站,udp_relay_mode (native/quic) 与 udp_over_stream 只在客户端出站生效,不会写入入站。客户端按用户输出完整 TUIC outbound JSON,links 返回 tuic_standard_uri_unavailable,不执行 SubMan 同步。完整边界见 TUIC 契约。
  • instance <operation> naive:支持 create/replace/delete/default/recover 与 revision CAS,拒绝 migrate;记录包含 1–128 个用户名/密码用户、手工 TLS、客户端 certificate/system 信任、listen.network、QUIC 拥塞控制、窗口、并发和额外 headers。服务端按 TCP/UDP 选择渲染 Naive 入站;客户端按用户输出完整 Naive outbound JSON,links 返回 naive_standard_uri_unavailable 和 naive_libcronet_required,不执行 SubMan 同步。完整边界见 NaiveProxy 契约。
  • instance <operation> shadowtls:支持 create/replace/delete/default/recover 与 revision CAS,拒绝 migrate;记录包含 v1/v2/v3 凭据、握手服务器与 SNI 映射、strict/wildcard SNI、客户端 certificate/system 信任和 loopback Mixed detour。服务端渲染 ShadowTLS 外层与隐藏的 loopback Mixed 内层;客户端按用户输出完整 outbound JSON,links 返回 shadowtls_standard_uri_unavailable,不执行 SubMan 同步。完整边界见 ShadowTLS 契约。
  • update sbv:从 GitHub 更新 /usr/local/bin/sbv 管理脚本;别名为 sbv update-sbv。
  • update sing-box [latest|x.y.z]:普通运维更新入口,逐字节保留现有配置,目标核心校验通过后才重启服务,失败明确返回非零;别名为 sbv update-sing-box [latest|x.y.z]。普通更新只要求核心、配置和服务文件齐全且当前核心 check 通过,不重建或自动修复协议状态;依赖齐全时跳过包管理器。目标为 1.14.4+ 时,旧路由 action: direct 在下载前被 legacy_direct_action 拦截。先备份,通过 component list 读取 revision,再由操作者执行独立的 component rebuild 迁移托管基线规则,并核对手工差异保留;手工规则需单独迁移为 action: route 和 outbound: direct。重建可能重启服务,不属于二进制更新。自动化升级优先使用上面的固定版本 agent upgrade。

Mixed 实例写入使用类型化记录文件;create 和 replace 必须通过 --file 提供一个完整 JSON 对象,不接受命令行凭据。示例(replace 时 id 和 tag 必须保持原值,不能借此改身份):

{
  "id": "main",
  "name": "办公 Mixed",
  "tag": "mixed-in",
  "listen": {"address": "127.0.0.1", "port": 1080},
  "authentication": {
    "enabled": true,
    "username": "proxy-user",
    "password": "请替换为私有凭据"
  },
  "outbound_policy": "default",
  "dependencies": []
}

记录只允许上述字段;listen、outbound_policy 和 dependencies 也会参与候选配置及依赖检查,当前 dependencies 必须为空数组。写入成功后,根状态标记为 CONFIG_SCHEMA_VERSION=2,结构化文件以 schema_version: 1、protocol: "mixed"、单调 revision、default_instance_id 和 instances[] 封装该记录。nodes/links 是只读发现入口,可用于找到实例 id/tag;若输出 instance_revision,写入 CAS 应使用它,否则应从同一状态快照读取 revision(当前 capabilities 只声明需要 revision,不提供当前值),不能用猜测值覆盖并发修改。recover 是例外:必须使用未完成事务 journal 中原始的 expected_revision,不能拿当前 store revision 冒充恢复条件。

交互式管理会话在整个菜单期间持有排他管理 flock;需要先选择菜单 0 退出会话,其他 Agent 读写才能取得同一管理锁。Agent 只读操作使用共享锁,写入使用排他锁;锁冲突或未完成事务会返回结构化错误,不会静默绕过锁。

实例结果的 transaction.firewall 保留后端可用性和脱敏诊断,并同步写入持久 result 文件;事务目录清理后仍可审计。unavailable 不代表已开放防火墙,也不代表公网业务已验证。

已有 1.13.x 主机应先运行 sbv update sbv 更新管理脚本,再调用 capabilities 与 upgrade-check。1.14 对旧版 inline tls.acme 和远程规则集 download_detour 会给出弃用 warning,但两者到 1.16 才移除,因此 warning 本身不会阻止 1.13→1.14;其他真实不兼容会在目标 1.14 二进制的 sing-box check 阶段阻止重启并触发回滚。

sbv 自更新的失败语义

sbv update sbv 和 sbv update-sbv 使用同一套事务流程:PRECHECK → STAGE → VALIDATE → BACKUP → COMMIT → POSTCHECK → CLEANUP。远程内容只会写入 /usr/local/bin 同目录的候选文件,候选必须通过非空/最小大小、预期 shebang、bash -n、唯一 SCRIPT_VERSION、项目身份和版本单调性校验,之后才会使用同目录原子 mv 提交。候选 SHA-256 仅用于本地提交前后完整性核对,不代表远端签名或供应链认证。

  • 下载或校验失败:changed=false、rollback_attempted=false,原有 sbv 的内容、权限和所有者保持不变;CLI 返回非零,交互菜单展示错误摘要后继续运行。
  • 当前版本相同且目标健康:安全 no-op,不会创建备份或替换目标文件。
  • 提交后 postcheck 失败:自动恢复备份,并再次校验旧版本、SHA-256、Bash 语法和执行权限,报告 rolled_back=true。
  • rollback_failed:自动恢复未通过,报告 manual_intervention_required=true,并保留 root-only 备份和候选恢复文件。请先按错误提示人工恢复并重新执行 bash -n、版本、SHA-256 与执行权限校验,再运行 sbv。

交互菜单 14 更新成功后会自动切换到新版管理菜单;如果磁盘文件已是最新版、当前进程仍运行旧版,也会切换。当前进程和文件都已是最新版时继续当前菜单。CLI 更新成功后正常退出,下次运行 sbv 即使用新版。自动切换失败时会保留当前菜单并提示退出后重新运行 sbv,已安装的更新仍然有效。错误摘要和脱敏诊断会写入 /root/.sing-box-vps/logs/sbv.log;日志写入失败不会覆盖原始更新错误。

首次从不含自动切换逻辑的旧版升级时,旧进程仍需退出后重新运行一次 sbv;进入新版后,后续菜单更新会自动切换。

Agent/Hermes 文档入口:

升级事务验收

升级前在 /root/.sing-box-vps/backups/upgrades/ 创建仅 root 可读的持久备份。实际升级只有 transaction.result_persisted=true 且 transaction.status=success 才能接受成功。目标已安装时是无变更结果:transaction.status=not_attempted、transaction.reason=already_installed,不要求不存在的事务文件。失败时按 rolled_back 与 rollback_ok 判断恢复结果,不以退出码代替回读。

媒体检测 system.media 仍为交互操作;WARP 模式仅复用正式服务已有且固定走 WARP 的认证入口,不能通过复制生产凭据建立检测隧道。前提和清理边界见管理菜单。

Clone this wiki locally