李管春做设备数据类项目时，我常被问到同一个组合：Kafka 和 Cassandra 为什么要一起用，MySQL 不够吗？还是 Kafka 存了就能省数据库？这类问题真到线上就变得很具体——你手里可能是几千个采集点，每秒上千条消息，写库不抗压、查询还要尽量快。我这套从实际项目里沉淀下来的做法，是把 Kafka 放在接入层做流量整形和缓冲，把 Cassandra 当持久化与查询底座，一条链路各司其职。这篇文章我会用设备指标上报这个案例，把 topic 设计、表结构设计、生产端消费端代码、上线后排查坑点都摊开讲，希望你看完能直接参考它设计自己的大数据接入方案。
1. 把 Kafka 和 Cassandra 串起来：这套方案到底解决了什么问题
1.1 单独用 Kafka 存数据，为什么撑不住业务查询
Kafka 本质上是一个“分布式提交日志”。它确实把消息落到磁盘上，也能按 partition 和 offset 顺序读取，但这是为了高吞吐的顺序读写，不是为了应付业务查询设计的。如果你想按设备 ID 查它最近三个月的所有记录，Kafka 没有索引、没有 TTL 级别的行删除机制，除非按分区全量扫描加过滤，否则基本拿不到高效结果。就算长期保留消息，磁盘成本也很吓人，因为你要保存同一份数据的多个副本，还要为每个分区维护一堆 segment 文件，并不能像数据库那样只留“查询需要的数据结构”。
还有一层容易被忽略的问题：Kafka 的消费者是拉模型，它的订阅、消费组、offset 机制都是为了“把消息流分发出去”，不是为了让业务系统低延迟地随机查询。业务端如果直接靠连 Kafka 做点查，那基本是把消息中间件错用成数据库，后患会集中在数据清理、历史回放和即席分析这些环节上。
1.2 单独用 Cassandra，又缺了流量缓冲和重放能力
Cassandra 是分布式宽表数据库，单集群写入吞吐很高，在良好分区模型下能线性扩展，也适合保存海量带时间特征的业务数据。但如果你让每台设备直接把数据写到 Cassandra，流量出现陡峭峰值时，所有写请求都会瞬间压到 coordinator 节点上，write path 会变得不稳定，触发 memtable 刷写、compaction 排队，甚至出现节点间的数据不同步。更麻烦的是，Cassandra 没有“消费者组”的概念，没法像消息系统那样让多个下游按自己的节奏消费同一份数据，也无法在数据写入失败后简单地重放最近一段消息。
简单说：Cassandra 擅长“存得住、批量写、按主键查”，但它不擅长“接住突发的流量并公平地分发给多个消费方”。这件事正好是 Kafka 的看家本领。把 Kafka 放在 Cassandra 前面，相当于给数据库装了一个蓄水池：洪水来了先蓄起来，下游按自己能力排洪；下游抖动了，消息还在 Kafka 里留存，可以等恢复后继续消费。这是这套组合最原始的动机，也是我推荐在接入场景优先考虑它的第一个原因。
1.3 组合的真实定位：一条可重放的流量缓冲管道加一个可横向扩展的存储底座
Kafka 在这一架构里是流动的数据管道，它关注的是“谁生产、谁消费、消费到哪了”，关心的是每条消息的实时性和分区有序性；Cassandra 是数据的落点，它关注的是“用什么主键写、用什么主键读、保留多久”，关心的是最终查询效率和集群容量。两者组合后，可以拆成三类非常常见的大数据场景：
- 实时上报类：设备或客户端先把数据写入 Kafka，Flink、Spark Streaming 或普通消费程序过来消费，做清洗、字段补全、窗口聚合后写入 Cassandra，提供给后端 API 或报表查询。
- 异步解耦类：上游业务把需要落库的数据写入 Kafka，Cassandra 作为最终数据底座，消费逻辑由专门团队维护，不拖累上游响应时间。
- 变更分发类：利用 Cassandra CDC 特性或业务触发逻辑，把数据库中的变更事件发到 Kafka，下游再同步到缓存、搜索引擎或数据仓库。
我们的设备指标项目就是第一种。后面所有细节，我都按这个案例来讲。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 一个结合案例的完整落地链路：设备指标实时上报存储
2.1 案例背景与整体数据流设计
先交代业务场景：车间里有 3000 个采集点，每台设备每秒上报一次运行指标，字段包括设备号、时间戳、温度、振动、电流等。高峰期因为叠加事件上报，瞬时流量能到每秒 4000 到 5000 条消息。业务要求：第一，能保留 180 天明细，用于设备故障回溯；第二，能随时查某个设备最近一小时或某一天的指标曲线；第三，能看到每台设备的最新实时状态。当时对比了很多方案，最后定下的数据链路是：
设备采集端 → 接入网关 → Kafka topic device_metric_raw → 流处理/消费程序做格式校验和字段清洗 → Cassandra。
接入网关只负责把设备消息包装成统一 JSON 后发给 Kafka，它不直接与数据库交互。消费程序是核心的“数据工人”，负责把 Kafka 消息转换成 Cassandra 的写入请求。整套架构里 Kafka 的消息保留时间通常设成 24 到 72 小时就够，因为 Cassandra 才是真正承载历史数据的地方，Kafka 只做临时缓冲；万一消费程序崩溃或者 Cassandra 短暂不可用，消息还能在 Kafka 中保留一段时间，等恢复后继续消费，不会因为数据库抖动就丢数据。
这里需要注意，消息链路里没有在消费程序前再加一层 Redis，也没有直接让网关写 Cassandra，就是为了避免把业务的“实时性压力”传导到数据库。Kafka 的写入吞吐量本身比 Cassandra 对突发流量的容忍度高很多，把削峰这件事放在 Kafka 这一层做，架构才不容易被瞬时流量打穿。
2.2 Kafka 中的 Topic、分区和消息格式设计
先看 topic 设计。整个项目初期只规划一个原始数据主题，优点是好管理，缺点是不同业务的数据耦合在一起。如果你的设备类型差异较大，字段结构也很不一样，我更建议按业务域拆多个 topic，比如 device_temperature_raw、device_vibration_raw 或按“设备分组”命名。但千万不要把粒度拆到“每类设备一个 topic”，那样 topic 数量会失控，broker 元数据压力和维护成本都会增加。通用原则是：先按数据类型或业务域拆，再考虑分区和 key。
生产端发送消息时，我建议把 key 设置为 deviceId。Kafka 会根据 key 的哈希值把同一种 key 的消息送到同一个分区，这样同一台设备的消息在 partition 内是严格有序的。虽然 Cassandra 本身并不依赖这个顺序，但后续如果你想做“设备的实时状态”这种语义，从同一分区消费能减少很多乱序处理的麻烦。
消息体我一开始用的 JSON，结构类似：
json复制{
"deviceId": "M-10086",
"ts": 1752537600000,
"temperature": 36.5,
"vibration": 0.08,
"current": 2.3,
"status": "normal"
}
这种格式的好处是直观、便于排查问题，设备厂商的调试人员也能直接看懂。缺点是每个字段没有 schema 约束，消息结构改了以后生产端和消费端很容易不一致。项目后期我们切换到了 Avro 格式并使用统一 schema 管理，但这是后话。如果你的团队规模不大、字段变更不频繁，先用 JSON 跑通链路没毛病，反而是 Schema Registry 这套体系的维护成本对三五个人的小团队来说有点高。
2.3 Cassandra 表结构：按查询路径而不是按关系范式设计
Cassandra 数据建模第一条铁律是“先列查询，再建表”。我们不能像 MySQL 那样建一张大宽表，然后靠各种二级索引和 where 条件去查。Cassandra 对于没有按分区键过滤的查询体验非常差，数据量一大，全表扫描基本不可用。所以这个案例里，我把业务查询拆成了三类，对应三张表。
第一张表，保存每台设备的最新状态，用于大屏展示和实时报警判断：
sql复制CREATE TABLE IF NOT EXISTS device_realtime (
device_id text PRIMARY KEY,
temperature double,
vibration double,
current double,
status text,
ts bigint
);
这里主键只有 device_id，因为我们是按设备维度覆盖写，每台设备只保留一条最新状态。Cassandra 对同一主键的插入就是 upsert，天然适合这个场景。
第二张表，保存明细数据，用于按设备查历史曲线。这里要重点考虑分区大小问题。如果只把 device_id 作为分区键，那么一台设备 180 天的数据全塞在同一个分区里，很快会达到 Cassandra 单分区容量上限，也会造成热点。我采用“设备号 + 小时桶”作为分区键，小时桶格式是 yyyyMMddHH，这样每台设备每小时最多 3600 行，单个分区很小，查询一天的数据最多拼 24 个分区，集群能轻松扛住。
sql复制CREATE TABLE IF NOT EXISTS device_metric_detail (
device_id text,
hour_bucket text,
ts bigint,
temperature double,
vibration double,
current double,
status text,
PRIMARY KEY ((device_id, hour_bucket), ts)
) WITH CLUSTERING ORDER BY (ts DESC)
AND default_time_to_live = 15552000;
第三张表，保存每小时聚合指标，用于趋势分析和日报。表结构里以 device_id 为主键，hour_bucket 作为聚类列，查询时按时间范围倒序扫描：
sql复制CREATE TABLE IF NOT EXISTS device_metric_1h (
device_id text,
hour_bucket text,
avg_temperature double,
max_vibration double,
avg_current double,
sample_count int,
PRIMARY KEY (device_id, hour_bucket)
) WITH CLUSTERING ORDER BY (hour_bucket DESC);
写这段给你看的重点是：Cassandra 的超表能力靠的是表结构映射到查询模式，而不是在查询时依赖灵活过滤。在做表设计之前，最好先列一下业务方真正要发起的查询 SQL，再逐个设计分区键、聚类键和 TTL。
2.4 分区桶大小的计算细节与选择
分区怎么切分，是 Cassandra 设计里最值得较真的环节。有人把所有用户 ID 当分区键，单个用户数据量巨大时，这个分区就变成热点，同一分区的读写性能被锁在一个节点上。有人把时间戳放分区键，又会导致每个分区只有一条数据，写入虽然能分散，但查询一次要跨无数分区，性能反而很差。
我们在案例中选的是“设备号 + 小时”组合分区键，这个判断来自容量估算：一台设备每小时最多 3600 条记录，每条 JSON 解析后放 Cassandra 一行大概 150 到 250 字节，也就是说单个分区一小时的数据量为 0.6 到 1MB 左右。这个量级对 Cassandra 来说正好处于健康区间。如果采集间隔变成每秒 10 条，一小时就变成 36000 行，单分区会到 10MB 以上，那也可以用“设备号 + 小时 + 分钟”的分桶方式；如果设备上报频率低，一天只有几百条，那可以直接用“设备号 + 天”做分区，减少查询时的分区数。总的原则是让单个分区行数控制在几万行以内，单分区数据量控制在几十 MB 以内，避免数据倾斜和读放大。
还要提醒一点：组合分区键的取值不要用时间戳本身。直接拿原始时间戳作为分区键，会让同一设备的连续时间数据分散到无数分区里，做范围查询时查询路径会非常碎，根本没法用。
3. 代码级实操：Producer 配置、Cassandra 消费写入与序列化取舍
3.1 Kafka Producer 的关键参数：别把消息发丢
数据进入 Kafka 环节后，最容易犯的错误是只写一个 bootstrap.servers 和 value-serializer 就认为完成了。实际上生产环境至少需要把几个和可靠性有关的参数设对。我给出的 Java Producer 最小可靠配置是：
java复制Properties props = new Properties();
props.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "kafka-1:9092,kafka-2:9092,kafka-3:9092");
props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
props.put(ProducerConfig.ACKS_CONFIG, "all");
props.put(ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, true);
props.put(ProducerConfig.RETRIES_CONFIG, Integer.MAX_VALUE);
props.put(ProducerConfig.LINGER_MS_CONFIG, 10);
props.put(ProducerConfig.BATCH_SIZE_CONFIG, 65536);
props.put(ProducerConfig.COMPRESSION_TYPE_CONFIG, "lz4");
KafkaProducer<String, String> producer = new KafkaProducer<>(props);
acks=all 表示 leader 和 ISR 内所有副本都写入成功后才返回成功，避免 leader 节点宕机时消息丢失；enable.idempotence=true 让 producer 发送消息时带序列号，避免网络重试造成消息重复写入。linger.ms=10 和 batch.size=64KB 是为了把多条消息攒成一个批次批量发送，减少网络往返次数和设备上报场景下的小消息。虽然加 linger 会让单条消息有最多 10ms 的发送延迟，但对设备实时监控这个场景来说完全能接受，而且能显著提升吞吐。
有个容易被忽略的注意点：开启幂等后，retries 会提升为一个很大的数，这是合理设计，因为要保证重试不会乱序、不会重复。如果你用的是旧版本客户端且 ACKS 不是 all，幂等配置会直接被拒绝，需要先厘清这些参数之间的依赖关系。
3.2 消费端为什么我建议手动提交并配合 Cassandra 幂等更新
消费端最核心的矛盾是：Cassandra 写入出现抖动时，Kafka 消费到底该不该继续 poll？如果继续 poll 并执行 Cassandra 写入，本地内存里的未提交消息会越堆越多，最终内存溢出；如果直接 commitSync 但不写库，那消息就丢了。我的选择是“单条消息立即转成 Cassandra 幂等写，批量后手动提交”，伪代码如下：
java复制while (true) {
ConsumerRecords<String, String> records = consumer.poll(Duration.ofMillis(500));
if (records.isEmpty()) {
continue;
}
PreparedStatement insertDetail = session.prepare(
"INSERT INTO device_metric_detail " +
"(device_id, hour_bucket, ts, temperature, vibration, current, status) " +
"VALUES (?, ?, ?, ?, ?, ?, ?)"
);
for (ConsumerRecord<String, String> record : records) {
DeviceMetric metric = JsonUtil.parseObject(record.value(), DeviceMetric.class);
String hourBucket = DateTimeUtil.toHourBucket(metric.getTs());
session.execute(insertDetail.bind(
metric.getDeviceId(),
hourBucket,
metric.getTs(),
metric.getTemperature(),
metric.getVibration(),
metric.getCurrent(),
metric.getStatus()
));
}
// 每条消息都执行 Cassandra 写，但 offset 按批提交
consumer.commitSync();
}
这个方案实际是“至少一次”语义：如果消费线程在 Cassandra 写入成功后、offset 提交前崩溃，重启后同一批消息会被再次消费。但因为这里对 Cassandra 的写操作是同主键覆盖写，同一主键重复执行 INSERT 不会产生多条脏数据，所以整体是幂等安全的。反过来，如果你先把一批消息提交掉，再写 Cassandra，中途失败就会丢数据，这种“最多一次”语义在设备记录场景里不可接受。
在实际项目中，我又加了 cassandra 写入失败时的熔断保护：当连续写入失败或抛出 WriteTimeoutException，调用 consumer.pause(consumer.assignment()) 暂停当前分区消费，等 Cassandra 恢复后调用 consumer.resume(consumer.assignment())。这样才能真正保护消费进程，避免无限重试把 Cassandra 压死。
3.3 PreparedStatement 复用和批量写入的坑
上面代码里我为了演示把 prepare 放在了循环内，真实工程项目里绝不能这样写。PreparedStatement 是 DataStax Driver 里可以被反复 bind 的模板，每次 prepare 都要和集群做一次查询计划协商，代价很高。正确做法是启动时准备好，循环内只用 bind。如果业务允许更激进的批量写入，可以用 Cassandra 的BatchStatement 把同一分区内的多条 INSERT 打包执行，但批次大小最好不要超过几十条，不然 coordinator 节点的压力会非常大，协调开销甚至大于写入本身。
消费端写入 Cassandra 时常犯的另一个错误是不看 Cassandra 返回的一致性级别。设备上报场景我通常用 LOCAL_QUORUM，也就是本地数据中心大多数副本确认。这样配置下来，如果 Cassandra 集群只有 3 个节点、RF=3，那么每次写入需要至少 2 个副本确认。适当降低一致性到 LOCAL_ONE 能换来延迟下降，但同机架节点故障时可能丢数据；写指标明细时我更偏保守，优先保证不丢。
3.4 消息格式从 JSON 演进到 Avro 的时机
小规模跑通时用 JSON 是完全可以接受的。但一旦多个消费端团队开始消费同一个 topic，而且需要添加字段、废弃字段，JSON 的弱点就暴露出来了：老消费端不感知新字段还能忍受，最怕生产者把某个字段从字符串改成了数字，下游解析直接报错却没人能提前发现。如果你预见到这个 topic 会被多个系统长期使用，建议尽早引入 Avro。Avro 配合 schema registry 之后，生产端和消费端都只维护一个 schema 地址，字段演进通过兼容性规则来控制。代价是你需要额外维护 schema-registry 组件，调试时也不能直接打开一条原始消息看内容，需要先解码 schema。我给团队的建议是：项目原型期和字段非常稳定的内部 topic，用 JSON 没问题；要对外提供数据或跨团队共享数据时，尽快迁到 Avro。
4. 上线后我反复踩到的组装坑：从元数据拉取失败到消费延迟飙升
4.1 Docker 里跑 Kafka 报 fetch metadata 错误，99% 是 advertised.listeners 的问题
把 Kafka 装进 Docker 后，开发机上的 Java 程序连接时经常会报：
text复制Error while fetching metadata with correlation id 3 : {device_metric_raw=LEADER_NOT_AVAILABLE}
第一次碰到时，很多人以为是 broker 没起来，不断重启容器，结果还是一样。问题核心出在 Kafka 的监听地址和客户端可见地址不一样。在容器里，broker 会把 localhost:9092 或者 kafka:9092 作为 advertised listener 广播给客户端。如果客户端跑在宿主机上，它拿到 kafka:9092 后当然解析不了这个主机名，元数据拉取失败或者连接超时就是必然的。
单机用 Docker Compose 起一个 KRaft 模式 Kafka 做测试，一种比较可靠的配置是这样：
yaml复制version: "3.8"
services:
kafka:
image: apache/kafka:3.8.0
container_name: kafka
ports:
- "9092:9092"
environment:
KAFKA_NODE_ID: 1
KAFKA_PROCESS_ROLES: broker,controller
KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093
KAFKA_LISTENERS: PLAINTEXT://:9092,CONTROLLER://:9093
KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT
这里的关键是把 KAFKA_ADVERTISED_LISTENERS 设成客户端实际能访问到的地址。宿主机上的代码访问就写成 PLAINTEXT://localhost:9092，如果客户端也要在其它容器里访问，那就把容器服务名也写成一个 listener。看到 fetch metadata 报错时，先别急着翻连接代码，在客户端机器上执行 telnet 目标地址 9092，能通基本就成功了一半。
4.2 cluster authorization failed 和 JAAS 配置问题
消息中间件一旦开了 SASL 认证，报错就变得五花八门。最常见的两个是：
- producer 发送时报
cluster authorization failed； - 应用启动时报
no service name defined in either JAAS or Kafka config。
cluster authorization failed 不是密码错误，而是客户端发起的集群级操作没有权限。比如普通用户尝试创建 topic、查询集群信息，或者没有对目标 topic 的写权限时，就会收到这个错误。排查时先确认代码里用的账号是不是配置了 ACL。用 kafka-acls 工具加一条写权限：
bash复制kafka-acls.sh --bootstrap-server kafka-1:9092 \
--add \
--allow-principal User:device_app \
--operation Write \
--operation Describe \
--topic device_metric_raw
另外还要允许 Write 到事务 ID 相关的内部 topic，如果开了幂等或事务模式的话。否则 producer 也会在初始化阶段被拦。
第二个报错是客户端缺少服务名配置，通常出现在与非 Kafka 使用 SASL_PLAINTEXT 或 GSSAPI 时。检查 sasl.jaas.config 里是否写对了 serviceName，同时在 broker 端也要明确 listener.name.sasl_plaintext.sasl.kerberos.service.name。这类配置项很容易在从测试环境复制到生产环境时漏掉，建议把生产配置模板化，用配置中心统一管理。
4.3 Kafka 消息延迟高，但先别急着调并发参数
消息延迟高是整个链路里最模糊的症状，可能来自 Kafka 本身，也可能来自 Cassandra。我排查时一般按这样的顺序推进：
先看消费者的 Lag 分布。执行：
bash复制kafka-consumer-groups.sh --bootstrap-server kafka-1:9092 \
--group device_metric_consumer --describe
如果 Lag 在所有分区上都不均匀，比如某个分区明显落后其他分区，优先怀疑 key 分布有问题，大量设备的数据集中在少数几个分区。解决办法是重新评估 key 划分，或者把 topic 分区数增大后重发消息，但这个动作成本很高，所以一开始规划分区时就要想清楚设备量级。
如果所有分区 Lag 都差不多，Lag 还在持续增长，那就要看 Cassandra 侧。在 cqlsh 里执行：
bash复制nodetool status
nodetool compactionstats
nodetool tpstats
如果 Cassandra 节点的 pending tasks 很高，说明写入压力已经超过数据库处理能力。这时不要盲目调大消费端的 max.poll.records，因为这会增加单批写入的堆积时间，反而让 Cassandra 压力更大。正确做法是回头检查表结构是否合理、compaction 策略是否正确、每秒写入量是否达到节点瓶颈。只有确认 Cassandra 健康，才应该调整 consumer 的并发线程数、分区数或批量大小。
还有一类原因很隐蔽：消费端业务代码里做了耗时的外部调用，比如每次消息都要去远端接口补充设备信息。这样处理能力会从单线程几千条降到几十条。哪怕 Cassandra 配置再好，业务逻辑慢一样拖垮消费，这种问题只有通过链路追踪才能定位到。
4.4 重复消费后，Cassandra 表还能保证数据正确吗
Kafka 因为网络分区、消费者组 rebalance、提交失败等原因造成重复消费，是常态。很多人一听到重复，第一反应是想上 Kafka 事务实现精确一次。但事务机制在“Kafka 到外部数据库”这种跨系统写路径里并不能真正实现端到端恰好一次，因为 Kafka 事务只能保证它自身 topic 的原子性，不能和 Cassandra 的写入合并成一个分布式原子事务。强行用事务只会带来大量吞吐损失。
工程上更实用的做法是接受“至少一次”，然后用幂等写来兜底。这个项目里，明细表的主键是设备 ID、小时桶和时间戳，消费端重复执行同一条 INSERT，最终数据还是一行，幂等没有问题。如果你在 Cassandra 里做的是计数器类累加字段，那就要非常小心了，重复消费会把 count 和 sum 算两次。我建议把需要精确计算的指标放到每小时聚合表里，聚合任务从明细表中重新计算后覆盖写入，而不是在消费每条明细时直接递增聚合字段。这样即使重复消费，也只是多触发几次重算，最终写进 Cassandra 的结果是一样的。
5. 压测与容量规划：分区数量、副本因子和压缩策略怎么配套调整
5.1 Kafka 分区数不是越大越好
关于分区数，业界流传着一些“分区数等于 Broker 数乘消费并行数”的说法，但真正的核心逻辑是：Topic 并行消费的能力上限就是分区数，每个分区同一时刻只能被一个消费者线程消费。如果你的消费端计划开 4 个线程并行处理，那 topic 至少要有 4 个分区，否则必然有线程空闲；如果单分区每秒能消费 5000 条，而你业务峰值只有 1000 条每秒，那 4 个分区已经非常富裕，没必要设置成 100 个。
分区数过多会带来哪些问题？第一，Kafka 的元数据要跟踪每个分区的 leader、ISR 状态，分区数量过大会加重 broker 负载；第二，consumer group rebalance 时，所有成员要重新分配分区，分区数越多，分配时间越长，期间会有短暂不可消费；第三，每个分区的文件句柄、内存缓冲都是开销，几百个分区在你这个小集群上纯属浪费。
再做一个基于实际场景的估算：3000 设备每秒各上报一条 JSON，消息大约