腾讯云 EdgeOne + COS 部署手册

本文整理两种常见部署模式：

1. API 加速⁠：客户端在 EdgeOne 边缘节点终止 TLS，EdgeOne 再通过 HTTPS 回源到负载均衡或源站。
2. 静态站点⁠：构建产物上传到 COS，EdgeOne 提供自定义域名、HTTPS、缓存与刷新能力。

所有示例都使用占位符，不包含真实账号、域名、Bucket、Zone、负载均衡器或凭证。生产环境中的 SecretId、SecretKey 和临时令牌应来自环境变量、密钥管理服务或 CI 的 Secret Store，不能写入仓库或公开文档。

1. 变量与安全边界

后续命令统一使用环境变量：

export TENCENTCLOUD_SECRET_ID='<secret-id>'
export TENCENTCLOUD_SECRET_KEY='<secret-key>'

export EO_ZONE_ID='<edgeone-zone-id>'
export API_DOMAIN='api.example.com'
export STATIC_DOMAIN='www.example.com'
export ORIGIN_DOMAIN='origin.example.internal'

export COS_BUCKET='example-web-<appid>'
export COS_REGION='ap-guangzhou'

安全原则：

• 管理账号只用于创建基础设施；部署流水线使用独立子账号或短期凭证。
• IAM/CAM 策略按具体 Bucket 和必要动作授权，不使用账号级 cos:*。
• 日志、Shell history 和 CI 输出中不得打印 SecretKey 或签名后的完整请求头。
• 公开文档只展示占位符；真实资源清单放入私有运维系统。

2. 模式 A：EdgeOne HTTPS 回源 API

flowchart LR
    C[Client] -->|HTTPS| EO[EdgeOne Edge]
    EO -->|HTTPS origin fetch| LB[Load Balancer / Reverse Proxy]
    LB --> APP[Application]

推荐顺序是“先回源、再证书、后 DNS”。这样可以在切换生产流量前完成验证，避免证书未部署或回源 Host 不匹配造成 5xx。

2.1 创建加速域名

tccli teo CreateAccelerationDomain \
  --region ap-guangzhou \
  --endpoint teo.tencentcloudapi.com \
  --ZoneId "$EO_ZONE_ID" \
  --DomainName "$API_DOMAIN" \
  --OriginInfo '{"OriginType":"IP_DOMAIN","Origin":"'"$ORIGIN_DOMAIN"'","PrivateAccess":"off"}' \
  --OriginProtocol HTTPS \
  --HttpsOriginPort 443

检查以下配置：

• 源站证书覆盖 ORIGIN_DOMAIN，证书链完整且未过期。
• 回源 Host 与负载均衡器的七层路由规则一致。
• 源站 443 端口允许 EdgeOne 回源，并避免无意暴露管理端口。
• HTTP 到 HTTPS 的跳转在预期层处理，避免回源重定向循环。

2.2 部署边缘证书

tccli teo ModifyHostsCertificate \
  --region ap-guangzhou \
  --endpoint teo.tencentcloudapi.com \
  --ZoneId "$EO_ZONE_ID" \
  --Hosts '["'"$API_DOMAIN"'"]' \
  --Mode eofreecert

轮询域名与证书状态，确认两者均已就绪后再改 DNS：

tccli teo DescribeAccelerationDomains \
  --region ap-guangzhou \
  --endpoint teo.tencentcloudapi.com \
  --ZoneId "$EO_ZONE_ID"

2.3 切换前验证

先解析 EdgeOne 分配的接入域名，使用 curl --resolve 让请求命中边缘节点，同时保留正确的 SNI 与 Host：

EO_CNAME="${API_DOMAIN}.eo.dnse1.com"
EO_IP=$(dig +short "$EO_CNAME" A | awk '/^[0-9.]+$/ {print; exit}')

curl --fail --show-error --silent \
  --resolve "${API_DOMAIN}:443:${EO_IP}" \
  -o /dev/null \
  -w 'HTTP %{http_code} TLS %{ssl_verify_result}\n' \
  "https://${API_DOMAIN}/health"

只有在 TLS 校验为 0、健康检查返回预期状态、回源日志无异常时，才将业务域名 CNAME 指向 EdgeOne。

2.4 DNS 切换

tccli dnspod ModifyRecord \
  --endpoint dnspod.tencentcloudapi.com \
  --Domain example.com \
  --RecordId '<record-id>' \
  --SubDomain api \
  --RecordType CNAME \
  --RecordLine Default \
  --Value "${API_DOMAIN}.eo.dnse1.com" \
  --TTL 600

切换前先降低 TTL；稳定运行后再恢复常规 TTL。保留原记录值，确保出现异常时可以快速回滚。

3. 模式 B：COS 静态站点 + EdgeOne

flowchart LR
    C[Browser] -->|HTTPS| EO[EdgeOne Edge]
    EO -->|Origin fetch| COS[COS static website endpoint]

3.1 准备 Bucket

静态网站托管通常需要：

• 创建指定区域的 Bucket。
• 上传 index.html 与静态资源。
• 配置静态网站首页和错误页。
• 根据业务需要决定公开读、私有回源或签名访问，不要机械地给整个 Bucket 开放写权限。

COS 静态网站端点通常形如：

<bucket>.cos-website.<region>.myqcloud.com

3.2 创建静态站点加速域名

COS_WEBSITE_ENDPOINT="${COS_BUCKET}.cos-website.${COS_REGION}.myqcloud.com"

tccli teo CreateAccelerationDomain \
  --region ap-guangzhou \
  --endpoint teo.tencentcloudapi.com \
  --ZoneId "$EO_ZONE_ID" \
  --DomainName "$STATIC_DOMAIN" \
  --OriginInfo '{"OriginType":"COS","Origin":"'"$COS_WEBSITE_ENDPOINT"'","PrivateAccess":"off"}' \
  --OriginProtocol FOLLOW \
  --HttpOriginPort 80 \
  --HttpsOriginPort 443

当 OriginType=COS 时，不要额外设置 HostHeader；由平台根据 COS 源站类型处理。随后按模式 A 的顺序部署边缘证书、预验证并切换 DNS。

3.3 上传与缓存刷新

coscli sync ./dist "cos://${COS_BUCKET}/" \
  --region "$COS_REGION" \
  --delete

tccli teo CreatePurgeTask \
  --region ap-guangzhou \
  --endpoint teo.tencentcloudapi.com \
  --ZoneId "$EO_ZONE_ID" \
  --Type purge_host \
  --Targets '["'"$STATIC_DOMAIN"'"]'

--delete 会删除目标端多余对象，只应在构建目录和目标 Bucket 前缀都已确认时使用。若发布流程不能保证这一点，改用不可变文件名并只上传新增资源。

4. 最小权限

部署账号应只获得目标 Bucket 与缓存刷新所需权限。下面是结构示意，不是可直接套用的完整策略：

{
  "version": "2.0",
  "statement": [
    {
      "effect": "allow",
      "action": [
        "cos:PutObject",
        "cos:DeleteObject",
        "cos:GetObject",
        "cos:GetBucket"
      ],
      "resource": [
        "qcs::cos:<region>:uid/<appid>:<bucket>/*"
      ]
    },
    {
      "effect": "allow",
      "action": ["teo:CreatePurgeTask"],
      "resource": ["<edgeone-resource-scope>"]
    }
  ]
}

实际动作名和资源格式应以当前腾讯云 CAM 文档及 API 返回为准。上线前使用独立测试账号验证“能发布、不能管理其他 Bucket”。

5. 上线检查表

• EdgeOne 域名状态正常。
• 边缘证书覆盖业务域名，证书链与有效期正常。
• API 回源使用 HTTPS，源站证书和 Host 路由正确。
• curl --resolve 预验证通过。
• DNS 原值已记录，可在故障时回滚。
• 静态资源使用内容哈希或明确的缓存版本策略。
• HTML 缓存时间短于带哈希的 JS/CSS/图片。
• 部署账号只拥有目标资源的最小权限。
• 日志、脚本和文档中没有真实密钥或账号级资源清单。

6. 常见故障

7. 回滚

出现证书、回源或缓存异常时：

1. 将 DNS 恢复到切换前记录。
2. 验证源站直连可用。
3. 保留 EdgeOne 配置用于离线排查，不要在故障中连续叠加修改。
4. 修复后再次通过 curl --resolve 预验证，再进行下一次切换。

把证书部署、预验证、DNS 切换和回滚明确拆开，远比“创建完域名立即改 DNS”更可靠。