一、系统定位
青码即时通讯系统是一套面向企业私有部署、行业定制和独立品牌运营的即时通信解决方案。系统不是单一聊天页面，而是由移动端、H5、PC 网页端、业务 API、WebSocket 实时服务、数据库、文件服务、离线推送和运营后台共同组成。
系统适用于企业内部沟通、会员社交、客户服务、项目协作、垂直社区和需要实时消息能力的定制平台。正式运营前应完成真实服务器部署、并发测试、备份恢复和隐私合规检查。
二、系统组成
1. 用户客户端
- uni-app 移动端：用于打包 Android、iOS 和 H5，承担消息列表、通讯录、聊天、群聊和个人中心等功能。
- PC 网页端：适合桌面办公场景，提供会话、联系人、文件传输和多窗口操作。
- 管理后台：用于用户、群聊、举报、敏感词、公告、推送、系统配置、授权和日志管理。
2. 服务端
- PHP API：负责登录鉴权、好友关系、群组、消息历史、文件记录、后台管理和业务规则。
- MySQL：保存用户、关系链、会话、消息索引、群成员、设备、推送记录和审计信息。
- Workerman WebSocket：负责长连接、心跳、在线状态、实时消息投递、事件通知和断线处理。
- push-worker：对不在线或退到后台的设备执行离线推送任务。
三、核心功能
| 模块 | 主要能力 |
|---|---|
| 账号与安全 | 注册、登录、退出、设备管理、令牌刷新、登录限制和异常记录 |
| 好友与通讯录 | 搜索、申请、同意、拒绝、备注、黑名单、新好友红点和实时通知 |
| 单聊 | 文本、图片、文件、语音、引用、撤回、已读未读和历史记录 |
| 群聊 | 建群、邀请、移除、群主与管理员、群公告、禁言和成员管理 |
| 实时通信 | WebSocket 鉴权、心跳、重连、在线状态和多端消息同步 |
| 离线推送 | UniPush 2.0、厂商通道、推送队列、失败重试和设备状态管理 |
| 运营后台 | 用户、群聊、举报、敏感词、公告、日志、风控和授权状态 |
四、消息处理流程
- 客户端生成唯一请求号并向 API 或 WebSocket 服务提交消息。
- 服务端验证登录状态、好友或群成员关系、消息类型和发送频率。
- 数据库事务保存消息、会话摘要和未读计数。
- WebSocket 向在线设备投递消息和状态事件。
- 接收端回执送达或已读状态，服务端再同步给发送端其他设备。
- 接收端不在线时，将推送任务写入队列，由 push-worker 执行。
五、部署拓扑
客户端 App / H5 / PC
│ HTTPS / WSS
▼
Nginx 反向代理与 SSL
├── PHP API
├── Workerman WebSocket
├── 文件与对象存储
└── 管理后台
│
├── MySQL
├── 推送任务
└── 日志与备份生产环境建议把 API、WebSocket、任务进程和数据库分别监控。客户数量或在线连接增长后，再按实际压力增加 Redis、消息队列、对象存储和多节点网关。
六、安全设计
- 所有业务权限必须由服务端再次判断，不能只依赖前端按钮隐藏。
- 登录密码使用安全哈希保存，令牌设置有效期并支持主动失效。
- 发送消息、添加好友、上传文件和验证码接口必须限流。
- 文件上传同时验证扩展名、MIME、大小和保存目录。
- 后台使用独立入口、权限分级、TOTP、IP 白名单和操作审计。
- 生产环境强制 HTTPS/WSS，关闭 PHP 错误公开显示和目录索引。
七、授权与版本
系统可以接入青码授权中心，按域名、IP、设备或账号签发授权，并设置有效期、最大用户数、最大连接数和功能套餐。授权判断应同时覆盖 PHP API、WebSocket、push-worker 和升级下载，不能只放在前端。
八、上线前检查
- 完成全新安装与覆盖升级测试。
- 验证注册、登录、加好友、单聊、群聊、已读未读和离线推送闭环。
- 验证 Workerman 与 push-worker 由宝塔进程守护持续运行。
- 完成数据库每日备份和至少一次恢复演练。
- 检查隐私政策、用户协议、备案信息和第三方服务配置。
九、V6.9.2 实际交付模块
V6.9.2 服务端不是单一接口文件，而是按业务能力拆分为多个服务模块。当前正式交付包包含账号鉴权、消息、群功能、风控、钱包、支付、音视频、推送、备份、授权、PC 扫码登录和系统检查等服务。
| 模块 | 主要职责 |
|---|---|
| Auth / SecurityService | 登录身份、令牌、设备状态、异常访问和安全策略。 |
| ImService / MessageService | 会话、消息写入、撤回、已读、消息派发和历史同步。 |
| GroupFeatureService / GroupRiskService | 群成员、群公告、群权限、定时消息、群风控和成员状态。 |
| PushService | 在线通知、离线推送任务、设备绑定、失败重试和回执记录。 |
| CallService | 语音、视频呼叫状态、房间权限和临时通话凭证。 |
| WalletService / PaymentDirectService | 钱包流水、支付密码、官方支付回调、幂等和风险检查。 |
| BackupService / SystemCheck | 数据库备份、结构版本、运行状态、兼容性和上线健康检查。 |
| LicenseService | API、WebSocket、后台、任务进程和升级下载的商业授权门禁。 |
十、正式入口说明
api/index.php：主要业务 API 入口。realtime/index.php：实时轮询或降级同步入口。websocket/server.php：WebSocket 长连接服务及事件投递。push-worker.php：推送、派发和异步任务处理。admin/：运营管理后台。pc/：PC 网页客户端。uniapp/与uniapp-cli/：两种客户端工程形式。upgrade/：版本升级和数据库结构迁移入口。
十一、数据一致性原则
消息、会话摘要、未读数量、派发任务和推送任务之间必须保持一致。服务端保存成功后才向客户端确认；网络重试通过客户端消息唯一号去重；WebSocket 只负责实时投递，客户端重新连接后仍应从服务端补拉缺失数据。