> Sponsored by CodeX

# sing-box Xboard Fork

这是一个基于上游 [SagerNet/sing-box](https://github.com/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](./install.sh)
  Linux 安装脚本
- [update.sh](./update.sh)
  Linux 升级脚本
- [option/xboard.go](./option/xboard.go)
  `services.xboard` 配置结构
- [service/xboard/service.go](./service/xboard/service.go)
  Xboard 动态服务实现
- [configs](./configs)
  配置示例目录

## 快速开始

### 1. 编译并安装

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

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

升级已安装的 sing-box：

```bash
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` 才结束
- 至少要有一个节点

## 运行与管理

查看状态：

```bash
systemctl status singbox
```

查看日志：

```bash
journalctl -u singbox -f
```

重启服务：

```bash
systemctl restart singbox
```

手动运行：

```bash
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.single-node.json)
- [configs/10-base.multi-node.json](./configs/10-base.multi-node.json)
- [configs/route.json](./configs/route.json)
- [configs/outbound.json](./configs/outbound.json)

## `services.xboard` 配置说明

配置结构定义见 [option/xboard.go](./option/xboard.go)。

### 最小单节点示例

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

### 多节点示例

```json
{
  "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. 协议识别

推荐面板显式返回：

```json
{
  "protocol": "vless"
}
```

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

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

### 2. 监听地址与端口

推荐面板返回：

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

### 3. PROXY protocol

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

```json
{
  "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](./configs/panel-response.vless-reality.json)

### 5. Shadowsocks 2022

推荐面板返回：

- `protocol: "shadowsocks"`
- `cipher`
- `server_key`

示例见：

- [configs/panel-response.shadowsocks2022.json](./configs/panel-response.shadowsocks2022.json)

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

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

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

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

```text
Xboard setup error: missing certificate
```

示例见：

- [configs/panel-response.anytls-acme-dns.json](./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` 的接口兼容。

你可以从面板下发：

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

也可以下发腾讯云凭据：

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

## 配置示例目录

[configs](./configs) 目录中已经提供了这些示例：

- [configs/10-base.single-node.json](./configs/10-base.single-node.json)
  单节点基础配置
- [configs/10-base.multi-node.json](./configs/10-base.multi-node.json)
  多节点基础配置
- [configs/route.json](./configs/route.json)
- [configs/outbound.json](./configs/outbound.json)
  出站配置模板
- [configs/panel-response.vless-reality.json](./configs/panel-response.vless-reality.json)
  VLESS REALITY 面板回包
- [configs/panel-response.shadowsocks2022.json](./configs/panel-response.shadowsocks2022.json)
  Shadowsocks 2022 面板回包
- [configs/panel-response.anytls-acme-dns.json](./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。

## 开发验证

近期已验证通过的命令：

```bash
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

```text
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.
```