即时通讯(im)
装上即时通讯后怎么配好友校验与撤回时长、长连接走哪条通道、消息收不到时查哪。
应用编码 im,本页对应应用版本 1.0.1(引擎要求 >=5.6.2 <6.0.0),许可 UNLICENSED 且需授权(licenseRequired),仓库 wujies-im-plugin。
im 管的是会话、消息、联系人、好友申请和群聊(含入群申请)这一整套关系与消息流。
app.json 的 dependencies 为空,任何部署都能单独装;实时推送复用平台自带的 WebSocket 能力,im 自己不起长连接端点,连接地址与开关都在宿主那一侧。
README 里另有一个「全员频道」的实现约定(群号 IMCHANNEL、ensureChannelMember 懒加入、频道行 owner_user_id = 0 由系统持有、成员面板按 pageSize 200 封顶),代码里已就位,联机表现未做验证。
装它
dependencies 为空,安装顺序上 im 不挡别人,但 mall 把它列为必需依赖:商城的「联系客服」要让买家和这家店的客服在 im 里说得上话,调用的是 im 的会话与好友申请服务。凑齐完整商城时按 在部署里使用应用 给的顺序,im 装在 mall 之前。
装成功后侧栏多一个「即时通讯」,下面九项:
| 菜单 | 路由 | 需要的权限码 |
|---|---|---|
| 即使通信配置 | imSettings | im:settings:list |
| 工作台 | workbench | im:conversation:list |
| 会话管理 | conversation | im:conversation:list |
| 消息记录 | message | im:message:list |
| 联系人管理 | contact | im:contact:list |
| 好友申请 | friendRequest | im:friendRequest:list |
| 群聊管理 | group | im:group:list |
| 群成员管理 | groupMember | im:groupMember:list |
| 入群申请 | groupJoinRequest | im:group:joinRequest:list |
清单里的「即使通信配置」是菜单名原样带的一个笔误(应为「即时通讯配置」),app.json 与种子数据都按这个串发,改它会同时对不上已授权的老菜单,先记着。
配它
「即使通信配置」页写的是 sys_config 里 config_category = 'im' 的那批行,保存即生效。
公开读取由宿主的泛化端点 GET /open/im/config 负责:品牌八项(logo/favicon/name/nameEn/backgroundImage/description/copyright/icp)各占返回体的一个字段,其余 im.* 键去掉前缀原样透传,logo、favicon、backgroundImage 存的是 OSS 行 id、返回时被换成可访问 URL。
im 仓库自己不含 /open/im/** 控制器,那批键都靠这个泛化端点读。
| 键 | 默认值 | 什么时候要改 |
|---|---|---|
im.name / im.nameEn / im.description | 无界即时通讯 / Wujie Instant Messaging / 无界即时通讯系统 | 对外品牌文案 |
im.copyright / im.icp | 见种子脚本 | 对外服务填自己主体的备案号 |
im.logo / im.favicon / im.backgroundImage | 空 | 存的是 OSS 行 id,换部署后成死引用,需在本页重传 |
im.friendRequestNeedVerify | true | 关掉后加好友不用对方同意 |
im.messageRecallMinutes | 2 | 消息可撤回的时间窗(分钟) |
im.groupCreateEnabled | true | 关掉后普通用户不能建群 |
im.maxFileSizeMb | 50 | 会话内单文件上限,只能比对象存储与网关的 body 限制更严 |
用它
管理员在「工作台」看全局会话,「会话管理 / 消息记录 / 联系人管理 / 好友申请 / 群聊管理 / 群成员管理 / 入群申请」逐条查询、导出或处置。这些接口前缀 /im/conversation、/im/message、/im/contact、/im/friendRequest、/im/group,每条都挂 im:* 权限码;会话还能隐藏、置顶、免打扰,消息可代发与撤回,群里有成员管理、入群申请审批和退群。
会员在会员中心「即时通讯」(/member/im)里收发,接口走 /portal/im/**。这一层只校验登录(@SaCheckLogin),不看 im:* 权限码,每个查询都强制 ownerUserId 等于当前登录用户,因此会员只看得到自己的会话与消息;发消息、撤回、改备注、拉黑、加删好友、建群入群、退群都在这层。翻页有上限(单页 500、会话最多翻 200 页、好友申请与群搜索更严),群号限定 [A-Za-z0-9_-]{1,64}。
实时通道由平台 wujies-common-websocket 提供:im 通过 WebSocketUtils.publishMessage 投递新消息(事件类型 im.message),通过 WebSocketSessionHolder.existSession 判断对方在不在线,握手建立时宿主还会广播 im.presence 在线事件。端点路径与开关看宿主 application.yml 的 websocket.*,默认 websocket.enabled: true、websocket.path: /resource/websocket、allowedOrigins: '*'。浏览器侧连接地址形如 ?Authorization=Bearer <token>&clientid=<客户端 id>,token 与 clientid 用查询串携带(握手带不了自定义头),握手时比对 clientid 且校验 Sa-Token 登录态,对不上直接拒绝连接。这段握手行为未做联机验证,路径以部署环境的 application.yml 为准。
出问题查什么
| 现象 | 先看 |
|---|---|
| 页面能打开、消息要手动刷新才出现 | 宿主 websocket.enabled 是否为 true、前端 WebSocket 开关是否同时开着,两端不一致就只断推送 |
| 长连接握不上或反复掉线 | token 与 clientid 是否都带上且和登录时一致,allowedOrigins 是否放行当前域 |
| 会员看不到某条会话 | /portal/im/** 按登录用户过滤,本人以外的会话本就查不到,与权限码无关 |
| 加好友直接成功、没走审批 | im.friendRequestNeedVerify 是否为 false |
| 消息撤不回 | 距发送是否已超过 im.messageRecallMinutes 分钟 |
| 商城点「联系客服」报错 | mall 依赖 im,确认 im 已装并启用,见 在部署里使用应用 |
| 建群失败、群号被挡 | im.groupCreateEnabled 是否为 false;群号需匹配 [A-Za-z0-9_-]{1,64},其它字符走不进 /portal/im |
| 会话里的文件传不上 | 单文件是否超过 im.maxFileSizeMb,同时看对象存储与网关的 body 上限,取更严的那一个 |
| 装完侧栏没有「即时通讯」 | 菜单树在登录时生成,重建入口同上 |
实现索引
| 项 | 值 |
|---|---|
| 数据表 | im_contact、im_conversation、im_friend_request、im_group、im_group_join_request、im_group_member、im_message |
| 后台接口前缀 | /im/conversation、/im/message、/im/contact、/im/friendRequest、/im/group |
| 会员端 | /portal/im/**(@SaCheckLogin,无 im:* 权限码,按当前用户过滤) |
| 公开端 | 无自有 /open/im/**;站点配置由宿主 GET /open/im/config 读取 |
| 实时通道 | 宿主 wujies-common-websocket,端点为 websocket.path(默认 /resource/websocket),im 不自建 |
| 迁移脚本 | migrations/01-create-im-tables.sql、migrations/02-create-im-website-config.sql |
| 源码 | cn/wujies/im |
那七张表同时是卸载时的删除依据:AppPurgeService 从迁移脚本解析 CREATE TABLE 得到「本应用声明的表」。迁移脚本一经执行内容不可改(摘要记账见 数据库迁移),通用排查见 故障排查。