Skip to content
English下载

基础配置 ​

[general] 决定 Core 怎样路由流量、记录哪些日志、在哪里监听。每个字段都可以不写,不写就取默认值; 整个 [general] 都不写也是合法的。

toml
[general]
route-mode = "rule"
global-proxy = ""
log-level = "info"
log-file = true
port = 7890
protocols = "mixed"
allow-lan = false
api-listen = ""

字段 ​

字段类型默认值取值
route-mode字符串"rule"rule、global、direct(小写)
global-proxy字符串""节点、代理组、DIRECT 或 REJECT;route-mode = "global" 时必须存在
log-level字符串"info"trace、debug、info、warn(或 warning)、error、critical、off,不区分大小写
log-file布尔truefalse 时不写日志文件
port整数78901–65535;0 关闭本地端口
protocols字符串或数组"mixed"mixed、socks5(别名 socks)、http、none
allow-lan布尔falsetrue 时监听 0.0.0.0,否则监听 127.0.0.1
api-listen字符串""IP:端口、localhost:端口 或 [IPv6]:端口;为空表示不开 TCP 控制接口
ipv6布尔false能解析和保存,但 Core 里没有任何模块读取它

写了其他字段会报错:Unknown general field '<key>'。旧配置里的 api-secret 会被静默丢弃。

路由模式 ​

模式效果
rule每条连接按 [route].rules 匹配,第一条命中的生效
global所有连接都走 global-proxy
direct所有连接都直连;节点、代理组和规则照常加载,但不使用
toml
[general]
route-mode = "global"
global-proxy = "work"        # 节点或代理组

[[proxy]]
name = "work"
type = "socks5"
server = "proxy.example.org"
port = 1080
  • route-mode = "global" 而 global-proxy 为空或不存在时,加载失败: Global mode requires an existing proxy target。其他模式下不检查 global-proxy。
  • 写成 Rule、GLOBAL 会报错(Unknown mode),模式必须小写。
  • 在界面里切换模式只改正在运行的 Core,不会改文件。重新激活 Profile 时,只有当你在文件里改过 route-mode,文件里的值才会生效。

初次配置时可以按这个顺序排查:先用 direct 确认本机环境正常,再用 global 确认某个节点可用, 最后切到 rule。

日志 ​

log-level 决定 Core 记录多少日志。它同时过滤日志文件和界面 日志 页显示的内存日志(最近 5000 条)。 设为 off 两者都不再记录。

log-file = false 只停止写文件,内存日志照常工作。

日志文件写在日志目录:

平台日志目录
Windows%LOCALAPPDATA%\Specola\Logs;以 Windows 服务运行时为 %ProgramData%\Specola\Logs
macOS~/Library/Logs/com.specola.Specola
Linux$XDG_STATE_HOME/specola/log,默认 ~/.local/state/specola/log
  • 启动 Core 前设置环境变量 SPECOLA_LOG_DIR 可以换一个目录。它只影响日志。
  • 正式版每天一个文件,文件名为 specola_YYYY-MM-DD,零点换新文件,保留最近 7 个。
  • 还没有加载 Profile 时,Core 按 info 级别记录。

本地端口 ​

port 和 protocols 为支持代理设置的程序开一个本地端口。

toml
[general]
port = 7890
protocols = "mixed"          # 同一个端口同时支持 SOCKS5 和 HTTP
toml
[general]
port = 1080
protocols = ["socks5"]       # 只支持 SOCKS5
protocols接受
mixedSOCKS5 和 HTTP
socks5 或 socks只接受 SOCKS5
http只接受 HTTP,包含 CONNECT
none什么都不接受,不开端口
  • 数组可以列出多个值:["socks5", "http"] 等同于 mixed。
  • 数组不能为空(要关闭请写 "none"),不能重复同一协议(["mixed", "http"] 重复了 HTTP), none 不能和其他值一起写。
  • 没有 https 这个值。http 本身包含 CONNECT,HTTPS 网站照样能用。
  • port = 0 或 protocols = "none" 时只剩增强模式,没有显式代理端口。
  • 端口小于 1024 时能加载,但会告警;打开这样的端口需要管理员或 root 权限。

端口支持哪些请求 ​

端口根据每条连接的第一个字节区分 SOCKS5 和 HTTP。

客户端协议支持不支持
SOCKS5对 IPv4 地址、IPv6 地址或域名的 CONNECT用户名密码认证、UDP ASSOCIATE、BIND、SOCKS4
HTTPCONNECT host:port(HTTPS 及其他 TCP);带完整 http:// URL 的普通请求;或者路径加 Host 头代理认证(Proxy-Authorization 会被删掉)、一个连接上发多个请求
  • 端口只承载 TCP。程序发出的 UDP 只有通过增强模式才会进入 Specola。
  • 普通 HTTP 请求的响应带 Connection: close,一个连接只处理一个请求。
  • 请求头超过 64 KiB 时返回 431 并断开。
  • 经 SOCKS5 或 HTTP 传来的域名按原样参与域名规则匹配,Core 不需要先解析它。

客户端这样设置:

bash
curl -x http://127.0.0.1:7890 https://example.com
curl -x socks5h://127.0.0.1:7890 https://example.com
export ALL_PROXY=socks5h://127.0.0.1:7890

Core 从不修改操作系统的代理设置。界面里有一个开关可以在运行时停止、开启这个端口;在那里停掉的端口, 重新激活 Profile 后仍然保持停止。

[general.inbound] ​

旧配置把这两个字段写在子表里,现在仍然可用:

toml
[general.inbound]
port = 7890
protocols = "mixed"

两种写法只能选一种。port(或 protocols)两处都写会报错: Configure general.port only once; do not also use general.inbound。子表里写其他字段也会报错。

局域网访问 ​

allow-lan = true 时端口绑定到 0.0.0.0,局域网里的其他设备也能使用。只绑定 IPv4。

  • 端口没有认证。能连到它的人都能用你的节点。只在可信网络里打开,并用防火墙限制来源。
  • 来自其他设备的连接没有进程信息,进程规则对它们永远不命中。请改用 SRC-IP-CIDR 分流(见分流规则)。

控制接口 ​

桌面应用总是通过本地通道和 Core 通信:Windows 上是命名管道,macOS 和 Linux 上是 Unix socket, 不需要任何配置(见 CLI)。api-listen 额外开一个 TCP 监听,让脚本或另一台机器上的 应用控制这个 Core。它使用同样的 MessagePack-RPC 协议,不是 HTTP,详见控制接口。

toml
[general]
api-listen = "0.0.0.0:9090"      # 也可以是 "127.0.0.1:9090"、"[::1]:9090"、"localhost:9090"
  • 地址必须是 IP 字面量或 localhost,后面跟 1–65535 的端口。写成 router.lan:9090 这样的主机名会报错: general.api-listen must be IP:port, localhost:port, or [IPv6]:port。
  • 无论绑定哪个地址,Core 只为本机和私有网络的客户端服务:回环、10.0.0.0/8、172.16.0.0/12、 192.168.0.0/16、100.64.0.0/10(CGNAT、Tailscale)、169.254.0.0/16、fc00::/7 和 fe80::/10, 以及这些地址的 IPv4 映射 IPv6 形式。其他客户端一连上就会被断开,并记入日志。
  • 没有认证,也没有加密。这些网络里的任何设备都能读取流量统计、修改路由、编辑 Profile。 绝对不要把这个端口映射到公网。
  • license.* 和 core.shutdown 通过 TCP 调用会被拒绝,只能走本地通道。
  • 同一时间最多接受 8 个连接。
  • 修改或删除 api-listen 后重新激活 Profile 即生效。Core 先打开新的监听,再让旧的继续服务约两秒, 保证发出这次修改的客户端能收到完整回复。新地址打不开(端口被占用、地址不属于本机)时,激活失败, 一切保持原样。

在 Linux 路由器上以 --gateway 启动时,Core 还会在加载任何 Profile 之前,在 LAN 地址的 9090 端口 打开控制监听,见 CLI。

ipv6 ​

general.ipv6 能解析、能保存,界面也会显示,但 Core 不使用它。DNS 是否返回 IPv6 由 [dns].ipv6 控制,是否接管 IPv6 流量由 [enhanced-mode].ip-version 控制。

改动如何生效 ​

重新激活 Profile 后,[general] 的所有改动都会应用到正在运行的 Core,不需要重启。

改动效果
log-level、log-file立即生效
route-mode、global-proxy对新连接生效
port、protocols、allow-lan监听迁移到新设置,已建立的连接不受影响
api-listenTCP 监听按上文所述迁移

Linux 上增强模式使用 eBPF 时,监听的改动会重建整个运行时,已建立的连接会断开。任何一步失败, 前面已完成的步骤都会撤销。加载失败的 Profile 不会影响正在运行的那一份。

报错 ​

报错原因
Unknown general field '<key>'字段拼错,或已被移除
general.port must be an integer写成了 port = "7890"
Invalid mixed port: <n>port 不在 0–65535 之间
inbound.type contains unsupported value '<v>' (expected mixed, socks5, http, or none)protocols 的值不对,包括 https
inbound.type contains duplicate protocol '<v>'同一协议写了两次,例如 ["mixed", "http"]
inbound.type none cannot be combined with another protocol["none", "http"]
inbound.type array must not be empty; use 'none' explicitlyprotocols = []
Unknown mode: <v> (should be rule/global/direct)route-mode 写错或大小写不对
Global mode requires an existing proxy targetglobal 模式下 global-proxy 为空或不存在
Unknown log level: <v>log-level 写错
general.api-listen must be IP:port, localhost:port, or [IPv6]:port写了主机名、缺端口或端口为 0
Use general.port and general.api-listen旧配置里的 mixed-port 或 external-controller

关于 protocols 的报错写的是 inbound.type,因为 Core 内部用这个名字读取 protocols。

旧版字段名 ​

旧写法现在
mixed-portport(报错)
external-controllerapi-listen(报错)
顶层 [inbound][general] 里的 port 和 protocols(报错)
protocols = ["http", "https"]protocols = "http"(报错)
api-secret不需要:控制接口没有密钥(静默丢弃)

排错 ​

  1. 程序连不上端口。 确认 protocols 包含客户端使用的协议,且端口没有被别的程序占用;端口打不开时, 激活会失败并给出原因。客户端设成 SOCKS4,或设成带密码的 SOCKS5,都会被拒绝。
  2. 其他设备连不上端口。 设置 allow-lan = true,使用本机的 IPv4 地址,并在防火墙里放行端口。
  3. 远程客户端连不上控制接口。 客户端必须在私有网络里,公网地址一连上就会被断开(日志里搜索 refused TCP client)。经 VPN 访问时,请使用 100.64.0.0/10 或其他私有网段的地址。
  4. 没有日志文件。 检查 log-file 和 log-level,到对应平台的日志目录查找;如果设置了 SPECOLA_LOG_DIR,就去那个目录找。

另见完整配置了解所有配置段,以及 CLI 了解如何自己运行 Core。