---
title: 腾讯云 EdgeOne + COS 部署手册：API 回源与静态站点
url: https://doc.liz6.com/devops/runbooks/wildwindstudio-edgeone-setup
locale: zh
area: devops
tags:
- EdgeOne
- COS
- CDN
- DNSPod
- HTTPS
- DevOps
- devops
- runbooks
date: 2026-08-11
modified: 2026-08-11
description: 一份可复用、已脱敏的腾讯云 EdgeOne 部署指南，覆盖 HTTPS API 回源、COS 静态站点、证书上线、DNS 切换、缓存刷新、最小权限与故障排查。
---

# 腾讯云 EdgeOne + COS 部署手册

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

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

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

## 1. 变量与安全边界

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

```bash
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

```mermaid
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 创建加速域名

```bash
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 部署边缘证书

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

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

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

### 2.3 切换前验证

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

```bash
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 切换

```bash
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

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

### 3.1 准备 Bucket

静态网站托管通常需要：

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

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

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

### 3.2 创建静态站点加速域名

```bash
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 上传与缓存刷新

```bash
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 与缓存刷新所需权限。下面是结构示意，不是可直接套用的完整策略：

```json
{
  "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. 常见故障

| 症状 | 常见原因 | 排查方式 |
|---|---|---|
| `teo.intl...` 超时 | CLI 使用了国际站端点 | 显式指定 `--endpoint teo.tencentcloudapi.com` |
| TLS 握手失败 | 边缘证书仍在部署，或 SNI/域名不匹配 | 检查证书状态并用 `openssl s_client -servername` 验证 |
| EdgeOne 返回 5xx | 源站不可达、回源 Host 错误或源站证书失败 | 查看回源日志并直接验证源站 HTTPS |
| COS 回源配置拒绝 HostHeader | COS 源站类型不允许自定义 HostHeader | 移除该配置，让平台自动处理 |
| 上传返回 `403 AccessDenied` | 子账号缺少目标 Bucket 动作或资源范围 | 检查 CAM 策略的 action 与 resource |
| 发布后仍看到旧页面 | HTML 缓存未刷新或缓存键不符合预期 | 查询缓存状态并按域名/URL 刷新 |
| DNS 切换后部分地区仍访问旧源 | TTL 尚未到期或递归解析器缓存 | 使用多个公共 DNS 查询并等待传播 |

## 7. 回滚

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

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

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