fix(hole-punch): retain candidate reuse and prediction budgets

Remove the unconditional easy-symmetric array reset so retries reuse the
existing 84-socket pool. Keep refilling consumed slots to avoid
permanent depletion after failed transport admission.

Preserve the predictable scan budget for multiple public IPs instead of
multiplying it by address count. Defer prediction freshness and coverage
changes until they can be addressed within the existing pressure limits.

Verify that two failed easy-symmetric attempts reuse all candidates,
that consumed candidates still recover, and that a 50-target prediction
budget with two public IPs retains the original 300-datagram total.

.cargo/config

@@ -1,7 +0,0 @@
-[target.aarch64-unknown-linux-gnu]
-linker = "aarch64-linux-gnu-gcc"
-[target.aarch64-unknown-linux-musl]
-linker = "aarch64-linux-musl-gcc"
-rustflags = ["-C", "target-feature=+crt-static"]
-[target.'cfg(all(windows, target_env = "msvc"))']
-rustflags = ["-C", "target-feature=+crt-static"]

.cargo/config.toml

@@ -0,0 +1,96 @@
+# region Native
+
+[target.x86_64-unknown-linux-gnu]
+rustflags = ["-C", "link-arg=-fuse-ld=mold"]
+
+[target.aarch64-unknown-linux-gnu]
+rustflags = ["-C", "link-arg=-fuse-ld=mold"]
+
+[target.'cfg(all(windows, target_env = "msvc"))']
+rustflags = ["-C", "target-feature=+crt-static"]
+
+[target.wasm32-unknown-unknown]
+rustflags = [
+    "-C",
+    "opt-level=z",
+    "--cfg",
+    'getrandom_backend="wasm_js"',
+]
+
+# region
+
+# region CI
+
+[target.x86_64-unknown-linux-musl]
+rustflags = ["-C", "target-feature=+crt-static"]
+
+[target.aarch64-unknown-linux-musl]
+rustflags = ["-C", "target-feature=+crt-static"]
+
+[target.riscv64gc-unknown-linux-musl]
+rustflags = ["-C", "target-feature=+crt-static"]
+
+[target.armv7-unknown-linux-musleabihf]
+rustflags = ["-C", "target-feature=+crt-static"]
+
+[target.armv7-unknown-linux-musleabi]
+rustflags = ["-C", "target-feature=+crt-static"]
+
+[target.arm-unknown-linux-musleabihf]
+rustflags = ["-C", "target-feature=+crt-static"]
+
+[target.arm-unknown-linux-musleabi]
+rustflags = ["-C", "target-feature=+crt-static"]
+
+[target.loongarch64-unknown-linux-musl]
+rustflags = ["-C", "target-feature=+crt-static"]
+
+[target.mipsel-unknown-linux-musl]
+linker = "mipsel-unknown-linux-muslsf-gcc"
+rustflags = [
+    "-C",
+    "target-feature=+crt-static",
+    "-L",
+    "./musl_gcc/mipsel-unknown-linux-muslsf/mipsel-unknown-linux-muslsf/lib",
+    "-L",
+    "./musl_gcc/mipsel-unknown-linux-muslsf/mipsel-unknown-linux-muslsf/sysroot/usr/lib",
+    "-L",
+    "./musl_gcc/mipsel-unknown-linux-muslsf/lib/gcc/mipsel-unknown-linux-muslsf/15.1.0",
+    "-l",
+    "atomic",
+    "-l",
+    "ctz",
+    "-l",
+    "gcc",
+]
+
+[target.mips-unknown-linux-musl]
+linker = "mips-unknown-linux-muslsf-gcc"
+rustflags = [
+    "-C",
+    "target-feature=+crt-static",
+    "-L",
+    "./musl_gcc/mips-unknown-linux-muslsf/mips-unknown-linux-muslsf/lib",
+    "-L",
+    "./musl_gcc/mips-unknown-linux-muslsf/mips-unknown-linux-muslsf/sysroot/usr/lib",
+    "-L",
+    "./musl_gcc/mips-unknown-linux-muslsf/lib/gcc/mips-unknown-linux-muslsf/15.1.0",
+    "-l",
+    "atomic",
+    "-l",
+    "ctz",
+    "-l",
+    "gcc",
+]
+
+[target.aarch64-unknown-linux-ohos]
+ar = "/usr/local/ohos-sdk/linux/native/llvm/bin/llvm-ar"
+linker = "/home/runner/sdk/native/llvm/aarch64-unknown-linux-ohos-clang.sh"
+
+[target.aarch64-unknown-linux-ohos.env]
+PKG_CONFIG_PATH = "/usr/local/ohos-sdk/linux/native/sysroot/usr/lib/pkgconfig:/usr/local/ohos-sdk/linux/native/sysroot/usr/local/lib/pkgconfig"
+PKG_CONFIG_LIBDIR = "/usr/local/ohos-sdk/linux/native/sysroot/usr/lib:/usr/local/ohos-sdk/linux/native/sysroot/usr/local/lib"
+PKG_CONFIG_SYSROOT_DIR = "/usr/local/ohos-sdk/linux/native/sysroot"
+SYSROOT = "/usr/local/ohos-sdk/linux/native/sysroot"
+
+# endregion

.config/nextest.toml

@@ -0,0 +1,31 @@
+[profile.default]
+slow-timeout = { period = "60s", terminate-after = 1 }
+
+[profile.default.junit]
+path = "junit.xml"
+
+[profile.ci]
+test-threads = 32
+
+[test-groups.subnet-proxy]
+max-threads = 8
+
+[[profile.default.overrides]]
+filter = 'test(tests::three_node::subnet_proxy_three_node_test)'
+test-group = 'subnet-proxy'
+
+# These tests modify or inspect host-wide interfaces, routes, or BPF state.
+# They must exclude all other tests, including the isolated network fixtures.
+# Foreign-network listener discovery also enumerates the default namespace.
+# Run exclusive tests first so the parallel pool does not repeatedly drain.
+[[profile.default.overrides]]
+filter = 'test(tests::upnp_test) | test(common::ifcfg::netlink::tests) | test(instance::public_ipv6_provider::platform::tests) | test(instance::dns_server::tests) | test(socket::fake_tcp::netfilter::linux_bpf::tests) | test(tests::three_node::foreign_network_advertises_listeners_for_direct_connect)'
+threads-required = 'num-test-threads'
+priority = 100
+
+# These assertions require a reply within 100 ms, on the first ping, or a
+# minimum measured throughput. Competing tests can delay packet processing.
+[[profile.default.overrides]]
+filter = 'test(tests::three_node::p2p_only_test) | test(tests::three_node::relay_peer_e2e_encryption) | test(tests::three_node::whitelist_test) | test(relay_bps_limit_test) | test(instance_recv_bps_limit_test)'
+threads-required = 'num-test-threads'
+priority = 100

.envrc

@@ -0,0 +1,2 @@
+PROFILE=$(cat .flake-profile 2>/dev/null)
+use flake .#${PROFILE}

.gitattributes

@@ -0,0 +1 @@
+*.sh text eol=lf

.github/CI.md

@@ -0,0 +1,82 @@
+# CI
+
+[中文](CI.zh-CN.md)
+
+| Trigger | Core | GUI | Mobile |
+| --- | --- | --- | --- |
+| PR targeting `main`/`develop`, or push to either branch | Core/Web `cargo check`: Linux x64, Windows x64, macOS ARM64 | Linux frontend build and Rust check | Android ARM64 frontend build and Rust check |
+| Push to `releases/**`, or manual dispatch | 16 targets and Magisk artifacts | Installers for 7 targets | APKs for 4 architectures |
+
+Test runs CI script tests, fmt, clippy, WASI, Cargo.lock validation, and
+Linux tests for `easytier`/`easytier-core`, including `three_node`. Full mode
+also checks each `easytier` feature except `macos-ne`.
+
+Linux tests run on one runner with 32 concurrent nextest processes. Network
+integration tests use separate namespaces and bridges for each test. Subnet
+proxy cases run at most eight at a time. Tests that use host-wide network state,
+measure bandwidth, or make time-sensitive connectivity assertions run first,
+exclusively, before the parallel tests.
+
+These four workflows skip build/test jobs for draft PRs. Path and duplicate
+content checks can skip ordinary builds and Rust jobs. The result jobs are
+`core-result`, `gui-result`, `mobile-result`, and `test`.
+
+PR dashboard builds run only for frontend, Core configuration, schema, or
+build configuration changes. Ordinary branch pushes build the dashboard.
+Core checks run independently; Web embedding is compiled only in full mode.
+Test skips the frontend build in ordinary mode; its test archive builds
+only Rust packages.
+
+PR runs can upload the test archive for reuse within CI. The dashboard is
+uploaded only in full mode.
+Core binaries, GUI installers, APKs, and Magisk artifacts require full mode.
+Compilation outputs are cached. Ordinary pushes do not cancel full builds.
+
+## Nightly
+
+Scheduled at 03:17 Asia/Shanghai, or started manually on `main`. Check Core,
+GUI, Mobile, and Test separately. Compare main HEAD with that workflow's latest
+successful `workflow_dispatch` run: skip matching commits; dispatch otherwise.
+Core's `sign_windows` is set to `false` for nightly builds.
+
+Nightly waits for the dispatched runs, retrying failed jobs once. A second
+failure or a cancelled run fails Nightly and prevents publication. The build
+and wait job has a three-hour timeout. Once all four components succeed at the
+same commit, Nightly updates the rolling `nightly` prerelease using that commit,
+even if main advances while builds are running. If main changes between the
+dispatch requests and the builds target different commits, Nightly fails and
+must be started again.
+
+Builds dispatched with `GITHUB_TOKEN` do not trigger downstream `workflow_run`
+jobs, so scheduled publication and retries run directly in Nightly. Completion
+events still handle full main builds dispatched manually by a maintainer.
+Nightly Release can also be started manually to publish existing main HEAD
+builds without rebuilding them.
+
+Nightly uses the same asset names and archive layout as version releases.
+Core, Web, and Magisk ZIP names include the built commit's version (for example,
+`easytier-linux-x86_64-v2.7.0.zip`). GUI installers and Android APKs retain their
+original filenames without an extra ZIP wrapper. `SHA256SUMS` covers every
+download. Asset URLs can change when the project version changes; use the
+fixed `nightly` release page to find the current files.
+
+## Manual builds and releases
+
+Repository Write access is required. In Actions, run Core, GUI, and Mobile
+separately on the PR branch to obtain full artifacts. The branch must contain
+these workflow definitions. Fork PRs need a temporary branch in this repository.
+
+Manual Core builds default to SignPath test signing (`sign_windows: true`).
+Full macOS GUI builds are signed and notarized.
+
+Release is a separate manual workflow. Its Core/GUI/Mobile run IDs must refer
+to successful full builds from their respective workflows at the same commit.
+It downloads their artifacts and creates a draft release.
+
+## Other workflows
+
+- OHOS runs independently. Relevant PRs run bridge tests and check the bindings
+  for the host and ARM64 OHOS. Non-PR runs build and upload HAR artifacts;
+  publishing and downstream builds retain their existing main/manual conditions.
+- Go, JavaScript Hosts, and Nix use their own path filters.
+- Docker is manual; it downloads a specified Core run's artifacts and pushes images.

.github/CI.zh-CN.md

@@ -0,0 +1,73 @@
+# CI
+
+[English](CI.md)
+
+| 触发方式 | Core | GUI | Mobile |
+| --- | --- | --- | --- |
+| 目标为 `main`/`develop` 的 PR，或 push 到这两个分支 | Linux x64、Windows x64、macOS ARM64 的 Core/Web `cargo check` | Linux 前端构建和 Rust 检查 | Android ARM64 前端构建和 Rust 检查 |
+| Push 到 `releases/**`，或手动触发 | 16 个目标和 Magisk 产物 | 7 个目标的安装包 | 4 个架构的 APK |
+
+Test 运行 CI 脚本测试、fmt、clippy、WASI、Cargo.lock 检查，以及
+`easytier`/`easytier-core` 的 Linux 测试（含 `three_node`）。全量模式还逐个
+检查 `easytier` 的 feature，排除 `macos-ne`。
+
+Linux 测试使用一个 runner，nextest 总并发度为 32。网络集成测试为每个测试
+创建独立的 namespace 和网桥。子网代理用例最多同时运行八个；带宽测试、
+使用宿主机全局网络状态的测试和时间敏感的连通性测试优先独占
+执行，完成后再运行并发测试。
+
+这四个 workflow 的构建和测试任务跳过 draft PR。普通构建和 Rust 任务可因
+无关路径或重复内容而跳过。汇总检查为 `core-result`、`gui-result`、
+`mobile-result` 和 `test`。
+
+PR 仅在前端、Core 配置源码、schema 或构建配置变化时构建 Web 前端。
+普通分支 push 仍构建 Web 前端。Core 检查独立运行；Web 的嵌入模式仅在
+全量构建中编译。
+Test 在普通模式下跳过前端构建，测试归档仅构建 Rust 包。
+
+PR 可上传供 CI 内部复用的测试归档。Web 前端仅在全量模式上传。
+Core 二进制、GUI 安装包、APK 和 Magisk 产物仅在全量模式上传。编译产物
+启用缓存。普通 push 不会取消全量构建。
+
+## 每日构建
+
+定时为北京时间 03:17，也可以在 `main` 上手动运行。分别检查 Core、GUI、
+Mobile、Test：比较 main HEAD 与该 workflow 最近一次成功的
+`workflow_dispatch` 提交，相同则跳过，不同或无成功记录则触发该 workflow。
+每日 Core 构建设置 `sign_windows: false`。
+
+Nightly 等待已触发的构建结束，失败任务自动重试一次。再次失败或取消会使
+Nightly 失败并阻止发布，构建和等待任务的超时为三小时。四个组件在同一提交
+上全部成功后，Nightly 使用该提交更新固定的 `nightly` 预发布版本，即使等待
+期间 main 已有新提交。如果 main 在各次触发请求之间变化，导致构建提交不
+一致，Nightly 会失败，需要重新运行。
+
+`GITHUB_TOKEN` 触发的构建不会触发下游 `workflow_run` 任务，因此定时构建的
+发布和重试直接由 Nightly 执行。维护者手动触发的 main 全量构建仍由完成事件
+处理。也可手动运行 Nightly Release，使用 main HEAD 的现有成功构建直接发布。
+
+Nightly 的产物名称和压缩包目录结构与版本发布保持一致。Core、Web 和 Magisk
+ZIP 文件名包含构建提交中的版本号，例如 `easytier-linux-x86_64-v2.7.0.zip`。
+GUI 安装包和 Android APK 保留原始文件名，不再套一层 ZIP。`SHA256SUMS`
+包含所有下载文件的校验值。项目版本变化时产物下载地址也会变化，可通过固定的
+`nightly` 发布页面查找当前文件。
+
+## 手动构建与发布
+
+需要仓库 Write 权限。在 Actions 分别运行 Core、GUI、Mobile，选择 PR 分支
+即可生成全量产物。该分支必须包含这些 workflow 定义。Fork PR 需要先在本
+仓库建立临时分支。
+
+手动 Core 构建默认开启 SignPath 测试签名（`sign_windows: true`）。
+全量 macOS GUI 构建会签名和公证。
+
+Release 是独立的手动 workflow。输入的 Core/GUI/Mobile run ID 必须分别来自
+正确的 workflow、全量构建成功，且提交相同。它下载这些产物并创建 draft
+release。
+
+## 其他 workflow
+
+- OHOS 独立运行。相关 PR 运行桥接单测，并检查宿主平台和 ARM64 OHOS 的绑定。
+  非 PR 构建生成并上传 HAR；发布和下游构建仍按原有主线/手动触发条件执行。
+- Go、JavaScript Hosts、Nix 使用各自的路径过滤。
+- Docker 手动触发，下载指定 Core 构建的产物并推送镜像。

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,135 @@
+# Copyright 2024-present Easytier Programme within The Commons Conservancy
+# SPDX-License-Identifier: Apache-2.0
+
+name: 🐞 问题报告 / Bug Report
+title: '[bug] '
+description: 报告一个问题 / Report a bug
+labels: ['type: bug', 'status: needs triage']
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## 在提交问题之前 / First of all
+        1. 请先搜索有关此问题的 [现有问题](https://github.com/EasyTier/EasyTier/issues?q=is%3Aissue)。
+        1. Please search for [existing issues](https://github.com/EasyTier/EasyTier/issues?q=is%3Aissue) about this problem first.
+        2. 请确保所使用的 Easytier 版本都是最新的。
+        2. Make sure that all Easytier versions are up-to-date.
+        3. 请确保这是 EasyTier 的问题，而不是你正在使用的其他内容引起的问题。
+        3. Make sure it's an issue with EasyTier and not something else you are using.
+        4. 请记得遵守我们的社区准则并保持友好态度。
+        4. Remember to follow our community guidelines and be friendly.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: 问题简要描述 / Brief Description
+      description: 对问题的简要描述，包括期望的行为和实际发生的情况。 / A brief description of the issue, including expected vs actual behavior.
+      placeholder: |
+        例如：节点 A 无法连接到节点 B，期望能够正常建立连接
+        Example: Node A cannot connect to Node B, expected to establish connection normally
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment-info
+    attributes:
+      label: 环境信息 / Environment Information
+      description: 请提供网络拓扑、节点信息和系统环境详情。 / Please provide network topology, node information and system environment details.
+      placeholder: |
+        **EasyTier 版本（非常重要）/ EasyTier Version (Very Important):** v1.2.0
+        
+        **网络拓扑 / Network Topology:**
+        - 节点 A (10.1.1.1): Windows 11 Pro 22H2, Wifi，有 IPV6 地址
+        - 节点 B (10.1.1.2): Ubuntu 22.04.3 LTS (Linux 5.15.0-72-generic), 公网 IP
+        - 节点 C (10.1.1.3): macOS Ventura 13.4.1, 5G 流量，无 IPV6 地址
+        
+        **Network Topology:**
+        - Node A (10.1.1.1): Windows 11 Pro 22H2, Wifi, has IPV6 address
+        - Node B (10.1.1.2): Ubuntu 22.04.3 LTS (Linux 5.15.0-72-generic), public IP
+        - Node C (10.1.1.3): macOS Ventura 13.4.1, 5G traffic, no IPV6 address
+    validations:
+      required: true
+
+  - type: textarea
+    id: node-configs
+    attributes:
+      label: 节点配置 / Node Configurations
+      description: 请提供每个节点的配置文件或启动参数。 / Please provide configuration files or startup parameters for each node.
+      placeholder: |
+        **节点 A 配置 / Node A Config:**
+        ```
+        easytier-core --config-file config.toml
+        ```
+        
+        **节点 B 配置 / Node B Config:**
+        ```
+        easytier-core --ipv4 10.1.1.2 --peers tcp://1.2.3.4:11010
+        ```
+        
+        请贴出完整的配置文件内容或命令行参数
+        Please paste complete configuration file contents or command line arguments
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: 日志信息 / Log Information
+      description: 请提供相关的日志信息，包括 GUI 的事件日志或命令行的控制台输出。 / Please provide relevant log information, including GUI event logs or command line console output.
+      placeholder: |
+        请粘贴相关的日志信息：
+        - GUI 用户：请提供事件日志中的错误信息
+        - 命令行用户：请提供控制台输出的详细日志
+        - 一般情况下，提供默认输出的事件日志即可
+        - 如果能提供 --file-log-level debug 输出的日志，会更方便 debug
+        
+        Please paste relevant log information:
+        - GUI users: Please provide error messages from event logs
+        - CLI users: Please provide detailed console output logs
+        - Default log output is usually sufficient
+        - If possible, logs with --file-log-level debug would be more helpful for debugging
+        
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: 重现步骤 / Reproduction Steps
+      description: 请提供详细的步骤来重现这个问题。 / Please provide detailed steps to reproduce this issue.
+      placeholder: |
+        1. 启动节点 A，使用配置 xxx / Start Node A with config xxx
+        2. 启动节点 B，使用配置 yyy / Start Node B with config yyy  
+        3. 尝试从节点 A ping 节点 B / Try to ping Node B from Node A
+        4. 观察到错误：xxx / Observe error: xxx
+        
+        请提供详细的操作步骤，以便我们能够重现问题
+        Please provide detailed steps so we can reproduce the issue
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: 预期结果 / Expected Behavior
+      description: 清楚地描述您期望发生的事情。 / A clear description of what you expected to happen.
+      placeholder: |
+        例如：节点 A 应该能够成功 ping 通节点 B，延迟在 100ms 以内
+        Example: Node A should be able to ping Node B successfully with latency under 100ms
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: 额外信息 / Additional Context
+      description: 在这里添加关于问题的任何其他上下文信息。 / Add any other context about the problem here.
+      placeholder: |
+        例如：
+        - 这个问题是否在特定时间出现？
+        - 是否有网络环境的特殊配置？
+        - 是否尝试过其他解决方案？
+        
+        Example:
+        - Does this issue occur at specific times?
+        - Are there any special network environment configurations?
+        - Have you tried any other solutions?

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,179 @@
+# Copyright 2024-present Easytier Programme within The Commons Conservancy
+# SPDX-License-Identifier: Apache-2.0
+
+name: 💡 新功能请求 / Feature Request
+title: '[feat] '
+description: 提出一个想法 / Suggest an idea
+labels: ['type: feature request']
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## 提交功能请求前请注意 / Before Submitting
+        1. 请先搜索 [现有的功能请求](https://github.com/EasyTier/EasyTier/issues?q=is%3Aissue+label%3A%22type%3A+feature+request%22) 确保您的想法尚未被提出。
+        1. Please search [existing feature requests](https://github.com/EasyTier/EasyTier/issues?q=is%3Aissue+label%3A%22type%3A+feature+request%22) to ensure your idea hasn't been suggested already.
+        2. 请确保这个功能确实适合 EasyTier 项目的目标和范围。
+        2. Please ensure this feature fits within EasyTier's goals and scope.
+        3. 考虑这个功能是否能让更多用户受益，而不只是解决个人需求。
+        3. Consider whether this feature would benefit many users, not just personal needs.
+
+  - type: dropdown
+    id: feature-category
+    attributes:
+      label: 功能类别 / Feature Category
+      description: 请选择这个功能请求属于哪个类别 / Please select which category this feature request belongs to
+      options:
+        - 网络连接 / Network Connectivity
+        - 安全和加密 / Security & Encryption  
+        - 性能优化 / Performance Optimization
+        - 用户界面 / User Interface
+        - 配置管理 / Configuration Management
+        - 监控和日志 / Monitoring & Logging
+        - 平台支持 / Platform Support
+        - API 和集成 / API & Integration
+        - 其他 / Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: 使用场景 / Use Case
+      description: 描述您希望这个功能解决的具体使用场景或问题 / Describe the specific use case or problem you want this feature to solve
+      placeholder: |
+        例如：
+        - 作为企业用户，我需要在多个分支机构之间建立安全的网络连接
+        - 作为开发者，我希望能够通过 API 监控网络状态
+        - 作为系统管理员，我需要更详细的连接日志来排查问题
+        
+        Example:
+        - As an enterprise user, I need to establish secure network connections between multiple branch offices
+        - As a developer, I want to monitor network status through APIs
+        - As a system administrator, I need more detailed connection logs for troubleshooting
+    validations:
+      required: true
+
+  - type: textarea
+    id: current-limitations
+    attributes:
+      label: 当前限制 / Current Limitations
+      description: 描述当前 EasyTier 的哪些限制阻止了您实现这个使用场景 / Describe what current limitations in EasyTier prevent you from achieving this use case
+      placeholder: |
+        例如：
+        - 目前不支持基于用户角色的访问控制
+        - 缺少对 IPv6 的完整支持
+        - 没有提供 REST API 来获取网络状态
+        
+        Example:
+        - Currently lacks role-based access control
+        - Missing complete IPv6 support
+        - No REST API available for network status
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-solution
+    attributes:
+      label: 建议的解决方案 / Proposed Solution
+      description: 详细描述您希望添加的功能以及它应该如何工作 / Describe in detail the feature you'd like to add and how it should work
+      placeholder: |
+        请描述：
+        - 功能的具体实现方式
+        - 用户界面或 API 设计
+        - 配置选项和参数
+        - 与现有功能的集成方式
+        
+        Please describe:
+        - Specific implementation approach
+        - User interface or API design
+        - Configuration options and parameters  
+        - Integration with existing features
+    validations:
+      required: true
+
+  - type: textarea
+    id: benefits
+    attributes:
+      label: 预期收益 / Expected Benefits
+      description: 说明这个功能会带来什么好处，会影响哪些用户群体 / Explain what benefits this feature would bring and which user groups it would affect
+      placeholder: |
+        例如：
+        - 提高网络连接的稳定性和性能
+        - 简化大规模部署的管理复杂度
+        - 增强企业用户的安全性需求
+        - 降低新用户的学习成本
+        
+        Example:
+        - Improve network connection stability and performance
+        - Simplify management complexity for large-scale deployments
+        - Enhance security requirements for enterprise users
+        - Reduce learning curve for new users
+
+  - type: textarea
+    id: technical-considerations
+    attributes:
+      label: 技术考虑 / Technical Considerations
+      description: 如果您了解技术细节，请分享相关的技术考虑或约束 / If you have technical knowledge, please share relevant technical considerations or constraints
+      placeholder: |
+        例如：
+        - 可能需要修改网络协议栈
+        - 需要考虑跨平台兼容性
+        - 可能影响现有性能
+        - 依赖第三方库或协议
+        
+        Example:
+        - May require modifications to network protocol stack
+        - Cross-platform compatibility needs consideration
+        - Potential impact on existing performance
+        - Dependencies on third-party libraries or protocols
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: 备选方案 / Alternative Solutions
+      description: 您是否考虑过其他解决方案？是否有现有的替代方案？ / Have you considered other solutions? Are there existing alternatives?
+      placeholder: |
+        例如：
+        - 使用第三方工具 X 可以部分解决，但缺少 Y 功能
+        - 通过脚本workaround可以实现，但不够优雅
+        - 其他类似项目 Z 有这个功能，可以参考其实现
+        
+        Example:
+        - Third-party tool X can partially solve this, but lacks Y functionality
+        - Can be achieved through script workarounds, but not elegant
+        - Similar project Z has this feature, could reference its implementation
+
+  - type: textarea
+    id: implementation-priority
+    attributes:
+      label: 实现优先级 / Implementation Priority
+      description: 这个功能对您有多重要？是否有时间要求？ / How important is this feature to you? Any time requirements?
+      placeholder: |
+        例如：
+        - 高优先级：阻碍了我们的生产部署
+        - 中优先级：会显著改善用户体验
+        - 低优先级：锦上添花的功能
+        
+        Example:
+        - High priority: Blocking our production deployment
+        - Medium priority: Would significantly improve user experience
+        - Low priority: Nice-to-have feature
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: 补充信息 / Additional Context
+      description: 添加任何其他相关信息，如截图、链接、参考资料等 / Add any other relevant information such as screenshots, links, or references
+      placeholder: |
+        例如：
+        - 相关的 RFC 或技术规范
+        - 其他项目的实现示例
+        - 用户调研或反馈数据
+        - 设计草图或流程图
+        
+        Example:
+        - Relevant RFCs or technical specifications
+        - Implementation examples from other projects
+        - User research or feedback data
+        - Design sketches or flowcharts

.github/SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+[简体中文](SECURITY.zh-CN.md) | English
+
+## Supported Versions
+
+Security updates are provided for the latest EasyTier release. Before reporting a vulnerability, please verify it against the latest release or the current `main` branch when practical.
+
+| Version | Supported |
+| --- | --- |
+| Latest release | Yes |
+| Older releases | No |
+
+## Reporting a Vulnerability
+
+Please report suspected vulnerabilities through GitHub's [private vulnerability reporting form](https://github.com/EasyTier/EasyTier/security/advisories/new).
+
+Do not disclose the vulnerability in a public issue, discussion, or pull request. A useful report should include:
+
+- the affected EasyTier version or commit;
+- the affected platform and relevant configuration, with secrets removed;
+- a description of the vulnerability and its potential impact;
+- reproducible steps or a minimal proof of concept; and
+- any known mitigations or workarounds.
+
+The maintainers will assess the report and coordinate remediation and disclosure through the private advisory. Please allow reasonable time for a fix before publishing details.
+
+When investigating, avoid accessing or modifying other users' data, disrupting services, or violating applicable laws.

.github/SECURITY.zh-CN.md

@@ -0,0 +1,28 @@
+# 安全策略
+
+简体中文 | [English](SECURITY.md)
+
+## 支持的版本
+
+EasyTier 仅为最新正式版本提供安全更新。报告漏洞前，请尽可能在最新正式版本或当前 `main` 分支上确认问题仍然存在。
+
+| 版本 | 是否支持 |
+| --- | --- |
+| 最新正式版本 | 是 |
+| 更早版本 | 否 |
+
+## 报告安全漏洞
+
+请通过 GitHub 的[私有漏洞报告表单](https://github.com/EasyTier/EasyTier/security/advisories/new)报告疑似安全漏洞。
+
+请勿在公开 Issue、Discussion 或 Pull Request 中披露漏洞。一份有效的报告应包括：
+
+- 受影响的 EasyTier 版本或提交；
+- 受影响的平台和相关配置，请移除其中的密钥等敏感信息；
+- 漏洞说明及其潜在影响；
+- 可复现的步骤或最小概念验证；
+- 已知的缓解措施或临时解决方案。
+
+维护者将评估报告，并通过私有安全公告协调修复和披露。请在公开漏洞详情前为修复预留合理时间。
+
+调查漏洞时，请勿访问或修改其他用户的数据、干扰服务或违反适用的法律法规。

.github/actions/prepare-build/action.yml

@@ -0,0 +1,98 @@
+name: prepare-build
+author: Luna
+description: Prepare build environment
+inputs:
+  target:
+    description: 'The target to build for'
+    required: false
+  pnpm:
+    description: 'Whether to run pnpm build'
+    required: true
+    default: 'true'
+  pnpm-build-filter:
+    description: 'The filter argument for pnpm build (e.g. ./easytier-web/*)'
+    required: false
+    default: './easytier-web/*'
+  gui:
+    description: 'Whether to prepare the GUI build environment'
+    required: true
+    default: 'true'
+  token:
+    description: 'GitHub token, used by setup-protoc action'
+    required: false
+runs:
+  using: 'composite'
+  steps:
+    - run: mkdir -p easytier-gui/dist
+      shell: bash
+
+    - name: Install dependencies
+      if: ${{ runner.os == 'Linux' }}
+      run: |
+        sudo apt-get update
+        sudo apt-get install -qqy build-essential mold musl-tools
+      shell: bash
+
+    - name: Setup protoc
+      uses: arduino/setup-protoc@v3
+      with:
+        version: '35.1'
+        # GitHub repo token to use to avoid rate limiter
+        repo-token: ${{ inputs.token }}
+
+    - name: Verify protoc version
+      run: |
+        version="$(protoc --version | tr -d '\r')"
+        test "$version" = "libprotoc 35.1"
+      shell: bash
+
+    - name: Setup Frontend Environment
+      if: ${{ inputs.pnpm == 'true' }}
+      uses: ./.github/actions/prepare-pnpm
+      with:
+        token: ${{ inputs.token }}
+        build-filter: ${{ inputs.pnpm-build-filter }}
+
+    - name: Install GUI dependencies (Linux)
+      if: ${{ inputs.gui == 'true' && runner.os == 'Linux' }}
+      run: |
+        sudo apt-get install -qq xdg-utils \
+        libappindicator3-dev \
+        libgtk-3-dev \
+        librsvg2-dev \
+        libwebkit2gtk-4.1-dev \
+        libxdo-dev
+      shell: bash
+
+    - uses: actions-rust-lang/setup-rust-toolchain@v1
+      with:
+        toolchain: 1.95
+        target: ${{ !contains(inputs.target, 'mips') && inputs.target || '' }}
+        components: ${{ contains(inputs.target, 'mips') && 'rust-src' || '' }}
+        cache: false
+        rustflags: ''
+
+    - name: Install Rust (MIPS)
+      if: ${{ contains(inputs.target, 'mips') }}
+      run: |
+        MUSL_TARGET=${{ inputs.target }}sf
+        mkdir -p ./musl_gcc
+        wget --inet4-only -c https://github.com/cross-tools/musl-cross/releases/download/20250520/${MUSL_TARGET}.tar.xz -P ./musl_gcc/
+        tar xf ./musl_gcc/${MUSL_TARGET}.tar.xz -C ./musl_gcc/
+        sudo ln -sf $(pwd)/musl_gcc/${MUSL_TARGET}/bin/*gcc /usr/bin/
+        sudo ln -sf $(pwd)/musl_gcc/${MUSL_TARGET}/include/ /usr/include/musl-cross
+        sudo ln -sf $(pwd)/musl_gcc/${MUSL_TARGET}/${MUSL_TARGET}/sysroot/ ./musl_gcc/sysroot
+        sudo chmod -R a+rwx ./musl_gcc
+
+        if [[ -d "./musl_gcc/sysroot" ]]; then
+          echo "BINDGEN_EXTRA_CLANG_ARGS=--sysroot=$(readlink -f ./musl_gcc/sysroot)" >> $GITHUB_ENV
+        fi
+
+        cd "$PWD/musl_gcc/${MUSL_TARGET}/lib/gcc/${MUSL_TARGET}/15.1.0" || exit 255
+        # for panic-abort
+        cp libgcc_eh.a libunwind.a
+        
+        # for mimalloc
+        ar x libgcc.a _ctzsi2.o _clz.o _bswapsi2.o
+        ar rcs libctz.a _ctzsi2.o _clz.o _bswapsi2.o
+      shell: bash

.github/actions/prepare-pnpm/action.yml

@@ -0,0 +1,75 @@
+name: 'Setup pnpm'
+author: Luna
+description: 'Setup Node.js, pnpm, and install dependencies'
+
+inputs:
+  token:
+    description: 'GitHub token, used by setup-protoc action'
+    required: false
+  build-filter:
+    description: 'The filter argument for pnpm build (e.g. ./easytier-web/*)'
+    required: false
+    default: ''
+
+runs:
+  using: "composite"
+  steps:
+    - uses: actions-rust-lang/setup-rust-toolchain@v1
+      with:
+        toolchain: 1.95
+        target: wasm32-unknown-unknown
+        cache: false
+        rustflags: ''
+
+    - uses: taiki-e/install-action@v2
+      with:
+        tool: wasm-pack
+
+    - uses: arduino/setup-protoc@v3
+      with:
+        version: '35.1'
+        repo-token: ${{ inputs.token }}
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v5
+      with:
+        node-version: 22
+
+    - name: Install pnpm
+      uses: pnpm/action-setup@v5
+      with:
+        version: 10
+        run_install: false
+
+    - name: Get pnpm store directory
+      shell: bash
+      run: |
+        echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+    - name: Setup pnpm cache
+      uses: actions/cache@v5
+      with:
+        path: ${{ env.STORE_PATH }}
+        key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+        restore-keys: |
+          ${{ runner.os }}-pnpm-store-
+
+    - name: Install and build
+      shell: bash
+      run: |
+        pnpm -r install
+        if [ -n "${{ inputs.build-filter }}" ]; then
+          echo "Building with filter: ${{ inputs.build-filter }}"
+          pnpm -r --workspace-concurrency=1 --filter "${{ inputs.build-filter }}" build
+        else
+          echo "No build filter provided, building all packages"
+          pnpm -r --workspace-concurrency=1 build
+        fi
+
+    - name: Bundle config generator with web frontend
+      shell: bash
+      run: |
+        if [ -f easytier-web/frontend/dist/index.html ] && [ -f easytier-web/config-generator/dist/index.html ]; then
+          mkdir -p easytier-web/frontend/dist/config-generator
+          cp -R easytier-web/config-generator/dist/. easytier-web/frontend/dist/config-generator/
+        fi

.github/scripts/builds.test.js

@@ -0,0 +1,204 @@
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const dispatch = require('./nightly-build.js');
+const validate = require('./validate-release-builds.js');
+
+const context = { repo: { owner: 'EasyTier', repo: 'EasyTier' } };
+const core = { info() {} };
+const workflows = ['core.yml', 'gui.yml', 'mobile.yml', 'test.yml'];
+
+function nightly(branches, successfulRuns = {}) {
+  const f = { dispatched: [], retried: [], responses: {}, inspected: [], sleeps: 0 };
+  const github = {
+    paginate: async () => branches,
+    rest: {
+      repos: { listBranches() {} },
+      actions: {
+        async listWorkflowRuns(request) {
+          assert.equal(request.event, 'workflow_dispatch');
+          assert.equal(request.status, 'success');
+          const sha = successfulRuns[`${request.branch}/${request.workflow_id}`];
+          return { data: { workflow_runs: sha ? [{ head_sha: sha }] : [] } };
+        },
+        async createWorkflowDispatch(request) {
+          assert.equal(request.headers['X-GitHub-Api-Version'], '2026-03-10');
+          f.dispatched.push(request);
+          return { data: { workflow_run_id: f.dispatched.length, html_url: `run/${f.dispatched.length}` } };
+        },
+        async getWorkflowRun({ run_id }) {
+          const workflow = f.dispatched[run_id - 1].workflow_id;
+          f.inspected.push({ workflow, dispatched: f.dispatched.length });
+          return { data: {
+            head_sha: branches.find(branch => branch.name === 'main').commit.sha,
+            status: 'completed', conclusion: 'success', run_attempt: 1,
+            ...f.responses[workflow]?.shift(),
+          } };
+        },
+        async reRunWorkflowFailedJobs({ run_id }) {
+          f.retried.push(run_id);
+        },
+      },
+    },
+  };
+  f.run = () => dispatch({ github, context, core, sleep: async delay => {
+    assert.equal(delay, 60_000);
+    assert.ok(++f.sleeps < 10, 'nightly should eventually finish');
+  } });
+  return f;
+}
+
+test('first nightly builds every workflow on an existing main branch', async () => {
+  const f = nightly([{ name: 'main', commit: { sha: 'new' } }]);
+  assert.equal(await f.run(), 'new');
+  assert.deepEqual(f.dispatched.map(run => run.workflow_id), workflows);
+  assert.ok(f.dispatched.every(run => run.ref === 'main'));
+  assert.deepEqual(f.dispatched[0].inputs, { sign_windows: false });
+  assert.ok(f.dispatched.slice(1).every(run => !run.inputs));
+  assert.deepEqual(f.inspected.map(run => run.workflow), workflows);
+  assert.ok(f.inspected.every(run => run.dispatched === 4));
+});
+
+test('unchanged branches skip builds and unmonitored branches are ignored', async () => {
+  const successfulRuns = Object.fromEntries(workflows.map(workflow => [`main/${workflow}`, 'same']));
+  const f = nightly([
+    { name: 'main', commit: { sha: 'same' } },
+    { name: 'feature', commit: { sha: 'new' } },
+  ], successfulRuns);
+  assert.equal(await f.run(), 'same');
+  assert.deepEqual(f.dispatched, []);
+  assert.equal(f.sleeps, 0);
+});
+
+test('nightly retries a failed component using its last successful commit', async () => {
+  const successfulRuns = Object.fromEntries(workflows.map(workflow => [`main/${workflow}`, 'new']));
+  successfulRuns['main/gui.yml'] = 'old';
+  const f = nightly([{ name: 'main', commit: { sha: 'new' } }], successfulRuns);
+  assert.equal(await f.run(), 'new');
+  assert.deepEqual(f.dispatched.map(run => run.workflow_id), ['gui.yml']);
+});
+
+test('nightly only builds main even when other branches exist', async () => {
+  const f = nightly([
+    { name: 'main', commit: { sha: 'new' } },
+    { name: 'develop', commit: { sha: 'new' } },
+    { name: 'feature', commit: { sha: 'new' } },
+  ]);
+  await f.run();
+  assert.deepEqual(f.dispatched.map(run => run.workflow_id), workflows);
+  assert.ok(f.dispatched.every(run => run.ref === 'main'));
+});
+
+test('nightly waits for every dispatched build before allowing publication', async () => {
+  const f = nightly([{ name: 'main', commit: { sha: 'new' } }]);
+  f.responses['core.yml'] = [{ status: 'queued' }, { status: 'in_progress' }, {}];
+  f.responses['test.yml'] = [{ status: 'in_progress' }, {}];
+  assert.equal(await f.run(), 'new');
+  assert.equal(f.sleeps, 2);
+  assert.deepEqual(f.inspected.map(run => run.workflow), [
+    ...workflows, 'core.yml', 'test.yml', 'core.yml',
+  ]);
+});
+
+test('nightly retries failed jobs once and waits for the new attempt', async () => {
+  const f = nightly([{ name: 'main', commit: { sha: 'new' } }]);
+  f.responses['gui.yml'] = [
+    { conclusion: 'failure' },
+    { conclusion: 'failure' }, // The API still returns the first attempt.
+    { status: 'in_progress', run_attempt: 2 },
+    { run_attempt: 2 },
+  ];
+  assert.equal(await f.run(), 'new');
+  assert.deepEqual(f.retried, [2]);
+  assert.equal(f.sleeps, 3);
+});
+
+test('nightly fails instead of publishing if a retried build fails again', async () => {
+  const f = nightly([{ name: 'main', commit: { sha: 'new' } }]);
+  f.responses['mobile.yml'] = [{ conclusion: 'failure' }, { conclusion: 'failure', run_attempt: 2 }];
+  await assert.rejects(f.run(), /mobile.yml: run 3 finished with failure/);
+  assert.deepEqual(f.retried, [3]);
+});
+
+test('nightly does not retry cancelled or timed-out builds', async () => {
+  for (const conclusion of ['cancelled', 'timed_out']) {
+    const f = nightly([{ name: 'main', commit: { sha: 'new' } }]);
+    f.responses['test.yml'] = [{ conclusion }];
+    await assert.rejects(f.run(), new RegExp(`test.yml: run 4 finished with ${conclusion}`));
+    assert.deepEqual(f.retried, []);
+  }
+});
+
+test('nightly rejects a dispatch that races with a new main commit', async () => {
+  const f = nightly([{ name: 'main', commit: { sha: 'new' } }]);
+  f.responses['gui.yml'] = [{ head_sha: 'newer', status: 'queued' }];
+  await assert.rejects(f.run(), /main changed while dispatching/);
+  assert.deepEqual(f.retried, []);
+});
+
+process.env.CORE_RUN_ID = '1';
+process.env.GUI_RUN_ID = '2';
+process.env.MOBILE_RUN_ID = '3';
+
+function releaseRuns() {
+  return ['core.yml', 'gui.yml', 'mobile.yml'].map(workflow => ({
+    path: `.github/workflows/${workflow}`,
+    conclusion: 'success',
+    event: 'workflow_dispatch',
+    head_branch: 'main',
+    head_sha: 'same',
+  }));
+}
+
+async function release(runs) {
+  const github = {
+    rest: {
+      actions: {
+        async getWorkflowRun({ run_id }) {
+          return { data: runs[run_id - 1] };
+        },
+      },
+    },
+  };
+  return validate({ github, context, core });
+}
+
+test('release accepts successful full builds from one commit', async () => {
+  await release(releaseRuns());
+});
+
+test('release accepts full builds triggered by a release branch push', async () => {
+  const runs = releaseRuns();
+  runs[0].event = 'push';
+  runs[0].head_branch = 'releases/2.7';
+  runs[1].event = 'push';
+  runs[1].head_branch = 'releases/2.7';
+  await release(runs);
+});
+
+test('release rejects PR builds and regular branch pushes', async () => {
+  for (const event of ['pull_request', 'push']) {
+    const runs = releaseRuns();
+    runs[0].event = event;
+    await assert.rejects(release(runs), /successful full build/);
+  }
+});
+
+test('release rejects failed and cancelled builds', async () => {
+  for (const conclusion of ['failure', 'cancelled']) {
+    const runs = releaseRuns();
+    runs[1].conclusion = conclusion;
+    await assert.rejects(release(runs), /successful full build/);
+  }
+});
+
+test('release rejects run IDs from the wrong workflow', async () => {
+  const runs = releaseRuns();
+  runs[1].path = runs[0].path;
+  await assert.rejects(release(runs), /successful full build/);
+});
+
+test('release rejects builds from different commits', async () => {
+  const runs = releaseRuns();
+  runs[2].head_sha = 'different';
+  await assert.rejects(release(runs), /same commit/);
+});

.github/scripts/nightly-build.js

@@ -0,0 +1,70 @@
+const { setTimeout } = require('node:timers/promises');
+
+module.exports = async ({ github, context, core, sleep = setTimeout }) => {
+  const repository = context.repo;
+  const branches = await github.paginate(github.rest.repos.listBranches, {
+    ...repository,
+    per_page: 100,
+  });
+
+  for (const branch of branches.filter(({ name }) => name === 'main')) {
+    const pending = new Map();
+    for (const workflow of ['core.yml', 'gui.yml', 'mobile.yml', 'test.yml']) {
+      const { data } = await github.rest.actions.listWorkflowRuns({
+        ...repository,
+        workflow_id: workflow,
+        branch: branch.name,
+        event: 'workflow_dispatch',
+        status: 'success',
+        per_page: 1,
+      });
+      if (data.workflow_runs[0]?.head_sha === branch.commit.sha) {
+        core.info(`${workflow}: ${branch.name} is already built successfully.`);
+        continue;
+      }
+
+      const { data: run } = await github.rest.actions.createWorkflowDispatch({
+        ...repository,
+        workflow_id: workflow,
+        ref: branch.name,
+        // This API version returns the dispatched run ID.
+        headers: { 'X-GitHub-Api-Version': '2026-03-10' },
+        ...(workflow === 'core.yml' ? { inputs: { sign_windows: false } } : {}),
+      });
+      pending.set(workflow, { id: run.workflow_run_id, attempt: 1 });
+      core.info(`${workflow}: dispatched ${run.html_url} for ${branch.name}.`);
+    }
+
+    // GITHUB_TOKEN dispatches do not trigger downstream workflow_run jobs.
+    // Wait here so publication and retries do not depend on those events.
+    while (pending.size) {
+      for (const [workflow, build] of pending) {
+        const { data: run } = await github.rest.actions.getWorkflowRun({
+          ...repository, run_id: build.id,
+        });
+        if (run.head_sha !== branch.commit.sha) {
+          throw new Error(`${workflow}: main changed while dispatching; run Nightly again.`);
+        }
+        // A rerun request can return before the new attempt becomes visible.
+        if (run.run_attempt < build.attempt || run.status !== 'completed') continue;
+        if (run.conclusion === 'success') {
+          core.info(`${workflow}: run ${build.id} succeeded.`);
+          pending.delete(workflow);
+        } else if (run.conclusion === 'failure' && run.run_attempt === 1) {
+          await github.rest.actions.reRunWorkflowFailedJobs({
+            ...repository, run_id: build.id,
+          });
+          build.attempt = 2;
+          core.info(`${workflow}: retrying failed jobs in run ${build.id}.`);
+        } else {
+          throw new Error(`${workflow}: run ${build.id} finished with ${run.conclusion}.`);
+        }
+      }
+      if (pending.size) {
+        core.info(`Waiting for ${[...pending.keys()].join(', ')} at ${branch.commit.sha}.`);
+        await sleep(60_000);
+      }
+    }
+    return branch.commit.sha;
+  }
+};

.github/scripts/nightly-release.js

@@ -0,0 +1,241 @@
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+const { createHash } = require('node:crypto');
+const { promisify } = require('node:util');
+
+const exec = promisify(execFile);
+
+const workflows = ['core', 'gui', 'mobile', 'test'];
+
+function releaseNotes(repository, baseline, sha, commits, runs) {
+  const url = `https://github.com/${repository.owner}/${repository.repo}`;
+  const changes = [...commits]
+    .sort((a, b) => Date.parse(b.commit.committer.date) - Date.parse(a.commit.committer.date))
+    .map(commit => {
+      const date = new Date(commit.commit.committer.date).toISOString().slice(0, 10);
+      const subject = commit.commit.message.split('\n')[0];
+      return `- ${date} — ${subject} ([${commit.sha.slice(0, 7)}](${commit.html_url}))`;
+    });
+  return [
+    '# EasyTier Nightly',
+    '',
+    'Development builds from `main`. This prerelease is updated in place. Asset names follow version releases.',
+    '',
+    `Commit: [${sha}](${url}/commit/${sha})`,
+    `Builds: ${runs.map(run => `[${run.name}](${run.html_url})`).join(' · ')}`,
+    '',
+    `## Changes since [${baseline.tag_name}](${baseline.html_url})`,
+    '',
+    'Dates are commit dates in UTC, newest first.',
+    '',
+    ...changes,
+    ...(changes.length ? [] : ['No changes since this version.']),
+    '',
+    `[Full changelog](${url}/compare/${baseline.tag_name}...${sha})`,
+    '',
+  ].join('\n');
+}
+
+async function prepare({ github, context, core, sha }) {
+  const repository = context.repo;
+  const { data: branch } = await github.rest.repos.getBranch({ ...repository, branch: 'main' });
+  sha ||= context.payload.workflow_run?.head_sha || branch.commit.sha;
+  const { data: ancestry } = await github.rest.repos.compareCommitsWithBasehead({
+    ...repository, basehead: `${sha}...${branch.commit.sha}`, per_page: 1,
+  });
+  if (!['ahead', 'identical'].includes(ancestry.status)) {
+    core.info(`${sha} is no longer on main.`);
+    return null;
+  }
+
+  // Listing releases also finds an unfinished draft from the first upload.
+  const releases = await github.paginate(github.rest.repos.listReleases, {
+    ...repository, per_page: 100,
+  });
+  const release = releases.find(item => item.tag_name === 'nightly');
+  if (release?.immutable) throw new Error('The nightly release must allow asset and tag updates.');
+  if (release && !release.draft) {
+    const { data: comparison } = await github.rest.repos.compareCommitsWithBasehead({
+      ...repository, basehead: `nightly...${sha}`, per_page: 1,
+    });
+    if (!['ahead', 'identical'].includes(comparison.status)) {
+      core.info('A newer nightly is already available; skipping this older build.');
+      return null;
+    }
+    if (comparison.status === 'identical' && release.body?.includes(`Commit: [${sha}]`)) {
+      core.info(`${sha} is already published.`);
+      return null;
+    }
+  }
+
+  const runs = [];
+  const artifacts = {};
+  for (const workflow of workflows) {
+    const { data } = await github.rest.actions.listWorkflowRuns({
+      ...repository,
+      workflow_id: `${workflow}.yml`,
+      branch: 'main',
+      head_sha: sha,
+      event: 'workflow_dispatch',
+      status: 'success',
+      per_page: 1,
+    });
+    const run = data.workflow_runs[0];
+    if (!run || run.head_sha !== sha || run.head_branch !== 'main' ||
+        run.event !== 'workflow_dispatch' || run.conclusion !== 'success') {
+      core.info(`Waiting for a successful full ${workflow} build at ${sha}.`);
+      return null;
+    }
+    runs.push(run);
+    if (workflow === 'test') continue;
+    const uploaded = await github.paginate(github.rest.actions.listWorkflowRunArtifacts, {
+      ...repository, run_id: run.id, per_page: 100,
+    });
+    // Reruns can retain same-name artifacts from earlier attempts. Select the
+    // newest ID, matching download-artifact's latest:true lookup.
+    const byName = new Map();
+    for (const artifact of uploaded) {
+      if (!/^(easytier-[\w.-]+|Easytier-Magisk)$/.test(artifact.name)) continue;
+      if (!byName.has(artifact.name) || artifact.id > byName.get(artifact.name).id) {
+        byName.set(artifact.name, artifact);
+      }
+    }
+    const files = [...byName.values()];
+    if (!files.length || files.some(artifact => artifact.expired)) {
+      throw new Error(`${workflow}: build artifacts are missing or expired.`);
+    }
+    artifacts[workflow] = files.map(artifact => ({ id: artifact.id, name: artifact.name }));
+  }
+
+  // Version releases may be published by a maintainer from a bot-created draft,
+  // and may themselves be prereleases. Neither author nor /releases/latest
+  // identifies the last manually published version reliably.
+  const baseline = releases.filter(item => !item.draft && /^v\d+\.\d+\.\d+(?:[-+].*)?$/.test(item.tag_name))
+    .sort((a, b) => Date.parse(b.published_at) - Date.parse(a.published_at))[0];
+  if (!baseline) throw new Error('No published version release found for the nightly changelog.');
+  const commits = await github.paginate(github.rest.repos.compareCommitsWithBasehead, {
+    ...repository, basehead: `${baseline.tag_name}...${sha}`, per_page: 100,
+  }, response => response.data.commits);
+  const { data: config } = await github.rest.repos.getContent({
+    ...repository, path: 'easytier-gui/src-tauri/tauri.conf.json', ref: sha,
+  });
+  const { version } = JSON.parse(Buffer.from(config.content, 'base64').toString('utf8'));
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version)) {
+    throw new Error('The build must declare a valid release version.');
+  }
+
+  return {
+    sha,
+    version: `v${version}`,
+    release_id: release?.id,
+    runs: Object.fromEntries(workflows.map((workflow, index) => [workflow, runs[index].id])),
+    artifacts,
+    body: releaseNotes(repository, baseline, sha, commits, runs),
+  };
+}
+
+async function packageAssets({ build, source, directory }) {
+  directory = path.resolve(directory);
+  await fs.mkdir(directory);
+  const assets = [];
+  for (const [workflow, artifacts] of Object.entries(build.artifacts)) {
+    for (const artifact of artifacts) {
+      const artifactPath = path.resolve(source, artifact.name);
+      const files = [];
+      for (const file of await fs.readdir(artifactPath, { recursive: true })) {
+        if ((await fs.stat(path.join(artifactPath, file))).isFile()) files.push(file);
+      }
+      if (!files.length) throw new Error(`Empty artifact: ${artifact.name}`);
+      if (workflow === 'core') {
+        const name = `${artifact.name}-${build.version}.zip`;
+        await exec('chmod', ['-R', '755', artifactPath]);
+        // Match release.yml: only Magisk has its files at the ZIP root.
+        const magisk = artifact.name === 'Easytier-Magisk';
+        await exec('zip', ['-qr', path.join(directory, name), magisk ? '.' : artifact.name], {
+          cwd: magisk ? artifactPath : path.resolve(source),
+        });
+        assets.push(name);
+      } else {
+        for (const file of files) {
+          const name = path.basename(file);
+          if (assets.includes(name)) throw new Error(`Duplicate release asset: ${name}`);
+          await fs.copyFile(path.join(artifactPath, file), path.join(directory, name));
+          assets.push(name);
+        }
+      }
+    }
+  }
+  const checksums = [];
+  for (const name of assets.sort()) {
+    const data = await fs.readFile(path.join(directory, name));
+    if (!data.length) throw new Error(`Empty asset: ${name}`);
+    checksums.push(`${createHash('sha256').update(data).digest('hex')}  ${name}\n`);
+  }
+  await fs.writeFile(path.join(directory, 'SHA256SUMS'), checksums.join(''));
+  build.assets = [...assets, 'SHA256SUMS'].sort();
+}
+
+async function publish({ github, context, core, build, directory }) {
+  const repository = context.repo;
+  const names = build.assets;
+  const files = (await fs.readdir(directory)).sort();
+  if (!names?.length || JSON.stringify(files) !== JSON.stringify(names)) {
+    throw new Error('Packaged files do not match the selected nightly artifacts.');
+  }
+  for (const name of files) {
+    if (!(await fs.stat(path.join(directory, name))).size) throw new Error(`Empty asset: ${name}`);
+  }
+
+  const releases = await github.paginate(github.rest.repos.listReleases, {
+    ...repository, per_page: 100,
+  });
+  let release = releases.find(item => item.tag_name === 'nightly');
+  if (release?.immutable) throw new Error('The nightly release must allow asset and tag updates.');
+  if ((release?.id || undefined) !== build.release_id) {
+    throw new Error('The nightly release changed during preparation; run the workflow again.');
+  }
+  if (!release) {
+    const { data } = await github.rest.repos.createRelease({
+      ...repository, tag_name: 'nightly', target_commitish: build.sha,
+      name: 'Nightly', draft: true, prerelease: true, make_latest: 'false',
+    });
+    release = data;
+  }
+
+  const previousAssets = await github.paginate(github.rest.repos.listReleaseAssets, {
+    ...repository, release_id: release.id, per_page: 100,
+  });
+  for (const name of files) {
+    const previous = previousAssets.find(asset => asset.name === name);
+    if (previous) {
+      await github.rest.repos.deleteReleaseAsset({ ...repository, asset_id: previous.id });
+    }
+    await github.rest.repos.uploadReleaseAsset({
+      ...repository, release_id: release.id, name,
+      data: await fs.readFile(path.join(directory, name)),
+      headers: { 'content-type': name.endsWith('.zip') ? 'application/zip' : 'application/octet-stream' },
+    });
+  }
+  // Remove retired platforms only after all replacement assets are uploaded.
+  for (const asset of previousAssets.filter(asset => !files.includes(asset.name))) {
+    await github.rest.repos.deleteReleaseAsset({ ...repository, asset_id: asset.id });
+  }
+
+  // A new draft does not necessarily have a tag yet.
+  try {
+    await github.rest.git.getRef({ ...repository, ref: 'tags/nightly' });
+    await github.rest.git.updateRef({ ...repository, ref: 'tags/nightly', sha: build.sha, force: true });
+  } catch (error) {
+    if (error.status !== 404) throw error;
+    await github.rest.git.createRef({ ...repository, ref: 'refs/tags/nightly', sha: build.sha });
+  }
+  await github.rest.repos.updateRelease({
+    ...repository, release_id: release.id, name: 'Nightly', body: build.body,
+    target_commitish: build.sha,
+    draft: false, prerelease: true, make_latest: 'false',
+  });
+  core.info(`Updated nightly at ${build.sha}: ${release.html_url}`);
+}
+
+module.exports = { prepare, packageAssets, publish, releaseNotes };

.github/scripts/nightly-release.test.js

@@ -0,0 +1,398 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { createHash } = require('node:crypto');
+const { test } = require('node:test');
+const { prepare, packageAssets, publish, releaseNotes } = require('./nightly-release.js');
+
+const repository = { owner: 'EasyTier', repo: 'EasyTier' };
+const core = { info() {} };
+const notFound = () => Object.assign(new Error('Not found'), { status: 404 });
+
+function fixture() {
+  const calls = [];
+  const state = {
+    release: null,
+    ancestry: 'ahead',
+    publishedComparison: 'ahead',
+    tagExists: false,
+    version: '2.7.0',
+    releases: [
+      { tag_name: 'v2.6.4', published_at: '2026-05-12', html_url: 'stable' },
+      { tag_name: 'v2.7.0', published_at: '2026-10-06', prerelease: true, html_url: 'version' },
+      { tag_name: 'v2.8.0', published_at: '2026-10-12', draft: true },
+    ],
+    runs: Object.fromEntries(['core', 'gui', 'mobile', 'test'].map((name, index) => [name, {
+      id: index + 1, name, head_sha: 'built', head_branch: 'main',
+      event: 'workflow_dispatch', conclusion: 'success', html_url: `run/${index + 1}`,
+    }])),
+    artifacts: {
+      1: [{ id: 10, name: 'easytier-linux-x86_64' }, { id: 11, name: 'Easytier-Magisk' },
+        { id: 12, name: 'signpath-unsigned-windows-x86_64' }],
+      2: [{ id: 20, name: 'easytier-gui-windows-x86_64' }],
+      3: [{ id: 30, name: 'easytier-mobile-android-aarch64' }],
+    },
+    assets: [],
+  };
+  const repos = {
+    async getBranch() { return { data: { commit: { sha: 'main-head' } } }; },
+    async getContent(request) {
+      calls.push(['version', request.ref]);
+      assert.equal(request.path, 'easytier-gui/src-tauri/tauri.conf.json');
+      return { data: { content: Buffer.from(JSON.stringify({ version: state.version })).toString('base64') } };
+    },
+    async compareCommitsWithBasehead(request) {
+      calls.push(['compare', request.basehead]);
+      return { data: { status: request.basehead.startsWith('nightly...') ? state.publishedComparison : state.ancestry } };
+    },
+    listReleases() {},
+    listReleaseAssets() {},
+    async createRelease(request) {
+      calls.push(['create', request]);
+      state.release = { id: 100, draft: true, html_url: 'nightly' };
+      return { data: state.release };
+    },
+    async deleteReleaseAsset(request) { calls.push(['delete', request.asset_id]); },
+    async uploadReleaseAsset(request) {
+      calls.push(['upload', request.name]);
+      if (state.uploadFails) throw new Error('Upload failed');
+    },
+    async updateRelease(request) {
+      calls.push(['update', request]);
+      Object.assign(state.release, request);
+    },
+  };
+  const actions = {
+    async listWorkflowRuns(request) {
+      assert.equal(request.branch, 'main');
+      assert.equal(request.event, 'workflow_dispatch');
+      assert.equal(request.status, 'success');
+      const run = state.runs[request.workflow_id.replace('.yml', '')];
+      return { data: { workflow_runs: run ? [run] : [] } };
+    },
+    listWorkflowRunArtifacts() {},
+  };
+  const github = {
+    rest: {
+      repos, actions,
+      git: {
+        async getRef() { if (!state.tagExists) throw notFound(); },
+        async createRef(request) { calls.push(['createTag', request.sha]); state.tagExists = true; },
+        async updateRef(request) { calls.push(['updateTag', request.sha]); },
+      },
+    },
+    async paginate(method, request, map) {
+      if (method === repos.listReleases) {
+        return state.releases.concat(state.release ? [{ tag_name: 'nightly', ...state.release }] : []);
+      }
+      if (method === repos.listReleaseAssets) return state.assets;
+      if (method === actions.listWorkflowRunArtifacts) return state.artifacts[request.run_id];
+      if (method === repos.compareCommitsWithBasehead) {
+        calls.push(['changelog', request.basehead]);
+        assert.equal(request.per_page, 100);
+        // Exercise the response mapper used to collect every comparison page.
+        return map({ data: { commits: [commit('old', '2026-10-10T12:00:00Z')] } })
+          .concat(map({ data: { commits: [commit('new', '2026-10-12T12:00:00Z')] } }));
+      }
+      throw new Error('Unexpected API call');
+    },
+  };
+  const context = { repo: repository, payload: { workflow_run: { head_sha: 'built' } } };
+  return { state, calls, github, context, core };
+}
+
+function commit(sha, date) {
+  return { sha, html_url: `commit/${sha}`, commit: { committer: { date }, message: `${sha} change\n\nDetails` } };
+}
+
+test('nightly selects one main commit and uses the last published version, including prereleases', async () => {
+  const f = fixture();
+  f.state.release = { id: 99, published_at: '2026-10-13' };
+  const build = await prepare(f);
+  assert.equal(build.sha, 'built');
+  assert.equal(build.version, 'v2.7.0');
+  assert.ok(f.calls.some(call => call[0] === 'version' && call[1] === 'built'));
+  assert.deepEqual(build.runs, { core: 1, gui: 2, mobile: 3, test: 4 });
+  assert.deepEqual(build.artifacts.core.map(a => a.id), [10, 11]);
+  assert.ok(f.calls.some(call => call[0] === 'changelog' && call[1] === 'v2.7.0...built'));
+  assert.match(build.body, /Changes since \[v2.7.0\]/);
+  assert.ok(build.body.indexOf('2026-10-12') < build.body.indexOf('2026-10-10'));
+});
+
+test('asset versions come from the built commit rather than the changelog baseline', async () => {
+  const f = fixture();
+  f.state.version = '2.8.0-rc.1';
+  assert.equal((await prepare(f)).version, 'v2.8.0-rc.1');
+  f.state.version = '../invalid';
+  await assert.rejects(prepare(f), /valid release version/);
+});
+
+test('nightly waits for every component and the full test run', async () => {
+  for (const workflow of ['core', 'gui', 'mobile', 'test']) {
+    const f = fixture();
+    delete f.state.runs[workflow];
+    assert.equal(await prepare(f), null);
+  }
+});
+
+test('nightly rejects a mismatched commit, branch, event or failed result', async () => {
+  for (const field of ['head_sha', 'head_branch', 'event', 'conclusion']) {
+    const f = fixture();
+    f.state.runs.gui[field] = 'different';
+    assert.equal(await prepare(f), null);
+  }
+});
+
+test('nightly accepts successful failed-job reruns without requiring a new run ID', async () => {
+  const f = fixture();
+  f.state.runs.gui.run_attempt = 2;
+  assert.equal((await prepare(f)).runs.gui, 2);
+});
+
+test('nightly refuses missing or expired artifacts before changing a release', async () => {
+  for (const artifacts of [[], [{ id: 20, name: 'easytier-gui-windows-x86_64', expired: true }]]) {
+    const f = fixture();
+    f.state.artifacts[2] = artifacts;
+    await assert.rejects(prepare(f), /missing or expired/);
+  }
+});
+
+test('an older completed run cannot replace a newer nightly or a removed main commit', async () => {
+  const f = fixture();
+  f.state.ancestry = 'diverged';
+  assert.equal(await prepare(f), null);
+  f.state.ancestry = 'ahead';
+  f.state.release = { id: 100 };
+  for (const status of ['behind', 'diverged']) {
+    f.state.publishedComparison = status;
+    assert.equal(await prepare(f), null);
+  }
+});
+
+test('duplicate completion events skip a fully published commit', async () => {
+  const f = fixture();
+  f.state.release = { id: 100, body: 'Commit: [built](url)' };
+  f.state.publishedComparison = 'identical';
+  assert.equal(await prepare(f), null);
+});
+
+test('nightly can resume an initial draft or an interrupted release-note update', async () => {
+  const f = fixture();
+  f.state.release = { id: 100, draft: true };
+  assert.ok(await prepare(f));
+  assert.ok(!f.calls.some(call => call[1] === 'nightly...built'));
+  f.state.release.draft = false;
+  f.state.release.body = 'Commit: [old](url)';
+  f.state.publishedComparison = 'identical';
+  assert.ok(await prepare(f));
+});
+
+test('manual publication checks the current main commit', async () => {
+  const f = fixture();
+  f.context.payload = {};
+  for (const run of Object.values(f.state.runs)) run.head_sha = 'main-head';
+  assert.equal((await prepare(f)).sha, 'main-head');
+});
+
+test('scheduled publication uses the completed commit even after main advances', async () => {
+  const f = fixture();
+  f.context.payload = {};
+  const build = await prepare({ ...f, sha: 'built' });
+  assert.equal(build.sha, 'built');
+  assert.ok(f.calls.some(call => call[0] === 'compare' && call[1] === 'built...main-head'));
+  assert.deepEqual(build.runs, { core: 1, gui: 2, mobile: 3, test: 4 });
+});
+
+test('nightly requires a published version baseline and a mutable release', async () => {
+  const f = fixture();
+  f.state.releases = [];
+  await assert.rejects(prepare(f), /No published version/);
+  f.state.release = { immutable: true };
+  await assert.rejects(prepare(f), /must allow asset and tag updates/);
+});
+
+test('notes date every entry in UTC and sort by timestamp, not input order', () => {
+  const notes = releaseNotes(repository, { tag_name: 'v2.7.0', html_url: 'version' }, 'built', [
+    commit('middle', '2026-10-12T15:00:00Z'),
+    commit('oldest', '2026-10-12T01:00:00+08:00'),
+    commit('newest', '2026-10-12T19:00:00Z'),
+  ], []);
+  assert.match(notes, /2026-10-11 — oldest change/);
+  assert.ok(notes.indexOf('newest change') < notes.indexOf('middle change'));
+  assert.ok(notes.indexOf('middle change') < notes.indexOf('oldest change'));
+  assert.ok(!notes.includes('Details'));
+});
+
+async function packageFiles(t, f) {
+  const build = await prepare(f);
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'easytier-nightly-test-'));
+  t.after(() => fs.rm(root, { recursive: true, force: true }));
+  const source = path.join(root, 'artifacts');
+  const directory = path.join(root, 'assets');
+  const contents = {
+    'easytier-linux-x86_64': ['easytier-core'],
+    'Easytier-Magisk': ['module.prop', 'bin/easytier-core'],
+    'easytier-gui-windows-x86_64': ['easytier-gui_2.7.0_x64-setup.exe'],
+    'easytier-mobile-android-aarch64': ['app-arm64-release.apk'],
+    ...f.files,
+  };
+  for (const artifact of Object.values(build.artifacts).flat()) {
+    for (const name of contents[artifact.name]) {
+      const file = path.join(source, artifact.name, name);
+      await fs.mkdir(path.dirname(file), { recursive: true });
+      await fs.writeFile(file, `contents of ${name}`, { mode: 0o644 });
+    }
+  }
+  await packageAssets({ build, source, directory });
+  return { ...f, build, source, directory };
+}
+
+test('nightly exposes native installers and matches version-release ZIP names and layout', async t => {
+  const f = fixture();
+  f.state.artifacts[1].push({ id: 14, name: 'easytier-web-dashboard' });
+  f.state.artifacts[2].push(
+    { id: 21, name: 'easytier-gui-macos-aarch64' },
+    { id: 22, name: 'easytier-gui-linux-x86_64' },
+  );
+  f.files = {
+    'easytier-web-dashboard': ['index.html', 'assets/app.js'],
+    'easytier-gui-macos-aarch64': ['easytier-gui_2.7.0_aarch64.dmg'],
+    'easytier-gui-linux-x86_64': [
+      'easytier-gui_2.7.0_amd64.deb',
+      'easytier-gui-2.7.0-1.x86_64.rpm',
+      'easytier-gui_2.7.0_amd64.AppImage',
+    ],
+  };
+  const { build, directory } = await packageFiles(t, f);
+  assert.deepEqual(build.assets, [
+    'Easytier-Magisk-v2.7.0.zip',
+    'SHA256SUMS',
+    'app-arm64-release.apk',
+    'easytier-gui-2.7.0-1.x86_64.rpm',
+    'easytier-gui_2.7.0_aarch64.dmg',
+    'easytier-gui_2.7.0_amd64.AppImage',
+    'easytier-gui_2.7.0_amd64.deb',
+    'easytier-gui_2.7.0_x64-setup.exe',
+    'easytier-linux-x86_64-v2.7.0.zip',
+    'easytier-web-dashboard-v2.7.0.zip',
+  ]);
+  for (const [name, entry] of [
+    ['easytier-linux-x86_64', 'easytier-linux-x86_64/easytier-core'],
+    ['easytier-web-dashboard', 'easytier-web-dashboard/assets/app.js'],
+    ['Easytier-Magisk', 'bin/easytier-core'],
+  ]) {
+    const archive = path.join(directory, `${name}-v2.7.0.zip`);
+    const files = execFileSync('unzip', ['-Z1', archive], { encoding: 'utf8' }).trim().split('\n');
+    assert.ok(files.includes(entry));
+    assert.ok(!files.some(file => file.startsWith('Easytier-Magisk/')));
+    assert.match(execFileSync('zipinfo', ['-l', archive], { encoding: 'utf8' }), /-rwxr-xr-x/);
+  }
+  assert.equal(await fs.readFile(path.join(directory, 'app-arm64-release.apk'), 'utf8'),
+    'contents of app-arm64-release.apk');
+  const sums = await fs.readFile(path.join(directory, 'SHA256SUMS'), 'utf8');
+  assert.equal(sums.trim().split('\n').length, build.assets.length - 1);
+  for (const line of sums.trim().split('\n')) {
+    const [checksum, name] = line.split('  ');
+    const data = await fs.readFile(path.join(directory, name));
+    assert.equal(checksum, createHash('sha256').update(data).digest('hex'));
+  }
+});
+
+test('packaging refuses missing, empty or duplicate installer artifacts', async t => {
+  const f = fixture();
+  const args = await packageFiles(t, f);
+  const artifactPath = path.join(args.source, 'easytier-mobile-android-aarch64');
+  await fs.rm(args.directory, { recursive: true });
+  await fs.rm(artifactPath, { recursive: true });
+  await assert.rejects(packageAssets(args), /ENOENT/);
+  await fs.rm(args.directory, { recursive: true });
+  await fs.mkdir(artifactPath);
+  await assert.rejects(packageAssets(args), /Empty artifact/);
+  await fs.rm(args.directory, { recursive: true });
+  await fs.writeFile(path.join(artifactPath, 'easytier-gui_2.7.0_x64-setup.exe'), 'duplicate');
+  await assert.rejects(packageAssets(args), /Duplicate release asset/);
+});
+
+test('reruns publish only the newest artifact for each name, ignoring expired older attempts', async t => {
+  const f = fixture();
+  f.state.artifacts[1].push(
+    { id: 13, name: 'easytier-linux-x86_64' },
+    { id: 9, name: 'easytier-linux-x86_64', expired: true },
+  );
+  const args = await packageFiles(t, f);
+  assert.deepEqual(args.build.artifacts.core.map(a => a.id), [13, 11]);
+  await publish(args);
+  assert.equal(f.calls.filter(call => call[0] === 'upload' && call[1] === 'easytier-linux-x86_64-v2.7.0.zip').length, 1);
+});
+
+test('first publication creates one draft, uploads assets and then publishes a prerelease', async t => {
+  const f = fixture();
+  await publish(await packageFiles(t, f));
+  const creation = f.calls.find(call => call[0] === 'create')[1];
+  assert.equal(creation.draft, true);
+  assert.equal(creation.prerelease, true);
+  assert.equal(creation.make_latest, 'false');
+  const update = f.calls.at(-1);
+  assert.equal(update[0], 'update');
+  assert.equal(update[1].release_id, 100);
+  assert.equal(update[1].draft, false);
+  assert.equal(update[1].make_latest, 'false');
+  assert.ok(f.calls.some(call => call[0] === 'createTag'));
+});
+
+test('updates keep the release ID and remove obsolete assets only after uploads finish', async t => {
+  const f = fixture();
+  f.state.release = { id: 99, draft: false, target_commitish: 'first-build' };
+  f.state.tagExists = true;
+  f.state.assets = [
+    { id: 50, name: 'easytier-linux-x86_64-v2.7.0.zip' },
+    { id: 51, name: 'retired-platform.zip' },
+  ];
+  await publish(await packageFiles(t, f));
+  assert.ok(!f.calls.some(call => call[0] === 'create' || call[0] === 'createTag'));
+  assert.equal(f.calls.at(-1)[1].release_id, 99);
+  assert.equal(f.state.release.target_commitish, 'built');
+  const lastUpload = f.calls.findLastIndex(call => call[0] === 'upload');
+  assert.ok(f.calls.findIndex(call => call[0] === 'delete' && call[1] === 51) > lastUpload);
+});
+
+test('incomplete packaging cannot mutate the published release', async t => {
+  const f = fixture();
+  const args = await packageFiles(t, f);
+  await fs.unlink(path.join(args.directory, 'Easytier-Magisk-v2.7.0.zip'));
+  await assert.rejects(publish(args), /do not match/);
+  assert.ok(!f.calls.some(call => ['create', 'delete', 'upload', 'update'].includes(call[0])));
+});
+
+test('a failed upload does not advance the tag, notes or draft publication', async t => {
+  const f = fixture();
+  const args = await packageFiles(t, f);
+  f.state.uploadFails = true;
+  await assert.rejects(publish(args), /Upload failed/);
+  assert.equal(f.state.release.draft, true);
+  assert.ok(!f.calls.some(call => ['createTag', 'updateTag', 'update'].includes(call[0])));
+});
+
+test('a retry resumes the initial draft after an upload failure without creating another release', async t => {
+  const f = fixture();
+  const args = await packageFiles(t, f);
+  f.state.uploadFails = true;
+  await assert.rejects(publish(args), /Upload failed/);
+  f.state.uploadFails = false;
+  const retry = await prepare(f);
+  assert.equal(retry.release_id, 100);
+  await fs.rm(args.directory, { recursive: true });
+  await packageAssets({ ...args, build: retry });
+  await publish({ ...args, build: retry });
+  assert.equal(f.calls.filter(call => call[0] === 'create').length, 1);
+  assert.equal(f.state.release.draft, false);
+});
+
+test('publication stops if the release was replaced during artifact downloads', async t => {
+  const f = fixture();
+  const args = await packageFiles(t, f);
+  f.state.release = { id: 999 };
+  await assert.rejects(publish(args), /changed during preparation/);
+});

.github/scripts/validate-release-builds.js

@@ -0,0 +1,25 @@
+module.exports = async ({ github, context, core }) => {
+  const builds = [
+    ['core.yml', process.env.CORE_RUN_ID],
+    ['gui.yml', process.env.GUI_RUN_ID],
+    ['mobile.yml', process.env.MOBILE_RUN_ID],
+  ];
+  let commit;
+
+  for (const [workflow, runId] of builds) {
+    const { data: run } = await github.rest.actions.getWorkflowRun({
+      ...context.repo,
+      run_id: Number(runId),
+    });
+    const fullBuild = run.event === 'workflow_dispatch' ||
+      (run.event === 'push' && run.head_branch.startsWith('releases/'));
+    if (run.path !== `.github/workflows/${workflow}` || run.conclusion !== 'success' || !fullBuild) {
+      throw new Error(`${workflow}: run ${runId} must be a successful full build.`);
+    }
+    if (commit && run.head_sha !== commit) {
+      throw new Error('Core, GUI and Mobile must be built from the same commit.');
+    }
+    commit = run.head_sha;
+    core.info(`${workflow}: validated full build ${runId} at ${commit}.`);
+  }
+};

.github/workflows/Dockerfile

@@ -0,0 +1,48 @@
+FROM alpine:latest AS base
+FROM base AS builder
+
+ARG TARGETPLATFORM
+
+COPY . /tmp/artifacts
+WORKDIR /tmp/output
+RUN ARTIFACT_ARCH=""; \
+    if [ "$TARGETPLATFORM" = "linux/amd64" ]; then \
+        ARTIFACT_ARCH="x86_64"; \
+    elif [ "$TARGETPLATFORM" = "linux/arm/v6" ]; then \
+        ARTIFACT_ARCH="armhf"; \
+    elif [ "$TARGETPLATFORM" = "linux/arm/v7" ]; then \
+        ARTIFACT_ARCH="armv7hf"; \
+    elif [ "$TARGETPLATFORM" = "linux/arm64" ]; then \
+        ARTIFACT_ARCH="aarch64"; \
+    elif [ "$TARGETPLATFORM" = "linux/riscv64" ]; then \
+        ARTIFACT_ARCH="riscv64"; \
+    else \
+        echo "Unsupported architecture: $TARGETPLATFORM"; \
+        exit 1; \
+    fi; \
+    cp /tmp/artifacts/easytier-linux-${ARTIFACT_ARCH}/* /tmp/output;
+
+FROM base
+
+RUN apk add --no-cache tzdata tini
+WORKDIR /app
+COPY --from=builder --chmod=755 /tmp/output/* /usr/local/bin
+
+# users can use "-e TZ=xxx" to adjust it
+ENV TZ=Asia/Shanghai
+
+# tcp
+EXPOSE 11010/tcp
+# udp
+EXPOSE 11010/udp
+# wg
+EXPOSE 11011/udp
+# ws
+EXPOSE 11011/tcp
+# wss
+EXPOSE 11012/tcp
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=5 \
+    CMD ["/usr/local/bin/easytier-cli", "--rpc-portal", "127.0.0.1:15888", "--output", "json", "node", "info"]
+
+ENTRYPOINT ["/sbin/tini", "--", "easytier-core"]

.github/workflows/core.yml

@@ -0,0 +1,441 @@
+name: EasyTier Core
+
+on:
+  workflow_dispatch:
+    inputs:
+      sign_windows:
+        description: Submit Windows artifacts for SignPath test signing
+        type: boolean
+        default: true
+  push:
+    branches: [ "develop", "main", "releases/**" ]
+  pull_request:
+    branches: [ "develop", "main" ]
+    types: [ opened, synchronize, reopened, ready_for_review ]
+
+concurrency:
+  # A new PR or branch push must not cancel a full build.
+  group: ${{ github.workflow }}-${{ (github.event_name == 'workflow_dispatch' || startsWith(github.ref_name, 'releases/')) && 'full' || 'check' }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+
+defaults:
+  run:
+    # necessary for windows
+    shell: bash
+
+jobs:
+  pre_job:
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    env:
+      RELEVANT_PATHS: >-
+        ["Cargo.toml", "Cargo.lock", "rust-toolchain.toml", ".cargo/**",
+        "pnpm-lock.yaml", "pnpm-workspace.yaml", "package.json", "easytier/**",
+        "easytier-core/**", "easytier-proto/**", "easytier-rpc-build/**",
+        "easytier-web/**", "easytier-contrib/easytier-magisk/**",
+        ".github/workflows/core.yml", ".github/actions/**"]
+      FRONTEND_PATHS: >-
+        ["easytier-web/frontend/**", "easytier-web/frontend-lib/**",
+        "easytier-web/config-generator/**", "easytier-proto/proto/**",
+        "easytier-core/src/config/**", "easytier-core/src/lib.rs",
+        "pnpm-lock.yaml", "pnpm-workspace.yaml", "package.json",
+        "Cargo.toml", "Cargo.lock", "rust-toolchain.toml", ".cargo/**",
+        "easytier-core/Cargo.toml", "easytier-proto/Cargo.toml",
+        ".github/workflows/core.yml", ".github/actions/prepare-pnpm/**"]
+    outputs:
+      full_build: ${{ github.event_name == 'workflow_dispatch' || startsWith(github.ref_name, 'releases/') }}
+      frontend_changed: ${{ steps.path_filter.outputs.frontend }}
+      # Release builds must run even if they only change release metadata.
+      should_skip: >-
+        ${{
+          (
+            steps.skip_check.outputs.should_skip == 'true' ||
+            (
+              github.event_name == 'pull_request' &&
+              steps.path_filter.outputs.relevant != 'true'
+            )
+          ) &&
+          github.event_name != 'workflow_dispatch' &&
+          !startsWith(github.ref_name, 'releases/')
+        }}
+    steps:
+      - id: skip_check
+        if: github.event_name != 'workflow_dispatch' && !startsWith(github.ref_name, 'releases/')
+        uses: fkirc/skip-duplicate-actions@v5
+        with:
+          concurrent_skipping: 'same_content_newer'
+          skip_after_successful_duplicate: 'true'
+          paths: ${{ env.RELEVANT_PATHS }}
+
+      - id: path_filter
+        if: >-
+          github.event_name == 'pull_request' &&
+          steps.skip_check.outputs.should_skip != 'true'
+        uses: dorny/paths-filter@v4
+        with:
+          filters: |
+            relevant: ${{ env.RELEVANT_PATHS }}
+            frontend: ${{ env.FRONTEND_PATHS }}
+
+  check:
+    name: Check (${{ matrix.TARGET }})
+    needs: pre_job
+    if: needs.pre_job.outputs.should_skip != 'true' && needs.pre_job.outputs.full_build != 'true'
+    strategy:
+      fail-fast: true
+      matrix:
+        include:
+          - TARGET: x86_64-unknown-linux-musl
+            OS: ubuntu-24.04
+            FEATURES: jemalloc
+          - TARGET: aarch64-apple-darwin
+            OS: macos-latest
+            FEATURES: jemalloc
+          - TARGET: x86_64-pc-windows-msvc
+            OS: windows-latest
+            FEATURES: mimalloc
+    runs-on: ${{ matrix.OS }}
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: ./.github/actions/prepare-build
+        with:
+          target: ${{ matrix.TARGET }}
+          gui: false
+          pnpm: false
+          token: ${{ github.token }}
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: core-check-${{ matrix.TARGET }}
+          save-if: ${{ github.event_name != 'pull_request' }}
+
+      - name: Check Core and Web
+        run: cargo check --locked --all-targets --target ${{ matrix.TARGET }} --features ${{ matrix.FEATURES }}
+
+  build_web:
+    runs-on: ubuntu-latest
+    needs: pre_job
+    if: >-
+      needs.pre_job.outputs.should_skip != 'true' &&
+      (
+        needs.pre_job.outputs.full_build == 'true' ||
+        github.event_name != 'pull_request' ||
+        needs.pre_job.outputs.frontend_changed == 'true'
+      )
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Frontend Environment
+        uses: ./.github/actions/prepare-pnpm
+        with:
+          token: ${{ github.token }}
+          build-filter: './easytier-web/*'
+
+      - name: Archive artifact
+        if: needs.pre_job.outputs.full_build == 'true'
+        uses: actions/upload-artifact@v5
+        with:
+          name: easytier-web-dashboard
+          path: |
+            easytier-web/frontend/dist/*
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - TARGET: x86_64-unknown-linux-musl
+            OS: ubuntu-24.04
+            ARTIFACT_NAME: linux-x86_64
+          - TARGET: aarch64-unknown-linux-musl
+            OS: ubuntu-24.04-arm
+            ARTIFACT_NAME: linux-aarch64
+
+          - TARGET: riscv64gc-unknown-linux-musl
+            OS: ubuntu-24.04
+            ARTIFACT_NAME: linux-riscv64
+          - TARGET: loongarch64-unknown-linux-musl
+            OS: ubuntu-24.04
+            ARTIFACT_NAME: linux-loongarch64
+
+          - TARGET: armv7-unknown-linux-musleabihf # raspberry pi 2-3-4, not tested
+            OS: ubuntu-24.04
+            ARTIFACT_NAME: linux-armv7hf
+          - TARGET: armv7-unknown-linux-musleabi # raspberry pi 2-3-4, not tested
+            OS: ubuntu-24.04
+            ARTIFACT_NAME: linux-armv7
+          - TARGET: arm-unknown-linux-musleabihf # raspberry pi 0-1, not tested
+            OS: ubuntu-24.04
+            ARTIFACT_NAME: linux-armhf
+          - TARGET: arm-unknown-linux-musleabi # raspberry pi 0-1, not tested
+            OS: ubuntu-24.04
+            ARTIFACT_NAME: linux-arm
+
+          - TARGET: mips-unknown-linux-musl
+            OS: ubuntu-24.04
+            ARTIFACT_NAME: linux-mips
+          - TARGET: mipsel-unknown-linux-musl
+            OS: ubuntu-24.04
+            ARTIFACT_NAME: linux-mipsel
+
+          - TARGET: x86_64-unknown-freebsd
+            OS: ubuntu-24.04
+            ARTIFACT_NAME: freebsd-13.2-x86_64
+            BSD_VERSION: 13.2
+
+          - TARGET: x86_64-apple-darwin
+            OS: macos-latest
+            ARTIFACT_NAME: macos-x86_64
+          - TARGET: aarch64-apple-darwin
+            OS: macos-latest
+            ARTIFACT_NAME: macos-aarch64
+
+          - TARGET: x86_64-pc-windows-msvc
+            OS: windows-latest
+            ARTIFACT_NAME: windows-x86_64
+          - TARGET: i686-pc-windows-msvc
+            OS: windows-latest
+            ARTIFACT_NAME: windows-i686
+          - TARGET: aarch64-pc-windows-msvc
+            OS: windows-11-arm
+            ARTIFACT_NAME: windows-arm64
+
+    runs-on: ${{ matrix.OS }}
+    env:
+      NAME: easytier
+      TARGET: ${{ matrix.TARGET }}
+      OS: ${{ matrix.OS }}
+      OSS_BUCKET: ${{ secrets.ALIYUN_OSS_BUCKET }}
+    needs:
+      - pre_job
+      - build_web
+    if: needs.pre_job.outputs.should_skip != 'true' && needs.pre_job.outputs.full_build == 'true'
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set current ref as env variable
+        run: |
+          echo "GIT_DESC=$(git log -1 --format=%cd.%h --date=format:%Y-%m-%d_%H:%M:%S)" >> $GITHUB_ENV
+
+      - name: Download web artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: easytier-web-dashboard
+          path: easytier-web/frontend/dist/
+
+      - name: Prepare build environment
+        uses: ./.github/actions/prepare-build
+        with:
+          target: ${{ matrix.TARGET }}
+          gui: false
+          pnpm: false
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          # The prefix cache key, this can be changed to start a new cache manually.
+          # default: "v0-rust"
+          prefix-key: ""
+          shared-key: core-release-${{ matrix.TARGET }}
+          cache-targets: "true"
+
+      - uses: mlugg/setup-zig@v2
+        if: ${{ contains(matrix.OS, 'ubuntu') }}
+        with:
+          version: 0.16.0
+          use-cache: true
+
+      - uses: taiki-e/install-action@v2
+        if: ${{ contains(matrix.OS, 'ubuntu') }}
+        with:
+          # v0.23.3 emits -mcpu=generic+v6+strict_align for
+          # arm-unknown-linux-musleabi, which zig 0.16.0 rejects;
+          # unpin only together with a zig bump.
+          tool: cargo-zigbuild@0.23.2
+
+      - name: Build
+        if: ${{ !contains(matrix.TARGET, 'mips') }}
+        run: |          
+          if [[ "$TARGET" == *windows* ]]; then
+            SUFFIX=.exe
+          else
+            SUFFIX=""
+          fi
+
+          if [[ "$TARGET" =~ (x86_64-unknown-linux-musl|aarch64-unknown-linux-musl|windows|darwin) ]]; then
+            BUILD=build
+          else
+            BUILD=zigbuild
+          fi
+
+          if [[ "$TARGET" =~ ^(riscv64|loongarch64|aarch64).*$ || "$TARGET" =~ (freebsd|windows) ]]; then
+            FEATURES="mimalloc"
+          else
+            FEATURES="jemalloc"
+          fi
+          
+          cargo $BUILD --release --target $TARGET --package=easytier-web --features=embed
+          mv ./target/$TARGET/release/easytier-web"$SUFFIX" ./target/$TARGET/release/easytier-web-embed"$SUFFIX"
+          
+          cargo $BUILD --release --target $TARGET --features=$FEATURES
+
+      - name: Build (MIPS)
+        if: ${{ contains(matrix.TARGET, 'mips') }}
+        env:
+          RUSTC_BOOTSTRAP: 1
+        run: |
+          cargo build -r --target $TARGET -Z build-std=std,panic_abort --package=easytier --features=jemalloc
+
+      - name: Compress
+        run: |
+          mkdir -p ./artifacts/objects/
+
+          # windows is the only OS using a different convention for executable file name
+          if [[ $OS =~ ^windows.*$ ]]; then
+              SUFFIX=.exe
+              case $TARGET in
+                  x86_64*)  ARCH_DIR=x86_64 ;;
+                  i686*)    ARCH_DIR=i686 ;;
+                  aarch64*) ARCH_DIR=arm64 ;;
+              esac
+              if [[ -n "$ARCH_DIR" ]]; then
+                  find "easytier/third_party/${ARCH_DIR}" -maxdepth 1 -type f \( -name "*.dll" -o -name "*.sys" \) -exec cp {} ./artifacts/objects/ \;
+              fi
+          fi
+
+          if [[ $GITHUB_REF_TYPE =~ ^tag$ ]]; then
+            TAG=$GITHUB_REF_NAME
+          else
+            TAG=$GITHUB_SHA
+          fi
+          
+          if [[ $OS =~ ^ubuntu.*$ && ! $TARGET =~ (loongarch|freebsd) ]]; then
+            HOST_ARCH=$(uname -m)
+            case $HOST_ARCH in
+              x86_64)  UPX_ARCH="amd64" ;;
+              aarch64) UPX_ARCH="arm64" ;;
+              *)       UPX_ARCH="amd64" ;;
+            esac
+
+            UPX_VERSION=4.2.4
+            UPX_PKG="upx-${UPX_VERSION}-${UPX_ARCH}_linux"
+            curl -L "https://github.com/upx/upx/releases/download/v${UPX_VERSION}/${UPX_PKG}.tar.xz" -s | tar xJvf -
+            cp "${UPX_PKG}/upx" .
+            UPX_BIN=./upx
+          fi
+
+          for BIN in ./target/$TARGET/release/easytier-{core,cli,web,web-embed}"$SUFFIX"; do
+            if [[ -f "$BIN" ]]; then
+              if [[ -n "$UPX_BIN" ]]; then
+                $UPX_BIN --lzma --best "$BIN" || true
+              fi
+
+              mv "$BIN" ./artifacts/objects/
+            fi
+          done
+
+          mv ./artifacts/objects/* ./artifacts/
+          rm -rf ./artifacts/objects/
+
+      - name: Archive artifact
+        uses: actions/upload-artifact@v5
+        with:
+          name: easytier-${{ matrix.ARTIFACT_NAME }}
+          path: |
+            ./artifacts/*
+
+      - name: Prepare SignPath test artifact
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.sign_windows && contains(matrix.TARGET, 'windows') }}
+        run: |
+          mkdir -p ./signpath-artifacts
+          cp \
+            ./artifacts/easytier-core.exe \
+            ./artifacts/easytier-cli.exe \
+            ./artifacts/easytier-web.exe \
+            ./artifacts/easytier-web-embed.exe \
+            ./signpath-artifacts/
+
+      - name: Upload unsigned SignPath test artifact
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.sign_windows && contains(matrix.TARGET, 'windows') }}
+        id: signpath-upload
+        uses: actions/upload-artifact@v5
+        with:
+          name: signpath-unsigned-${{ matrix.ARTIFACT_NAME }}
+          path: ./signpath-artifacts/*
+          if-no-files-found: error
+
+      - name: Submit SignPath test-signing request
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.sign_windows && contains(matrix.TARGET, 'windows') }}
+        uses: signpath/github-action-submit-signing-request@v2
+        with:
+          api-token: ${{ secrets.SIGNPATH_API_TOKEN }}
+          organization-id: 368cf38d-86d5-4bfe-a1fa-82a50dce7e9f
+          project-slug: EasyTier
+          signing-policy-slug: test-signing
+          artifact-configuration-slug: initial
+          github-artifact-id: ${{ steps.signpath-upload.outputs.artifact-id }}
+          wait-for-completion: true
+          output-artifact-directory: ./signpath-signed-artifacts
+
+      - name: Upload signed SignPath test artifact
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.sign_windows && contains(matrix.TARGET, 'windows') }}
+        uses: actions/upload-artifact@v5
+        with:
+          name: signpath-signed-${{ matrix.ARTIFACT_NAME }}
+          path: ./signpath-signed-artifacts/*
+          if-no-files-found: error
+
+  build_magisk:
+    runs-on: ubuntu-latest
+    needs: [ pre_job, build_web, build ]
+    if: needs.pre_job.result == 'success' && needs.pre_job.outputs.should_skip != 'true' && needs.pre_job.outputs.full_build == 'true' && !cancelled()
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v5  # 必须先检出代码才能获取模块配置
+
+      # 下载二进制文件到独立目录
+      - name: Download Linux aarch64 binaries
+        uses: actions/download-artifact@v4
+        with:
+          name: easytier-linux-aarch64
+          path: ./downloaded-binaries/  # 独立目录避免冲突
+
+      - name: Download Magisk WebUI
+        uses: actions/download-artifact@v4
+        with:
+          name: easytier-web-dashboard
+          path: ./downloaded-webui/
+
+      # 将二进制文件和 WebUI 复制到 Magisk 模块目录
+      - name: Prepare Magisk module
+        run: |
+          module_dir=./easytier-contrib/easytier-magisk
+          mkdir -p "$module_dir/webroot"
+          cp ./downloaded-binaries/easytier-core "$module_dir/"
+          cp ./downloaded-binaries/easytier-cli "$module_dir/"
+          cp ./downloaded-binaries/easytier-web "$module_dir/"
+          cp -R ./downloaded-webui/config-generator/. "$module_dir/webroot/"
+          test -f "$module_dir/webroot/index.html"
+
+      # 上传生成的模块
+      - name: Upload Magisk Module
+        uses: actions/upload-artifact@v5
+        with:
+          name: Easytier-Magisk
+          path: |
+            ./easytier-contrib/easytier-magisk
+            !./easytier-contrib/easytier-magisk/build.sh
+            !./easytier-contrib/easytier-magisk/magisk_update.json
+          if-no-files-found: error
+
+  core-result:
+    runs-on: ubuntu-latest
+    needs: [ pre_job, check, build_web, build, build_magisk ]
+    if: ${{ always() }}
+    steps:
+      - name: Mark result as failed
+        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
+        run: exit 1

.github/workflows/docker.yml

@@ -0,0 +1,103 @@
+name: EasyTier Docker
+
+on:
+  workflow_dispatch:
+    inputs:
+      run_id:
+        description: 'The run id of EasyTier-Core Action in EasyTier repo'
+        type: number
+        default: 10228239965
+        required: true
+      image_tag:
+        description: 'Tag for this image build'
+        type: string
+        default: 'v2.7.0'
+        required: true
+      mark_latest:
+        description: 'Mark this image as latest'
+        type: boolean
+        default: false
+        required: true
+      mark_unstable:
+        description: 'Mark this image as unstable'
+        type: boolean
+        default: false
+        required: true
+
+jobs:
+  docker:
+    if: contains('["KKRainbow"]', github.actor)
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v5
+      -
+        name: Validate inputs
+        run: |
+          if [[ "${{ inputs.mark_latest }}" == "true" && "${{ inputs.mark_unstable }}" == "true" ]]; then
+            echo "Error: mark_latest and mark_unstable cannot both be true"
+            exit 1
+          fi
+      -
+        name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+      -
+        name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      -
+        name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: login github container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Download artifact
+        id: download-artifact
+        uses: dawidd6/action-download-artifact@v11
+        with:
+          github_token: ${{secrets.GITHUB_TOKEN}}
+          run_id: ${{ inputs.run_id }}
+          repo: EasyTier/EasyTier
+          path: docker_context
+      - name: List files
+        run: |
+          ls -l -R .
+      - name: Prepare Docker tags
+        id: tags
+        run: |
+          # Base tags with version
+          DOCKERHUB_TAGS="easytier/easytier:${{ inputs.image_tag }}"
+          GHCR_TAGS="ghcr.io/easytier/easytier:${{ inputs.image_tag }}"
+
+          # Add latest tags if requested
+          if [[ "${{ inputs.mark_latest }}" == "true" ]]; then
+            DOCKERHUB_TAGS="${DOCKERHUB_TAGS},easytier/easytier:latest"
+            GHCR_TAGS="${GHCR_TAGS},ghcr.io/easytier/easytier:latest"
+          fi
+
+          # Add unstable tags if requested
+          if [[ "${{ inputs.mark_unstable }}" == "true" ]]; then
+            DOCKERHUB_TAGS="${DOCKERHUB_TAGS},easytier/easytier:unstable"
+            GHCR_TAGS="${GHCR_TAGS},ghcr.io/easytier/easytier:unstable"
+          fi
+
+          # Combine all tags
+          ALL_TAGS="${DOCKERHUB_TAGS},${GHCR_TAGS}"
+
+          echo "tags=${ALL_TAGS}" >> $GITHUB_OUTPUT
+          echo "Generated tags: ${ALL_TAGS}"
+      -
+        name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: ./docker_context
+          platforms: linux/amd64,linux/arm/v6,linux/arm/v7,linux/arm64,linux/riscv64
+          push: true
+          file: .github/workflows/Dockerfile
+          tags: ${{ steps.tags.outputs.tags }}

.github/workflows/go.yml

@@ -0,0 +1,44 @@
+name: EasyTier Go
+
+on:
+  push:
+    branches: ["develop", "main", "releases/**"]
+    paths:
+      - "easytier-go/**"
+      - ".github/workflows/go.yml"
+  pull_request:
+    branches: ["develop", "main"]
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - "easytier-go/**"
+      - ".github/workflows/go.yml"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test Go modules
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version: "1.25.x"
+          cache-dependency-path: |
+            easytier-go/go.sum
+            easytier-go/examples/tun/go.sum
+
+      - name: Test main module
+        working-directory: easytier-go
+        run: go test ./...
+
+      - name: Test TUN example module
+        working-directory: easytier-go/examples/tun
+        run: go test ./...

.github/workflows/gui.yml

@@ -0,0 +1,297 @@
+name: EasyTier GUI
+
+on:
+  workflow_dispatch:
+  push:
+    branches: ["develop", "main", "releases/**"]
+  pull_request:
+    branches: ["develop", "main"]
+    types: [opened, synchronize, reopened, ready_for_review]
+
+concurrency:
+  # A new PR or branch push must not cancel a full build.
+  group: ${{ github.workflow }}-${{ (github.event_name == 'workflow_dispatch' || startsWith(github.ref_name, 'releases/')) && 'full' || 'check' }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+
+defaults:
+  run:
+    # necessary for windows
+    shell: bash
+
+jobs:
+  pre_job:
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    env:
+      RELEVANT_PATHS: >-
+        ["Cargo.toml", "Cargo.lock", "rust-toolchain.toml", ".cargo/**",
+        "pnpm-lock.yaml", "pnpm-workspace.yaml", "package.json", "easytier/**",
+        "easytier-core/**", "easytier-proto/**", "easytier-rpc-build/**",
+        "easytier-gui/**", "tauri-plugin-vpnservice/**",
+        "easytier-web/frontend-lib/**", ".github/workflows/gui.yml",
+        ".github/actions/**"]
+    outputs:
+      full_build: ${{ github.event_name == 'workflow_dispatch' || startsWith(github.ref_name, 'releases/') }}
+      # Release builds must run even if they only change release metadata.
+      should_skip: >-
+        ${{
+          (
+            steps.skip_check.outputs.should_skip == 'true' ||
+            (
+              github.event_name == 'pull_request' &&
+              steps.path_filter.outputs.relevant != 'true'
+            )
+          ) &&
+          github.event_name != 'workflow_dispatch' &&
+          !startsWith(github.ref_name, 'releases/')
+        }}
+    steps:
+      - id: skip_check
+        if: github.event_name != 'workflow_dispatch' && !startsWith(github.ref_name, 'releases/')
+        uses: fkirc/skip-duplicate-actions@v5
+        with:
+          concurrent_skipping: 'same_content_newer'
+          skip_after_successful_duplicate: 'true'
+          paths: ${{ env.RELEVANT_PATHS }}
+
+      - id: path_filter
+        if: >-
+          github.event_name == 'pull_request' &&
+          steps.skip_check.outputs.should_skip != 'true'
+        uses: dorny/paths-filter@v4
+        with:
+          filters: |
+            relevant: ${{ env.RELEVANT_PATHS }}
+
+  check:
+    name: Check GUI (Linux)
+    needs: pre_job
+    if: needs.pre_job.outputs.should_skip != 'true' && needs.pre_job.outputs.full_build != 'true'
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: ./.github/actions/prepare-build
+        with:
+          gui: true
+          pnpm: true
+          pnpm-build-filter: easytier-gui...
+          token: ${{ github.token }}
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: gui-check-x86_64-unknown-linux-gnu
+          save-if: ${{ github.event_name != 'pull_request' }}
+
+      - name: Check GUI
+        run: cargo check --locked --all-targets --package easytier-gui --features custom-protocol
+
+  build-gui:
+    strategy:
+      fail-fast: true
+      matrix:
+        include:
+          - TARGET: x86_64-unknown-linux-musl
+            OS: ubuntu-24.04
+            GUI_TARGET: x86_64-unknown-linux-gnu
+            ARTIFACT_NAME: linux-x86_64
+          - TARGET: aarch64-unknown-linux-musl
+            OS: ubuntu-24.04-arm
+            GUI_TARGET: aarch64-unknown-linux-gnu
+            ARTIFACT_NAME: linux-aarch64
+
+          - TARGET: x86_64-apple-darwin
+            OS: macos-latest
+            GUI_TARGET: x86_64-apple-darwin
+            ARTIFACT_NAME: macos-x86_64
+          - TARGET: aarch64-apple-darwin
+            OS: macos-latest
+            GUI_TARGET: aarch64-apple-darwin
+            ARTIFACT_NAME: macos-aarch64
+
+          - TARGET: x86_64-pc-windows-msvc
+            OS: windows-latest
+            GUI_TARGET: x86_64-pc-windows-msvc
+            ARTIFACT_NAME: windows-x86_64
+          - TARGET: i686-pc-windows-msvc
+            OS: windows-latest
+            GUI_TARGET: i686-pc-windows-msvc
+            ARTIFACT_NAME: windows-i686
+          - TARGET: aarch64-pc-windows-msvc
+            OS: windows-11-arm
+            GUI_TARGET: aarch64-pc-windows-msvc
+            ARTIFACT_NAME: windows-arm64
+
+    runs-on: ${{ matrix.OS }}
+    env:
+      NAME: easytier
+      TARGET: ${{ matrix.TARGET }}
+      OS: ${{ matrix.OS }}
+      GUI_TARGET: ${{ matrix.GUI_TARGET }}
+      OSS_BUCKET: ${{ secrets.ALIYUN_OSS_BUCKET }}
+    needs: pre_job
+    if: needs.pre_job.outputs.should_skip != 'true' && needs.pre_job.outputs.full_build == 'true'
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set current ref as env variable
+        run: |
+          echo "GIT_DESC=$(git log -1 --format=%cd.%h --date=format:%Y-%m-%d_%H:%M:%S)" >> $GITHUB_ENV
+
+      - name: Prepare build environment
+        uses: ./.github/actions/prepare-build
+        with:
+          target: ${{ matrix.TARGET }}
+          gui: true
+          pnpm: true
+          pnpm-build-filter: easytier-gui...
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          # The prefix cache key, this can be changed to start a new cache manually.
+          # default: "v0-rust"
+          prefix-key: ""
+          shared-key: gui-release-${{ matrix.GUI_TARGET }}
+          cache-targets: "true"
+
+      - name: copy correct DLLs
+        if: ${{ contains(matrix.GUI_TARGET, 'windows') }}
+        run: |
+          case $TARGET in
+              x86_64*)  ARCH_DIR=x86_64 ;;
+              i686*)    ARCH_DIR=i686 ;;
+              aarch64*) ARCH_DIR=arm64 ;;
+          esac
+          if [[ -n "$ARCH_DIR" ]]; then
+              find "./easytier/third_party/${ARCH_DIR}" -maxdepth 1 -type f \( -name "*.dll" -o -name "*.sys" \) -exec cp {} ./easytier-gui/src-tauri/ \;
+          fi
+
+      - name: Validate macOS signing secrets
+        if: ${{ contains(matrix.GUI_TARGET, 'darwin') && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) }}
+        env:
+          APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
+          APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+          APPLE_SIGNING_IDENTITY: ${{ secrets.APPLE_SIGNING_IDENTITY }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        run: |
+          missing=()
+          for name in APPLE_CERTIFICATE APPLE_CERTIFICATE_PASSWORD APPLE_SIGNING_IDENTITY APPLE_ID APPLE_PASSWORD APPLE_TEAM_ID; do
+            if [[ -z "${!name}" ]]; then
+              missing+=("$name")
+            fi
+          done
+          if (( ${#missing[@]} )); then
+            printf 'Missing macOS signing secret(s): %s\n' "${missing[*]}" >&2
+            exit 1
+          fi
+
+      - name: Build GUI
+        if: ${{ matrix.GUI_TARGET != '' && (!contains(matrix.GUI_TARGET, 'darwin') || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name != github.repository)) }}
+        uses: tauri-apps/tauri-action@v0
+        with:
+          projectPath: ./easytier-gui
+          args: --verbose --target ${{ matrix.GUI_TARGET }}
+
+      - name: Build GUI (signed and notarized)
+        if: ${{ contains(matrix.GUI_TARGET, 'darwin') && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) }}
+        timeout-minutes: 60
+        uses: tauri-apps/tauri-action@v0
+        env:
+          APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
+          APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+          APPLE_SIGNING_IDENTITY: ${{ secrets.APPLE_SIGNING_IDENTITY }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        with:
+          projectPath: ./easytier-gui
+          args: --verbose --target ${{ matrix.GUI_TARGET }}
+
+      - name: Notarize and staple macOS DMG
+        if: ${{ contains(matrix.GUI_TARGET, 'darwin') && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) }}
+        timeout-minutes: 45
+        env:
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        run: |
+          set -euo pipefail
+
+          dmg_dir="./target/$GUI_TARGET/release/bundle/dmg"
+          if [[ ! -d "$dmg_dir" ]]; then
+            printf 'macOS DMG directory not found: %s\n' "$dmg_dir" >&2
+            exit 1
+          fi
+
+          dmgs=()
+          while IFS= read -r dmg; do
+            dmgs+=("$dmg")
+          done < <(find "$dmg_dir" -maxdepth 1 -type f -name "*.dmg" | sort)
+          if (( ${#dmgs[@]} == 0 )); then
+            printf 'No macOS DMG found in %s\n' "$dmg_dir" >&2
+            exit 1
+          fi
+
+          for dmg in "${dmgs[@]}"; do
+            printf 'Verifying signed DMG: %s\n' "$dmg"
+            codesign --verify --verbose=4 "$dmg"
+            codesign -dv --verbose=4 "$dmg"
+
+            printf 'Notarizing DMG: %s\n' "$dmg"
+            xcrun notarytool submit "$dmg" \
+              --apple-id "$APPLE_ID" \
+              --password "$APPLE_PASSWORD" \
+              --team-id "$APPLE_TEAM_ID" \
+              --wait \
+              --timeout 40m
+
+            printf 'Stapling DMG: %s\n' "$dmg"
+            xcrun stapler staple "$dmg"
+            xcrun stapler validate "$dmg"
+          done
+
+      - name: Collect artifact
+        run: |
+          mkdir -p ./artifacts/objects/
+          
+          if [[ $GITHUB_REF_TYPE =~ ^tag$ ]]; then
+            TAG=$GITHUB_REF_NAME
+          else
+            TAG=$GITHUB_SHA
+          fi
+
+          # copy gui bundle, gui is built without specific target
+          if [[ $GUI_TARGET =~ windows ]]; then
+              mv ./target/$GUI_TARGET/release/bundle/nsis/*.exe ./artifacts/objects/
+          elif [[ $GUI_TARGET =~ darwin ]]; then
+              mv ./target/$GUI_TARGET/release/bundle/dmg/*.dmg ./artifacts/objects/
+          elif [[ $GUI_TARGET =~ linux ]]; then
+              mv ./target/$GUI_TARGET/release/bundle/deb/*.deb ./artifacts/objects/
+              mv ./target/$GUI_TARGET/release/bundle/rpm/*.rpm ./artifacts/objects/
+              mv ./target/$GUI_TARGET/release/bundle/appimage/*.AppImage ./artifacts/objects/
+          fi
+
+          mv ./artifacts/objects/* ./artifacts/
+          rm -rf ./artifacts/objects/
+
+      - name: Archive artifact
+        uses: actions/upload-artifact@v5
+        with:
+          name: easytier-gui-${{ matrix.ARTIFACT_NAME }}
+          path: |
+            ./artifacts/*
+
+  gui-result:
+    runs-on: ubuntu-latest
+    needs: [ pre_job, check, build-gui ]
+    if: ${{ always() }}
+    steps:
+      - name: Mark result as failed
+        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
+        run: exit 1

.github/workflows/js.yml

@@ -0,0 +1,62 @@
+name: EasyTier JavaScript Hosts
+
+on:
+  push:
+    branches: ["develop", "main", "releases/**"]
+    paths:
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "easytier-core/**"
+      - "easytier-proto/**"
+      - "easytier-js/**"
+      - ".github/workflows/js.yml"
+  pull_request:
+    branches: ["develop", "main"]
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "easytier-core/**"
+      - "easytier-proto/**"
+      - "easytier-js/**"
+      - ".github/workflows/js.yml"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: 1.95
+          target: wasm32-wasip1
+          cache: false
+          rustflags: ''
+
+      - uses: arduino/setup-protoc@v3
+        with:
+          version: '35.1'
+          repo-token: ${{ github.token }}
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+
+      - uses: pnpm/action-setup@v5
+        with:
+          version: 10
+          run_install: false
+
+      - name: Install dependencies
+        run: pnpm --dir easytier-js install --frozen-lockfile
+
+      - name: Build and test
+        run: pnpm --dir easytier-js check

.github/workflows/mobile.yml

@@ -0,0 +1,164 @@
+name: EasyTier Mobile
+
+on:
+  workflow_dispatch:
+  push:
+    branches: ["develop", "main", "releases/**"]
+  pull_request:
+    branches: ["develop", "main"]
+    types: [opened, synchronize, reopened, ready_for_review]
+
+concurrency:
+  # A new PR or branch push must not cancel a full build.
+  group: ${{ github.workflow }}-${{ (github.event_name == 'workflow_dispatch' || startsWith(github.ref_name, 'releases/')) && 'full' || 'check' }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+
+defaults:
+  run:
+    # necessary for windows
+    shell: bash
+
+jobs:
+  pre_job:
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    env:
+      RELEVANT_PATHS: >-
+        ["Cargo.toml", "Cargo.lock", "rust-toolchain.toml", ".cargo/**",
+        "pnpm-lock.yaml", "pnpm-workspace.yaml", "package.json", "easytier/**",
+        "easytier-core/**", "easytier-proto/**", "easytier-rpc-build/**",
+        "easytier-gui/**", "tauri-plugin-vpnservice/**",
+        "easytier-web/frontend-lib/**", ".github/workflows/mobile.yml",
+        ".github/actions/**"]
+    outputs:
+      full_build: ${{ github.event_name == 'workflow_dispatch' || startsWith(github.ref_name, 'releases/') }}
+      # Release builds must run even if they only change release metadata.
+      should_skip: >-
+        ${{
+          (
+            steps.skip_check.outputs.should_skip == 'true' ||
+            (
+              github.event_name == 'pull_request' &&
+              steps.path_filter.outputs.relevant != 'true'
+            )
+          ) &&
+          github.event_name != 'workflow_dispatch' &&
+          !startsWith(github.ref_name, 'releases/')
+        }}
+    steps:
+      - id: skip_check
+        if: github.event_name != 'workflow_dispatch' && !startsWith(github.ref_name, 'releases/')
+        uses: fkirc/skip-duplicate-actions@v5
+        with:
+          concurrent_skipping: 'same_content_newer'
+          skip_after_successful_duplicate: 'true'
+          paths: ${{ env.RELEVANT_PATHS }}
+
+      - id: path_filter
+        if: >-
+          github.event_name == 'pull_request' &&
+          steps.skip_check.outputs.should_skip != 'true'
+        uses: dorny/paths-filter@v4
+        with:
+          filters: |
+            relevant: ${{ env.RELEVANT_PATHS }}
+
+  build-mobile:
+    strategy:
+      fail-fast: true
+      matrix:
+        ARCH: ${{ fromJSON(needs.pre_job.outputs.full_build == 'true' && '["aarch64", "armv7", "i686", "x86_64"]' || '["aarch64"]') }}
+    runs-on: ubuntu-latest
+    env:
+      NAME: easytier
+      TARGET: ${{ matrix.ARCH == 'armv7' && 'armv7-linux-androideabi' || format('{0}-linux-android', matrix.ARCH) }}
+      ARCH: ${{ matrix.ARCH }}
+      OSS_BUCKET: ${{ secrets.ALIYUN_OSS_BUCKET }}
+    needs: pre_job
+    if: needs.pre_job.outputs.should_skip != 'true'    
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set current ref as env variable
+        run: |
+          echo "GIT_DESC=$(git log -1 --format=%cd.%h --date=format:%Y-%m-%d_%H:%M:%S)" >> $GITHUB_ENV
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: 'oracle'
+          java-version: '21'
+
+      - name: Setup Android SDK
+        uses: android-actions/setup-android@v3
+        with:
+          cmdline-tools-version: '11076708'
+          packages: 'build-tools;34.0.0 ndk;26.0.10792818 platform-tools platforms;android-34 '
+
+      - name: Setup Android Environment
+        run: |
+          echo "$ANDROID_HOME/platform-tools" >> $GITHUB_PATH
+          echo "$ANDROID_HOME/ndk/26.0.10792818/toolchains/llvm/prebuilt/linux-x86_64/bin" >> $GITHUB_PATH
+          echo "NDK_HOME=$ANDROID_HOME/ndk/26.0.10792818/" >> $GITHUB_ENV
+
+      - name: Prepare build environment
+        uses: ./.github/actions/prepare-build
+        with:
+          target: ${{ env.TARGET }}
+          gui: false
+          pnpm: true
+          pnpm-build-filter: easytier-gui...
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          # The prefix cache key, this can be changed to start a new cache manually.
+          # default: "v0-rust"
+          prefix-key: ""
+          shared-key: mobile-${{ env.TARGET }}-${{ needs.pre_job.outputs.full_build }}
+          cache-targets: "true"
+          save-if: ${{ github.event_name != 'pull_request' }}
+
+      - name: Check Android ARM64
+        if: needs.pre_job.outputs.full_build != 'true'
+        run: cargo check --locked --lib --target "$TARGET" --package easytier-gui --features custom-protocol
+
+      - name: Build
+        if: needs.pre_job.outputs.full_build == 'true'
+        run: |
+          cd easytier-gui
+          pnpm tauri android build --apk --target "$ARCH" --split-per-abi
+
+      - name: Collect artifact
+        if: needs.pre_job.outputs.full_build == 'true'
+        run: |
+          mkdir -p ./artifacts/objects/
+          mv easytier-gui/src-tauri/gen/android/app/build/outputs/apk/*/release/*.apk ./artifacts/objects/
+          
+          if [[ $GITHUB_REF_TYPE =~ ^tag$ ]]; then
+            TAG=$GITHUB_REF_NAME
+          else
+            TAG=$GITHUB_SHA
+          fi
+
+          mv ./artifacts/objects/* ./artifacts/
+          rm -rf ./artifacts/objects/
+
+      - name: Archive artifact
+        if: needs.pre_job.outputs.full_build == 'true'
+        uses: actions/upload-artifact@v5
+        with:
+          name: easytier-mobile-android-${{ matrix.ARCH }}
+          path: |
+            ./artifacts/*
+
+  mobile-result:
+    runs-on: ubuntu-latest
+    needs: [ pre_job, build-mobile ]
+    if: ${{ always() }}
+    steps:
+      - name: Mark result as failed
+        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
+        run: exit 1

.github/workflows/nightly-release.yml

@@ -0,0 +1,104 @@
+name: EasyTier Nightly Release
+
+on:
+  workflow_call:
+    inputs:
+      sha:
+        description: Commit whose full builds the caller has waited for
+        required: true
+        type: string
+  workflow_run:
+    workflows: [EasyTier Core, EasyTier GUI, EasyTier Mobile, EasyTier Test]
+    branches: [main]
+    types: [completed]
+  workflow_dispatch:
+
+concurrency:
+  group: easytier-nightly-release
+  cancel-in-progress: false
+
+permissions:
+  actions: read
+  contents: write
+
+jobs:
+  release:
+    if: >-
+      ((github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') &&
+       github.ref == 'refs/heads/main') ||
+      (github.event.workflow_run.event == 'workflow_dispatch' &&
+       github.event.workflow_run.conclusion == 'success' &&
+       github.event.workflow_run.head_repository.full_name == github.repository)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: main
+
+      - name: Select complete main builds and prepare release notes
+        id: prepare
+        uses: actions/github-script@v8
+        env:
+          BUILD_SHA: ${{ inputs.sha }}
+        with:
+          script: |
+            const fs = require('node:fs');
+            const { prepare } = require('./.github/scripts/nightly-release.js');
+            const build = await prepare({ github, context, core, sha: process.env.BUILD_SHA });
+            if (!build) return;
+            fs.writeFileSync('nightly-release.json', JSON.stringify(build));
+            for (const workflow of ['core', 'gui', 'mobile']) {
+              core.setOutput(`${workflow}_run_id`, build.runs[workflow]);
+              core.setOutput(`${workflow}_artifact_ids`, build.artifacts[workflow].map(a => a.id).join(','));
+              // download-artifact extracts a single artifact directly into path.
+              const suffix = build.artifacts[workflow].length === 1 ? `/${build.artifacts[workflow][0].name}` : '';
+              core.setOutput(`${workflow}_path`, `nightly-artifacts${suffix}`);
+            }
+            core.setOutput('ready', 'true');
+
+      - name: Download Core artifacts
+        if: steps.prepare.outputs.ready == 'true'
+        uses: actions/download-artifact@v5
+        with:
+          github-token: ${{ github.token }}
+          run-id: ${{ steps.prepare.outputs.core_run_id }}
+          artifact-ids: ${{ steps.prepare.outputs.core_artifact_ids }}
+          path: ${{ steps.prepare.outputs.core_path }}
+
+      - name: Download GUI artifacts
+        if: steps.prepare.outputs.ready == 'true'
+        uses: actions/download-artifact@v5
+        with:
+          github-token: ${{ github.token }}
+          run-id: ${{ steps.prepare.outputs.gui_run_id }}
+          artifact-ids: ${{ steps.prepare.outputs.gui_artifact_ids }}
+          path: ${{ steps.prepare.outputs.gui_path }}
+
+      - name: Download Mobile artifacts
+        if: steps.prepare.outputs.ready == 'true'
+        uses: actions/download-artifact@v5
+        with:
+          github-token: ${{ github.token }}
+          run-id: ${{ steps.prepare.outputs.mobile_run_id }}
+          artifact-ids: ${{ steps.prepare.outputs.mobile_artifact_ids }}
+          path: ${{ steps.prepare.outputs.mobile_path }}
+
+      - name: Package assets like version releases
+        if: steps.prepare.outputs.ready == 'true'
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const fs = require('node:fs');
+            const { packageAssets } = require('./.github/scripts/nightly-release.js');
+            const build = require(`${process.env.GITHUB_WORKSPACE}/nightly-release.json`);
+            await packageAssets({ build, source: 'nightly-artifacts', directory: 'nightly-assets' });
+            fs.writeFileSync('nightly-release.json', JSON.stringify(build));
+
+      - name: Update the fixed nightly prerelease
+        if: steps.prepare.outputs.ready == 'true'
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const { publish } = require('./.github/scripts/nightly-release.js');
+            const build = require(`${process.env.GITHUB_WORKSPACE}/nightly-release.json`);
+            await publish({ github, context, core, build, directory: 'nightly-assets' });

.github/workflows/nightly-retry.yml

@@ -0,0 +1,28 @@
+name: EasyTier Nightly Retry
+
+on:
+  workflow_run:
+    workflows: [EasyTier Core, EasyTier GUI, EasyTier Mobile, EasyTier Test]
+    branches: [main]
+    types: [completed]
+
+permissions:
+  actions: write
+
+jobs:
+  retry:
+    if: >-
+      github.event.workflow_run.event == 'workflow_dispatch' &&
+      github.event.workflow_run.conclusion == 'failure' &&
+      github.event.workflow_run.run_attempt == 1 &&
+      github.event.workflow_run.head_repository.full_name == github.repository
+    runs-on: ubuntu-latest
+    steps:
+      - name: Retry failed jobs once
+        uses: actions/github-script@v8
+        with:
+          script: |
+            await github.rest.actions.reRunWorkflowFailedJobs({
+              ...context.repo,
+              run_id: context.payload.workflow_run.id,
+            });

.github/workflows/nightly.yml

@@ -0,0 +1,42 @@
+name: EasyTier Nightly
+
+on:
+  schedule:
+    # 03:17 Asia/Shanghai; avoid the busy start of the hour.
+    - cron: '17 19 * * *'
+  workflow_dispatch:
+
+concurrency:
+  group: easytier-nightly
+  cancel-in-progress: false
+
+permissions:
+  actions: write
+  contents: read
+
+jobs:
+  dispatch:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 180
+    outputs:
+      sha: ${{ steps.build.outputs.sha }}
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Build main and wait for successful results
+        id: build
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const dispatch = require('./.github/scripts/nightly-build.js');
+            core.setOutput('sha', await dispatch({ github, context, core }));
+
+  release:
+    needs: dispatch
+    permissions:
+      actions: read
+      contents: write
+    uses: ./.github/workflows/nightly-release.yml
+    with:
+      sha: ${{ needs.dispatch.outputs.sha }}

.github/workflows/nix.yml

@@ -0,0 +1,44 @@
+name: Nix Check
+
+on:
+  push:
+    branches: ["main", "develop"]
+    paths:
+      - "**/*.nix"
+      - "flake.lock"
+      - "rust-toolchain.toml"
+  pull_request:
+    branches: ["main", "develop"]
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - "**/*.nix"
+      - "flake.lock"
+      - "rust-toolchain.toml"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check-full-shell:
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v27
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+
+      - name: Magic Nix Cache
+        uses: DeterminateSystems/magic-nix-cache-action@v6
+
+      - name: Warm up full devShell
+        run: nix develop .#full --command true
+
+      - name: Cargo check in flake environment
+        run: nix develop .#full --command cargo check
+
+      - name: Cargo build in flake environment
+        run: nix develop .#full --command cargo build

.github/workflows/ohos.yml

@@ -0,0 +1,264 @@
+name: ohos
+
+on:
+  push:
+    branches: [develop, main, "releases/**", "ohos/**"]
+    tags:
+      - "v*"
+      - "!*-pre"
+  pull_request:
+    branches: [develop, main, "ohos/**"]
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "rust-toolchain.toml"
+      - ".cargo/**"
+      - "easytier/**"
+      - "easytier-core/**"
+      - "easytier-proto/**"
+      - "easytier-rpc-build/**"
+      - "easytier-contrib/easytier-ohrs/**"
+      - ".github/workflows/ohos.yml"
+      - ".github/actions/**"
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: Publish this non-main branch and dispatch downstream builds
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  actions: write
+  contents: read
+  pull-requests: read
+
+env:
+  CARGO_TERM_COLOR: always
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  pre_job:
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    outputs:
+      should_skip: ${{ steps.skip_check.outputs.should_skip == 'true' && github.ref_type != 'tag' && github.ref_name != 'main' && !startsWith(github.ref_name, 'releases/') }}
+    steps:
+      - id: skip_check
+        uses: fkirc/skip-duplicate-actions@v5
+        with:
+          concurrent_skipping: 'same_content_newer'
+          skip_after_successful_duplicate: 'true'
+          cancel_others: 'true'
+          paths: '["Cargo.toml", "Cargo.lock", "rust-toolchain.toml", ".cargo/**", "easytier/**", "easytier-core/**", "easytier-proto/**", "easytier-contrib/easytier-ohrs/**", ".github/workflows/ohos.yml", ".github/actions/**"]'
+
+  ohos:
+    name: ohos
+    needs: pre_job
+    if: needs.pre_job.outputs.should_skip != 'true'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Set up Rust
+        uses: ./.github/actions/prepare-build
+        with:
+          target: aarch64-unknown-linux-ohos
+          gui: false
+          pnpm: false
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up HarmonyOS
+        uses: ErBWs/setup-ohos@v1
+
+      - name: Install ohrs
+        if: github.event_name != 'pull_request'
+        uses: taiki-e/install-action@v2
+        with:
+          tool: ohrs
+
+      - name: Prepare OHOS tools
+        run: |
+          set -euo pipefail
+          sudo apt-get install -qqy \
+            pkg-config curl libgl1-mesa-dev expect llvm clang lldb lld
+          rustup component add rustfmt
+
+          sudo mkdir -p "$OHOS_NDK_HOME/native/llvm"
+          sudo tee "$OHOS_NDK_HOME/native/llvm/aarch64-unknown-linux-ohos-clang.sh" >/dev/null <<'EOF'
+          #!/bin/sh
+          exec "$OHOS_NDK_HOME/native/llvm/bin/clang" \
+            -target aarch64-linux-ohos \
+            --sysroot="$OHOS_NDK_HOME/native/sysroot" \
+            -D__MUSL__ "$@"
+          EOF
+          sudo chmod +x \
+            "$OHOS_NDK_HOME/native/llvm/aarch64-unknown-linux-ohos-clang.sh"
+
+      - name: Check formatting
+        run: |
+          cargo fmt --all --manifest-path \
+            easytier-contrib/easytier-ohrs/Cargo.toml -- --check
+
+      - name: Test OHOS bridge
+        run: |
+          cargo test --locked --manifest-path \
+            easytier-contrib/easytier-ohrs/Cargo.toml \
+            -p easytier-ohos-core -p easytier-ohos-features \
+            --lib -- --test-threads=1
+
+      - name: Check OHOS bindings
+        run: |
+          cargo check --locked --manifest-path \
+            easytier-contrib/easytier-ohrs/Cargo.toml \
+            -p easytier-ohrs --tests
+
+      - name: Check OHOS target
+        if: github.event_name == 'pull_request'
+        working-directory: easytier-contrib/easytier-ohrs
+        run: |
+          source env.sh
+          cargo check --locked -p easytier-ohrs --tests \
+            --target aarch64-unknown-linux-ohos
+
+      - name: Build HAR
+        if: github.event_name != 'pull_request'
+        id: package
+        env:
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          set -euo pipefail
+          cargo_version=$(cargo metadata --format-version 1 --no-deps \
+            --manifest-path easytier/Cargo.toml | jq -r '.packages[0].version')
+          # Rolling tags such as nightly are not package versions.
+          last_tag=$(git describe --tags --match 'v[0-9]*' --abbrev=0 HEAD 2>/dev/null || true)
+          if [ -n "$last_tag" ]; then
+            base_version=$(printf '%s\n' "$cargo_version" "${last_tag#v}" \
+              | sort -V | tail -n 1)
+            commit_count=$(git rev-list --count "$last_tag..HEAD")
+          else
+            base_version=$cargo_version
+            commit_count=0
+          fi
+
+          source_branch=${GITHUB_HEAD_REF:-}
+          if [ -z "$source_branch" ]; then
+            if [ "$GITHUB_REF_TYPE" = branch ]; then
+              source_branch=$GITHUB_REF_NAME
+            else
+              source_branch=${DEFAULT_BRANCH:-main}
+            fi
+          fi
+          branch_id=$(printf '%s' "$source_branch" \
+            | tr '[:upper:]' '[:lower:]' \
+            | sed -E 's/[^a-z0-9-]+/-/g; s/^-+//; s/-+$//' \
+            | cut -c1-64)
+          branch_id=${branch_id:-main}
+
+          package_name=easytier-ohrs
+          package_version="${base_version}-${branch_id}-${commit_count}-${GITHUB_RUN_NUMBER}-${GITHUB_RUN_ATTEMPT}-g$(git rev-parse --short=8 HEAD)"
+          echo "name=$package_name" >> "$GITHUB_OUTPUT"
+          echo "EASYTIER_PACKAGE_NAME=$package_name" >> "$GITHUB_ENV"
+          echo "EASYTIER_VERSION=$package_version" >> "$GITHUB_ENV"
+
+          package_dir=easytier-contrib/easytier-ohrs/package
+          jq --arg name "$package_name" --arg version "$package_version" \
+            '.name = $name | .version = $version' \
+            "$package_dir/oh-package.json5" > "$package_dir/oh-package.tmp.json5"
+          mv "$package_dir/oh-package.tmp.json5" "$package_dir/oh-package.json5"
+          {
+            echo "## $package_name $package_version"
+            echo
+            echo "- Core version: $base_version"
+            echo "- Core commit: $GITHUB_SHA"
+            git log -1 --pretty=format:'- %s'
+            echo
+          } > "$package_dir/CHANGELOG.md"
+
+          cd easytier-contrib/easytier-ohrs
+          source env.sh
+          ohrs build --release --arch aarch
+          ohrs artifact
+          mv package.har "$package_name.har"
+
+      - name: Upload HAR
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-artifact@v5
+        with:
+          name: ${{ steps.package.outputs.name }}
+          path: easytier-contrib/easytier-ohrs/${{ steps.package.outputs.name }}.har
+          retention-days: 5
+          if-no-files-found: error
+
+      - name: Publish and dispatch
+        if: >-
+          (github.event_name == 'push' &&
+           github.ref_type == 'branch' &&
+           github.ref_name == 'main' &&
+           github.event.forced != true) ||
+          (github.event_name == 'workflow_dispatch' &&
+           github.ref_type == 'branch' &&
+           (github.ref_name == 'main' || inputs.publish))
+        working-directory: easytier-contrib/easytier-ohrs
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CODEARTS_PRIVATE_OHPM: ${{ secrets.CODEARTS_PRIVATE_OHPM }}
+          DOWNSTREAM_DISPATCH_TOKEN: ${{ secrets.DOWNSTREAM_DISPATCH_TOKEN }}
+        run: |
+          set -euo pipefail
+          if [ "$GITHUB_EVENT_NAME" = push ]; then
+            pull_requests=$(gh api \
+              -H "Accept: application/vnd.github+json" \
+              "/repos/$GITHUB_REPOSITORY/commits/$GITHUB_SHA/pulls")
+            if ! jq -e \
+              --arg repository "$GITHUB_REPOSITORY" \
+              --arg branch "$GITHUB_REF_NAME" \
+              --arg sha "$GITHUB_SHA" \
+              'any(.[];
+                .merged_at != null and
+                .base.repo.full_name == $repository and
+                .base.ref == $branch and
+                .merge_commit_sha == $sha)' \
+              <<< "$pull_requests" >/dev/null; then
+              echo "Direct push: HAR built without publishing."
+              exit 0
+            fi
+          fi
+
+          mkdir -p "$HOME/.ohpm"
+          umask 077
+          printf '%s' "$CODEARTS_PRIVATE_OHPM" > "$HOME/.ohpm/.ohpmrc"
+          trap 'rm -f "$HOME/.ohpm/.ohpmrc"' EXIT
+          ohpm publish "$EASYTIER_PACKAGE_NAME.har"
+
+          payload=$(jq -nc \
+            --arg repository "$GITHUB_REPOSITORY" \
+            --arg ref "refs/heads/$GITHUB_REF_NAME" \
+            --arg package "$EASYTIER_PACKAGE_NAME" \
+            '{
+              event_type: "core-har-published",
+              client_payload: {
+                core_repository: $repository,
+                core_ref: $ref,
+                package_name: $package
+              }
+            }')
+          for repository in \
+            FrankHan052176/EasyTier-ArkTS \
+            FrankHan052176/easytier-pro-app; do
+            curl --fail-with-body --silent --show-error \
+              -X POST \
+              -H "Accept: application/vnd.github+json" \
+              -H "Authorization: Bearer $DOWNSTREAM_DISPATCH_TOKEN" \
+              -H "X-GitHub-Api-Version: 2022-11-28" \
+              "$GITHUB_API_URL/repos/$repository/dispatches" \
+              --data "$payload"
+          done

.github/workflows/release.yml

@@ -0,0 +1,107 @@
+name: EasyTier Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      core_run_id:
+        description: 'The run id of EasyTier-Core Action in EasyTier repo'
+        type: number
+        required: true
+      gui_run_id:
+        description: 'The run id of EasyTier-GUI Action in EasyTier repo'
+        type: number
+        required: true
+      mobile_run_id:
+        description: 'The run id of EasyTier-Mobile Action in EasyTier repo'
+        type: number
+        required: true
+      version:
+        description: 'Version for this release'
+        type: string
+        default: 'v2.7.0'
+        required: true
+      make_latest:
+        description: 'Mark this release as latest'
+        type: boolean
+        default: true
+        required: true
+
+permissions:
+  actions: read
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Validate complete builds
+        uses: actions/github-script@v8
+        env:
+          CORE_RUN_ID: ${{ inputs.core_run_id }}
+          GUI_RUN_ID: ${{ inputs.gui_run_id }}
+          MOBILE_RUN_ID: ${{ inputs.mobile_run_id }}
+        with:
+          script: |
+            const validate = require('./.github/scripts/validate-release-builds.js');
+            await validate({ github, context, core });
+
+      - name: Download Core Artifact
+        uses: dawidd6/action-download-artifact@v11
+        with:
+          github_token: ${{secrets.GITHUB_TOKEN}}
+          run_id: ${{ inputs.core_run_id }}
+          repo: ${{ github.repository }}
+          path: release_assets
+
+      - name: Download GUI Artifact
+        uses: dawidd6/action-download-artifact@v11
+        with:
+          github_token: ${{secrets.GITHUB_TOKEN}}
+          run_id: ${{ inputs.gui_run_id }}
+          repo: ${{ github.repository }}
+          path: release_assets_nozip
+
+      - name: Download Mobile Artifact
+        uses: dawidd6/action-download-artifact@v11
+        with:
+          github_token: ${{secrets.GITHUB_TOKEN}}
+          run_id: ${{ inputs.mobile_run_id }}
+          repo: ${{ github.repository }}
+          path: release_assets_nozip
+
+      - name: Zip release assets
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          mkdir zipped_assets
+
+          find release_assets_nozip -type f -exec mv {} zipped_assets \;
+          ls -l -R ./zipped_assets
+
+          cd release_assets
+          ls -l -R ./
+          chmod -R 755 .
+          for x in `ls`; do
+            if [ "$x" = "Easytier-Magisk" ]; then
+              # for Easytier-Magisk, make sure files are in the root of the zip
+              cd $x;
+              zip -r ../../zipped_assets/$x-${VERSION}.zip .;
+              cd ..;
+            else
+              zip -r ../zipped_assets/$x-${VERSION}.zip $x;
+            fi
+          done
+
+      - name: Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: ${{ inputs.version }}
+          draft: true
+          files: |
+            ./zipped_assets/*
+          token: ${{ secrets.GITHUB_TOKEN }}
+          tag_name: ${{ inputs.version }}

.github/workflows/rust.yml

@@ -1,151 +0,0 @@
-name: Rust
-
-on:
-  push:
-    branches: [ "develop", "main" ]
-  pull_request:
-    branches: [ "develop", "main" ]
-
-env:
-  CARGO_TERM_COLOR: always
-
-defaults:
-  run:
-    # necessary for windows
-    shell: bash
-
-jobs:
-  build:
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - TARGET: aarch64-unknown-linux-musl
-            OS: ubuntu-latest
-          - TARGET: x86_64-unknown-linux-musl
-            OS: ubuntu-latest
-          - TARGET: x86_64-apple-darwin
-            OS: macos-latest
-          - TARGET: aarch64-apple-darwin
-            OS: macos-latest
-          - TARGET: x86_64-pc-windows-msvc
-            OS: windows-latest
-    runs-on: ${{ matrix.OS }}
-    env:
-      NAME: easytier
-      TARGET: ${{ matrix.TARGET }}
-      OS: ${{ matrix.OS }}
-    steps:
-    - uses: actions/checkout@v3
-    - name: Setup protoc
-      uses: arduino/setup-protoc@v2
-      with:
-         # GitHub repo token to use to avoid rate limiter
-        repo-token: ${{ secrets.GITHUB_TOKEN }}
-    - name: Cargo cache
-      uses: actions/cache@v4.0.0
-      with:
-        path: |
-          ~/.cargo
-          ./target
-        key: build-cargo-registry-${{matrix.TARGET}}
-    - name: Install rust target
-      run: |
-        # dependencies are only needed on ubuntu as that's the only place where
-        # we make cross-compilation
-        if [[ $OS =~ ^ubuntu.*$ ]]; then
-          sudo apt-get update && sudo apt-get install -qq crossbuild-essential-arm64 crossbuild-essential-armhf musl-tools
-          #  curl -s musl.cc | grep mipsel
-          case $TARGET in 
-            mipsel-unknown-linux-musl)
-              MUSL_URI=mipsel-linux-musl-cross
-              ;;
-            aarch64-unknown-linux-musl)
-              MUSL_URI=aarch64-linux-musl-cross
-              ;;
-            armv7-unknown-linux-musleabihf)
-              MUSL_URI=armv7l-linux-musleabihf-cross
-              ;;   
-            arm-unknown-linux-musleabihf)
-              MUSL_URI=arm-linux-musleabihf-cross
-              ;;        
-            mips-unknown-linux-musl)
-              MUSL_URI=mips-linux-musl-cross
-              ;;
-          esac
-        
-          if [  -n "$MUSL_URI" ]; then
-            mkdir -p ./musl_gcc 
-            wget -c https://musl.cc/$MUSL_URI.tgz -P ./musl_gcc/
-            tar zxf ./musl_gcc/$MUSL_URI.tgz -C ./musl_gcc/
-            sudo ln -s $(pwd)/musl_gcc/$MUSL_URI/bin/*gcc /usr/bin/
-          fi
-        fi
-        
-        # see https://github.com/rust-lang/rustup/issues/3709
-        rustup set auto-self-update disable
-        rustup install 1.75
-        rustup default 1.75
-        rustup target add $TARGET
-    - name: Run build
-      run: cargo build --release --verbose --target $TARGET
-    - name: Compress
-      run: |
-        mkdir -p ./artifacts/objects/
-        # windows is the only OS using a different convention for executable file name
-        if [[ $OS =~ ^windows.*$ ]]; then
-            SUFFIX=.exe
-            cp third_party/Packet.dll ./artifacts/objects/
-            cp third_party/wintun.dll ./artifacts/objects/
-        fi
-        if [[ $GITHUB_REF_TYPE =~ ^tag$ ]]; then
-          TAG=$GITHUB_REF_NAME
-        else
-          TAG=$GITHUB_SHA
-        fi
-        mv ./target/$TARGET/release/easytier-core"$SUFFIX" ./artifacts/objects/
-        mv ./target/$TARGET/release/easytier-cli"$SUFFIX" ./artifacts/objects/
-        tar -cvf ./artifacts/$NAME-$TARGET-$TAG.tar -C ./artifacts/objects/ .
-        rm -rf ./artifacts/objects/
-    - name: Archive artifact
-      uses: actions/upload-artifact@v4
-      with:
-        name: easytier-${{ matrix.OS }}-${{ matrix.TARGET }}
-        path: |
-          ./artifacts/*
-    - name: Upload OSS
-      uses: Menci/upload-to-oss@main
-      with:
-        access-key-id: ${{ secrets.ALIYUN_OSS_ACCESS_ID }}
-        access-key-secret: ${{ secrets.ALIYUN_OSS_ACCESS_KEY }}
-        endpoint: ${{ secrets.ALIYUN_OSS_ENDPOINT }}
-        bucket: ${{ secrets.ALIYUN_OSS_BUCKET }}
-        local-path: ./artifacts/
-        remote-path: /easytier-releases/${{ github.sha }}/
-        no-delete-remote-files: true
-        retry: 5
-        increment: true
-  test:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v3
-    - name: Setup protoc
-      uses: arduino/setup-protoc@v2
-      with:
-         # GitHub repo token to use to avoid rate limiter
-        repo-token: ${{ secrets.GITHUB_TOKEN }}
-    - name: Setup tools for test
-      run: sudo apt install bridge-utils
-    - name: Setup system for test
-      run: |
-        sudo sysctl net.bridge.bridge-nf-call-iptables=0
-        sudo sysctl net.bridge.bridge-nf-call-ip6tables=0
-    - name: Cargo cache
-      uses: actions/cache@v4.0.0
-      with:
-        path: |
-          ~/.cargo
-          ./target
-        key: build-cargo-registry-test
-    - name: Run tests
-      run: sudo -E env "PATH=$PATH" cargo test --verbose

.github/workflows/test.yml

@@ -0,0 +1,218 @@
+name: EasyTier Test
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ "develop", "main", "releases/**" ]
+  pull_request:
+    branches: [ "develop", "main" ]
+    types: [ opened, synchronize, reopened, ready_for_review ]
+
+concurrency:
+  # A new PR or branch push must not cancel a full build.
+  group: ${{ github.workflow }}-${{ (github.event_name == 'workflow_dispatch' || startsWith(github.ref_name, 'releases/')) && 'full' || 'check' }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+#  RUSTC_WRAPPER: "sccache"
+#  SCCACHE_GHA_ENABLED: "true"
+
+defaults:
+  run:
+    # necessary for windows
+    shell: bash
+
+jobs:
+  ci-scripts:
+    name: Test CI scripts
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+
+      - run: node --test .github/scripts/*.test.js
+
+  pre_job:
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    env:
+      RELEVANT_PATHS: >-
+        ["Cargo.toml", "Cargo.lock", "rust-toolchain.toml", ".cargo/**",
+        ".config/nextest.toml",
+        "pnpm-lock.yaml", "pnpm-workspace.yaml", "package.json", "easytier/**",
+        "easytier-core/**", "easytier-proto/**", "easytier-rpc-build/**",
+        "easytier-web/**", "easytier-gui/src-tauri/**",
+        "tauri-plugin-vpnservice/**", "easytier-contrib/**",
+        ".github/workflows/test.yml", ".github/actions/**"]
+    outputs:
+      full_build: ${{ github.event_name == 'workflow_dispatch' || startsWith(github.ref_name, 'releases/') }}
+      should_skip: >-
+        ${{
+          (
+            steps.skip_check.outputs.should_skip == 'true' ||
+            (
+              github.event_name == 'pull_request' &&
+              steps.path_filter.outputs.relevant != 'true'
+            )
+          ) &&
+          github.event_name != 'workflow_dispatch' &&
+          !startsWith(github.ref_name, 'releases/')
+        }}
+    steps:
+      - id: skip_check
+        if: github.event_name != 'workflow_dispatch' && !startsWith(github.ref_name, 'releases/')
+        uses: fkirc/skip-duplicate-actions@v5
+        with:
+          concurrent_skipping: 'never'
+          skip_after_successful_duplicate: 'true'
+          paths: ${{ env.RELEVANT_PATHS }}
+
+      - id: path_filter
+        if: >-
+          github.event_name == 'pull_request' &&
+          steps.skip_check.outputs.should_skip != 'true'
+        uses: dorny/paths-filter@v4
+        with:
+          filters: |
+            relevant: ${{ env.RELEVANT_PATHS }}
+
+  check:
+    name: Run linters & check
+    runs-on: ubuntu-latest
+    needs: pre_job
+    if: needs.pre_job.outputs.should_skip != 'true'
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Prepare build environment
+        uses: ./.github/actions/prepare-build
+        with:
+          gui: true
+          pnpm: ${{ needs.pre_job.outputs.full_build == 'true' }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          components: rustfmt,clippy
+          target: wasm32-wasip1
+          cache: false
+          rustflags: ''
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: test-check
+          save-if: ${{ github.event_name != 'pull_request' }}
+
+      - uses: taiki-e/install-action@cargo-hack
+        if: needs.pre_job.outputs.full_build == 'true'
+
+      - name: Check formatting
+        if: ${{ !cancelled() }}
+        run: cargo fmt --all -- --check
+
+      - name: Check Clippy
+        if: ${{ !cancelled() }}
+        run: cargo clippy --all-targets --features full --all -- -D warnings
+
+      - name: Check features
+        if: ${{ !cancelled() && needs.pre_job.outputs.full_build == 'true' }}
+        run: cargo hack check --package easytier --each-feature --exclude-features macos-ne --verbose
+
+      - name: Check WASI
+        if: ${{ !cancelled() }}
+        run: >-
+          cargo check --package easytier-core --lib --target wasm32-wasip1
+          --features management-rpc,proxy-smoltcp-stack,ring-crypto,wasi-crypto-offload
+
+      - name: Check Cargo.lock is up to date
+        if: ${{ !cancelled() }}
+        run: |
+          if ! cargo metadata --format-version 1 --locked > /dev/null; then
+            echo "::error::Cargo.lock is out of date. Run cargo generate-lockfile or cargo build locally, then commit Cargo.lock."
+            exit 1
+          fi
+
+  pre-test:
+    name: Build test
+    runs-on: ubuntu-latest
+    needs: pre_job
+    if: needs.pre_job.outputs.should_skip != 'true'
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Prepare build environment
+        uses: ./.github/actions/prepare-build
+        with:
+          gui: false
+          pnpm: false
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: Swatinem/rust-cache@v2
+
+      - uses: taiki-e/install-action@nextest
+
+      - name: Archive test
+        run: >-
+          cargo nextest archive --archive-file tests.tar.zst
+          --package easytier --package easytier-core --features full
+
+      - uses: actions/upload-artifact@v5
+        with:
+          name: tests
+          path: tests.tar.zst
+          retention-days: 1
+
+  run-tests:
+    name: Run tests
+    runs-on: ubuntu-latest
+    needs: [ pre_job, pre-test ]
+    if: needs.pre_job.outputs.should_skip != 'true'
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup tools for test
+        run: sudo apt install bridge-utils
+      - name: Setup upnpd for test
+        run: |
+          sudo apt-get update
+          sudo DEBIAN_FRONTEND=noninteractive apt-get install -y miniupnpd miniupnpd-iptables iptables
+
+      - name: Setup system for test
+        run: |
+          sudo modprobe br_netfilter
+          sudo modprobe tun
+          if [ ! -e /dev/net/tun ]; then
+            sudo mkdir -p /dev/net
+            sudo mknod /dev/net/tun c 10 200
+          fi
+          sudo sysctl net.bridge.bridge-nf-call-iptables=0
+          sudo sysctl net.bridge.bridge-nf-call-ip6tables=0
+          sudo sysctl net.ipv6.conf.lo.disable_ipv6=0
+          sudo ip addr add 2001:db8::2/64 dev lo
+
+      - uses: taiki-e/install-action@nextest
+
+      - name: Download tests
+        uses: actions/download-artifact@v4
+        with:
+          name: tests
+
+      - name: Run tests
+        run: |
+          sudo prlimit --pid $$ --nofile=1048576:1048576
+          sudo -E env "PATH=$PATH" EASYTIER_LINUX_BPF_INTEGRATION=required \
+            cargo nextest run --archive-file tests.tar.zst --profile ci --no-fail-fast
+
+  test:
+    runs-on: ubuntu-latest
+    needs: [ pre_job, ci-scripts, check, pre-test, run-tests ]
+    if: ${{ always() }}
+    steps:
+      - name: Mark result as failed
+        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
+        run: exit 1

.gitignore

@@ -4,10 +4,6 @@ debug/
 target/
 target-*/
 
-# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
-# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
-Cargo.lock
-
 # These are backup files generated by rustfmt
 **/*.rs.bk
 
@@ -15,6 +11,8 @@ Cargo.lock
 *.pdb
 
 .vscode
+/.idea
+/.direnv/
 
 # perf & flamegraph
 perf.data
@@ -24,3 +22,31 @@ flamegraph.svg
 root-target
 
 nohup.out
+
+.DS_Store
+
+components.d.ts
+
+musl_gcc
+
+# log
+easytier-panic.log
+
+# web
+node_modules
+easytier-web/frontend-lib/src/generated/
+easytier-web/config-generator/dist/
+easytier-web/config-generator/src/generated/
+
+.vite
+
+easytier-gui/src-tauri/*.dll
+easytier-gui/src-tauri/*.sys
+/easytier-contrib/easytier-ohrs/dist/
+
+.direnv
+.flake-profile
+
+# contrib
+go.sum
+.test-env/

CONTEXT.md

@@ -0,0 +1,132 @@
+# EasyTier Domain Context
+
+## Module layers
+
+`easytier-core` layers dependencies from `foundation` upward through the
+portable networking domains. `foundation` contains infrastructure Modules
+that have no dependency on a networking domain and may be used by any higher
+layer.
+
+## Operation broker
+
+An operation broker owns the lifecycle of asynchronous work submitted by an
+external caller to core. It allocates opaque operation IDs, arbitrates
+completion, cancellation, and disposal, retains terminal outcomes, and
+publishes a batch-drainable completion queue.
+
+The broker does not interpret operation kinds, outcomes, resources, wire
+formats, or domain errors. Each domain Module owns those semantics and composes
+the broker under the same lock as any state that must change atomically with an
+operation transition.
+
+Host capability operations use a separate seam. They turn Host readiness into
+Rust task wakeups and do not share the caller-to-core broker state machine.
+
+## Credential grant
+
+A credential grant contains the authorization constraints shared by generated,
+imported, managed, and attached-peer credentials: ACL groups, relay permission,
+allowed proxy CIDRs, and whether concurrent reuse is allowed. It does not own
+credential identity, key material, lifetime, persistence, or runtime ownership.
+Each credential intake path normalizes the grant before installing it.
+
+## Peer Relay advertisement
+
+A platform peer may prefer an eligible directly connected credential relay by
+omitting covered credential-leaf edges from only its own advertised OSPF
+connection row. Its local route calculation still uses the complete physical
+adjacency so direct-destination fallback remains available. Other peers'
+source-owned rows and versions are never rewritten, cached for promotion, or
+otherwise changed by this projection.
+
+Before a graceful Instance stop, the owner publishes a new-version empty
+connection row while keeping its physical adjacencies available for route
+synchronization. It waits for the current direct route Sessions to acknowledge
+that withdrawal up to a bounded deadline, then continues shutdown. Abrupt
+process loss cannot publish this withdrawal and retains the normal route
+expiry behavior.
+
+Relay eligibility comes from the transport-authenticated credential identity
+and grant, not self-reported route metadata. The advertisement Module does not
+support changing a credential's relay permission in place; such a permission
+change is a credential revocation and new authenticated Session.
+
+## Attached peer
+
+An attached peer is an ordinary `PeerManagerCore` connected to another
+`PeerManagerCore` through an authenticated in-process transport. Each
+authenticated portal client owns one complete peer manager. The managers are
+protocol peers; `attached` describes only the local transport and its trusted
+ingress provenance, not a parent/child peer role.
+
+An attached peer owns one complete IPv4 CIDR (for example `10.144.0.5/16`).
+Its address and advertised network are independent of the network manager's
+own static or DHCP address. A VPN portal derives the attached peer route and
+the external client's allowed network from that single CIDR; it does not infer
+either value from the portal-hosting instance.
+
+An external portal client uses that same IPv4 address on its native tunnel
+interface. The portal validates the source address and forwards IPv4 packets
+unchanged between the native tunnel and the attached peer; it does not assign
+a second tunnel-only address or perform address translation.
+
+Each manager owns its ACL execution state, route service, RPC endpoint, secure
+sessions, packet processing, and lifecycle. Portal code supplies raw packets
+and peer configuration but does not build, reload, or coordinate ACL filters.
+
+When the network manager uses Secure Mode, an attached peer authenticates as a
+credential peer. Its portal-owned, in-memory credential grant carries ACL
+groups and is revoked with the attached runtime; the peer never receives the
+network secret or ACL group secrets. A non-Secure-Mode network retains the
+legacy admin-attached identity for compatibility. A credential peer cannot host
+a portal because it cannot issue credential grants. Each live portal Session
+owns a fresh attached-peer identity, while the external client key remains
+stable across Sessions; a replacement Session must never reuse the previous
+non-reusable credential identity.
+
+## Compact compatibility Host
+
+A compact compatibility Host retains accepted values in the authoritative TOML
+model for management readback, while the shared host-aware normalization path
+omits capabilities that the compact runtime cannot execute. Omitted settings
+are silent no-ops and must not be advertised as live network capabilities.
+
+## Embedded logging
+
+Logging belongs to the WASI runtime, which installs its subscriber at module
+startup. The independent logger ABI and process-level `LoggerRpc` control
+the same module-wide level, including before any Instance exists. Instance
+configuration and lifecycle never initialize or reset logging. The Host owns
+the output sink through WASI stdout; output errors do not interrupt Core.
+
+## Web compatibility Host
+
+The Web compatibility Host runs the portable EasyTier guest in JavaScript
+runtimes that provide WebAssembly JSPI. Its shared runtime Module owns guest
+lifecycle, Host capability operations, data-plane resources, and WebSocket
+message handling. Browser and Cloudflare Adapters own only the platform-specific
+way that WebSockets are dialed or accepted and the matching guest artifact.
+
+The Browser Adapter is an outbound-only EasyTier instance with a smoltcp TCP
+data plane. The Cloudflare Adapter is an inbound-only relay hosted by one named
+Durable Object. Their public configuration exposes only capabilities each Host
+can execute; guest ABI details and serialized TOML remain internal.
+
+## Web configuration consumers
+
+Central network management and an external Console are alternative consumers
+of `ClientManager`. An external webhook selects Console mode; otherwise the
+central service registers devices through an in-process webhook handler and
+publishes each device's complete compiled configuration through the existing
+Full reconcile API. `ClientManager` owns persistence, offline replay, and
+runtime reconciliation without knowing central network business state.
+
+The central service owns network intent, device registration and bans, and
+Gateway runtimes. Central HTTP mutations and direct public configuration writes
+share its mutation lock so ownership checks cannot race with enrollment.
+Internal Console APIs retain their upstream behavior and central routes and
+publication workers are disabled in Console mode.
+
+Device deletion uses the upstream disconnect semantics: an already in-flight
+validation may register the device again. A persisted ban rejects subsequent
+validations. Deletion does not introduce device generations or session fences.

CONTRIBUTING.md

@@ -0,0 +1,236 @@
+# Contributing to EasyTier
+
+[中文版](CONTRIBUTING_zh.md)
+
+Thank you for your interest in contributing to EasyTier! This document provides guidelines and instructions for contributing to the project.
+
+## Table of Contents
+
+- [Development Environment Setup](#development-environment-setup)
+  - [Prerequisites](#prerequisites)
+  - [Installation Steps](#installation-steps)
+- [Project Structure](#project-structure)
+- [Build Guide](#build-guide)
+  - [Building Core](#building-core)
+  - [Building GUI](#building-gui)
+  - [Building Mobile](#building-mobile)
+- [Development Workflow](#development-workflow)
+- [Testing Guidelines](#testing-guidelines)
+- [Pull Request Guidelines](#pull-request-guidelines)
+- [Additional Resources](#additional-resources)
+
+## Development Environment Setup
+
+### Prerequisites
+
+#### Required Tools
+- Node.js v21 or higher
+- pnpm v9 or higher
+- Rust toolchain (version 1.95)
+- LLVM and Clang
+- Protoc (Protocol Buffers compiler)
+
+#### Platform-Specific Dependencies
+
+**Linux (Ubuntu/Debian)**
+```bash
+# Core build dependencies
+sudo apt-get update && sudo apt-get install -y \
+    musl-tools \
+    llvm \
+    clang \
+    protobuf-compiler
+
+# GUI build dependencies
+sudo apt install -y \
+    libwebkit2gtk-4.1-dev \
+    build-essential \
+    curl \
+    wget \
+    file \
+    libgtk-3-dev \
+    librsvg2-dev \
+    libxdo-dev \
+    libssl-dev \
+    libappindicator3-dev \
+    patchelf
+
+# Testing dependencies
+sudo apt install -y bridge-utils
+```
+
+**For Cross-Compilation**
+- musl-cross toolchain (for MIPS and other architectures)
+- Additional setup may be required (see `.github/workflows/` for details)
+
+**For Android Development**
+- Java 20
+- Android SDK (Build Tools 34.0.0)
+- Android NDK (26.0.10792818)
+
+### Installation Steps
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/EasyTier/EasyTier.git
+   cd EasyTier
+   ```
+
+2. Install dependencies:
+   ```bash
+   # Install Rust toolchain
+   rustup install 1.95
+   rustup default 1.95
+
+   # Install project dependencies
+   pnpm -r install
+   ```
+
+## Project Structure
+
+```
+easytier/          # Core functionality and libraries
+easytier-web/      # Web dashboard and frontend
+easytier-gui/      # Desktop GUI application
+.github/workflows/ # CI/CD configuration files
+```
+
+## Build Guide
+
+### Building Core
+
+```bash
+# Standard build
+cargo build --release
+
+# Platform-specific builds
+cargo build --release --target x86_64-unknown-linux-musl     # Linux x86_64
+cargo build --release --target aarch64-unknown-linux-musl    # Linux ARM64
+cargo build --release --target x86_64-apple-darwin           # macOS x86_64
+cargo build --release --target aarch64-apple-darwin          # macOS M1/M2
+cargo build --release --target x86_64-pc-windows-msvc        # Windows x86_64
+```
+
+Build artifacts: `target/[target-triple]/release/`
+
+### Building the WASI core
+
+```bash
+script/build-wasi-core.sh
+```
+
+This builds the `easytier-core` Go-host profile for `wasm32-wasip1`, then
+optimizes it with the pinned official Binaryen release. Binaryen is downloaded
+once into `target/binaryen/` and verified by SHA-256; set `WASM_OPT` to use an
+existing matching binary.
+
+### Building GUI
+
+```bash
+# 1. Build frontend
+pnpm -r build
+
+# 2. Build GUI application
+cd easytier-gui
+
+# Linux
+pnpm tauri build --target x86_64-unknown-linux-gnu
+
+# macOS
+pnpm tauri build --target x86_64-apple-darwin      # Intel
+pnpm tauri build --target aarch64-apple-darwin     # Apple Silicon
+
+# Windows
+pnpm tauri build --target x86_64-pc-windows-msvc   # x64
+```
+
+Build artifacts: `easytier-gui/src-tauri/target/release/bundle/`
+
+### Building Mobile
+
+```bash
+# 1. Install Android targets
+rustup target add aarch64-linux-android
+rustup target add armv7-linux-androideabi
+rustup target add i686-linux-android
+rustup target add x86_64-linux-android
+
+# 2. Build Android application
+cd easytier-gui
+pnpm tauri android build
+```
+
+Build artifacts: `easytier-gui/src-tauri/gen/android/app/build/outputs/apk/universal/release/`
+
+### Build Notes
+
+1. Cross-compilation for ARM/MIPS requires additional setup
+2. Windows builds need correct DLL files
+3. Check `.github/workflows/` for detailed build configurations
+
+## Development Workflow
+
+1. Create a feature branch from `develop`:
+   ```bash
+   git checkout develop
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Make your changes following our coding standards
+
+3. Write or update tests as needed
+
+4. Use conventional commit messages:
+   ```
+   feat: add new feature
+   fix: resolve bug
+   docs: update documentation
+   test: add tests
+   chore: update dependencies
+   ```
+
+5. Submit a pull request to `develop`
+
+## Testing Guidelines
+
+### Running Tests
+
+```bash
+# Configure system (Linux)
+sudo modprobe br_netfilter
+sudo sysctl net.bridge.bridge-nf-call-iptables=0
+sudo sysctl net.bridge.bridge-nf-call-ip6tables=0
+
+# Run tests
+cargo test --no-default-features --features=full --verbose
+```
+
+### Test Requirements
+
+- Write tests for new features
+- Maintain existing test coverage
+- Tests should be isolated and repeatable
+- Include both unit and integration tests
+
+## Pull Request Guidelines
+
+1. Target the `develop` branch
+2. Ensure all tests pass
+3. Include clear description and purpose
+4. Reference related issues
+5. Keep changes focused and atomic
+6. Update documentation as needed
+
+## Additional Resources
+
+- [Issue Tracker](https://github.com/EasyTier/EasyTier/issues)
+- [Project Documentation](https://github.com/EasyTier/EasyTier/wiki)
+
+## Questions or Need Help?
+
+Feel free to:
+- Open an issue for questions
+- Join our community discussions
+- Reach out to maintainers
+
+Thank you for contributing to EasyTier! 

CONTRIBUTING_zh.md

@@ -0,0 +1,233 @@
+# EasyTier 贡献指南
+
+[English Version](CONTRIBUTING.md)
+
+感谢您对 EasyTier 项目的关注！本文档提供了参与项目贡献的指南和说明。
+
+## 目录
+
+- [EasyTier 贡献指南](#easytier-贡献指南)
+  - [目录](#目录)
+  - [开发环境配置](#开发环境配置)
+    - [前置要求](#前置要求)
+      - [必需工具](#必需工具)
+      - [平台特定依赖](#平台特定依赖)
+    - [安装步骤](#安装步骤)
+  - [项目结构](#项目结构)
+  - [构建指南](#构建指南)
+    - [构建核心组件](#构建核心组件)
+    - [构建桌面应用](#构建桌面应用)
+    - [构建移动应用](#构建移动应用)
+    - [构建注意事项](#构建注意事项)
+  - [开发工作流](#开发工作流)
+  - [测试指南](#测试指南)
+    - [运行测试](#运行测试)
+    - [测试要求](#测试要求)
+  - [Pull Request 规范](#pull-request-规范)
+  - [其他资源](#其他资源)
+  - [需要帮助？](#需要帮助)
+
+## 开发环境配置
+
+### 前置要求
+
+#### 必需工具
+- Node.js v21 或更高版本
+- pnpm v9 或更高版本
+- Rust 工具链（版本 1.95）
+- LLVM 和 Clang
+- Protoc（Protocol Buffers 编译器）
+
+#### 平台特定依赖
+
+**Linux (Ubuntu/Debian)**
+```bash
+# 核心构建依赖
+sudo apt-get update && sudo apt-get install -y \
+    musl-tools \
+    llvm \
+    clang \
+    protobuf-compiler
+
+# GUI 构建依赖
+sudo apt install -y \
+    libwebkit2gtk-4.1-dev \
+    build-essential \
+    curl \
+    wget \
+    file \
+    libgtk-3-dev \
+    librsvg2-dev \
+    libxdo-dev \
+    libssl-dev \
+    libappindicator3-dev \
+    patchelf
+
+# 测试依赖
+sudo apt install -y bridge-utils
+```
+
+**交叉编译依赖**
+- musl-cross 工具链（用于 MIPS 和其他架构）
+- 可能需要额外配置（详见 `.github/workflows/` 目录）
+
+**Android 开发依赖**
+- Java 20
+- Android SDK（Build Tools 34.0.0）
+- Android NDK（26.0.10792818）
+
+### 安装步骤
+
+1. 克隆仓库：
+   ```bash
+   git clone https://github.com/EasyTier/EasyTier.git
+   cd EasyTier
+   ```
+
+2. 安装依赖：
+   ```bash
+   # 安装 Rust 工具链
+   rustup install 1.95
+   rustup default 1.95
+
+   # 安装项目依赖
+   pnpm -r install
+   ```
+
+## 项目结构
+
+```
+easytier/          # 核心功能和库
+easytier-web/      # Web 仪表盘和前端
+easytier-gui/      # 桌面 GUI 应用
+.github/workflows/ # CI/CD 配置文件
+```
+
+## 构建指南
+
+### 构建核心组件
+
+```bash
+# 标准构建
+cargo build --release
+
+# 特定平台构建
+cargo build --release --target x86_64-unknown-linux-musl     # Linux x86_64
+cargo build --release --target aarch64-unknown-linux-musl    # Linux ARM64
+cargo build --release --target x86_64-apple-darwin           # macOS x86_64
+cargo build --release --target aarch64-apple-darwin          # macOS M1/M2
+cargo build --release --target x86_64-pc-windows-msvc        # Windows x86_64
+```
+
+构建产物位置：`target/[target-triple]/release/`
+
+### 构建桌面应用
+
+```bash
+# 1. 构建前端
+pnpm -r build
+
+# 2. 构建 GUI 应用
+cd easytier-gui
+
+# Linux
+pnpm tauri build --target x86_64-unknown-linux-gnu
+
+# macOS
+pnpm tauri build --target x86_64-apple-darwin      # Intel
+pnpm tauri build --target aarch64-apple-darwin     # Apple Silicon
+
+# Windows
+pnpm tauri build --target x86_64-pc-windows-msvc   # x64
+```
+
+构建产物位置：`easytier-gui/src-tauri/target/release/bundle/`
+
+### 构建移动应用
+
+```bash
+# 1. 安装 Android 目标平台
+rustup target add aarch64-linux-android
+rustup target add armv7-linux-androideabi
+rustup target add i686-linux-android
+rustup target add x86_64-linux-android
+
+# 2. 构建 Android 应用
+cd easytier-gui
+pnpm tauri android build
+```
+
+构建产物位置：`easytier-gui/src-tauri/gen/android/app/build/outputs/apk/universal/release/`
+
+### 构建注意事项
+
+1. ARM/MIPS 的交叉编译需要额外配置
+2. Windows 构建需要正确的 DLL 文件
+3. 详细构建配置请参考 `.github/workflows/` 目录
+
+## 开发工作流
+
+1. 从 `develop` 分支创建特性分支：
+   ```bash
+   git checkout develop
+   git checkout -b feature/your-feature-name
+   ```
+
+2. 按照代码规范进行修改
+
+3. 编写或更新测试
+
+4. 使用规范的提交信息：
+   ```
+   feat: 添加新功能
+   fix: 修复问题
+   docs: 更新文档
+   test: 添加测试
+   chore: 更新依赖
+   ```
+
+5. 提交 Pull Request 到 `develop` 分支
+
+## 测试指南
+
+### 运行测试
+
+```bash
+# 配置系统（Linux）
+sudo modprobe br_netfilter
+sudo sysctl net.bridge.bridge-nf-call-iptables=0
+sudo sysctl net.bridge.bridge-nf-call-ip6tables=0
+
+# 运行测试
+cargo test --no-default-features --features=full --verbose
+```
+
+### 测试要求
+
+- 为新功能编写测试
+- 维护现有测试覆盖率
+- 测试应该是独立且可重复的
+- 包含单元测试和集成测试
+
+## Pull Request 规范
+
+1. 目标分支为 `develop`
+2. 确保所有测试通过
+3. 包含清晰的描述和目的
+4. 关联相关的 issues
+5. 保持变更的原子性和聚焦性
+6. 及时更新相关文档
+
+## 其他资源
+
+- [问题追踪](https://github.com/EasyTier/EasyTier/issues)
+- [项目文档](https://github.com/EasyTier/EasyTier/wiki)
+
+## 需要帮助？
+
+欢迎：
+- 提出问题
+- 参与社区讨论
+- 联系维护者
+
+感谢您为 EasyTier 做出贡献！ 

Cargo.toml

@@ -1,144 +1,119 @@
-[package]
-name = "easytier"
-description = "A full meshed p2p VPN, connecting all your devices in one network with one command."
-homepage = "https://github.com/KKRainbow/EasyTier"
-repository = "https://github.com/KKRainbow/EasyTier"
-version = "0.1.1"
-edition = "2021"
-authors = ["kkrainbow"]
-keywords = ["vpn", "p2p", "network", "easytier"]
-categories = ["network-programming", "command-line-utilities"]
-rust-version = "1.75"
-license-file = "LICENSE"
-readme = "README.md"
+[workspace]
+resolver = "2"
+members = [
+    "easytier-core",
+    "easytier-proto",
+    "easytier",
+    "easytier-web",
+    "easytier-gui/src-tauri",
+    "easytier-contrib/easytier-mini",
+    "easytier-contrib/easytier-ffi",
+    "easytier-contrib/easytier-uptime",
+    "easytier-contrib/easytier-android-jni",
+    "easytier-contrib/easytier-ios",
+    "easytier-contrib/easytier-ohrs", # it needs ohrs sdk
+    "easytier-contrib/easytier-ohrs/crates/*",
+]
+default-members = ["easytier", "easytier-web"]
+exclude = []
 
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+[workspace.package]
+edition = "2024"
+rust-version = "1.95"
 
-[[bin]]
-name = "easytier-core"
-path = "src/easytier-core.rs"
-
-[[bin]]
-name = "easytier-cli"
-path = "src/easytier-cli.rs"
-test = false
-
-[dependencies]
-tracing = { version = "0.1", features = ["log"] }
-tracing-subscriber = { version = "0.3", features = [
-    "env-filter",
-    "local-time",
-    "time",
-] }
-tracing-appender = "0.2.3"
-log = "0.4"
-thiserror = "1.0"
-auto_impl = "1.1.0"
-crossbeam = "0.8.4"
-time = "0.3"
-toml = "0.8.12"
-chrono = "0.4.35"
-
-gethostname = "0.4.3"
-
-futures = "0.3"
-
-tokio = { version = "1", features = ["full"] }
-tokio-stream = "0.1"
-tokio-util = { version = "0.7.9", features = ["codec", "net"] }
-
-async-stream = "0.3.5"
-async-trait = "0.1.74"
-
-dashmap = "5.5.3"
-timedmap = "1.0.1"
-
-# for tap device
-tun = { version = "0.6.1", features = ["async"] }
-# for net ns
-nix = { version = "0.27", features = ["sched", "socket", "ioctl"] }
-
-uuid = { version = "1.5.0", features = [
-    "v4",
-    "fast-rng",
-    "macro-diagnostics",
-    "serde",
-] }
-
-# for ring tunnel
-crossbeam-queue = "0.3"
-once_cell = "1.18.0"
-
-# for packet
-rkyv = { "version" = "0.7.42", features = [
-    "validation",
-    "archive_le",
-    "strict",
-    "copy_unsafe",
-    "arbitrary_enum_discriminant",
-] }
-postcard = { "version" = "1.0.8", features = ["alloc"] }
-
-# for rpc
-tonic = "0.10"
-prost = "0.12"
+[workspace.dependencies]
+optionize = "0.5"
+# Shared versions and sources; members select features and optional dependencies.
 anyhow = "1.0"
-tarpc = { version = "0.32", features = ["tokio1", "serde1"] }
-
-url = { version = "2.5", features = ["serde"] }
-
-# for tun packet
-byteorder = "1.5.0"
-
-# for proxy
-cidr = "0.2.2"
-socket2 = "0.5.5"
-
-# for hole punching
-stun_codec = "0.3.4"
-bytecodec = "0.4.15"
-rand = "0.8.5"
-
-serde = { version = "1.0", features = ["derive"] }
-pnet = { version = "0.34.0", features = ["serde"] }
-public-ip = { version = "0.2", features = ["default"] }
-
-clap = { version = "4.4.8", features = ["unicode", "derive", "wrap_help"] }
-
-async-recursion = "1.0.5"
-
-network-interface = "1.1.1"
-
-# for ospf route
-pathfinding = "4.9.1"
-
-# for cli
-tabled = "0.15.*"
-humansize = "2.1.3"
-
-
-[target.'cfg(windows)'.dependencies]
-windows-sys = { version = "0.52", features = [
-    "Win32_Networking_WinSock",
-    "Win32_NetworkManagement_IpHelper",
-    "Win32_Foundation",
-    "Win32_System_IO",
-] }
-
-[build-dependencies]
-tonic-build = "0.10"
-
-[target.'cfg(windows)'.build-dependencies]
-reqwest = { version = "0.11", features = ["blocking"] }
-zip = "0.6.6"
-
-
-[dev-dependencies]
-serial_test = "3.0.0"
+arc-swap = "1.9"
+async-trait = "0.1.92"
+atomic-shim = "0.2.0"
+auto_impl = "1.3.0"
+axum = "0.8"
+# Match pbjson 0.9's base64 dependency; upgrade together to avoid two codecs.
+base64 = "0.22.1"
+bon = "3.10.1"
+bytecodec = "0.5.0"
+bytes = "1.12.1"
+chrono = "0.4.45"
+cidr = "0.3.2"
+clap = "4.6.7"
+crossbeam = "0.8.5"
+crossbeam-utils = "0.8.23"
+dashmap = "6.2.1"
+easytier = { version = "2.7.0", path = "easytier", default-features = false }
+easytier-core = { version = "2.7.0", path = "easytier-core", default-features = false }
+easytier-ffi = { version = "0.1.0", path = "easytier-contrib/easytier-ffi", default-features = false }
+easytier-ohos-core = { version = "0.1.0", path = "easytier-contrib/easytier-ohrs/crates/easytier-ohos-core", default-features = false }
+easytier-ohos-features = { version = "0.1.0", path = "easytier-contrib/easytier-ohrs/crates/easytier-ohos-features", default-features = false }
+easytier-proto = { version = "2.7.0", path = "easytier-proto", default-features = false }
+futures = { version = "0.3", default-features = false }
+gethostname = "1.1"
+guarden = "0.3"
+# Keep HMAC/SHA2 on digest 0.10, shared by stun_codec 0.4 and snow 0.10.
+# Upgrade this crypto family together when those upstream constraints move.
+hmac = "0.12.1"
+http-body-util = "0.1"
+hyper = { version = "1", default-features = false }
+hyper-util = { version = "0.1", default-features = false }
+indoc = "2.0.7"
+log = "0.4"
+mimalloc = "*"
+once_cell = "1.21"
+parking_lot = "0.12.5"
+percent-encoding = "2.3.2"
+pin-project-lite = "0.2.17"
+prost = "0.14.4"
+prost-types = "0.14.4"
+quanta = "0.12"
+# rand 0.10 / x25519-dalek 3 require a coordinated RNG trait migration.
+rand = "0.8.8"
+reqwest = { version = "0.13.5", default-features = false }
+rust-i18n = "4"
+rustls = { version = "0.23.45", default-features = false }
+# tower-sessions-sqlx-store 0.15 requires SQLx 0.8; SeaORM 2 requires SQLx 0.9.
+sea-orm = "1.1.20"
+sea-orm-migration = "1.1.20"
+serde = "1.0.229"
+serde_json = "1.0"
+# See the HMAC constraint above; SHA2 must use the same digest generation.
+sha2 = "0.10.9"
+smoltcp = { version = "0.14.0", default-features = false }
+sqlx = "0.8.6"
+strum = "0.28.0"
+stun_codec = "0.4.0"
+sys-locale = "0.3"
+tauri = "2.11.5"
+tempfile = "3.27.0"
+thiserror = "2.0"
+thunk-rs = { git = "https://github.com/EasyTier/thunk.git", default-features = false }
+tokio = { version = "1.53", default-features = false }
+tokio-rustls = { version = "0.26", default-features = false }
+tokio-util = "0.7.19"
+toml = "1.1.6"
+tower-http = "0.7"
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", default-features = false }
+url = "2.5"
+uuid = "1.26.1"
+winapi = "0.3.9"
+windows = "0.62"
+x25519-dalek = "2.0.1"
+# zerocopy 0.8 requires migrating the packet layout and casting APIs.
+zerocopy = "0.7.35"
 
 [profile.dev]
-panic = "abort"
+panic = "unwind"
+debug = 2
 
 [profile.release]
 panic = "abort"
 lto = true
+codegen-units = 1
+opt-level = 3
+strip = true
+
+[profile.mini]
+inherits = "release"
+opt-level = "z"
+strip = "symbols"

EasyTier.code-workspace

@@ -0,0 +1,57 @@
+{
+	"folders": [
+		{
+			"path": "."
+		},
+		{
+			"name": "core",
+			"path": "easytier"
+		},
+		{
+			"name": "gui",
+			"path": "easytier-gui"
+		},
+		{
+			"name": "web",
+			"path": "easytier-web"
+		},
+		{
+			"name": "ffi",
+			"path": "easytier-contrib/easytier-ffi"
+		},
+		{
+			"name": "magisk",
+			"path": "easytier-contrib/easytier-magisk"
+		},
+		{
+			"name": "openharmony",
+			"path": "easytier-contrib/easytier-ohrs"
+		},
+		{
+			"name": "uptime",
+			"path": "easytier-contrib/easytier-uptime"
+		},
+		{
+			"name": "vpnservice",
+			"path": "tauri-plugin-vpnservice"
+		},
+		{
+			"name": "rpc-build",
+			"path": "easytier-rpc-build"
+		}
+	],
+	"settings": {
+		"i18n-ally.sourceLanguage": "cn",
+		"i18n-ally.keystyle": "nested",
+		"i18n-ally.sortKeys": true,
+		// Disable the default formatter
+		"prettier.enable": false,
+		"editor.formatOnSave": true,
+		"editor.formatOnSaveMode": "modifications",
+		"editor.formatOnPaste": false,
+		"editor.formatOnType": true,
+		"[nix]": {
+			"editor.formatOnSave": false,
+		},
+	}
+}

LICENSE

@@ -1,73 +1,165 @@
-Apache License
-Version 2.0, January 2004
-http://www.apache.org/licenses/
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
 
-TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
 
-1. Definitions.
 
-"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
 
-"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+  0. Additional Definitions.
 
-"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
 
-"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
 
-"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
 
-"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
 
-"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
 
-"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
 
-"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+  1. Exception to Section 3 of the GNU GPL.
 
-"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
 
-2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+  2. Conveying Modified Versions.
 
-3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
 
-4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
 
-     (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
 
-     (b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+  3. Object Code Incorporating Material from Library Header Files.
 
-     (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
 
-     (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
 
-     You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
 
-5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+  4. Combined Works.
 
-6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
 
-7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
 
-8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
 
-9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
 
-END OF TERMS AND CONDITIONS
+   d) Do one of the following:
 
-APPENDIX: How to apply the Apache License to your work.
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
 
-To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!)  The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
 
-Copyright 2023 sunsijie
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
 
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
+  5. Combined Libraries.
 
-http://www.apache.org/licenses/LICENSE-2.0
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

README.md

@@ -1,202 +1,349 @@
- # EasyTier
- 
- [![GitHub](https://img.shields.io/github/license/KKRainbow/EasyTier)](https://github.com/KKRainbow/EasyTier/blob/main/LICENSE)
- [![GitHub last commit](https://img.shields.io/github/last-commit/KKRainbow/EasyTier)](https://github.com/KKRainbow/EasyTier/commits/main)
- [![GitHub issues](https://img.shields.io/github/issues/KKRainbow/EasyTier)](https://github.com/KKRainbow/EasyTier/issues)
- [![GitHub actions](https://github.com/KKRainbow/EasyTier/actions/workflows/rust.yml/badge.svg)](https://github.com/KKRainbow/EasyTier/actions/)
- 
+# EasyTier
+
+[![Github release](https://img.shields.io/github/v/tag/EasyTier/EasyTier)](https://github.com/EasyTier/EasyTier/releases)
+[![GitHub](https://img.shields.io/github/license/EasyTier/EasyTier)](https://github.com/EasyTier/EasyTier/blob/main/LICENSE)
+[![GitHub last commit](https://img.shields.io/github/last-commit/EasyTier/EasyTier)](https://github.com/EasyTier/EasyTier/commits/main)
+[![GitHub issues](https://img.shields.io/github/issues/EasyTier/EasyTier)](https://github.com/EasyTier/EasyTier/issues)
+[![GitHub Core Actions](https://github.com/EasyTier/EasyTier/actions/workflows/core.yml/badge.svg)](https://github.com/EasyTier/EasyTier/actions/workflows/core.yml)
+[![GitHub GUI Actions](https://github.com/EasyTier/EasyTier/actions/workflows/gui.yml/badge.svg)](https://github.com/EasyTier/EasyTier/actions/workflows/gui.yml)
+[![GitHub Test Actions](https://github.com/EasyTier/EasyTier/actions/workflows/test.yml/badge.svg)](https://github.com/EasyTier/EasyTier/actions/workflows/test.yml)
+[<img src="https://devin.ai/assets/askdeepwiki.png" alt="Ask DeepWiki" height="20"/>](https://deepwiki.com/EasyTier/EasyTier)
+
 [简体中文](/README_CN.md) | [English](/README.md)
 
- EasyTier is a simple, plug-and-play, decentralized VPN networking solution implemented with the Rust language and Tokio framework.
- 
- ## Features
- 
-- **Decentralized**: No need to rely on centralized services, nodes are equal and independent.
-- **Cross-platform**: Supports MacOS/Linux/Windows, will support IOS and Android in the future. The executable file is statically linked, making deployment simple.
-- **Networking without public IP**: Supports networking using shared public nodes, refer to [Configuration Guide](#Networking-without-public-IP)
-- **NAT traversal**: Supports UDP-based NAT traversal, able to establish stable connections even in complex network environments.
-- **Subnet Proxy (Point-to-Network)**: Nodes can expose accessible network segments as proxies to the VPN subnet, allowing other nodes to access these subnets through the node.
-- **Smart Routing**: Selects links based on traffic to reduce latency and increase throughput.
-- **TCP Support**: Provides reliable data transmission through concurrent TCP links when UDP is limited, optimizing performance.
-- **High Availability**: Supports multi-path and switches to healthy paths when high packet loss or network errors are detected.
+> ✨ A simple, secure, decentralized virtual private network solution powered by Rust and Tokio
 
- 
- ## Installation
- 
- 1. **Download the precompiled binary file**
- 
-     Visit the [GitHub Release page](https://github.com/KKRainbow/EasyTier/releases) to download the binary file suitable for your operating system.
- 
- 2. **Install via crates.io**
-    ```sh
-    cargo install easytier
-    ```
- 
- 3. **Install from source code**
-    ```sh
-    cargo install --git https://github.com/KKRainbow/EasyTier.git
-    ```
- 
- ## Quick Start
- 
- Make sure EasyTier is installed according to the [Installation Guide](#Installation), and both easytier-core and easytier-cli commands are available.
- 
- ### Two-node Networking
- 
- Assuming the network topology of the two nodes is as follows
- 
- ```mermaid
- flowchart LR
- 
- subgraph Node A IP 22.1.1.1
- nodea[EasyTier\n10.144.144.1]
- end
- 
- subgraph Node B
- nodeb[EasyTier\n10.144.144.2]
- end
- 
- nodea <-----> nodeb
- 
- ```
- 
- 1. Execute on Node A:
-    ```sh
-    sudo easytier-core --ipv4 10.144.144.1
-    ```
-    Successful execution of the command will print the following.
- 
-    ![alt text](assets/image-2.png)
- 
- 2. Execute on Node B
-    ```sh
-    sudo easytier-core --ipv4 10.144.144.2 --peers udp://22.1.1.1:11010
-    ```
- 
- 3. Test Connectivity
- 
-    The two nodes should connect successfully and be able to communicate within the virtual subnet
-    ```sh
-    ping 10.144.144.2
-    ```
- 
-    Use easytier-cli to view node information in the subnet
-    ```sh
-    easytier-cli peer
-    ```
-    ![alt text](assets/image.png)
-    ```sh
-    easytier-cli route
-    ```
-    ![alt text](assets/image-1.png)
+<p align="center">
+<img src="assets/config-page.png" width="300" alt="config page">
+<img src="assets/running-page.png" width="300" alt="running page">
+</p>
 
----
- 
- ### Multi-node Networking
- 
- Based on the two-node networking example just now, if more nodes need to join the virtual network, you can use the following command.
- 
- ```
- sudo easytier-core --ipv4 10.144.144.2 --peers udp://22.1.1.1:11010
- ```
- 
- The `--peers` parameter can fill in the listening address of any node already in the virtual network.
- 
- ---
- 
- ### Subnet Proxy (Point-to-Network) Configuration
- 
- Assuming the network topology is as follows, Node B wants to share its accessible subnet 10.1.1.0/24 with other nodes.
- 
- ```mermaid
- flowchart LR
- 
- subgraph Node A IP 22.1.1.1
- nodea[EasyTier\n10.144.144.1]
- end
- 
- subgraph Node B
- nodeb[EasyTier\n10.144.144.2]
- end
- 
- id1[[10.1.1.0/24]]
- 
- nodea <--> nodeb <-.-> id1
- 
- ```
- 
- Then the startup parameters for Node B's easytier are (new -n parameter)
- 
- ```sh
- sudo easytier-core --ipv4 10.144.144.2 -n 10.1.1.0/24
- ```
- 
- Subnet proxy information will automatically sync to each node in the virtual network, and each node will automatically configure the corresponding route. Node A can check whether the subnet proxy is effective through the following command.
- 
- 1. Check whether the routing information has been synchronized, the proxy_cidrs column shows the proxied subnets.
- 
-    ```sh
-    easytier-cli route
-    ```
-    ![alt text](assets/image-3.png)
- 
-2. Test whether Node A can access nodes under the proxied subnet
- 
-    ```sh
-    ping 10.1.1.2
-    ```
- 
- ---
- 
- ### Networking without Public IP
- 
- EasyTier supports networking using shared public nodes. The currently deployed shared public node is ``tcp://easytier.public.kkrainbow.top:11010``.
- 
- When using shared nodes, each node entering the network needs to provide the same ``--network-name`` and ``--network-secret`` parameters as the unique identifier of the network.
- 
- Taking two nodes as an example, Node A executes:
- 
- ```sh
- sudo easytier-core -i 10.144.144.1 --network-name abc --network-secret abc -e 'tcp://easytier.public.kkrainbow.top:11010'
- ```
- 
- Node B executes
- 
- ```sh
- sudo easytier-core --ipv4 10.144.144.2 --network-name abc --network-secret abc -e 'tcp://easytier.public.kkrainbow.top:11010'
- ```
- 
- After the command is successfully executed, Node A can access Node B through the virtual IP 10.144.144.2.
- 
- 
- ### Configurations
- 
- You can use ``easytier-core --help`` to view all configuration items
- 
- 
- # Roadmap
- 
- - [ ] Improve documentation and user guides.
- - [ ] Support features such as encryption, TCP hole punching, etc.
- - [ ] Support Android, IOS and other mobile platforms.
- - [ ] Support Web configuration management.
- 
- # Community and Contribution
- 
- We welcome and encourage community contributions! If you want to get involved, please submit a [GitHub PR](https://github.com/KKRainbow/EasyTier/pulls). Detailed contribution guidelines can be found in [CONTRIBUTING.md](https://github.com/KKRainbow/EasyTier/blob/main/CONTRIBUTING.md).
- 
- # Related Projects and Resources
- 
- - [ZeroTier](https://www.zerotier.com/): A global virtual network for connecting devices.
- - [TailScale](https://tailscale.com/): A VPN solution aimed at simplifying network configuration.
- - [vpncloud](https://github.com/dswd/vpncloud): A P2P Mesh VPN
- 
- # License
- 
- EasyTier is released under the [Apache License 2.0](https://github.com/KKRainbow/EasyTier/blob/main/LICENSE).
- 
- # Contact
- 
- - Ask questions or report problems: [GitHub Issues](https://github.com/KKRainbow/EasyTier/issues)
- - Discussion and exchange: [GitHub Discussions](https://github.com/KKRainbow/EasyTier/discussions)
- - QQ Group: 949700262
+📚 **[Full Documentation](https://easytier.cn/en/)** | 🖥️ **[Web Console](https://easytier.cn/web)** | 📝 **[Download Releases](https://github.com/EasyTier/EasyTier/releases)** | **[Nightly](https://github.com/EasyTier/EasyTier/releases/tag/nightly)** | 🧩 **[Third Party Tools](https://easytier.cn/en/guide/installation_gui.html#third-party-graphical-interfaces)** | ❤️ **[Sponsor](#sponsor)**
+
+## Features
+
+### Core Features
+
+- 🔒 **Decentralized**: Nodes are equal and independent, no centralized services required  
+- 🚀 **Easy to Use**: Multiple operation methods via web, client, and command line  
+- 🌍 **Cross-Platform**: Supports Win/MacOS/Linux/FreeBSD/Android and X86/ARM/MIPS architectures  
+- 🔐 **Secure**: AES-GCM or WireGuard encryption, prevents man-in-the-middle attacks  
+
+### Advanced Capabilities
+
+- 🔌 **Efficient NAT Traversal**: Supports UDP and IPv6 traversal, works with NAT4-NAT4 networks  
+- 🌐 **Subnet Proxy**: Nodes can share subnets for other nodes to access  
+- 🔄 **Intelligent Routing**: Latency priority and automatic route selection for best network experience  
+- ⚡ **High Performance**: Zero-copy throughout the entire link, supports TCP/UDP/WSS/WG protocols  
+
+### Network Optimization
+
+- 📊 **UDP Loss Resistance**: KCP/QUIC proxy optimizes latency and bandwidth in high packet loss environments  
+- 🔧 **Web Management**: Easy configuration and monitoring through web interface  
+- 🛠️ **Zero Config**: Simple deployment with statically linked executables  
+
+## Quick Start
+
+### 📥 Installation
+
+Choose the installation method that best suits your needs:
+
+Linux (Recommended):
+```bash
+curl -fsSL "https://github.com/EasyTier/EasyTier/blob/main/script/install.sh?raw=true" | sudo bash -s install
+```
+
+Homebrew (MacOS/Linux):
+```bash
+brew tap brewforge/chinese
+brew install --cask easytier-gui
+```
+
+Windows (Recommended, run with administrator privileges):
+```powershell
+irm "https://github.com/EasyTier/EasyTier/blob/main/script/install.ps1?raw=true" | iex
+```
+
+Install via cargo (Latest development version): 
+```bash
+cargo install --git https://github.com/EasyTier/EasyTier.git easytier
+```
+
+Install prebuilt CLI tools with [cargo-binstall](https://github.com/cargo-bins/cargo-binstall) (specify an existing release version):
+```bash
+cargo binstall --git https://github.com/EasyTier/EasyTier.git --version 2.6.4 easytier
+```
+
+This installs `easytier-core` and `easytier-cli` using the repository's metadata, independently of crates.io publication. On Windows, also copy the DLL and driver files from the matching release ZIP beside the installed binaries; binstall only installs executables.
+
+[Install pre-built binary](https://github.com/EasyTier/EasyTier/releases) (Recommended, All platforms supported)
+
+For a smaller executable, try [easytier-mini](https://github.com/EasyTier/easytier-mini), which supports basic TCP/UDP networking. See its documentation for supported features and usage.
+
+[Install via Docker](https://easytier.cn/en/guide/installation.html#installation-methods)
+
+[Install OpenWrt ipk package](https://github.com/EasyTier/luci-app-easytier)
+
+Additional steps:
+
+[One-Click Register Service](https://easytier.cn/en/guide/network/oneclick-install-as-service.html) (Automatically start when the system boots and run in the background)
+
+### 🚀 Basic Usage
+
+#### Quick Networking with Shared Nodes
+
+EasyTier supports quick networking using shared public nodes. When you don't have a public IP, you can use the free shared nodes provided by the EasyTier community. Nodes will automatically attempt NAT traversal and establish P2P connections. When P2P fails, data will be relayed through shared nodes.
+
+When using shared nodes, each node entering the network needs to provide the same `--network-name` and `--network-secret` parameters as the unique identifier of the network.
+
+Taking two nodes as an example (Please use more complex network name to avoid conflicts):
+
+1. Run on Node A:
+
+```bash
+# Run with administrator privileges
+sudo easytier-core -d --network-name abc --network-secret abc -p tcp://<SharedNodeIP>:11010
+```
+
+2. Run on Node B:
+
+```bash
+# Run with administrator privileges
+sudo easytier-core -d --network-name abc --network-secret abc -p tcp://<SharedNodeIP>:11010
+```
+
+After successful execution, you can check the network status using `easytier-cli`:
+
+```text
+| ipv4         | hostname       | cost  | lat_ms | loss_rate | rx_bytes | tx_bytes | tunnel_proto | nat_type | id         | version         |
+| ------------ | -------------- | ----- | ------ | --------- | -------- | -------- | ------------ | -------- | ---------- | --------------- |
+| 10.126.126.1 | abc-1          | Local | *      | *         | *        | *        | udp          | FullCone | 439804259  | 2.6.2-70e69a38~ |
+| 10.126.126.2 | abc-2          | p2p   | 3.452  | 0         | 17.33 kB | 20.42 kB | udp          | FullCone | 390879727  | 2.6.2-70e69a38~ |
+|              | PublicServer_a | p2p   | 27.796 | 0.000     | 50.01 kB | 67.46 kB | tcp          | Unknown  | 3771642457 | 2.6.2-70e69a38~ |
+```
+
+You can test connectivity between nodes:
+
+```bash
+# Test connectivity
+ping 10.126.126.1
+ping 10.126.126.2
+```
+
+Note: If you cannot ping through, it may be that the firewall is blocking incoming traffic. Please turn off the firewall or add allow rules.
+
+To improve availability, you can connect to multiple shared nodes simultaneously:
+
+```bash
+# Connect to multiple shared nodes
+sudo easytier-core -d --network-name abc --network-secret abc -p tcp://<SharedNodeIP1>:11010 -p udp://<SharedNodeIP2>:11010
+```
+
+Once your network is set up successfully, you can easily configure it to start automatically on system boot. Refer to the [One-Click Register Service guide](https://easytier.cn/en/guide/network/oneclick-install-as-service.html) for step-by-step instructions on registering EasyTier as a system service.
+
+#### Decentralized Networking
+
+EasyTier is fundamentally decentralized, with no distinction between server and client. As long as one device can communicate with any node in the virtual network, it can join the virtual network. Here's how to set up a decentralized network:
+
+1. Start First Node (Node A):
+
+```bash
+# Start the first node
+sudo easytier-core -i 10.144.144.1
+```
+
+After startup, this node will listen on the following ports by default:
+- TCP: 11010
+- UDP: 11010
+- WebSocket: 11011
+- WebSocket SSL: 11012
+- WireGuard: 11013
+
+2. Connect Second Node (Node B):
+
+```bash
+# Connect to the first node using its public IP
+sudo easytier-core -i 10.144.144.2 -p udp://FIRST_NODE_PUBLIC_IP:11010
+```
+
+3. Verify Connection:
+
+```bash
+# Test connectivity
+ping 10.144.144.2
+
+# View connected peers
+easytier-cli peer
+
+# View routing information
+easytier-cli route
+
+# View local node information
+easytier-cli node
+```
+
+For more nodes to join the network, they can connect to any existing node in the network using the `-p` parameter:
+
+```bash
+# Connect to any existing node using its public IP
+sudo easytier-core -i 10.144.144.3 -p udp://ANY_EXISTING_NODE_PUBLIC_IP:11010
+```
+
+### 🔍 Advanced Features
+
+#### Subnet Proxy
+
+Assuming the network topology is as follows, Node B wants to share its accessible subnet 10.1.1.0/24 with other nodes:
+
+```mermaid
+flowchart LR
+
+subgraph Node A Public IP 22.1.1.1
+nodea[EasyTier<br/>10.144.144.1]
+end
+
+subgraph Node B
+nodeb[EasyTier<br/>10.144.144.2]
+end
+
+id1[[10.1.1.0/24]]
+
+nodea <--> nodeb <-.-> id1
+```
+
+To share a subnet, add the `-n` parameter when starting EasyTier:
+
+```bash
+# Share subnet 10.1.1.0/24 with other nodes
+sudo easytier-core -i 10.144.144.2 -n 10.1.1.0/24
+```
+
+Subnet proxy information will automatically sync to each node in the virtual network, and each node will automatically configure the corresponding route. You can verify the subnet proxy setup:
+
+1. Check if the routing information has been synchronized (the proxy_cidrs column shows the proxied subnets):
+
+```bash
+# View routing information
+easytier-cli route
+```
+
+![Routing Information](/assets/image-3.png)
+
+2. Test if you can access nodes in the proxied subnet:
+
+```bash
+# Test connectivity to proxied subnet
+ping 10.1.1.2
+```
+
+#### WireGuard Integration
+
+EasyTier can act as a WireGuard server, allowing any device with a WireGuard client (including iOS and Android) to access the EasyTier network. Here's an example setup:
+
+```mermaid
+flowchart LR
+
+ios[[iPhone<br/>WireGuard Installed]]
+
+subgraph Node A Public IP 22.1.1.1
+nodea[EasyTier<br/>10.144.144.1]
+end
+
+subgraph Node B
+nodeb[EasyTier<br/>10.144.144.2]
+end
+
+id1[[10.1.1.0/24]]
+
+ios <-.-> nodea <--> nodeb <-.-> id1
+```
+
+1. Start EasyTier with WireGuard portal enabled:
+
+```bash
+# Register one WireGuard client as virtual peer 10.144.144.3
+sudo easytier-core -i 10.144.144.1 \
+  --network-secret portal-secret \
+  --vpn-portal wg://0.0.0.0:11013 \
+  --vpn-portal-private-key "$(wg genkey)" \
+  --vpn-portal-client phone=10.144.144.3
+```
+
+2. Get WireGuard client configuration:
+
+```bash
+# Get WireGuard client configuration
+easytier-cli vpn-portal
+```
+
+3. In the output configuration, replace a wildcard `Peer.Endpoint` with the
+   public IP/domain of your EasyTier node, then import it. `Interface.Address`
+   is local to that WireGuard client and may be changed to any IPv4 address;
+   EasyTier translates it to the registered virtual-peer address.
+
+#### Self-Hosted Public Shared Node
+
+You can run your own public shared node to help other nodes discover each other. A public shared node is just a regular EasyTier network (with same network name and secret) that other networks can connect to.
+
+To run a public shared node:
+
+```bash
+# No need to specify IPv4 address for public shared nodes
+sudo easytier-core --network-name mysharednode --network-secret mysharednode
+```
+
+## Related Projects
+
+- [ZeroTier](https://www.zerotier.com/): A global virtual network for connecting devices.
+- [TailScale](https://tailscale.com/): A VPN solution aimed at simplifying network configuration.
+
+### Contact Us
+
+- 💬 **[Telegram Group](https://t.me/easytier)**
+- 👥 **[QQ Group]**
+  - No.1 [949700262](https://qm.qq.com/q/wFoTUChqZW)
+  - No.2 [837676408](https://qm.qq.com/q/4V33DrfgHe)
+  - No.3 [957189589](https://qm.qq.com/q/YNyTQjwlai)
+
+## License
+
+EasyTier is released under the [LGPL-3.0](https://github.com/EasyTier/EasyTier/blob/main/LICENSE).
+
+## Responsible Use
+
+Use EasyTier only for lawful purposes and in compliance with applicable laws
+and regulations. You are responsible for ensuring that you are authorized to
+connect to and administer the networks and devices involved.
+
+## Sponsor
+
+CDN acceleration and security protection for this project are sponsored by Tencent EdgeOne.
+
+<p align="center">
+  <a href="https://edgeone.ai/?from=github" target="_blank">
+    <img src="assets/edgeone.png" width="200" alt="EdgeOne Logo">
+  </a>
+</p>
+
+Special thanks to [Langlang Cloud](https://langlangy.cn/?i26c5a5)  and [RainCloud](https://www.rainyun.com/NjM0NzQ1_) for sponsoring our public servers.
+We also thank [Linfeng Cloud (林枫云)](https://www.dkdun.cn/aff/RZGBFYSW) for supporting EasyTier.
+
+<p align="center">
+<a href="https://langlangy.cn/?i26c5a5" target="_blank">
+<img src="assets/langlang.png" width="200">
+</a>
+<a href="https://langlangy.cn/?i26c5a5" target="_blank">
+<img src="assets/raincloud.png" width="200">
+</a>
+<a href="https://www.dkdun.cn/aff/RZGBFYSW" target="_blank">
+<img src="assets/linfengyun.png" width="200" alt="林枫云">
+</a>
+</p>
+
+
+If you find EasyTier helpful, please consider sponsoring us. Software development and maintenance require a lot of time and effort, and your sponsorship will help us better maintain and improve EasyTier.
+
+<p align="center">
+<img src="assets/wechat.png" width="200">
+<img src="assets/alipay.png" width="200">
+</p>

README_CN.md

@@ -1,203 +1,345 @@
 # EasyTier
 
-[![GitHub](https://img.shields.io/github/license/KKRainbow/EasyTier)](https://github.com/KKRainbow/EasyTier/blob/main/LICENSE)
-[![GitHub last commit](https://img.shields.io/github/last-commit/KKRainbow/EasyTier)](https://github.com/KKRainbow/EasyTier/commits/main)
-[![GitHub issues](https://img.shields.io/github/issues/KKRainbow/EasyTier)](https://github.com/KKRainbow/EasyTier/issues)
-[![GitHub actions](https://github.com/KKRainbow/EasyTier/actions/workflows/rust.yml/badge.svg)](https://github.com/KKRainbow/EasyTier/actions/)
+[![Github release](https://img.shields.io/github/v/tag/EasyTier/EasyTier)](https://github.com/EasyTier/EasyTier/releases)
+[![GitHub](https://img.shields.io/github/license/EasyTier/EasyTier)](https://github.com/EasyTier/EasyTier/blob/main/LICENSE)
+[![GitHub last commit](https://img.shields.io/github/last-commit/EasyTier/EasyTier)](https://github.com/EasyTier/EasyTier/commits/main)
+[![GitHub issues](https://img.shields.io/github/issues/EasyTier/EasyTier)](https://github.com/EasyTier/EasyTier/issues)
+[![GitHub Core Actions](https://github.com/EasyTier/EasyTier/actions/workflows/core.yml/badge.svg)](https://github.com/EasyTier/EasyTier/actions/workflows/core.yml)
+[![GitHub GUI Actions](https://github.com/EasyTier/EasyTier/actions/workflows/gui.yml/badge.svg)](https://github.com/EasyTier/EasyTier/actions/workflows/gui.yml)
+[![GitHub Test Actions](https://github.com/EasyTier/EasyTier/actions/workflows/test.yml/badge.svg)](https://github.com/EasyTier/EasyTier/actions/workflows/test.yml)
+[<img src="https://devin.ai/assets/askdeepwiki.png" alt="Ask DeepWiki" height="20"/>](https://deepwiki.com/EasyTier/EasyTier)
 
 [简体中文](/README_CN.md) | [English](/README.md)
 
-一个简单、即插即用、去中心化的内网穿透 VPN 组网方案，使用 Rust 语言和 Tokio 框架实现。
+> ✨ 一个由 Rust 和 Tokio 驱动的简单、安全、去中心化的异地组网方案
 
-## 特点
+<p align="center">
+<img src="assets/config-page.png" width="300" alt="配置页面">
+<img src="assets/running-page.png" width="300" alt="运行页面">
+</p>
 
-- **去中心化**：无需依赖中心化服务，节点平等且独立。
-- **跨平台**：支持 MacOS/Linux/Windows，未来将支持 IOS 和 Android。可执行文件静态链接，部署简单。
-- **无公网 IP 组网**：支持利用共享的公网节点组网，可参考 [配置指南](#无公网IP组网)
-- **NAT 穿透**：支持基于 UDP 的 NAT 穿透，即使在复杂的网络环境下也能建立稳定的连接。
-- **子网代理（点对网）**：节点可以将可访问的网段作为代理暴露给 VPN 子网，允许其他节点通过该节点访问这些子网。
-- **智能路由**：根据流量智能选择链路，减少延迟，提高吞吐量。
-- **TCP 支持**：在 UDP 受限的情况下，通过并发 TCP 链接提供可靠的数据传输，优化性能。
-- **高可用性**：支持多路径和在检测到高丢包率或网络错误时切换到健康路径。
+📚 **[完整文档](https://easytier.cn)** | 🖥️ **[Web 控制台](https://easytier.cn/web)** | 📝 **[下载发布版本](https://github.com/EasyTier/EasyTier/releases)** | **[Nightly](https://github.com/EasyTier/EasyTier/releases/tag/nightly)** | 🧩 **[第三方工具](https://easytier.cn/guide/installation_gui.html#%E7%AC%AC%E4%B8%89%E6%96%B9%E5%9B%BE%E5%BD%A2%E7%95%8C%E9%9D%A2)** | ❤️ **[赞助](#赞助)**
 
-## 安装
+## 特性
 
-1. **下载预编译的二进制文件**
+### 核心特性
 
-    访问 [GitHub Release 页面](https://github.com/KKRainbow/EasyTier/releases) 下载适用于您操作系统的二进制文件。
+- 🔒 **去中心化**：节点平等且独立，无需中心化服务
+- 🚀 **易于使用**：支持通过网页、客户端和命令行多种操作方式
+- 🌍 **跨平台**：支持 Win/MacOS/Linux/FreeBSD/Android 和 X86/ARM/MIPS 架构
+- 🔐 **安全**：AES-GCM 或 WireGuard 加密，防止中间人攻击
 
-2. **通过 crates.io 安装**
-   ```sh
-   cargo install easytier
-   ```
+### 高级功能
 
+- 🔌 **高效 NAT 穿透**：支持 UDP 和 IPv6 穿透，可在 NAT4-NAT4 网络中工作
+- 🌐 **子网代理**：节点可以共享子网供其他节点访问
+- 🔄 **智能路由**：延迟优先和自动路由选择，提供最佳网络体验
+- ⚡ **高性能**：整个链路零拷贝，支持 TCP/UDP/WSS/WG 协议
 
-3. **通过源码安装**
-   ```sh
-   cargo install --git https://github.com/KKRainbow/EasyTier.git
-   ```
+### 网络优化
+
+- 📊 **UDP 丢包抗性**：KCP/QUIC 代理在高丢包环境下优化延迟和带宽
+- 🔧 **Web 管理**：通过 Web 界面轻松配置和监控
+- 🛠️ **零配置**：静态链接的可执行文件，简单部署
 
 ## 快速开始
 
-确保已按照 [安装指南](#安装) 安装 EasyTier，并且 easytier-core 和 easytier-cli 两个命令都已经可用。
+### 📥 安装
 
-### 双节点组网
+选择最适合您需求的安装方式：
 
-假设双节点的网络拓扑如下
+Linux（推荐）：
+```bash
+curl -fsSL "https://github.com/EasyTier/EasyTier/blob/main/script/install.sh?raw=true" | sudo bash -s install
+```
+
+Homebrew（MacOS/Linux）：
+```bash
+brew tap brewforge/chinese
+brew install --cask easytier-gui
+```
+
+Windows（推荐，请以管理员权限运行）：
+```powershell
+irm "https://github.com/EasyTier/EasyTier/blob/main/script/install.ps1?raw=true" | iex
+```
+
+通过 cargo 安装（最新开发版本）：
+```bash
+cargo install --git https://github.com/EasyTier/EasyTier.git easytier
+```
+
+通过 [cargo-binstall](https://github.com/cargo-bins/cargo-binstall) 安装预编译命令行工具（请指定已有 release 的版本）：
+```bash
+cargo binstall --git https://github.com/EasyTier/EasyTier.git --version 2.6.4 easytier
+```
+
+此方式使用仓库中的 metadata 安装 `easytier-core` 和 `easytier-cli`，不依赖 crates.io 发布。在 Windows 上，还需将对应 release ZIP 中的 DLL 和驱动文件复制到安装后的程序旁；binstall 只安装可执行文件。
+
+[下载预编译文件](https://github.com/EasyTier/EasyTier/releases)（推荐，支持所有平台）
+
+需要更小的可执行文件，可使用 [easytier-mini](https://github.com/EasyTier/easytier-mini)：支持基础 TCP/UDP 组网，功能范围与使用方式见其文档。
+
+[通过 Docker 安装](https://easytier.cn/guide/installation.html#%E5%AE%89%E8%A3%85%E6%96%B9%E5%BC%8F)
+
+[安装 OpenWrt ipk 软件包](https://github.com/EasyTier/luci-app-easytier)
+
+附加步骤：
+
+[一键注册系统服务](https://easytier.cn/guide/network/oneclick-install-as-service.html)（系统启动时自动后台运行）
+
+### 🚀 基本用法
+
+#### 使用共享节点快速组网
+
+EasyTier 支持使用共享节点快速组网。当您没有公网 IP 时，可以使用公共共享节点。节点会自动尝试 NAT 穿透并建立 P2P 连接。当 P2P 失败时，数据将通过共享节点中继。
+
+使用共享节点时，每个进入网络的节点需要提供相同的 `--network-name` 和 `--network-secret` 参数作为网络的唯一标识符。
+
+以两个节点为例（请使用更复杂的网络名称以避免冲突）：
+
+1. 在节点 A 上运行：
+
+```bash
+# 以管理员权限运行
+sudo easytier-core -d --network-name abc --network-secret abc -p tcp://<共享节点IP>:11010
+```
+
+2. 在节点 B 上运行：
+
+```bash
+# 以管理员权限运行
+sudo easytier-core -d --network-name abc --network-secret abc -p tcp://<共享节点IP>:11010
+```
+
+执行成功后，可以使用 `easytier-cli` 检查网络状态：
+
+```text
+| ipv4         | hostname       | cost  | lat_ms | loss_rate | rx_bytes | tx_bytes | tunnel_proto | nat_type | id         | version         |
+| ------------ | -------------- | ----- | ------ | --------- | -------- | -------- | ------------ | -------- | ---------- | --------------- |
+| 10.126.126.1 | abc-1          | Local | *      | *         | *        | *        | udp          | FullCone | 439804259  | 2.6.2-70e69a38~ |
+| 10.126.126.2 | abc-2          | p2p   | 3.452  | 0         | 17.33 kB | 20.42 kB | udp          | FullCone | 390879727  | 2.6.2-70e69a38~ |
+|              | PublicServer_a | p2p   | 27.796 | 0.000     | 50.01 kB | 67.46 kB | tcp          | Unknown  | 3771642457 | 2.6.2-70e69a38~ |
+```
+
+您可以测试节点之间的连通性：
+
+```bash
+# 测试连通性
+ping 10.126.126.1
+ping 10.126.126.2
+```
+
+注意：如果无法 ping 通，可能是防火墙阻止了入站流量。请关闭防火墙或添加允许规则。
+
+为了提高可用性，您可以同时连接多个共享节点：
+
+```bash
+# 连接多个共享节点
+sudo easytier-core -d --network-name abc --network-secret abc -p tcp://<公共节点IP>:11010 -p udp://<公共节点IP>:11010
+```
+
+#### 去中心化组网
+
+EasyTier 本质上是去中心化的，没有服务器和客户端的区分。只要一个设备能与虚拟网络中的任何节点通信，它就可以加入虚拟网络。以下是如何设置去中心化网络：
+
+1. 启动第一个节点（节点 A）：
+
+```bash
+# 启动第一个节点
+sudo easytier-core -i 10.144.144.1
+```
+
+启动后，该节点将默认监听以下端口：
+- TCP：11010
+- UDP：11010
+- WebSocket：11011
+- WebSocket SSL：11012
+- WireGuard：11013
+
+2. 连接第二个节点（节点 B）：
+
+```bash
+# 使用第一个节点的公网 IP 连接
+sudo easytier-core -i 10.144.144.2 -p udp://第一个节点的公网IP:11010
+```
+
+3. 验证连接：
+
+```bash
+# 测试连通性
+ping 10.144.144.2
+
+# 查看已连接的对等节点
+easytier-cli peer
+
+# 查看路由信息
+easytier-cli route
+
+# 查看本地节点信息
+easytier-cli node
+```
+
+更多节点要加入网络，可以使用 `-p` 参数连接到网络中的任何现有节点：
+
+```bash
+# 使用任何现有节点的公网 IP 连接
+sudo easytier-core -i 10.144.144.3 -p udp://任何现有节点的公网IP:11010
+```
+
+### 🔍 高级功能
+
+#### 子网代理
+
+假设网络拓扑如下，节点 B 想要与其他节点共享其可访问的子网 10.1.1.0/24：
 
 ```mermaid
 flowchart LR
 
-subgraph 节点 A IP 22.1.1.1
-nodea[EasyTier\n10.144.144.1]
+subgraph 节点 A 公网 IP 22.1.1.1
+nodea[EasyTier<br/>10.144.144.1]
 end
 
 subgraph 节点 B
-nodeb[EasyTier\n10.144.144.2]
-end
-
-nodea <-----> nodeb
-
-```
-
-1. 在节点 A 上执行：
-   ```sh
-   sudo easytier-core --ipv4 10.144.144.1
-   ```
-   命令执行成功会有如下打印。
-
-   ![alt text](assets/image-2.png)
-
-2. 在节点 B 执行
-   ```sh
-   sudo easytier-core --ipv4 10.144.144.2 --peers udp://22.1.1.1:11010
-   ```
-
-3. 测试联通性
-
-   两个节点应成功连接并能够在虚拟子网内通信
-   ```sh
-   ping 10.144.144.2
-   ```
-
-   使用 easytier-cli 查看子网中的节点信息
-   ```sh
-   easytier-cli peer
-   ```
-   ![alt text](assets/image.png)
-   ```sh
-   easytier-cli route
-   ```
-   ![alt text](assets/image-1.png)
-
----
-
-### 多节点组网
-
-基于刚才的双节点组网例子，如果有更多的节点需要加入虚拟网络，可以使用如下命令。
-
-```
-sudo easytier-core --ipv4 10.144.144.2 --peers udp://22.1.1.1:11010
-```
-
-其中 `--peers ` 参数可以填写任意一个已经在虚拟网络中的节点的监听地址。
-
----
-
-### 子网代理（点对网）配置
-
-假设网络拓扑如下，节点 B 想将其可访问的子网 10.1.1.0/24 共享给其他节点。
-
-```mermaid
-flowchart LR
-
-subgraph 节点 A IP 22.1.1.1
-nodea[EasyTier\n10.144.144.1]
-end
-
-subgraph 节点 B
-nodeb[EasyTier\n10.144.144.2]
+nodeb[EasyTier<br/>10.144.144.2]
 end
 
 id1[[10.1.1.0/24]]
 
 nodea <--> nodeb <-.-> id1
-
 ```
 
-则节点 B 的 easytier 启动参数为（新增 -n 参数）
+要共享子网，在启动 EasyTier 时添加 `-n` 参数：
 
-```sh
-sudo easytier-core --ipv4 10.144.144.2 -n 10.1.1.0/24
+```bash
+# 与其他节点共享子网 10.1.1.0/24
+sudo easytier-core -i 10.144.144.2 -n 10.1.1.0/24
 ```
 
-子网代理信息会自动同步到虚拟网络的每个节点，各个节点会自动配置相应的路由，节点 A 可以通过如下命令检查子网代理是否生效。
+子网代理信息将自动同步到虚拟网络中的每个节点，每个节点将自动配置相应的路由。您可以验证子网代理设置：
 
-1. 检查路由信息是否已经同步，proxy_cidrs 列展示了被代理的子网。
+1. 检查路由信息是否已同步（proxy_cidrs 列显示代理的子网）：
 
-   ```sh
-   easytier-cli route
-   ```
-   ![alt text](assets/image-3.png)
-
-2. 测试节点 A 是否可访问被代理子网下的节点
-
-   ```sh
-   ping 10.1.1.2
-   ```
-
----
-
-### 无公网IP组网
-
-EasyTier 支持共享公网节点进行组网。目前已部署共享的公网节点 ``tcp://easytier.public.kkrainbow.top:11010``。
-
-使用共享节点时，需要每个入网节点提供相同的 ``--network-name`` 和 ``--network-secret`` 参数，作为网络的唯一标识。
-
-以双节点为例，节点 A 执行：
-
-```sh
-sudo easytier-core -i 10.144.144.1 --network-name abc --network-secret abc -e 'tcp://easytier.public.kkrainbow.top:11010'
+```bash
+# 查看路由信息
+easytier-cli route
 ```
 
-节点 B 执行
+![路由信息](/assets/image-3.png)
 
-```sh
-sudo easytier-core --ipv4 10.144.144.2 --network-name abc --network-secret abc -e 'tcp://easytier.public.kkrainbow.top:11010'
+2. 测试是否可以访问代理子网中的节点：
+
+```bash
+# 测试到代理子网的连通性
+ping 10.1.1.2
 ```
 
-命令执行成功后，节点 A 即可通过虚拟 IP 10.144.144.2 访问节点 B。
+#### WireGuard 集成
 
----
+EasyTier 可以作为 WireGuard 服务器，允许任何安装了 WireGuard 客户端的设备（包括 iOS 和 Android）访问 EasyTier 网络。以下是设置示例：
 
-### 其他配置
+```mermaid
+flowchart LR
 
-可使用 ``easytier-core --help`` 查看全部配置项
+ios[[iPhone<br/>已安装 WireGuard]]
 
+subgraph 节点 A 公网 IP 22.1.1.1
+nodea[EasyTier<br/>10.144.144.1]
+end
 
-# 路线图
+subgraph 节点 B
+nodeb[EasyTier<br/>10.144.144.2]
+end
 
-- [ ] 完善文档和用户指南。
-- [ ] 支持加密、TCP 打洞等特性。
-- [ ] 支持 Android、IOS 等移动平台。
-- [ ] 支持 Web 配置管理。
+id1[[10.1.1.0/24]]
 
-# 社区和贡献
+ios <-.-> nodea <--> nodeb <-.-> id1
+```
 
-我们欢迎并鼓励社区贡献！如果你想参与进来，请提交 [GitHub PR](https://github.com/KKRainbow/EasyTier/pulls)。详细的贡献指南可以在 [CONTRIBUTING.md](https://github.com/KKRainbow/EasyTier/blob/main/CONTRIBUTING.md) 中找到。
+1. 启动启用 WireGuard 门户的 EasyTier：
 
-# 相关项目和资源
+```bash
+# 将一个 WireGuard 客户端注册为虚拟 peer 10.144.144.3
+sudo easytier-core -i 10.144.144.1 \
+  --network-secret portal-secret \
+  --vpn-portal wg://0.0.0.0:11013 \
+  --vpn-portal-private-key "$(wg genkey)" \
+  --vpn-portal-client phone=10.144.144.3
+```
 
-- [ZeroTier](https://www.zerotier.com/): 一个全球虚拟网络，用于连接设备。
-- [TailScale](https://tailscale.com/): 一个旨在简化网络配置的 VPN 解决方案。
-- [vpncloud](https://github.com/dswd/vpncloud): 一个 P2P Mesh VPN
+2. 获取 WireGuard 客户端配置：
 
-# 许可证
+```bash
+# 获取 WireGuard 客户端配置
+easytier-cli vpn-portal
+```
 
-EasyTier 根据 [Apache License 2.0](https://github.com/KKRainbow/EasyTier/blob/main/LICENSE) 许可证发布。
+3. 如果输出配置中的 `Peer.Endpoint` 是通配地址，将其替换为 EasyTier
+   节点的公网 IP/域名后即可导入。`Interface.Address` 只是客户端本地地址，
+   可以改为任意 IPv4 地址；EasyTier 会把它转换成已注册的虚拟 peer 地址。
 
-# 联系方式
+#### 自建公共共享节点
 
-- 提问或报告问题：[GitHub Issues](https://github.com/KKRainbow/EasyTier/issues)
-- 讨论和交流：[GitHub Discussions](https://github.com/KKRainbow/EasyTier/discussions)
-- QQ 群： 949700262
+您可以运行自己的公共共享节点来帮助其他节点相互发现。公共共享节点只是一个普通的 EasyTier 网络（具有相同的网络名称和密钥），其他网络可以连接到它。
+
+要运行公共共享节点：
+
+```bash
+# 公共共享节点无需指定 IPv4 地址
+sudo easytier-core --network-name mysharednode --network-secret mysharednode
+```
+
+网络设置成功后，您可以轻松配置它以在系统启动时自动启动。请参阅 [一键注册服务指南](https://easytier.cn/en/guide/network/oneclick-install-as-service.html) 了解如何将 EasyTier 注册为系统服务。
+
+## 相关项目
+
+- [ZeroTier](https://www.zerotier.com/)：用于连接设备的全球虚拟网络。
+- [TailScale](https://tailscale.com/)：旨在简化网络配置的 VPN 解决方案。
+
+### 联系我们
+
+- 💬 **[Telegram 群组](https://t.me/easytier)**
+- 👥 **QQ 群**
+  - 一群 [949700262](https://qm.qq.com/q/wFoTUChqZW)
+  - 二群 [837676408](https://qm.qq.com/q/4V33DrfgHe)
+  - 三群 [957189589](https://qm.qq.com/q/YNyTQjwlai)
+
+## 许可证
+
+EasyTier 在 [LGPL-3.0](https://github.com/EasyTier/EasyTier/blob/main/LICENSE) 许可下发布。
+
+## 使用规范
+
+请仅将 EasyTier 用于合法用途，并遵守适用的法律法规。使用者有责任确保其已获授权连接和管理相关网络与设备。
+
+## 赞助
+
+本项目的 CDN 加速和安全防护由腾讯云 EdgeOne 赞助。
+
+<p align="center">
+<a href="https://edgeone.ai/?from=github" target="_blank">
+<img src="assets/edgeone.png" width="200">
+</a>
+</p>
+
+特别感谢 [浪浪云](https://langlangy.cn/?i26c5a5) 和 [雨云](https://www.rainyun.com/NjM0NzQ1_) 赞助我们的公共服务器。
+也感谢 [林枫云](https://www.dkdun.cn/aff/RZGBFYSW) 对 EasyTier 的支持。
+
+<p align="center">
+<a href="https://langlangy.cn/?i26c5a5" target="_blank">
+<img src="assets/langlang.png" width="200">
+</a>
+<a href="https://langlangy.cn/?i26c5a5" target="_blank">
+<img src="assets/raincloud.png" width="200">
+</a>
+<a href="https://www.dkdun.cn/aff/RZGBFYSW" target="_blank">
+<img src="assets/linfengyun.png" width="200" alt="林枫云">
+</a>
+</p>
+
+如果您觉得 EasyTier 有帮助，请考虑赞助我们。软件开发和维护需要大量的时间和精力，您的赞助将帮助我们更好地维护和改进 EasyTier。
+
+<p align="center">
+<img src="assets/wechat.png" width="200">
+<img src="assets/alipay.png" width="200">
+</p>

android.nix

@@ -0,0 +1,116 @@
+# Android build environment
+{
+  pkgs,
+  nixpkgs,
+  system,
+}:
+
+let
+  androidEnv = pkgs.callPackage "${nixpkgs}/pkgs/development/mobile/androidenv" {
+    inherit pkgs;
+    licenseAccepted = true;
+  };
+
+  includeAuto = pkgs.stdenv.hostPlatform.isx86_64 || pkgs.stdenv.hostPlatform.isDarwin;
+  ndkVersion = "26.1.10909125";
+  ndkVersions = [ ndkVersion ];
+
+  sdkArgs = {
+    includeNDK = true;
+    includeSources = true;
+    includeSystemImages = false;
+    includeEmulator = false;
+    inherit ndkVersions;
+    useGoogleAPIs = true;
+    useGoogleTVAddOns = true;
+    buildToolsVersions = [ "34.0.0" ];
+    numLatestPlatformVersions = 10;
+    includeExtras = [
+      "extras;google;gcm"
+    ]
+    ++ pkgs.lib.optionals includeAuto [
+      "extras;google;auto"
+    ];
+    extraLicenses = [
+      "android-sdk-preview-license"
+      "android-googletv-license"
+      "android-sdk-arm-dbt-license"
+      "google-gdk-license"
+      "intel-android-extra-license"
+      "intel-android-sysimage-license"
+      "mips-android-sysimage-license"
+    ];
+  };
+
+  androidComposition = androidEnv.composeAndroidPackages sdkArgs;
+  androidSdk = androidComposition.androidsdk;
+  platformTools = androidComposition.platform-tools;
+  cmake = androidComposition.cmake;
+  ndkHostTag =
+    if pkgs.stdenv.isLinux then
+      "linux-x86_64"
+    else if pkgs.stdenv.isDarwin then
+      "darwin-x86_64"
+    else
+      "";
+  ndkToolchain = "${androidSdk}/libexec/android-sdk/ndk/${ndkVersion}/toolchains/llvm/prebuilt/${ndkHostTag}";
+in
+{
+  inherit
+    androidSdk
+    platformTools
+    cmake
+    ndkToolchain
+    ndkVersion
+    ;
+
+  # List of packages required for Android development
+  packages = [
+    pkgs.jdk # openjdk 21
+    androidSdk
+    platformTools
+    cmake
+    pkgs.glibc_multi.dev
+  ];
+
+  # Provide Rust extensions/targets for use by the upper-level flake
+  rust = {
+    extensions = [ "rust-std" ];
+    targets = [
+      "aarch64-linux-android"
+      "armv7-linux-androideabi"
+      "i686-linux-android"
+      "x86_64-linux-android"
+    ];
+  };
+
+  # Android environment variables and shellHook
+  envVars = {
+    LANG = "C.UTF-8";
+    LC_ALL = "C.UTF-8";
+    JAVA_HOME = "${pkgs.jdk}/lib/openjdk";
+    ANDROID_SDK_ROOT = "${androidSdk}/libexec/android-sdk";
+    ANDROID_NDK_ROOT = "\${ANDROID_SDK_ROOT}/ndk-bundle";
+    NDK_HOME = "${androidSdk}/libexec/android-sdk/ndk/${ndkVersion}";
+    LIBCLANG_PATH = "${ndkToolchain}/lib";
+    KCP_SYS_EXTRA_HEADER_PATH = "${ndkToolchain}/lib/clang/19/include:${pkgs.glibc_multi.dev}/include";
+    ZSTD_SYS_STATIC = "1";
+    BINDGEN_EXTRA_CLANG_ARGS = "--sysroot=${ndkToolchain}/sysroot -I${ndkToolchain}/lib/clang/17/include ";
+
+    shellHook = ''
+      echo "Android environment activated"
+      export GRADLE_OPTS="-Dorg.gradle.project.android.aapt2FromMavenOverride=$(echo "$ANDROID_SDK_ROOT/build-tools/"*"/aapt2")"
+      cmake_root="$(echo "$ANDROID_SDK_ROOT/cmake/"*/)"
+      export PATH="$cmake_root/bin:$PATH"
+
+      unset NIX_CFLAGS_COMPILE
+      unset NIX_CFLAGS_COMPILE_FOR_BUILD
+
+      cat <<EOF > easytier-gui/local.properties
+      sdk.dir=$ANDROID_SDK_ROOT
+      ndk.dir=$ANDROID_NDK_ROOT
+      cmake.dir=$cmake_root
+      EOF
+    '';
+  };
+}

build.rs

@@ -1,102 +0,0 @@
-#[cfg(target_os = "windows")]
-use std::{
-    env,
-    fs::File,
-    io::{copy, Cursor},
-    path::PathBuf,
-};
-
-#[cfg(target_os = "windows")]
-struct WindowsBuild {}
-
-#[cfg(target_os = "windows")]
-impl WindowsBuild {
-    fn check_protoc_exist() -> Option<PathBuf> {
-        let path = env::var_os("PROTOC").map(PathBuf::from);
-        if path.is_some() && path.as_ref().unwrap().exists() {
-            return path;
-        }
-
-        let path = env::var_os("PATH").unwrap_or_default();
-        for p in env::split_paths(&path) {
-            let p = p.join("protoc");
-            if p.exists() {
-                return Some(p);
-            }
-        }
-
-        None
-    }
-
-    fn get_cargo_target_dir() -> Result<std::path::PathBuf, Box<dyn std::error::Error>> {
-        let out_dir = std::path::PathBuf::from(std::env::var("OUT_DIR")?);
-        let profile = std::env::var("PROFILE")?;
-        let mut target_dir = None;
-        let mut sub_path = out_dir.as_path();
-        while let Some(parent) = sub_path.parent() {
-            if parent.ends_with(&profile) {
-                target_dir = Some(parent);
-                break;
-            }
-            sub_path = parent;
-        }
-        let target_dir = target_dir.ok_or("not found")?;
-        Ok(target_dir.to_path_buf())
-    }
-
-    fn download_protoc() -> PathBuf {
-        println!("cargo:info=use exist protoc: {:?}", "k");
-        let out_dir = Self::get_cargo_target_dir().unwrap();
-        let fname = out_dir.join("protoc");
-        if fname.exists() {
-            println!("cargo:info=use exist protoc: {:?}", fname);
-            return fname;
-        }
-
-        println!("cargo:info=need download protoc, please wait...");
-
-        let url = "https://github.com/protocolbuffers/protobuf/releases/download/v26.0-rc1/protoc-26.0-rc-1-win64.zip";
-        let response = reqwest::blocking::get(url).unwrap();
-        println!("{:?}", response);
-        let mut content = response
-            .bytes()
-            .map(|v| v.to_vec())
-            .map(Cursor::new)
-            .map(zip::ZipArchive::new)
-            .unwrap()
-            .unwrap();
-        let protoc_zipped_file = content.by_name("bin/protoc.exe").unwrap();
-        let mut content = protoc_zipped_file;
-
-        copy(&mut content, &mut File::create(&fname).unwrap()).unwrap();
-
-        fname
-    }
-
-    pub fn check_for_win() {
-        // add third_party dir to link search path
-        println!("cargo:rustc-link-search=native=third_party/");
-        let protoc_path = if let Some(o) = Self::check_protoc_exist() {
-            println!("cargo:info=use os exist protoc: {:?}", o);
-            o
-        } else {
-            Self::download_protoc()
-        };
-        std::env::set_var("PROTOC", protoc_path);
-    }
-}
-
-fn main() -> Result<(), Box<dyn std::error::Error>> {
-    #[cfg(target_os = "windows")]
-    WindowsBuild::check_for_win();
-
-    tonic_build::configure()
-        .type_attribute(".", "#[derive(serde::Serialize, serde::Deserialize)]")
-        .type_attribute("cli.DirectConnectedPeerInfo", "#[derive(Hash)]")
-        .type_attribute("cli.PeerInfoForGlobalMap", "#[derive(Hash)]")
-        .btree_map(&["."])
-        .compile(&["proto/cli.proto"], &["proto/"])
-        .unwrap();
-    // tonic_build::compile_protos("proto/cli.proto")?;
-    Ok(())
-}

docs/central-network-e2e.md

@@ -0,0 +1,209 @@
+# 中央网络管理 E2E 验证记录
+
+## 范围与执行约定
+
+- 被测 PR：`feat/web-central-console-v2`；初始代码提交：后端 `5f66627d`，前端 `57a15acb`。
+- 测试日期：2026-09-30。先建立本清单，再逐项执行和回填结果。
+- 主验证链路：真实浏览器 / HTTP API → 独立 SQLite 数据库 → Web 中央服务 → Docker 内真实 Core → 配置文件 / peer / route / 实际数据包。
+- 数据面测试使用隔离 network namespace 和测试专属进程；不修改现有业务节点。
+- `通过` 必须有实际执行证据；单元测试、mock 页面测试不能冒充真实 E2E。覆盖不完整标记 `部分通过`，环境障碍标记 `阻塞`，缺陷标记 `失败`，未执行保持 `待测`。
+- 首轮只记录缺陷；用户随后批准修复，修复后的专项和受影响链路回归见下文，保留首轮失败证据。
+- 本文记录中央网络相关功能；第三方 OIDC/验证码供应商、其他平台原生 GUI 不纳入本轮完整 E2E 承诺。
+
+## 环境与复现入口
+
+- 宿主机 Web：`cargo build -p easytier-web --features embed`，Docker `rust` 中 Core/CLI：`cargo build -p easytier --bins`；版本 `2.7.0-57a15acb`。
+- `rust` 容器具备 root、TUN、iproute2、原生 wg、ping、Python。每次数据面测试创建独立 bridge 和四个 network namespace，清理时只删除本次资源。未修改容器全局 IP forwarding。
+- 数据面复现：构建后在 `easytier-web/frontend` 执行 `node tests/central-coverage.mjs`。独立 SQLite、随机端口和进程日志保存在 `.test-env/central-e2e-*`。
+- 真实 baseline 使用原 `central-e2e.test.mjs`，本次临时副本仅跳过重复构建并增加截图，结束已删除。
+
+## 用例与结果
+
+### 访问与运行模式
+
+| ID | 测试点 | 步骤 / 预期断言 | 状态 | 结果与证据 |
+|---|---|---|---|---|
+| A01 | 登录与会话 | 真实浏览器登录，未登录访问中央接口被拒绝，登出后会话失效 | 通过 | 真实 Chromium 双账号登录；匿名与登出后中央接口 401。security results。 |
+| A02 | 控制台元信息 | 用户名、配置服务器协议/端口、Gateway 开关/地址与启动参数一致 | 通过 | 真实 console-info 核对用户名、协议/端口及模式；Gateway启用/关闭的 peer_url 与 relay_data 均对照启动参数。 |
+| A03 | 中央与 Console 模式隔离 | 外部 webhook 模式不暴露中央网络路由；原有内部 Full/Patch API 可用 | 通过 | 外部 webhook 模式中央 GET 404/POST 405；真实 Core internal Full/Patch、Web 重启与删除 TOML 通过。 |
+| A04 | Gateway 启动参数校验 | 无 Gateway 时禁止创建 Gateway 网络；外部 webhook 与 Gateway 同时配置被拒绝 | 通过 | 无 Gateway 建网 400；webhook+Gateway、监听协议不匹配、非法地址启动 exit 2。 |
+| A05 | 跨租户隔离 | 另一租户不能读写网络、成员、凭据、ACL、设备，也不能代理其节点 RPC | 通过 | 双租户网络/成员/配置/ACL/凭据/设备/在线代理 RPC 全部隔离；另一网络使用原凭据不能接入。 |
+
+### 设备管理
+
+| ID | 测试点 | 步骤 / 预期断言 | 状态 | 结果与证据 |
+|---|---|---|---|---|
+| D01 | 设备登记 | 真实 Core 使用登记命令连接，机器 ID、主机名、版本、在线状态可见 | 通过 | 隔离 netns 内三个真实 Core 登记，API 返回机器 ID、版本和在线信息。 |
+| D02 | 设备展示 | 搜索、排序、列表/卡片、详情及设备所属网络正确 | 通过 | 独立真实浏览器：两 Core 的搜索、排序、列表/卡片、详情与所属网络；刷新一致。 |
+| D03 | 别名 | 保存、清空、超长拒绝；刷新和服务重启后保持 | 通过 | 别名设置/清空/超长拒绝；真实 Web 重启后 Persisted Alias 仍在。 |
+| D04 | 离线与重连 | Core 停止后显示离线但保留记录，重连后恢复在线且不重复登记 | 通过 | 真实停止/重启 Core，离线变更在重连后实际生效；设备不重复。 |
+| D05 | 删除设备 | 移除设备及其成员关系、运行配置和引用；不封禁时允许重新登记 | 通过 | 真实删除并移除成员；非封禁删除后同 machine ID 重新登记成功。 |
+| D06 | 封禁与解封 | 删除并封禁后拒绝重连，封禁列表记录尝试；解封后可重新登记 | 通过 | 删除封禁后重连尝试被记录；解封后真实 Core 重登记且不恢复旧成员。 |
+
+### 网络生命周期
+
+| ID | 测试点 | 步骤 / 预期断言 | 状态 | 结果与证据 |
+|---|---|---|---|---|
+| N01 | Gateway 网络创建 | 浏览器创建安全 Gateway 网络，真实成员连接到正确 Gateway | 通过 | 真实浏览器建安全 Gateway 网络；三个 TUN 成员实际 ping 互通。 |
+| N02 | Manual 网络 | 指定自建真实 peer，配置下发后成功连接 | 通过 | 真实自建 A 作为 Manual peer；B 下发相同 URL 并实际 ping A。 |
+| N03 | PublicServer 网络 | 使用隔离自建公开 peer 验证 URL 下发和连接，不依赖公网公共节点 | 通过 | PublicServer 指向隔离自建 A；Core 编译后 peer URL 一致并实际互通。运行配置通用表示为 Manual，不要求保留 UI 模式名。 |
+| N04 | Standalone 网络 | 允许创建并下发，不自动配置外部 peer | 通过 | Standalone 保存后真实 Core peer_urls 清空，不自动连外部 peer。 |
+| N05 | 基础设置与密钥 | 修改显示名、网络名、网段和网络密钥；成员运行配置随之更新 | 通过 | 显示名/网络名/密钥旋转实际 Core 配置收敛并恢复 ping；网段相关见 R03。 |
+| N06 | 安全模式 | 安全/非安全网络均可组网，切换后重新收敛 | 通过 | 安全→非安全→安全均实际收敛，期间分别验证 ping。 |
+| N07 | 模式切换 | Gateway 与其他模式切换，旧 Gateway 退出、新配置生效 | 通过 | 完整模式切换及实际 ping 通过；独立 unmanaged probe 验证切 Standalone 后旧 Gateway 断开且新连接被拒，切回 Gateway 恢复。 |
+| N08 | 网络删除 | 在线/离线成员配置最终清除，删除最后一个网络不残留 Gateway | 通过 | 最后网络删除后在线/离线成员实例与 TOML 清除；独立 probe 确认旧 Gateway 断开且新 probe 无法接入，全程 Web 不重启。 |
+| N09 | 非法及重复配置 | 空名字、错误 URL/CIDR、重复网络身份被拒绝且不破坏原配置 | 通过 | 修复后 Manual/PublicServer 在空网创建和已有成员更新时均拒绝 bogus://；合法 discovery 协议仍可保存。原缺陷与修复证据见 F01。 |
+| N10 | 多网络汇总 | 同一设备加入两个网络，修改/删除其一不影响另一个 | 通过 | 同一 Core 两实例；删除第二网络后第一个实例保留且运行。 |
+
+### 成员配置
+
+| ID | 测试点 | 步骤 / 预期断言 | 状态 | 结果与证据 |
+|---|---|---|---|---|
+| M01 | 批量添加/移除 | 真实节点加入/离开；重复/不存在/跨租户设备的批量请求不部分提交 | 通过 | 三真实节点添加；重复 ID 409、部分未知/外租户 404，成员与实例均无部分提交；移除另见 D05/N08。 |
+| M02 | 主机名与静态 IP | 设置和清空成员主机名、IP，运行节点反映修改；重复/越界 IP 被拒绝 | 通过 | 真实成员主机名/IP 设置与清空、重复/越界拒绝；配置生效后实际 ping 通过。 |
+| M03 | 代理子网 | IPv4 子网配置、路由广播及转发一致；当前不支持的 IPv6 输入原子拒绝 | 通过 | IPv4 代理子网真实路由和 ping 通过；IPv6 输入保存前400，数据库及两Core TOML保持。原缺陷见 F02。 |
+| M04 | 高级配置 | 读取、保存、重置覆盖配置；运行与持久化一致 | 通过 | 高级 MTU 1300 下发；读取覆盖、清空重置均经真实 API 验证。 |
+| M05 | 中央所有权 | 高级配置不能覆盖中央身份、凭据、ACL；直接 REST/RPC 修改中央实例被拒绝 | 通过 | 独立实测伪造/清空 identity、secure_mode、managed_credentials、ACL 均保留中央值且 MTU 生效；真实 TOML/RPC 核对。直接 run/save/delete 与凭据写 RPC 均 409。 |
+| M06 | 离线下发 | 设备离线期间修改/删除，重连后恢复最新完整配置 | 通过 | 离线修改主机名 → Web 重启 → Core 重连读到最新值并能 ping；baseline另验证离线删除 TOML。 |
+| M07 | 并发操作 | 同时修改不同成员/网络，最终完整配置包含全部成功变更 | 通过 | 同时修改两个真实成员主机名，最终成员配置同时保留两次成功修改。 |
+| M08 | 成员编辑竞态 | 迟到的 A 成员配置响应不能污染 B 成员表单和保存目标 | 通过 | route.fetch 取得真实 A 响应后延迟交付；切到 B，迟到响应未覆盖 B，PUT 与持久化目标均正确。 |
+
+### 凭据及临时节点
+
+| ID | 测试点 | 步骤 / 预期断言 | 状态 | 结果与证据 |
+|---|---|---|---|---|
+| C01 | 凭据生成与展示 | 生成、列表、复制/接入信息、TTL 和复用属性一致，刷新仍可查看 | 通过 | 真实浏览器生成一小时/nonreusable凭据；读取剪贴板核对 secret/CLI/TOML；刷新保持，执行复制命令成功接入。 |
+| C02 | 多节点复用 | 两个真实临时 Core 使用同一 reusable 凭据，成员/凭据视图均展示 | 通过 | 真实 baseline 两个独立 Core 使用同一 reusable 凭据；成员和凭据页均展示两个 peer。 |
+| C03 | 非复用约束 | 同一 non-reusable 凭据的并发连接受限 | 通过 | 两个真实 Core 共用不可复用凭据，仅一个身份进入管理员路由；停止赢家后另一节点接替。控制连接数量不是路由独占的判断标准。 |
+| C04 | 撤销 | 撤销后既有连接断开且不能重新连接，视图清理 | 通过 | 真实 baseline 撤销后两 Core 断开，等待 6 秒仍不能重连，临时节点视图清空。 |
+| C05 | 过期 | 短 TTL 凭据到期后连接被清理，不能再次接入 | 通过 | 15 秒 TTL 到期后实际远端路由移除；用同一凭据重启 Core，6.5 秒仍不能重连。 |
+| C06 | 临时托管成员 | 临时成员收到专属凭据而非网络密钥，IP/子网与权限一致 | 通过 | 真实 TOML/credential grant 校验；临时 C→B 指定 ACL 允许而 A 被阻断；C 代理子网实际访问按 ACL 区分 A/B。 |
+| C07 | 受引用与非法凭据 | 被成员引用的凭据不可单独撤销，非法 TTL/重复 ID 不破坏原状态 | 通过 | 被临时成员引用撤销 409；TTL 0/超一年 400、负值 422、重复 ID 409且原列表保持。 |
+
+### ACL 策略
+
+| ID | 测试点 | 步骤 / 预期断言 | 状态 | 结果与证据 |
+|---|---|---|---|---|
+| L01 | 编辑流程 | 浏览器新增、编辑、禁用、排序、删除规则，刷新后保持 | 通过 | 真实浏览器 ACL 新建、编辑、禁用、拖拽排序、删除；API 与页面刷新均确认持久化。 |
+| L02 | 默认策略 | 真实数据包验证默认 allow/deny，而不只检查保存成功 | 通过 | 实际 ICMP：默认 allow 可达 → deny 阻断 → allow 恢复。 |
+| L03 | 成员与组选择 | 真实安全组成员匹配，未授权成员不能借用另一成员权限 | 通过 | 实际安全成员组：指定 A→B 允许，未授权 C→B 被阻断。 |
+| L04 | 协议与端口 | 实际 TCP/UDP/ICMP 流量验证允许/拒绝及端口范围 | 通过 | 五个真 echo 端口先确认存活；TCP 18080 通/18082 断；UDP 范围两端 18081、18082 通/18083 断；跨协议和 ICMP 另有实测。 |
+| L05 | 子网目标 | 验证成员代理子网规则的编译和真实转发效果 | 通过 | IPv4 代理子网实际 ICMP；仅允许子网时节点 VIP 不可达；临时成员代理权限另独立实测通过。IPv6输入缺陷见 F02。 |
+| L06 | 统计 | 产生流量后节点 ACL 统计可查询并对应命中规则 | 通过 | 产生 ping 后真实 ACL RPC stats 返回对应规则 ID、命中包和字节计数。 |
+| L07 | 删除引用与非法规则 | 移除成员清理引用；错误选择器/端口被拒绝且旧策略保持 | 通过 | 真实 baseline 移除成员清理 ACL 引用；14 种非法规则全部 400，每次读回旧策略完全相等。 |
+
+### WireGuard 管理
+
+| ID | 测试点 | 步骤 / 预期断言 | 状态 | 结果与证据 |
+|---|---|---|---|---|
+| W01 | 启用与关闭 | 成员高级配置启用 WireGuard；关闭保留私钥和客户端，再启用恢复 | 通过 | 原生 wg 客户端实际流量：关闭阻断；服务端私钥和客户端保留；重新启用恢复。 |
+| W02 | 客户端增删与清空 | 中央成员通过配置保存管理客户端；普通实例热更新同步持久化 | 通过 | 中央完整配置添加/清空；普通 Console 模式 RPC 添加/移除/清空，对照实际 Core、Web SQLite、TOML 与重启恢复。 |
+| W03 | 真实 WireGuard 接入 | 原生 wg 客户端完成握手，通过隧道访问真实网络节点 | 通过 | 原生 Linux wg latest-handshakes 非零；通过 Portal 实际 ping 另一真实 Core。 |
+| W04 | 地址/权限校验 | 重复/非法地址与未声明组被拒绝，已有有效客户端不受损 | 通过 | 中央配置重复地址/名称、非法IP、网络/广播/节点地址、未知组均400，原配置及流量保持；普通实例验证同前。见 F02。 |
+| W05 | 撤销与重启持久化 | 移除客户端后不能访问；保留客户端在节点/服务重启后仍能接入 | 通过 | 原生 wg 清空客户端后实际 ping 被阻断；有效客户端跨 Core 重启可重新握手和访问。 |
+
+### 运行详情与数据面
+
+| ID | 测试点 | 步骤 / 预期断言 | 状态 | 结果与证据 |
+|---|---|---|---|---|
+| R01 | 节点详情 | 真实节点 peer、route、TOML、版本/错误等展示与 RPC 一致 | 通过 | 真实浏览器 peer/route IP/CIDR、连接计数、版本与 RPC 一致；导出 TOML 与真实 RPC 逐字相同。 |
+| R02 | 日志级别 | 读取/设置真实节点日志级别并读回确认 | 通过 | 真实浏览器逐级设置六种日志级别、RPC读回与整页刷新回显均正确；省略字段显示Disabled，中文选项正确。见 F03。 |
+| R03 | DHCP 全动态网络 | 两个全 DHCP 节点在无静态 IP 时分配不同地址并能互通 | 通过 | 三个全 DHCP Core 无静态成员，获得三个不同 10.126.126.x 地址并实际互通。 |
+| R04 | DHCP 地址保持 | 已有地址节点暂时失去其他 IPv4 广播，不切回默认网段 | 通过 | 另独立验证 A DHCP 从 B 继承非默认10.88.99.1/24；停B、route只剩无IPv4 Gateway后，18秒9次读回均保留原地址。 |
+| R05 | Gateway 同端口分流 | 管理连接和普通/Noise 组网连接共用端口，相互不串流 | 通过 | 同一 TCP端口承载三 Core 的配置登记及 Gateway secure/普通组网，切换安全模式后实际 ping 均通过。 |
+| R06 | Gateway 中继开关 | 以只经 Gateway 的拓扑确认 relay_data 开关效果 | 通过 | 真实 Gateway 拓扑禁用成员 P2P；relay_data 开→ping通，重启关→ping断，重启开→恢复。 |
+
+### 恢复与兼容性
+
+| ID | 测试点 | 步骤 / 预期断言 | 状态 | 结果与证据 |
+|---|---|---|---|---|
+| P01 | Web 服务重启 | 网络、成员、凭据、ACL、Gateway 与设备别名恢复，运行配置不丢失 | 通过 | 真实 Web 重启恢复网络/成员/凭据/Gateway/别名及离线新配置；另保持 default deny 的 UDP 范围 ACL 重启，GET 完全相同且实际允许/拒绝均保持。 |
+| P02 | Core 重启 | 持久化 TOML 恢复并与最新中央配置收敛 | 通过 | 真实 Core 重启后最新中央配置恢复；WireGuard 保留客户重新接入。 |
+| P03 | 普通实例兼容 | 非中央实例已有保存/运行/停止及 WireGuard 操作保持可用 | 通过 | 外部 Console webhook 模式真实普通实例保存/启动/停止/重启/删除及 WG 热更新；核对 Web SQLite 与 Core TOML。 |
+| P04 | HTTP 安全随机 | 普通 HTTP 无 randomUUID 时 ACL ID 和网络密钥仍用安全随机源 | 通过 | loopback HTTP 页面手动禁用 randomUUID，观测 getRandomValues；ACL ID 与密钥成功生成，新密钥落入真实 Core TOML。 |
+| P05 | 浏览器交互补充 | 导航/刷新、暗色/多语言/移动端及错误恢复；明确区分真实 E2E 与 mock UI 测试 | 通过 | 真实中英/明暗/桌面移动布局、导航刷新及 Web 真停机→Retry→重启重登录恢复；另有16项mock UI补充。 |
+
+## 执行记录与证据索引
+
+首次执行 59 个功能条目：**55 通过、4 失败、0 待测**。当时失败的 N09、M03、W04、R02 归为下述三组发现；不把同一无效配置造成的后续失败重复计数。主数据面基线 22/22 通过不代表整体验收通过；审查补强和定向复测单独列出，未隐藏测试等待条件问题。
+
+原始日志、截图、临时密钥/DB 和辅助脚本保留在本机忽略目录 `.test-env/`，不提交测试密钥和数据库。下表路径相对于仓库根目录；辅助报告中保留原 `/tmp` 来源路径，但其内容也已复制归档。
+
+| 证据 | 最终执行 | 归档位置 |
+|---|---|---|
+| 主真实数据面 | 22/22 组通过 | `.test-env/central-e2e-2316549/results.json` 与各进程日志；复现脚本 `easytier-web/frontend/tests/central-coverage.mjs` |
+| 审查后加强端口断言的主套件 | 21/22 通过；M02 等待条件修正后定向4/4通过 | `.test-env/central-e2e-2745102/results.json`；`.test-env/central-e2e-2971552/results.json` |
+| 原真实 baseline | 1/1 通过，18.24 秒 | `.test-env/central-e2e-evidence-20260930/central-e2e-baseline-evidence/baseline.log`，3 张真实截图 |
+| Dashboard mock 补充 | 16/16 通过，33.56 秒 | 同上 `dashboard.log`；此项不计为真实后端验证 |
+| 访问/隔离/Console/非法 URL | 14 组通过，N09 失败 | `.test-env/central-e2e-evidence-20260930/central-security-e2e-vM8P3H/` |
+| Gateway 在线生命周期 | 3/3 通过，Web PID 全程不变 | `.test-env/central-e2e-evidence-20260930/central-security-e2e-CY4Q6S/` |
+| 非法 ACL | 14 个请求全部正确拒绝 | `.test-env/central-e2e-evidence-20260930/central-security-e2e-qw5Fsn/` |
+| 凭据生命周期 | 1 综合场景通过，55.39 秒 | `.test-env/central-e2e-evidence-20260930/central-e2e-credential-evidence/` |
+| 批次原子性/浏览器凭据复制 | 1 综合场景通过，6.46 秒 | `.test-env/central-e2e-evidence-20260930/central-e2e-batch-evidence/` |
+| 同协议端口范围/非默认 ACL 重启 | 4/4 通过 | `.test-env/central-e2e-port-range-2757460/results.json` |
+| 中央 override 所有权 | 2/2 通过 | `.test-env/central-e2e-evidence-20260930/central-security-e2e-eOCOeK/` |
+| 临时成员真实包权限 | 3/3 通过 | `.test-env/central-e2e-temporary-2280549/results.json` |
+| 非默认 DHCP 地址保持 | 1/1 通过，18 秒连续观察 | `.test-env/central-e2e-dhcp-hold-2439398/results.json` |
+| 真实 UI/竞态/随机数/故障恢复 | 6/6 通过 | `.test-env/central-e2e-evidence-20260930/central-ui-e2e-YhcgUD/`，16 张截图 |
+| 普通实例/WG/IPv6诊断 | 12/12 组通过 | `.test-env/central-e2e-evidence-20260930/central-security-e2e-F7VjL0/` |
+| 中央 WG 非法配置 | 3 个非法请求均暴露 F02 | `.test-env/central-e2e-evidence-20260930/central-security-e2e-HvHrqo/` |
+| 真实节点详情/日志级别 UI | R01 通过、R02 失败 | `.test-env/central-e2e-evidence-20260930/central-node-ui-e2e-5UwmgY/`，6 张截图 |
+
+执行过程中修正过测试假设：CIDR 地址不能直接作为 ping 目标；连续配置发布后需等待实例收敛；protobuf JSON enum 返回名称且默认零值省略；Core 通用 peer 配置不保留 PublicServer UI 名称；切到 DHCP 需清除之前固定的成员 IP；Docker 创建的 600 权限 TOML 通过容器读取；不可复用凭据检查可路由身份而非物理连接数量。这些不是产品缺陷。早期数据面记录保留于 `.test-env/central-e2e-audit-*`、`.test-env/central-e2e-2067723/`，主套件完整正向基线使用 `2316549`，端口范围同时由 `2745102` 与独立 `2757460` 实测。`2745102` 的 M02 在地址已上报但路由尚未收敛时立即 ping 失败；脚本改为等待实际可达后，原步骤定向重跑 `2971552` 4/4 通过；IPv6 阻塞证据仍使用早期运行，并由独立 Core 请求复核。
+
+## 首轮缺陷及修复状态
+
+### F01：不支持的 peer 协议可保存并触发连续失败（已修复）
+
+- **major / high confidence**；对应 N09。
+- 有效网络已有真实 Core，PATCH 网络为 Manual，`peer_urls=["bogus://127.0.0.1:9999"]`。
+- 实际 HTTP 200，SQLite 网络意图被替换；真实 Core 报 `unsupported core manual connector URL`。18 秒观察内有 292 次实例创建失败重试。
+- 预期保存前拒绝并保持有效配置。根因入口 `easytier-web/src/central_network/compiler.rs:232`，目前仅检查 URL 能否解析。
+- 证据：归档 `central-security-e2e-vM8P3H/results.json` 的 `N09-protocol` / `N09-runtime-evidence`，`central.log:1221` 起。
+- `http://` 和 `https://` 是 Core 支持的 discovery connector，不在非法协议之列。
+
+### F02：中央完整配置缺少 Core 可执行性校验（已修复已发现路径）
+
+- **major / high confidence**；对应 M03、W04。属中央编译/发布边界的局部架构问题，不能把后续每次下发失败作为新 bug。
+- 成员 PATCH `proxy_cidrs=["198.18.240.0/24","2001:db8:240::/64"]` 返回 200，但 Core 的代理网段转换只接受 IPv4；该设备 TOML 保持旧值，后续主机名/网络身份更新也不收敛。独立验证开启 IPv6 同样失败，移除 IPv6 网段成功，排除测试环境关闭 IPv6 的影响。
+- 中央成员完整配置 PUT 分别加入重复 WireGuard IP、`virtual_ip="invalid-ip"`、`groups=["not-declared"]`，都返回 200；真实 Core 分别报 duplicate IP、parse error、unknown ACL group。三轮均从有效基线独立开始并恢复。
+- 普通实例的 WG 客户端 PATCH 对上述非法输入会拒绝，且 Web DB/运行配置保持。因此普通热更新验证不能替代中央 Full 的验证。
+- 证据：`.test-env/central-e2e-audit-1689346/` 的成员快照、DB 与旧 TOML；归档 `central-security-e2e-F7VjL0/results.json`；`central-security-e2e-HvHrqo/results.json` 和 `central-full-validation.log:29` 起。
+- 修复已在中央编译阶段复用 Core 配置转换、可移植配置规范化和 Portal 客户端校验；Core 只开放原有纯校验函数。
+
+### F03：日志级别页面回显错误（已修复）
+
+- **minor / high confidence**；对应 R02；实际设置日志级别能够生效。
+- 六个下拉选项显示翻译函数源码；初始 DISABLED RPC 返回 `{}`，页面误显示 Info；设置 WARNING 后 RPC 返回 `{"level":"WARNING"}`，重开详情显示 Loading。
+- 两处局部问题：`easytier-web/frontend/src/components/NetworkDetail.vue:456-463` 使用函数作为 option label；`easytier-web/frontend/src/modules/api.ts:457-463` 未转换 protobuf 字符串枚举且零值默认不正确。
+- 证据：归档 `central-node-ui-e2e-5UwmgY/results.json` 的 R02-initial/options/after-set/reopen 与四张 R02 截图。修复后六级设置、刷新和翻译均经真实浏览器与 RPC 重新验证。
+
+## 修复回归（2026-09-30）
+
+**当前清单 59 项均为通过，0 项待测、0 项未关闭缺陷。** 原55项的证据保留；本次重跑受影响的主数据面、原浏览器生命周期及专项，未声称将首轮所有独立脚本再执行一遍。
+
+- 后端：在数据库写事务开始前的中央 `compile()` 里检查候选配置。网络级 URL 复用 Core 支持规则，覆盖无成员的网络；成员配置先合并中央字段与 override，再执行 Core 转换及 Portal 客户端校验。失败返回400，旧数据库和运行状态不变。
+- Core：只公开现有 `validate_manual_url`、`validate_clients`，没有改变实例运行逻辑、增加 RPC 或读取远端设备状态；不执行主机能力校验。
+- 前端：protobuf 日志枚举转换为数字，省略字段对应 Disabled=0；下拉项使用随语言更新的翻译字符串。
+- IPv6 代理子网按当前 Core 转换能力拒绝，本轮未扩展 IPv6 代理功能。
+
+| 回归 | 结果 | 本机证据 |
+|---|---|---|
+| 后端完整测试 | 232/232 通过，含协议/成员配置/事务不变回归 | `.test-env/central-fix-20260930/central-fix-web-tests.log` |
+| 前端构建与 Web embed 构建 | 通过 | `.test-env/central-fix-20260930/central-fix-web-build.log` |
+| Dashboard 浏览器回归 | 17/17 通过，含日志枚举专项；mock API | `.test-env/central-fix-20260930/central-fix-dashboard.log` |
+| 真实主数据面 | 22/22 通过 | `.test-env/central-e2e-6121215/results.json` |
+| 原真实浏览器生命周期 | 1/1 通过，15.92 秒 | `.test-env/central-fix-20260930/central-fix-baseline.log` |
+| 配置拒绝与原子性专项 | 14/14 通过 | `.test-env/central-validation-6182364/results.json`；脚本 `easytier-web/frontend/tests/central-validation.mjs` |
+| 真实日志级别 UI/RPC | R01/R02 均通过；六级逐次设置、刷新、中文选项 | `.test-env/central-fix-logger-20260930/evidence/results.json` |
+
+专项的12个非法请求均返回400：对照3张中央意图表完整行、网络与成员配置、两个真实 Core 的 `show_node_info` TOML，全部不变；拒绝期间每条连续15个 ping，共180包零丢包。合法 HTTP/HTTPS/TXT/SRV × Manual/PublicServer 共8次空网保存成功；IPv4代理路由/实际ping、有效WireGuard客户端和清空均通过。
+
+原 baseline 最初在旧断言“IPv6代理保存200”处失败，这正是本次修复改变的行为。现改为先断言IPv6返回400，再用受支持的IPv4代理子网完成浏览器ACL流程，重跑通过；旧输出保留在 `central-fix-baseline-old-expectation.log`，不计为新的产品回退。
+
+### 覆盖边界
+
+- 本轮覆盖所列中央管理功能在 Linux + Chromium + TCP Gateway 下的真实链路；不据此声称所有操作系统、浏览器、底层传输协议组合或长时间压力场景均通过。
+- PublicServer 使用隔离自建真实 peer；外部 Console 仅模拟第三方 webhook 的 validate-token 响应，其 Web、Core、SQLite、Full/Patch 路径真实执行。
+- HTTP 随机数用例在 loopback origin 手动禁用 randomUUID，实际调用 getRandomValues；不冒充公网非安全 origin 的浏览器兼容矩阵。
+- 所有测试专属 Web/Core、bridge 和 network namespace 均已清理；保留忽略目录证据。修复只涉及中央编译器、Core 校验函数可见性、日志页面及回归测试；未修改 ClientManager，未 push。

docs/core-architecture.md

@@ -0,0 +1,679 @@
+# EasyTier Core Architecture
+
+## Status and scope
+
+This document describes the current architecture after the portable-core
+refactor. It is the source of truth for ownership, dependency direction,
+feature boundaries, and validation. It intentionally records the resulting
+design rather than the migration history.
+
+The refactor has three principal crate roles:
+
+- `easytier-core` owns portable EasyTier configuration, protocol state,
+  routing, peer state, connectivity orchestration, packet processing, and
+  instance lifecycle.
+- `easytier` is the native composition root. It owns operating-system
+  resources, native protocol engines, process integration, CLI and native
+  presentation.
+- `easytier-proto` owns generated protobuf and RPC types, descriptor data, and
+  the feature slices needed by core and presentation users.
+
+`easytier-core` is designed to compile without direct operating-system network
+access. It supports native hosts through Rust traits and has a target-only WASI
+adapter and ABI implementation under `easytier-core/src/wasi`.
+
+This architecture does not require compatibility with old internal module
+paths. Wire compatibility, configuration compatibility, management semantics,
+and externally used application behaviour remain compatibility requirements.
+
+## Architectural vocabulary
+
+The following terms have specific meanings in this document:
+
+- **Module**: an interface and the implementation hidden behind it.
+- **Host**: the process or runtime embedding core and owning platform
+  resources.
+- **Host capability**: an operation core may request but must not implement
+  with direct OS calls.
+- **Adapter**: a concrete implementation of a Host capability or protocol
+  extension.
+- **Composition root**: code that creates core configuration, Host Adapters,
+  instances, and process-level services.
+- **Runtime configuration**: the authoritative normalized state used after an
+  instance starts.
+- **Packet plane**: portable packet classification, routing, transformation,
+  proxy/NAT state, and forwarding decisions.
+
+New abstractions should pass a deletion test: deleting a useful deep Module
+should force non-trivial policy or lifecycle logic to reappear in multiple
+callers. A pass-through wrapper with no independent invariant is not an
+architectural boundary.
+
+## Crate dependency direction
+
+The principal dependency direction is:
+
+```text
+easytier-proto <- easytier-core <- easytier
+```
+
+Presentation crates and platform integrations consume these crates. Portable
+policy must not move outward merely because one current consumer is native.
+Conversely, core must not absorb an OS mechanism or a protocol engine whose
+dependencies cannot satisfy the core target contract.
+
+### `easytier-proto`
+
+The protobuf crate is split by public Cargo features:
+
+- `core` provides the common wire messages, peer RPC messages, generated RPC
+  runtime, and descriptor bytes needed by core.
+- `api` adds management API messages.
+- protocol-specific features add only their generated message modules.
+- `json-rpc` enables the well-known protobuf JSON types used by the management
+  plane.
+- `full` is the compatibility aggregate used by complete products.
+
+The core crate depends on `easytier-proto` with default features disabled and
+enables only `core`, adding API or JSON-RPC types through its own management
+features.
+
+The main core/native path has no `prost-reflect` dependency. OSPF route
+reflection uses the focused wire editor in
+`peers/route/route_peer_wire.rs`. It retains the original encoded
+`RoutePeerInfo`, replaces only the fields credential filtering is allowed to
+change, and leaves all other top-level and nested fields intact. This is
+required so unknown fields survive mixed-version, multi-hop propagation.
+Generated Rust types remain responsible for normal message construction and
+validation.
+
+Descriptor sets are still generated and embedded by `easytier-proto`; removing
+runtime reflection did not remove descriptor data used by configuration and
+RPC tooling. The OHOS integration has its own schema service and dependency
+policy and is outside this replacement.
+
+### `easytier-core`
+
+Core owns portable behaviour and exposes capability seams. Its normal
+dependencies use Tokio runtime, time, synchronization, and I/O traits without
+requiring the full Tokio feature set.
+
+Core may depend on optional portable engines when their owning feature is
+enabled. It does not create real native TCP/UDP sockets, alter routes, open a
+TUN device, enter a network namespace, configure system DNS, manage a service,
+or invoke UPnP/NAT-PMP directly.
+
+### `easytier`
+
+The native crate owns:
+
+- process startup, shutdown, signals, service management, and allocators;
+- filesystem configuration input and persistence;
+- real TCP/UDP, DNS, TUN, raw-socket, route, interface, namespace, and socket
+  option operations;
+- UPnP and NAT-PMP operations;
+- Unix and FakeTCP resources;
+- WebSocket/WSS, QUIC, WireGuard, and KCP concrete engines;
+- native Magic DNS serving and system DNS integration;
+- CLI, web, GUI, FFI, and native management presentation.
+
+Native code may translate values and assemble Adapters. It must not maintain a
+second peer graph, reproduce core routing or hole-punch policy, or invent an
+alternative instance lifecycle.
+
+## Internal core layers
+
+The physical module layout follows this downward order:
+
+```text
+foundation
+  <- config / packet
+  <- socket
+  <- host
+  <- tunnel
+  <- listener / connectivity
+  <- peers / rpc
+  <- gateway
+  <- instance
+  <- management
+```
+
+`process_runtime` is a process- or module-scoped owner shared by instances.
+`wasi` is target integration and is compiled only for tests or the WASI target;
+it is not an additional portable domain layer.
+
+### Foundation
+
+`foundation/` contains task supervision, the time facade, rate limiting,
+statistics primitives, and the domain-neutral external operation broker. The
+broker owns asynchronous operation lifecycle and completion storage while the
+calling domain owns operation kinds, outcomes, resources, and errors.
+Foundation must not depend on a domain layer.
+
+### Configuration and packets
+
+`config/` owns:
+
+- the complete `TomlConfig` model;
+- parsing, serialization, and validation;
+- OS-independent defaults;
+- peer, encryption, gateway, and API input models;
+- normalized runtime snapshots and the live runtime configuration store.
+
+The Host supplies platform facts through `CoreInstanceHostConfig`. Core applies
+the policy that combines those facts with TOML input. This is especially
+important for a WASI build: the compile-time guest target cannot be used as a
+proxy for the Host operating system.
+
+`packet/` owns EasyTier packet structures, compression, STUN and hole-punch
+wire codecs. It does not own socket I/O or connection policy.
+
+### Socket and Host seams
+
+`socket/` contains transport-neutral primitives:
+
+- `SocketContext`, including IP-family policy, optional socket mark, and an
+  opaque network-namespace token;
+- virtual TCP socket, listener, and factory traits;
+- virtual UDP socket and factory traits;
+- UDP session multiplexing, classification, and lifecycle;
+- in-process Ring sockets.
+
+UDP sessions expose a scoped hole-punch source observer keyed by transaction
+ID. Listeners carry a registration handle for their existing receive loop, which
+reports the first matching source; dropping the observer removes the registration.
+Cone clients optionally prepare that transaction in the listener-selection RPC;
+the response echoes its ID only after registration. The registration retains
+early UDP sources until the cone-sending RPC claims it. Unclaimed registrations
+expire after 30 seconds through the existing listener cleanup loop, covering
+local socket and STUN preparation without a separate receive or sending task.
+Clients omitting the optional transaction retain registration at the sending RPC;
+older servers omit the echoed ID and do not confirm early registration.
+Connectivity owns preparation expiry, the active RPC lifetime, candidate selection
+and bounded sending to the signaled and observed addresses.
+Cone clients start the existing UDP handshake without requiring a reverse
+hole-punch packet, and the session layer remains the sole receiver.
+
+`host/` is the single home of Host capability seams:
+
+- DNS and DNS record resolution;
+- connector environment observations;
+- packet ingress and egress;
+- Host socket operation bridges and handle-based TCP/UDP/listener adapters;
+- host-owned, message-preserving tunnel endpoints.
+
+Core owns scheduling, backpressure, cancellation, UDP session state, and
+protocol state even when each actual operation crosses a Host Adapter. A Host
+Adapter owns the real resource and performs the OS operation.
+
+For host-owned tunnels, ownership crosses the guest ABI only after a bounded
+Host listener queue accepts the tunnel. The queue is registered through
+`CoreHostAdapters` and consumed by the normal `CoreListenerRuntime`, so the
+tunnel still reaches `PeerAcceptedTunnelHandler` and cannot bypass peer
+handshake, admission, events, or routing policy. Each Host receive produces
+one complete `DummyTunnel` payload; no stream framing is added. The Host owns
+transport-specific message validation and maps a clean close to tunnel EOF.
+
+Hosts without outbound sockets select `CoreConnectivityMode::InboundOnly` for
+one instance. That startup plan retains listeners and the peer/router while
+omitting STUN, outbound connectors, and hole punching. Cargo features only
+compile Host Adapters; they do not change `CoreInstance` fields, lifecycle, or
+management semantics.
+
+The native `NativeHostRuntime` is process-wide and does not retain an instance
+`GlobalCtx`, namespace guard, socket mark, or connectivity state. Differences
+between instances travel in each request's `SocketContext`. A narrow
+instance-host projection may expose listener and interface facts, but it does
+not become another socket factory.
+
+### Tunnel and listener
+
+A socket is a raw communication endpoint. A Tunnel is an EasyTier connection
+created by adding framing, metadata, handshakes, and protocol lifecycle.
+
+Core owns:
+
+- raw TCP framing and upgrade;
+- UDP tunnel/session framing and classification;
+- Ring Tunnel identity and registry state;
+- encryption and secure-datagram policy that is portable;
+- client/server protocol selection interfaces;
+- listener planning, optional/required listener policy, retry, accept
+  scheduling, running-listener registry, and orderly shutdown.
+
+Native protocol Adapters own WebSocket/WSS, QUIC, WireGuard, and KCP engines.
+Unix and FakeTCP are socket resources that feed a core protocol upgrader; they
+are not independent owners of EasyTier peer state.
+
+Each protocol registration must provide a coherent client/server Adapter.
+Unavailable configured transports must be rejected during validation or
+protocol selection in the standard runtime, rather than silently falling back
+to another transport. A compact compatibility Host may instead retain the
+desired value for management readback and omit it from normalized runtime
+state; it must not advertise or partially activate the unavailable transport.
+
+### Connectivity
+
+`connectivity/` owns:
+
+- manual connection and endpoint discovery policy;
+- direct candidate selection;
+- retry, backoff, blacklists, and listener reuse;
+- STUN requests, responses, probing, NAT inference, and published endpoint
+  state;
+- TCP and UDP hole-punch state machines;
+- UDP port-mapping policy and lease lifecycle;
+- conversion of successful sockets into protocol-upgrade requests.
+
+The Host owns DNS execution, socket syscalls, interface enumeration, bind
+device/mark/namespace operations, and concrete UPnP/NAT-PMP calls. STUN-only
+hole punching remains available when the Host does not supply a port-mapping
+Adapter.
+
+Some connectivity files intentionally implement peer-facing adapter traits for
+`PeerManagerCore`. These are localized integration edges between adjacent
+domains, not permission for lower socket or Host layers to depend on peers.
+
+### Peers and RPC
+
+`peers/` is the authoritative owner of:
+
+- admission and connection sessions;
+- peer maps and connection lifecycle;
+- ACL and whitelist decisions;
+- OSPF route calculation and graph algorithms;
+- peer and credential RPC registration;
+- foreign-network admission, identity, relay, and lifecycle;
+- peer-center state and public IPv6 policy;
+- traffic metrics and peer snapshots.
+
+Submodules progress from kernel types and utilities, through ACL/context,
+connection state, route state, manager services, and finally foreign-network
+and peer-center composition. Callers consume the public surface declared by
+the domain rather than reaching into a parallel native peer owner.
+
+`rpc/` owns the peer-flavoured RPC transport, packet fragmentation, client and
+server lifecycle, handler registry, and standalone listener/client lifecycle.
+Generated service descriptors and message types remain in `easytier-proto`.
+
+### Gateway
+
+`gateway/` owns portable packet-plane features:
+
+- proxy CIDR state and monitoring policy;
+- packet parsing, reassembly, NAT/proxy state, and TCP/UDP/ICMP decisions;
+- the smoltcp-backed portable dataplane selected by its feature;
+- SOCKS5 framing, authentication, association, routing, and session state;
+- wrapped-transport planning and session state used by KCP and QUIC Adapters;
+- DHCP allocation policy;
+- Magic DNS route and response policy;
+- VPN portal client/session policy;
+- UDP broadcast classification and rewrite policy.
+
+Each VPN portal client is normalized to one attached-peer IPv4 CIDR. The
+portable gateway owns that client address and prefix; the hosting network
+manager's DHCP or static address is not a source of portal client routing
+facts.
+
+TUN, raw sockets, transparent-destination lookup, concrete protocol engines,
+native DNS servers, namespace operations, and route application stay in native
+Adapters.
+
+Optional gateway capabilities are selected by cohesive Modules. Disabled
+implementations retain stable lifecycle calls and report unsupported
+configuration in the standard runtime. A compact compatibility Host may
+silently normalize those settings to no-ops while preserving the desired TOML
+model; disabled implementations do not duplicate portable policy.
+
+The instance-scoped `DataPlaneSession` composes the foundation operation broker
+under the same session lock as its resource and quota state. The broker owns
+generic completion, cancellation, free, drain, and take transitions. The data
+plane retains TCP/UDP resource ownership, operation metadata, route deadlines,
+and error semantics.
+
+The proposed restructuring of the smoltcp data plane, SOCKS5 and port-forward
+Adapters, portable KCP engine, event-driven FFI/WASI completion model, and Go
+Host integration is tracked in
+[`data-plane-runtime-plan.md`](data-plane-runtime-plan.md). That document is a
+future implementation plan; this document remains the source of truth for the
+currently implemented architecture until the plan is completed.
+
+### Instance and management
+
+`CoreInstance::new(CoreInstanceConfig, CoreHostAdapters)` is the sole direct
+construction path for a normalized instance. `CoreInstance::from_toml` uses
+the same normalization and construction path. Core constructs the peer graph,
+runtime store, STUN collector, connectivity managers, listener runtime, packet
+plane, gateway runtimes, and lifecycle owners.
+
+A core instance:
+
+- owns all mutable portable state for one network;
+- is one-shot after `stop`;
+- exposes one complete `start` and one `stop` lifecycle interface;
+- starts Modules in a fixed serial composition order without cross-Module
+  started flags or staged activation;
+- installs initial ACL, proxy CIDR, and manual-peer inputs before startup;
+- serializes lifecycle operations with one instance-level operation lock;
+- owns cooperative cancellation and component shutdown order;
+- exposes `CorePacketPlane` as the narrow packet/route projection used by Host
+  dataplane Adapters;
+- treats its normalized runtime store as authoritative after construction.
+
+`CoreHostAdapters` contains the required Host, DNS, packet sink, and
+`CoreProcessRuntime`, plus optional protocol and platform capabilities. The
+bundle carries capabilities, not preconstructed portable managers.
+
+By default, the standard native factory owns one continuously driven Tokio
+executor per instance. `multi_thread` selects a multi-thread or current-thread
+runtime; `multi_thread_count` sets the worker count with the historical minimum
+of two. The `easytier-core --shared-runtime` option instead shares one
+multi-thread executor across the factory and all its instances. Its worker count
+defaults to the available CPU count and can be set with the process-level
+`--multi-thread-count` option, with a minimum of one; per-instance runtime flags
+are ignored in this mode. Construction, start/stop, and FFI data-plane tasks use
+the selected executor, independent of the process management runtime. Dropping
+the last factory or instance Host owner shuts down the executor without blocking
+a worker on its own termination. Compact and WASI Hosts retain their externally
+supplied execution model.
+
+Each Module owns partial-start cleanup for its internal resources.
+`CoreInstance` has one outer cancellation and recovery path for the complete
+serial startup. `Running` therefore means the Host runtime and every enabled
+portable Module have started successfully; there is no separate post-Host
+activation state. Host packet tasks stop before PeerManager resources are
+cleared.
+
+`InstanceManager<F>` is the canonical UUID-indexed instance collection for one
+Host composition. Its `InstanceFactory` constructs one complete record before
+the manager performs an atomic uniqueness check. The manager owns collection
+membership; it does not own startup order, persistence, daemon policy, cached
+errors, ABI handles, or RPC projections.
+
+`management/` consumes the canonical manager and instances. It owns:
+
+- stable UUID/name selection;
+- read-only instance and peer management RPC;
+- full process mutation and configuration transactions when enabled;
+- persistence and logger-control capability interfaces;
+- management listener/client lifecycle and JSON-RPC presentation.
+
+There is one process-level management entry. Instances and the manager do not
+depend on management response projections.
+
+## Process-scoped state
+
+`CoreProcessRuntime` owns portable resources shared across instances in one
+process or instantiated module:
+
+- the Ring Tunnel registry and namespace;
+- a reference-counted protected TCP-port registry.
+
+The composition root creates and shares one runtime. Management listener ports
+are protected before bind and held by leases after the concrete port is known.
+Native and target adapters supply bound resources but do not implement a
+second protected-port registry.
+
+Process-global capability objects may contain stateless or shared platform
+mechanisms. They must not contain instance-specific peer, route,
+configuration, or connectivity state.
+
+### Native shared TUN ownership
+
+The native composition owns `SharedVirtualNicRegistry`. Named desktop TUNs
+are shared within a network namespace; mobile instances attach to one supplied
+TUN descriptor. Members own address, route, and MTU claims, not the physical
+device. Bootstrap route cleanup runs only when that device is created. Mobile
+IPv6 claims are initialized before forwarding and follow public IPv6 updates.
+Mobile VPN configuration is projected from admitted members' native claims.
+Admission keeps unchanged attached members ahead of conflicting newcomers or
+reconfigured members. Rejected members are reported individually, while the
+remaining members stay attached. Each member's initial claims are applied as
+one batch before it can open or replace the shared descriptor.
+Mobile claims update dispatcher tables without configuring the OS interface;
+the platform VPN owns its addresses, routes, and MTU.
+If applying native claims fails, the shared NIC is invalidated and its
+dispatcher is stopped so every member can recreate the device. Restoring only
+the recorded claims would leave partially applied OS configuration in use.
+TUN replacement and I/O failures also invalidate the shared NIC. TUN writes
+have bounded waits so a stalled device cannot indefinitely block claim updates
+or member cleanup.
+
+Desktop and mobile shared TUNs use the same lazily initialized native Tokio
+runtime, independent of every member's executor. It creates the device's async
+I/O registration, drives dispatchers, and completes member claim cleanup even
+after the member executor stops or the registration is dropped outside Tokio.
+The runtime has two workers on desktop to allow independent TUN dispatchers
+to run concurrently, and retains one worker on mobile. It owns no registry or
+member claims; those remain with each shared NIC. Cleanup remains asynchronous,
+and the last member's cleanup stops the dispatcher and releases the desktop
+device. A process-lifetime runtime does not extend the device's lifetime.
+Unnamed desktop TUNs and instance-local work retain their existing executors.
+
+Each member connects through one bounded Ring Tunnel. The shared dispatcher
+polls member streams in rotation and writes directly to their sinks, with no
+per-member forwarding tasks or intermediate packet queues. Desktop and mobile
+use one dispatch loop; mobile descriptor replacement is a control message.
+The loop consumes Tokio's cooperative budget even when packets are dropped.
+
+Only the member running the Magic DNS resolver claims its shared fake-IP
+route. The claim is removed before resolver shutdown and acquired by the next
+serving member after takeover. Client-only runners do not claim that route.
+
+The dispatcher preserves desktop kernel-forwarded subnet sources. It corrects
+wrong-member local sources and, on mobile, synthetic sources. Native local
+flows and translated flows reserve member-scoped transport tuples so address
+translation cannot merge sockets using the same port and remote endpoint.
+Collisions remap the source port or ICMP Echo identifier; replies restore the
+original tuple. Unrelated route updates and member removals retain mappings.
+All Echo sequence numbers for one identifier share a reservation; translation
+preserves the sequence field in each request and reply.
+Removing an involved address or member releases its mappings. A full member
+queue drops that packet without blocking other members or control messages.
+
+With one attached member, packets go directly to that member without destination
+matching or new source translations. Native flow reservations remain active so
+later members cannot reuse their tuples. Existing translations continue in both
+directions after other members leave. Unmodified IPv4 fragments and IPv6
+extension headers pass through the single-member path unchanged.
+
+Reservations are bounded at 4096 flows. Activity in either direction refreshes
+them; table pressure reclaims reservations idle for at least 180 seconds. If
+all slots remain active, new tracked flows are dropped rather than evicting a
+live mapping. Desktop external-source forwarding bypasses this table. As with
+other idle-expiring NAT state, very late replies after tuple reuse cannot be
+distinguished from replies to the new flow.
+
+Translation supports unfragmented IPv4 and ordinary IPv6 TCP, UDP, and ICMP
+Echo traffic. IPv4 fragment and IPv6 extension-header translation remain
+unsupported. ICMP errors quoting a translated flow are not reverse-translated;
+in particular, a smaller downstream MTU can prevent PMTU discovery for such
+flows. This limitation does not affect unmodified flows and is intentionally
+retained rather than extending the dispatcher into a full ICMP/fragment NAT.
+
+## Runtime configuration authority
+
+`TomlConfig` is the authoritative desired configuration used for management
+readback and patch transactions. Compact Hosts keep unsupported accepted values
+there so controllers observe the configuration they submitted.
+
+The separately typed, normalized core runtime store is authoritative for live
+behavior:
+
+- peer feature flags and routing policy;
+- listeners and initial peers;
+- ACL and whitelist inputs;
+- manual and VPN portal CIDRs;
+- gateway and connectivity settings;
+- runtime configuration patches.
+
+Manual routing retains three distinct states: absent routes select automatic
+routing, a present empty list installs no remote subnet routes, and a present
+nonempty list selects explicit routes. `NetworkConfig.enable_manual_routes`
+preserves this distinction on readback. `InstanceConfigPatch` applies its
+optional `enable_manual_routes` together with route edits in one route
+sub-patch: true retains an empty manual list and false restores automatic
+routing. Omitting the mode preserves released RoutePatch behavior, including
+returning to automatic routing when the edited list becomes empty. This does
+not change the ordered partial-commit contract of a multi-field patch.
+
+`HeartbeatRequest.support_manual_routes_patch` advertises this complete route
+contract, including typed empty-manual readback, on the WebClient Session.
+The Web controller uses the current authenticated heartbeat to choose route
+patches; observed instance configuration caches contain no capability state.
+Released clients omit the flag and still receive
+full configuration replacements for route changes. For their ambiguous empty
+readback, Web reads the existing `GetConfig.toml_config`, or, when absent, the
+instance-scoped `ShowNodeInfo` TOML used by 2.6.4. It reads only the instance ID
+and route field, requires a matching instance, and confirms the actual mode
+before recording application. Supporting clients use typed readback directly;
+compact clients with raw GetConfig need no Peer management RPC.
+
+Host persistence is an effect following a successful core transaction. A Host
+Adapter must not call back into an instance to obtain a hidden configuration
+snapshot while core is applying an operation.
+
+Non-serializable resources such as TUN descriptors, packet sinks, execution
+domains, and native protocol engines are construction context, not TOML
+fields.
+
+## Logging
+
+The main native runtime uses a small logger implemented in
+`easytier/src/common/log`:
+
+- `log` records and `tracing` events share console and file sinks;
+- timestamps, compact formatting, optional terminal colours, `NO_COLOR`, and
+  basic `RUST_LOG` target/level filters are implemented directly;
+- file rotation uses the existing EasyTier rolling appender;
+- management RPC can reload the file level;
+- an atomic maximum-level gate rejects disabled events before target matching
+  or file-filter locking;
+- concurrent file-level reload serializes the filter and atomic-level update.
+
+File logging and no-file logging are separate selected backends. The default
+tracing backend records events and deliberately ignores span trees. The
+optional `tracing` feature selects the tokio-console subscriber integration;
+only that diagnostic profile pulls the main crate's `tracing-subscriber` and
+`console-subscriber` dependencies.
+
+The native CLI enables the `CORE` and `easytier_core::instance::manager` console
+targets by default. Instance startup failures are reported immediately with the
+instance ID and complete error chain, including the listener URL for bind
+failures. When all instances stop, the CLI's failure summary retains each failed
+instance's ID and saved error. Explicit console levels and `RUST_LOG` directives
+still control which records are emitted.
+
+Contrib applications and platform integrations may have independent logging
+requirements and are not implicitly wired to the native process logger.
+
+## Feature model
+
+Features represent coherent capabilities, not arbitrary source fragments.
+Important core feature relationships are:
+
+- `management-rpc` enables generated management API types and read-only
+  management services.
+- `management` adds configuration writes, full management composition, rich
+  errors, and JSON-RPC.
+- `proxy-packet` enables portable packet parsing/proxy machinery and the
+  required smoltcp packet features.
+- `proxy-smoltcp-stack` adds the async TCP/UDP smoltcp stack.
+- `dns-resolver` is the shared Hickory resolver leaf used by endpoint
+  discovery and Magic DNS without coupling either capability to the other.
+- `endpoint-discovery` adds HTTPS endpoint discovery dependencies.
+- `magic-dns` enables its DNS server, management wire messages, and portable
+  packet-query integration.
+- `tcp-hole-punch` enables the TCP hole-punch runtime.
+- `dhcp-ipv4`, `public-ipv6-provider`, `vpn-portal`,
+  `wrapped-transport`, and `proxy-cidr-monitor` are independent gateway or
+  platform-policy leaves.
+- `extended-services` is the compatibility aggregate for those leaves.
+- encryption and compression engines remain independently selectable.
+
+The native crate maps product features to the core and protocol features it
+actually consumes. A protocol feature must not accidentally enable unrelated
+gateway or management capabilities.
+
+Production feature and platform selection belongs at Module or Adapter
+boundaries rather than inside shared implementations. The logger demonstrates
+the intended pattern: file and tracing variants are complete backend modules
+with one stable interface, so shared event processing contains no feature
+branches.
+
+## Module boundaries
+
+The dependency directions in this document define the intended module
+boundaries. Changes that require a new upward edge must first define a stable
+lower-layer interface or explicitly revise this architecture.
+
+Modules are `pub(crate)` by default. Each domain's `mod.rs` declares its
+outward surface. Public visibility is used for real cross-crate Host,
+configuration, management, packet-plane, or test-support interfaces.
+
+## Architectural invariants
+
+1. Portable EasyTier policy has one owner in `easytier-core`.
+2. Core does not perform real OS socket, DNS, TUN, route, filesystem
+   configuration, process, or service-manager operations.
+3. Host-OS policy is runtime input; a WASI compile target is not Host policy.
+4. Every real socket and DNS operation crosses a Host capability seam.
+5. Core owns socket scheduling, backpressure, protocol state, and cancellation.
+6. Dial, accept, and hole-punch paths produce sockets before protocol upgrade.
+7. Peer admission consumes upgraded transports and does not create OS
+   resources.
+8. Each instance owns its mutable peer, route, connectivity, gateway, and
+   runtime configuration state.
+9. One Host composition has one canonical UUID-to-instance manager.
+10. Process-level runtimes do not capture instance state.
+11. `CoreInstance::new` is the sole normalized direct construction entry.
+12. The manager owns membership, not lifecycle or presentation.
+13. Management consumes the manager; the manager does not return management
+    projections.
+14. Unknown protobuf fields in reflected route information survive forwarding
+    and credential filtering.
+15. Feature selection is localized at cohesive Module/Adapter boundaries.
+16. The standard runtime rejects unsupported configured capabilities. Compact
+    compatibility Hosts may preserve them as runtime no-ops, but never change
+    wire protocol, advertise them, or silently fall back to an unsafe mode.
+
+## Validation
+
+Changes to these boundaries should run, at minimum:
+
+```text
+cargo fmt --all -- --check
+cargo check -p easytier-core -p easytier-proto -p easytier --features full
+cargo test -p easytier-core --lib
+```
+
+Feature work should add focused checks for the changed no-default, isolated,
+default, full, and cross-target profiles. Socket, TUN, namespace, protocol
+engine, and multi-node changes require the relevant Docker integration tests.
+WASI ABI or Adapter changes require a `wasm32-wasip1` build and target-side
+tests. These compiler-resolved profiles are the authority for feature and
+target boundaries.
+
+CI path filters include `easytier-core`, `easytier-proto`, native, web, GUI
+Tauri, and contrib. The archived Rust test suite contains both `easytier` and
+`easytier-core`.
+
+## Known limitations and debt
+
+- Some production feature and platform gates still select fields or statements
+  inside shared implementations. New code should prefer complete Module or
+  Adapter variants, and existing cases should move only when their owning
+  Module is changed.
+- Connectivity retains localized Adapter implementations that name
+  `PeerManagerCore`; further decoupling requires an interface extraction, not
+  a visibility-only move.
+- Native Linux namespace guards exist in paths that can cross async suspension.
+  Because `setns` is thread-local, those operations should eventually be kept
+  on one non-migrating execution context.
+- QUIC session retirement after failed or exhausted accepted sessions remains
+  separate native-engine correctness work; it must preserve multiple
+  connections sharing one QUIC endpoint/session.
+
+These limitations are not reasons to add fallback owners or parallel state.
+Fixes should preserve the ownership rules above and address the responsible
+Module directly.

docs/credential-peers.md

@@ -0,0 +1,55 @@
+# Inspect credential users from the CLI
+
+On a node that stores the issued credentials, list their currently authenticated
+direct peers:
+
+```sh
+easytier-cli credential peers
+
+# Select one network instance and return machine-readable output.
+easytier-cli --instance-name my-network --output json credential peers
+```
+
+The table associates each credential ID with peer IDs, virtual IPv4/IPv6
+addresses, and hostnames. A reusable credential can have multiple peers;
+multiple tunnels to the same peer appear only once. Existing `credential list`
+output is unchanged.
+
+JSON output has this shape for one instance:
+
+```json
+{
+  "credentials": [
+    {
+      "credential_id": "user-123",
+      "peers": [
+        {
+          "peer_id": 42,
+          "ipv4": "10.144.144.2",
+          "ipv6": null,
+          "hostname": "laptop"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Without an explicit instance selector, the command follows the other CLI query
+commands: it queries running instances, wrapping multiple results with their
+instance IDs and names.
+
+## Scope
+
+The association uses the remote public key of an authenticated live credential
+connection, matched against the credential's SHA-256 public-key fingerprint.
+It never uses a route advertisement alone as proof of credential identity.
+Credential secrets and connection keys are not printed.
+
+This is a per-node snapshot, not a network-wide login history. An empty `peers`
+array (shown as `no direct peers` in the table) does not mean a credential is
+unused elsewhere: its users may only be connected to another node or reachable
+through a relay. Older cores without credential fingerprints cannot be matched.
+Missing route addresses are returned as `null` (shown as `-`); a peer may connect
+before its route or DHCP address is available. Addresses and connection state
+can change between the RPC snapshots.

docs/easytier-web-managed-config-sync-plan.md

@@ -0,0 +1,584 @@
+# EasyTier Web Managed Config Incremental Sync Plan
+
+## Status
+
+- 状态：Implemented（核心协议、持久化与 Session 增量收敛）
+- 实施范围：EasyTier Web 的 HTTP 接收、校验、SQLite 持久化和 Session 运行态收敛
+- 上游依赖：后续由 Console 计算并发送 Patch
+- 兼容要求：保留现有 Full PUT
+
+本文记录当前接收端方案。Session 合并已持久化 Patch 的 touched instance IDs，
+并在运行态收敛时读取这些实例的最新持久化状态。重启、通知丢失或无法安全判断
+实例 ownership 时沿用 Full reconcile。
+
+## 1. 背景与结论
+
+当前 `/validate-token` webhook 已经只交换 token、机器信息和 revision，不再
+携带完整 managed config 集合。剩余的大集合位于独立的配置发布路径：
+
+```text
+PUT /api/internal/users/:user-id/machines/:machine-id/networks
+```
+
+Console 每次发布都会向该路径发送完整 Exact Set。实例很多时，请求体、JSON
+解析、现有配置扫描和逐条 SQLite 写入都随实例总数增长。
+
+第一阶段采用以下方案：
+
+1. 保留 PUT，作为完整发布、首次同步和冲突恢复路径。
+2. 在同一路径增加 PATCH；普通变更只发送完整的单实例 upsert 和删除 ID。
+3. PATCH 使用 `expected_config_revision` 做 compare-and-swap（CAS）。
+4. Full/Patch 的配置变更与 revision 更新在一个 SQLite transaction 中提交。
+5. Patch 只查询和写入 touched instances，不扫描完整 Target。
+6. 写入成功后通知 Session 本次 expected、target 和 transaction 实际 touched
+   instance IDs。
+7. Session 只合并 revision 连续的 touched IDs，并以 SQLite 当前状态为准增量
+   收敛；可信 runtime base、通知链或 persisted target 无法证明连续时回退 Full。
+
+普通变更的接收端成本由：
+
+```text
+O(total instances)
+```
+
+降为：
+
+```text
+wire / JSON / persistence transaction / runtime config apply = O(changed instances)
+```
+
+冷启动或 revision 冲突仍需要 `O(total)` 的 Full。这是没有可用基线时传递完整
+目标状态所必需的成本；如果 Full 超过安全的单请求上限，需另行设计 staged
+snapshot，而不是直接分页写入 live rows。
+
+## 2. 目标与非目标
+
+### 2.1 目标
+
+1. 普通新增、更新和删除只传输、解析、查询并写入变化实例。
+2. Config rows 与 persisted revision 原子提交。
+3. Patch 可安全重试，并能确定性处理并发或乱序请求。
+4. 保持 user-owned 与 web-owned 配置的 ownership 规则。
+5. 保持 Full Exact Set 的删除和显式空集合语义。
+6. 为 Full 和 Patch 设置显式且可测试的容量限制。
+7. 先部署接收端，再允许 Console 使用 Patch。
+
+### 2.2 非目标
+
+1. 修改 `/validate-token` request/response。
+2. 在本阶段实现 Console 的 diff/cache 逻辑。
+3. 优化 Core heartbeat 中的完整运行实例上报。
+4. 实现 Full 分页、上传会话或持久化 delivery FSM。
+5. 让冷启动 Full 的成本低于 `O(total)`。
+
+## 3. 必须保持的语义
+
+### 3.1 Full Exact Set
+
+Full 表示一个 `(user_id, machine_id)` 下全部期望的 web-owned configs：
+
+- 请求中存在的实例应被创建或更新；
+- 已存在但请求中缺失的 web-owned 实例应被删除；
+- 空集合应删除该 Target 下全部 web-owned 实例；
+- user-owned 实例不能被覆盖或删除。
+
+### 3.2 Patch
+
+Patch 只描述从一个已知 revision 到另一个 revision 的变化：
+
+- `upserts`：新增或变化实例的完整 config；
+- `delete_instance_ids`：从目标集合中删除的实例 ID；
+- `expected_config_revision`：receiver 必须已经处于的 base revision；
+- `config_revision`：提交完成后的 target revision。
+
+Patch 不是独立的完整目标。当前 revision 与 expected revision 不一致时，必须
+返回冲突且不做任何写入。
+
+### 3.3 Revision invariants
+
+1. 一个 persisted revision 只对应与其一起提交的 web-owned projection。
+2. Config mutation 和 revision advancement 必须位于同一 transaction。
+3. Patch 只能应用在完全匹配的 expected revision 上。
+4. 当前 revision 已等于 target revision 时，返回幂等成功且不重复写入。
+5. Publisher 不得为不同目标状态复用同一个 target revision。
+6. 任何其他写路径只要改变 web-owned row，就必须在同一 transaction 中清除
+   managed revision；否则未来 Patch 会基于错误的 base。
+7. Persisted revision 与 Session applied revision 保持为两个不同事实。HTTP
+   成功只代表本地持久化完成，不代表 Core 已经应用。
+
+## 4. HTTP contract
+
+### 4.1 保留 Full PUT
+
+路径不变：
+
+```text
+PUT /api/internal/users/:user-id/machines/:machine-id/networks
+```
+
+现有 JSON shape 保持兼容：
+
+```json
+{
+  "managed_network_configs": [
+    {
+      "instance_id": "11111111-1111-1111-1111-111111111111",
+      "network_config": {}
+    }
+  ],
+  "config_revision": "target-revision",
+  "expected_config_revision": "base-revision"
+}
+```
+
+`expected_config_revision` 保持当前含义：
+
+- 字段缺失：兼容旧调用者，不检查 base；
+- 空字符串：要求当前 persisted revision 不存在；
+- 非空字符串：要求当前 revision 与该值相等。
+
+新 Console 必须发送 expected revision。省略 expected 的形式只用于旧版本兼容
+和明确的运维修复。
+
+`config_revision` 的处理：
+
+- 非空：配置与 target revision 原子提交；
+- 缺失：保留旧 Full 请求兼容，但清除已有 managed revision，因此该结果不能
+  作为后续 Patch base；
+- 空字符串：拒绝为 400。
+
+Revisioned Full 遇到 user-owned instance ID 冲突时整体失败。Legacy
+unrevisioned Full 保持当前兼容行为：跳过 user-owned row，且绝不覆盖它。
+
+### 4.2 新增 Patch
+
+同一资源增加：
+
+```text
+PATCH /api/internal/users/:user-id/machines/:machine-id/networks
+```
+
+请求格式：
+
+```json
+{
+  "upserts": [
+    {
+      "instance_id": "11111111-1111-1111-1111-111111111111",
+      "network_config": {}
+    }
+  ],
+  "delete_instance_ids": [
+    "22222222-2222-2222-2222-222222222222"
+  ],
+  "config_revision": "target-revision",
+  "expected_config_revision": "base-revision"
+}
+```
+
+Patch contract：
+
+1. 两个 revision 字段均必填、非空且不能相同。
+2. `upserts` 中的 instance ID 不得重复。
+3. `delete_instance_ids` 中的 ID 不得重复。
+4. 同一个 ID 不得同时出现在 upsert 和 delete 中。
+5. 每个 upsert 必须携带该实例的完整 `NetworkConfig`，不支持字段级 JSON
+   Patch。
+6. `network_config` 内部的 instance ID 不受信任，receiver 使用 envelope 中的
+   `instance_id` 进行归一化。
+7. 删除不存在的 ID 是幂等 no-op。
+8. Upsert 或 delete 碰到 user-owned row 时，整个 Patch 返回冲突且不写入。
+9. 不允许从“receiver revision 不存在”的未知状态直接 Patch；使用 Full 建立
+   Exact Set 和首个 revision。
+10. 空 Patch 不能把 revision 改成另一个值；这通常表示 publisher revision
+    计算错误，因此返回 400。
+
+### 4.3 HTTP outcomes
+
+| 条件 | HTTP | 语义 |
+| --- | ---: | --- |
+| Full/Patch 新提交成功 | 204 | Config 和 revision 已持久化 |
+| Target revision 已经存在 | 204 | 幂等成功，无 row mutation |
+| Expected revision 不匹配 | 409 | 零写入，调用者重新观察或发送 Full |
+| User-owned ownership 冲突 | 409 | 零写入，不能自动覆盖 |
+| 非法 ID、重复、交集或非法 config | 400 | 调用 contract 错误 |
+| 请求超过 byte limit | 413 | 未进入 reconciliation |
+| 条目数或单 config 超过限制 | 422 | 超出接收端容量 contract |
+| SQLite 错误 | 500 | Transaction rollback |
+
+409 返回机器可读字段：revision 冲突为
+`code=managed_config_revision_conflict` 并在已知时带
+`current_config_revision`；ownership 冲突为
+`code=managed_config_ownership_conflict`。响应不得返回配置内容。日志不得记录
+token、secret 或完整 config JSON。
+
+## 5. Receiver architecture
+
+### 5.1 Module responsibilities
+
+| Module | 本阶段职责 |
+| --- | --- |
+| Internal HTTP Adapter | 内部鉴权、body/count limit、DTO 解析、HTTP 状态映射 |
+| `ClientManager` | 解析 Target，调用 managed-config Interface，成功后通知 Session |
+| `client_manager::managed_config` | Full/Patch 规则、归一化、typed outcome |
+| `Db` Adapter | CAS、ownership fence、批量 mutation、revision transaction |
+| Session runtime reconciliation | 校验 applied/base/target fence，增量收敛 touched instances；断链时 Full |
+
+HTTP Adapter 不实现 ownership、diff 或 transaction 逻辑。PUT 和 PATCH 共用
+managed-config Module，避免两套规则逐渐分叉。
+
+### 5.2 Internal Interface
+
+Module 接收两种 intent：
+
+```text
+Full {
+  desired_configs,
+  target_revision: Option<Revision>,
+  expected_revision: Any | Exact(Option<Revision>)
+}
+
+Patch {
+  upserts,
+  delete_instance_ids,
+  target_revision: Revision,
+  expected_revision: Revision
+}
+```
+
+返回 typed outcome：
+
+```text
+Applied {
+  previous_revision,
+  target_revision
+}
+
+AlreadyApplied {
+  target_revision
+}
+
+RevisionConflict {
+  expected_revision,
+  current_revision
+}
+
+OwnershipConflict {
+  instance_id
+}
+```
+
+Validation error 与 database error 保持独立类型。HTTP handler 只负责将这些结果
+映射到 section 4.3 的状态码。
+
+## 6. Receiver implementation
+
+### 6.1 Validation and normalization
+
+在打开 SQLite write transaction 之前完成：
+
+- request byte/count/per-entry limit；
+- UUID、重复 ID 和 upsert/delete 交集校验；
+- config key 拼写归一化；
+- envelope instance ID 覆盖 nested identity；
+- `NetworkConfig` 反序列化。
+
+这样非法大请求不会长时间占用 SQLite writer lock。Ownership 必须在 transaction
+内重新查询，因为 transaction 外的结果可能已过期。
+
+当 request 带 target revision 时，可以先做一次 O(1) revision read；如果当前值
+已经等于 target，可直接返回 `AlreadyApplied`，避免完整 config 归一化。任何可能
+写入的请求仍必须在 transaction 内再次检查 revision。
+
+### 6.2 Full transaction
+
+在同一个 SQLite connection 上执行：
+
+1. `BEGIN IMMEDIATE`。
+2. 读取 `(user_id, machine_id)` 当前 persisted revision。
+3. 若 supplied target 已经是 current，返回 `AlreadyApplied`。
+4. 检查 optional expected revision。
+5. 只读取现有 row 的 `(instance_id, source)`；不加载无关 config JSON。
+6. 执行 user-owned ownership fence。
+7. 批量 upsert 全部 desired web-owned rows。
+8. 计算并批量删除 `existing_web_ids - desired_ids`。
+9. 最后写入 supplied target revision；legacy unrevisioned Full 则删除旧 revision。
+10. Commit。
+
+任一步骤失败都 rollback。Full 仍是 `O(total)`，但不会再逐条独立提交，也不会
+出现“部分 rows 已更新、revision 仍是旧值”的中间持久状态。
+
+### 6.3 Patch transaction
+
+在同一个 SQLite connection 上执行：
+
+1. `BEGIN IMMEDIATE`。
+2. 读取 current revision。
+3. 如果 current 等于 target，返回 `AlreadyApplied`。
+4. 如果 current 不等于 expected，返回 `RevisionConflict`。
+5. 只查询 upsert/delete IDs 的 source。
+6. 任一 touched ID 属于 user 时，返回 `OwnershipConflict`。
+7. 批量 upsert changed configs。
+8. 批量删除 requested web-owned IDs。
+9. 最后写入 target revision。
+10. Commit。
+
+Patch 禁止：
+
+- list 全部 Target rows；
+- 重算完整 Target digest；
+- 根据 touched IDs 之外的数据做 stale-row scan。
+
+因此其数据库工作量只随 `upserts + deletes` 增长。
+
+### 6.4 Bounded batch SQL
+
+批量操作不构造无限长 SQL。根据 SQLite bind-variable limit 选取固定 batch size，
+并在同一个 transaction 内分批执行：
+
+- multi-row `INSERT ... ON CONFLICT DO UPDATE`；
+- 带 `source = web` 条件的 batch delete；
+- 只返回 instance ID/source 的 ownership query。
+
+Patch statement 数量应为 `O(ceil(delta / batch_size))`；Full 为
+`O(ceil(total / batch_size))`。每个 accepted request 只有一个 transaction 和
+一次 revision 写入。
+
+### 6.5 Alternate-write revision invalidation
+
+现有其他路径可能 save、delete、disable 或改变 web-owned row。若这些路径修改
+rows 后仍保留旧 managed revision，Patch CAS 会把错误状态当作正确 base。
+
+因此所有 config mutation Adapter 必须遵守：
+
+1. 判断 mutation 是否改变 web-owned row；
+2. 在一个 transaction 中执行 mutation；
+3. 在 commit 前删除该 Target 的 managed revision。
+
+Managed Full/Patch 在同一 transaction 内先完成 mutation，最后写入新的 target
+revision。只影响 user-owned rows 的操作不清除 managed revision。
+
+本方案不在 `/validate-token` 读取 revision 时重算完整 digest，否则周期性验证会
+重新变成 `O(total)`。Revision 完整性由所有写入 Adapter 局部维护。
+
+### 6.6 Locking, cancellation and notification
+
+现有 per-target process-local lock 可以保留，用于减少同进程的重复工作，但它不
+承担正确性。正确性由 SQLite transaction 和 CAS 提供。
+
+- Transaction 内不执行 Session RPC、网络请求或无关 async 工作。
+- HTTP future 在 commit 前取消时，transaction drop 必须 rollback。
+- Commit 后即使 response 或 notification 丢失，persisted state 仍然有效；调用者
+  用同一 target retry 会得到幂等成功。
+- 只有带 target revision 的 `Applied` 才通知匹配的 live Session；
+  `AlreadyApplied`、legacy unrevisioned Full、conflict 和失败不重复通知。
+- Notification 必须发生在 commit 之后。
+- Full notification 将 pending reconcile hint 提升为 Full，触发完整收敛。
+- Patch notification 携带 expected revision、target revision、upsert IDs 和本次
+  transaction 实际接受删除的 web-owned IDs。请求删除但数据库原本不存在的 ID
+  仍是 no-op，不能借机删除 Core 中同 ID 的 user-owned 实例。
+- Session 将尚未应用的 Patch touched IDs 合并为一个 Dirty set，并始终以 SQLite
+  最新 revision 下的 rows 为准。它不重放历史 Patch，也不维护 Patch queue 或
+  delivery FSM。只有 incoming expected 等于 pending target 的通知才能合并；Dirty
+  hint 保留最早 expected 和最新 target。乱序、不连续或无法证明顺序的通知将 hint
+  提升为 Full。多个连续 Patch 积压时，旧 round 由 runtime epoch 拦截，下一 round
+  直接收敛到最新 target。
+- Session 分开记录对外报告的 applied revision 和内部可信的 runtime base。开始任何
+  runtime side effect 前清除 applied；Patch round 的 side effects 完全包含在 Dirty
+  set 中，因此失败或被新通知拦截时仍保留最早 runtime base，以便按最新持久化状态
+  重试 Dirty set。Full round、direct mutation、授权失败或 Session ownership 中断会
+  清除 runtime base。
+- 只有可信 runtime base 等于 Dirty 最早 expected，并且 SQLite persisted revision
+  等于 Dirty 最新 target 时，才允许增量 round。重连后 runtime base 未知、通知
+  丢失，或 SQLite 已经提交了更靠后的 revision 而通知尚未送达时都回退 Full，避免
+  不完整的 Dirty set 把完整 target revision 误标为已应用。
+- 增量 round 逐个读取 Dirty set 中的最新 row。仍然存在且启用的 web-owned row
+  使用其最新 config；已经删除的 row 进入 delete set；遇到 disabled 或非 web-owned
+  row 时回退 Full，以保留 ownership 规则。完成前再次校验 persisted target
+  revision；只有全部 touched instances 成功且 target 仍相同，才推进 applied
+  revision。
+- 任何通过 EasyTier Web mutation route 直接 Run、Save、Delete 或切换实例状态的
+  操作在执行前和结束后（包括部分 side effect 后返回错误）都清除 Session applied
+  revision、可信 runtime base 与 pending hint，增加运行配置 cache epoch，并唤醒一次 Full
+  reconcile。旧 round 只有 epoch 仍匹配时才能推进 applied revision；新一轮不得
+  信任 mutation 前缓存的 runtime config。否则 runtime-only mutation 或 Core 成功、
+  SQLite 失败的复合 mutation 可能在 persisted revision 不变时破坏 Patch base 的
+  完整性。
+
+## 7. Capacity contract
+
+当前 route 没有显式 body limit，Axum `Json` 使用依赖版本的默认 2 MiB 限制。
+生产容量不应依赖框架隐式默认值。
+
+本阶段定义并测试四个独立限制：
+
+- decoded request 最大 bytes；
+- Full entries / Patch upserts 最大数量；
+- Patch deletes 最大数量；
+- 单个 `network_config` 最大 bytes。
+
+限制只应用于 internal managed-config route，不提高其他 public route 的 limit。
+具体默认值不能拍脑袋确定：先采集 1k/10k representative configs 的 encoded
+size 和 peak memory，再选择有明确 headroom 的默认值及硬上限。
+
+提高 Full limit 只是确保 fallback 覆盖已支持的生产规模，不是稳态优化。请求压缩
+同样只能降低 wire bytes，不能降低 JSON materialization 和 SQLite 工作量，因此
+不作为 Patch 的前置条件。
+
+## 8. Failure and recovery
+
+| Failure | Receiver state | Caller action |
+| --- | --- | --- |
+| Invalid payload | Unchanged | 修复请求，不重试相同 payload |
+| Capacity exceeded | Unchanged | 使用较小 Patch；Full 需检查支持规模 |
+| Revision conflict | Unchanged | 重新观察；有 base 时重算 Patch，否则 Full |
+| Ownership conflict | Unchanged | 解决 ownership，不能自动覆盖 |
+| SQLite error before commit | Rolled back | 从相同 observed revision 重试 |
+| Response lost after commit | Target committed | 同一 target retry，幂等成功 |
+| Process exits before revisioned Session notify | Target committed | 现有 revision reconciliation 恢复 |
+| Alternate web-row mutation | Revision atomically cleared | 下一次观察触发 Full 修复 |
+| Console cache loss | Receiver unchanged | Console 发布 Full |
+
+Receiver 不保存 Patch delivery ledger。Publisher 根据自己的完整目标和 receiver
+当前 revision 重算 Patch 或选择 Full。
+
+## 9. Rollout and rollback
+
+### 9.1 Receiver-first rollout
+
+1. 为现有 Full 行为增加 characterization tests。
+2. 将 Full rows/revision 改为一个 atomic transaction。
+3. 为 alternate web-row mutation 增加 revision invalidation。
+4. 增加 PATCH、typed conflict、capacity limits 和 metrics。
+5. 在 Console 仍只发送 PUT 时部署到全部 EasyTier Web 实例。
+6. 完成旧 Console PUT、新 Console PUT/PATCH contract 测试。
+7. 最后启用 Console Patch 发布。
+
+Patch capability 不通过 `/validate-token` 协商。部署顺序就是 compatibility gate；
+这样不会把配置能力重新耦合回鉴权 Interface。
+
+Console 遇到 409 可以 re-observe 后发送 Full。它不能把 404、401 或 malformed
+response 当作旧 receiver 并静默换一种 mutation contract；出现 404 表示接收端
+部署门禁未满足。
+
+### 9.2 Rollback
+
+- Console 尚未发送 Patch 时，EasyTier Web 可正常回滚。
+- Console 已发送 Patch 后，先回滚 Console，使调用恢复为 PUT，再回滚 Web。
+- PUT 在整个发布周期保持兼容。
+- Patch 和 Full 写入相同 rows/revision，不需要格式级数据迁移。
+
+本方案不新增 persistent table。现有 Target/instance unique index 应覆盖 touched-ID
+查询；若实现时需要新 index，必须先用实际 SQLite query plan 证明。
+
+## 10. Verification
+
+### 10.1 Contract tests
+
+- 现有 Full JSON 继续接受。
+- 空 Full 删除所有 web-owned rows，保留 user-owned rows。
+- Patch add/update/delete 与等价 Full 得到相同最终 projection。
+- Duplicate/overlap/invalid config 返回 400 且零写入。
+- Patch 缺少 revision 返回 400。
+- Revision conflict 返回 409 和 current revision，不返回 config。
+- Byte/count/per-entry limits 分别有确定性测试。
+
+### 10.2 Transaction and ownership tests
+
+- 在 upsert 后、delete 后、revision write 前注入错误，rows/revision 全部 rollback。
+- Revisioned Full/Patch 的 user-owned collision 整体 rollback。
+- 删除不存在的 ID 幂等成功。
+- 两个 target 从同一 base 并发时，一个成功、一个 409。
+- 相同 target retry 只有第一次写入，第二次为 no-op success。
+- Alternate save/delete/disable web row 与 revision invalidation 原子提交。
+- User-owned-only mutation 不清除 managed revision。
+- 数据库重连后，任一 persisted revision 都对应完整一致的 rows。
+
+### 10.3 Scale tests
+
+至少使用 1k 和 10k representative entries：
+
+- 单实例 Patch 的 decoded bytes、row reads、writes 和 statement count 不随 Target
+  总实例数增长；
+- Patch 不执行 list-all query；
+- Full 使用 bounded batches 和一个 transaction；
+- Revision read 保持 O(1)；
+- 超限 Full 稳定返回 413/422，而不是耗尽进程内存；
+- 并发请求无 deadlock，且 CAS 结果确定。
+
+Session 测试还必须验证：连续 Patch 的 Dirty IDs 会合并且保留最早 expected；未知
+或不匹配的 runtime base、乱序/不连续通知使用 Full；增量 round 读取最新 row；已经
+删除的 web-owned row 只删除对应 Dirty ID；Full notification 覆盖 Dirty hint；目标
+revision 已变化或 touched runtime apply 失败时不推进 applied revision；直接 runtime
+mutation 使 revision 与运行配置 cache 同时失效。运行态 Config Get/Patch/Run/Delete
+数量应随 touched instances 增长。为确认运行实例身份而进行的一次 list/meta RPC
+可以保留，它不发送或重写所有实例配置。
+
+## 11. Observability
+
+每个请求记录结构化字段，但不记录 config 内容：
+
+- mode：`full` / `patch`；
+- user/machine scope；
+- request bytes；
+- desired/upsert/delete count；
+- normalization、target-lock wait、transaction duration；
+- SQL statement/batch count；
+- result：applied、already-applied、revision-conflict、ownership-conflict、
+  invalid、oversized、database-error；
+- Session notification 是否发送。
+
+Rollout acceptance：
+
+- Console 启用后 Patch 占普通变更的绝大多数；
+- 单实例变化的 request size 与 SQLite cost 与单实例成比例；
+- conflict rate 可解释且稳定；
+- 支持规模内的 Full 没有 413/422；
+- validate-token latency 不随 Target 实例数增长。
+
+## 12. 后续优化
+
+### 12.1 Session runtime delta apply（已实现）
+
+Patch commit outcome 已携带 expected、target 和 transaction 实际 touched IDs。
+Session 只合并 expected/target 连续的 Dirty IDs，并在每一轮从 SQLite 读取最新
+target revision 对应的当前 rows；因此正常积压只增加 Dirty set，不需要保留中间
+revision 的 Patch queue。可信 runtime base 必须等于 Dirty 最早 expected；Patch
+side effect 失败可保留该 base 重试，通知丢失、乱序、进程重启或新 Session 尚无
+runtime base 时回退 Full。Full
+notification、disabled row 或 ownership 无法证明时也回退 Full。
+
+### 12.2 Chunked Full
+
+不能把 Full Exact Set 直接分页写入 live rows：接收端无法在中间页判断哪些旧
+实例最终应删除，crash 也会暴露半套目标。
+
+如果测量证明单请求 Full 无法覆盖必须支持的冷恢复规模，需要单独设计带
+snapshot ID、staging rows、expiry、finalize 和 atomic swap 的协议。在出现数据
+证明前不新增该状态机。
+
+## 13. Implementation files and checklist
+
+主要涉及：
+
+- `easytier-web/src/restful/network.rs`
+- `easytier-web/src/client_manager/mod.rs`
+- `easytier-web/src/client_manager/managed_config.rs`
+- `easytier-web/src/db/mod.rs`
+- 对应 contract、database 和 managed-config tests
+
+完成条件：
+
+- [x] 现有 Full compatibility tests 固定。
+- [x] Full config rows 与 revision 原子提交。
+- [x] Alternate web-owned mutations 原子清除 revision。
+- [x] PATCH contract 和 typed 409 实现。
+- [x] Patch 只查询、写入 touched IDs。
+- [ ] Bulk SQL 遵守 tested bind-count bound。
+- [ ] Route byte/count/per-entry limits 有文档和测试。
+- [x] User-owned rows 不能被 Full/Patch 覆盖或删除。
+- [x] Empty Full 语义保持。
+- [x] Applied/AlreadyApplied/conflict 的通知行为符合设计。
+- [x] Session 在 revision 连续时只收敛 touched instances，断链时使用 Full。
+- [ ] 1k/10k scale 与 concurrent CAS tests 通过。
+- [ ] Receiver-first compatibility matrix 通过。

docs/kcp-control-reliability-design-2026-09-14.md

@@ -0,0 +1,470 @@
+# KCP 控制报文可靠性与旧版兼容设计
+
+日期：2026-09-14。
+
+状态：已按本文实现并提交；当前实现、验收结果及仍未定位的异常见
+[实现与验证记录](kcp-control-reliability-validation-2026-09-14.md)。
+本文保留设计要求，具体通过范围以验证记录为准。
+
+## 1. 背景与问题边界
+
+此前已修复 TCP 代理任一方向 EOF 导致双向转发提前退出、KCP accept
+通知队列满后连接交接丢失、接收缓冲排空与提前 FIN 的处理，以及握手前
+心跳触发 RST 的竞态。具体版本及结果见
+[半关闭验证记录](tcp-proxy-half-close-validation-2026-09-14.md)。
+
+仍有两个问题：
+
+1. 已证实的握手最终 ACK 丢失：源端收到 SYNACK 后认为连接建立，目标端
+   仍停留在 SynReceived；服务端先发 greeting 的业务因此超时。
+2. 一次未主动注入丢包的反向半关闭超时：发送端出现输出队列 Full，FIN
+   已进入端点输出队列，但没有证据证明它何时到达对端。失败日志未记录
+   客户端已收字节数，尚不能确定缺少的是数据、EOF，还是两者。后续
+   TRACE 重跑通过，不足以消除或解释原失败。
+
+KCP 数据传输自身的确认重传没有覆盖外层 SYN、SYNACK、握手确认和 FIN。
+这是连接状态机的局部协议设计问题。修复需要明确控制报文的重复处理、
+完成条件和状态寿命，无需重做 KCP 数据传输或 EasyTier 路由架构。
+
+本设计解决已证实的握手恢复缺口，并为 FIN 增加可靠确认。同时继续调查
+第二项异常；不能将新增 FIN 重传直接当作该异常已经修复的证明。
+
+## 2. 目标、范围与不变量
+
+目标：
+
+- 新旧节点双向正常互通，滚动升级不得要求所有节点同时升级。
+- 新节点之间，控制报文在重试预算内丢失、重复或乱序时能够恢复。
+- 连接只交接一次，应用数据不重复交付，EOF 不越过已接收数据。
+- 半关闭只关闭一个发送方向，另一方向仍可长期传输。
+- 无法恢复时有界结束并报告错误，不能用正常 EOF 掩盖失败。
+- 关闭记录、待发送控制报文和重试任务均有明确生命周期。
+
+范围：kcp-sys 的报文定义、连接状态机、端点调度与清理、必要的流错误
+传播，以及 EasyTier 的依赖 pin、集成测试和验证记录。
+
+不新增路由能力公告、PeerFeatureFlag 字段、配置开关或应用层请求重试；
+不修改 TCP flow-key 修复、QUIC 协议、KCP 数据分段和拥塞算法。保留现有
+connect API、调用方超时和业务测试的 5 秒 socket 超时。
+
+协议不变量：
+
+1. 模式由本连接握手确定，交付应用后不能切换。
+2. 握手状态变化和是否产生应答是两件事；可靠模式允许状态不变但应答。
+3. 已经进入应用交接路径的连接，重复控制包不能再次 accept。
+4. FIN_ACK 只确认对方 FIN，不表示自己也关闭发送方向。
+5. 只有正常收到对端 FIN 且排空接收数据，才能向应用报告正常 EOF。
+6. FIN 确认成功后，FIN 重试期限不能限制正常半关闭连接的寿命。
+7. 重复包不能延长握手、FIN 重试和最终关闭记录的固定截止时间。
+
+## 3. 版本基线与兼容证据
+
+| 用途 | kcp-sys revision |
+| --- | --- |
+| 旧协议基线 | `d7427c22d764deb1860a7d37acc446ed5033464c` |
+| 本设计实施基线，已含前述局部修复 | `b37ee660fb70bb6d816fb8bbc08b140e55e7218b` |
+
+源码检查确认：
+
+- 旧 header 含三个 u32、一个 flags 字节及一个 `rsv` 保留字节，总长
+  14 字节；旧实现不读取 `rsv`。
+- 旧 SYNACK 使用新建且清零的 header，不回显 SYN 的 `rsv`。
+- 旧 FSM 收到重复 SYN 时可能构造 RST，但状态不变；外层
+  `KcpConnectionState::handle_packet` 丢弃状态未变化时的输出，
+  因此已检查的旧端点不会实际发送该 RST。
+- `rsv` 未被读取、状态不变时抑制输出的行为，在已检查历史
+  `a5f4b4e`、`37f653c`、`0f2fea1`、`9ce5c08`、`0f0a055`、
+  `71eff18`、`d7427c2` 中一致。
+
+这些是源码与历史检查，不是上述每个 revision 的运行测试。正式兼容
+声明必须对应实际测试的 EasyTier 版本及其锁定依赖，不能扩展为所有
+未检查的历史版本或第三方修改版本都已验证。
+
+实现基线源码：
+[报文定义](https://github.com/EasyTier/kcp-sys/blob/b37ee660fb70bb6d816fb8bbc08b140e55e7218b/src/packet_def.rs)、
+[状态机](https://github.com/EasyTier/kcp-sys/blob/b37ee660fb70bb6d816fb8bbc08b140e55e7218b/src/state.rs)、
+[端点](https://github.com/EasyTier/kcp-sys/blob/b37ee660fb70bb6d816fb8bbc08b140e55e7218b/src/endpoint.rs)。
+
+## 4. 报文格式与连接内协商
+
+### 4.1 字段定义
+
+保持 14 字节 header、连接标识字段、已有 flags 和 KCP DATA payload
+布局不变。使用已有 `rsv` 字节：
+
+| 值 | 定义 |
+| --- | --- |
+| `0` | 旧协议，后文称 legacy |
+| `1` | 本文可靠控制协议，后文称可靠模式 |
+
+新增 FIN_ACK 使用 flags 当前未分配的最高位 `0x80`。它是独立报文，
+flags 必须恰好为 FIN_ACK，`rsv=1`，payload 为空。不能用 FIN|ACK
+表示关闭确认，因为旧端会把 FIN 位解释为对端关闭发送方向。
+
+可靠模式报文约束：
+
+| 报文 | flags | payload |
+| --- | --- | --- |
+| SYN | SYN | 原有连接元数据，重传保持完全相同 |
+| SYNACK | SYN\|ACK | 空 |
+| 最终握手确认 | ACK\|DATA | 空 |
+| 数据及 KCP 内部确认 | ACK\|DATA | 原有 KCP payload |
+| 关闭发送方向 | FIN | 空 |
+| 关闭确认 | FIN_ACK (`0x80`) | 空 |
+| 重置、心跳 | 原有 RST、PING、PING\|PONG | 沿用现有定义 |
+
+可靠模式报文均带 `rsv=1`。legacy 的后续报文仍使用现有格式和 `rsv=0`；
+新源端最初提出协商的 SYN 是可能发给旧目标端的唯一保留字节扩展。
+
+只有匹配连接标识、当前握手阶段和合法 flags/payload 的 SYNACK，
+才可以确认模式。不能通过 PING/PONG 确认：旧端的心跳应答会复制输入
+报文，可能保留它并不理解的 `rsv`。
+
+### 4.2 协商步骤
+
+1. 新源端发送 SYN，`rsv=1`，进入尚未确认模式的 SynSent。
+2. 新目标端收到 SYN：`rsv=1` 时回复 SYNACK `rsv=1`，记录可靠模式
+   候选状态；`rsv=0` 时从头使用 legacy，回复 SYNACK `rsv=0`。
+3. 旧目标端忽略 `rsv`，自然回复 SYNACK `rsv=0`。新源端收到它后，
+   在交付应用前确定 legacy，最终 ACK 及后续报文都使用旧模式。
+4. 新源端收到合法 SYNACK `rsv=1` 后确认可靠模式，发送最终 ACK
+   `rsv=1`。目标端收到匹配模式的确认后完成握手并登记待 accept。
+5. 源端继续在收到合法 SYNACK 后完成 connect，不增加第四次握手或
+   额外 RTT。最终 ACK 丢失后的恢复规则见第 5 节。
+
+未识别的 SYN `rsv` 值不得被当作可靠能力，可按不支持扩展响应 legacy
+SYNACK。新源端只接受它实际支持的 SYNACK 模式 `0` 或 `1`；未知值
+报告协议错误，不启用增强行为。重复 SYN 不允许更改已有连接的模式或
+连接元数据。已协商可靠模式后，模式不匹配的控制包不得触发降级。
+
+节点重启或降级后的新连接重新协商；不缓存按节点永久生效的协议模式。
+不承诺跨进程重启维持既有连接。
+
+### 4.3 初始 SYN 与旧版兼容
+
+首个 SYN 或 SYNACK 丢失时，源端尚不可能拿到协商确认。因此 SynSent
+期间允许在原截止时间内重传完全相同的 SYN，不以前置能力公告或已收到
+SYNACK 为条件。
+
+在已检查的旧端点中，重复 SYN 不引出 RST，但也不会让旧目标端重发
+SYNACK。所以新源端→旧目标端仍保留旧目标端 SYNACK 丢失时的限制。
+这一行为必须由真实旧依赖运行测试确认，不能只测试重写的 legacy 模型。
+
+新目标端对旧源端保持 legacy 行为，不主动开启 SYNACK 重传。
+legacy 分支继续保留“状态不变则抑制 FSM 输出”的现有行为；不得将
+可靠模式的应答修复无条件套用，否则会改变旧连接的 RST 行为。
+
+## 5. 可靠握手与重复报文
+
+源端在 SynSent 重传 SYN，目标端在可靠 SynReceived 重传 SYNACK。
+所有重传使用原连接 ID，不创建额外连接或重试业务请求。
+
+| 当前状态 | 输入 | 动作 |
+| --- | --- | --- |
+| 无状态 | 合法 SYN | 保存模式与连接元数据，建立 SynReceived，回复 SYNACK |
+| SynReceived | 相同 SYN | 重新回复 SYNACK，不替换状态或延长截止时间 |
+| SynReceived | 匹配的 ACK\|DATA | 完成握手，登记待 accept 一次，停止 SYNACK 定时重传 |
+| SynSent | 合法 SYNACK | 确定模式，发送最终 ACK，完成 connect |
+| Established 或半关闭 | 重复 SYNACK | 回复最终 ACK，不重新创建流、不改变关闭状态 |
+| 已握手、尚未最终释放 | 相同 SYN | 可重发原 SYNACK，不重复 accept、不恢复已关闭方向 |
+| 已握手 | 重复最终 ACK | 幂等处理，不重复交接连接 |
+
+ACK\|DATA 带有效 KCP payload 时仍按 KCP 处理。若它同时完成握手，
+不得为了修复握手而重复交付 payload；必须验证 accept 前到达数据时，
+现有 KCP 重传和接收路径最终完整交付字节。
+
+最终 ACK 丢失的正常恢复：
+
+```mermaid
+sequenceDiagram
+    participant S as 源端
+    participant D as 目标端
+    S->>D: SYN
+    D->>S: SYNACK
+    S--xD: 最终 ACK 丢失
+    Note over S: connect 已返回
+    Note over D: 保持 SynReceived
+    D->>S: 重传 SYNACK
+    S->>D: 重发最终 ACK
+    Note over D: 登记待 accept 一次
+```
+
+### 5.1 最终 ACK 丢失后立即 FIN
+
+空流的发送缓冲本来就是空的，connect 返回后可以立即 shutdown；不能
+假设 FIN 一定晚于最终 ACK 到达。
+
+可靠 SynReceived 收到匹配模式和连接标识的合法 FIN 时，将它视为
+隐含的握手确认，同时执行：
+
+1. 完成握手并停止 SYNACK 重传。
+2. 登记待 accept 一次，保存对端发送方向已关闭。
+3. 回复 FIN_ACK；accept 创建流时继承对端关闭状态。
+4. 接收排空后报告 EOF，本端仍可回复数据。
+
+不能先进入 Closed 再返回 RST，也不能要求应用先发送非空数据才能
+完成握手。该规则仅用于可靠模式。
+
+## 6. FIN、确认与双向关闭
+
+### 6.1 本端关闭发送方向
+
+保留现有顺序：应用关闭发送队列，发送任务把排队数据交给 KCP，并等待
+`waitsnd == 0`，然后进入 FIN 待确认阶段。重试预算从这一阶段开始计算，
+不能从应用开始传输或尚未排空数据时开始计算。
+
+FIN 发送入队成功不代表对端已收到。记录待确认状态、下一次重传时间和
+固定截止时间，直到收到有效 FIN_ACK 或连接明确失败。收到对端 FIN
+本身不等同于本端 FIN 已被确认。
+
+保留现有 AsyncWrite shutdown 的本地关闭语义，不将其返回成功解释为
+对端已确认。关闭确认和最终回收由端点负责；后续超时通过仍存活的流和
+诊断状态表达，不能变成伪造的正常 EOF。
+
+### 6.2 收到 FIN 或 FIN_ACK
+
+- 收到 FIN：记录对端发送方向已关闭，并安排 FIN_ACK。接收任务仍需
+  把已确认接收的数据交给应用，排空后才产生 EOF。
+- FIN_ACK 可以先于应用读完数据发送；它确认端点收到了 FIN，不确认
+  应用已经消费数据。因此接收状态和缓冲生命周期不能随确认提前删除。
+- 重复 FIN：重复应答 FIN_ACK，不重复产生应用 EOF，不重置连接。
+- 收到 FIN_ACK：仅当本端确实已经发送 FIN，且模式、连接标识、flags
+  和 payload 全部合法时，停止本端 FIN 重传。
+- 提前、重复或与当前阶段无关的 FIN_ACK 不推进状态、不关闭写方向。
+
+发送和接收两个方向分别记录完成情况。现有 Established、LocalClosed、
+PeerClosed、Closed 不足以单独表达“本端 FIN 已发但未确认”，应在现有
+连接状态内补足该信息，不另建一套连接所有权或通用重试框架。
+
+### 6.3 正常回收与短暂关闭记录
+
+可靠模式最终回收分两步：
+
+1. 本端 FIN 已确认、对端 FIN 已收到，并且接收任务排空后，释放 KCP
+   数据对象、应用通道和数据任务；在原 state_map 保留最小关闭记录。
+2. 固定保留期结束后删除该记录。重复报文不延长保留期。
+
+关闭记录仅保存原连接 ID、协议模式、正常关闭原因、回复重复 FIN 所需
+信息和过期时间。它继续回复 FIN_ACK；合法在途 PING/PONG 可以忽略，
+不得因现有 Closed 心跳路径而回复 RST。迟到 SYN/SYNACK 不得重新
+accept、创建数据对象或恢复连接；已经完成的数据包可以丢弃。
+
+双方同时关闭时，即使只有一方收到 FIN_ACK，先完成的一方也要依靠该
+记录继续回答另一方的 FIN 重传。不能沿用“Closed 且 recv_done 就立即
+删除所有状态”的判断。
+
+legacy 继续使用原有回收规则。可靠模式的短暂记录会使状态表在有限
+时间内多保留条目，容量验收必须单独计算，不能继续要求所有内部状态
+在原 15 秒观察点清零。
+
+## 7. 定时、队列与失败路径
+
+### 7.1 拟定默认参数
+
+以下为实现初值，需由定点丢包与延迟测试验证后固定；调整须在验证记录
+说明，不能为了让测试通过而延长业务超时。
+
+| 参数 | 初值 / 规则 |
+| --- | --- |
+| SYN、SYNACK、FIN 首次重传间隔 | 200 ms |
+| 后续重传 | 指数退避，单次间隔上限 2 s |
+| 源端握手期限 | 调用方现有 `connect(timeout_dur)`，不延长 |
+| 可靠目标端握手期限 | 首次收到 SYN 后 60 s，不由心跳或重复包续期 |
+| FIN 待确认期限 | 进入 FIN 阶段后 60 s |
+| 正常关闭记录保留期 | 65 s，覆盖 FIN 重试窗口并留调度余量 |
+
+目标端和 FIN 的 60 秒预算是端点控制状态的资源边界，不替代应用更短的
+超时。网络永久不可达时，正确结果是可诊断的超时和最终清理。
+
+关闭记录保留期必须不少于另一端允许的最大 FIN 重试窗口加余量，因此
+FIN 期限不能变成各端任意可调且互不知情的参数。若后续版本改变这些
+上界，需要重新审查版本间兼容性。
+
+FIN 已确认后立即解除 FIN 重试期限；正常半关闭继续按既有连接存活规则
+处理。仅本端 FIN 未确认才受该期限限制，反向有数据或 PONG 也不能使
+未确认 FIN 无限续期。
+
+### 7.2 端点调度与输出队列
+
+使用单个端点控制调度任务和现有 state_map；不为每次重传创建任务，不
+扩容或改成无界队列。按最近的控制截止时间唤醒，新状态通过通知更新
+调度；没有待处理控制状态时，避免对全部空闲连接进行高频扫描。
+
+状态记录是控制报文待处理事实的来源。输出队列暂满时保留该事实，稍后
+再尝试；不能像原 accept 通知一样丢失后就再无恢复机会。
+
+- 用短临界区和非阻塞入队，禁止持有 state_map/conn_map 锁跨 await。
+- 每次实际入队前重新检查状态、连接标识和期限，防止陈旧重传在取消或
+  回收后继续发送。回收不能与入队检查形成复活旧连接的竞态。
+- SYN/SYNACK/FIN 的重传受各自固定预算限制。重复请求所需的 ACK 或
+  FIN_ACK 应答可合并为待发状态，不能累计无界报文列表。
+- 应答暂时无法入队时由调度器继续尝试；应答不会获得独立的无限寿命。
+  合并应答记录从首次待发起最多保留 60 秒，重复请求不续期；正常关闭
+  记录中的应答还受该记录更早的截止时间限制。入队成功即撤销待发标记。
+  单纯的应答待发过期只清除该应答，不因此关闭仍合法存活的连接；请求
+  发送方最终依靠自身握手或 FIN 重试期限判定成功或失败。
+- 队列满不能阻塞整个控制调度任务，也不能阻止它处理其他连接的截止
+  时间。不得把“尝试入队成功”统计成“对端确认成功”。
+
+### 7.3 取消、错误与连接 ID
+
+- connect future 取消或超时：撤销该连接的重试与本地所有权；目标端
+  未完成握手的状态按其固定期限退出，重复包不能延长。
+- 有效 RST、端点销毁或 FIN 重试耗尽：停止控制重试、唤醒等待任务，
+  保留错误与正常 EOF 的区别。只发送必要的现有重置通知，不建立 RST
+  确认和重试协议。
+- 清理失败连接不能重新产生待 accept；迟到的控制响应不能恢复已取消
+  的 connect future。
+- ConnId 分配必须避开所有仍有效的状态，包括正常关闭记录。回绕不能
+  复用仍在保留期内的 ID；会话标识变化后，旧报文不得作用于新会话。
+- 保留期之后无限迟到的包不在可靠恢复窗口内。不得通过永久保存关闭
+  记录来试图覆盖无界的网络延迟。
+
+## 8. 兼容性矩阵与降级
+
+| 源端 | 目标端 | 预期模式 | 必须满足 |
+| --- | --- | --- | --- |
+| 旧 | 旧 | legacy | 对照基线，保留既有行为 |
+| 新 | 旧 | SYNACK `rsv=0` 确定 legacy | 正常互通，不发 FIN_ACK，不要求目标支持新确认 |
+| 旧 | 新 | 从 SYN `rsv=0` 确定 legacy | 正常互通，不主动开启新 SYNACK/FIN 重传语义 |
+| 新 | 新 | 本连接握手确认可靠模式 | 握手与关闭在重试预算内恢复 |
+
+兼容的含义是旧节点仍可互通，且混合组合不因新代码发生行为退化。它不
+意味着旧目标端自动获得 accept 修复，或旧连接获得其未实现的 ACK/FIN
+恢复能力。必须把遗留失败与新增失败分别记录。
+
+发布或回退影响后续新连接的协商。协议模式固定在连接内，禁止基于后续
+路由公告变化对活跃连接进行升级或降级。旧可执行程序重启后不承担继续
+解释原进程可靠模式连接的义务。
+
+## 9. 实施拆分
+
+实施使用独立协议修复分支，以 `b37ee660` 及 EasyTier 当前已验证修复
+为基线，不将协议改动混入原 TCP flow-key patch。
+
+1. **先建立兼容测试夹具。** 使用实际旧依赖和当前基线端点，确认 `rsv`
+   处理、旧 SYNACK、重复 SYN 和旧模式输出门控。明确失败基线。
+2. **实现协商及状态处理。** 增加模式、合法报文校验、可靠模式幂等应答，
+   保留 legacy 路径。补上最终 ACK 丢失加立即 FIN 的交叉状态。
+3. **实现统一控制调度及可靠关闭。** 补足握手/FIN 期限、FIN_ACK、正常
+   关闭记录、队列暂满、取消和错误清理。
+4. **完成依赖验证后接入 EasyTier。** 更新依赖 pin 与锁文件，运行真实
+   代理路径、混合版本和跨平台验证，提交可追溯记录。
+
+协商声明代表完整可靠控制协议，不能在只实现握手恢复、尚未实现 FIN_ACK
+时对外声明 `rsv=1`。中间提交可以用于审阅，但仅完整实现且验证通过的
+依赖版本可被 EasyTier 发布使用。
+
+代码主要落点为 kcp-sys 的 `packet_def.rs`、`state.rs`、`endpoint.rs`，
+按实际错误传播需要调整 `stream.rs`；不预先拆出通用协议框架。EasyTier
+预计只需依赖更新、测试和记录，不需要修改 protobuf 或节点能力公告。
+
+## 10. 验证与验收标准
+
+### 10.1 确定性协议测试
+
+在端点输入/输出之间设置测试用报文过滤器，按连接 ID、报文类型和次数
+精确丢弃、延迟或重复报文。可使用可控时钟测试期限，不依赖随机 netem
+才能触发边界，也不通过扩大生产超时使测试通过。
+
+| 场景 | 验收断言 |
+| --- | --- |
+| 分别丢首个 SYN、SYNACK、最终 ACK | 新新组合恢复，同一连接只交接一次 |
+| 连续丢多次控制包后恢复链路 | 截止时间内恢复，重试次数与退避符合预期 |
+| 最终 ACK 丢失后空流立即 FIN | 目标完成握手、返回 EOF、仍能回复数据，无 RST |
+| 最终 ACK 丢失后首个 DATA 到达 | 正确完成握手，应用字节完整且不重复 |
+| 重复 SYN/SYNACK/ACK，含半关闭阶段 | 不重复创建连接，不恢复已经关闭的方向 |
+| 丢单向 FIN 或 FIN_ACK | 重传恢复；确认不关闭另一方向 |
+| 双方同时 FIN，单侧或双侧确认丢失 | 正确排空，正常关闭记录继续应答，最终回收 |
+| FIN 先于 accept 或 connect 返回 | 空请求、空响应均正确得到 EOF |
+| 接收缓冲尚未被应用读完 | FIN_ACK 不导致缓冲和数据任务提前释放 |
+| FIN 已确认后持续半关闭超过 60 s | 反向仍可传输，不受 FIN 期限误杀 |
+| 正常关闭记录收到重复 FIN、旧心跳 | 应答或忽略，无 RST，不延长固定保留期 |
+| SYN/FIN 永久丢失、控制输出队列长时间满 | 到期退出，无无限任务或状态残留 |
+| 队列临时满后恢复 | 待发事实不丢失，其他连接和清理继续运行 |
+| connect 取消、RST、端点销毁与重试并发 | 不复活旧状态，等待者正确结束，无伪 EOF |
+| ConnId 回绕、会话变化、迟到报文 | 不命中仍在保留期的旧 ID，不污染新会话 |
+
+### 10.2 真实旧版兼容测试
+
+测试夹具必须运行旧依赖的真实 endpoint，不能只在新实现上设置 legacy
+标志代替旧版本。首次验收覆盖 `d7427c2`、`b37ee660` 与新实现的组合，
+并记录 EasyTier 发布验证实际选用的旧二进制版本和哈希。
+
+除四种组合的双向数据与关闭外，额外断言：
+
+- 旧端收到 SYN `rsv=1` 仍按旧协议回复 SYNACK `rsv=0`。
+- 重复 SYN 不引出混合连接新增 RST；legacy 输出门控保持原有行为。
+- 混合组合捕获不到 FIN_ACK；旧端不必识别任何新控制语义。
+- PING/PONG、错误连接 ID、非法 flags 或未知 SYNACK 模式不能确认能力。
+- 新连接在节点升级、回退后重新选择正确模式，不沿用节点级缓存。
+- 旧版原有半关闭或丢包失败作为对照保留，不将它们写成新协议已通过。
+
+### 10.3 EasyTier 流量与平台验证
+
+Linux 需要 root 的测试在现有 `rust` 容器中运行。复用正常 target，权限
+问题通过修复所有权解决，不另开编译目录。
+
+- 完整三节点组合及 ACL、配置更新、端口转发、断连测试。
+- TCP/KCP/QUIC × 内核/smoltcp 六种模式，检查未修改协议没有退化。
+- 每组合 300 次短连接、16 并发、5 秒 socket 超时；KCP 每栈追加三轮，
+  与已有每版本 2,400 次 KCP 结果对照。
+- 空请求、256 KiB 请求后 EOF、1 MiB 响应，以及服务端先半关闭后客户端
+  才发送 256 KiB 的反向场景，均逐字节核对。
+- `netem delay 10ms 3ms loss 1%` 下持续双连接与短连接；定点控制包丢失
+  由协议测试证明，随机丢包实验用于验证整体行为。
+- 新旧两方向真实二进制互通；无丢包与丢包结果分别记录。
+- Linux、macOS、Windows 原生依赖测试及网关测试；格式与严格 Clippy。
+  缺少组件、未运行的项目不得记录为通过。
+
+### 10.4 未解释的反向超时
+
+复现脚本必须记录超时时已收到的字节数、是否收到 EOF、源端口、连接 ID，
+并在双方记录 FIN/FIN_ACK 的入队、发送和接收时间。补足原失败缺少的
+证据，区分数据缺失、关闭通知缺失、队列延迟和状态处理错误。
+
+恢复实际链路的 FIN 丢失，只能证明这一类注入故障已修复；仍需解释原
+异常或明确保留未定位项。不得用重跑通过覆盖原始失败。
+
+### 10.5 资源与交付门槛
+
+分别统计：应用代理连接、KCP 数据对象、半开握手、未确认 FIN、正常关闭
+记录、FD 和 RSS。保留期内的轻量记录属于设计成本，不能混同于活跃连接
+泄漏；其数量约受每秒关闭连接数乘以保留期约束，需实测内存成本。
+
+静止并超过握手/FIN 期限及关闭记录保留期后，所有应回收状态必须消失。
+使用重复负载周期检查资源是否持续累积，并检查端点空闲及大量并发时
+控制调度的 CPU 成本。不能仅凭一次 FD 回到基线宣布不存在泄漏。
+
+交付必须满足：确定性恢复用例通过；实际旧版兼容用例没有新增失败；
+错误路径有界清理；原有矩阵没有新退化；所有异常如实保留。完整最终
+代码 diff 由独立子代理审查，只处理高置信度真实缺陷。验证记录绑定
+提交、依赖 revision、二进制哈希、准确命令及原始日志。
+
+## 11. 当前进度与证据
+
+已完成：连接级版本协商、握手与 FIN 恢复、FIN_ACK、重复控制处理、
+正常关闭记录、队列饱和处理与取消清理。kcp-sys 最终提交为
+`3ef5c4161faf99940f3ed51efd43cef0cbc02b4f`，EasyTier 最终依赖接入为
+`ee02b8f7`。首次验收已测试真实旧实现 `d7427c2` 和 `b37ee660`。
+后续测试整理仅保留 `d7427c2` 长期基线；当前维护版本与依赖 pin 见
+[实现与验证记录](kcp-control-reliability-validation-2026-09-14.md)。
+
+三平台原生依赖测试、Linux 完整矩阵及实际流量的本轮结果单独记录，
+不沿用上一轮局部修复的通过数。最终代码审查没有 blocker / major，
+一项首次 SYNACK 调度竞态 minor 按用户规则记录待办。
+
+仍需保留的边界：原反向超时没有足够证据做最终归因；混合版本保留
+legacy 的控制恢复限制；有限负载和应用级资源采样不能代替生产规模
+长期内存、CPU 和容量验证。所有实测异常及未执行项见关联验证记录。
+
+此前调查原始产物位于：
+
+```text
+/data/project/proxy-close-validation-20260914/
+```
+
+关键证据：`remaining-loss-handshake.md`、`loss-handshake-evidence.log`、
+`delivery-reverse-timeout.md`、`fin-send-path-old-new.txt`、
+`delivery-manifest.json`、`traffic-summary.md`。上述绝对路径是本机
+调查产物位置；仓库读者可通过关联验证记录了解结论与证据限制。

docs/kcp-control-reliability-validation-2026-09-14.md

@@ -0,0 +1,296 @@
+# KCP 控制报文可靠性实现与验证（2026-09-14）
+
+本文记录
+[协议设计](kcp-control-reliability-design-2026-09-14.md)
+的实现与验证，独立于此前的 TCP flow-key 和半关闭局部修复。
+
+## 兼容测试维护整理
+
+当前维护版本为 kcp-sys `268533568d734ae89dc89603078da3ca522effe1`。
+保留 `d7427c22` 作为长期兼容基线，移除中间版本 `b37ee660` 的
+`kcp-sys-baseline` dev-dependency 与三项重复用例；单次使用的宏展开为
+普通测试函数。四项旧版兼容测试继续覆盖能力协商、双向数据、半关闭及
+重复 SYN；15 项 library 与 12 项协议回归不变。
+
+整理后 Linux 共 31/31 测试通过，格式与严格 Clippy 通过。EasyTier
+同步依赖 pin 与锁文件，并通过 `cargo +1.95 check --locked -p easytier
+--features full`。此次只整理测试与测试依赖，协议源码未改变。
+历史三平台 34/34 和全部流量结果仍属于下述 `3ef5c416` 实现验证，
+没有重写为整理后版本的执行结果。中间基线作为调查证据保留在本文。
+本次日志位于 `/data/project/kcp-compat-cleanup-validation/`。
+
+## 版本与实现
+
+- kcp-sys 基线：`b37ee660fb70bb6d816fb8bbc08b140e55e7218b`。
+- kcp-sys 初版实现：`c84733d4479b40a299d51f4c5b8bb02ccacadc68`。
+- kcp-sys 最终实现：`3ef5c4161faf99940f3ed51efd43cef0cbc02b4f`，补齐
+  可靠模式下未知连接 RST 输出队列饱和时的非阻塞处理。
+- EasyTier 基线：`851e7523`；接入提交：`4fedbdd1`、`ee02b8f7`，
+  仅修改依赖 pin 和 Cargo.lock。
+- 最终真实流量二进制：`final-easytier-core`，SHA-256：
+  `962f2480cb611ceb6cab293560d0dfb337218594cdc298a08f0e83801a2d17b8`。
+  它在接入提交前构建，源码及依赖内容与该提交一致；识别产物以哈希和
+  依赖 revision 为准，不单凭内嵌的 EasyTier git 版本字符串。
+
+依赖已发布到 `EasyTier/kcp-sys` 的独立分支
+`fix/control-reliability-20260914`，远端引用核对为上述最终 revision。
+EasyTier 任务分支为 `fix/kcp-control-reliability`。
+
+实现保留 14 字节 header，通过 SYN/SYNACK 的 `rsv` 协商可靠控制模式。
+收到旧 SYNACK 后固定使用 legacy，旧源端连接新目标端也从头使用 legacy。
+只有协商为可靠模式的连接使用独立 FIN_ACK 和新增恢复逻辑。
+
+可靠模式在原连接 ID 上恢复 SYN、SYNACK 和 FIN；重复握手不重复交接。
+最终 ACK 丢失后的空 FIN 可以同时确认握手并报告对端半关闭，反向仍能
+发送数据。FIN_ACK 只确认收到 FIN，不关闭本端发送方向，也不提前释放
+尚未被应用读取的接收数据。
+
+控制请求和待发送应答在原连接状态中保存，由端点统一调度。输出队列
+暂满不会丢失待发事实或延长固定期限；取消 connect 同步撤销本地状态。
+状态检查、控制入队和清理保持一致锁序，不持锁跨 await。
+
+初始重传间隔 200 ms、指数退避至 2 s；源端使用调用方连接超时，目标端
+握手及 FIN 待确认期限为 60 s。正常双向关闭且接收排空后释放数据对象，
+原状态表保留 65 s 的关闭记录，继续应答重复 FIN，并避免迟到心跳引出
+RST。FIN 一旦确认，正常半关闭不受 FIN 重试期限限制。
+
+## 自动化结果
+
+| 验证 | 结果 |
+| --- | --- |
+| Linux kcp-sys | 15 library + 12 协议回归 + 7 真实旧依赖兼容，34/34 |
+| macOS kcp-sys | 相同 34/34，两个 example target 通过 |
+| Windows kcp-sys | 相同 34/34，两个 example target 通过 |
+| Linux 两个 example target、格式、严格 Clippy | 通过 |
+| macOS 格式、严格 Clippy | 通过 |
+| Windows 格式、Clippy | 所选 stable 缺少组件，未执行 |
+| Linux 原生网关测试 | 200/200 |
+| macOS、Windows 原生网关测试 | 各 200/200 |
+| EasyTier 完整三节点及补充集成测试 | 276/276，834.639 s |
+| EasyTier Linux 严格 Clippy | 通过 |
+
+macOS 首次获取依赖遇到 GitHub TLS 错误，随后导入本机真实 Git 对象与
+checkout，在依赖 revision 不变的情况下离线测试；没有改成 path 依赖，
+也没有用新实现替换旧依赖。Windows 原始日志为 UTF-16LE，另保存 UTF-8
+副本。两平台复用原 target，没有另开编译目录绕过权限问题。
+
+协议修改集中在 kcp-sys，EasyTier core 源码没有变化。原生网关验证检查
+与现有相同 core 源码的兼容行为，不能替代上面的真实新旧 KCP 端点测试。
+远端应用 manifest 仍锁定旧依赖 `d7427c2`，网关命令只选择 easytier-core；
+关键转发文件 `tcp_proxy_service.rs` 哈希与本地一致。因此不能将这组
+网关测试描述为完整原生应用已经接入最终新依赖。
+
+## 失败到通过的对照
+
+- 丢弃第一份最终握手 ACK：基线客户端 connect 返回，服务端 accept
+  超过 5 s 仍未完成；实现后约 0.25 s 恢复，并成功发送服务端 greeting。
+- 新源端连接真实旧依赖：基线仅因 SYN 尚未声明协商能力而未达到新协议
+  测试要求；实现后 SYN 提出 `rsv=1`、旧 SYNACK 回复 `rsv=0`，后续
+  数据与关闭均走 legacy。该项验证协商功能，不把它描述为旧版互通 bug。
+- 原有 RST 单测曾在新连接上注入 `rsv=0` 的合成 RST，因可靠模式拒绝
+  不匹配模式而超时；测试改为注入该连接实际协商版本的 RST 后通过。
+  模式不匹配的报文不能用于证明正常 RST 错误传播失败。
+- 新增双向大缓冲夹具最初单次写入超过既有 KCP send 的分片限制，出现
+  `Err(-2)`。调整为与原有测试一致的 16 KiB 分块，仍验证双向各
+  200 KiB 总数据和原 5 s 期限；本补丁没有修改既有单次大写入限制。
+
+- 最终补查发现初版 `c84733d` 对未知可靠 FIN 的 RST 仍使用阻塞发送。
+  填满输出队列后，新 SYN 不能在 100 ms 内进入状态表；改为可靠模式
+  的无状态应答使用 try_send 后通过。需要重试的有状态控制仍由状态表
+  保管；legacy 发送路径不变。
+
+原始失败日志保留，未使用扩大业务超时或重跑通过覆盖失败记录。
+
+## 协议与生命周期覆盖
+
+12 项公有 API 协议回归使用真实端点及按报文类型过滤的链路：
+
+- 连续丢 SYN、连续丢 SYNACK、丢最终 ACK 后的服务端 greeting。
+- 所有空最终 ACK 均丢失，空 FIN 直接完成握手，EOF 后仍可回复。
+- 单向 FIN 或 FIN_ACK 丢失，另一方向仍可传输。
+- 双向 200 KiB 缓冲、双方首个关闭确认丢失、延后读取与排空。
+- 半关闭后重复 SYN/SYNACK/ACK；握手 ACK 丢失时 DATA 乱序、重复。
+- FIN 确认后推进 61 s，再恢复实际时钟，仍可反向传输。
+- PONG 保留 `rsv=1`、非法 SYNACK flags、非空 SYNACK 均不能确认模式。
+- 未知 SYNACK version 返回 `InvalidProtocolVersion`，不启用新模式。
+
+15 项 library 测试包含原有 10 项以及五项生命周期与队列测试：取消 connect
+立即释放状态；重复 SYN 与满输出队列不延长半开期限；未确认 FIN 超时
+唤醒读端并释放状态；正常关闭记录应答迟到包、不引出 RST、不被延长，
+保留期间跳过相同 ConnId，期满后删除旧记录而不影响新连接；满输出
+队列下未知可靠 FIN 不能阻止后续 SYN 进入握手。
+
+可控时钟只用于测试期限，不修改生产时间常量。数据测试仍通过实际 KCP
+发送、接收及 AsyncRead/AsyncWrite 路径。
+
+## 真实旧依赖兼容
+
+dev-dependency 固定并实际运行 `d7427c2`、`b37ee660` 两个历史实现，
+没有用新代码上的 legacy 开关模拟旧端。
+
+7 项测试覆盖旧 SYN 处理探针和两个基线的新旧双向连接、256 KiB 双向
+数据、半关闭、重复 SYN。报文捕获断言：新源初始 SYN 可为 `rsv=1`，
+其余混合连接报文均为 `rsv=0`；没有 FIN_ACK、新增 RST 或重复 accept。
+
+`d7427c2` 原有正常关闭被报告为 BrokenPipe 的行为仍在对照中保留。
+兼容意味着旧节点仍可互通，不意味着它自动获得新协议的恢复能力。
+
+## 实际代理流量
+
+实验使用独立 namespace，底层 UDP，
+覆盖 TCP/KCP/QUIC 与内核/smoltcp 六种模式。固定每轮 300 次短连接、
+16 并发、5 s socket 超时，逐字节校验大小请求、纯空请求及反向半关闭。
+
+验证分为两个阶段；不将初版流量统计冒充最终版本结果。
+
+### 初版 c84733d
+
+二进制 `protocol-easytier-core` 的 SHA-256 为
+`f41ff98762ed1ce8691d8f83b8c9e47acc4548c76432a17cd2daba36e2cc7b80`。
+
+- 六模式主矩阵：1,800 次短连接、12 次大小请求半关闭、6 次反向
+  半关闭、192 次纯空请求，全部通过。
+- KCP 每栈追加三轮，合并主矩阵共 2,400 次 KCP 短连接，全部通过。
+- `netem delay 10ms 3ms loss 1%` 六模式：1,800 次短连接、12 次大小
+  半关闭、6 次反向、192 次纯空及每组合 15 s 双连接持续流量，全部通过。
+- 新旧双方向各六模式：3,600 次短连接、24 次大小半关闭、384 次纯空
+  和每组合 3 s 持续流量通过；**反向半关闭为 11/12，存在一次失败**。
+
+旧端为依赖 b37 的 `delivery-easytier-core`，SHA-256 为
+`4635810ac9a536258f9b7ff606e5e1a5eb0243cb0f187825ba6f721d92dfc4fe`。
+失败发生在新 source → 旧 destination 的 KCP/smoltcp，连接
+`conv=3560055726`、源端口 `40748`：客户端已经收到完整 1 MiB，随后
+等待 EOF 超过 5 s；因此未进入后发 256 KiB 阶段。旧目标端在
+10:11:08.953 进入 LocalClosed，直到客户端超时才见客户端方向关闭。
+DEBUG 不能确定旧端 FIN 后续的发送、到达或处理点，不能直接定性为
+FIN 丢失，也不能把混合版本测试写成全部通过。
+
+另一次有界 KCP/kernel 丢包 TRACE 测试中，300 次短连接及全部半关闭
+通过。实际捕获的控制事件全部使用 version 1：连接 `1468864199` 的
+重复 SYNACK 相隔约 200 ms，目标随后收到 ACK，业务完成；连接
+`1468864161` 的重复 FIN 后收到 FIN_ACK。它们证明实际链路使用了
+新控制恢复路径；单轮成功不代表任意丢包条件下都能成功。
+
+### 最终 3ef5c416
+
+- 六模式主矩阵全部通过：1,800 次短连接、12 次大小半关闭、6 次反向
+  半关闭、192 次纯空请求。
+- 六模式随机丢包全部通过：相同流量规模，另每组合 15 s 双连接持续
+  逐字节回显。原 5 s socket 超时不变，没有添加应用重试。
+- 混合版本无丢包，两连接方向 × 两个 KCP 栈全部通过：1,200 次短连接、
+  8 次大小半关闭、4 次反向及 128 次纯空请求。该轮通过不覆盖初版
+  混合实验中的 EOF 超时记录。
+- KCP 每栈追加三轮全部通过；合并主矩阵为 **2,400/2,400** 次 KCP
+  短连接；追加轮次的 12 次大小、6 次反向和 192 次纯空也全部通过。
+混合丢包仍走 legacy，下表为单轮**失败数**，不重跑取最好结果。
+每组合为 300 短连接、2 次大小半关闭、1 次反向、32 次纯空和 3 s 持续流量。
+
+| 连接方向/栈 | 短连接失败 | 大小失败 | 反向失败 | 纯空失败 | 持续失败 |
+| --- | --- | --- | --- | --- | --- |
+| b37 → 最终新 / kernel | 6 | 0 | 0 | 16 | 0 |
+| b37 → 最终新 / smoltcp | 2 | 0 | 0 | 13 | 0 |
+| 最终新 → b37 / kernel | 7 | 1 | 0 | 16 | 0 |
+| 最终新 → b37 / smoltcp | 1 | 0 | 0 | 14 | 0 |
+
+唯一大小用例失败停在 greeting 阶段，5 s 超时；纯空失败为 response
+阶段收到空 EOF。为判断兼容回退，另跑一次相同条件、相同业务参数的
+b37 → b37 旧旧对照：kernel 短连接失败 2/300、纯空失败 12/32；
+smoltcp 分别为 0/300、16/32。两栈的大小、反向与持续项目均通过。
+
+旧旧 TRACE 确认了一条失败链：kernel 的 `conv=3046346801`、空请求
+`id=3`、源端口 `35958`，目标在 10:30:44.112 先收到 FIN，直接
+Closed 并发送 RST；10:30:44.115 才收到最终 ACK|DATA。源在 .113
+收到 RST，客户端约 37 ms 后得到零字节 EOF。`src/state.rs` 的
+SynReceived + FIN → Closed/RST 路径本次没有修改；可靠模式单独支持
+FIN 完成握手，legacy 按已批准设计保留原行为。
+
+这条时序证明上述失效路径在旧旧连接也存在，不能由随机样本的失败率
+断言所有混合版本失败均已归因或已经排除一切回退。混合实验原 DEBUG
+不足以逐包归因全部失败。兼容保证旧节点可按原协议互通；控制恢复能力
+需要两端都协商为 version 1，混合部署仍不能获得这一保证。
+
+最终丢包轮次直接启用 KCP TRACE：kernel 捕获 5 个成功连接收到重复
+SYNACK、4 个收到重复 FIN；smoltcp 分别为 2 个、5 个。捕获的控制
+报文均使用 version 1。详见 `final-control-recovery-*-summary.json`
+及对应 `evidence.log`；这份证据直接绑定最终二进制。
+
+资源观察区分应用代理条目与内部 KCP 状态。CLI 不直接暴露依赖内部
+关闭记录，不能用 CLI 条目清零证明内部记录已经删除；内部期限由
+生命周期测试验证。实际流量保存起始、结束、15 s、80 s 的 FD/RSS 与
+应用代理条目。65 s 关闭记录属于设计成本，不能沿用旧的 15 s 内部
+状态必须清零的断言。
+
+最终每栈三轮连续负载的资源结果如下。a 为 source，b 为 destination。
+该追加轮次的 FD 全程未增长；应用 proxy 条目在 15 s 与 80 s 均为零。
+
+| 栈/节点 | FD 前后 | RSS 前 → 80 s（KiB） | 负载 CPU 秒 / 墙钟秒 | 静置 15–80 s 单核 CPU |
+| --- | --- | --- | --- | --- |
+| kernel/a | 15 → 15 | 46,944 → 50,792 | 2.20 / 2.697 | 0.29% |
+| kernel/b | 15 → 15 | 46,580 → 49,344 | 1.12 / 2.694 | 0.31% |
+| smoltcp/a | 14 → 14 | 46,784 → 50,352 | 4.39 / 5.378 | 0.49% |
+| smoltcp/b | 14 → 14 | 46,024 → 49,060 | 2.32 / 5.368 | 0.48% |
+
+CPU 来自 `/proc/PID/stat` 的 user/system ticks 与单调时钟差，包含
+路由、心跳、代理、日志等全部进程工作。产物为 debug 构建，表中负载
+CPU 也不是纯协议开销或吞吐基准。RSS 未回到起点，无法由这些采样区分
+分配器缓存与其他长期对象，也不能推算每条关闭记录的精确内存成本。
+内部对象期限由单测验证，生产规模的逐对象内存与长期容量验证仍未完成。
+主矩阵 kernel/b 在 15 s 采样曾由 15 个 FD 暂升为 16，80 s 恢复为 15；
+该瞬时变化同样保留在原始报告，未作为持续增长处理。
+原始记录为 `final-kcp-repeat-kcp-*-resources.json`，换算另存
+`final-resource-summary.json`。
+
+## 审查、复现与限制
+
+初轮独立子代理只读审查 `b37ee660..c84733d`，没有高置信度缺陷发现。
+最终由新子代理审查完整 `b37ee660..3ef5c416` 及 EasyTier 最终 pin，
+未发现 blocker / major；重点检查旧版输出规则、握手与关闭交叉状态、
+队列、取消清理和锁序。
+
+最终审查记录一项 **minor / high confidence** 待办：
+`kcp-sys/src/endpoint.rs:922` 新 SYN 路径先 notify 再插入连接状态，
+多线程时可能先消费通知并漏过首次 SYNACK 调度。正常源端约 200 ms 后
+重发 SYN 即可恢复；若后续 SYN 未到达，则等待约 10 s 周期扫描。状态
+不会丢失，也不会永久阻塞，但特别短的 connect 期限可能超时。按用户
+minor 默认记录的规则保留；后续最小改动是将通知放到状态插入之后。
+
+主要命令：
+
+```sh
+# kcp-sys 工作树
+cargo test --all-targets
+cargo fmt --all -- --check
+cargo clippy --all-targets -- -D warnings
+
+# EasyTier，Linux root 集成测试在 rust 容器内执行
+cargo +1.95 test --locked -p easytier-core \
+  --features proxy-smoltcp-stack --lib gateway::
+cargo +1.95 nextest run --locked -p easytier --features full --lib \
+  -E 'test(subnet_proxy_three_node_test) | test(subnet_proxy_half_close_test) | test(acl_rule_test_inbound) | test(acl_rule_test_subnet_proxy) | test(proxy_three_node_disconnect_test) | test(config_patch_test) | test(port_forward_with_inbound_default_drop_acl_test)' \
+  --test-threads 1 --no-fail-fast
+cargo +1.95 clippy --locked -p easytier --features full \
+  --lib --tests -- -D warnings
+```
+
+本机原始日志、脚本、JSON 与二进制：
+
+```text
+/data/project/kcp-control-validation-20260914/
+```
+
+主要证据为 `final-ack-red.log`、`final-ack-green.log`、
+`final-dependency-tests.log`、`final-dependency-clippy.log`、
+`unknown-close-full-output-red.log`、`legacy-final.log`、
+`negotiation-lifetime-regressions.log`、`final-native-*-tests.log`、
+`linux-gateway.log`、`integration-final.log`、`app-final-clippy.log`。
+`integration-protocol.log` 是初版的中断轮次，切换最终实现后重新执行完整
+矩阵，不计入最终通过数。
+流量的准确 argv、产物 hash 和逐连接结果另存该目录。完整流量汇总为
+`traffic-summary.md`，混合丢包对照为 `mixed-loss-analysis.md`，
+旧旧逐包证据为 `legacy-fin-before-ack-evidence.log` 与
+`legacy-fin-before-ack-client.json`。测试环境清理记录为 `cleanup.json`。
+
+此前单次反向超时的具体丢包点仍不能由旧 DEBUG 日志倒推出。定点 FIN
+丢失测试证明该类失效现在能够恢复，不能因此改写原事故的根因结论。
+Windows/macOS 原生 TUN 端到端、生产规模长期负载、吞吐与容量上限仍
+不是这些有限测试能够证明的事项。

docs/ohos-downstream-builds.md

@@ -0,0 +1,65 @@
+# HarmonyOS HAR delivery
+
+The `ohos` workflow builds the Core HAR on pushes, pull requests, tags, and
+manual runs. Every successful run retains a short-lived HAR artifact, while
+publication to the private OHPM registry is deliberately restricted:
+
+- A push to `main` publishes only when the pushed SHA is the merge commit of a
+  pull request targeting `main` and the push is not forced.
+- A manual run on `main` publishes by default.
+- A manual run on another branch publishes only when its `publish` input is
+  enabled.
+- Direct pushes, pull requests, tags, and ordinary non-main branch builds do
+  not publish.
+
+## Package identity
+
+All branches publish the same private package name, `easytier-ohrs`. The
+source branch is encoded in the package version instead of the package name:
+
+```text
+<core-version>-<branch-id>-<commits-since-tag>-<run-number>-<run-attempt>-g<short-sha>
+```
+
+`branch-id` is a lowercase, OHPM-safe form of the source branch. Publishing a
+new version advances the registry's `latest` version. After publication, Core
+sends the `core-har-published` repository dispatch to the ArkTS and Pro
+repositories. The payload contains only `core_repository`, `core_ref`, and
+`package_name`.
+
+## App install sequence
+
+ArkTS and Pro use the same three OHPM commands:
+
+```bash
+ohpm uninstall "$CORE_HAR_PACKAGE"
+ohpm install "$CORE_HAR_PACKAGE@latest" \
+  --registry "$CORE_HAR_REGISTRY"
+ohpm install
+```
+
+The App workflow then reads the installed version from:
+
+```text
+oh_modules/<package_name>/oh-package.json5
+```
+
+The existing `oh-package-lock.json5` and `oh_modules` directory are not
+manually deleted. Because the package name remains `easytier-ohrs`, downstream
+source imports do not need to be rewritten.
+
+## Secrets
+
+Core requires:
+
+- `CODEARTS_PRIVATE_OHPM`: publish-capable OHPM configuration.
+- `DOWNSTREAM_DISPATCH_TOKEN`: permission to dispatch both App repositories.
+
+ArkTS and Pro require:
+
+- `CODEARTS_PRIVATE_OHPM_READ`: read-only private OHPM authentication.
+- `SIGNING_REPOSITORY_TOKEN`: read access to the corresponding private signing
+  repository.
+
+Signing and AppGallery Connect credentials remain downstream application
+concerns and are not passed through the Core dispatch payload.

docs/quic-proxy-memory-benchmark-2026-07-27.md

@@ -0,0 +1,176 @@
+# QUIC TCP Proxy 内存对比（2026-07-27）
+
+## 结论
+
+在相同的双节点 network namespace 环境中，当前分支相对 2.6.4：
+
+- 空闲且未建立 TCP proxy 连接时，两端合计 USS 从 15.95 MiB
+  降至 11.66 MiB，下降 26.9%；
+- 66 条空闲 TCP proxy 连接时，两端合计 USS 从 19.45 MiB
+  降至 13.85 MiB，下降 28.8%；
+- 固定 1 Gbit/s 的单流 TCP proxy 传输中，两端平均 USS 从
+  20.69 MiB 降至 14.75 MiB，下降 28.7%，同步峰值从
+  21.50 MiB 降至 15.02 MiB；
+- 从 0 增长到 66 条空闲连接推算，每条连接在两个 core 上合计
+  增加约 33.9 KiB USS；2.6.4 为 54.2 KiB，下降 37.4%；
+- 当前分支的匿名内存下降约 40% 至 44%，说明堆和连接缓冲区开销
+  确实降低。
+
+当前分支的 RSS 比 2.6.4 高约 5% 至 11%，但这部分差异没有出现在
+Anonymous 中，主要体现为非匿名或共享驻留页。PSS 在高连接数及
+固定吞吐场景基本持平，USS 和 Anonymous 则显著更低。因此不能
+只根据 RSS 判断发生了内存回退。
+
+## 测试对象
+
+| 版本 | 标识 | 二进制 |
+|---|---|---|
+| 当前分支 | commit `9e2ed33aeb37`，版本 `2.6.4-9e2ed33a` | `target/x86_64-unknown-linux-musl/release/easytier-core` |
+| 2.6.4 | 版本 `2.6.4-8428a89d` | `/data/tickets/easytier/easytier-linux-x86_64/easytier-core` |
+
+当前分支使用以下命令重新构建，确保被测二进制准确对应 HEAD：
+
+```console
+cargo build --release \
+  --target x86_64-unknown-linux-musl \
+  -p easytier \
+  --features jemalloc \
+  --bin easytier-core \
+  --bin easytier-cli
+```
+
+两个二进制均为 stripped static PIE。当前分支明确使用 musl 和
+jemalloc。
+
+## 测试拓扑
+
+- 两个 `easytier-core` 分别运行在独立的 network namespace；
+- namespace 通过 Linux bridge 和 veth 连接；
+- underlay 地址为 `10.251.89.10/24` 和 `10.251.89.11/24`；
+- EasyTier 虚拟地址为 `10.144.144.1/24` 和
+  `10.144.144.2/24`；
+- 两个节点之间使用 UDP listener 建立 EasyTier peer 连接；
+- 源节点启用 `--enable-quic-proxy true`；
+- 两个节点均保留默认 QUIC input；
+- TCP client 从 `10.144.144.1` 访问绑定在
+  `10.144.144.2` 上的 server；
+- `tcp_proxy_connect` 指标的 `protocol` 标签确认为 `QUIC`；
+- 66 条连接场景通过两端各 132 个 established TCP socket 条目
+  确认当前连接数。
+
+## 采样口径
+
+数据读取自 `/proc/<pid>/smaps_rollup`：
+
+- RSS：进程映射的全部驻留页，包含共享代码页；
+- PSS：共享页按共享进程数量分摊后的驻留内存；
+- USS：`Private_Clean + Private_Dirty`，表示进程独占内存；
+- Anonymous：匿名页，主要反映堆、栈和运行时缓冲区。
+
+空闲场景每隔 2 秒采样一次，共 5 次，表格记录均值。固定吞吐场景
+持续 20 秒，每隔 2 秒采样一次，共 8 次，同时记录均值和峰值。
+所有容量单位均为 MiB。
+
+## 空闲连接结果
+
+以下数据均为两个 EasyTier core 的合计值：
+
+| 当前连接数 | 当前 RSS | 2.6.4 RSS | 当前 PSS | 2.6.4 PSS | 当前 USS | 2.6.4 USS | USS 变化 | 当前 Anonymous | 2.6.4 Anonymous |
+|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| 0 | 40.42 | 36.33 | 26.03 | 24.50 | 11.66 | 15.95 | -26.9% | 8.89 | 15.62 |
+| 1 | 41.52 | 38.46 | 26.49 | 25.98 | 11.46 | 16.82 | -31.9% | 9.08 | 16.23 |
+| 10 | 41.63 | 38.79 | 26.59 | 26.32 | 11.56 | 17.15 | -32.6% | 9.19 | 16.55 |
+| 66 | 43.68 | 41.11 | 28.76 | 28.63 | 13.85 | 19.45 | -28.8% | 11.22 | 18.79 |
+
+0 条和 1 条连接之间的小幅反向波动属于分配器回收和采样时序噪声，
+不能解释为连接产生负开销。使用 0 到 66 条连接的跨度估算单位
+连接成本更稳定。
+
+### 分节点 USS
+
+| 当前连接数 | 当前源端 | 当前目的端 | 2.6.4 源端 | 2.6.4 目的端 |
+|---:|---:|---:|---:|---:|
+| 0 | 5.45 | 6.21 | 8.07 | 7.88 |
+| 1 | 5.43 | 6.03 | 8.68 | 8.14 |
+| 10 | 5.49 | 6.07 | 8.90 | 8.25 |
+| 66 | 6.60 | 7.25 | 10.19 | 9.25 |
+
+### 单位连接增量
+
+以 0 到 66 条连接的 USS 增量计算：
+
+| 版本 | 两端 USS 增量 | 每连接两端合计 | 每连接单端平均 |
+|---|---:|---:|---:|
+| 当前分支 | 2.19 MiB | 33.9 KiB | 17.0 KiB |
+| 2.6.4 | 3.50 MiB | 54.2 KiB | 27.1 KiB |
+
+当前分支的每连接独占内存增量下降约 37.4%。
+
+## 固定 1 Gbit/s 活跃流量
+
+为排除两个版本最大吞吐不同造成的缓冲区差异，使用
+`iperf3 -b 1G -P 1 -t 20` 将两个版本都限制为 1 Gbit/s。
+两次测试均实际完成 2.33 GiB 传输，接收端报告 1000 Mbit/s。
+
+### 平均值
+
+| 版本 | 节点 | RSS | PSS | USS | Anonymous |
+|---|---|---:|---:|---:|---:|
+| 当前分支 | 源端 | 22.89 | 15.41 | 7.94 | 6.88 |
+| 当前分支 | 目的端 | 21.77 | 14.29 | 6.82 | 5.27 |
+| 当前分支 | 两端合计 | 44.67 | 29.70 | 14.75 | 12.14 |
+| 2.6.4 | 源端 | 22.59 | 16.34 | 11.70 | 11.35 |
+| 2.6.4 | 目的端 | 19.95 | 13.67 | 8.99 | 8.77 |
+| 2.6.4 | 两端合计 | 42.53 | 30.01 | 20.69 | 20.13 |
+
+### 对比
+
+| 指标 | 当前分支 | 2.6.4 | 变化 |
+|---|---:|---:|---:|
+| 两端平均 RSS | 44.67 | 42.53 | +5.0% |
+| 两端平均 PSS | 29.70 | 30.01 | -1.0% |
+| 两端平均 USS | 14.75 | 20.69 | -28.7% |
+| 两端平均 Anonymous | 12.14 | 20.13 | -39.7% |
+| 两端同步峰值 USS | 15.02 | 21.50 | -30.2% |
+
+## 分节点原始统计
+
+下表保留各场景所有样本计算出的均值；`max_uss` 是该节点采样期间
+的最大 USS。
+
+| 版本 | 场景 | 节点 | 样本数 | mean_rss | mean_pss | mean_uss | mean_anon | max_uss |
+|---|---|---|---:|---:|---:|---:|---:|---:|
+| 当前 | 0 连接 | 源端 | 5 | 19.830 | 12.636 | 5.451 | 4.314 | 5.582 |
+| 当前 | 0 连接 | 目的端 | 5 | 20.587 | 13.393 | 6.208 | 4.579 | 6.320 |
+| 当前 | 1 连接 | 源端 | 5 | 20.463 | 12.944 | 5.432 | 4.401 | 5.465 |
+| 当前 | 1 连接 | 目的端 | 5 | 21.061 | 13.541 | 6.030 | 4.682 | 6.051 |
+| 当前 | 10 连接 | 源端 | 5 | 20.522 | 13.002 | 5.491 | 4.459 | 5.496 |
+| 当前 | 10 连接 | 目的端 | 5 | 21.105 | 13.585 | 6.073 | 4.726 | 6.086 |
+| 当前 | 66 连接 | 源端 | 5 | 21.513 | 14.050 | 6.595 | 5.498 | 6.672 |
+| 当前 | 66 连接 | 目的端 | 5 | 22.169 | 14.706 | 7.251 | 5.723 | 7.375 |
+| 当前 | 1 Gbit/s | 源端 | 8 | 22.893 | 15.410 | 7.936 | 6.877 | 8.188 |
+| 当前 | 1 Gbit/s | 目的端 | 8 | 21.773 | 14.291 | 6.816 | 5.266 | 6.832 |
+| 2.6.4 | 0 连接 | 源端 | 5 | 18.278 | 12.355 | 8.071 | 7.876 | 8.328 |
+| 2.6.4 | 0 连接 | 目的端 | 5 | 18.048 | 12.144 | 7.880 | 7.747 | 8.203 |
+| 2.6.4 | 1 连接 | 源端 | 5 | 19.535 | 13.279 | 8.676 | 8.262 | 8.727 |
+| 2.6.4 | 1 连接 | 目的端 | 5 | 18.920 | 12.705 | 8.143 | 7.971 | 8.191 |
+| 2.6.4 | 10 连接 | 源端 | 5 | 19.762 | 13.506 | 8.902 | 8.473 | 8.910 |
+| 2.6.4 | 10 连接 | 目的端 | 5 | 19.027 | 12.812 | 8.250 | 8.078 | 8.297 |
+| 2.6.4 | 66 连接 | 源端 | 5 | 21.069 | 14.805 | 10.194 | 9.702 | 10.320 |
+| 2.6.4 | 66 连接 | 目的端 | 5 | 20.045 | 13.822 | 9.252 | 9.088 | 9.293 |
+| 2.6.4 | 1 Gbit/s | 源端 | 8 | 22.588 | 16.343 | 11.697 | 11.354 | 12.258 |
+| 2.6.4 | 1 Gbit/s | 目的端 | 8 | 19.946 | 13.670 | 8.993 | 8.774 | 9.277 |
+
+## 解释和限制
+
+1. 以固定 1 Gbit/s 场景为例，当前分支 RSS 增加 5.0%，但
+   Anonymous 下降 39.7%，PSS 下降 1.0%。这说明差异主要体现
+   在非匿名或共享驻留页；本次没有保存逐 VMA 数据，因此不进一步
+   将它归因到某一个具体映射。
+2. 两个相同版本进程运行在同一宿主机时会共享可执行文件代码页，
+   所以 PSS 比 RSS 更适合估算该测试拓扑的宿主机总成本，USS 和
+   Anonymous 更适合判断 EasyTier 私有堆及缓冲区的变化。
+3. 这是一轮受控 A/B 测试，而不是长期统计分布。数值可用于确认
+   差异方向和量级；若作为发布门禁，应固定机器负载并增加多轮重复。
+4. 本文只比较 QUIC TCP proxy 内存，不使用未限速吞吐结果推断性能，
+   避免吞吐差异污染内存结论。

docs/socket-protection.md

@@ -0,0 +1,84 @@
+# Host socket protection
+
+VPN bypass is a socket-creation requirement, not an operation on a socket that
+core has already connected. Core and WASI guests never need an OS file descriptor.
+
+## Portable requests
+
+`TcpBindOptions::need_protect` and `UdpBindOptions::need_protect` travel through the
+existing connect/bind operations. A host requiring VPN bypass must acknowledge
+successful protection before connect, bind/listen, or publishing the socket.
+Failure or cancellation fails creation and discards the owned socket; emitting
+an event alone is not acknowledgement. Platforms without VPN bypass can treat
+the requirement as a no-op.
+
+- TCP connect constructors request protection, including egress for proxies.
+- TCP transport/hole-punch listeners request protection. Hosts retain this flag
+  on the listener and protect accepted children before handing them to core.
+- Local ProxyNat/SOCKS/port-forward/port-lease listeners do not request it.
+- UDP transport, candidates, listeners, NAT egress and STUN request protection;
+  HolePunchControl, local SOCKS/port-forward and port-lease sockets do not.
+- Low-level TCP/UDP bind options default to protection, including deserialization
+  of options without `need_protect`. The named local/TUN-facing constructors set
+  `false` explicitly. The UDP default keeps its historical purpose label for
+  socket setup; only the named `hole_punch_control()` constructor opts out.
+- `with_bind()` replaces the **entire** bind object. A local listener's replacement
+  must retain its opt-out rather than inherit the protected default. A native
+  adapter must honor explicit `false`, not silently change it based on `purpose`.
+- DNS and source-route queries are already host-owned operations. A bypass-enabled
+  host must protect their underlying sockets before querying/probing, including
+  DNS TCP fallback, rather than letting system DNS silently bypass this contract.
+
+## TUN-facing ingress and port forwarding
+
+The extra `force_smoltcp` wildcard port-forward ingress listener has been removed.
+Normal TUN-backed ingress is delivered to the existing unprotected native listener;
+its accepted sockets remain unprotected so overlay replies can return through TUN.
+The physical/underlay egress socket is protected independently. A separate
+DataPlane listener must not mask broken host/TUN routing in this path.
+
+This does not remove the existing public DataPlane listener APIs, the generic
+no-TUN smoltcp TCP proxy, or `force_smoltcp` itself. Those have other uses. Whether
+Android subnet proxy works without forced smoltcp needs actual platform regression
+testing; socket-creation unit tests alone do not establish that result.
+
+## Native integration and HarmonyOS
+
+The native `easytier` adapter implements the creation requirement using an async
+`NativeSocketProtector` callback. This is a native implementation detail, not a
+new portable or WASI ABI. It takes only the native handle; the creation options
+select policy, without a second purpose enum. Namespace switching is confined to synchronous socket
+creation and never held across the callback's await.
+
+The existing native `bind` builder is async and shared by TCP/UDP creation. Its
+legacy direct-call default remains unprotected; portable factories explicitly
+pass their core bind options (default protected). Callers must await `.call()`.
+TCP listeners reuse TCP socket creation then listen, instead of duplicating the
+setup. Existing legacy WebSocket direct-call policy is unchanged.
+
+The HarmonyOS broker wakes the already-pending request consumer with `Notify`
+(no polling timer). It keeps a duplicate FD alive until ArkTS completes
+`VpnConnection.protect(fd)` and returns its ACK. The waiting creation future is
+woken immediately by the oneshot acknowledgement. Failure stays fail-closed;
+shutdown retains dispatched FDs for late ACKs to prevent FD reuse races.
+The ArkTS request shape is unchanged; its diagnostic `purpose` string is now
+the generic `"socket"`. Neither ACK routing nor protection policy uses that label.
+
+This guarantees ordering, not a wall-clock real-time bound: OS/ArkTS scheduling
+can still delay protection. Such a delay keeps the socket unconnected; it must
+never allow the first SYN/query to race ahead of protection.
+
+## WASI option format
+
+The `easytier_host` import names and function signatures are unchanged. TCP
+connect, TCP listen and UDP bind use option document **version 3** (previously 2):
+one `u8` boolean `need_protect` is inserted immediately after the existing purpose
+byte and before the optional bind-device field. All other field encodings and
+purpose values are unchanged. The document version lets older hosts reject
+unsupported options instead of silently ignoring protection. DNS, environment,
+instance-config and data-plane layouts/versions are unchanged.
+
+An embedding host must update its versioned option decoder and honor the flag
+inside its existing creation implementation. The external host implementation
+is not in this repository: building the guest proves propagation/compatibility
+of imports, not that every external host has implemented platform protection.

docs/tcp-proxy-flow-key-validation-2026-09-13.md

@@ -0,0 +1,137 @@
+# TCP proxy flow-key 验证记录（2026-09-13）
+
+本次验证没有发现只在修复版本出现的行为退化。同源端口、不同目标的
+并发连接在六种代理模式下均由父提交的超时变为成功。验证中仍有半关闭
+失败和 KCP 突发短连接超时，父提交也存在这些现象，不能将结果描述为
+所有场景均无异常。
+
+## 版本与范围
+
+- 修复版本：`eb83655958be932d6de34e090dc361b6f3ba3393`。
+- 父提交：`e0bdb516b6dc8a654940efbe12960dbfa846f424`。
+- 本次提交仅新增测试与记录，生产代码保持上述修复版本的内容。
+- Linux 测试在现有 `rust` 容器内运行，Rust 1.93.1。
+- macOS arm64、Windows x64 原生测试使用 Rust 1.95.0。
+
+父提交使用独立 worktree，但复用当前 worktree 的 `target`。第一次父提交
+网关测试意外复用了修复版本的构建缓存，结果已排除。清理相应 package
+的构建产物后重新编译，确认父提交网关测试为 189 项，修复版本原有
+192 项。真实流量实验还通过 CLI 核对两端实际运行的版本号。
+
+## 自动化验证
+
+| 验证 | 结果 |
+| --- | --- |
+| 修复版本完整 `subnet_proxy_three_node_test` 矩阵 | 256/256，714.800 秒 |
+| ACL、端口转发 ACL、配置更新、代理断连 | 父提交与修复版本各 14/14 |
+| 父提交 Linux 网关测试 | 189/189 |
+| 新增测试后的 Linux 网关测试 | 198/198 |
+| 新增测试后的 macOS 原生网关测试 | 198/198 |
+| 新增测试后的 Windows 原生网关测试 | 198/198 |
+
+完整三节点矩阵覆盖 TUN/no-TUN、普通/公共中继、源端 KCP/QUIC 开关、
+目标端 KCP/QUIC 开关及对应输入禁用组合。每个组合检查映射子网地址、
+真实子网地址和节点虚拟地址上的 ICMP、TCP、UDP。
+
+命令（Linux 需在容器内运行）：
+
+```sh
+cargo nextest run -p easytier --features full --lib \
+  subnet_proxy_three_node_test --test-threads 1 --no-fail-fast
+
+cargo test -p easytier-core --features proxy-smoltcp-stack --lib gateway::
+
+cargo fmt --all -- --check
+
+cargo clippy -p easytier-core \
+  --features proxy-smoltcp-stack,ring-crypto --lib --tests -- -D warnings
+```
+
+格式检查和上述严格 Clippy 检查均通过。仅启用 `proxy-smoltcp-stack`
+时，严格 Clippy 被未修改的 `tunnel/encrypt/mod.rs` 中
+`assert_interoperable` 未使用警告阻断；增加 `ring-crypto` 会启用调用
+该函数的现有后端互操作测试。本次没有修改或屏蔽该警告。
+
+14 项补充集成测试来自以下测试组，使用各版本独立保存的测试二进制，
+逐项 `--exact` 执行，避免不同进程同时操作相同的测试 network namespace：
+
+- `acl_rule_test_inbound`：4 项。
+- `acl_rule_test_subnet_proxy`：4 项。
+- `port_forward_with_inbound_default_drop_acl_test`：3 项。
+- `config_patch_test`：1 项。
+- `proxy_three_node_disconnect_test`：2 项。
+
+三节点矩阵与流量实验在新增测试前完成；新增测试不改变生产代码，随后
+在三平台重新执行完整网关测试。macOS、Windows 的结果不包含原生 TUN
+端到端验证。
+
+## 新增回归测试
+
+测试位于 `easytier-core/src/gateway/proxy/tcp_proxy_engine.rs`：
+
+1. SYN 在 accept 前后重传，均保留转换端口，且不会重复 accept。
+2. 旧连接处于 ClosingSrc、ClosingDst、Closed 时，被同一流的新连接
+   替换；旧连接清理不会删除新映射，反向地址、端口和校验和仍正确。
+3. 过期 SYN 同时释放两个索引，已 accept 的连接不受 SYN 超时清理影响。
+4. 转换端口计数器回绕后跳过零、已占用端口和监听端口。
+5. 实际填满同一源 IP 的 65,534 个转换端口后，新 SYN 被丢弃；其他源
+   IP 仍可建立映射，释放一个条目后该端口可复用，clear 后也可重新分配。
+6. 八个线程同时处理同一流，仅建立一个映射并成功 accept 一次。
+
+端口池测试验证实际容量和恢复行为，没有将 debug 构建的耗时用作生产
+性能阈值，也没有通过延长超时或添加重试改变被测行为。
+
+## 真实流量对照
+
+使用独立的 `flow_val_a`、`flow_val_b` namespace，物理链路为一对 veth。
+虚拟地址为 `10.251.92.1/24` 和 `10.251.92.2/24`；目标端将
+`192.0.2.0/24` 映射到 `198.18.0.0/24`。两个 TCP 服务监听真实地址
+`.10`、`.11` 的 23456 端口，返回服务地址标记，并逐字节回显、校验数据。
+底层隧道使用 UDP，两个节点均使用四线程运行时。
+
+每个版本分别验证普通 TCP、KCP、QUIC 与内核/smoltcp 的六种组合。
+
+| 场景 | 父提交 | 修复版本 |
+| --- | --- | --- |
+| 源 IP/端口相同、两个不同目标的并发连接，各进行 30 轮回显 | 6/6 超时 | 6/6 通过 |
+| 同一四元组 RST 后重连，30 次，间隔 20ms | 6/6 通过 | 6/6 通过 |
+| 普通 TCP、QUIC 的短连接，各 300 次、16 并发 | 各组合 300/300 | 各组合 300/300 |
+| KCP 内核模式短连接，300 次、16 并发 | 4 次超时 | 4 次超时 |
+| KCP smoltcp 模式短连接，300 次、16 并发 | 12 次超时 | 11 次超时 |
+| 关闭客户端写端后等待服务端响应 | 6/6 无响应数据 | 6/6 无响应数据 |
+
+各组合完成流量后等待 15 秒。修复版本两端的代理条目均回收为零，FD
+数量回到接近起始水平（采样期间 RPC 连接带来约一个 FD 的差异）。这只能
+证明本次有限负载下的回收行为，不能证明长期内存占用没有增长。
+
+KCP 的超时阈值为 5 秒，尚未定位这些突发短连接超时的根因；两版都有
+失败不等于已证明每次失败属于同一根因。半关闭实验的服务端在 EOF 后
+返回响应；未修改的 `copy_bidirectional_no_shutdown` 在任一方向结束
+后即退出转发，与两版都丢失该响应的现象一致。本次不修复这两类问题。
+
+## 丢包与混合版本
+
+- 在客户端 veth 出方向施加 `netem delay 10ms 3ms loss 1%`。
+- 两版各六种模式，每个组合保持两个连接持续回显至少 15 秒，所有数据
+  均通过逐字节校验；共 12/12 通过。
+- 无 netem 时，旧源端/新目标端、新源端/旧目标端，各覆盖六种模式。
+  两个连接持续回显至少 2 秒，共 12/12 通过。
+- 混合版本验证使用不同客户端源端口，验证正常互通；它不意味着仍运行
+  旧代理引擎的一端也获得了同源端口冲突修复。
+
+## 证据与限制
+
+本机原始日志、流量脚本、各阶段 JSON、二进制与 SHA-256 清单保存在：
+
+```text
+/data/project/tcp-flow-validation-20260913/
+```
+
+主要记录为 `manifest.json`、`current-matrix-summary.log`、
+`*-extra.json`、`traffic-matrix.json`、`loss-interop.json` 和
+`current-final*gateway.log`。矩阵记录是最终摘要，不是完整逐项日志。
+实验进程、独立 namespace 和 netem 均已清理。
+
+未覆盖 Windows/macOS 原生 TUN 路径、生产防火墙/conntrack 规则兼容性、
+长期运行、吞吐回归基准，以及接近容量极限时的真实内核连接负载。
+端口耗尽已在引擎级验证，但不能替代上述生产容量测试。

docs/tcp-proxy-half-close-validation-2026-09-14.md

@@ -0,0 +1,178 @@
+# TCP 代理半关闭与 KCP 短连接修复验证（2026-09-14）
+
+本次修复上一轮验证发现的半关闭失败、无丢包 KCP 突发连接交接丢失，
+以及跨平台验证暴露的握手前心跳竞态。这些是转发与连接生命周期的局部
+逻辑问题；没有改变 KCP 报文格式，也没有增加重试或放宽业务超时。
+丢包网络下另有握手最终 ACK 丢失的问题，本次未修复，见下文。
+
+## 版本与根因
+
+- EasyTier 基线：`24572b49`；生产修复：`03fa375e`、`fd6e2a3e`。
+- kcp-sys 基线：`d7427c22d764deb1860a7d37acc446ed5033464c`。
+- 最终依赖：`b37ee660fb70bb6d816fb8bbc08b140e55e7218b`，
+  `Cargo.toml` 和 `Cargo.lock` 均锁定此 Git revision。
+  已发布到 kcp-sys 的 `fix/accept-half-close-20260914` 专用分支，
+  便于其他机器获取锁定的依赖；未合并主分支。
+- 旧版真实流量对照：`eb836559`，已包含 flow-key 修复，尚无本次修复。
+- 最终流量二进制：`delivery-easytier-core`，SHA-256：
+  `4635810ac9a536258f9b7ff606e5e1a5eb0243cb0f187825ba6f721d92dfc4fe`。
+  构建内容与最终生产代码一致；构建发生在依赖 pin 提交前，内嵌版本号
+  不用于区分本次产物，以 SHA-256 和依赖 revision 为准。
+
+修复内容：
+
+1. 原转发函数在任一方向 EOF 后退出，取消另一方向，服务端在请求 EOF
+   后返回的响应因此丢失。改用 Tokio 双向拷贝传播写端关闭，继续转发
+   反向数据，直到双向完成或发生错误。
+2. KCP 容量为 4 的 accept 通知队列满时，已建立连接失去交接机会。
+   在连接状态中保留待 accept 标记，队列为空时领取待交接连接；保留
+   原有有界通知队列和串行领取，防止重复交接。
+3. KCP 将正常关闭当作读错误，并可能在 FIN 后丢弃已经确认接收、尚未
+   交给应用的数据。现在先排空接收数据再返回 EOF，RST 和端点销毁仍
+   返回错误；双向关闭清理等待接收任务完成。EOF 判断和过期清理的
+   状态读取顺序也一并修正，避免并发数据到达或心跳更新被旧判断覆盖。
+4. FIN 可以先于 accept 或 connect 返回到达。创建流时继承该关闭状态，
+   使纯空请求、纯空响应也能得到 EOF。半关闭连接继续响应心跳。
+5. Windows 原生测试捕获到 PING 先于 SYN 到达，对端因连接未知返回
+   RST；旧依赖也复现相同时序。周期心跳现在只覆盖已建立和半关闭状态。
+
+## 回归覆盖与自动化结果
+
+| 验证 | 结果 |
+| --- | --- |
+| Linux、macOS arm64、Windows x64 原生网关测试 | 各 200/200 |
+| 最终 kcp-sys 三平台原生测试 | 各 10/10，两个 example target 通过 |
+| 最终完整三节点矩阵及补充集成测试 | 276/276，848.628 秒 |
+| EasyTier 格式检查、Linux 严格 Clippy | 通过 |
+| kcp-sys Linux/macOS 格式检查、严格 Clippy | 通过 |
+
+网关新增两个测试，分别从两端先关闭写方向；使用空请求、32 KiB 请求
+及 64 KiB 响应，接收方等到 EOF 才返回响应。旧转发函数两项均在 5 秒
+超时，修复后通过。原生网关测试不依赖应用层 KCP，心跳修复没有改变
+这些测试的生产代码。
+
+新增三节点半关闭测试覆盖 TCP/KCP/QUIC × 内核/smoltcp 六种模式，
+各检查两个关闭方向、空请求和 64 KiB 请求、128 KiB 响应。完整集成
+集合共 276 项：原有三节点矩阵 256 项、新增 6 项、ACL/配置更新/
+端口转发/断连 14 项，均在已有 `rust` 容器中串行运行。
+
+依赖回归覆盖：32 次握手全部完成后才 accept；200 KiB 缓冲数据后的
+EOF/响应；双向关闭后跨越清理周期再读数据；半关闭心跳；RST/端点销毁
+读错误；FIN 先于 accept、FIN 先于 connect 返回；各握手阶段的心跳
+筛选。通知饱和测试在旧实现第五次 accept 超时；提前 FIN 测试在修复
+前等待 EOF 超时。排空测试使用多工作线程运行时，并做过额外重复验证。
+
+主要命令（Linux 容器内，Rust 1.95）：
+
+```sh
+cargo +1.95 test --locked -p easytier-core \
+  --features proxy-smoltcp-stack --lib gateway::
+cargo +1.95 nextest run --locked -p easytier --features full --lib \
+  -E 'test(subnet_proxy_three_node_test) | test(subnet_proxy_half_close_test) | test(acl_rule_test_inbound) | test(acl_rule_test_subnet_proxy) | test(proxy_three_node_disconnect_test) | test(config_patch_test) | test(port_forward_with_inbound_default_drop_acl_test)' \
+  --test-threads 1 --no-fail-fast
+cargo fmt --all -- --check
+cargo +1.95 clippy --locked -p easytier --features full \
+  --lib --tests -- -D warnings
+```
+
+网关严格 Clippy 另以 `proxy-smoltcp-stack,ring-crypto` 通过；原因见上一轮
+记录中的既有未使用警告说明。Windows 所选 stable 工具链缺少格式检查
+组件，未将 Windows 格式或 Clippy 计为通过。
+
+## 最终二进制真实流量
+
+普通 TCP、KCP、QUIC 与内核/smoltcp 六种组合，底层 UDP；每组合 300 次
+短连接、16 并发、5 秒 socket 超时，检查 greeting 和逐字节回显。
+
+- 六模式主矩阵：1,800/1,800 次短连接通过。
+- 请求 EOF 后返回响应：小/大请求共 12/12，通过；大请求 256 KiB，
+  响应 1 MiB + 4 字节。
+- 服务端先关闭写端，客户端读到 EOF 后再发 256 KiB：6/6，通过，
+  服务端实际校验接收数据。
+- connect 后立即关闭写端，不发送模式字节、不等待 greeting：每模式
+  32 次、16 并发，共 192/192 次纯空请求通过。
+- KCP 每栈额外三轮，与主矩阵合计 2,400/2,400 次短连接通过。追加
+  测试的大小半关闭及 192 次纯空请求通过，6 次反向半关闭中 1 次超时，
+  因此不能将所有追加半关闭计为通过，具体证据见下文。
+- 最终版本在 `delay 10ms 3ms loss 1%` 下，六模式各两个连接持续
+  15 秒逐字节回显、12 次大小半关闭及 6 次反向半关闭通过。KCP 短连接
+  仍有内核模式 5/300、smoltcp 模式 8/300 次 greeting 超时，其他
+  四种模式零失败；没有为每次超时单独抓包证明原因相同。
+- 新旧两方向 × 六模式，共 12 组合正常持续回显通过。旧源端→新目标端
+  1,800 次短连接全通过；新源端→旧目标端 KCP 内核模式 12/300、
+  smoltcp 模式 9/300 次超时，其他四种模式零失败。
+
+旧版同样的无丢包 KCP 2,400 次短连接有 78 次 greeting 超时；旧版六种
+模式在请求 EOF 后均没有响应，且出现过 QUIC 请求数据被截断。
+
+最终版本 KCP 主矩阵后，两种栈源端各 335 条 Closed 代理记录均在
+15 秒观察点清零；目标端记录为零。两端 FD 数保持内核模式 15、smoltcp
+模式 14。RSS 较起始保留约 3.2–4.4 MiB 增长，单次有限负载不能证明
+或排除长期内存泄漏，也不能将代理条目清零等同于所有内部对象回收。
+
+## 仍然存在的丢包握手问题与升级限制
+
+在源端施加 `netem delay 10ms 3ms loss 1%` 后，中间修复版本
+（SHA-256 `2e78ecf…`）KCP 仍有 3/600 次 greeting 超时。额外有界
+TRACE 重跑捕获 3 个连接：源端收到 SYN|ACK，发出空 ACK|DATA 后即
+返回已建立；目标端未收到最终 ACK，直到 5 秒后的 FIN 才返回 RST。
+这与 accept 通知饱和不同，目标端尚未完成握手。
+
+该控制报文可靠性问题需要单独设计握手恢复、重传及过期清理的一致性，
+不能仅延长超时或重试应用请求。本次没有声称消除了所有 KCP 超时。
+具体连接号和双方日志行见 `remaining-loss-handshake.md`、
+`loss-handshake-evidence.log`。
+
+混合版本正常回显通过并不意味着旧端获得修复。旧 KCP 目标端仍保留
+accept 缺陷；KCP 的完整半关闭能力需要两端升级。没有修改报文格式。
+
+追加无 netem 的 KCP/kernel 反向半关闭中，连接 `3969305677` 在等
+服务端数据和 EOF 时超时；服务端没有收到客户端原定在 EOF 后发送的
+256 KiB 数据。发送端同一连接出现 780 次数据输出队列 Full，随后在
+08:36:47.247 UTC 发送缓冲排空，FIN 成功进入输出队列；接收端直到
+5 秒业务超时都未报告对端关闭，08:37:01.030 才报告关闭或重置信号。
+该 debug 日志行也可能由 RST 触发，不能据此认定迟到的是 FIN，更不能
+将数据队列 Full 直接解释为 FIN 被该队列丢弃。现有 FIN 发送路径没有
+确认重传；这一单次失败的具体丢包点尚未证实，保留为未解决的验证异常。
+同场景有界 TRACE 重跑 3 轮，900 次短连接、3 次反向半关闭均通过，
+抓包确认成功轮次收到 FIN 并完成反向数据，未复现原失败；不能以重跑
+通过覆盖原失败。旧依赖与最终依赖的发送排空后入队 FIN 路径相同，
+对照保存在 `fin-send-path-old-new.txt`。
+
+异常轮次的 15 秒资源观察点仍有 1 条 Closed 代理记录，无 Connecting/
+Connected，FD 已回到起始值；因此仅主矩阵可以报告该观察点全部清零。
+定向 TRACE 三轮的 1,005 条 Closed 记录在 15 秒观察点全部清零。
+
+## 验证中的异常与证据
+
+首轮未完成的集成运行中，端口转发 ACL case 3 曾在连接本地监听端口时
+出现一次 ConnectionRefused；随后完整一轮 276 项通过，同项也通过。
+旧版单次及额外十次均通过，因此没有证据把这次失败断言为旧版必现问题，
+也未修改无关的端口转发代码。新增半关闭测试的早期夹具曾只等待路由
+公告而未等待实际 TUN 路由可用，已补足就绪检查，并用有界 try_join
+及时报告连接错误；这不计入生产代码的 red/green 对照。
+
+Windows 测试早期表现为挂起，原因是测试 join 在 connect 失败后仍等待
+accept。限定握手等待后暴露出上述 PING/RST/SYN 竞态，旧依赖和修复前
+分支均有 TRACE 证据；最终原生测试通过。完整 diff 和后续心跳增量均
+经过独立子代理审查，没有 high-confidence 的新缺陷发现。
+
+原始脚本、日志、逐连接 JSON、二进制和哈希保存在本机：
+
+```text
+/data/project/proxy-close-validation-20260914/
+```
+
+主要文件：`delivery-manifest.json`、`delivery-integration.log`、`delivery-clippy.log`、
+`final-core-gateway.log`、`macos-core.log`、`windows-core.log`、
+`mac-kcp-heartbeat-tests.log`、`final-tests.log`（Windows KCP）、
+`delivery-summary.json`、`delivery-kcp-repeat-summary.json`、
+`delivery-*-resources.json`、`traffic-summary.md`、`traffic-binaries.json`、
+`delivery-commands.json`、`artifacts-manifest.json`、`delivery-reverse-timeout.md`、
+`relay-red.log`、`windows-kcp-trace-fail.txt`、
+`windows-kcp-baseline-startup.txt`。Windows 部分原始日志为 UTF-16LE。
+Linux kcp-sys 测试、格式、Clippy 及依赖测试 red/green 对照为子代理
+执行结果，未单独落盘原始命令日志；最终 10 项测试耗时 11.03 秒。
+
+未覆盖 Windows/macOS 原生 TUN 端到端路径、生产规模长时间运行、吞吐
+基准及容量极限负载。流量实验仅使用并清理自己的 namespace 和进程。

easytier-contrib/easytier-android-jni/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "easytier-android-jni"
+version = "0.1.0"
+edition.workspace = true
+rust-version.workspace = true
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+# JNI 0.22 changes native entry points to EnvUnowned and Env.
+jni = "0.21.1"
+once_cell.workspace = true
+log.workspace = true
+android_logger = "0.15"
+serde_json.workspace = true
+easytier = { workspace = true, default-features = true }
+easytier-ffi.workspace = true

easytier-contrib/easytier-android-jni/README.md

@@ -0,0 +1,282 @@
+# EasyTier Android JNI
+
+这是 EasyTier 的 Android JNI 绑定库，允许 Android 应用程序调用 EasyTier 的网络功能。
+
+## 功能特性
+
+- 🚀 完整的 EasyTier FFI 接口封装
+- 📱 原生 Android JNI 支持
+- 🔧 支持多种 Android 架构 (arm64-v8a, armeabi-v7a, x86, x86_64)
+- 🛡️ 类型安全的 Java 接口
+- 🔌 支持通过 JSON 调用已暴露的 EasyTier RPC 查询/管理接口
+- 📝 详细的错误处理和日志记录
+
+## 支持的架构
+
+- `arm64-v8a` (aarch64-linux-android)
+- `armeabi-v7a` (armv7-linux-androideabi)
+- `x86` (i686-linux-android)
+- `x86_64` (x86_64-linux-android)
+
+## 构建要求
+
+### 系统要求
+
+- Rust 1.70+
+- Android NDK r21+
+- Linux/macOS 开发环境
+
+### 环境设置
+
+1. **安装 Rust**
+   ```bash
+   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+   source ~/.cargo/env
+   ```
+
+2. **安装 Android NDK**
+   - 下载 Android NDK: https://developer.android.com/ndk/downloads
+   - 解压到合适的目录
+   - 设置环境变量:
+     ```bash
+     export ANDROID_NDK_ROOT=/path/to/android-ndk
+     ```
+
+3. **添加 Android 目标**
+   ```bash
+   rustup target add aarch64-linux-android
+   rustup target add armv7-linux-androideabi
+   rustup target add i686-linux-android
+   rustup target add x86_64-linux-android
+   ```
+
+## 构建步骤
+
+1. **克隆项目并进入目录**
+   ```bash
+   cd /path/to/EasyTier/easytier-contrib/easytier-android-jni
+   ```
+
+2. **运行构建脚本**
+   ```bash
+   ./build.sh
+   ```
+
+3. **构建完成后，库文件将生成在 `target/android/` 目录下**
+   ```
+   target/android/
+   ├── arm64-v8a/
+   │   └── libeasytier_android_jni.so
+   ├── armeabi-v7a/
+   │   └── libeasytier_android_jni.so
+   ├── x86/
+   │   └── libeasytier_android_jni.so
+   └── x86_64/
+       └── libeasytier_android_jni.so
+   ```
+
+## Android 项目集成
+
+### 1. 复制库文件
+
+将生成的 `.so` 文件复制到您的 Android 项目中：
+
+```
+your-android-project/
+└── src/main/
+    ├── jniLibs/
+    │   ├── arm64-v8a/
+    │   │   └── libeasytier_android_jni.so
+    │   ├── armeabi-v7a/
+    │   │   └── libeasytier_android_jni.so
+    │   ├── x86/
+    │   │   └── libeasytier_android_jni.so
+    │   └── x86_64/
+    │       └── libeasytier_android_jni.so
+    └── java/
+        └── com/easytier/jni/
+            └── EasyTierJNI.java
+```
+
+### 2. 复制 Java 接口
+
+将 `java/com/easytier/jni/EasyTierJNI.java` 复制到您的 Android 项目的相应包路径下。
+
+### 3. 添加权限
+
+在 `AndroidManifest.xml` 中添加必要的权限：
+
+```xml
+<uses-permission android:name="android.permission.INTERNET" />
+<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
+```
+
+## 使用示例
+
+### 基本使用
+
+```java
+import com.easytier.jni.EasyTierJNI;
+import java.util.Map;
+
+public class EasyTierManager {
+    
+    // 初始化网络实例
+    public void startNetwork() {
+        String config = """
+            inst_name = "my_instance"
+            network = "my_network"
+            """; 
+        
+        try {
+            // 解析配置
+            int result = EasyTierJNI.parseConfig(config);
+            if (result != 0) {
+                String error = EasyTierJNI.getLastError();
+                throw new RuntimeException("配置解析失败: " + error);
+            }
+            
+            // 启动网络实例
+            result = EasyTierJNI.runNetworkInstance(config);
+            if (result != 0) {
+                String error = EasyTierJNI.getLastError();
+                throw new RuntimeException("网络实例启动失败: " + error);
+            }
+            
+            System.out.println("EasyTier 网络实例启动成功");
+            
+        } catch (RuntimeException e) {
+            System.err.println("启动失败: " + e.getMessage());
+        }
+    }
+    
+    // 获取网络信息
+    public void getNetworkInfo() {
+        try {
+            Map<String, String> infos = EasyTierJNI.collectNetworkInfosAsMap(10);
+            for (Map.Entry<String, String> entry : infos.entrySet()) {
+                System.out.println(entry.getKey() + ": " + entry.getValue());
+            }
+        } catch (RuntimeException e) {
+            System.err.println("获取网络信息失败: " + e.getMessage());
+        }
+    }
+    
+    // 停止所有实例
+    public void stopNetwork() {
+        try {
+            int result = EasyTierJNI.stopAllInstances();
+            if (result == 0) {
+                System.out.println("所有网络实例已停止");
+            }
+        } catch (RuntimeException e) {
+            System.err.println("停止网络失败: " + e.getMessage());
+        }
+    }
+}
+```
+
+### 通用 JSON RPC
+
+`EasyTierJNI.callJsonRpc(serviceName, methodName, domainName, payloadJson)` 可以调用已暴露的
+EasyTier RPC 服务，payload 和返回值均为 protobuf JSON。该接口不支持
+`api.manage.WebClientService`；实例启动、保留、删除、信息收集仍使用专用 JNI API。
+
+```java
+String response = EasyTierJNI.callJsonRpc(
+    "api.logger.LoggerRpcService",
+    "get_logger_config",
+    "{}"
+);
+```
+
+### VPN 服务集成
+
+如果您要在 Android VPN 服务中使用：
+
+```java
+public class EasyTierVpnService extends VpnService {
+    
+    @Override
+    public int onStartCommand(Intent intent, int flags, int startId) {
+        // 建立 VPN 连接
+        ParcelFileDescriptor vpnInterface = establishVpnInterface();
+        
+        if (vpnInterface != null) {
+            int fd = vpnInterface.getFd();
+            
+            // 设置 TUN 文件描述符
+            try {
+                EasyTierJNI.setTunFd("my_instance", fd);
+            } catch (RuntimeException e) {
+                Log.e("EasyTier", "设置 TUN FD 失败", e);
+            }
+        }
+        
+        return START_STICKY;
+    }
+    
+    private ParcelFileDescriptor establishVpnInterface() {
+        Builder builder = new Builder();
+        builder.setMtu(1500);
+        builder.addAddress("10.0.0.2", 24);
+        builder.addRoute("0.0.0.0", 0);
+        builder.setSession("EasyTier VPN");
+        
+        return builder.establish();
+    }
+}
+```
+
+## API 参考
+
+### EasyTierJNI 类方法
+
+| 方法 | 描述 | 参数 | 返回值 |
+|------|------|------|--------|
+| `parseConfig(String config)` | 解析 TOML 配置 | config: 配置字符串 | 0=成功, -1=失败 |
+| `runNetworkInstance(String config)` | 启动网络实例 | config: 配置字符串 | 0=成功, -1=失败 |
+| `setTunFd(String instanceName, int fd)` | 设置 TUN 文件描述符 | instanceName: 实例名, fd: 文件描述符 | 0=成功, -1=失败 |
+| `retainNetworkInstance(String[] names)` | 保留指定实例 | names: 实例名数组 | 0=成功, -1=失败 |
+| `collectNetworkInfos(int maxLength)` | 收集网络信息 | maxLength: 最大条目数 | 信息字符串数组 |
+| `collectNetworkInfosAsMap(int maxLength)` | 收集网络信息为 Map | maxLength: 最大条目数 | Map<String, String> |
+| `getLastError()` | 获取最后错误 | 无 | 错误消息字符串 |
+| `stopAllInstances()` | 停止所有实例 | 无 | 0=成功, -1=失败 |
+| `retainSingleInstance(String name)` | 保留单个实例 | name: 实例名 | 0=成功, -1=失败 |
+
+## 故障排除
+
+### 常见问题
+
+1. **构建失败: "Android NDK not found"**
+   - 确保设置了 `ANDROID_NDK_ROOT` 环境变量
+   - 检查 NDK 路径是否正确
+
+2. **运行时错误: "java.lang.UnsatisfiedLinkError"**
+   - 确保 `.so` 文件放在正确的 `jniLibs` 目录下
+   - 检查目标架构是否匹配
+
+3. **配置解析失败**
+   - 检查 TOML 配置格式是否正确
+   - 使用 `getLastError()` 获取详细错误信息
+
+### 调试技巧
+
+- 启用 Android 日志查看 JNI 层的日志输出
+- 使用 `adb logcat -s EasyTier-JNI` 查看相关日志
+- 检查 `getLastError()` 返回的错误信息
+
+## 许可证
+
+本项目遵循与 EasyTier 主项目相同的许可证。
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request 来改进这个项目。
+
+## 相关链接
+
+- [EasyTier 主项目](https://github.com/EasyTier/EasyTier)
+- [Android NDK 文档](https://developer.android.com/ndk)
+- [Rust JNI 文档](https://docs.rs/jni/)

easytier-contrib/easytier-android-jni/build.rs

@@ -0,0 +1,17 @@
+use std::{env, path::PathBuf};
+
+fn main() {
+    let target_os = env::var("CARGO_CFG_TARGET_OS").unwrap_or_default();
+    if !matches!(target_os.as_str(), "android" | "linux") {
+        return;
+    }
+
+    let manifest_dir = PathBuf::from(env::var("CARGO_MANIFEST_DIR").unwrap());
+    let exports = manifest_dir.join("exports.map");
+    println!("cargo:rerun-if-changed={}", exports.display());
+    println!(
+        "cargo:rustc-cdylib-link-arg=-Wl,--version-script={}",
+        exports.display()
+    );
+    println!("cargo:rustc-cdylib-link-arg=-Wl,--exclude-libs,ALL");
+}

easytier-contrib/easytier-android-jni/build.sh

@@ -0,0 +1,129 @@
+#!/bin/bash
+
+# EasyTier Android JNI 构建脚本
+# 用于编译适用于 Android 平台的 JNI 库
+# 使用 cargo-ndk 工具简化 Android 编译过程
+
+set -e
+
+# 颜色输出
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+REPO_ROOT=$(git rev-parse --show-toplevel)
+
+echo -e "${GREEN}EasyTier Android JNI 构建脚本 (使用 cargo-ndk)${NC}"
+echo "=============================================="
+
+# 检查 Rust 是否安装
+if ! command -v rustc &> /dev/null; then
+    echo -e "${RED}错误: 未找到 Rust 编译器，请先安装 Rust${NC}"
+    exit 1
+fi
+
+# 检查 cargo 是否安装
+if ! command -v cargo &> /dev/null; then
+    echo -e "${RED}错误: 未找到 Cargo，请先安装 Rust 工具链${NC}"
+    exit 1
+fi
+
+# 检查 cargo-ndk 是否安装
+if ! cargo ndk --version &> /dev/null; then
+    echo -e "${YELLOW}cargo-ndk 未安装，正在安装...${NC}"
+    cargo install cargo-ndk
+    if ! cargo ndk --version &> /dev/null; then
+        echo -e "${RED}错误: cargo-ndk 安装失败${NC}"
+        exit 1
+    fi
+fi
+
+echo -e "${GREEN}cargo-ndk 版本: $(cargo ndk --version)${NC}"
+
+# Android 目标架构映射 (cargo-ndk 使用的架构名称)
+# ANDROID_TARGETS=("arm64-v8a" "armeabi-v7a" "x86" "x86_64")
+ANDROID_TARGETS=("arm64-v8a")
+
+# Android 架构到 Rust target 的映射
+declare -A TARGET_MAP
+TARGET_MAP["arm64-v8a"]="aarch64-linux-android"
+TARGET_MAP["armeabi-v7a"]="armv7-linux-androideabi"
+TARGET_MAP["x86"]="i686-linux-android"
+TARGET_MAP["x86_64"]="x86_64-linux-android"
+
+# 检查并安装所需的 Rust target
+echo -e "${YELLOW}检查并安装 Android 目标架构...${NC}"
+for android_target in "${ANDROID_TARGETS[@]}"; do
+    rust_target="${TARGET_MAP[$android_target]}"
+    if ! rustup target list --installed | grep -q "$rust_target"; then
+        echo -e "${YELLOW}安装目标架构: $rust_target (for $android_target)${NC}"
+        rustup target add "$rust_target"
+    else
+        echo -e "${GREEN}目标架构已安装: $rust_target (for $android_target)${NC}"
+    fi
+done
+
+# 创建输出目录
+OUTPUT_DIR="./target/android"
+mkdir -p "$OUTPUT_DIR"
+
+# 构建函数
+build_for_target() {
+    local android_target=$1
+    echo -e "${YELLOW}构建目标: $android_target${NC}"
+    
+    # 首先构建 easytier-ffi
+    echo -e "${YELLOW}构建 easytier-ffi for $android_target${NC}"
+    (cd $REPO_ROOT/easytier-contrib/easytier-ffi && cargo ndk -t $android_target build --release)
+    
+    # 构建 JNI 库
+    cargo ndk -t $android_target build --release
+    
+    # 复制库文件到输出目录
+    # cargo-ndk 使用 Rust target 名称作为目录名，而不是 Android 架构名称
+    rust_target="${TARGET_MAP[$android_target]}"
+    mkdir -p "$OUTPUT_DIR/$android_target"
+    cp "$REPO_ROOT/target/$rust_target/release/libeasytier_android_jni.so" "$OUTPUT_DIR/$android_target/"
+    cp "$REPO_ROOT/target/$rust_target/release/libeasytier_ffi.so" "$OUTPUT_DIR/$android_target/"
+    echo -e "${GREEN}库文件已复制到: $OUTPUT_DIR/$android_target/${NC}"
+}
+
+# 检查 Android NDK (cargo-ndk 会自动处理 NDK 路径)
+if [ -z "$ANDROID_NDK_ROOT" ] && [ -z "$ANDROID_NDK_HOME" ] && [ -z "$NDK_HOME" ]; then
+    echo -e "${YELLOW}警告: 未设置 Android NDK 环境变量${NC}"
+    echo "cargo-ndk 将尝试自动检测 NDK 路径"
+    echo "如果构建失败，请设置以下环境变量之一:"
+    echo "  - ANDROID_NDK_ROOT"
+    echo "  - ANDROID_NDK_HOME" 
+    echo "  - NDK_HOME"
+else
+    if [ -n "$ANDROID_NDK_ROOT" ]; then
+        echo -e "${GREEN}使用 Android NDK: $ANDROID_NDK_ROOT${NC}"
+    elif [ -n "$ANDROID_NDK_HOME" ]; then
+        echo -e "${GREEN}使用 Android NDK: $ANDROID_NDK_HOME${NC}"
+    elif [ -n "$NDK_HOME" ]; then
+        echo -e "${GREEN}使用 Android NDK: $NDK_HOME${NC}"
+    fi
+fi
+
+# 构建所有目标
+echo -e "${YELLOW}开始构建所有目标架构...${NC}"
+for target in "${ANDROID_TARGETS[@]}"; do
+    build_for_target "$target"
+done
+
+echo -e "${GREEN}构建完成！${NC}"
+echo -e "${GREEN}所有库文件已生成到: $OUTPUT_DIR${NC}"
+echo ""
+echo "目录结构:"
+ls -la "$OUTPUT_DIR"/*/
+
+echo ""
+echo -e "${YELLOW}使用说明:${NC}"
+echo "1. 将生成的 .so 文件复制到您的 Android 项目的 src/main/jniLibs/ 目录下"
+echo "2. 将 java/com/easytier/jni/EasyTierJNI.java 复制到您的 Android 项目中"
+echo "3. 在您的 Android 代码中调用 EasyTierJNI 类的方法"
+echo ""
+echo -e "${GREEN}注意: 此脚本使用 cargo-ndk 工具，无需手动设置复杂的环境变量${NC}"
+echo -e "${GREEN}cargo-ndk 会自动处理交叉编译所需的工具链配置${NC}"

easytier-contrib/easytier-android-jni/example_config.toml

@@ -0,0 +1,56 @@
+# EasyTier Android JNI 示例配置文件
+# 这是一个基本的配置示例，展示如何配置 EasyTier 网络实例
+
+# 实例名称 (必需)
+inst_name = "android_instance"
+
+# 网络名称 (必需)
+network = "my_easytier_network"
+
+# 网络密钥 (可选，用于网络加密)
+# network_secret = "your_secret_key_here"
+
+# 监听地址 (可选)
+# listeners = ["tcp://0.0.0.0:11010", "udp://0.0.0.0:11010"]
+
+# 对等节点地址 (可选)
+# peers = ["tcp://peer1.example.com:11010", "udp://peer2.example.com:11010"]
+
+# 虚拟 IP 地址 (可选)
+# ipv4 = "10.144.144.1"
+
+# 主机名 (可选)
+# hostname = "android-device"
+
+# 启用 IPv6 (可选)
+# ipv6 = "fd00::1"
+
+# 代理网络 (可选)
+# proxy_networks = ["192.168.1.0/24"]
+
+# 退出节点 (可选)
+# exit_nodes = ["peer1"]
+
+# 启用加密 (可选)
+# enable_encryption = true
+
+# 启用 IPv4 转发 (可选)
+# enable_ipv4 = true
+
+# 启用 IPv6 转发 (可选)
+# enable_ipv6 = false
+
+# MTU 设置 (可选)
+# mtu = 1420
+
+# 日志级别 (可选: error, warn, info, debug, trace)
+# log_level = "info"
+
+# 禁用 P2P (可选)
+# disable_p2p = false
+
+# 使用多路径 (可选)
+# use_multi_path = true
+
+# 延迟优先 (可选)
+# latency_first = false

easytier-contrib/easytier-android-jni/exports.map

@@ -0,0 +1,6 @@
+{
+    global:
+        Java_com_easytier_jni_EasyTierJNI_*;
+    local:
+        *;
+};

easytier-contrib/easytier-android-jni/kotlin/com/easytier/jni/EasyTierJNI.kt

@@ -0,0 +1,155 @@
+package com.easytier.jni
+
+fun interface ConfigServerEventCallback {
+    fun onEvent(eventJson: String)
+}
+
+/** EasyTier JNI 接口类 提供 Android 应用调用 EasyTier 核心网络功能的接口 */
+object EasyTierJNI {
+    init {
+        // 加载本地库
+        System.loadLibrary("easytier_android_jni")
+    }
+
+    /**
+     * 设置 TUN 文件描述符
+     * @param instanceName 实例名称
+     * @param fd TUN 文件描述符
+     * @return 0 表示成功，-1 表示失败
+     * @throws RuntimeException 当操作失败时抛出异常
+     */
+    @JvmStatic external fun setTunFd(instanceName: String, fd: Int): Int
+
+    /**
+     * 解析配置字符串
+     * @param config TOML 格式的配置字符串
+     * @return 0 表示成功，-1 表示失败
+     * @throws RuntimeException 当配置解析失败时抛出异常
+     */
+    @JvmStatic external fun parseConfig(config: String): Int
+
+    /**
+     * 运行网络实例
+     * @param config TOML 格式的配置字符串
+     * @return 0 表示成功，-1 表示失败
+     * @throws RuntimeException 当实例启动失败时抛出异常
+     */
+    @JvmStatic external fun runNetworkInstance(config: String): Int
+
+    /**
+     * 启动配置服务器客户端
+     * @param url 配置服务器 URL
+     * @param hostname 主机名，传入 null 使用系统主机名
+     * @param machineId 稳定机器 ID，由调用方负责持久化
+     * @param secureMode 是否启用 secure mode
+     * @param callback 远程配置应用/删除事件回调
+     * @return 0 表示成功，-1 表示失败
+     * @throws RuntimeException 当客户端启动失败时抛出异常
+     */
+    @JvmStatic
+    external fun startConfigServerClient(
+            url: String,
+            hostname: String?,
+            machineId: String,
+            secureMode: Boolean,
+            callback: ConfigServerEventCallback?
+    ): Int
+
+    /**
+     * 停止配置服务器客户端
+     * @return 0 表示成功，-1 表示失败
+     * @throws RuntimeException 当客户端停止失败时抛出异常
+     */
+    @JvmStatic external fun stopConfigServerClient(): Int
+
+    /** 查询配置服务器客户端是否已连接 */
+    @JvmStatic external fun isConfigServerClientConnected(): Boolean
+
+    /**
+     * 保留指定的网络实例，停止其他实例
+     * @param instanceNames 要保留的实例名称数组，传入 null 或空数组将停止所有实例
+     * @return 0 表示成功，-1 表示失败
+     * @throws RuntimeException 当操作失败时抛出异常
+     */
+    @JvmStatic external fun retainNetworkInstance(instanceNames: Array<String>?): Int
+
+    /**
+     * 停止指定的网络实例，其他实例不受影响
+     * @param instanceName 要停止的实例名称，不存在时为 no-op
+     * @return 0 表示成功，-1 表示失败
+     * @throws RuntimeException 当操作失败时抛出异常
+     */
+    @JvmStatic external fun deleteNetworkInstance(instanceName: String): Int
+
+    /**
+     * 收集网络信息
+     * @param maxLength 最大返回条目数
+     * @return 包含网络信息的 JSON 字符串
+     * @throws RuntimeException 当操作失败时抛出异常
+     */
+    @JvmStatic external fun collectNetworkInfos(maxLength: Int): String?
+
+    /**
+     * 列出当前运行的实例名称和实例 ID。
+     * @param maxLength 最大返回条目数
+     * @return JSON 对象，key 为 instance name，value 为 instance id
+     * @throws RuntimeException 当操作失败时抛出异常
+     */
+    @JvmStatic external fun listInstances(maxLength: Int): String?
+
+    /**
+     * 调用暴露的 EasyTier RPC 方法，输入和输出均为 protobuf JSON 字符串。
+     *
+     * 不支持 api.manage.WebClientService；实例启动、保留、删除、信息收集请继续使用专用 JNI API。
+     * payloadJson 需要包含目标 RPC 所需的 instance selector。
+     *
+     * @param serviceName RPC 服务名，例如 api.instance.PeerManageRpcService
+     * @param methodName RPC 方法名，支持 snake_case 或 proto 方法名
+     * @param domainName 仅 TcpProxyRpcService 使用；传 null 或空字符串默认 tcp
+     * @param payloadJson protobuf JSON 请求体
+     * @return protobuf JSON 响应体
+     * @throws RuntimeException 当 RPC 调用失败时抛出异常
+     */
+    @JvmStatic
+    external fun callJsonRpc(
+            serviceName: String,
+            methodName: String,
+            domainName: String?,
+            payloadJson: String
+    ): String?
+
+    /**
+     * 调用不需要 domainName 的 EasyTier RPC 方法。
+     */
+    @JvmStatic
+    fun callJsonRpc(serviceName: String, methodName: String, payloadJson: String): String? {
+        return callJsonRpc(serviceName, methodName, null, payloadJson)
+    }
+
+    /**
+     * 获取最后的错误消息
+     * @return 错误消息字符串，如果没有错误则返回 null
+     */
+    @JvmStatic external fun getLastError(): String?
+
+    /**
+     * 便利方法：停止所有网络实例
+     * @return 0 表示成功，-1 表示失败
+     * @throws RuntimeException 当操作失败时抛出异常
+     */
+    @JvmStatic
+    fun stopAllInstances(): Int {
+        return retainNetworkInstance(null)
+    }
+
+    /**
+     * 便利方法：停止指定实例外的所有实例
+     * @param instanceName 要保留的实例名称
+     * @return 0 表示成功，-1 表示失败
+     * @throws RuntimeException 当操作失败时抛出异常
+     */
+    @JvmStatic
+    fun retainSingleInstance(instanceName: String): Int {
+        return retainNetworkInstance(arrayOf(instanceName))
+    }
+}

easytier-contrib/easytier-android-jni/kotlin/com/easytier/jni/EasyTierManager.kt

@@ -0,0 +1,252 @@
+package com.easytier.jni
+
+import android.app.Activity
+import android.content.Intent
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import com.squareup.moshi.Moshi
+import com.squareup.wire.WireJsonAdapterFactory
+import common.Ipv4Inet
+import web.NetworkInstanceRunningInfoMap
+
+fun parseIpv4InetToString(inet: Ipv4Inet?): String? {
+    val addr = inet?.address?.addr ?: return null
+    val networkLength = inet.network_length
+
+    // 将 int32 转换为 IPv4 字符串
+    val ip =
+            String.format(
+                    "%d.%d.%d.%d",
+                    (addr shr 24) and 0xFF,
+                    (addr shr 16) and 0xFF,
+                    (addr shr 8) and 0xFF,
+                    addr and 0xFF
+            )
+
+    return "$ip/$networkLength"
+}
+
+/** EasyTier 管理类 负责管理 EasyTier 实例的生命周期、监控网络状态变化、控制 VpnService */
+class EasyTierManager(
+        private val activity: Activity,
+        private val instanceName: String,
+        private val networkConfig: String
+) {
+    companion object {
+        private const val TAG = "EasyTierManager"
+        private const val MONITOR_INTERVAL = 3000L // 3秒监控间隔
+    }
+
+    private val handler = Handler(Looper.getMainLooper())
+    private var isRunning = false
+    private var currentIpv4: String? = null
+    private var currentProxyCidrs: List<String> = emptyList()
+    private var vpnServiceIntent: Intent? = null
+
+    // JSON 解析器
+    private val moshi = Moshi.Builder().add(WireJsonAdapterFactory()).build()
+    private val adapter = moshi.adapter(NetworkInstanceRunningInfoMap::class.java)
+
+    // 监控任务
+    private val monitorRunnable =
+            object : Runnable {
+                override fun run() {
+                    if (isRunning) {
+                        monitorNetworkStatus()
+                        handler.postDelayed(this, MONITOR_INTERVAL)
+                    }
+                }
+            }
+
+    /** 启动 EasyTier 实例和监控 */
+    fun start() {
+        if (isRunning) {
+            Log.w(TAG, "EasyTier 实例已经在运行中")
+            return
+        }
+
+        try {
+            // 启动 EasyTier 实例
+            val result = EasyTierJNI.runNetworkInstance(networkConfig)
+            if (result == 0) {
+                isRunning = true
+                Log.i(TAG, "EasyTier 实例启动成功: $instanceName")
+
+                // 开始监控网络状态
+                handler.post(monitorRunnable)
+            } else {
+                Log.e(TAG, "EasyTier 实例启动失败: $result")
+                val error = EasyTierJNI.getLastError()
+                Log.e(TAG, "错误信息: $error")
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "启动 EasyTier 实例时发生异常", e)
+        }
+    }
+
+    /** 停止 EasyTier 实例和监控 */
+    fun stop() {
+        if (!isRunning) {
+            Log.w(TAG, "EasyTier 实例未在运行")
+            return
+        }
+
+        isRunning = false
+
+        // 停止监控任务
+        handler.removeCallbacks(monitorRunnable)
+
+        try {
+            // 停止 VpnService
+            stopVpnService()
+
+            // 停止 EasyTier 实例
+            EasyTierJNI.stopAllInstances()
+            Log.i(TAG, "EasyTier 实例已停止: $instanceName")
+
+            // 重置状态
+            currentIpv4 = null
+            currentProxyCidrs = emptyList()
+        } catch (e: Exception) {
+            Log.e(TAG, "停止 EasyTier 实例时发生异常", e)
+        }
+    }
+
+    /** 监控网络状态 */
+    private fun monitorNetworkStatus() {
+        try {
+            val infosJson = EasyTierJNI.collectNetworkInfos(10)
+            if (infosJson.isNullOrEmpty()) {
+                Log.d(TAG, "未获取到网络信息")
+                return
+            }
+
+            val networkInfoMap = parseNetworkInfo(infosJson)
+            val networkInfo = networkInfoMap?.map?.get(instanceName)
+
+            if (networkInfo == null) {
+                Log.d(TAG, "未找到实例 $instanceName 的网络信息")
+                return
+            }
+
+            Log.d(TAG, "网络信息: $networkInfo")
+
+            // 检查实例是否正在运行
+            if (!networkInfo.running) {
+                Log.w(TAG, "EasyTier 实例未运行: ${networkInfo.error_msg}")
+                return
+            }
+
+            val newIpv4Inet = networkInfo.my_node_info?.virtual_ipv4
+
+            if (newIpv4Inet == null) {
+                Log.w(TAG, "EasyTier No Ipv4: $networkInfo")
+                return
+            }
+
+            // 获取当前节点的 IPv4 地址
+            val newIpv4 = parseIpv4InetToString(newIpv4Inet)
+
+            // 获取所有节点的 proxy_cidrs
+            val newProxyCidrs = mutableListOf<String>()
+            networkInfo.routes?.forEach { route ->
+                route.proxy_cidrs?.let { cidrs -> newProxyCidrs.addAll(cidrs) }
+            }
+
+            // 检查是否有变化
+            val ipv4Changed = newIpv4 != currentIpv4
+            val proxyCidrsChanged = newProxyCidrs != currentProxyCidrs
+
+            if (ipv4Changed || proxyCidrsChanged) {
+                Log.i(TAG, "网络状态发生变化:")
+                Log.i(TAG, "  IPv4: $currentIpv4 -> $newIpv4")
+                Log.i(TAG, "  Proxy CIDRs: $currentProxyCidrs -> $newProxyCidrs")
+
+                // 更新状态
+                currentIpv4 = newIpv4
+                currentProxyCidrs = newProxyCidrs.toList()
+
+                // 重启 VpnService
+                if (newIpv4 != null) {
+                    restartVpnService(newIpv4, newProxyCidrs)
+                }
+            } else {
+                Log.d(TAG, "网络状态无变化 - IPv4: $currentIpv4, Proxy CIDRs: ${currentProxyCidrs.size} 个")
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "监控网络状态时发生异常", e)
+        }
+    }
+
+    /** 解析网络信息 JSON */
+    private fun parseNetworkInfo(jsonString: String): NetworkInstanceRunningInfoMap? {
+        return try {
+            adapter.fromJson(jsonString)
+        } catch (e: Exception) {
+            Log.e(TAG, "解析网络信息失败", e)
+            null
+        }
+    }
+
+    /** 重启 VpnService */
+    private fun restartVpnService(ipv4: String, proxyCidrs: List<String>) {
+        try {
+            // 先停止现有的 VpnService
+            stopVpnService()
+
+            // 启动新的 VpnService
+            startVpnService(ipv4, proxyCidrs)
+        } catch (e: Exception) {
+            Log.e(TAG, "重启 VpnService 时发生异常", e)
+        }
+    }
+
+    /** 启动 VpnService */
+    private fun startVpnService(ipv4: String, proxyCidrs: List<String>) {
+        try {
+            val intent = Intent(activity, EasyTierVpnService::class.java)
+            intent.putExtra("ipv4_address", ipv4)
+            intent.putStringArrayListExtra("proxy_cidrs", ArrayList(proxyCidrs))
+            intent.putExtra("instance_name", instanceName)
+
+            activity.startService(intent)
+            vpnServiceIntent = intent
+
+            Log.i(TAG, "VpnService 已启动 - IPv4: $ipv4, Proxy CIDRs: $proxyCidrs")
+        } catch (e: Exception) {
+            Log.e(TAG, "启动 VpnService 时发生异常", e)
+        }
+    }
+
+    /** 停止 VpnService */
+    private fun stopVpnService() {
+        try {
+            vpnServiceIntent?.let { intent ->
+                activity.stopService(intent)
+                Log.i(TAG, "VpnService 已停止")
+            }
+            vpnServiceIntent = null
+        } catch (e: Exception) {
+            Log.e(TAG, "停止 VpnService 时发生异常", e)
+        }
+    }
+
+    /** 获取当前状态信息 */
+    fun getStatus(): EasyTierStatus {
+        return EasyTierStatus(
+                isRunning = isRunning,
+                instanceName = instanceName,
+                currentIpv4 = currentIpv4,
+                currentProxyCidrs = currentProxyCidrs.toList()
+        )
+    }
+
+    /** 状态数据类 */
+    data class EasyTierStatus(
+            val isRunning: Boolean,
+            val instanceName: String,
+            val currentIpv4: String?,
+            val currentProxyCidrs: List<String>
+    )
+}

easytier-contrib/easytier-android-jni/kotlin/com/easytier/jni/EasyTierVpnService.t.kt

@@ -0,0 +1,143 @@
+package com.easytier.jni
+
+import android.content.Intent
+import android.net.VpnService
+import android.os.ParcelFileDescriptor
+import android.util.Log
+import kotlin.concurrent.thread
+
+class EasyTierVpnService : VpnService() {
+
+    private var vpnInterface: ParcelFileDescriptor? = null
+    private var isRunning = false
+    private var instanceName: String? = null
+
+    companion object {
+        private const val TAG = "EasyTierVpnService"
+    }
+
+    override fun onCreate() {
+        super.onCreate()
+        Log.d(TAG, "VPN Service created")
+    }
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        // 获取传入的参数
+        val ipv4Address = intent?.getStringExtra("ipv4_address")
+        val proxyCidrs = intent?.getStringArrayListExtra("proxy_cidrs") ?: arrayListOf()
+        instanceName = intent?.getStringExtra("instance_name")
+
+        if (ipv4Address == null || instanceName == null) {
+            Log.e(TAG, "缺少必要参数: ipv4Address=$ipv4Address, instanceName=$instanceName")
+            stopSelf()
+            return START_NOT_STICKY
+        }
+
+        Log.i(
+                TAG,
+                "启动 VPN Service - IPv4: $ipv4Address, Proxy CIDRs: $proxyCidrs, Instance: $instanceName"
+        )
+
+        thread {
+            try {
+                setupVpnInterface(ipv4Address, proxyCidrs)
+            } catch (t: Throwable) {
+                Log.e(TAG, "VPN 设置失败", t)
+                stopSelf()
+            }
+        }
+
+        return START_STICKY
+    }
+
+    private fun setupVpnInterface(ipv4Address: String, proxyCidrs: List<String>) {
+        try {
+            // 解析 IPv4 地址和网络长度
+            val (ip, networkLength) = parseIpv4Address(ipv4Address)
+
+            // 1. 准备 VpnService.Builder
+            val builder = Builder()
+            builder.setSession("EasyTier VPN")
+                    .addAddress(ip, networkLength)
+                    .addDnsServer("223.5.5.5")
+                    .addDnsServer("114.114.114.114")
+                    .addDisallowedApplication("com.easytier.easytiervpn")
+
+            // 2. 添加路由表 - 为每个 proxy CIDR 添加路由
+            proxyCidrs.forEach { cidr ->
+                try {
+                    val (routeIp, routeLength) = parseCidr(cidr)
+                    builder.addRoute(routeIp, routeLength)
+                    Log.d(TAG, "添加路由: $routeIp/$routeLength")
+                } catch (e: Exception) {
+                    Log.w(TAG, "解析 CIDR 失败: $cidr", e)
+                }
+            }
+
+            // 3. 构建虚拟网络接口
+            vpnInterface = builder.establish()
+
+            if (vpnInterface == null) {
+                Log.e(TAG, "创建 VPN 接口失败")
+                return
+            }
+
+            Log.i(TAG, "VPN 接口创建成功")
+
+            // 4. 将 TUN 文件描述符传递给 EasyTier
+            instanceName?.let { name ->
+                val fd = vpnInterface!!.fd
+                val result = EasyTierJNI.setTunFd(name, fd)
+                if (result == 0) {
+                    Log.i(TAG, "TUN 文件描述符设置成功: $fd")
+                } else {
+                    Log.e(TAG, "TUN 文件描述符设置失败: $result")
+                }
+            }
+
+            isRunning = true
+
+            // 5. 保持服务运行
+            while (isRunning && vpnInterface != null) {
+                Thread.sleep(1000)
+            }
+        } catch (t: Throwable) {
+            Log.e(TAG, "VPN 接口设置过程中发生错误", t)
+        } finally {
+            cleanup()
+        }
+    }
+
+    /** 解析 IPv4 地址，返回 IP 和网络长度 */
+    private fun parseIpv4Address(ipv4Address: String): Pair<String, Int> {
+        return if (ipv4Address.contains("/")) {
+            val parts = ipv4Address.split("/")
+            Pair(parts[0], parts[1].toInt())
+        } else {
+            // 默认使用 /24 网络
+            Pair(ipv4Address, 24)
+        }
+    }
+
+    /** 解析 CIDR，返回 IP 和网络长度 */
+    private fun parseCidr(cidr: String): Pair<String, Int> {
+        val parts = cidr.split("/")
+        if (parts.size != 2) {
+            throw IllegalArgumentException("无效的 CIDR 格式: $cidr")
+        }
+        return Pair(parts[0], parts[1].toInt())
+    }
+
+    private fun cleanup() {
+        isRunning = false
+        vpnInterface?.close()
+        vpnInterface = null
+        Log.i(TAG, "VPN 接口已清理")
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        Log.d(TAG, "VPN Service destroyed")
+        cleanup()
+    }
+}

easytier-contrib/easytier-android-jni/kotlin/com/easytier/jni/README.md

@@ -0,0 +1,41 @@
+# 使用说明
+
+1. 需要将 proto 文件放入 app/src/main/proto
+2. android/gradle/libs.versions.toml 中加入依赖
+
+```
+# Wire 核心运行时
+android-wire-runtime = { group = "com.squareup.wire", name = "wire-runtime", version = "5.3.11" }
+moshi = { module = "com.squareup.moshi:moshi", version.ref = "moshi" }
+android-wire-moshi-adapter = { group = "com.squareup.wire", name = "wire-moshi-adapter", version = "5.3.11" }
+kotlinx-serialization-json = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-json", version = "1.9.0" }
+```
+
+3. build.gradle.kts 中加入
+
+```
+plugins {
+    ...
+    alias(libs.plugins.wire)
+}
+
+dependencies {
+    ...
+    implementation(libs.android.wire.runtime)
+    implementation(libs.android.wire.moshi.adapter)
+    implementation(libs.moshi)
+}
+
+...
+
+wire {
+    kotlin {
+        rpcRole = "none"
+    }
+}
+```
+
+4. 调用 easytier-contrib/easytier-android-jni/build.sh 生成 jni 和 ffi 的 so 文件。
+并将生成的 so 文件放到 android/app/src/main/jniLibs/arm64-v8a 目录下。
+
+5. 使用 EasyTierManager 可以拉起 EasyTier 实例并启动 Android VpnService 组件。

easytier-contrib/easytier-android-jni/src/callback.rs

@@ -0,0 +1,124 @@
+use std::{
+    ffi::{CStr, c_char, c_void},
+    sync::{Arc, Mutex, MutexGuard},
+};
+
+use easytier_ffi::ConfigServerEventCallback;
+use jni::JNIEnv;
+use jni::objects::{GlobalRef, JObject, JValue};
+use once_cell::sync::Lazy;
+
+use crate::error;
+
+pub(crate) struct JniConfigServerCallback {
+    java_vm: jni::JavaVM,
+    callback: GlobalRef,
+}
+
+static CONFIG_SERVER_CALLBACK: Lazy<Mutex<Option<Arc<JniConfigServerCallback>>>> =
+    Lazy::new(|| Mutex::new(None));
+
+pub(crate) fn lock_callback_storage()
+-> Result<MutexGuard<'static, Option<Arc<JniConfigServerCallback>>>, String> {
+    CONFIG_SERVER_CALLBACK
+        .lock()
+        .map_err(|e| format!("Failed to lock config server callback: {}", e))
+}
+
+pub(crate) fn new_callback(
+    env: &mut JNIEnv,
+    callback: &JObject,
+) -> Result<Arc<JniConfigServerCallback>, String> {
+    let java_vm = env
+        .get_java_vm()
+        .map_err(|e| format!("Failed to get JavaVM: {:?}", e))?;
+    let callback = env
+        .new_global_ref(callback)
+        .map_err(|e| format!("Failed to create callback global ref: {:?}", e))?;
+    Ok(Arc::new(JniConfigServerCallback { java_vm, callback }))
+}
+
+pub(crate) fn callback_fn(
+    callback: &Option<Arc<JniConfigServerCallback>>,
+) -> ConfigServerEventCallback {
+    callback
+        .as_ref()
+        .map(|_| config_server_event_callback as unsafe extern "C" fn(*const c_char, *mut c_void))
+}
+
+pub(crate) fn user_data(callback: &Option<Arc<JniConfigServerCallback>>) -> *mut c_void {
+    callback
+        .as_ref()
+        .map(|callback| Arc::as_ptr(callback) as *mut c_void)
+        .unwrap_or(std::ptr::null_mut())
+}
+
+impl JniConfigServerCallback {
+    fn clear_pending_exception(
+        env: &mut JNIEnv,
+        context: &str,
+        error: &dyn std::fmt::Debug,
+    ) -> String {
+        match env.exception_check() {
+            Ok(true) => {
+                if let Err(clear_err) = env.exception_clear() {
+                    return format!(
+                        "{}: {:?}; failed to clear pending Java exception: {:?}",
+                        context, error, clear_err
+                    );
+                }
+            }
+            Ok(false) => {}
+            Err(check_err) => {
+                return format!(
+                    "{}: {:?}; failed to check pending Java exception: {:?}",
+                    context, error, check_err
+                );
+            }
+        }
+
+        format!("{}: {:?}", context, error)
+    }
+
+    fn on_event(&self, event_json: *const c_char) -> Result<(), String> {
+        let event_json = unsafe { CStr::from_ptr(event_json) }
+            .to_str()
+            .map_err(|e| format!("Invalid config server event JSON: {:?}", e))?;
+        let mut env = self
+            .java_vm
+            .attach_current_thread()
+            .map_err(|e| format!("Failed to attach callback thread: {:?}", e))?;
+        let event_json = env.new_string(event_json).map_err(|e| {
+            Self::clear_pending_exception(&mut env, "Failed to create event string", &e)
+        })?;
+
+        if let Err(e) = env.call_method(
+            self.callback.as_obj(),
+            "onEvent",
+            "(Ljava/lang/String;)V",
+            &[JValue::from(&event_json)],
+        ) {
+            return Err(Self::clear_pending_exception(
+                &mut env,
+                "Failed to call config server callback",
+                &e,
+            ));
+        }
+        Ok(())
+    }
+}
+
+unsafe extern "C" fn config_server_event_callback(
+    event_json: *const c_char,
+    user_data: *mut c_void,
+) {
+    if event_json.is_null() || user_data.is_null() {
+        return;
+    }
+
+    let callback = unsafe { &*(user_data as *const JniConfigServerCallback) };
+
+    if let Err(error) = callback.on_event(event_json) {
+        error::set_callback_error(error);
+    }
+}

easytier-contrib/easytier-android-jni/src/config_server_api.rs

@@ -0,0 +1,140 @@
+use std::ptr;
+
+use easytier_ffi::{
+    in_config_server_callback, is_config_server_client_connected, start_config_server_client,
+    stop_config_server_client,
+};
+use jni::JNIEnv;
+use jni::objects::{JClass, JObject, JString};
+use jni::sys::{JNI_FALSE, JNI_TRUE, jboolean, jint};
+
+use crate::{
+    callback, error,
+    strings::{jstring_to_cstring, optional_jstring_to_cstring},
+};
+
+pub(crate) fn start_config_server_client_jni(
+    env: &mut JNIEnv,
+    config_server_url: JString,
+    hostname: JString,
+    machine_id: JString,
+    secure_mode: jboolean,
+    callback_obj: JObject,
+) -> jint {
+    if in_config_server_callback() {
+        error::throw_exception(
+            env,
+            "Cannot start config server client from config server callback",
+        );
+        return -1;
+    }
+
+    let config_server_url = match jstring_to_cstring(env, &config_server_url) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            error::throw_exception(env, &format!("Invalid config server URL: {}", e));
+            return -1;
+        }
+    };
+    let hostname = match optional_jstring_to_cstring(env, &hostname) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            error::throw_exception(env, &format!("Invalid hostname: {}", e));
+            return -1;
+        }
+    };
+    let machine_id = match jstring_to_cstring(env, &machine_id) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            error::throw_exception(env, &format!("Invalid machine ID: {}", e));
+            return -1;
+        }
+    };
+
+    let callback_ref = if callback_obj.is_null() {
+        None
+    } else {
+        match callback::new_callback(env, &callback_obj) {
+            Ok(state) => Some(state),
+            Err(e) => {
+                error::throw_exception(env, &e);
+                return -1;
+            }
+        }
+    };
+
+    let mut callback_guard = match callback::lock_callback_storage() {
+        Ok(guard) => guard,
+        Err(e) => {
+            error::throw_exception(env, &e);
+            return -1;
+        }
+    };
+    if callback_guard.is_none() {
+        error::clear_callback_error();
+    }
+
+    let callback_fn = callback::callback_fn(&callback_ref);
+    let user_data = callback::user_data(&callback_ref);
+    let result = unsafe {
+        start_config_server_client(
+            config_server_url.as_ptr(),
+            hostname
+                .as_ref()
+                .map(|value| value.as_ptr())
+                .unwrap_or(ptr::null()),
+            machine_id.as_ptr(),
+            secure_mode == JNI_TRUE,
+            callback_fn,
+            user_data,
+        )
+    };
+    if result != 0 {
+        if let Some(error_msg) = error::get_last_error() {
+            error::throw_exception(env, &error_msg);
+        }
+        return result;
+    }
+
+    *callback_guard = callback_ref;
+    result
+}
+
+pub(crate) fn stop_config_server_client_jni(mut env: JNIEnv, _class: JClass) -> jint {
+    if in_config_server_callback() {
+        let result = stop_config_server_client();
+        if result != 0
+            && let Some(error_msg) = error::get_last_error()
+        {
+            error::throw_exception(&mut env, &error_msg);
+        }
+        return result;
+    }
+
+    let mut callback_guard = match callback::lock_callback_storage() {
+        Ok(guard) => guard,
+        Err(e) => {
+            error::throw_exception(&mut env, &e);
+            return -1;
+        }
+    };
+
+    let result = stop_config_server_client();
+    if result != 0 {
+        if let Some(error_msg) = error::get_last_error() {
+            error::throw_exception(&mut env, &error_msg);
+        }
+        return result;
+    }
+
+    *callback_guard = None;
+    result
+}
+
+pub(crate) fn is_config_server_client_connected_jni(_env: JNIEnv, _class: JClass) -> jboolean {
+    if is_config_server_client_connected() != 0 {
+        JNI_TRUE
+    } else {
+        JNI_FALSE
+    }
+}

easytier-contrib/easytier-android-jni/src/error.rs

@@ -0,0 +1,74 @@
+use std::{
+    ffi::{CStr, c_char},
+    ptr,
+    sync::Mutex,
+};
+
+use easytier_ffi::{free_string, get_error_msg};
+use jni::JNIEnv;
+use jni::objects::JClass;
+use jni::sys::jstring;
+use once_cell::sync::Lazy;
+
+static JNI_CALLBACK_ERROR: Lazy<Mutex<Option<String>>> = Lazy::new(|| Mutex::new(None));
+
+pub(crate) fn set_callback_error(error: String) {
+    log::error!("{}", error);
+    if let Ok(mut guard) = JNI_CALLBACK_ERROR.lock() {
+        *guard = Some(error);
+    }
+}
+
+pub(crate) fn clear_callback_error() {
+    if let Ok(mut guard) = JNI_CALLBACK_ERROR.lock() {
+        *guard = None;
+    }
+}
+
+fn take_callback_error() -> Option<String> {
+    JNI_CALLBACK_ERROR
+        .lock()
+        .ok()
+        .and_then(|mut guard| guard.take())
+}
+
+fn get_ffi_last_error() -> Option<String> {
+    unsafe {
+        let mut error_ptr: *const c_char = ptr::null();
+        get_error_msg(&mut error_ptr);
+        if error_ptr.is_null() {
+            None
+        } else {
+            let error_cstr = CStr::from_ptr(error_ptr);
+            let error_str = error_cstr.to_string_lossy().into_owned();
+            free_string(error_ptr);
+            Some(error_str)
+        }
+    }
+}
+
+pub(crate) fn get_last_error() -> Option<String> {
+    match (get_ffi_last_error(), take_callback_error()) {
+        (Some(ffi_error), Some(callback_error)) => Some(format!(
+            "{}; config server callback error: {}",
+            ffi_error, callback_error
+        )),
+        (Some(ffi_error), None) => Some(ffi_error),
+        (None, Some(callback_error)) => Some(callback_error),
+        (None, None) => None,
+    }
+}
+
+pub(crate) fn throw_exception(env: &mut JNIEnv, message: &str) {
+    let _ = env.throw_new("java/lang/RuntimeException", message);
+}
+
+pub(crate) fn get_last_error_jni(env: JNIEnv, _class: JClass) -> jstring {
+    match get_last_error() {
+        Some(error) => match env.new_string(&error) {
+            Ok(jstr) => jstr.into_raw(),
+            Err(_) => ptr::null_mut(),
+        },
+        None => ptr::null_mut(),
+    }
+}

easytier-contrib/easytier-android-jni/src/json_rpc_api.rs

@@ -0,0 +1,91 @@
+use std::{
+    ffi::{CStr, c_char},
+    ptr,
+};
+
+use easytier_ffi::{call_json_rpc, free_string};
+use jni::JNIEnv;
+use jni::objects::{JClass, JString};
+use jni::sys::jstring;
+
+use crate::{
+    error::{get_last_error, throw_exception},
+    strings::{jstring_to_cstring, optional_jstring_to_cstring},
+};
+
+pub(crate) fn call_json_rpc_jni(
+    mut env: JNIEnv,
+    _class: JClass,
+    service_name: JString,
+    method_name: JString,
+    domain_name: JString,
+    payload_json: JString,
+) -> jstring {
+    let service_name_cstr = match jstring_to_cstring(&mut env, &service_name) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            throw_exception(&mut env, &format!("Invalid service name: {}", e));
+            return ptr::null_mut();
+        }
+    };
+    let method_name_cstr = match jstring_to_cstring(&mut env, &method_name) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            throw_exception(&mut env, &format!("Invalid method name: {}", e));
+            return ptr::null_mut();
+        }
+    };
+    let domain_name_cstr = match optional_jstring_to_cstring(&mut env, &domain_name) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            throw_exception(&mut env, &format!("Invalid domain name: {}", e));
+            return ptr::null_mut();
+        }
+    };
+    let payload_json_cstr = match jstring_to_cstring(&mut env, &payload_json) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            throw_exception(&mut env, &format!("Invalid payload JSON: {}", e));
+            return ptr::null_mut();
+        }
+    };
+
+    let domain_name_ptr = domain_name_cstr
+        .as_ref()
+        .map_or(ptr::null(), |cstr| cstr.as_ptr());
+    let mut response_ptr: *const c_char = ptr::null();
+    let result = unsafe {
+        call_json_rpc(
+            service_name_cstr.as_ptr(),
+            method_name_cstr.as_ptr(),
+            domain_name_ptr,
+            payload_json_cstr.as_ptr(),
+            &mut response_ptr,
+        )
+    };
+
+    if result != 0 {
+        if let Some(error) = get_last_error() {
+            throw_exception(&mut env, &error);
+        }
+        return ptr::null_mut();
+    }
+
+    if response_ptr.is_null() {
+        throw_exception(&mut env, "JSON RPC returned a null response");
+        return ptr::null_mut();
+    }
+
+    let response = unsafe { CStr::from_ptr(response_ptr) }
+        .to_string_lossy()
+        .into_owned();
+    free_string(response_ptr);
+
+    match env.new_string(&response) {
+        Ok(jstr) => jstr.into_raw(),
+        Err(_) => {
+            throw_exception(&mut env, "Failed to create JSON RPC response string");
+            ptr::null_mut()
+        }
+    }
+}

easytier-contrib/easytier-android-jni/src/lib.rs

@@ -0,0 +1,271 @@
+//! JNI facade for Android callers of EasyTier.
+//!
+//! This file intentionally lists every Java-visible native method exported by
+//! `libeasytier_android_jni.so`. The implementation details live in sibling
+//! modules so this facade stays readable as an API map.
+//!
+//! Network management APIs:
+//! - `setTunFd(instanceName, fd)`: attach an Android TUN fd to an instance.
+//! - `parseConfig(config)`: validate TOML config text.
+//! - `runNetworkInstance(config)`: start a local network instance.
+//! - `retainNetworkInstance(instanceNames)`: retain named instances and stop the rest.
+//! - `deleteNetworkInstance(instanceName)`: stop exactly one named instance.
+//! - `listInstances()`: return running instance names and IDs as JSON.
+//! - `collectNetworkInfos()`: return running instance info as a JSON string.
+//! - `callJsonRpc(...)`: call an exposed EasyTier RPC service with JSON payload.
+//!
+//! Config server client APIs:
+//! - `startConfigServerClient(url, hostname, machineId, secureMode, callback)`:
+//!   start the managed remote config client.
+//! - `stopConfigServerClient()`: stop the managed client and release its Java callback.
+//! - `isConfigServerClientConnected()`: return whether the managed client is connected.
+//!
+//! Error API:
+//! - `getLastError()`: return the latest FFI/JNI error string for the calling thread.
+//!
+mod callback;
+mod config_server_api;
+mod error;
+mod json_rpc_api;
+mod logger;
+mod network_api;
+mod strings;
+
+use jni::JNIEnv;
+use jni::objects::{JClass, JObject, JObjectArray, JString};
+use jni::sys::{jboolean, jint, jstring};
+
+/// Attach a TUN file descriptor to an EasyTier network instance.
+///
+/// Java signature:
+/// `EasyTierJNI.setTunFd(instanceName: String, fd: Int): Int`
+///
+/// `instanceName` must name an instance known to the shared FFI instance cache.
+/// The `fd` must be a valid Android TUN file descriptor. On failure this
+/// returns `-1` and throws `RuntimeException` with the FFI error message when
+/// one is available.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_setTunFd(
+    env: JNIEnv,
+    class: JClass,
+    inst_name: JString,
+    fd: jint,
+) -> jint {
+    logger::init();
+    network_api::set_tun_fd_jni(env, class, inst_name, fd)
+}
+
+/// Validate a TOML network config string.
+///
+/// Java signature:
+/// `EasyTierJNI.parseConfig(config: String): Int`
+///
+/// This only validates the config text; it does not start or mutate any
+/// instance. On failure this returns `-1` and throws `RuntimeException`.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_parseConfig(
+    env: JNIEnv,
+    class: JClass,
+    config: JString,
+) -> jint {
+    logger::init();
+    network_api::parse_config_jni(env, class, config)
+}
+
+/// Start one local EasyTier network instance from TOML config text.
+///
+/// Java signature:
+/// `EasyTierJNI.runNetworkInstance(config: String): Int`
+///
+/// The instance name in the config must be unique in the FFI instance cache.
+/// On failure this returns `-1` and throws `RuntimeException`.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_runNetworkInstance(
+    env: JNIEnv,
+    class: JClass,
+    config: JString,
+) -> jint {
+    logger::init();
+    network_api::run_network_instance_jni(env, class, config)
+}
+
+/// Retain the named network instances and stop all other instances.
+///
+/// Java signature:
+/// `EasyTierJNI.retainNetworkInstance(instanceNames: Array<String>?): Int`
+///
+/// Passing `null` or an empty array stops all instances. Null elements inside a
+/// non-empty array are invalid. On failure this returns `-1` and throws
+/// `RuntimeException`.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_retainNetworkInstance(
+    env: JNIEnv,
+    class: JClass,
+    instance_names: JObjectArray,
+) -> jint {
+    logger::init();
+    network_api::retain_network_instance_jni(env, class, instance_names)
+}
+
+/// Stop exactly one named network instance without affecting other instances.
+///
+/// Java signature:
+/// `EasyTierJNI.deleteNetworkInstance(instanceName: String): Int`
+///
+/// An unknown name is a no-op. On failure this returns `-1` and throws
+/// `RuntimeException`.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_deleteNetworkInstance(
+    env: JNIEnv,
+    class: JClass,
+    instance_name: JString,
+) -> jint {
+    logger::init();
+    network_api::delete_network_instance_jni(env, class, instance_name)
+}
+
+/// Collect running network instance information.
+///
+/// Java signature:
+/// `EasyTierJNI.collectNetworkInfos(maxLength: Int): String?`
+///
+/// Returns a JSON string containing `NetworkInstanceRunningInfoMap`, or null if
+/// collection fails. `maxLength` limits how many FFI entries are collected. On
+/// failure this throws `RuntimeException` when an error message is available.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_collectNetworkInfos(
+    env: JNIEnv,
+    class: JClass,
+    max_length: jint,
+) -> jstring {
+    logger::init();
+    network_api::collect_network_infos_jni(env, class, max_length)
+}
+
+/// List running network instance names and IDs.
+///
+/// Java signature:
+/// `EasyTierJNI.listInstances(maxLength: Int): String?`
+///
+/// Returns a JSON object whose keys are instance names and whose values are
+/// instance ID strings. On failure this returns null and throws
+/// `RuntimeException`.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_listInstances(
+    env: JNIEnv,
+    class: JClass,
+    max_length: jint,
+) -> jstring {
+    logger::init();
+    network_api::list_instances_jni(env, class, max_length)
+}
+
+/// Call an exposed EasyTier RPC method using protobuf JSON.
+///
+/// Java signature:
+/// `EasyTierJNI.callJsonRpc(serviceName, methodName, domainName, payloadJson): String?`
+///
+/// Instance lifecycle management RPCs are intentionally not exposed here. Use
+/// the dedicated EasyTierJNI instance APIs for start/retain/delete/collect.
+/// `payloadJson` must include any `instance` selector required by the target
+/// RPC. On failure this returns null and throws `RuntimeException`.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_callJsonRpc(
+    env: JNIEnv,
+    class: JClass,
+    service_name: JString,
+    method_name: JString,
+    domain_name: JString,
+    payload_json: JString,
+) -> jstring {
+    logger::init();
+    json_rpc_api::call_json_rpc_jni(
+        env,
+        class,
+        service_name,
+        method_name,
+        domain_name,
+        payload_json,
+    )
+}
+
+/// Return the latest FFI/JNI error string for the calling thread.
+///
+/// Java signature:
+/// `EasyTierJNI.getLastError(): String?`
+///
+/// This combines the FFI thread-local error with any pending config-server Java
+/// callback error. It returns null when no error is available.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_getLastError(
+    env: JNIEnv,
+    class: JClass,
+) -> jstring {
+    error::get_last_error_jni(env, class)
+}
+
+/// Start the managed config-server client.
+///
+/// Java signature:
+/// `EasyTierJNI.startConfigServerClient(url, hostname, machineId, secureMode, callback): Int`
+///
+/// JNI only converts Java values and keeps the Java callback alive. The FFI
+/// layer owns singleton lifecycle, config-server/data-plane mutual exclusion,
+/// remote instance tracking, and callback event timing. If `callback` is
+/// non-null, each remote apply/delete event is delivered to
+/// `ConfigServerEventCallback.onEvent(eventJson)`.
+///
+/// On failure this returns `-1` and throws `RuntimeException`.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_startConfigServerClient(
+    mut env: JNIEnv,
+    _class: JClass,
+    config_server_url: JString,
+    hostname: JString,
+    machine_id: JString,
+    secure_mode: jboolean,
+    callback: JObject,
+) -> jint {
+    logger::init();
+    config_server_api::start_config_server_client_jni(
+        &mut env,
+        config_server_url,
+        hostname,
+        machine_id,
+        secure_mode,
+        callback,
+    )
+}
+
+/// Stop the managed config-server client.
+///
+/// Java signature:
+/// `EasyTierJNI.stopConfigServerClient(): Int`
+///
+/// The FFI layer performs the actual stop and managed instance cleanup. JNI
+/// releases the Java callback reference after FFI stop succeeds. On failure
+/// this returns `-1` and throws `RuntimeException`.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_stopConfigServerClient(
+    env: JNIEnv,
+    class: JClass,
+) -> jint {
+    logger::init();
+    config_server_api::stop_config_server_client_jni(env, class)
+}
+
+/// Report whether the managed config-server client is connected.
+///
+/// Java signature:
+/// `EasyTierJNI.isConfigServerClientConnected(): Boolean`
+///
+/// Returns `JNI_TRUE` only when the FFI config-server client exists and reports
+/// connected.
+#[unsafe(no_mangle)]
+pub extern "system" fn Java_com_easytier_jni_EasyTierJNI_isConfigServerClientConnected(
+    env: JNIEnv,
+    class: JClass,
+) -> jboolean {
+    logger::init();
+    config_server_api::is_config_server_client_connected_jni(env, class)
+}

easytier-contrib/easytier-android-jni/src/logger.rs

@@ -0,0 +1,13 @@
+use once_cell::sync::Lazy;
+
+static LOGGER_INIT: Lazy<()> = Lazy::new(|| {
+    android_logger::init_once(
+        android_logger::Config::default()
+            .with_max_level(log::LevelFilter::Debug)
+            .with_tag("EasyTier-JNI"),
+    );
+});
+
+pub(crate) fn init() {
+    Lazy::force(&LOGGER_INIT);
+}

easytier-contrib/easytier-android-jni/src/network_api.rs

@@ -0,0 +1,285 @@
+use std::{ffi::CStr, ptr};
+
+use easytier::proto::api::manage::{NetworkInstanceRunningInfo, NetworkInstanceRunningInfoMap};
+use easytier_ffi::{
+    KeyValuePair, collect_network_infos, delete_network_instance, free_string, list_instance,
+    parse_config, retain_network_instance, run_network_instance, set_tun_fd,
+};
+use jni::JNIEnv;
+use jni::objects::{JClass, JObjectArray, JString};
+use jni::sys::{jint, jstring};
+
+use crate::{
+    error::{get_last_error, throw_exception},
+    strings::jstring_to_cstring,
+};
+
+pub(crate) fn set_tun_fd_jni(
+    mut env: JNIEnv,
+    _class: JClass,
+    inst_name: JString,
+    fd: jint,
+) -> jint {
+    let inst_name_cstr = match jstring_to_cstring(&mut env, &inst_name) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            throw_exception(&mut env, &format!("Invalid instance name: {}", e));
+            return -1;
+        }
+    };
+    unsafe {
+        let result = set_tun_fd(inst_name_cstr.as_ptr(), fd);
+        if result != 0
+            && let Some(error) = get_last_error()
+        {
+            throw_exception(&mut env, &error);
+        }
+        result
+    }
+}
+
+pub(crate) fn parse_config_jni(mut env: JNIEnv, _class: JClass, config: JString) -> jint {
+    let config_cstr = match jstring_to_cstring(&mut env, &config) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            throw_exception(&mut env, &format!("Invalid config string: {}", e));
+            return -1;
+        }
+    };
+    unsafe {
+        let result = parse_config(config_cstr.as_ptr());
+        if result != 0
+            && let Some(error) = get_last_error()
+        {
+            throw_exception(&mut env, &error);
+        }
+        result
+    }
+}
+
+pub(crate) fn run_network_instance_jni(mut env: JNIEnv, _class: JClass, config: JString) -> jint {
+    let config_cstr = match jstring_to_cstring(&mut env, &config) {
+        Ok(cstr) => cstr,
+        Err(e) => {
+            throw_exception(&mut env, &format!("Invalid config string: {}", e));
+            return -1;
+        }
+    };
+    unsafe {
+        let result = run_network_instance(config_cstr.as_ptr());
+        if result != 0
+            && let Some(error) = get_last_error()
+        {
+            throw_exception(&mut env, &error);
+        }
+        result
+    }
+}
+
+pub(crate) fn delete_network_instance_jni(
+    mut env: JNIEnv,
+    _class: JClass,
+    instance_name: JString,
+) -> jint {
+    let instance_name = match jstring_to_cstring(&mut env, &instance_name) {
+        Ok(name) => name,
+        Err(error) => {
+            throw_exception(&mut env, &format!("Invalid instance name: {error}"));
+            return -1;
+        }
+    };
+    let instance_names = [instance_name.as_ptr()];
+    unsafe {
+        let result = delete_network_instance(instance_names.as_ptr(), instance_names.len());
+        if result != 0
+            && let Some(error) = get_last_error()
+        {
+            throw_exception(&mut env, &error);
+        }
+        result
+    }
+}
+
+pub(crate) fn retain_network_instance_jni(
+    mut env: JNIEnv,
+    _class: JClass,
+    instance_names: JObjectArray,
+) -> jint {
+    if instance_names.is_null() {
+        return retain_all(&mut env);
+    }
+
+    let array_length = match env.get_array_length(&instance_names) {
+        Ok(len) => len as usize,
+        Err(e) => {
+            throw_exception(&mut env, &format!("Failed to get array length: {:?}", e));
+            return -1;
+        }
+    };
+
+    if array_length == 0 {
+        return retain_all(&mut env);
+    }
+
+    let mut c_strings = Vec::with_capacity(array_length);
+    let mut c_string_ptrs = Vec::with_capacity(array_length);
+
+    for i in 0..array_length {
+        let java_string = match env.get_object_array_element(&instance_names, i as i32) {
+            Ok(obj) => obj,
+            Err(e) => {
+                throw_exception(
+                    &mut env,
+                    &format!("Failed to get array element {}: {:?}", i, e),
+                );
+                return -1;
+            }
+        };
+
+        if java_string.is_null() {
+            throw_exception(
+                &mut env,
+                &format!("Invalid instance name at index {}: null", i),
+            );
+            return -1;
+        }
+
+        let jstring = JString::from(java_string);
+        let c_string = match jstring_to_cstring(&mut env, &jstring) {
+            Ok(cstr) => cstr,
+            Err(e) => {
+                throw_exception(
+                    &mut env,
+                    &format!("Invalid instance name at index {}: {}", i, e),
+                );
+                return -1;
+            }
+        };
+
+        c_string_ptrs.push(c_string.as_ptr());
+        c_strings.push(c_string);
+    }
+
+    unsafe {
+        let result = retain_network_instance(c_string_ptrs.as_ptr(), c_string_ptrs.len());
+        if result != 0
+            && let Some(error) = get_last_error()
+        {
+            throw_exception(&mut env, &error);
+        }
+        result
+    }
+}
+
+fn retain_all(env: &mut JNIEnv) -> jint {
+    unsafe {
+        let result = retain_network_instance(ptr::null(), 0);
+        if result != 0
+            && let Some(error) = get_last_error()
+        {
+            throw_exception(env, &error);
+        }
+        result
+    }
+}
+
+pub(crate) fn collect_network_infos_jni(
+    mut env: JNIEnv,
+    _class: JClass,
+    max_length: jint,
+) -> jstring {
+    let max_length = max_length.max(0) as usize;
+    let mut infos = vec![
+        KeyValuePair {
+            key: ptr::null(),
+            value: ptr::null(),
+        };
+        max_length
+    ];
+
+    unsafe {
+        let count = collect_network_infos(infos.as_mut_ptr(), max_length);
+        if count < 0 {
+            if let Some(error) = get_last_error() {
+                throw_exception(&mut env, &error);
+            }
+            return ptr::null_mut();
+        }
+
+        let mut ret = NetworkInstanceRunningInfoMap::default();
+        for info in infos.iter().take(count as usize) {
+            let key_ptr = info.key;
+            let val_ptr = info.value;
+            if key_ptr.is_null() || val_ptr.is_null() {
+                break;
+            }
+
+            let key = CStr::from_ptr(key_ptr).to_string_lossy().into_owned();
+            let val = CStr::from_ptr(val_ptr).to_string_lossy().into_owned();
+            free_string(key_ptr);
+            free_string(val_ptr);
+            let value = match serde_json::from_str::<NetworkInstanceRunningInfo>(&val) {
+                Ok(v) => v,
+                Err(_) => {
+                    throw_exception(&mut env, "Failed to parse JSON");
+                    continue;
+                }
+            };
+            ret.map.insert(key, value);
+        }
+
+        let json_str = serde_json::to_string(&ret).unwrap_or_else(|_| "{}".to_string());
+        match env.new_string(&json_str) {
+            Ok(jstr) => jstr.into_raw(),
+            Err(_) => {
+                throw_exception(&mut env, "Failed to create JSON string");
+                ptr::null_mut()
+            }
+        }
+    }
+}
+
+pub(crate) fn list_instances_jni(mut env: JNIEnv, _class: JClass, max_length: jint) -> jstring {
+    let max_length = max_length.max(0) as usize;
+    let mut infos = vec![
+        KeyValuePair {
+            key: ptr::null(),
+            value: ptr::null(),
+        };
+        max_length
+    ];
+
+    unsafe {
+        let count = list_instance(infos.as_mut_ptr(), max_length);
+        if count < 0 {
+            if let Some(error) = get_last_error() {
+                throw_exception(&mut env, &error);
+            }
+            return ptr::null_mut();
+        }
+
+        let mut ret = serde_json::Map::new();
+        for info in infos.iter().take(count as usize) {
+            let key_ptr = info.key;
+            let val_ptr = info.value;
+            if key_ptr.is_null() || val_ptr.is_null() {
+                break;
+            }
+
+            let key = CStr::from_ptr(key_ptr).to_string_lossy().into_owned();
+            let val = CStr::from_ptr(val_ptr).to_string_lossy().into_owned();
+            free_string(key_ptr);
+            free_string(val_ptr);
+            ret.insert(key, serde_json::Value::String(val));
+        }
+
+        let json_str = serde_json::Value::Object(ret).to_string();
+        match env.new_string(&json_str) {
+            Ok(jstr) => jstr.into_raw(),
+            Err(_) => {
+                throw_exception(&mut env, "Failed to create instance list JSON string");
+                ptr::null_mut()
+            }
+        }
+    }
+}

easytier-contrib/easytier-android-jni/src/strings.rs

@@ -0,0 +1,23 @@
+use std::ffi::CString;
+
+use jni::JNIEnv;
+use jni::objects::JString;
+
+pub(crate) fn jstring_to_cstring(env: &mut JNIEnv, jstr: &JString) -> Result<CString, String> {
+    let java_str = env
+        .get_string(jstr)
+        .map_err(|e| format!("Failed to get string: {:?}", e))?;
+    let rust_str = java_str.to_str().map_err(|_| "Invalid UTF-8".to_string())?;
+    CString::new(rust_str).map_err(|_| "String contains null byte".to_string())
+}
+
+pub(crate) fn optional_jstring_to_cstring(
+    env: &mut JNIEnv,
+    jstr: &JString,
+) -> Result<Option<CString>, String> {
+    if jstr.is_null() {
+        return Ok(None);
+    }
+
+    jstring_to_cstring(env, jstr).map(Some)
+}

easytier-contrib/easytier-ffi/Cargo.toml

@@ -0,0 +1,40 @@
+[package]
+name = "easytier-ffi"
+version = "0.1.0"
+edition.workspace = true
+rust-version.workspace = true
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[features]
+default = ["c-abi", "ffi-dataplane"]
+c-abi = []
+ffi-dataplane = [
+    "easytier/ffi-dataplane",
+    "easytier-core/proxy-smoltcp-stack",
+]
+macos-ne = ["easytier/macos-ne"]
+
+[dependencies]
+easytier = { workspace = true, default-features = true, features = ["tracing-log"] }
+easytier-core = { workspace = true, default-features = true }
+
+once_cell.workspace = true
+tokio = { workspace = true, default-features = true, features = ["rt-multi-thread", "io-util", "time", "sync", "macros"] }
+async-trait.workspace = true
+log.workspace = true
+
+serde_json.workspace = true
+uuid.workspace = true
+
+[build-dependencies]
+thunk-rs = { workspace = true, features = [
+    "win7",
+] }
+
+[package.metadata.cargo-machete]
+ignored = [
+    # Windows-only build.rs setup calls thunk::thunk().
+    "thunk-rs",
+]

easytier-contrib/easytier-ffi/DATA_PLANE_ABI.md

@@ -0,0 +1,108 @@
+# Native data-plane ABI v3
+
+The native data-plane ABI is a thin adapter over the instance-owned
+`DataPlaneSession`. It does not own sockets, operation state, completion
+queues, routing policy, or timeouts.
+
+## Conventions
+
+- Every immediate call returns `0` on success or a negative
+  `DataPlaneErrorKind` value on failure.
+- `data_plane_completion_wait` returns `1` when a completion is ready, `0` on
+  timeout or session close, and a negative error value on failure.
+- `data_plane_completion_drain` returns a non-negative descriptor count or a
+  negative error value.
+- Handle zero is invalid.
+- `timeout_ms == UINT64_MAX` means no deadline.
+- TCP connect/bind/accept and UDP bind timeouts start when submission is
+  accepted.
+- TCP streams and UDP sockets have persistent read and write deadlines.
+  `data_plane_resource_deadline_set` replaces the selected directions'
+  deadlines immediately, including for active operations. An expired deadline
+  remains expired until it is replaced or cleared with `UINT64_MAX`.
+- Deadline direction `1` selects reads, `2` selects writes, and `3` selects
+  both.
+- Request and write bytes are copied before a submit call returns.
+- Socket-address fields use native-endian integers. Address bytes are in
+  network order. ABI v3 accepts IPv4 only.
+
+`DataPlaneSocketAddr` is:
+
+```c
+typedef struct {
+    uint16_t family;      /* 4 */
+    uint16_t port;
+    uint8_t address[16];  /* IPv4 uses the first four bytes */
+} DataPlaneSocketAddr;
+```
+
+`DataPlaneCompletion` is:
+
+```c
+typedef struct {
+    uint64_t operation_id;
+    uint16_t operation_kind;
+    uint16_t status; /* 0 or DataPlaneErrorKind */
+} DataPlaneCompletion;
+```
+
+## Lifecycle
+
+One native session may be open for an EasyTier instance at a time:
+
+```text
+data_plane_session_open
+  -> set resource deadlines
+  -> submit operations
+  -> completion_wait
+  -> completion_drain
+  -> typed result_take
+  -> resource_close / operation_free
+data_plane_session_close
+```
+
+Closing a native session cancels and discards its outstanding operations and
+resources and wakes a thread blocked in `data_plane_completion_wait`.
+
+The resource and operation IDs returned by the ABI belong to that session.
+They must always be passed together with the same session handle.
+
+## Completion and result ownership
+
+Submission returns an operation ID immediately. Completion descriptors carry
+only the operation ID, operation kind, and terminal status. Draining a
+descriptor makes its typed result available but does not consume it.
+
+`data_plane_result_size` reports the TCP-read or UDP-receive payload size.
+Typed result-take functions consume the result exactly once. If a supplied
+buffer is too small, they return `-BufferTooSmall` and leave the result
+available for a later call.
+
+Call `data_plane_operation_free` when a drained result is intentionally
+abandoned. Call `data_plane_resource_close` for TCP streams, listeners, and
+UDP sockets.
+
+## Operation kinds
+
+| Value | Operation |
+| ---: | --- |
+| 1 | TCP connect |
+| 2 | TCP bind |
+| 3 | TCP accept |
+| 4 | TCP read |
+| 5 | TCP write |
+| 6 | UDP bind |
+| 7 | UDP receive |
+| 8 | UDP send |
+
+The exported function families are:
+
+- `data_plane_tcp_*_submit`
+- `data_plane_udp_*_submit`
+- `data_plane_resource_deadline_set`
+- `data_plane_completion_wait`
+- `data_plane_completion_drain`
+- `data_plane_*_result_take`
+- `data_plane_operation_cancel`
+- `data_plane_operation_free`
+- `data_plane_resource_close`

easytier-contrib/easytier-ffi/build.rs

@@ -0,0 +1,8 @@
+fn main() {
+    let target_os = std::env::var("CARGO_CFG_TARGET_OS").unwrap_or_default();
+    let target_arch = std::env::var("CARGO_CFG_TARGET_ARCH").unwrap_or_default();
+
+    if target_os == "windows" && (target_arch == "x86" || target_arch == "x86_64") {
+        thunk::thunk();
+    }
+}

easytier-contrib/easytier-ffi/examples/csharp.cs

@@ -0,0 +1,159 @@
+public class EasyTierFFI
+{
+    // 导入 DLL 函数
+    private const string DllName = "easytier_ffi.dll";
+
+    [DllImport(DllName, CallingConvention = CallingConvention.Cdecl)]
+    private static extern int parse_config([MarshalAs(UnmanagedType.LPStr)] string cfgStr);
+
+    [DllImport(DllName, CallingConvention = CallingConvention.Cdecl)]
+    private static extern int run_network_instance([MarshalAs(UnmanagedType.LPStr)] string cfgStr);
+
+    [DllImport(DllName, CallingConvention = CallingConvention.Cdecl)]
+    private static extern int retain_network_instance(IntPtr instNames, int length);
+
+    [DllImport(DllName, CallingConvention = CallingConvention.Cdecl)]
+    private static extern int collect_network_infos(IntPtr infos, int maxLength);
+
+    [DllImport(DllName, CallingConvention = CallingConvention.Cdecl)]
+    private static extern void get_error_msg(out IntPtr errorMsg);
+
+    [DllImport(DllName, CallingConvention = CallingConvention.Cdecl)]
+    private static extern void free_string(IntPtr str);
+
+    // 定义 KeyValuePair 结构体
+    [StructLayout(LayoutKind.Sequential)]
+    public struct KeyValuePair
+    {
+        public IntPtr Key;
+        public IntPtr Value;
+    }
+
+    // 解析配置
+    public static void ParseConfig(string config)
+    {
+        if (string.IsNullOrEmpty(config))
+        {
+            throw new ArgumentException("Configuration string cannot be null or empty.");
+        }
+
+        int result = parse_config(config);
+        if (result < 0)
+        {
+            throw new Exception(GetErrorMessage());
+        }
+    }
+
+    // 启动网络实例
+    public static void RunNetworkInstance(string config)
+    {
+        if (string.IsNullOrEmpty(config))
+        {
+            throw new ArgumentException("Configuration string cannot be null or empty.");
+        }
+
+        int result = run_network_instance(config);
+        if (result < 0)
+        {
+            throw new Exception(GetErrorMessage());
+        }
+    }
+
+    // 保留网络实例
+    public static void RetainNetworkInstances(string[] instanceNames)
+    {
+        IntPtr[] namePointers = null;
+        IntPtr namesPtr = IntPtr.Zero;
+
+        try
+        {
+            if (instanceNames != null && instanceNames.Length > 0)
+            {
+                namePointers = new IntPtr[instanceNames.Length];
+                for (int i = 0; i < instanceNames.Length; i++)
+                {
+                    if (string.IsNullOrEmpty(instanceNames[i]))
+                    {
+                        throw new ArgumentException("Instance name cannot be null or empty.");
+                    }
+                    namePointers[i] = Marshal.StringToHGlobalAnsi(instanceNames[i]);
+                }
+
+                namesPtr = Marshal.AllocHGlobal(Marshal.SizeOf<IntPtr>() * namePointers.Length);
+                Marshal.Copy(namePointers, 0, namesPtr, namePointers.Length);
+            }
+
+            int result = retain_network_instance(namesPtr, instanceNames?.Length ?? 0);
+            if (result < 0)
+            {
+                throw new Exception(GetErrorMessage());
+            }
+        }
+        finally
+        {
+            if (namePointers != null)
+            {
+                foreach (var ptr in namePointers)
+                {
+                    if (ptr != IntPtr.Zero)
+                    {
+                        Marshal.FreeHGlobal(ptr);
+                    }
+                }
+            }
+
+            if (namesPtr != IntPtr.Zero)
+            {
+                Marshal.FreeHGlobal(namesPtr);
+            }
+        }
+    }
+
+    // 收集网络信息
+    public static KeyValuePair<string, string>[] CollectNetworkInfos(int maxLength)
+    {
+        IntPtr buffer = Marshal.AllocHGlobal(Marshal.SizeOf<KeyValuePair>() * maxLength);
+        try
+        {
+            int count = collect_network_infos(buffer, maxLength);
+            if (count < 0)
+            {
+                throw new Exception(GetErrorMessage());
+            }
+
+            var result = new KeyValuePair<string, string>[count];
+            for (int i = 0; i < count; i++)
+            {
+                var kv = Marshal.PtrToStructure<KeyValuePair>(buffer + i * Marshal.SizeOf<KeyValuePair>());
+                string key = Marshal.PtrToStringAnsi(kv.Key);
+                string value = Marshal.PtrToStringAnsi(kv.Value);
+
+                // 释放由 FFI 分配的字符串内存
+                free_string(kv.Key);
+                free_string(kv.Value);
+
+                result[i] = new KeyValuePair<string, string>(key, value);
+            }
+
+            return result;
+        }
+        finally
+        {
+            Marshal.FreeHGlobal(buffer);
+        }
+    }
+
+    // 获取错误信息
+    private static string GetErrorMessage()
+    {
+        get_error_msg(out IntPtr errorMsgPtr);
+        if (errorMsgPtr == IntPtr.Zero)
+        {
+            return "Unknown error";
+        }
+
+        string errorMsg = Marshal.PtrToStringAnsi(errorMsgPtr);
+        free_string(errorMsgPtr); // 释放错误信息字符串
+        return errorMsg;
+    }
+}

easytier-contrib/easytier-ffi/examples/example_ffi_call.c

@@ -0,0 +1,100 @@
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <stdbool.h>
+#include <unistd.h> // for sleep
+
+// FFI struct and function declarations
+typedef struct {
+    const char* key;
+    const char* value;
+} KeyValuePair;
+
+typedef void (*config_server_event_callback)(
+    const char* event_json,
+    void* user_data
+);
+
+extern int parse_config(const char* cfg_str);
+extern int run_network_instance(const char* cfg_str);
+extern void get_error_msg(const char** out);
+extern void free_string(const char* s);
+extern int collect_network_infos(KeyValuePair* infos, size_t max_length);
+extern int start_config_server_client(
+    const char* config_server_url,
+    const char* hostname,
+    const char* machine_id,
+    bool secure_mode,
+    config_server_event_callback callback,
+    void* user_data
+);
+extern int stop_config_server_client(void);
+extern int is_config_server_client_connected(void);
+
+static void on_config_server_event(const char* event_json, void* user_data) {
+    (void)user_data;
+    printf("config server event: %s\n", event_json);
+}
+
+int main() {
+    const char* config = "inst_name = \"test\"\nnetwork = \"test_network\"\n";
+    int ret;
+
+    // 调用 parse_config
+    ret = parse_config(config);
+    if (ret != 0) {
+        const char* err = NULL;
+        get_error_msg(&err);
+        if (err) {
+            printf("parse_config error: %s\n", err);
+            free_string(err);
+        }
+        return 1;
+    }
+    printf("parse_config success\n");
+
+    // 调用 run_network_instance
+    ret = run_network_instance(config);
+    if (ret != 0) {
+        const char* err = NULL;
+        get_error_msg(&err);
+        if (err) {
+            printf("run_network_instance error: %s\n", err);
+            free_string(err);
+        }
+        return 1;
+    }
+    printf("run_network_instance success\n");
+
+    // 周期性调用 collect_network_infos 并打印
+    const size_t max_infos = 8;
+    KeyValuePair* infos = (KeyValuePair*)malloc(sizeof(KeyValuePair) * max_infos);
+    if (!infos) {
+        fprintf(stderr, "malloc failed\n");
+        return 1;
+    }
+
+    for (int i = 0; i < 5; ++i) { // 循环5次作为示例
+        memset(infos, 0, sizeof(KeyValuePair) * max_infos);
+        int count = collect_network_infos(infos, max_infos);
+        if (count < 0) {
+            const char* err = NULL;
+            get_error_msg(&err);
+            if (err) {
+                printf("collect_network_infos error: %s\n", err);
+                free_string(err);
+            }
+            break;
+        }
+        printf("collect_network_infos: %d instance(s)\n", count);
+        for (int j = 0; j < count; ++j) {
+            printf("  [%d] key: %s\n      value: %s\n", j, infos[j].key, infos[j].value);
+            free_string(infos[j].key);
+            free_string(infos[j].value);
+        }
+        sleep(1);
+    }
+    free(infos);
+
+    return 0;
+}

easytier-contrib/easytier-ffi/examples/go/go.sum

@@ -0,0 +1,2 @@
+github.com/go-webgpu/goffi v0.4.1 h1:2hQH5XXloxTyTtIleYv+Rajlwzp6UOETURhSZ5+zJxU=
+github.com/go-webgpu/goffi v0.4.1/go.mod h1:wfoxNsJkU+5RFbV1kNN1kunhc1lFHuJKK3zpgx08/uM=

easytier-contrib/easytier-ffi/src/config_server.rs

@@ -0,0 +1,482 @@
+use std::{
+    cell::Cell,
+    collections::HashSet,
+    ffi::{CString, c_char, c_int, c_void},
+    sync::{
+        Arc, Mutex,
+        atomic::{AtomicBool, Ordering},
+    },
+};
+
+use easytier::{
+    common::{
+        MachineIdOptions,
+        config::{ConfigLoader as _, TomlConfigLoader},
+    },
+    web_client::{WebClient, WebClientHooks, parse_config_server_endpoint, run_web_client},
+};
+use uuid::Uuid;
+
+use crate::{
+    data_plane::remove_data_plane_sessions_by_instance_ids,
+    error::set_error_msg,
+    state::{ffi_context, resolve_instance_id_by_name},
+    strings::{c_str_to_string, optional_c_str_to_string},
+    types::ConfigServerEventCallback,
+};
+
+thread_local! {
+    static IN_CONFIG_SERVER_CALLBACK: Cell<bool> = const { Cell::new(false) };
+}
+
+static CONFIG_SERVER_CLIENT: once_cell::sync::Lazy<Mutex<Option<ManagedConfigServerClient>>> =
+    once_cell::sync::Lazy::new(|| Mutex::new(None));
+static CONFIG_SERVER_CLIENT_ACTIVE: once_cell::sync::Lazy<AtomicBool> =
+    once_cell::sync::Lazy::new(|| AtomicBool::new(false));
+static CONFIG_SERVER_CLIENT_STOPPING: once_cell::sync::Lazy<AtomicBool> =
+    once_cell::sync::Lazy::new(|| AtomicBool::new(false));
+static LAST_CONFIG_SERVER_CALLBACK_ERROR: once_cell::sync::Lazy<Mutex<Option<String>>> =
+    once_cell::sync::Lazy::new(|| Mutex::new(None));
+
+pub(crate) struct ConfigServerCallbackScope;
+
+impl ConfigServerCallbackScope {
+    pub(crate) fn enter() -> Self {
+        IN_CONFIG_SERVER_CALLBACK.with(|in_callback| in_callback.set(true));
+        Self
+    }
+}
+
+impl Drop for ConfigServerCallbackScope {
+    fn drop(&mut self) {
+        IN_CONFIG_SERVER_CALLBACK.with(|in_callback| in_callback.set(false));
+    }
+}
+
+pub fn in_config_server_callback() -> bool {
+    IN_CONFIG_SERVER_CALLBACK.with(Cell::get)
+}
+
+fn config_server_machine_id_options(machine_id: String) -> MachineIdOptions {
+    MachineIdOptions {
+        explicit_machine_id: Some(machine_id),
+        state_dir: None,
+    }
+}
+
+pub fn validate_config_server_client_options(
+    config_server_url_s: &str,
+    machine_id: &str,
+) -> Result<(), String> {
+    if machine_id.trim().is_empty() {
+        return Err("machine_id is empty".to_string());
+    }
+
+    parse_config_server_endpoint(config_server_url_s)
+        .map(|_| ())
+        .map_err(|error| error.to_string())
+}
+
+struct ManagedConfigServerClient {
+    client: WebClient,
+    hooks: Arc<ManagedConfigServerClientHooks>,
+}
+
+pub(crate) struct ManagedConfigServerClientHooks {
+    pub(crate) instance_ids: Mutex<HashSet<Uuid>>,
+    callback_delivery: Mutex<()>,
+    stopping: AtomicBool,
+    callback: ConfigServerEventCallback,
+    user_data: usize,
+}
+
+impl ManagedConfigServerClientHooks {
+    pub(crate) fn new(callback: ConfigServerEventCallback, user_data: *mut c_void) -> Self {
+        Self {
+            instance_ids: Mutex::new(HashSet::new()),
+            callback_delivery: Mutex::new(()),
+            stopping: AtomicBool::new(false),
+            callback,
+            user_data: user_data as usize,
+        }
+    }
+
+    #[cfg(test)]
+    pub(crate) fn tracked_instance_ids(&self) -> Vec<Uuid> {
+        self.instance_ids
+            .lock()
+            .map(|guard| guard.iter().copied().collect())
+            .unwrap_or_default()
+    }
+
+    fn remove_tracked_instance_ids(&self, ids: &[Uuid]) -> Result<Vec<Uuid>, String> {
+        let mut guard = self.instance_ids.lock().map_err(|err| err.to_string())?;
+        Ok(ids
+            .iter()
+            .filter_map(|id| guard.remove(id).then_some(*id))
+            .collect())
+    }
+
+    fn validate_instance_name(&self, inst_name: &str, inst_id: Uuid) -> Result<(), String> {
+        if let Some(existing_id) =
+            resolve_instance_id_by_name(inst_name).map_err(|error| error.to_string())?
+            && existing_id != inst_id
+        {
+            return Err(format!("instance name {} already exists", inst_name));
+        }
+
+        Ok(())
+    }
+
+    pub(crate) fn start_stopping(&self) -> Vec<Uuid> {
+        let _delivery_guard = if in_config_server_callback() {
+            None
+        } else {
+            self.callback_delivery.lock().ok()
+        };
+        let mut guard = match self.instance_ids.lock() {
+            Ok(guard) => guard,
+            Err(_) => return Vec::new(),
+        };
+        self.stopping.store(true, Ordering::Release);
+        guard.drain().collect()
+    }
+
+    pub(crate) fn note_callback_error(&self, error: String) {
+        log::warn!("config server event callback failed: {}", error);
+        if let Ok(mut guard) = LAST_CONFIG_SERVER_CALLBACK_ERROR.lock() {
+            *guard = Some(error);
+        }
+    }
+
+    fn emit_event_with_delivery_locked(
+        &self,
+        event: &str,
+        instance_id: Uuid,
+    ) -> Result<(), String> {
+        if self.stopping.load(Ordering::Acquire) {
+            return Ok(());
+        }
+
+        let Some(callback) = self.callback else {
+            return Ok(());
+        };
+        let instance_name = ffi_context()
+            .manager
+            .instance(instance_id)
+            .map(|instance| instance.instance_name().to_owned())
+            .unwrap_or_default();
+        let network_name = ffi_context()
+            .manager
+            .config(instance_id)
+            .map(|config| config.get_network_identity().network_name)
+            .unwrap_or_default();
+        let event_json = serde_json::json!({
+            "event": event,
+            "success": true,
+            "instance_id": instance_id.to_string(),
+            "instance_name": instance_name,
+            "network_name": network_name,
+            "error": null,
+        })
+        .to_string();
+        let event_json = CString::new(event_json).map_err(|err| err.to_string())?;
+        let _callback_scope = ConfigServerCallbackScope::enter();
+        unsafe {
+            callback(event_json.as_ptr(), self.user_data as *mut c_void);
+        }
+        Ok(())
+    }
+
+    fn emit_event(&self, event: &str, instance_id: Uuid) -> Result<(), String> {
+        let _delivery_guard = self
+            .callback_delivery
+            .lock()
+            .map_err(|err| err.to_string())?;
+        self.emit_event_with_delivery_locked(event, instance_id)
+    }
+
+    fn wait_for_callback_delivery(&self) {
+        if in_config_server_callback() {
+            return;
+        }
+
+        if let Ok(guard) = self.callback_delivery.lock() {
+            drop(guard);
+        }
+    }
+}
+
+#[async_trait::async_trait]
+impl WebClientHooks for ManagedConfigServerClientHooks {
+    fn manages_remote_config_instances(&self) -> bool {
+        true
+    }
+
+    async fn pre_run_network_instance(&self, cfg: &TomlConfigLoader) -> Result<(), String> {
+        if self.stopping.load(Ordering::Acquire) {
+            return Err("config server client is stopping".to_string());
+        }
+
+        let inst_name = cfg.get_inst_name();
+        let inst_id = cfg.get_id();
+
+        self.validate_instance_name(&inst_name, inst_id)
+    }
+
+    async fn post_run_network_instance(&self, id: &Uuid) -> Result<(), String> {
+        let _delivery_guard = self
+            .callback_delivery
+            .lock()
+            .map_err(|err| err.to_string())?;
+        if self.stopping.load(Ordering::Acquire) {
+            return Err("config server client is stopping".to_string());
+        }
+        let Some(inst_name) = ffi_context()
+            .manager
+            .instance(*id)
+            .map(|instance| instance.instance_name().to_owned())
+        else {
+            return Err(format!("instance {} not found after start", id));
+        };
+
+        self.instance_ids
+            .lock()
+            .map_err(|err| err.to_string())?
+            .insert(*id);
+        if let Err(error) = self.validate_instance_name(&inst_name, *id) {
+            self.remove_tracked_instance_ids(&[*id])?;
+            return Err(error);
+        }
+
+        remove_data_plane_sessions_by_instance_ids(&[*id]);
+
+        if let Err(err) = self.emit_event_with_delivery_locked("run_network_instance", *id) {
+            self.note_callback_error(err);
+        }
+        Ok(())
+    }
+
+    async fn post_remove_network_instances(&self, ids: &[Uuid]) -> Result<(), String> {
+        let removed_ids = self.remove_tracked_instance_ids(ids)?;
+        remove_data_plane_sessions_by_instance_ids(&removed_ids);
+
+        for id in removed_ids {
+            if let Err(err) = self.emit_event("delete_network_instance", id) {
+                self.note_callback_error(err);
+            }
+        }
+        Ok(())
+    }
+}
+
+pub(crate) fn remove_config_server_tracked_instance_ids(ids: &[Uuid]) {
+    if ids.is_empty() {
+        return;
+    }
+
+    if let Ok(guard) = CONFIG_SERVER_CLIENT.lock()
+        && let Some(managed) = guard.as_ref()
+        && let Err(err) = managed.hooks.remove_tracked_instance_ids(ids)
+    {
+        log::warn!("failed to remove config server tracked ids: {}", err);
+    }
+}
+
+pub(crate) fn wait_for_config_server_delivery() {
+    let hooks = CONFIG_SERVER_CLIENT
+        .lock()
+        .ok()
+        .and_then(|guard| guard.as_ref().map(|managed| managed.hooks.clone()));
+    if let Some(hooks) = hooks {
+        hooks.wait_for_callback_delivery();
+    }
+}
+
+pub(crate) fn last_callback_error() -> Option<String> {
+    LAST_CONFIG_SERVER_CALLBACK_ERROR
+        .lock()
+        .ok()
+        .and_then(|guard| guard.clone())
+}
+
+pub(crate) fn clear_last_callback_error() {
+    if let Ok(mut guard) = LAST_CONFIG_SERVER_CALLBACK_ERROR.lock() {
+        *guard = None;
+    }
+}
+
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) fn is_config_server_active_or_stopping() -> bool {
+    CONFIG_SERVER_CLIENT_ACTIVE.load(Ordering::Acquire)
+        || CONFIG_SERVER_CLIENT_STOPPING.load(Ordering::Acquire)
+}
+
+#[cfg(test)]
+pub(crate) fn set_active_for_test(active: bool) {
+    CONFIG_SERVER_CLIENT_ACTIVE.store(active, Ordering::Release);
+}
+
+/// # Safety
+/// Start the config server client.
+///
+/// `config_server_url` must be a valid null-terminated UTF-8 string.
+/// `hostname` may be null; if non-null it must be a valid null-terminated UTF-8 string.
+/// `machine_id` must be a valid null-terminated UTF-8 string.
+/// `event_json` passed to `callback` is valid only during that callback invocation.
+pub(crate) unsafe fn start_config_server_client(
+    config_server_url: *const c_char,
+    hostname: *const c_char,
+    machine_id: *const c_char,
+    secure_mode: bool,
+    callback: ConfigServerEventCallback,
+    user_data: *mut c_void,
+) -> c_int {
+    if in_config_server_callback() {
+        set_error_msg("cannot start config server client from config server callback");
+        return -1;
+    }
+
+    let config_server_url = match unsafe { c_str_to_string(config_server_url, "config_server_url") }
+    {
+        Ok(value) => value,
+        Err(err) => {
+            set_error_msg(&err);
+            return -1;
+        }
+    };
+    let hostname = match unsafe { optional_c_str_to_string(hostname, "hostname") } {
+        Ok(value) => value,
+        Err(err) => {
+            set_error_msg(&err);
+            return -1;
+        }
+    };
+    let machine_id = match unsafe { c_str_to_string(machine_id, "machine_id") } {
+        Err(err) => {
+            set_error_msg(&err);
+            return -1;
+        }
+        Ok(value) => value,
+    };
+    if let Err(err) = validate_config_server_client_options(&config_server_url, &machine_id) {
+        set_error_msg(&err);
+        return -1;
+    }
+
+    let mut guard = match CONFIG_SERVER_CLIENT.lock() {
+        Ok(guard) => guard,
+        Err(err) => {
+            set_error_msg(&format!("failed to lock config server client: {}", err));
+            return -1;
+        }
+    };
+
+    if guard.is_some() {
+        set_error_msg("config server client already exists");
+        return -1;
+    }
+    if CONFIG_SERVER_CLIENT_STOPPING.load(Ordering::Acquire) {
+        set_error_msg("config server client is stopping");
+        return -1;
+    }
+    clear_last_callback_error();
+
+    #[cfg(feature = "ffi-dataplane")]
+    let data_plane_usage_guard = match crate::data_plane::lock_for_config_server_start() {
+        Ok(guard) => guard,
+        Err(err) => {
+            set_error_msg(&err);
+            return -1;
+        }
+    };
+
+    CONFIG_SERVER_CLIENT_ACTIVE.store(true, Ordering::Release);
+    #[cfg(feature = "ffi-dataplane")]
+    drop(data_plane_usage_guard);
+
+    let hooks = Arc::new(ManagedConfigServerClientHooks::new(callback, user_data));
+    let client = match ffi_context().runtime.block_on(run_web_client(
+        &config_server_url,
+        config_server_machine_id_options(machine_id),
+        hostname,
+        secure_mode,
+        ffi_context().manager.clone(),
+        Some(hooks.clone()),
+    )) {
+        Ok(client) => client,
+        Err(err) => {
+            CONFIG_SERVER_CLIENT_ACTIVE.store(false, Ordering::Release);
+            set_error_msg(&format!("failed to start config server client: {}", err));
+            return -1;
+        }
+    };
+
+    *guard = Some(ManagedConfigServerClient { client, hooks });
+    0
+}
+
+pub(crate) fn stop_config_server_client() -> c_int {
+    if in_config_server_callback() {
+        set_error_msg("cannot stop config server client from config server callback");
+        return -1;
+    }
+
+    let guard = match CONFIG_SERVER_CLIENT.lock() {
+        Ok(guard) => guard,
+        Err(err) => {
+            set_error_msg(&format!("failed to lock config server client: {}", err));
+            return -1;
+        }
+    };
+
+    let Some(managed) = guard.as_ref() else {
+        CONFIG_SERVER_CLIENT_ACTIVE.store(false, Ordering::Release);
+        return 0;
+    };
+    if CONFIG_SERVER_CLIENT_STOPPING.swap(true, Ordering::AcqRel) {
+        set_error_msg("config server client is stopping");
+        return -1;
+    }
+    let hooks = managed.hooks.clone();
+    // Keep the client discoverable until the canonical transaction drains its
+    // tracking. Earlier removals must still retire IDs from these same hooks.
+    drop(guard);
+
+    let delete_result = ffi_context().runtime.block_on(
+        ffi_context()
+            .process_management
+            .delete_owned_network_instances_selected_by(|| hooks.start_stopping()),
+    );
+    let managed = match CONFIG_SERVER_CLIENT.lock() {
+        Ok(mut guard) => guard.take(),
+        Err(err) => {
+            hooks.wait_for_callback_delivery();
+            CONFIG_SERVER_CLIENT_ACTIVE.store(false, Ordering::Release);
+            set_error_msg(&format!("failed to lock config server client: {err}"));
+            return -1;
+        }
+    };
+    drop(managed);
+    hooks.wait_for_callback_delivery();
+    CONFIG_SERVER_CLIENT_ACTIVE.store(false, Ordering::Release);
+    CONFIG_SERVER_CLIENT_STOPPING.store(false, Ordering::Release);
+
+    if let Err(err) = delete_result {
+        set_error_msg(&format!(
+            "failed to delete config server instances: {}",
+            err
+        ));
+        return -1;
+    }
+    0
+}
+
+pub(crate) fn is_config_server_client_connected() -> c_int {
+    CONFIG_SERVER_CLIENT
+        .lock()
+        .ok()
+        .and_then(|guard| guard.as_ref().map(|managed| managed.client.is_connected()))
+        .map(i32::from)
+        .unwrap_or(0)
+}

easytier-contrib/easytier-ffi/src/data_plane/abi.rs

@@ -0,0 +1,685 @@
+use std::{
+    ffi::{c_char, c_int, c_uchar},
+    net::{IpAddr, Ipv4Addr, SocketAddr},
+    ptr,
+};
+
+use easytier_core::gateway::DataPlaneErrorKind;
+
+use super::session::{self, NativeDataPlaneError, NativeDataPlaneResult};
+use crate::{
+    error::set_error_msg,
+    strings::c_str_to_string,
+    types::{DataPlaneCompletion, DataPlaneSocketAddr},
+};
+
+pub const DATA_PLANE_DEADLINE_READ: u32 = 1 << 0;
+pub const DATA_PLANE_DEADLINE_WRITE: u32 = 1 << 1;
+
+fn failure(error: NativeDataPlaneError) -> c_int {
+    set_error_msg(&error.message);
+    -(error.kind as c_int)
+}
+
+fn status(result: NativeDataPlaneResult<()>) -> c_int {
+    match result {
+        Ok(()) => 0,
+        Err(error) => failure(error),
+    }
+}
+
+fn invalid(message: impl Into<String>) -> NativeDataPlaneError {
+    NativeDataPlaneError {
+        kind: DataPlaneErrorKind::Io,
+        message: message.into(),
+    }
+}
+
+fn socket_addr(address: DataPlaneSocketAddr) -> NativeDataPlaneResult<SocketAddr> {
+    let ip = match address.family {
+        4 => IpAddr::V4(Ipv4Addr::new(
+            address.address[0],
+            address.address[1],
+            address.address[2],
+            address.address[3],
+        )),
+        6 => {
+            return Err(NativeDataPlaneError {
+                kind: DataPlaneErrorKind::AddressFamilyUnsupported,
+                message: "IPv6 is not supported by data-plane ABI v3".to_string(),
+            });
+        }
+        family => {
+            return Err(NativeDataPlaneError {
+                kind: DataPlaneErrorKind::AddressFamilyUnsupported,
+                message: format!("unsupported address family {family}"),
+            });
+        }
+    };
+    Ok(SocketAddr::new(ip, address.port))
+}
+
+fn ffi_socket_addr(address: SocketAddr) -> DataPlaneSocketAddr {
+    match address.ip() {
+        IpAddr::V4(ip) => {
+            let mut bytes = [0; 16];
+            bytes[..4].copy_from_slice(&ip.octets());
+            DataPlaneSocketAddr {
+                family: 4,
+                port: address.port(),
+                address: bytes,
+            }
+        }
+        IpAddr::V6(ip) => DataPlaneSocketAddr {
+            family: 6,
+            port: address.port(),
+            address: ip.octets(),
+        },
+    }
+}
+
+unsafe fn copy_input(ptr: *const c_uchar, len: u32) -> NativeDataPlaneResult<Vec<u8>> {
+    if len == 0 {
+        return Ok(Vec::new());
+    }
+    if ptr.is_null() {
+        return Err(invalid("input buffer is null"));
+    }
+    Ok(unsafe { std::slice::from_raw_parts(ptr, len as usize) }.to_vec())
+}
+
+unsafe fn output_slice<'a>(ptr: *mut c_uchar, len: u32) -> NativeDataPlaneResult<&'a mut [u8]> {
+    if len == 0 {
+        return Ok(&mut []);
+    }
+    if ptr.is_null() {
+        return Err(invalid("output buffer is null"));
+    }
+    Ok(unsafe { std::slice::from_raw_parts_mut(ptr, len as usize) })
+}
+
+fn write_operation(
+    out_operation: *mut u64,
+    submit: impl FnOnce() -> NativeDataPlaneResult<u64>,
+) -> c_int {
+    if out_operation.is_null() {
+        return failure(invalid("out_operation is null"));
+    }
+    match submit() {
+        Ok(operation) => {
+            unsafe {
+                *out_operation = operation;
+            }
+            0
+        }
+        Err(error) => failure(error),
+    }
+}
+
+/// # Safety
+///
+/// If non-null, `inst_name` must point to a valid NUL-terminated string.
+/// `out_session` must be null or point to writable, properly aligned storage
+/// for one `u64`.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_session_open(
+    inst_name: *const c_char,
+    out_session: *mut u64,
+) -> c_int {
+    if out_session.is_null() {
+        return failure(invalid("out_session is null"));
+    }
+    unsafe {
+        *out_session = 0;
+    }
+    let inst_name = match unsafe { c_str_to_string(inst_name, "inst_name") } {
+        Ok(inst_name) => inst_name,
+        Err(error) => return failure(invalid(error)),
+    };
+    match session::open(&inst_name) {
+        Ok(handle) => {
+            unsafe {
+                *out_session = handle;
+            }
+            0
+        }
+        Err(error) => failure(error),
+    }
+}
+
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub extern "C" fn data_plane_session_close(session: u64) -> c_int {
+    status(super::session::close(session))
+}
+
+/// # Safety
+///
+/// `out_operation` must be null or point to writable, properly aligned
+/// storage for one `u64`.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_connect_submit(
+    session: u64,
+    peer_addr: DataPlaneSocketAddr,
+    timeout_ms: u64,
+    out_operation: *mut u64,
+) -> c_int {
+    let peer_addr = match socket_addr(peer_addr) {
+        Ok(address) => address,
+        Err(error) => return failure(error),
+    };
+    write_operation(out_operation, || {
+        super::session::submit_tcp_connect(session, peer_addr, timeout_ms)
+    })
+}
+
+/// # Safety
+///
+/// `out_operation` must be null or point to writable, properly aligned
+/// storage for one `u64`.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_bind_submit(
+    session: u64,
+    local_port: u16,
+    timeout_ms: u64,
+    out_operation: *mut u64,
+) -> c_int {
+    write_operation(out_operation, || {
+        super::session::submit_tcp_bind(session, local_port, timeout_ms)
+    })
+}
+
+/// # Safety
+///
+/// `out_operation` must be null or point to writable, properly aligned
+/// storage for one `u64`.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_accept_submit(
+    session: u64,
+    listener: u64,
+    timeout_ms: u64,
+    out_operation: *mut u64,
+) -> c_int {
+    write_operation(out_operation, || {
+        super::session::submit_tcp_accept(session, listener, timeout_ms)
+    })
+}
+
+/// # Safety
+///
+/// `out_operation` must be null or point to writable, properly aligned
+/// storage for one `u64`.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_read_submit(
+    session: u64,
+    stream: u64,
+    max_len: u32,
+    out_operation: *mut u64,
+) -> c_int {
+    write_operation(out_operation, || {
+        super::session::submit_tcp_read(session, stream, max_len)
+    })
+}
+
+/// # Safety
+///
+/// When `len` is nonzero, `data` must point to `len` readable bytes.
+/// `out_operation` must be null or point to writable, properly aligned
+/// storage for one `u64`.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_write_submit(
+    session: u64,
+    stream: u64,
+    data: *const c_uchar,
+    len: u32,
+    out_operation: *mut u64,
+) -> c_int {
+    let data = match unsafe { copy_input(data, len) } {
+        Ok(data) => data,
+        Err(error) => return failure(error),
+    };
+    write_operation(out_operation, || {
+        super::session::submit_tcp_write(session, stream, data)
+    })
+}
+
+/// # Safety
+///
+/// `out_operation` must be null or point to writable, properly aligned
+/// storage for one `u64`.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_udp_bind_submit(
+    session: u64,
+    local_port: u16,
+    timeout_ms: u64,
+    out_operation: *mut u64,
+) -> c_int {
+    write_operation(out_operation, || {
+        super::session::submit_udp_bind(session, local_port, timeout_ms)
+    })
+}
+
+/// # Safety
+///
+/// `out_operation` must be null or point to writable, properly aligned
+/// storage for one `u64`.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_udp_receive_submit(
+    session: u64,
+    socket: u64,
+    max_len: u32,
+    out_operation: *mut u64,
+) -> c_int {
+    write_operation(out_operation, || {
+        super::session::submit_udp_receive(session, socket, max_len)
+    })
+}
+
+/// # Safety
+///
+/// When `len` is nonzero, `data` must point to `len` readable bytes.
+/// `out_operation` must be null or point to writable, properly aligned
+/// storage for one `u64`.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_udp_send_submit(
+    session: u64,
+    socket: u64,
+    peer_addr: DataPlaneSocketAddr,
+    data: *const c_uchar,
+    len: u32,
+    out_operation: *mut u64,
+) -> c_int {
+    let peer_addr = match socket_addr(peer_addr) {
+        Ok(address) => address,
+        Err(error) => return failure(error),
+    };
+    let data = match unsafe { copy_input(data, len) } {
+        Ok(data) => data,
+        Err(error) => return failure(error),
+    };
+    write_operation(out_operation, || {
+        super::session::submit_udp_send(session, socket, peer_addr, data)
+    })
+}
+
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub extern "C" fn data_plane_resource_deadline_set(
+    session: u64,
+    resource: u64,
+    direction: u32,
+    timeout_ms: u64,
+) -> c_int {
+    let read = direction & DATA_PLANE_DEADLINE_READ != 0;
+    let write = direction & DATA_PLANE_DEADLINE_WRITE != 0;
+    if direction == 0 || direction & !(DATA_PLANE_DEADLINE_READ | DATA_PLANE_DEADLINE_WRITE) != 0 {
+        return failure(invalid(format!("invalid deadline direction {direction}")));
+    }
+    status(super::session::set_resource_deadline(
+        session, resource, read, write, timeout_ms,
+    ))
+}
+
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub extern "C" fn data_plane_operation_cancel(session: u64, operation: u64) -> c_int {
+    status(super::session::cancel_operation(session, operation))
+}
+
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub extern "C" fn data_plane_operation_free(session: u64, operation: u64) -> c_int {
+    status(super::session::free_operation(session, operation))
+}
+
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub extern "C" fn data_plane_resource_close(session: u64, resource: u64) -> c_int {
+    status(super::session::close_resource(session, resource))
+}
+
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub extern "C" fn data_plane_completion_wait(session: u64, timeout_ms: u64) -> c_int {
+    match super::session::completion_wait(session, timeout_ms) {
+        Ok(true) => 1,
+        Ok(false) => 0,
+        Err(error) => failure(error),
+    }
+}
+
+/// # Safety
+///
+/// When `capacity` is nonzero, `completions` must point to writable, properly
+/// aligned storage for `capacity` consecutive [`DataPlaneCompletion`] values.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_completion_drain(
+    session: u64,
+    completions: *mut DataPlaneCompletion,
+    capacity: u32,
+) -> c_int {
+    if capacity != 0 && completions.is_null() {
+        return failure(invalid("completions is null"));
+    }
+    let drained = match super::session::drain_completions(session, capacity as usize) {
+        Ok(drained) => drained,
+        Err(error) => return failure(error),
+    };
+    for (index, completion) in drained.iter().enumerate() {
+        unsafe {
+            ptr::write(
+                completions.add(index),
+                DataPlaneCompletion {
+                    operation_id: completion.operation_id.get(),
+                    operation_kind: completion.kind as u16,
+                    status: completion.status.code(),
+                },
+            );
+        }
+    }
+    drained.len() as c_int
+}
+
+/// # Safety
+///
+/// `out_size` must be null or point to writable, properly aligned storage for
+/// one `u32`.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_result_size(
+    session: u64,
+    operation: u64,
+    out_size: *mut u32,
+) -> c_int {
+    if out_size.is_null() {
+        return failure(invalid("out_size is null"));
+    }
+    match super::session::result_size(session, operation) {
+        Ok(size) => match u32::try_from(size) {
+            Ok(size) => {
+                unsafe {
+                    *out_size = size;
+                }
+                0
+            }
+            Err(_) => failure(invalid("data-plane result size exceeds u32")),
+        },
+        Err(error) => failure(error),
+    }
+}
+
+/// # Safety
+///
+/// Each output pointer must be null or point to writable, properly aligned
+/// storage for its pointee type. Non-null output locations must not overlap.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_connect_result_take(
+    session: u64,
+    operation: u64,
+    out_stream: *mut u64,
+    out_local_addr: *mut DataPlaneSocketAddr,
+    out_peer_addr: *mut DataPlaneSocketAddr,
+) -> c_int {
+    if out_stream.is_null() || out_local_addr.is_null() || out_peer_addr.is_null() {
+        return failure(invalid("TCP connect result output pointer is null"));
+    }
+    match super::session::take_tcp_connect(session, operation) {
+        Ok(result) => {
+            unsafe {
+                *out_stream = result.stream;
+                *out_local_addr = ffi_socket_addr(result.local_addr);
+                *out_peer_addr = ffi_socket_addr(result.peer_addr);
+            }
+            0
+        }
+        Err(error) => failure(error),
+    }
+}
+
+/// # Safety
+///
+/// Each output pointer must be null or point to writable, properly aligned
+/// storage for its pointee type. Non-null output locations must not overlap.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_bind_result_take(
+    session: u64,
+    operation: u64,
+    out_listener: *mut u64,
+    out_local_addr: *mut DataPlaneSocketAddr,
+) -> c_int {
+    if out_listener.is_null() || out_local_addr.is_null() {
+        return failure(invalid("TCP bind result output pointer is null"));
+    }
+    match super::session::take_tcp_bind(session, operation) {
+        Ok(result) => {
+            unsafe {
+                *out_listener = result.listener;
+                *out_local_addr = ffi_socket_addr(result.local_addr);
+            }
+            0
+        }
+        Err(error) => failure(error),
+    }
+}
+
+/// # Safety
+///
+/// Each output pointer must be null or point to writable, properly aligned
+/// storage for its pointee type. Non-null output locations must not overlap.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_accept_result_take(
+    session: u64,
+    operation: u64,
+    out_stream: *mut u64,
+    out_local_addr: *mut DataPlaneSocketAddr,
+    out_peer_addr: *mut DataPlaneSocketAddr,
+) -> c_int {
+    if out_stream.is_null() || out_local_addr.is_null() || out_peer_addr.is_null() {
+        return failure(invalid("TCP accept result output pointer is null"));
+    }
+    match super::session::take_tcp_accept(session, operation) {
+        Ok(result) => {
+            unsafe {
+                *out_stream = result.stream;
+                *out_local_addr = ffi_socket_addr(result.local_addr);
+                *out_peer_addr = ffi_socket_addr(result.peer_addr);
+            }
+            0
+        }
+        Err(error) => failure(error),
+    }
+}
+
+/// # Safety
+///
+/// When `capacity` is nonzero, `data` must point to `capacity` writable bytes.
+/// Each scalar output pointer must be null or point to writable, properly
+/// aligned storage for its pointee type. Non-null output ranges must not
+/// overlap.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_read_result_take(
+    session: u64,
+    operation: u64,
+    data: *mut c_uchar,
+    capacity: u32,
+    out_len: *mut u32,
+    out_eof: *mut bool,
+) -> c_int {
+    if out_len.is_null() || out_eof.is_null() {
+        return failure(invalid("TCP read result output pointer is null"));
+    }
+    let data = match unsafe { output_slice(data, capacity) } {
+        Ok(data) => data,
+        Err(error) => return failure(error),
+    };
+    match super::session::take_tcp_read(session, operation, data) {
+        Ok(result) => {
+            unsafe {
+                *out_len = result.len as u32;
+                *out_eof = result.eof;
+            }
+            0
+        }
+        Err(error) => failure(error),
+    }
+}
+
+/// # Safety
+///
+/// `out_len` must be null or point to writable, properly aligned storage for
+/// one `u32`.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_tcp_write_result_take(
+    session: u64,
+    operation: u64,
+    out_len: *mut u32,
+) -> c_int {
+    if out_len.is_null() {
+        return failure(invalid("out_len is null"));
+    }
+    match super::session::take_tcp_write(session, operation) {
+        Ok(len) => match u32::try_from(len) {
+            Ok(len) => {
+                unsafe {
+                    *out_len = len;
+                }
+                0
+            }
+            Err(_) => failure(invalid("TCP write result exceeds u32")),
+        },
+        Err(error) => failure(error),
+    }
+}
+
+/// # Safety
+///
+/// Each output pointer must be null or point to writable, properly aligned
+/// storage for its pointee type. Non-null output locations must not overlap.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_udp_bind_result_take(
+    session: u64,
+    operation: u64,
+    out_socket: *mut u64,
+    out_local_addr: *mut DataPlaneSocketAddr,
+) -> c_int {
+    if out_socket.is_null() || out_local_addr.is_null() {
+        return failure(invalid("UDP bind result output pointer is null"));
+    }
+    match super::session::take_udp_bind(session, operation) {
+        Ok(result) => {
+            unsafe {
+                *out_socket = result.socket;
+                *out_local_addr = ffi_socket_addr(result.local_addr);
+            }
+            0
+        }
+        Err(error) => failure(error),
+    }
+}
+
+/// # Safety
+///
+/// When `capacity` is nonzero, `data` must point to `capacity` writable bytes.
+/// Each scalar output pointer must be null or point to writable, properly
+/// aligned storage for its pointee type. Non-null output ranges must not
+/// overlap.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_udp_receive_result_take(
+    session: u64,
+    operation: u64,
+    data: *mut c_uchar,
+    capacity: u32,
+    out_len: *mut u32,
+    out_peer_addr: *mut DataPlaneSocketAddr,
+    out_truncated: *mut bool,
+) -> c_int {
+    if out_len.is_null() || out_peer_addr.is_null() || out_truncated.is_null() {
+        return failure(invalid("UDP receive result output pointer is null"));
+    }
+    let data = match unsafe { output_slice(data, capacity) } {
+        Ok(data) => data,
+        Err(error) => return failure(error),
+    };
+    match super::session::take_udp_receive(session, operation, data) {
+        Ok(result) => {
+            unsafe {
+                *out_len = result.len as u32;
+                *out_peer_addr = ffi_socket_addr(result.peer_addr);
+                *out_truncated = result.truncated;
+            }
+            0
+        }
+        Err(error) => failure(error),
+    }
+}
+
+/// # Safety
+///
+/// `out_len` must be null or point to writable, properly aligned storage for
+/// one `u32`.
+#[cfg_attr(feature = "c-abi", unsafe(no_mangle))]
+pub unsafe extern "C" fn data_plane_udp_send_result_take(
+    session: u64,
+    operation: u64,
+    out_len: *mut u32,
+) -> c_int {
+    if out_len.is_null() {
+        return failure(invalid("out_len is null"));
+    }
+    match super::session::take_udp_send(session, operation) {
+        Ok(len) => match u32::try_from(len) {
+            Ok(len) => {
+                unsafe {
+                    *out_len = len;
+                }
+                0
+            }
+            Err(_) => failure(invalid("UDP send result exceeds u32")),
+        },
+        Err(error) => failure(error),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn socket_address_round_trip() {
+        let address = "127.0.0.1:1234".parse::<SocketAddr>().unwrap();
+        assert_eq!(socket_addr(ffi_socket_addr(address)).unwrap(), address);
+    }
+
+    #[test]
+    fn ipv6_is_rejected_by_v3() {
+        let error = socket_addr(ffi_socket_addr(
+            "[2001:db8::1]:4321".parse::<SocketAddr>().unwrap(),
+        ))
+        .unwrap_err();
+        assert_eq!(error.kind, DataPlaneErrorKind::AddressFamilyUnsupported);
+    }
+
+    #[test]
+    fn invalid_address_family_is_stable() {
+        let error = socket_addr(DataPlaneSocketAddr {
+            family: 9,
+            ..Default::default()
+        })
+        .unwrap_err();
+        assert_eq!(error.kind, DataPlaneErrorKind::AddressFamilyUnsupported);
+    }
+
+    #[test]
+    fn invalid_deadline_direction_is_rejected_before_session_lookup() {
+        let invalid = -(DataPlaneErrorKind::Io as c_int);
+        assert_eq!(data_plane_resource_deadline_set(u64::MAX, 1, 0, 0), invalid);
+        assert_eq!(data_plane_resource_deadline_set(u64::MAX, 1, 4, 0), invalid);
+    }
+
+    #[test]
+    fn null_operation_output_does_not_submit() {
+        let submitted = std::cell::Cell::new(false);
+
+        assert_eq!(
+            write_operation(std::ptr::null_mut(), || {
+                submitted.set(true);
+                Ok(1)
+            }),
+            -(DataPlaneErrorKind::Io as c_int)
+        );
+        assert!(!submitted.get());
+    }
+}

easytier-contrib/easytier-ffi/src/data_plane/mod.rs

@@ -0,0 +1,16 @@
+//! Native C ABI adapter for the instance-scoped data-plane operation broker.
+
+#[cfg(feature = "ffi-dataplane")]
+mod abi;
+#[cfg(feature = "ffi-dataplane")]
+mod session;
+
+#[cfg(feature = "ffi-dataplane")]
+pub use abi::*;
+#[cfg(feature = "ffi-dataplane")]
+pub(crate) use session::{
+    lock_for_config_server_start, remove_data_plane_sessions_by_instance_ids,
+};
+
+#[cfg(not(feature = "ffi-dataplane"))]
+pub(crate) fn remove_data_plane_sessions_by_instance_ids(_ids: &[uuid::Uuid]) {}