544 lines
16 KiB
Markdown
544 lines
16 KiB
Markdown
# 萌芽账户认证中心 API 文档
|
||
|
||
访问 **`GET /`** 或 **`GET /api`**（无鉴权）可得到 JSON 格式的简要说明（服务名、版本、`/api/docs` 与 `/api/health` 入口、路由前缀摘要）。
|
||
|
||
接入地址：
|
||
- 统一登录前端：`https://auth.shumengya.top`
|
||
- 后端 API：`https://auth.api.shumengya.top`
|
||
- 本地开发 API：`http://<host>:8080`
|
||
|
||
对外接入建议：
|
||
1. 第三方应用按钮跳转到统一登录前端。
|
||
2. 登录成功后回跳到业务站点。
|
||
3. 业务站点使用回跳带回的 `token` 调用后端 API。
|
||
|
||
示例按钮：
|
||
```html
|
||
<a href="https://auth.shumengya.top/?redirect_uri=https%3A%2F%2Fapp.example.com%2Fauth%2Fcallback&state=abc123">
|
||
使用萌芽统一账户认证登录
|
||
</a>
|
||
```
|
||
|
||
回跳说明：
|
||
- 用户已登录时，统一登录前端会提示“继续授权”或“切换账号”。
|
||
- 登录成功后会回跳到 `redirect_uri`（或 `return_url`），并在 URL **`#fragment`**（哈希）中带上令牌与用户信息（见下表）。
|
||
- 第三方应用拿到 `token` 后，建议调用 **`POST /api/auth/verify`**（无副作用、适合网关鉴权）或 **`GET /api/auth/me`**（会更新访问记录，适合业务拉全量资料）校验并解析用户身份。
|
||
|
||
### 统一登录前端：查询参数
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `redirect_uri` | 与 `return_url` 至少其一 | 登录成功后的回跳地址，须进行 URL 编码；可为绝对 URL 或相对路径（相对路径相对统一登录站点解析）。 |
|
||
| `return_url` | 同上 | 与 `redirect_uri` 同义，二者都传时优先 `redirect_uri`。 |
|
||
| `state` | 否 | OAuth 风格透传字符串；回跳时原样写入哈希参数，供业务防 CSRF 或关联会话。 |
|
||
| `prompt` | 否 | 预留；前端可读，当前可用于将来扩展交互策略。 |
|
||
| `client_id` | 否 | 第三方应用稳定标识（字母数字开头，可含 `_.:-`，最长 64）。写入用户「应用接入记录」，并随登录请求提交给后端。 |
|
||
| `client_name` | 否 | 展示用名称（最长 128），与 `client_id` 配对；可选。 |
|
||
|
||
### 回跳 URL：`#` 哈希参数
|
||
|
||
成功授权后，前端将使用 [`URLSearchParams`](https://developer.mozilla.org/zh-CN/docs/Web/API/URLSearchParams) 写入哈希，例如：`https://app.example.com/auth/callback#token=...&expiresAt=...&account=...&username=...&state=...`。
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `token` | JWT，调用受保护接口时放在请求头 `Authorization: Bearer <token>`。 |
|
||
| `expiresAt` | 过期时间，RFC3339（与签发侧一致，当前默认为登录时起算 **7 天**）。 |
|
||
| `account` | 账户名（与 JWT `sub` 一致）。 |
|
||
| `username` | 展示用昵称，可能为空。 |
|
||
| `state` | 若登录请求携带了 `state`，则原样返回。 |
|
||
|
||
业务站点回调页应用脚本读取 `location.hash`，解析后**仅在 HTTPS 环境**将 `token` 存于内存或安全存储，并尽快用后端 **`POST /api/auth/verify`** 校验（勿仅信任哈希中的明文字段）。
|
||
|
||
### 第三方后端接入建议
|
||
|
||
1. **仅信服务端**：回调页将 `token` 交给自有后端，由后端请求 `POST https://<api-host>/api/auth/verify`（JSON body：`{"token":"..."}`），根据 `valid` 与 `user.account` 建立会话。
|
||
2. **CORS**：浏览器直连 API 时须后端已配置 CORS（本服务默认允许任意 `Origin`）；若从服务端发起请求则不受 CORS 限制。
|
||
3. **令牌过期**：`verify` / `me` 返回 401 或 `verify` 中 `valid:false` 时，应引导用户重新走统一登录。
|
||
|
||
## 认证与统一登录
|
||
|
||
### 登录获取统一令牌
|
||
`POST /api/auth/login`
|
||
|
||
请求：
|
||
```json
|
||
{
|
||
"account": "demo",
|
||
"password": "demo123",
|
||
"clientId": "my-app",
|
||
"clientName": "我的应用"
|
||
}
|
||
```
|
||
|
||
`clientId` / `clientName` 可选；规则与请求头 `X-Auth-Client` / `X-Auth-Client-Name` 一致。传入且格式合法时，会在登录成功后写入该用户的 **应用接入记录**（见下文 `authClients`）。
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"token": "jwt-token",
|
||
"expiresAt": "2026-03-14T12:00:00Z",
|
||
"user": {
|
||
"account": "demo",
|
||
"username": "示例用户",
|
||
"email": "demo@example.com",
|
||
"level": 0,
|
||
"sproutCoins": 10,
|
||
"secondaryEmails": ["demo2@example.com"],
|
||
"phone": "13800000000",
|
||
"avatarUrl": "https://example.com/avatar.png",
|
||
"websiteUrl": "https://example.com",
|
||
"bio": "### 简介",
|
||
"createdAt": "2026-03-14T12:00:00Z",
|
||
"updatedAt": "2026-03-14T12:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
若账户已被管理员封禁，返回 **403**，且**不会签发 JWT**，响应示例：
|
||
|
||
```json
|
||
{
|
||
"error": "account is banned",
|
||
"banReason": "违规内容"
|
||
}
|
||
```
|
||
|
||
`banReason` 可能为空字符串或省略。
|
||
|
||
**常见 HTTP 状态码（登录）**
|
||
|
||
| 状态码 | 含义 |
|
||
|--------|------|
|
||
| 200 | 成功，返回 `token`、`expiresAt`、`user`。 |
|
||
| 400 | 请求体非法或缺少 `account` / `password`。 |
|
||
| 401 | 账户不存在或密码错误（统一文案 `invalid credentials`）。 |
|
||
| 403 | 账户已封禁（见上文 JSON）。 |
|
||
| 500 | 服务器内部错误（读库、签发 JWT 失败等）。 |
|
||
|
||
**JWT 概要**：算法 **HS256**；载荷含 `account`（与 `sub` 一致）、`iss`（见 `data/config/auth.json`）、`iat` / `exp`。客户端只需透传字符串，**勿在前端解析密钥**。
|
||
|
||
### 校验令牌
|
||
`POST /api/auth/verify`
|
||
|
||
请求：
|
||
```json
|
||
{
|
||
"token": "jwt-token"
|
||
}
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"valid": true,
|
||
"user": { "account": "demo", "...": "..." }
|
||
}
|
||
```
|
||
|
||
若账户已封禁，返回 **200** 且 `valid` 为 **false**（不返回 `user` 对象），示例：
|
||
|
||
```json
|
||
{
|
||
"valid": false,
|
||
"error": "account is banned",
|
||
"banReason": "违规内容"
|
||
}
|
||
```
|
||
|
||
令牌过期、签名错误、issuer 不匹配等解析失败时返回 **401**，示例：`{"valid": false, "error": "invalid token"}`。
|
||
|
||
`verify` 与 `me` 的取舍：**仅校验身份、不改变用户数据**时用 `verify`；需要最新资料、签到状态或写入「最后访问」时用 `GET /api/auth/me`（需 Bearer）。
|
||
|
||
**应用接入记录（可选）**：第三方在 **`POST /api/auth/verify`** 或 **`GET /api/auth/me`** 上携带请求头：
|
||
|
||
- `X-Auth-Client`：应用 ID（格式同登录 JSON 的 `clientId`）
|
||
- `X-Auth-Client-Name`：可选展示名
|
||
|
||
校验成功且用户未封禁时，服务端会更新该用户 JSON 中的 `authClients` 数组（`clientId`、`displayName`、`firstSeenAt`、`lastSeenAt`）。**`POST /api/auth/verify` 的响应体 `user` 仍为 `Public()`，不含 `authClients`**，避免向调用方泄露用户在其他应用的接入情况；**`GET /api/auth/me`** 与管理员列表中的 `user`（`OwnerPublic`）**包含** `authClients`，用户可在统一登录前端的个人中心查看。
|
||
|
||
### 获取当前用户信息
|
||
`GET /api/auth/me`
|
||
|
||
请求头：
|
||
`Authorization: Bearer <jwt-token>`
|
||
|
||
可选（由前端调用 `https://cf-ip-geo.smyhub.com/api` 等接口解析后传入，用于记录「最后访问 IP」与「最后显示位置」）：
|
||
- `X-Visit-Ip`：客户端公网 IP（与地理接口返回的 `ip` 一致即可）
|
||
- `X-Visit-Location`：展示用位置文案（例如将 `geo.countryName`、`regionName`、`cityName` 拼接为 `中国 四川 成都`）
|
||
|
||
**服务端回退（避免浏览器跨域导致头缺失）**：若未传 `X-Visit-Location`，后端会用 `X-Visit-Ip`；若也未传 `X-Visit-Ip`，则用连接的 `ClientIP()`（请在前置反向代理上正确传递 `X-Forwarded-For` 等，并在生产环境为 Gin 配置可信代理）。随后服务端请求 `GEO_LOOKUP_URL`（默认 `https://cf-ip-geo.smyhub.com/api?ip=<ip>`）解析展示位置并写入用户记录。
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"user": { "account": "demo", "...": "..." },
|
||
"checkIn": {
|
||
"rewardCoins": 1,
|
||
"checkedInToday": false,
|
||
"lastCheckInDate": "",
|
||
"lastCheckInAt": "",
|
||
"today": "2026-03-14"
|
||
}
|
||
}
|
||
```
|
||
|
||
> `user` 还会包含 `lastVisitAt`、`lastVisitDate`、`checkInDays`、`checkInStreak`、`visitDays`、`visitStreak` 等统计字段。
|
||
|
||
> 在登录用户本人、管理员列表等场景下，`user` 还可包含 `lastVisitIp`、`lastVisitDisplayLocation`（最近一次通过 `/api/auth/me` 上报的访问 IP 与位置文案）。**公开用户资料接口** `GET /api/public/users/:account` 与 **`POST /api/auth/verify` 的 `user` 中不包含这两项**（避免公开展示或第三方校验时令牌响应携带访问隐私）。
|
||
|
||
> 说明：密码不会返回。
|
||
|
||
若账户在登录后被封禁，持旧 JWT 调用 `GET /api/auth/me`、`PUT /api/auth/profile`、`POST /api/auth/check-in`、辅助邮箱等需登录接口时，返回 **403**，正文同登录封禁响应（`error` + 可选 `banReason`）。客户端应作废本地令牌。
|
||
|
||
### 每日签到
|
||
`POST /api/auth/check-in`
|
||
|
||
请求头：
|
||
`Authorization: Bearer <jwt-token>`
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"checkedIn": true,
|
||
"alreadyCheckedIn": false,
|
||
"rewardCoins": 1,
|
||
"awardedCoins": 1,
|
||
"message": "签到成功",
|
||
"user": { "account": "demo", "...": "..." }
|
||
}
|
||
```
|
||
|
||
### 更新当前用户资料
|
||
`PUT /api/auth/profile`
|
||
|
||
请求头：
|
||
`Authorization: Bearer <jwt-token>`
|
||
|
||
请求（字段可选）：
|
||
```json
|
||
{
|
||
"password": "newpass",
|
||
"username": "新昵称",
|
||
"phone": "13800000000",
|
||
"avatarUrl": "https://example.com/avatar.png",
|
||
"websiteUrl": "https://example.com",
|
||
"bio": "### 新简介"
|
||
}
|
||
```
|
||
|
||
说明：`websiteUrl` 须为 `http`/`https` 地址；可传空字符串清除；未写协议时服务端会补全为 `https://`。
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"user": { "account": "demo", "...": "..." }
|
||
}
|
||
```
|
||
|
||
## 用户广场
|
||
|
||
### 获取用户公开主页
|
||
`GET /api/public/users/{account}`
|
||
|
||
说明：
|
||
- 仅支持账户名 `account`，不支持昵称查询。
|
||
- 适合第三方应用展示用户公开资料。
|
||
- 若该账户已被封禁，返回 **404** `{"error":"user not found"}`（与不存在账户相同，避免公开资料泄露）。
|
||
- 响应中含该用户**最近一次被服务端记录的**访问 IP（`lastVisitIp`）与展示用地理位置（`lastVisitDisplayLocation`，与本人中心一致）；`POST /api/auth/verify` 返回的用户 JSON **不含**上述两项。
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"user": {
|
||
"account": "demo",
|
||
"username": "示例用户",
|
||
"level": 3,
|
||
"sproutCoins": 10,
|
||
"avatarUrl": "https://example.com/avatar.png",
|
||
"websiteUrl": "https://example.com",
|
||
"lastVisitIp": "203.0.113.1",
|
||
"lastVisitDisplayLocation": "中国 广东省 深圳市",
|
||
"bio": "### 简介"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 公开注册策略
|
||
`GET /api/public/registration-policy`
|
||
|
||
无需鉴权。用于前端判断是否展示「邀请码」输入框。
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"requireInviteCode": false
|
||
}
|
||
```
|
||
|
||
当 `requireInviteCode` 为 **true** 时，`POST /api/auth/register` 必须携带有效 `inviteCode`（见下节）。
|
||
|
||
### 注册账号（发送邮箱验证码）
|
||
`POST /api/auth/register`
|
||
|
||
请求：
|
||
```json
|
||
{
|
||
"account": "demo",
|
||
"password": "demo123",
|
||
"username": "示例用户",
|
||
"email": "demo@example.com",
|
||
"inviteCode": "ABCD1234"
|
||
}
|
||
```
|
||
|
||
- `inviteCode`：可选。若服务端开启「强制邀请码」，则必填且须为管理员发放的未过期、未用尽邀请码。邀请码**不区分大小写**；成功完成 `verify-email` 创建用户后才会扣减使用次数。
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"sent": true,
|
||
"expiresAt": "2026-03-14T12:10:00Z"
|
||
}
|
||
```
|
||
|
||
### 验证邮箱并完成注册
|
||
`POST /api/auth/verify-email`
|
||
|
||
请求：
|
||
```json
|
||
{
|
||
"account": "demo",
|
||
"code": "123456"
|
||
}
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"created": true,
|
||
"user": { "account": "demo", "...": "..." }
|
||
}
|
||
```
|
||
|
||
### 忘记密码（发送重置验证码）
|
||
`POST /api/auth/forgot-password`
|
||
|
||
请求：
|
||
```json
|
||
{
|
||
"account": "demo",
|
||
"email": "demo@example.com"
|
||
}
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"sent": true,
|
||
"expiresAt": "2026-03-14T12:10:00Z"
|
||
}
|
||
```
|
||
|
||
### 重置密码
|
||
`POST /api/auth/reset-password`
|
||
|
||
请求：
|
||
```json
|
||
{
|
||
"account": "demo",
|
||
"code": "123456",
|
||
"newPassword": "newpass"
|
||
}
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{ "reset": true }
|
||
```
|
||
|
||
### 申请添加辅助邮箱（发送验证码）
|
||
`POST /api/auth/secondary-email/request`
|
||
|
||
请求头：
|
||
`Authorization: Bearer <jwt-token>`
|
||
|
||
请求：
|
||
```json
|
||
{
|
||
"email": "demo2@example.com"
|
||
}
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"sent": true,
|
||
"expiresAt": "2026-03-14T12:10:00Z"
|
||
}
|
||
```
|
||
|
||
### 验证辅助邮箱
|
||
`POST /api/auth/secondary-email/verify`
|
||
|
||
请求头：
|
||
`Authorization: Bearer <jwt-token>`
|
||
|
||
请求：
|
||
```json
|
||
{
|
||
"email": "demo2@example.com",
|
||
"code": "123456"
|
||
}
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"verified": true,
|
||
"user": { "account": "demo", "...": "..." }
|
||
}
|
||
```
|
||
|
||
## 管理端接口（需要管理员 Token）
|
||
|
||
管理员 Token 存放在 `data/config/admin.json` 中；如果文件不存在，后端启动时会自动生成并写入该文件。
|
||
请求时可使用以下任一方式携带：
|
||
- Query：`?token=<admin-token>`
|
||
- Header：`X-Admin-Token: <admin-token>`
|
||
|
||
### 签到奖励设置
|
||
`GET /api/admin/check-in/config`
|
||
|
||
`PUT /api/admin/check-in/config`
|
||
|
||
请求：
|
||
```json
|
||
{
|
||
"rewardCoins": 1
|
||
}
|
||
```
|
||
- Header：`Authorization: Bearer <admin-token>`
|
||
|
||
### 注册策略与邀请码
|
||
|
||
`GET /api/admin/registration`
|
||
|
||
响应含 `requireInviteCode` 与 `invites` 数组（每项含 `code`、`note`、`maxUses`、`uses`、`expiresAt`、`createdAt`）。`maxUses` 为 0 表示不限次数。
|
||
|
||
`PUT /api/admin/registration`
|
||
|
||
请求：
|
||
```json
|
||
{ "requireInviteCode": true }
|
||
```
|
||
|
||
`POST /api/admin/registration/invites`
|
||
|
||
请求：
|
||
```json
|
||
{
|
||
"note": "内测批次",
|
||
"maxUses": 10,
|
||
"expiresAt": "2026-12-31T15:59:59Z"
|
||
}
|
||
```
|
||
|
||
`expiresAt` 可省略；须为 RFC3339。响应 `201`，`invite` 内含服务端生成的 8 位邀请码。
|
||
|
||
`DELETE /api/admin/registration/invites/{code}`
|
||
|
||
删除指定邀请码（`code` 与存储大小写可能不同，按不区分大小写匹配）。
|
||
|
||
### 获取用户列表
|
||
`GET /api/admin/users`
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"total": 1,
|
||
"users": [{ "account": "demo", "...": "..." }]
|
||
}
|
||
```
|
||
|
||
### 新建用户
|
||
`POST /api/admin/users`
|
||
|
||
请求：
|
||
```json
|
||
{
|
||
"account": "demo",
|
||
"password": "demo123",
|
||
"username": "示例用户",
|
||
"email": "demo@example.com",
|
||
"level": 0,
|
||
"sproutCoins": 10,
|
||
"secondaryEmails": ["demo2@example.com"],
|
||
"phone": "13800000000",
|
||
"avatarUrl": "https://example.com/avatar.png",
|
||
"websiteUrl": "https://example.com",
|
||
"bio": "### 简介"
|
||
}
|
||
```
|
||
|
||
### 更新用户
|
||
`PUT /api/admin/users/{account}`
|
||
|
||
请求（字段可选）：
|
||
```json
|
||
{
|
||
"password": "newpass",
|
||
"username": "新昵称",
|
||
"level": 1,
|
||
"secondaryEmails": ["demo2@example.com"],
|
||
"sproutCoins": 99,
|
||
"websiteUrl": "https://example.com",
|
||
"banned": true,
|
||
"banReason": "违规说明（最多 500 字）"
|
||
}
|
||
```
|
||
|
||
- `banned`：是否封禁；解封时请传 `false`，并可将 `banReason` 置为空字符串。
|
||
- `banReason`：仅当用户处于封禁状态时允许设为非空；封禁时若首次写入会记录 `bannedAt`（RFC3339，存于用户 JSON）。
|
||
|
||
管理员列表 `GET /api/admin/users` 中每条 `user` 可含 `banned`、`banReason`（不含 `bannedAt` 亦可从存储文件中查看）。
|
||
|
||
### 删除用户
|
||
`DELETE /api/admin/users/{account}`
|
||
|
||
响应：
|
||
```json
|
||
{ "deleted": true }
|
||
```
|
||
|
||
## 数据存储说明
|
||
|
||
- 用户数据：`data/users/*.json`
|
||
- 注册待验证：`data/pending/*.json`
|
||
- 密码重置记录：`data/reset/*.json`
|
||
- 辅助邮箱验证：`data/secondary/*.json`
|
||
- 管理员 Token：`data/config/admin.json`
|
||
- JWT 配置：`data/config/auth.json`
|
||
- 邮件配置：`data/config/email.json`
|
||
- 注册策略与邀请码：`data/config/registration.json`
|
||
|
||
## 快速联调用示例
|
||
|
||
```bash
|
||
# 服务根路径 JSON 说明
|
||
curl -s http://localhost:8080/ | jq .
|
||
|
||
# 登录
|
||
curl -X POST http://localhost:8080/api/auth/login \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"account":"demo","password":"demo123"}'
|
||
|
||
# 校验令牌（推荐第三方网关先调此接口）
|
||
curl -X POST http://localhost:8080/api/auth/verify \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"token":"<jwt-token>"}'
|
||
|
||
# 使用令牌获取用户信息（会更新访问记录）
|
||
curl http://localhost:8080/api/auth/me \
|
||
-H 'Authorization: Bearer <jwt-token>'
|
||
```
|