layababa 问题全清单

接线 X-01 关链抛成 RATE_LIMITED

现状： refuseWithoutNewChainOwner 在没有热私聊 / MQ06 owner 时硬拒，抛 ErrorCode.RATE_LIMITED（retryable=true）。Flutter 发送/mutation 重试对该码固定 5s 泵，outbox 不结束。出厂 IMCORE_HOT_PRIVATE_ENABLED=false。首页仍写「5 分钟跑通第一条消息」，发送步不提好友门和三代旗。好友策略 requireCanSendPrivate 要求互为正式好友。

可能的 bug / 代价： 接入方按默认 compose 发第一条，看到「操作过于频繁」，永远重试同一 clientMessageId。关链、未互加、真 429 三种失败长得一样。旗已打开的生产栈不容易撞，新接入 / 评测栈必撞。

修复思路： 专用非 retryable 码 + hostAction=去开旗；客户端对该码 terminal。文档改成：先互加、且旗已开。不要默认开链，不要把容量满并进新码。

参考： Tinode {ctrl 503}；Turms CLIENT_REQUESTS_TOO_FREQUENT；JuggleIM server-api-quickstart.sh 先互加再发。

接线 MSG-02 WS 漏接 ConfirmUnknown

现状： REST MessageController.sendPrivate 已把 HotPrivateConfirmUnknownException 收成 HTTP 200 + SERVER_CONFIRMING。该异常是 RuntimeException。WS wsPrivateMessage / handleV4 只稳接 BusinessException，其余变 INTERNAL_ERROR。ChatPersistedAck 会被 Flutter mergeAck 当成 VISIBLE。PREPARED 仍挡住第二条 seq。

可能的 bug / 代价： broker 抖动或 5s confirm 超时：客户端以为发送失败或已经可见。排障合同假。HTTP 兜底能救一部分，默认传输却先走 WS。

修复思路： 只在 wsPrivateMessage 对齐 REST：带 state，禁止无 state 的成功 ack。不要改 REST 200 合同。

参考： 仓内架构合同 4.1、Q474；对照文 hop H7。

语义 MSG-04 MQ01 先 VISIBLE 再落 Mongo

现状： prepare 先占 seq → confirm → markVisible → 回执带 seq，日志 mongo=pending。落库是 HotPrivatePersistenceConsumer.persistBody。gap-repair 跳过 hot-owned seq。DI-002 仍暂缓。

可能的 bug / 代价： ack 之后、persist 之前杀 im-core：发送方握着 seq，history 可能没有，补洞也不烧这条。对端若已扇出，一边看见一边拉不到。

修复思路（二选一，都不是一跳）： 像 MQ06/Tinode 那样耐久后再回 VISIBLE；或让 v3_sync / gap-repair 能读 Redis 热序号。不要偷偷改，这是全体私聊 ack 语义。

参考： Tinode Save 后再 {ctrl 202 params.seq}；MQ06 persist+outbox 同事务再 ack。

合同冲突 MSG-03 重连每会话只拉一页

现状： shouldDrainHasMoreDuringReconnectBatch 恒 false（FEX-034）。最多 50 会话 × 一次 v3_sync。打开会话才 drain（FEX-027）。列表预览靠 REST 刷新。群 signal 超前另走群同步。新设备登录推送只 toast。

可能的 bug / 代价： 长离线群积了远超一页，重连后未点开的会话正文不齐，用户以为丢了。这是故意限流，不是漏写循环。

修复思路： 若要改，先废/改 Q031「登录不得下全量、one-shot 不是全量同步」，再立项带阈值的 drain。不要当漏接线修，否则和 30 天 COLD 打架。

参考： OpenIM 连接后 GetMaxSeq 再按区间拉；Tinode since 拉到 count 控制帧。

协议债 MSG-05 两套同步合同

现状： WsV3SyncResponse 有 skippedSeqRanges；WsConversationSyncResponse 只有 safeCursor/hasMore。重连批量开关默认关。V4 通道里仍叫 v3Sync。

可能的 bug / 代价： 打开会话、重连、群 signal 三条路径的「洞」语义不一致，排障要对三份协议。

修复思路： 对外收成「每会话 maxSeq + 闭区间」。实现上可以两套，合同不能两套。

参考： OpenIM 一条 GetMaxSeq 打天下。

待核 MSG-06 缺口检测先抬 knownMax

现状： ImMessageGapDetector.checkMessage 在 newSeq>knownMax+1 时先把 knownMax 抬到 newSeq，同时报 missing 并走 repairLiveForwardGap（≤100 走 v3_sync，否则一页降序 query）。

可能的 bug / 代价： 若 repair 失败或只修了一截，中间号再也进不了检测器。复核认为「已回报 missing」所以不是漏修——失败路径仍可能丢洞。

修复思路： 先核对 repair 失败时 knownMax 会不会回滚。不要为了对齐 OpenIM 重写检测器。

参考： OpenIM 每条推送重算 lastSeq==synced+count。

多端 MSG-07 私聊没有通知再拉；空会话无 ledger

现状： 私聊与普通群 ChatFanoutPush 全文。TCP 写前才 registerAttempt PENDING。空会话从未建账本。写失败不回滚已 persist，靠工人重试（有 ledger 时）。

可能的 bug / 代价： 未打开、多端、写失败的私聊没有「先占序号再轻量通知」。空会话失败只能等以后打开再 sync。

修复思路： 可先在多端/未打开上复用超级群信号，不要再抄一套 OpenIM 全网关推全文。

参考： 野火先 insertUserMessages 再 QoS0 Notify。

多端 MSG-08 群扇出不含发送方其他设备

现状： MQ06 消费时 visibleGroupMembers 减发送方。发送方其他端靠自己的发送回执/出箱，不靠直播扇出。

可能的 bug / 代价： 主叫第二台设备可能看不到自己刚发的群消息，直到打开会话同步。这是刻意 recipient-only，改它会动证据模型。

修复思路： 若产品要「我的其他端实时看见」，应单独加发送方多端回推，不要把发送方塞进收件人集合凑数。

参考： OpenIM IsSenderSync；野火 exceptClientId 仍通知其他 session。

接线 RTC-01 新邀请偷走旧铃

现状： CallSessionManager.create() 先 replaceRingingSession，把双方已有 RINGING CAS 成 CANCELLED/REPLACED，再 occupy。CALL_BUSY 只挡 ANSWERED 且心跳还在。单测断言第二路 create 成功。

可能的 bug / 代价： A 打给 B 正在响，C 再打，A 的铃被静默替换。产品「对方忙」在振铃阶段不成立。这是日常路径。

修复思路： RINGING 占用直接抛已有 CALL_BUSY。不加 BUSY 状态，不重做双 key。

参考： JuggleIM grab 对 Outgoing/Connecting/Connected 回 16103；2026-07-05 稿 SETNX 即忙。

卫生 RTC-02 一对一终态不拆 TRTC 房

现状： 会议/直播终态已 enqueueDismissRoom。CallService.hangup / forceEndDisconnected / 振铃超时只出信令、卡片、话单。客户端会 exitRoom。

可能的 bug / 代价： provider 房间残留到 TRTC 空房超时。DismissRoom 不使 UserSig 立刻失效；振铃超时无人进房，接线接近空操作。主要是配额/控制台卫生，不是用户还停在通话里。

修复思路： 终态调用已有端口。不要换媒体栈。

参考： 仓内 MeetingTerminalService / BroadcastService.end。

长会 RTC-03 refreshAfter 不算换票

现状： 服务端按半 TTL 算 refreshAfter。Flutter 只解析。一对一 renewCredential fetch 后丢结果；直播 renew 空实现。真换票要对已进房 TRTC cleanup+re-enter+generation。

可能的 bug / 代价： 业务面仍 ANSWERED/LIVE，媒体静默鉴权失败。Call TTL=86400、通话上限 4h 时一对一几乎撞不到；直播更长会撞。

修复思路： 有真实长直播再立项整条续签。不要只挂 Timer 假装续上。Q395：缺长会数据先别拍。

参考： 对照文「发证时机 + 世代换票」，不是 Janus iceRestart。

政策 RTC-04 主持失联后房间仍 LIVE

现状： repairPresence 在 hostGrace（默认 120s）后只 markLeftIfActive，注释写明观众扫描永不自动结束主持房。不入队 DismissRoom。end() / transferHost 端口都在。LIVE-01 禁止 viewer sweep 隐式 end host。

可能的 bug / 代价： 观众停在没有发布者的 TRTC 房，直到有人点结束。运营看到一直 LIVE 的空房。

修复思路： 不能直接调人工 transferHost（要在场 admin）。应对齐会议「无发布者截止 + 系统角色」：到期转交在线管理员，否则 ENDED+拆房。一刀 end 会误伤连麦。

参考： 会议空房 emptyRoomDeadlineAt；essay「最后一名发布者消失必须终态」。

并发 RTC-05 连麦先数再写

现状： approve 先 count(isOnMic)>=4 再 viewer CAS。CAS 不管房间席位。没有 onMicCount 字段。

可能的 bug / 代价： 两管理员在麦=3 时同时批，可发出第 5 张 CALL_PUBLISH，TRTC 会进房。窗口窄。

修复思路： 房间文档 onMicCount<4 的 findAndModify，失败回滚。这是新账本，覆盖上/下麦/离场/关播。

参考： 对照文映射的房间级 CAS，不是 Janus publisher 上限。

控制面 RTC-06 连麦邀请只 push

现状： inviteLinkMic 只推送，无耐久行、无 TTL。accept 不依赖未过期邀请行。

可能的 bug / 代价： 推送丢了、过期了，对面仍能上麦。控制面没有「这张邀请还在不在」。

修复思路： 做成带 TTL 的邀请行，accept 必须读到。可和 RTC-05 并成连麦控制面一单。

参考： 一对一振铃 Redis 截止；JuggleIM Incoming 行。

多实例 RTC-07 主持 60s grace 在堆上

现状： MeetingKernel.pendingModeratorStaleGraceUntil 是进程内 ConcurrentHashMap。网关 EXPECTED_INSTANCE_COUNT=1。

可能的 bug / 代价： 现在单实例几乎不痛。一旦多实例或进程重启：宽限丢失，可能双断或跳过等待。

修复思路： 上多实例时再迁 Redis 心跳键。现在单独做是过度开发。

参考： 振铃截止已在 Redis ZSET。

SLA RTC-08 onRemoteLeft 立即挂断

现状： onRemoteLeft 立刻 finish+hangup。TRTC adapter 对短暂离房有约 10s soft-leave。connectionLost 标 recovering。心跳任务只扫 calling 活跃（TTL 30s）。

可能的 bug / 代价： 超过 soft-leave 的闪断会变成双方挂，话单 COMPLETED。若改成等 30s 心跳：会撤已写的约 10s 反僵尸，且「只离 TRTC、WS 还在」心跳看不见，可能挂死。

修复思路： 先改超时 SLA 文档，再改代码。不要既要 10s 反僵尸又要等心跳。

参考： JuggleIM 接通后等 ping（不要抄它记 Complete）。

状态机 RTC-09 没有 Connecting

现状： RINGING → ANSWERED 就开 30s 心跳。进房慢靠加 TTL 补。没有 MEDIA_CONNECTED。

可能的 bug / 代价： 接听后进房慢，心跳当对端断网。TTL 从 10s 加到 30s 是补丁不是结构。

修复思路： 进房完成前状态不允许心跳杀。纯改进，别和 RTC-01 捆一起。

参考： JuggleIM Incoming/Outgoing/Connecting/Connected。

产品 RTC-10 无 CallKit / 独立 VoIP

现状： 无 PushKit、无独立 voip token。野火是对照里证据最全的一套。

可能的 bug / 代价： iOS 杀进程/锁屏后来电容易漏或慢。不是信令状态机 bug，是系统来电能力缺口。

修复思路： 单独产品里程碑，不要塞进「吸收开源 IM」。

参考： 野火 PushKit + 前台服务；Tinode 形状对但仓库里 FIXME。

文档 DOC-01 通话设计稿过期

现状： 2026-07-05 稿仍写 BUSY 状态、邀请就发双方 UserSig。实现是邀请 mediaReady=false、无 BUSY 状态、振铃可被 REPLACED。

可能的 bug / 代价： 评审按旧稿打架，会把 RTC-01 修歪。

修复思路： 随 RTC-01 改稿，删邀请发证和 BUSY 状态。

接线 OPS-04 聚合 health 当发布闸

现状： readiness 组已排除可选 OSS。客户手册和 server-deploy.yml 仍 curl /actuator/health 与 /api/health，非 2xx rollback。#620：上传 200、聚合因 cdnOssProvider DOWN 变 503。

可能的 bug / 代价： 消息面已通，发布失败回滚；或为过闸关掉真依赖探针。

修复思路： 改绑 /actuator/health/readiness。不上 Prometheus 产线。

参考： Rocket.Chat /readyz；dev-example 已有部分绑 readiness。

SKU OPS-01 默认最重且拒发

现状： 源码 compose：Mongo rs0 单成员 + Redis 主从 + Rabbit + 8 JVM。旗默认关。不交运行时镜像，客户 20 个 Maven 自建 8 张。Spring starter 评估形态能开链、单 JVM，但不是官方默认。

可能的 bug / 代价： 按生产 SKU 跟文档走，第一条消息发不出去（叠 X-01）。自建是天级。

修复思路： 要你拍：embed/评测 profile 是否写成官方首条路径。八单元留生产。不是当晚拆微服务。

参考： Tinode single-instance 能发、cluster 加法；JuggleIM 一进程+MySQL。

文档 OPS-02 无首条脚本，quickstart 漏好友

现状： 首页五步直达发送。Core 发送步没有互加好友。无私有仓外可跑的断言脚本。

可能的 bug / 代价： 文档路径结构上走不通，再叠限流码，排障一天。

修复思路： 和 X-01 同一单：文档步骤 + 可选仓内脚本（开旗、互加、发一条、断言非 RATE_LIMITED）。

参考： JuggleIM server-api-quickstart.sh。

文档 OPS-03 灾备页旧服务名

现状： 恢复/回滚页和 release.py pin 仍列 bot-server / im-media-service。运行时已并入 im-core / open-service。

可能的 bug / 代价： 按页 stop 会停不存在的服务或拉错镜像。compose 未知服务名会报错，不是静默。

修复思路： 改名单。不要趁机上备份演练门禁。

已知债 OPS-05 网关钉死单实例、无排空

现状： REALTIME_GATEWAY_EXPECTED_INSTANCE_COUNT=1，内存 session registry，禁止 memory 多实例。滚动踢全部套接字。八单元文档写成最根本的债。

可能的 bug / 代价： 每次发网关，全员掉线再重连。不是「高可用没抄好」，是连接平面还没做。

修复思路： 独立连接平面项目（注册表外置、排空、再谈 N=3）。不要从 Tinode cluster.yml 直接抄进现在的单例网关。

参考： Tinode 三节点 + 少数派拒写；OpenIM 全网关广播不依赖粘滞。

已知债 OPS-06 跨节点默认关，好友投递账本在本地盘

现状： CROSS_NODE 默认 false。好友投递 ledger 在节点本地卷。只 restore Mongo 不还该卷会分裂。

可能的 bug / 代价： 多网关时投递账对不上。灾备漏卷。

修复思路： 跟 OPS-05 一起。备份命令已提到该卷，恢复清单要写进同一时间戳。

拍板 OPS-07 Redis 从库挂则不能写

现状： min-replicas-to-write 1 + 热私聊耐久副本。从库挂 → NOREPLICAS，全站写拒绝。有专门降级 runbook。

可能的 bug / 代价： 用耐久买来的「一挂全挂」。设计如此，不是漏配。

修复思路： 保持则演练 runbook；若要可写降级，必须和 IMCORE_HOT_PRIVATE_DURABILITY_REPLICAS 一起改，并接受可见消息可能丢从库副本。

参考： docs/operations/redis-replica-failure-degradation-runbook.md。

合同 OPS-08 无多活、无演练 restore

现状： 对外页已写：单机 Mongo/Redis/Rabbit、单副本应用；跨区/多活/零停机/备份演练未验证。备份是命令骨架，无 cron、无演练门禁。

可能的 bug / 代价： 机房故障没有第二写站点。不是文档撒谎，是能力没有。

修复思路： 继续对外诚实。不要为了对照 Turms README 上「多活」去堆假集群。

参考： Rocket.Chat 从第一天 Mongo 副本集（可单成员）当踏脚石；没人给过演练收据。

交付 OPS-09 不交镜像、客户自建 8 张

现状： 官方交付 Flutter pub + Maven jar。deploy-v* 无镜像层。这是 2026-08-11 已拍板。

可能的 bug / 代价： 接入重。不是缺陷，是交付形态。列在这里以免对照时被说成「漏了 Docker 官方镜像」。

修复思路： 不改除非重新拍板交付面。