---
description: >-
  记录用户创建的 Personal Access Token (PAT) 元数据。session ID 直接使用 PAT
  主键（sha256(rawToken)），不再写入 ACCESS_TOKENS。
navTitle: PERSONAL_ACCESS_TOKENS
---
# **PERSONAL\_ACCESS\_TOKENS 个人访问令牌表**

Personal Access Token（PAT）是用户手动创建的长期访问凭证，用于脚本、CLI、CI/CD 等无法交互式登录的场景。用户拿到 PAT 后，将其作为 Bearer token 携带在请求中，或者URL参数 `access_token`传递，即可代替用户名密码完成鉴权。

## 位置{#position}

模型路径：`/sysdata/data/tables/sec/PERSONAL_ACCESS_TOKENS.tbl`

物理表名：`SZSYS_5_PERSONAL_ACCESS_TOKENS`

## 表结构{#structure}

| 字段名 | 字段类型 | 字段描述 |
| :----  | :---- | :------ |
| ID | VARCHAR(128) | 主键，`sha256(rawToken)`。鉴权时对请求中携带的原始 token 做 SHA-256 后以此值查表 |
| 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 | 创建时间 |

## 表索引{#indexes}

| 类型 | 名称 | 字段列表 | 是否唯一 | 说明 |
| :---- | :---- | :---- | :------ | :------ |
| 主键 | PRIMARY | ID | 是 | `sha256(rawToken)` 哈希值作为主键，鉴权时直接主键 lookup |

## 快速理解{#overview}

### PAT 鉴权流程

用户携带 PAT 请求资源时，系统按以下流程鉴权：

| 步骤 | 阶段 | 动作 |
| :---: | :--- | :--- |
| 1 | 请求拦截 | 识别 `Authorization: Bearer succ-xxx` 前缀 |
| 2 | 凭证校验 | 对 rawToken 做 SHA-256，查 PERSONAL\_ACCESS\_TOKENS 确认 token 有效且未过期 |
| 3 | 会话分配 | 以 PAT 主键（sha256(rawToken)）作为 session ID 创建 Session |
| 4 | 用户登录 | 校验用户状态，创建 HTTP Session |
| 5 | 后续请求 | 同一 rawToken 再次请求时，直接通过 session ID（即 PAT ID）查找已有会话 |

## 数据示例{#row-examples}

以下展示 PAT 的典型落表形态。`ID` 由 sha256 计算，示例中用可读占位表示。

| ID | USER\_ID | NAME | DESC | ENABLED | EXPIRE\_TIME | CREATE\_TIME |
| :-- | :-- | :-- | :-- | :-- | :-- | :-- |
| `a1b2c3...` | `admin` | `My CI Token` | `用于 Jenkins 自动部署流水线` | `1` | `2026-09-17 10:00:00` | `2026-06-17 10:00:00` |
| `f7g8h9...` | `zhangsan` | `数据导出脚本` | `每日凌晨导出报表数据` | `0` | `2027-01-01 00:00:00` | `2026-01-01 00:00:00` |

- 第 1 行：`admin` 创建的 PAT，有效期 3 个月。
- 第 2 行：`zhangsan` 的 PAT 已被吊销（`ENABLED = 0`），即使未到过期时间也无法使用。

## 使用注意{#notice}

1. `ID` 是 `sha256(rawToken)` 哈希，不可反推。rawToken 仅在创建时返回一次，之后无法找回。
2. `ENABLED = 0` 后鉴权立即失效，关联 session 被清除。
3. session ID 为 PAT 主键（sha256(rawToken)），PAT 表自身承载 session 标识。
4. rawToken 以 `succ-` 为前缀，鉴权时通过前缀区分 PAT 和普通 access\_token，避免盲目 sha256 所有 token。