主题
PERSONAL_ACCESS_TOKENS 个人访问令牌表
Personal Access Token（PAT）是用户手动创建的长期访问凭证，用于脚本、CLI、CI/CD 等无法交互式登录的场景。用户拿到 PAT 后，将其作为 Bearer token 携带在请求中，或者URL参数 access_token传递，即可代替用户名密码完成鉴权。
位置
模型路径：/sysdata/data/tables/sec/PERSONAL_ACCESS_TOKENS.tbl
物理表名：SZSYS_5_PERSONAL_ACCESS_TOKENS
表结构
| 字段名 | 字段类型 | 字段描述 |
|---|---|---|
| ID | VARCHAR(128) | 主键，令牌原文单向加密后的值，不可反推。鉴权时对请求携带的令牌做同样的加密后以此值查表 |
| USER_ID | VARCHAR(128) | 所属用户 ID |
| USER_DIRECTORY | VARCHAR(64) | 用户目录，sys 系统用户、external 外部用户 |
| NAME | VARCHAR(256) | 用户给 token 取的备注名，如 "My CI Script" |
| DESC | VARCHAR(1024) | 用途描述，如 "用于 Jenkins 自动部署流水线" |
| ENABLED | NUMBER(1) | 是否启用。1 有效，0 已吊销。吊销时清除关联 session |
| EXPIRE_TIME | TIMESTAMP | 过期时间，由用户指定（按天/月或永不过期） |
| CREATE_TIME | TIMESTAMP | 创建时间 |
| TOKEN_MASK | VARCHAR(64) | 脱敏后的令牌明文，形如 succ-abcd****abdc：保留明文前 9 位和末 4 位，中间固定 4 个 *。只在签发时写入一次，供用户辨认列表里哪条对应手里的令牌 |
| LAST_ACCESS_TIME | TIMESTAMP | 最后一次以该令牌原文发起访问的时间，见使用注意里的记录规则 |
| LAST_ACCESS_IP | NUMBER(16) | 最后一次以该令牌原文发起访问的来源 IPv4 地址，整数格式存储；取不到地址时为 0 |
表索引
| 类型 | 名称 | 字段列表 | 是否唯一 | 说明 |
|---|---|---|---|---|
| 主键 | PRIMARY | ID | 是 | 令牌原文加密后的值作为主键，鉴权时直接主键 lookup |
快速理解
PAT 鉴权流程
用户携带 PAT 请求资源时，系统按以下流程鉴权：
| 步骤 | 阶段 | 动作 |
|---|---|---|
| 1 | 请求拦截 | 识别 Authorization: Bearer succ-xxx 前缀 |
| 2 | 凭证校验 | 对令牌原文做单向加密，以此查 PERSONAL_ACCESS_TOKENS 确认令牌有效且未过期 |
| 3 | 会话分配 | 以 PAT 主键作为 session ID 创建 Session |
| 4 | 用户登录 | 校验用户状态，创建 HTTP Session |
| 5 | 后续请求 | 同一 rawToken 再次请求时，直接通过 session ID（即 PAT ID）查找已有会话 |
数据示例
以下展示 PAT 的典型落表形态，ID / TOKEN_MASK 用可读占位表示。
| ID | USER_ID | USER_DIRECTORY | NAME | DESC | ENABLED | EXPIRE_TIME | CREATE_TIME | TOKEN_MASK | LAST_ACCESS_TIME | LAST_ACCESS_IP |
|---|---|---|---|---|---|---|---|---|---|---|
succ-9f3c2a7e... | admin | sys | My CI Token | 用于 Jenkins 自动部署流水线 | 1 | 2026-09-17 10:00:00 | 2026-06-17 10:00:00 | succ-9f3c****b7d1 | 2026-09-28 17:20:00 | 192168007033 |
succ-21c9f7b... | zhangsan | sys | 数据导出脚本 | 每日凌晨导出报表数据 | 0 | 2027-01-01 00:00:00 | 2026-01-01 00:00:00 | succ-4d81****0ea9 | 2026-03-02 08:15:00 | 192168007033 |
succ-4bd0a83... | lisi | external | 旧脚本 | （空） | 1 | （空，永不过期） | 2025-11-01 09:00:00 | （空） | （空） | （空） |
- 第 1 行：
admin创建的 PAT，有效期 3 个月，最近一次带令牌访问来自内网192.168.7.33。 - 第 2 行：
zhangsan的 PAT 已被吊销（ENABLED = 0），即使未到过期时间也无法使用。 - 第 3 行：未保存脱敏令牌且尚无访问记录的旧令牌，
TOKEN_MASK/LAST_ACCESS_*为空。 LAST_ACCESS_IP以整数格式存储，上面的192168007033即192.168.7.33。
使用注意
ID是令牌原文单向加密后的值，不可反推。令牌原文仅在创建时返回一次，之后无法找回。ENABLED = 0后鉴权立即失效，关联 session 被清除。- session ID 为 PAT 主键，PAT 表自身承载 session 标识。
- 令牌原文以
succ-为前缀，鉴权时靠前缀区分个人令牌和普通 access_token。 TOKEN_MASK保留明文的前 9 位（含succ-前缀）和后 4 位，中间固定 4 个*，共 17 个字符。它只在签发时写入一次，之后不随任何操作更新，仅供人工辨认，不能用于鉴权。- 旧令牌可能没有
TOKEN_MASK，界面显示「—」。由于系统不保存令牌原文，无法补生成脱敏值。 LAST_ACCESS_*通常在访问后约 20 秒更新，不是实时数据；短时间内多次访问只保留最近一次记录。LAST_ACCESS_*只覆盖以令牌原文发起的请求（Authorization: Bearer succ-xxx或 URL 参数access_token）。令牌首次登录后改用JSESSIONIDcookie 续期的请求、以及命中登录跳过规则的 URI 都不记录，所以它可能明显早于用户印象里的「最近活动时间」。- 地址取不到或不是 IPv4（例如 IPv6 客户端）时
LAST_ACCESS_IP记 0，界面显示「—」。
