消息基础概念
消息系统将事件的生产与处理解耦。Broker 存储并提供消息，客户端发现路由并维护消费进度。选择 API 前，先用以下概念理解数据位置、进度与故障。
主题、队列与消息
主题 是逻辑消息流，例如 DocsFirstMessage。一个 主题 可以在一个或多个 Broker 上具有多个消息队列。消息队列由 主题、Broker 和 队列 ID 标识，偏移量只在该队列内部有意义。Broker A 的队列 0 与 Broker B 的队列 0 不是同一个序列。
消息包含正文，以及 Tag、Key、属性等元数据。Tag 用于订阅过滤；Key 可以用于消息定位或承载应用标识。Tag 和消息 Key 都不会自动实现业务去重。
以订单创建事件为例：正文携带事件，主题 归类事件，应用业务标识让下游数据库识别重复处理。Broker 消息 ID 有助于诊断，但不应代替明确的业务幂等策略。
生产者组 与 消费者组
生产者 查询可写队列并发送消息。生产者组 标识生产者上下文，事务消息还具有专门的分组和回调要求。除非应用有意协调，发送调用与本地业务事务仍是两个操作。
消费者组 表示消费订阅和进度身份。在集群消费模式中，同组消费者通过队列分配与协调分担工作。另一消费组可以独立消费同一 主题。因此，向已有组增加消费者，与为每个消费者设置新组名，是两种不同的行为。
同一组内保持订阅一致。只修改某个成员的 主题、过滤器或消费模式，可能造成意料之外的投递或协调行为。广播是独立模式，其进度和重试假设也不同。
路由是元数据，不承载消息正文
NameServer 接收 Broker 注册并回答路由查询。客户端使用返回的 Broker 地址与 Broker 通信，消息正文不经过 NameServer。
Broker 公布的地址必须能被客户端访问。容器可能成功注册一个私网地址，而主机客户端无法连接。只检查 NameServer 端口无法诊断这第二跳。
消费位置与确认
| 概念 | 含义 | 不能证明什么 |
|---|---|---|
| 队列偏移量 | 单个队列序列中的位置 | 所有队列之间的全局顺序 |
| 消费位置 | 消费者读取或本地推进的位置 | 进度已持久提交到共享保存位置 |
| 已提交偏移量 | 供后续恢复使用的消费进度 | 与应用数据库事务原子提交 |
| 发送确认 | Broker 按配置写入策略返回的结果 | 所有消费者都处理了事件 |
| POP receipt/ACK | 一次 POP 投递的凭据与完成确认 | 与普通 LitePull 偏移量提交相同 |
LitePull 手动提交应在整批业务处理成功后记录进度。如果业务写入成功后、进度记录前进程失败，事件可能再次处理。先提交则产生相反窗口：业务未成功，进度已经前进。
ConsumeFromFirstOffset 是初始位置策略，不会在每次重启时清空已有组的进度。复用消费组通常会从已有位置继续。
顺序、重试与延迟投递
顺序保证取决于维护它的队列和处理模型。多个队列提供并行度，不形成全局单一序列。重试可能延迟后续处理或产生重复，具体取决于所选模型。
延迟投递要求系统稍后让消息可用，不保证业务一定在精确的时钟瞬间执行。消费调度、负载和故障仍会影响处理时间。
任何模型都应区分“已接纳”“按策略持久化”“读路径可见”“已投递”“业务处理完成”。投递与重试进一步解释这些边界。
在教程中使用这些概念
第一条消息教程使用一个 主题、一个明确的消费组和 LitePull 手动提交。排查网络前，先确保两端名称一致。首次诊断按进程配置、主题 元数据和消费进度依次定位。