4. 配置文件模型#

Link1 使用 YAML 配置。你可以把配置文件看成一份“网络行为说明书”：哪些端口接收流量，DNS 怎么解析，哪些出口可用，规则如何选择出口。

App 配置与内核配置#

Link1 App 会管理配置档案、运行状态和页面展示；内核配置只描述网络行为。普通用户主要需要理解内核配置中的这些部分：

配置部分	负责什么	是否必须
基础运行	端口、模式、日志级别、局域网访问	至少需要一个入口
DNS/hosts	域名解析、Fake-IP、静态域名映射	TUN/透明代理强烈建议配置
入站接管	`mixed-port`、TUN、透明代理、协议 listener	至少需要一种入口
出站与策略	节点、订阅、策略组	需要一个可被规则引用的出口
规则	决定连接走哪里	推荐至少有 `MATCH` 兜底
高级能力	HTTP Engine、设备发现、NTP、实验开关	按需开启

App 相关的内部状态不建议用户手写进主配置。用户文档只介绍会影响网络行为的字段。

顶层结构#

常见完整结构如下：

# 1. 基础运行
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

# 2. DNS 与 hosts
dns: {}
hosts: {}
hosts-providers: {}

# 3. 入站接管
tun: {}
app-proxy: {}
sniffer: {}
listeners: []

# 4. 出站与策略
proxies: []
proxy-providers: {}
proxy-groups: []

# 5. 规则
rule-providers: {}
rule-sets: {}
sub-rules: {}
rules: []

# 6. 高级能力
http-engine: {}
device-discovery: {}
profile: {}
tls: {}
experimental: {}
ntp: {}
iptables: {}

你不需要一次写完所有块。最小配置只需要入口、出站和规则。

YAML 基础#

YAML 用缩进表达层级：

proxies:
  - name: node-a
    type: socks5
    server: 127.0.0.1
    port: 1080

注意：

用空格缩进，不要用 Tab。

字段名大小写和短横线要写对，如 mixed-port。

字符串里有特殊字符时建议加引号。

列表用 -。

map 用 key: value。

同一级缩进必须对齐；缩进错位会导致字段被放到错误层级。

名称与引用#

Link1 里很多对象通过名称引用：

proxies:
  - name: node-a
    type: socks5
    server: 127.0.0.1
    port: 1080

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - node-a
      - DIRECT

rules:
  - MATCH,PROXY

实际影响：

node-a 是出站节点名称。

PROXY 是策略组名称。

rules 的 action 可以引用节点或策略组。

名称必须唯一，不能和内置动作冲突。

引用不存在的名称会在配置编译时报错。

命名建议：

类型	推荐风格	例子
手写节点	简短但可识别线路	`hk-1`、`jp-hy2`
订阅 provider	体现来源	`airport`、`office-vpn`
手动策略组	大写业务名	`PROXY`、`AI`、`MEDIA`
自动策略组	体现算法	`AUTO`、`FALLBACK`
规则集	小写类别	`private`、`china`、`reject`

内置动作#

Link1 内置：

名称	含义
`DIRECT`	直连目标
`REJECT`	拒绝连接

你也可以显式创建 type: direct 或 type: reject 节点，但普通配置通常直接使用内置动作即可。

路径解析#

很多字段可以写文件路径：

proxy-providers.*.path

rule-providers.*.path

hosts-providers.*.path

证书和私钥字段，如 certificate、private-key、ca

HTTP Engine 的 file、body-file、spool-dir

建议：

proxy-providers:
  airport:
    type: http
    url: https://example.com/sub.yaml
    path: ./providers/airport.yaml

实际影响：

路由器或服务部署时，推荐使用固定工作目录和相对路径，便于整体迁移。

如果路径文件不存在，HTTP provider 可下载生成；file provider 则通常需要文件已存在。

App 导入配置时，应确保引用的本地文件也被放到对应配置目录中。

默认值与显式值#

有些字段有默认值，例如：

字段	默认值	影响
`mode`	`rule`	按规则路由
`log-level`	`info`	输出 info 级别日志
`allow-lan`	`false`	默认不开放局域网
`bind-address`	`*`	配合端口监听地址
`ipv6`	`true`	总体允许 IPv6，但 DNS 仍有自己的 `dns.ipv6`
`find-process-mode`	`strict`	进程规则按严格模式获取进程信息
`profile.store-selected`	`true`	持久化策略组选择
`profile.store-fake-ip`	`true`	持久化 Fake-IP 映射

默认值让配置更短，但不代表你不需要理解它们。例如 allow-lan=false 很安全，但局域网设备会连不上。

配置编译与错误定位#

Link1 内核启动前会把 YAML 编译成运行时结构。编译阶段会检查：

端口范围是否合法。

必填字段是否缺失。

协议是否支持某个字段。

规则 action 是否存在。

provider 类型和格式是否合法。

TUN/透明代理字段是否符合平台限制。

DNS server scheme 是否支持。

错误示例：

compile config "config.yaml": proxy-groups[0].proxies[1]="node-x" is undefined

读法：

proxy-groups[0]：第一个策略组。

proxies[1]：该组的第二个成员。

node-x is undefined：引用了不存在的节点或组。

排错技巧：

先看路径：proxies[3]、rules[12]、dns.nameserver[1] 指向错误位置。

再看对象名：很多错误来自拼写不一致。

最后看组合限制：例如 TUN 和平台透明入口不能同时启用，某协议不支持某个传输层。

配置分层建议#

Link1 的主配置是一个 YAML 文件。用户手册里的示例都按单文件展示，是为了让复制、导入和排障更简单。

如果你熟悉其他工具里的 !include，需要注意：Link1 不依赖 YAML !include 来拆主配置。App 导入配置档案时会以一份主 YAML 为中心管理配置；相对路径则用于引用外部资源，例如 provider 文件、规则文件、证书、HTTP Engine 脚本、Mock body。这样迁移时只要保证这些文件和主配置的相对位置不变即可。

推荐目录组织方式：

link1/
  config.yaml
  providers/
    airport.yaml
  rules/
    private.yaml
    reject.yaml
  certs/
    ca.pem
    client.key
  http-engine/
    scripts/
      rewrite.js
    bodies/
      mock.json

这样做的好处：

主配置只保留“网络行为”：入站、DNS、出站、策略组、规则。

订阅/provider、规则集、证书、脚本和 Mock body 有固定位置。

排障时能从错误路径快速定位，例如 http-engine/scripts/rewrite.js 或 rules/private.yaml。

App 导入/导出配置档案时更容易整体迁移。

拆分时的经验：

内容	建议放哪里	原因
主入口配置	`config.yaml`	App 导入、校验、应用都以它为入口。
订阅缓存/本地 provider	`providers/`	避免和手写节点混在一起。
规则集	`rules/`	规则经常更新，单独维护更清楚。
证书/私钥	`certs/`	便于设置权限，也便于排查路径错误。
HTTP Engine 脚本	`http-engine/scripts/`	脚本通常比 YAML 长，单独文件更容易调试。
Mock body	`http-engine/bodies/`	保持 YAML 简洁，避免长文本转义。

如果要把配置发给别人排查，只发主 YAML 往往不够；凡是被 file:、path:、provider 或规则集引用的文件，都要一起提供，敏感凭据需先脱敏。

常见配置块关系#

proxies            静态出站节点
proxy-providers    动态或订阅出站节点
proxy-groups       把节点/Provider 节点组合成出口
rules              把连接导向节点或策略组
rule-providers     大量规则来源
rule-sets          编译后的规则集或内联规则集
sub-rules          子规则流程

dns                解析域名与 Fake-IP
hosts              静态域名映射
hosts-providers    外部 hosts 文件
sniffer            从流量中嗅探域名

mixed-port/port/socks-port/redir-port/tproxy-port/tun/app-proxy/listeners
                   决定流量如何进入 Link1

一份配置怎样逐步长大#

阶段 1：确认入口可用#

mixed-port: 7890
rules:
  - MATCH,DIRECT

目标：确认内核启动、客户端能连接。

阶段 2：加入一个出站节点#

proxies:
  - name: node-a
    type: socks5
    server: 127.0.0.1
    port: 1080
proxy-groups:
  - name: PROXY
    type: select
    proxies: [node-a, DIRECT]
rules:
  - MATCH,PROXY

目标：确认代理节点能用。

阶段 3：加入 DNS 和域名规则#

dns:
  enable: true
  nameserver:
    - https://dns.google/dns-query
rules:
  - DOMAIN-SUFFIX,example.com,PROXY
  - MATCH,DIRECT

目标：确认域名规则命中。

阶段 4：再加入 TUN、订阅、规则集或 HTTP Engine#

每次只加一类高级能力，并在 App 中观察连接、规则和日志变化。

不推荐的写法#

一上来就开启所有高级能力#

不要在第一次配置时同时开启 TUN、Sniffer、HTTP Engine、多个 provider、复杂规则。先用 mixed-port + MATCH,DIRECT 或一个上游节点验证基础链路，再逐步加功能。

把所有流量都交给 Sniffer 补救#

Sniffer 是补充手段，不是 DNS 配置的替代品。TUN/透明代理场景应优先让 DNS 进入 Link1。

复制其他内核配置后不验证#

Link1 兼容常见字段，但不是所有历史字段都支持。迁移配置后先运行 App 校验，或直接运行：

spark -f config.yaml -t