Sponsored by CodeX

sing-box Xboard Fork

这是一个基于上游 SagerNet/sing-box 的定制分支，主要面向 Xboard / UniProxy 面板联动部署场景。

它保留了上游 sing-box 内核能力，同时补充了：

• Xboard 动态入站服务
• 多节点托管
• 面板协议自动识别
• VLESS / REALITY 面板字段映射
• Shadowsocks 2022 用户同步与密钥处理
• AnyTLS / Trojan / Hysteria / TUIC 的本地 TLS / ACME 支持
• 安装脚本与分离式配置模板
• PROXY protocol 客户端真实 IP 传递

如果你要查看官方功能基线、通用配置文档、原始内核行为，请优先参考上游：

• 上游仓库：https://github.com/SagerNet/sing-box
• 上游文档：https://sing-box.sagernet.org

适用场景

这个仓库更适合以下用途：

• 从 Xboard / UniProxy 面板拉取节点配置
• 从面板拉取用户并动态更新
• 单机运行多个节点
• 给面板型机场节点准备安装脚本
• 对接面板下发的 protocol、cert_config、accept_proxy_protocol、REALITY 字段等

主要特性

• services.xboard 动态服务
• 支持单节点和多节点
• 协议优先从面板返回的 protocol 识别
• 支持面板回包控制 accept_proxy_protocol
• 支持 VLESS REALITY 的 server_name、public_key、private_key、short_id
• 支持 ACME：
  • auto_tls
  • cert_mode = http
  • cert_mode = dns
• 当前已支持的 ACME DNS provider：
  • cloudflare
  • alidns
  • tencentcloud
  • dnspod
  • acmedns
• 安装脚本默认生成：
  • /etc/sing-box/config.d/10-base.json
  • /etc/sing-box/config.d/route.json
  • /etc/sing-box/config.d/outbound.json
• 安装后的服务名为：
  • singbox.service

仓库内关键文件

• install.sh Linux 安装脚本
• update.sh Linux 升级脚本
• option/xboard.go services.xboard 配置结构
• service/xboard/service.go Xboard 动态服务实现
• configs 配置示例目录

快速开始

1. 编译并安装

在 Linux 服务器上进入仓库目录：

curl -fsSL https://s3.cloudyun.top/downloads/singbox/install.sh | bash

install.sh 默认会从 https://s3.cloudyun.top/downloads/singbox 下载对应架构的预编译 sing-box 二进制，再继续进入面板和服务配置流程。

升级已安装的 sing-box：

curl -fsSL https://s3.cloudyun.top/downloads/singbox/update.sh | bash

update.sh 会从同一发布地址下载对应架构的 sing-box 二进制，并自动重启已检测到的 singbox 或 sing-box 服务。

脚本会做这些事情：

1. 检查 Go 环境
2. 编译当前仓库代码
3. 生成分离配置
4. 创建 singbox.service
5. 启动服务

2. 安装过程会询问的内容

• Panel URL
• Panel Token
• 一个或多个 Node ID
• DNS 模式：
  • udp
  • local
• 当前节点前面是否有发送 PROXY protocol 的四层代理

3. 多节点输入规则

• 安装脚本会持续要求输入 Node ID
• 输入 NO 才结束
• 至少要有一个节点

运行与管理

查看状态：

systemctl status singbox

查看日志：

journalctl -u singbox -f

重启服务：

systemctl restart singbox

手动运行：

sing-box -D /var/lib/sing-box -C /etc/sing-box/config.d run

推荐配置结构

建议把配置拆成两部分。

10-base.json

放这些内容：

• 日志
• DNS
• services
• 基础路由规则

route.json

• route.rules
• route.auto_detect_interface
• common DNS hijack rules

outbound.json

放这些内容：

• 全部出站
• 出站标签
• 你自己的分流依赖

这样更方便：

• 面板动态服务和你的自定义出站分离
• 安装脚本生成的基础配置不容易被误改
• 调整出站时不会影响 Xboard 服务主体

示例已放在：

• configs/10-base.single-node.json
• configs/10-base.multi-node.json
• configs/route.json
• configs/outbound.json

services.xboard 配置说明

配置结构定义见 option/xboard.go。

最小单节点示例

{
  "type": "xboard",
  "panel_url": "https://panel.example.com",
  "key": "replace-with-node-token",
  "sync_interval": "1m",
  "report_interval": "1m",
  "node_id": 286
}

多节点示例

{
  "type": "xboard",
  "panel_url": "https://panel.example.com",
  "key": "replace-with-node-token",
  "sync_interval": "1m",
  "report_interval": "1m",
  "nodes": [
    {
      "node_id": 286
    },
    {
      "node_id": 774
    }
  ]
}

当前推荐做法

• 只传 panel_url
• 只传 key
• 只传 node_id 或 nodes

下面这些字段仍然保留兼容，但常规部署一般不需要：

• config_panel_url
• user_panel_url
• config_node_id
• user_node_id
• node_type

说明：

• 当前逻辑会优先从面板回包中的 protocol 自动识别协议
• node_type 更适合做历史兼容，不建议再依赖它做主配置

面板配置回包约定

1. 协议识别

推荐面板显式返回：

{
  "protocol": "vless"
}

当前服务会按如下顺序识别协议：

1. protocol
2. node_type
3. 如果是 Shadowsocks 且存在 cipher，则回退识别为 shadowsocks

2. 监听地址与端口

推荐面板返回：

{
  "listen_ip": "0.0.0.0",
  "server_port": 443
}

3. PROXY protocol

如果前面有四层代理，并且它会发送 PROXY protocol 头，需要面板返回：

{
  "accept_proxy_protocol": true
}

如果用户是直连节点，不要开启这个字段，否则连接会失败。

4. VLESS REALITY

当前支持从面板获取这些字段：

• tls_settings.server_name
• tls_settings.public_key
• tls_settings.private_key
• tls_settings.short_id
• 顶层 server_name
• 顶层 public_key
• 顶层 private_key
• 顶层 short_id

示例见：

• configs/panel-response.vless-reality.json

5. Shadowsocks 2022

推荐面板返回：

• protocol: "shadowsocks"
• cipher
• server_key

示例见：

• configs/panel-response.shadowsocks2022.json

6. AnyTLS / Trojan / Hysteria / TUIC 的证书要求

这些协议通常要求本地具备可用 TLS 证书。当前支持：

• 文件证书
• 证书内容直传
• ACME 自动签发

如果面板没有下发可用证书，也没有有效 ACME 配置，常见报错是：

Xboard setup error: missing certificate

示例见：

• configs/panel-response.anytls-acme-dns.json

ACME 说明

当前支持：

• auto_tls: true
• cert_mode: "http"
• cert_mode: "dns"

DNS-01 provider

已支持：

• cloudflare
• alidns
• tencentcloud
• dnspod
• acmedns

DNSPod 说明

仓库已经内置 DNSPod provider 适配，不再依赖旧版 github.com/libdns/dnspod 的接口兼容。

你可以从面板下发：

{
  "cert_config": {
    "cert_mode": "dns",
    "dns_provider": "dnspod",
    "dns_env": {
      "DNSPOD_TOKEN": "id,token"
    }
  }
}

也可以下发腾讯云凭据：

{
  "cert_config": {
    "cert_mode": "dns",
    "dns_provider": "tencentcloud",
    "dns_env": {
      "TENCENTCLOUD_SECRET_ID": "xxx",
      "TENCENTCLOUD_SECRET_KEY": "xxx"
    }
  }
}

配置示例目录

configs 目录中已经提供了这些示例：

• configs/10-base.single-node.json 单节点基础配置
• configs/10-base.multi-node.json 多节点基础配置
• configs/route.json
• configs/outbound.json 出站配置模板
• configs/panel-response.vless-reality.json VLESS REALITY 面板回包
• configs/panel-response.shadowsocks2022.json Shadowsocks 2022 面板回包
• configs/panel-response.anytls-acme-dns.json AnyTLS + ACME DNS 验证面板回包

常见问题

unsupported protocol: empty

原因通常是：

• 面板没有返回 protocol
• 兼容字段 node_type 也为空

建议：

• 面板显式返回顶层 protocol

Xboard setup error: missing certificate

原因通常是：

• AnyTLS / Trojan / Hysteria / TUIC 需要证书
• 面板没有下发证书文件、证书内容或 ACME 参数

TLS handshake: REALITY: processed invalid connection

多数情况下表示客户端参数和当前 REALITY 节点配置不匹配，例如：

• server_name 错误
• public_key 错误
• short_id 错误
• 客户端实际上不是按 REALITY 模式连入

Server does not exist

通常是：

• 面板里不存在该 node_id
• token 不匹配
• 拉取配置或拉取用户的节点 ID 写错

真实 IP 没有正确获取

请确认：

1. 前置代理确实发送了 PROXY protocol
2. 面板确实下发了 accept_proxy_protocol: true

否则服务只能看到上游代理 IP。

开发验证

近期已验证通过的命令：

go test ./common/dnspod ./common/tls ./service/acme ./service/xboard
go build -trimpath -tags 'with_quic,with_utls,with_clash_api,with_gvisor,with_acme' ./cmd/sing-box

如果你改动了 Xboard、协议映射、ACME 或证书相关逻辑，建议至少执行一次以上命令。

License

Copyright (C) 2022 by nekohasekai <contact-sagernet@sekai.icu>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.

In addition, no derivative work may use the name or imply association
with this application without prior consent.