sing-box系列教程 01 – 初步认识JSON、sing-box 十大模块的功能和模块间的工作流程

sakuraikaede 发布于 2025-12-15 最后更新于 2025-12-16 33 次阅读 无~ 未分类

一. 前言

1. 作者的一些话

本系列将开启一个全新的教程，教程偏向一般肯独立思考、有接受大篇幅的信息理解能力的用户。

本文将着重于sing-box文档的讲解，以及其他注意事项的结合教学。

跟随本教程，你可以从头到尾理解并编写属于自己的sing-box配置文件，玩转sing-box。

二. JSON数据格式的轻量理解

1. 为什么要了解JSON数据格式？

💡引言 - sing-box

请点击上方的sing-box文档-配置部分的链接，查看该网页的第一句话：

“sing-box使用JSON作为配置文件格式”

因此我们要想完全理解sing-box配置，势必需要先简单了解JSON数据格式是什么，以及它的构成。

2. JSON数据格式的基本概念

  • JSON 是一种数据格式，不是编程语言。
  • 起源于 JavaScript 对象字面量的语法，但现在独立存在，几乎所有语言都有解析库。
  • 常见用途：配置文件、API 数据传输、数据库存储（如 MongoDB）。

听起来对你来说可能有点抽象对嘛，但只要记住，JSON不属于编程语言，它只是一种数据交换格式。因为结构清晰、轻量级，容易被机器和人读取，且各个编程语言都有JSON解析库，被广泛使用。

3. JSON的数据类型

JSON共支持6种数据类型

① 字符串（String）

  • 必须用双引号 "" 包裹起来
  • 支持转义字符：\\n, \\t, \\\\, \\"

例如：

"love"
"apple\\nmelon"

字符串（String）数据在sing-box配置文件中大量使用，如sing-box日志等级就使用字符串作为值：

"trace"
"debug"
"info"
"warn"
"error"
"fatal"
"panic"

② 数字（Number）

  • 支持整数、浮点数
  • 不支持 NaN、Infinity

例如：

42
3.1415
-100

数字（Number）数据在sing-box配置文件中大量使用，最常见的就是端口值，如下的443：

"server_port": 443

③ 布尔值（Boolean）

  • true 或 false

这个没什么好说的，布尔值只有如上两种。在sing-box中，常用于表示某功能的开启或关闭，如TUN模块启用自动路由：

"auto_route": true

④ 空值（null）

  • 表示空、无值
  • 仅有一个null

在sing-box配置文件中，这个值未见使用。

⑤ 对象（Object）

  • 无序的“键值对”集合

<aside> 💡

什么是“键值对”？

  • 键（key）：就像一个“名字”或者“标签”，用来标识某个数据。
  • 值（value）：对应的数据内容，可以是字符串、数字、布尔、null、对象、数组。

两者组合在一起，叫做 键值对。

如下就是一个基础的键值对，sing-box配置文件内大部分都是由键值对构成。

"type": "vless"

</aside>

  • 用 花括号 {} 包裹起来
  • 键（key）必须是字符串，值（value）可以是任意 JSON 类型
  • 对象是可以嵌套使用的
  • 同一个对象中的多个键值对，除最后一个以外，其余的末尾要加 ,

最典型的一个对象示例：

{
  "type": "vless",
  "tag": "vless-out",
  "server": "example.com",
  "server_port": 12345,
  "uuid": "A1B4A7EB-64AF-4747-B5C3-B2BB1DE2CE9D"
}

嵌套使用的对象示例（其中TLS部分就是在对象中嵌套使用对象）：

{
  "type": "hysteria2",
  "tag": "hy2-out",
  "server": "example.com",
  "server_port": 12345,
  "password": "A1B4A7EB-64AF-4747-B5C3-B2BB1DE2CE9D",
  "tls": {
    "enabled": true,
    "server_name": "example.com",
    "insecure": false
  },
  "up_mbps": 50,
  "down_mbps": 200
}

⑥ 数组（Array）

  • 有序的值列表
  • 用 方括号 []

一个基础的数组：

[1, 2, 3, "apple", false, null]

数组数据类型在sing-box配置文件中，常见于DNS规则和路由规则、节点组处，当添加多个数据时，就会使用数组（如下的outbounds处）：

{
  "tag": "url-test",
  "type": "selector",
  "outbounds": [
    "node1",
    "node2",
    "node3",
    "node4",
    "node5"
  ],
  "default": "node1"
}

了解到这里，你就已经对JSON格式有了一个基本的了解。

接下来，我们将开始了解sing-box的主要模块和工作流程。

三. sing-box主要模块

1. 10大模块的作用了解

{
  "log": {},
  "dns": {},
  "ntp": {},
  "certificate": {},
  "endpoints": [],
  "inbounds": [],
  "outbounds": [],
  "route": {},
  "services": [],
  "experimental": {}
}

//请从这里开始，使用代码编辑器，建议VS Code，一边观看教程一边跟随修改配置文件，加深理解。
  • Log模块

这个模块主要是控制sing-box核心运行时的日志输出方式和等级。

此模块可以省略不写。

如若不写，sing-box默认将开启trace日志等级，将运行时的一切日志都输出出来。

  • DNS模块

这个模块主要是负责sing-box核心使用的DNS服务器，如何处理DNS解析结果，DNS分流规则和其他DNS行为。

此模块可以省略不写。

如若不写，sing-box将直接把DNS解析交给操作系统完成，由操作系统控制。

  • NTP模块

<aside> 💡

什么是NTP？

NTP (Network Time Protocol，网络时间协议) 是TCP/IP协议中应用层的一个协议，用于客户端与服务端进行时钟同步，包括时间、时区等。

</aside>

这个模块主要是负责sing-box核心的内置时间，有些协议，如TLS/Shadowsocks/VMess等依赖正确的时间工作，此模块可以让这些协议在操作系统时间错误的情况下依然可以使用。

此模块可以省略不写。

如若不写，sing-box将直接使用系统时间。

  • Certificate模块

这个模块主要是控制sing-box核心信任的证书范围。

💡什么是证书？

证书是现代互联网的安全基石，它就像网络世界里的“身份证”，用来证明某个网站、个人或组织的身份是否真实可信，并且在数据传输中起到加密、验证、完整性保护的作用。

在sing-box中，这个模块主要是负责TLS证书。

TLS证书与所有使用了TLS安全层的协议有关，Vless+TLS/VMess+TLS/Hysteria等。

sing-box此模块可以自定义增减证书的信任范围。

此模块可以省略不写。

如若不写，sing-box直接使用系统受信任的 CA 证书。

  • Endpoints模块

这个模块是sing-box核心用于使用WireGuard和Tailscale协议的模块。

原来WireGuard模块隶属于Outbound模块，sing-box 1.12.0开始并入Endpoints模块，并同时增加了Tailscale的支持。

此模块根据需要决定是否写。

如若不写，sing-box将不启用WireGuard和Tailscale的支持。

  • Inbound模块

这个模块是sing-box核心用于确定如何接受流量进入的模块，也就是常说的入站模块。

sing-box作为服务端使用时，这个模块常用于配置指定加密协议的服务端入站监听，比如shadowsocks/VMess/Vless/Hysteria等。

sing-box作为客户端使用时，这个模块常用于配置标准socks/HTTP代理，用于接管系统代理流量，或配置TUN接口全局接管操作系统流量。

此模块必须写。

  • Outbound模块

这个模块是sing-box核心用于确定流量如何离开的模块，也就是常说的出站模块。

sing-box作为服务端使用时，这个模块一般只开启一个直连出站，即sing-box不经任何处理直接把数据发送出去。如果有链式代理的情况，也可以配置转发的下一个目标。

sing-box作为客户端使用时，这个模块常用于配置指定加密协议的客户端出站，比如shadowsocks/VMess/Vless/Hysteria等。

此模块必须写。

  • Route模块

这个模块是sing-box核心用于确定流量应该如何路由、使用哪一个出站的模块，也就是常说的路由模块。

这个模块一般用于分流流量、确定默认的网络接口。

此模块可以不写。

如若不写，sing-box将使用内建默认路由（一般是第一个可用的出站）。

  • Services模块

这个模块是sing-box核心额外支持的一些服务。

目前支持Derp服务器、伪造systemd-resolved DBUS服务和SSM API。

该模块作为一般代理用途时极少使用。

此模块根据需要决定是否写。

  • Experimental模块

这个模块是sing-box核心的实验性功能模块。

Clash API和V2ray API就在此模块提供，用于便捷通过WebUI进行出站控制。

此模块根据需要决定是否写，但考虑到这是内核教程，在拥有多节点时，切换节点必须依赖该模块Clash API功能，所以此处标记为必须写。

2.sing-box 模块间的工作流程

对于仅仅使用代理的普通用户来说，上述10个模块并不都是需要使用的。

实际上，我们只需要DNS、Inbound、Outbound、Route和Experimental模块即可，这些模块在一般处理代理数据的工作流程是：

image.png

对于sing-box 1.11.0之前的版本，由于DNS协议嗅探在Inbound模块处，且有独立的特殊DNS出站，故带有DNS模块的流程为：

image.png

对于sing-box 1.11.0之后的版本，由于DNS协议嗅探在Route模块处，且不再具有独立的特殊DNS出站，故带有DNS模块的流程为：

image.png

3. Log模块详解

结构

{
  "log": {
    "disabled": false,
    "level": "info",
    "output": "box.log",
    "timestamp": true
  }
}

如上为整个Log模块的内容。

这个字段没什么内容，难度较低，没有二级功能，因此我们直接插入总配置即可：

{
  "log": {
    "disabled": false,
    "level": "info",
    "output": "box.log",
    "timestamp": true
  },
  "dns": {},
  "ntp": {},
  "certificate": {},
  "endpoints": [],
  "inbounds": [],
  "outbounds": [],
  "route": {},
  "services": [],
  "experimental": {}
}

字段

  • disabled 这个字段是控制sing-box是否在运行时输出日志的，如果设置为ture，则禁用日志，后面的level、output、timestamp就不再有效。
  • level 这个字段是日志等级，控制sing-box运行时输出的日志范围，有以下等级可选： trace debug info warn error fatal panic trace等级输出的内容最多，panic输出的内容最少，如果没有指示这个字段，sing-box默认为trace。
  • output 这个字段设置日志输出的位置，如果这个字段不为空，sing-box就会把日志输出到一个文件而不是在控制台中，注意，日志输出路径必须具有写权限。
  • timestamp 添加时间到日志每一行，设置为true的话每一行日志都有时间，反之没有。

总配置

比如常见记录日志的配置，等级为debug，不需要单独输出日志文件，每一行日志需要时间，那么只需要修改为：

{
  "log": {
    "disabled": false,
    "level": "debug",
    "timestamp": true
  },
  "dns": {},
  "ntp": {},
  "certificate": {},
  "endpoints": [],
  "inbounds": [],
  "outbounds": [],
  "route": {},
  "services": [],
  "experimental": {}
}

至此，你就写好了Log模块哦~

恭喜你迈出了第一步！那后面对你来说就不会太难~

此作者没有提供个人介绍。
最后更新于 2025-12-16