Files

renjue 82581d2949 Implement full media crawler workflow with Flask backend and Vue frontend.

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>

2026-05-09 16:16:18 +08:00

4.5 KiB

Raw Blame History

认证与授权

API Key 认证

所有 OpenAPI 请求都必须携带 X-API-Key。

X-API-Key: your-api-key

请求示例

curl -H "X-API-Key: your-api-key" https://hdhive.com/api/open/ping

用户身份来源

业务接口需要能确定调用用户。系统按以下顺序识别用户：

Authorization: Bearer <OpenAPI 用户 Access Token>：第三方应用授权后获得，必须属于当前应用。
Authorization: Bearer <站内用户 JWT>：站内登录态 Token。
API Key 绑定用户：个人 API Key 或管理员绑定用户的 OpenAPI 应用可回退到绑定用户。

非 meta 类接口如果无法确定用户，会返回 OPENAPI_USER_REQUIRED。

第三方应用授权流程

第三方应用应使用管理员创建的 OpenAPI 应用完成授权：

管理员创建 OpenAPI 应用，配置应用名称、绑定用户、scope、IP 策略、回调地址等。
第三方应用引导用户进入前端授权页 /openapi/authorize，并传入 client_id、redirect_uri、scope、state。
用户确认授权后，HDHive 前端调用 POST /api/public/openapi/oauth/authorize，后端以 JSON 返回一次性授权码。
HDHive 前端把用户重定向到第三方 redirect_uri，并在 query 中追加 code 和原始 state。
第三方应用服务端用授权码调用 POST /api/public/openapi/oauth/token 换取用户 Access Token 和 Refresh Token。
调用业务接口时同时传入应用 Secret 和用户 Access Token。

X-API-Key: app-secret
Authorization: Bearer user-access-token

用户授权页

第三方应用应把用户跳转到站点前端授权页，而不是直接展示后端 API：

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：

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 完全一致。后端会用它确认授权码确实来自同一次授权请求，避免授权码被截获后在其他回调上下文中兑换。

授权码回调形式

用户确认授权后，第三方应用收到的是浏览器跳转请求：

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 要求

4.5 KiB Raw Blame History Unescape Escape