腾讯云 EdgeOne + COS 導入ガイド

本稿では、2つの一般的な導入モードを整理しています。

1. API 加速⁠：クライアントは EdgeOne エッジノードで TLS を終端し、EdgeOne は HTTPS 経由でロードバランサまたはオリジンサーバーへバックエンド参照（オリジンフェッチ）を行います。
2. 静的サイト⁠：ビルド成果物を COS にアップロードし、EdgeOne がカスタムドメイン、HTTPS、キャッシュ、およびクリア機能を提供します。

すべての例ではプレースホルダーを使用しており、実際のアカウント、ドメイン、バケット、ゾーン、ロードバランサ、または認証情報は含まれていません。本番環境における SecretId、SecretKey、および一時トークンは、環境変数、シークレット管理サービス、または CI のシークレットストアから取得すべきであり、リポジトリや公開ドキュメントに書き込んではいけません。

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 ポリシーは、特定のバケットと必要なアクションに基づいて付与し、アカウントレベルの cos:* は使用しません。
• ログ、シェル履歴、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 が、ロードバランサのレイヤー7ルーティングルールと一致していること。
• オリジンサーバーの 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 バケットの準備

静的ウェブサイトホスティングには通常、以下が必要です。

• 指定されたリージョンにバケットを作成する。
• index.html と静的リソースをアップロードする。
• 静的ウェブサイトのトップページとエラーページを設定する。
• ビジネスの要件に応じて、公開読み取り、プライベートオリジン参照、または署名付きアクセスを選択し、バケット全体に書き込み権限を無条件に付与しないでください。

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 オプションは、ターゲットエンドポイントに余分なオブジェクトがある場合に削除します。これは、ビルドディレクトリとターゲットバケットのプレフィックスが確認されている場合にのみ使用してください。公開プロセスでこれを保証できない場合は、不変なファイル名を使用し、新規リソースのみをアップロードしてください。

4. 最小権限

デプロイアカウントは、ターゲットバケットとキャッシュクリアに必要な権限のみを持つべきです。以下は構造の例示であり、そのまま適用できる完全なポリシーではありません。

{
  "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 のレスポンスに基づいてください。本番公開前に、独立したテストアカウントを使用して「公開は可能だが、他のバケットの管理はできない」ことを検証してください。

5. 公開チェックリスト

• EdgeOne ドメインの状態が正常である。
• エッジ証明書がビジネスドメインをカバーしており、証明書チェーンと有効期限が正常である。
• API オリジン参照に HTTPS が使用されており、オリジンサーバーの証明書と Host ルーティングが正しい。
• curl --resolve による事前検証が通過した。
• DNS の元の値が記録されており、障害時にロールバック可能である。
• 静的リソースにはコンテンツハッシュまたは明確なキャッシュバージョン戦略が使用されている。
• HTML のキャッシュ時間は、ハッシュ付きの JS/CSS/画像よりも短い。
• デプロイアカウントは、ターゲットリソースに対して最小権限のみを持っている。
• ログ、スクリプト、ドキュメントに、実際のシークレットやアカウントレベルのリソースリストが含まれていない。

6. よくある障害

7. ロールバック

証明書、オリジン参照、またはキャッシュに異常が発生した場合：

1. DNS を切替前のレコードに戻す。
2. オリジンサーバーへのダイレクト接続が利用可能であることを確認する。
3. EdgeOne の設定を保持し、オフラインでの調査に備える。障害中に連続して変更を加えないこと。
4. 修正後、再度 curl --resolve による事前検証を行い、その後次の切替を行う。

証明書デプロイ、事前検証、DNS 切替、およびロールバックを明確に分離することは、「ドメイン作成直後に DNS を変更する」アプローチよりもはるかに信頼性が高くなります。