CMS Bot

cms-bot 使用教程

cms-bot 是本模板的投稿机器人——一个 GitHub App。访客在「📝 投稿」「🎵 投稿音乐」页面提交表单后，你的 Cloudflare Pages Function 会以 cms-bot 的身份在仓库里创建分支并发起 Pull Request；你审核合并后，Pages 自动重新构建，内容上线。

表单提交 → /api/submit（Pages Function）
        → 以 cms-bot 身份建分支 chronicle/* 或 music/*
        → 自动开 PR → 管理员合并 → 站点自动更新

由 cms-bot 发起的 PR 会自动打上「班史投稿」/「音乐投稿」标签（.github/labeler.yml）。

一、创建 App

GitHub App 名字全局唯一，cms-bot 若被占用就换一个（如 xx-class-cms-bot）。 App 归创建它的账号/组织所有——建议在自己的账号（或组织）下创建，私钥不假人手。

创建步骤

1. 打开 GitHub → 头像 → Settings → Developer settings → GitHub Apps → New GitHub App。 （组织仓库也可以在组织 Settings → Developer settings 里建，让 App 归组织所有。）
2. 按下表填写，然后点页面底部 Create GitHub App：

字段	填写
GitHub App name	cms-bot
Homepage URL	你的仓库地址
Webhook → Active	取消勾选：本模板只用 REST API，不需要 webhook
Repository permissions → Contents	Read and write
Repository permissions → Pull requests	Read and write
Where can this GitHub App be installed	Any account（= 公开，任何仓库都能安装）

其余权限保持默认（No access）即可。

二、拿到三样凭据

创建完成后，在 App 设置页（Settings → Developer settings → GitHub Apps → cms-bot）：

1. App ID：页面「About」区，纯数字。
2. 私钥：底部 Private keys → Generate a private key，自动下载 .pem 文件；用文本编辑器打开，全文（含 BEGIN/END 行）即 GITHUB_PRIVATE_KEY。
3. Installation ID：左侧 Install App → Install → 选你的仓库；安装页 URL https://github.com/settings/installations/<数字> 中的数字即 Installation ID。

三、配置 Cloudflare Pages

Pages 项目 → Settings → Variables and Secrets（Production 与 Preview 都加）：

变量	值
GITHUB_APP_ID	App ID
GITHUB_INSTALLATION_ID	Installation ID
GITHUB_PRIVATE_KEY	.pem 私钥全文
GITHUB_OWNER	仓库所有者（用户名或组织名）
GITHUB_REPO	仓库名

可选覆盖项见 Deployment 的环境变量总表。

四、验证

1. 打开线上站点「📝 投稿」页，填一篇测试投稿提交；
2. 出现「✅ 已创建 PR #N」并附链接即成功；
3. 仓库 Pull requests 里应有一条由 cms-bot 发起的 PR（自动带标签）；
4. 合并后 Pages 自动重建，内容出现在「📖 班史列表」。

常见问题

现象	原因 / 处理
installation token failed	App ID / 私钥 / Installation ID 不匹配，或 App 没安装到该仓库
分支不存在: main	GITHUB_BASE_BRANCH 与仓库默认分支不一致
PR 创建成功但站点没更新	Pages 构建失败或未触发，看 Cloudflare 部署日志
提交报「服务异常」	看 Pages 的 Functions 日志（Deployment → Functions logs）
想改投稿目标目录	配 CONTENT_DIR / SONGS_DIR / MEDIA_DIR 等变量

安全须知

• .pem 私钥 = bot 的完整身份：只存在 Cloudflare 环境变量里，不要提交进仓库、发群里、写进 wiki。
• 因此每个独立部署的班级都建议创建自己的 App（按上面步骤约 5 分钟），而不是共用同一个 cms-bot 的私钥——谁拿到私钥，就能以 bot 身份写入它安装过的所有仓库。
• bot 只需要 Contents 和 Pull requests 两项权限，不要多开。