【免费下载链接】hazel
Hazel Chat 是一个开源的实时团队协作聊天平台，基于 Effect-TS 函数式框架、ElectricSQL 本地优先（Local-first）同步、TanStack DB、React 和 PostgreSQL 构建。它不仅支持频道、私聊、在线状态、表情回应、文件附件等完整即时通讯能力，还内置 GitHub、Linear 等开发者工具集成和官方 Bot SDK——如果你正在找一个可以自托管、技术栈现代的开源聊天方案，这篇完整解析能帮你快速判断它到底有多强。
一、Hazel Chat 是什么？
一句话概括：Hazel Chat = 现代化开源团队聊天平台 + Effect-TS 全栈架构 + Local-first 实时同步。
与普通聊天应用不同，它的几个关键定位是：
- 功能完整：频道与私聊、线程、置顶消息、表情回应、文件附件（Cloudflare R2 存储）、可配置通知、组织（Organization）成员与角色管理
- 实时优先：消息秒达、在线/离线状态与"正在输入"提示实时更新
- 开发者友好：内置 GitHub / Linear / Railway 集成卡片、富文本编辑器、命令面板，并支持用简单 API 自建机器人
- 本地优先：基于 ElectricSQL 实现离线可用、后台自动同步、乐观更新与冲突自动解决
- 完全开源：可审查、可贡献、可自托管，无供应商锁定
二、核心功能清单：团队协作需要什么，它都有什么
1. 实时消息与在线状态
- 组织化的 Channels（频道） 与 Direct Messages（私聊），消息即时投递
- Presence 在线状态：一眼看出谁在线、谁在打字，远程团队跨时区协作不再"失踪"
- 线程回复：把讨论从主时间线中抽离，保持频道整洁
2. 富文本、表情回应与文件附件
- 由 Plate.js 驱动的富文本编辑器：支持格式化、Markdown、内联代码高亮
- 对任意消息使用 Emoji 表情回应，快速表达"已读/赞同"
- Pinned Messages（置顶消息）：重要信息一键保存、随时回看
- 通过 Files 标签页集中浏览频道内共享的图片、视频与文档，支持预览与下载，附件存储在 Cloudflare R2
3. 集成生态与 Bot：把工作流搬进聊天
这是 Hazel 面向开发者团队最有吸引力的部分：
| 集成 | 能力 |
|---|---|
| GitHub | PR、Issue 卡片，部署通知直接出现在聊天里 |
| Linear | 富文本 Issue 预览与状态更新 |
| Railway | 构建与部署状态实时推送 |
| 自定义 Webhook | 任何服务的事件都可以推送到频道 |
同时提供了官方机器人 SDK（@hazel-chat/bot-sdk）：机器人通过 WebSocket 连接到 Hazel 的 Bot Gateway，底层由 Durable Streams 提供消息重放与断线续传，你只需要关注业务逻辑。内置了发送、回复、编辑、删除、回应消息等工具函数，以及 AI / 流式输出辅助能力，详见 libs/bot-sdk/README.md。
4. 命令面板快速导航与跨端体验
- 按 ⌘K 唤起命令面板：跳转任意频道、查找成员、执行操作，键盘流党狂喜
- 全量消息全文搜索 + AI 会话摘要，快速补上"错过的讨论"
- 支持 macOS / Windows / Linux 桌面应用（Tauri，见 apps/desktop/），以及可离线使用的 PWA
三、技术架构：Effect-TS 如何撑起"实时"二字
Hazel 的技术选型相当前沿，也是它"强大"的根源。整体架构可以分为四层：
1. Effect-TS 类型安全后端
后端运行在 Bun 上，用 Effect-TS 承担核心职责：
- 依赖注入：通过 Service + Layer 体系组合依赖，结构清晰
- 类型化错误：所有错误都是带标签的类型化错误，而不是
try/catch一把抓 - 并发模型：用 Fiber 与 Stream 处理高并发消息流
- 类型安全 RPC：客户端与服务端通过 Effect RPC 通信，契约统一定义在
packages/domain/，跨端自动类型推断与序列化
更关键的是共享数据库层：packages/db/ 用 effect-orm 定义全部表结构（表定义在 packages/db/src/tables/），前后端共用同一套类型，字段名拼错在编译期就会被拦住。
2. ElectricSQL 本地优先实时同步
这是 Hazel 实时体验的核心：
- 客户端持有本地数据副本，查询直接读本地，响应极快
- 乐观更新：操作先本地生效，后台与服务器同步，自动冲突解决
- 离线可用：断网后继续收发消息，恢复后自动补齐
- 服务端由 ElectricSQL 实例 + 一个 Electric Proxy Worker（apps/electric-proxy/）负责按组织/频道权限过滤可见数据
3. Effect Cluster 分布式工作流
apps/cluster/ 是一个独立服务（端口 3020），用 Effect Cluster + Effect Workflow 处理后台任务：
- Durable Workflows：长任务持久化在 PostgreSQL，进程重启后自动恢复
- 自动重试与失败处理，适合消息通知、RSS 轮询、GitHub Webhook 处理等场景
- 内置 Cron 任务：在线状态清理、上传清理、打字指示器超时清理等
4. 多 Worker 边缘能力
除核心三件套外，仓库还包含 link-preview-worker（链接预览生成）与 bot-gateway（机器人消息网关）等独立服务，体现了"单体可跑、微服务可拆"的架构思路。
四、项目结构一览（Monorepo）
Hazel 使用 Turborepo 管理 Monorepo，目录职责清晰（详见 README.md）：
| 路径 | 说明 | 端口 |
|---|---|---|
| apps/web/ | React 前端（Vite + TanStack） | 3000 |
| apps/backend/ | Effect-TS API 服务 | 3003 |
| apps/cluster/ | 分布式工作流服务 | 3020 |
| apps/electric-proxy/ | ElectricSQL 同步代理 | - |
| apps/bot-gateway/ | 机器人消息网关 | 3034 |
| packages/db/ | effect-orm 表定义与迁移 | - |
| packages/domain/ | 共享 RPC/HTTP 契约与模型 | - |
| libs/bot-sdk/ | 官方机器人 SDK | - |
更深入的架构说明可参考仓库内的 CLAUDE.md（面向 AI 协作的架构指南）与 packages/db/README.md（数据库 Schema 文档）。
五、快速上手：5 分钟本地跑起来
前置条件：Bun ≥ 1.2.14 + Docker。
# 1. 克隆仓库
git clone https://gitcode.com/gh_mirrors/hazel12/hazel
cd hazel
# 2. 安装依赖
bun install
# 3. 交互式初始化（自动拉起 PostgreSQL/Redis/Electric/MinIO、
# 配置认证、生成密钥、初始化数据库）
bun run setup
# 4. 一键启动全部服务
bun run dev
启动后：Web 在 http://localhost:3000，后端 http://localhost:3003，Cluster http://localhost:3020。如需同时跑本地机器人，用 bun run dev:withBots。
常用开发命令：
| 命令 | 作用 |
|---|---|
bun run build | 构建全部应用与包 |
bun run typecheck | 全仓 TypeScript 类型检查 |
bun run test:once | 一次性跑完全部测试 |
bun run db:migrate | 应用数据库迁移 |
六、总结：谁适合用 Hazel Chat？
✅ 适合你，如果你：
- 想要一个可自托管的开源聊天平台，替代闭源 SaaS
- 团队重度使用 GitHub / Linear 等开发者工具，希望通知"长在聊天里"
- 关注前端工程，想研究 Effect-TS、Local-first、类型安全 RPC 等前沿模式
- 需要给团队自建 AI 或自动化机器人（官方 Bot SDK 开箱即用）
⚠️ 需要注意：认证目前默认走 Clerk（需开通账号配置 Key），且项目技术栈较新、迭代较快，二次开发前建议先通读架构文档。
总的来说，Hazel Chat 证明了"聊天软件"这件事依然可以用最现代的函数式、本地优先、边缘计算思路重新做一遍——功能层面追平主流商业产品，架构层面则甩开了一个身位。
【免费下载链接】hazel
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
