文档中心

消息队列 Kafka版

Topic 管理

创建 Topic

Topic（消息主题）是同一种类型消息的集合，是消息队列 Kafka版中数据写入操作的基本单元。本文档介绍创建单个 Topic 的操作步骤。

背景信息

在实际业务场景中，一个 Topic 常被用作承载同一种业务流量，由开发者根据自身系统设计、数据架构设计来决定如何设计不同的 Topic。每个 Topic 可以有多个生产者向它发送消息，也可以有多个消费者去消费其中的消息。

分区（Partition）是 Topic 在物理上的分组，每个 Topic 可以划分为多个分区，每个分区都是一个有序的队列。创建 Topic 时需要指定分区数量，但是随着业务流量的增长，也可以随时增加 Topic 的分区，扩展 Topic 承载业务流量的能力。

消息队列 Kafka版通过自动创建 Topic 的功能控制 Kafka 实例支持的 Topic 创建方式，该功能默认为关闭状态。

关闭时，只能通过控制台创建 Topic。

开启时，不仅可通过控制台创建 Topic，还可以在生产消息时直接指定数据写入一个不存在的 Topic，此时 Kafka 后端服务会自动为您创建此 Topic。

说明

每个规格的实例均提供一定额度的分区数量范围与免费分区数，如果免费分区额度已用完，则必须购买分区后才能继续创建 Topic 或扩分区。如果分区数量已达该规格的最大额度，则只能调整分区规格、获得更大的分区额度才能继续创建 Topic 或扩分区。

前提条件

已创建消息队列 Kafka版实例，且实例状态为运行中。详细操作步骤请参考创建实例。

手动创建 Topic

消息队列 Kafka版支持通过控制台或 OpenAPI 的方式手动逐个创建 Topic。

说明

成功创建 Topic 之后，不支持修改 Topic 名称，且分区数量只能调大、不能调小，创建或修改时请合理规划分区数量。

在应用迁移上云或实例备份等场景下，如果需要一次性创建多个 Topic，可以通过上传配置文件的方式批量创建 Topic，操作步骤可参考批量导入 Topic。

通过控制台创建 Topic

登录消息队列 Kafka版控制台。

在顶部菜单栏中选择实例所在的地域。

在实例列表页面单击指定实例名称。

在页签栏中单击Topic管理。

单击创建Topic。

填写 Topic 基础配置。

参数	说明
Topic名称	Topic 的名称。需要符合以下命名规范： 3～249 个字符。支持的字符包括英文、数字、短横线（-）、英文点（.）、下划线（_）。必须以英文或数字开头。不能与已存在的 Topic 名称重复。注意创建 Topic 之后不支持修改 Topic 名称，请谨慎操作。
描述	Topic 的备注信息，可以用于简单描述 Topic 的用途、对应的业务类型等信息。

填写 Topic 参数配置。

参数	说明
分区数	此 Topic 的分区数量。分区数量越大，消费的并发度越大。默认值为 12，取值范围为 1～300，且不可超过相应 Kafka 实例的剩余可用分区数。说明在修改 Topic 配置时，该参数只支持增加，不支持减少。 Topic 的分区会在 Kafka 实例内部打散存放，为保证分区在 Kafka 实例内能够均匀的被打散，建议设置Topic 分区数量为相应 Kafka 实例 Broker 数量的整数倍，您可参考查看节点信息，查看 Kafka 实例的 Broker 数量。
副本数	分区的副本个数，表示在对应数量的副本上备份数据，用于保障分区的高可用。当其中一个 Broker 故障时仍可保障数据可用性，副本数越大可靠性越高。副本数支持设置为 1、2 或 3，默认为 3。说明增加副本数会占用实例磁盘容量，请确保容量充足。增加副本时会占用实例带宽资源，建议在业务低峰期操作。减少副本数会降低数据可用性，请谨慎操作。 1 副本 Topic 无法保障数据可靠性且实例升级期间无法进行读写操作，建议选择 2 副本或 3 副本。
最小同步副本数	Topic 最小同步副本个数，即 min.insync.replicas 参数。该值越大，数据可靠性越好，但是可用性将会降低。副本数为 1 时，最小同步副本数只能为 1。副本数为 2 或 3 时，最小同步副本数不能超过副本数减 1。
消息保留时长	磁盘容量充足时，消息在此 Topic 中的最大保留时长，即消息的存储时间。消费者必须在此时间结束前消费消息，否则消息将被删除，删除的消息无法被消费。单位为小时，取值范围为 1～2160，目前支持的最大存储时长为 90 天。默认为实例级别的消息保留时长，您也可以在此处指定该 Topic 的消息保留时长，仅对该 Topic 生效。
最大消息大小	此 Topic 中单条消息的最大长度。取值范围为 1MB～12MB。默认为实例级别的最大消息大小，您也可以在此处指定该 Topic 的最大消息大小，仅对该 Topic 生效。

配置用户权限。

指定实例内 SASL 用户对该 Topic 的操作权限。

默认为全部允许，即全部 SASL 用户对于此 Topic 都具备读写权限，即使该用户关闭了 All Permitted 权限。您也可以选择自定义设置，为不同 SASL 用户分别指定权限类型。自定义权限包括：

只读：只具备消息订阅权限，不具备消息生产权限。

只写：只具备消息生产权限，不具备消息订阅权限。

读写：同时具备消息生产和消息订阅权限。

说明

自定义设置只对关闭了 All Permitted 的 SASL 用户生效。

创建 Topic 时，如果设置了自定义权限，消息队列 Kafka版会同步创建对应的 ACL，并将其显示在 ACL 列表中。创建 Topic 后如果需要修改自定义权限，推荐通过 ACL 操作，详细说明请参考创建 ACL。

配置消息清理策略。

DELETE：默认的消息清理策略。在磁盘容量充足的情况下，保留在最长保留时间范围内的消息；在磁盘容量不足时，将提前删除旧消息，以保证服务可用性。

说明

Kafka 实例默认的磁盘清理水位为 90%，具体以实际为准，详情请参见设置磁盘清理水位。

COMPACT：COMPACT 消息清理策略针对每个消息的 Key 进行整合，对于有相同 Key 的消息，只保留最新的 value 值，旧的记录则会被清除。

注意

如果消息没有 Key，不支持启用 COMPACT 消息清理策略。

DELETE,COMPACT：同时配置 DELETE 和 COMPACT 两种消息清理策略。只要消息满足任一条清理策略时，都将被清除。

（可选）配置 Topic 标签。

单击添加标签，输入标签键和标签值，为 Topic 添加自定义标签。

标签用于云资源的标识与分类，添加标签有利于识别和管理 Topic。每次支持添加 20 个标签，标签设置规则请参见标签设置规则。

单击创建。

在Topic管理页签中可以查看已创建好的 Topic。

通过 OpenAPI 创建 Topic

消息队列 Kafka版提供 OpenAPI CreateTopic，用于手动创建 Topic。

自动创建 Topic

使用自动创建 Topic 的功能前，需要先在控制台开启此功能，并通过客户端 SDK 在写入消息时指定一个不存在 Topic。自动创建的 Topic 默认配置如下。

参数	默认配置
Topic 名称	默认使用客户端 SDK 指定的 Topic 名称。应符合以下规范： 3～249 个字符。支持的字符包括英文、数字、短横线（-）、英文点（.）、下划线（_）。必须以英文或数字开头。不能与已存在的 Topic 名称重复。说明不可以 __ 开头，否则自动创建 Topic 失败。如果 Topic 名称中指定了不符合规范的字符，则可能出现无法采集 Topic 监控数据等问题。
描述	无。
分区数	开启自动创建 Topic 功能时设置的默认分区数。
副本数	开启自动创建 Topic 功能时设置的默认副本数。
最小同步副本数	默认为 1。
消息保留时长	默认沿用实例的消息保留时长。
最大消息大小	默认沿用实例的最大消息大小。
用户权限	默认此 Topic 无任何自定义权限。如果开启了 ACL，则权限为 All Permitted 的 SASL 用户才具备此 Topic 的读写权限。
标签	默认此 Topic 无任何自定义标签。如需为 Topic 设置标签，请参见管理 Topic 标签。
消息清理策略	自动创建的 Topic，消息清理策略默认为 DELETE。

说明

建议您仅在接入测试或数据迁移场景下使用自动创建 Topic 的功能。在实际的生产环境中，尤其是对性能和稳定性要求比较高的核心生产业务中建议关闭该功能。

相较于手动创建 Topic，自动创建 Topic 耗时更高，且成功创建 2 分钟后才会显示在 Topic 列表中。

实例更配过程中，禁止通过任何方式创建 Topic。通过客户端创建 Topic 之前，请确认实例状态为运行中（Running）。

1 开启自动创建 Topic 功能

登录消息队列 Kafka版控制台。

在顶部菜单栏中选择实例所在的地域。

在实例列表页面单击指定实例名称。

在Topic管理页签中单击设置自动创建 Topic。

开启自动创建Topic开关，设置以下参数，并单击创建。

参数	说明
ACL 用户自动授权	是否允许所有 ACL 用户自动创建 Topic。默认打开开关，表示允许所有 ACL 用户自动创建 Topic。打开该开关，将在 ACL管理页签下创建所有用户的创建和删除 Topic 的权限。说明该开关的启停也受所有用户的创建 Topic 权限所控制。主动删除所有用户的创建权限，该开关将关闭；主动开启所有用户的创建权限，该开关将打开。关闭开关，不允许 ACL 用户自动创建 Topic。此时可以通过 ACL 权限策略管理为目标用户配置 Topic 管理权限。更多信息，请参见创建 ACL。说明主动关闭该开关，所有用户的创建和删除 Topic 的权限不会被删除，请在 ACL管理页签下删除所有用户的创建和删除权限。更多信息，请参见删除 ACL。
默认分区数	自动创建的 Topic 的默认分区数量。取值范围为 1~300，且不可超过实例的剩余可用分区数。
默认副本数	自动创建的 Topic 的默认分区副本数量。支持设置为 1 副本、2 副本或 3 副本。

在弹出的对话框中单击确定。

说明

对于2023年10月26日及之前创建的实例，设置默认分区数或副本数时，后端服务会自动重启实例以使配置生效。

2 通过 Kafka 客户端 SDK 自动创建 Topic

开启自动创建 Topic 功能后，您可以在生产侧客户端 SDK 中设置一个不存在的 Topic 名称，请求向其写入消息数据。消息队列 Kafka版收到请求时会自动在对应实例中创建此 Topic。

您可以参考以下 Java 语言的示例代码在 Kafka 客户端 SDK 中为生产者实例设置消息写入的 Topic，也可以参考消息队列 Kafka版提供的示例项目，编写相关业务逻辑。