ip访问白名单必须通过network access页面或atlas projectipaccesslist cli配置，仅对project生效；常见连不上原因是cidr格式错误（如缺/32）、出口ip误判（需curl ifconfig.me确认）及权限不足（至少project read only），且配置有1–5分钟缓存延迟。
直接结论：IP访问白名单必须通过 Network Access 页面或 atlas projectIpAccessList CLI 命令配置，且仅对 Project 生效；填错 CIDR 格式、用错出口 IP 或权限不足，是连不上最常踩的三个坑。
在哪配？不是数据库页，也不是连接字符串里改
入口只有唯一位置：Network Access 页面——进入 Atlas 控制台 → 选中目标 Project → 左侧菜单点 Network Access → 右上角点 + ADD IP ADDRESS。别在集群设置、用户管理、连接字符串或旧版 “Whitelist” 标签页里找，那些已下线或无效。注意：projectIpAccessList 是当前唯一有效的 API 入口，2021 年 7 月起旧版 Whitelist 机制彻底弃用，调用会静默失败。
填什么才合法？CIDR 必须带掩码，不接受域名和端口
Atlas 只认标准 CIDR 表达式，任何省略掩码、混入端口或域名的操作都会报 Invalid CIDR notation：
- 单个 IPv4 地址必须写成
203.0.113.42/32（不是203.0.113.42） - IPv6 必须带完整前缀，例如
2001:db8::1/128（只填2001:db8::1会失败） - 不支持
example.com、*.domain.com、203.0.113.42:27017这类写法 -
0.0.0.0/0虽然能连，但等于裸奔，生产环境严禁使用
为什么加了还是连不上？出口 IP 和缓存延迟最易被忽略
常见现象是命令返回成功，但应用立刻卡在 Connection timed out——说明请求根本没进 Atlas 集群，不是鉴权问题：
- 本地实际出口 IP ≠
ifconfig或ipconfig结果：Wi-Fi 热点、企业代理、云主机跳转后看到的是网关 IP；用curl ifconfig.me实时查 - AWS EC2 等云主机若没配 EIP 或 NAT Gateway，要加的是 EIP，不是实例私有 IP
-
projectIpAccessList生效有缓存延迟，通常 1–2 分钟，极端情况达 5 分钟，刚添加完别立刻重试 - CLI 操作需确保 profile 正确指向目标 Project：
atlas config list查确认，--profile参数不能漏
要不要切 VPC Peering 或 Private Link？先问清楚流量路径
普通 Web 应用、CI/CD 机器、本地调试，老老实实填 IP 白名单最稳。只有当你明确需要绕过公网、降低延迟或满足合规要求时，才考虑 VPC Peering 或 AWS PrivateLink：
- VPC Peering 不走公网，但配置复杂、跨区域支持有限，且仍需处理 DNS 解析
- Private Link 更彻底，但要额外开通审批，还可能卡在内网 DNS 或路由策略上
- 别为了“架构好看”提前切——很多团队卡在 Private Link 的 DNS 配置上，反而比 IP 白名单更难排障
真正麻烦的从来不是加一条 IP，而是搞清你发出的请求到底从哪个 IP 出去、中间经过几层 NAT、以及 Atlas 看到的究竟是谁。这些细节不厘清，填再多条目也没用。
