API 自动化指南

供外部服务或其它应用通过 API Key 安全调用本站接口，实现采集、发布等自动化流程。 论坛内不提供内置采集应用，自动化逻辑请在独立服务中实现后对接本站 API。

1. 整体流程

  1. 在服务器上配置环境变量 API_KEY_PEPPER，并完成数据库迁移。
  2. 创建首把 API Key（管理命令或后台），保存仅显示一次的明文密钥。
  3. 在您的自动化服务中保存密钥，请求时携带 Authorization: Bearer …。
  4. 调用 GET /api/v1/me/ 确认密钥有效与权限范围。
  5. 按需调用业务 API（新闻/帖子发布等）；密钥管理接口见下表。

采集源配置、RSS 解析、审核发布等方案说明见项目文档 docs/automation/（方案存档，代码需自行或其它应用实现）。

2. 准备工作

环境变量

在 .env 中设置与 DJANGO_SECRET_KEY 独立的随机串：

API_KEY_PEPPER=请替换为长随机字符串

数据库迁移

python manage.py migrate apikeys

创建首把密钥

任选一种方式（明文只出现一次，请立即保存）：

python manage.py create_apikey \
  --name "自动化服务" \
  --scopes keys.manage,automation.write

或在 Django 后台 → API 密钥 中勾选权限新建（需 staff 账号）。

3. 认证方式

所有 /api/v1/ 接口均为 JSON，无需 CSRF，适合服务端调用。密钥格式：anl_ 开头。

方式 请求头
推荐 Authorization: Bearer anl_你的密钥
备选 X-Api-Key: anl_你的密钥

切勿将密钥写入前端页面、公开仓库或日志；泄露后请在后台吊销并重新创建。

4. 权限范围（scope）

每个密钥绑定若干 scope，接口会校验是否具备所需权限。后台通过复选框勾选，无需手写 JSON。

scope 说明 用途
automation.read 自动化-读取 查询新闻/帖子板块等只读数据
automation.write 自动化-写入 发布新闻/帖子等写入操作
keys.manage API 密钥管理 列出、创建、吊销 API Key
* 全部权限 包含以上全部权限，生产环境请按需最小授权

创建密钥时 scopes 可传 JSON 数组或逗号分隔字符串，例如 "automation.write,keys.manage"。

5. 可用接口

基础地址：https://www.anlian.cyou/api/v1/

方法 路径 所需权限 说明
GET /api/v1/me/ 任意有效 Key 校验密钥并返回名称、scope、最近使用时间等
GET /api/v1/keys/ keys.manage 或 staff 列出密钥（不含明文）
POST /api/v1/keys/ keys.manage 或 staff 创建密钥；响应含一次性 key 字段
GET /api/v1/news/boards/ automation.read 或 automation.write 列出可用新闻板块（发布时使用返回的 id 作为 news_board_id）
GET /api/v1/posts/boards/ automation.read 或 automation.write 列出可用帖子板块（发布时使用返回的 id 作为 board_id）
POST /api/v1/news/ automation.write 发布新闻；JSON 体含 title、news_board_id（或 board_id）、content
POST /api/v1/posts/ automation.write 发布帖子；JSON 体含 title、board_id、content；可选 is_anonymous
POST /api/v1/keys/<id>/revoke/ keys.manage 或 staff 吊销密钥（is_active=false）

发布接口使用专用账号（默认 automation_bot，可通过环境变量 AUTOMATION_PUBLISH_USERNAME 配置）。 采集源配置、RSS 解析等方案说明见项目文档 docs/automation/。

6. 请求示例

将 YOUR_KEY 替换为明文密钥；生产环境请使用 https://。

自检当前密钥

curl -sS "https://www.anlian.cyou/api/v1/me/" \
  -H "Authorization: Bearer YOUR_KEY"

创建子密钥（需 keys.manage）

curl -sS -X POST "https://www.anlian.cyou/api/v1/keys/" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"采集 Worker","scopes":"automation.write"}'

查询新闻板块（需 automation.read 或 automation.write）

curl -sS "https://www.anlian.cyou/api/v1/news/boards/" \
  -H "Authorization: Bearer YOUR_KEY"

查询帖子板块

curl -sS "https://www.anlian.cyou/api/v1/posts/boards/" \
  -H "Authorization: Bearer YOUR_KEY"

发布新闻（需 automation.write）

curl -sS -X POST "https://www.anlian.cyou/api/v1/news/" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"示例新闻标题","news_board_id":1,"content":"<p>正文 HTML</p>"}'

发布帖子（需 automation.write）

curl -sS -X POST "https://www.anlian.cyou/api/v1/posts/" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"示例帖子","board_id":1,"content":"<p>正文</p>","is_anonymous":false}'

吊销密钥

curl -sS -X POST "https://www.anlian.cyou/api/v1/keys/1/revoke/" \
  -H "Authorization: Bearer YOUR_KEY"

成功响应示例（/me/）

{
  "ok": true,
  "key": {
    "id": 1,
    "name": "自动化服务",
    "prefix": "anl_xxxx",
    "scopes": ["automation.write", "keys.manage"],
    "is_active": true,
    ...
  }
}

失败时返回 {"ok": false, "error": "…"}，HTTP 状态码为 401（未认证）或 403（权限不足）。

7. 在业务代码中接入

本站 Django 应用可为新接口添加装饰器，与外部服务使用同一套 Key：

from apikeys.decorators import require_api_key
from apikeys.scopes import AUTOMATION_WRITE

@require_api_key(scopes=[AUTOMATION_WRITE])
def trigger_ingest(request):
    # 仅持有 automation.write 的有效密钥可访问
    ...

外部 Python 服务示例（使用 requests）：

import os
import requests

API_BASE = "https://www.anlian.cyou/api/v1"
headers = {"Authorization": f"Bearer {os.environ['ANLIAN_API_KEY']}"}

r = requests.get(f"{API_BASE}/me/", headers=headers, timeout=30)
r.raise_for_status()
print(r.json())

8. 安全建议

  • 遵循最小权限：采集服务仅需 automation.write，勿默认使用 *。
  • 生产环境仅通过 HTTPS 调用；定期轮换密钥并在后台吊销旧 Key。
  • 自动化发布建议使用专用账号（如 automation_bot），避免与真人账号混用。
  • 采集外链需防 SSRF、内容 XSS 与禁词风控，详见自动化方案文档中的安全章节。

← 返回首页