csp/docs/第三方REST接入指南.md

CSP Quest World 第三方 REST 接入指南

本文档用于第三方系统（脚本、自动化平台、企业内部系统）快速接入 CSP Quest World 的 REST API。

1. 基础信息

• 线上基础地址：https://csp.hao.work/admin139/api/v1
• 文档入口（Swagger）：https://csp.hao.work/api-docs
• OpenAPI JSON：https://csp.hao.work/admin139/api/openapi.json
• 数据格式：application/json

2. 鉴权方式

受保护接口支持两种方式，任选其一：

1. Bearer Token（推荐）

• 先调用 /auth/login 获取 token
• 请求头带上：Authorization: Bearer <token>

2. Basic 账号密码（适合第三方直连）

• 请求头带上：Authorization: Basic <base64(username:password)>
• 示例：alice:password123 -> YWxpY2U6cGFzc3dvcmQxMjM=

说明：

• 两种方式都可访问全部 REST 接口。
• 管理员接口仍需管理员账号（如 admin）才能通过权限校验。

3. 快速调用示例

3.1 登录获取 Token

curl -X POST 'https://csp.hao.work/admin139/api/v1/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{"username":"alice","password":"password123"}'

3.2 使用 Bearer 调用

curl 'https://csp.hao.work/admin139/api/v1/me' \
  -H 'Authorization: Bearer <token>'

3.3 使用 Basic 调用

curl 'https://csp.hao.work/admin139/api/v1/me' \
  -H 'Authorization: Basic YWxpY2U6cGFzc3dvcmQxMjM='

4. Python 示例（requests）

import base64
import requests

BASE = "https://csp.hao.work/admin139/api/v1"
username = "alice"
password = "password123"

basic = base64.b64encode(f"{username}:{password}".encode("utf-8")).decode("utf-8")
headers = {"Authorization": f"Basic {basic}"}

resp = requests.get(f"{BASE}/me", headers=headers, timeout=15)
resp.raise_for_status()
print(resp.json())

5. 响应约定

• 成功：{ "ok": true, "data": ... }（Auth 接口除外）
• 失败：{ "ok": false, "error": "..." }

常见状态码：

• 200：成功
• 400：请求参数错误
• 401：未登录或鉴权失败
• 403：有登录身份但权限不足（如非管理员访问管理员接口）
• 404：资源不存在
• 409：状态冲突（例如任务已在运行）

6. 安全建议

1. 生产环境优先用 HTTPS。
2. 若可控，优先使用 Bearer Token，减少明文密码在网关/代理日志出现的风险。
3. 使用 Basic 时建议为第三方集成准备专用账号，并定期更换密码。
4. 管理员账号只用于管理员接口，不建议用于普通业务拉取。

7. 爬虫自动化接口（管理员）

• 爬虫列表：GET /admin/crawlers?status=&limit=
• 新增目标：POST /admin/crawlers，Body：{ "url": "https://example.com" }
• 重新入队：POST /admin/crawlers/{id}/queue
• 运行记录：GET /admin/crawlers/{id}/runs?limit=20
• 守护状态：GET /backend/crawler-guard/status

说明：

• 新地址入库后，后端守护会自动执行：规则生成（LLM）→ 自动测试 → 自动运行。
• crawler-guard/status 返回 active_requeue_interval_sec，用于确认周期重跑间隔（默认 43200 秒，即 12 小时）。
• 飞书群内 @机器人 的文本消息若含 URL，也会自动入库到爬虫列表。