Hazel Chat部署指南:从本地Docker到100% Cloudflare生产环境的完整路径
Hazel Chat部署指南:从本地Docker到100% Cloudflare生产环境的完整路径
Hazel Chat 部署只需三步就能跑起来:一个基于 Effect-TS、ElectricSQL 和 PostgreSQL 的现代实时聊天平台,支持团队频道、在线状态、文件附件与机器人集成。本指南带你完成 Hazel Chat 的本地 Docker 开发环境搭建,并讲解它如何迁移到 100% Cloudflare 生产架构(Workers、Durable Objects、R2、PlanetScale Postgres)。
🧰 部署前准备:3 个必备条件
Hazel Chat 是一个 Monorepo(Turborepo 管理),前端 React 19 + Vite,后端 Bun + Effect-TS,实时同步依赖 ElectricSQL。开始前请确认:
| 依赖 | 版本要求 | 用途 |
|---|---|---|
| Bun | ≥ 1.2.14 | 运行时与包管理(需要 workspace catalogs 特性) |
| Docker | 任意新版 | 本地 PostgreSQL / Electric / Redis / MinIO 等基础服务 |
| Clerk 账号 | 免费即可 | 用户认证(需开启 Organizations 功能) |
💡 没有 Bun 会报错
engine不满足,请先安装再执行后续命令。
📦 第一步:克隆仓库并安装依赖
git clone https://gitcode.com/gh_mirrors/hazel12/hazel
cd hazel
bun install
仓库核心结构一览,理解目录有助于排查部署问题:
├── apps/
│ ├── web/ # React 前端(端口 3000)
│ ├── backend/ # Effect-TS API 服务(端口 3003)
│ ├── cluster/ # 分布式工作流服务(端口 3020)
│ ├── electric-proxy/ # Electric SQL 代理
│ └── link-preview-worker/ # 链接预览生成
└── packages/
├── db/ # 数据表定义与迁移
└── domain/ # 共享类型与 RPC 契约
🚀 第二步:一键启动本地 Docker 环境(setup 向导)
Hazel Chat 提供了一个交互式设置向导,源码见 packages/setup/src/commands/setup.ts:
bun run setup
向导会自动完成以下工作:
- 生成并配置证书(Caddy 反向代理)
- 执行
docker compose up -d,拉起 docker-compose.yaml 中定义的 6 个本地服务 - 运行环境体检(doctor 检查)
- 配置 Clerk 认证密钥(
CLERK_PUBLISHABLE_KEY/CLERK_SECRET_KEY) - 生成各服务的
.env文件 - 初始化数据库
本地 Docker 服务与端口速查:
| 服务 | 端口 | 说明 |
|---|---|---|
| PostgreSQL 17 | 5432 | 主数据库(wal_level=logical 为 Electric 复制服务) |
| Electric | 3333 | 实时同步引擎,连接 Postgres 逻辑复制 |
| Durable Streams | 4437 | bot gateway 的持久事件日志 |
| Redis | 6380 | electric-proxy 缓存 |
| MinIO | 9000 / 9001 | S3 兼容对象存储(生产对应 Cloudflare R2) |
| Caddy | 5133 / 3004 | SSE 与 WebSocket 反向代理 |
🖥️ 第三步:启动开发服务并验证
bun run dev # 核心栈:web + backend + cluster + bot-gateway
bun run dev:withBots # 额外启动本地机器人应用
启动后各服务地址:
- Web 前端:http://localhost:3000
- Backend API:http://localhost:3003
- Cluster 工作流:http://localhost:3020
- Bot 网关:http://localhost:3034
在浏览器打开 3000 端口,看到频道列表和消息流即表示 Hazel Chat 本地部署成功。Clerk Webhook 需指向 http://<backend-host>/webhooks/clerk(本地开发需配合隧道暴露),订阅 user.* 与 organization* 事件,签名密钥填入 CLERK_WEBHOOK_SECRET。
实时同步是怎么工作的?
Hazel Chat 采用 Local-first 架构:前端组件写入 TanStackDB Collections(乐观更新),ElectricSQL 负责与服务端 Postgres 双向同步,离线也能操作,上线后自动同步。数据流示意如下(来自仓库内置库文档 unidirectional-data-flow.lg.png):
☁️ 进阶:从 Docker 到 100% Cloudflare 生产环境
Hazel Chat 的生产架构目标非常激进:几乎所有计算都跑在 Cloudflare 上,用 Alchemy v2(Effect 版 IaC)声明全部资源。完整设计见 infra/cloudflare-migration-plan.md。
生产环境组件对照表
| 组件 | 本地 Docker / Railway | Cloudflare 生产 |
|---|---|---|
| Web 前端 (Vite SPA) | 本地 Vite dev server | Workers 静态资源站点 |
| Backend API (Bun) | 本地 Bun 进程 | Effect Worker + Durable Objects(限流、Outbox 分发、Discord 网关)+ KV + Cron |
| Electric 实时同步 | Docker 容器 | 托管 Electric 实例(经 electric-proxy Worker 访问) |
| Redis | 本地容器 | 全部移除,替换为 RateLimit / KV / Workers Cache |
| MinIO 对象存储 | 本地容器 | R2 原生绑定 + presign 上传 |
| Postgres | Docker 容器 | PlanetScale Postgres(Alchemy 托管)+ Hyperdrive 连接 |
| bot-gateway | Bun + Durable Streams | 每 bot 一个 BotGateway Durable Object(SQLite 事件日志) |
| cluster 工作流 | Bun | 暂留 Railway,通过 Cloudflare Tunnel 接入 |
资源声明集中在根目录 alchemy.run.ts,每个 app 各自维护一份 apps/<app>/alchemy.run.ts;Electric 容器与 KV 的定义见 apps/electric-proxy/resources.ts。
三个部署 Stage 与命令
| Stage | 命令 | 数据库 | 域名 |
|---|---|---|---|
prd(生产) |
bun run alchemy:deploy:prd |
PlanetScale hazel,栈托管 |
*.hazel.sh |
pr-<n>(预览) |
PR_NUMBER=<n> bun run alchemy:deploy:pr |
共享预览库 | app-pr-<n>.hazel.sh |
dev_<user>(本地) |
bun run alchemy:dev |
Docker Postgres | workers.dev / localhost |
生产切换(Cutover)的关键顺序
来自迁移计划的推荐步骤,每一步都有回滚路径:
- 先 Plan 后 Deploy:
bunx alchemy plan --stage prd,确认现有 Workers、KV、自定义域名显示为adopt而非create/replace - 先迁数据库:
bun run db:migrate加载 packages/db/ 中的 schema,pg_dump迁移数据,再让 Railway 服务指向 PlanetScale - Electric 切换:DNS 指回 Railway 即完成回滚
- backend 切换:保持主机名不变,Railway 旧实例保留一周作为回滚
- BotGateway 切换:bot-sdk 自带重连,无感切换
- 下线 Railway 旧服务(backend、Redis、OTel collector)
CI/CD 由 GitHub Actions 驱动:main 分支 CI 通过后自动执行 bun run alchemy:deploy:prd 并轮询 api.hazel.sh/health 健康检查,见 .github/workflows/deploy-prd.yml;PR 加 preview 标签即部署独立预览环境,关闭后自动销毁。
⚡ 常见问题速查
| 问题 | 解决方法 |
|---|---|
bun run setup 卡在 Docker |
确认 Docker Desktop 已启动;docker compose up -d 手动执行看报错 |
| 端口冲突(5432/3000 等) | 修改 docker-compose.yaml 中映射端口,并同步 .env |
| Clerk 登录失败 | 检查 Webhook 是否暴露(需隧道)、签名密钥 CLERK_WEBHOOK_SECRET 是否一致 |
| 实时消息不更新 | 确认 Electric(3333)健康:docker compose ps;Postgres 需保持 wal_level=logical |
| 类型检查/测试 | bun run typecheck、bun run test:once |
🎉 到这里,你已经完成了 Hazel Chat 部署 的全流程:本地 Docker 开发环境 3 条命令起步,生产环境通过 Alchemy 一键声明 Cloudflare 全套资源。祝你部署顺利!




