🔌 对接文档

架构说明

本站是完全独立的纯静态网站（静态资源部署在 B 服务器，例如 Nginx、对象存储 OSS/CDN）。本站不在 Flask 服务中托管，所有动态数据（版本信息、公告）都通过浏览器 跨域 HTTP 向「后端 A」请求。

浏览器 ── HTTP (CORS) ──▶ 后端 A（雨墨工具箱 Flask API）
          │
          └── 静态资源（html/css/js）来自 B 服务器

好处：前后端解耦，静态站访问更快、可上 CDN，与业务 API 互不影响。

⚠️ 必须项：后端 A 开启 CORS

浏览器跨域请求会被拦截，因此「后端 A」必须允许本站域名跨域访问。后端是 Flask，使用 flask-cors 全局放开（仅建议开发期；上线建议限定白名单域名）：

# backend/app.py（后端 A）
from flask_cors import CORS
CORS(app)   # 开发期放开；上线建议：CORS(app, resources={r"/api/*": {"origins": ["https://你的博客域名"]}})

注意：若后端通过 Nginx 反代，也需要确保返回 Access-Control-Allow-Origin 响应头。

通用返回结构

所有接口统一返回 JSON：

{
  "success": true,          // 是否成功
  "message": "OK",          // 提示信息
  "data": { ... }           // 业务数据
}

可用接口

接口	方法	说明
/api/health	GET	健康检查
/api/home/announcements	GET	系统公告列表（首页公告条）
/api/check_update?current_version_code=0	GET	获取最新版本信息（下载中心）
/api/mod/list?user_id=&page=&page_size=	GET	公开 MOD 列表（可选）
/api/mod/categories	GET	MOD 分类（可选）

提示：带鉴权的接口（如个人数据、写操作）需要登录 token，博客页面通常只使用公开接口。

接口示例

1. 健康检查

GET /api/health
→ { "success": true, "message": "OK" }

2. 公告列表

GET /api/home/announcements
→ { "success": true, "data": { "items": [ { "tag": "更新", "content": "..." } ] } }

3. 检查更新（下载中心用）

GET /api/check_update?current_version_code=0
→ { "success": true, "data": { "latest_version": "1.0.0", "update_time": "...", ... } }

前端调用示例（JavaScript / fetch）

// js/api.js 已封装以下方法（见本站 js/api.js）：
const r = await YumApi.announcements();  // 拉公告
const u = await YumApi.checkUpdate();    // 拉版本
if (r.success) console.log(r.data.items);

接口基地址统一在 js/config.js 的 BLOG_CONFIG.apiBase 配置，站点迁移只用改这一处。