Skip to main content

Command Palette

Search for a command to run...

Agent

私有网络连接

Cherri Code 支持私有网络连接，满足企业版团队让 Cherri Code 与无法从公共互联网访问的系统协同工作的需求。这些系统包括自托管 GitHub Enterprise Server、GitLab Enterprise、Bitbucket Data Center、Artifactory、Nexus、私有源代码控制 API，以及这些系统回传至 Cherri Code 的 webhook 流量。

所有需要访问您的源代码控制系统的 Cherri Code 服务都使用相同的私有网络连接设置，包括 云端代理、Bugbot 和 Cherri Code 后端服务。

支持的选项

选项最适合用于云服务提供商状态
AWS PrivateLink在 Cherri Code 与您的 Git 提供商或软件包注册表之间建立私有网络连接，包括返回 Cherri Code 的 webhook 流量AWS支持
Cloudflare Tunnel当 AWS PrivateLink 不适用时，让 Cherri Code 访问私有源站可运行 cloudflared 的任何环境支持

如何选择

如果您的私有 Git 提供商或软件包注册表位于 AWS 中，或可部署在 AWS 网络负载均衡器之后，请使用 AWS PrivateLink。这是自托管 GitHub Enterprise Server 和 GitLab Enterprise 的首选方案。

AWS PrivateLink 可覆盖两个方向的流量：

  • Cherri Code 访问您的私有 Git 提供商，以克隆仓库并调用 Git API。
  • 您的 Git 提供商通过 api2.cursor.sh 向 Cherri Code 发送 Webhook 或回调，无需经由公共互联网出站。

如果无法发布 AWS 端点服务，或需要仅从您的网络建立出站隧道的部署模式，请使用 Cloudflare Tunnel。

如果您的团队需要 Google Private Service Connect (PSC)，请联系 Cherri Code。Cherri Code 目前不提供面向客户的 PSC 服务。

前提条件

开始前，请确保您具备：

  • Cherri Code 企业版工作区
  • 可通过 HTTPS 的 443 端口访问的自托管 GitHub Enterprise Server、GitLab Enterprise、Bitbucket Data Center 或私有软件包注册表 (如 Artifactory 或 Nexus)
  • Git 或注册表主机名的公信 TLS 证书
  • 该主机名的 DNS 所有权
  • 如果使用 AWS PrivateLink，具备创建端点服务或接口 VPC 端点的 AWS 权限
  • 如果使用 Cloudflare Tunnel，具备运行 cloudflared 的权限

Cherri Code 不支持在这些私有网络连接路径中使用自签名证书、未加密连接、SSH、自定义端口或仅支持 IPv6 的端点服务。

AWS PrivateLink

AWS PrivateLink 支持在 Cherri Code 与您的 Git 提供商或软件包注册表之间双向传输私有流量。具体需要单向还是双向连接，取决于您的网络策略。

方向 1：从 Cherri Code 到你的 Git 提供商或软件包注册表

当 Cherri Code 需要克隆仓库、调用 Git API 或访问 Artifactory 或 Nexus 等私有软件包注册表时，请选择此选项。

1. 创建 AWS 端点服务

在 Git 提供商或软件包注册表的 HTTPS 端点前配置网络负载均衡器。将该负载均衡器发布为 AWS VPC 端点服务。

向 Cherri Code 提供以下信息：

  • 端点服务名称，例如 com.amazonaws.vpce.us-east-1.vpce-svc-0123456789abcdef0
  • AWS 区域
  • Git 或注册表主机名，例如 github.example.com 或 artifactory.example.com
  • 端点服务是否启用了 AWS 托管私有 DNS
  • 网络负载均衡器是否保留客户端 IP，或后端是否按源 IP 进行筛选

如果端点服务不在 us-east-1，请在该端点服务上启用跨区域访问。

2. 授权 Cherri Code 的 AWS 主体

Cherri Code 会提供需要添加到端点服务“允许的主体”列表中的 AWS 主体。请添加 Cherri Code 提供的确切主体：

arn:aws:iam::<cursor-aws-account-id>:root

在允许此主体访问前，Cherri Code 无法创建接口端点。如果该主体缺失或不完全匹配，AWS 会返回 InvalidServiceName。

如果您的负载均衡器保留客户端 IP，或后端会筛选源 IP，请允许以下 Cherri Code PrivateLink 子网 CIDR：

10.2.8.0/2110.2.24.0/2110.2.40.0/21

3. 接受端点连接

Cherri Code 创建接口端点后，如果端点服务需要手动接受，请在您的 AWS 账户中接受该端点连接。

4. 配置 DNS

如果端点服务为 Git 或注册表主机名提供 AWS 托管的私有 DNS，Cherri Code 会在其接口端点上启用私有 DNS。

如果端点服务不提供私有 DNS，Cherri Code 会自行创建私有 DNS，并将该主机名映射到端点 DNS 名称。

在 Cherri Code 中使用与 TLS 证书和 DNS 中相同的主机名。

方向 2：从您的 Git 提供商到 api2.cursor.sh

如果您的 GitHub Enterprise Server 或 GitLab Enterprise 主机无法访问公共互联网，但仍需向 Cherri Code 发送 Webhook 或回调，请使用此选项。

Cherri Code 为 api2.cursor.sh 提供 AWS PrivateLink 端点服务。您可以在 AWS 账户中创建接口 VPC 端点并启用私有 DNS，使您的 Git 提供商网络将 api2.cursor.sh 解析为私有端点 IP 地址。

端点服务详情

创建端点前，Cherri Code 会确认您的 AWS 主体已加入允许列表。

字段值
服务名称com.amazonaws.vpce.us-east-1.vpce-svc-054b15427d4bea2b7
服务 IDvpce-svc-054b15427d4bea2b7
主区域us-east-1
支持的使用方区域us-east-1, us-east-2, us-west-2, eu-central-1, eu-west-1, ap-southeast-2
IP 地址类型仅 IPv4
私有 DNS 名称api2.cursor.sh

模式 1：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]}

AWS 会将您的 VPC 与 api2.cursor.sh 的私有托管区域关联。在 VPC 内，api2.cursor.sh 会解析为端点 ENI 的 IP 地址。无需创建 Route 53 记录。

模式 2：客户管理的私有托管区域

如果您希望自行管理 DNS 记录，请使用此模式。将 private_dns_enabled = false，然后为消费者 VPC 创建一个解析 api2.cursor.sh 的私有托管区域。

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 = false  security_group_ids  = [aws_security_group.cursor_api2_endpoint.id]}resource "aws_route53_zone" "cursor_api2" {  name    = "api2.cursor.sh"  comment = "Customer-managed PHZ for api2.cursor.sh scoped to the app VPC."  vpc {    vpc_id = aws_vpc.app.id  }}resource "aws_route53_record" "cursor_api2_a" {  zone_id = aws_route53_zone.cursor_api2.zone_id  name    = "api2.cursor.sh"  type    = "A"  alias {    name                   = aws_vpc_endpoint.cursor_api2.dns_entry[0].dns_name    zone_id                = aws_vpc_endpoint.cursor_api2.dns_entry[0].hosted_zone_id    evaluate_target_health = false  }}

如果 GitHub Enterprise Server 或 GitLab Enterprise 使用端点 VPC 外部的 DNS，请将对 api2.cursor.sh 的查询转发至 VPC 解析器，或创建等效的私有 DNS 覆盖。请勿创建公共 DNS 覆盖。

Cloudflare Tunnel

当 AWS PrivateLink 不适用时，请使用 Cloudflare Tunnel。

Cherri Code 会创建隧道，并提供：

  • 由 Cherri Code 控制的 DNS 下的公共主机名
  • 通过安全的 1Password 共享提供的隧道令牌
  • cloudflared 配置示例

您的网络运行 cloudflared 并向 Cloudflare 建立出站连接，无需配置入站防火墙规则。

cloudflared 配置示例：

ingress:  - hostname: <cursor-provided-hostname>    service: https://<your-internal-service>:443  - service: http_status:404

运行命令示例：

docker run -d --restart=always --name cloudflared \  -v /path/to/config.yml:/etc/cloudflared/config.yml \  cloudflare/cloudflared:latest \  tunnel --config /etc/cloudflared/config.yml \  run --token <TUNNEL_TOKEN>

请妥善保管隧道令牌，切勿通过电子邮件或 chat 发送。

完成源代码控制连接

配置好私有网络后，请在 Cherri Code 中完成源代码控制设置：

  • 如果使用 GitHub Enterprise Server，请按照 GitHub 集成设置 操作。
  • 如果使用 GitLab Enterprise，请按照 GitLab 集成设置 操作。
  • 如果使用 Bitbucket Data Center，请按照 Bitbucket 集成设置 操作。
  • 请使用 TLS 证书和私有 DNS 配置中包含的同一主机名。
  • 如果 Git 提供商前部署了代理，请确保其允许前提条件中所述的已认证 API 流量。

Cherri Code 会使用已连接的源代码控制集成，为云端代理、Bugbot 及其他需要访问代码仓库的 Cherri Code 服务提供支持。

检查私有 Webhook 路径

如果您的 Git 提供商通过 api2.cursor.sh PrivateLink 路径将 Webhook 发送到 Cherri Code，请从 GitHub Enterprise Server 或 GitLab Enterprise 所使用的同一网络路径运行以下检查：

getent hosts api2.cursor.sh# 或者，如果有 dig 命令dig +short api2.cursor.shcurl -sS #

解析出的每个 IP 都应位于您的 consumer VPC CIDR 内。如果看到 3.x.x.x 或 44.x.x.x 等 public IPs，说明私有 DNS 未生效。

curl 请求应返回 HTTP 200，且响应体以 Welcome to Cherri Code. 开头。这表明请求已到达正常运行的 Cherri Code api2 backend。

疑难排查

症状可能原因解决方法
Cherri Code 无法完成与您的 Git 提供商之间的私有连接Cherri Code 无法访问或连接到端点服务确认端点服务名称、区域和获准主体与 Cherri Code 提供的信息一致，然后将时间戳告知 Cherri Code
Cherri Code 显示端点连接正在等待客户操作端点服务需要在您的 AWS 账户中批准查看该服务待处理的端点连接请求，并批准 Cherri Code 的请求
Bugbot 或 Cloud Agents 可以连接到 GHES，但在 app 设置、仓库同步或 webhook 处理时失败GHES 前端的代理阻止或改写了经过身份验证的 GitHub REST 或 GraphQL API 请求允许 Cherri Code 的 GitHub App 集成使用经过身份验证的 GitHub REST 和 GraphQL API
api2.cursor.sh 解析为公共 IP 地址GitHub Enterprise Server 或 GitLab Enterprise 使用的解析器路径中未配置私有 DNS启用 AWS 托管的私有 DNS，或将 DNS 转发到端点 VPC 解析器
与 api2.cursor.sh:443 的 TCP 连接超时安全组、NACL、路由表或防火墙阻止了流向端点 ENI 的流量允许从您的 Git 提供商网络到端点 ENI 的 TCP 443 流量
api2.cursor.sh 的 TLS 连接失败DNS 指向错误的目标，或客户端未使用 SNI检查端点 DNS，并启用 SNI 后重试
curl # 未返回 Welcome to Cherri Code.流量未到达正常运行的 Cherri Code 后端将时间戳、源 VPC 和解析得到的端点 IP 地址告知 Cherri Code
Cloudflare Tunnel 无法连接cloudflared 无法连接到 Cloudflare，或 token/config 不正确检查出站防火墙规则、token 及 cloudflared 日志

Google Private Service Connect

Cherri Code 目前尚未提供面向客户的 Google Private Service Connect。

如果您需要从 GCP VPC 私有网络连接到 Cherri Code 服务，或从 Cherri Code 连接到 GCP 项目中的私有服务，请联系 Cherri Code，以便我们评估具体需求。目前，在适用的情况下，请使用 AWS PrivateLink 或 Cloudflare Tunnel。

需提供给 Cherri Code 的信息

对于连接您的 Git 提供商或软件包注册表的 AWS PrivateLink：

  • 端点服务名称
  • AWS 区域
  • Git 或注册表主机名
  • 是否启用了私有 DNS
  • 负载均衡器是否保留客户端 IP 地址或筛选源 IP 地址

对于通过 AWS PrivateLink 访问 api2.cursor.sh：

  • 需要加入 Cherri Code 允许列表的 AWS 主体
  • 将创建接口端点的 VPC 和区域
  • 是否计划使用 AWS 托管的私有 DNS 或客户管理的 DNS

对于 Cloudflare Tunnel：

  • 内部源站 URL
  • 用于安全的 1Password 共享的客户联系人
  • 任何主机名或命名限制

延伸阅读