Marketing-Website-Entwicklung (Volcengine)
End-to-End-Skill zum Erstellen und Bereitstellen einer zweisprachigen statischen Unternehmens-Website auf Volcengine. Zwei Phasen:
- Build – Astro 6 + React 19 Islands (nur mobiles Menü) + Tailwind 4. Inline-SVG überall. Eine einzige Inhaltsdatei (
src/content/site.ts) ist die alleinige Quelle der Wahrheit. - Deploy – TOS-Bucket + CDN + kostenloses DV-Zertifikat + HTTPS-Härtung, alles in idempotenten Node-Skripten über die
veCLI und Volcengine OpenAPI (SigV4-signiert viavolc-api.mjsfür Aktionen, dievenicht bereitstellt).
Wie Erfolg aussieht: Der Benutzer führt ~6 Befehle Ende-zu-Ende aus und erhält https://<ihre-domain>/, das eine produktionsreife zweisprachige Website mit HTTPS, Force-Redirect zu HTTPS, HSTS, HTTP/2, Edge-Caching und automatischer Cache-Invalidierung ausliefert. Jeder Infrastrukturschritt ist als idempotentes Skript versioniert.
Ist dieser Skill die richtige Wahl?
Dies ist ein bewusst opinionierter Workflow, der für ein bestimmtes Szenario optimiert ist. Bevor Sie in die Tiefe gehen, prüfen Sie, ob dieses Szenario tatsächlich der Situation des Benutzers entspricht. Wenn nicht, zeigen Sie die bessere Alternative auf, anstatt den Benutzer durch einen schwereren Pfad zu zwingen.
Verwenden Sie diesen Skill, wenn:
- Die Website für ein chinesisches Unternehmen oder ein Produkt, das sich an Nutzer in Festlandchina richtet, bestimmt ist – die Latenz vom Festland zu nicht-chinesischen CDNs ist schlecht genug (200-400 ms, oft schlimmer zu Spitzenzeiten), dass Besucher es bemerken und abspringen.
- ICP 备案 ist erforderlich oder bereits vorhanden – die Auslieferung in China benötigt legal die beim Ministerium registrierte Datei, die an eine in einer chinesischen Cloud gehostete Domain gebunden ist. Volcengine bündelt 备案-Unterstützung und bietet sie für die hier bereitgestellte Domain an.
- Der Benutzer befindet sich bereits im Volcengine-Ökosystem (andere Volcengine-Dienste, vorhandene TOS-Buckets usw.) und Konsolidierung ist wertvoll.
- Das zweisprachige zh/en-Muster ist gewünscht – die Inhaltsebene (
site.ts) ist darauf ausgelegt.
Verwenden Sie eine einfachere Alternative, wenn:
| Szenario | Empfohlene Alternative | Warum |
|---|---|---|
| Persönliche Website / Portfolio / Nebenprojekt, keine Anforderung an chinesisches Publikum | GitHub Pages | Kostenlos, automatisches HTTPS, Bereitstellung bei git push, keine zu verwaltende Infrastruktur. Keine der Volcengine-Fallstricke treffen zu. |
| Internationales Publikum (USA/EU/SEA), keine China-Präsenz geplant | Vercel (oder Cloudflare Pages / Netlify) | Kostenloses Kontingent, sofortige Bereitstellungen aus Git, Vorschau-URLs pro PR, automatisches HTTPS, globales Edge-Netzwerk. Überspringen Sie den gesamten ve CLI + ICP-Workflow vollständig. |
| Website benötigt serverlose Funktionen (Formulare, Authentifizierung, dynamische Inhalte) | Vercel oder Cloudflare Pages mit deren Edge-Funktionen | Dieser Skill liefert rein statische Inhalte aus – Volcengine hat serverlose Produkte, aber der Workflow hier deckt sie nicht ab. |
| Sie wünschen Vorschau-URLs pro Branch / PR-basierte Überprüfung | Vercel | Die Vorschau-URL-Benutzererfahrung von Vercel ist erstklassig. Dieser Skill erzeugt eine Produktions-Bereitstellung pro Push; keine Branch-Vorschauen. |
Wenn die Situation des Benutzers mit der Spalte "Verwenden Sie eine einfachere Alternative" übereinstimmt, teilen Sie ihm dies explizit mit, bevor Sie etwas gerüsten. Ein 2-minütiger Vercel-Deploy ist eine bessere Erfahrung als ein 30-minütiger Volcengine-Bootstrap, wenn der Benutzer nicht braucht, was Volcengine bietet. Drängen Sie sie nicht in den falschen Stack, nur weil sie diesen Skill aufgerufen haben.
Fragen Sie im Zweifelsfall: "Werden Nutzer in Festlandchina einen bedeutenden Teil Ihres Publikums ausmachen, und haben Sie (oder planen Sie) die ICP 备案 für die Domain einzureichen?" Wenn beide Antworten nein lauten, verweisen Sie auf Vercel / GitHub Pages und hören Sie auf.
Schritt 1: Absicht erfassen (IMMER ZUERST FRAGEN)
Schreiben Sie keinen Code, bevor Sie diese sechs Eingaben vom Benutzer haben. Wenn sie in der Aufforderung fehlen, fragen Sie via AskUserQuestion. Die meisten Teams werden alles haben, außer möglicherweise die öffentliche Sicherheitsnummer – diese ist als Platzhalter in Ordnung.
| # | Eingabe | Verwendet für | Hinweise |
|---|---|---|---|
| 1 | Unternehmensname (Chinesisch + Englisch) | COMPANY.nameZh / COMPANY.nameEn in site.ts; Footer; SEO | |
| 2 | Domain (z. B. example.com) | Überall – Bucket-Bindung, CDN, DNS, Zertifikats-SAN | MUSS bereits ICP-gemeldet und idealerweise auf Volcengine DNS gehostet sein. Wenn anderswo gehostet, muss der Benutzer manuell CNAME- + TXT-Einträge hinzufügen. |
| 3 | Marken-Assets-Verzeichnis (Pfad zu SVG-Logodateien) | Inline-Extraktion von BrandMark.astro (die letzten 3 Pfade des kurzen Logo-SVGs) | Normalerweise so etwas wie assets/logo/svg/Tenshow_short1.svg – kurze / symbol-only Variante. |
| 4 | Produktliste | PRODUCTS[] in site.ts | Jedes Produkt benötigt zweisprachigen Namen + Beschreibung, URL, Akzent-Hex-Farbe, Icon-Enum. |
| 5 | ICP-Registrierungsnummer | Footer | Die vom MIIT ausgestellte 备案号. |
| 6 | Arbeitsverzeichnis | Projekt-Root | Sollte Neuland (leer) sein, oder Sie müssen mit vorhandenen Dateien koordinieren. |
Optional:
- 公安备案号 (Nummer der öffentlichen Sicherheitsbehörde) – normalerweise ein Platzhalter zum Zeitpunkt des Gerüstbaus. Markieren Sie es deutlich in der README, damit der Benutzer es vor dem Start ersetzt.
- Markenakzentfarbe – extrahieren Sie sie aus den Hex-Werten des Logo-SVGs. Wenn nicht entscheidbar, verwenden Sie standardmäßig die dominante nicht-neutrale Farbe.
Schritt 2: Die statische Website erstellen
Vollständige Details in references/phase-1-static-site.md. Die Kurzfassung:
- Gerüst – kopieren Sie
assets/templates/package.jsonundassets/templates/astro.config.mjsin das Projekt-Root. Aktualisieren Sienamein package.json undsitein astro.config.mjs. - Pakete installieren –
pnpm install. - Den Astro-Agent-Skill installieren – nur nach erfolgreichem
pnpm install:
Wenn die Skill-Installation fehlschlägt, setzen Sie den Website-Bau fort und notieren Sie den Fehler, damit der Benutzer es später erneut versuchen kann; blockieren Sie den Workflow nicht darauf.npx skills add https://github.com/astrolicious/agent-skills --skill astro - Erstellen Sie die Quellstruktur entsprechend dem Layout in 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). - Extrahieren Sie das Markenzeichen aus dem SVG des Benutzers – verwenden Sie
assets/templates/BrandMark.astroals Ausgangspunkt. Die letzten 3<path>-Elemente des Short-Logo-SVGs sind das Zeichen; kopieren Sie sie wörtlich und wählen Sie Füllungen aus der Markenpalette. - Erstellen Sie die Abschnitte – Hero (mit dem genauen Rezept in phase-1-static-site.md – Gitterhintergrund + radialer Glow + Farbverlaufsüberschrift + Status-Pille + 2 CTAs), Über uns, Produkte, Fokus, Updates, Kontakt, Footer. Header fixiert, mobiles Menü = die einzige React-Insel.
- Lokal überprüfen –
pnpm devzum Entwickeln,pnpm build && pnpm previewzur Plausibilitätsprüfung der statischen Ausgabe, bevor Sie die Infrastruktur berühren.
Stack-Festlegung (nicht abweichen)
Astro 6, React 19 (nur mobiles Menü), Tailwind 4 via @tailwindcss/vite, pnpm 10, Node 22+, TypeScript strict, null externe Bilder, null UI-Bibliotheken, null Schriftdienste, Systemschriftstapel. Begründung und vollständige Details in phase-1-static-site.md.
Schritt 3: Bereitstellungsinfrastruktur einrichten
Vollständige Details in references/phase-2-volcengine-deploy.md. Lesen Sie ZUERST references/landmines.md – die Hälfte Ihrer Zeit in dieser Phase wird damit verbracht, die Fallstricke zu vermeiden, nicht Befehle auszuführen.
- Skripte kopieren – kopieren Sie das gesamte Verzeichnis
assets/scripts/undassets/cdn-payloads/in dasscripts/bzw.scripts/cdn-payloads/des Benutzers. Kopieren Sieassets/templates/deploy.config.mjsin das Projekt-Root und füllen Siebucket,region,endpoint,cdnDomainsaus. - Platzhalter in Payloads ersetzen –
{{DOMAIN}},{{BUCKET}},{{REGION}}inscripts/cdn-payloads/apex.jsonundwww.json.OriginHostmuss die Domain selbst sein, nicht leer – die Vorlagen sind sofort einsatzbereit; wenn Sie sie bearbeiten, bewahren SieOriginHost. Siehe landmines.md #3. - Erstellen Sie
.envim Projekt-Root (gitignoriert):
Volcengine AK/SK benötigtVOLC_ACCESS_KEY=AK... VOLC_SECRET_KEY=...TOSFullAccess,CDNFullAccess,DNSFullAccess,CertificateFullAccess(oder entsprechende Least-Privilege-Äquivalente). - Überprüfen, ob
veinstalliert ist:ve version– benötigt Version 1.0.x oder höher. Wenn fehlend, über die offizielle Volcengine-Dokumentation installieren.
Schritt 4: Die erste Bereitstellung ausführen
pnpm install # falls noch nicht erledigt
npx skills add https://github.com/astrolicious/agent-skills --skill astro # falls noch nicht erledigt
pnpm build # lokalen Build überprüfen
pnpm run setup:bucket # idempotent: Bucket + Website-Routing + Custom-Domain-Bindung
pnpm run deploy:upload # dist/ → Bucket synchronisieren
# an diesem Punkt: https://<bucket>.tos-<region>.volces.com/index.html sollte 200 zurückgeben
pnpm run setup:cdn # Verifizierung → CDN hinzufügen → CNAME → Zertifikat → HTTPS-Härtung
# 1-3 Minuten für DNS-Propagation warten
pnpm run cdn:refresh # Edge-Cache leeren, damit erste Aufrufe kein Bucket-Listing-JSON zurückgeben
Nach diesem ersten Durchlauf wird die tägliche Iteration zu einem Befehl:
pnpm run deploy && pnpm run cdn:refresh
Immer pnpm run verwenden, NICHT pnpm allein
pnpm deploy ist ein eingebauter pnpm-Workspace-Befehl – er wird außerhalb eines Workspaces mit dem Fehler ERR_PNPM_CANNOT_DEPLOY fehlschlagen. Verwenden Sie pnpm run deploy und pnpm run cdn:refresh. Dokumentieren Sie dies in der README des Projekts. Siehe landmines.md #6.
Schritt 5: Überprüfung
Führen Sie die curl + openssl-Checkliste in references/verification.md aus. Erwartet: 5× HTTP 200 auf Schlüsselrouten, 1× 301 auf HTTP → HTTPS, gültiges Zertifikat mit SAN, das Apex + www abdeckt, HTTP/2 + HSTS bestätigt, Cache-Control-Header, die den Regeln in deploy.config.mjs entsprechen.
Wenn eine Prüfung fehlschlägt, ordnet verification.md jeden Fehlermodus der Ursache und der Behebung zu.
Kritische Fallstricke, die Sie vor der Ausführung kennen müssen
Vollständige Aufzählung in landmines.md. Diejenigen, auf die Sie stoßen, wenn Sie das Lesen überspringen:
HTTPS_PROXY-Verschmutzung – TOS SDK + ein lokaler HTTP-Proxy =Protocol "http:" not supported. Jedes Skript inassets/scripts/löscht bereits Proxy-Umgebungsvariablen am Anfang – bewahren Sie diese Präambel, wenn Sie sie kopieren / anpassen.- TOS SDK-Eigenheiten –
headBucket(string)nichtheadBucket({bucket});listObjectsType2-Signatur bricht, wenncontinuationToken: undefinedin der Eingabe ist;putObjectstandardmäßig auf privat, selbst bei öffentlich lesbaren Buckets – setzen Sie immeracl: 'public-read'. - TOS hat keinen separaten Website-Endpunkt-Hostnamen – derselbe
<bucket>.tos-<region>.volces.comgibt entweder Bucket-Listing-JSON oderindex.htmlzurück, abhängig vomHost-Header. Sie MÜSSEN (a)putBucketCustomDomainpro Apex-/www-Domain aufrufen UND (b)OriginHostim CDNAddCdnDomain-Payload auf die Domain des Benutzers setzen (nicht leer). - CDN ≠ DCDN für die Verifizierung – CDN (内容分发网络) möchte TXT-Host
volccdnauthundcdn:CheckCdnDomain(nicht in derveCLI – verwenden Sievolc-api.mjs). DCDN (全站加速) verwendet_dnsauthundve dcdn VerifyDomainOwnership. Verwechslung = endlose Verifizierungsschleife. - TXT-Änderungen benötigen ~10 min zur Propagation beim Volcengine-Verifizierer. Holen Sie den Wert beim ersten Schreiben richtig; vermeiden Sie Wechsel.
pnpm deployist ein eingebauter Befehl. Verwenden Siepnpm run deploy.- Kostenloses DV-Zertifikat ANTRAG ist nur über die Konsole möglich. Die API-Ausstellung ist mit permanentem AK/SK blockiert (
OperationDenied.RequestFreeInstance). Aber das Auflisten bereits ausgestellter Zertifikate funktioniert einwandfrei – und kostenlose DV-Zertifikate werden oft bei der Domain-Registrierung automatisch ausgestellt. Führen Sie immer zuerstCertificateGetInstanceListdurch; suchen Sie inResult.Instances[](NICHTInstanceList, NICHTData) nach einem, dessenSansowohl Apex als auch www abdeckt.
Verhaltensregeln
- Zuerst planen; vor destruktiven Operationen bestätigen. Vor
createBucket,AddCdnDomain,DeleteRecordauf vorhandenem TXT oderBatchDeployCertfassen Sie zusammen, was passieren wird, und bitten Sie den Benutzer um Bestätigung. - Vor dem Schreiben den aktuellen Zustand auslesen. Führen Sie immer zuerst
ListRecords/ListCdnDomains/CertificateGetInstanceListdurch – kostenlose Zertifikate sind oft vorausgestellt, CDN-Domains können bereits existieren, DNS-Einträge können bereits auf das Richtige zeigen. Idempotenz ist der springende Punkt. - Wenn
veeine Aktion nicht hat, verwenden Sievolc-api.mjs, anstatt dem Benutzer zu sagen, er solleveaktualisieren oder die Konsole verwenden. Der einzige wirklich konsolen-exklusive Pfad ist die Ausstellung des kostenlosen DV-Zertifikats (landmines.md #4). - Wechseln Sie nicht ständig DNS-Einträge. Jede TXT-Änderung fügt ~10 min Cache hinzu. Holen Sie den Host/Wert beim ersten Mal richtig –
volccdnauthfür CDN,_dnsauthfür DCDN, sie sind nicht austauschbar. - Jede Konfigurationsentscheidung in
deploy.config.mjsauslagern, niemals in Skripten hartcodieren. Bucket, Region, Endpunkt, CDN-Domains, Cache-Regeln – alles lebt in der Konfiguration, damit der Benutzer eine Datei bearbeiten kann, um alles zu ändern. /usr/bin/curlist zuverlässiger alscurlbei der Durchführung von Prüfungen nach langen Befehlen in derselben Shell – die Bash-PATH-Suche wird gelegentlich komisch. Gleiches gilt für Tests in CI-Skripten.
Gebündelte Assets und Referenzen
assets/scripts/ (wörtlich in das scripts/-Verzeichnis des Benutzers kopieren)
lib/volc-api.mjs– SigV4-Signer, keine Abhängigkeiten. Verwenden Sie für jede Aktion, die in derveCLI fehlt.setup-bucket.mjs– idempotentes Bucket + Website + Custom-Domain-Binding.deploy.mjs– TOS-Sync-Uploader mit präfix-bezogenemCache-Control, Löschung von Verwaisten.cdn-setup.mjs– CDN-Orchestrierung: Eigentumsverifizierung → AddCdnDomain → CNAME → Zertifikat → HTTPS-Härtung.cdn-refresh.mjs– Cache-Invalidierung viacdn:SubmitRefreshTask(signiert vonvolc-api.mjs, funktioniert in CI ohneve).
assets/cdn-payloads/ (in scripts/cdn-payloads/ kopieren)
…[für die Übersetzung gekürzt]