EdgeChat 详细部署教程

EdgeChat 是一个基于 Cloudflare 全家桶（Workers + D1 + R2 + KV）的现代团队聊天系统，支持公开/私有群组、私信、实时消息、文件上传和管理后台。本教程将引导你完成从零开始的全流程部署。

一、部署前准备

1.1 必备资源

  • Cloudflare 账号（免费套餐即可）
  • GitHub 账号（用于自动部署）
  • 域名（可选，用于绑定自定义域名）
  • Node.js 环境（用于本地开发和手动部署）

1.2 Cloudflare 服务开通

在 Cloudflare Dashboard 中依次开通以下服务：

  1. Workers & Pages - 主计算服务
  2. D1 数据库 - 存储用户、消息、群组等数据
  3. R2 对象存储 - 存储文件上传和头像
  4. KV 存储 - 用于会话缓存和临时数据

二、部署方式选择

EdgeChat 支持三种部署方式，推荐优先使用 GitHub Actions 自动部署。

部署方式 适用场景 维护复杂度
GitHub Actions（推荐） 生产环境、长期维护 低（推送即部署）
本地手动部署 开发测试、快速验证 中
Docker 本地部署 本地模拟、离线测试 中

三、GitHub Actions 自动部署（推荐）

3.1 Fork 仓库

  1. 访问 EdgeChat 项目主页
  2. 点击右上角 Fork，将仓库复制到你的 GitHub 账号下

3.2 配置 Cloudflare API 凭证

在你的 GitHub 仓库设置中添加以下 Secrets（路径：Settings → Secrets and variables → Actions）：

Secret 名称 说明 获取方式
CLOUDFLARE_API_TOKEN Cloudflare API 令牌 Cloudflare Dashboard → 我的个人资料 → API 令牌 → 创建令牌（选择“编辑 Cloudflare Workers”模板）
CLOUDFLARE_ACCOUNT_ID Cloudflare 账户 ID Cloudflare Dashboard 右侧“账户 ID”

3.3 （可选）配置加密密钥

系统使用 AES-256-GCM 对消息和附件进行服务端加密。如需自定义密钥，创建 Repository Secret EDGECHAT_ENCRYPTION_KEYRING：

1
{"activeKeyId":"v1","keys":{"v1":"BASE64_ENCODED_32_BYTE_KEY"}}

注意：首次部署时若未提供，系统会自动生成随机密钥并长期使用。服务端加密不是端到端加密，Worker 运行环境和部署方仍位于信任边界内。

3.4 触发部署

  • 自动触发：推送代码到 master 或 main 分支
  • 手动触发：进入 Actions 页面，选择 Deploy Worker 工作流，点击 Run workflow

部署完成后，Cloudflare Worker 会分配一个 *.workers.dev 域名，可以直接访问使用。

四、本地手动部署

4.1 克隆代码并安装依赖

1
2
3
4
5
6
# 克隆你的 Fork 仓库
git clone https://github.com/你的用户名/Edgechat.git
cd Edgechat

# 安装依赖
npm install

4.2 配置 Cloudflare 凭证

在项目根目录创建 .env 文件（或设置环境变量）：

1
2
CLOUDFLARE_API_TOKEN=你的API令牌
CLOUDFLARE_ACCOUNT_ID=你的账户ID

4.3 初始化 D1 数据库

1
2
3
4
# 创建 D1 数据库（在 Cloudflare 控制台或通过 Wrangler）
npx wrangler d1 create edgechat-db

# 将输出的 database_id 和 database_name 填入 wrangler.toml

在 wrangler.toml 中配置 D1 绑定：

1
2
3
4
[[d1_databases]]
binding = "DB"
database_name = "edgechat-db"
database_id = "你的数据库ID"

4.4 创建 R2 存储桶

1
2
# 创建 R2 存储桶
npx wrangler r2 bucket create edgechat-uploads

在 wrangler.toml 中添加 R2 绑定：

1
2
3
[[r2_buckets]]
binding = "BUCKET"
bucket_name = "edgechat-uploads"

4.5 执行数据库迁移

1
2
3
4
# 应用数据库表结构（首次部署）
npx wrangler d1 execute edgechat-db --file=./worker/schema.sql

# 如需增量迁移，执行 migrations/ 目录下的文件

4.6 构建并部署

1
2
3
4
5
# 构建前端资源
npm run build

# 部署到 Cloudflare Workers
npm run deploy

五、Docker 本地部署（开发/测试）

项目提供了 Docker 支持，适合在本地环境中快速启动完整服务。

5.1 使用 Docker Compose

1
2
3
4
5
# 启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f

5.2 手动 Docker 构建

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

# 运行容器（需要配置环境变量）
docker run -p 8787:8787 \
  -e CLOUDFLARE_API_TOKEN=你的令牌 \
  -e CLOUDFLARE_ACCOUNT_ID=你的账户ID \
  edgechat

详细 Docker 配置参考项目根目录的 DOCKER.md 文件。

六、部署后配置

6.1 首次访问设置

  1. 访问分配的 Worker URL（如 https://你的子域名.workers.dev）
  2. 系统默认无用户，需通过 管理后台 创建第一个管理员用户
  3. 管理后台地址通常为 /admin（具体路径查看部署后提示）

6.2 管理员后台操作

  • 用户管理：创建用户、设置角色、启用/封禁账号（支持永久或定时封禁）
  • 群组管理：创建公开/私有群组
  • 邀请注册：生成注册邀请链接（系统不开放自助注册）
  • 网站设置：自定义站点名称、Logo 等

6.3 绑定自定义域名（可选）

  1. 在 Cloudflare Dashboard → Workers → 你的 Worker → 触发器
  2. 添加自定义域名（需在 Cloudflare DNS 中已解析）
  3. 配置 SSL/TLS 证书（Cloudflare 自动提供）

七、高级功能：Telegram 双向桥接

EdgeChat 支持与 Telegram 群组双向消息同步，实现跨平台聊天。

7.1 准备工作

  • 一个 Telegram Bot Token（通过 @BotFather 创建）
  • Telegram 群组 ID（将 Bot 加入群组后获取）

7.2 在管理后台配置

  1. 进入管理后台 → 群组设置
  2. 选择要绑定的 EdgeChat 群组
  3. 填写 Telegram Bot Token 和群组 ID
  4. 保存后，两侧消息自动实时同步

消息同步是双向的：EdgeChat 成员消息 → Telegram 群组，Telegram 群组消息 → EdgeChat 群组。

八、常见问题与维护

Q1：部署失败，提示 D1 或 R2 未绑定

  • 确认在 Cloudflare Dashboard 中已创建 D1 数据库和 R2 存储桶
  • 检查 wrangler.toml 中的 database_id 和 bucket_name 是否正确

Q2：文件上传失败

  • 检查 R2 存储桶权限和 CORS 配置
  • 确认 Worker 绑定的 R2 存储桶名称与配置文件一致

Q3：如何更新部署？

  • GitHub Actions：推送代码到主分支或手动触发工作流
  • 手动部署：拉取最新代码 → npm run build → npm run deploy

Q4：如何备份数据？

  • D1 数据库：使用 wrangler d1 export 命令导出
  • R2 文件：使用 R2 控制台或 S3 兼容工具同步

九、项目结构与扩展

EdgeChat 的核心代码结构清晰，便于二次开发：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
edgechat/
├── frontend/         # Vue 3 前端源码
│   ├── src/
│   │   ├── api.js    # API 调用封装
│   │   ├── store.js  # Pinia 状态管理
│   │   ├── ws.js     # WebSocket 实时消息
│   │   └── pages/    # 页面组件
├── worker/           # Cloudflare Worker 后端
│   ├── src/
│   │   ├── api/      # REST API 路由
│   │   ├── do/       # Durable Objects（实时会话）
│   │   ├── auth.js   # 认证逻辑
│   │   └── db.js     # D1 数据库操作
│   └── schema.sql    # 数据库表结构
└── wrangler.toml     # Cloudflare 配置文件

十、参考资源

通过以上步骤，你可以在 Cloudflare 免费额度内快速部署一个功能完整的团队聊天系统，无需管理服务器，数据完全归属自己。如需进一步定制或遇到问题，可查阅官方文档或在 GitHub 提交 Issue。