GitHub Secrets 配置

部署工作流只读 GitHub Secrets，不读 Variables。添加位置：仓库 Settings → Secrets and variables → Actions → Secrets → New repository secret。

一定要加在 Secrets 标签，加到 Variables 不会生效
名称区分大小写（必须是 R2_MEDIA_BUCKET，不是 r2_media_bucket）
值只填内容，不要写 NAME=...，一般不要加引号
保存后无法再次查看原值，只能重新设置
改完任何 Secret 都必须重新运行一次部署工作流——Secret 的修改不会自动同步到已部署的 Worker

必填项

这四项缺一个，部署就会直接停止。

CLOUDFLARE_API_TOKEN

登录 Cloudflare Dashboard
右上角头像 → My Profile → API Tokens
Create Token → Custom token
配置权限：

资源	权限	为什么
Account > Workers Scripts	Edit	部署 Worker
Account > D1	Edit	部署前执行 D1 迁移
Account > Workers KV Storage	Edit	部署 KV 绑定
Zone > Cache Purge	Purge（可选）	配合 `CF_ZONE_ID` 实现「发布即清缓存」

Create Token → 复制（仅显示一次）

格式：普通令牌字符串。

这个 Token 有两个用途：一是给 GitHub Actions 里的 wrangler 部署与 D1 迁移用；二是工作流会把它自动写成 Worker 的运行时 Secret CF_API_TOKEN，供 Worker 调 Cloudflare Cache Purge 接口清边缘缓存。所以如果想让「发布即清缓存」生效，权限里要勾上 Zone > Cache Purge。

CLOUDFLARE_ACCOUNT_ID

登录 Cloudflare Dashboard
选择任意域名（或看地址栏）
右侧栏 → API → Account ID
复制 UUID 格式的 ID

格式：32 位十六进制（如 a1b2c3d4e5f678901234567890abcdef）。

BLOG_D1_ID

npx wrangler d1 create blog

输出示例：

✅ Successfully created DB 'blog'
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

复制 database_id 的值。格式：UUID（带横线），例如 0fa366ac-f04a-4be2-8e11-5adc6ee6d686。

这个值不是数据库名（不是 blog），也不是 KV 的 id。工作流会做格式校验：去掉横线后必须是 32 位十六进制，否则直接报错中止。

BLOG_KV_ID

npx wrangler kv namespace create BLOG

输出示例：

✅ Successfully created KV namespace 'BLOG'
id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

复制 id 的值。格式：32 位十六进制（不含横线）。工作流同样会校验格式（长度必须是 32，字符只能是 0-9a-f），格式不对就直接报错中止。

可选项

CF_ZONE_ID

自定义域名所在 Cloudflare Zone 的 ID。控制台 → 选中你的域名 → 右侧栏 API → Zone ID。格式：32 位十六进制。配置后与 CF_API_TOKEN（工作流自动写入）配合，文章增删改时按 Cache-Tag 清除边缘缓存（posts / feed / sitemap / post:<id> / stats:<id>）。按标签清除在 Free / Pro / Business / Enterprise 都可用（免费版 5 次/分钟、单次最多 100 个操作），详见 Cloudflare 缓存清除文档。不配置则依赖 s-maxage 自然过期，功能不受影响。

PAGES_PROJECT_NAME

名字有误导性：这个 Secret 实际的作用是覆盖 Worker 名称（部署命令追加 --name <值>），与 Pages 无关。不填则使用 wrangler.workers.toml 里的 kejiland。随意改名会部署出一个新的 Worker（域名 / 绑定都要重新配），新手建议不填。

格式：Worker 名称（字母 / 数字 / 连字符）。

BLOG_WRITE_TOKEN

旧式静态写入令牌。现在的写操作走会话 token（Authorization: Bearer <session-token>），BLOG_WRITE_TOKEN 仅作为兼容保留。新部署不需要。

BLOG_RATE_LIMIT_BINDING

一个正整数（如 1001），作为 Workers Rate Limiting 绑定的 namespace_id。配置后会连锁触发两件事：

部署工作流改用 wrangler@^4.36.0（该绑定要求 ≥ 4.36）
向部署配置注入：

[[ratelimits]]
name = "LOGIN_LIMITER"
namespace_id = "1001"
  [ratelimits.simple]
  limit = 10
  period = 60

效果：登录接口在 Worker 入口按 IP 限流 10 次/分钟/位置，被拦下的请求不查库、不写库、不跑 PBKDF2。

情况	表现
不配置	行为与旧版完全一致：代码检测不到 `env.LOGIN_LIMITER` 就回退到 D1 计数
填了非数字	工作流直接报错中止（必须是正整数）
账户 / 套餐不支持	部署会失败；删掉这个 Secret 重新部署即恢复

详细的三层限流阈值与应急通道见安全设计；三种边缘加固方案（Cloudflare Access / WAF 限流规则 / 本绑定）见 Cloudflare Workers 部署。

邮件订阅（可选）

Resend 相关变量四项齐全（RESEND_API_KEY、BLOG_MAIL_FROM、SITE_URL 为启用条件；BLOG_MAIL_REPLY_TO 可选）后，订阅、新文章通知、评论通知与群发邮件才可用。

Secret	必填	说明
`RESEND_API_KEY`	可选	Resend API Key
`BLOG_MAIL_FROM`	可选	发件人地址，域名需在 Resend 验证
`BLOG_MAIL_REPLY_TO`	可选	回信地址
`BLOG_ADMIN_EMAIL`	可选	新评论通知收件邮箱；不填回退到「个人资料 → 邮箱」

内容、评论与 AI 开关（可选）

Secret	说明
`COMMENT_BLOCKLIST`	评论敏感词，换行或逗号分隔；优先级高于后台词库
`BLOG_PREVIEW_SECRET`	草稿预览链接 HMAC 签名密钥；不填由管理员密码哈希派生，改密码会让所有旧链接失效
`BLOG_AI_ENABLED`	`0` / `false` / `off` 整体关闭 AI；不填 = 有绑定就开启
`BLOG_AI_PUBLIC`	`0` / `false` / `off` 禁止匿名生成摘要；登录后仍可用

以上四项均由部署工作流在非空时自动写入 Worker，不需要再手动执行 wrangler secret put。

R2 存储（可选，8 个变量）

音乐与图片共用同一组凭据（代码只读取 R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY），所以这对凭据必须同时有权限访问两个桶。

Secret	填什么	格式
`R2_ACCESS_KEY_ID`	R2 API Token 的 Access Key ID	普通字符串
`R2_SECRET_ACCESS_KEY`	R2 API Token 的 Secret Access Key（只显示一次）	普通字符串
`R2_ENDPOINT`	`https://<账户ID>.r2.cloudflarestorage.com`	不带桶名、末尾不加 `/`、不是公开域名
`R2_BUCKET`	音乐桶名，如 `qingyu-music`	桶名
`R2_PUBLIC_BASE`	音乐桶公开域名，如 `https://music.example.com`	`https://` 开头，末尾不加 `/`
`R2_MEDIA_BUCKET`	媒体桶名，如 `qingyu-media`	桶名
`R2_MEDIA_PUBLIC_BASE`	媒体桶公开域名，如 `https://media.example.com`	`https://` 开头，末尾不加 `/`
`R2_BACKUP_BUCKET`	私有备份桶名；保存自动 / 手动备份 JSON，建议不要绑定公开域名。不填则备份与恢复功能停用	桶名

R2 凭据、Endpoint 与桶名是分组生效的：音乐配置需要 R2_BUCKET；媒体配置需要 R2_MEDIA_BUCKET；备份配置需要 R2_BACKUP_BUCKET。若只配媒体桶，图片上传可用；音乐桶不完整时，音乐上传会回退到媒体桶。要让音乐 / 媒体 / 备份彼此隔离，请分别配置三个桶与公开域名（备份桶不要绑定公开域名）。

音乐桶的判定逻辑（代码层面）：

音乐上传目标 = （R2_BUCKET 和 R2_PUBLIC_BASE 都非空）? 音乐桶 : 媒体桶

也就是说：只要音乐桶的两个变量有一个为空，音乐就会自动落到媒体桶。发现音乐传到了媒体桶，先检查 R2_BUCKET / R2_PUBLIC_BASE 是否漏填。

由工作流自动写入的运行时变量

下面这个不是你填的 GitHub Secret，但很容易和上面的表混淆：

运行时变量	谁写入	作用	没有时
`CF_API_TOKEN`	工作流自动写入（值取 `CLOUDFLARE_API_TOKEN`）	文章增删改后调 Cache Purge 接口清边缘缓存	不做缓存清除，新内容可能延迟 1~5 分钟生效

BLOG_AI_ENABLED / BLOG_AI_PUBLIC、BLOG_ADMIN_EMAIL、COMMENT_BLOCKLIST、BLOG_PREVIEW_SECRET 与 R2 / Resend 相关变量都由工作流在非空时写入，不再需要手工 wrangler secret put。

配置步骤

进入 GitHub 仓库 → Settings
Secrets and variables → Actions → Secrets 标签
New repository secret → 填入 Name 和 Value
重复添加所有 Secret
重新运行一次部署工作流，让运行时 Secret 生效

指南

部署

API 参考

数据库

安全

功能参考

贡献

更新日志

必填项

CLOUDFLARE_API_TOKEN

CLOUDFLARE_ACCOUNT_ID

BLOG_D1_ID

BLOG_KV_ID

推荐项

BLOG_ADMIN_SETUP_KEY

SITE_URL

可选项

CF_ZONE_ID

PAGES_PROJECT_NAME

BLOG_WRITE_TOKEN

BLOG_RATE_LIMIT_BINDING

邮件订阅（可选）

内容、评论与 AI 开关（可选）

R2 存储（可选，8 个变量）

由工作流自动写入的运行时变量

配置步骤

延伸阅读

​必填项

​CLOUDFLARE_API_TOKEN

​CLOUDFLARE_ACCOUNT_ID

​BLOG_D1_ID

​BLOG_KV_ID

​推荐项

​BLOG_ADMIN_SETUP_KEY

​SITE_URL

​可选项

​CF_ZONE_ID

​PAGES_PROJECT_NAME

​BLOG_WRITE_TOKEN

​BLOG_RATE_LIMIT_BINDING

​邮件订阅（可选）

​内容、评论与 AI 开关（可选）

​R2 存储（可选，8 个变量）

​由工作流自动写入的运行时变量

​配置步骤

​延伸阅读

必填项

CLOUDFLARE_API_TOKEN

CLOUDFLARE_ACCOUNT_ID

BLOG_D1_ID

BLOG_KV_ID

推荐项

BLOG_ADMIN_SETUP_KEY

SITE_URL

可选项

CF_ZONE_ID

PAGES_PROJECT_NAME

BLOG_WRITE_TOKEN

BLOG_RATE_LIMIT_BINDING

邮件订阅（可选）

内容、评论与 AI 开关（可选）

R2 存储（可选，8 个变量）

由工作流自动写入的运行时变量

配置步骤

延伸阅读