Développement Site Vitrine (Volcengine)
Compétence de bout en bout pour construire et livrer un site vitrine statique bilingue sur Volcengine. Deux phases :
- Construction — Astro 6 + React 19 islands (menu mobile uniquement) + Tailwind 4. SVG en ligne partout. Un seul fichier de contenu (
src/content/site.ts) est la source de vérité. - Déploiement — Bucket TOS + CDN + certificat DV gratuit + durcissement HTTPS, le tout scripté dans des scripts Node idempotents via l'interface en ligne de commande
veet les API Volcengine OpenAPI (signées SigV4 viavolc-api.mjspour les actions quevene propose pas).
À quoi ressemble le succès : l'utilisateur exécute ~6 commandes de bout en bout et obtient https://<son-domaine>/ servant un site bilingue de qualité production avec HTTPS, redirection forcée vers HTTPS, HSTS, HTTP/2, mise en cache périphérique et invalidation automatique du cache. Chaque étape d'infrastructure est dans le contrôle de version sous forme de script idempotent.
Cette compétence est-elle adaptée ?
Il s'agit d'un workflow délibérément avisé optimisé pour un scénario spécifique. Avant d'aller plus loin, vérifiez que ce scénario correspond réellement à la situation de l'utilisateur. Si ce n'est pas le cas, proposez la meilleure alternative plutôt que d'imposer un chemin plus lourd.
Utilisez cette compétence lorsque :
- Le site est destiné à une société chinoise ou à un produit ciblant les utilisateurs en Chine continentale — la latence depuis le continent vers les CDN non chinois est suffisamment mauvaise (200-400ms, souvent pire aux heures de pointe) pour que les visiteurs la remarquent et quittent le site.
- L'ICP 备案 est requis ou déjà en votre possession — distribuer en Chine de manière légale nécessite le dépôt lié à un domaine hébergé sur un cloud chinois. Volcengine fournit une assistance pour l'ICP et le propose pour le domaine que vous déployez ici.
- L'utilisateur est déjà dans l'écosystème Volcengine (autres services Volcengine, buckets TOS existants, etc.) et la consolidation est précieuse.
- Le modèle bilingue zh/en est souhaité — la couche de contenu (
site.ts) est conçue autour de cela.
Utilisez une alternative plus simple lorsque :
| Scénario | Alternative recommandée | Pourquoi |
|---|---|---|
| Site personnel / portfolio / projet secondaire, sans exigence d'audience chinoise | GitHub Pages | Gratuit, HTTPS automatique, déploiement sur git push, aucune infrastructure à gérer. Aucun des pièges Volcengine ne s'applique. |
| Audience internationale uniquement (US/EU/SEA), aucune présence en Chine prévue | Vercel (ou Cloudflare Pages / Netlify) | Niveau gratuit, déploiements instantanés depuis git, URL de prévisualisation par PR, HTTPS automatique, réseau périphérique mondial. Ignorez complètement l'interface ve et le workflow ICP. |
| Le site nécessite des fonctions serverless (formulaires, authentification, contenu dynamique) | Vercel ou Cloudflare Pages avec leurs fonctions périphériques | Cette compétence livre uniquement du statique — Volcengine a des produits serverless, mais ce workflow ne les couvre pas. |
| Vous voulez des URL de prévisualisation par branche / révision basée sur les PR | Vercel | L'UX d'URL de prévisualisation de Vercel est la meilleure de sa catégorie. Cette compétence produit un seul déploiement de production par push ; pas de prévisualisations de branche. |
Si la situation de l'utilisateur correspond à la colonne « Utilisez une alternative plus simple », dites-le lui explicitement avant de structurer quoi que ce soit. Un déploiement Vercel de 2 minutes est une meilleure expérience qu'un amorçage Volcengine de 30 minutes lorsque l'utilisateur n'a pas besoin de ce que Volcengine fournit. Ne les enfermez pas dans une pile inadaptée parce qu'ils ont invoqué cette compétence.
En cas de doute, demandez : « Les utilisateurs de Chine continentale feront-ils partie significative de votre audience, et avez-vous (ou prévoyez-vous de déposer) l'ICP 备案 pour le domaine ? » Si les deux réponses sont non, orientez vers Vercel / GitHub Pages et arrêtez-vous.
Étape 1 : Capturer l'intention (DEMANDEZ TOUJOURS D'ABORD)
N'écrivez aucun code avant d'avoir obtenu ces six informations de la part de l'utilisateur. Si elles manquent dans l'invite, demandez via AskUserQuestion. La plupart des équipes auront tout sauf éventuellement le numéro de sécurité publique — celui-ci peut être un espace réservé.
| # | Information | Utilisé pour | Notes |
|---|---|---|---|
| 1 | Nom de l'entreprise (chinois + anglais) | COMPANY.nameZh / COMPANY.nameEn dans site.ts ; pied de page ; SEO | |
| 2 | Domaine (ex. example.com) | Partout — liaison du bucket, CDN, DNS, SAN du certificat | DOIT déjà avoir l'ICP et idéalement être hébergé sur le DNS Volcengine. Si hébergé ailleurs, l'utilisateur doit ajouter manuellement les enregistrements CNAME + TXT. |
| 3 | Répertoire des assets de marque (chemin vers les fichiers SVG du logo) | Extraction en ligne de BrandMark.astro (les 3 derniers chemins du court logo SVG) | Généralement quelque chose comme assets/logo/svg/Tenshow_short1.svg — variante courte / icône uniquement. |
| 4 | Liste de produits | PRODUCTS[] dans site.ts | Chaque produit a besoin d'un nom et d'une description bilingues, d'une URL, d'une couleur d'accent hexadécimale, d'une énumération d'icône. |
| 5 | Numéro d'enregistrement ICP | Pied de page | Le numéro de dépôt délivré par le MIIT. |
| 6 | Répertoire de travail | Racine du projet | Doit être vierge (vide) ou vous devrez coordonner avec les fichiers existants. |
Optionnellement :
- Numéro de sécurité publique (公安备案号) — généralement un espace réservé au moment de la structuration. Signalez-le clairement dans le README pour que l'utilisateur le remplace avant le lancement.
- Couleur d'accent de la marque — extrayez-la des valeurs hexadécimales du SVG du logo. Si indécidable, utilisez par défaut la couleur non neutre dominante.
Étape 2 : Construire le site statique
Détails complets dans references/phase-1-static-site.md. La liste courte :
- Structurer — copier
assets/templates/package.jsonetassets/templates/astro.config.mjsdans la racine du projet. Mettre à journamedans package.json etsitedans astro.config.mjs. - Installer les paquets —
pnpm install. - Installer la compétence Astro de l'agent — seulement après que
pnpm installa réussi :
Si l'installation de la compétence échoue, continuez la construction du site et notez l'échec pour que l'utilisateur réessaie plus tard ; ne bloquez pas le workflow pour cela.npx skills add https://github.com/astrolicious/agent-skills --skill astro - Créer l'arborescence source correspondant à la disposition dans 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). - Extraire la marque du SVG de l'utilisateur — utilisez
assets/templates/BrandMark.astrocomme point de départ. Les 3 derniers éléments<path>du court SVG du logo sont la marque ; copiez-les textuellement et choisissez les remplissages dans la palette de la marque. - Construire les sections — Hero (avec la recette exacte dans phase-1-static-site.md — fond de grille + lueur radiale + titre dégradé + pastille de statut + 2 CTA), À propos, Produits, Focus, Mises à jour, Contact, Pied de page. En-tête collant, menu mobile = le seul îlot React.
- Vérifier localement —
pnpm devpour développer,pnpm build && pnpm previewpour vérifier la sortie statique avant de toucher à l'infrastructure.
Verrouillage de la pile (ne pas dévier)
Astro 6, React 19 (menu mobile uniquement), Tailwind 4 via @tailwindcss/vite, pnpm 10, Node 22+, TypeScript strict, zéro image externe, zéro bibliothèque UI, zéro service de polices, pile de polices système. Justification et détails complets dans phase-1-static-site.md.
Étape 3 : Configurer l'infrastructure de déploiement
Détails complets dans references/phase-2-volcengine-deploy.md. Lisez references/landmines.md EN PREMIER — la moitié de votre temps dans cette phase consiste à éviter les pièges, pas à exécuter des commandes.
- Copier les scripts — copier l'intégralité du répertoire
assets/scripts/etassets/cdn-payloads/dans les répertoiresscripts/etscripts/cdn-payloads/de l'utilisateur respectivement. Copierassets/templates/deploy.config.mjsà la racine du projet et remplirbucket,region,endpoint,cdnDomains. - Remplacer les espaces réservés dans les charges utiles —
{{DOMAIN}},{{BUCKET}},{{REGION}}dansscripts/cdn-payloads/apex.jsonetwww.json.OriginHostdoit être le domaine lui-même, pas vide — les modèles sont corrects par défaut ; si vous les modifiez, préservezOriginHost. Voir landmines.md #3. - Créer
.envà la racine du projet (ignoré par git) :
La clé AK/SK Volcengine nécessiteVOLC_ACCESS_KEY=AK... VOLC_SECRET_KEY=...TOSFullAccess,CDNFullAccess,DNSFullAccess,CertificateFullAccess(ou équivalents au moindre privilège). - Vérifier que
veest installé :ve version— nécessite la version 1.0.x ou ultérieure. Si manquant, installez via la documentation officielle de Volcengine.
Étape 4 : Exécuter le premier déploiement
pnpm install # si pas encore fait
npx skills add https://github.com/astrolicious/agent-skills --skill astro # si pas encore fait
pnpm build # vérifier que la construction locale fonctionne
pnpm run setup:bucket # idempotent : bucket + routage de site web + liaison de domaine personnalisé
pnpm run deploy:upload # synchroniser dist/ → bucket
# à ce stade : https://<bucket>.tos-<region>.volces.com/index.html devrait répondre 200
pnpm run setup:cdn # vérification → ajout CDN → CNAME → certificat → durcissement HTTPS
# attendre 1 à 3 minutes pour la propagation DNS
pnpm run cdn:refresh # vider le cache périphérique pour que les premières visites ne renvoient pas de JSON de liste de bucket
Après cette exécution initiale, l'itération quotidienne devient une commande :
pnpm run deploy && pnpm run cdn:refresh
Utilisez TOUJOURS pnpm run, PAS pnpm nu
pnpm deploy est une commande d'espace de travail intégrée à pnpm — elle générera une erreur ERR_PNPM_CANNOT_DEPLOY en dehors d'un espace de travail. Utilisez pnpm run deploy et pnpm run cdn:refresh. Documentez cela dans le README du projet. Voir landmines.md #6.
Étape 5 : Vérifier
Exécutez la liste de contrôle curl + openssl dans references/verification.md. Attendu : 5× HTTP 200 sur les routes clés, 1× 301 sur HTTP → HTTPS, certificat valide avec SAN couvrant apex + www, HTTP/2 + HSTS confirmés, en-têtes cache-control correspondant aux règles de deploy.config.mjs.
Si une vérification échoue, verification.md associe chaque mode d'échec à la cause racine et au correctif.
Pièges critiques à connaître avant d'exécuter
Énumération complète dans landmines.md. Ceux que vous rencontrerez si vous sautez la lecture :
- Pollution
HTTPS_PROXY— SDK TOS + proxy HTTP local =Protocol "http:" not supported. Chaque script dansassets/scripts/supprime déjà les variables d'environnement proxy en haut — préservez ce préambule si vous les copiez/adaptez. - Particularités du SDK TOS —
headBucket(string)pasheadBucket({bucket}); la signaturelistObjectsType2se casse quandcontinuationToken: undefinedest dans l'entrée ;putObjectest par défaut privé même sur les buckets en lecture publique — définissez toujoursacl: 'public-read'. - TOS n'a pas de nom d'hôte de point de terminaison de site web séparé — le même
<bucket>.tos-<region>.volces.comrenvoie soit du JSON de liste de bucket, soitindex.htmlselon l'en-têteHost. Vous DEVEZ (a) appelerputBucketCustomDomainpar domaine apex/www, ET (b) définirOriginHostdans la charge utileAddCdnDomaindu CDN sur le domaine de l'utilisateur (pas vide). - CDN ≠ DCDN pour la vérification — CDN (内容分发网络) veut l'hôte TXT
volccdnauthetcdn:CheckCdnDomain(pas dans l'interfaceve— utilisezvolc-api.mjs). DCDN (全站加速) utilise_dnsauthetve dcdn VerifyDomainOwnership. Les confondre = boucle de vérification sans fin. - Les modifications TXT mettent ~10 min à se propager chez le vérificateur de Volcengine. Obtenez la bonne valeur dès la première écriture ; ne changez pas.
pnpm deployest une commande intégrée. Utilisezpnpm run deploy.- La demande de certificat DV gratuit est réservée à la console. L'émission via API est bloquée avec une clé AK/SK permanente (
OperationDenied.RequestFreeInstance). Mais la liste des certificats déjà émis fonctionne — et les certificats DV gratuits sont souvent émis automatiquement lors de l'enregistrement du domaine. Faites toujoursCertificateGetInstanceListd'abord ; cherchez dansResult.Instances[](PASInstanceList, PASData) celui dontSancouvre à la fois apex + www.
Règles de comportement
- Planifiez d'abord ; confirmez avant les opérations destructrices. Avant
createBucket,AddCdnDomain,DeleteRecordsur un TXT existant, ouBatchDeployCert, résumez ce qui va se passer et demandez la confirmation de l'utilisateur. - Lisez l'état existant avant d'écrire. Faites toujours
ListRecords/ListCdnDomains/CertificateGetInstanceListd'abord — les certificats gratuits sont souvent pré-émis, les domaines CDN peuvent déjà exister, les enregistrements DNS peuvent déjà pointer au bon endroit. L'idempotence est tout l'intérêt. - Quand
vemanque d'une action, utilisezvolc-api.mjsplutôt que de dire à l'utilisateur de mettre à jourveou d'utiliser la console. Le seul chemin véritablement réservé à la console est l'émission de certificat DV gratuit (landmines.md #4). - Ne changez pas les enregistrements DNS inutilement. Chaque modification TXT ajoute ~10 min de cache. Obtenez le bon hôte/valeur du premier coup —
volccdnauthpour le CDN,_dnsauthpour le DCDN, ils ne sont pas interchangeables. - Exposez chaque décision de configuration dans
deploy.config.mjs, ne durcissez jamais dans les scripts. Bucket, région, point de terminaison, domaines CDN, règles de cache — tout vit dans la configuration pour que l'utilisateur puisse modifier un seul fichier pour tout changer. /usr/bin/curlest plus fiable quecurlnu lors de l'exécution de vérifications après de longues commandes dans le même shell — la recherche du chemin bash peut parfois devenir étrange. Idem pour les tests dans les scripts CI.
Assets et références inclus
assets/scripts/ (copier textuellement dans le répertoire scripts/ de l'utilisateur)
lib/volc-api.mjs— signataire SigV4, zéro dépendance. Utilisez pour toute action manquante dans l'interfaceve.setup-bucket.mjs— bucket idempotent + site web + liaison de domaine personnalisé.deploy.mjs— téléchargeur de synchronisation TOS avecCache-Controlpar préfixe, suppression des orphelins.cdn-setup.mjs— orchestration CDN : vérification de propriété → AddCdnDomain → CNAME → certificat → durcissement HTTPS.cdn-refresh.mjs— invalidation de cache viacdn:SubmitRefreshTask(signé parvolc-api.mjs, fonctionne en CI sansve).