Repository navigation
Agent CLI
统一目录及旧版迁移见 目录迁移。先执行 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;敏感结果不得写入共享日志。生产变更仍按运维手册的目标授权执行。
新建支持 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 入站。每种协议的运行条件、导出和验证范围见能力矩阵。
适合在 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_unavailablewarning;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、sharedhttp_client、network namespace 和 typedroute.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.envmigration 语义套到该预设。实例生命周期、两核心 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_unavailablewarning;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、v5none/httpobfs(HTTP host 作为客户端元数据)或 v6default/unshaped/unsafe-rawshaping。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 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 的认证入口,不能通过复制生产凭据建立检测隧道。前提和清理边界见管理菜单。