0 Fork 0

mirror of https://github.com/Vb-Lg/class-history-template.git synced 2026-11-03 17:36:47 +00:00

Table of Contents

cms-bot 使用教程

一、创建 App

创建步骤

二、拿到三样凭据
三、配置 Cloudflare Pages
四、验证
常见问题
安全须知

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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 归创建它的账号/组织所有——建议在自己的账号（或组织）下创建，私钥不假人手。

创建步骤

打开 GitHub → 头像 → Settings → Developer settings → GitHub Apps → New GitHub App。（组织仓库也可以在组织 Settings → Developer settings 里建，让 App 归组织所有。）
按下表填写，然后点页面底部 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）：

App ID：页面「About」区，纯数字。
私钥：底部 Private keys → Generate a private key，自动下载 .pem 文件；用文本编辑器打开，全文（含 BEGIN/END 行）即 GITHUB_PRIVATE_KEY。
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 的环境变量总表。

四、验证

打开线上站点「📝 投稿」页，填一篇测试投稿提交；
出现「✅ 已创建 PR #N」并附链接即成功；
仓库 Pull requests 里应有一条由 cms-bot 发起的 PR（自动带标签）；
合并后 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 两项权限，不要多开。

班史模板 · 文档

仓库 · Issues

class-history-template · 有问题欢迎提 Issue