Cursor Cloud Agent 访问不了内网服务：网络隔离与私有连接

2026-08-18

内网服务连不上这件事，在 Cloud Agent 上比在本地 Agent 上更容易踩，因为它压根不在你的机器上跑。Cursor 官方文档《Secrets & Network》页写明，代码运行在 Cursor 的 AWS 基础设施里、跑在隔离的虚拟机中，并在 agent 可访问期间存放在 VM 磁盘上。所以「我本机能连上这个数据库」这个前提，对 Cloud Agent 完全不成立。

现象长什么样

典型的三类表现：

agent 在终端里访问某个域名超时或被拒，公网上的其它域名却正常；
agent 要连的是内网主机名、私有 DNS 才能解析的服务，直接解析失败；
自托管的 GitHub Enterprise Server、GitLab Enterprise、Artifactory、Nexus 这类系统从公网不可达，clone 或拉包这一步就断了。

这三类对应的处置完全不同，混着试会白折腾很久。

第一步：确认是不是出站白名单挡的

Cursor 官方文档写明，Cloud Agent 默认具备互联网访问能力，同时可以为用户、团队和保存的环境（saved environments）配置 network egress controls 来限制可访问的域名。所以第一件事是确认当前生效的是哪种模式。《Secrets & Network》页列出三种出站访问模式，都在 Cloud Agents dashboard 上配置：

模式	文档写明的行为
Allow all network access	Cloud Agent 可访问任意外部主机，不施加域名限制
Default + allowlist	可访问默认域名集合，加上你自己添加到 allowlist 的域名
Allowlist only	只能访问你显式加入 allowlist 的域名

一共就这三档。文档还写明：即使处在 Allowlist only，仍有一小组域名保持可达以便 Cloud Agent 能正常工作，其中包括 Cursor 自家服务与源码管理（SCM）供应商。

可执行的判定动作：到 Cloud Agents dashboard 的 Security 这一栏下看当前用户级模式（官方文档写明用户级设置在这个位置，且作用于你创建的所有 Cloud Agent）；再确认这次跑的 agent 用的是不是某个保存的环境，因为环境有自己的一套设置。

优先级是最容易被绕晕的一处，文档写得很明确，只有三条：

如果环境自己定义了模式，环境设置生效（对使用该环境的 agent）；
如果环境是继承设置、而用户配置了自己的设置，用户设置优先；
环境和用户都没配，团队默认生效。

环境级另有两个继承选项：Inherit settings（用适用的用户或团队设置）与 Inherit settings + environment allowlist（在此基础上再加环境 allowlist 里的域名）。环境也可以直接被设成上面那三种模式之一。

还有一条会让人以为「我设置没保存」的情况：Enterprise 团队管理员可以用 Lock Network Access Policy 锁定这个设置。文档写明锁定后团队级设置对每个成员生效，成员无法从自己的 dashboard 覆盖。改了个人设置却毫无变化，先问管理员是不是锁了。

顺带记一条容易漏的：Cloud Agent 会把 artifacts（PR 上展示的截图、视频、日志引用）上传到 cloud-agent-artifacts.s3.us-east-1.amazonaws.com，用 Default + allowlist 或 Allowlist only 时要把这个精确主机加进 allowlist。文档自述了为什么不能图省事写成 *.s3.us-east-1.amazonaws.com：通配符会对该区域内每个 bucket 打开出站通路，给被提示注入的 agent 制造一条外泄路径。

第二步：确认是不是「没有通路」而不是「被挡」

如果目标服务本身就不接受公网入站，那加多少域名到 allowlist 都没用——需要的是一条私有网络通路。

Cursor 官方文档在《Secrets & Network》的 Private network access 一节写明：Cloud Agent 不需要跑在你自己的硬件上才能访问私有资源；对 VPC 或内网中的服务，可以在 Cloud Agent 环境里使用 Tailscale userspace networking、Cloudflare Tunnel 或类似的私有网络客户端。两种方式下，私有服务都不需要接受来自公网的入站流量。

Tailscale：默认模式不工作，这是反直觉的一处

《Cloud Agent Setup》页写得很直白：Tailscale 在 Cloud Agent VM 里以默认网络模式无法工作，要改用 userspace networking 模式。文档给出的启动方式是：

tailscaled --tun=userspace-networking \
  --outbound-http-proxy-listen=localhost:1054 \
  --socks5-server=localhost:1055

然后在希望流量走 Tailscale 的那个 shell 里导出代理变量：

export ALL_PROXY=socks5h://localhost:1055/
export HTTP_PROXY=http://localhost:1054/
export HTTPS_PROXY=http://localhost:1054/

之后再走你平常的 tailscale up ... 流程。文档同时写明一条边界：userspace networking 不能让这台 VM 充当 tailnet 的 exit node。

以上为按官方文档中的参数语义组合的示例，未经实测，以官方文档与 --help 的实际输出为准。另外提醒一句：这些命令是在 Cloud Agent 的环境里执行的（写进环境 Dockerfile、install script 或启动命令），不是在你本地的 Windows 终端里敲。Windows 用户不必去找这几条命令在 PowerShell 下的等价写法——执行地点根本不在本机。

Cloudflare Tunnel：适合有认证 HTTPS 主机名的场景

文档写明 cloudflared 在 Cloud Agent VM 里跑在 userspace，所以可用。给出的模式是：

在环境 Dockerfile 或 install script 里安装 cloudflared；
在私有网络内运行一个 cloudflared connector；
把一个带认证的主机名（文档示例写的是 vpc.example.com）通过隧道路由到私有 origin；
环境若用了受限出站，把这个主机名加进 Cloud Agent 网络 allowlist；
把 Cloudflare Access service token 的值存为 Cursor Secrets，文档举的变量名例子是 CF_ACCESS_CLIENT_ID 与 CF_ACCESS_CLIENT_SECRET。

之后 Cloud Agent 就以普通 HTTPS 调用该私有服务，带上 CF-Access-Client-Id 与 CF-Access-Client-Secret 请求头；connector 向 Cloudflare 发起出站连接并把请求转给私有 origin，服务不需要开放入站端口。

对私有 TCP 目标（比如数据库），文档给的做法是配置 Cloudflare TCP Access app，在启动命令里跑 cloudflared access tcp，然后把应用或测试命令指向 cloudflared 创建的本地监听端口——agent 连 localhost，隧道把流量转到私有 origin。

凭据放哪很重要。官方文档写明 Secrets 可设为 Environment Variable、Runtime Secret、Build Secret 三种类型；Runtime Secret 仍作为环境变量加载，但内容会从 agent 的工具调用结果、聊天记录、提交与提交信息中被删除并替换为占位串 [REDACTED]。文档同时点了它的边界：内部仍是环境变量，虽不展示给 agent，但通过 Terminal 与 agent 环境交互的用户仍然看得到。文档另要求隧道 token 与 Access service token 放 Cursor Secrets、不要放仓库，概念验证阶段创建的凭据用完轮换。

第三步：自托管 Git / 制品库走 private connectivity

如果连不上的是自托管 GitHub Enterprise Server、GitLab Enterprise、Bitbucket Data Center、Artifactory、Nexus 这一类，Cursor 官方文档另有一页《Private Connectivity》，面向 Enterprise 团队。文档写明这套私有连接配置在多个 Cursor 服务间共用，包括 Cloud Agent、Bugbot 与 Cursor 后端服务；开通方式是联系 Cursor 销售或 hi@cursor.com，不是自助开关。

支持的选项文档只列了两种，状态都标为 Supported：AWS PrivateLink（适合私有 Git 供应商或包仓库在 AWS、或能置于 AWS Network Load Balancer 之后的情形，也是自托管 GHES 与 GitLab Enterprise 的首选路径）与 Cloudflare Tunnel（适合无法发布 AWS endpoint service、或只想要一条出站隧道的部署模型，环境要求是任何能跑 cloudflared 的环境）。Google Private Service Connect 单独说一句：文档写明 Cursor 目前不提供面向客户的 PSC 服务，有需求要联系 Cursor 评估。

前置条件这一段不要跳过：Cursor Enterprise 工作区；自托管的 GHES / GitLab Enterprise / Bitbucket Data Center 或私有包仓库，且经 HTTPS 在 443 端口可达；该主机名要有公开受信的 TLS 证书；你要拥有该主机名的 DNS；用 AWS PrivateLink 要有创建 endpoint service 或 interface VPC endpoint 的 AWS 权限；用 Cloudflare Tunnel 要有运行 cloudflared 的权限。

对应的不支持清单也写死了：自签证书、未加密连接、SSH、自定义端口、仅 IPv6 的 endpoint service，在这些私有连接路径上都不支持。很多内网环境恰好卡在自签证书和非 443 端口这两条上，先对照这份清单省事得多。

AWS PrivateLink 可覆盖两个方向，按网络策略可能只需要一个，也可能两个都要：一是 Cursor 访问你的私有 Git 供应商去 clone 仓库、调 Git API；二是你的 Git 供应商经 api2.cursor.sh 向 Cursor 发 webhook 或回调，而不需要公网出站。第二个方向文档给了 Terraform 示例，推荐模式是 AWS 托管私有 DNS，即 private_dns_enabled = true：

resource "aws_vpc_endpoint" "cursor_api2" {
  vpc_id              = aws_vpc.app.id
  service_name        = "com.amazonaws.vpce.us-east-1.vpce-svc-054b15427d4bea2b7"
  service_region      = "us-east-1"
  vpc_endpoint_type   = "Interface"
  subnet_ids          = [for subnet in aws_subnet.app_private : subnet.id]
  private_dns_enabled = true
  security_group_ids  = [aws_security_group.cursor_api2_endpoint.id]
}

上面的 endpoint service 名称是官方文档当时给出的示例值，服务名与可用的 consumer region 随时可能调整，实际填写以官方文档最新内容为准。文档写明这种模式下 AWS 会把你的 VPC 关联到 api2.cursor.sh 的托管私有托管区，VPC 内该域名解析到 endpoint ENI 的 IP，不需要额外的 Route 53 记录；想自己掌握 DNS 记录，文档另给了 private_dns_enabled = false 加自建 private hosted zone 的模式。还有一条容易漏：如果 GHES 或 GitLab Enterprise 用的是 endpoint VPC 之外的 DNS，要把 api2.cursor.sh 的查询转发到该 VPC 的 resolver 或做等价的私有 DNS 覆盖——文档明确要求不要做公网 DNS 覆盖。

至于 IP 白名单这条路，文档态度写得很清楚：Cloud Agent 的出站 IP 段可通过一个 JSON 端点获取（curl https://cursor.com/docs/ips.json），响应里有 version、modified、cloudAgents、gitEgressProxy 这几个字段。但文档同时写明他们会因扩容与运维需要不时变更 IP，不建议把 IP 白名单当作主要安全机制，非用不可就定期监控这个端点。对 Git 主机，文档更推荐 git egress proxy 的 IP allow list 配置，因为它与 Cursor 的 GitHub app 直接集成。所以本文不抄具体 IP，需要时按端点当时的返回取。

处置后怎么验证

如果你配的是 api2.cursor.sh 这条 PrivateLink webhook 路径，官方文档给了明确的检查动作，并要求从 GHES 或 GitLab Enterprise 实际使用的那条网络路径上执行：

getent hosts api2.cursor.sh
# or, if dig is available
dig +short api2.cursor.sh
curl -sS https://api2.cursor.sh/

判读标准文档也写死了：解析出的每个 IP 都应落在你 consumer VPC 的 CIDR 内，看到 3.x.x.x 或 44.x.x.x 这样的公网 IP 就说明私有 DNS 没生效；curl 请求应返回 HTTP 200，响应体以 Welcome to Cursor. 开头，这表示请求到达了一个活着的 Cursor api2 后端。

Windows 侧要说明的是：getent 是 Linux 上的工具，官方文档给的这组检查针对的是 GHES / GitLab Enterprise 所在那台主机，通常是 Linux，官方文档没有说明 Windows 侧的等价写法。如果你的 Git 服务器确实跑在 Windows 上，需要用系统自带或另行安装的解析与请求工具做等价检查——这属于通用运维做法，不是 Cursor 官方文档的内容，判读标准仍以上面两条（解析结果是否在 VPC CIDR 内、响应体是否以 Welcome to Cursor. 开头）为准。

如果你配的是域名 allowlist，验证方式朴素得多：让 agent 去访问那个域名，同时对照 artifact 上传是否恢复。文档写明屏蔽 artifact 主机只会禁用上传，agent 会话与其它工具调用照常工作——这一点反过来也是个有用的信号。

什么情况说明不是这个原因

几种看着像网络隔离、其实不是的情况，逐条对一下：

一、Privacy Mode (Legacy) 没切换。 文档写明 Privacy Mode (Legacy) 不被支持，因为它阻止云端数据存储，而 Cloud Agent 运行期间需要在云端存放代码与环境数据；使用前要先从 Dashboard → Cloud Agents 切换到 Privacy Mode。这种情况下 agent 根本起不来，不是访问不了内网的问题。

二、GHES 连上了，但在 app setup、repo sync 或 webhook 处理阶段失败。 官方文档的排障表把这条归因为 GHES 前面的代理拦截或改写了已认证的 GitHub REST / GraphQL API 请求，处置是放行 Cursor 的 GitHub App 使用这些已认证 API。这不是网络通路的问题，是代理策略的问题。

三、Cursor 报告 endpoint connection 正在等待客户操作。 文档写明这是因为 endpoint service 需要在你的 AWS 账号里手动接受，去审批待处理的连接请求即可。

四、TCP 到 api2.cursor.sh:443 超时。 文档归因为安全组、NACL、路由表或防火墙挡了到 endpoint ENI 的流量，处置是放行从 Git 供应商网络到 endpoint ENI 的 TCP 443。这属于你侧的网络策略，跟 Cloud Agent 的 allowlist 模式无关。

五、仓库权限不足。 文档写明需要给 Cursor 的 GitHub app 授予要编辑仓库的读写权限，用于 clone 与改动。权限没给够表现出来也是「拿不到代码」，但和出站网络是两码事。

最后补一条改之前最好知道的事：文档写明团队级 allowlist 与桌面端 Agent 的 sandbox default network allowlist 是同一份，管理员在 dashboard 上配的这份会同时作用于 Cloud Agent 的网络访问和 sandbox 的网络策略，没有第二份要单独维护。文档还对 Cloud Agent 的自动执行写了风险提示：agent 会自动运行所有终端命令以便迭代测试，这与需要用户逐条批准命令的前台 agent 不同，自动执行引入数据外泄风险，攻击者可能通过提示注入诱使 agent 把代码上传到恶意站点。这也是前面「不要用通配符放宽 allowlist」那条建议的背景。

本文依据 Cursor 官方文档（cursor.com/docs 与 cursor.com/help）于 2026-08-18 的公开内容整理。该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。该产品迭代频繁，文中涉及的设置项与命令随版本变动，请以官方文档最新内容为准。本文不涉及订阅价格、额度与模型清单，相关信息请以官方定价与模型说明页为准。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。

合规与许可条款请以官方原文与你所在组织的要求为准，本文不构成法律意见。