--- title: 腾讯云 EdgeOne + COS 導入ガイド：API オリジン参照と静的サイト url: https://doc.liz6.com/ja/devops/runbooks/wildwindstudio-edgeone-setup locale: ja 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 導入ガイド 本稿では、2つの一般的な導入モードを整理しています。 1. **API 加速**：クライアントは EdgeOne エッジノードで TLS を終端し、EdgeOne は HTTPS 経由でロードバランサまたはオリジンサーバーへバックエンド参照（オリジンフェッチ）を行います。 2. **静的サイト**：ビルド成果物を COS にアップロードし、EdgeOne がカスタムドメイン、HTTPS、キャッシュ、およびクリア機能を提供します。 すべての例ではプレースホルダーを使用しており、実際のアカウント、ドメイン、バケット、ゾーン、ロードバランサ、または認証情報は含まれていません。本番環境における SecretId、SecretKey、および一時トークンは、環境変数、シークレット管理サービス、または CI のシークレットストアから取得すべきであり、リポジトリや公開ドキュメントに書き込んではいけません。 ## 1. 変数とセキュリティ境界 以降のコマンドでは、環境変数を統一して使用します。 ```bash export TENCENTCLOUD_SECRET_ID='' export TENCENTCLOUD_SECRET_KEY='' export EO_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-' export COS_REGION='ap-guangzhou' ``` セキュリティ原則： - 管理アカウントはインフラストラクチャの作成にのみ使用し、デプロイパイプラインでは独立したサブアカウントまたは短期間の認証情報を使用します。 - IAM/CAM ポリシーは、特定のバケットと必要なアクションに基づいて付与し、アカウントレベルの `cos:*` は使用しません。 - ログ、シェル履歴、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 が、ロードバランサのレイヤー7ルーティングルールと一致していること。 - オリジンサーバーの 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 '' \ --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 バケットの準備 静的ウェブサイトホスティングには通常、以下が必要です。 - 指定されたリージョンにバケットを作成する。 - `index.html` と静的リソースをアップロードする。 - 静的ウェブサイトのトップページとエラーページを設定する。 - ビジネスの要件に応じて、公開読み取り、プライベートオリジン参照、または署名付きアクセスを選択し、バケット全体に書き込み権限を無条件に付与しないでください。 COS 静的ウェブサイトエンドポイントは通常、以下のような形式になります。 ```text .cos-website..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` オプションは、ターゲットエンドポイントに余分なオブジェクトがある場合に削除します。これは、ビルドディレクトリとターゲットバケットのプレフィックスが確認されている場合にのみ使用してください。公開プロセスでこれを保証できない場合は、不変なファイル名を使用し、新規リソースのみをアップロードしてください。 ## 4. 最小権限 デプロイアカウントは、ターゲットバケットとキャッシュクリアに必要な権限のみを持つべきです。以下は構造の例示であり、そのまま適用できる完全なポリシーではありません。 ```json { "version": "2.0", "statement": [ { "effect": "allow", "action": [ "cos:PutObject", "cos:DeleteObject", "cos:GetObject", "cos:GetBucket" ], "resource": [ "qcs::cos::uid/:/*" ] }, { "effect": "allow", "action": ["teo:CreatePurgeTask"], "resource": [""] } ] } ``` 実際のアクション名とリソース形式は、現在の腾讯云 CAM ドキュメントおよび API のレスポンスに基づいてください。本番公開前に、独立したテストアカウントを使用して「公開は可能だが、他のバケットの管理はできない」ことを検証してください。 ## 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` が返る | サブアカウントがターゲットバケットのアクションまたはリソース範囲の権限を持っていない | CAM ポリシーの action と resource を確認する | | 公開後も古いページが表示される | HTML のキャッシュがクリアされていない、またはキャッシュキーが予期と一致しない | キャッシュステータスを確認し、ドメイン/URL 単位でクリアする | | DNS 切替後、一部の地域でまだ旧オリジンにアクセスされる | TTL が期限切れになっていない、または再帰型 DNS キャッシュが残っている | 複数の公開 DNS でクエリを実行し、伝播を待つ | ## 7. ロールバック 証明書、オリジン参照、またはキャッシュに異常が発生した場合： 1. DNS を切替前のレコードに戻す。 2. オリジンサーバーへのダイレクト接続が利用可能であることを確認する。 3. EdgeOne の設定を保持し、オフラインでの調査に備える。障害中に連続して変更を加えないこと。 4. 修正後、再度 `curl --resolve` による事前検証を行い、その後次の切替を行う。 証明書デプロイ、事前検証、DNS 切替、およびロールバックを明確に分離することは、「ドメイン作成直後に DNS を変更する」アプローチよりもはるかに信頼性が高くなります。