Communitygithub.com

マーケティングサイト開発 (Volcengine)

Astro 6 + React 19 アイランド + Tailwind 4 で構築したバイリンガル静的企業マーケティングサイトを、Volcengine TOS + CDN にエンドツーエンドでデプロイするための、意見が反映されたワークフロー。HTTPS、強制リダイレクト、HSTS、HTTP/2 をサポートし、`ve` CLI と Node SDK を介して完全に自動化します。

マーケティングサイト開発 (Volcengine) とは?

このスキルは、中国本土向けのバイリンガル(中文/英語)静的企業マーケティングサイトを Volcengine に構築およびデプロイするための、完全に自動化されたエンドツーエンドのワークフローを提供します。ビルドフェーズでは Astro 6、React 19(モバイルメニューのみ)、Tailwind 4 を使用し、単一のコンテンツファイル (`src/content/site.ts`) を情報源とします。デプロイフェーズでは、TOS バケット、CDN、無料 DV 証明書、HTTPS の強化を、冪等性のある Node スクリプト (`ve` CLI および自作の `volc-api.mjs` による SigV4 署名) で処理します。ユーザーは約 6 つのコマンドを実行するだけで、HTTPS、HTTP/2、HSTS、エッジキャッシュ、自動キャッシュ無効化を備えた本番品質のサイトを `https://<ドメイン>/` で公開できます。このスキルは、Astro エージェントスキルのインストールも自動化するため、将来のセッションでフレームワーク固有のガイダンスが利用可能になります。このワークフローは、中国企業向けで ICP 备案 が必要なサイト、またはすでに Volcengine エコシステムを利用しているユーザーに最適です。個人サイトや国際的なオーディエンスのみの場合は、Vercel や GitHub Pages のようなシンプルな代替案を推奨します。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/tenshowinnovation/tenshow-se-skills/tree/HEAD/marketing-site-dev

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

マーケティングサイト開発 (Volcengine) は何をしますか?

Volcengine 向けにバイリンガル静的企業マーケティングサイトを構築およびデプロイするためのエンドツーエンドスキル。2 つのフェーズ:

  1. ビルド — Astro 6 + React 19 アイランド (モバイルメニューのみ) + Tailwind 4。インライン SVG はすべての場所で使用。単一のコンテンツファイル (src/content/site.ts) が情報源です。
  2. デプロイ — TOS バケット + CDN + 無料 DV 証明書 + HTTPS 強化。すべて ve CLI および 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 が必要VercelVercel のプレビュー 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、証明書 SANICP 备案 が済んでおり、理想的には Volcengine DNS でホストされている必要があります。他でホストされている場合、ユーザーは手動で CNAME + TXT レコードを追加する必要があります。
3ブランドアセットディレクトリ (SVG ロゴファイルへのパス)インライン BrandMark.astro 抽出 (短いロゴ SVG の最後の 3 つのパス)通常は assets/logo/svg/Tenshow_short1.svg のようなもの — ショート / アイコンのみのバリアント。
4製品リストsite.ts の PRODUCTS[]各製品には、バイリンガルの名前と説明、URL、アクセントの16進カラー、アイコン列挙型が必要です。
5ICP 备案番号フッターMIIT 発行の 备案号。
6作業ディレクトリプロジェクトルートグリーンフィールド (空) である必要があります。そうでない場合は、既存のファイルと調整する必要があります。

オプション:

  • 公安备案号 — 通常、スキャフォールド時はプレースホルダー。README で明確にフラグを立て、ユーザーが起動前に置き換えるようにします。
  • ブランドアクセントカラー — ロゴ SVG の16進数値から抽出します。判断できない場合は、支配的なニュートラル以外の色をデフォルトにします。

ステップ 2: 静的サイトを構築する

詳細は references/phase-1-static-site.md にあります。概要:

  1. スキャフォールド — assets/templates/package.json と assets/templates/astro.config.mjs をプロジェクトルートにコピーします。package.json の name と astro.config.mjs の site を更新します。
  2. パッケージをインストール — pnpm install。
  3. Astro エージェントスキルをインストール — pnpm install が成功した後にのみ:
    npx skills add https://github.com/astrolicious/agent-skills --skill astro
    
    スキルのインストールに失敗した場合は、サイトのビルドを続行し、失敗をメモしてユーザーが後で再試行できるようにします。ワークフローをブロックしないでください。
  4. ソースツリーを作成 — 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) のレイアウトに一致するものを作成します。
  5. ブランドマークを抽出 — ユーザーの SVG から — assets/templates/BrandMark.astro を開始点として使用します。ショートロゴ SVG の最後の 3 つの <path> 要素がマークです。それらをそのままコピーし、ブランドパレットから塗りつぶしを選択します。
  6. セクションを構築 — ヒーロー (phase-1-static-site.md の正確なレシピ — グリッド背景 + 放射状グロー + グラデーションヘッドライン + ステータスピル + 2 つの CTA)、アバウト、製品、フォーカス、アップデート、お問い合わせ、フッター。ヘッダーはスティッキー、モバイルメニュー = 唯一の React アイランド。
  7. ローカルで確認 — 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 を読んでください — このフェーズの時間の半分は、コマンドを実行するのではなく、落とし穴を回避することに費やされます。

  1. スクリプトをコピー — assets/scripts/ ディレクトリ全体と assets/cdn-payloads/ を、それぞれユーザーの scripts/ と scripts/cdn-payloads/ にコピーします。assets/templates/deploy.config.mjs をプロジェクトルートにコピーし、bucket、region、endpoint、cdnDomains を入力します。
  2. ペイロードのプレースホルダーを置き換え — scripts/cdn-payloads/apex.json と www.json 内の {{DOMAIN}}、{{BUCKET}}、{{REGION}} を置き換えます。OriginHost は空ではなく、ドメイン自体である必要があります — テンプレートはそのまま正しい状態です。編集する場合は、OriginHost を保持してください。landmines.md #3 を参照してください。
  3. .env を作成 — プロジェクトルートに (gitignore されます):
    VOLC_ACCESS_KEY=AK...
    VOLC_SECRET_KEY=...
    
    Volcengine AK/SK には TOSFullAccess、CDNFullAccess、DNSFullAccess、CertificateFullAccess (または最小権限の同等物) が必要です。
  4. 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 にあります。読まないと遭遇するもの:

  1. HTTPS_PROXY の汚染 — TOS SDK + ローカル HTTP プロキシ = Protocol "http:" not supported。assets/scripts/ 内のすべてのスクリプトは、先頭でプロキシ環境変数を削除します — コピー/適用する場合は、そのプリアンブルを保持してください。
  2. TOS SDK の癖 — headBucket(string) は headBucket({bucket}) ではありません; listObjectsType2 のシグネチャは、入力に continuationToken: undefined があると壊れます; putObject はパブリックリードバケットでもデフォルトでプライベートになります — 常に acl: 'public-read' を設定してください。
  3. TOS には個別のウェブサイトエンドポイントホスト名がありません — 同じ <bucket>.tos-<region>.volces.com が、Host ヘッダーに応じてバケットリスト JSON または index.html を返します。(a) apex/www ドメインごとに putBucketCustomDomain を呼び出し、(b) CDN の AddCdnDomain ペイロードで OriginHost をユーザーのドメイン (空ではない) に設定する必要があります。
  4. 検証における CDN ≠ DCDN — CDN (内容分发网络) は TXT ホスト volccdnauth と cdn:CheckCdnDomain (ve CLI にはありません — volc-api.mjs を使用) を必要とします。DCDN (全站加速) は _dnsauth と ve dcdn VerifyDomainOwnership を使用します。これらを混同すると、無限の検証ループに陥ります。
  5. TXT 変更の伝搬には約 10 分かかります (Volcengine の検証器の場合)。最初の書き込みで値を正しく設定してください。変更を繰り返さないでください。
  6. pnpm deploy は組み込みコマンドです。 pnpm run deploy を使用してください。
  7. 無料 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 署名ツール、依存関係ゼロ。ve CLI にないアクションに使用します。
  • 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/ にコピー)

…[翻訳のため一部省略]

関連スキル