refactor: 枚举移入Models目录，命名空间更新为Rainbow.Entity.Models
|
# Rainbow 架构设计
> 版本：v2.2 | 日期：2026-07-03 | [← 返回 README](/NewLife/RainbowBridge/Blob/master/Doc/../README.md)
>
> 需求对应：[需求文档](/NewLife/RainbowBridge/Blob/master/Doc/需求文档.md) | 功能清单：[功能模块清单](/NewLife/RainbowBridge/Blob/master/Doc/功能模块清单.md)
---
## 1. 架构概览
Rainbow 采用**前后端分离 + Cube 后台 + 数据库驱动 + 跨平台适配**架构（StarChat 模式）。Linux 全功能主力，dnsmasq 为 DNS/DHCP 核心，通过 `IDhcpDnsAdapter` 接口预留自研服务器扩展能力。
```
用户浏览器
├── / → React SPA（仪表盘/终端/WAN/DNS/防火墙）
├── /admin → Cube 魔方后台（用户/角色/日志/系统配置）
├── /api/* → RESTful JSON API
└── 拦截页（:9080） → DNS 拦截提示页（独立端口）
─────────────────────────────────────────────────────────
┌─────────────────────────────────────────────────────────┐
│ React 前端（Web/） │
│ Vite + TypeScript + TailwindCSS + 星语UI规范 │
│ Dashboard │ 终端 │ 多WAN │ DNS │ 防火墙 │ 设置 │
├─────────────────────────────────────────────────────────┤
│ Rainbow.Web（双入口：API + Cube） │
│ ┌──────────────────┐ ┌──────────────────────────────┐ │
│ │ RESTful API │ │ Cube /admin 后台 │ │
│ │ [ApiController] │ │ [EntityController] │ │
│ │ /api/system │ │ /admin 用户/角色/日志/配置 │ │
│ │ /api/devices │ │ 菜单+权限+审计 │ │
│ │ /api/dns/rules │ │ │ │
│ └──────────────────┘ └──────────────────────────────┘ │
│ + 拦截页服务（:9080，DNS 阻断时展示提示页） │
├─────────────────────────────────────────────────────────┤
│ XCode 实体层（Rainbow.Data） │
│ Model.xml → xcode 生成实体类（14+ 表） │
│ Device / DnsRule / DnsBlacklist / DhcpBinding ... │
│ Services: ShellExecutor / DnsmasqManager / WanManager │
│ Adapters: IOSAdapter / IFirewallAdapter / IDhcpDnsAdapter │
├─────────────────────────────────────────────────────────┤
│ SQLite 数据库（Rainbow.db） │
├─────────────────────────────────────────────────────────┤
│ 系统层（按平台适配） │
│ Linux: pppd / dnsmasq / iptables / iproute2 / /proc │
│ Windows: netsh / Get-NetAdapter / WMI / perf counters │
│ macOS: pfctl / networksetup / sysctl / bootpd │
└─────────────────────────────────────────────────────────┘
```
### 1.1 项目组成
| 项目 | 类型 | 框架 | 说明 |
|------|------|------|------|
| `Rainbow.Data` | 类库 | net6.0 + XCode | 实体（Model.xml）+ Services + 跨平台适配器 |
| `Rainbow.Web` | Web API + Cube | net10.0 | RESTful API + Cube /admin + StarAgent |
| `Web/` | 前端 | React 19 + Vite + TailwindCSS | SPA 前端，星语UI规范 |
| `XUnitTest` | 测试 | net10.0 + xUnit | 单元测试 / 集成测试 / E2E |
### 1.2 核心设计决策
| 决策点 | 选择 | 理由 |
|--------|------|------|
| 前端框架 | React 19 + Vite + TailwindCSS | 前后端分离，现代化 UI，星语UI规范 |
| 后台管理 | Cube /admin（StarChat 模式） | RBAC/菜单/日志/配置开箱即用 |
| 数据层 | XCode ORM + SQLite + Model.xml | 建模即代码，零配置 |
| 系统交互 | ShellExecutor + Sudo 白名单 | 安全执行系统命令，跨平台命令适配 |
| DNS/DHCP | dnsmasq（Linux 主力），接口预留自研 | 当前依托成熟稳定的 dnsmasq，`IDhcpDnsAdapter` + `DhcpDnsConfig` 接口设计确保未来可替换 |
| DNS 拦截 | DNS 重定向 + iptables REDIRECT + 独立端口拦截页 | 不影响 Rainbow 主服务 |
| 进程守护 | StarAgent | 自动发现/崩溃重启/远程管理 |
| 跨平台 | Linux 全功能 / Windows P1 / macOS P2 | 按平台成熟度分期覆盖，通过适配器接口统一 |
### 1.3 DnsmasqManager 配置同步数据流
```
Web 配置（DnsRule/DnsBlacklist/DhcpPool/DhcpBinding）
↓ CRUD 钩子自动触发
DnsmasqManager.ApplyAsync()
↓ 从 SQLite 读取全量配置
生成 /etc/dnsmasq.d/rainbow.conf
↓ 写入磁盘
systemctl reload dnsmasq（或 kill -HUP）
↓ 零停机重载
dnsmasq 生效 → 设备 DHCP 分配到正确 IP/DNS
```
DNS 黑名单命中统计：
```
dnsmasq 查询日志（/var/log/dnsmasq.log）
↓ TimerX 每分钟增量解析
匹配 DnsBlacklist 域名 → 批量更新 Hits + LastHit
↓
/api/dns/blacklist/stats 返回真实拦截数据
```
---
## 2. 数据模型（Model.xml）
### 2.1 Entity 目录结构
```
Rainbow.Data/
├── Model.xml ← 数据模型定义
├── Entity/ ← xcode 自动生成
│ ├── 设备.cs / 设备.Biz.cs
│ ├── WAN接口.cs / WAN接口.Biz.cs
│ ├── PPPoE账号.cs / PPPoE账号.Biz.cs
│ ├── DHCP地址池.cs / DHCP地址池.Biz.cs
│ ├── DNS规则.cs / DNS规则.Biz.cs
│ ├── 防火墙规则.cs / 防火墙规则.Biz.cs
│ ├── 网络日志.cs / 网络日志.Biz.cs
│ └── 配置快照.cs / 配置快照.Biz.cs
├── Services/
│ ├── ShellExecutor.cs ← 跨平台命令执行
│ ├── SudoWhitelist.cs
│ ├── ShellAuditLogger.cs
│ ├── ConfigBackup.cs
│ ├── MonitorCollector.cs
│ ├── WanManager.cs
│ ├── PppManager.cs
│ ├── DnsmasqManager.cs ← 配置同步 + DHCP tag（本次迭代核心）
│ ├── DhcpDnsConfig.cs ← 结构化配置 DTO（接口预留）
│ ├── FirewallManager.cs
│ ├── IOSAdapter.cs ← 系统监控接口 + Debian/Windows/Mac 实现
│ ├── AdapterFactory.cs ← 平台感知适配器工厂
│ ├── FirewallAdapters.cs ← IFirewallAdapter + Iptables/Nftables
│ ├── DhcpDnsAdapters.cs ← IDhcpDnsAdapter + Dnsmasq/Systemd/Bind9
│ ├── INetworkRouteManager.cs ← 路由管理接口（新增）
│ ├── INetworkStatProvider.cs ← 流量统计接口（新增）
│ ├── INetworkInterfaceManager.cs ← 网口管理接口（新增）
│ ├── Windows/ ← Windows 平台适配器（P1）
│ └── Mac/ ← macOS 平台适配器（P2）
└── Models.cs ← DTO 模型类
```
### 2.2 核心表设计
详见 `Rainbow.Data/Model.xml`：
| 表名 | 中文 | 主键 | 关键索引 |
|------|------|------|---------|
| Device | 设备 | Id (Int64, 雪花) | MacAddress UNIQUE |
| WanInterface | WAN接口 | Id (Int32 自增) | Name UNIQUE |
| PppoeAccount | PPPoE账号 | Id (Int32 自增) | InterfaceName UNIQUE |
| DhcpPool | DHCP地址池 | Id (Int32 自增) | |
| DnsRule | DNS规则 | Id (Int32 自增) | Domain |
| FirewallRule | 防火墙规则 | Id (Int32 自增) | RuleType, IsEnabled |
| NetworkLog | 网络日志 | Id (Int64, 雪花) | CreateTime |
| ConfigSnapshot | 配置快照 | Id (Int32 自增) | CreateTime |
---
## 3. API 设计
### 3.1 控制器结构（Rainbow.Web/Controllers/）
```
Controllers/
├── HealthController.cs [Route("api/health")]
├── SystemController.cs [Route("api/system")]
├── DashboardController.cs [Route("api/dashboard")]
├── DeviceController.cs [Route("api/devices")]
├── WanController.cs [Route("api/wan")]
├── PppoeController.cs [Route("api/pppoe")]
├── DhcpController.cs [Route("api/dhcp")]
├── DnsController.cs [Route("api/dns")]
├── FirewallController.cs [Route("api/firewall")]
├── BackupController.cs [Route("api/backup")]
└── LogController.cs [Route("api/logs")]
```
### 3.2 API 规范
- 所有接口返回 JSON，使用 `ActionResult<T>` 或 `IActionResult`
- 成功返回 `Ok(data)`，失败返回 `BadRequest(new { error = "..." })`
- 控制器继承 `ControllerBase`，使用 `[ApiController]` 特性
- 参考 StarChat Controller 模式：构造函数注入服务
### 3.3 关键接口示例
```csharp
[ApiController]
[Route("api/devices")]
public class DeviceController : ControllerBase
{
[HttpGet]
public ActionResult<List<Device>> GetDevices() { ... }
[HttpPost("{mac}/block")]
public async Task<ActionResult> BlockDevice(String mac) { ... }
[HttpPut("{mac}/alias")]
public async Task<ActionResult> UpdateAlias(String mac, [FromBody] AliasDto dto) { ... }
}
```
---
## 4. 前端架构（Web/）
### 4.1 目录结构
```
Web/
├── src/
│ ├── App.tsx ← 路由 + 布局
│ ├── main.tsx ← 入口
│ ├── pages/ ← 页面组件
│ │ ├── Dashboard.tsx
│ │ ├── Devices.tsx
│ │ ├── WanPage.tsx
│ │ ├── PppoePage.tsx
│ │ ├── DhcpPage.tsx
│ │ ├── DnsPage.tsx
│ │ ├── FirewallPage.tsx
│ │ └── SettingsPage.tsx
│ ├── components/ ← 通用组件
│ │ ├── GaugeChart.tsx
│ │ ├── TrafficChart.tsx
│ │ └── StatusCard.tsx
│ ├── lib/ ← API 调用 + 工具
│ │ ├── api.ts
│ │ └── theme.ts
│ ├── stores/ ← Zustand 状态管理
│ └── styles/ ← TailwindCSS + 主题变量
├── package.json
├── vite.config.ts
└── tsconfig.json
```
### 4.2 设计规范
遵循 `星语UI规范.md` 三大核心维度：
- **玻璃拟态**：半透明磨砂背景 + 细边框 + 柔和阴影
- **品牌渐变**：主色调 `#5B5BFF → #8B5CF6`
- **微动效**：hover 上浮、Modal scaleIn、Toast slideInRight
---
## 5. 开发工作流
### 5.1 数据建模
1. 编辑 `Rainbow.Data/Model.xml` 定义表结构
2. 执行 `xcode Rainbow.Data` 生成实体类到 `Entity/`
3. 实体类即拥有完整 CRUD 能力
### 5.2 API 开发
1. 在 `Rainbow.Web/Controllers/` 创建 API 控制器
2. 注入 Service 和 XCode 实体
3. 接口从数据库读取 → 必要时执行系统命令 → 返回
### 5.3 前端开发
```bash
cd Web
pnpm install
pnpm dev # 开发服务器（默认代理到 http://localhost:8080）
pnpm build # 生产构建 → Web/dist/
```
---
## 6. 部署
```bash
# 1. 构建后端
dotnet publish -c Release -o /opt/rainbow Rainbow.Web/
# 2. 构建前端
cd Web && pnpm build && cp -r dist /opt/rainbow/wwwroot/
# 3. sudo 白名单
cp deploy/rainbow.sudoers /etc/sudoers.d/rainbow
# 4. StarAgent 自动发现并守护
```
---
（完）
```
┌──────────────────────────────────────────────────────────────────┐
│ Web 表现层（NewLife.Cube MVC） │
│ Dashboard │ 多WAN │ PPPoE │ DHCP/DNS │ 防火墙 │ IPv6 │
│ VLAN │ 静态路由 │ VPN(WireGuard/OpenVPN) │ 防沉迷 │
│ 认证登录 │ SSO │ RBAC │ 操作日志 │ 系统设置 │
├──────────────────────────────────────────────────────────────────┤
│ 桥接服务层（Rainbow.Data） │
│ ShellExecutor · WanManager · PppManager │
│ DnsmasqManager · FirewallManager · VlanManager │
│ RouteManager · VpnManager · MonitorCollector │
│ DeviceTracker · ConfigBackup │
├──────────────────────────────────────────────────────────────────┤
│ Linux 网络层（Linux Kernel） │
│ pppd · dnsmasq · iptables/nftables · iproute2 · wireguard │
│ /proc /sys · conntrack · StarAgent · openvpn │
└──────────────────────────────────────────────────────────────────┘
```
### 1.1 项目组成
| 项目 | 类型 | 目标框架 | OutputType | 说明 |
|------|------|---------|-----------|------|
| `Rainbow.Data` | 类库 | netstandard2.0 | Library | 配置类（`Config<T>`）、数据模型、桥接服务实现 |
| `Rainbow.Web` | Cube MVC 应用 | net10.0 | Exe | Web 管理界面，集成 Cube 全功能认证+SSO |
| `XUnitTest` | 单元测试 | net10.0 | Library | xUnit，覆盖桥接服务层核心逻辑和配置类 |
### 1.2 NuGet 依赖链（仅 NewLife 系列）
```
Rainbow.Web ──→ NewLife.Cube.Core ──→ NewLife.Core
│ ├── NewLife.Remoting
│ └── NewLife.Stardust.Extensions
└──→ Rainbow.Data ──→ NewLife.XCode ──→ NewLife.Core
└── NewLife.Stardust
```
### 1.3 模块关系
```
Rainbow.Web (Areas/)
├── Admin/
│ ├── HomeController 仪表盘
│ └── SystemController 系统设置
└── Network/
├── WanController 多WAN
├── PppoeController PPPoE
├── DhcpController DHCP
├── DnsController DNS
├── FirewallController 防火墙
├── VlanController VLAN
├── RouteController 静态路由
├── VpnController VPN
└── MonitorController 实时监控
│ DI
Rainbow.Data ──→ ShellExecutor/WanManager/DnsmasqManager/...
│ sudo + 文件 IO
Linux 网络栈 ──→ pppd/dnsmasq/iptables/iproute2/wireguard/openvpn
```
### 1.4 核心设计决策
| 决策点 | 选择 | 理由 |
|--------|------|------|
| Web 框架 | NewLife.Cube（MVC） | RBAC + SSO + 菜单 + CRUD 开箱即用 |
| 分层 | 两层（Web + Data） | 单入口应用，复杂度在桥接服务层 |
| 多 WAN | iproute2 策略路由 | 内核原生，比 mwan3 更底层可控 |
| IPv6 | dnsmasq DHCPv6 + RA + ip6tables | 与 IPv4 统一入口 |
| VLAN | `ip link type vlan` | 内核原生 802.1Q |
| VPN | WireGuard（优先）+ OpenVPN | 性能与兼容性兼顾 |
| 进程守护 | StarAgent | 自动发现/崩溃重启/远程管理/零配置 |
| 数据持久化 | SQLite + `Config<T>` JSON | 轻量零配置，配置热更新 |
### 1.5 StarAgent 守护
Rainbow 不做 systemd 服务，由 StarAgent 统一管理。StarAgent 自动发现 `/opt/rainbow` 下的 .NET 项目，提供崩溃重启、健康检查、远程管理和日志聚合。
### 1.6 认证体系
Cube 内置全功能认证：表单登录 + 验证码 → RBAC（角色→菜单→按钮） → OAuth2.0/OIDC SSO → JWT Token。`WebSetting` 中配置 `SSOServer`/`AppId`/`Secret` 即可接入第三方认证中心。
---
## 2. 桥接服务层
### 2.1 命令执行安全边界
```
用户操作 → Controller → Service（Rainbow.Data）
→ ShellExecutor.Execute(cmd, args, needSudo, timeout)
→ SudoWhitelist.IsWhitelisted(cmd) // 白名单正则校验
→ Process.Start(sudo, argList) // ArgumentList 防注入
→ SemaphoreSlim(4) 并发控制 // 最多 4 个 Shell 进程
→ 超时 CancellationTokenSource // 默认 30s
→ 审计日志（命令/参数/耗时/退出码）
```
### 2.2 各服务管理器
| 服务 | 核心方法 | 系统工具 |
|------|---------|---------|
| `WanManager` | `AddWan()` / `SetLoadBalance()` / `CheckFailover()` | ip, iptables, ping |
| `PppManager` | `ConnectAsync()` / `DisconnectAsync()` / `GetStatusAsync()` | pppoe-start/stop/status, ip |
| `DnsmasqManager` | `GetLeasesAsync()` / `AddStaticLeaseAsync()` / `SetDhcpv6()` / `SetRA()` | dnsmasq, systemctl |
| `FirewallManager` | `AddPortForwardAsync()` / `BlockMacAsync()` / `AddIp6tablesRuleAsync()` | iptables, ip6tables, nft |
| `VlanManager` | `CreateVlanAsync()` / `DeleteVlanAsync()` | ip link |
| `RouteManager` | `AddRouteAsync()` / `AddPolicyRouteAsync()` | ip route, ip rule |
| `VpnManager` | `CreateWireGuardAsync()` / `CreateOpenVpnAsync()` / `GetVpnStatusAsync()` | wg, wg-quick, openvpn, systemctl |
| `MonitorCollector` | `GetNetworkStatsAsync()` / `GetCpuUsageAsync()` / `GetIPv6StatusAsync()` | /proc, ip |
| `ConfigBackup` | `BackupAsync()` / `RollbackAsync()` | 文件 IO |
---
## 3. 多 WAN 负载均衡
```
ISP-A(PPPoE)──ppp0──┐ ┌──eth0(LAN)──内网
├─ 软路由 ─┤
ISP-B(DHCP)───eth1──┘ └──eth0.10(VLAN10)
```
**实现**：每 WAN 口独立路由表（`ip route add table 100/200`） → iptables 按连接标记 fwmark（statistic nth/random） → `ip rule fwmark` 选择路由表。
**模式**：轮询（每包交替）/ 权重（按带宽比例）/ 源地址哈希（固定出口）/ 策略路由（目标 IP 匹配）/ 故障切换（ping 检测 + 自动切路由）。
---
## 4. IPv6 双栈
```
ISP ──IPV6CP──→ ppp0（全球单播 IPv6 + /60 PD前缀）
│
┌───────────┴───────────┐
│ dnsmasq │
│ DHCPv6(IA_NA/IA_PD) │
│ RA(SLAAC) │
└───────────┬───────────┘
│
┌───────────┴───────────┐
│ eth0(LAN) │
│ 内网设备获取 IPv6 │
│ ip6tables 防火墙 │
└───────────────────────┘
```
---
## 5. 部署
```bash
# 1. 发布
dotnet publish -c Release -o /opt/rainbow Rainbow.Web/
# 2. StarAgent 自动发现并守护（无需 systemd）
# 3. sudo 白名单
cp deploy/rainbow.sudoers /etc/sudoers.d/rainbow
```
---
（完）
|