Hive

Appearance

Hive v1.0.0 节点兼容基础设施 Roadmap ​

本文只讨论一个前提：

  • 边缘节点保持 v1.0.0，暂不升级
  • 先把管理侧、本地基础设施、数据模型、后台能力搭起来
  • 后续按 roadmap 一项一项实现

这份 roadmap 是对 05-airport-roadmap.md 的收敛版，重点是“哪些现在就能做，且不要求节点改动”。

一、当前兼容基线 ​

从现有 v1.0.0 节点脚本看，节点当前只会在 provision 期间做一次注册，上报字段是：

  • mac
  • mac6
  • hostname
  • cf_url
  • tunnel_id
  • tailscale_ip
  • easytier_ip
  • frp_port
  • xray_uuid

也就是说，当前节点没有下面这些能力：

  • 周期性心跳
  • 主动上报版本号
  • 主动上报出口 IP / 国家 / ASN
  • 主动上报延迟、负载、在线人数、流量
  • 接收服务端动态配置
  • 每个用户独立 UUID / 独立鉴权

这几个限制会直接决定 roadmap 的边界。

二、必须先说清楚的限制 ​

1. 现在做不了“强用户控制” ​

当前节点使用的是节点级 UUID，不是用户级 UUID。

这意味着在不升级节点的前提下：

  • 可以做“用户专属订阅链接”
  • 可以做“按用户生成不同的节点列表”
  • 但不能真正做到用户过期后立刻失效
  • 也不能真正做到单用户封禁后立刻断开访问

原因很简单：

  • 用户一旦拿到某个节点的 vless://...uuid@host 配置
  • 节点侧仍然会接受这个 UUID
  • 服务端就算把订阅 token 禁掉，也阻止不了用户继续用已经导入的配置

所以在 v1.0.0 阶段，用户体系最多只能做 软控制，不能当成正式的强鉴权。

2. 现在做不了“真实心跳” ​

当前节点只在 provision 时调用一次 /nodes/register。

所以：

  • last_seen 不能当成可靠在线状态
  • 节点是否在线，只能通过服务端探测和旁路数据推断

3. 现在做不了“节点能力编排” ​

不升级节点的情况下，服务端只能使用现有字段做编排：

  • cf_url
  • xray_uuid
  • tailscale_ip
  • easytier_ip
  • frp_port
  • 管理员补充的 location、note

不能要求节点支持新协议、新路径、新认证方式。

三、Roadmap 总原则 ​

v1.0.0 阶段的目标不是一步到位做成完整平台，而是先把下面三层打稳：

  1. 管理平面可部署：服务端、数据库、UI、备份、监控、发布都稳定
  2. 节点资产可管理：节点有台账、有状态、有标签、有线路归属
  3. 订阅交付可运营：管理员能稳定生成和维护“线路化”的订阅

在这三个目标完成之前，不建议把重点放在正式用户套餐系统上。

四、本阶段只做的事项 ​

这一轮只做 100% 不需要升级 v1.0.0 边缘节点 的功能。

也就是只做下面这些：

  1. 管理平面部署标准化
  2. 数据库迁移、备份、恢复
  3. 节点台账增强
  4. 服务端探测状态
  5. 线路模型
  6. 订阅生成重构
  7. 管理后台基础设施页面
  8. 认证、RBAC、审计强化
  9. 监控、告警、发布、回滚流程

下面这些本阶段明确不做：

  • 用户正式套餐系统
  • 用户专属强鉴权
  • 到期即失效
  • 单用户封禁即时生效
  • 流量计费
  • 节点主动心跳
  • 节点版本上报
  • 服务端下发节点动态配置

五、需求清单与实施顺序 ​

下面按建议实施顺序列出，每一项后面都标明是否需要节点升级。

R1. 固化 v1.0.0 节点兼容契约 ​

目的：

  • 把当前节点真实上报字段、服务端依赖字段、兼容行为固定下来
  • 后续做服务端改造时，不误伤现有节点

交付物：

  • 一份 v1.0.0 节点兼容说明
  • 一份注册接口契约说明
  • 一份“哪些字段来自节点、哪些字段来自管理侧”的清单

是否需要节点升级：否

R2. 搭建可重复部署的管理平面 ​

目的：

  • 先把本地基础设施搭稳，后续功能才有落点

范围：

  • registry 服务部署
  • registry-ui 部署
  • MySQL 初始化
  • nginx / Cloudflare / 反向代理接入
  • 环境变量规范
  • systemd 或 compose 部署方式统一

交付物：

  • 一套标准部署脚本或部署手册
  • 一套开发 / 测试 / 生产环境变量模板
  • 一套启动、升级、回滚流程

是否需要节点升级：否

R3. 建立数据库迁移、备份、恢复机制 ​

目的：

  • 后面会加表、改表，没有迁移和备份，任何迭代都不安全

范围：

  • schema version 表
  • 迁移脚本
  • MySQL 定时备份
  • 恢复演练

交付物：

  • 可执行的 migration 机制
  • 自动备份任务
  • 恢复文档

是否需要节点升级：否

R4. 节点台账增强，但不改节点协议 ​

目的：

  • 继续使用现有注册字段，但把节点作为“基础设施资产”管理起来

范围：

  • 节点启用 / 禁用
  • 节点标签
  • 节点权重
  • 节点区域 / 国家 / 城市
  • 节点备注、维护状态、下线原因

交付物：

  • nodes 扩展字段或关联表
  • UI 中的筛选、标签、批量编辑能力

是否需要节点升级：否

R5. 用服务端探测补足“伪心跳” ​

目的：

  • 在节点不升级的前提下，尽量拿到可靠状态

可用探测源：

  • Prometheus node-exporter
  • Tailscale 可达性
  • cf_url HTTP / TLS 探测
  • FRP 端口连通性
  • 最近注册时间

交付物：

  • node_status_checks 或等价状态表
  • 周期性探测任务
  • Dashboard 上的“在线 / 异常 / 不可达 / 未知”状态

是否需要节点升级：否

说明：

  • 这里得到的是“服务端推断状态”，不是节点主动心跳
  • 先够用，后续节点升级时再替换成真实 heartbeat

R6. 把“订阅分组”升级成“线路管理” ​

目的：

  • 当前分组太像临时清单，不像正式交付模型
  • 不升级节点也完全可以先做线路层

范围：

  • lines
  • line_nodes
  • inbounds 或等价入口定义
  • 线路名称、排序、区域、展示文案、启用状态

交付物：

  • 线路管理 API
  • 线路管理 UI
  • 节点与线路绑定能力

是否需要节点升级：否

R7. 重构订阅生成逻辑 ​

目的：

  • 从“导出全部节点 / 导出分组节点”切到“导出线路化内容”

范围：

  • 线路级 VLESS 订阅
  • 线路级 Clash/Mihomo 订阅
  • 订阅命名规则
  • 订阅模板规范

交付物：

  • 新的订阅生成层
  • 与旧 subscription_groups 并行兼容一段时间

是否需要节点升级：否

R8. 管理后台补齐基础设施视角的页面 ​

目的：

  • 让后台先像“基础设施控制台”，再谈用户侧产品

优先页面：

  • 节点状态页
  • 线路管理页
  • 订阅模板页
  • 运维任务 / 审计页

交付物：

  • registry-ui 新页面与导航
  • 更强的列表筛选、批量操作、状态查看

是否需要节点升级：否

R9. 强化认证、RBAC 与审计 ​

目的：

  • 先把管理面安全打稳

范围：

  • 设备认证与管理员认证彻底分离
  • API Secret 轮换机制
  • 更细粒度 RBAC
  • 节点变更、线路变更、订阅变更审计

交付物：

  • 新权限项
  • 更完整的审计日志
  • 凭据轮换流程

是否需要节点升级：否

R10. 建立监控、告警与值班基础设施 ​

目的：

  • 你现在要搭的是“基础设施”，那监控和告警必须一起落

范围：

  • registry 自身指标
  • MySQL 健康
  • 任务探测失败告警
  • 节点大面积离线告警
  • 订阅生成失败告警

交付物：

  • Prometheus 规则
  • Grafana 看板
  • 告警通道

是否需要节点升级：否

R11. 做发布流程与回滚流程 ​

目的：

  • 后续我们一项一项实现时，必须能安全上线

范围：

  • 发布步骤标准化
  • 数据库迁移顺序
  • UI 构建与静态资源发布
  • 回滚预案

交付物：

  • 发布 runbook
  • 回滚 runbook
  • 发布前检查清单

是否需要节点升级：否

R12. 预埋未来用户系统的数据模型，但暂不做强业务闭环 ​

目的：

  • 可以先把未来会用到的表和接口设计好
  • 但不要在 v1.0.0 阶段误以为已经具备正式用户管控

可做内容：

  • customers
  • plans
  • plan_lines
  • subscription_tokens

当前限制：

  • 这些能力在 v1.0.0 阶段只能提供“软控制”
  • 不能承诺到期即断、封禁即失效、单用户计量准确

是否需要节点升级：部分需要

建议：

  • 这项排在基础设施之后
  • 先做表设计和接口草案，不急着正式上线运营

状态：本阶段不做

六、v1.0.0 阶段暂缓事项 ​

下面这些不是不能做，而是不应该在当前阶段优先做：

  • 用户正式套餐系统
  • 支付与订单
  • 流量计费
  • 用户设备数强限制
  • 用户到期后即时失效
  • 单用户封禁即时生效
  • 节点主动心跳
  • 节点版本与配置上报
  • 服务端下发节点动态配置

其中前 6 项的核心阻塞点，是当前节点仍然使用节点级 UUID。

七、推荐的第一阶段实现包 ​

如果按“先把基础设施搭好”的目标，建议第一阶段只做下面 6 个包：

  1. R2 管理平面部署标准化
  2. R3 数据库迁移与备份恢复
  3. R4 节点台账增强
  4. R5 服务端探测状态
  5. R6 线路模型
  6. R9 认证与审计强化

这 6 项做完，你们的本地基础设施就从“能跑”升级成“可维护、可扩展、可上线”。

八、建议的逐项实施顺序 ​

建议严格按下面顺序来：

  1. 先做 R2
  2. 再做 R3
  3. 再做 R9
  4. 再做 R4
  5. 再做 R5
  6. 再做 R6
  7. 再做 R7
  8. 再做 R8
  9. 最后再讨论 R12

原因：

  • 没有部署规范，后续功能没有稳定落点
  • 没有迁移和备份，不适合开始改数据模型
  • 没有认证和审计，管理面风险太高
  • 没有线路模型，订阅就还是临时清单

九、下一步 ​

下一轮最适合直接开始的是：

  • 把 R2 拆成具体任务

也就是先明确：

  • 本地基础设施到底采用什么部署方式
  • registry、registry-ui、MySQL、nginx 分别怎么跑
  • 配置文件放哪里
  • 如何升级、回滚、备份

这部分一旦定下来，后面每个需求都可以按同一套基础设施方式往上叠。