MagicDB Studio
NoSQL & Messaging
MongoDB 与 Kafka
浏览 MongoDB 集合、过滤并检查文档，同时以受控方式验证 Kafka Topic 与测试消息链路。
适用场景
本页适合需要在同一桌面工作台中检查 MongoDB 数据形态，或对 Kafka 连接和单条测试消息做基础验证的开发者与运维人员。
- MongoDB 数据核查：按数据库、集合逐层浏览，使用查询条件缩小文档范围，检查字段、嵌套对象与 JSON 结构。
- 集合变更前确认：先读取目标文档并校验 JSON，再决定是否编辑；重要数据应先在数据库侧完成可恢复备份。
- Kafka 联通性验证：查看 Topic、分区与副本信息，按分区和 offset 拉取少量消息，或发送无副作用的测试消息。
- 问题定位：区分网络、认证、Topic 不存在、分区选择错误与权限不足，不把界面可见等同于拥有生产或管理权限。
能力边界：Kafka 在当前文档中按目录 / 实验性能力使用，具体可用性取决于实际集群、客户端兼容性与授权。页面不保证消费位点提交、生产权限、完整消费组治理或完整集群管理能力。
入口路径
先在连接中心新建或选择对应数据源，并在保存前执行连接测试。MongoDB 连接成功后，从连接对象树展开数据库与集合；Kafka 连接成功后，从该连接进入 Topic、分区或消息相关视图。不同内测构建中的菜单名称可能略有差异，应以当前界面实际提供的入口为准。
- 打开 MagicDB Studio，进入连接中心。
- 选择“新建连接”，按目标类型选择 MongoDB 或 Kafka，并填写实际环境要求的连接信息。
- 点击“测试连接”；测试成功后再保存，失败时先保留错误信息并检查网络、认证和服务端访问控制。
- 从已保存连接进入对象树；MongoDB 展开至集合，Kafka 展开至 Topic 后再执行读取或测试发送。
前置条件
- 已安装可用的 MagicDB Studio，且本机能够访问目标 MongoDB 或 Kafka 服务地址；不要写死依赖某个易过期的服务版本。
- 已从管理员处获得准确的主机、端口、认证信息及必要的网络放行；若部署要求额外认证或加密参数，以集群策略和当前连接表单为准。
- MongoDB 账号至少应具备目标数据库与集合的读取权限；需要编辑文档时，再单独确认写权限和备份方案。
- Kafka 账号应按任务最小授权：浏览元数据、读取测试 Topic 或向测试 Topic 写入。能连接 Broker 不代表能读取或生产消息。
- 生产环境操作前准备专用测试 Topic、可识别的测试消息和回滚 / 清理约定，避免向真实业务流写入不可撤销的数据。
编号步骤
- 测试并保存连接。分别填写 MongoDB 或 Kafka 的服务地址与认证信息，先执行“测试连接”。确认目标环境、连接名称和错误提示无误后再保存；不要仅凭默认端口判断连接对象。
- 浏览 MongoDB 集合。在对象树中展开目标数据库和集合，先查看集合信息、索引与字段采样，再打开文档列表。确认集合名、环境标签和记录数量级，避免在错误集合上继续操作。
- 过滤并检查文档。输入尽可能收敛的查询条件，先小范围读取结果；逐条检查字段类型、缺失字段、嵌套对象和数组。若准备编辑，先复制原始文档作为恢复依据，并利用 JSON 校验排除非法结构。
- 预览 MongoDB 变更影响。再次核对过滤条件是否唯一命中预期文档。仅在已确认写权限、备份和目标环境后提交编辑；保存后重新查询并比对关键字段，不把界面提示当作数据正确性的唯一证据。
- 检查 Kafka Topic 元数据。进入 Kafka 连接后选择目标 Topic，查看分区、副本等可见信息。确认 Topic 名、集群和分区编号，不在不明确保留策略与消费者影响时创建、删除或调整生产 Topic。
- 拉取少量消息。选择明确的分区和 offset 范围，以小批量方式检查 key、value 与时间信息。记录查询条件；拉取结果为空时，分别检查 offset 范围、分区、权限和 Topic 是否有数据。
- 发送可识别的测试消息。只向已批准的测试 Topic 发送，预先检查 key、value、目标分区和序列化格式。发送后再按相同 Topic 与分区拉取确认；界面发送成功不保证下游已消费，也不代表具备生产环境持续写入权限。
MongoDB · 集合与文档
工作台 · 数据库对象树上下文
参数说明
字段是否出现以及可选值取决于数据源、服务端配置和当前构建。下表用于操作前核对，不代替管理员提供的集群参数。
| 对象 | 参数 | 用途与检查点 | 边界 / 风险 |
|---|---|---|---|
| MongoDB | 主机、端口、数据库与认证信息 | 定位服务并完成身份验证；连接测试时核对目标环境。 | 网络可达不等于集合可读或可写，权限由服务端决定。 |
| MongoDB | 集合 | 限定文档所属对象；操作前核对数据库名与集合名。 | 同名集合可能存在于不同环境或数据库中。 |
| MongoDB | 查询过滤条件 | 缩小返回文档范围；优先使用可明确命中的字段。 | 空条件或宽泛条件可能读取大量数据；编辑前必须再次确认命中范围。 |
| MongoDB | 文档 JSON | 检查字段、嵌套对象与数组，编辑时进行 JSON 校验。 | JSON 语法合法不代表业务语义正确，也不替代备份与保存后复查。 |
| Kafka | Broker 地址与认证参数 | 发现集群并建立连接；按部署要求填写当前表单提供的认证项。 | 兼容性和认证方式以实际集群为准，连接成功不授予额外权限。 |
| Kafka | Topic | 指定消息所属主题；发送前逐字核对名称与环境。 | 不要在未确认策略时对生产 Topic 做管理性操作。 |
| Kafka | 分区与 offset | 控制读取位置与范围，便于小批量检查消息。 | 工具可见的 offset 信息不保证能够提交或维护消费位点。 |
| Kafka | 消息 key / value | 构造可识别的测试消息，并与消费者约定格式。 | 发送前确认序列化与下游兼容；不保证生产权限或投递后的业务处理结果。 |
预期结果
- MongoDB 连接测试通过后，可逐层看到数据库与集合，并能读取目标集合的有限文档结果。
- 过滤结果应与预期条件一致；文档内容可用于检查字段结构，编辑内容在提交前通过 JSON 校验，提交后能重新查询核对。
- Kafka 连接可展示授权范围内的 Topic，以及可用的分区、副本或 Broker 元数据；具体展示以集群权限和兼容性为准。
- 在具备读取权限时，可按指定分区和 offset 拉取消息；在具备生产权限时，可向批准的测试 Topic 发送消息并尝试回读验证。
验收原则：将“连接成功”“读取成功”“发送请求成功”和“下游实际消费成功”分别验证。任一界面反馈都不应被扩展解释为消费位点已提交、生产权限永久有效或 Kafka 管理能力完整。
常见问题
MongoDB 能连接，但看不到数据库或集合怎么办？
先确认连接到正确实例，再核对账号对目标数据库的读取权限。若服务端限制元数据枚举，可让管理员直接确认授权范围；不要通过反复创建同名连接绕过权限问题。
MongoDB 查询很慢或返回文档过多怎么办？
立即收窄过滤条件，优先使用已知标识字段，并参考集合索引信息。先小范围读取和抽样检查，不使用空条件进行大集合全量浏览；必要时由数据库管理员分析索引和服务端负载。
文档通过 JSON 校验后是否可以直接保存？
不可以据此判断业务正确。JSON 校验主要排除结构语法问题；仍需核对字段类型、业务约束、目标环境与命中范围，并在重要变更前备份原文档，保存后重新查询验证。
Kafka 能看到 Topic，但拉取不到消息怎么办？
依次检查 Topic、分区和 offset 范围，确认该分区确有数据，并核对读取权限。空结果不一定表示 Topic 无消息，也可能是 offset 超出有效范围、数据已按保留策略清理或当前能力与集群不兼容。
Kafka 测试消息发送失败或发送后无法回读怎么办？
确认使用测试 Topic，检查生产权限、目标分区、key / value 格式及服务端错误。发送成功但回读不到时，再检查读取权限和 offset 选择；不要据此假定工具会管理消费位点，也不要向生产 Topic 反复重试。