#JWT Token 生成

本系统 API 使用 Bearer Token 进行身份认证。

如果你需要获取某个用户的 JWT Token，推荐做法是：

1. 先使用管理员账号申请一个 admin 权限的 API 密钥
2. 再调用 yiaskAuth:issueUserToken 接口，为目标用户签发可直接使用的 JWT Token

#前置条件

• 当前账号必须有 admin 权限
• 已知目标用户的 userId

#第一步：申请管理员 API 密钥

使用管理员账号登录系统后，进入：

右上角设置按钮 -> API密钥

创建一个新的 API 密钥，并确保它使用的是 admin 权限。

创建完成后，你会得到一个 Bearer Token。后续调用 yiaskAuth:issueUserToken 时，Authorization 头里填的就是这个管理员 API 密钥。

#第二步：调用 yiaskAuth:issueUserToken

接口地址：

POST /api/yiaskAuth:issueUserToken

请求头：

Authorization: Bearer <ADMIN_API_KEY>
Content-Type: application/json

请求体：

{
  "userId": 2
}

#cURL 示例

curl 'http://localhost:13000/api/yiaskAuth:issueUserToken' \
  -X POST \
  -H 'Authorization: Bearer <ADMIN_API_KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "userId": 2
  }'

#返回示例

{
  "token": "<USER_JWT_TOKEN>",
  "jti": "8ef7dc1d-4ddb-4c55-b6f5-0dd6dc28b6b4",
  "expiresAt": "2026-03-27T08:00:00.000Z",
  "user": {
    "id": 2,
    "username": "alice",
    "email": "alice@example.com",
    "nickname": "Alice"
  }
}

#返回字段说明

#第三步：使用返回的用户 Token

在后续 API 请求中，将上一步返回的 token 放入 Authorization 请求头：

Authorization: Bearer <USER_JWT_TOKEN>

示例：

curl 'http://localhost:13000/api/auth:check' \
  -H 'Authorization: Bearer <USER_JWT_TOKEN>' \
  -H 'X-SPACES: default'

#常见错误

#1. 返回 403

说明当前调用者不是 root 或 admin，或者你申请的 API 密钥不是 admin 权限。

#2. 返回 404

说明传入的 userId 不存在。

#3. 注销时报时间格式错误

不要自己手工拼 JWT Payload，也不要自己用 APP_KEY 加密。

如果手工生成的 Token 缺少 jti、exp 等字段，后续调用 auth:signOut 时可能出现时间字段错误。请统一使用 yiaskAuth:issueUserToken 接口签发。

#安全建议

1. 妥善保管管理员 API 密钥，不要提交到代码仓库或暴露到前端。
2. 管理员 API 密钥只用于服务端调用，不要直接发给终端用户。
3. 生产环境务必使用 HTTPS。
4. 建议定期轮换 API 密钥，并清理不再使用的旧密钥。