如何快速部署EdgeChat:Cloudflare Workers团队聊天系统从零到上线完全指南

原创2026-10-16 19:29:431,968 阅读

如何快速部署EdgeChat:Cloudflare Workers团队聊天系统从零到上线完全指南

EdgeChat 是一个完全运行在 Cloudflare Worker 上的现代团队聊天系统,支持实时群聊与私信、Telegram 双向桥接、语音与文件分享,并对消息和附件提供服务端加密。本文带你从零开始,走通 GitHub Actions 自动部署 和 Docker 一键启动 两条路线,几分钟内把属于自己团队的聊天空间正式上线——全程无需维护一台常驻服务器。

EdgeChat 聊天界面:Cloudflare Workers 团队聊天系统首页预览


一、EdgeChat 是什么?为什么选择它?

EdgeChat 解决了一个很具体的痛点:想拥有一个独立的聊天空间,又不想长期维护服务器、数据库和一整套运行环境。

它把应用和数据全部放在你自己的 Cloudflare 账号下,通过 GitHub Actions 自动部署和更新,天然免运维。核心能力包括:

你关心的事 EdgeChat 的做法
部署与维护 基于 Cloudflare Workers,免维护常驻服务器;支持 GitHub Actions 自动部署
成员与管理 独立账号、公开/私有群组、私信与管理后台
已有的 Telegram 群 通过 Bot 双向桥接,两侧成员各用各的习惯入口
隐私与扩展 消息与附件服务端加密,源码开放可二次开发

💡 项目本身免费开源,云服务费用取决于你的 Cloudflare 套餐与用量。

EdgeChat 管理后台仪表盘:用户管理与实例设置预览


二、部署前准备:5 分钟理清需要准备什么

无论走哪条路线,先准备好以下几样东西,能帮你少走弯路:

  • 一个 Cloudflare 账号(免费版即可起步)
  • 账号 ID 与 API Token:在 Cloudflare 后台「My Profile → API Tokens」创建一个,授予 Account: Workers、D1、KV、R2 的编辑权限
  • 源码仓库(GitHub Actions 路线需要)

EdgeChat 依赖三类 Cloudflare 资源,工作流会自动检测并创建,你无需手动逐个建:

资源 用途 绑定名
D1 数据库(消息、群组、用户) DB
KV 会话存储 SESSIONS
R2 文件 / 头像存储 FILES

这些绑定关系都定义在 wrangler.example.toml 中,部署时脚本会把它复制成实际配置并填充真实的资源 ID。


三、路线一(推荐):GitHub Actions 一键自动部署上线

这是官方最推荐的「从零到上线」方式:自动建资源、自动跑测试、自动迁移数据库、自动部署 Worker,后续更新也全靠它。

步骤 1:获取源码并 Fork

git clone https://gitcode.com/gh_mirrors/ed/Edgechat
cd Edgechat

然后把仓库 Fork / 推送到你自己的 GitHub 账号下(GitHub Actions 部署需要公开仓库)。

步骤 2:配置仓库 Secrets

进入仓库 Settings → Secrets and variables → Actions,至少添加:

  • CLOUDFLARE_API_TOKEN
  • CLOUDFLARE_ACCOUNT_ID

可选(推荐,自动创建管理员账号):

  • EDGECHAT_ADMIN_USERNAME(默认 admin)
  • EDGECHAT_ADMIN_PASSWORD
  • EDGECHAT_ADMIN_DISPLAY_NAME(默认 Administrator)

步骤 3:手动触发 Deploy Worker

在 Actions 面板选择 Deploy Worker → Run workflow。整个流程会自动完成:

  1. 安装依赖并运行 npm test
  2. 构建前端静态资源
  3. 检测并创建缺失的 D1 / KV / R2 资源
  4. 首次部署自动初始化数据库表结构与管理员账号
  5. 生成并注入服务端加密密钥
  6. 发布 Worker,得到你的专属访问地址

⚡ 之后每次向 master / main 分支推送代码改动,也会自动触发部署。工作流定义见 deploy-worker.yml。

步骤 4:打开访问地址,登录后台

部署成功后会得到一个 *.workers.dev 地址。用你配置的管理员账号登录后,即可创建群组、管理成员、开启 Telegram 桥接。

EdgeChat 与 Telegram 双向消息桥接:两个入口同一段讨论演示


四、路线二:Docker 一键本地部署(适合本地开发测试)

如果你想在本地先跑起来看看效果、或做二次开发,Docker 是最快的方式。注意:Docker 仅用于本地开发与测试,生产环境请部署到 Cloudflare Workers。

一行命令启动

EDGECHAT_ADMIN_PASSWORD='请替换为强密码' ./docker-start.sh

这个脚本会自动:

  • ✅ 构建并启动 Docker 容器
  • ✅ 初始化本地数据库表
  • ✅ 用与 GitHub Actions 相同的 PBKDF2 规则创建管理员账号
  • ✅ 显示访问信息

启动完成后,浏览器访问 http://localhost:8788 即可。

常用运维命令

docker compose ps          # 查看容器状态
docker compose logs -f      # 查看日志
docker compose restart      # 重启服务
docker compose down         # 停止服务
docker compose down -v      # 停止并清除所有本地数据

📌 本地开发数据保存在 .wrangler/state/ 目录,停止容器不会丢数据;只有 down -v 会清空。更多说明见 DOCKER.md 与 docker-start.sh。


五、可选:手动部署(Wrangler)

如果你希望完全掌控每一步,也可以在本地手动发布:

# 配置好 wrangler.toml 后
npm install
npm run deploy      # 构建前端并执行 wrangler deploy

配置以 wrangler.example.toml 为模板,把其中的 YOUR_D1_DATABASE_ID_HERE、YOUR_KV_NAMESPACE_ID_HERE 等占位符替换为你的真实资源 ID 即可。非交互环境下部署需要提前设置 CLOUDFLARE_API_TOKEN 环境变量。


六、上线后的 4 个关键配置

部署只是开始,上线后建议优先完成这几件事:

  1. 确认消息保留期:默认 7 天自动清理。修改 MESSAGE_RETENTION_DAYS(正整数,如 30)后重新部署;缩短保留期会删除更早消息,不可恢复,见 auto-update.md。
  2. 启用 Telegram 双向桥接:管理员在后台把任意 EdgeChat 群组与 Telegram 群绑定,网页与 Telegram 消息互相同步,一对一私信不进入桥接。
  3. 理解加密边界:EdgeChat 对新写入的消息正文和新上传的附件使用 AES-256-GCM 服务端静态加密。⚠️ 这是服务端加密,不是端到端加密,掌握密钥的部署方仍需要被信任。
  4. 开启语音通话(可选):配置 EDGECHAT_TURN_KEY_ID 与 EDGECHAT_TURN_API_TOKEN 两个 Secret 后,私聊才能使用 TURN 回退;未配置时仅支持 P2P。

七、常见问题排查

现象 原因 解决办法
页面提示「服务器开小差了」 数据库未初始化 重新运行 ./docker-start.sh,或手动执行初始化数据库与创建管理员步骤
端口 8788 被占用 端口映射冲突 修改 docker-compose.yml 中的 ports,如 9000:8787
容器一直重启 配置或依赖错误 docker compose logs --tail=50 查看日志定位
自动更新未生效 定时任务被禁用 在 Actions 中重新启用 Sync Upstream 工作流,见 auto-update.md

八、项目结构速览

Edgechat/
├─ assets/previews/       # 界面预览图
├─ frontend/              # Vue 3 前端(聊天界面、管理后台)
├─ worker/
│  ├─ schema.sql         # 数据库结构
│  ├─ migrations/        # 数据库迁移
│  └─ src/               # API、认证与 Durable Objects
├─ capacitor/            # 基于 Web UI 的 Android 客户端
├─ .github/workflows/     # 自动部署与 CI
├─ wrangler.example.toml  # Worker 配置模板
└─ docker-compose.yml     # Docker 编排

前端基于 Vue 3 + Vite,后端基于 Cloudflare Workers + Hono,实时通信依赖 Durable Objects,详见 README.md 技术栈说明。


九、总结

🎯 一句话总结:

  • 想要长期稳定运行 → 走 GitHub Actions 路线,配置好 Cloudflare Secrets,手动触发 Deploy Worker,全自动上线 + 自动更新。
  • 想要本地快速试玩 / 二次开发 → 走 Docker 路线,一行命令 ./docker-start.sh 即起。

EdgeChat 让「拥有一个自己的聊天空间」这件事,从维护服务器简化成了配置两个 Secret。现在,就去部署属于你团队的实时聊天系统吧!🚀

登录后查看全文
Edgechat