如何快速部署EdgeChat:Cloudflare Workers团队聊天系统从零到上线完全指南
如何快速部署EdgeChat:Cloudflare Workers团队聊天系统从零到上线完全指南
EdgeChat 是一个完全运行在 Cloudflare Worker 上的现代团队聊天系统,支持实时群聊与私信、Telegram 双向桥接、语音与文件分享,并对消息和附件提供服务端加密。本文带你从零开始,走通 GitHub Actions 自动部署 和 Docker 一键启动 两条路线,几分钟内把属于自己团队的聊天空间正式上线——全程无需维护一台常驻服务器。
一、EdgeChat 是什么?为什么选择它?
EdgeChat 解决了一个很具体的痛点:想拥有一个独立的聊天空间,又不想长期维护服务器、数据库和一整套运行环境。
它把应用和数据全部放在你自己的 Cloudflare 账号下,通过 GitHub Actions 自动部署和更新,天然免运维。核心能力包括:
| 你关心的事 | EdgeChat 的做法 |
|---|---|
| 部署与维护 | 基于 Cloudflare Workers,免维护常驻服务器;支持 GitHub Actions 自动部署 |
| 成员与管理 | 独立账号、公开/私有群组、私信与管理后台 |
| 已有的 Telegram 群 | 通过 Bot 双向桥接,两侧成员各用各的习惯入口 |
| 隐私与扩展 | 消息与附件服务端加密,源码开放可二次开发 |
💡 项目本身免费开源,云服务费用取决于你的 Cloudflare 套餐与用量。
二、部署前准备: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_TOKENCLOUDFLARE_ACCOUNT_ID
可选(推荐,自动创建管理员账号):
EDGECHAT_ADMIN_USERNAME(默认admin)EDGECHAT_ADMIN_PASSWORDEDGECHAT_ADMIN_DISPLAY_NAME(默认Administrator)
步骤 3:手动触发 Deploy Worker
在 Actions 面板选择 Deploy Worker → Run workflow。整个流程会自动完成:
- 安装依赖并运行
npm test - 构建前端静态资源
- 检测并创建缺失的 D1 / KV / R2 资源
- 首次部署自动初始化数据库表结构与管理员账号
- 生成并注入服务端加密密钥
- 发布 Worker,得到你的专属访问地址
⚡ 之后每次向
master/main分支推送代码改动,也会自动触发部署。工作流定义见 deploy-worker.yml。
步骤 4:打开访问地址,登录后台
部署成功后会得到一个 *.workers.dev 地址。用你配置的管理员账号登录后,即可创建群组、管理成员、开启 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 个关键配置
部署只是开始,上线后建议优先完成这几件事:
- 确认消息保留期:默认 7 天自动清理。修改
MESSAGE_RETENTION_DAYS(正整数,如30)后重新部署;缩短保留期会删除更早消息,不可恢复,见 auto-update.md。 - 启用 Telegram 双向桥接:管理员在后台把任意 EdgeChat 群组与 Telegram 群绑定,网页与 Telegram 消息互相同步,一对一私信不进入桥接。
- 理解加密边界:EdgeChat 对新写入的消息正文和新上传的附件使用 AES-256-GCM 服务端静态加密。⚠️ 这是服务端加密,不是端到端加密,掌握密钥的部署方仍需要被信任。
- 开启语音通话(可选):配置
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。现在,就去部署属于你团队的实时聊天系统吧!🚀


