CDN内容分发管理工具

配置和优化CDN部署，管理缓存策略与安全加固，实现加速、稳定分发及故障排查。

Install

openclaw skills install @thcjp/cdn-toolkit

核心功能: 本技能提供化工作流场景等能力。

CDN

快速开始

确认运行环境满足依赖说明中的要求
在AI Agent对话中调用本技能,提供必要的输入参数
检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

专业版增强能力

能力	免费版	付费版
基础功能	支持	支持
深度漏洞扫描与CVE关联	不支持	支持
安全基线合规审计	不支持	支持
批量资产风险评分	不支持	支持
威胁情报实时订阅与告警	不支持	支持
零日漏洞检测与防护规则下发	不支持	支持

主要能力

CDN 配置部署与域名接入，支持 CNAME 接入、NS 接入、ANS 接入三种模式
缓存策略优化：TTL 规则、缓存键（Cache-Key）配置、查询字符串排序与忽略、Vary 头处理
安全加固：WAF 规则、DDoS 防护、防盗链（Referer/Token）、HTTPS 强制与 HSTS、IP 黑白名单
性能调优：Brotli/Gzip 压缩、图片优化（WebP/AVIF 自适应）、HTTP/2 与 HTTP/3、边缘函数（Edge Functions）
故障排障：缓存命中率分析、回源诊断、HTTP 状态码分析、边缘节点探测、DNS 解析链路追踪
多 CDN 智能调度与容灾切换，支持按地域、运营商、权重分配流量

启动指引

确认运行环境满足依赖说明中的要求
在AI Agent对话中调用本技能,提供必要的输入参数
检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

应用场景

场景	输入	输出
安全检查	目标域名与扫描选项	漏洞列表与风险评级
CDN配置	域名与缓存规则	分发状态与边缘节点列表
缓存策略	域名与过期规则	缓存命中率与配置状态
性能优化	域名与资源类型	压缩方案与加载耗时对比
故障排障	域名与异常现象	诊断报告与修复建议

不适用于：需要人工判断的复杂决策场景

操作流程

确认运行环境满足依赖说明中的要求
根据适用场景选择合适的使用方式
执行操作并检查输出结果
如遇错误，参考错误处理章节

流程详解：缓存策略配置

以一个典型电商站点为例，完整的缓存策略配置步骤如下：

步骤 1：资源分类与 TTL 规划

资源类型	URL 特征	建议缓存时间	浏览器缓存
HTML 页面	`/*.html`	10 分钟	不缓存或 60 秒
CSS/JS	`/static/*.{css,js}`	30 天	1 年
图片	`/*.{png,jpg,webp}`	30 天	30 天
API 接口	`/api/*`	不缓存	不缓存
版本化静态资源	`/static/v2.1.0/*`	1 年	1 年

步骤 2：缓存键配置

查询字符串处理策略选择依据：

忽略全部参数：适用于图片等静态资源，URL a.jpg?ver=1 和 a.jpg?ver=2 共享同一缓存
保留全部参数：适用于 API 或动态页面
保留指定参数：适用于同时含版本号和追踪参数的场景，如保留 ver 忽略 utm_source
参数排序：?b=2&a=1 与 ?a=1&b=2 归一为同一缓存键，避免缓存冗余

步骤 3：验证缓存命中

bash

# 检查响应头中的缓存命中状态
curl -sI "https://example.com/static/app.js" | grep -i "cf-cache-status\|x-cache\|age\|hit"

# Cloudflare 返回示例: cf-cache-status: HIT
# AWS CloudFront 返回示例: X-Cache: Hit from cloudfront
# 阿里云 CDN 返回示例: X-Cache: HIT

缓存策略优选实践

避免缓存穿透

对于不存在的资源（404），建议设置短 TTL（如 10 秒），防止恶意请求绕过缓存直接打到源站：

text

# Cloudflare Page Rule 示例
匹配: *example.com/non-existent/*
设置: 缓存级别 -> 缓存所有内容, Edge Cache TTL -> 10s

动态内容缓存

即使 API 响应为 JSON，如果数据更新频率低于请求频率，仍可在边缘缓存：

text

# Cache-Control 头部配置
Cache-Control: public, max-age=30, s-maxage=300
# s-maxage=300 让 CDN 缓存 5 分钟，max-age=30 让浏览器缓存 30 秒

缓存预热与刷新

预热：在发版前主动将新版本静态资源推送到边缘节点，避免首次访问回源延迟
刷新：紧急修复后清除旧缓存，注意刷新粒度（按 URL 刷新 vs 按目录刷新 vs 全量刷新）
灰度刷新：先刷新部分节点，观察无异常后再全量刷新

安全加固指南

HTTPS 强制跳转与 HSTS

text

# Nginx 源站配置
server {
    listen 80;
    return 301 https://$host$request_uri;
}

# HSTS 头部（通过 CDN 全局添加）
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

防盗链配置

Referer 防盗链：检查请求头 Referer，允许白名单域名，阻止空 Referer（根据业务需求）
Token 鉴权：生成带过期时间的签名 URL，适用于付费内容保护

text

# 签名 URL 格式示例
https://cdn.example.com/video.mp4?auth_key=1700000000-0-0-abc123hash
# auth_key = 过期时间戳-随机数-用户ID-MD5签名

WAF 规则配置要点

防护类型	建议动作	说明
SQL 注入	阻断	拦截 `UNION SELECT`、`OR 1=1` 等特征
XSS 攻击	阻断	拦截 `<script>`、`onerror=` 等特征
路径穿越	阻断	拦截 `../`、`..\\` 序列
高频请求	限速	单 IP 每秒 > 100 次触发限速
异常 User-Agent	质询	空 UA 或已知爬虫 UA 触发 JS 质询

主流 CDN 平台配置对照

功能	Cloudflare	AWS CloudFront	阿里云 CDN	腾讯云 CDN
接入方式	NS/CNAME	CNAME	CNAME	CNAME
缓存规则	Page Rules/Cache Rules	Cache Behavior	缓存配置	缓存配置
边缘函数	Workers	Lambda@Edge	Edge Routine	EdgeOne Functions
图片优化	Polish	无内置	图片处理	图片处理
WAF	内置	需额外购买	需额外购买	需额外购买
实时日志	Logpush	Kinesis	实时日志	实时日志

故障排障速查

场景 1：缓存命中率低（< 80%）

排查步骤：

检查 Cache-Control 头是否包含 no-cache、private、no-store
检查查询字符串参数是否过多导致缓存键碎片化
检查是否存在 Vary: * 或 Vary: User-Agent 导致缓存失效
检查回源频率，确认源站是否返回 Set-Cookie 导致 CDN 不缓存

场景 2：内容更新后仍显示旧版本

text

# 1. 确认缓存是否已被刷新
com/page.html" | grep -i "age\|x-cache"

# 2. 检查文件名是否带版本号（推荐方案）
# 错误做法: app.js  (更新后需手动刷新缓存)
# 正确做法: app.v2.1.0.js  (文件名变更自动绕过缓存)

# 3. 紧急情况：通过 API 强制刷新
# Cloudflare
curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/purge_cache" \
  -H "Authorization: Bearer {token}" \
  -d '{"files":["https://example.com/page.html"]}'

场景 3：CDN 节点回源超时

可能原因与处理：

源站带宽瓶颈 -> 升级源站带宽或启用 CDN 源站负载均衡
源站防火墙拦截 CDN 回源 IP -> 将 CDN 回源 IP 段加入白名单
源站响应慢（> 30 秒） -> 检查源站数据库和后端服务性能
回源 Host 配置错误 -> 确认回源 Host 与源站虚拟主机配置匹配

请求格式

参数名	类型	必填	说明
domain	string	是	待配置的 CDN 域名，如 `cdn.example.com`
action	string	是	操作类型：`configure`/`optimize`/`troubleshoot`/`security`
content	string	否	CDN 处理的内容输入，可选值: json/text/markdown
cache_rules	object	否	缓存规则配置，包含 URL 模式与 TTL
security_config	object	否	安全配置，包含 WAF/防盗链/HTTPS 选项
style	string	否	输出风格, 参考 `references/style.md`

响应格式

json

{
  "success": true,
  "data": {
    "domain": "cdn.example.com",
    "status": "configured",
    "cache_hit_rate": "94.2%",
    "edge_nodes": 42,
    "config_summary": {
      "cache_rules": "8 条规则已生效",
      "https": "已启用, HSTS 已配置",
      "compression": "Brotli + Gzip",
      "waf": "已启用, 12 条规则"
    },
    "performance": {
      "avg_ttfb_ms": 45,
      "bandwidth_saved": "78.5%"
    },
    "metadata": {
      "template_used": "cdn-optimizer",
      "word_count": 0,
      "style": "专业"
    }
  },
  "error": null
}

输出模板参考: assets/output.json

异常管理

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达

环境要求

运行环境

Agent平台: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
操作系统: Windows / macOS / Linux

依赖说明(补充)

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供

API Key 配置

可用性分类

分类: MD+execute()
说明: 基于Markdown的AI Skill,

API Key配置方式:

bash

export API_KEY="${API_KEY:?请设置环境变量}"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

疑问解答

Q1: 如何开始使用CDN？

A: 首先在 CDN 服务商控制台添加加速域名，配置源站地址（IP 或域名）。然后根据业务类型设置缓存规则（静态资源长缓存、动态内容不缓存）。配置完成后在域名 DNS 解析中添加 CNAME 记录指向 CDN 分配的域名。等待 DNS 生效后（通常 5-30 分钟），通过 curl -sI 检查响应头中的 X-Cache 字段确认缓存是否命中。

Q2: 如何提升缓存命中率？

A: 1) 确保 Cache-Control 头设置合理，避免使用 no-cache/private；2) 对查询字符串进行规范化，忽略无意义参数（如 utm 追踪参数）；3) 对版本化静态资源使用长 TTL；4) 避免不必要的 Vary 头（如 Vary: User-Agent 会导致缓存碎片化）；5) 定期检查缓存命中率报表，优化低命中率的 URL。

Q3: CDN 回源频繁如何排查？

A: 使用 CDN 控制台的回源日志或实时日志分析功能，筛选回源请求。常见原因包括：缓存 TTL 设置过短、源站返回 Set-Cookie 头导致 CDN 不缓存、Cache-Control: private 配置、查询参数变化导致缓存键不匹配。可通过 curl -sI 检查源站返回的响应头确认问题。

故障恢复流程

错误场景(续)	原因	处理方式
LLM响应超时或无响应	网络延迟或模型负载过高	请求重试；确认Agent平台LLM服务正常
输入内容格式不正确	用户输入不符合skill预期格式	检查输入是否符合skill使用说明中的格式要求，参考示例章节
执行结果与预期不符	指令描述不够明确或上下文不足	提供更详细的指令描述，补充必要的上下文信息
命令执行失败	运行环境不满足要求或权限不足	确认运行环境符合依赖说明中的要求；检查命令权限设置

创新亮点

效率提升量化分析

操作步骤	手动耗时	自动化耗时	时间节约	准确率提升
CDN配置部署	1 小时	5 分钟	55 分钟	100%
缓存策略优化	2 小时	15 分钟	1.5 小时	95%
安全加固设置	30 分钟	10 分钟	20 分钟	98%
性能调优	2 小时	30 分钟	1.5 小时	90%
故障排障	2 小时	30 分钟	1.5 小时	95%

差异化对比

对比维度	本技能	手动操作	Python脚本	专业软件
易用性	高	低	中	高
功能全面性	高	低	中	高
自动化程度	高	低	中	高
成本	低	中	高	高
维护难度	低	高	中	高

核心痛点解决

痛点	描述	影响范围	解决方案	量化效果
配置复杂	CDN配置复杂，手动操作容易出错	影响网站性能和用户体验	提供自动化配置工具，降低配置难度	减少配置错误 90%
安全风险	缺乏安全防护，容易受到攻击	影响网站安全	提供安全加固功能，降低安全风险	降低安全事件 80%
性能瓶颈	缓存策略不当，导致性能瓶颈	影响网站访问速度	提供缓存策略优化工具，提升网站性能	提升访问速度 30%

主要功能

自动化执行: 配置优化排障CDN部署,缓存策略+安全加固,加速又稳。Configure, optimize, and troubles
文件处理: 支持多种文件格式的读取、解析和写入操作
API集成: 通过标准化接口调用外部服务并处理响应
命令执行: 在安全沙箱中执行系统命令并收集结果
信息检索: 快速搜索和过滤目标数据

故障处理体系

针对CDN内容分发管理工具使用中可能遇到的常见问题,提供以下排查方案:

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置,确认代理设置