更新日期:2026-11-12。本文是项目交接入口,事实和测试结果以对应提交为准。
XNode 对接官方 Xboard 面板,保留面板推送和轮询的自动更新能力。落地机可在本地 config.yml 配置 Trojan TCP+TLS fallback;面板更新用户、节点端口、路由等数据时,本地 fallback 规则继续进入生成的内核配置。兼容性检查应拒绝把配置有 fallback 的节点改成非 Trojan、非 TCP 或 Reality,避免误以为 fallback 仍有效。
同时持续核对 Xray-core、sing-box 官方代码及 Xboard 面板接口,逐项升级、测试,不以版本号较新作为合并依据。
- 本 fork:
PiPi-happy/XNode,dev分支,当前基线7abd6d5,发布标签v1.14.1;依赖与健康接口加固尚待发布为v1.14.3。 - 上游节点后端:
cedar2025/Xboard-Node,dev分支,审查时618263a。本 fork 已增加机器模式、证书、热更新等大量代码,不能直接用上游覆盖。 - 官方面板:
cedar2025/Xboard,核对版本d826a3b。 - 当前
go.mod使用 Go1.27、Xray-corev1.260327.1-0.20261031132019-a4a3dff5b20c和 sing-boxv1.14.4;两个内核均直接使用官方模块,不再依赖 fork 替换。CI 与 Docker builder 锁定 Go1.27.4。
kernel:
type: xray # 也支持 singbox
fallbacks:
- dest: "127.0.0.1:8080"
- alpn: h2
dest: "127.0.0.1:8082"dest 必须是明确的 host:port;空 alpn 是默认目标。http/1.1 使用默认目标,h2 使用指定目标。每个 ALPN 只允许一条规则。Xray 使用 inbound settings.fallbacks;sing-box 使用 fallback 和 fallback_for_alpn。有 ALPN 规则时,TLS 会通告相应 ALPN;默认目标与 h2 共存时也通告 http/1.1。回落目标必须由独立的 HTTP 服务提供,XNode 不负责安装网站。sing-box 会为配置的回落目标生成优先直连规则;若目标是本机管理端口,已认证的代理用户也可能访问该端口,因此只应指向可公开访问的回落网站端口。
配置属于本地 kernel,不从 Xboard API 读取。顶层设置由多实例继承,静态多节点可通过 nodes[].kernel.fallbacks 覆盖。机器模式目前共用实例的规则;若同一机器上不同节点需要不同回落目标,应使用多个实例或后续增加按节点 ID 的映射。
- 解析无效地址、端口或重复 ALPN 时拒绝启动。
- 面板推送或轮询更新兼容的 Trojan 节点后,生成的两种内核配置仍包含本地 fallback。
- 面板改为不兼容协议、传输或 Reality 时拒绝该更新,并保留已运行配置。
- HTTP/1.1 与 h2 的 HTTPS 请求分别到达本地目标;Trojan 正确用户仍能连接。
- 本地配置、双内核生成、兼容性校验与单元测试;两种实际内核的配置解析器均接受生成结果。
- 本机真实连接集成测试:两种内核的 HTTP/1.1 与 h2 请求均到达预期回落服务,正确密码的 Trojan 连接也成功。测试命令:
go test -tags integration -timeout 30s ./internal/kernel/integration。 - 香港 Linux 实机从公网请求
gcphkb.dodoasclothing.uk:10221:TLS SNI 下 HTTP/1.1 与 h2 均回落到主站并返回 200;从 Xboard 当前用户集读取凭据,标准 Trojan 认证和 TCP 转发成功(目标站返回 301)。Nginx 回源分别监听127.0.0.1:8080和127.0.0.1:8082。 - Xboard 将节点端口从
10121改为10221后,XNode 已拉取新端口;本地 fallback 规则保持不变,健康检查和新端口下 HTTP/1.1、h2、有效 Trojan 请求均通过。错误 Trojan 密码测试返回 400。 - 用户已通过浏览器访问
gcphkb.dodoasclothing.uk:10221并确认显示主站。不同客户端对错误 Trojan 凭据的探测行为仍不作为 HTTP fallback 验收条件。
- 官方 Xboard
ServerService::buildNodeConfig仍发送protocol、networkSettings、tls_settings、custom_outbounds、custom_routes、cert_config等字段;当前internal/panel/types.go可接收这些字段。 - Xboard 扩展配置的代表性 JSON 契约测试覆盖网络设置、TLS、路由、自定义出站、证书和 multiplex/brutal;AnyTLS
padding_scheme的字符串和数组格式均有测试。真实运行面板 API 响应的脱敏样本尚未归档。协议列表审查发现 Xray 已有 HTTP 与 SOCKS inbound 生成器但运行时支持列表遗漏,已补齐列表和回归测试。 - 官方 Xboard 的机器节点接口使用
POST /api/v2/server/machine/nodes;fork 的机器模式代码已改为 POST。 - 官方 sing-box Trojan inbound 定义
fallback和fallback_for_alpn;官方 Xray-core Trojan/VLESS 定义fallbacks。 - 升级前直接切换官方 sing-box 时会因 fork 热更新 API 不兼容而无法编译;此问题已在迭代 3 改为官方 API,并通过配置重启实现兼容。
- 升级前官方 Xray-core 缺少 fork 的
features/bandwidth;此问题已在迭代 3 将限速适配移入 XNode dispatcher 后解决。 - 当前 fork 的 CI 原用 Go 1.25.7(低于
go.mod的 1.26)、发布和升级指向cedar2025。已把 CI 工具链、镜像命名空间、安装脚本和xbctl下载地址改为本 fork。 - fork 的 PR 目标分支是
dev,原 CI 未监听该分支;Docker 发布任务也会在 PR 上尝试写入。已补上devPR 测试,并限定镜像发布只在 push 上运行。 - Xray Trojan 在证书自动启用 TLS 时曾修改传入的面板节点对象;已改为复制对象后生成配置,避免影响缓存的面板状态。
- sing-box 默认的私网地址阻断规则会把
127.0.0.1回落也阻断;已增加只匹配配置目标和 Trojan inbound 的优先直连规则,并用真实 TLS 回落请求复验。
- 官方 sing-box
v1.14.4已完成适配和升级。 - 官方 Xray-core
v1.260327.1-0.20261031132019-a4a3dff5b20c已完成适配和升级。 - 依赖更新后通过本机
go test ./...、race 测试、go vet ./...、go mod tidy -diff和 Linux amd64/arm64 交叉构建。 - GitHub Actions 已完成
v1.14.1标签及dev分支验证:全仓测试、fallback 集成测试、Linux amd64/arm64 构建和 Release 发布成功。 - 安装脚本已使用本 fork
devRelease 资产;devRelease 的 arm64 资产已更新。若下载仍收到 504,可稍后重试同一 URL,或下载版本标签资产验证网络链路。 - 使用真实 Xboard 面板导出脱敏节点配置,补充 API 响应契约样本并覆盖目前未出现的字段变体。
- 香港落地机的公网 HTTP/1.1/h2 回落和有效 Trojan 凭据测试已通过,详情见迭代 4。
- Xboard 节点端口更新后 fallback 保留已在香港实机验证。
- 用户已用浏览器打开新节点端口并确认显示主站。
- 阅读本文件、
config.yml.example和相关提交。 - 确认当前
go.mod的require与replace,勿跳过 fork 差异直接删除替换。 - 在独立分支升级一个内核,先编译和运行该内核测试,再运行全仓测试。
- 用官方 Xboard 的实际 API 响应测试热更新,并在 Linux 节点验证 fallback 和代理连接。
- 每次迭代更新本文的基线、结论、验证命令和未解决风险。
- Xboard:https://github.com/cedar2025/Xboard
- xboard-node:https://github.com/cedar2025/Xboard-Node
- Xray fallback:https://xtls.github.io/en/config/features/fallback.html
- sing-box Trojan inbound:https://sing-box.sagernet.org/configuration/inbound/trojan/
- 当前开发分支:
codex/core-dependency-updates;该提交已合入远端dev,main保留上一个正式基线。 - 目标内核:官方 sing-box
v1.14.4;官方 Xray-corev26.10.31(Go 伪版本v1.260327.1-0.20261031132019-a4a3dff5b20c)。fork 替换已移除。 - Xray fork 的 bandwidth feature 已移到 XNode dispatcher:保留原始 Reader,在 Writer 上使用按用户共享的 limiter;同时适配上游 Xray UUID、Shadowsocks cipher API。
- sing-box fork 的运行时
UpdateRules、UpdatableInbound和 InboundManager 移除/关闭 API 已改为官方接口;配置和用户变更执行整盒重启,启动失败时恢复旧配置。限速/设备限制元数据在仅限制变化时仍刷新。 - Go 依赖已通过
go get -u ./...更新并 tidy;Vultr libdns 驱动与 govultr 最新版本不兼容,暂时固定 govultrv3.20.0以保留 DNS API 行为。 - CI 和 Docker builder Go 工具链改为 1.27。
- 已通过:
go test ./...、go test -race -count=1 ./internal/...、go mod tidy -diff,以及 Linux amd64/arm64 构建。GitHub Actions 的 tag/dev 全仓测试、fallback 集成测试、两架构构建及 Release 均成功。 - Xray Trojan TLS fallback 集成测试通过:HTTP/1.1 与 h2 请求回落到 backend;有效 Trojan 用户请求也能到达 backend。测试明确放行 Xray freedom outbound 的
127.0.0.0/8,因为 Xray 默认会黑洞 Trojan 访问私网地址;这只在集成测试配置中设置,不改变生产默认策略。 - 当前主机为 macOS,sing-box 完整集成测试启动时曾被系统 DNS 监听注册拒绝(
watch DNS configuration ... status 9);2026-11-12 本机完整 fallback 集成测试已通过。GitHub Linux CI 上两内核 fallback 集成测试也已通过。 - 上游稳定版本核对:官方 Xray-core
v26.10.31、sing-boxv1.14.4,Go1.27.3;sing-box1.15.0-alpha.13是预发布版本,暂不作为生产升级目标。
- 目标机运行 XNode
7abd6d5(v1.14.1),内核为 sing-box,Trojan inbound 初始端口10121。 - 发现 Docker fallback 容器已运行,但
/etc/xboard-node/config.yml的实例kernel.fallbacks为空,XNode 与 Nginx 回源原先未接通。已备份配置并设置默认回落127.0.0.1:8080、ALPNh2回落127.0.0.1:8082;配置热加载/重启成功,健康检查返回 200。 - 从本地公网客户端请求
https://gcphkb.dodoasclothing.uk:10121/:HTTP/1.1 返回主站 200,HTTP/2 返回主站 200;两次都直连该落地机公网 IP。 - 使用当前 Xboard 用户 UUID 作为 Trojan 凭据进行标准握手和 TCP 转发,目标站返回 301,确认有效 Trojan 用户仍可代理连接。
- 2026-11-11,用户在 Xboard 将节点端口改为
10221;XNode 拉取配置后监听更新,新端口的 HTTP/1.1 和 h2 回落仍返回 200,当前面板用户的 Trojan 转发仍成功。错误密码测试返回 400;该测试不是普通 HTTPS 探测请求,普通 HTTPS 探测已返回主站 200。 - 用户自用的一键安装工具不属于本仓库发布内容;README 仅记录 XNode 本地 fallback 的配置契约和部署要求。
- 尚待:在干净 Linux 主机上完成一次端到端部署回归。
- README 中英文版已说明 fallback 的适用协议、node/machine 模式与内核类型关系、服务监听要求、机器模式继承行为和健康检查端口限制。
- 静态安全审阅发现的加固项:面板 API token 会依 Xboard API 契约出现在部分请求参数中,面板连接应使用 HTTPS 并避免在代理/访问日志记录敏感 query;Docker 现存安装不会由本地 fallback 工具自动升级,应持续修补宿主机 Docker。2026-11-12 health check 已改为只绑定
127.0.0.1,远程监控需通过 SSH 隧道或受限代理访问。 - fallback 只处理匹配的 Trojan TCP+TLS TLS 握手并提供普通网站回落,不能承诺抵御所有主动探测或封禁。
- 本环境最初没有 Go 工具链;已在临时目录安装官方 Go
1.27.4,并通过govulncheck ./...(No vulnerabilities found)。CI 已加入固定版本govulncheck v1.9.0。
- Xray-core 保持官方稳定版
v26.10.31,sing-box 保持官方稳定版v1.14.4;未升级预发布版。 - Go 工具链升级到
1.27.4;Docker builder 更新为golang:1.27.4-alpine3.24,运行时基础镜像更新为alpine:3.24.4。 go get -u ./...更新当前源码实际使用且兼容的依赖。Vultr DNS providergithub.com/libdns/vultr/v2 v2.0.4与最新govultr/v3.34.0编译不兼容,因此暂留govultr/v3.20.0;其余有兼容更新的依赖已更新。- 已通过 Go
1.27.4的go test ./...、go test -race -count=1 ./internal/...、fallback 集成测试、go vet ./...、Linux amd64/arm64 交叉构建和govulncheck ./...。 - health check 从
0.0.0.0:<port>改为127.0.0.1:<port>。XNode 节点及 Xboard 通信不变;外部监控无法直接连此端口,使用 SSH 隧道/本机受限代理。