快速开始
1. 创建 Cloudflare API 令牌
文档中的 Cloudflare 控制台配图使用中文界面。如果你的控制台显示英文，可以按照下面给出的中英文菜单名称操作。
1.1 使用 Workers 编辑模板
- 打开 Cloudflare 的 API 令牌页面。
- 点击“创建令牌”（
Create Token）。 - 找到“编辑 Cloudflare Workers”（
Edit Cloudflare Workers）模板。 - 点击该模板右侧的“使用模板”（
Use template）。
这个模板会预先加入部署 Worker 所需的基础权限。不要选择只读模板，否则 GitHub Actions 无法创建或更新 Worker。
1.2 添加 D1 数据库编辑权限
在模板的权限列表中，点击“添加更多”（Add more），新增一条权限：
| 范围 | 服务 | 权限级别 |
|---|---|---|
账户（Account） | D1 | 编辑（Edit） |
也就是在三个下拉框中依次选择 Account -> D1 -> Edit。中文界面通常显示为“账户 -> D1 -> 编辑”。
注意
这里只需要创建一个 API Token。“添加 D1 权限”是给当前 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
复制时不要带引号、前后空格或换行。如果 Token 丢失，Cloudflare 无法再次显示原值，只能重新创建。
1.4 复制账户 ID
进入要部署 EdgeChat 的 Cloudflare 账户，在账户首页或 Workers & Pages 概览中找到“账户 ID”（Account ID），然后复制它。
账户 ID 通常是一个 32 位十六进制字符串，只包含数字 0-9 和字母 a-f，格式大致如下：
0123456789abcdef0123456789abcdef
将这个值保存为 GitHub Repository Secret：
CLOUDFLARE_ACCOUNT_ID不要把账户 ID 与域名的 Zone ID 混淆。自动部署需要的是账户级的 Account ID。
2. 准备仓库
Fork 或克隆此仓库到你的 GitHub 账号：
3. 配置必需项
下面这 4 个配置是自动部署的核心：
| 配置项 | 作用 | 是否必需 |
|---|---|---|
CLOUDFLARE_API_TOKEN | 让 GitHub Actions 调用 Cloudflare API，完成资源检查和部署。 | 必需 |
CLOUDFLARE_ACCOUNT_ID | 指定要部署到哪个 Cloudflare 账号。 | 必需 |
CFCHAT_ADMIN_USERNAME | 首次部署时自动创建的管理员用户名。 | 必需 |
CFCHAT_ADMIN_PASSWORD | 首次部署时自动创建的管理员密码。 | 必需 |
4. 进入自动部署
- Fork 或克隆仓库到你的 GitHub 账号
- 到仓库
Settings -> Secrets and variables -> Actions添加上面 4 个 Secrets - 推送到
main或master - 或者在 Actions 页面手动触发
workflow_dispatch
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 自动部署。