连接地址是应用程序与文档数据库 MongoDB 版实例建立通信的基础配置。通过正确的连接地址配置，应用请求可精准路由至集群主节点、从节点、只读节点或 Mongos 节点，为实现实例稳定访问、高可用与读写分离提供基础支撑。本文介绍 MongoDB 连接地址的配置方法及相关建议。

背景信息

连接地址类型

文档数据库 MongoDB 版提供私网、公网两类连接地址，适配副本集、分片集群架构使用。如需了解连接地址的类型区别、查看方法、申请释放操作以及不同实例支持的连接地址，请参见查看连接地址。

连接地址格式

各连接地址的格式、参数说明以及示例如下：

副本集实例

私网地址

私网地址（只读）

Primary 地址

Secondary 地址

ReadOnly 地址

格式

参数说明

参数	说明
mongodb://	固定前缀，用于标识 MongoDB 连接协议，不可修改。
<username>	必填，数据库账号名称，默认为 root。
<password>	必填，数据库账号对应密码。
<host1>:<port>,<host2>:<port>,...,<hostN>:<port>	必填，副本集实例主、从节点的域名和端口信息，多个节点用英文逗号（,）分隔。默认端口号为 3717。端口号的可修改范围为1000~65535，具体操作请参见修改端口号。
<database>	可选，身份认证时使用的数据库，默认为 admin。
replicaSet=<replicaSetName>	必填，副本集名称。
authSource=admin	必填，固定填写 admin，用于数据库账号权限认证。
readPreference=<value>	可选，自定义读节点优先策略，可选择优先读取主节点或从节点。
retryWrites=true	可选，建议生产环境配置，网络轻微抖动时自动重试写入请求，提升访问稳定性。

示例

分片集群实例

私网地址

Mongos 地址

Shard 地址

ConfigServer 地址

分片集群多 Mongos 节点高可用接入地址，是业务应用访问分片集群的标准推荐入口。

格式

参数说明

参数	说明
mongodb://	固定前缀，用于标识 MongoDB 连接协议，不可修改。
<username>	必填，数据库账号名称，默认为 root。
<password>	必填，数据库账号对应密码。
<mongos1>:<port>,<mongos2>:<port>...	必填，分片集群多个 Mongos 节点的域名和端口信息，多个节点用英文逗号（,）分隔。默认端口号为 3717。端口号的可修改范围为1000~65535，具体操作请参见修改端口号。
<database>	可选，身份认证时使用的数据库，默认为 admin。
authSource=admin	必填，固定填写 admin，用于数据库账号权限认证。
retryWrites=true	可选，建议生产环境配置，网络轻微抖动时自动重试写入请求，提升访问稳定性。

示例

读写分离参数

业务访问数据库时，为分担主节点读取压力、提升查询性能与集群稳定性，您可在连接地址中配置 readPreference 和 readPreferenceTags 两类参数实现读写分离。如需了解参数基础说明及读写分离连接地址配置方法，请参见读写分离。

配置方案与适用场景

您可结合自身业务场景，选择适配的连接地址配置方案，具体场景及配置详情如下：

序号	适用场景	配置说明	单点故障影响	连接地址配置	核心配置参数
1	电商下单、支付结算、用户登录认证等核心场景。无需读写分离，追求数据强一致和高可用。	默认高可用配置（推荐），读写请求均访问主节点。	主节点故障：实例自动主备切换，切换后可正常读写；从节点故障：无影响。	mongodb://<user>:<password>@host0,host1/?authSource=admin&replicaSet=rs-mongo-replica-xxx&retryWrites=true	retryWrites=true
2	中小电商、内容平台。需实现零成本读写分离（不新增节点），如商品详情查询、文章列表加载，控制节点部署成本。	读写分离配置（推荐），读请求优先访问从节点，故障时访问主节点，零成本分流。	主节点故障：主备切换后，可正常读写；从节点故障：无影响。说明无需新增节点。若主从节点存在数据同步延迟，则会对业务读取数据的准确性造成影响。	mongodb://<user>:<password>@host0,host1/?authSource=admin&replicaSet=rs-mongo-replica-xxx&retryWrites=true&readPreference=secondaryPreferred	readPreference=secondaryPreferred
3	大型电商、大数据平台，强依赖读写分离，追求高可用，如实时数据分析、用户行为统计、高频商品查询，需稳定读请求路由。	读写分离配置（推荐），读请求优先访问只读节点，无可用节点时访问主节点。	主节点故障：主备切换后，可正常读写；部分只读节点故障：无影响；所有只读节点故障：无影响。说明建议新增 2 个及以上只读节点。	mongodb://<user>:<password>@host0,host1,readonly-host0,readonly-host1/?authSource=admin&replicaSet=rs-mongo-replica-xxx&retryWrites=true&readPreference=secondaryPreferred&readPreferenceTags=role:readonly	readPreference=secondaryPreferred&readPreferenceTags=role:readonly
4	非核心链路的读写分离场景，如商品评论列表查询、历史订单查询（非核心页面）。读请求仅允许访问从节点。	读写分离配置，读请求仅访问从节点，核心在线链路避免使用。	主节点故障：主备切换后，写请求正常，读请求失败；从节点故障：读请求失败。	mongodb://<user>:<password>@host0,host1/?authSource=admin&replicaSet=rs-mongo-replica-xxx&retryWrites=true&readPreference=secondary	readPreference=secondary
5	读写分离且读请求仅允许访问只读节点（无降级需求），如固定时段的报表统计、非实时数据查询。	读写分离配置，读请求仅访问只读节点，无可用节点时不降级。	主节点故障：主备切换后，可正常读写；部分只读节点故障：无影响；所有只读节点故障：读请求失败。说明需提前规划并部署只读节点，确保读请求有可用节点承接。	mongodb://<user>:<password>@host0,host1,readonly-host0,readonly-host1/?authSource=admin&replicaSet=rs-mongo-replica-xxx&retryWrites=true&readPreference=secondary&readPreferenceTags=role:readonly	readPreference=secondary&readPreferenceTags=role:readonly
6	运维人员临时调试、故障排查，如数据库性能检测、数据异常排查，无需高可用保障。	单节点访问，生产环境避免使用。	节点故障：读写请求全部失败。	mongodb://<user>:<password>@host0/?directConnection=true	directConnection=true

配置选型总结：

零成本读写分离（不新增节点）：推荐使用配置方案 2。

高并发读扩展（新增只读节点）：推荐使用配置方案 3，建议新增 2 个及以上只读节点，避免单点故障。

生产环境禁止使用：配置方案 4（存在核心链路读请求失败风险）和配置方案 6（无高可用保障）。

配置验证与问题排查

配置连通性验证

完成连接地址配置后，您可通过以下方式快速验证连通性，确认配置生效：

云服务器测试（推荐）

在部署业务的火山引擎 ECS 服务器中安装 MongoDB Shell 工具，执行以下命令连接实例。

mongosh "mongodb://<username>:<password>@<host>:<port>/admin?authSource=admin"

将命令中占位符替换为您实际的数据库账号、密码、实例域名及端口，若可正常进入数据库交互界面且无报错，即配置正常。

客户端工具验证

通过 MongoDB Compass、Navicat 等可视化客户端，输入标准的连接地址、账号密码及认证参数。若能正常建立连接并查看库表数据，即配置无误。

业务应用验证

将连接地址填入业务项目配置文件并重启应用，若无数据库连接报错，且可正常完成数据读写操作，即配置生效可用。

常见问题排查

您在配置连接地址和连通性验证时，若遇到连接、登录或访问类异常，可参照下表自行排查处理。若遇到其他网络类问题，可查阅网络连接文档。若问题仍无法解决，可提交工单联系技术支持协助。

问题现象	常见原因	处理方案
连接超时，无法访问实例	未配置 IP 白名单、未放行 3717 端口、网络地址选择错误	1. 在控制台添加客户端 IP 至白名单；2. 放行 3717 端口；3. 优先使用私网地址连接。说明添加客户端 IP 至白名单的具体操作，请参见创建白名单。
登录失败，提示认证异常	账号密码错误、连接认证参数配置错误	核对账号密码，确保连接配置中 authSource=admin 参数正确。
直连从节点 / 只读节点，写入报错	未使用集群统一的连接地址，仅单独直连从节点 / 只读节点	使用集群统一的连接地址，不单独直连从节点 / 只读节点。
副本集连接异常，路由失败	未配置 replicaSet 参数、节点域名填写错误	补充 replicaSet 参数配置，按控制台显示的节点域名准确填写。
分片集群连接失败	节点地址拼接错误，连接 Shard、ConfigServer 节点未配置 replicaSet 参数（连接 Mongos 节点无需配置此参数）	按标准格式拼接节点地址，Shard 和 ConfigServer 节点补充 replicaSet 参数配置。
网络不稳定，连接频繁中断、写入失败	未开启写入重试功能	开启写入重试功能（配置 retryWrites=true 参数），避免连接中断导致写入失败。