登录与 Token 协议

Forge Admin 使用 Sa-Token 实现认证，以下描述登录流程与 Token 使用规范。

登录接口

请求

POST /login
Content-Type: application/json

{
  "username": "admin",
  "password": "123456",
  "code": "a1b2",
  "uuid": " captcha-uuid"
}

参数	类型	必填	说明
username	string	是	用户名
password	string	是	密码（明文传输，建议生产环境启用 HTTPS）
code	string	否	验证码（启用验证码时必填）
uuid	string	否	验证码唯一标识

响应

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "token": "xxxx-xxxx-xxxx-xxxx"
  }
}

Token 使用

登录成功后，后续所有请求需在 Header 中携带 Token：

Authorization: Bearer xxxx-xxxx-xxxx-xxxx

或直接：

Authorization: xxxx-xxxx-xxxx-xxxx

具体格式取决于 sa-token.token-prefix 配置。默认不设前缀时直接传 Token 值。

Token 刷新

Sa-Token 默认采用续期机制：每次请求自动延长 Token 有效期。无需显式调用刷新接口。

配置项	说明
sa-token.timeout	Token 有效期，默认 30 天
sa-token.active-timeout	Token 临时有效期，超时未请求则失效

如需主动刷新 Token，可调用：

POST /refreshToken
Authorization: Bearer {old-token}

退出登录

POST /logout
Authorization: Bearer {token}

退出后 Token 立即失效，后续请求将返回 401 未登录错误。

Token 校验失败响应

场景	HTTP 状态码	业务码	错误信息
未携带 Token	401	401	未能读取到有效 token
Token 已过期	401	401	token 已过期
Token 已被踢下线	401	401	token 已被顶下线

💡 前端应在 Axios 拦截器中统一处理 401 响应，自动跳转登录页。