inp2p/ARCH_V1_USER_NETWORK.md

INP2P 最终方案 v1（用户网络模型）

状态：已冻结（按 2026-03-03 讨论结论） 目标：稳定优先，先完成认证/网络模型收敛，再做增量体验优化。

---

0. 冻结决策（已确认）

1. 一账号=一网络（1:1）
2. Hub 离线自动回 Mesh
3. 改 IP 后：目标节点重连 + 同网广播更新
4. API Key：保留后台能力，前台不突出
5. 暂不上 Refresh Token
6. Node 唯一标识采用 UUID（稳定优先）

---

1. 核心对象模型

1.1 Account（账号）

• 控制台登录主体（人）
• 字段：
  • account_id (int64 PK)
  • username (unique)
  • password_hash
  • status (1/0)
  • created_at

1.2 Network（用户网络）

• 每个账号唯一绑定一个网络
• 字段：
  • network_id (int64 PK)
  • account_id (unique FK -> accounts)
  • cidr (e.g. 10.0.1.0/24)
  • mode (mesh|hub)
  • hub_node_id (nullable, FK -> nodes.node_id)
  • fallback_to_mesh (bool, default true)
  • status (1/0)
  • created_at, updated_at

1.3 Node（设备）

• 设备唯一标识不变；展示名可变
• 字段：
  • node_id (UUID, PK) ✅ 后端唯一键
  • network_id (FK)
  • hostname (设备上报)
  • alias (用户自定义昵称，可空)
  • virtual_ip (network cidr 内)
  • node_secret_hash
  • relay_enabled (bool)
  • online (bool)
  • last_seen
  • created_at, updated_at

1.4 凭证对象

• session_tokens（控制台会话，短期）
• enroll_tokens（一次性/短期入网码）
• api_keys（后台自动化，非控制台主要路径）

---

2. 凭证与认证边界（彻底拆分）

2.1 会话 token（控制台）

• 登录成功后返回 session_token
• 内含：account_id, network_id, role=owner, exp
• 用于所有控制台 API

2.2 enroll token（设备入网）

• 控制台生成，一次性，短时有效（默认 10 分钟）
• 设备携带 hostname + enroll token 兑换 node_id + node_secret + virtual_ip

2.3 node_secret（设备长期）

• 设备 WS 登录凭证
• 仅设备连接信令使用，不用于控制台

2.4 API Key（后台能力）

• 用于自动化脚本/平台对接
• 不作为控制台默认登录路径
• 前台不突出，仅高级设置页可见

---

3. 网络与 IPAM 规则

3.1 子网分配

• 池：10.0.1.0/24 ~ 10.0.254.0/24
• 保留：10.0.0.0/24、10.0.255.0/24
• 账号注册时分配第一个可用网段

3.2 地址分配

• 每网络内自动分配：从 .2 开始
• 保留 .0/.255/.1
• 禁止重复占用

3.3 手动改 IP

• 必须在网络 CIDR 内
• 不可与现有节点冲突
• 成功后触发：
  1. 目标节点收到 ip_changed 推送并重连
  2. 服务端广播 peer_ip_changed 给同网在线节点

---

4. 拓扑模式状态机

4.1 Mesh（默认）

• 同网节点按策略尝试直连（UDP/TCP）
• 失败后按中继策略兜底

4.2 Hub

• 条件：hub_node_id 必填，且必须“在线 + 同网络 + relay_enabled=true”
• 数据面按 hub 转发

4.3 Hub 离线回退

• 监测阈值：15~30 秒无心跳
• 自动回 mesh（记录审计日志）
• Hub 恢复后暂不自动切回（v1 简化）

---

5. API 草图（v1）

5.1 认证

• POST /api/v1/auth/register
  • req: {username,password}
  • rsp: {account_id, network:{cidr,mode}}
• POST /api/v1/auth/login
  • req: {username,password}
  • rsp: {session_token, expires_in, network}
• POST /api/v1/auth/logout

5.2 网络配置

• GET /api/v1/network
• POST /api/v1/network/mode
  • req: {mode:"mesh"|"hub", hub_node_id?}
• POST /api/v1/network/hub
  • req: {hub_node_id}（含在线校验）

5.3 节点管理

• GET /api/v1/nodes
• POST /api/v1/nodes/{node_id}/alias
  • req: {alias}
• POST /api/v1/nodes/{node_id}/ip
  • req: {virtual_ip}
• POST /api/v1/nodes/{node_id}/kick

5.4 入网与设备凭证

• POST /api/v1/enroll/create
• POST /api/v1/enroll/revoke/{id}
• POST /api/v1/enroll/consume
  • req: {code, hostname}
  • rsp: {node_id, node_secret, virtual_ip, network_cidr}

5.5 自动化（低显著）

• GET/POST /api/v1/settings/api-keys

---

6. 前端展示规范

• 节点主显示名：alias || hostname
• 次级显示：node_id（短）
• 明确区分：
  • "控制台会话"（session）
  • "设备凭证"（node_secret）
  • "自动化凭证"（api key）
• API Key 页面放到“高级设置”折叠区，不作为主流程入口

---

7. 迁移计划（分阶段）

Phase A（认证收敛，必做）

1. auth/login 改为返回 session token，不再返回 API key
2. 中间件基于 session 解出 account_id/network_id
3. 控制台 API 全量改用 session 鉴权

Phase B（节点模型升级）

1. 引入 node_id(UUID)
2. 增加 alias 字段
3. 节点唯一性改以 node_id 为准（非 hostname）

Phase C（IPAM + 拓扑闭环）

1. 改 IP 重连与广播机制
2. Hub 在线校验 + 自动回 mesh
3. 观测与审计日志完善

---

8. 验收标准（v1）

1. 用户登录后拿到 session token（不是 API key）
2. 同一网络外的数据不可见
3. 改 IP 后目标节点重连，其他节点收到变更通知
4. hub 下线后自动回 mesh
5. node_id 在重命名 hostname/alias 后仍不变
6. API Key 不影响控制台主流程

---

9. 风险与规避

• 风险：旧 token 体系与新 session 并存期可能混淆
  • 规避：版本开关 + 明确响应字段（token_type=session）
• 风险：节点重连窗口导致短时抖动
  • 规避：变更前提示 + 逐节点串行生效
• 风险：hub 恢复/掉线频繁导致模式抖动
  • 规避：加入最小驻留时间（如 60s）

---

10. 下一步实施顺序（立即执行）

1. 后端：新增 session token 生成/校验（无 refresh）
2. 后端：中间件切换到 session 识别 network
3. 前端：登录流程改读 session_token
4. 后端：保留 API key 能力但移出主登录流程
5. 回归联调：登录、节点、sdwan、connect、enroll、hub 回退