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
9 changes: 7 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,14 @@ jobs:
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version: '1.26'
go-version: '1.27.4'
cache: true

- name: Run govulncheck
run: |
go install golang.org/x/vuln/cmd/govulncheck@v1.9.0
govulncheck ./...

- name: Run tests
run: make test

Expand All @@ -46,7 +51,7 @@ jobs:
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version: '1.26'
go-version: '1.27'
cache: true

- name: Build
Expand Down
4 changes: 2 additions & 2 deletions Dockerfile
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Build stage
FROM golang:1.26-alpine AS builder
FROM golang:1.27.4-alpine3.24 AS builder

RUN apk add --no-cache git

Expand All @@ -17,7 +17,7 @@ RUN CGO_ENABLED=0 go build -ldflags "-s -w \
-o xboard-node ./cmd/xboard-node

# Runtime stage — sing-box & xray-core are embedded as Go libraries
FROM alpine:3.20
FROM alpine:3.24.4

RUN apk add --no-cache ca-certificates tzdata

Expand Down
30 changes: 25 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Fork of xboard-node for the official [Xboard](https://github.com/cedar2025/Xboar

## Features

- Protocols: V2Ray family, Trojan, Shadowsocks, Hysteria2, TUIC, AnyTLS
- Protocols: V2Ray family, Trojan, Shadowsocks, Hysteria2, TUIC, AnyTLS, and Mieru (through the Mieru author's MBox-enabled sing-box fork; no separate Mita service is required).
- Sync: WebSocket push + REST polling dual channel
- User controls: speed limit, device limit, alive-IP tracking, hot update
- Deploy modes: node mode, machine mode, standalone mode
Expand All @@ -27,6 +27,8 @@ docker run -d --restart=always --network=host \
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`.

For Mieru nodes, XNode routes to the Mieru author's MBox-enabled sing-box fork automatically; see [Mieru support](docs/mieru.md).

### Installer (Linux systemd)

```bash
Expand Down Expand Up @@ -59,7 +61,9 @@ 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:
Local fallback is configured only in `config.yml`, never from panel data. It applies to **Trojan + TCP + TLS**: ordinary TLS requests are forwarded to a local web service based on ALPN, while Trojan authentication traffic continues to the node. It can serve a normal website for ordinary web requests, but does not guarantee protection from every probing or blocking technique.

`node` and `machine` are panel management modes and are independent of the kernel type. Both support fallback. sing-box is the default kernel; Xray is also supported. Both kernels use this configuration:

```yaml
kernel:
Expand All @@ -70,9 +74,25 @@ kernel:
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).
Run a local HTTP/1.1 service on 8080 and an h2c-capable service on 8082. XNode
forwards fallback traffic but does not install or manage the website service.
Use explicit `host:port` destinations, and do not repeat an ALPN. Bind the local
services to `127.0.0.1` so their backend ports are not exposed publicly.

Fallback rules survive compatible panel updates. Top-level `kernel.fallbacks`
is inherited by instances; nodes in the same machine instance share the rules.
Use multiple instances or a node-level override when nodes need different
destinations. Switching a node away from Trojan TCP+TLS is rejected while local
fallbacks are enabled. See [PRD](docs/PRD.md).

For Docker deployments, mount the config containing `kernel.fallbacks` at
`/etc/xboard-node/config.yml`. If the fallback targets use `127.0.0.1`, the XNode
container must also use the host network (`--network=host`); otherwise that
address refers to the container itself. The systemd installer sets the
health-check port to `65530` by default; Docker or manual configs listen only
when `health_port` is set. The unauthenticated endpoint binds only to
`127.0.0.1`; remote monitoring cannot connect directly. Use an SSH tunnel or a
restricted local proxy when remote monitoring is needed.

## Extensions

Expand Down
15 changes: 10 additions & 5 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,11 @@ XNode 是适配[官方 Xboard 面板](https://github.com/cedar2025/Xboard)的节

## 主要功能

- 支持 Trojan、VLESS、VMess、Shadowsocks、Hysteria2、TUIC、AnyTLS 等协议;具体可用协议取决于所选内核。
- 支持 Trojan、VLESS、VMess、Shadowsocks、Hysteria2、TUIC、AnyTLS 和 Mieru(Mieru 使用其作者维护的 MBox sing-box 分支,无需单独安装 Mita)。
- 支持单节点、机器模式、独立模式,以及一个进程管理多个实例。
- 支持用户限速、设备限制、在线 IP 统计和用户热更新。
- 支持在**本机配置文件**中为 Trojan TCP+TLS 设置 fallback;面板下发的配置不会覆盖这些规则。
- Mieru 节点自动切换到 MBox sing-box 内核;详见 [Mieru 支持](docs/mieru.md)。

## 安装

Expand All @@ -31,7 +32,9 @@ curl -fsSL https://raw.githubusercontent.com/PiPi-happy/XNode/dev/install.sh | \

## 本地 fallback 配置

在节点机器的 `config.yml` 中加入:
fallback 是本地节点配置,不由 Xboard 面板下发。它适用于 **Trojan + TCP + TLS**:普通 TLS 请求按 ALPN 转发到本机 Web 服务,Trojan 认证流量仍由节点处理。它能让普通网页请求显示回落网站,但不保证规避所有主动探测或封禁。

`node` 和 `machine` 是面板管理模式,与内核类型相互独立。两种模式都支持 fallback;默认内核为 sing-box,也可使用 Xray。两种内核均支持下面的配置:

```yaml
kernel:
Expand All @@ -42,11 +45,13 @@ kernel:
dest: "127.0.0.1:8082"
```

本机需分别准备监听 8080 的 HTTP/1.1 服务和监听 8082、支持 h2c 的服务。XNode 负责将非 Trojan 流量转发到这些目标,不会安装或管理网站。`dest` 必须写明地址和端口;同一 ALPN 不能重复。
本机需分别准备监听 8080 的 HTTP/1.1 服务和监听 8082、支持 h2c 的服务。XNode 负责将非 Trojan 流量转发到这些目标,不会安装或管理网站。`dest` 必须写明地址和端口;同一 ALPN 不能重复。回落服务建议只监听 `127.0.0.1`,避免把后端端口直接暴露到公网。

面板更新用户或兼容的节点参数时,本地 fallback 仍会生效。若面板把节点改成非 Trojan、非 TCP 或 Reality,后端会拒绝该不兼容更新。顶层 `kernel.fallbacks` 会由实例继承;机器模式下,同一实例管理的节点共用规则。不同节点需要不同目标时,可使用多个实例或节点级覆盖。

面板更新用户或兼容的节点参数时,本地 fallback 仍会生效。若面板把节点改成非 Trojan、非 TCP 或 Reality,后端会拒绝该不兼容更新。机器模式下,同一实例管理的节点共用本地 fallback 规则;不同节点需要不同目标时,可使用多个实例。
sing-box 会为配置的 fallback 目标生成优先直连规则。回落目标应是网站服务,不要指向本机管理后台、控制面板或其他敏感端口。

注意:sing-box 会为配置的 fallback 目标生成优先直连规则。回落目标应是可公开访问的网站服务,不要指向本机管理后台端口。
Docker 部署需要把含有 `kernel.fallbacks` 的配置文件挂载到容器内 `/etc/xboard-node/config.yml`。若 fallback 使用 `127.0.0.1` 目标,XNode 容器还需使用宿主网络(`--network=host`),否则该地址会指向容器自身。systemd 安装器默认设置健康检查端口 `65530`;Docker 或手动配置只有在设置 `health_port` 后才会监听。健康接口无身份验证,但仅监听 `127.0.0.1`,远程监控不能直接连接;如需远程监控,应通过 SSH 隧道或受限的本机代理访问。

## 运维与开发

Expand Down
4 changes: 2 additions & 2 deletions cmd/xboard-node/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ func runWithReload(initialRoot *config.RootConfig, configPath string) {
if port <= 0 {
return
}
ln, err := net.Listen("tcp", fmt.Sprintf(":%d", port))
ln, err := net.Listen("tcp", fmt.Sprintf("127.0.0.1:%d", port))
if err != nil {
nlog.Core().Error("failed to start health check listener", "port", port, "error", err)
os.Exit(1)
Expand All @@ -76,7 +76,7 @@ func runWithReload(initialRoot *config.RootConfig, configPath string) {
healthSrv = &http.Server{Handler: mux, ReadHeaderTimeout: 5 * time.Second}
healthPort = port
go func() {
nlog.Core().Debug(fmt.Sprintf("health check listening on :%d", port))
nlog.Core().Debug(fmt.Sprintf("health check listening on 127.0.0.1:%d", port))
if err := healthSrv.Serve(ln); err != nil && err != http.ErrServerClosed {
nlog.Core().Warn("health check server stopped", "error", err)
}
Expand Down
Loading
Loading