Skip to content
English下载

架构 ​

Specola 由两个程序组成。Core 负责所有网络工作,Specola 应用是控制 Core 的桌面界面。两者只通过控制接口通信, 所以 Core 也可以单独运行、配合别的界面,或由脚本驱动。

text
 Specola app (Qt Quick)      scripts, remote app
          │                         │
          │ local IPC               │ TCP (api-listen, optional)
          ▼                         ▼
 ┌──────────────────── Core ────────────────────┐
 │ control API → CoreRuntime                    │
 │   proxies · routing · local port · DNS       │
 │   Enhanced Mode · health checks · tools      │
 │   telemetry · logging · license              │
 └──────────────────────────────────────────────┘

Core 与应用 ​

CoreSpecola 应用
可执行文件specola-service.exe(Windows)、specola-core(macOS、Linux)Specola 桌面应用
源码src/(C++20、Asio)gui/qml/(Qt Quick)
负责Profile、监听、DNS、规则、代理协议、增强模式窗口、托盘、主题、页面状态
是否需要管理员权限仅增强模式需要从不需要

谁来启动 Core:

平台启动者生命周期
Windows(安装版)服务控制管理器,以 specola-service 服务(LocalSystem)运行独立于应用;应用请求它启动和停止
macOS、Linux应用,作为子进程,带 --parent-pid应用退出时随之退出
任意平台你在终端里启动(--config <文件>)直到 Ctrl+C;应用会连接它

应用启动时先尝试连接正在运行的 Core,没有响应才自己启动一个。一台电脑上只能运行一个 Core,第二个会立即以 Another specola-core process is already running 退出。

不带 --config 启动的 Core 会等待应用激活 Profile。某个 Profile 启动失败时,Core 仍保持控制接口开放,以便换一个 Profile。

控制接口 ​

应用与 Core 之间使用 MessagePack RPC。请求、应答和数据流定义在 api/*.toml 中(例如 profile.activateProfile、 proxy.selectGroupMember、routing.setMode)。见控制接口。

传输方式地址谁能连接
本机 IPC(始终开启)Windows:命名管道 \\.\pipe\specola;macOS、Linux:Unix 套接字 /tmp/specola.sockWindows:本机用户;macOS、Linux:启动 Core 的用户(套接字权限 0600,Core 以 root 运行时归属发起启动的用户)
TCP(可选)[general] api-listen,例如 "127.0.0.1:9090"只接受回环和私有网段的客户端:10/8、172.16/12、192.168/16、100.64/10、169.254/16、fc00::/7、fe80::/10
  • --ipc-endpoint <路径> 可以改变本机 IPC 地址。
  • TCP 接口没有认证。除非信任网络里的每台设备,否则请绑定到回环地址。许可证相关操作和 core.shutdown 在 TCP 上一律拒绝。
  • api-listen 跟随 Profile:激活 Profile 时打开、迁移或关闭,不需要重启。
  • 尚未加载 Profile 时,只响应 sys.*、core.*、profile.*、license.*、overview.*、ssh.* 和 gateway.* 方法,其他方法返回 Core initialization is not complete。Profile 加载期间,请求返回 Core is loading a Profile。

应用还会告诉 Core 用户的 Profiles 目录在哪里(profile.setDirectory)。之后 Core 以该用户的身份读写 Profile 文件, 即使 Core 本身以 root 或 LocalSystem 运行。你在应用里编辑节点或规则时,由 Core 把改动写入 Profile 文件并重新加载; 加载不了的改动不会保存。

Core 内部 ​

Core 持有一份不可变的配置快照,以及由它构建出的各个部分(CoreRuntime,src/core/core_runtime.hpp):

部分职责
日志日志级别、内存日志、按天的日志文件
许可证许可证状态(数据目录里的 license.json)
统计连接、每条规则、每个节点和总流量的计数
节点每个 [[proxy]] 和 [[proxy-group]] 一个实例,以及代理组的成员选择
路由规则表、路由模式、bypass、兜底出站、Fake-IP 与 DNS 映射
入口本地 HTTP/SOCKS5 端口
DNS应答被接管的查询、Fake-IP 地址池、可选的 DNS 监听
增强模式Windows 和 macOS 上的 TUN,Linux 上的 eBPF
健康检查定期对代理组成员做 URL 测试
工具通过控制接口提供的延迟测试等,见工具

启动顺序:许可证、节点和代理组、规则、DNS、本地端口、健康检查,最后是增强模式——等它要把流量导入的各部分都就绪之后。 在 Linux 上,路由器网关(--gateway <文件>)与这些部分并行运行,可以为局域网客户端使用 DNS 模块。

Windows 服务模式 ​

Windows 安装程序把 Core 注册为 specola-service 服务。它以 LocalSystem 身份运行,所以应用以普通权限运行时也能使用增强模式。

  • 服务自己的数据放在 %ProgramData%\Specola,只有 SYSTEM 和 Administrators 可以读写。
  • 服务没有自己的 Profiles 目录。应用会绑定当前登录用户的 %LOCALAPPDATA%\Specola\profiles,服务以该用户身份读取。
  • 命名管道允许交互式用户连接,所以未提权的应用可以控制它。
  • 被强制结束的 Core 可能留下 Windows 的 DNS 重定向(一条 NRPT 规则)。Core 每次启动都会清除它;也可以以管理员身份 运行 specola-service.exe --reset-network 手动清除。

数据目录 ​

目录WindowsmacOSLinux
数据(资源、license.json)%LOCALAPPDATA%\Specola~/Library/Application Support/com.specola.Specola$XDG_CONFIG_HOME/specola(~/.config/specola)
Profiles<数据>\profiles<数据>/profiles<数据>/profiles
下载缓存<数据>\Cache\remote~/Library/Caches/com.specola.Specola/remote$XDG_CACHE_HOME/specola/remote
日志<数据>\Logs~/Library/Logs/com.specola.Specola$XDG_STATE_HOME/specola/log
运行时<数据>\Runtime~/Library/Caches/com.specola.Specola/runtime$XDG_RUNTIME_DIR/specola
  • Windows 服务使用 %ProgramData%\Specola 作为数据目录。
  • SPECOLA_LOG_DIR 可以改变日志目录,其他目录没有改动的选项。
  • 通过 sudo 或 polkit 启动的 Core 使用发起启动的那个用户的目录。

Profiles 目录里的内容:

text
profiles/
├── work.toml                  a profile
├── work.toml.modules          modules it applies, one per line (optional)
├── work.toml.disabled-rules   rules switched off in the app (optional)
├── modules/home-lan.toml      a module, see Modules
└── .removed/                  removed profiles, kept here

从 Profile 文件到运行中的配置 ​

激活 Profile(或通过 --config 指定)时,Core 依次:

  1. 读取文件,然后合并 <profile>.modules 里列出的模块。
  2. 丢弃 [metadata] 等被忽略的段落并给出告警,拒绝未知字段。
  3. 把结果解析成内部配置(AppConfig)并检查:名字、引用、规则语法、FINAL 是否在最后、平台限制。
  4. 找到 Profile 引用的文件(相对路径依次在 Profile 所在目录、数据目录、可执行文件旁的 resources/ 中查找), 下载远程的 GeoIP、GeoSite 和规则集文件,下载失败时使用缓存。
  5. 应用 <profile>.disabled-rules。

--test-config 正是执行这些步骤后停止。任何错误都会中止加载,正在运行的 Profile 不受影响。

然后:

  • 第一个 Profile: Core 构建并启动所有部分(CoreRuntime::bootstrap)。
  • 之后的 Profile: Core 把新配置和正在运行的配置比较(ConfigDiff),只就地应用差异:监听、控制接口、节点表和规则表、 DNS、增强模式、日志设置、路由模式。不能就地应用的改动(以及 Linux eBPF 下监听、DNS、增强模式或嗅探的任何改动) 会按新配置重建所有部分。重建失败时,Core 重建之前的配置;如果连这一步也失败,Core 会停止,需要重新启动。

重新加载时保留什么,见工作原理。

另见 ​