From fe1dd9ec959ac0432a4b2e8684b6b05817e21790 Mon Sep 17 00:00:00 2001 From: Peter Tang Date: Sun, 8 Nov 2026 11:41:55 +0800 Subject: [PATCH 1/2] feat: add local Trojan fallback across kernels and repair fork delivery --- .github/workflows/ci.yml | 16 +- Dockerfile | 2 +- Makefile | 5 +- README.md | 39 ++-- cmd/xbctl/main.go | 8 +- config.yml.example | 6 + docs/PRD.md | 86 +++++++++ install.sh | 8 +- internal/config/config.go | 68 +++++-- internal/config/fallback_test.go | 35 ++++ internal/kernel/integration/fallback_test.go | 183 +++++++++++++++++++ internal/kernel/singbox/config.go | 52 ++++++ internal/kernel/singbox/fallback_test.go | 43 +++++ internal/kernel/xray/config.go | 36 +++- internal/kernel/xray/fallback_test.go | 46 +++++ internal/service/service.go | 5 + internal/service/service_test.go | 31 +++- 17 files changed, 619 insertions(+), 50 deletions(-) create mode 100644 docs/PRD.md create mode 100644 internal/config/fallback_test.go create mode 100644 internal/kernel/integration/fallback_test.go create mode 100644 internal/kernel/singbox/fallback_test.go create mode 100644 internal/kernel/xray/fallback_test.go diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ce917ccd..fce29c76 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,7 +5,7 @@ on: branches: [main, master, dev] tags: ["v*"] pull_request: - branches: [main, master] + branches: [main, master, dev] env: FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true @@ -20,12 +20,15 @@ jobs: - name: Set up Go uses: actions/setup-go@v5 with: - go-version: '1.25.7' + go-version: '1.26' cache: true - name: Run tests run: make test + - name: Test Trojan fallback over TLS + run: make test-integration + build: name: Build runs-on: ubuntu-latest @@ -43,7 +46,7 @@ jobs: - name: Set up Go uses: actions/setup-go@v5 with: - go-version: '1.25.7' + go-version: '1.26' cache: true - name: Build @@ -72,6 +75,7 @@ jobs: name: Build & Push Docker Image runs-on: ubuntu-latest needs: test + if: github.event_name == 'push' permissions: contents: read packages: write @@ -98,9 +102,9 @@ jobs: push: true platforms: linux/amd64,linux/arm64 tags: | - ghcr.io/cedar2025/xboard-node:latest - ghcr.io/cedar2025/xboard-node:${{ github.sha }} - ${{ startsWith(github.ref, 'refs/tags/') && format('ghcr.io/cedar2025/xboard-node:{0}', github.ref_name) || '' }} + ghcr.io/pipi-happy/xnode:latest + ghcr.io/pipi-happy/xnode:${{ github.sha }} + ${{ startsWith(github.ref, 'refs/tags/') && format('ghcr.io/pipi-happy/xnode:{0}', github.ref_name) || '' }} release: name: Release diff --git a/Dockerfile b/Dockerfile index 07303dc0..8d6a145d 100644 --- a/Dockerfile +++ b/Dockerfile @@ -33,7 +33,7 @@ WORKDIR /etc/xboard-node # -e apiHost=https://panel.example.com \ # -e apiKey=YOUR_TOKEN \ # -e nodeID=1 \ -# ghcr.io/cedar2025/xboard-node:latest +# ghcr.io/pipi-happy/xnode:latest # # Supported env vars: # apiHost / API_HOST → panel URL diff --git a/Makefile b/Makefile index 2f5c9ca0..bc671596 100644 --- a/Makefile +++ b/Makefile @@ -2,7 +2,7 @@ VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo dev) BUILD_TIME ?= $(shell date -u +%Y-%m-%dT%H:%M:%SZ) LDFLAGS := -s -w -X main.version=$(VERSION) -X main.buildTime=$(BUILD_TIME) -X main.commit=$(shell git rev-parse --short HEAD 2>/dev/null || echo unknown) -.PHONY: build clean test docker install build-linux build-linux-arm64 build-all +.PHONY: build clean test test-integration docker install build-linux build-linux-arm64 build-all # Build for current platform build: @@ -26,6 +26,9 @@ build-all: build-linux build-linux-arm64 test: go test -v -race -count=1 ./internal/... +test-integration: + go test -tags integration -timeout 30s ./internal/kernel/integration + # Clean build artifacts clean: rm -f xboard-node xbctl xboard-node-linux-* xbctl-linux-* diff --git a/README.md b/README.md index 32cc9aee..e7918979 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# xboard-node +# XNode -Node backend for [Xboard](https://github.com/cedar2025/Xboard). Supports `sing-box` / `xray-core` dual kernels. +Fork of xboard-node for the official [Xboard](https://github.com/cedar2025/Xboard) panel. Supports `sing-box` / `xray-core` dual kernels. > **Disclaimer**: This project is for educational and learning purposes only. @@ -19,28 +19,26 @@ Node backend for [Xboard](https://github.com/cedar2025/Xboard). Supports `sing-b ```bash docker run -d --restart=always --network=host \ -e apiHost=https://panel.com -e apiKey=TOKEN -e nodeID=1 \ - ghcr.io/cedar2025/xboard-node:latest + ghcr.io/pipi-happy/xnode:latest ``` -### Docker Compose - -```bash -git clone -b compose --depth 1 https://github.com/cedar2025/xboard-node.git -cd xboard-node -vim config/config.yml # set panel.url / token / node_id -docker compose up -d -``` +The fork image is published by this repository's CI. Mount a local `config.yml` into +`/etc/xboard-node/config.yml` when using `kernel.fallbacks`. ### Installer (Linux systemd) ```bash # Node mode -curl -fsSL https://raw.githubusercontent.com/cedar2025/xboard-node/dev/install.sh | \ +curl -fsSL https://raw.githubusercontent.com/PiPi-happy/XNode/dev/install.sh | \ sudo bash -s -- --mode node --panel https://panel.example.com --token TOKEN --node-id 1 # Machine mode -curl -fsSL https://raw.githubusercontent.com/cedar2025/xboard-node/dev/install.sh | \ +curl -fsSL https://raw.githubusercontent.com/PiPi-happy/XNode/dev/install.sh | \ sudo bash -s -- --mode machine --panel https://panel.example.com --token TOKEN --machine-id 1 +``` + +The installer downloads this fork's `dev` release by default. For reproducible +deployments, pass `--version ` after publishing a tagged release. ## xbctl @@ -59,6 +57,21 @@ xbctl service restart Legacy single-panel config is fully compatible. Appending bindings auto-migrates to `instances` format. See `config.yml.example`. +Local Trojan TCP+TLS fallback is configured only in `config.yml`, never from panel data: + +```yaml +kernel: + type: xray # or singbox + fallbacks: + - dest: "127.0.0.1:8080" + - alpn: h2 + dest: "127.0.0.1:8082" +``` + +Run a local HTTP/1.1 service on 8080 and an h2c-capable service on 8082. The +fallback rules survive compatible panel updates. Switching the node away from +Trojan TCP+TLS is rejected while local fallbacks are enabled. See [PRD](docs/PRD.md). + ## Extensions - Custom routes: [docs-custom-routes.md](docs-custom-routes.md) diff --git a/cmd/xbctl/main.go b/cmd/xbctl/main.go index 4a05d669..62d92da5 100644 --- a/cmd/xbctl/main.go +++ b/cmd/xbctl/main.go @@ -30,7 +30,7 @@ const ( serviceName = "xboard-node.service" serviceFilePath = "/etc/systemd/system/xboard-node.service" defaultInstallRoot = "/etc/xboard-node" - downloadBase = "https://github.com/cedar2025/xboard-node/releases" + downloadBase = "https://github.com/PiPi-happy/XNode/releases" ) var ( @@ -54,7 +54,7 @@ type fileRootConfig struct { WS *config.WSConfig `yaml:"ws,omitempty"` Runtime *fileRuntimeConfig `yaml:"runtime,omitempty"` Cert *config.CertConfig `yaml:"cert,omitempty"` - Instances []fileInstance `yaml:"instances,omitempty"` + Instances []fileInstance `yaml:"instances,omitempty"` } type fileInstance struct { @@ -386,7 +386,7 @@ func runUpgrade(args []string) error { return err } - version := "latest" + version := "dev" for i := 0; i < len(args); i++ { if args[i] == "--version" && i+1 < len(args) { version = args[i+1] @@ -1157,7 +1157,7 @@ func latestInstanceID(instances []*config.Config) string { func regenerateServiceFile() error { unit := fmt.Sprintf(`[Unit] Description=Xboard Node Backend -Documentation=https://github.com/cedar2025/xboard-node +Documentation=https://github.com/PiPi-happy/XNode After=network-online.target Wants=network-online.target diff --git a/config.yml.example b/config.yml.example index 030bb655..be7f1564 100644 --- a/config.yml.example +++ b/config.yml.example @@ -10,6 +10,12 @@ # ── Multiple instances ── # kernel: # type: "singbox" +# # 本地 Trojan TCP+TLS fallback;面板热更新不会覆盖。 +# # 目标需由本机 HTTP 服务监听,h2 目标需支持 h2c。 +# fallbacks: +# - dest: "127.0.0.1:8080" +# - alpn: "h2" +# dest: "127.0.0.1:8082" # log: # level: "info" # instances: diff --git a/docs/PRD.md b/docs/PRD.md new file mode 100644 index 00000000..3bbcdd5a --- /dev/null +++ b/docs/PRD.md @@ -0,0 +1,86 @@ +# XNode 产品与迭代记录 + +更新日期:2026-11-08。本文是项目交接入口,事实和测试结果以对应提交为准。 + +## 目标与范围 + +XNode 对接官方 Xboard 面板,保留面板推送和轮询的自动更新能力。落地机可在本地 `config.yml` 配置 Trojan TCP+TLS fallback;面板更新用户、节点端口、路由等数据时,本地 fallback 规则继续进入生成的内核配置。兼容性检查应拒绝把配置有 fallback 的节点改成非 Trojan、非 TCP 或 Reality,避免误以为 fallback 仍有效。 + +同时持续核对 Xray-core、sing-box 官方代码及 Xboard 面板接口,逐项升级、测试,不以版本号较新作为合并依据。 + +## 代码基线 + +- 本 fork:`PiPi-happy/XNode`,`dev` 分支,审查基线 `0a29338`。 +- 上游节点后端:`cedar2025/Xboard-Node`,`dev` 分支,审查时 `618263a`。本 fork 已增加机器模式、证书、热更新等大量代码,不能直接用上游覆盖。 +- 官方面板:`cedar2025/Xboard`,审查时默认分支 `d826a3b`。 +- 当前 `go.mod`:Xray-core 声明 `v1.260327.0`,实际通过 `replace` 使用 `cedar2025/Xray-core` 的 `f479355`;sing-box 声明 `v1.13.2`,实际通过 `replace` 使用 `cedar2025/sing-box` 的 `2e665cb`(1.14.0 alpha 2 派生版)。因此不能只看 `require` 行判断运行内核版本。 + +## 迭代 1:本地 fallback + +### 配置契约 + +```yaml +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 正确用户仍能连接。 + +### 当前状态 + +- [x] 本地配置、双内核生成、兼容性校验与单元测试;两种实际内核的配置解析器均接受生成结果。 +- [x] 本机真实连接集成测试:两种内核的 HTTP/1.1 与 h2 请求均到达预期回落服务,正确密码的 Trojan 连接也成功。测试命令:`go test -tags integration -timeout 30s ./internal/kernel/integration`。 +- [ ] Linux 实机集成测试:浏览器 HTTP/1.1/h2、错误密码、正确密码、面板热更新。 + +## 迭代 2:内核与面板适配 + +### 已核对 + +- 官方 Xboard `ServerService::buildNodeConfig` 仍发送 `protocol`、`networkSettings`、`tls_settings`、`custom_outbounds`、`custom_routes`、`cert_config` 等字段;当前 `internal/panel/types.go` 可接收这些字段。 +- 官方 Xboard 的机器节点接口使用 `POST /api/v2/server/machine/nodes`;fork 的机器模式代码已改为 POST。 +- 官方 sing-box Trojan inbound 定义 `fallback` 和 `fallback_for_alpn`;官方 Xray-core Trojan/VLESS 定义 `fallbacks`。 +- 官方 sing-box `v1.14.4` 替换当前 fork 时无法编译:缺少 `adapter.Router.UpdateRules`、`adapter.UpdatableInbound` 等 fork 专用热更新接口;需移植补丁或改写热更新后再升级。 +- 官方 Xray-core Go 模块 `v1.260327.0` 替换当前 fork 时无法编译:缺少 `features/bandwidth`;需移植限速补丁或重做该能力后再升级。 +- 当前 fork 的 CI 原用 Go 1.25.7(低于 `go.mod` 的 1.26)、发布和升级指向 `cedar2025`。已把 CI 工具链、镜像命名空间、安装脚本和 `xbctl` 下载地址改为本 fork。 +- fork 的 PR 目标分支是 `dev`,原 CI 未监听该分支;Docker 发布任务也会在 PR 上尝试写入。已补上 `dev` PR 测试,并限定镜像发布只在 push 上运行。 +- Xray Trojan 在证书自动启用 TLS 时曾修改传入的面板节点对象;已改为复制对象后生成配置,避免影响缓存的面板状态。 +- sing-box 默认的私网地址阻断规则会把 `127.0.0.1` 回落也阻断;已增加只匹配配置目标和 Trojan inbound 的优先直连规则,并用真实 TLS 回落请求复验。 + +### 待完成的升级门槛 + +- [ ] 对照官方稳定版 sing-box 1.14.4,解决 fork 特有 API、依赖图和测试差异后升级。 +- [ ] 对照官方 Xray-core 2026-10 系列;官方 Go 模块标签目前只列到 `v1.260327.0`,需确认目标 Git 提交、fork 特有补丁和模块兼容性。 +- [ ] 用实际面板响应样本覆盖新协议、证书和路由字段的契约测试。 +- [x] 本机 `go test ./...` 通过(Go 1.27.3,2026-11-08)。 +- [x] CI 同款 `make test`(全仓 race 检测)通过;新增 `make test-integration` 作为 CI 第二项测试。 +- [x] `go vet ./...`、Linux amd64 交叉编译(与 CI 相同构建标签)、`bash -n install.sh`、`git diff --check` 通过(2026-11-08)。 +- [x] Linux arm64 交叉编译通过(与 CI 相同构建标签)。 +- [ ] Linux 实机回归及 GitHub Actions 验证。 + +## 交接步骤 + +1. 阅读本文件、`config.yml.example` 和相关提交。 +2. 确认当前 `go.mod` 的 `require` 与 `replace`,勿跳过 fork 差异直接删除替换。 +3. 在独立分支升级一个内核,先编译和运行该内核测试,再运行全仓测试。 +4. 用官方 Xboard 的实际 API 响应测试热更新,并在 Linux 节点验证 fallback 和代理连接。 +5. 每次迭代更新本文的基线、结论、验证命令和未解决风险。 + +## 官方依据 + +- Xboard: +- xboard-node: +- Xray fallback: +- sing-box Trojan inbound: diff --git a/install.sh b/install.sh index 5107da7e..cfba4789 100755 --- a/install.sh +++ b/install.sh @@ -24,10 +24,10 @@ DEFAULT_HEALTH_PORT=65530 DEFAULT_KERNEL="singbox" DEFAULT_MODE="node" DEFAULT_ACTION="install" -DEFAULT_RELEASE_VERSION="latest" +DEFAULT_RELEASE_VERSION="dev" DEFAULT_LOG_LEVEL="info" DEFAULT_KERNEL_LOG_LEVEL="warn" -DEFAULT_DOWNLOAD_BASE="https://github.com/cedar2025/xboard-node/releases" +DEFAULT_DOWNLOAD_BASE="https://github.com/PiPi-happy/XNode/releases" ACTION="${DEFAULT_ACTION}" MODE="" @@ -186,7 +186,7 @@ usage() { OPTIONAL: --node-type, -T Explicit node type for node mode --kernel, -k singbox or xray (default: singbox) - --version Release version or latest (default: latest) + --version Release version or latest (default: dev) --binary Use a local xboard-node binary path instead of downloading --xbctl-binary Use a local xbctl binary path instead of downloading --health-port Local health port (default: 65530, use 0 to disable) @@ -592,7 +592,7 @@ render_service() { cat >"$TMP_DIR/${SERVICE_NAME}" < 65535 { + return fmt.Errorf("kernel.fallbacks[%d].dest has invalid port", i) + } + } + return nil } // RuntimeConfig tunes Go runtime memory behaviour. @@ -142,6 +170,8 @@ type KernelConfig struct { // customization of dns, outbounds, endpoints, route, experimental, etc. // Compatible with V2bX OriginalPath format. CustomConfig string `yaml:"custom_config"` + // Fallbacks are applied to Trojan TCP+TLS inbounds after panel updates. + Fallbacks []FallbackConfig `yaml:"fallbacks,omitempty"` } type CertConfig struct { @@ -507,6 +537,9 @@ func (c *Config) inheritFrom(parent *Config) { if c.Kernel.CustomConfig == "" { c.Kernel.CustomConfig = parent.Kernel.CustomConfig } + if c.Kernel.Fallbacks == nil { + c.Kernel.Fallbacks = parent.Kernel.Fallbacks + } if len(c.Kernel.CustomOutbound) == 0 { c.Kernel.CustomOutbound = parent.Kernel.CustomOutbound } @@ -717,6 +750,11 @@ func (c *Config) validate() error { if n.NodeID <= 0 { return fmt.Errorf("nodes[%d].node_id must be positive", i) } + if n.Kernel != nil { + if err := validateFallbacks(n.Kernel.Fallbacks); err != nil { + return fmt.Errorf("nodes[%d]: %w", i, err) + } + } } } switch c.Kernel.Type { @@ -724,6 +762,9 @@ func (c *Config) validate() error { default: return fmt.Errorf("kernel.type must be 'singbox' or 'xray', got '%s'", c.Kernel.Type) } + if err := validateFallbacks(c.Kernel.Fallbacks); err != nil { + return err + } if c.Cert.AutoTLS && c.Cert.Domain == "" { return fmt.Errorf("cert.domain is required when cert.auto_tls is enabled") } @@ -771,6 +812,9 @@ func (c *Config) ExpandNodes() []*Config { if entry.Kernel.CustomConfig != "" { nodeCfg.Kernel.CustomConfig = entry.Kernel.CustomConfig } + if entry.Kernel.Fallbacks != nil { + nodeCfg.Kernel.Fallbacks = entry.Kernel.Fallbacks + } } else { // Auto-derive a unique config_dir per node to avoid conflicts. nodeCfg.Kernel.ConfigDir = fmt.Sprintf("%s/node-%d", c.Kernel.ConfigDir, entry.NodeID) diff --git a/internal/config/fallback_test.go b/internal/config/fallback_test.go new file mode 100644 index 00000000..1ff544cb --- /dev/null +++ b/internal/config/fallback_test.go @@ -0,0 +1,35 @@ +package config + +import "testing" + +func TestLocalFallbacksInheritAndValidate(t *testing.T) { + path := writeTemp(t, ` +kernel: + type: xray + fallbacks: + - dest: "127.0.0.1:8080" + - alpn: h2 + dest: "127.0.0.1:8082" +instances: + - panel: + url: https://panel.example.com + token: secret + node_id: 1 +`) + root, err := LoadRoot(path) + if err != nil { + t.Fatal(err) + } + if got := root.Instances[0].Kernel.Fallbacks; len(got) != 2 || got[1].ALPN != "h2" || got[1].Dest != "127.0.0.1:8082" { + t.Fatalf("inherited fallbacks: %#v", got) + } + for _, bad := range [][]FallbackConfig{ + {{Dest: "8080"}}, + {{Dest: "127.0.0.1:0"}}, + {{ALPN: "h2", Dest: "127.0.0.1:8080"}, {ALPN: "h2", Dest: "127.0.0.1:8082"}}, + } { + if err := validateFallbacks(bad); err == nil { + t.Errorf("accepted invalid fallback: %#v", bad) + } + } +} diff --git a/internal/kernel/integration/fallback_test.go b/internal/kernel/integration/fallback_test.go new file mode 100644 index 00000000..7961742f --- /dev/null +++ b/internal/kernel/integration/fallback_test.go @@ -0,0 +1,183 @@ +//go:build integration + +package integration_test + +import ( + "bufio" + "context" + "crypto/ecdsa" + "crypto/elliptic" + "crypto/rand" + "crypto/sha256" + "crypto/tls" + "crypto/x509" + "crypto/x509/pkix" + "encoding/hex" + "encoding/pem" + "io" + "math/big" + "net" + "net/http" + "net/http/httptest" + "net/url" + "path/filepath" + "strconv" + "testing" + "time" + + "github.com/cedar2025/xboard-node/internal/config" + "github.com/cedar2025/xboard-node/internal/kernel" + "github.com/cedar2025/xboard-node/internal/kernel/singbox" + "github.com/cedar2025/xboard-node/internal/kernel/xray" + "github.com/cedar2025/xboard-node/internal/model" + "golang.org/x/net/http2" + "golang.org/x/net/http2/h2c" +) + +func testCertificate(t *testing.T) (kernel.TLSCert, *x509.CertPool) { + t.Helper() + key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) + if err != nil { + t.Fatal(err) + } + template := &x509.Certificate{ + SerialNumber: big.NewInt(1), + Subject: pkix.Name{CommonName: "localhost"}, + DNSNames: []string{"localhost"}, + NotBefore: time.Now().Add(-time.Hour), + NotAfter: time.Now().Add(time.Hour), + KeyUsage: x509.KeyUsageDigitalSignature, + ExtKeyUsage: []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth}, + } + der, err := x509.CreateCertificate(rand.Reader, template, template, &key.PublicKey, key) + if err != nil { + t.Fatal(err) + } + privateDER, err := x509.MarshalECPrivateKey(key) + if err != nil { + t.Fatal(err) + } + certPEM := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der}) + keyPEM := pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: privateDER}) + pool := x509.NewCertPool() + pool.AppendCertsFromPEM(certPEM) + return kernel.TLSCert{CertPEM: certPEM, KeyPEM: keyPEM}, pool +} + +func freePort(t *testing.T) int { + t.Helper() + listener, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Fatal(err) + } + port := listener.Addr().(*net.TCPAddr).Port + listener.Close() + return port +} + +func TestTrojanTLSFallbackHTTP11AndH2(t *testing.T) { + backend := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Write([]byte("fallback-ok")) + })) + defer backend.Close() + backendURL, _ := url.Parse(backend.URL) + h2Backend := httptest.NewServer(h2c.NewHandler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Write([]byte("fallback-h2-ok")) + }), &http2.Server{})) + defer h2Backend.Close() + h2URL, _ := url.Parse(h2Backend.URL) + cert, roots := testCertificate(t) + + for _, name := range []string{"xray", "singbox"} { + t.Run(name, func(t *testing.T) { + kcfg := config.KernelConfig{ + Type: name, + ConfigDir: filepath.Join(t.TempDir(), "config"), + Fallbacks: []config.FallbackConfig{ + {Dest: backendURL.Host}, + {ALPN: "h2", Dest: h2URL.Host}, + }, + } + var node kernel.Kernel + if name == "xray" { + node = xray.New(kcfg) + } else { + node = singbox.New(kcfg) + } + port := freePort(t) + spec := &model.NodeSpec{Protocol: "trojan", Network: "tcp", ListenIP: "127.0.0.1", ServerPort: port, TLS: 1} + spec.CustomRouteRules = []model.CustomRouteRule{{Match: model.RouteMatch{IPCIDRs: []string{"127.0.0.1"}}, Action: model.RouteAction{Type: "direct"}}} + if err := node.Start(spec, []model.UserSpec{{ID: 1, UUID: "valid-password"}}, cert); err != nil { + t.Fatal(err) + } + defer node.Stop() + conn, err := tls.DialWithDialer(&net.Dialer{Timeout: 5 * time.Second}, "tcp", net.JoinHostPort("127.0.0.1", strconv.Itoa(port)), &tls.Config{ + RootCAs: roots, ServerName: "localhost", NextProtos: []string{"http/1.1"}, + }) + if err != nil { + t.Fatal(err) + } + defer conn.Close() + conn.SetDeadline(time.Now().Add(5 * time.Second)) + if _, err := conn.Write([]byte("GET / HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n")); err != nil { + t.Fatal(err) + } + response, err := http.ReadResponse(bufio.NewReader(conn), nil) + if err != nil { + t.Fatal(err) + } + defer response.Body.Close() + if response.StatusCode != http.StatusOK { + t.Fatalf("fallback status: %s", response.Status) + } + body, err := io.ReadAll(response.Body) + if err != nil || string(body) != "fallback-ok" { + t.Fatalf("fallback body = %q, error = %v", body, err) + } + + h2Client := &http.Client{Transport: &http2.Transport{ + AllowHTTP: true, + DialTLSContext: func(ctx context.Context, network, addr string, _ *tls.Config) (net.Conn, error) { + return tls.DialWithDialer(&net.Dialer{Timeout: 5 * time.Second}, "tcp", net.JoinHostPort("127.0.0.1", strconv.Itoa(port)), &tls.Config{ + RootCAs: roots, ServerName: "localhost", NextProtos: []string{"h2"}, + }) + }, + }} + h2Response, err := h2Client.Get("http://localhost/") + if err != nil { + t.Fatal(err) + } + defer h2Response.Body.Close() + h2Body, err := io.ReadAll(h2Response.Body) + if err != nil || h2Response.StatusCode != http.StatusOK || string(h2Body) != "fallback-h2-ok" { + t.Fatalf("h2 fallback status=%s body=%q error=%v", h2Response.Status, h2Body, err) + } + + validConn, err := tls.DialWithDialer(&net.Dialer{Timeout: 5 * time.Second}, "tcp", net.JoinHostPort("127.0.0.1", strconv.Itoa(port)), &tls.Config{ + RootCAs: roots, ServerName: "localhost", + }) + if err != nil { + t.Fatal(err) + } + defer validConn.Close() + validConn.SetDeadline(time.Now().Add(5 * time.Second)) + _, backendPortText, _ := net.SplitHostPort(backendURL.Host) + backendPort, _ := strconv.Atoi(backendPortText) + digest := sha256.Sum224([]byte("valid-password")) + request := append([]byte(hex.EncodeToString(digest[:])+"\r\n"), 1, 1, 127, 0, 0, 1, byte(backendPort>>8), byte(backendPort)) + request = append(request, []byte("\r\nGET / HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n")...) + if _, err := validConn.Write(request); err != nil { + t.Fatal(err) + } + validResponse, err := http.ReadResponse(bufio.NewReader(validConn), nil) + if err != nil { + t.Fatalf("valid Trojan connection failed: %v", err) + } + defer validResponse.Body.Close() + validBody, err := io.ReadAll(validResponse.Body) + if err != nil || validResponse.StatusCode != http.StatusOK || string(validBody) != "fallback-ok" { + t.Fatalf("valid Trojan status=%s body=%q error=%v", validResponse.Status, validBody, err) + } + }) + } +} diff --git a/internal/kernel/singbox/config.go b/internal/kernel/singbox/config.go index fe11766b..691bd2fb 100644 --- a/internal/kernel/singbox/config.go +++ b/internal/kernel/singbox/config.go @@ -74,6 +74,58 @@ func buildConfig(kcfg config.KernelConfig, nc *model.NodeSpec, users []model.Use } mergeCustomSingbox(cfg, kcfg) + if inbound != nil && len(kcfg.Fallbacks) > 0 && nc.Protocol == "trojan" { + alpn := M{} + advertised := make([]string, 0, len(kcfg.Fallbacks)) + hasDefault := false + tag := "_xnode_fallback_direct" + occupied := make(map[string]bool) + for _, outbound := range cfg["outbounds"].([]M) { + if value, ok := outbound["tag"].(string); ok { + occupied[value] = true + } + } + for occupied[tag] { + tag += "_" + } + cfg["outbounds"] = append(cfg["outbounds"].([]M), M{"type": "direct", "tag": tag}) + route := cfg["route"].(M) + rules := route["rules"].([]M) + fallbackRules := make([]M, 0, len(kcfg.Fallbacks)) + for _, fb := range kcfg.Fallbacks { + host, portText, _ := net.SplitHostPort(fb.Dest) // validated when local config is loaded + port, _ := strconv.Atoi(portText) + target := M{"server": host, "server_port": port} + rule := M{"inbound": []string{"trojan-in"}, "port": []int{port}, "outbound": tag} + if net.ParseIP(host) != nil { + rule["ip_cidr"] = []string{host} + } else { + rule["domain"] = []string{host} + } + fallbackRules = append(fallbackRules, rule) + if fb.ALPN == "" { + inbound["fallback"] = target + hasDefault = true + } else { + alpn[fb.ALPN] = target + advertised = append(advertised, fb.ALPN) + } + } + if len(alpn) > 0 { + inbound["fallback_for_alpn"] = alpn + } + if len(advertised) > 0 { + if hasDefault { + if _, ok := alpn["http/1.1"]; !ok { + alpn["http/1.1"] = inbound["fallback"] + advertised = append(advertised, "http/1.1") + } + } + inbound["fallback_for_alpn"] = alpn + inbound["tls"].(M)["alpn"] = advertised + } + route["rules"] = append(fallbackRules, rules...) + } return cfg } diff --git a/internal/kernel/singbox/fallback_test.go b/internal/kernel/singbox/fallback_test.go new file mode 100644 index 00000000..70d0dd09 --- /dev/null +++ b/internal/kernel/singbox/fallback_test.go @@ -0,0 +1,43 @@ +package singbox + +import ( + "context" + "encoding/json" + "testing" + + "github.com/cedar2025/xboard-node/internal/config" + "github.com/cedar2025/xboard-node/internal/kernel" + "github.com/cedar2025/xboard-node/internal/panel" + "github.com/sagernet/sing-box/include" + "github.com/sagernet/sing-box/option" + singJSON "github.com/sagernet/sing/common/json" +) + +func TestLocalFallbackSurvivesPanelRefresh(t *testing.T) { + kcfg := config.KernelConfig{Fallbacks: []config.FallbackConfig{ + {Dest: "127.0.0.1:8080"}, + {ALPN: "h2", Dest: "127.0.0.1:8082"}, + }} + for _, port := range []int{443, 8443} { + nc := testNodeSpec(&panel.NodeConfig{Protocol: "trojan", ServerPort: port, Network: "tcp", TLS: 1}) + cfg := buildConfig(kcfg, nc, testUsers, kernel.TLSCert{CertPEM: []byte("CERT"), KeyPEM: []byte("KEY")}) + inbound := cfg["inbounds"].([]M)[0] + fallback := inbound["fallback"].(M) + h2 := inbound["fallback_for_alpn"].(M)["h2"].(M) + if fallback["server"] != "127.0.0.1" || fallback["server_port"] != 8080 || h2["server_port"] != 8082 { + t.Fatalf("port %d: lost local fallback: %#v %#v", port, fallback, h2) + } + h1 := inbound["fallback_for_alpn"].(M)["http/1.1"].(M) + alpn := inbound["tls"].(M)["alpn"].([]string) + if h1["server_port"] != 8080 || len(alpn) != 2 || alpn[0] != "h2" || alpn[1] != "http/1.1" { + t.Fatalf("port %d: wrong TLS ALPN: %#v %#v", port, h1, alpn) + } + data, err := json.Marshal(cfg) + if err != nil { + t.Fatal(err) + } + if _, err := singJSON.UnmarshalExtendedContext[option.Options](include.Context(context.Background()), data); err != nil { + t.Fatalf("sing-box rejected fallback config: %v", err) + } + } +} diff --git a/internal/kernel/xray/config.go b/internal/kernel/xray/config.go index 1603f7b0..1c9c0772 100644 --- a/internal/kernel/xray/config.go +++ b/internal/kernel/xray/config.go @@ -81,9 +81,40 @@ func buildConfig(kcfg config.KernelConfig, nc *model.NodeSpec, users []model.Use cfg["routing"] = buildRouting(nc.Routes, nc.CustomRouteRules, mergeRouteList(nc.CustomRoutes, kcfg.CustomRoute)) mergeCustomXray(cfg, kcfg) + if inbound != nil && len(kcfg.Fallbacks) > 0 && nc.Protocol == "trojan" { + fallbacks := make([]M, 0, len(kcfg.Fallbacks)) + alpn := make([]string, 0, len(kcfg.Fallbacks)) + hasDefault := false + for _, fb := range kcfg.Fallbacks { + item := M{"dest": fb.Dest} + if fb.ALPN != "" { + item["alpn"] = fb.ALPN + alpn = append(alpn, fb.ALPN) + } else { + hasDefault = true + } + fallbacks = append(fallbacks, item) + } + inbound["settings"].(M)["fallbacks"] = fallbacks + if len(alpn) > 0 { + if hasDefault && !containsALPN(alpn, "http/1.1") { + alpn = append(alpn, "http/1.1") + } + inbound["streamSettings"].(M)["tlsSettings"].(M)["alpn"] = alpn + } + } return cfg } +func containsALPN(values []string, target string) bool { + for _, value := range values { + if value == target { + return true + } + } + return false +} + // outboundConfigToXray converts a structured OutboundConfig (from the panel) // into an Xray outbound object. Xray uses a nested layout where protocol- // specific fields go inside a "settings" key, and chain proxying uses "proxySettings". @@ -298,8 +329,9 @@ func buildTrojan(base M, nc *model.NodeSpec, users []model.UserSpec, tc kernel.T // we should enable a default TLS config to ensure the inbound can start. ss, _ := base["streamSettings"].(M) if security, ok := ss["security"].(string); !ok || (security != "tls" && security != "reality") { - nc.TLS = 1 // Force internal state to trigger TLS build in applyStreamSettings - applyStreamSettings(base, nc, tc) + withTLS := *nc + withTLS.TLS = 1 + applyStreamSettings(base, &withTLS, tc) } return base diff --git a/internal/kernel/xray/fallback_test.go b/internal/kernel/xray/fallback_test.go new file mode 100644 index 00000000..ad2b171f --- /dev/null +++ b/internal/kernel/xray/fallback_test.go @@ -0,0 +1,46 @@ +package xray + +import ( + "bytes" + "testing" + + "github.com/cedar2025/xboard-node/internal/config" + "github.com/cedar2025/xboard-node/internal/kernel" + "github.com/cedar2025/xboard-node/internal/panel" + "github.com/xtls/xray-core/infra/conf/serial" +) + +func TestLocalFallbackSurvivesPanelRefresh(t *testing.T) { + kcfg := config.KernelConfig{Fallbacks: []config.FallbackConfig{ + {Dest: "127.0.0.1:8080"}, + {ALPN: "h2", Dest: "127.0.0.1:8082"}, + }} + for _, port := range []int{443, 8443} { + nc := testNodeSpec(&panel.NodeConfig{Protocol: "trojan", ServerPort: port, Network: "tcp", TLS: 1}) + cfg := buildConfig(kcfg, nc, testUsers, kernel.TLSCert{CertPEM: []byte("CERT"), KeyPEM: []byte("KEY")}) + inbound := cfg["inbounds"].([]M)[0] + fallbacks := inbound["settings"].(M)["fallbacks"].([]M) + if len(fallbacks) != 2 || fallbacks[0]["dest"] != "127.0.0.1:8080" || fallbacks[1]["alpn"] != "h2" { + t.Fatalf("port %d: lost local fallback: %#v", port, fallbacks) + } + alpn := inbound["streamSettings"].(M)["tlsSettings"].(M)["alpn"].([]string) + if len(alpn) != 2 || alpn[0] != "h2" || alpn[1] != "http/1.1" { + t.Fatalf("port %d: wrong TLS ALPN: %#v", port, alpn) + } + data, err := marshalConfig(kcfg, nc, testUsers, kernel.TLSCert{CertPEM: []byte("CERT"), KeyPEM: []byte("KEY")}) + if err != nil { + t.Fatal(err) + } + if _, err := serial.LoadJSONConfig(bytes.NewReader(data)); err != nil { + t.Fatalf("xray rejected fallback config: %v", err) + } + } +} + +func TestTrojanTLSAutodetectDoesNotMutatePanelSpec(t *testing.T) { + nc := testNodeSpec(&panel.NodeConfig{Protocol: "trojan", ServerPort: 443, Network: "tcp"}) + _ = buildConfig(testKernelCfg, nc, testUsers, kernel.TLSCert{CertPEM: []byte("CERT"), KeyPEM: []byte("KEY")}) + if nc.TLS != 0 { + t.Fatalf("buildConfig changed panel TLS state to %d", nc.TLS) + } +} diff --git a/internal/service/service.go b/internal/service/service.go index 890940db..403901cf 100644 --- a/internal/service/service.go +++ b/internal/service/service.go @@ -1158,6 +1158,11 @@ func validateNodeRuntime(cfg *config.Config, kcfgSupported []string, spec *model if !containsString(kcfgSupported, spec.Protocol) { return fmt.Errorf("protocol %q is not supported by kernel %q", spec.Protocol, cfg.Kernel.Type) } + if len(cfg.Kernel.Fallbacks) > 0 { + if spec.Protocol != "trojan" || (spec.Network != "" && spec.Network != "tcp") || spec.TLS == 2 { + return fmt.Errorf("local kernel.fallbacks requires a Trojan TCP+TLS node; panel supplied protocol=%q network=%q tls=%d", spec.Protocol, spec.Network, spec.TLS) + } + } if err := validateTLSRequirements(spec, tls, cfgKernelType(cfg)); err != nil { return err } diff --git a/internal/service/service_test.go b/internal/service/service_test.go index 374ff7aa..9487bd4d 100644 --- a/internal/service/service_test.go +++ b/internal/service/service_test.go @@ -14,6 +14,24 @@ import ( "golang.org/x/time/rate" ) +func TestLocalFallbackRejectsIncompatiblePanelUpdate(t *testing.T) { + cfg := &config.Config{Kernel: config.KernelConfig{Type: "xray", Fallbacks: []config.FallbackConfig{{Dest: "127.0.0.1:8080"}}}} + cert := kernel.TLSCert{CertPEM: []byte("CERT"), KeyPEM: []byte("KEY")} + for _, spec := range []model.NodeSpec{ + {Protocol: "vless", Network: "tcp", TLS: 1}, + {Protocol: "trojan", Network: "ws", TLS: 1}, + {Protocol: "trojan", Network: "tcp", TLS: 2}, + } { + if err := validateNodeRuntime(cfg, []string{"trojan", "vless"}, &spec, cert); err == nil { + t.Errorf("accepted incompatible panel update: %+v", spec) + } + } + good := &model.NodeSpec{Protocol: "trojan", Network: "tcp", TLS: 1} + if err := validateNodeRuntime(cfg, []string{"trojan"}, good, cert); err != nil { + t.Fatalf("rejected compatible panel update: %v", err) + } +} + type fakeKernel struct { running bool @@ -34,8 +52,8 @@ type fakeKernel struct { deviceLimitFunc func(string) (int, bool) } -func (f *fakeKernel) Name() string { return "fake" } -func (f *fakeKernel) Protocols() []string { return []string{"vless"} } +func (f *fakeKernel) Name() string { return "fake" } +func (f *fakeKernel) Protocols() []string { return []string{"vless"} } func (f *fakeKernel) Capabilities() kernel.Capabilities { return kernel.Capabilities{} } func (f *fakeKernel) Start(nodeConfig *model.NodeSpec, users []model.UserSpec, tls kernel.TLSCert) error { _, _, _ = nodeConfig, users, tls @@ -46,7 +64,7 @@ func (f *fakeKernel) Start(nodeConfig *model.NodeSpec, users []model.UserSpec, t f.running = true return nil } -func (f *fakeKernel) Stop() { f.running = false } +func (f *fakeKernel) Stop() { f.running = false } func (f *fakeKernel) IsRunning() bool { return f.running } func (f *fakeKernel) Reload(nodeConfig *model.NodeSpec, users []model.UserSpec, tls kernel.TLSCert) error { _, _, _ = nodeConfig, users, tls @@ -92,9 +110,9 @@ func (f *fakeKernel) CloseUserConnections(ctx context.Context, uuid string) erro return nil } func (f *fakeKernel) SetSpeedLimitFunc(fn func(uuid string) *rate.Limiter) { f.speedLimitFunc = fn } -func (f *fakeKernel) SetDeviceLimitFunc(fn func(uuid string) (int, bool)) { f.deviceLimitFunc = fn } -func (f *fakeKernel) UpdateGlobalDevices(users map[int][]string) { _ = users } -func (f *fakeKernel) ClearGlobalDevices() {} +func (f *fakeKernel) SetDeviceLimitFunc(fn func(uuid string) (int, bool)) { f.deviceLimitFunc = fn } +func (f *fakeKernel) UpdateGlobalDevices(users map[int][]string) { _ = users } +func (f *fakeKernel) ClearGlobalDevices() {} func newTestService(k *fakeKernel) *Service { sharedLimiter := limiter.New() @@ -198,7 +216,6 @@ func TestApplyUserDeltaAddPreparesLimiterBeforeKernelUpdate(t *testing.T) { } } - func TestValidateNodeRuntimeRejectsUnsupportedDNSProvider(t *testing.T) { cfg := &config.Config{Kernel: config.KernelConfig{Type: "singbox"}} err := validateNodeRuntime(cfg, []string{"http"}, &model.NodeSpec{ From e98f97109f2ec86601f6b55c980cccd78062cb36 Mon Sep 17 00:00:00 2001 From: Peter Tang Date: Sun, 8 Nov 2026 12:01:25 +0800 Subject: [PATCH 2/2] docs: add Simplified Chinese README --- README.md | 2 ++ README.zh-CN.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+) create mode 100644 README.zh-CN.md diff --git a/README.md b/README.md index e7918979..0135966f 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # XNode +[简体中文说明](README.zh-CN.md) · English + Fork of xboard-node for the official [Xboard](https://github.com/cedar2025/Xboard) panel. Supports `sing-box` / `xray-core` dual kernels. > **Disclaimer**: This project is for educational and learning purposes only. diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 00000000..26a72700 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,65 @@ +# XNode + +[English](README.md) · 简体中文 + +XNode 是适配[官方 Xboard 面板](https://github.com/cedar2025/Xboard)的节点后端 fork,内置 Xray-core 和 sing-box 两种内核。支持面板 WebSocket 推送与 REST 轮询,面板更新用户、路由等配置后,后端会自动同步。 + +## 主要功能 + +- 支持 Trojan、VLESS、VMess、Shadowsocks、Hysteria2、TUIC、AnyTLS 等协议;具体可用协议取决于所选内核。 +- 支持单节点、机器模式、独立模式,以及一个进程管理多个实例。 +- 支持用户限速、设备限制、在线 IP 统计和用户热更新。 +- 支持在**本机配置文件**中为 Trojan TCP+TLS 设置 fallback;面板下发的配置不会覆盖这些规则。 + +## 安装 + +Linux systemd 单节点模式: + +```bash +curl -fsSL https://raw.githubusercontent.com/PiPi-happy/XNode/dev/install.sh | \ + sudo bash -s -- --mode node --panel https://panel.example.com --token TOKEN --node-id 1 +``` + +机器模式: + +```bash +curl -fsSL https://raw.githubusercontent.com/PiPi-happy/XNode/dev/install.sh | \ + sudo bash -s -- --mode machine --panel https://panel.example.com --token TOKEN --machine-id 1 +``` + +安装脚本默认下载本仓库的 `dev` Release。正式部署可传入 `--version <版本标签>` 固定版本。Docker 镜像为 `ghcr.io/pipi-happy/xnode:latest`;如需本地 fallback,请将配置文件挂载到容器内 `/etc/xboard-node/config.yml`。 + +## 本地 fallback 配置 + +在节点机器的 `config.yml` 中加入: + +```yaml +kernel: + type: xray # 也可用 singbox + fallbacks: + - dest: "127.0.0.1:8080" + - alpn: h2 + dest: "127.0.0.1:8082" +``` + +本机需分别准备监听 8080 的 HTTP/1.1 服务和监听 8082、支持 h2c 的服务。XNode 负责将非 Trojan 流量转发到这些目标,不会安装或管理网站。`dest` 必须写明地址和端口;同一 ALPN 不能重复。 + +面板更新用户或兼容的节点参数时,本地 fallback 仍会生效。若面板把节点改成非 Trojan、非 TCP 或 Reality,后端会拒绝该不兼容更新。机器模式下,同一实例管理的节点共用本地 fallback 规则;不同节点需要不同目标时,可使用多个实例。 + +注意:sing-box 会为配置的 fallback 目标生成优先直连规则。回落目标应是可公开访问的网站服务,不要指向本机管理后台端口。 + +## 运维与开发 + +安装后可运行 `xbctl` 查看帮助;常用命令: + +```bash +xbctl list +xbctl status +xbctl service restart +``` + +配置示例见 [`config.yml.example`](config.yml.example)。设计、测试结果、内核升级限制和后续事项见[项目 PRD](docs/PRD.md)。 + +## 许可证 + +MPL-2.0。