Skip to content
English下载

完整配置 ​

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:

bash
specola-core --test-config --config home.toml       # Windows 上是 specola-service.exe

带注释的 Profile ​

服务器、密码和 UUID 都是占位值,请换成你有权使用的服务器。

toml
# ── 通用设置 ──────────────────────────────────────────────────────────────
[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]] tlsenabled、server-name、alpn、skip-cert-verify、certificate、certificate-path、realityTLS
[[proxy]] transporttype(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、listenerDNS
[sniffer]enable、protocols、override-destination、http-ports、tls-ports、timeout-ms、max-bytesSniffer
[enhanced-mode]enable、backend、ip-version增强模式
[enhanced-mode.tun]auto-route、address、routes、exclude-routes、dns-hijack、dns-namespacesTUN
[enhanced-mode.ebpf]unmatched-trafficLinux 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-controllerport、api-listen
protocols 的值 httpshttp
dialer_proxydialer-proxy
代理类型 ssh、mieru、sudoku—
上述六个以外的 [dns] 字段([dns.upstream]、nameserver-policy 等)以及 tls:// 上游见 DNS
代理组字段 use在 proxies 里列出成员
规则类型 SUB-RULE—
enhanced-mode.typebackend
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 不会影响正在运行的那一份。详见基础配置。