Xboard-Node

Xboard面板专用节点后端。支持Sing-Box和Xray-Core内核

特征

• 协议支持：V2Ray系列、Trojan、Shadowsocks、Hysteria2、TUIC、AnyTLS
• 节点同步：WebSocket推送+REST轮询双通道
• 用户控制：速度限制、设备限制、实时 IP 跟踪、热更新
• 部署模式：节点模式、机器模式、独立模式
• 多实例：单个进程绑定多个面板/节点

常用命令

重启

xbctl service restart

开启

xbctl service start

停止

xbctl service stop

查看状态

xbctl service status

查看日志

xbctl service logs

查看版本号

xbctl version

安装

Docker (单容器快速运行)

最简单、最快速的测试或单节点部署方式

docker run -d --restart=always --network=host \
  -e apiHost=https://panel.com -e apiKey=TOKEN -e nodeID=1 \
  ghcr.io/cedar2025/xboard-node:latest

Docker Compose (容器编排/生产推荐)

目前主流的生产环境部署方式

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

Installer (Linux systemd) (Linux systemd 脚本/原生安装)

通过 Shell 脚本将程序直接安装在 Linux 系统中作为服务运行

# Node mode 节点模式
# 传统模式：对接 Xboard 面板上的“节点 ID”
# 用途：最常用的科学上网节点部署方式
curl -fsSL https://raw.githubusercontent.com/cedar2025/xboard-node/dev/install.sh | \
  sudo bash -s -- --mode node --panel https://panel.example.com --token TOKEN --node-id 1

# Machine mode 机器模式
# 机器模式：对接面板上的“机器 ID”
# 用途：通常用于更底层的管理或特定的多实例绑定需求，这是 Xboard 最近版本引入的新特性，允许一台服务器更灵活地绑定多个节点
curl -fsSL https://raw.githubusercontent.com/cedar2025/xboard-node/dev/install.sh | \
  sudo bash -s -- --mode machine --panel https://panel.example.com --token TOKEN --machine-id 1

# xbctl
# 输入 “xbctl” 查看所有命令

```bash
xbctl list                          # list all instances
xbctl status                        # running status
xbctl bind add-node --panel URL --token TOKEN --node-id 1
xbctl bind add-machine --panel URL --token TOKEN --machine-id 1
xbctl bind remove-node --panel URL --node-id 1
xbctl service restart

建议：

新手或者想省事： 直接用 Docker Compose
进阶用户（单实例多节点，并习惯使用命令行管理）： 推荐 Installer (Linux systemd)，并利用 xbctl 工具

命令&注释

输入 xbctl 查看所有命令

xbctl

命令&注释

xbctl commands:  # xbctl 菜单
  xbctl help  # 显示帮助信息
  xbctl status  # 查看当前服务的运行状态 
  xbctl list [--output text|json]  # 列出所有绑定的实例列出所有绑定的实例（可选输出格式为文本或 JSON）
  xbctl instance list [--output text|json]   # 列出实例详情
  xbctl instance get <id> [--output text|json]  # 获取特定 ID 实例的详细信息
  xbctl config init --mode node|machine --panel-url URL --token TOKEN [flags]  # 初始化配置。需指定模式（节点或机器）、面板地址和通信令牌
  xbctl config health-port [--config PATH]   # 配置健康检查端口
  xbctl service status|start|stop|restart|enable|disable|logs  # 系统服务管理（查看状态、启动、停止、重启、设置开机自启、取消自启、查看日志）
  xbctl health  # 运行健康检查，确认节点连接是否正常
  xbctl bind add-node --panel-url URL --token TOKEN --node-id ID [--node-type TYPE] [--kernel singbox|xray]  # 绑定新节点。需提供：面板地址、Token、节点 ID。可选：节点类型、内核选择（singbox 或 xray）
  xbctl bind add-machine --panel-url URL --token TOKEN --machine-id ID [--kernel singbox|xray]  # 绑定新机器模式。需提供：面板地址、Token、机器 ID
  xbctl bind remove <instance-id>  # 通过实例 ID 移除绑定
  xbctl bind remove-node --panel URL --node-id ID  # 通过面板地址和节点 ID 移除特定节点
  xbctl bind remove-machine --panel URL --machine-id ID   #通过面板地址和机器 ID 移除特定机器
  xbctl upgrade [--version VERSION]  # 升级 xbctl 和后端版本（可指定版本号）
  xbctl uninstall [--purge] [--yes]  # 卸载程序。--purge: 彻底清除所有配置文件。--yes: 跳过确认步骤
  xbctl version  # 查看当前版本号

shortcuts:  # 快捷指令
  xbctl start|stop|restart        = xbctl service start|stop|restart  # 等同于管理服务（启动/停止/重启）
  xbctl log|logs                  = xbctl service logs   # 查看运行日志（排查错误常用）
  xbctl bind-node ...             = xbctl bind add-node ...  # 快速绑定一个新节点
  xbctl bind-machine ...          = xbctl bind add-machine ...  # 快速绑定一个新机器模式实例
  xbctl unbind-node ...           = xbctl bind remove-node ...  # 快速解绑（删除）一个节点
  xbctl unbind-machine ...        = xbctl bind remove-machine ... # 快速解绑（删除）一个机器模式实例

表格式

命令	注释
xbctl help	显示帮助信息
xbctl status	查看当前服务的运行状态
xbctl list [--output text|json]	列出所有绑定的实例（可选输出格式为文本或 JSON）
xbctl instance list [--output text|json]	列出实例详情
xbctl instance get <id> [--output text|json]	获取特定 ID 实例的详细信息
xbctl config init --mode node|machine --panel-url URL --token TOKEN [flags]	初始化配置。需指定模式（节点或机器）、面板地址和通信令牌
xbctl config health-port [--config PATH]	配置健康检查端口
xbctl service status|start|stop|restart|enable|disable|logs	系统服务管理 （查看状态、启动、停止、重启、设置开机自启、取消自启、查看日志）
xbctl health	运行健康检查，确认节点连接是否正常
xbctl bind add-node --panel-url URL --token TOKEN --node-id ID [--node-type TYPE] [--kernel singbox|xray]	绑定新节点。 需提供：面板地址、Token、节点 ID。 可选：节点类型、内核选择（singbox 或 xray）
xbctl bind add-machine --panel-url URL --token TOKEN --machine-id ID [--kernel singbox|xray]	绑定新机器模式。 需提供：面板地址、Token、机器 ID
xbctl bind remove <instance-id>	通过实例 ID 移除绑定
xbctl bind remove-node --panel URL --node-id ID	通过面板地址和节点 ID 移除特定节点
xbctl bind remove-machine --panel URL --machine-id ID	通过面板地址和机器 ID 移除特定机器
xbctl upgrade [--version VERSION]	升级 xbctl 和后端版本（可指定版本号）
xbctl uninstall [--purge] [--yes]	卸载程序。 --purge: 彻底清除所有配置文件。 --yes: 跳过确认步骤
xbctl version	查看当前版本号

配置

旧版单面板配置完全兼容。追加绑定会自动迁移到 instances 新格式。请参阅 config.yml.example。

扩展

• 自定义路由：docs-custom-routes.md
• 自定义出站请求：docs-custom-outbounds.md
• DNS 提供商（ACME DNS-01）：docs-dns-providers.md

原文来源：Github