一个 YAML、一个程序、一个网页——基于 Alpine Linux 的极简路由器系统
_{A minimal, declarative router OS on Alpine Linux: one YAML file, one static binary, one web UI.}

安装 · 功能 · 使用 · AI agent · 开发 · 下载

整台路由器就是一个 router.yaml。mr（静态 Go 程序，不常驻）负责校验、生成所有配置、应用并自检，出问题自动回滚。 网页、命令行和 AI agent 走的是同一条路。

当前稳定版本：v0.4.0（以 Releases 页面为准） / Current stable release: v0.4.0 (see Releases for the current version).

亮点 / Highlights

• 🛡️ 改不坏：每次改动先预览、分级；倒计时内不确认就自动回滚，断电也会回滚；完整历史，随时退回。
• ⚡ 快：普通流量始终走硬件加速（MT7986 PPE + WED），分流、按域名选线路、单口多拨都不影响卸载。
• 🪶 小：没有空转的守护进程；DDNS、证书、体检都是按需运行的短命令。
• 🧩 全：多线、IPv6、选择性代理、反向代理、去广告、设备管理，一个网页里全部可配。
• 🤖 为 agent 设计：配置即代码，命令输出 JSON，作用域 API token，自带 agent skill。

截图 / Screenshots

手机端	选择性代理	实时监控（深色）

_{截图均为演示数据。}

功能 / Features

模块	功能
网络	PPPoE（1500 MTU）/ DHCP / 静态；多拨（单口多拨每条会话独立 MAC、多口多拨、拨号顺序），多线故障切换与负载均衡；策略路由（按设备 / 网段 / 域名，设备的 IPv4 + IPv6 都能固定到一条线）；双线 IPv6，运营商换前缀自动恢复；访客 / IoT 网络、VLAN；主路由 / 旁路由 / 纯 AP 三种模式；require_public_ip 在 PPPoE 得到私网 / CGNAT 时只重拨这一条线、逐步退避到 15 分钟、不放弃，期间策略路由回落到主路由；可选 ipv6_relay SLAAC 中继（下一版 / next release）
首次设置	新环境首次打开面板进入向导：管理员密码、时区、检测上网方式（mr wan detect）、上游 / LAN 冲突检查、WiFi 和带确认窗口的应用；First-run wizard for password, time zone, connection detection, upstream/LAN conflict check, WiFi and confirm-window apply
换环境	光猫与 LAN 同网段时仍可上网、解析和访问光猫管理页；合并 PPPoE / DHCP / DHCPv6 提供的 DNS，按 WAN 健康状态排序，全部失效时由 dns.fallback 兜底；网页改 LAN 网段会平移相关地址、清旧网桥地址并在新地址一次性确认，不失联；Changing ISP or LAN networks keeps internet and modem access working with DNS from PPPoE/DHCP/DHCPv6 sources ordered by WAN health; dns.fallback is used when all sources are unavailable, and a LAN renumber confirms on the new address
WiFi	多 SSID、WPA2/3、访客隔离；组播转单播、802.11v 频段引导、射频健康与自愈；定时开关
DNS / DHCP	静态分配、本地记录、DNS 分流、DoT；去广告；DNS 主导权（拦截设备私自 DoH / DoT）
防火墙	端口转发、IPv6 入站、通信规则（含时间段）、硬件 / 软件卸载；默认拒绝公网入站
代理	sing-box 选择性透明代理（fake-ip + tproxy），全协议节点、订阅、节点组；按设备全局代理（IPv4 + IPv6）
设备	设备清单与分组、暂停上网、上下线通知；按设备限速、月流量、家长控制；在家 / 离家规则
服务	DDNS（Cloudflare / 阿里云 / DNSPod / DuckDNS / dyndns2 / webhook）；HTTPS 反向代理 + 自动证书；网络唤醒；Tailscale 出口节点
运维	mr doctor 体检与一键修复、事件与通知；异地备份（WebDAV / S3 / GitHub）；升级前检查、更新提示；watchcat；测速
安全变更	语义 diff、变更历史、风险分级、底线规则（guard）；作用域 API token、mr get / set、mr schema
界面	中文 / English，手机可用，浅色 / 深色，原文编辑 router.yaml，全局搜索，实时监控与 24 小时历史

不做（与极简冲突）：UPnP、SQM、fullcone NAT、WireGuard 服务端（sing-box 已支持 WireGuard 节点）、应用识别 / DPI。

安装 / Install

任意架构的 Alpine Linux（x86 小主机、虚拟机、树莓派、ARM 板）——装好 Alpine（磁盘模式 sys）后：

wget -O install.sh https://github.com/Cd1s/mini-router/releases/latest/download/install.sh && sh install.sh

固定到某个发行版时，在下载后另行指定：MR_VERSION=vX.Y.Z sh install.sh。安装脚本会安装包括 ethtool 在内的依赖。 按提示选模式、网口、WAN 类型和密码；AX6000 刷最新发行版后，或 Alpine 使用 MR_APPLY=0 安装后，第一次打开面板会进入首次设置向导，其中有“检测上网方式”。旧用户升级不会弹向导。 只有一个网口？选旁路由（bypass）。首次向导和升级说明见下方文档。 详细步骤、单网口、无人值守和卸载：docs/install-alpine.md。

Redmi AX6000 固件——最新发行版的 OpenWrt 6.18 内核 + mt76 + WED/PPE 硬件加速，可先在内存里试运行再写入闪存， 之后在网页里升级，失败自动回到旧系统：docs/flash.md。

使用 / Usage

mr plan                    # 看会改什么（也可以直接在网页里改）
mr apply --confirm 120     # 应用；120 秒内不 mr confirm 就自动回滚
mr confirm
mr -c new.yaml apply --confirm 120    # 改一份副本再应用：先快照在用的配置，回滚完整
mr wan mac wan2            # 多拨：给同一网口上的第二条 PPPoE 生成固定 MAC（写进 wan[].mac）
mr set 'wifi.steering.enabled=true'   # 按路径改配置，保留注释
mr doctor                  # 体检；--heal 一键修复
mr status · mr history · mr rollback N · mr ddns status · mr edge status     # JSON 输出

各模块配置：docs/modules/ · API：docs/api.md · 示例：examples/

AI agent

skills/mini-router 是给 Claude Code、Codex 等 agent 的操作手册：安全改动流程、配置速查、诊断命令、禁止事项。

mkdir -p ~/.claude/skills && cp -r skills/mini-router ~/.claude/skills/

开发 / Development

• 模块约定：docs/MODULES.md——每个功能 = Go 文件 + 网页文件 + 文档 + CI 片段。
• sudo ./tools/ci.sh（Linux）：单元测试，用真实的 nft / dnsmasq / hostapd / sing-box 校验生成的配置， 并在网络命名空间里跑防火墙、多线、代理、反向代理的端到端测试。
• 网页本地调试：python3 tools/mock/mockapi.py 8088
• 从源码构建：./tools/release.sh vX.Y.Z out/release；AX6000 固件：build/m3/。
• 全新环境实验室：tools/lab/README.md 在全新 Alpine 虚拟机中运行真实 install.sh，模拟 DHCP、PPPoE、DHCPv6-PD、CGNAT、光猫同网段、IPv6 relay 和 LAN 客户端；只在构建机运行，不进 GitHub Actions。 Fresh-environment lab: tools/lab/README.md runs the real installer in fresh Alpine VMs with simulated DHCP, PPPoE, DHCPv6-PD, CGNAT, modem-overlapping-LAN, IPv6 relay and a LAN client; it runs on the build host, outside GitHub Actions.

License

MIT。AX6000 镜像包含 sing-box（GPL-3.0）、Linux 内核（GPL-2.0）等上游组件，各自遵循其许可证。