102 行
3.2 KiB
Markdown
102 行
3.2 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
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 调用
|
||
|
||
```bash
|
||
curl 'https://csp.hao.work/admin139/api/v1/me' \
|
||
-H 'Authorization: Bearer <token>'
|
||
```
|
||
|
||
### 3.3 使用 Basic 调用
|
||
|
||
```bash
|
||
curl 'https://csp.hao.work/admin139/api/v1/me' \
|
||
-H 'Authorization: Basic YWxpY2U6cGFzc3dvcmQxMjM='
|
||
```
|
||
|
||
## 4. Python 示例（requests）
|
||
|
||
```python
|
||
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，也会自动入库到爬虫列表。
|