PrivateLink 回调与排障

让私有 Git 服务通过 api2.cursor.sh 的私网端点向 Cursor 发送事件。

This page has not been translated into English yet. The original Chinese version is shown below.

当 GitHub Enterprise Server 或 GitLab Enterprise 不能访问公网，仍可通过 Cursor 发布的 AWS PrivateLink 服务发送 webhook 或 callback。这个方向与 Cursor 访问私有 Git 服务分别配置，按网络策略选择一个或两个方向。

服务参数

先让 Cursor 将你的 AWS principal 加入允许列表，再创建 interface VPC endpoint。

参数	官方当前值
Service name	`com.amazonaws.vpce.us-east-1.vpce-svc-054b15427d4bea2b7`
Service ID	`vpce-svc-054b15427d4bea2b7`
Home region	`us-east-1`
Consumer regions	`us-east-1`、`us-east-2`、`us-west-2`、`eu-central-1`、`eu-west-1`、`ap-southeast-2`
IP 类型	仅 IPv4
Private DNS	`api2.cursor.sh`

端点服务参数可能调整，实际开通时由 Cursor 确认。

DNS 两种模式

推荐 AWS-managed private DNS，把 private_dns_enabled 设为 true，AWS 自动关联私有 hosted zone，VPC 内无需另建 Route 53 记录。

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]
}

需要自主管理 DNS 时设为 false，创建仅关联 consumer VPC 的 api2.cursor.sh private hosted zone，并用 A alias 指向 endpoint DNS。官方页面给出了完整 Terraform 示例。

Git 服务使用 VPC 外部 DNS 时，把该域查询转发到 VPC resolver，或建立等效私有覆盖；不要创建公共 DNS 覆盖。

从真实 webhook 网络验证

在 Git 服务实际使用的网络路径执行：

getent hosts api2.cursor.sh
dig +short api2.cursor.sh
curl -sS https://api2.cursor.sh/

前两个命令是可替代的解析检查，按系统可用工具选择。解析结果应全部在 consumer VPC CIDR 内；看到公网 IP 表示私有 DNS 未生效。curl 应返回 HTTP 200，正文以 Welcome to Cursor. 开头，表示到达健康的 Cursor 后端。

常见失败

症状	检查方向
端点等待客户操作	AWS 待批准的 endpoint connection
DNS 返回公网 IP	private DNS 开关、DNS 转发和 Git 服务实际 resolver
TCP 443 超时	security group、NACL、路由和防火墙到 endpoint ENI 的访问
TLS 失败	DNS 目标、SNI 和主机名
GHES 能连通但 App 安装或同步失败	代理是否阻断或改写已认证 REST/GraphQL 请求
响应不是预期欢迎文本	记录时间、来源 VPC 和解析 IP，交给 Cursor 排查
Cloudflare Tunnel 不连接	出站防火墙、token、配置与 cloudflared 日志

建立 Cursor 到私有服务的方向见企业私网连接。