设备 & 会话管理 + 每设备流量归因（设计方案）

Pangolin · 「我的设备」管理 + 控制面会话 + 数据面按设备记账 · 2026-06-28

一句话：后端绝大部分已经建好，只是「没接线」。devices 表、每设备数据面凭证 dp_uuid、 usage_device_daily、设备列表/删除接口都在——但 RegisterIfAbsent 生产代码从不调用，导致 devices 表永远是空的，整条每设备链路退回账户级。本方案 = 打通三条已存在的链路 + 新增 sessions 表，让设备/会话/每设备流量三件事一次成型。

1. 背景与现状（已建 vs 缺口）

排查三端（控制面 Go / 数据面 sing-box / 客户端 Flutter）后的对照：

能力	现状	位置	缺口
devices 表 + 列表/删除接口	已建	`migrations/*/000001`、`internal/devices/{store,service,handler}.go`、`GET/DELETE /v1/me/devices`	表始终为空（无人写入）
设备隐式注册 `RegisterIfAbsent`	未接线	`devices/service.go`	已实现，生产请求路径从不调用（仅单测用）
每设备数据面凭证 `dp_uuid`	就绪未生效	`migrations/*/000015`、`nodes/store.go: EnsureDeviceDpUUID`	依赖 device 行存在；表空 → 退回账户级 `users.dp_uuid`
每设备用量表 `usage_device_daily`	就绪未生效	`migrations/*/000015`、`nodes/store.go: AccumulateDeviceUsage`	因 deviceID 永为 0 → 从不写入
sing-box 按 dp_uuid 计量	已建	`agentd/render.go`、`usage_v2ray.go`	无（已按 `user>>>{dp_uuid}>>>traffic` 计量、reset 取增量）
会话（JWT + Redis 白名单）	已建	`auth/token.go`（access 15min / refresh 30day）	会话不绑设备 → 无法「按设备强制退出」
客户端「我的设备」页	已建	`widgets/account_screens.dart: DevicesScreen`	无在线状态/客户端版本；操作仅「移除」
客户端设备身份	硬编码	`connection_provider.dart: _kDeviceId='mac-001'`	固定值；版本（`appVersionProvider` 有）没上报

核心缺口一句话：RegisterIfAbsent 没被调用 → devices 表空 → EnsureDeviceDpUUID 找不到设备行 → 退回账户级 dp_uuid → UserDeviceByDpUUID 返回 deviceID=0 → AccumulateDeviceUsage 被 if deviceID>0 跳过 → usage_device_daily 永远空。补上「登录即注册设备」这一步，整条链路自洽。

已确认的设计决策

在线判定 = 数据面在线：devices.last_seen 在阈值内（建议 3 分钟）才算「在线」，另列「最后登录时间」。
两个操作：强制退出 = 吊销该设备会话踢下线（设备留在列表）；清除登录信息 = 彻底移除（删设备 + 吊销会话 + 吊销 dp_uuid）。
会话存储 = 新增 sessions 表（DB，可查历史、能按设备精准吊销），保留 Redis 白名单做快速校验。

2. 总体架构（三端数据流）

三支柱：设备身份（客户端稳定 UUID + 上报元数据）→ 会话（每次登录建 session 绑设备）→ 每设备流量（设备注册后 dp_uuid 自然铺开）。

  CLIENT (Flutter)              CONTROL PLANE (Go)                AGENT + SING-BOX
  ───────────────              ──────────────────                ────────────────
  device_id (UUID v4,           POST /auth/login|register
   secure storage)        ──▶    body: device{id,name,                 ┌───────────────┐
  name / platform /              platform,client_version}              │ devices 表    │
  client_version (上报)          │  ├─ RegisterIfAbsent ──────────────▶│ (终于被填充)  │
                                 │  └─ TokenManager.Issue              └───────┬───────┘
                                 │       └─ INSERT sessions(jti,device)        │
                                 │                                     EnsureDeviceDpUUID
  POST /v1/nodes/{id}/connect ─▶ ConnectNode                          铸 per-device dp_uuid
  body: {device_id}              │  └─ EnsureDeviceDpUUID ────推 Hub──▶ 下发 sing-box
                                 │       (命中 device 行)              VLESS user.uuid=dp_uuid
                                 │                                            │
                                 ◀── ReportUsage(dp_uuid,up,down) ── sing-box 按 dp_uuid 计量
                                 │     UserDeviceByDpUUID→(user,device)  user>>>{dp_uuid}>>>traffic
                                 │     ├─ AccumulateUsage     (账户级 usage_daily)
                                 │     ├─ AccumulateDeviceUsage(设备级 usage_device_daily)
  GET /v1/me/devices ◀───────────┤     └─ touch devices.last_seen ← 驱动「在线」判定
  {name,platform,client_version, │
   online,last_login}            │  POST /v1/me/devices/{uuid}/logout → 吊销 session（强制退出）
                                 │  DELETE /v1/me/devices/{uuid}       → 删设备+吊销会话+吊销 dp_uuid

3. 数据模型

3.1 新增 `sessions` 表（migration 000016，mysql + sqlite）

每次登录一条；绑定设备与 refresh-token JTI，支撑「按设备强制退出 / 最后登录 / 会话历史」。SQL 走中性方言（不用 NOW()/UTC_TIMESTAMP()，时间 Go 端算好传参）。

sessions(
  id            INTEGER PK AUTOINCREMENT,
  user_id       NOT NULL,            -- FK users.id
  device_id     NOT NULL,            -- FK devices.id（会话归属哪台设备）
  refresh_jti   TEXT NOT NULL UNIQUE,-- 绑定当前 refresh token 的 JTI
  client_ip     TEXT,                -- 登录来源 IP
  client_version TEXT,               -- 登录时客户端版本（历史留痕）
  created_at    DATETIME NOT NULL,   -- 登录时间（设备「最后登录」取最近一条）
  last_active   DATETIME,            -- refresh 轮换时更新
  revoked_at    DATETIME NULL        -- 强制退出/登出置位；非空=已失效
)
INDEX (user_id), INDEX (device_id), UNIQUE (refresh_jti)

时机	对 sessions 的动作
登录 / 注册	`TokenManager.Issue` 同事务 `INSERT` 一条（写 device_id / jti / ip / version / created_at）
刷新令牌	rotation：更新该行 `refresh_jti`（新 jti）+ `last_active`
登出	按 refresh-jti 置 `revoked_at=now` + Redis 删 jti
强制退出	按 device_id 把该设备所有未撤销 session 置 `revoked_at` + Redis 删各 jti

3.2 `devices` 表加列（同迁移）

列	类型	用途
`client_version`	TEXT NULL	该设备最近上报的客户端版本，列表展示
`totp_trusted_until`	DATETIME NULL	预留：未来 2FA「信任设备」过期点；清除登录信息时一并清空

既有列：uuid / user_id / name / platform / last_seen / created_at / dp_uuid(000015)。设备「最后登录时间」= 该设备最近一条 session.created_at（不复用 last_seen，后者是数据面活跃度）。

3.3 `usage_device_daily`（已存在，本方案使其真正写入）

usage_device_daily(user_id, device_id, date, bytes_up, bytes_down, minutes_used)
  PK(device_id, date)   -- 增量累加：bytes_up = bytes_up + EXCLUDED.bytes_up

账户总流量 = 账户级 usage_daily（AccumulateUsage 始终写）；设备明细 = usage_device_daily（AccumulateDeviceUsage，deviceID>0 时写）。二者由同一份 ReportUsage 增量同时落库。

4. API 增量一览

端点	变化
`POST /auth/login` `POST /auth/register`	请求体增 `device:{id,name,platform,client_version}` → 触发 `RegisterIfAbsent` + 建 session
`POST /auth/refresh`	更新 `session.last_active` + jti 轮换（同步换 session.refresh_jti）
`POST /auth/logout`	按 refresh-jti 置 `session.revoked_at`（+ Redis 删，已有）
`GET /v1/me/devices`	响应每项增 `client_version` / `online`(bool) / `last_login`(RFC3339)
`POST /v1/me/devices/{uuid}/logout`	新强制退出：吊销该设备所有 session
`DELETE /v1/me/devices/{uuid}`	增强：吊销 session + 真实吊销 dp_uuid（落地 `CredentialRevoker`，当前是 `NoopRevoker`）

5. 在线 / 离线判定（数据面在线）

在线 = devices.last_seen 距今 < 阈值（建议 3 分钟）。
谁刷 last_seen：① connect 时 touch；② ReportUsage 时 touch——连着时每 ~60s 一次。当前 handler_grpc.go: ReportUsage 解析 dp_uuid→(user,device) 后只累流量、不 touch last_seen，需补这一步。
前端：last_seen < 3min → 绿点「在线」；否则灰点「离线」，并显示「最后登录 · {time}」。

为什么不用「会话有效」当在线：refresh token 30 天，会话有效不代表正在用。VPN 语境下「在线」应是「此刻正连着节点走流量」，故以数据面 last_seen 为准。

6. 两个操作的语义

	强制退出	清除登录信息
端点	`POST …/devices/{uuid}/logout`	`DELETE …/devices/{uuid}`
会话	吊销该设备所有 session（revoked_at + Redis 删 jti）	同左（一并吊销）
devices 行	保留（仍在列表，转「离线/已退出」）	删除
数据面凭证 dp_uuid	不动（重登后仍可用）	吊销：经 `nodes.Hub` 给各节点推 upsert 去掉该 dp_uuid 的 sing-box user
效果	该设备下次 refresh 失败 → 需重新登录	设备从信任列表彻底剔除
未来 2FA	—	同时清 `totp_trusted_until` → 重登需重做 2FA

本机：列表高亮「本机」；本机一般不显示「强制退出」（或显示「退出登录」= 本地 logout）。删除/退出他机需二次确认弹窗（危险样式）。

7. 前端 UI（「我的 → 我的设备」）

沿用既有 DevicesScreen 卡片列表，行内信息扩展 + 行尾操作。颜色/字号/间距全走唯一真相源 token（pangolin_theme），不硬编码。

┌─────────────────────────────────────────────────────────────┐
│ [▦] MacBook Pro                        ● 在线        [ ⋯ ]   │   ⋯ 菜单:
│     macOS · v1.0.10 · 本机                                   │   ├ 强制退出
├─────────────────────────────────────────────────────────────┤   └ 清除登录信息
│ [▦] iPhone 15                          ○ 离线        [ ⋯ ]   │
│     iOS · v1.0.9 · 最后登录 2 小时前                          │
├─────────────────────────────────────────────────────────────┤
│ [▦] Windows-PC                         ○ 离线        [ ⋯ ]   │
│     windows · v1.0.10 · 最后登录 3 天前                       │
└─────────────────────────────────────────────────────────────┘
  PRO 套餐最多 5 台设备同时在线 · 已用 3 / 5

model Device 加 clientVersion / online(bool) / lastLogin(DateTime?)。
设备身份：弃用 _kDeviceId='mac-001'，首启生成 UUID v4 存 flutter_secure_storage；登录/注册请求体带 device:{id,name,platform,client_version}。
API/provider：account_api 加 forceLogout(uuid)；devicesProvider 加对应方法（remove 已有）。
l10n：新增在线/离线/客户端版本/最后登录/强制退出/清除登录信息/本机/确认弹窗（zh+en，app_text.dart + strings_{zh,en}.dart），脱敏不含红线词。

8. 实现路线（分期；本设计文档不含编码）

P1 · 设备注册打通 — 客户端稳定 device_id + 登录上报元数据；控制面接线 RegisterIfAbsent。
产出：「我的设备」列表显示真实登录过的设备（最大缺口闭合）。

P2 · sessions 表 + 在线/最后登录 — migration 000016；Issue/Refresh/Logout 写 session；ReportUsage touch last_seen；GET /devices 返回 online/last_login/client_version。

P3 · 两个操作 — 强制退出端点 + 清除增强（session 吊销 + CredentialRevoker 真实吊销 dp_uuid）。

P4 · 每设备流量验证 — 端到端确认 usage_device_daily 填充 + 统计页设备下拉接真数据（对接已有 deviceUsageProvider，呼应统计整改 #10）。

P5 · （未来）2FA 信任设备 — 清除登录信息联动 2FA 重验（totp_trusted_until）。

关联：统计体系整改（#5）（每设备归因 / 统计页设备下拉）· 功能 × 测试覆盖清单（设备/会话验收）。本文为设计方案；实现按 P1–P5 后续单独排期。