Repository navigation
SubMan Address Selection
本规范约束 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 使用同一套监听和地址族选择规则,不再通过通用“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 名称一致性同时核对。冻结运行时、应用提交、生产范围及证据边界见统一命名验收记录。该结果仍不代表生产代理主机或所有公网协议链路已部署验收。