Hazel Chat部署指南:从本地Docker到100% Cloudflare生产环境的完整路径

原创2026-10-30 16:02:021,944 阅读

Hazel Chat部署指南:从本地Docker到100% Cloudflare生产环境的完整路径

Hazel Chat 部署只需三步就能跑起来:一个基于 Effect-TS、ElectricSQL 和 PostgreSQL 的现代实时聊天平台,支持团队频道、在线状态、文件附件与机器人集成。本指南带你完成 Hazel Chat 的本地 Docker 开发环境搭建,并讲解它如何迁移到 100% Cloudflare 生产架构(Workers、Durable Objects、R2、PlanetScale Postgres)。

Hazel Chat 实时聊天平台的部署目标界面

🧰 部署前准备: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

向导会自动完成以下工作:

  1. 生成并配置证书(Caddy 反向代理)
  2. 执行 docker compose up -d,拉起 docker-compose.yaml 中定义的 6 个本地服务
  3. 运行环境体检(doctor 检查)
  4. 配置 Clerk 认证密钥(CLERK_PUBLISHABLE_KEY / CLERK_SECRET_KEY)
  5. 生成各服务的 .env 文件
  6. 初始化数据库

本地 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 # 额外启动本地机器人应用

启动后各服务地址:

Hazel Chat 本地部署成功后的频道消息界面

在浏览器打开 3000 端口,看到频道列表和消息流即表示 Hazel Chat 本地部署成功。Clerk Webhook 需指向 http://<backend-host>/webhooks/clerk(本地开发需配合隧道暴露),订阅 user.* 与 organization* 事件,签名密钥填入 CLERK_WEBHOOK_SECRET。

集成管理界面:Linear、GitHub 等第三方工具连接

实时同步是怎么工作的?

Hazel Chat 采用 Local-first 架构:前端组件写入 TanStackDB Collections(乐观更新),ElectricSQL 负责与服务端 Postgres 双向同步,离线也能操作,上线后自动同步。数据流示意如下(来自仓库内置库文档 unidirectional-data-flow.lg.png):

TanStackDB 单向数据流:Components、Collections 与 Server 之间的 Update/Sync/Persist 循环

☁️ 进阶:从 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)的关键顺序

来自迁移计划的推荐步骤,每一步都有回滚路径:

  1. 先 Plan 后 Deploy:bunx alchemy plan --stage prd,确认现有 Workers、KV、自定义域名显示为 adopt 而非 create/replace
  2. 先迁数据库:bun run db:migrate 加载 packages/db/ 中的 schema,pg_dump 迁移数据,再让 Railway 服务指向 PlanetScale
  3. Electric 切换:DNS 指回 Railway 即完成回滚
  4. backend 切换:保持主机名不变,Railway 旧实例保留一周作为回滚
  5. BotGateway 切换:bot-sdk 自带重连,无感切换
  6. 下线 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 标签即部署独立预览环境,关闭后自动销毁。

部署后团队在 Hazel 频道中同步 Cloudflare 部署状态

⚡ 常见问题速查

问题 解决方法
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 全套资源。祝你部署顺利!

登录后查看全文
hazel