skycurtain
e4d25526f3
- 需求清单：独立计费平台定位，R1-R15 全部定案（12 项裁决 + R10 裁撤 + R3/R4 延后），裁决档案含访问主体模型（作者登录体系 + 成员长期令牌）、分摊哲学（平台不做价值判断只提供事实服务）、双形态交付（完整前后端先行，CFW 抽取版后续） - 数据模型定稿（一表一文档）：api_keys（16 列，401 状态机裁撤——引擎记录不决策）/ usage_logs（25 列，billing_source 与 subscription_id 提列，非消费行去重含 content 指纹）/ payments（币种无关支付记录，只存事实）/ qpu_history（按日志时刻取值）/ members（成员实体与长期令牌）/ users（空库双通道初始化与重置）/ sessions（服务端会话，否决 JWT） - 接口参考：NewAPI-接口范围融合字段级实证，定位 docs/references/（计费平台可用接口参考，唯一上游参考） - README / AGENTS：新版设计语境（项目沿革、重开设计动因、协作约定、文档自立原则）
64 lines
3.3 KiB
Markdown
64 lines
3.3 KiB
Markdown
# sessions 表字段设计
|
||
|
||
> 数据模型新增表之三：管理面会话——HttpOnly cookie 里的令牌与服务端状态的对应物。裁决背景见 `docs/design/需求清单.md` §9「访问主体模型」。
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 状态 | 定稿（2026-10-01） |
|
||
| 关联 | `docs/design/users表字段设计.md`（`user_id` 指向）· `docs/design/需求清单.md` §9 |
|
||
| 范围 | 列结构 + 语义 + 写入时机；cookie 参数（SameSite 等）归技术稿；方言映射归数据访问层设计 |
|
||
| 字段数 | 5 = 1 主键 + 4 业务字段 |
|
||
|
||
---
|
||
|
||
## 1. 表定位
|
||
|
||
- **一行 = 一次活跃登录**——登录成功 INSERT，登出 / 过期 DELETE
|
||
- 浏览器侧只持有令牌明文（HttpOnly cookie），服务端只存哈希
|
||
- **唯一服务对象是管理面（作者）登录**——`user_id` 指向单行的 `users` 表；成员链路**不经此表**（成员凭证是 `members.token_hash` 长期令牌，无会话语义，辨析见 `members表字段设计.md` 3.2）
|
||
|
||
## 2. 字段清单
|
||
|
||
| 列 | 类型 | 值来源 | 说明 |
|
||
|----|------|--------|------|
|
||
| `id` | bigserial PK | 自增 | |
|
||
| `user_id` | bigint FK | 登录成功时 | → `users.id` |
|
||
| `token_hash` | text UNIQUE | 登录成功时 | 会话令牌（随机 256bit）的哈希——cookie 存明文、库存哈希 |
|
||
| `expires_at` | timestamptz | 登录成功时 | 过期时间（如 7 天）；过期即拒绝 |
|
||
| `created_at` | timestamptz | 登录成功时 | |
|
||
|
||
## 3. 决策记录（含理由）
|
||
|
||
### 3.1 服务端会话（查库校验），明确否决 JWT
|
||
|
||
- **JWT 的问题域我们没有**：JWT（无状态令牌）的收益在多服务共享认证、水平扩展免共享存储、海量会话——本项目是单后端、单实例、单管理员，收益一项不占，负担全额缴纳
|
||
- **不可吊销是致命伤**：JWT 签发后、过期前无法作废——登出仅是客户端删 cookie（令牌仍有效）、踢下线做不到、改密后旧会话无法失效；业界绕法「短过期 + refresh token」需要服务端存储 refresh token，绕回有状态，JWT 的唯一优势随之蒸发
|
||
- **多一个要管理的秘密**：签名密钥的保管、轮换、泄露处置，凭空多一项运维（CFW 形态下多一处 secret 配置）
|
||
- **本设计即业界最佳实践的翻译**：随机 256bit 令牌、哈希存储、`HttpOnly`/`Secure`/`SameSite`、服务端校验、过期拒绝、登出即吊销——对应 OWASP Session Management Cheat Sheet 逐条要求；「成熟」体现在模式本身。现成认证库的评估归实现期技术稿，模式不变
|
||
|
||
### 3.2 令牌哈希存储
|
||
|
||
拖库不泄会话令牌。
|
||
|
||
### 3.3 过期清理为惰性删除
|
||
|
||
校验命中过期行即删 + 拒绝；不建定时清理任务——过期行占用量级：个位数/月，无清理压力。
|
||
|
||
### 3.4 单设备多会话不互斥
|
||
|
||
同一账号可多处登录（各自行）——单人场景无需「顶号」语义。
|
||
|
||
## 4. 写入时机
|
||
|
||
| 时机 | 动作 |
|
||
|------|------|
|
||
| 登录成功 | INSERT（用户名 + PBKDF2 验证密码通过） |
|
||
| 登出 | DELETE 该行 |
|
||
| 校验命中过期行 | DELETE + 拒绝（惰性清理） |
|
||
|
||
## 5. 待定事项
|
||
|
||
| 事项 | 归属 |
|
||
|------|------|
|
||
| cookie 参数（`HttpOnly` / `Secure` / `SameSite=Lax` / Path 限管理面）、会话时长取值 | 技术稿 |
|