admin/Xboard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(api): 新增节点月流量限额强制下线

Browse Source 
新增节点级月流量限额配置、重置调度和运行状态持久化
下发 traffic_limit 给 mi-node，并在超额后停止内核、到期后恢复
管理端支持编辑限额参数并展示额度进度、状态和下次重置
手动与定时重置会同步清理限额状态并通知节点刷新配置
This commit is contained in:
yinjianm
2026-04-29 00:46:12 +08:00
parent 52529d1f58
commit 922e86070d
26 changed files with 1127 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.helloagents/archive/2026-04/202604281921_node-traffic-limit-enforcement/.status.json
+10
View File
@@ -0,0 +1,10 @@
{
"status": "completed",
"completed": 11,
"failed": 0,
"pending": 0,
"total": 11,
"percent": 100,
"current": "验收完成，准备归档",
"updated_at": "2026-04-28 20:37:00"
}
.helloagents/archive/2026-04/202604281921_node-traffic-limit-enforcement/proposal.md
+252
View File
@@ -0,0 +1,252 @@
# 变更提案: node-traffic-limit-enforcement
## 元信息
```yaml
类型: 新功能
方案类型: implementation
优先级: P1
状态: 已确认
创建: 2026-04-28
```
---
## 1. 需求
### 背景
部分节点供应商有固定月流量额度，且每个节点的额度重置时间不同。当前 Xboard 只在面板侧通过 `show`、订阅过滤或节点累计 `u/d` 判断可见性，不能让 `mi-node` 实际停止节点内核，因此无法满足超额后真实下线的要求。
### 目标
- 管理员可以为单个节点设置每月流量额度，上行和下行合并计算。
- 管理员可以设置每月重置日期和重置时间。
- `mi-node` 在当前周期内统计节点总流量，达到额度后调用内核 `Stop()`，使节点真实下线。
- 重置时间到达后，`mi-node` 清理本周期状态并重新启动内核，使节点恢复上线。
- Xboard 负责保存、下发、展示和手动重置节点流量限额状态，不把该状态混入 `show` 或 `auto_online`。
### 约束条件
```yaml
时间约束: 本轮在现有 Xboard 与 mi-node 项目内增量实现，不重写节点同步架构。
性能约束: mi-node 额度检查复用现有 tracker tick，不能增加按连接扫描的重负载路径。
兼容性约束: 未启用节点流量限额的节点行为保持不变；旧 mi-node 忽略新增配置字段。
业务约束: 节点下线必须是 mi-node 内核停止，不只是订阅隐藏或 show=false。
```
### 验收标准
- [ ] Xboard 节点编辑接口和管理端可保存节点月流量额度、重置日、重置时间。
- [ ] Xboard 下发的节点配置包含流量限额、重置规则和时区信息。
- [ ] mi-node 可解析新增配置，并在达到额度后停止内核，同时阻止 `ensureRunning()` 自动拉起。
- [ ] mi-node 在重置时间到达后清理限额状态并恢复内核运行。
- [ ] mi-node 重启后能从本地持久化状态恢复周期用量和限额下线状态。
- [ ] Xboard 管理端能展示限额额度、当前已用、下次重置、限额状态。
- [ ] 手动/自动重置节点流量后会通知 mi-node，使本地限额状态及时恢复。
- [ ] `go test ./...`、`admin-frontend npm run build` 完成；PHP 侧在本机工具可用时执行语法/测试验证。
---
## 2. 方案
### 技术方案
采用“节点本地强执行 + 面板配置编排”。
Xboard 在 `v2_server` 增加限额配置字段，复用已有 `transfer_enable` 作为节点月流量额度，新增启用状态、重置日、重置时间、时区和限额状态字段。`ServerService::buildNodeConfig()` 将限额配置下发给 `mi-node`，`ServerObserver` 在配置字段变化时推送 `sync.config`。管理端节点编辑弹窗增加限额配置区，节点列表流量浮层展示限额状态。
`mi-node` 在 `NodeConfig` / `NodeSpec` 中新增 `traffic_limit` 结构，新增节点流量限额管理组件，复用 tracker 每个 tick 计算出的增量合计周期用量。达到额度后设置 suspended 状态并调用 `kernel.Stop()`；在重置时间到达后清空周期状态，并在已有 `lastConfig` / `lastUsers` 可用时重启内核。状态写入本地 JSON，避免进程重启后丢失周期用量。
### 影响范围
```yaml
涉及模块:
- Xboard 数据模型: v2_server 限额字段、casts、保存校验。
- Xboard 节点同步: buildNodeConfig、ServerObserver、NodeSyncService 推送触发。
- Xboard 节点状态: report metrics 缓存、手动重置流量后通知节点恢复。
- Xboard 管理端: 节点编辑弹窗、类型定义、保存映射、节点列表限额展示。
- mi-node 面板协议: panel.NodeConfig、model.NodeSpec、WS/REST 转换。
- mi-node 服务层: tracker 增量接入、内核 stop/start gate、metrics 上报。
- mi-node 本地状态: 新增持久化文件保存周期用量和 suspended 状态。
预计变更文件: 20-30 个，跨 PHP、Vue/TypeScript、Go 三层。
```
### 风险评估
| 风险 | 等级 | 应对 |
|------|------|------|
| mi-node 本地周期用量与 Xboard `u/d` 展示短暂不一致 | 中 | 以 mi-node 为强执行源，Xboard 展示同时保留面板统计和 node metrics；手动重置触发 config/full sync。 |
| `ensureRunning()` 或配置 reload 在 suspended 状态下误重启内核 | 高 | 在 `startKernel()` / `ensureRunning()` / `applyChanges()` 入口统一检查限额 gate，并补单元测试。 |
| 重置日遇到短月，如 31 号 | 中 | 下次重置时间计算时钳制到当月最后一天。 |
| 旧 mi-node 不支持新增字段 | 低 | 新字段为可选结构，旧节点忽略；Xboard 仍能保存和展示配置。 |
| 同一节点多实例运行导致额度各自计算 | 中 | 本轮按一节点一运行实例处理；方案文档注明该边界，多实例集中裁决不在本轮范围。 |
### 方案取舍
```yaml
唯一方案理由: 本方案把真实下线放在 mi-node 本地执行，能避免面板报告延迟导致超额后仍继续服务，同时保留 Xboard 的配置、审计和人工操作入口。
放弃的替代路径:
- 面板集中裁决 + WS 停启事件: 状态源集中但依赖 report/WS 延迟，不能保证及时停止节点。
- 只扩展 show/enabled 或用户移除逻辑: 成本低但不满足“节点实际下线”。
回滚边界: 可关闭单节点限额开关恢复旧行为；数据库新增字段可独立回滚；mi-node 新增限额组件不影响未启用限额节点。
```
---
## 3. 技术设计
### 架构设计
```mermaid
flowchart TD
A[Xboard 管理端节点编辑] --> B[v2_server 限额字段]
B --> C[ServerService::buildNodeConfig]
C --> D[REST/WS sync.config]
D --> E[mi-node NodeSpec.TrafficLimit]
E --> F[TrafficLimitManager 本地状态]
G[tracker.Process delta] --> F
F -->|超额| H[kernel.Stop]
F -->|到达重置时间| I[startKernel]
F --> J[metrics.traffic_limit]
J --> K[Xboard 管理端状态展示]
```
### API 设计
#### Admin 节点保存 payload
- **请求新增字段**:
- `traffic_limit_enabled`: boolean
- `traffic_limit_reset_day`: integer|null，1-31
- `traffic_limit_reset_time`: string|null，`HH:mm`
- `traffic_limit_timezone`: string|null，默认面板时区
- `transfer_enable`: integer|null，字节，0 表示不限额
- **响应**: 复用现有节点保存响应。
#### 节点配置下发
- **新增结构**:
```json
{
"traffic_limit": {
"enabled": true,
"limit": 1099511627776,
"reset_day": 1,
"reset_time": "04:00",
"timezone": "Asia/Shanghai",
"current_used": 123456,
"next_reset_at": 1774977600
}
}
```
#### mi-node metrics
- **新增结构**:
```json
{
"traffic_limit": {
"enabled": true,
"limit": 1099511627776,
"used": 123456,
"suspended": false,
"next_reset_at": 1774977600,
"last_reset_at": 1772299200
}
}
```
### 数据模型
| 字段 | 类型 | 说明 |
|------|------|------|
| `traffic_limit_enabled` | boolean | 是否启用节点月流量强制下线。 |
| `traffic_limit_reset_day` | tinyint nullable | 每月重置日，1-31，短月钳制到最后一天。 |
| `traffic_limit_reset_time` | string nullable | 每月重置时间，`HH:mm`。 |
| `traffic_limit_timezone` | string nullable | 重置时间使用的时区，默认面板时区。 |
| `traffic_limit_status` | string nullable | 面板缓存的限额状态，如 `normal` / `suspended`。 |
| `traffic_limit_last_reset_at` | integer nullable | 最近一次重置时间戳。 |
| `traffic_limit_next_reset_at` | integer nullable | 下一次重置时间戳。 |
| `traffic_limit_suspended_at` | integer nullable | 最近一次超额下线时间戳。 |
---
## 4. 核心场景
### 场景: 节点超额后真实下线
**模块**: mi-node 服务层
**条件**: 节点启用流量限额，周期用量累计达到 `limit`。
**行为**: `TrafficLimitManager` 标记 suspended，持久化状态，调用 `kernel.Stop()`。
**结果**: `kernel_status=false`，节点不再提供代理服务，`ensureRunning()` 不会自动重启。
### 场景: 重置时间到达后恢复上线
**模块**: mi-node 服务层
**条件**: 节点处于限额 suspended，当前时间达到 `next_reset_at`。
**行为**: 管理组件清空周期用量，更新 reset 时间，持久化状态，调用 `startKernel(lastConfig,lastUsers)`。
**结果**: 节点内核重新运行，metrics 显示 `suspended=false`。
### 场景: 管理员调整限额配置
**模块**: Xboard 节点同步
**条件**: 管理员保存节点限额字段。
**行为**: Xboard 保存字段，`ServerObserver` 触发 `sync.config`。
**结果**: mi-node 收到新配置并重新计算限额状态；未启用限额时不影响旧行为。
---
## 5. 技术决策
### node-traffic-limit-enforcement#D001: 由 mi-node 本地强制节点下线
**日期**: 2026-04-28
**状态**: ✅采纳
**背景**: 用户明确要求“不是只是不显示，要实际上的下线”。
**选项分析**:
| 选项 | 优点 | 缺点 |
|------|------|------|
| A: mi-node 本地强执行 | 停机及时，网络异常时仍能执行，符合真实下线 | 需要本地状态持久化和更多测试 |
| B: Xboard 集中裁决后下发停启 | 状态集中，管理端一致性强 | 依赖 report/WS 延迟，节点可能继续服务 |
| C: 修改 show/enabled/用户列表 | 实现简单 | 不是真实节点下线 |
**决策**: 选择方案 A。
**理由**: 真实下线必须发生在运行代理内核的进程内，本地强执行可以最小化超额后的继续服务窗口。
**影响**: `mi-node` 服务层成为限额执行源，Xboard 负责配置和展示。
### node-traffic-limit-enforcement#D002: 复用 `transfer_enable` 作为节点月额度
**日期**: 2026-04-28
**状态**: ✅采纳
**背景**: Xboard 已有 `v2_server.transfer_enable/u/d` 字段和管理端流量统计展示。
**选项分析**:
| 选项 | 优点 | 缺点 |
|------|------|------|
| A: 复用 `transfer_enable` | 避免重复额度字段，兼容已有过滤与展示 | 字段语义需要在 UI 中明确为节点月额度 |
| B: 新增 `traffic_limit_bytes` | 语义独立 | 与现有 `transfer_enable` 容易重复和不同步 |
**决策**: 选择方案 A。
**理由**: 现有字段已经是节点流量上限，新增启用和重置规则即可表达“每月额度”。
**影响**: 保存 payload、模型 casts、下发配置和 UI 显示都以 `transfer_enable` 为额度来源。
---
## 6. 验证策略
```yaml
verifyMode: test-first
reviewerFocus:
- mi-node suspended 状态下所有内核启动路径是否被 gate 住。
- Xboard 限额字段变化是否一定触发 config sync。
- 手动重置是否同时清面板统计并通知节点恢复。
testerFocus:
- go test ./...
- cd admin-frontend && npm run build
- PHP 可用时执行 php artisan test 或针对新增测试执行 vendor/bin/phpunit
- 节点配置接口返回 traffic_limit 结构
- mi-node 超额 stop、重置 start、重启恢复状态
uiValidation: optional
riskBoundary:
- 不执行生产数据库迁移。
- 不推送远端、不部署生产环境。
- 不修改与节点限额无关的 show/auto_online/gfw 检测策略。
```
---
## 7. 成果设计
### 设计方向
- **美学基调**: 工具型运维界面，保持节点工作台既有密度和控件体系，新增内容以紧凑表单行、状态标签和进度信息呈现。
- **记忆点**: 节点流量浮层中出现一条清晰的“额度进度 + 下次重置 + 限额状态”信息带。
- **参考**: 延续当前 `NodesView.vue` 和 `NodeEditorDialog.vue` 的 Element Plus 管理端风格。
### 视觉要素
- **配色**: 使用现有状态色，正常为绿色，接近限额为橙色，限额下线为红色，避免引入新的主视觉体系。
- **字体**: 沿用项目当前字体栈，避免在管理端局部引入不一致字体。
- **布局**: 节点编辑弹窗在基础配置区增加“流量限额”配置组；节点列表流量 popover 在今日/本月/累计后增加额度状态。
- **动效**: 仅使用 Element Plus 表单显隐和 loading 状态，不新增装饰动效。
- **氛围**: 保持运维工具克制、可扫描，避免营销式说明文字。
### 技术约束
- **可访问性**: 开关、输入框、时间选择器保留明确 label；状态不只靠颜色表达。
- **响应式**: 编辑弹窗使用现有 grid/form 布局，在窄屏下自动换行。
.helloagents/archive/2026-04/202604281921_node-traffic-limit-enforcement/tasks.md
+119
View File
@@ -0,0 +1,119 @@
# 任务清单: node-traffic-limit-enforcement
> **@status:** completed | 2026-04-29 00:21
> **LIVE_STATUS:** completed | completed=11 failed=0 pending=0 total=11 percent=100 current=验收完成，准备归档
```yaml
@feature: node-traffic-limit-enforcement
@created: 2026-04-28
@status: completed
@mode: R2
@package: 202604281921_node-traffic-limit-enforcement
```
## 进度概览
| 完成 | 失败 | 跳过 | 总数 |
|------|------|------|------|
| 11 | 0 | 0 | 11 |
---
## 任务列表
### 1. Xboard 数据与接口
- [√] 1.1 修改 `database/migrations/*_add_*_to_v2_server_table.php`、`app/Models/Server.php`
- 预期变更: 新增节点限额启用、重置日、重置时间、时区、状态时间戳字段；补齐 casts 和属性语义。
- 完成标准: `v2_server` 可保存限额配置和运行状态；未设置时默认不启用。
- 验证方式: 代码审查 migration up/down 与 casts；PHP 可用时执行语法检查或迁移测试。
- depends_on: []
- [√] 1.2 修改 `app/Http/Requests/Admin/ServerSave.php`、`app/Http/Controllers/V2/Admin/Server/ManageController.php`
- 预期变更: 管理端保存和批量/手动重置入口支持限额字段，手动重置清理面板限额状态并通知节点。
- 完成标准: 节点保存 payload 可包含限额字段；重置节点流量后 `u/d` 与限额状态一起清理。
- 验证方式: 审查 validation、save/update/resetTraffic/batchResetTraffic 路径；PHP 可用时执行相关测试。
- depends_on: [1.1]
- [√] 1.3 修改 `app/Services/ServerService.php`、`app/Observers/ServerObserver.php`、`app/Services/NodeSyncService.php`
- 预期变更: `buildNodeConfig()` 下发 `traffic_limit`；限额字段变化触发 `sync.config`；metrics 缓存限额状态。
- 完成标准: 配置接口返回完整 `traffic_limit` 结构；节点上报 metrics 后管理端能读取限额状态。
- 验证方式: 静态审查 config 结构和 observer 触发字段；PHP 可用时补接口/单元测试。
- depends_on: [1.1, 1.2]
- [√] 1.4 新增或扩展 Xboard 定时重置逻辑，作用范围 `app/Console`、`app/Services`
- 预期变更: 到达节点重置时间时清理面板 `u/d` 与限额状态，并推送节点配置同步。
- 完成标准: 自动重置不会影响未启用限额节点；短月重置日按当月最后一天处理。
- 验证方式: 代码审查时间计算；PHP 可用时补服务测试。
- depends_on: [1.1, 1.3]
### 2. Xboard 管理端
- [√] 2.1 修改 `admin-frontend/src/types/api.d.ts`、`admin-frontend/src/utils/nodeEditorOptions.ts`、`admin-frontend/src/utils/nodeEditorMapper.ts`
- 预期变更: 前端类型、表单模型、节点保存映射支持月额度、限额开关、重置日、重置时间、时区。
- 完成标准: 新建/编辑节点时限额字段能正确回填和提交；禁用限额时提交安全默认值。
- 验证方式: `cd admin-frontend && npm run build`。
- depends_on: [1.2]
- [√] 2.2 修改 `admin-frontend/src/views/nodes/NodeEditorDialog.vue`、`admin-frontend/src/views/nodes/NodesView.vue`、`admin-frontend/src/utils/nodes.ts`
- 预期变更: 编辑弹窗新增流量限额配置区；节点列表/流量浮层展示额度、使用量、状态和下次重置。
- 完成标准: UI 文案简洁；状态不只依赖颜色；移动宽度下不挤压原有控件。
- 验证方式: `cd admin-frontend && npm run build`，必要时人工检查节点页。
- depends_on: [2.1, 1.3]
### 3. mi-node 协议与执行
- [√] 3.1 修改 `internal/panel/types.go`、`internal/model/types.go`、`internal/model/panel.go`、`internal/controlplane/mailbox.go`
- 预期变更: 新增 `TrafficLimit` 配置结构，并完成 REST/WS/machine mailbox 转换和 clone。
- 完成标准: 新字段可从 Xboard 配置进入 `NodeSpec`，machine mode 不丢字段。
- 验证方式: `go test ./internal/model ./internal/controlplane` 或 `go test ./...`。
- depends_on: [1.3]
- [√] 3.2 新增 `internal/trafficlimit` 或同等职责包
- 预期变更: 实现周期窗口、短月重置日、双向增量累加、suspended 判定、本地 JSON 持久化和 metrics snapshot。
- 完成标准: 单元测试覆盖未启用、超额、重置、短月、重启恢复。
- 验证方式: `go test ./internal/trafficlimit`。
- depends_on: [3.1]
- [√] 3.3 修改 `internal/tracker/tracker.go`、`internal/service/service.go`
- 预期变更: tracker 暴露本 tick 节点总增量；Service 在 track tick 后检查限额，超额 `kernel.Stop()`，重置后恢复 `startKernel()`，并阻止 suspended 状态下自动启动。
- 完成标准: `ensureRunning()`、`applyChanges()`、用户更新路径不会绕过 suspended gate；metrics 包含 `traffic_limit`。
- 验证方式: `go test ./internal/service ./internal/tracker` 或 `go test ./...`。
- depends_on: [3.2]
### 4. 验证与知识库
- [√] 4.1 补充 Xboard 与 mi-node 相关测试
- 预期变更: 为 Xboard 配置下发/重置服务、mi-node 限额状态机和 service gate 补核心测试。
- 完成标准: 测试覆盖超额下线、到点恢复、手动重置通知、短月重置。
- 验证方式: `go test ./...`；PHP 测试在本机运行时可用时执行。
- depends_on: [1.4, 3.3]
- [√] 4.2 运行验收并同步知识库
- 预期变更: 执行可用验证命令；更新 `.helloagents/context.md`、模块文档、`CHANGELOG.md`，并记录验证结果。
- 完成标准: 验收报告列出通过项、受阻项和残余风险；方案包状态更新为 completed 或标明失败原因。
- 验证方式: `go test ./...`、`cd admin-frontend && npm run build`、知识库 diff 审查。
- depends_on: [4.1]
---
## 执行日志
| 时间 | 任务 | 状态 | 备注 |
|------|------|------|------|
| 2026-04-28 19:21 | 方案包初始化 | completed | 用户选择方案 1：节点本地强执行 + 面板配置编排；子代理构思按主代理直接执行记录 |
| 2026-04-28 20:32 | Xboard 限额配置与管理端 | completed | 新增限额字段、配置下发、重置服务、节点编辑表单和流量浮层展示 |
| 2026-04-28 20:34 | mi-node 限额执行 | completed | 新增本地持久化限额管理器、tracker 双向增量、内核停启 gate 和 metrics |
| 2026-04-28 20:36 | 测试与验证 | completed | go test ./...、admin-frontend npm run build、PHP 语法检查通过；Laravel PHPUnit 因缺 vendor/autoload.php 未运行 |
| 2026-04-28 20:37 | 知识库同步 | completed | 更新 Xboard 与 mi-node 模块文档、上下文和 CHANGELOG |
---
## 执行备注
- 本轮不执行生产部署、不运行生产数据库迁移、不推送远端。
- 子代理调度因当前主代理工具约束降级为主代理直接执行，后续任务按同一职责清单串行落地。
- `transfer_enable` 复用为节点月流量额度；新增字段只负责启用、重置规则和限额运行状态。
- 已补充 Xboard `ServerTrafficLimitServiceTest` 与 mi-node `trafficlimit/service/tracker` 相关测试；本机缺少 `vendor/autoload.php`，Laravel PHPUnit 未执行，仅完成 PHP 语法检查。
- 可用验收结果：`go test ./...` 通过；`admin-frontend npm run build` 通过；本轮 PHP 文件 `php -l` 通过。
.helloagents/archive/_index.md
+2
View File
@@ -7,6 +7,7 @@
| 时间戳 | 名称 | 类型 | 涉及模块 | 决策 | 结果 |
|--------|------|------|---------|------|------|
| 202604281921 | node-traffic-limit-enforcement | implementation | node-traffic-limit,admin-frontend,mi-node | node-traffic-limit-enforcement#D001,#D002 | ✅完成 |
| 202604281625 | admin-frontend-node-traffic-hover | - | - | - | ✅完成 |
| 202604281632 | admin-frontend-node-auto-online-immediate-sync | - | - | - | ✅完成 |
| 202604281441 | fix-admin-node-gfw-null-enabled | implementation | node-gfw-check,admin-frontend | fix-admin-node-gfw-null-enabled#D001 | ✅完成 |
@@ -46,6 +47,7 @@
## 按月归档
### 2026-04
- [202604281921_node-traffic-limit-enforcement](./2026-04/202604281921_node-traffic-limit-enforcement/) - 新增节点月流量限额强制下线能力，Xboard 负责配置、重置调度和状态展示，mi-node 负责本地额度累计、内核停止与重置恢复
- [202604281441_fix-admin-node-gfw-null-enabled](./2026-04/202604281441_fix-admin-node-gfw-null-enabled/) - 修复 `parent_id=0` 父节点不会被自动墙检入队导致长期显示“未检测”的问题，并让自动墙检查询对齐项目父节点与启用语义
- [202604281303_xboard-reusable-server-deploy](./2026-04/202604281303_xboard-reusable-server-deploy/) - 新增可复制到服务器的 Xboard Compose 部署模板，补齐独立 `scheduler` 服务，并提供 `.env.example`、初始化/部署/更新/状态检查脚本和部署说明
- [202604281258_fix-send-email-job-timeout](./2026-04/202604281258_fix-send-email-job-timeout/) - 修复 `SendEmailJob` 10 秒超时导致 `send_email` 队列批量失败的问题，补齐邮件 job 超时/backoff、SMTP transport timeout、运行时 mailer 刷新和 MailLog 配置脱敏