app-platform-networking

应用平台网络技能

配置域名、路由、CORS、VPC、静态 IP 和服务间通信。

快速决策

What networking do you need?
├── Custom domain?
│   └── YES → See domains-dns.md
│
├── Multiple services on one domain?
│   ├── Different paths (/api, /app) → Path-based routing
│   └── Different subdomains (api.*, app.*) → Subdomain routing
│
├── Frontend calling API across origins?
│   └── YES → CORS configuration
│
├── Secure database connectivity?
│   └── YES → VPC + trusted sources
│
└── Need static outbound IP?
    └── YES → Dedicated egress

---

适用场景

场景	是否需要此技能
仅使用入门域名	否
自定义域名	是
多个服务使用不同路径	是
多个子域名	是
跨子域名 API 调用（CORS）	是
通过 VPC 安全访问数据库	是
防火墙允许列表（出站 IP）	是

---

快速参考

功能	App Spec 字段	示例
自定义域名	domains[].domain	example.com
通配符	domains[].wildcard	true
路径路由	ingress.rules[].match.path.prefix	/api
子域名路由	ingress.rules[].match.authority.exact	api.example.com
CORS	ingress.rules[].cors	参见参考文档
VPC	vpc.id	UUID
专用出站 IP	egress.type	DEDICATED_IP

---

基于路径的路由（快速入门）

ingress:
  rules:
    - component: { name: api }
      match: { path: { prefix: /api } }

    - component: { name: frontend }
      match: { path: { prefix: / } }

规则顺序很重要： 将特定规则放在前面。

完整指南：参见 ingress-routing.md

---

子域名路由（快速入门）

domains:
  - domain: example.com
    type: PRIMARY
    wildcard: true
    zone: example.com

ingress:
  rules:
    - component: { name: api }
      match:
        authority: { exact: api.example.com }
        path: { prefix: / }

    - component: { name: app }
      match:
        authority: { exact: app.example.com }
        path: { prefix: / }

完整指南：参见 domains-dns.md

---

CORS（快速入门）

ingress:
  rules:
    - component: { name: api }
      match: { path: { prefix: /api } }
      cors:
        allow_origins:
          - exact: https://app.example.com
        allow_methods: [GET, POST, PUT, DELETE, OPTIONS]
        allow_headers: [Content-Type, Authorization]
        allow_credentials: true

注意： 使用 allow_credentials: true 时，仅使用精确来源（不要使用正则表达式）。

完整指南：参见 cors-configuration.md

---

VPC + 可信来源（快速入门）

vpc:
  id: your-vpc-uuid

VPC CIDR 允许列表（推荐）：

doctl vpcs get $VPC_ID --format IPRange  # e.g., 10.126.0.0/20
doctl databases firewalls append $CLUSTER_ID --rule ip_addr:10.126.0.0/20

设置	可信来源规则
仅公开访问	app:$APP_ID
已启用 VPC	ip_addr:<vpc-cidr>

重要： 即使使用 VPC，可绑定变量仍会返回公共主机名。请使用私有 URL：

doctl databases connection --private <cluster-id> --format URI

完整指南：参见 vpc-trusted-sources.md

---

参考文件

• domains-dns.md — 域名类型、DNS 设置、通配符、TLS、CAA
• ingress-routing.md — 路径路由、重写、重定向、authority 匹配
• cors-configuration.md — CORS 字段、模式、凭据
• vpc-trusted-sources.md — VPC 设置、可信来源矩阵、私有 URL
• static-ips-egress.md — 入站 IP、专用出站、HTTP/2、内部端口
• complete-patterns.md — 5 种完整架构模式

---

常见问题

问题	解决方法
域名无法解析	检查 DNS 记录，并等待最多 72 小时完成传播
SSL 证书错误	添加 letsencrypt.org 和 pki.goog 的 CAA 记录
CORS 预检失败	将 OPTIONS 添加到 allow_methods
VPC 连接被拒绝	使用 VPC CIDR 允许列表，而不是基于应用的规则
请求被错误组件处理	调整规则顺序（特定规则放在前面）

---

与其他技能集成

• → designer：向 app spec 添加域名/入口配置
• → troubleshooting：排查 DNS、CORS、VPC 问题
• → postgres：为托管数据库配置 VPC 连接
• → deployment：部署网络配置更改