Files

T

skycurtain e4d25526f3 docs: 设计阶段定稿——需求清单（15 项全定案）与七篇表设计定稿

- 需求清单：独立计费平台定位，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：新版设计语境（项目沿革、重开设计动因、协作约定、文档自立原则）

2026-10-01 14:54:06 +08:00

3.5 KiB

Raw Blame History

users 表字段设计

数据模型新增表之二：管理员——登录体系的身份落点，实际只有一行（作者，唯一管理员）。裁决背景见 docs/design/需求清单.md §9「访问主体模型」。

项目	内容
状态	定稿（2026-10-01）
关联	`docs/design/sessions表字段设计.md`（登录会话指向本表）· `docs/design/需求清单.md` §9
范围	列结构 + 语义 + 写入时机；登录流程细节（PBKDF2 参数、节流）归技术稿；方言映射归数据访问层设计
字段数	4 = 1 主键 + 3 业务字段

1. 表定位

一行 = 一个管理员账号——本表设计为单行（作者），不存在注册路径
凭证经部署期初始化创建（env / wrangler secret 的引导凭证，空库幂等落库）——部署完成即就绪；空库且 env 无凭证时由引导页完成初始化（重置兜底通道，见 3.1）

2. 字段清单

列	类型	值来源	说明
`id`	bigserial PK	自增
`username`	text UNIQUE	部署期初始化	登录名
`password_hash`	text	部署期初始化 / 改密	PBKDF2-SHA256 哈希（WebCrypto 原生，两形态统一——Workers 无 argon2/bcrypt）
`created_at`	timestamptz	初始化时

3. 决策记录（含理由）

3.1 单行表，不做注册；初始化与重置 = 空库双通道

管理员账号由空库初始化创建；改密走登录后的表单（旧密码验证 → 落库）。「单行」是部署行为约定，不是 schema 约束——表结构天然支持多行，未来若需要多管理员 + 角色，扩展为增量动作（加 role 列 + 中间件分支 + 管理页），无需推倒任何东西。

管理面入口的幂等三态判断：

users 非空 → 登录页（如常）
空库 + env 凭证在 → 静默重建（部署与重置共用此通道；密码即 env 凭证）
空库 + env 凭证无 → 引导页（设置新用户名密码，直接进入登录态；users 非空后永不复现）

忘记密码的重置：删除 users 行（母体：请运营方执行一条 SQL；CFW：自助 wrangler d1 execute）→ 下一次请求触发三态判断 → 有 env 静默重建后改密，无 env 引导页当场设新密码。env 凭证可留可删、无依赖——留着享受静默重建，删了有页面兜底；抢注窗口仅存在于「删 env + 删行」的重置瞬间（作者主导、分钟级），部署路径（env 在）永远无窗口。

3.2 密码哈希选 PBKDF2-SHA256

WebCrypto 原生支持——母体与 CFW 抽取版同一实现（Workers runtime 无 argon2/bcrypt，选它们会造成两形态分叉）；迭代参数归技术稿。

3.3 不建多用户 / 角色引擎

管理操作只有作者一人——RBAC 无用武之地；权限边界由访问面物理隔离（管理面 API 与成员 API 两套路由）。

4. 写入时机

时机	动作
部署期初始化（双通道）	空库 + env 凭证在 → 静默 INSERT（幂等，已初始化则永远跳过）；空库 + env 凭证无 → 引导页设新密码后 INSERT（重置兜底）
改密（管理面表单）	UPDATE `password_hash`

改密落审计日志（审计为独立需求，表结构归技术稿）。

5. 待定事项

事项	归属
PBKDF2 迭代参数、登录失败节流策略	技术稿
审计日志表结构	技术稿

3.5 KiB Raw Blame History Unescape Escape