82581d2949
Add TMDB search and media detail pages, HDHive resource ingestion flow, unified error handling, Docker single-container runtime, and project docs/config updates for local deployment. Co-authored-by: Cursor <cursoragent@cursor.com>
113 lines
4.5 KiB
Markdown
113 lines
4.5 KiB
Markdown
# 认证与授权
|
||
|
||
## API Key 认证
|
||
|
||
所有 OpenAPI 请求都必须携带 `X-API-Key`。
|
||
|
||
```http
|
||
X-API-Key: your-api-key
|
||
```
|
||
|
||
### 请求示例
|
||
|
||
```bash
|
||
curl -H "X-API-Key: your-api-key" https://hdhive.com/api/open/ping
|
||
```
|
||
|
||
## 用户身份来源
|
||
|
||
业务接口需要能确定调用用户。系统按以下顺序识别用户：
|
||
|
||
1. `Authorization: Bearer <OpenAPI 用户 Access Token>`：第三方应用授权后获得，必须属于当前应用。
|
||
2. `Authorization: Bearer <站内用户 JWT>`：站内登录态 Token。
|
||
3. API Key 绑定用户：个人 API Key 或管理员绑定用户的 OpenAPI 应用可回退到绑定用户。
|
||
|
||
非 `meta` 类接口如果无法确定用户，会返回 `OPENAPI_USER_REQUIRED`。
|
||
|
||
## 第三方应用授权流程
|
||
|
||
第三方应用应使用管理员创建的 OpenAPI 应用完成授权：
|
||
|
||
1. 管理员创建 OpenAPI 应用，配置应用名称、绑定用户、scope、IP 策略、回调地址等。
|
||
2. 第三方应用引导用户进入前端授权页 `/openapi/authorize`，并传入 `client_id`、`redirect_uri`、`scope`、`state`。
|
||
3. 用户确认授权后，HDHive 前端调用 `POST /api/public/openapi/oauth/authorize`，后端以 JSON 返回一次性授权码。
|
||
4. HDHive 前端把用户重定向到第三方 `redirect_uri`，并在 query 中追加 `code` 和原始 `state`。
|
||
5. 第三方应用服务端用授权码调用 `POST /api/public/openapi/oauth/token` 换取用户 Access Token 和 Refresh Token。
|
||
6. 调用业务接口时同时传入应用 Secret 和用户 Access Token。
|
||
|
||
```http
|
||
X-API-Key: app-secret
|
||
Authorization: Bearer user-access-token
|
||
```
|
||
|
||
### 用户授权页
|
||
|
||
第三方应用应把用户跳转到站点前端授权页，而不是直接展示后端 API：
|
||
|
||
```text
|
||
https://hdhive.com/openapi/authorize?client_id=app_xxx&redirect_uri=https%3A%2F%2Fclient.example.com%2Fcallback&scope=query%20unlock&state=opaque-state
|
||
```
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|---|---|---|
|
||
| `client_id` | 是 | OpenAPI 应用公开 Client ID，不是 Secret |
|
||
| `redirect_uri` | 是 | 回调地址，必须在应用配置的回调地址列表内 |
|
||
| `scope` | 否 | 请求的用户授权 scope，空格分隔；为空时按应用允许范围处理 |
|
||
| `state` | 否 | 第三方应用自定义状态，建议用于 CSRF 防护和回跳上下文 |
|
||
|
||
### 授权码换 Token
|
||
|
||
后端换取 Token 时必须使用应用 Secret：
|
||
|
||
```bash
|
||
curl -X POST https://hdhive.com/api/public/openapi/oauth/token \\
|
||
-H "X-API-Key: app-secret" \\
|
||
-H "Content-Type: application/json" \\
|
||
-d '{
|
||
"grant_type": "authorization_code",
|
||
"code": "authorization-code",
|
||
"redirect_uri": "https://client.example.com/callback"
|
||
}'
|
||
```
|
||
|
||
返回的 `access_token` 用于业务 OpenAPI 调用，`refresh_token` 用于刷新用户授权 Token。
|
||
|
||
`redirect_uri` 在换取 Token 时不会触发跳转，它是授权码安全校验字段，必须与创建授权码时传入的 `redirect_uri` 完全一致。后端会用它确认授权码确实来自同一次授权请求，避免授权码被截获后在其他回调上下文中兑换。
|
||
|
||
### 授权码回调形式
|
||
|
||
用户确认授权后，第三方应用收到的是浏览器跳转请求：
|
||
|
||
```text
|
||
https://client.example.com/callback?code=authorization-code&state=opaque-state
|
||
```
|
||
|
||
`code` 是一次性授权码，第三方应用应该在自己的服务端用应用 Secret 换取 Token，不要在浏览器里暴露应用 Secret。
|
||
|
||
## Scope
|
||
|
||
| scope | 说明 | 典型能力 |
|
||
|---|---|---|
|
||
| `meta` | 元信息接口 | 健康检查、配额、用量查询 |
|
||
| `query` | 查询接口 | 资源查询、分享详情、资源链接检查 |
|
||
| `write` | 写入接口 | 创建、更新、删除分享 |
|
||
| `unlock` | 解锁接口 | 解锁资源并获取链接 |
|
||
| `vip` | VIP 接口 | 用户信息、签到、VIP 用量 |
|
||
|
||
应用必须拥有对应 scope，用户授权 Token 如果限制了 scope，也必须包含对应 scope。
|
||
|
||
## 认证错误码
|
||
|
||
| 错误码 | HTTP 状态码 | 说明 |
|
||
|---|---|---|
|
||
| `MISSING_API_KEY` | 401 | 未提供 `X-API-Key` |
|
||
| `INVALID_API_KEY` | 401 | API Key 无效或不存在 |
|
||
| `DISABLED_API_KEY` | 401 | API Key 已被禁用 |
|
||
| `EXPIRED_API_KEY` | 401 | API Key 已过期 |
|
||
| `INVALID_OPENAPI_USER_TOKEN` | 401 | OpenAPI 用户 Token 无效 |
|
||
| `OPENAPI_TOKEN_APP_MISMATCH` | 401 | 用户 Token 不属于当前应用 |
|
||
| `OPENAPI_USER_REQUIRED` | 403 | 业务接口缺少用户身份 |
|
||
| `SCOPE_NOT_ALLOWED` | 403 | 应用未授权该接口组 |
|
||
| `USER_SCOPE_NOT_ALLOWED` | 403 | 用户授权 Token scope 不足 |
|
||
| `VIP_REQUIRED` | 403 | 当前用户不满足 Premium 要求 |
|