必须在声明队列时设置x-single-active-consumer=true，不可动态修改已存在队列的该属性，否则报错“声明的队列的和server上的队列不一致”，需删除重建队列。
必须在声明队列时设置 x-single-active-consumer=true，且不能对已存在的非 SAC 队列动态修改——否则会报错“声明的队列的和 server 上的队列不一致”。
创建队列时必须传入参数 x-single-active-consumer=true
这个参数不是消费者端的配置，而是队列级别的声明属性。它只在 queueDeclare 或 Queue 构造时生效，之后无法变更。
- Spring AMQP 中，需通过
Queue构造器传入arguments：new Queue("my.queue", true, false, false, Collections.singletonMap("x-single-active-consumer", true)) - 原生 Java Client：
channel.queueDeclare("my.queue", true, false, false, args)，其中args.put("x-single-active-consumer", true) - 命令行或管理界面创建队列时，需在
Arguments字段手动添加键值对：x-single-active-consumer = true（注意值是布尔类型true，不是字符串"true"）
多个消费者连接后，只有第一个能真正收消息
启用 SAC 后，RabbitMQ 会主动拒绝后续消费者的 basic.consume 请求（除非当前活跃消费者断开），你能在管理界面看到队列状态标有 SAC，且只有一个消费者显示为 single active 标签。
RabbitMQ 4.2.3
下载
RabbitMQ 4.2.3 是 2026 年初发布的重要稳定更新版本，重点修复了 Khepri 元数据存储相关问题，并改进了监控性能。对于使用 Docker、Kubernetes 或微服务架构的开发团队来说，该版本兼容性和稳定性表现较好。
- 消费者掉线（如网络中断、进程退出）后，RabbitMQ 会在几秒内自动将下一个等待中的消费者提升为活跃态，无需人工干预
- 如果所有消费者都断开，队列进入“无活跃消费者”状态，新消息会堆积，但不会丢失
- 不要依赖客户端重连逻辑来“抢占”活跃权——SAC 的切换完全由 broker 控制，客户端无法主动申请成为活跃消费者
常见错误：改不了已有队列的 SAC 属性
这是最常卡住开发者的点：RabbitMQ 不允许修改已存在队列的 x-single-active-consumer 值。哪怕只是从 false 改成 true，也会触发 PRECONDITION_FAILED 错误，附带错误信息：DEPRECATED: queue x-single-active-consumer attribute mismatch 或类似提示。
- 唯一解决办法是删除旧队列再重建（确保消息已消费完，或已配置死信/备份机制）
- 生产环境切勿直接
auto-delete或设durable=false来规避——这会导致消息丢失 - 上线前务必确认队列名未被其他服务复用；重命名队列是最安全的迁移方式，例如从
user.event.queue改为user.event.queue.sac
真正要注意的不是“怎么开”，而是“什么时候必须开”：SAC 本质是用消费吞吐换顺序保障，它会让所有消息串行经过单个 TCP 连接，网络延迟、GC 暂停、业务处理阻塞都会直接拖慢整体速率。如果你的场景只需要同 key 消息有序（比如同一个订单 ID 的增删改），更推荐按 key 分队列 + 每队列配 SAC，而不是把所有消息塞进一个 SAC 队列。
