如何设置MongoDB Atlas云数据库的IP访问列表以配置访问策略？

本文共计667个文字，预计阅读时间需要3分钟。

Atlas已自2021年7月起正式废弃旧有的白名单（Whitelist）机制，所有新配置必须使用projectIpAccessList资源，否则连接将会被默认拒绝——不是错误，而是直接被防火墙拦截。

为什么 atlas projectIpAccessList add 命令执行后仍连不上？

常见原因是权限不足或参数格式错误。该命令要求 API Key 至少具备 Project Read Only 或更高角色（如 Project Owner），且 --cidrBlock 必须是合法 CIDR 表达式（如 192.168.1.0/24），不能是单个 IP（如 192.168.1.100）——除非加 /32 后缀。

• atlas projectIpAccessList add --cidrBlock "203.0.113.42/32" --comment "my-laptop" ✅
• atlas projectIpAccessList add --cidrBlock "203.0.113.42" ❌（会报 400 错误：invalid CIDR notation）
• 若用 CLI 操作，确保已通过 atlas auth login 登录，且 --profile 指向正确项目（可用 atlas config list 查看）

如何用 API 批量添加多个 IP 段？

直接调用 Admin API 的 POST /groups/{GROUP-ID}/accessList 端点更可控，尤其适合 CI/CD 流水线。注意：GROUP-ID 是 Atlas 项目 ID（非名称），可在项目 Settings → General 页面顶部找到，形如 60f1a2b3c4d5e6f7g8h9i0j1。

• 请求体需为 JSON 数组，每个元素含 cidrBlock 和可选 comment
• 支持临时条目：加上 deleteAfterDate 字段（ISO 8601 格式，如 "2026-04-22T00:00:00Z"），7 天内自动清理
• 不建议一次性提交超过 100 条，否则可能触发速率限制（HTTP 429）

UI 配置和 CLI/API 的行为差异

Atlas 控制台（Project Settings → Network Access）底层调用的也是同一套 projectIpAccessList 接口，但 UI 有隐藏逻辑：

• 输入单个 IP（如 203.0.113.42）时，UI 自动补成 /32；CLI 不会自动补，必须手写
• UI 中删除条目后，实际是发起 DELETE /groups/{GROUP-ID}/accessList/{ACCESS-LIST-ENTRY-ID}，而 CLI 的 atlas projectIpAccessList delete 需要先用 list 查出 id 字段
• UI 不显示 deleteAfterDate 字段，但 CLI 和 API 创建的临时条目仍会准时过期

真正容易被忽略的是：IP Access List 生效有缓存延迟，通常 1–2 分钟，但偶尔达 5 分钟。如果刚加完就测连通性失败，别急着重试命令，先等一等再验证。