完整配置
Specola 的 Profile 是一个 TOML 文件。每个配置段、每个字段都可以不写,不写就取默认值。本页先给出一份用到所有配置段的 Profile,再列出全部字段的索引。
刚开始使用?请先看快速开始,之后再把这里当作参考。
最完整的版本随程序附带:resources/client/reference.toml,包含每个字段、每种代理类型以及每个取值的注释, 在 Windows、macOS 和 Linux 上都能原样加载。
文件规则
- 顶层配置段只有:
[general]、[[proxy]]、[[proxy-group]]、[route]、[dns]、[sniffer]、[enhanced-mode]。 其他都会报错,下文会被忽略的名字除外。 - 除了
[[proxy]](及其内联表)和[sniffer],其他配置段里出现未知字段都会报错,拼写错误不会被悄悄忽略。 [[proxy]]里的表(tls、transport、reality、headers)必须写成内联表:tls = { server-name = "..." }。[dns]的hosts、listener和[route]的geoip、geosite也一样。- 名称区分大小写。
DIRECT和REJECT是内置的,不要再声明。 - 规则里的 Windows 路径要用单引号的 TOML 字符串:
'PROCESS-PATH,C:\Tools\app.exe,DIRECT'。
不启动 Core 也能校验 Profile:
specola-core --test-config --config home.toml # Windows 上是 specola-service.exe带注释的 Profile
服务器、密码和 UUID 都是占位值,请换成你有权使用的服务器。
# ── 通用设置 ──────────────────────────────────────────────────────────────
[general]
route-mode = "rule" # rule | global | direct
global-proxy = "SELECT" # global 模式的目标:代理、代理组、DIRECT 或 REJECT
log-level = "info" # trace | debug | info | warn | error | critical | off
log-file = true # 按天写日志文件,保留 7 天
port = 7890 # 本地 SOCKS5/HTTP 端口;0 关闭
protocols = "mixed" # mixed | socks5 | http | none,或数组
allow-lan = false # true 时监听 0.0.0.0
api-listen = "" # 可选的 TCP 控制接口,例如 "127.0.0.1:9090"
ipv6 = false # 能解析,Core 不使用
# ── 代理 ──────────────────────────────────────────────────────────────────
[[proxy]]
name = "socks-example"
type = "socks5"
server = "proxy.example.org"
port = 1080
username = "example-user"
password = "replace-with-password"
[[proxy]]
name = "https-example"
type = "http"
server = "proxy.example.org"
port = 8443
username = "example-user"
password = "replace-with-password"
tls = { server-name = "proxy.example.org" } # HTTPS 代理
[[proxy]]
name = "vless-ws"
type = "vless"
server = "proxy.example.org"
port = 443
uuid = "b1479ae4-f64b-4b27-bdab-4fb0f4ecdba9"
tls = { server-name = "proxy.example.org" }
transport = { type = "ws", host = ["proxy.example.org"], path = "/ws" }
dialer-proxy = "socks-example" # 经 socks-example 连接这台服务器
# ── 代理组:成员只能是代理、DIRECT 或 REJECT,不能是代理组 ────────────────
[[proxy-group]]
name = "SELECT"
type = "select"
proxies = ["vless-ws", "https-example", "DIRECT"]
[[proxy-group]]
name = "AUTO"
type = "url-test"
proxies = ["vless-ws", "https-example"]
url = "https://www.gstatic.com/generate_204"
interval = 300 # 秒;不写就没有周期检查
tolerance = 50 # 成员要快出这么多毫秒,AUTO 才切换
# ── 路由:第一条命中的生效,FINAL 放最后 ──────────────────────────────────
[route]
rules = [
"IP-CIDR,192.168.0.0/16,DIRECT",
"IP-CIDR6,fc00::/7,DIRECT",
"RULE-SET,private-domains,DIRECT",
"PROCESS-NAME-REGEX,^(git|ssh)(\\.exe)?$,SELECT",
"DOMAIN-SUFFIX,example.net,AUTO",
"FINAL,DIRECT",
]
bypass = ["localhost", "*.local", "127.0.0.0/8", "::1/128"] # 在任何规则之前直接 DIRECT
final-mixed = "" # 本地端口的 FINAL;为空时用 FINAL 规则
final-enhanced = "" # 增强模式流量的 FINAL
resolve-unknown-domains = false
geo-update = "weekly" # daily | weekly | monthly | never
rule-set = [
{ name = "private-domains", type = "inline", behavior = "classical", rules = ["DOMAIN-SUFFIX,lan", "DOMAIN-SUFFIX,home.arpa"] },
]
# geoip = { type = "local", path = "geoip.dat" } # 只有 GEOIP 规则需要
# geosite = { type = "remote", url = "https://example.org/geosite.dat", proxy = "socks-example" }
# asn = "asn.txt" # 只有 IP-ASN 规则需要
# ── DNS:只有这六个字段 ───────────────────────────────────────────────────
[dns]
ipv6 = false
mode = "fake-ip" # fake-ip | fake-ip-all | real-ip
fake-ip-range = "198.18.0.1/16"
nameserver-proxy = ["https://1.1.1.1/dns-query", "udp://8.8.8.8:53"]
hosts = { "router.lan" = "192.168.1.1", "nas.lan" = ["192.168.1.10", "fd00::10"] }
listener = { enable = false, address = "127.0.0.1:1053" }
# ── 嗅探:只作用于增强模式和网关流量 ──────────────────────────────────────
[sniffer]
enable = true
protocols = ["http", "tls"]
override-destination = true
http-ports = [80, 8080]
tls-ports = [443, 8443]
timeout-ms = 500
max-bytes = 16384
# ── 增强模式:需要管理员权限 ──────────────────────────────────────────────
[enhanced-mode]
enable = false
ip-version = "ipv4" # ipv4 | ipv6 | dual
# 不写 backend:Windows 和 macOS 用 tun,Linux 用 ebpf
[enhanced-mode.tun] # Windows 和 macOS
auto-route = true
address = "198.19.0.1/30" # 仅 Windows
routes = []
exclude-routes = []
dns-hijack = true # 仅 Windows
dns-namespaces = ["."] # 仅 Windows
[enhanced-mode.ebpf] # Linux
unmatched-traffic = "direct" # direct | core字段索引
| 配置段 | 字段 | 文档 |
|---|---|---|
[general] | route-mode、global-proxy、log-level、log-file、port、protocols、allow-lan、api-listen、ipv6 | 基础配置 |
[general.inbound] | port、protocols(同样字段的旧位置) | 基础配置 |
[[proxy]] | name、type、server、port 以及各类型自己的字段 | 代理 |
[[proxy]] tls | enabled、server-name、alpn、skip-cert-verify、certificate、certificate-path、reality | TLS |
[[proxy]] transport | type(raw、ws、http、httpupgrade、grpc)及其字段;只用于 VMess 和 VLESS | 传输层 |
[[proxy]] dialer-proxy | 先经过的代理或代理组 | 代理链 |
[[proxy-group]] | name、type、proxies、url、interval、tolerance、strategy、dialer-proxy、icon | 代理组 |
[route] | rules、rule-set、geoip、geosite、asn、geo-update、bypass、final-mixed、final-enhanced、resolve-unknown-domains | 分流规则 |
[route] 中的 PROCESS-* 规则 | PROCESS-NAME、PROCESS-PATH 及其通配符、正则形式,include-children | 进程规则 |
[dns] | ipv6、mode、fake-ip-range、nameserver-proxy、hosts、listener | DNS |
[sniffer] | enable、protocols、override-destination、http-ports、tls-ports、timeout-ms、max-bytes | Sniffer |
[enhanced-mode] | enable、backend、ip-version | 增强模式 |
[enhanced-mode.tun] | auto-route、address、routes、exclude-routes、dns-hijack、dns-namespaces | TUN |
[enhanced-mode.ebpf] | unmatched-traffic | Linux eBPF |
忽略与拒绝
下面这些旧配置里的名字能加载,但会告警(Ignoring configuration field ...),而且不起作用,其内容被丢弃:
| 被忽略 | 说明 |
|---|---|
[metadata] | Core 从不读取它,所以其中的订阅设置和 download-via 都不生效。应用会从文件里读取 metadata.name 来显示 Profile 名称 |
[[module]]、modules、[[subscription]]、subscriptions、sub-rules、rule-providers | 改用模块和 [route].rule-set |
顶层 [hosts] | 改用 [dns].hosts |
[tunnel]、[ntp]、[gateway]、[state] | 路由器设置写在 --gateway 文件里 |
ssh-port-forward、ssh-port-forwards、port-forwards、ssh-probe | 不可用(见工具) |
[[proxy-groups]](复数) | 其中的代理组会丢失;请写 [[proxy-group]] |
enhanced-mode.process-proxy | 按进程分流请写成进程规则 |
general.api-secret | 静默丢弃,不告警 |
下面这些会报错:
| 被拒绝 | 改为 |
|---|---|
顶层 [rule] 或 rules | [route] rules |
顶层 [[rule-set]] | [route] rule-set |
顶层 [inbound] | [general] 里的 port 和 protocols |
顶层 proxies = [...] | [[proxy]](proxies 只在模块文件里可用) |
[[proxy-provider]] 及其他未知配置段 | — |
general.mixed-port、general.external-controller | port、api-listen |
protocols 的值 https | http |
dialer_proxy | dialer-proxy |
代理类型 ssh、mieru、sudoku | — |
上述六个以外的 [dns] 字段([dns.upstream]、nameserver-policy 等)以及 tls:// 上游 | 见 DNS |
代理组字段 use | 在 proxies 里列出成员 |
规则类型 SUB-RULE | — |
enhanced-mode.type | backend |
enhanced-mode.ebpf.process-routing | 不需要:Core 根据规则自动推导 |
Linux 上 enable = true 且 backend = "tun" | ebpf |
附属文件
Profile 旁边可以有两个可选文件,文件名是 Profile 的文件名加后缀:对 home.toml 来说,是 home.toml.modules 和 home.toml.disabled-rules。
<profile>.modules 按顺序列出 Profile 使用的模块,每行一个文件名(work.toml)。模块文件放在 Profile 旁边的 modules 目录里。加载 Profile 时:
[[proxy]]、[[proxy-group]]和[route] rule-set的条目按名称合并;同名条目会替换原有的。- 模块的
route.rules排在 Profile 自己的规则之前;列表中靠后的模块,其规则排在靠前的模块之前。 - 其他字段合并进 Profile,以模块的值为准。
- 模块文件可以用
proxies = [...]写代理;其中的[metadata]会被忽略。 - 模块文件不存在时告警并跳过;模块不是合法的 TOML 时加载失败。
这个文件由应用管理,详见模块。
<profile>.disabled-rules 记录你在应用里停用的规则,每行一条规则原文。加载 Profile 时跳过这些规则, Profile 文件本身不变。规则按完整原文识别,所以编辑过的规则会重新启用。FINAL 不能停用。
--test-config 也会读取这两个文件。
改动如何生效
重新激活 Profile 后,所有改动都会就地生效,不需要重启 Core:日志、路由模式、本地端口、api-listen、代理、代理组和规则 (保留下来的代理组会沿用之前的选择和健康状态)、DNS、嗅探和增强模式。Linux eBPF 下,本地端口、DNS、增强模式或嗅探的改动 会重建整个运行时。加载失败的 Profile 不会影响正在运行的那一份。详见基础配置。
