マーケティングサイト開発 (Volcengine) は何をしますか?
Volcengine 向けにバイリンガル静的企業マーケティングサイトを構築およびデプロイするためのエンドツーエンドスキル。2 つのフェーズ:
- ビルド — Astro 6 + React 19 アイランド (モバイルメニューのみ) + Tailwind 4。インライン SVG はすべての場所で使用。単一のコンテンツファイル (
src/content/site.ts) が情報源です。 - デプロイ — TOS バケット + CDN + 無料 DV 証明書 + HTTPS 強化。すべて
veCLI および Volcengine OpenAPI (veが提供しないアクションについてはvolc-api.mjsで SigV4 署名) を介して、冪等性のある Node スクリプトでスクリプト化されています。
成功の指標: ユーザーがエンドツーエンドで約 6 つのコマンドを実行し、https://<ドメイン>/ で本番品質のバイリンガルサイトが提供され、HTTPS、HTTPS への強制リダイレクト、HSTS、HTTP/2、エッジキャッシュ、自動キャッシュ無効化が有効になっていること。すべてのインフラストラクチャステップは、冪等性のあるスクリプトとしてバージョン管理されています。
このスキルは適切ですか?
これは意図的に意見が反映されたワークフローであり、特定のシナリオに最適化されています。詳細に入る前に、そのシナリオが実際にユーザーの状況と一致するかどうかを確認してください。一致しない場合は、ユーザーに負荷の高いパスを強制するのではなく、より優れた代替案を提示してください。
以下の場合にこのスキルを使用します:
- サイトが中国企業、または中国本土のユーザーをターゲットにした製品向けである場合 — 中国本土から中国国外の CDN へのレイテンシは十分に悪く (200~400ms、ピーク時はさらに悪化)、訪問者が気付いて離脱します。
- ICP 备案 が必要、またはすでに取得している場合 — 中国国内で合法的に配信するには、中国のクラウドでホストされているドメインに紐付けられた登録が必要です。Volcengine は备案 のサポートをバンドルしており、ここでデプロイするドメインに対して提供しています。
- ユーザーがすでに Volcengine エコシステム (他の Volcengine サービス、既存の TOS バケットなど) を利用しており、統合に価値がある場合。
- バイリンガル (zh/en) パターンが望まれている場合 — コンテンツレイヤー (
site.ts) はそれを前提に設計されています。
以下の場合は、よりシンプルな代替案を使用します:
| シナリオ | 推奨代替案 | 理由 |
|---|---|---|
| 個人サイト / ポートフォリオ / サイドプロジェクト、中国のオーディエンス要件なし | GitHub Pages | 無料、自動 HTTPS、git push でデプロイ、管理するインフラなし。Volcengine の落とし穴はゼロ。 |
| 国際的なオーディエンスのみ (米国/欧州/東南アジア)、中国展開の計画なし | Vercel (または Cloudflare Pages / Netlify) | 無料枠、git からの即時デプロイ、PR ごとのプレビュー URL、自動 HTTPS、グローバルエッジネットワーク。ve CLI + ICP ワークフロー全体をスキップ。 |
| サーバーレス関数 (フォーム、認証、動的コンテンツ) が必要なサイト | Vercel または Cloudflare Pages (エッジ関数を使用) | このスキルは純粋に静的サイトを出荷します — Volcengine にもサーバーレス製品はありますが、このワークフローではカバーしていません。 |
| ブランチ / PR ベースのレビュー用プレビュー URL が必要 | Vercel | Vercel のプレビュー URL UX は業界最高です。このスキルはプッシュごとに 1 つの本番デプロイを生成します。ブランチプレビューはありません。 |
ユーザーの状況が「よりシンプルな代替案を使用」の列に一致する場合は、何かをスキャフォールドする前に明示的にその旨を伝えてください。ユーザーが Volcengine の提供するものを必要としない場合、30 分の Volcengine ブートストラップよりも 2 分の Vercel デプロイの方が優れたエクスペリエンスです。このスキルを呼び出したからといって、間違ったスタックにユーザーを引きずり込まないでください。
迷ったときは、次のように質問してください: 「中国本土のユーザーがあなたのオーディエンスの重要な部分を占めますか?また、そのドメインの ICP 备案 を取得していますか(または取得する予定ですか)?」 両方の答えが「いいえ」の場合は、Vercel / GitHub Pages を指摘して終了します。
ステップ 1: 意図をキャプチャする (常に最初に質問する)
ユーザーから以下の 6 つの入力を受け取るまで、コードを作成しないでください。プロンプトにない場合は、AskUserQuestion を使用して質問してください。ほとんどのチームはすべてを用意していますが、公安备案番号は除く可能性があります — これはプレースホルダーでも問題ありません。
| # | 入力 | 使用箇所 | メモ |
|---|---|---|---|
| 1 | 会社名 (中国語 + 英語) | site.ts の COMPANY.nameZh / COMPANY.nameEn、フッター、SEO | |
| 2 | ドメイン (例: example.com) | すべての場所 — バケットバインディング、CDN、DNS、証明書 SAN | ICP 备案 が済んでおり、理想的には Volcengine DNS でホストされている必要があります。他でホストされている場合、ユーザーは手動で CNAME + TXT レコードを追加する必要があります。 |
| 3 | ブランドアセットディレクトリ (SVG ロゴファイルへのパス) | インライン BrandMark.astro 抽出 (短いロゴ SVG の最後の 3 つのパス) | 通常は assets/logo/svg/Tenshow_short1.svg のようなもの — ショート / アイコンのみのバリアント。 |
| 4 | 製品リスト | site.ts の PRODUCTS[] | 各製品には、バイリンガルの名前と説明、URL、アクセントの16進カラー、アイコン列挙型が必要です。 |
| 5 | ICP 备案番号 | フッター | MIIT 発行の 备案号。 |
| 6 | 作業ディレクトリ | プロジェクトルート | グリーンフィールド (空) である必要があります。そうでない場合は、既存のファイルと調整する必要があります。 |
オプション:
- 公安备案号 — 通常、スキャフォールド時はプレースホルダー。README で明確にフラグを立て、ユーザーが起動前に置き換えるようにします。
- ブランドアクセントカラー — ロゴ SVG の16進数値から抽出します。判断できない場合は、支配的なニュートラル以外の色をデフォルトにします。
ステップ 2: 静的サイトを構築する
詳細は references/phase-1-static-site.md にあります。概要:
- スキャフォールド —
assets/templates/package.jsonとassets/templates/astro.config.mjsをプロジェクトルートにコピーします。package.json のnameと astro.config.mjs のsiteを更新します。 - パッケージをインストール —
pnpm install。 - Astro エージェントスキルをインストール —
pnpm installが成功した後にのみ:
スキルのインストールに失敗した場合は、サイトのビルドを続行し、失敗をメモしてユーザーが後で再試行できるようにします。ワークフローをブロックしないでください。npx skills add https://github.com/astrolicious/agent-skills --skill astro - ソースツリーを作成 — phase-1-static-site.md (
src/content/site.ts、src/components/、src/layouts/BaseLayout.astro、src/pages/index.astro、src/pages/en/index.astro、src/styles/global.css) のレイアウトに一致するものを作成します。 - ブランドマークを抽出 — ユーザーの SVG から —
assets/templates/BrandMark.astroを開始点として使用します。ショートロゴ SVG の最後の 3 つの<path>要素がマークです。それらをそのままコピーし、ブランドパレットから塗りつぶしを選択します。 - セクションを構築 — ヒーロー (phase-1-static-site.md の正確なレシピ — グリッド背景 + 放射状グロー + グラデーションヘッドライン + ステータスピル + 2 つの CTA)、アバウト、製品、フォーカス、アップデート、お問い合わせ、フッター。ヘッダーはスティッキー、モバイルメニュー = 唯一の React アイランド。
- ローカルで確認 —
pnpm devで開発、pnpm build && pnpm previewでインフラに触れる前に静的出力を sanity check します。
スタックの固定 (逸脱しないこと)
Astro 6、React 19 (モバイルメニューのみ)、Tailwind 4 (@tailwindcss/vite 経由)、pnpm 10、Node 22+、TypeScript strict、外部画像ゼロ、UI ライブラリゼロ、フォントサービスゼロ、システムフォントスタック。根拠と詳細は phase-1-static-site.md にあります。
ステップ 3: デプロイインフラをセットアップする
詳細は references/phase-2-volcengine-deploy.md にあります。最初に references/landmines.md を読んでください — このフェーズの時間の半分は、コマンドを実行するのではなく、落とし穴を回避することに費やされます。
- スクリプトをコピー —
assets/scripts/ディレクトリ全体とassets/cdn-payloads/を、それぞれユーザーのscripts/とscripts/cdn-payloads/にコピーします。assets/templates/deploy.config.mjsをプロジェクトルートにコピーし、bucket、region、endpoint、cdnDomainsを入力します。 - ペイロードのプレースホルダーを置き換え —
scripts/cdn-payloads/apex.jsonとwww.json内の{{DOMAIN}}、{{BUCKET}}、{{REGION}}を置き換えます。OriginHostは空ではなく、ドメイン自体である必要があります — テンプレートはそのまま正しい状態です。編集する場合は、OriginHostを保持してください。landmines.md #3 を参照してください。 .envを作成 — プロジェクトルートに (gitignore されます):
Volcengine AK/SK にはVOLC_ACCESS_KEY=AK... VOLC_SECRET_KEY=...TOSFullAccess、CDNFullAccess、DNSFullAccess、CertificateFullAccess(または最小権限の同等物) が必要です。veがインストールされていることを確認:ve version— 1.0.x 以降が必要です。ない場合は、Volcengine の公式ドキュメントに従ってインストールします。
ステップ 4: 初回デプロイを実行する
pnpm install # まだの場合
npx skills add https://github.com/astrolicious/agent-skills --skill astro # まだの場合
pnpm build # ローカルビルドが動作することを確認
pnpm run setup:bucket # 冪等: バケット + ウェブサイトルーティング + カスタムドメインバインディング
pnpm run deploy:upload # dist/ をバケットに同期
# この時点で: https://<bucket>.tos-<region>.volces.com/index.html が 200 を返すはず
pnpm run setup:cdn # 検証 → CDN 追加 → CNAME → 証明書 → HTTPS 強化
# DNS 伝搬に 1~3 分待機
pnpm run cdn:refresh # 初回アクセスでバケットリスト JSON が返されないようにエッジキャッシュをパージ
この初回実行後、日常的なイテレーションは1 つのコマンドになります:
pnpm run deploy && pnpm run cdn:refresh
常に pnpm run を使用し、裸の pnpm は使用しない
pnpm deploy は pnpm の組み込みワークスペースコマンドです — ワークスペース外では ERR_PNPM_CANNOT_DEPLOY でエラーになります。pnpm run deploy と pnpm run cdn:refresh を使用してください。これをプロジェクトの README に記載してください。landmines.md #6 を参照してください。
ステップ 5: 確認
references/verification.md の curl + openssl チェックリストを実行します。期待される結果: 主要ルートで 5 回の HTTP 200、HTTP → HTTPS で 1 回の 301、apex + www をカバーする SAN を持つ有効な証明書、HTTP/2 + HSTS の確認、deploy.config.mjs ルールに一致するキャッシュコントロールヘッダー。
いずれかのチェックに失敗した場合、verification.md は各障害モードを根本原因と修正方法にマッピングしています。
実行前に知っておくべき重要な落とし穴
完全な列挙は landmines.md にあります。読まないと遭遇するもの:
HTTPS_PROXYの汚染 — TOS SDK + ローカル HTTP プロキシ =Protocol "http:" not supported。assets/scripts/内のすべてのスクリプトは、先頭でプロキシ環境変数を削除します — コピー/適用する場合は、そのプリアンブルを保持してください。- TOS SDK の癖 —
headBucket(string)はheadBucket({bucket})ではありません;listObjectsType2のシグネチャは、入力にcontinuationToken: undefinedがあると壊れます;putObjectはパブリックリードバケットでもデフォルトでプライベートになります — 常にacl: 'public-read'を設定してください。 - TOS には個別のウェブサイトエンドポイントホスト名がありません — 同じ
<bucket>.tos-<region>.volces.comが、Hostヘッダーに応じてバケットリスト JSON またはindex.htmlを返します。(a) apex/www ドメインごとにputBucketCustomDomainを呼び出し、(b) CDN のAddCdnDomainペイロードでOriginHostをユーザーのドメイン (空ではない) に設定する必要があります。 - 検証における CDN ≠ DCDN — CDN (内容分发网络) は TXT ホスト
volccdnauthとcdn:CheckCdnDomain(veCLI にはありません —volc-api.mjsを使用) を必要とします。DCDN (全站加速) は_dnsauthとve dcdn VerifyDomainOwnershipを使用します。これらを混同すると、無限の検証ループに陥ります。 - TXT 変更の伝搬には約 10 分かかります (Volcengine の検証器の場合)。最初の書き込みで値を正しく設定してください。変更を繰り返さないでください。
pnpm deployは組み込みコマンドです。pnpm run deployを使用してください。- 無料 DV 証明書の申請はコンソールのみです。 永続的な AK/SK (
OperationDenied.RequestFreeInstance) では API 発行がブロックされます。ただし、すでに発行された証明書のリストは機能します — 無料 DV 証明書はドメイン登録時に自動発行されることがよくあります。常に最初にCertificateGetInstanceListを実行してください。apex + www の両方をカバーするSanを持つものをResult.Instances[](InstanceListでもDataでもありません) から探します。
動作ルール
- 最初に計画し、破壊的操作の前に確認する。
createBucket、AddCdnDomain、既存の TXT に対するDeleteRecord、またはBatchDeployCertの前に、何が起ころうとしているかを要約し、ユーザーに確認を求めます。 - 書き込む前に既存の状態を読み取る。 常に最初に
ListRecords/ListCdnDomains/CertificateGetInstanceListを実行します — 無料証明書はしばしば事前発行されており、CDN ドメインはすでに存在する場合があり、DNS レコードはすでに正しい場所を指している場合があります。冪等性がすべてです。 veにアクションがない場合は、ユーザーにveのアップグレードやコンソールの使用を伝えるのではなく、volc-api.mjsを使用する。 唯一の真のコンソール専用パスは、無料 DV 証明書の発行です (landmines.md #4)。- DNS レコードを変更しすぎない。 TXT を変更するたびに約 10 分のキャッシュが追加されます。ホスト/値を最初の 1 回で正しく設定してください — CDN の場合は
volccdnauth、DCDN の場合は_dnsauth。これらは交換できません。 - すべての設定決定を
deploy.config.mjsに表示し、スクリプトにハードコードしない。 バケット、リージョン、エンドポイント、CDN ドメイン、キャッシュルール — すべて設定に配置し、ユーザーが 1 つのファイルを編集してすべてを変更できるようにします。 - 同じシェルで長時間のコマンドを実行した後にチェックを実行する場合、
/usr/bin/curlは裸のcurlよりも信頼性が高い — bash の PATH ルックアップが時々おかしくなることがあります。CI スクリプトのテストでも同様です。
バンドルされたアセットとリファレンス
assets/scripts/ (そのままユーザーの scripts/ にコピー)
lib/volc-api.mjs— SigV4 署名ツール、依存関係ゼロ。veCLI にないアクションに使用します。setup-bucket.mjs— 冪等性のあるバケット + ウェブサイト + カスタムドメインバインディング。deploy.mjs— プレフィックスごとのCache-Control、孤立ファイル削除機能付き TOS 同期アップローダー。cdn-setup.mjs— CDN オーケストレーション: 所有権確認 → AddCdnDomain → CNAME → 証明書 → HTTPS 強化。cdn-refresh.mjs—cdn:SubmitRefreshTaskによるキャッシュ無効化 (volc-api.mjsで署名、veなしで CI で動作)。
assets/cdn-payloads/ (scripts/cdn-payloads/ にコピー)
…[翻訳のため一部省略]