Skip to content

SubMan Address Selection

KnowSky404 edited this page Nov 2, 2026 · 4 revisions

SubMan 地址选择规范

本规范约束 sing-box-vps 向 SubMan 推送节点时使用的连接地址。运行时实现以 install.sh 为准;连接设置见交互管理。

范围与术语

同一台 VPS 可以承载 IPv4、IPv6、双栈和仅供本机使用的不同实例。节点的连接地址必须与对应实例的监听能力一致,不能仅凭 VPS 有 IPv6 地址,就为只监听 IPv4 的实例发布 IPv6 节点。

信息 用途 能证明什么
主机 IP 栈 为未单独指定监听地址的旧配置选择默认入站栈 本机存在相应地址族;不证明公网可达
实例 listen.address 确定该实例允许发布的地址族或具体地址 配置声明的监听范围;不证明服务正在监听
全局 INBOUND_STACK_MODE 决定使用全局监听栈的旧配置和 REALITY 的地址选择 对这些入口生效的入站策略
公网 IP 探测 为通配监听地址提供客户端可填写的具体 IP 探测端点返回一个合法的同族地址;不证明入站可达
OUTBOUND_STACK_MODE 决定 VPS 解析域名和向目标拨号时的地址族策略 出站偏好;不决定分享给客户端的 VPS 地址
TLS server_name / SNI 验证服务端身份并携带 TLS 名称 与证书匹配的名称;不替代连接地址

本次修复限于地址探测、SubMan 候选地址及其同步编排,不修改实例监听地址、端口、TLS、系统协议栈、防火墙或服务生命周期。SubMan 本身的协议支持范围、URI 表达限制和 Workspace 身份校验保持现有契约。

选择规则

先读取已加载实例的监听地址,再查询所需地址族的公网 IP。结构化实例的 listen.address 会原样生成服务端配置,全局协议栈变更不会改写该字段,因此它对该实例具有优先权。

全部 14 个结构化代理协议的新建与追加安装默认单个 :: 监听,在 Linux sing-box 双栈 socket 模型下接受 IPv4/IPv6;不要在同端口额外添加 0.0.0.0 监听。已有实例和显式 0.0.0.0、具体 IP、回环地址保持原值;REALITY 与 legacy 入口实际监听仍遵循全局入站模式。此默认值不新增 SubMan 协议支持:仅已支持协议按探测成功的地址族生成候选,两族都成功时才产生 v4/v6 两条。默认值和验收要求见默认双栈监听契约。

入口类型或实例监听地址 候选连接地址 全局入站模式的作用
结构化实例 0.0.0.0 仅 IPv4 公网地址 不把实例扩大为 IPv6,也不替实例改为仅 IPv6
结构化实例 :: 或等价的全零 IPv6 写法 项目双栈监听模型允许的已探测 IPv4、IPv6 地址 不改写实例的显式通配监听配置
结构化实例的具体 IPv4 使用该地址 不替换为探测地址
结构化实例的具体 IPv6 使用该地址 不替换为探测地址
使用全局监听栈的入口,ipv4_only 仅 IPv4 公网地址 选择 IPv4
使用全局监听栈的入口,ipv6_only 仅 IPv6 公网地址 选择 IPv6
使用全局监听栈的入口,dual_stack 分别使用已探测 IPv4、IPv6 地址 两族分别生成候选

具体监听地址包括显式绑定的回环地址;保留这类地址不代表节点可从公网连接。0.0.0.0 和 :: 是监听通配地址,不能直接作为公网节点的连接地址。等价的全零 IPv6 写法按规范化后的通配地址处理,不能误当作具体节点地址。

:: 的候选规则沿用本项目的双栈监听模型,不宣称已验证内核、容器网络、提供商防火墙或客户端链路支持双栈。地址选择不能替代真实运行态或公网验收。

HY2 与 SNI

HY2 使用同一套监听和地址族选择规则,不再通过通用“IPv4 优先”探测绕过实例监听或全局入站策略。对同一 HY2 实例的 IPv4、IPv6 候选,用户、端口、认证及 TLS 参数来自同一实例,连接 IP 可以不同,SNI 保留配置的证书名称。

例如,证书名称为 hy2.example.com 的节点可以连接 203.0.113.10 并使用 hy2.example.com 作为 SNI;域名字段的存在不是强制发布 IPv4 或跳过 IPv6 的理由。

探测与失败语义

每个地址族依次查询已有探测端点;单次请求保留连接和总耗时限制。只有请求成功、响应去除两端空白后恰好是一个合法同族 IP 时,该端点才算成功。空响应、HTML、错误页面、域名、多个地址、错误地址族和不合法 IP 均不可进入分享 URI 或 SubMan payload;当前端点失败后才尝试下一个端点。

get_public_ipv4 和 get_public_ipv6 在没有有效地址时返回非零状态且不输出候选。通用 get_public_ip 优先返回有效 IPv4;全部 IPv4 端点失败或返回无效内容后,再尝试 IPv6;两族均失败时返回非零状态。它只用于允许通用回退的调用方,不能给已限定地址族的 SubMan 路径扩大范围。

  • 仅 IPv4 的候选不可因 IPv4 探测失败改用 IPv6;仅 IPv6 同理。
  • 双栈允许发布其中已探测成功的地址族;未探测到某族不代表该族远端旧节点应被删除。
  • 没有合法候选时,该实例同步必须报告失败,不能把零次写入计为成功。
  • 失败结果不得包含 Token、认证凭据、私钥或完整分享链接。
  • 候选选择失败不执行节点写入或旧键清理。允许其他独立实例继续同步,但最终结果应如实保留失败或部分成功。

节点身份与已有节点

地址族通过 IPv4、IPv6 标签传递给后续节点构建。现有外部键算法在地址族明确时使用 :v4、:v6 后缀,使同一实例的两个地址族具有不同身份;用户摘要、实例 ID 和前缀的原有规则继续生效。具体监听地址沿用现有“监听地址”标签和不带地址族后缀的身份,不因为本次修复改变已有具体地址节点的键。

externalKey 是更新身份,节点显示名称不是地址选择依据。结构化节点按地址族候选在原显示名后附加 -v4 或 -v6;具体绑定地址保留原显示名。这样同一实例的两族节点可直接区分,实际更新仍以外部键为准。用户或实例名称无需暴露认证信息,IPv6 在 URI 的主机位置使用方括号。地址族后缀、用户摘要等均计入完整外部键的 119 UTF-8 字节上限,不能通过静默截断改变身份。

旧键清理仍需要明确、受保护的目标身份和成功替代写入证据。既有 REALITY 旧键清理只能在本轮全部已选候选成功写入后执行;地址选择失败或候选写入未全部成功不得触发清理。本次修复不新增远端节点删除,也不根据某一族探测失败删除已有 :v4、:v6 节点。此前曾发布但已不符合监听能力的额外地址族节点,以及旧 HY2 无地址族后缀节点,可能继续保留;操作员应先核对新节点及旧节点身份,再明确删除不再需要的记录,不能仅凭新候选列表推断远端已经清理。

所有真实写入继续执行目标 Workspace Gist ID、revision/ETag、外部键及响应契约校验;写入结果不确定时先读取并对账,不盲目重发。节点更新不等于 SubMan 已重新发布订阅或 sing-box 文件。

验收示例

以下地址均为隔离测试数据,不能作为公网可达性证据。

输入或故障 预期结果
同一台双栈 VPS:VMess 监听 0.0.0.0,REALITY 使用全局双栈 VMess 仅产生 IPv4 候选,REALITY 分别产生 IPv4、IPv6 候选
结构化 HY2 监听 ::,两族探测成功 两族分别构建可识别的候选,SNI 保持同一配置名称
结构化 HY2 监听 0:0:0:0:0:0:0:0,两族探测成功 与 :: 相同,使用具体探测地址和 -v4、-v6 显示名
结构化实例绑定 2001:db8::20 精确保留此地址,不替换为默认公网 IPv4
全局仅 IPv6 的旧 HY2,两族探测均成功 仅选择 IPv6
仅 IPv4 的实例,IPv4 全部探测失败、IPv6 成功 报告该实例无候选,不发布 IPv6,不清理旧节点
双栈仅 IPv6 探测成功 只发布有效 IPv6 候选,不删除已有 IPv4 节点
第一个 IPv4 端点返回 HTML,第二个返回 203.0.113.10 仅输出第二个端点的合法 IPv4
通用探测的两个 IPv4 端点失败,IPv6 返回 2001:db8::10 get_public_ip 返回 IPv6,状态为成功
所有允许的探测均失败 返回失败,无伪造地址、无写入、无旧键清理
某个候选远端写入结果不确定 保留该结果,按既有读回对账流程处理,不当作替代节点已全部成功

验证边界

按 AGENTS.md 第 4.2 节 选择最小充分集合:公网 IP 探测的隔离测试、地址选择矩阵、受影响协议的 payload 与同步编排、SubMan API mock、语法、文档链接及版本一致性。修改配置生成或节点连接材料时,对受影响输出执行 sing-box check;只有实际改变监听、网络或生命周期时才追加对应真实 Docker 场景。

本地 mock、配置检查、隔离 Docker、真实 SubMan、公网链路和生产验收分别记录。此规范不是对真实 VPS 或 SubMan 数据的验收报告,也不以创建 PR 或更新版本为理由要求全量协议回归。

2026-10-30 的补充验收已覆盖真实 SubMan 应用/SQLite 存储中的五协议、30 个用户/地址候选,以及明确授权的生产 Workspace 中六个 VMess 候选和独立测试聚合。改名后节点 ID、外部键及聚合成员保持,原业务和发布文件不变,临时数据已清理;具体监听、IPv4/IPv6 选择与本地 URI 名称一致性同时核对。冻结运行时、应用提交、生产范围及证据边界见统一命名验收记录。该结果仍不代表生产代理主机或所有公网协议链路已部署验收。

Clone this wiki locally