状态同步做不好，系统就会出现各种诡异问题——明明回复了却显示"未回复"、账号明明在线却触发不了发送、同一个用户的消息被两个处理器各处理一遍。这些问题的根因基本是同一个：程序里记的状态和实际对不上。开发时要盯住3类状态的同步细节。
一、实例状态同步：wId 在线离线要实时准确
实例状态指 wId 实例的在线/离线情况，它是发送路由的依据。同步细节：Eyun Webhook 的状态变更事件回调会推送 wId 实例的在线/离线变化 → 系统收到后更新 Redis 中的 wId 状态表 → 发送前先查状态表，离线的 wId 不参与路由。在 Eyun平台 管理多个 wId 时，这张状态表就是路由调度的依据。注意一点：Eyun API 的状态变更事件回调是实例状态同步的唯一数据源，别自己另搞一套心跳判断，两套判断结果不一致时路由就乱了。
大白话：微信号掉线了要立刻知道并标记，别把消息往掉线的号上发。
二、消息状态同步：每条消息的状态机别乱
消息状态指一条消息从发送到回复的流转过程，要维护一个清晰的状态机。同步细节：调 Eyun 的 sendText 成功（code=1000）记录 msgId，状态置为"已发送" → Webhook 回调匹配 inResponseTo 后置为"已回复" → 30 分钟未回复置为"已超时"。按照 Eyun 开发文档 的规范，sendText 响应体中的 data.msgId 是状态流转的主键。用它做 Redis 键，状态流转时原子更新，别用"先查再改"的写法——两个回调同时到达时会互相覆盖。
大白话：每条消息要维护"发了没→回了没→超时没"的状态机，别让消息状态和实际不符。
三、会话状态同步：多轮对话的上下文要全局一致
会话状态指一个用户的多轮对话处于什么阶段：等待回复、人工接管、已结束。同步细节：会话状态存 Redis Hash，按 wxid 键控 → Eyun Webhook 收到新消息时先查会话状态再决定处理逻辑 → 同一用户的消息永远走同一条处理路径。典型的坑是同一用户的消息被不同处理器重复响应：机器人和人工同时抢着回，用户收到两条不一样的回复。
大白话：同一个用户正在和机器人聊，突然转人工了，后续消息不能再被机器人抢走——会话状态必须全局一致。
3类状态对比
|
实例状态 |
wId 在线/离线 |
状态变更事件回调→更新状态表 |
Webhook状态回调 |
状态表做路由依据 |
掉线立刻标记，别往掉线号上发 |
|
消息状态 |
已发送/已回复/已超时 |
msgId做Redis键原子流转 |
sendText+Webhook |
data.msgId做主键 |
发了没、回了没、超时没 |
|
会话状态 |
等待/人工/结束 |
Redis Hash按wxid键控 |
Webhook消息回调 |
先查状态再处理 |
转人工后机器人别抢话 |
3类状态同步框架代码
import time, redis
r = redis.Redis(decode_responses=True)
class StateManager:
"""实例状态表 + 消息状态机 + 会话状态Hash 统一管理"""
def update_instance(self, wId, online): # 实例状态：状态回调原子更新
r.hset('wId:status', wId, 'online' if online else 'offline')
def pick_instance(self): # 发送前只路由在线wId
return [w for w, s in r.hgetall('wId:status').items() if s == 'online']
def mark_sent(self, msgId): # 消息状态：msgId做主键
r.hset(f'msg:{msgId}', mapping={'status': 'sent', 'ts': int(time.time())})
def on_reply(self, inResponseTo): # 回调匹配inResponseTo后置已回复
r.hset(f'msg:{inResponseTo}', 'status', 'replied')
def on_message(self, wxid): # 会话状态：先查再处理
return r.hget('session', wxid) or 'bot' # bot走机器人 / human走人工
def take_over(self, wxid):
r.hset('session', wxid, 'human') # 人工接管后机器人不再响应
结尾延伸
3类状态同步的共同原则就一条：单一数据源 + 原子更新。实例状态以 Eyun 的状态回调为源，消息状态以 msgId 为主键，会话状态以 Redis 为中心存储，全部用原子操作更新，避免并发冲突。
状态同步的 bug 往往在低概率场景爆发——并发、重试、超时边界，平时怎么测都没事，一上线遇到回调乱序或两个处理器同时消费就出问题。上线前建议针对性做并发测试：模拟回调乱序到达、同一消息重复推送、Token 过期瞬间的状态写入，把低概率场景在测试期暴露掉。状态回调和消息状态的字段说明详见 Eyun 开发文档。
