From a92ddccc465a59b4a53e9e13217ee04f8ad1c4a2 Mon Sep 17 00:00:00 2001
From: mediabot-pt <295750538+mediabot-pt@users.noreply.github.com>
Date: Tue, 7 Jul 2026 11:18:15 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=E6=8E=A5=E5=8F=A3?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3=E5=8F=AF=E7=94=A8=E6=80=A7=E8=AF=B4=E6=98=8E?=
 =?UTF-8?q?=EF=BC=8C=E8=A1=A5=E5=85=85=20PAR=20Server=20=E6=95=B4=E4=BD=93?=
 =?UTF-8?q?=E4=B8=8D=E5=8F=AF=E7=94=A8=E6=97=B6=E7=9A=84=20CDN=20fallback?=
 =?UTF-8?q?=20=E6=96=B9=E6=A1=88?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/mediabot-api-migration.md | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/docs/mediabot-api-migration.md b/docs/mediabot-api-migration.md
index 65f99ae..7060eac 100644
--- a/docs/mediabot-api-migration.md
+++ b/docs/mediabot-api-migration.md
@@ -67,10 +67,16 @@ ETag: "abc123def456..."
 ```
 _（Body 为空，节省带宽）_
 
-**可用性保障**:
-- 优先从 MySQL 数据库读取
-- 数据库不可用时自动回退到七牛云 CDN `snapshots/{siteId}.json`
-- 两层级联失败返回 500
+**可用性保障**（PAR Server 端三层级联）:
+- 第一层：优先从 MySQL 数据库读取
+- 第二层：数据库异常时自动回退到七牛云 CDN `snapshots/{siteId}.json`
+- 第三层：CDN 也无数据时，实时构建（从各子表 + 七牛云存储拼装）
+- 全部失败返回 500
+
+**MediaBot 端建议**（应对 PAR Server 整体不可用）:
+- MediaBot 应缓存每个站点的 CDN URL（`https://{七牛云CDN域名}/snapshots/{siteId}.json`）
+- 当 PAR Server 连接超时/拒绝连接时，直接请求 CDN URL 作为终极 fallback
+- 这样即使 PAR Server 宕机，配置仍可通过 CDN 获取（每次 publish 都会同步上传到 CDN）
 
 ---
 
@@ -189,7 +195,9 @@ MediaBot 启动 / 定时任务:
 
 ```
 1. 优先调用新接口 GET /api/v1/snapshots/{siteId}
-2. 失败时 fallback 到旧接口组合:
+2. PAR Server 不可用时 fallback 到 CDN:
+   - 直接 GET https://{CDN域名}/snapshots/{siteId}.json
+3. CDN 也无数据时 fallback 到旧接口组合:
    - GET /api/v1/configs/{siteId}/script
    - GET /api/v1/sites/{siteId}/pages
    - GET /api/v1/risk-rules/{siteType}