Quick Start

快速开始 / Quick Start

本页用于快速跑起 SPACK，并验证 SPA fallback、压缩变体、robots.txt 和健康检查。

This page helps you run SPACK quickly and verify SPA fallback, compression variants, robots.txt, and health endpoints.

最小 Docker 用法 / Minimal Docker Usage

FROM ghcr.io/lyonbrown4d/spack:latest

COPY ./dist /app

ENV SPACK_ASSETS_ROOT=/app
ENV SPACK_ASSETS_PATH=/
ENV SPACK_ASSETS_ENTRY=index.html
ENV SPACK_ASSETS_FALLBACK_TARGET=index.html
ENV SPACK_HTTP_PORT=80
ENV SPACK_COMPRESSION_ENABLE=true
ENV SPACK_COMPRESSION_MODE=lazy
ENV SPACK_IMAGE_ENABLE=true

中文：把前端构建产物复制到 /app，再把 SPACK_ASSETS_ROOT 指向这个目录即可。默认端口是 80，debug runtime 默认端口是 8080。

English: Copy your frontend build output to /app and point SPACK_ASSETS_ROOT to it. The default HTTP port is 80; the debug runtime defaults to 8080.

本地源码运行 / Run From Source

$env:SPACK_ASSETS_ROOT = "D:\path\to\dist"
go run .

使用配置文件和 CLI 覆盖：

go run . --config .\spack.yaml --http.port=8080 --assets.root=.\dist

Run with a config file and CLI overrides:

go run . --config ./spack.yaml --http.port=8080 --assets.root=./dist

SPA Fixture 验证 / SPA Fixture Verification

仓库包含一个最小 SPA fixture，可以用于验证静态资源、fallback 和压缩生成。

The repository includes a minimal SPA fixture for validating static serving, fallback, and compression.

pnpm -C test build
$env:SPACK_ASSETS_ROOT = (Resolve-Path .\test\build\dist).Path
$env:SPACK_ASSETS_PATH = "/"
go run .

打开或请求：

• http://127.0.0.1/
• http://127.0.0.1/docs
• http://127.0.0.1/about
• http://127.0.0.1/catalog
• http://127.0.0.1/robots.txt

Open or request the same URLs to verify entry serving, SPA fallback, catalog output, and robots behavior.

压缩检查 / Compression Check

curl.exe -I -H "Accept-Encoding: br,zstd,gzip" http://127.0.0.1/assets/payload.json

预期行为：

• 第一次请求可能返回 identity，因为 lazy compression 正在异步生成。
• 后续请求应返回 Content-Encoding: br、zstd 或 gzip。
• 响应应包含 Vary: Accept-Encoding。

Expected behavior:

• The first request may return identity while lazy compression is generated asynchronously.
• Later requests should return Content-Encoding: br, zstd, or gzip.
• The response should include Vary: Accept-Encoding.

健康检查 / Health Checks

Endpoint	用途 / Purpose
/healthz	综合健康检查 / Aggregate health check
/livez	存活检查 / Liveness check
/readyz	就绪检查 / Readiness check
/catalog	运行时资产索引 / Runtime asset catalog
/robots.txt	静态或生成的 robots 文件 / Static or generated robots file

如果开启 debug runtime：

If the debug runtime is enabled:

Endpoint	用途 / Purpose
/prometheus	Prometheus metrics
/debug/statsviz	Go runtime visualization
/pprof/*	Go pprof endpoints

常用命令 / Common Commands

task test
task lint
task build
task perf:k6:frontend
task perf:k6:split

中文：task perf:k6:* 会使用 Docker 启动 SPACK、SPACK prefork 和 Nginx，并通过 k6 走真实 HTTP 协议压测。

English: task perf:k6:* starts SPACK, SPACK prefork, and Nginx through Docker, then runs k6 over real HTTP.