mirror of
https://gitee.com/zoujingli/ThinkAdmin.git
synced 2026-06-06 20:18:10 +08:00
6f4056f64d
补充 v8 重构后的架构文档、组件说明和迁移记录，方便后续维护者理解插件边界。 主要内容： - 更新根 README，说明 v8 插件分层、系统模块、交付命令和验证流程。 - 新增组件明细、插件边界、路由分发、软删除和稳定性文档。 - 记录 Storage 合并到 System、旧 View 移除和 Helper 并入 System 的决策。 - 补充文档注释报告和后续重构计划，便于持续演进。
150 lines
3.3 KiB
Markdown
150 lines
3.3 KiB
Markdown
# 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`
|
||
|
||
统一请求头：
|
||
|
||
```http
|
||
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`
|
||
|
||
### 推荐用法
|
||
|
||
```php
|
||
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`：短期能力授权
|
||
|
||
不要按每个终端来源都拆一套新的认证协议。
|