EdgeChat 部署教程：在 Cloudflare 上搭建团队聊天系统

EdgeChat 是一个构建在 Cloudflare Workers 之上的开源团队聊天系统，利用 Durable Objects 实现实时 WebSocket 通信，D1 存储数据，R2 存储文件。它提供账号体系、群组/私聊、文件上传、管理后台，甚至支持与 Telegram 双向桥接。由于完全运行在 Cloudflare 生态中，大部分场景下可以运行在免费额度内，无需自己维护服务器。

⚙️ 核心依赖与免费额度

EdgeChat 充分利用了 Cloudflare 的 serverless 服务栈，这也是它能做到低成本运维的关键：

组件 作用 Cloudflare 免费额度
Workers 运行应用的核心计算环境 每日 10 万次请求
Durable Objects 管理 WebSocket 连接与房间状态 包含在 Workers 免费计划中
D1 存储用户、消息等结构化数据 5 GB 存储空间
R2 存储文件、头像等对象 10 GB 存储空间 / 每月
KV 缓存会话等轻量数据 1 GB 存储空间

对于个人或小团队而言，这些免费额度通常足够使用。

📦 方案一：GitHub Actions 自动部署（推荐）

这是官方推荐的方式，能实现“一键部署”，非常适合长期维护和生产环境。

1. 准备 Cloudflare 资源

  1. Fork 仓库：将 aozorae/Edgechat 仓库 Fork 到你的 GitHub 账号下。
  2. 准备 Cloudflare 账号：你需要一个 Cloudflare 账号，并激活 R2 服务（在 Cloudflare Dashboard 的 R2 页面按指引操作，通常需要绑定支付方式，但免费额度足够，基本不会产生费用）。
  3. 创建 API 令牌：
    • 进入 Cloudflare Dashboard → 右下角头像 → 我的个人资料 → API 令牌。
    • 点击 创建令牌，选择 编辑 Cloudflare Workers 模板。
    • 在“账户权限”和“区域权限”中，确保授予对 Workers、D1、R2 和 KV 的读写权限。
    • 创建并复制生成的 API 令牌。

2. 配置 GitHub Secrets

在你 Fork 的仓库中，进入 Settings → Secrets and variables → Actions，点击 New repository secret，依次添加以下四个关键变量：

  • CLOUDFLARE_API_TOKEN：上一步复制的 API 令牌。
  • CLOUDFLARE_ACCOUNT_ID：你的 Cloudflare 账户 ID（在 Workers 概览页右侧可以找到）。
  • CFCHAT_ADMIN_USERNAME：首次部署时自动创建的管理员用户名。
  • CFCHAT_ADMIN_PASSWORD：首次部署时自动创建的管理员密码。

3. 触发部署

  1. 在你的仓库中，点击上方的 Actions 标签页。
  2. 在左侧边栏中找到并点击 Deploy Worker 工作流。
  3. 点击右侧的 Run workflow 下拉按钮，选择分支（通常是 master 或 main），然后点击 Run workflow。

工作流运行成功后（约几分钟），你可以在 Cloudflare Dashboard 的 Workers 部分找到名为 edgechat 的服务，访问其分配的 *.workers.dev 域名即可使用。

4. (可选) 服务端加密

部署工作流会自动处理消息和附件的 AES-256-GCM 服务端加密。你可以通过设置 GitHub Secret EDGECHAT_ENCRYPTION_KEYRING 来手动指定密钥，或通过工作流的 rotate_encryption_key 选项进行密钥轮换。

📦 方案二：手动部署 / 本地开发

如果你希望更精细地控制或进行二次开发，可以按照以下步骤操作。

1. 环境要求

  • Node.js 20+
  • Wrangler CLI：Cloudflare Workers 官方命令行工具，npm install -g wrangler。
  • 使用 wrangler login 进行身份验证。

2. 克隆与安装

1
2
3
git clone https://github.com/aozorae/Edgechat.git
cd Edgechat
npm install

3. 资源准备与配置

在部署前，需要先在 Cloudflare 上创建所需的资源，并更新 wrangler.toml 中的绑定配置：

  • 创建 D1 数据库：wrangler d1 create cfchat-db
  • 创建 R2 Bucket：wrangler r2 bucket create cfchat-files
  • 创建 KV Namespace：wrangler kv:namespace create SESSIONS
  • 将上述命令输出的资源 ID，填入 wrangler.toml 文件对应的 [[d1_databases]]、[[r2_buckets]] 和 [[kv_namespaces]] 部分。

4. 本地开发与部署

  • 前端开发（热重载）：npm run dev:frontend
  • 本地构建：npm run build
  • 手动部署：npm run deploy（部署前需确保环境变量如 CLOUDFLARE_API_TOKEN 已正确设置）

🐳 方案三：Docker 本地运行

如果你希望在本地容器环境中测试，项目提供了 Dockerfile。

1
2
3
4
5
# 构建镜像
docker build -t edgechat .

# 运行容器（映射到本地端口 8787）
docker run -p 8787:8787 edgechat

这会在 http://localhost:8787 启动服务，但需要注意，这主要用于本地开发测试，生产环境仍建议部署到 Cloudflare Workers。

📝 首次登录与基础配置

  1. 访问部署好的 EdgeChat 实例 URL（例如 https://edgechat.你的用户名.workers.dev）。
  2. 如果使用 GitHub Actions 部署，使用你在 Secrets 中设置的 CFCHAT_ADMIN_USERNAME 和 CFCHAT_ADMIN_PASSWORD 登录。
  3. 登录后，即可在管理后台创建群组、邀请用户，或配置 Telegram 桥接功能。

🩺 常见问题与排障

  • 访问返回 403/404：检查 wrangler.toml 中的 Worker 名称和 compatibility_date 是否与 Cloudflare Dashboard 信息一致，并确认 D1、R2、KV 的绑定名称准确无误。
  • 文件上传失败：确认 R2 Bucket 已正确创建，且 GitHub Secrets 或 wrangler.toml 中的 Bucket 名称完全匹配。
  • WebSocket 连接不稳定：Durable Objects 实例偶尔可能因节点维护而重建。可以在 Cloudflare Dashboard 的 Durable Objects 部分查看实例状态。这是正常现象，客户端会自动重连。
  • 国内访问慢：可以为 Worker 绑定自定义域名，并将该域名通过 Cloudflare CDN 加速，这能显著改善国内访问体验。

EdgeChat 利用 Cloudflare 的生态，提供了一个低门槛、易维护的现代化聊天方案。它很适合于小型团队、兴趣小组，或是需要将内部沟通与 Telegram 社区打通的场景。部署完成后，你就可以开始创建你的专属聊天空间了。