#JWT Token 生成

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

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

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

#前置条件

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

#第一步：申请管理员 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 和 username 二选一，不能同时提供或同时不提供。

{
  "userId": 2
}

或使用 username：

{
  "username": "alice"
}

#cURL 示例

使用 userId：

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

使用 username：

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

#返回示例

{
  "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 或 username 对应的用户不存在。

#3. 返回 400 - 参数错误

可能的原因：

• 同时提供了 userId 和 username
• 两个参数都没有提供
• userId 不是正整数
• username 为空字符串或非字符串类型

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

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

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

#安全建议

1. 妥善保管管理员 API 密钥，不要提交到代码仓库或暴露到前端。
2. 管理员 API 密钥只用于服务端调用，不要直接发给终端用户。
3. 生产环境务必使用 HTTPS。
4. 建议定期轮换 API 密钥，并清理不再使用的旧密钥。
5. 管理员账号下，进入“系统配置 - 安全性 - Token策略”，配置 Token 过期时间等安全参数（如下图所示）。建议缩短 Token 过期时间，例如 1 小时。