vladimirperovic/minimalrouter

# Minimal Router OS

安装 · Proxmox · 当前验证 · 文档 · 安全 · 路线图

Minimal Router OS 是一个专用的 Alpine Linux 路由器设备，配备 Go 控制平面和静态 React 仪表板。数据包转发仍保留在 Linux 内核中。该项目使用成熟的组件，而不是实现一个新的数据包处理栈： - 使用 `nftables` 进行防火墙和 NAT； - 使用 `pppd` 进行 PPPoE； - 使用 `dnsmasq` 进行 DHCP、DNS、过滤和有限服务集； - 使用 WireGuard 进行远程访问； - 可选的 Squid、QoS、Cloudflare DDNS 和 Wi-Fi AP 支持。 ## 当前基线 已实现并覆盖于开发环境中的功能： - 非特权 `routerd` 以及受限的特权 `router-applyd`； - SQLite 规范配置状态和迁移； - 类型化验证和确定性配置生成； - 快照、预检、应用、验证、提交确认和回滚； - WAN 默认拒绝策略和 LAN 到 WAN 的 NAT； - PPPoE、DHCP、DNS、WireGuard、DNS 过滤配置文件、QoS、DDNS 和 Wi-Fi 路径； - Argon2id 身份验证、安全会话、CSRF、速率限制和可选的 TOTP； - 加密备份导出、配置快照和本地恢复控制台； - 使用持久操作日志的防崩溃 A/B 更新激活和回滚； - 签名清单、SHA-256 验证、校验和、SPDX SBOM 和来源证明； - 前端单元测试和 Playwright 浏览器 E2E 测试； - 全新的 Alpine 安装、首次运行向导、签名更新、激活和回滚 CI； - 竞争测试、`vet`、`govulncheck`、CodeQL、密钥扫描、`gosec`、`shellcheck` 和 `actionlint`； - API/更新基准测试、模糊测试、ARM64 QEMU 冒烟测试，以及隔离的 WAN-router-LAN 命名空间实验室。 当前的仪表板构建使用 TypeScript 6.0.3 和 Node.js 类型定义 26.1.2。Node.js 仅作为构建时依赖；它不会安装或运行在路由器上。 有关带有确切日期的自动化证据、基准测试范围以及剩余的手动测试关卡，请参见 [`docs/CURRENT_VALIDATION.md`](docs/CURRENT_VALIDATION.md)。 ## 尚未验证的部分 GitHub Actions 无法建立目标主机的生产就绪状态。该项目仍需要记录以下证据： - 所有者实际的 Proxmox 虚拟机和桥接/NIC 配置； - 多次重启后稳定的 WAN/LAN 标识； - 真实的 ISP PPPoE 连接和重连； - 物理或 VirtIO NIC 吞吐量、数据包速率、CPU、IRQ、延迟和热量； - 真实的 WireGuard 吞吐量以及从不相关网络中的恢复； - 外部 IPv4/IPv6 扫描； - 备份还原到全新的虚拟机中； - 在一次性目标上进行破坏性故障注入； - 至少七天的持续运行； - 所有者签名的安装/恢复介质和独立的安全审查。 ## 架构 ``` flowchart LR Browser[Administrator browser] UI[Static React dashboard] Routerd[routerd — unprivileged API] DB[(SQLite canonical state)] Applyd[router-applyd — privileged helper] Recovery[Local recovery console] Linux[Linux networking services] LAN[LAN clients] WAN[Internet] Browser --> UI UI -->|HTTPS /api/v1| Routerd Routerd --> DB Routerd -->|typed local IPC| Applyd Recovery -->|local console only| DB Applyd --> Linux LAN <--> Linux Linux <--> WAN ``` 每次配置变更都遵循相同的不变量： ``` input → validation → typed model → generation → preflight → snapshot → apply → verification → commit or rollback ``` 不支持的功能将直接失败或显示为不可用，而不会进行模拟。 ## 受控安装 目前还没有签名的稳定版 ISO。请使用纯净的 Alpine Linux 3.22 虚拟机或具有两个接口和本地控制台访问权限的专用测试系统。 从以下文档开始： - [`docs/INSTALLATION.md`](docs/INSTALLATION.md) - [`docs/PROXMOX.md`](docs/PROXMOX.md) - [`docs/RECOVERY.md`](docs/RECOVERY.md) - [`docs/TESTING.md`](docs/TESTING.md) 请保留现有的路由器。初始测试必须使用隔离的 LAN 和测试/NAT WAN 路径。切勿在同一生产 LAN 上运行两个 DHCP 服务器。 构建 AMD64 开发归档： ``` git clone https://github.com/vladimirperovic/minimalrouter.git cd minimalrouter pnpm --dir web install --frozen-lockfile make dist-amd64 cd build sha256sum -c minimalrouter-linux-amd64.tar.gz.sha256 ``` 开发归档并不是签名过的稳定版固件发布。 ## 开发 要求： - `go.mod` 中声明的 Go 版本； - Node.js 22； - pnpm。 ``` go test -race ./... go vet ./... pnpm --dir web install --frozen-lockfile pnpm --dir web lint pnpm --dir web test pnpm --dir web build pnpm --dir web exec playwright install chromium pnpm --dir web test:e2e ``` 其他自动化测试套件定义在： - `.github/workflows/ci.yml`； - `.github/workflows/deep-validation.yml`； - `.github/workflows/performance.yml`； - `.github/workflows/codeql.yml`。 ## 安全与隐私 路由器是一个安全边界。在运行或更改特权代码之前，请阅读 [`SECURITY.md`](SECURITY.md)。请勿在公开的 issues 中报告漏洞。 切勿提交或公开附上： - PPPoE 凭证； - 管理员密码、哈希、会话或 CSRF 值； - WireGuard 私钥、预共享密钥、配置文件或二维码； - 提供商令牌； - 签名私钥； - 备份、数据库、快照、数据包捕获或运行时日志； - 真实的公开地址、主机名、MAC 地址或设备清单。 本项目不包含任何故意由项目运营的分析、广告或云遥测功能。请参见 [`PRIVACY.md`](PRIVACY.md)。 ## 文档 完整的索引位于 [`docs/README.md`](docs/README.md)。关键文档： - [`ARCHITECTURE.md`](ARCHITECTURE.md) - [`PROJECT.md`](PROJECT.md) - [`SECURITY.md`](SECURITY.md) - [`docs/CURRENT_VALIDATION.md`](docs/CURRENT_VALIDATION.md) - [`docs/INSTALLATION.md`](docs/INSTALLATION.md) - [`docs/PROXMOX.md`](docs/PROXMOX.md) - [`docs/TESTING.md`](docs/TESTING.md) - [`docs/RECOVERY.md`](docs/RECOVERY.md) - [`docs/RESOURCE_AND_HARDWARE_TEST.md`](docs/RESOURCE_AND_HARDWARE_TEST.md) - [`docs/SECURITY_REVIEW.md`](docs/SECURITY_REVIEW.md) - [`ROADMAP.md`](ROADMAP.md) - [`CHANGELOG.md`](CHANGELOG.md) ## 发布 目前还没有稳定的签名发布。官方发布必须遵循 [`docs/RELEASE_PROCESS.md`](docs/RELEASE_PROCESS.md) 和 [`docs/RELEASE_SECURITY.md`](docs/RELEASE_SECURITY.md)，发布签名清单、校验和、SPDX SBOM、来源证明、已知限制以及明确支持的部署类别。 ## 许可证 Minimal Router OS 基于 [MIT 许可证](LICENSE) 提供。 项目名称和文档不暗示 Netgate、pfSense、OpenWrt、AdGuard、Cloudflare、Alpine Linux 或任何其他引用的项目或公司的认可。

标签：Alpine Linux, Docker 部署, EVTX分析, Go, MITM代理, nftables, React, Ruby工具, Syscalls, WireGuard, 日志审计, 特征检测, 网络运维, 路由器操作系统