壹信 — 即时通讯系统 - 壹信-开源即时通讯

代码库包含：Flutter 客户端（多端）、Go 后端服务、Vue3 管理后台
更详细的源码结构说明见：PROJECT_STRUCTURE.md

1. 项目简介 (Project Overview)

壹信是一套 Telegram 风格的即时通讯系统，提供“消息收发与多端同步 + 社交动态 + 钱包交易 + 音视频通话 + 运营管理后台”的完整闭环，面向移动端与桌面端使用场景。
壹信 IM 百万级高并发架构技术官网：https://www.66demo.cn

核心功能（按业务域归类）：

即时通讯：私聊 / 群聊 / 频道；文本/图片/视频/语音/文件；撤回/编辑/转发；表情回应；已读回执

实时能力：WebSocket 实时推送、在线状态、正在输入

消息可靠性：断网消息队列与网络恢复自动重发（客户端）

社交动态：朋友圈动态流、点赞、评论、话题、屏蔽

钱包体系：余额、交易流水、充值/提现、转账、红包（含过期退款定时任务）

音视频通话：Agora RTC；来电处理（iOS/Android CallKit 适配）；桌面通知辅助

管理后台：用户/会话/动态/钱包/通话/举报管理与统计面板

核心技术栈（自动识别）：

客户端（Flutter / Dart）

Flutter SDK：>=3.2.0 <4.0.0（见 pubspec.yaml）

状态管理：Riverpod（flutter_riverpod + riverpod_annotation）

路由：go_router（lib/core/router/app_router.dart）

网络：Dio + WebSocket（lib/core/services/api/api_client.dart、lib/core/services/api/websocket_service.dart）

本地存储：Isar（lib/core/services/storage/models/）

通话：Agora RTC + CallKit（lib/core/services/call_service.dart）

服务端（Go）

Web 框架：Gin（路由集中注册于 backend/cmd/server/main.go）

ORM：GORM（MySQL）

数据层：MySQL（关系数据）、MongoDB（消息文档/按月分集合）、Redis（缓存/序号/限流/MQ）

实时：WebSocket Hub（backend/internal/ws/）

异步：Redis MQ（backend/internal/mq/）

推送：APNs（backend/internal/services/push_service.go）

管理后台（Vue3）

Vue3 + Vite + TypeScript（入口 admin/src/main.ts）

UI：Element Plus

状态：Pinia

图表：ECharts

HTTP：Axios（封装位于 admin/src/utils/http/）

环境变量：.env*（见 admin/.env*）

备注：如执行 flutter pub get 提示缺少 flutter_riverpod，请检查 pubspec.yaml 中该依赖是否被注释并取消注释后重试。

2. 项目架构与目录结构 (Architecture)

整体架构（逻辑视图）：

Flutter 客户端（iOS/Android/macOS/Windows/Linux/Web）

通过 REST API 与 Go 后端交互（鉴权：Bearer Token）

通过 WebSocket 接收实时消息/事件（断线重连 + 心跳 + 订阅）

Vue 管理后台

调用后端 /api/v1/admin/* 管理接口（管理员 Bearer Token）

Go 后端

MySQL：用户/会话/钱包/动态/系统设置/通话记录等

MongoDB：聊天消息文档（按 chatId + 月分集合）

Redis：缓存、限流、消息序号、消息队列

WebSocket：实时推送（新消息/已读/输入状态/通话事件等）

.
|-- lib/                       # Flutter 客户端核心源码（feature-first）
|-- assets/                    # Flutter 资源（images/icons/emoji/sounds/fonts）
|-- backend/                   # Go 后端（Gin + GORM + Mongo + Redis + WS + MQ）
|-- admin/                     # Vue3 管理后台（Vite + ElementPlus + Pinia）
|-- android/ ios/ macos/ ...   # Flutter 各平台宿主工程
|-- test/                      # Flutter 测试
|-- pubspec.yaml               # Flutter 依赖与资源清单
`-- PROJECT_STRUCTURE.md       # 源码结构与功能说明书

核心模块职责概览：

lib/core/：路由、主题、API/WS、通话、后台保活、离线队列、本地存储等基础能力

lib/features/：auth/chat/contacts/moments/wallet/call/settings 等业务模块

backend/internal/handlers/：HTTP API 入口（参数校验/权限校验/调用服务）

backend/internal/services/：业务服务层（消息入库/同步、推送、钱包定时任务、Agora token 等）

backend/internal/ws/：WebSocket Hub（连接管理、订阅、广播）

admin/src/views/：管理后台业务页面（用户/会话/动态/钱包/通话/统计）

3. 接口文档 (API Documentation) 🌟重点

3.1 通用约定

Base URL：{SERVER}/api/v1

认证方式（用户端）：Authorization: Bearer <token>

认证方式（管理端）：Authorization: Bearer <admin_token>

统一响应结构：

code: 0 表示成功，非 0 为错误

message: 错误/提示信息

data: 业务数据（可能是对象/数组）

3.2 核心 API（按模块分类）

以下接口来自后端路由注册：backend/cmd/server/main.go。若需要“全量接口清单”，建议基于该文件生成 OpenAPI/Swagger。

Auth（认证）

接口名称	Method	Endpoint	关键参数	功能描述
用户登录	POST	`/auth/login`	`username,password,device_id,device_type,device_name`	登录并返回 token + 用户信息
用户注册	POST	`/auth/register`	`username,password,nickname,device_id,...`	注册并返回 token + 用户信息
检查用户名	POST	`/auth/check-username`	`username`	校验用户名是否可用
刷新 Token	POST	`/auth/refresh`	Header Bearer	刷新访问 token（需登录）
退出登录	POST	`/auth/logout`	-	退出当前登录态（服务端侧清理/失效处理）
修改密码	POST	`/auth/change-password`	`old_password,new_password`	修改登录密码（需登录）

User（用户）

接口名称	Method	Endpoint	关键参数	功能描述
获取当前用户	GET	`/user/me`	-	获取本人资料
更新当前用户	PUT	`/user/me`	`nickname,username,avatar,bio...`	更新本人资料
检查用户名（登录后）	POST	`/user/check-username`	`username`	登录态下校验用户名是否可用
搜索用户	GET	`/user/search`	`keyword`	搜索用户
搜索用户+公开群/频道	GET	`/user/search-all`	`keyword`	聚合搜索
隐私设置-获取/更新	GET/PUT	`/user/privacy`	- / `payload`	管理隐私配置
黑名单列表/拉黑/移除	GET/POST/DELETE	`/user/blocked` `/user/blocked/:blocked_id`	`blocked_id`	用户拉黑与管理
设备列表/踢设备/踢其它设备	GET/DELETE/POST	`/user/devices` `/user/devices/:device_id` `/user/devices/terminate-others`	`device_id`	设备管理
会话列表/终止会话/终止其它会话	GET/DELETE/POST	`/user/sessions` `/user/sessions/:session_id` `/user/sessions/terminate-others`	`session_id`	登录会话管理
推送 token 设置	POST/DELETE	`/user/push-token`	`token`	绑定/移除推送 token
推送设置	GET/PUT	`/user/push-settings`	`show_preview,...`	消息预览等设置
删除账号	DELETE	`/user/account`	-	删除当前账号（需登录）
获取用户资料	GET	`/user/:id`	path `id`	获取用户公开资料
共同群/频道	GET	`/user/:id/common-groups`	path `id`	查询共同群/频道

Chat（会话/群/频道）

接口名称	Method	Endpoint	关键参数	功能描述
会话列表	GET	`/chat/list`	`page,page_size`	获取会话列表（含置顶/未读等）
创建会话	POST	`/chat/create`	`type,name,member_ids,is_public...`	创建私聊/群/频道
获取/更新/删除会话	GET/PUT/DELETE	`/chat/:id`	path `id`	会话详情与维护
成员列表	GET	`/chat/:id/members`	-	获取成员信息
加/移成员	POST/DELETE	`/chat/:id/members` `/chat/:id/members/:user_id`	`user_ids` / path `user_id`	成员管理
设置成员角色	PUT	`/chat/:id/members/:user_id/role`	`role`	角色变更（成员/管理员/群主）
退群/隐藏/加入	POST	`/chat/:id/leave` `/chat/:id/hide` `/chat/:id/join`	-	会话操作
入群申请列表/审核	GET/POST	`/chat/:id/join-requests` `/chat/:id/join-requests/:request_id/review`	`approve`	入群审批流
禁言/解禁/查询禁言	POST/POST/GET	`/chat/:id/mute` `/chat/:id/unmute` `/chat/:id/mute-status`	`user_id,duration`	群禁言能力
置顶/免打扰/切换未读	POST	`/chat/:id/pin` `/chat/:id/mute-chat` `/chat/:id/toggle-unread`	-	会话状态开关
清空聊天记录	POST	`/chat/:id/clear`	-	清空聊天内容（逻辑）
搜索聊天消息	GET	`/chat/:id/search`	`keyword`	服务端消息搜索

Message（消息）

接口名称	Method	Endpoint	关键参数	功能描述
发送消息	POST	`/message/send`	`chat_id,type,content,reply_to,mentions`	发送文本/媒体/文件/语音等
拉取消息列表	GET	`/message/list`	`chat_id,before_seq,limit`	分页拉取历史消息
增量同步消息	POST	`/message/sync`	`chat_id,last_seq`	断线重连后的增量同步
撤回/删除消息	POST	`/message/revoke` `/message/delete`	`chat_id,msg_id`	撤回（对方可见）/仅对自己删除
标记已读	POST	`/message/read`	`chat_id,msg_seq`	清未读并广播已读回执
表情回应	POST	`/message/reaction/add` `/message/reaction/remove`	`chat_id,msg_id,emoji`	添加/移除回应
转发/编辑	POST	`/message/forward` `/message/edit`	`source_chat_id,source_msg_id,target_chat_id` / `content`	转发与编辑文本消息
媒体/文件/链接列表	GET	`/message/media`	`chat_id,type,page,limit`	获取会话媒体归档
媒体统计	GET	`/message/media/count`	`chat_id`	统计 media/file/link/voice 数量

Contact（联系人）

接口名称	Method	Endpoint	关键参数	功能描述
联系人列表	GET	`/contact/list`	-	获取联系人/好友列表
添加联系人	POST	`/contact/add`	`user_id`	添加联系人（双向/单向关系以服务端规则为准）
删除联系人	DELETE	`/contact/:id`	path `id`	删除联系人
设置备注	PUT	`/contact/:id/remark`	`remark`	修改联系人备注

Report（举报）

接口名称	Method	Endpoint	关键参数	功能描述
提交举报	POST	`/report`	`target_type,target_id,reason,description?`	举报用户/群/频道/消息等内容

Moments（动态/朋友圈）

接口名称	Method	Endpoint	关键参数	功能描述
动态列表	GET	`/moment/list`	`page`	获取动态流
动态详情	GET	`/moment/:id/detail`	`id`	获取单条动态
发布/更新/删除动态	POST/PUT/DELETE	`/moment/publish` `/moment/:id`	`content,images...`	动态管理
点赞/取消点赞	POST	`/moment/:id/like` `/moment/:id/unlike`	-	点赞能力
评论列表/发表评论	GET/POST	`/moment/:id/comments` `/moment/:id/comment`	`content`	评论能力
热门话题	GET	`/moment/topics/hot`	-	话题榜
我的动态相关	GET	`/moment/my/moments` `/moment/my/likes` `/moment/my/comments` `/moment/my/received-likes`	`page`	我的动态、点赞、评论与收到的点赞
搜索动态	GET	`/moment/search`	`keyword,page`	动态搜索
屏蔽动态/屏蔽用户动态	POST	`/moment/:id/block` `/moment/block-user/:userId`	-	内容屏蔽

Wallet（钱包）

接口名称	Method	Endpoint	关键参数	功能描述
获取钱包	GET	`/wallet`	-	余额、冻结金额、是否设置支付密码
钱包设置	GET	`/wallet/settings`	-	币种/过期时间/公告等
交易流水	GET	`/wallet/transactions`	`page,page_size,type`	交易记录查询
设置/修改支付密码	POST	`/wallet/pay-password`	`password(6位),old_password?`	支付密码设置
验证支付密码	POST	`/wallet/verify-password`	`password`	风控校验
充值方式/提交订单	GET/POST	`/wallet/recharge-methods` `/wallet/recharge-order`	`method_id,amount,proof_image`	充值申请
查询充值订单	GET	`/wallet/recharge-orders`	-	充值订单列表
充值（模拟）	POST	`/wallet/recharge`	`amount`	模拟充值（仅开发/演示用途，生产通常应关闭）
红包-发送/领取/详情	POST/POST/GET	`/wallet/red-packet/send` `/wallet/red-packet/:id/claim` `/wallet/red-packet/:id`	`type,total_amount,total_count,pay_password`	红包流程
转账-发送/接收/拒收/详情	POST/POST/POST/GET	`/wallet/transfer/send` `/wallet/transfer/:id/accept` `/wallet/transfer/:id/reject` `/wallet/transfer/:id`	`amount,receiver_id,pay_password`	转账流程
提现方式/发起提现	GET/POST	`/wallet/withdraw/methods` `/wallet/withdraw`	`method_id,amount,form_data,pay_password`	提现流程

Call（音视频通话）

接口名称	Method	Endpoint	关键参数	功能描述
获取 Agora 配置	GET	`/call/config`	-	是否启用、AppID 等
获取 Token	GET	`/call/token`	`channel_name,uid`	获取 RTC token
创建通话	POST	`/call/create`	`target_user_id,call_type`	发起语音/视频
接听/拒绝/结束	POST	`/call/accept` `/call/reject` `/call/end`	`call_id,reason?`	通话状态流转
取消通话	DELETE	`/call/:call_id`	path `call_id`	主叫取消
通话记录	GET	`/call/history`	`page`	通话历史

Upload（文件上传）

接口名称	Method	Endpoint	关键参数	功能描述
上传图片/多图	POST	`/upload/image` `/upload/images`	`multipart`	上传图片资源
上传视频/语音/文件	POST	`/upload/video` `/upload/voice` `/upload/file`	`multipart`	上传媒体/文件
上传头像	POST	`/upload/avatar`	`multipart`	用户头像上传

WebSocket（实时推送）

Endpoint：GET /ws（实际连接：ws(s)://{SERVER}/api/v1/ws?device_type=xxx&token=xxx）

关键参数：token、device_type

典型消息类型（客户端常量位于 lib/core/services/api/websocket_service.dart）：

消息：new_message、message_revoked、message_edited

状态：typing、read/read_receipt、online_status

反应：reaction

通话：incoming_call、call_accepted、call_rejected、call_ended、call_cancelled

Admin（管理后台 API）

接口名称	Method	Endpoint	关键参数	功能描述
管理员登录	POST	`/admin/login`	`username,password`	获取 `admin_token`
当前管理员	GET	`/admin/me`	-	获取当前管理员信息
修改管理员密码	PUT	`/admin/password`	`old_password,new_password`	修改密码
仪表盘统计	GET	`/admin/stats/dashboard`	-	获取总览统计
用户列表	GET	`/admin/users/list`	`page,page_size,keyword?`	用户管理列表
会话列表	GET	`/admin/chats/list`	`page,page_size,type?`	会话/群/频道管理列表
动态列表	GET	`/admin/moments/list`	`page,page_size,status?`	动态内容管理
举报列表	GET	`/admin/reports/list`	`page,page_size,status?,target_type?`	举报处理与跟踪
系统设置（获取/更新）	GET/PUT	`/admin/settings`	`payload`	系统开关、公告、官方账号等配置

说明：管理端还有更细的写操作（封禁/解封/踢人/重置密码/删除内容等），以 backend/cmd/server/main.go 的 /api/v1/admin 路由组为准。

4. 快速开始 (Getting Started)

更完整的安装与运行说明见：安装依赖教程.txt、backend/baota/README.md

4.1 前置要求

Flutter：>=3.2.0 <4.0.0

Go：以 backend/go.mod 为准（包含 toolchain 声明）

Node.js：>=20.19.0（见 admin/package.json）

pnpm：>=8.8.0

数据库：MySQL 8.x、MongoDB 7.x、Redis 7.x

4.2 启动后端（推荐：本地跑 API + Docker 起 DB）

启动数据库（仅启动 MySQL/MongoDB/Redis）：

配置后端：

编辑 backend/config.yaml（生产务必修改 jwt.secret）

启动 API：

服务默认：

API：http://localhost:8080/api/v1

健康检查：GET http://localhost:8080/health

默认管理账号（后端首次启动会初始化）：

用户名：admin

密码：123456

生产环境务必修改默认管理员密码，并按需关闭/移除演示接口（例如 /wallet/recharge 模拟充值）。

4.3 启动 Flutter 客户端

安装依赖：

运行（示例）：

修改后端地址（客户端请求与 WS 地址）：

编辑 lib/core/services/api/api_client.dart 中 ApiConfig.serverUrl 与 ApiConfig.wsUrl

打包脚本：

Android：./build_apk.sh

iOS（真机）：./install_ios.sh

4.4 启动管理后台（admin）

安装依赖并启动：

配置 API：

开发环境代理目标：编辑 admin/.env.development 的 VITE_API_PROXY_URL

生产环境 API：编辑 admin/.env.production 的 VITE_API_URL

构建生产包：

壹信 — 即时通讯系统

1. 项目简介 (Project Overview)#

2. 项目架构与目录结构 (Architecture)#

3. 接口文档 (API Documentation) 🌟重点#

3.1 通用约定#

3.2 核心 API（按模块分类）#

Auth（认证）#

User（用户）#

Chat（会话/群/频道）#

Message（消息）#

Contact（联系人）#

Report（举报）#

Moments（动态/朋友圈）#

Wallet（钱包）#

Call（音视频通话）#

Upload（文件上传）#

WebSocket（实时推送）#

Admin（管理后台 API）#

4. 快速开始 (Getting Started)#

4.1 前置要求#

4.2 启动后端（推荐：本地跑 API + Docker 起 DB）#

4.3 启动 Flutter 客户端#

4.4 启动管理后台（admin）#