ThinkAdmin/docs/architecture/auth-token-session.md

Auth And Token Session

目标

当前项目的认证体系只保留“显式 Token + Token Session”这一套主线，不再使用标准 PHP Session 承载登录态。

统一原则：

• 登录态必须由显式 Token 表达
• 临时用户态必须绑定到 Token 对应的 sid
• 业务请求统一使用 Authorization
• 后台壳页首跳只允许一次性 access_key 引导，不长期在 URL 或 Cookie 中保留认证态
• 登录来源可以有多种，但认证协议尽量收敛

标准认证协议

1. 后台认证

• 类型：system-auth
• 载体：Authorization: Bearer <JWT>
• 首屏壳页：允许一次性 access_key
• 会话：JWT 内的 sid 绑定 CacheSession

适用场景：

• 后台运营人员
• 管理员
• 需要 RBAC 的内部接口

2. 业务账号认证

• 类型：account-auth
• 载体：Authorization: Bearer <JWT>
• 会话：JWT 内的 sid 绑定 CacheSession

适用场景：

• 会员
• 分销员
• 商户
• 店员
• 任何“业务用户”身份

注意：

• wap / web / wxapp / wechat / iosapp / android 是登录来源或终端通道
• 它们不是独立的认证协议

3. 设备认证

• 当前仅 wuma 保留独立设备 token
• 载体：Authorization: Bearer <token>
• 附加头：X-Device-Code、X-Device-Type
• 这不是 JWT，也不是通用账号协议

适用场景：

• PDA
• 扫码枪
• 仓库终端
• 封闭设备接口

4. 能力令牌

• 当前后台上传使用短期能力 token
• 它不是登录态，不参与通用用户会话

适用场景：

• 上传授权
• 短时能力下放

请求识别规则

统一入口为请求级令牌解析服务：

• 有 Authorization 时，只按请求头判定
• 后台壳页首次进入时，可通过一次性 access_key 引导写入本地 Token
• 不再依赖认证 Cookie 回退
• 不再混用 Api-Token、Api-Code、Api-Type

统一请求头：

Authorization: Bearer <token>
X-Device-Code: <device-code>
X-Device-Type: <device-type>

Token Session 规则

核心定义

• Token 表达“你是谁”
• Token Session 表达“这次登录上下文里的临时状态”
• Token Session 的主键是 sid

存储实现

• 服务：CacheSession
• 统一入口：tsession()
• 存储后端：系统 cache
• 支持：file、redis 等缓存驱动

配置键

• token_session_expire
• token_session_touch
• token_session_gc_interval
• token_session_store

使用约束

• 默认作用域必须来自当前 Token 的 sid
• 未完成 Token 鉴权时，不能直接依赖默认作用域
• 如需离线或系统级缓存，必须显式传入 scope

推荐用法

tsession()->write('draft', ['step' => 1]);
$draft = tsession()->read('draft', []);

tsession()->put(['from' => 'order']);
$all = tsession()->all();

tsession()->delete('draft');
tsession()->clear();
tsession()->destroy();

禁止项

• 不再使用 think\Session
• 不再使用 think\\facade\\Session
• 不再使用 SessionInit
• 不再使用 PHPSESSID
• 不再使用标准 Session 环境变量作为系统登录态配置

推荐分层

如果系统存在多类账号，建议按下面方式分层：

• system-auth：后台人员
• account-auth：所有业务用户
• device token：封闭设备
• capability token：短期能力授权

不要按每个终端来源都拆一套新的认证协议。