EasyTier 配置参数详解

适用版本：EasyTier 2.6.4（源码 commit 164e2db6aecd13117d840821d5b889b51cb7c463，提交说明 feat(core): expose WireGuard client traffic metrics (#2537)）。

事实基准：本档全部结论以该 commit 的源码为准，关键结论均标注 文件:行号 出处（相对 EasyTier 仓库根目录）。官方文档（https://easytier.cn/guide/network/configurations.html 等）作为补充信息引用并注明"官方文档"；两者不一致时以源码为准（差异汇总见第 8.5 节）。

覆盖范围：命令行版 easytier-core（全部命令行参数、配置文件 TOML 全部字段、优先级/合并规则）与 easytier-cli（全部子命令与参数），以及使用 RPC 管理通道连接其他 easytier-core 的方法（第 6 章专门说明"GRPC"一词在 EasyTier 中的真实含义）。

不包含：GUI（easytier-gui）、easytier-web 控制台细节与任何第三方版本的内容。

目录

1. 第 1 章　简介与版本信息（阅读方法与通用约定）
2. 第 2 章　easytier-core 命令行参数详解（89 个参数逐条详解）
3. 第 3 章　easytier-core 配置文件（TOML）字段详解
4. 第 4 章　配置文件与命令行的优先级与合并规则
5. 第 5 章　easytier-cli 全部子命令与参数详解（17 个顶层子命令 / 共 56 条命令）
6. 第 6 章　连接 easytier-core：管理 RPC 通道（原"gRPC"章节需求）
7. 第 7 章　常用完整组网示例
8. 第 8 章　附录：参数速查表与差异说明

第 1 章　简介与版本信息

1.1 EasyTier 与本文档范围

EasyTier 是一个使用 Rust 编写的去中心化（无中心服务器也可组网）P2P VPN / 虚拟组网工具，官方自我描述为 "A full meshed p2p VPN, connecting all your devices in one network with one command."（easytier/Cargo.toml:3）。

命令行发行版压缩包内含 4 个可执行程序（官方下载页说明）：

本文只覆盖命令行版，不包含 GUI（easytier-gui）与第三方版本。

1.2 版本信息

1.3 阅读本档的方法

• 每个参数独立成条，固定字段：名称（含短选项）、类型、默认值、环境变量、功能说明、示例、注意事项、源码出处。参数存在短选项时在条目标题中一并给出（如 -i, --ipv4）；无短选项的条目不再单列"短选项"字段。
• 源码出处格式为 文件:行号，相对 EasyTier 仓库根目录（例如 easytier/src/core.rs:95）。
• 帮助文本（本文中写作"帮助文本"）引自 easytier/locales/app.yml 的 zh-CN 词条（CLI 按 rust_i18n 按系统 locale 选择语言，回退 en；Linux 下 export LANG=zh_CN 可让帮助显示中文——官方 FAQ）。
• "官方文档"字样指 easytier.cn 文档站的说明；官方页自称"更多配置项请参考 easytier-core --help 输出"，即官方也承认其参数表并非穷尽，一切以源码为准。

1.4 通用约定（全档适用）

① "可选值 bool"：指该参数定义为 num_args = 0..=1, default_missing_value = "true"（clap）。可以只写 --xxx（等价 --xxx=true），也可以写 --xxx=false。

② "多值"：指 value_delimiter = ','（逗号分隔）和/或 num_args = 0..（空格分隔 / 可重复参数）。例如 -p tcp://a:11010,udp://b:11010 与 -p tcp://a:11010 -p udp://b:11010 等价。

③ 环境变量（ET_*）：除下表所列外，其余全部 CLI 参数都支持同名 ET_<大写下划线参数名> 环境变量（clap env = "..." 属性）。命令行 > 环境变量。

④ 编译特性（feature）门控：以下参数/协议随编译 feature 存在，官方发行版一般全部开启：

⑤ 全部参数均非必填：easytier-core 无任何参数也能运行——此时网络身份为 network_name = "default"、network_secret = ""（NetworkIdentity::default，easytier-core/src/config/mod.rs:235-239），即加入名为 default 的默认网络。

⑥ 组网身份：虚拟网络的唯一身份是 network_name + network_secret（[network_identity]）。同网同名同密钥的节点才能互通；网络名支持中文（官方文档），与其他用户的网络名冲突可能导致组网失败（官方快速组网页）。

第 2 章　easytier-core 命令行参数详解

本章逐条详解 easytier-core 的全部 89 个命令行参数：进程与配置来源选项（Cli，8 个）+ 网络选项（NetworkOptions，74 个）+ 日志选项（LoggingOptions，5 个）+ RPC 门户选项（RpcPortalOptions，2 个）。参数定义集中在 easytier/src/core.rs（Cli 85-140、NetworkOptions 142-763、LoggingOptions 765-801、RpcPortalOptions 803-820）。

2.1 配置的三种来源与启动流程

easytier-core 的配置有三种来源，最终都归一到同一个 TOML 配置模型 TomlConfigLoader（TomlConfig 的类型别名，easytier-core/src/config/toml.rs:1191）再启动网络实例（run_main，easytier/src/core.rs:1498-1664）：

1. 命令行直接创建：既没有 -c/--config-file、没有 --config-dir、也没有 --config-server 且非 --daemon 时，用空配置起底，把全部 CLI 网络参数合并进去，启动 1 个实例（core.rs:1577-1585, 1622-1637）。
2. 配置文件：-c（可多个）或 --config-dir（目录内全部 .toml）逐个加载，每个文件 = 一个独立网络实例；满足合并条件时 CLI 参数会合并进该文件配置（见第 4 章）。
3. 配置服务器：-w/--config-server 连接 Web 配置服务器，由远端下发配置；可配合 --config-dir 持久化下发内容。

进程级选项（日志 5 个、-r/--rpc-portal、-w/--config-server、--machine-id、--config-dir、--daemon、--check-config、--gen-autocomplete、--disable-env-parsing）不参与"CLI 覆盖配置文件"的合并体系，对整个进程生效（core.rs:1498-1664）。

2.2 进程与配置来源选项（Cli，8 个）

-w, --config-server <URL>

• 类型/默认值：String；无默认（不连接配置服务器）。环境变量：ET_CONFIG_SERVER。
• 功能：连接 Web 配置服务器（如官方托管控制台或自建 easytier-web），由远端下发网络配置。帮助文本："配置服务器地址，必须使用完整 URL：--config-server udp://127.0.0.1:22020/admin，udp 可以根据配置服务器替换为 tcp、ws、wss（配置服务器 ws 被代理为 wss 时）"。
• 示例：easytier-core -w udp://203.0.113.9:22020/admin-token-123
• 注意：
  • URL 最后一段路径作为认证 Token，不可为空（ConfigServerEndpoint::parse，easytier-core/src/management/full/web_client.rs:54-78）；非 ws/wss 协议会剥掉 path 再作为连接地址。
  • ⚠️ 与官方文档不一致：官方文档写有"仅用户名 --config-server admin（使用官方服务器）"的简写形式，但本 commit 源码未实现——裸词无法通过 Url::parse，必须给完整 URL（差异见 8.5 节）。
  • 可与 --config-dir 共存：远端下发的配置持久化到该目录。
  • 该选项是进程级的，不参与第 4 章的合并体系。
• 出处：easytier/src/core.rs:85-140；easytier/src/web_client/mod.rs:105-162。

--machine-id <ID>

• 类型/默认值：String（uuid 格式）；默认从本地持久化状态读取，首次启动时可能基于系统信息生成，之后保持固定。环境变量：ET_MACHINE_ID。
• 功能：Web 配置服务器通过 machine id 识别机器，用于断线重连后的配置恢复；需要保证唯一且固定不变。
• 示例：easytier-core -w udp://1.2.3.4:22020/t --machine-id 018f4fb1-7a2c-7d1f-9d89-935b0ad7e135
• 注意：仅在配合 -w/--config-server 时有意义（core.rs:1512-1523 传入 MachineIdOptions）。
• 出处：easytier/src/core.rs:85-140。
• 配置文件：无对应配置文件字段（进程级参数，仅命令行/环境变量；仅配合 -w/--config-server 使用，core.rs:1512-1523）。与 TOML 顶层 instance_id 不是同一概念：instance_id 是网络实例的 UUID（仅 TOML，3.3 节），--machine-id 是向配置服务器标识"机器"的 UUID（easytier/src/common/machine_id.rs:18-30），二者不互相映射。

-c, --config-file <PATH>...

• 类型/默认值：Vec<PathBuf>，多值（逗号分隔、可重复、num_args=1..）；无默认。环境变量：ET_CONFIG_FILE。
• 功能：加载 TOML 配置文件。帮助文本："配置文件路径，注意：命令行中的配置的选项会覆盖配置文件中的选项"。每个文件启动 1 个独立网络实例。
• 示例：easytier-core -c /etc/easytier/layer1.toml；从 stdin 读入：cat a.toml | easytier-core -c -；多文件：easytier-core -c a.toml -c b.toml。
• 注意：
  • 特殊值 - 表示从 stdin 读 TOML，且 stdin 配置视为静态配置（不可通过 RPC 修改）（easytier/src/common/config.rs:68-76）。
  • --check-config 依赖本参数（缺省报错，core.rs:1785-1788）。
  • 与 --config-dir 叠加时全部一起加载。
  • 官方文档示例使用 .yaml 扩展名（easytier-core -c ./config.yaml），但内容格式实为 TOML——这是官方文档自身的命名不一致，建议用 .toml。
• 出处：easytier/src/core.rs:85-140；easytier/src/common/config.rs:62-112。

--config-dir <DIR>

• 类型/默认值：PathBuf；无默认。环境变量：ET_CONFIG_DIR。
• 功能：加载目录中所有 .toml 文件（各启动 1 个实例），并将配置服务器下发的配置保存在此目录中。
• 示例：easytier-core --config-dir /etc/easytier/conf.d
• 注意：传入非目录路径会直接报错（core.rs:1556-1558）；目录内文件按目录读取顺序加载。CLI 网络参数要作用于目录内文件，须满足第 4.2 节的合并条件（通常需要 --network-name 匹配）。
• 出处：easytier/src/core.rs:85-140。

--gen-autocomplete <SHELL>

• 类型/默认值：枚举 bash|elvish|fish|powershell|zsh|nu；无默认。环境变量：无。
• 功能：生成对应 shell 的补全脚本，打印到 stdout 后立即退出。
• 示例：easytier-core --gen-autocomplete bash > ~/.bash_completion.d/easytier-core
• 注意：nu（Nushell）走专用生成器；easytier-cli 侧有对应子命令 gen-autocomplete（第 5.4.17 节）。
• 出处：easytier/src/core.rs:85-140, 1749-1758。
• 配置文件：无对应配置文件字段（进程动作类参数：打印补全脚本后立即退出，core.rs:1749-1758；仅命令行）。

--check-config

• 类型/默认值：可选值 bool；无默认（开关）。环境变量：无。
• 功能：校验 -c 给出的每个配置文件（含 stdin -）能否解析为合法 TOML 配置；成功退出码 0，失败 1，不启动网络。
• 示例：easytier-core --check-config -c /etc/easytier/mynet.toml
• 注意：必须同时给 -c，否则报错（core.rs:1785-1788）。
• 出处：easytier/src/core.rs:85-140, 1760-1768, 1783-1804。

--daemon

• 类型/默认值：可选值 bool；无默认（开关）。环境变量：无。
• 功能：以守护进程模式运行：持有 DaemonGuard，即使所有网络实例都停止，进程也不退出，适合配合配置服务器常驻等待下发。
• 示例：easytier-core --daemon -w udp://203.0.113.9:22020/token
• 注意：--daemon 模式禁止"从 CLI 参数创建实例"（core.rs:1577-1579）——必须至少有配置文件或配置服务器，否则进程空跑。
• 出处：easytier/src/core.rs:85-140；easytier-core/src/instance/manager.rs:308-313, 427-440。

--disable-env-parsing

• 类型/默认值：可选值 bool；无默认（开关）。环境变量：无。
• 功能：禁用配置文件中的环境变量解析，即关闭 TOML 文本内 ${VAR}、$VAR、${VAR:-default} 的展开（easytier/src/common/config.rs:81-91；展开实现 easytier/src/common/env_parser.rs:21-40）。
• 示例：easytier-core -c secret.toml --disable-env-parsing
• 注意：注意区分两个独立机制——本参数关闭的是"配置文件文本内的变量展开"；CLI 参数自身的 ET_* 环境变量读取不受影响。
• 出处：easytier/src/core.rs:85-140。

2.3 网络基础选项（NetworkOptions 前半）

--network-name <NAME>

• 类型/默认值：String；缺省 "default"。环境变量：ET_NETWORK_NAME。
• 功能：标识此 VPN 网络的网络名称（帮助文本）。虚拟网络身份的第一要素：同网同名同密钥才能互通。
• 示例：easytier-core --network-name mynet --network-secret s3cret
• 注意：支持中文（官方文档）；与其他用户网络名冲突可能导致组网失败（官方快速组网页）。它还是"CLI 参数合并进配置文件"的匹配键之一（第 4.2 节）。
• 出处：easytier/src/core.rs:142-306；默认值 easytier-core/src/config/mod.rs:235-239。

--network-secret <SECRET>

• 类型/默认值：String；缺省空串。环境变量：ET_NETWORK_SECRET。
• 功能：网络密钥，用于验证此节点属于 VPN 网络（帮助文本）。
• 示例：--network-secret 'replace-with-a-strong-secret'
• 注意：与 --credential 互斥语义（凭据模式下不能有 secret，第 4.4 节）；无 secret 的网络等于不设防，生产环境务必设置强密钥。
• 出处：easytier/src/core.rs:142-306；easytier-core/src/config/toml.rs:703-737。

-i, --ipv4 <CIDR>

• 类型/默认值：String（解析为 Ipv4Inet）；无默认——为空则仅转发数据包，不创建 TUN 设备（帮助文本）。环境变量：ET_IPV4。短选项：-i。
• 功能：设置本节点虚拟 IPv4 地址。
• 示例：-i 10.144.144.10（自动补掩码）；-i 10.144.144.10/24。
• 注意：
  • 省略掩码时（如 10.0.0.1）按 /32 解析后自动改为 /24（easytier-core/src/config/toml.rs:803-816）。
  • 与 -d/--dhcp 互斥语义：同时给出时 CLI -i 值生效。
  • 虚拟 IP 网段不能与其他虚拟网重叠（官方多实例要求）。
• 出处：easytier/src/core.rs:142-306。

--ipv6 <CIDR>

• 类型/默认值：String（解析为 Ipv6Inet）；无默认。环境变量：ET_IPV6。
• 功能：本节点的虚拟 IPv6 地址，可与 IPv4 一起双栈运行（帮助文本）。
• 示例：--ipv6 fdab::10/64
• 注意：受 --disable-ipv6 影响。
• 出处：easytier/src/core.rs:142-306。
• 配置文件：对应字段 ipv6（顶层），示例：ipv6 = "fdab::10/64"；合并语义：覆盖（第 4.4 节）。

--ipv6-public-addr-provider

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_IPV6_PUBLIC_ADDR_PROVIDER。
• 功能：将此节点的公网 IPv6 子网共享给其他节点，使它们也能获得公网 IPv6 地址；仅 Linux 支持（帮助文本）。
• 示例：easytier-core --ipv6-public-addr-provider
• 注意：可配 --ipv6-public-addr-prefix 手动指定子网；"消费方"是 --ipv6-public-addr-auto。
• 出处：easytier/src/core.rs:142-306。
• 配置文件：对应字段 ipv6_public_addr_provider（顶层），示例：ipv6_public_addr_provider = false；合并语义：覆盖（第 4.4 节）。

--ipv6-public-addr-auto

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_IPV6_PUBLIC_ADDR_AUTO。
• 功能：自动从共享了 IPv6 子网的对等节点获取一个公网 IPv6 地址（帮助文本）。
• 示例：easytier-core --ipv6-public-addr-auto
• 出处：easytier/src/core.rs:142-306。
• 配置文件：对应字段 ipv6_public_addr_auto（顶层），示例：ipv6_public_addr_auto = false；合并语义：覆盖（第 4.4 节）。

--ipv6-public-addr-prefix <CIDR>

• 类型/默认值：String（解析为 Ipv6Cidr）；无默认。环境变量：ET_IPV6_PUBLIC_ADDR_PREFIX。
• 功能：手动指定要共享的公网 IPv6 子网，不自动从系统路由检测（帮助文本）。
• 示例：--ipv6-public-addr-prefix 2001:db8:100::/64
• 注意：依赖 --ipv6-public-addr-provider。
• 出处：easytier/src/core.rs:142-306。
• 配置文件：对应字段 ipv6_public_addr_prefix（顶层），示例：ipv6_public_addr_prefix = "2001:db8:100::/64"；合并语义：覆盖（第 4.4 节）。

-d, --dhcp

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_DHCP。短选项：-d。
• 功能：由 EasyTier 自动确定并设置虚拟 IP 地址。帮助文本："默认从 10.0.0.1 开始。警告：在使用 DHCP 时，如果网络中出现 IP 冲突，IP 将自动更改。"
• 示例：easytier-core -d --network-name abc --network-secret abc -p tcp://<共享节点>:11010
• 注意：官方快速组网页补充：DHCP 默认分配 10.126.126.0/24 网段，可用 -i 10.11.11.0/24 指定其他网段。与 -i 互斥语义（都给时 -i 覆盖 dhcp 结果）。IP 冲突时 IP 会自动变化，依赖固定 IP 的服务（如端口转发目标）需留意。
• 出处：easytier/src/core.rs:142-306。
• 配置文件：对应字段 dhcp（顶层），示例：dhcp = true；合并语义：覆盖（第 4.4 节）。

-p, --peers <URI>...

• 类型/默认值：Vec<String>，多值；无默认。环境变量：ET_PEERS。短选项：-p。
• 功能：最初要连接的对等节点（帮助文本）。
• 示例：-p tcp://public.kkrainbow.top:11010 -p udp://1.2.3.4:11010 或 -p tcp://a:11010,udp://b:11010
• 注意：
  • 支持的 URL scheme（TunnelScheme，easytier/src/tunnel/mod.rs:158-171）：tcp、udp、wg、quic、ws、wss、faketcp、ring、txt、srv、unix（unix 平台）、http、https。
  • 追加语义：合并进配置文件时是 push 追加，不覆盖文件中的 [[peer]]（第 4.4 节）。
  • 官方建议：多共享节点时所有节点指定相同的共享节点列表。
• 出处：easytier/src/core.rs:142-306。

-e, --external-node <URI>

• 类型/默认值：String；无默认。环境变量：ET_EXTERNAL_NODE。短选项：-e。
• 功能：使用公共共享节点来发现对等节点（帮助文本）。
• 示例：-e tcp://public.easytier.top:11010
• 注意：实现上等价于再追加一个 peer（core.rs:1086-1095），语义上用于公共服务器发现。
• 出处：easytier/src/core.rs:142-306。
• 配置文件：对应字段 peer（顶层表数组，见 3.5 节），实现上等价于向现有 [[peer]] 追加一条（core.rs:1086-1095），示例：[[peer]] 下 uri = "tcp://public.easytier.top:11010"；合并语义：追加（第 4.4 节）。

-n, --proxy-networks <CIDR>...

• 类型/默认值：Vec<String>，多值；无默认。环境变量：ET_PROXY_NETWORKS。短选项：-n。
• 功能：子网代理（点对网）：将本地网络导出到 VPN 中的其他对等节点。帮助文本："例如：10.0.0.0/24。还支持将代理网络映射到其他 CIDR，例如：10.0.0.0/24->192.168.0.0/24，其他对等节点可以通过 IP 192.168.0.1 来访问 10.0.0.1"。
• 示例：-n 192.168.1.0/24；-n 10.1.1.0/24 -n 10.2.0.0/16 -n 10.3.3.3/32（掩码 32 可代理单 IP）；映射：-n '192.168.1.0/24->10.1.1.0/24'。
• 注意：
  • 解析在 easytier-core/src/config/api_input.rs:21-49：<cidr> 或 <cidr>-><mapped_cidr>，多于一个 -> 报错。
  • 映射后网段大小必须与原网段相同，否则启动失败（官方文档）。
  • 追加语义（第 4.4 节）；协议级过滤（allow = ["tcp","udp","icmp"]）只能通过 TOML [[proxy_network]] 设置。
• 出处：easytier/src/core.rs:142-306。

-l, --listeners <URL>...

• 类型/默认值：Vec<String>，多值；无默认——但"纯 CLI 启动且未给出"时会自动展开为默认 11010 全协议监听（第 4.4 节）。环境变量：ET_LISTENERS。短选项：-l。
• 功能：监听器用于接受连接（帮助文本），允许三种格式：
  1. 端口号：11010；
  2. URL：tcp://0.0.0.0:11010，协议可为 tcp、udp、ring、wg、ws、wss、quic、faketcp；
  3. 协议端口对：wg:11011。
• 示例：-l 11010；-l tcp://0.0.0.0:11010,udp://0.0.0.0:11010；-l wg:11011；仅 IPv6：-l 'tcp://[::]:12345' -l 'udp://[::]:12345'。
• 注意：
  • 智能展开（core.rs:823-887）：纯端口 → 全部 IP 协议按偏移展开（见 2.12 节）；裸 IP → 每协议 IP:11010+偏移；SocketAddr → 每协议 addr:port+偏移；proto:port → 单协议；完整 URL 原样。
  • 与 --no-listener 互斥；监听 0.0.0.0 会自动同时接受 IPv6（官方 P2P 优化页）。
  • 多实例时监听端口不能冲突（官方 FAQ：Address already in use）。
• 出处：easytier/src/core.rs:142-306, 823-887, 1061-1076。
• 配置文件：对应字段 listeners（顶层），示例：listeners = ["tcp://0.0.0.0:11010", "udp://0.0.0.0:11010", "wg://0.0.0.0:11011"]；合并语义：覆盖（-l 或 --no-listener 给出时整体重设；未给出且文件未写 listeners 时补默认 11010 全协议展开，第 4.4 节）。

--mapped-listeners <URL>...

• 类型/默认值：Vec<String>，多值；无默认。环境变量：ET_MAPPED_LISTENERS。
• 功能：手动指定监听器的公网地址，其他节点可以使用该地址连接到本节点（帮助文本），用于 NAT 后宣告公网映射。
• 示例：--mapped-listeners tcp://123.123.123.123:11223 -l tcp://0.0.0.0:11010
• 注意：scheme 限 tcp/udp/wg/quic/ws/wss/faketcp（MappedListenerPolicy，easytier-core/src/config/mod.rs:79-85），允许省略端口；与 --no-listener 同用时覆盖文件值。
• 出处：easytier/src/core.rs:142-306。
• 配置文件：对应字段 mapped_listeners（顶层），示例：mapped_listeners = ["tcp://123.123.123.123:11223"]；合并语义：覆盖（第 4.4 节）。

--no-listener

• 类型/默认值：bool，默认 false。环境变量：ET_NO_LISTENER。
• 功能：不监听任何端口，只连接到对等节点（帮助文本）。客户端/叶节点用。
• 示例：easytier-core -d -p tcp://203.0.113.7:11010 --no-listener
• 注意：覆盖 -l/--listeners（core.rs:1061-1068：no_listener || !listeners.is_empty() 时重设监听列表）；官方去中心组网页提示：会影响非打洞连接的建立。
• 出处：easytier/src/core.rs:142-306。
• 配置文件：对应字段 listeners（顶层）的"置空"表达，示例：listeners = []；合并语义：覆盖（CLI 给出时把监听列表整体重设为空，core.rs:1061-1068；第 4.4 节）。

--hostname <NAME>

• 类型/默认值：String；缺省取系统主机名。环境变量：ET_HOSTNAME。
• 功能：用于标识此设备的主机名（虚拟网内显示名，帮助文本）。
• 示例：--hostname office-pc
• 注意：读取系统名时会剥离控制字符并截断到 32 字符（easytier-core/src/config/toml.rs:768-789）；CLI 值覆盖文件值；开启魔法 DNS 后该名用于 <hostname>.et.net 域名。
• 出处：easytier/src/core.rs:142-306。

-m, --instance-name <NAME>

• 类型/默认值：String；缺省 "default"（easytier-core/src/config/toml.rs:24-26）。环境变量：ET_INSTANCE_NAME。短选项：-m。
• 功能：实例名称，用于在同一台机器上标识此 VPN 节点（帮助文本）；easytier-cli 可用 -n/--instance-name 选择实例。
• 示例：easytier-core -m home-instance -c /etc/easytier/home.toml
• 注意：注意与 --hostname（虚拟网内显示名）区分；多实例部署时建议每实例显式命名。
• 出处：easytier/src/core.rs:142-306。

2.4 VPN 门户（WireGuard 接入）选项

--vpn-portal <URL>

• 类型/默认值：String；无默认。环境变量：ET_VPN_PORTAL。
• 功能：开启 WireGuard VPN 门户服务端，允许标准 WireGuard 客户端接入虚拟网。帮助文本示例格式："WireGuard VPN 门户监听 URL，例如 wg://0.0.0.0:51820"。
• 示例：--vpn-portal wg://0.0.0.0:51820
• 注意：
  • 必须是 wg://IP:PORT 形式：scheme 必须为 wg、host 必须是 IP、不允许 path/用户名/query（core.rs:890-919）。
  • ⚠️ 与官方文档不一致：旧版的 CIDR 路径格式（官方文档仍写着 wg://0.0.0.0:11010/10.14.14.0/24）已删除，启动报错 "legacy VPN portal CIDR paths are no longer supported"；客户端改用 --vpn-portal-client NAME=CIDR 声明（差异见 8.5 节）。
• 出处：easytier/src/core.rs:277-305, 890-919。
• 配置文件：对应字段 vpn_portal_config（顶层嵌套表，见 3.7 节），示例：[vpn_portal_config] 下 wireguard_listen = "0.0.0.0:51820"；合并语义：覆盖（任一 --vpn-portal* 参数给出即重建该表，未给的子字段保留文件值，第 4.4 节）。

--vpn-portal-private-key <KEY>

• 类型/默认值：String（base64）；无默认（缺省由实现自动生成）。环境变量：ET_VPN_PORTAL_PRIVATE_KEY。
• 功能：WireGuard 门户服务端私钥。
• 示例：--vpn-portal wg://0.0.0.0:51820 --vpn-portal-private-key "$(wg genkey)"
• 注意：依赖 --vpn-portal（或配置文件已有 [vpn_portal_config]）；帮助文本建议通过环境变量传入，避免命令行暴露。
• 出处：easytier/src/core.rs:277-305。

--vpn-portal-client <NAME=CIDR>...

• 类型/默认值：Vec<String>，多值；无默认。环境变量：ET_VPN_PORTAL_CLIENT。
• 功能：定义允许接入 WireGuard 门户的具名客户端及其虚拟网段，如 alice=10.144.0.5/16；可重复指定。
• 示例：--vpn-portal-client alice=10.144.0.5/16 --vpn-portal-client bob=10.144.0.6/16
• 注意：给出时整体替换配置文件中的 clients 列表（core.rs:1126-1130）；多客户端请使用更大网段（官方建议如 /16）。
• 出处：easytier/src/core.rs:277-305, 1106-1137。

--vpn-portal-client-group <NAME=GROUP>...

• 类型/默认值：Vec<String>，多值；无默认。环境变量：ET_VPN_PORTAL_CLIENT_GROUP。
• 功能：为 --vpn-portal-client 定义的客户端附加 ACL 分组成员关系，如 alice=staff。
• 示例：--vpn-portal-client alice=10.144.0.5/16 --vpn-portal-client-group alice=staff
• 注意：强依赖——必须有至少一个 --vpn-portal-client 且 NAME 必须已存在，否则启动报错（core.rs:1106-1110, 954-959）。
• 出处：easytier/src/core.rs:277-305。
• 配置文件：对应字段 vpn_portal_config.clients[].groups（嵌套表，见 3.7 节），示例：groups = ["staff"]；合并语义：覆盖（随 --vpn-portal-client 的 clients 整体替换生效；强依赖至少一个 --vpn-portal-client，第 4.4 节）。

2.5 加密 / 安全模式 / 凭据选项

-u, --disable-encryption

• 类型/默认值：可选值 bool，默认 false（即默认加密）。环境变量：ET_DISABLE_ENCRYPTION。短选项：-u。
• 功能：禁用对等节点通信的加密。帮助文本："默认为 false，必须与对等节点相同。"
• 示例：easytier-core ... -u
• 注意：实现上写入 flags.enable_encryption = !v（core.rs）；全网节点必须一致，否则无法互通。
• 出处：easytier/src/core.rs:314-330。
• 配置文件：对应字段 enable_encryption（[flags]；语义取反：CLI 写入 enable_encryption = !v，core.rs:1220），示例：enable_encryption = true；合并语义：逐字段覆盖（第 4.4 节）。

--encryption-algorithm <ALGO>

• 类型/默认值：枚举 String；缺省 aes-gcm（[flags] encryption_algorithm 默认值，toml.rs:28-76）。环境变量：ET_ENCRYPTION_ALGORITHM。
• 功能：选择对等通信的加密算法。
• 示例：--encryption-algorithm chacha20
• 注意：
  • ⚠️ 与官方文档不一致（帮助文本与解析器不一致）（差异见 8.5 节）：帮助称支持 ''、xor、chacha20、aes-gcm、aes-gcm-256、openssl-aes128-gcm、openssl-aes256-gcm、openssl-chacha20；但解析器（easytier-core/src/config/encryption.rs:32-44）实际接受：xor、aes-gcm（别名 openssl-aes-gcm）、aes-256-gcm（别名 openssl-aes-256-gcm）、chacha20（别名 chacha20-poly1305、openssl-chacha20）；空串、aes-gcm-256、openssl-aes128-gcm、openssl-aes256-gcm 会解析失败。
  • 依赖加密未禁用（-u 未开启）时才有意义；运行期遇到不可用算法会回退 aes-gcm（easytier-core/src/instance/config.rs:145-152）。
• 出处：easytier/src/core.rs:314-330；easytier-core/src/config/encryption.rs:7-44。

--secure-mode

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_SECURE_MODE。
• 功能：启用安全模式（Noise 安全握手与认证路径）。官方安全模式页：在原有 network_name/network_secret 基础上加 --secure-mode 即可提升安全性。
• 示例：easytier-core -d --network-name office --network-secret 'xxx' --secure-mode -p tcp://node-a.example.com:11010
• 注意：可与 --local-private-key/--local-public-key 组合固定本机身份（core.rs:1204-1213）；共享节点建议固定私钥（否则每次启动随机生成，客户端无法锁定其身份）；仅开 --secure-mode 不等于确认了共享节点身份（官方安全模式页）。--credential 会隐式启用 secure mode。
• 出处：easytier/src/core.rs:314-330, 1196-1213；easytier-core/src/config/mod.rs:102-135。
• 配置文件：对应字段 [secure_mode] 的 enabled（顶层嵌套表，见 3.9 节），示例：[secure_mode] 下 enabled = true；合并语义：覆盖（--secure-mode 给出才设置；--credential 亦会隐式启用，第 4.4 节）。

--local-private-key <KEY>

• 类型/默认值：String（base64 X25519 私钥）；无默认——未提供时随机生成、仅适合当前实例。环境变量：ET_LOCAL_PRIVATE_KEY。
• 功能：安全模式下的本地静态身份私钥。
• 示例：--secure-mode --local-private-key <base64>
• 注意：依赖 --secure-mode；提供时自动派生公钥；若同时给出 --local-public-key 且两者不匹配则报错（easytier-core/src/config/mod.rs:102-135）。共享节点建议显式固定（官方文档）。
• 出处：easytier/src/core.rs:314-330。
• 配置文件：对应字段 [secure_mode] 的 local_private_key（见 3.9 节），示例：local_private_key = "<base64 X25519>"；合并语义：覆盖（随 --secure-mode/--credential 一起写入，第 4.4 节）。

--local-public-key <KEY>

• 类型/默认值：String（base64 X25519 公钥）；无默认——由私钥派生或随机生成。环境变量：ET_LOCAL_PUBLIC_KEY。
• 功能：安全模式下的本地公钥；通常省略。
• 示例：--secure-mode --local-public-key <base64>
• 注意：依赖 --secure-mode；与私钥不匹配报错。
• 出处：easytier/src/core.rs:314-330。
• 配置文件：对应字段 [secure_mode] 的 local_public_key（见 3.9 节），示例：local_public_key = "<base64 X25519>"；合并语义：覆盖（随 --secure-mode 一起写入，第 4.4 节）。

--credential <KEY>

• 类型/默认值：String（base64 X25519 私钥，由管理节点 easytier-cli credential generate 签发）；无默认。环境变量：ET_CREDENTIAL。
• 功能：以临时凭据身份加入网络，无需 network_secret（帮助文本："凭据密钥……用于作为临时节点加入网络，无需 network_secret"）。
• 示例：easytier-core --network-name mynet --credential <secret-base64> -p tcp://node-a:11010
• 注意：
  • 隐式启用 secure mode，并将该私钥设为本机身份私钥（core.rs:1006-1008, 1196-1203）。
  • 与 --network-secret 互斥语义：凭据模式下不设置 secret。
  • 凭据的组/中继/代理网段权限由签发参数决定（第 5.4.16 节）；凭据功能要求整条链路支持安全模式（官方安全模式页）。
• 出处：easytier/src/core.rs:314-330, 1006-1008, 1196-1203。
• 配置文件：无独立对应字段——实现上写入 [secure_mode]（enabled = true，并把该私钥写入 local_private_key，core.rs:1196-1213），同时按凭据模式处理 network_identity（不设 network_secret）；合并语义：覆盖（隐式启用 secure mode，第 4.4 节）。

--credential-file <PATH>

• 类型/默认值：PathBuf；无默认。环境变量：ET_CREDENTIAL_FILE。
• 功能：凭据存储文件路径，用于管理节点重启后保留已签发的临时凭据。
• 示例：--secure-mode --credential-file /var/lib/easytier/credentials.json
• 注意：作为管理节点（签发方）使用。
• 出处：easytier/src/core.rs:314-330；TOML 对应字段 credential_file（toml.rs:560, 1132-1138）。

2.6 运行时行为开关

--default-protocol <PROTO>

• 类型/默认值：Option<String>；缺省 "tcp"（[flags] default_protocol 的默认值，toml.rs:28-76）。环境变量：ET_DEFAULT_PROTOCOL。
• 功能：连接到对等节点时使用的默认协议（帮助文本）——连接 URL 未显式指明 scheme 时生效。
• 示例：--default-protocol udp
• 注意：实现上写入 flags.default_protocol（core.rs:1216-1218）；官方参数表已收录本参数。
• 出处：easytier/src/core.rs:308-313, 1216-1218；easytier/locales/app.yml:114-116。

--multi-thread

• 类型/默认值：可选值 bool；实际默认 true（gen_default_flags 中 multi_thread: true，toml.rs:48）。环境变量：ET_MULTI_THREAD。
• 功能：使用多线程 tokio 运行时。
• 示例：easytier-core --multi-thread=false（单线程运行）
• 注意：⚠️ 与官方文档不一致：帮助文本写"默认为单线程"，与源码默认值 true 不一致，以源码为准（差异见 8.5 节）。
• 出处：easytier/src/core.rs:332-534；easytier-core/src/config/toml.rs:48。

--multi-thread-count <N>

• 类型/默认值：u32，默认 2。环境变量：ET_MULTI_THREAD_COUNT。
• 功能：使用的线程数；帮助文本："仅在多线程模式下有效。取值必须大于 2"。
• 示例：--multi-thread --multi-thread-count 4
• 注意：依赖 --multi-thread。
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 multi_thread_count（[flags]，u32），示例：multi_thread_count = 2；注意与 bool 型的 multi_thread 是两个独立字段（--multi-thread 对应后者）；合并语义：逐字段覆盖（第 4.4 节）。

--disable-ipv6

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_DISABLE_IPV6。
• 功能：不使用 IPv6（帮助文本）；实现写入 flags.enable_ipv6 = !v。
• 示例：--disable-ipv6
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 enable_ipv6（[flags]；语义取反：CLI 写入 enable_ipv6 = !v，core.rs:1226），示例：enable_ipv6 = true；合并语义：逐字段覆盖（第 4.4 节）。

--dev-name <NAME>

• 类型/默认值：String；无默认。环境变量：ET_DEV_NAME。
• 功能：自定义 TUN 接口名称。
• 示例：--dev-name et_test
• 注意：依赖创建 TUN（无 --no-tun 且有虚拟 IP）。
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 dev_name（[flags]），示例：dev_name = "et_test"；合并语义：逐字段覆盖（第 4.4 节）。

--mtu <MTU>

• 类型/默认值：u16，默认 1380。环境变量：ET_MTU。
• 功能：TUN 设备的 MTU。
• 示例：--mtu 1400
• 注意：⚠️ 与官方文档不一致：帮助文本称"非加密时为 1380，加密时为 1360"，但源码默认固定 1380，全源码无 1360 的自动调整逻辑（差异见 8.5 节）。
• 出处：easytier/src/core.rs:332-534；easytier-core/src/config/toml.rs:35。

--latency-first

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_LATENCY_FIRST。
• 功能：延迟优先模式：尝试使用最低延迟路径转发流量；默认使用最短（跳数）路径（帮助文本）。
• 示例：--latency-first
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 latency_first（[flags]），示例：latency_first = false；合并语义：逐字段覆盖（第 4.4 节）。

--exit-nodes <IP>...

• 类型/默认值：Vec<IpAddr>，多值；无默认。环境变量：ET_EXIT_NODES。
• 功能：转发所有流量的出口节点（虚拟 IPv4），优先级由列表顺序决定（帮助文本）。
• 示例：--exit-nodes 10.144.144.1,10.144.144.2
• 注意：目标节点须开启 --enable-exit-node；非空时整体覆盖配置文件中的 exit_nodes（第 4.4 节）。
• 出处：easytier/src/core.rs:332-534。

--enable-exit-node

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_ENABLE_EXIT_NODE。
• 功能：允许此节点成为出口节点（其他节点可把本机设为 --exit-nodes）。
• 示例：--enable-exit-node
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 enable_exit_node（[flags]），示例：enable_exit_node = false；合并语义：逐字段覆盖（第 4.4 节）。

--proxy-forward-by-system

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_PROXY_FORWARD_BY_SYSTEM。
• 功能：通过系统内核转发子网代理数据包，禁用内置 NAT（帮助文本）。适合网关设备本身就有转发规则的场景。
• 示例：-n 192.168.1.0/24 --proxy-forward-by-system
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 proxy_forward_by_system（[flags]），示例：proxy_forward_by_system = false；合并语义：逐字段覆盖（第 4.4 节）。

--no-tun

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_NO_TUN。
• 功能：不创建 TUN 设备（免 Root/管理员权限），仍可被访问（TCP/UDP/ICMP）、可做子网代理（-n）；主动访问可用 SOCKS5 功能（官方无 TUN 模式页）。
• 示例：easytier-core --no-tun -n 192.168.1.0/24 --socks5 1080
• 注意：无 tun feature 的构建中强制视为 true（core.rs:1239）。
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 no_tun（[flags]），示例：no_tun = false；合并语义：逐字段覆盖（第 4.4 节；无 tun feature 的构建中源码强制 no_tun = true，core.rs:1239）。

--use-smoltcp

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_USE_SMOLTCP。
• 功能：为子网代理和 KCP 代理启用 smoltcp 用户态协议栈（帮助文本）。
• 示例：-n 192.168.1.0/24 --use-smoltcp
• 注意：无法关闭防火墙/无内核转发权限时使用；官方文档：目前仅影响 TCP，UDP/ICMP 始终用户态栈，性能劣于内核栈。
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 use_smoltcp（[flags]），示例：use_smoltcp = false；合并语义：逐字段覆盖（第 4.4 节）。

--manual-routes <CIDR>...

• 类型/默认值：Option<Vec<String>>，多值；无默认。环境变量：ET_MANUAL_ROUTES。
• 功能：手动分配路由 CIDR，将禁用子网代理和从对等节点传播的 WireGuard 路由。帮助文本示例：192.168.0.0/16。
• 示例：--manual-routes 192.168.0.0/16,10.0.0.0/8
• 注意：给出时整体替换 routes 字段（非追加）；列表为空则不处理任何非虚拟网流量（官方子网代理页）。
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 routes（顶层），示例：routes = ["192.168.0.0/16"]；合并语义：覆盖（给出时整体替换 routes，非追加，第 4.4 节）。

--relay-network-whitelist <NAME>...

• 类型/默认值：Option<Vec<String>>，多值；缺省 "*"（转发所有网络）。环境变量：ET_RELAY_NETWORK_WHITELIST。
• 功能：仅转发白名单网络的流量，支持通配符。帮助文本："如果本地网络不在白名单中，如果没有其他路由路径可用，流量仍然可以转发。如果该参数为空，则禁用转发。例如：*（所有网络），def*（以 def 为前缀的网络），net1 net2（只允许 net1 和 net2）"。
• 示例：--relay-network-whitelist net1,net2；只帮其他网建 P2P 不转发数据：--relay-network-whitelist --relay-all-peer-rpc（白名单置空，官方共享节点页）。
• 注意：多个名字最终 join 成空格分隔字符串写入 flags.relay_network_whitelist（core.rs:1241-1243）。
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 relay_network_whitelist（[flags]，String；CLI 多值 join 成空格分隔字符串，core.rs:1241-1243），示例：relay_network_whitelist = "*"；合并语义：逐字段覆盖（第 4.4 节）。

--p2p-only

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_P2P_ONLY。
• 功能：仅与已建立 P2P 连接的对等节点通信（拒绝中转链路，无直连则丢弃，帮助文本/官方 P2P 优化页）。
• 示例：--p2p-only
• 注意：与 --lazy-p2p 同开时，首次访问未直连节点可能等待失败。
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 p2p_only（[flags]），示例：p2p_only = false；合并语义：逐字段覆盖（第 4.4 节）。

--lazy-p2p

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_LAZY_P2P。
• 功能：仅在实际流量需要某个对等节点时才尝试建立 P2P；被标记为 need-p2p 的节点仍会主动建立连接（帮助文本）。
• 示例：--lazy-p2p
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 lazy_p2p（[flags]），示例：lazy_p2p = false；合并语义：逐字段覆盖（第 4.4 节）。

--disable-p2p

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_DISABLE_P2P。
• 功能：禁用普通自动 P2P；仍会与标记为 need-p2p 的节点建立连接，其他节点不应主动与当前节点建立 P2P（帮助文本）。
• 示例：--disable-p2p --need-p2p（按需白名单式 P2P，官方 P2P 优化页）。
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 disable_p2p（[flags]），示例：disable_p2p = false；合并语义：逐字段覆盖（第 4.4 节）。

--need-p2p

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_NEED_P2P。
• 功能：声明即使其他节点启用了 lazy-p2p，也应主动与当前节点建立 P2P 连接（帮助文本）。服务器/房主节点用。
• 示例：--need-p2p
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 need_p2p（[flags]），示例：need_p2p = false；合并语义：逐字段覆盖（第 4.4 节）。

--disable-udp-hole-punching

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_DISABLE_UDP_HOLE_PUNCHING。
• 功能：禁用 UDP 打洞功能。
• 示例：--disable-udp-hole-punching
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 disable_udp_hole_punching（[flags]），示例：disable_udp_hole_punching = false；合并语义：逐字段覆盖（第 4.4 节）。

--disable-tcp-hole-punching

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_DISABLE_TCP_HOLE_PUNCHING。
• 功能：禁用 TCP 打洞功能。
• 示例：--disable-tcp-hole-punching
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 disable_tcp_hole_punching（[flags]），示例：disable_tcp_hole_punching = false；合并语义：逐字段覆盖（第 4.4 节）。

--disable-sym-hole-punching

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_DISABLE_SYM_HOLE_PUNCHING。
• 功能：禁用基于生日攻击的对称 NAT（NAT4）UDP 打洞功能，该打洞方式可能会被运营商封锁（帮助文本）。
• 示例：--disable-sym-hole-punching
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 disable_sym_hole_punching（[flags]），示例：disable_sym_hole_punching = false；合并语义：逐字段覆盖（第 4.4 节）。

--disable-upnp

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_DISABLE_UPNP。
• 功能：禁用符合条件监听器的运行时 UPnP/NAT-PMP 端口映射；自动端口映射默认开启。
• 示例：--disable-upnp
• 注意：本参数为源码中存在但官方文档参数表未收录的项之一。
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 disable_upnp（[flags]），示例：disable_upnp = false；合并语义：逐字段覆盖（第 4.4 节）。

--enable-udp-broadcast-relay

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_ENABLE_UDP_BROADCAST_RELAY。
• 功能：仅 Windows：捕获物理网卡上的本机 UDP 广播包并转发给 EasyTier 对等节点，帮助局域网游戏发现房间；需要管理员权限。
• 示例：--enable-udp-broadcast-relay
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 enable_udp_broadcast_relay（[flags]），示例：enable_udp_broadcast_relay = false；合并语义：逐字段覆盖（第 4.4 节）。

--relay-all-peer-rpc

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_RELAY_ALL_PEER_RPC。
• 功能：转发所有对等节点的 RPC 数据包，即使对等节点不在转发网络白名单中；可帮助白名单外网络中的节点建立 P2P 连接（帮助文本）。
• 示例：--relay-network-whitelist --relay-all-peer-rpc（公共服务器推荐组合，官方共享节点页）
• 出处：easytier/src/core.rs:332-534。
• 配置文件：对应字段 relay_all_peer_rpc（[flags]），示例：relay_all_peer_rpc = false；合并语义：逐字段覆盖（第 4.4 节）。

2.7 代理与端口转发选项

--socks5 <PORT>

• 类型/默认值：u16；无默认。环境变量：ET_SOCKS5。feature：socks5。
• 功能：启用 SOCKS5 服务器，允许 SOCKS5 客户端访问虚拟网络；格式为端口，如 1080（帮助文本）。
• 示例：easytier-core --socks5 1080
• 注意：只填端口，监听 0.0.0.0:PORT（core.rs:1150-1157）；无需用户名密码验证（官方文档）；TOML 侧对应 socks5_proxy 完整 URL（第 3 章）。按域名/部分流量分流的出口用法见 7.13 节。
• 出处：easytier/src/core.rs:536-662。

--compression <ALGO>

• 类型/默认值：枚举 none|zstd，默认 none。环境变量：ET_COMPRESSION。
• 功能：数据压缩算法（帮助文本）。
• 示例：--compression zstd
• 注意：写入 flags.data_compress_algo；其他值直接 panic（core.rs:1256-1265）。
• 出处：easytier/src/core.rs:536-662。
• 配置文件：对应字段 data_compress_algo（[flags]；none→"None"、zstd→"Zstd"，core.rs:1256-1265），示例：data_compress_algo = "None"（也可写 1/2，见 3.10 节）；合并语义：逐字段覆盖（第 4.4 节）。

--bind-device <BOOL>

• 类型/默认值：Option<bool>，需要显式值（无 num_args=0..=1，必须写 --bind-device false 这种形式）；缺省 true（toml.rs gen_default_flags bind_device: true）。环境变量：ET_BIND_DEVICE。
• 功能：将连接器的套接字绑定到物理设备以避免路由问题。帮助文本："比如子网代理网段与某节点的网段冲突，绑定物理设备后可以与该节点正常通信。"
• 示例：--bind-device false
• 出处：easytier/src/core.rs:536-662。

--socket-mark <MARK>

• 类型/默认值：u32；无默认（缺省不设置 SO_MARK；0 是合法值）。环境变量：ET_SOCKET_MARK。平台：仅 Linux/Android/Fuchsia。
• 功能：在 EasyTier 底层套接字（TCP、UDP、QUIC、WebSocket、WireGuard 及 FakeTCP 诱饵套接字）上设置 SO_MARK（fwmark），需要 CAP_NET_ADMIN 权限；帮助文本同时提示：FakeTCP 的实际载荷通过原始 TUN 写入，内核不会为其打标记。
• 示例：--socket-mark 66
• 出处：easytier/src/core.rs:558-567。
• 配置文件：对应字段 socket_mark（[flags]，optional u32；不写 = 不动 SO_MARK），示例：socket_mark = 66；合并语义：逐字段覆盖（第 4.4 节；仅 Linux/Android/Fuchsia）。

--enable-kcp-proxy

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_ENABLE_KCP_PROXY。
• 功能：使用 KCP 代理 TCP 流，提高在 UDP 丢包网络上的延迟和吞吐量（帮助文本）。
• 示例：--enable-kcp-proxy
• 注意：对端不想接收 KCP 代理流量时在对端加 --disable-kcp-input；默认用内核网络栈，防火墙受限时组合 --use-smoltcp；对端不支持时自动回落 TCP（官方 KCP 代理页）。
• 出处：easytier/src/core.rs:536-662。
• 配置文件：对应字段 enable_kcp_proxy（[flags]），示例：enable_kcp_proxy = false；合并语义：逐字段覆盖（第 4.4 节）。

--disable-kcp-input

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_DISABLE_KCP_INPUT。
• 功能：不允许其他节点使用 KCP 代理 TCP 流到此节点；开启 KCP 代理的节点访问此节点时，依然使用原始 TCP 连接（帮助文本）。
• 示例：--disable-kcp-input
• 出处：easytier/src/core.rs:536-662。
• 配置文件：对应字段 disable_kcp_input（[flags]），示例：disable_kcp_input = false；合并语义：逐字段覆盖（第 4.4 节）。

--enable-quic-proxy

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_ENABLE_QUIC_PROXY。
• 功能：使用 QUIC 代理 TCP 流（v2.3.2 引入，官方 KCP 代理页）。
• 示例：--enable-quic-proxy
• 注意：官方文档：v2.6.0+ QUIC 优先于 KCP 生效（目的端关闭 QUIC 输入后 KCP 才生效）；BBR 在高丢包下带宽更高，KCP 延迟更低。
• 出处：easytier/src/core.rs:536-662。
• 配置文件：对应字段 enable_quic_proxy（[flags]），示例：enable_quic_proxy = false；合并语义：逐字段覆盖（第 4.4 节）。

--disable-quic-input

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_DISABLE_QUIC_INPUT。
• 功能：不允许其他节点使用 QUIC 代理 TCP 流到此节点（帮助文本）。
• 示例：--disable-quic-input
• 出处：easytier/src/core.rs:536-662。
• 配置文件：对应字段 disable_quic_input（[flags]），示例：disable_quic_input = false；合并语义：逐字段覆盖（第 4.4 节）。

--port-forward <URL>...

• 类型/默认值：Vec<url::Url>，多值（num_args=1..，逗号分隔）；无默认。环境变量：ET_PORT_FORWARD。
• 功能：将本地端口转发到虚拟网络中的远程端口。帮助文本："例如：udp://0.0.0.0:12345/10.126.126.1:23456，表示将本地 UDP 端口 12345 转发到虚拟网络中的 10.126.126.1:23456。可以指定多个。"
• 示例：--port-forward udp://0.0.0.0:12345/10.126.126.1:23456
• 注意：URL 格式 <proto>://<bind>/<dst>，proto 为 tcp/udp（core.rs:1159-1190）；追加语义（第 4.4 节）。
• 出处：easytier/src/core.rs:536-662；easytier-core/src/config/gateway.rs:15-20。
• 配置文件：对应字段 port_forward（顶层表数组，见 3.8 节），示例：[[port_forward]] 下 bind_addr = "0.0.0.0:11011"、dst_addr = "10.126.126.1:11011"、proto = "tcp"；合并语义：追加（第 4.4 节）。

--accept-dns <BOOL>

• 类型/默认值：Option<bool>，需要显式值；缺省 false。环境变量：ET_ACCEPT_DNS。
• 功能：启用魔法 DNS：可用 <hostname>.et.net 域名访问其他节点。帮助文本："魔法 DNS 将修改您的系统 DNS 设置，请谨慎启用。"
• 示例：--accept-dns true
• 注意：DNS 服务器地址 100.100.100.101；仅 Windows/macOS 自动配置系统 DNS，Linux 需手动（官方魔法 DNS 页）；主机名支持中文；依赖参数 --tld-dns-zone 可自定义顶级域。
• 出处：easytier/src/core.rs:536-662。
• 配置文件：对应字段 accept_dns（[flags]），示例：accept_dns = false；合并语义：逐字段覆盖（第 4.4 节）。

--tld-dns-zone <ZONE>

• 类型/默认值：String，默认 et.net.（常量 DEFAULT_ET_DNS_ZONE，toml.rs:20）。环境变量：ET_TLD_DNS_ZONE。
• 功能：指定魔法 DNS 的顶级域名区域；仅在 accept_dns 为 true 时使用（帮助文本）。
• 示例：--accept-dns true --tld-dns-zone vpn.example.
• 出处：easytier/src/core.rs:536-662。

--private-mode <BOOL>

• 类型/默认值：Option<bool>，需要显式值；缺省 false。环境变量：ET_PRIVATE_MODE。
• 功能：如果为 true，则仅允许两类 foreign network 接入：本节点能验证其使用相同 network secret 的节点，或已通过 foreign network 管理节点传播而被信任的 credential 节点；否则 secret 不同或缺失时会被拒绝（帮助文本）。
• 示例：--private-mode true --network-name my-network --network-secret my-secret（私有共享节点，官方共享节点页）
• 出处：easytier/src/core.rs:536-662。
• 配置文件：对应字段 private_mode（[flags]），示例：private_mode = false；合并语义：逐字段覆盖（第 4.4 节）。

--foreign-relay-bps-limit <BPS>

• 类型/默认值：u64，默认 u64::MAX（无限制）。环境变量：ET_FOREIGN_RELAY_BPS_LIMIT。
• 功能：作为共享节点时，限制非本地网络（外来网络）流量的转发速率，单位 BPS（字节每秒）。
• 示例：--foreign-relay-bps-limit 1048576
• 出处：easytier/src/core.rs:536-662。
• 配置文件：对应字段 foreign_relay_bps_limit（[flags]，u64），示例：foreign_relay_bps_limit = 1048576；合并语义：逐字段覆盖（第 4.4 节；默认值 u64::MAX 的 dump 写法见 3.10 节）。

--instance-recv-bps-limit <BPS>

• 类型/默认值：u64，默认 u64::MAX（无限制）。环境变量：ET_INSTANCE_RECV_BPS_LIMIT。
• 功能：限制当前网络实例整体入站流量的总接收速率，单位 BPS。
• 示例：--instance-recv-bps-limit 10485760
• 出处：easytier/src/core.rs:536-662。
• 配置文件：对应字段 instance_recv_bps_limit（[flags]，u64），示例：instance_recv_bps_limit = 10485760；合并语义：逐字段覆盖（第 4.4 节）。

--tcp-whitelist <PORT>...

• 类型/默认值：Vec<String>，多值；无默认。环境变量：无。
• 功能：TCP 端口白名单，支持单个端口（80）和范围（8000-9000）（帮助文本）；ACL 之外的轻量端口过滤。
• 示例：--tcp-whitelist 80,8000-9000
• 注意：追加语义；与 acl set 互不影响（第 5.4.11 节）；官方 ACL 页：easytier-core -d --tcp-whitelist 端口号 可自动生成简单端口白名单 ACL 规则。
• 出处：easytier/src/core.rs:648-662。
• 配置文件：对应字段 tcp_whitelist（顶层），示例：tcp_whitelist = ["80", "8000-9000"]；合并语义：追加（第 4.4 节）。

--udp-whitelist <PORT>...

• 类型/默认值：Vec<String>，多值；无默认。环境变量：无。
• 功能：UDP 端口白名单，支持单个端口（53）和范围（5000-6000）（帮助文本）。
• 示例：--udp-whitelist 53
• 注意：同 --tcp-whitelist（追加语义、无 env）。
• 出处：easytier/src/core.rs:648-662。
• 配置文件：对应字段 udp_whitelist（顶层），示例：udp_whitelist = ["53"]；合并语义：追加（第 4.4 节）。

2.8 中继协议开关

--disable-relay-kcp

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_DISABLE_RELAY_KCP。
• 功能：如果为 true，则禁止节点转发 KCP 数据包，防止过度消耗流量（帮助文本）。
• 示例：--disable-relay-kcp
• 出处：easytier/src/core.rs:664-734。
• 配置文件：对应字段 disable_relay_kcp（[flags]），示例：disable_relay_kcp = false；合并语义：逐字段覆盖（第 4.4 节）。

--disable-relay-quic

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_DISABLE_RELAY_QUIC。
• 功能：如果为 true，则禁止节点转发 QUIC 数据包，防止过度消耗流量（帮助文本）。
• 示例：--disable-relay-quic
• 出处：easytier/src/core.rs:664-734。
• 配置文件：对应字段 disable_relay_quic（[flags]），示例：disable_relay_quic = false；合并语义：逐字段覆盖（第 4.4 节）。

--enable-relay-foreign-network-kcp

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_ENABLE_RELAY_FOREIGN_NETWORK_KCP。
• 功能：如果为 true，则作为共享节点时也可以转发其他网络的 KCP 数据包；默认不转发（帮助文本）。
• 示例：--enable-relay-foreign-network-kcp
• 出处：easytier/src/core.rs:664-734。
• 配置文件：对应字段 enable_relay_foreign_network_kcp（[flags]），示例：enable_relay_foreign_network_kcp = false；合并语义：逐字段覆盖（第 4.4 节）。

--enable-relay-foreign-network-quic

• 类型/默认值：可选值 bool，默认 false。环境变量：ET_ENABLE_RELAY_FOREIGN_NETWORK_QUIC。
• 功能：如果为 true，则作为共享节点时也可以转发其他网络的 QUIC 数据包；默认不转发（帮助文本）。
• 示例：--enable-relay-foreign-network-quic
• 出处：easytier/src/core.rs:664-734。
• 配置文件：对应字段 enable_relay_foreign_network_quic（[flags]），示例：enable_relay_foreign_network_quic = false；合并语义：逐字段覆盖（第 4.4 节）。

2.9 STUN / NAT 探测选项

--stun-servers <ADDR>...

• 类型/默认值：Option<Vec<String>>，多值；无默认（使用内置列表）。环境变量：ET_STUN_SERVERS。
• 功能：覆盖内置的默认 UDP STUN 服务器列表；未设置 --tcp-stun-servers 时，TCP STUN 也使用此列表（帮助文本）。
• 示例：--stun-servers stun.example.com:3478；禁用：--stun-servers ""。
• 注意（三态行为，core.rs:1318-1326, 1444-1457）：
  • 不指定 = 用内置列表（easytier-core/src/config/mod.rs:21-26：txt:stun.easytier.cn、stun.miwifi.com、stun.chat.bilibili.com、stun.hitv.com）；
  • 指定列表 = 追加到现有值；
  • 指定空串 = 清空（禁用） UDP STUN 以及回退的 TCP/IPv6 STUN。
  • 条目支持 host:port 与 txt:（DNS SRV）形式。
• 出处：easytier/src/core.rs:700-725。
• 配置文件：对应字段 stun_servers（顶层），示例：stun_servers = ["txt:stun.easytier.cn", "stun.miwifi.com"]；合并语义：三态（不指定 = 不动文件/用内置；指定列表 = 追加到文件已有值；指定空串 = 清空禁用，第 4.4 节）。

--stun-servers-v6 <ADDR>...

• 类型/默认值：Option<Vec<String>>，多值；无默认（内置 txt:stun-v6.easytier.cn，config/mod.rs:36）。环境变量：ET_STUN_SERVERS_V6。
• 功能：覆盖内置的默认 IPv6 STUN 服务器列表；如果未设置但已设置 stun-servers，则禁用 IPv6 STUN；如果设置了但是为空，则不使用 IPv6 STUN 服务器（帮助文本）。
• 示例：--stun-servers-v6 ""
• 出处：easytier/src/core.rs:700-725。
• 配置文件：对应字段 stun_servers_v6（顶层），示例：stun_servers_v6 = ["txt:stun-v6.easytier.cn"]；合并语义：三态（同 --stun-servers，第 4.4 节）。

--tcp-stun-servers <ADDR>...

• 类型/默认值：Option<Vec<String>>，多值；无默认（内置列表见 config/mod.rs:27-35，含 stun.hot-chilli.net 等）。环境变量：ET_TCP_STUN_SERVERS。
• 功能：覆盖内置的默认 TCP STUN 服务器列表；如果未设置，TCP STUN 会优先使用 stun-servers，否则使用默认列表；如果设置了但是为空，则禁用 TCP STUN（帮助文本）。
• 示例：--tcp-stun-servers turn.example.com:3478
• 出处：easytier/src/core.rs:700-725。

2.10 日志选项（LoggingOptions，进程级）

重要：日志配置属于进程级配置——日志系统在进程启动时、加载任何配置文件之前初始化，因此不支持写在 -c 配置文件中，只能通过命令行参数或环境变量设置（官方文档与源码一致：TOML 中旧版 [file_logger]/[console_logger] 段已不被支持、会被忽略，toml.rs:516-564 无对应字段）。同一进程加载多个配置文件运行多个实例时，日志配置对所有实例共用。

--console-log-level <LEVEL>

• 类型/默认值：String，默认 info。环境变量：ET_CONSOLE_LOG_LEVEL。
• 功能：控制台日志级别。可选值：trace、debug、info、warn、error、off（官方文档）。
• 示例：easytier-core --console-log-level debug
• 注意：RUST_LOG 环境变量优先级更高，可按 target 精细控制（官方文档示例：RUST_LOG=warn,easytier_core=debug,hyper=off easytier-core）。
• 出处：easytier/src/core.rs:765-801。
• 配置文件：无对应配置文件字段（进程级参数，仅命令行/环境变量——日志系统在加载任何配置文件前初始化，官方文档明确日志配置不支持写入 -c 配置文件；TOML 中旧 [file_logger]/[console_logger] 段已不被解析，见 2.10 节）。

--file-log-level <LEVEL>

• 类型/默认值：String，默认 off（文件日志关闭）。环境变量：ET_FILE_LOG_LEVEL。
• 功能：文件日志级别；设为除 off 外的值即开启文件日志（官方文档）。
• 示例：--file-log-level info
• 注意：默认写进程工作目录下 easytier.log，按天滚动轮转，超限自动清理（官方文档）。
• 出处：easytier/src/core.rs:765-801。
• 配置文件：无对应配置文件字段（进程级参数，仅命令行/环境变量；依据同 2.10 节说明：日志配置不支持写入 -c 配置文件）。

--file-log-dir <DIR>

• 类型/默认值：String，默认当前目录。环境变量：ET_FILE_LOG_DIR。
• 功能：存储日志文件的目录。
• 示例：--file-log-level info --file-log-dir /var/log/easytier
• 出处：easytier/src/core.rs:765-801。
• 配置文件：无对应配置文件字段（进程级参数，仅命令行/环境变量；依据同 2.10 节说明：日志配置不支持写入 -c 配置文件）。

--file-log-size <MB>

• 类型/默认值：u64，默认 100。环境变量：ET_FILE_LOG_SIZE。
• 功能：单个文件日志大小上限，单位 MB。
• 示例：--file-log-size 50
• 出处：easytier/src/core.rs:765-801。
• 配置文件：无对应配置文件字段（进程级参数，仅命令行/环境变量；依据同 2.10 节说明：日志配置不支持写入 -c 配置文件）。

--file-log-count <N>

• 类型/默认值：usize，默认 10。环境变量：ET_FILE_LOG_COUNT。
• 功能：保留日志文件的最大数量。
• 示例：--file-log-count 5
• 注意：运行期可经 RPC 调整文件日志级别：easytier-cli logger set debug（合法值 disabled/error/warning/info/debug/trace，第 5.4.15 节）。
• 出处：easytier/src/core.rs:765-801。
• 配置文件：无对应配置文件字段（进程级参数，仅命令行/环境变量；依据同 2.10 节说明：日志配置不支持写入 -c 配置文件）。

2.11 RPC 门户选项（RpcPortalOptions）

-r, --rpc-portal <ADDR>

• 类型/默认值：String；默认 0（首先尝试 15888）。环境变量：ET_RPC_PORTAL。短选项：-r。
• 功能：开启供管理的 RPC 门户监听（TCP），供 easytier-cli / Web 控制台连接。帮助文本："0 表示随机端口，12345 表示在 localhost 的 12345 上监听，0.0.0.0:12345 表示在所有接口的 12345 上监听。默认是 0，首先尝试 15888。"
• 示例：-r 15888；-r 0.0.0.0:15888；-r 127.0.0.1:15888。
• 注意（解析规则以源码为准，easytier/src/rpc_service/api.rs:119-154）：

  输入	实际绑定
  不传 / 0	0.0.0.0:0 → 在 15888~15899 范围从低到高找第一个空闲 TCP 端口
  纯端口 12345	0.0.0.0:12345（监听所有接口，不是 localhost！）
  完整 SocketAddr	原样绑定
  其他非法字符串	报错退出

  • ⚠️ 与官方文档不一致：帮助文案与官网写"12345 表示在 localhost 监听"，但源码把纯端口解析为 0.0.0.0（差异见 8.5 节）。
  • 15888~15899 全部被占用则启动失败（No free port found for RPC portal）；随机选中的端口不打印到日志，可用 ss -tlnp | grep easytier-core 确认。
  • 该通道无认证无 TLS，安全控制仅靠来源 IP 白名单（第 6 章）。
• 出处：easytier/src/core.rs:803-820；easytier/src/rpc_service/api.rs:119-154。
• 配置文件：无对应配置文件字段（进程级参数，仅命令行/环境变量：管理 RPC 监听由进程启动时直接建立，Config（toml.rs:516-564）无 rpc_portal 字段）。

--rpc-portal-whitelist <CIDR>...

• 类型/默认值：Option<Vec<IpCidr>>，多值（逗号分隔）；缺省 127.0.0.0/8 + ::1/128（仅回环）。环境变量：ET_RPC_PORTAL_WHITELIST。
• 功能：RPC 门户白名单，仅允许这些来源地址访问 RPC 门户（帮助文本示例：127.0.0.1/32,127.0.0.0/8,::1/128）。
• 示例：--rpc-portal-whitelist 127.0.0.1/32,192.168.1.0/24
• 注意：显式配置后完全替换默认白名单——只写 192.168.1.0/24 时回环不再默认放行，需自行加上；条目可写 127.0.0.1（等价 /32）或 CIDR。
• 出处：easytier/src/core.rs:803-820；白名单实现 easytier-core/src/management/rpc_server_hook.rs:9-52。

2.12 监听协议与端口偏移速查

-l/--listeners 的"纯端口/IP 展开"与默认端口依赖协议偏移表（easytier-core/src/connectivity/protocol/mod.rs:44-64）：

示例：-l 11010 等价于同时监听 tcp://0.0.0.0:11010、udp://0.0.0.0:11010、wg://0.0.0.0:11011、ws://0.0.0.0:11011、quic://0.0.0.0:11012、wss://0.0.0.0:11012、faketcp://0.0.0.0:11013（按编译 feature 裁剪）。

注：官方去中心组网页的"-l 12345"示例行写 WG:12348，与源码偏移表（wg +1）不一致，以源码为准；官方同页"默认监听端口表"（TCP/UDP 11010、WS 11011、WSS 11012、WG 11011、QUIC 11012、FakeTCP 11013）与源码一致。

2.13 参数间关系汇总（互斥 / 依赖 / 隐式联动）

• 互斥（语义冲突）：
  • -i/--ipv4 ↔ -d/--dhcp（同时给出时 -i 优先）；
  • --network-secret ↔ --credential（凭据模式删除 secret）；
  • -l/--listeners ↔ --no-listener；
  • --ipv6-public-addr-prefix 依赖 --ipv6-public-addr-provider。
• 依赖：
  • --check-config ⇒ 必须给 -c；
  • --machine-id 仅配合 -w；
  • --tld-dns-zone 仅配合 --accept-dns true；
  • --vpn-portal-client-group ⇒ 至少一个 --vpn-portal-client；
  • --local-private-key/--local-public-key 配合 --secure-mode；
  • --multi-thread-count 配合 --multi-thread。
• 隐式联动：
  • --credential ⇒ 隐式 --secure-mode 并占用 local_private_key；
  • -u/--disable-encryption 改写 flags.enable_encryption；
  • --disable-ipv6 改写 flags.enable_ipv6；
  • --manual-routes ⇒ 整体覆盖 routes；
  • --exit-nodes 非空 ⇒ 整体覆盖 exit_nodes。
• 覆盖关系（CLI 相对配置文件）：见第 4 章。

第 3 章　easytier-core 配置文件（TOML）字段详解

本章详解 -c/--config-file 加载的 TOML 配置文件的全部字段。配置模型定义在 easytier-core/src/config/toml.rs（Config struct，toml.rs:516-564），行为实现在 toml.rs:754-1188；[flags] 字段名即 protobuf FlagsInConfig 字段名（easytier-proto/proto/common.proto:7-91）。

3.1 配置文件的使用方法

官方《配置文件》页要点（https://easytier.cn/guide/network/config-file.html ）：

• 用 -c 指定：easytier-core -c ./config.toml；命令行中的配置选项会覆盖配置文件中的选项（规则详见第 4 章）。
• 由参数生成配置文件（官方推荐做法）：用参数运行 easytier-core，对应参数的配置文件会打印在命令行中，可手动复制保存为 .toml；不带参数直接运行可获得最小配置文件。
• 多配置文件：easytier-core -c ./config1.toml -c ./config2.toml，一个进程加载多份配置、启动多个虚拟网络。
• 官方还提供网页"配置助手"（https://easytier.cn/assistant/ ）按需生成配置文件。

3.2 加载规则（源码行为，排错必读）

加载入口 load_config_from_file（easytier/src/common/config.rs:62-112）→ TomlConfigLoader::new_from_str_with_source（toml.rs:686-701）：

1. 特殊路径：-c - 从 stdin 读取，并视为静态配置（不可通过 RPC 修改）。
2. 环境变量展开（可用 --disable-env-parsing 关闭）：由 shellexpand::env 实现（common/env_parser.rs:21-40）——支持 ${VAR}、$VAR、${VAR:-default}；$$ 转义为字面 $；未定义且无默认值的变量保持原样不报错；一旦发生展开，该配置文件自动被标记为只读（READ_ONLY）+ 不可删（NO_DELETE），防止密钥类内容被远程 RPC 改写（common/config.rs:97-99）。
3. 顶层未知字段被静默忽略：Config 结构没有 deny_unknown_fields，拼错的顶层 key 不会报错（排错时注意！）。仅 [vpn_portal_config]、[[vpn_portal_config.clients]]、[[managed_credentials]] 三个子结构启用 deny_unknown_fields（toml.rs:449, 473, 486）。
4. 旧字段不再支持：[file_logger]/[console_logger] 段（旧版示例中存在）不属于 Config 结构、会被忽略——日志只能用 CLI 参数/env（第 2.10 节）；[vpn_portal_config] client_cidr（旧版字段）触发显式报错（toml.rs:1249-1261）。
5. [flags] 浅合并：flags 与内置默认值 map（gen_default_flags()，toml.rs:28-76）逐 key 浅合并——文件里写了的 key 覆盖默认，没写用默认。因此 [flags] 中只写想改的字段即可。
6. 实例身份：instance_id 未写时自动生成 UUIDv4（toml.rs:937-951）；network_identity 未写时视为 network_name="default", network_secret=""；[secure_mode] enabled=true 且无 network_secret 时进入凭据模式（不合成 secret，toml.rs:703-737）。

最小可用配置（两组网必需字段）：

[network_identity]
network_name = "mynet"
network_secret = "s3cret"

3.3 顶层字段逐条详解（Config，toml.rs:516-564）

netns

• 类型/默认值：String；无默认。功能：Linux network namespace——实例的底层 socket/TUN 进入该 ns。对应 CLI：仅 TOML（无 CLI 参数）。示例：netns = "vpn0"。出处：toml.rs:519, 795-801；消费点 instance/config.rs:185。

hostname

• 类型/默认值：String；缺省运行期取系统主机名（≤32 字符、剥离控制字符）。功能：虚拟网内显示的主机名。对应 CLI：--hostname。示例：hostname = "office-pc"。出处：toml.rs:520, 768-789。

instance_name

• 类型/默认值：String；默认 "default"。功能：同机多实例的实例标识（RPC API 选择实例用）。对应 CLI：-m/--instance-name。示例：instance_name = "home-node"。出处：toml.rs:521, 755-766。

instance_id

• 类型/默认值：String（UUID）；缺省自动生成 UUIDv4。功能：实例唯一 ID；配置目录托管文件的命名也用它（<uuid>.toml）。对应 CLI：仅 TOML。示例：instance_id = "87ede5a2-9c3d-492d-9bbe-989b9d07e742"。出处：toml.rs:522, 937-951。

ipv4

• 类型/默认值：String（Ipv4Inet）；无默认（无虚拟 IPv4 时不创建 TUN）。功能：本机虚拟 IPv4；省略掩码按 /32 解析后自动改 /24。对应 CLI：-i/--ipv4。示例：ipv4 = "10.144.144.10"。出处：toml.rs:523, 803-816。

ipv6

• 类型/默认值：String（Ipv6Inet）；无默认。功能：本机虚拟 IPv6（双栈）。对应 CLI：--ipv6。示例：ipv6 = "fdab::10/64"。出处：toml.rs:524, 822-829。

ipv6_public_addr_provider

• 类型/默认值：bool，默认 false。功能：共享本机公网 IPv6 子网给他人（仅 Linux）。对应 CLI：--ipv6-public-addr-provider。示例：ipv6_public_addr_provider = false。出处：toml.rs:525, 831-841。

ipv6_public_addr_auto

• 类型/默认值：bool，默认 false。功能：从共享节点自动获取公网 IPv6。对应 CLI：--ipv6-public-addr-auto。出处：toml.rs:526, 843-853。

ipv6_public_addr_prefix

• 类型/默认值：String（Ipv6Cidr）；无默认。功能：手动指定共享的公网 IPv6 子网。对应 CLI：--ipv6-public-addr-prefix。示例：ipv6_public_addr_prefix = "2001:db8:100::/64"。出处：toml.rs:527, 855-866。

dhcp

• 类型/默认值：bool，默认 false。功能：自动分配虚拟 IPv4（从 10.0.0.1 起）。对应 CLI：-d/--dhcp。示例：dhcp = true。出处：toml.rs:528, 868-874。

network_identity

• 类型/默认值：表（见 3.4）；缺省 network_name="default"、network_secret=""。功能：网络身份。对应 CLI：--network-name / --network-secret。出处：toml.rs:529, 953-964。

listeners

• 类型/默认值：字符串数组（URL）；⚠️ 字段整体缺省时（未与 CLI 合并的场景）= 不监听；与 CLI 合并且文件未写时 = 默认展开 11010 全协议（第 4.4 节）。功能：监听器列表，格式同 -l。对应 CLI：-l/--listeners、--no-listener。示例：listeners = ["tcp://0.0.0.0:11010", "udp://0.0.0.0:11010", "wg://0.0.0.0:11011"]。出处：toml.rs:530, 966-989；默认展开 core.rs:1069-1076。

mapped_listeners

• 类型/默认值：字符串数组；无默认。功能：监听器的公网映射地址。对应 CLI：--mapped-listeners。示例：mapped_listeners = ["tcp://123.123.123.123:11223"]。出处：toml.rs:531, 991-1002。

exit_nodes

• 类型/默认值：IP 数组；默认空。功能：全流量出口节点（按序优先）。对应 CLI：--exit-nodes（CLI 非空时整体覆盖）。示例：exit_nodes = ["10.144.144.1"]。出处：toml.rs:532, 1024-1035。

peer

• 类型/默认值：表数组（见 3.5）；默认空。功能：初始连接的对端列表。对应 CLI：-p/--peers、-e/--external-node（追加，不覆盖）。出处：toml.rs:534, 975-981。

proxy_network

• 类型/默认值：表数组（见 3.6）；默认空。功能：子网代理。对应 CLI：-n/--proxy-networks（追加）。出处：toml.rs:535, 876-935。

vpn_portal_config

• 类型/默认值：表（见 3.7）；无默认。功能：WireGuard 接入门户。对应 CLI：--vpn-portal*（CLI 给出任一参数即重建该表，未给的子字段保留文件值）。出处：toml.rs:537, 1004-1009。

routes

• 类型/默认值：CIDR 字符串数组；无默认。功能：手动路由（禁用子网代理/WG 路由自动传播）。对应 CLI：--manual-routes（给出时整体替换）。示例：routes = ["192.168.0.0/16"]。出处：toml.rs:539, 1037-1043。

socks5_proxy

• 类型/默认值：URL 字符串；无默认。功能：SOCKS5 服务，TOML 用完整 URL（比 CLI --socks5 只给端口更灵活）。对应 CLI：--socks5。示例：socks5_proxy = "socks5://0.0.0.0:1080"。出处：toml.rs:541, 1045-1051。按域名/部分流量分流的出口用法见 7.13 节。

port_forward

• 类型/默认值：表数组（见 3.8）；默认空。功能：端口转发。对应 CLI：--port-forward（追加）。出处：toml.rs:543, 1053-1064。

secure_mode

• 类型/默认值：表（见 3.9）；无默认。功能：Noise 安全模式。对应 CLI：--secure-mode、--local-private-key、--local-public-key。出处：toml.rs:545, 1124-1130。

flags

• 类型/默认值：表（见 3.10）；与内置默认浅合并。功能：运行时行为旗标。对应 CLI：大多数 NetworkOptions 参数逐字段对应。出处：toml.rs:547-550, 739-748, 1011-1022。

acl

• 类型/默认值：表（见 3.11）；无默认。功能：ACL 访问控制。对应 CLI：仅 TOML（运行期可用 easytier-cli acl set 整体替换）。出处：toml.rs:552, 1066-1072。

tcp_whitelist

• 类型/默认值：字符串数组；默认空。功能：TCP 端口白名单（单端口/范围）。对应 CLI：--tcp-whitelist（追加）。示例：tcp_whitelist = ["80", "8000-9000"]。出处：toml.rs:554, 1074-1085。

udp_whitelist

• 类型/默认值：字符串数组；默认空。功能：UDP 端口白名单。对应 CLI：--udp-whitelist（追加）。示例：udp_whitelist = ["53"]。出处：toml.rs:555, 1087-1098。

stun_servers

• 类型/默认值：字符串数组；无默认（用内置列表；空数组=禁用）。功能：覆盖 UDP STUN。对应 CLI：--stun-servers（三态：不指定/追加/空串清空）。示例：stun_servers = ["txt:stun.easytier.cn", "stun.miwifi.com"]。出处：toml.rs:556, 1100-1106。

tcp_stun_servers

• 类型/默认值：字符串数组；无默认。功能：覆盖 TCP STUN。对应 CLI：--tcp-stun-servers。示例：tcp_stun_servers = ["stun.hot-chilli.net"]。出处：toml.rs:557, 1108-1114。

stun_servers_v6

• 类型/默认值：字符串数组；无默认。功能：覆盖 IPv6 STUN。对应 CLI：--stun-servers-v6。示例：stun_servers_v6 = ["txt:stun-v6.easytier.cn"]。出处：toml.rs:558, 1116-1122。

credential_file

• 类型/默认值：路径字符串；无默认。功能：凭据持久化文件。对应 CLI：--credential-file。示例：credential_file = "/var/lib/easytier/credentials.bin"。出处：toml.rs:560, 1132-1138。

managed_credentials

• 类型/默认值：表数组（见 3.12）；默认空。功能：管理节点签发的凭据清单。对应 CLI：仅 TOML（运行期可用 easytier-cli credential upsert）。出处：toml.rs:561-562, 1140-1146。

source

• 类型/默认值：表 { source = "user" | "web" }；默认 user。功能：配置来源标记（内部/WEB 管理）；"user" 会被规范化删除，只落盘 "web"。对应 CLI：仅 TOML（一般手写不填）。出处：toml.rs:563, 337-364, 1148-1163。

3.4 [network_identity]（toml.rs:299-305）

[network_identity]
network_name = "office"
network_secret = "replace-with-a-strong-secret"

3.5 [[peer]]（PeerConfig，toml.rs:403-407）

[[peer]]
uri = "tcp://relay.example.com:11010"
peer_public_key = "<relay-public-key-base64>"   # 可选

3.6 [[proxy_network]]（ProxyNetworkConfig，toml.rs:409-414）

[[proxy_network]]
cidr = "192.168.1.0/24"
mapped_cidr = "10.1.0.0/24"      # 可选
allow = ["tcp", "udp", "icmp"]   # 可选

3.7 [vpn_portal_config] 与 [[vpn_portal_config.clients]]（toml.rs:448-479，deny_unknown_fields）

[[vpn_portal_config.clients]] 子字段（toml.rs:472-479，deny_unknown_fields）：

⚠️ 旧字段 client_cidr 已废弃，写入会显式报错（toml.rs:1249-1261）。

[vpn_portal_config]
wireguard_listen = "0.0.0.0:51820"
wireguard_private_key = "<base64>"
[[vpn_portal_config.clients]]
name = "alice"
virtual_ip = "10.144.144.10/24"
groups = ["staff"]

3.8 [[port_forward]]（PortForwardConfig，config/gateway.rs:15-20）

[[port_forward]]
bind_addr = "0.0.0.0:11011"
dst_addr = "10.126.126.1:11011"
proto = "tcp"

3.9 [secure_mode]（SecureModeConfig，proto/common.proto:275-283）

[secure_mode]
enabled = true
local_private_key = "<optional-base64-private-key>"

3.10 [flags] 全部字段（FlagsInConfig，common.proto:7-91；默认值 gen_default_flags，toml.rs:28-76）

字段名即 proto 字段名（snake_case）；文件里只写需要修改的字段（浅合并）。

3.11 [acl]（Acl：proto/acl.proto；仅 TOML / 运行期 easytier-cli acl set）

结构：[acl.acl_v1] → chains（规则链数组）+ group（组声明/成员）。枚举在 TOML 中可写整数（推荐、有测试覆盖 toml.rs:1653-1691）或 pbjson 字符串名。

[[acl.acl_v1.chains]]（Chain）字段：

[[acl.acl_v1.chains.rules]]（Rule）字段：

[acl.acl_v1.group]（GroupInfo）字段：

官方 ACL 页提示：ACL 修改后通常需重启进程生效；easytier-core -d --tcp-whitelist 端口号 可自动生成简单端口白名单规则；easytier-cli acl stats 查看统计。完整示例见第 7.7 节。

3.12 [[managed_credentials]]（ManagedCredentialConfig，toml.rs:485-499；deny_unknown_fields；仅 TOML）

[[managed_credentials]]
credential_id = "temp-alice"
credential_secret = "<base64 X25519>"
groups = ["staff"]
allow_relay = false
allowed_proxy_cidrs = ["10.0.0.0/24"]
expiry_unix = 2000000000
reusable = true

3.13 仅 TOML 支持（CLI 不可设置）的字段一览

netns、instance_id、[[proxy_network]] allow、[[peer]] peer_public_key、[acl] 全部、[[managed_credentials]] 全部、[source]、[flags] disable_relay_data、[flags] prefer_peer_relay、[flags] quic_listen_port（deprecated）、socks5_proxy（URL 形式）。

3.14 全字段 TOML 示例（字段形状参考）

instance_name = "home-node"                    # 同机实例名
instance_id = "87ede5a2-9c3d-492d-9bbe-989b9d07e742"  # 可选，缺省自动生成
hostname = "office-pc"                         # 虚拟网内主机名
netns = "vpn0"                                 # 仅 TOML：Linux network namespace
ipv4 = "10.144.144.10"                         # /32 自动改 /24
ipv6 = "fdab::10/64"
ipv6_public_addr_provider = false
ipv6_public_addr_auto = false
ipv6_public_addr_prefix = "2001:db8:100::/64"  # 需要时才写
dhcp = false

[network_identity]
network_name = "mynet"
network_secret = "${MY_SECRET}"                # 支持环境变量展开

listeners = ["tcp://0.0.0.0:11010", "udp://0.0.0.0:11010", "wg://0.0.0.0:11011"]
mapped_listeners = ["tcp://123.123.123.123:11223"]

[[peer]]
uri = "tcp://public.kkrainbow.top:11010"
peer_public_key = "<可选，对端 secure-mode 公钥>"

[[proxy_network]]
cidr = "192.168.1.0/24"
mapped_cidr = "10.1.0.0/24"     # 可选，同长度映射
allow = ["tcp", "udp", "icmp"]  # 可选，协议过滤

routes = ["192.168.0.0/16"]     # 手动路由
exit_nodes = ["10.144.144.1"]
socks5_proxy = "socks5://0.0.0.0:1080"

[[port_forward]]
bind_addr = "0.0.0.0:11011"
dst_addr = "10.126.126.1:11011"
proto = "tcp"

[secure_mode]
enabled = true
local_private_key = "<base64 X25519>"   # 可选，缺省随机
local_public_key = "<base64 X25519>"    # 可选，缺省由私钥派生

[vpn_portal_config]
wireguard_listen = "0.0.0.0:51820"
wireguard_private_key = "<base64>"
[[vpn_portal_config.clients]]
name = "alice"
virtual_ip = "10.144.144.10/24"
groups = ["staff"]

[acl.acl_v1.group]
members = ["admin", "web-server"]
[[acl.acl_v1.group.declares]]
group_name = "staff"
group_secret = "group-pw"

[[acl.acl_v1.chains]]
name = "protect"
chain_type = 3           # 1=Inbound 2=Outbound 3=Forward
enabled = true
default_action = 2       # 0=Noop 1=Allow 2=Drop
[[acl.acl_v1.chains.rules]]
name = "allow-my-devices"
priority = 1000
action = 1               # 1=Allow
source_ips = ["10.144.144.2/32"]
protocol = 5             # 0=Unspecified 1=TCP 2=UDP 3=ICMP 4=ICMPv6 5=Any
enabled = true

tcp_whitelist = ["80", "8000-9000"]
udp_whitelist = ["53"]

stun_servers = ["txt:stun.easytier.cn", "stun.miwifi.com"]
tcp_stun_servers = ["stun.hot-chilli.net"]
stun_servers_v6 = ["txt:stun-v6.easytier.cn"]

credential_file = "/var/lib/easytier/credentials.bin"

[[managed_credentials]]
credential_id = "temp-alice"
credential_secret = "<base64 X25519>"
groups = ["staff"]
allow_relay = false
allowed_proxy_cidrs = ["10.0.0.0/24"]
expiry_unix = 2000000000
reusable = true

[flags]                  # 任何 FlagsInConfig 字段；只写需要改的
default_protocol = "tcp"
mtu = 1380
latency_first = false

第 4 章　配置文件与命令行的优先级与合并规则

4.1 权威规则与总优先级

• 帮助文本（easytier/locales/app.yml:18，core_clap.config_file）："命令行中的配置的选项会覆盖配置文件中的选项"。
• 实现即 NetworkOptions::merge_into（easytier/src/core.rs:995-1348）：对每个支持的字段，CLI 显式给出（Option::Some / Vec 非空）才写入。
• 总优先级链：

命令行显式值  >  ET_* 环境变量  >  配置文件值  >  内置默认值

4.2 合并条件（can_merge，core.rs:966-993）

CLI 网络参数并非总是合并进配置文件，须同时满足：

1. NetworkOptions 整体不是默认值（至少给了一个网络相关参数；(*self) == NetworkOptions::default() 则不合并，core.rs:973-975）；
2. 且满足其一：
   • 来源是 -c 显式指定的配置文件，且 -c 恰好 1 个、--config-dir 文件数为 0（单文件场景，无条件合并）；
   • 或 CLI --network-name 已给出，且等于该配置文件的 network_identity.network_name（多文件/目录场景按网络名匹配）。

反例：--config-dir 加载的文件，若 CLI 没给 --network-name 或名字对不上，CLI 网络参数完全不作用于它。合并成功后该配置被标记为只读+不可删（core.rs:1600-1605），且该文件不再触发"从 CLI 创建实例"。

4.3 什么时候从 CLI 直接创建实例（crate_cli_network，core.rs:1577-1585）

crate_cli_network =
    若 --daemon                          → false（守护进程模式绝不从 CLI 创建实例）
    否则若 配置文件数==0 且 无 --config-server → true（纯 CLI 启动）
    否则                                  → (--network-name 已给出)

即：--daemon 模式必须有配置文件或配置服务器；混合场景想"文件 + CLI 微调"须满足 4.2 节，否则想从 CLI 起实例必须显式给 --network-name。

4.4 逐字段合并行为（merge_into，core.rs:995-1348）

注意：--manual-routes 给出时是整体替换 routes（不是追加）；--exit-nodes 同理（非空即替换）。

4.5 环境变量在合并体系中的位置

ET_* 环境变量由 clap 在解析 CLI 时读取（env 属性），因此处于"命令行之下、配置文件之上"。此外配置文件文本内部还支持 ${VAR} 展开（3.2 节第 2 条）——两者是独立机制（一个读参数、一个改写 TOML 文本），可以叠加使用。

4.6 易错语义清单（源码行为）

• TOML 顶层未知字段被静默忽略：拼错字段名不报错（3.2 节第 3 条）。
• [file_logger]/[console_logger] 已不被解析：日志只能用 CLI/env（2.10 节）。
• ${VAR} 展开后配置自动只读：不可再被 RPC 修改/删除（3.2 节第 2 条）。
• listeners 字段整体缺省 = 不监听（未与 CLI 合并场景）：文件里不写 listeners 也不给 -l 且走文件启动时，节点不监听任何端口（3.3 节 listeners 条）。
• --daemon 不从 CLI 创建实例（4.3 节）。
• 纯端口 -r 12345 实际绑定 0.0.0.0（2.11 节）。

第 5 章　easytier-cli 全部子命令与参数详解

本档依据：research/cli-params.md 结论，即源码 easytier/src/easytier-cli.rs（3612 行，commit 164e2db6，包版本 2.6.4）。官方文档没有 easytier-cli 参考页，本章全部以源码为准。

5.1 概述与运行机制

• 二进制名 easytier-cli，入口 easytier/src/easytier-cli.rs::main()（需 management feature 编译，easytier/Cargo.toml:25-27）。
• 与 easytier-core 的通信：main() 把全局参数 --rpc-portal 拼成 tcp://<ip>:<port>，用 runtime_rpc_client() 建立 standalone RPC 客户端（easytier-cli.rs:3247-3251；实现 easytier/src/proto/rpc/standalone.rs:26-28）。即 CLI 通过 core 的 RPC 门户（默认 127.0.0.1:15888） 下发查询/配置命令（详见第 6 章）。
• 例外：service、stun、gen-autocomplete 三个命令不经过 RPC，在 CLI 进程本地完成。
• 帮助文本支持 i18n：按系统 locale 选择语言，回退 en（easytier-cli.rs:3243-3244）。
• 语法约定（重要）：全局参数（-p/-v/-o/--no-trunc/-i/-n）定义在根命令上且未标记 global = true，因此必须写在子命令名之前：

# 正确
easytier-cli -p 127.0.0.1:15888 peer list
# 错误（clap 会报 unknown argument）
easytier-cli peer list -p 127.0.0.1:15888

5.2 全局参数详解（根命令 Cli，easytier-cli.rs:84-119，共 6 个）

-p, --rpc-portal <SOCKET_ADDR>

• 类型/默认值：SocketAddr；默认 127.0.0.1:15888。
• 功能：easytier-core 的 RPC 门户地址；CLI 以 tcp://ip:port 连接该地址。
• 示例：easytier-cli -p 203.0.113.7:15888 peer list（连远程 core）
• 注意：类型是 SocketAddr 而不是 URL——只接受 host:port，grpc:// 之类前缀会解析失败（第 6 章）。
• 出处：easytier-cli.rs:87-93, 3247-3251。

-v, --verbose

• 类型/默认值：bool；默认 false。
• 功能：详细输出：多数查询命令改为输出原始结构的 pretty JSON（而非表格/加工后的 JSON）。
• 示例：easytier-cli --verbose peer list
• 注意：对 peer-center、acl、vpn-portal、stats、logger、credential、stun 无额外效果，仅 -o json 生效。
• 出处：easytier-cli.rs:95-96。

-o, --output <FORMAT>

• 类型/默认值：枚举 table|json；默认 table。
• 功能：输出格式；json 输出表格行的 pretty JSON。
• 示例：easytier-cli -o json peer list
• 出处：easytier-cli.rs:98-105, 159-163。

--no-trunc

• 类型/默认值：bool；默认 false。
• 功能：禁用列截断：table 模式默认按终端宽度丢列（按各命令 drop 列表）再截断可选列（加 ... 后缀），此参数关闭该行为。
• 示例：easytier-cli --no-trunc peer list
• 注意：输出重定向（检测不到终端宽度）时自动不截断（easytier-cli.rs:3069-3074）。
• 出处：easytier-cli.rs:107-112, 3022-3067。

-i, --instance-id <UUID>

• 类型/默认值：uuid::Uuid（可选）；无默认。
• 功能：只操作指定实例 ID 的网络实例。
• 示例：easytier-cli -i 5e9f2c1e-1234-4abc-9de0-000000000001 peer list
• 注意：与 -n 同时给出时 id 优先，name 被静默忽略（easytier-cli.rs:174-185）。
• 出处：easytier-cli.rs:114-115, 165-168。

-n, --instance-name <STRING>

• 类型/默认值：String（可选）；无默认。
• 功能：按实例名选择网络实例。
• 示例：easytier-cli -n office peer list
• 出处：easytier-cli.rs:170-171。

5.3 实例选择与多实例 fan-out（easytier-cli.rs:779-916）

• 选择器构造（174-185）：给了 -i 就用 Selector::Id，否则用 Selector::InstanceSelector{name}。
• 未给 -i/-n 时，多数命令会 fan-out 到所有实例（fanout_targets，779-840）：
  1. 通过 WebClientService.list_network_instance 列出全部实例；若 core 没有 WebClientService（普通单实例 core），返回 None → 退化为单实例模式，不发 fan-out；
  2. 实例列表为空则报错 no running instances found；
  3. 否则取每个实例的元数据名（instance_name，为空则回退 network_name），按标签排序后逐实例执行。
• 多实例结果展示（print_results/print_json_results，872-916）：table 模式每个实例前打一行 == <实例名 (实例ID)> ==；json 模式输出数组 [{ "instance_id": ..., "instance_name": ..., "result": ... }]。
• 修改类命令（connector add/remove、whitelist、acl set、vpn-portal client 等）同样按 fan-out 语义应用到"选中的实例(s)"。

5.4 输出格式与表格截断（easytier-cli.rs:3022-3074）

• 表格用 markdown 风格（Style::markdown()）。终端太窄时先按各命令配置的 drop 列表（优先丢 version/tunnel 等次要列）丢整列，仍不够再把可选列截断为 xxx...。
• --no-trunc 或输出重定向（检测不到终端宽度）时不截断；proxy_cidrs 列有专门测试保证最后才被丢（667-701）。

5.5 子命令总览（SubCommand 枚举，easytier-cli.rs:121-157）

共 17 个顶层子命令，嵌套子命令 39 个，合计 56 条命令：

注：任务调研中提到的 sticker 子命令在源码中不存在；completions 对应的实际命令名为 gen-autocomplete。clap 4 派生命名规则：枚举变体转 kebab-case（MappedListener → mapped-listener 等）。

5.6 子命令逐个详解

5.6.1 peer — 对等节点信息（easytier-cli.rs:187-210；dispatch 3263-3279）

嵌套子命令可省略，省略等同 list。

peer list（无参数；handler 1442-1598）

• 功能：列出本节点可见的所有 peer（含本机行）。
• 输出列：ipv4（CIDR）、hostname、cost（Local/Direct/跳数）、lat(ms)、loss、rx、tx、tunnel（逗号分隔的连接协议）、NAT、version；另有隐藏列 id、裸 ipv4。
• 排序：本机行（cost=Local）最先，其次公共服务器主机名，再按 IPv4、hostname（1526-1565）。
• 窄屏 drop 优先级：version → tunnel → NAT → tx → rx → loss → lat(ms)；可选列 tunnel、version（1593-1594）。
• --verbose：输出原始 PeerRoutePair 数组 JSON（不含本机行）；-o json：输出表格行的 JSON。

easytier-cli peer list

输出示意：

| ipv4            | hostname | cost  | lat(ms) | loss | rx     | tx     | tunnel  | NAT           | version |
|-----------------|----------|-------|---------|------|--------|--------|---------|---------------|---------|
| 10.126.126.1/24 | host-a   | Local | -       | -    | -      | -      | -       | UdpBlocked    | 2.6.4   |
| 10.126.126.2/24 | host-b   | 1     | 3.20    | 0.0% | 1.2 MB | 3.4 MB | tcp,udp | OpenInternet  | 2.6.4   |

peer ipv6（无参数；handler 1600-1746）

• 功能：显示各节点的公网 IPv6 地址与 IPv6 前缀提供者信息。
• 输出：第一张表列 peer_id、hostname、inst_id、ipv4、public_ipv6_addr、provider_prefix；若本机是 IPv6 前缀提供者，追加 Local provider prefix: ... 与租约表（peer_id、inst_id、leased_addr、valid_until、reused）。
• --verbose / -o json：整体输出 {nodes, local_provider} JSON。

easytier-cli peer ipv6

peer list-foreign [--trusted-keys]（handler 1761-1819）

• 功能：列出本实例发现的外部网络（如连接公共服务器后其它网络的信息）。

• 输出（纯文本）：<序号> Network Name: <名称>，随后每个 peer 一行 peer_id, peer_conn_count, conns: [ remote_addr, rx_bytes, tx_bytes, latency_us ]；--trusted-keys 时追加 trusted_keys: 块。
• --verbose / -o json：输出原始 ForeignNetworkMap JSON。

easytier-cli peer list-foreign --trusted-keys

peer list-global-foreign（handler 1821-1841）

• 功能：从 peer center 视角列出全局外部网络：Peer ID: <id> + 每行 Network Name, Last Updated, Version, PeerIds。

easytier-cli peer list-global-foreign

5.6.2 connector — 管理出站连接器（easytier-cli.rs:226-252；dispatch 3280-3299）

嵌套子命令可省略，省略等同 list。

connector 级过滤参数（226-236）：

⚠️ 源码事实：这两个参数声明了但未生效——dispatch（3280-3299）只匹配 conn_args.sub_command，全文件无 conn_args.ipv4 / conn_args.peers 的使用点。传了也不会改变行为（保留参数）。

connector add <URL>（handler 1395-1440）

• 功能：添加一个出站 connector 并持久化到实例配置（走 ConfigRpc.patch_config）。
• 位置参数：url（String，必填）。
• 校验：url::Url::parse + TunnelScheme::try_from 两级校验（1387-1393）。可用 scheme：tcp、udp、wg、quic、ws/wss、faketcp、unix（unix 平台）、http、https、ring、txt、srv；不支持时报 unsupported scheme "..." in url (...)。
• 输出：connector add applied to selected instance(s): <url>；多实例时 fan-out 应用。

easytier-cli connector add tcp://1.2.3.4:11010

connector remove <URL>（handler 1402 附近）

• 功能：移除 connector。
• 注意：URL 只做 url::Url::parse，不校验 scheme。
• 输出：connector remove applied to selected instance(s): <url>。

easytier-cli connector remove tcp://1.2.3.4:11010

connector list（handler 1982-1993）

• 功能：列出 connectors；table 模式为 Rust {:#?} debug 打印（非标准表格），--verbose / -o json 输出原始 JSON。

easytier-cli connector list

5.6.3 mapped-listener — 管理映射监听器（easytier-cli.rs:254-268；dispatch 3300-3318）

把"本机公网映射地址"登记到网络中（供其它节点直连尝试）。嵌套子命令可省略，省略等同 list。

mapped-listener add <URL>（handler 2169-2215）

• 功能：登记映射监听器并持久化（patch_config.mapped_listeners）。
• 校验（2205-2215）：必须是 tcp:// 或 udp:// 且带端口号，否则报 Url (...) must start with tcp:// or udp:// / is missing port num。

easytier-cli mapped-listener add tcp://1.2.3.4:11010

mapped-listener remove <URL>（handler 2205 校验同上）

easytier-cli mapped-listener remove tcp://1.2.3.4:11010

mapped-listener list（handler 2156-2167）

• table 为 {:#?} debug 打印；--verbose / -o json 输出 JSON。

easytier-cli mapped-listener list

5.6.4 stun — NAT 类型探测（easytier-cli.rs:129-130；dispatch 3323-3346）

• 功能：执行 STUN 探测，输出本机 NAT 类型与公网地址。
• 参数：无。
• 重要：在 CLI 进程本地执行 STUN 探测（runtime_stun_info_collector），不连接 easytier-core、不经 RPC——结果反映的是运行 CLI 的这台机器的 NAT 环境（除非与 core 同机）。
• 行为：轮询直到 udp_nat_type 与 tcp_nat_type 都非 Unknown（每 200ms 一次），整体超时 25 秒。
• 输出：-o json 时为 StunInfo 的 pretty JSON；否则 stun info: {:#?} debug 格式（含 public_ip、udp_nat_type、tcp_nat_type 等）。

easytier-cli stun

5.6.5 route — 路由信息（easytier-cli.rs:212-224；dispatch 3319-3322）

嵌套子命令可省略，省略等同 list。

route list（handler 1843-1980）

• 功能：显示到各节点的路由。
• 输出列：ipv4、hostname、proxy_cidrs、next_hop_ipv4（cost=1 时为 DIRECT）、next_hop_hostname、next_hop_lat、path_len、path_latency，以及低延迟优先路由的 next_hop_ipv4_lat_first、next_hop_hostname_lat_first、path_len_lat_first、path_latency_lat_first、version；首行为本机（next_hop 显示 Local）。
• 窄屏 drop 优先级（ROUTE_DROP_COLUMNS，596-605）：version → next_hop_hostname_lat_first → next_hop_ipv4_lat_first → path_len_lat_first → path_latency_lat_first → next_hop_hostname → next_hop_lat；proxy_cidrs 保证保留。
• --verbose：输出原始 RouteListData{node_info, peer_routes} JSON；-o json：表格行 JSON。

easytier-cli route list

route dump（handler 1748-1759）

• 功能：请求 core dump 路由（PeerManageRpc.dump_route），输出 CIDR 格式文本：response: <core 返回字符串>；--verbose / -o json 时输出 JSON。
• 注意：table 模式输出为 debug 格式文本。

easytier-cli route dump

5.6.6 peer-center — 全局对等节点视角（easytier-cli.rs:133-134；dispatch 3347-3349）

• 功能：展示全局 peer map：每个节点的直连对端及延迟。无嵌套子命令。
• 输出列：node_id、hostname、ipv4、direct_peers（多行文本 node_id(hostname[ip]): Xms）。
• 注意：仅响应 -o json（输出 PeerCenterRowData 数组）；--verbose 对本命令无额外效果。

easytier-cli peer-center

5.6.7 vpn-portal — WireGuard 门户客户端管理（easytier-cli.rs:270-294；dispatch 3350-3367）

嵌套子命令可省略，省略 = 查看门户信息。

vpn-portal（默认；handler 2799-2841）

• 功能：查看门户状态：portal_name: <vpn_type>、listener: <监听URL>（如有），以及每个客户端块（client / virtual_ip / state / peer_id / endpoint / tunnel_ip / groups）和 WireGuard client_config 文本（client_config_start/end 标记之间，可直接复制给 wg 客户端）。-o json 输出原始 VpnPortalInfo JSON。

easytier-cli vpn-portal

vpn-portal add-client <NAME> --virtual-ip <CIDR> [--groups <GROUP>]...（handler 2739-2764）

easytier-cli vpn-portal add-client phone --virtual-ip 10.90.0.2/16 --groups mobile --groups guest

vpn-portal remove-client <NAME>（按名称移除）

easytier-cli vpn-portal remove-client phone

vpn-portal clear-clients（清空全部客户端）

easytier-cli vpn-portal clear-clients

5.6.8 node — 查看本节点（easytier-cli.rs:296-308；dispatch 3368-3370）

嵌套子命令可省略，省略等同 info。

node info（handler 2843-2908）

• 功能：markdown 键值表输出本节点信息：Virtual IP、Hostname、Proxy CIDRs、Peer ID、Public IPv4/Public IPv6（来自 stun_info.public_ip）、UDP Stun Type、Interface IPv4/Interface IPv6、Listener <idx>（跳过 ring 开头的内置监听）。
• --verbose / -o json：输出完整 NodeInfo JSON。

easytier-cli node info

node config（handler 2861-2864）

• 功能：输出该实例当前生效的配置 TOML 文本（node_info.config）；--verbose / -o json 时仅输出 config 字段 JSON。
• 用途：排查"最终生效配置"（含 CLI 合并结果）的最直接手段。

easytier-cli node config

5.6.9 service — 系统服务管理（easytier-cli.rs:486-541；dispatch 3371-3445）

把 easytier-core 注册为系统服务（systemd/launchd/Windows 服务，service_manager crate）。本地操作，不经 RPC。嵌套子命令必填。

service 级参数（486-493）：

service install [OPTIONS] [CORE_ARGS]...（handler 3374-3426）

• 注意：CORE_ARGS 为 trailing_var_arg——其后所有内容（含 --flag）都归入 core 参数，因此 install 自身选项必须写在 CORE_ARGS 之前（535-540）。
• 安装前打印 install_options: {:#?}（3424）。

sudo easytier-cli service install --core-path /usr/local/bin/easytier-core \
  --network-name mynet --network-secret secretpass

service uninstall / status / start / stop（handler 3427-3443）

• uninstall：注销服务；status：输出 Service is running / Service is stopped / Service is not installed；start/stop：启动/停止服务。

easytier-cli service status

5.6.10 proxy — TCP/KCP/QUIC 代理连接状态（easytier-cli.rs:141-142；dispatch 3446-3498）

• 功能：聚合查询 5 类 TCP 代理通道：tcp、kcp_src、kcp_dst、quic_src、quic_dst（3449），合并全部 entries。无嵌套子命令。
• 输出列：src、dst、start_time（本地时间 %Y-%m-%d %H:%M:%S）、state（TcpProxyEntryState）、transport_type（Tcp/Kcp/Quic）。
• --verbose：直接输出 entries 的 pretty JSON；窄屏 drop/可选列：start_time、state、transport_type。

easytier-cli proxy

5.6.11 acl — ACL 管理与统计（easytier-cli.rs:310-348；dispatch 3499-3506）

嵌套子命令可省略，省略等同 stats。

acl stats（handler 1995-2011）

• 功能：显示 ACL 规则命中统计：有统计则 Display 格式输出，否则 No ACL statistics available；-o json 输出原始 AclStats JSON。

easytier-cli acl stats

acl set <ACL>（handler 2033-2154）

• 功能：运行时整体替换 ACL，无需重启 core。
• 位置参数：acl（String，必填）——完整 ACL 的 TOML 字符串，或 @/path/to/acl.toml（读文件）。
• TOML 结构与配置文件 [acl] 段一致，需含 [acl.acl_v1]（源码 doc 注释 317-333 原文示例）：

[acl.acl_v1]
[[acl.acl_v1.chains]]
name = "Inbound"
chain_type = 1
enabled = true
default_action = 2
[[acl.acl_v1.chains.rules]]
protocol = 3
action = 1

• 注意：
  • 解析失败报 failed to parse ACL TOML (expected [acl.acl_v1] structure)；空 ACL（无 chain 且无 group）报错（2050-2057）。
  • 回显时 group_secret 被替换为 <redacted>，避免凭据泄漏（2059-2068）。
  • 多实例 fan-out；每个实例输出 == <label> == + ACL updated successfully (N chain(s)) 或失败信息；-o json 时输出 {instance, success, chains, acl}。
  • tcp_whitelist/udp_whitelist 是独立配置项，不在 acl set 管辖内（2013-2015）。

easytier-cli acl set @/etc/easytier/acl.toml

5.6.12 port-forward — 端口转发管理（easytier-cli.rs:350-378；dispatch 3507-3539）

嵌套子命令可省略，省略等同 list。

port-forward add <PROTOCOL> <BIND_ADDR> <DST_ADDR>（handler 2217-2260）

• 通过 patch_config.port_forwards（action=Add）持久化；输出 Port forward rule added: tcp 0.0.0.0:8080。

easytier-cli port-forward add tcp 0.0.0.0:8080 10.1.1.1:80

port-forward remove <PROTOCOL> <BIND_ADDR> [DST_ADDR]

• 功能：移除规则；dst_addr 可选（只按 protocol+bind_addr 匹配时省略）。

easytier-cli port-forward remove tcp 0.0.0.0:8080

port-forward list（handler 2285-2323）

• 输出列：protocol、bind_addr、dst_addr；--verbose / -o json 输出原始 ListPortForwardResponse JSON。

easytier-cli port-forward list

5.6.13 whitelist — TCP/UDP 端口白名单（easytier-cli.rs:380-404；dispatch 3540-3556）

嵌套子命令可省略，省略等同 show。

whitelist set-tcp <PORTS> / set-udp <PORTS>（handler 2325-2380）

• 位置参数：ports（String）——逗号分隔，单项为单端口（u16）或区间 start-end（start ≤ end），如 80,443,8000-9000；解析见 parse_port_list（2990-3019），非法报 Invalid port number/range。
• 语义：整体替换该协议白名单（先发 Clear 再 Add）。
• 输出：TCP whitelist updated: <ports> / UDP whitelist updated: <ports>。

easytier-cli whitelist set-tcp 80,443,8000-9000

whitelist clear-tcp / clear-udp（handler 2417-2429）

easytier-cli whitelist clear-tcp

whitelist show（handler 2431-2459）

• 输出两行：TCP Whitelist: 80, 443（空则 None）与 UDP Whitelist: None；--verbose / -o json 输出原始 GetWhitelistResponse JSON。

easytier-cli whitelist show

5.6.14 stats — 统计信息（easytier-cli.rs:406-418；dispatch 3557-3564）

嵌套子命令可省略，省略等同 show。

stats show（handler 2910-2968）

• 输出列：Metric Name、Value、Labels（k=v 逗号连接，空为 -）。值格式化：名字含 bytes → 二进制 humanize（如 1.5 MiB）；含 duration → <N> ms；其余原样。-o json 输出 MetricSnapshot 数组。

easytier-cli stats show

stats prometheus（handler 2970-2988）

• 功能：原样输出 Prometheus 文本格式指标（含 WireGuard 客户端流量指标，即本版本 commit #2537 引入的能力）；-o json 输出 {"prometheus_text": "..."}。适合被 Prometheus 抓取脚本调用。

easytier-cli stats prometheus

5.6.15 logger — 日志配置（easytier-cli.rs:420-435；dispatch 3565-3572）

嵌套子命令可省略，省略等同 get。

logger get（handler 2461-2487）

• 输出：table 模式 Current Log Level: <level>；-o json 输出原始 GetLoggerConfigResponse JSON。

easytier-cli logger get

logger set <LEVEL>（handler 2489-2524）

• 位置参数：level（String，大小写不敏感）——disabled、error、warning、info、debug、trace；其它报 Invalid log level: ...。
• 功能：动态修改 core 的文件日志级别（经 LoggerRpc）；输出 Log level successfully set to: <level>。
• 注意：调整的是文件日志级别（官方文档口径）。

easytier-cli logger set debug

5.6.16 credential — 临时凭据管理（easytier-cli.rs:437-484；dispatch 3573-3599）

嵌套子命令必填（无默认）。需节点已开启 secure mode（管理节点配置 --secure-mode，建议配合 --credential-file 持久化）。

credential generate [OPTIONS]（handler 2526-2578）

• 输出（table 模式）：

Credential generated successfully:
  credential_id:     <uuid>
  credential_secret: <secret>

To use this credential on a new node:
  easytier-core --network-name <name> --secure-mode --credential <secret> -p <node-url>

easytier-cli credential generate --ttl 3600 --groups guest --allow-relay --reusable true

credential revoke <CREDENTIAL_ID>（handler 2580-2614）

• 位置参数：credential_id（String，UUID）。输出 Credential revoked successfully 或 Credential not found。

easytier-cli credential revoke 8b1f6c1e-1234-4abc-9de0-000000000001

credential list（handler 2616-2671）

• 功能：列出活跃凭据，表格列：ID、Groups、Relay、Reusable、Expiry（<N>s remaining 或 expired）、Allowed CIDRs；无凭据输出 No active credentials。

easytier-cli credential list

5.6.17 gen-autocomplete <SHELL> — 生成补全脚本（easytier-cli.rs:155-156；dispatch 3600-3608）

• 位置参数：shell——bash、elvish、fish、powershell、zsh、nu（easytier/src/lib.rs:32-39）。
• 功能：向 stdout 打印对应 shell 的补全脚本；nu（Nushell）走专用生成器，其余走 clap_complete。
• 注意：本地执行，不经 RPC。

easytier-cli gen-autocomplete zsh > "${fpath[1]}/_easytier-cli"
easytier-cli gen-autocomplete bash > /etc/bash_completion.d/easytier-cli

5.7 互斥 / 组合规则与源码陷阱汇总

互斥 / 组合规则（cli-params.md §4）：

1. -i/--instance-id 与 -n/--instance-name 二选一；同时给出时 id 优先，name 被忽略。
2. 全局参数位置：-p/-v/-o/--no-trunc/-i/-n 必须位于子命令之前（根命令参数，非 global=true）。
3. --verbose 与 -o json 可同时存在；对多数查询命令 --verbose 优先（输出原始结构 JSON），-o json 输出表格行 JSON。对 peer-center、acl、vpn-portal、stats、logger、credential、stun，--verbose 无效果。
4. port-forward add 的 dst_addr 必填；remove 的 dst_addr 可选。
5. acl set 与 whitelist 互不覆盖。
6. credential 与 service 的嵌套子命令必填；其余均有默认子命令（见 5.5 表）。
7. connector add 的 URL scheme 校验严格（TunnelScheme 列表），connector remove 只做 URL 语法解析。
8. mapped-listener add/remove 强制 tcp:// 或 udp:// 且必须带端口。
9. service install 的 [CORE_ARGS]... 为 trailing_var_arg：install 自身选项必须写在 CORE_ARGS 之前。

源码层面陷阱（cli-params.md §5，使用时留意）：

• connector --ipv4/--peers 声明未生效（228-232 vs dispatch 3280-3299）。
• port-forward add/remove 对非法 dst_addr 会 panic（unwrap()，2242），而不是打印错误。
• stun 是 CLI 本机探测，不反映 core 所在主机（除非同机执行），且不依赖 --rpc-portal。
• route dump / connector list / mapped-listener list 的 table 模式是 Rust debug 格式化输出，非标准表格。
• peer list 的 lat(ms)：cost=1 时取直连延迟，否则取"低延迟优先路径"的整段延迟（1471-1475）。
• 二进制需以 management feature 编译（easytier/Cargo.toml:25-27）。

第 6 章　连接 easytier-core：管理 RPC 通道（原"gRPC"章节需求）

需求原文要求"使用 gRPC 连接其他 easytier-core"。经源码考证，当前版本的 EasyTier 管理通道不是 gRPC。本章如实呈现：管理通道的真实形态、服务端/客户端配置方法、安全机制、服务能力清单、完整示例与排错。禁止虚构 grpc:// URL——本仓库全部 git 历史中从未存在该形式的连接地址。

6.1 重要结论：gRPC 的历史与现状（源码考证）

• 当前 Cargo.lock 中 tonic 仅作为 tokio-console 调试工具的传递依赖存在，EasyTier 自身代码不依赖。
• git log --all -S 'grpc://' 与全历史 git grep 'grpc://' 均无结果。
• 官方文档全文（中英文）grep grpc 零结果；"RPC 设置"一节只描述 --rpc-portal 与 --rpc-portal-whitelist。

落地结论：第三方程序想远程管理 easytier-core，正确路径是：
a) 直接复用 EasyTier 的 Rust crate（easytier::proto 的 runtime_rpc_client + ClientFactory，见 6.4.3）；
b) 部署 easytier-web 走其 REST API 代理（见 6.4.4）。
两者都不是 gRPC。

6.2 服务端：在 easytier-core 上开启管理 RPC

6.2.1 开启与监听地址（--rpc-portal）

• CLI 定义：easytier/src/core.rs:804-820（RpcPortalOptions）；启动挂载 core.rs:1504-1510（ApiRpcServer::new(...).serve()，与实例管理器同生共死）。
• 解析规则（easytier/src/rpc_service/api.rs:119-154，源码为准）：

• 端口扫描：find_free_tcp_port(15888..15900)（easytier/src/utils/mod.rs:16-18）；全部占用则启动失败（No free port found for RPC portal）。选出的随机端口不打印到日志，用 ss -tlnp | grep easytier-core 确认。
• ⚠️ 与官方文档不一致：帮助文案和官网都写"12345 表示在 localhost 的 12345 上监听"，但源码把纯端口解析为 0.0.0.0:P（所有接口）——以源码为准（api.rs:120-122）。
• 协议形态：监听器是裸 TCP tunnel（TcpTunnelListener，easytier/src/rpc_service/api.rs:31-42）——没有 HTTP/2、没有 TLS、没有 UDP。线路协议为 protobuf 消息 RpcPacket（easytier-proto/proto/common.proto:149-164，含 transaction_id、descriptor（服务+方法名）、body、is_request、分片字段、compression_info），经 tunnel 帧封装、可选 zstd 压缩。grpcurl/curl/任何 gRPC 客户端都无法与该端口对话。

6.2.2 访问控制（--rpc-portal-whitelist）

• 实现：ManagementRpcServerHook（easytier-core/src/management/rpc_server_hook.rs:9-52）——基于客户端来源 IP 的 CIDR 白名单，在 TCP accept 后立即检查，未命中返回错误 RPC portal client IP {ip} is not in whitelist {…} 并断开连接（standalone.rs:105-111）。
• 默认白名单：127.0.0.0/8 + ::1/128（仅回环，rpc_server_hook.rs:14-20）。
• 显式传参后完全替换默认值：例如 --rpc-portal-whitelist 192.168.1.0/24 生效后，回环地址不再默认放行，需自行加上 127.0.0.1/32 或 127.0.0.0/8。
• 参数格式：逗号分隔的 IP 或 CIDR（127.0.0.1 等价 127.0.0.1/32）；env ET_RPC_PORTAL_WHITELIST。

6.2.3 安全须知（必须阅读）

1. 管理 RPC 无认证：没有密码、Token 或证书校验，唯一访问控制是来源 IP 白名单。拿到端口访问权 = 拿到 core 的完全控制权（增删连接器、改配置、下线实例、读凭据等）。
2. 明文传输：TCP tunnel 无 TLS，管理流量（含配置、凭据操作参数）明文过网。
3. 推荐做法：
   • 默认（不传 -r）：绑定 0.0.0.0 但端口随机（15888~15899）+ 仅回环白名单，本机使用安全；
   • 远程管理优先用 SSH 隧道（见 6.5 示例 3b），或把白名单收敛到管理网段；
   • 白名单按最小化原则配置 CIDR，并依赖防火墙限流；
   • 不要把 --rpc-portal-whitelist 0.0.0.0/0 暴露公网。
4. easytier-web 的反向通道是唯一带 Token 的管理通道（URL 末段即 Token，见 6.4.4）。

6.3 客户端：连接一个 easytier-core

6.3.1 easytier-cli（官方命令行客户端）

• 全局参数 -p/--rpc-portal <host:port>（默认 127.0.0.1:15888，easytier-cli.rs:86-93）：拿到 host:port 后内部固定拼成 tcp:// URL 建立原生 TCP tunnel（easytier-cli.rs:3247-3260）。
• 支持连远程 core：easytier-cli -p 203.0.113.7:15888 peer list（前提：目标白名单放行你的出口 IP）。
• 协议不可选：永远 TCP；grpc://127.0.0.1:15888 这类 URL 传不进去（SocketAddr 解析直接失败）。
• 连接为一次性短连接（每条子命令建连→执行→退出）；StandAloneClient 在同一命令内复用连接、出错自动重连（easytier-core/src/rpc/standalone.rs:242-264）。

6.3.2 多实例选择

• 一个 core 进程可同时跑多个网络实例；管理 RPC 是进程级的，请求里的 InstanceIdentifier（proto：easytier-proto/proto/api_instance.proto）选择目标实例，CLI 对应 -i <uuid> / -n <实例名>（easytier-cli.rs:165-182）；不带选择器时部分命令 fan-out 到所有实例（easytier-cli.rs:787-916）。

6.3.3 其他客户端（Rust / FFI）

use easytier::proto::rpc::standalone::{runtime_rpc_client, RuntimeRpcClient};
let mut client = runtime_rpc_client("tcp://127.0.0.1:15888".parse().unwrap());
let peer = client.scoped_client::<PeerManageRpcClientFactory<BaseController>>("".into()).await?;
let resp = peer.list_peer(BaseController::default(), ListPeerRequest::default()).await?;

（出处：easytier/src/proto/rpc/standalone.rs:18-28；CLI 同款用法 easytier/src/easytier-cli.rs:918-928。）

6.3.4 easytier-web（反向连接 + REST 代理，简要）

• 方向相反：easytier-web 不主动连 core，而是 core 作为 web client 主动外连 web 控制台：easytier-core --config-server <url>（-w，见 2.2 节）。
• URL 格式：<proto>://<host>:<port>/<token>，URL 最后一段路径即认证 Token（ConfigServerEndpoint::parse，web_client.rs:53-87）；允许的协议与 listeners 一致（如 udp://192.0.2.1:22020/admin）。
• easytier-web 端口：配置下发默认 22020（udp），REST API 默认 11211（easytier-web/src/main.rs:67-131）。
• REST 通用 RPC 代理（登录态）：POST /api/v1/machines/:machine-id/proxy-rpc（easytier-web/src/restful/rpc.rs:206-211），请求体 {service_name, method_name, payload}，服务名形如 api.config.ConfigRpcService、api.instance.PeerManageRpcService（restful/rpc.rs:100-141）——这是第三方程序做自动化管理的现成 HTTP 入口（仍不是 gRPC）。

6.4 管理通道服务清单（rpc.proto 主要能力）

注：任务提示中的"rpc.proto"实际对应一组 api_*.proto（easytier-proto/proto/api_instance.proto、api_config.proto、api_logger.proto、api_manage.proto）与 common.proto::RpcPacket。服务由进程级 ServiceRegistry 注册（空 domain），完整注册集见 easytier-core/src/management/full/mod.rs:74-91；精简构建（无 management feature）仅注册只读的 PeerManageRpc + ConnectorManageRpc（management/mod.rs:58-68）。

13 个服务 → 方法 → easytier-cli 子命令映射：

（stun、service、gen-autocomplete 三个子命令不经过管理 RPC：stun 本地探测、service 操作操作系统服务、gen-autocomplete 生成补全。）

所有实例级请求的第一字段是 InstanceIdentifier，CLI 用 -i/-n 填充；控制器 BaseController 携带 tunnel 信息（服务端白名单看到的正是它）。

6.5 端到端示例（可直接复制）

示例 1：本机默认连接（零配置）

# 终端 1：启动 core。不传 -r，等价 --rpc-portal 0：
#   在 15888~15899 里挑第一个空闲端口（通常就是 15888），白名单默认仅回环
easytier-core --network-name mynet --network-secret s3cret

# 终端 2：CLI 默认连 127.0.0.1:15888
easytier-cli peer list
easytier-cli node info
easytier-cli -o json peer list

示例 2：固定端口 + 本机连接

easytier-core -r 127.0.0.1:15888 --network-name mynet --network-secret s3cret
easytier-cli -p 127.0.0.1:15888 route
easytier-cli -p 127.0.0.1:15888 logger set debug   # 动态调日志级别

示例 3a：远程管理 + 白名单

# 服务端（203.0.113.7）：监听所有接口；白名单=管理机 192.168.1.0/24 + 回环
easytier-core -r 0.0.0.0:15888 \
  --rpc-portal-whitelist 192.168.1.0/24,127.0.0.1/32 \
  --network-name mynet --network-secret s3cret

# 管理机（192.168.1.50）远程执行
easytier-cli -p 203.0.113.7:15888 peer list
easytier-cli -p 203.0.113.7:15888 connector add tcp://203.0.113.8:11010

示例 3b：远程管理 + SSH 隧道（更安全的替代）

# 不开放 RPC 端口到网络，改走 SSH 转发：
ssh -N -L 15888:127.0.0.1:15888 user@203.0.113.7
# 然后在本机像本地一样使用（core 侧可保持 -r 127.0.0.1:15888 或默认回环白名单）
easytier-cli -p 127.0.0.1:15888 peer list

示例 4：多实例 core + 按实例操作

# 一个 core 进程加载多份配置文件
easytier-core --config-dir /etc/easytier --rpc-portal 0.0.0.0:15888 \
  --rpc-portal-whitelist 127.0.0.0/8

easytier-cli -p 127.0.0.1:15888 -n office peer list      # 按实例名选择
easytier-cli -p 127.0.0.1:15888 -i 5e9f...-uuid node info # 按实例 ID 选择

示例 5：easytier-web 托管（带 Token 的反向通道 + REST 代理）

# 服务器上起 web 控制台（config-server 22020/udp + REST API 11211）
easytier-web

# 节点上以 web client 身份外连（URL 末段是 Token）
easytier-core --config-server udp://203.0.113.9:22020/admin-token-123

# 第三方自动化走 REST 代理（登录后）。请求体字段为
# {service_name, method_name, payload}（easytier-web/src/restful/rpc.rs:15-20）：
curl -X POST http://203.0.113.9:11211/api/v1/machines/<machine-id>/proxy-rpc \
  -H 'Content-Type: application/json' \
  -d '{"service_name":"api.instance.PeerManageRpcService","method_name":"list_peer","payload":{}}'

示例 6（反例）：为什么"跨协议"连不上

# 15888 不是 gRPC/HTTP 端口 —— 以下全部失败，属预期行为：
grpcurl -plaintext 127.0.0.1:15888 list          # 非 HTTP/2，握手即断
curl http://127.0.0.1:15888                      # 私有二进制帧，无 HTTP 响应
easytier-cli -p 'grpc://127.0.0.1:15888' peer list   # SocketAddr 解析直接报错

6.6 常见连接失败排查

第 7 章　常用完整组网示例

以下示例全部可复制执行，参数语义见第 2 章。约定：<A 公网 IP> 等占位符需替换；Linux 需 root/sudo（创建 TUN），Windows 以管理员运行 .\easytier-core.exe。

7.1 双机直连组网（去中心化，最简）

适合两台机器其中之一有公网 IP（或同一内网）。

# 节点 A（有公网 IP，例如 203.0.113.7）
sudo easytier-core \
  --network-name mynet --network-secret 's3cret' \
  -i 10.144.144.1 \
  -l 11010 \
  -r 15888

# 节点 B（NAT 后）
sudo easytier-core \
  --network-name mynet --network-secret 's3cret' \
  --dhcp \
  -p udp://203.0.113.7:11010

要点：默认即监听 11010 全协议（TCP/UDP 同端口，WG/WS 11011、QUIC/WSS 11012、FakeTCP 11013，见 2.12）；-d 自动分配虚拟 IP；验证用 easytier-cli peer list、easytier-cli route list、easytier-cli node info。极端简化版（官方去中心组网页）：sudo easytier-core -i 10.144.144.1 与 sudo easytier-core -d -p udp://22.1.1.1:11010（默认网络，不推荐用于生产）。

7.2 通过公共共享节点组网（DHCP）

sudo easytier-core \
  --network-name abc --network-secret abc \
  -d \
  -p tcp://public.kkrainbow.top:11010

• 多个共享节点：-p tcp://1.1.1.1:11010 -p udp://1.1.1.2:11011（官方建议所有节点指定相同共享节点列表）。
• 也可用 -e/--external-node tcp://public.easytier.top:11010 声明公共服务器做发现。
• 官方快速组网页：DHCP 默认网段 10.126.126.0/24；需指定网段时给某节点 -i 10.11.11.11/24。

7.3 子网代理（点对网）

节点 A 能访问本地网段 192.168.1.0/24，把它导出给虚拟网：

# 节点 A（代理方）
sudo easytier-core \
  --network-name mynet --network-secret 's3cret' \
  -i 10.126.126.1 \
  -n 192.168.1.0/24

# 节点 B（消费方，之后可直接访问 192.168.1.x）
sudo easytier-core \
  --network-name mynet --network-secret 's3cret' \
  --dhcp \
  -p tcp://<A 地址>:11010

• 多网段：-n 10.1.1.0/24 -n 10.2.0.0/16 -n 10.3.3.3/32（掩码 32 可代理单 IP）。
• 网段映射：-n '192.168.1.0/24->10.1.1.0/24'（映射后网段大小必须与原网段相同）。
• --manual-routes 192.168.0.0/16：只把指定 CIDR 写入路由，禁用子网代理与对等传播的自动路由。
• --proxy-forward-by-system：网关设备上交由内核转发、关闭内置 NAT。
• --use-smoltcp：无法关闭防火墙时用用户态协议栈（仅影响 TCP，性能劣于内核栈）。
• 防火墙需放行虚拟网卡 INPUT/OUTPUT；验证：easytier-cli route list 的 proxy_cidrs 列。
• 协议级过滤（仅 TCP/UDP/ICMP）用 TOML [[proxy_network]] allow（3.6 节）。

7.4 KCP / QUIC 代理与 WSS 监听（带宽延迟优化）

# 服务端：开启 KCP/QUIC 代理 + 监听 WSS（11012，可过 CDN/反代）
sudo easytier-core \
  --network-name mynet --network-secret 's3cret' \
  -i 10.126.126.1 \
  -l 11010 \
  --enable-kcp-proxy --enable-quic-proxy

# 客户端：NAT 后、只想收不发
sudo easytier-core \
  --network-name mynet --network-secret 's3cret' \
  --dhcp \
  -p wss://<服务端>:11012 \
  --disable-kcp-input --disable-quic-input

• 仅 WSS 监听：-l wss://0.0.0.0:11012（独立默认 443，见 2.12）。
• 防火墙受限环境给代理加用户态栈：--use-smoltcp。
• 官方说明：v2.6.0+ QUIC 优先于 KCP 生效（目的端关闭 QUIC 输入后 KCP 才生效）；对端不支持时自动回落 TCP。
• 查看活跃代理连接：easytier-cli proxy（transport_type 列显示 Tcp/Kcp/Quic）。

7.5 安全模式组网（三种场景）

场景一：普通节点启用安全模式（在原有 name/secret 基础上）：

sudo easytier-core \
  --network-name office --network-secret 'replace-with-a-strong-secret' \
  --secure-mode \
  -d -p tcp://node-a.example.com:11010

场景二：共享节点固定身份 + 客户端锁定公钥：

# 共享节点：固定私钥（否则每次启动随机生成，客户端无法锁定其身份）
sudo easytier-core --secure-mode --local-private-key '<base64 X25519>' -l 11010

客户端在配置文件中用 [[peer]] peer_public_key 锁定（仅 TOML 支持，见 3.5）：

[network_identity]
network_name = "office"
network_secret = "replace-with-a-strong-secret"

[secure_mode]
enabled = true

[[peer]]
uri = "tcp://relay.example.com:11010"
peer_public_key = "<relay-public-key-base64>"

仅开 --secure-mode 不等于确认了共享节点身份（官方安全模式页）；升级时先升级服务端再升级客户端。

场景三：临时凭据接入：

# 管理节点：开启 secure mode 并持久化凭据
sudo easytier-core --network-name office --network-secret 'xxx' --secure-mode \
  --credential-file /var/lib/easytier/credentials.json

# 签发 24 小时凭据（权限受限：guest 组、允许中继、允许代理指定网段）
easytier-cli credential generate --ttl 86400 --groups guest --allow-relay \
  --allowed-proxy-cidrs 192.168.10.0/24

# 临时节点：用凭据加入（隐式启用 secure mode，无需 network-secret）
sudo easytier-core --network-name office --credential '<credential-secret-base64>' \
  -p tcp://node-a.example.com:11010

7.6 WireGuard 客户端接入（VPN 门户）

# 服务端：声明门户与具名客户端（旧版 wg://.../CIDR 路径格式已废弃！）
sudo easytier-core \
  --network-name mynet --network-secret 's3cret' \
  -i 10.126.126.1 \
  --vpn-portal wg://0.0.0.0:51820 \
  --vpn-portal-client alice=10.90.0.2/16 --vpn-portal-client bob=10.90.0.3/16

# 获取 WireGuard 客户端配置（client_config 文本夹在标记行之间）
easytier-cli vpn-portal

• 多客户端用更大网段（如 /16）；客户端分组：--vpn-portal-client-group alice=staff。
• 也可纯 TOML 管理（[vpn_portal_config]，见 3.7）。

7.7 ACL 配置文件示例

/etc/easytier/acl.toml：

[acl.acl_v1.group]
members = ["admin", "web-server"]
[[acl.acl_v1.group.declares]]
group_name = "staff"
group_secret = "group-pw"

[[acl.acl_v1.chains]]
name = "protect-node"
chain_type = 1            # 1=Inbound（访问本机）
enabled = true
default_action = 2        # 2=Drop（静默丢弃）

[[acl.acl_v1.chains.rules]]
name = "allow-admin-ssh"
priority = 1000
action = 1                # 1=Allow
source_groups = ["admin"]
protocol = 1              # 1=TCP
ports = ["22"]
enabled = true

[[acl.acl_v1.chains.rules]]
name = "allow-icmp"
priority = 500
action = 1
protocol = 3              # 3=ICMP（IPv6 用 4=ICMPv6，放开任意协议用 5=Any）
enabled = true

使用方式（二选一）：

# 方式一：随配置文件加载（写进主配置的 [acl] 段后 -c 启动）
sudo easytier-core -c /etc/easytier/mynet.toml

# 方式二：运行时整体替换（免重启；也可直接内联 TOML 字符串）
easytier-cli acl set @/etc/easytier/acl.toml
easytier-cli acl stats

要点：所有节点的 group.declares 必须完全一致；规则按 priority 降序匹配；tcp_whitelist/udp_whitelist 是独立机制、不受 acl set 影响。

7.8 配置文件 + 多实例 + CLI 微调

# /etc/easytier/mynet.toml
instance_name = "mynet"
hostname = "office"
[network_identity]
network_name = "mynet"
network_secret = "s3cret"
listeners = ["tcp://0.0.0.0:11010"]
[[peer]]
uri = "tcp://public.kkrainbow.top:11010"
[flags]
latency_first = true

# 校验（不启动；退出码 0 = 合法）
easytier-core --check-config -c /etc/easytier/mynet.toml

# 单文件 + CLI 微调：因为 network_name 一致（单文件场景无条件合并），CLI 覆盖 MTU、追加白名单
sudo easytier-core -c /etc/easytier/mynet.toml --mtu 1420 --tcp-whitelist 22,80,443

# 多实例：conf.d 下每个 .toml 一个实例；CLI 参数仅对网络名匹配的文件生效（4.2）
sudo easytier-core --config-dir /etc/easytier/conf.d --network-name mynet --mtu 1420

# 查看最终生效配置（含合并结果）
easytier-cli node config

多实例要求：不同虚拟网虚拟 IP 网段不能重叠；监听端口与 RPC 端口都不能冲突（官方 FAQ）。

7.9 无 TUN / SOCKS5 / 端口转发（免 Root 场景）

# 无 TUN：可被访问、可做子网代理，但无法主动发起访问（主动访问走 SOCKS5）
sudo easytier-core \
  --network-name mynet --network-secret 's3cret' \
  --no-tun \
  -n 192.168.1.0/24 \
  --socks5 1080
# 本机用 socks5://<本机>:1080 即可访问虚拟网

# 端口转发：把本地 UDP 12345 转发到虚拟网内 10.126.126.1:53
sudo easytier-core --network-name mynet --network-secret 's3cret' --dhcp \
  --port-forward udp://0.0.0.0:12345/10.126.126.1:53

7.10 搭建共享节点（公共服务器）

# 纯公共服务器：不带网络参数启动（无需 root）
easytier-core

# 推荐：只帮其他网建 P2P、只转发 RPC，不转发业务流量
easytier-core --relay-network-whitelist --relay-all-peer-rpc

# 私有共享节点：仅允许指定网络接入
easytier-core --private-mode true --network-name my-network --network-secret my-secret

• systemd 部署建议 LimitNOFILE=1048576；可用 fail2ban 防无效连接（官方共享节点页）。
• 作为共享节点建议固定 secure-mode 私钥（7.5 场景二）。

7.11 出口节点（全流量出口）

# 节点 A：允许成为出口
sudo easytier-core --network-name mynet --network-secret 's3cret' \
  -i 10.126.126.1 --enable-exit-node

# 节点 B：把流量交给 A（可多个，按顺序优先）
sudo easytier-core --network-name mynet --network-secret 's3cret' \
  --dhcp -p tcp://<A 地址>:11010 --exit-nodes 10.126.126.1

7.12 服务化与环境变量

# 一键注册系统服务（CORE_ARGS 之前的都是 install 自身选项）
sudo easytier-cli service install \
  --core-path /usr/local/bin/easytier-core \
  -- --network-name mynet --network-secret 's3cret' -d -p tcp://public.kkrainbow.top:11010
easytier-cli service status

# 环境变量等价写法（ET_*；命令行 > env > 配置文件）
sudo ET_NETWORK_NAME=mynet ET_NETWORK_SECRET=s3cret ET_DHCP=true easytier-core

# 精细日志控制（覆盖 --console-log-level）
sudo RUST_LOG=warn,easytier_core=debug,hyper=off easytier-core --file-log-level info \
  --file-log-dir /var/log/easytier

7.13 SOCKS5 出口（按域名/部分流量分流）

结论先行：--exit-nodes 是"把本机全部流量交给出口节点"的机制（7.11 节）；EasyTier 没有"只让某个域名/应用走出口"的分流参数。要让"只有 YouTube 等指定域名经指定节点出网"，标准做法是两步组合——出口节点开启内置 SOCKS5 服务器 + 客户端用支持规则分流的工具（Clash/mihomo、SwitchyOmega、PAC 等）把指定域名指向它。

工作原理（源码行为）：SOCKS5 客户端把连接请求交给出口节点 A 代为发起——目标是虚拟网内地址的连接仍走 EasyTier 隧道；其余目标（如 youtube.com，域名由 A 本机解析）按网关连接策略 OverlayOrDirect 走 A 自己的网络直接出网（easytier-core/src/gateway/dataplane/mod.rs:128-140、gateway/dataplane/route.rs:30-57；域名解析在 gateway/socks5/host.rs:28-53）。因此本场景下 A 不需要 --enable-exit-node，与 --exit-nodes/出口节点机制无关。

节点 A（出口方：开启内置 SOCKS5）

sudo easytier-core \
  --network-name mynet --network-secret 's3cret' \
  -i 10.126.126.1 \
  --socks5 1080
# 监听 0.0.0.0:1080（CLI 只填端口）。注意：此场景 A 不需要 --enable-exit-node——
# SOCKS5 收到的"上网"流量由 A 本机直接出网，不走出口节点机制。

等价 TOML（socks5_proxy 为完整 URL，用 -c 启动；需要时还可把监听收窄到指定地址）：

# /etc/easytier/mynet.toml
[network_identity]
network_name = "mynet"
network_secret = "s3cret"

ipv4 = "10.126.126.1"
socks5_proxy = "socks5://0.0.0.0:1080"

sudo easytier-core -c /etc/easytier/mynet.toml

节点 B（客户端：规则分流，只把指定域名交给 A）

B 正常组网即可（能通过虚拟网访问 A 的虚拟 IP，参考 7.1 节）。以 Clash/mihomo 为例：

proxies:
  - name: easytier-socks5
    type: socks5
    server: 10.126.126.1      # A 的虚拟 IP
    port: 1080                # A 的 --socks5 端口

rules:
  # 只让 YouTube 相关域名走 A 的 SOCKS5 出口
  - DOMAIN-SUFFIX,youtube.com,easytier-socks5
  - DOMAIN-SUFFIX,googlevideo.com,easytier-socks5   # YouTube 视频流
  - DOMAIN-SUFFIX,ytimg.com,easytier-socks5
  - DOMAIN-SUFFIX,youtu.be,easytier-socks5
  - MATCH,DIRECT                                     # 其余流量直连

浏览器场景用 SwitchyOmega 或 PAC 文件也能达到同样的"按域名分流"效果。

注意事项

• 安全（务必阅读）：内置 SOCKS5 无认证（源码固定允许无认证连接，gateway/socks5/adapter.rs:95-99），且 CLI 写法固定监听 0.0.0.0（core.rs:1150-1157）——任何能路由到该端口的主机都可使用。务必用防火墙限制来源；仅本机使用时可改用 TOML 把监听收窄为 socks5_proxy = "socks5://127.0.0.1:1080"。
• feature 门控：--socks5/socks5_proxy 受编译 feature socks5 门控（easytier/Cargo.toml:374），官方发行版一般已启用。
• 粗粒度备选（不推荐）：也可以用"出口节点 + --exit-nodes（7.11 节）+ --manual-routes 只填 Google 网段"把到 Google 的流量路由到出口。缺点：殃及所有 Google 服务（搜索/邮件等一并走出口），且 Google 网段列表多变、需持续维护——按域名精确分流请优先用本节的 SOCKS5 方案。
• ACL 不是替代品：ACL（3.11 节）做的是虚拟网内的权限控制（谁能访问谁），不解决"本机哪些流量交给哪个出口"的分流问题。
• 数据面限制：SOCKS5 网关的 TCP 数据面目前仅支持 IPv4 目标（gateway/dataplane/mod.rs:569-574，IPv6 目标返回 AddressFamilyUnsupported）。
• 与 7.9/7.11 的关系一句话：7.9 的 SOCKS5 用于"免 Root 访问虚拟网"，7.11 的 --exit-nodes 用于"全部流量走出口"，本节用于"按域名把部分上网流量交给指定节点出网"。

第 8 章　附录：参数速查表与差异说明

8.1 easytier-core 命令行参数速查表（89 个）

进程与配置来源（8）

网络基础（16）

VPN 门户（4）

加密 / 安全模式 / 凭据（7）

运行时行为（23）

代理与端口转发（16）

白名单 / 中继 / STUN（8）

日志（5，进程级，不能写入配置文件）

RPC 门户（2）

8.2 TOML 配置字段速查表

顶层字段（31）：

[flags] 字段：43 个，逐字段速查见 3.10 表（默认值均为 gen_default_flags，toml.rs:28-76）。

8.3 easytier-cli 命令速查表（17 顶层 / 56 条）

全局参数：-p/--rpc-portal（默认 127.0.0.1:15888）、-v/--verbose、-o/--output table|json、--no-trunc、-i/--instance-id、-n/--instance-name——必须写在子命令之前。

8.4 默认端口速查

8.5 官方文档与源码差异汇总（以源码为准）

另：官方参数表未收录但源码存在的参数：--daemon、--check-config、--gen-autocomplete（安装页有提及）、--ipv6-public-addr-provider/-auto/-prefix、--disable-upnp、--enable-udp-broadcast-relay、--socket-mark、--instance-recv-bps-limit、--disable-relay-quic、--enable-relay-foreign-network-quic、--tcp-stun-servers。

8.6 参考来源

源码（commit 164e2db6，本档所有 文件:行号 相对仓库根）：

• easytier/src/core.rs（CLI 参数、合并）、easytier/locales/app.yml（帮助文本）、easytier/src/common/config.rs 与 common/env_parser.rs（加载/变量展开）
• easytier-core/src/config/toml.rs（TOML 模型）、config/mod.rs、config/encryption.rs、config/gateway.rs、config/api_input.rs
• easytier/src/easytier-cli.rs（CLI 子命令）、easytier/src/tunnel/mod.rs（协议 scheme）
• easytier/src/rpc_service/api.rs、easytier-core/src/management/*、easytier-core/src/rpc/*、easytier-proto/proto/*.proto（管理 RPC）
• easytier/src/web_client/mod.rs、easytier-core/src/management/full/web_client.rs、easytier-web/src/main.rs、easytier-web/src/restful/*（配置服务器）

官方文档（easytier.cn，文档仓库 main @ c0660fe2）：

• 配置参数总表：https://easytier.cn/guide/network/configurations.html
• 配置文件：https://easytier.cn/guide/network/config-file.html
• 快速组网 / 去中心组网 / 子网代理 / KCP 代理 / 安全模式 / 搭建共享节点 / P2P 优化 / 魔法 DNS / SOCKS5 / 无 TUN / WireGuard 接入 / Web 控制台 / ACL / 安装 / FAQ（各专题页 URL 见官方侧边栏）