分享我的开源项目: 基于Go开发的微服务即时通讯与社交平台
工作之余断断续续开发了一年时间，欢迎stars
go-hichat-api
English | 简体中文
go-hichat-api 是Go语言后端与 Web 客户端仓库，是一个基于 go-zero 的微服务即时通讯与社交平台。项目整合 REST API、zRPC 服务、WebSocket 长连接、Kafka 异步链路、MongoDB 聊天记录、MySQL 业务数据、Redis 运行时状态，以及独立的 WebRTC 流媒体服务。
这个仓库可以作为现代 IM 系统的实践参考，覆盖清晰的服务边界、消息投递、已读回执、在线状态、动态通知、富媒体消息、社交关系、动态空间和 Next.js Web 客户端。
项目地址
https://github.com/iceymoss/go-hichat-api
项目亮点
- 基于 go-zero REST 和 zRPC 的微服务架构。
- 通过
.api和.proto文件维护 API 优先的服务契约。 - WebSocket 网关支持认证、心跳、在线状态、消息 ACK、已读回执和实时推送。
- Kafka 链路处理聊天投递、已读事件、消息撤回、动态通知和后台任务。
- MongoDB 存储聊天记录，MySQL 存储业务数据，Redis 存储会话、缓存、在线状态和运行时协调数据。
- 独立 WebRTC 流媒体服务，支持通话、会议、屏幕共享、直播、房间和 SFU 流程。
web/下提供完整 Web 客户端，技术栈为 Next.js 16、React 19、Bun、TypeScript、Tailwind CSS 和 Semi UI。
核心能力
| 领域 | 能力 |
|---|---|
| 用户与账号 | 手机号/密码登录、JWT 签发、手机/邮箱验证码、密码重置、资料管理、头像上传、账号注销、用户搜索和内部用户查询 RPC。 |
| 社交关系 | 好友申请、好友列表、备注、拉黑、朋友圈权限、消息通知设置、标签、好友举报和在线状态查询。 |
| 群组 | 建群、搜索群、入群申请、成员邀请、邀请 token、成员管理、群公告、角色、管理员操作、群主转让和群@。 |
| 即时通讯 | 单聊/群聊会话、会话置顶/免打扰、MongoDB 聊天记录、文本/文件/语音/图片/视频消息、引用、提及、未读状态、已读记录、消息撤回和媒体上传。 |
| 实时网关 | WebSocket 认证、路由分发、Redis 在线状态、Kafka 消息投递、服务端推送、ACK 跟踪、重试、去重和动态通知。 |
| 动态空间 | 动态发布、可见范围、媒体资源、评论、回复、点赞、草稿、未读计数、动态消息通知和在线推送。 |
| 异步任务 | 聊天、已读、撤回和动态通知事件的 Kafka 消费，以及 cron 任务扩展点。 |
| 流媒体 | WebRTC 单聊语音/视频通话、群组语音/视频通话。 |
| Web 客户端 | Next.js 应用、Bun 脚本、TypeScript、Tailwind CSS、Semi UI。 |
产品截图
截取自基于演示数据集运行的 Web 客户端（14 个预置用户，含好友、群组、会话和动态，由 scripts/mockdata 生成）。
账号
登录 | 注册 | 忘记密码 |
即时通讯
会话列表 | 单聊会话 |
群会话 | 创建群聊 |
多选 · 免打扰 · 置顶 | 对话内资料卡片 |
音视频通话
来电提醒 | 群通话界面 | 多人群通话中 |
好友
好友列表 · 详情 · 设置 | 好友申请详情 |
收到的申请 | 我发起的申请 |
动态空间（朋友圈）
发布动态 | 列表 · 详情 · 评论 · 点赞 |
我的朋友圈 | 朋友圈空间 |
点赞 / 评论列表 |
个人主页与设置
我的主页 | 我的收藏 | 系统设置 |
更多设置 |
架构
┌──────────────────────────────────────────────────────────────────────────────┐ │ L0 客户端层 │ │ │ │ Web Client (web/: Next.js + React) Mobile / Third-party Clients │ └───────────────┬────────────────────────────┬───────────────────────────┬─────┘ │ REST │ WebSocket │ WebRTC ▼ ▼ ▼ ┌──────────────────────────────────────────────────────────────────────────────┐ │ L1 接入层 │ │ │ │ HTTP APIs 实时接入 媒体接入 │ │ ┌─────────────────────────────┐ ┌───────────────────────┐ ┌──────────┐ │ │ │ user/api social/api │ │ im/ws │ │streaming │ │ │ │ im/api trend/api │ │ auth heartbeat ack │ │signaling │ │ │ │ REST routes + JWT context │ │ online push routing │ │rooms SFU │ │ │ └──────────────┬──────────────┘ └───────────┬───────────┘ └────┬─────┘ │ └─────────────────┼──────────────────────────────┼─────────────────────┼───────┘ │ zRPC │ 发布/消费 │ Redis ▼ ▼ ▼ ┌──────────────────────────────────────────────────────────────────────────────┐ │ L2 领域服务层 │ │ │ │ ┌────────────┐ ┌──────────────┐ ┌────────────┐ ┌──────────────┐ │ │ │ user/rpc │ │ social/rpc │ │ im/rpc │ │ trend/rpc │ │ │ │ 认证 │ │ 好友 │ │ 会话 │ │ 动态 │ │ │ │ 资料 │ │ 群组 │ │ 聊天记录 │ │ 评论 │ │ │ │ 验证码 │ │ 申请 │ │ 已读/撤回 │ │ 点赞/通知 │ │ │ └─────┬──────┘ └──────┬───────┘ └─────┬──────┘ └──────┬───────┘ │ └────────┼────────────────┼────────────────┼────────────────┼─────────────────┘ │ │ │ │ │ MySQL │ MySQL │ MongoDB │ MySQL + Kafka ▼ ▼ ▼ ▼ ┌──────────────────────────────────────────────────────────────────────────────┐ │ L3 事件与异步层 │ │ │ │ Kafka Topics │ │ ┌────────────────┐ ┌───────────────┐ ┌────────────────┐ ┌───────────────┐ │ │ │ chat-transfer │ │ read-transfer │ │ recall-transfer│ │ trend-notify │ │ │ └───────┬────────┘ └──────┬────────┘ └───────┬────────┘ └──────┬────────┘ │ │ └─────────────────┴──────────┬───────┴─────────────────┘ │ │ ▼ │ │ apps/task/mq: 持久化聊天、更新已读、推送撤回和动态通知 │ │ apps/task/cron: 统计、清理和可扩展定时任务 │ └────────────────────────────────────────┬─────────────────────────────────────┘ │ 持久化 / 更新 / 推送 ▼ ┌──────────────────────────────────────────────────────────────────────────────┐ │ L4 数据与运行时基础设施 │ │ │ │ MySQL: 用户、好友、群组、动态、评论、点赞、通知 │ │ MongoDB: 聊天记录、已读记录、撤回状态 │ │ Redis: session/JWT 状态、在线状态、缓存、WS 运行态、房间状态 │ │ Etcd: go-zero RPC 服务注册与发现 │ └──────────────────────────────────────────────────────────────────────────────┘ 关键连接 1. Web/Mobile -> HTTP APIs -> zRPC -> Domain RPC -> MySQL/MongoDB。 2. Web/Mobile -> im/ws -> Kafka -> task/mq -> MongoDB + im/ws 推送。 3. trend/rpc -> Kafka trend-notify -> task/mq -> im/ws -> 在线客户端。 4. RPC 服务注册到 Etcd；API 服务从 Etcd 发现 RPC 节点。 5. im/ws 和 streaming 使用 Redis 存储在线状态、会话、缓存和房间状态。服务列表
| 服务 | 层 | 职责 |
|---|---|---|
user | api,rpc,models | 账号、认证、资料、验证码、用户查询 |
social | api,rpc,socialmodels | 好友、好友申请、群组、群成员、邀请链接、群公告 |
im | api,rpc,ws,models,immodels | 会话、聊天记录、已读回执、消息撤回、WebSocket 网关 |
trend | api,rpc,models | 动态、评论、点赞、草稿、媒体、动态通知 |
task | mq,cron | Kafka 消费者和定时任务 |
streaming | internal,room,sfu,webrtc | WebRTC 通话、房间、会议、屏幕共享、直播 |
demo | 独立示例 | 内部 demo 服务，不属于主启动脚本 |
技术栈
- 后端：Go 1.25、go-zero、zRPC、gRPC、goctl。
- 实时通信：WebSocket、Kafka、WebRTC、Pion。
- 存储：MySQL、MongoDB、Redis。
- 服务发现：Etcd。
- 前端：Next.js 16、React 19、Bun、TypeScript、Tailwind CSS、Semi UI。
仓库结构
由tree -L 2生成。
. ├── CLAUDE.md ├── LICENSE ├── README.md ├── apps │ ├── im │ ├── social │ ├── streaming │ ├── task │ ├── trend │ └── user ├── cmd ├── common ├── config │ ├── config-local.yaml │ └── config-sample.yaml ├── deploy │ ├── dockerfile │ ├── sql │ ├── sql_init.go │ └── trendmig ├── docker-compose.yaml ├── docs │ ├── README.zh-CN.md │ ├── api.md │ ├── development-guide.md │ ├── imgs │ ├── screenshots │ └── specs ├── go.mod ├── go.sum ├── hichat2.sh ├── logs │ ├── im-api │ ├── im-im │ ├── im-rpc │ ├── im-ws │ ├── social-api │ ├── social-rpc │ ├── task-mq │ ├── task-task │ ├── trend-api │ ├── trend-rpc │ ├── user-api │ └── user-rpc ├── pkg │ ├── 2fa │ ├── bitmap │ ├── config │ ├── constants │ ├── ctxdata │ ├── db │ ├── encrypt │ ├── errors │ ├── http │ ├── interceptor │ ├── logger │ ├── message │ ├── relationcache │ ├── sensitive │ ├── storage │ ├── systemconfig │ ├── test │ ├── transaction │ ├── utils │ ├── wuid │ └── xerr ├── resources │ └── sensitive └── web ├── Caddyfile ├── bun.lock ├── components.json ├── dev.log ├── dist ├── download ├── eslint.config.mjs ├── examples ├── next-env.d.ts ├── next.config.ts ├── node_modules ├── package.json ├── postcss.config.mjs ├── public ├── scripts ├── src ├── tailwind.config.ts ├── tsconfig.json ├── tsconfig.tsbuildinfo ├── upload └── worklog.md快速开始
一键部署（Docker Compose）
无需本地工具链，只要有 Docker，克隆后一条命令即可拉起整套服务（6 个微服务 + 中间件 + 前端）：
gitclone https://github.com/iceymoss/go-hichat-api.gitcdgo-hichat-apidockercompose up-d--build随后访问http://localhost:2470。首次使用点「注册」即可——演示模式下验证码会自动填入输入框（无需真实短信），填昵称密码即可注册登录。
dockercomposeps# 查看各服务状态dockercompose logs-fweb# 跟踪某个服务日志dockercompose down# 停止（保留数据）dockercompose down-v# 停止并清空所有数据卷# 一键清理：删数据卷 + 删本项目构建的镜像dockercompose down-v--remove-orphans&&dockerimages'hichat-*'-q|xargs-rdockerrmi架构、端口、清理卸载、服务器域名（反向代理 + HTTPS）部署、音视频（TURN）说明详见 Docker 部署指南。
填充演示数据（可选）
部署完想立刻有数据可点、可截图？内置的数据生成器会注册14 个中文示例用户，并灌入好友、群组、单聊/群聊、动态及评论点赞——即 产品截图 里展示的那套数据。
用 Docker Compose 部署的（无需本机 Go 工具链），直接跑随仓库附带的一次性服务：
dockercompose--profilemock run--rmmockdata从源码运行的（已装 Go）：
go run ./scripts/mockdata# 完整数据集go run ./scripts/mockdata -trends-only# 只重灌动态/评论/点赞随后访问http://localhost:2470，用主角账号登录：
- 手机号
13800138000，密码hichat2024。14 个账号同密码，手机号为13800138000–13800138013。
仅在「全新/空库」上跑一次；重复运行会产生重复的好友申请与群。它只插入演示数据，不会删除任何东西。人设与内容脚本见
scripts/mockdata。
前置依赖
- Go 1.25 或更高版本（与
go.mod的go指令一致）。 - Web 客户端需要 Bun。
- MySQL、Redis、Etcd、MongoDB 和 Kafka。
- go-zero 工具链：
goctl、protoc、protoc-gen-go和protoc-gen-go-grpc。
本地依赖安装和代码生成说明见 开发指南。
启动后端服务
先启动所需基础设施，再运行主后端服务：
./hichat2.sh该脚本会启动 user、social、IM、task 和 trend 服务，并将日志写入logs/。
按需手动启动单个服务：
go run apps/<service>/<layer>/<service>.go-fapps/<service>/<layer>/etc/<service>-sample.yaml单独启动 streaming 服务：
apps/streaming/start.sh启动 Web 客户端
cdweb buninstallbun devWeb 开发服务默认运行在3001端口。
开发
- 开发指南：本地中间件配置、go-zero 工具链、代码生成、启动说明和 Docker 示例。
- API 文档：生成的 REST 和 gRPC 契约汇总。
- 功能规格：功能分析、设计说明和实现记录。
测试
在仓库根目录运行后端测试：
gotest./...-count=1在web/下运行前端 lint：
bun lint贡献
请参考 贡献指南 了解贡献规范。
许可证
本项目基于 Apache License 2.0 开源。