中文 | English
基于微内核的 OpenWrt 代理与网络管理平台
独立管理 Mihomo · 多机场自动选优 · 功能插件组合 · 独立热替换
NetFleet 将订阅管理、业务分流、自动选路、DNS、透明代理和运行维护整合到同一个 LuCI 界面。原生模式直接管理 Mihomo，可在没有运行 Nikki 的 OpenWrt 设备上完成首次接入；已有 Nikki 用户也可以沿用现有环境，或通过迁移入口转到 NetFleet 原生后端。
它围绕“机场、地区、业务出口”组织网络：用实时测量选择路径，以主用、备用和直连分层处理故障。微内核负责服务组合与生命周期，订阅、策略、后端、选择、恢复和管理由功能插件提供，单台设备配置和多设备声明式部署共用同一套运行逻辑。
- 独立完成代理管理。 原生模式覆盖订阅、配置文件、DNS、透明代理、核心维护和备份恢复。
- 统一组织多个机场。 查看地区、节点、延迟与用量，设置主用和备用，让局部线路故障有替代路径。
- 按业务自动选择出口。 常规网络与有地区要求的服务可以使用不同出口能力，选择结果和切换原因可见。
- 自由组合功能插件。 服务、业务动作、配置和页面通过同一插件协议接入，支持独立安装、更新和热替换；自有与第三方开发者共用接口和工具。
- 明确切换网络运行模式。 在 OpenWrt 原生直连、Mihomo 原生代理和 NetFleet 增强代理间切换，分别控制核心、网络接管与增强调度；实际行为见运行模式。
- 复现多设备配置。 Fleet 入口按明确版本部署，在设备端校验、编译并回读结果。
| 方式 | 适用场景 | 管理分工 |
|---|---|---|
| NetFleet + Mihomo（原生） | 从零配置，或希望由 NetFleet 统一管理 | NetFleet 管理订阅、配置、核心服务、DNS 和透明代理，无需运行 Nikki 服务 |
| Nikki + Mihomo | 已有稳定 Nikki 环境，希望加入多机场选优与恢复 | Nikki 保留订阅和数据面管理，NetFleet 提供共享策略、选优与恢复事务 |
两种后端明确选择、互斥运行，迁移有独立预检和失败恢复。原生后端复用固定版本 Nikki 的配置投影与 nft 模板，保留上游来源与许可证；当前网络接入采用 TProxy。
NetFleet 把“访问需求”和“具体节点”分开管理。规则只需要选择稳定的能力，例如常规网络或具有地区要求的服务；机场和节点则作为可替换资源参与实时选择。这样一来，新增机场、节点改名或局部故障都不会迫使用户重写整套规则。
自动选择分为三层：
- 地区决定网络距离、内容可用性和连接体验；
- 机场代表相对独立的线路和额度，用于隔离故障；
- 节点由 Mihomo URLTest 在同一地区内完成快速切换。
每一轮都使用最新测量结果，并设置切换门槛，避免线路在细小延迟波动中来回跳动。历史数据用于帮助用户理解运行情况，当前选择始终以当轮可用性和实时测量为准。
NetFleet 将业务、平台能力和界面组织为功能插件。内核处理发现、服务绑定、依赖解析、调用准入和资源生命周期；订阅、选路、配置编译、恢复、后端与调度通过服务组合运行。插件可同时声明服务、CLI 命令、浏览器业务动作、配置和页面，独立安装后由宿主发现，无需为新功能修改宿主的 RPC 或导航表。
系统配置明确选择服务提供者，并支持具名实例的局部绑定与配置。同一插件可以组合出不同用途的实例；服务和页面的作用域统一管理监听、连接及清理函数，在调用结束、退出页面或卸载时撤销所属资源。管理员可在“插件与更新 → 服务组合”编辑组合 JSON，先校验依赖和预览影响，再确认应用；失败恢复原组合与资源状态。
选择算法已独立成包；存储、OpenWrt 配置和运行管理分别由平台插件提供，内核的系统操作也通过注入的宿主适配器完成。业务服务可以通过能力绑定复用，跨平台分工见平台能力边界。
插件有两种开发方式：UCode 服务插件通过声明依赖和 context.use() 组合能力；进程插件通过 Extension API v1 使用 Shell、Python 等设备支持的语言。两者共用安装目录、管理入口和软件包流程，任何符合协议的插件都能被发现、加载和热替换。
每次调用使用当前插件代码，升级先等待在途调用结束，新调用随即使用新版本。选优算法等不在 Mihomo 长期依赖链中的插件可独立更新，无需重启 Mihomo；资源插件自身或其依赖更新时，通过该资源插件的排空与恢复方法完成交接。浏览器自动发现插件清单变化，撤销旧页面并加载新版本；页面、子模块与样式使用同一代码 revision 的资源目录。
| 功能插件 | 作用 | 交付与运行方式 |
|---|---|---|
| 默认网络功能 | 订阅、编译、选优、启停、恢复、配置和调度 | opl-netfleet 组合默认产品，每个功能插件独立打包 |
| 产品界面 | 概览、出口、机场、地区、配置、组件和诊断 | product-ui 贡献七个页面，LuCI 壳只负责发现、导航和页面生命周期 |
| HTTPS 兼容 | 为指定设备和目标提供 HTTP/1.1 到 HTTP/2 的兼容转换 | 管理插件连接独立可选转换包；设备信任私有 CA 后显式接入，故障时旁路回原选路 |
| Zashboard | 查看 Mihomo 实时连接、流量、规则命中和代理组 | 独立 Dashboard 插件管理入口和资源；面板资源可单独更新，无需重启 Mihomo |
| 开发示例 | 独立服务、配置保存与可交互页面 | workspace-note 提供完整外部插件；host-info 和 device-info 分别演示最小服务组合与进程入口 |
自有和第三方开发者使用同一套脚手架、声明校验、OpenWrt 软件包和签名分发流程。可直接从插件开发与安装指南开始；服务与热替换合同见微内核与功能插件，进程接口与组件管理见模块与扩展。
UCode 运行服务在 OpenWrt 本地执行，Mihomo 负责连接和组内节点健康检查，LuCI 展示状态并提交受限操作。运行和恢复不依赖浏览器持续打开，也不要求云端控制器或 Node.js 宿主。
配置先校验、生成候选，再显式启用并检查真实运行结果。退出增强或故障恢复时优先切回可独立运行的 Recovery Profile；主动选择 OpenWrt 原生直连则直接清理自身网络接管、停止代理。恢复插件协调统一恢复路径，各资源插件承担自己的故障退出。
NetFleet 脚本与界面包为 noarch；当前随 Feed 提供的 Mihomo 核心只覆盖 ARM64
aarch64_generic。其他架构需已有兼容核心，不能把代码包可安装等同于空白设备完整支持。
安装范围以所选 Release 和软件包合同为准。
macOS 本机 MVP 的构建、使用和验证见macOS 开发指南。
它复用 NetFleet 核心业务与 React 界面组件，提供原生桌面窗口、菜单和快捷键；系统代理与 TUN 需要本机管理员授权。
提供本地 .app 和需 Developer ID 签名、公证及 VM 验收的 DMG 构建入口；
下述软件源安装命令仅适用于 OpenWrt。
两端共享检查、独立交付；版本与源码身份、候选构建及发布入口见双平台交付。
开始前，目标设备需要：
- 可用的 OpenWrt 软件包管理器；
- Mihomo 及该发布包要求的 OpenWrt 依赖；
- 原生接入：包含原生后端支持的包、可用上游 DNS 和一个有效机场订阅；接入前不得有其他代理核心占用网络；
- Nikki 接入：已正常运行的 Nikki、一份可独立使用的原生配置，以及至少一个有效订阅缓存。
在 OpenWrt 25.12 上，用一次性安装入口加入签名软件源并安装默认产品与 LuCI，软件包管理器会解析微内核和功能插件依赖：
uclient-fetch -q -O /tmp/install-netfleet.sh https://github.com/gaofeng21cn/opl-netfleet/releases/latest/download/install-netfleet.sh && sh /tmp/install-netfleet.sh需要全功能安装时，在同一安装入口选择 NETFLEET_INSTALL_PROFILE=full。可选包源必须提供
签名的 compat-packages.adb、compat-public-key.pem 与对应 APK；默认与产品包源同址，
分开托管时由 NETFLEET_COMPAT_FEED_BASE 指定。没有完整依赖时安装失败，不悄悄降为基础组合。
NETFLEET_INSTALL_PROFILE=full sh /tmp/install-netfleet.sh全功能指安装 HTTPS 引擎和 Device identity 等可选能力。HTTPS 默认关闭，保留已配置的规则和信任， 需要时从插件配置页一键开启。已有安装的功能开关不会因选择安装组合而改变。
该命令只安装 APK 公钥、软件源和程序文件，不写入 policy、订阅或 Nikki mixin，也不自动接管网络。
安装完成后，打开 LuCI 的“服务 -> NetFleet”。空白设备先选择“首次接入 Mihomo”，明确确认下载订阅及网络接管；使用已运行 Nikki 时直接进入发现。随后进入共享首次设置：
- 发现当前原生 Profile、机场缓存、地区和
MATCH主入口组； - 检查当前环境并展示推荐配置；
- 在用户确认后生成策略、编译配置并启动 NetFleet；
- 回读运行状态和保护探针结果。
整个过程由设备本地完成。订阅 URL 和令牌保存在所选后端的私有配置中，不进入 policy 或公开状态。接管后可维护机场角色、地区映射、出口能力、业务绑定、域名与网段规则、自动周期和保护探针。原生订阅地址由独立“管理订阅”入口保存；修改来源不会自动停网，更新成功前继续使用上次可用缓存。
已有 Nikki 设备需要切换后端时，在“配置 -> 基础接入”选择“迁移到 NetFleet 原生后端”。迁移前检查真实资源和业务；成功后只运行原生后端，失败恢复旧后端，不长期双写。后端迁移与普通软件升级不是同一操作。
LuCI 的“插件与更新”页显示组件安装版本、Mihomo 运行版本及关键依赖，可手动检查软件源。 “功能插件”中可安装、升级和卸载受信软件源提供的独立插件。操作前会列出实际软件包变化， 确认后在后台执行并显示进度；卸载须先禁用插件，存在服务引用时拒绝卸载，私有配置保留。 默认功能插件、可选插件和已安装的 HTTPS 运行包共用此入口。兼容依赖由 APK 解析，只替换实际变化的包。 NetFleet 按默认产品清单一起更新微内核、功能插件与 LuCI；第三方插件可以独立维护。原生后端的 Mihomo 单独确认更新，先验证当前配置，失败时恢复旧包和运行状态。不默认无人值守升级，也不升级整个系统。
同页的 Zashboard 区域独立检查和更新官方静态资源，不重启 Mihomo 或修改连接凭据。已安装版本来自有效安装记录或本地资源识别，无法识别时显示未知；检查更新后才展示可用版本。软件包、代理核心和面板资源分别确认，不隐式捆绑更新。
完整产品通过组件页升级。独立功能插件也可以直接从已配置的软件源定向更新，例如：
apk update && apk upgrade opl-netfleet-plugin-selection-algorithm升级保留现有策略、订阅缓存和系统服务绑定，软件包钩子负责代码替换前后的排空与恢复。升级后在组件页和状态页检查版本及运行结果；新配置仍通过显式应用生效。插件安装、升级和卸载步骤见开发与安装指南。
“配置 -> 网络接入”管理原生后端的 DNS、代理范围、设备规则、监听和认证，应用前校验，失败恢复原配置；不修改 OpenWrt 的 WAN/LAN 地址或默认路由。业务流量的域名与网段分流在“业务规则”中配置。
“配置 -> 配置文件与备份”用于导入、下载和编辑本地配置，以及导出或恢复 NetFleet 备份。使用中的文件不能直接覆盖或删除。备份包含订阅地址、服务组合、实例配置和插件私有持久数据；恢复前检查所需插件与接口兼容性，插件程序仍由签名包安装。备份含私有数据，不是系统固件备份，应妥善保管。
“诊断”提供核心重启、重载及按需读取的启动日志；即使 Mihomo 控制接口不可用，仍可排查启动错误。管理范围与恢复规则见设备独立管理。
启用后，NetFleet 会按设定周期刷新订阅并运行一轮有界健康检查。根能力先选择地区；有额外地区要求的能力会在允许时跟随该地区，否则选择自己的最快合格地区。地区内的具体节点继续由 Mihomo URLTest 维护。
切换顺序固定为：
当前优选 -> 其他主用机场 -> 备用机场 -> DIRECT
这套顺序把日常性能和故障恢复放在同一条可见路径中。用户可以从 LuCI 看到当前能力、地区、机场、节点、选择原因和回退状态。
选择 Mihomo 原生代理会退出增强调度、保留原生代理；选择 OpenWrt 原生直连则停止代理并撤销网络接管。切换后回读实际运行状态，业务是否可达仍以真实探针为准，不把模式切换成功当成网络恢复。模式定义与恢复规则统一见运行模式。
个人使用可以直接通过 LuCI 完成首次设置。日常软件更新使用“插件与更新”，原生接入和 Nikki 迁移使用各自设备端入口。需要在多台设备上精确复现 Nikki 环境时，可使用 Fleet 声明式部署入口：
scripts/deploy-openwrt.sh <ssh-target> --ref <release-or-commit> \
--packages /private/path/netfleet-packages \
--instance /private/path/deployment-bundledeployment bundle 由私有 OPL Instance 生成，包含策略、订阅引用、后端 mixin 和平台声明。默认部署会完成安装、编译和 staged 回读；增加 --activate 后，部署器会先确认同一源码已经通过 OpenWrt QEMU qualification，再启用并回读目标设备。该四文件投影用于 Nikki 环境；原生设备更新不应用 Nikki bundle 或启动 Nikki。各入口的适用状态见部署操作。
多设备推广建议先在可本地恢复的 canary 完成一次“编译、启用、回读、关闭”全流程，再把同一发布包和配置推广到其他设备。完整步骤见Canary 推广与复原。
netfleet-delivery 由本仓维护，引用当前交付与验证文档。安装到 Codex 时使用原生 Skill 安装器，从本仓的 skills/netfleet-delivery 路径安装；更新先保留本地修改，再从所选源码版本重新安装。Skill 安装不执行设备更新。
创建带服务、配置动作和页面的完整插件：
python3 scripts/netfleet-plugin.py scaffold my-plugin /tmp/my-plugin --kind service --template complete
python3 scripts/netfleet-plugin.py validate /tmp/my-plugin生成目录可以作为独立仓库开发、打包和分发。省略 --template complete 使用最小服务模板，使用 --kind process 创建进程插件。完整 workspace-note 示例、实例配置、SDK 打包和签名安装流程见插件开发与安装。
快速检查：
scripts/check-fast.sh完整 fake-device 部署矩阵：
scripts/check-full.sh本机 React/Vite 支持同一页面插件宿主，并保留实时只读与离线参考开发入口。设备端由 LuCI 壳加载已安装插件贡献的页面：
cd ui
bun install
NETFLEET_UI_TARGET=<ssh-alias> NETFLEET_UI_TARGET_LABEL="Canary" bun run dev- 文档索引
- 架构总览
- 微内核与功能插件
- 设备独立管理
- 模块与扩展
- 插件开发与安装
- macOS 开发
- HTTPS 兼容模块
- UI 设计
- 能力与平台归属
- 平台实现层
- OpenWrt 平台实现：宿主、网关、管理与包更新机制。
- macOS 平台实现
- 产品白皮书
- 开发与设备操作规则
OPL NetFleet 默认采用 Apache License 2.0，另有明确许可声明的文件除外。LuCI 等文件保留其 MIT 声明。包含 Nikki 派生模块的组合分发仍须遵循 GNU GPL 3.0。原有 NetFleet 文件的 Apache-2.0 声明继续保留，许可正文见 Apache-2.0；复用的 Nikki 模块保留其 GPL-3.0 许可证、版权、固定上游版本和修改说明。第三方原始声明不因组合分发而移除。