快速开始

1. 创建 Cloudflare API 令牌

文档中的 Cloudflare 控制台配图使用中文界面。如果你的控制台显示英文，可以按照下面给出的中英文菜单名称操作。

1.1 使用 Workers 编辑模板

1. 打开 Cloudflare 的 API 令牌页面。
2. 点击“创建令牌”（Create Token）。
3. 找到“编辑 Cloudflare Workers”（Edit Cloudflare Workers）模板。
4. 点击该模板右侧的“使用模板”（Use template）。

这个模板会预先加入部署 Worker 所需的基础权限。不要选择只读模板，否则 GitHub Actions 无法创建或更新 Worker。

1.2 核对并补齐编辑权限

Cloudflare 会随控制台版本调整模板自带的权限。不要按截图里的行数照抄；请以最终权限摘要为准，确保同一个 Token 包含下面 4 项：

服务	权限级别
Workers Scripts	编辑（Edit）
D1	编辑（Edit）
Workers KV Storage	编辑（Edit）
R2	编辑（Edit）

先检查“编辑 Cloudflare Workers”模板已经包含哪些项目，再点击“添加更多”（Add more）补齐缺少的 D1、Workers KV Storage 或 R2 权限；模板以后若已经包含某一项，不要重复添加。

当前 GitHub Action 的 CI 配置没有 Workers Routes，因此不需要 Workers Routes Write。定时清理使用的 Cron Trigger 随 Worker 脚本一同部署，Cloudflare 也没有名为 Cron Triggers 的独立 API Token 权限。只有你自行在 CI 配置中添加自定义域名 routes 时，才需要为对应 Zone 增加 Workers Routes Write。

注意

这里只需要创建一个 API Token。补充权限是给当前 Token 新增权限行，不是再创建第二个 Token。

在“账户资源”（Account Resources）中选择：

• 包含（Include）
• 指定账户（Specific account）
• 选择准备部署 EdgeChat 的 Cloudflare 账户

如果页面提供客户端 IP 地址过滤或令牌有效期设置，可以保持默认值。确认权限摘要无误后，点击“继续以显示摘要”（Continue to summary），再点击“创建令牌”（Create Token）。

1.3 复制并保存 API Token

Cloudflare 只会完整显示一次新 Token。立即复制页面中的 Token，并把它保存为 GitHub Repository Secret：

CLOUDFLARE_API_TOKEN

截图中的账号 ID 和 Token 已脱敏。EdgeChat 只需要 CLOUDFLARE_API_TOKEN，不需要结果窗口下方的 S3 访问密钥。

复制时不要带引号、前后空格或换行。如果 Token 丢失，Cloudflare 无法再次显示原值，只能重新创建。

1.4 复制账户 ID

进入要部署 EdgeChat 的 Cloudflare 账户，在账户首页或 Workers & Pages 概览中找到“账户 ID”（Account ID），然后复制它。

账户 ID 通常是一个 32 位十六进制字符串，只包含数字 0-9 和字母 a-f，格式大致如下：

0123456789abcdef0123456789abcdef

新版控制台通常会在 Token 创建结果窗口同时显示账户 ID；如果没有显示，也可以从账户首页或 Workers & Pages 概览复制。

将这个值保存为 GitHub Repository Secret：

CLOUDFLARE_ACCOUNT_ID

不要把账户 ID 与域名的 Zone ID 混淆。自动部署需要的是账户级的 Account ID。

2. 准备仓库

Fork 或克隆此仓库到你的 GitHub 账号：

3. 配置必需项

打开仓库的 Settings -> Secrets and variables -> Actions，选择 Secrets，点击 New repository secret：

下面这 4 个配置是自动部署的核心，全部添加为 Repository secrets：

配置项	作用	是否必需
CLOUDFLARE_API_TOKEN	让 GitHub Actions 调用 Cloudflare API，完成资源检查和部署。	必需
CLOUDFLARE_ACCOUNT_ID	指定要部署到哪个 Cloudflare 账号。	必需
CFCHAT_ADMIN_USERNAME	首次部署时自动创建的管理员用户名。	必需
CFCHAT_ADMIN_PASSWORD	首次部署时自动创建的管理员密码。	必需

4. 进入自动部署

1. 打开仓库的 Actions 页面并选择 Deploy Worker
2. 点击 Run workflow
3. 选择 main 或 master 分支后确认运行
4. 以后推送到 main 或 master 也会自动触发部署

5. 工作流会自动做什么

• 安装依赖
• 构建前端
• 检查或创建 Cloudflare 资源
• 初始化 D1 数据库
• 写入管理员账号
• 首次部署自动生成并注入服务端加密密钥，后续部署保持不变
• 部署 Worker

6. 部署后检查

• 打开首页，确认站点能正常访问
• 用管理员账号登录
• 检查聊天和后台页面是否正常
• 账号已开通 R2 时，检查文件上传是否正常
• 确认管理员后台没有消息正文查看入口
• 需要 Telegram 互通时，进入“Telegram 互通”连接 Bot，并从后台列出的公开或私有群组中创建映射
• 打开“网站设置”，确认版本更新状态能够正常显示

如果 Cloudflare 账号尚未开通 R2，Actions 仍会完成部署，但不会建立 FILES binding。此时文字聊天可正常使用，上传附件会提示“当前部署没有绑定 R2，无法上传附件”，附件读取和 Telegram 文件同步也不可用。开通 R2 后重新运行部署即可自动恢复，无需手工修改 Worker 配置。

版本更新状态由管理员浏览器直接比对当前部署提交与公开 GitHub 仓库，不需要配置定时任务或额外 Secret。手动部署时，请从已经推送的干净 Git 提交执行构建，避免后台无法准确识别当前版本。

Telegram Bot Token 由管理员在后台填写，Worker 使用现有服务端加密密钥环加密后保存到 D1，不需要新增明文配置或 GitHub Secret。详细步骤见 Telegram Bridge 集成。

如果你想看更完整的流程说明，可以继续看 GitHub Actions 自动部署。