Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 10 additions & 6 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 4 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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-*
Expand Down
41 changes: 28 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# xboard-node
# XNode

Node backend for [Xboard](https://github.com/cedar2025/Xboard). Supports `sing-box` / `xray-core` dual kernels.
[简体中文说明](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.

Expand All @@ -19,28 +21,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 <release-tag>` after publishing a tagged release.

## xbctl

Expand All @@ -59,6 +59,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)
Expand Down
65 changes: 65 additions & 0 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
@@ -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。
8 changes: 4 additions & 4 deletions cmd/xbctl/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 (
Expand All @@ -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 {
Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -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

Expand Down
6 changes: 6 additions & 0 deletions config.yml.example
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
86 changes: 86 additions & 0 deletions docs/PRD.md
Original file line number Diff line number Diff line change
@@ -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:<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/>
8 changes: 4 additions & 4 deletions install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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=""
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -592,7 +592,7 @@ render_service() {
cat >"$TMP_DIR/${SERVICE_NAME}" <<EOF_UNIT
[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

Expand Down
Loading
Loading