CN-JS-HuiBai/SingboxForPanel

Fork 0

Files

CN-JS-HuiBai 66c252d6ef Reapply SingboxForPanel integration on upstream stable

2026-04-16 10:29:41 +08:00

9.8 KiB

Raw Blame History

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/20-outbounds.json
安装后的服务名为：
- singbox.service

仓库内关键文件

install.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 二进制，再继续进入面板和服务配置流程。

脚本会做这些事情：

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

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

`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"
}

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

protocol
node_type
如果是 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/20-outbounds.example.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 也为空

建议：

`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 没有正确获取

请确认：

前置代理确实发送了 PROXY protocol
面板确实下发了 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.

9.8 KiB

Raw Blame History

sing-box Xboard Fork

适用场景

主要特性

仓库内关键文件

快速开始

1. 编译并安装

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

3. 多节点输入规则

运行与管理

推荐配置结构

`10-base.json`

`20-outbounds.json`

`services.xboard` 配置说明

最小单节点示例

多节点示例

当前推荐做法

面板配置回包约定

1. 协议识别

2. 监听地址与端口

3. PROXY protocol

4. VLESS REALITY

5. Shadowsocks 2022

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

ACME 说明

DNS-01 provider

DNSPod 说明

配置示例目录

常见问题

`unsupported protocol: empty`

`Xboard setup error: missing certificate`

`TLS handshake: REALITY: processed invalid connection`

`Server does not exist`

真实 IP 没有正确获取

开发验证

License

9.8 KiB Raw Blame History Unescape Escape

sing-box Xboard Fork

适用场景

主要特性

仓库内关键文件

快速开始

1. 编译并安装

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

3. 多节点输入规则

运行与管理

推荐配置结构

10-base.json

20-outbounds.json

services.xboard 配置说明

最小单节点示例

多节点示例

当前推荐做法

面板配置回包约定

1. 协议识别

2. 监听地址与端口

3. PROXY protocol

4. VLESS REALITY

5. Shadowsocks 2022

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

ACME 说明

DNS-01 provider

DNSPod 说明

配置示例目录

常见问题

unsupported protocol: empty

Xboard setup error: missing certificate

TLS handshake: REALITY: processed invalid connection

Server does not exist

真实 IP 没有正确获取

开发验证

License

9.8 KiB

Raw Blame History

`10-base.json`

`20-outbounds.json`

`services.xboard` 配置说明

`unsupported protocol: empty`

`Xboard setup error: missing certificate`

`TLS handshake: REALITY: processed invalid connection`

`Server does not exist`