ThemeDist Monitor — API 接口文档#

获取主题数据 → Schema 校验 → HTML 标签清洗 → XSS 模式扫描 → CSS 安全分析 → 安全判定

{
  "type": "vercel",
  "label": "Vercel",
  "status": "online",
  "color": "brightgreen",
  "message": "online"
}

![Vercel 状态](https://themedist-monitor.vercel.app/api/v1/badges/vercel)
![Netlify 状态](https://themedist-monitor.vercel.app/api/v1/badges/netlify)
![主题安全](https://themedist-monitor.vercel.app/api/v1/badges/theme)

<img src="https://themedist-monitor.vercel.app/api/v1/badges/vercel" alt="Vercel Status" />
<img src="https://themedist-monitor.vercel.app/api/v1/badges/theme" alt="Theme Safety" />

# 获取 SVG 徽章
curl -sS 'https://themedist-monitor.vercel.app/api/v1/badges/vercel'

# 调试模式查看 JSON 元数据
curl -sS 'https://themedist-monitor.vercel.app/api/v1/badges/vercel?debug=1' | jq .

{
  "overall": "healthy",
  "platforms": {
    "vercel": {
      "status": "online",
      "latencyMs": 245,
      "cacheStatus": "HIT"
    },
    "netlify": {
      "status": "online",
      "latencyMs": 312,
      "cacheStatus": "MISS"
    }
  },
  "theme": {
    "date": "2026-05-24",
    "presetName": "Minimal Blue",
    "themeCount": 151,
    "isSafe": true
  },
  "database": {
    "status": "connected",
    "pending": 7,
    "approved": 4
  },
  "checkedAt": "2026-05-24T00:00:00.000Z"
}

curl -sS 'https://themedist-monitor.vercel.app/api/v1/status' | jq .

async function checkHealth() {
  const res = await fetch('https://themedist-monitor.vercel.app/api/v1/status');
  const data = await res.json();
  console.log(`Overall: \${data.overall}`);
  console.log(`Vercel: \${data.platforms.vercel.status} (\${data.platforms.vercel.latencyMs}ms)`);
  console.log(`Netlify: \${data.platforms.netlify.status} (\${data.platforms.netlify.latencyMs}ms)`);
  return data;
}

{
  "status": {
    "vercel": { "status": "online", "latencyMs": 245, "cacheStatus": "HIT" },
    "netlify": { "status": "online", "latencyMs": 312, "cacheStatus": "MISS" },
    "db": "healthy",
    "dbRedis": "connected",
    "dbPending": 7,
    "dbApproved": 4
  },
  "metrics": {
    "avgLatency24h": { "vercel": 280, "netlify": 340 },
    "cdnHitRate": 85,
    "themeCount": 12,
    "sla": { "7day": 99.8, "30day": 99.5 }
  },
  "performanceLogs": [
    {
      "id": "uuid",
      "timestamp": "2026-05-24T12:00:00.000Z",
      "platform": "vercel",
      "endpoint": "https://themedist.vercel.app/api/v1/today.json",
      "statusCode": 200,
      "latencyMs": 245,
      "cacheStatus": "HIT",
      "cacheControl": "public, max-age=3600"
    }
  ],
  "latestSnapshot": {
    "id": "uuid",
    "date": "2026-05-24",
    "preset": "minimal-blue",
    "presetName": "Minimal Blue",
    "author": "themedist",
    "themeCount": 12,
    "isValidSchema": true,
    "securityStatus": "safe",
    "flaggedReasons": []
  },
  "alerts": {
    "unresolved": [],
    "recent": []
  },
  "securityIncidents": [],
  "metricsHistory": {
    "vercelLatency": [{ "timestamp": "...", "value": 245 }],
    "netlifyLatency": [{ "timestamp": "...", "value": 312 }],
    "cdnHitRate": [{ "timestamp": "...", "value": 85 }]
  },
  "timestamp": "2026-05-24T12:00:00.000Z"
}

curl -sS 'https://themedist-monitor.vercel.app/api/v1/data' | jq '.metrics'

{
  "message": "Monitor check complete",
  "timestamp": "2026-05-24T06:51:05.605Z",
  "performanceLogs": [
    {
      "id": "839c12f6-...",
      "timestamp": "2026-05-24T06:51:01.354Z",
      "platform": "vercel",
      "endpoint": "https://themedist.vercel.app/api/v1/today.json",
      "statusCode": 200,
      "latencyMs": 820,
      "cacheStatus": "MISS",
      "cacheControl": "public, max-age=3600",
      "error": null
    }
  ],
  "themeSnapshot": {
    "id": "3ce3e8ad-...",
    "date": "2026-05-24",
    "preset": "holiday-144",
    "presetName": "BUDDHA BIRTHDAY",
    "themeCount": 151,
    "isValidSchema": true,
    "securityStatus": "safe",
    "flaggedReasons": []
  },
  "alerts": [],
  "notificationsSent": 0
}

# 手动触发检测
curl -sS 'https://themedist-monitor.vercel.app/api/v1/monitor' | jq .

# 仅查看是否触发告警
curl -sS 'https://themedist-monitor.vercel.app/api/v1/monitor' | jq '.alerts'

curl -sS -X POST \
  -H 'Authorization: Bearer your-cron-secret' \
  'https://themedist-monitor.vercel.app/api/v1/monitor' | jq .

{ "message": "All monitoring data cleared" }

curl -sS -X DELETE \
  -H 'Authorization: Bearer your-cron-secret' \
  'https://themedist-monitor.vercel.app/api/v1/monitor'

{
  "status": "safe",
  "message": "当前主题可安全使用",
  "securityStatus": "safe",
  "flaggedReasons": [],
  "schemaValid": true,
  "themeName": "Minimal Blue",
  "checkedAt": "2026-05-24",
  "timestamp": "2026-05-24T12:00:00.000Z"
}

{
  "status": "unsafe",
  "message": "检测到安全风险",
  "securityStatus": "unsafe",
  "flaggedReasons": [
    "检测到事件处理器: onclick",
    "检测到 javascript: 协议"
  ],
  "schemaValid": true,
  "themeName": "Malicious Theme",
  "checkedAt": "2026-05-24",
  "timestamp": "2026-05-24T12:00:00.000Z"
}

curl -sS 'https://themedist-monitor.vercel.app/api/v1/security-status' | jq .

{
  "env": {
    "HTTPS_PROXY": "not set",
    "HTTP_PROXY": "not set"
  },
  "probes": [
    {
      "url": "themedist.vercel.app/api/v1/today.json",
      "ok": true,
      "status": 200,
      "ms": 245
    },
    {
      "url": "themedist.netlify.app/api/v1/today.json",
      "ok": true,
      "status": 200,
      "ms": 312
    },
    {
      "url": "www.baidu.com",
      "ok": true,
      "status": 200,
      "ms": 180
    }
  ],
  "summary": "All reachable",
  "timestamp": "2026-05-24T12:00:00.000Z"
}

curl -sS 'https://themedist-monitor.vercel.app/api/v1/diagnose' | jq .

{
  "date": "2026-05-24",
  "preset": "minimal-blue",
  "presetName": "Minimal Blue",
  "author": "themedist",
  "available": 12,
  "cssVars": {
    "--color-primary": "#3b82f6",
    "--color-bg": "#0f172a"
  },
  "customCss": ":root { ... }",
  "extensions": [],
  "directory": [],
  "_meta": {
    "sanitized": true,
    "schemaValid": true,
    "source": "vercel",
    "timestamp": "2026-05-24T12:00:00.000Z"
  }
}

async function applyTheme() {
  try {
    const res = await fetch('https://themedist-monitor.vercel.app/api/v1/today-safe');
    if (!res.ok) {
      console.error('无法获取安全主题数据');
      return;
    }
    const theme = await res.json();
    // 直接将清洗后的 CSS 变量应用到 :root
    const root = document.documentElement;
    Object.entries(theme.cssVars).forEach(([key, value]) => {
      root.style.setProperty(key, value);
    });
    console.log(`已应用主题: \${theme.presetName} (来源: \${theme._meta.source})`);
  } catch (err) {
    console.error('主题加载失败', err);
  }
}

curl -sS 'https://themedist-monitor.vercel.app/api/v1/today-safe' | jq '._meta'

{
  "probe": {
    "region": "hkg1",
    "duration": 520
  },
  "results": [
    {
      "id": "uuid",
      "timestamp": "2026-05-24T12:00:00.000Z",
      "region": "hkg1",
      "platform": "vercel",
      "endpoint": "https://themedist.vercel.app/api/v1/today.json",
      "statusCode": 200,
      "latencyMs": 245
    },
    {
      "id": "uuid",
      "timestamp": "2026-05-24T12:00:00.000Z",
      "region": "hkg1",
      "platform": "netlify",
      "endpoint": "https://themedist.netlify.app/api/v1/today.json",
      "statusCode": 200,
      "latencyMs": 312
    }
  ]
}

curl -sS 'https://themedist-monitor.vercel.app/api/v1/probe' | jq '.probe.region'

{
  "duration": 245,
  "platform": "vercel"
}

{ "ok": true }

{ "error": "duration 需为 0–60000 之间的数值" }

// 在页面加载时记录主题获取耗时并上报
const start = performance.now();

fetch('https://themedist-monitor.vercel.app/api/v1/today-safe')
  .then(res => res.json())
  .then(theme => {
    const duration = Math.round(performance.now() - start);
    // 应用主题...
    Object.entries(theme.cssVars).forEach(([k, v]) => {
      document.documentElement.style.setProperty(k, v);
    });
    // 上报遥测（fire-and-forget）
    navigator.sendBeacon(
      'https://themedist-monitor.vercel.app/api/v1/telemetry',
      JSON.stringify({ duration, platform: 'vercel' })
    );
  });

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  -d '{"duration": 245, "platform": "vercel"}' \
  'https://themedist-monitor.vercel.app/api/v1/telemetry'

## ThemeDist 服务状态

![Vercel](https://themedist-monitor.vercel.app/api/v1/badges/vercel)
![Netlify](https://themedist-monitor.vercel.app/api/v1/badges/netlify)
![安全](https://themedist-monitor.vercel.app/api/v1/badges/theme)

// 轻量轮询 — 适合状态指示灯
setInterval(async () => {
  const { overall, platforms } = await fetch(
    'https://themedist-monitor.vercel.app/api/v1/status'
  ).then(r => r.json());

  updateIndicator('vercel-light', platforms.vercel.status);
  updateIndicator('netlify-light', platforms.netlify.status);
}, 30000); // 每 30 秒

// 完整数据 — 适合图表仪表盘
async function loadDashboard() {
  const data = await fetch(
    'https://themedist-monitor.vercel.app/api/v1/data'
  ).then(r => r.json());

  renderLatencyChart(data.metricsHistory.vercelLatency);
  renderCdnPieChart(data.metrics.cdnHitRate);
  renderAlertList(data.alerts.unresolved);
}

// React Hook 示例
function useThemeDist() {
  const [theme, setTheme] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const start = performance.now();
    fetch('https://themedist-monitor.vercel.app/api/v1/today-safe')
      .then(res => res.json())
      .then(data => {
        setTheme(data);
        // 应用 CSS 变量
        const root = document.documentElement;
        Object.entries(data.cssVars).forEach(([k, v]) => {
          root.style.setProperty(k, v);
        });
        // 上报遥测
        const duration = Math.round(performance.now() - start);
        fetch('https://themedist-monitor.vercel.app/api/v1/telemetry', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ duration, platform: 'vercel' }),
        }).catch(() => {}); // 静默失败
      })
      .finally(() => setLoading(false));
  }, []);

  return { theme, loading };
}

#!/bin/bash
# crontab: */5 * * * * /path/to/themedist-healthcheck.sh

STATUS=\$(curl -sS 'https://themedist-monitor.vercel.app/api/v1/status')
OVERALL=\$(echo "\$STATUS" | jq -r '.overall')

if [ "\$OVERALL" = "down" ]; then
  # 触发你的告警通道（Slack、PagerDuty 等）
  echo "ThemeDist 全面宕机！" | mail -s "ALERT" ops@example.com
elif [ "\$OVERALL" = "degraded" ]; then
  echo "ThemeDist 性能降级: \$STATUS" | mail -s "WARN" ops@example.com
fi

curl -sS 'https://themedist-monitor.vercel.app/api/v1/diagnose' | jq .

Vercel Cron (每日 0:00 UTC)
       │
       ▼
POST /api/v1/monitor (Bearer 鉴权)
       │
       ▼
  runAllChecks()
       │
       ├─► fetch themedist.vercel.app  ─► PerformanceLog ─► KV ZSET
       ├─► fetch themedist.netlify.app ─► PerformanceLog ─► KV ZSET
       ├─► fetch DIY themes API       ─► DB health check
       ├─► fetch index-data.json      ─► Build index check
       ├─► fetch trending.json        ─► Redis write path
       ├─► fetch admin/health.json    ─► Redis direct status
       └─► validate + security scan   ─► ThemeSnapshot ─► KV ZSET
                                               │
                                    ┌──────────┴──────────┐
                                    ▼                     ▼
                              Alert 判定             Status Hash
                                    │                  (KV HASH)
                                    ▼
                              Email 通知
                           (Nodemailer + QQ SMTP)

用户请求:
  /api/v1/status   ─► 读取 KV HASH        ─► 即时响应 (Edge, <50ms)
  /api/v1/data     ─► 读取 KV ZSET/LIST   ─► 聚合响应 (Node, ~100ms)
  /api/v1/badges   ─► 读取 KV HASH        ─► 渲染 SVG (Node, ~50ms)

第 1 层：Schema 校验
  └─ 验证 today.json 结构完整性（必需字段、CSS 变量数量下限）

第 2 层：HTML 清洗
  └─ 白名单标签 + 白名单属性 + 事件处理器剥离

第 3 层：XSS 模式扫描（14 条正则规则）
  └─ script 标签、事件处理器、javascript: 协议、document.cookie、
     eval()、iframe、data:text/html

第 4 层：CSS 安全分析
  └─ @import 外链白名单、expression() 检测、behavior 检测、
     -moz-binding 检测、url() 引用审查、变量数量异常检测

第 5 层：IP 封禁
  └─ 1 小时内违规 5 次 → 24 小时封禁

# 安装依赖
npm install

# 启动开发服务器（默认 localhost:3000）
npm run dev

# 手动执行一次监控检测
npm run monitor

# 访问 API 文档
open http://localhost:3000/api-docs

# 访问仪表盘
open http://localhost:3000

HTTPS_PROXY=http://proxy.example.com:8080
HTTP_PROXY=http://proxy.example.com:8080

src/
├── app/
│   ├── page.tsx                       # 仪表盘 UI 主页
│   ├── layout.tsx                     # 根布局（Metadata + Providers）
│   ├── globals.css                    # 全局样式 + Tailwind 指令
│   ├── api-docs/page.tsx              # API 文档页（渲染 DOCS/API.md）
│   └── api/
│       ├── badges/[type]/route.ts     # SVG 徽章端点
│       ├── status/route.ts            # 平台健康摘要（Edge Runtime）
│       ├── data/route.ts              # 仪表盘完整数据
│       ├── monitor/route.ts           # 触发 / 清除监控检测
│       ├── security-status/route.ts   # 安全审计结果
│       ├── diagnose/route.ts          # 网络连通性诊断
│       ├── today-safe/route.ts        # 安全主题代理
│       ├── probe/route.ts             # 边缘探测（Edge Runtime）
│       ├── telemetry/route.ts         # RUM 遥测上报
│       └── debug-kv/route.ts          # KV 存储诊断
├── components/
│   ├── live-status.tsx                # 实时状态卡片
│   ├── metrics-panel.tsx              # 图表面板
│   ├── theme-audit.tsx                # 安全审计卡片
│   ├── alerts-history.tsx             # 告警历史列表
│   ├── failover-guide.tsx             # 集成指南 + 代码片段
│   ├── copy-all-button.tsx            # 复制按钮
│   ├── providers.tsx                  # i18n + Header + Footer
│   └── theme-dist-theme.tsx           # 主题 CSS 变量应用
├── lib/
│   ├── monitor.ts                     # 核心监控编排
│   ├── store.ts                       # 数据持久化（KV / 本地文件）
│   ├── kv.ts                          # Vercel KV 封装
│   ├── security.ts                    # XSS 扫描器
│   ├── css-analyzer.ts                # CSS 安全分析器
│   ├── html-sanitizer.ts              # HTML 标签清洗器
│   ├── validator.ts                   # JSON Schema 校验器
│   ├── notifier.ts                    # 邮件告警发送
│   ├── fetch-proxy.ts                 # 代理感知 fetch
│   ├── rate-limit.ts                  # 频率限制
│   ├── alert-cooldown.ts              # 告警冷却期
│   ├── archiver.ts                    # 数据归档
│   ├── cors.ts                        # CORS 头工具
│   ├── security-logger.ts             # 安全事件日志
│   ├── ip-blocker.ts                  # IP 封禁
│   └── i18n.tsx                       # 中英文国际化
└── types/
    └── index.ts                       # TypeScript 类型定义