指南 on bouine

从 NGINX 迁移

Mon, 01 Jan 0001 00:00:00 +0000

Directive mapping

NGINX directive	bouine config	Notes
`proxy_cache_path ... max_size=1g`	`storage.hot_max_bytes: 1GiB`	bouine uses in-RAM storage, no filesystem levels
`proxy_cache_path ... keys_zone=api:10m`	Not needed	bouine manages shard count automatically (`N=NumCPU`)
`proxy_cache_valid 200 60s`	`routes[].cache.ttl_default: 60s`	Per-route, respects `Cache-Control` by default
`proxy_cache_valid 404 10s`	`routes[].cache.negative_ttl: 10s`	Negative caching for error responses
`proxy_cache_use_stale error http_500 http_502 http_503 http_504`	`routes[].cache.stale_if_error: 30s`	Serves stale on origin 5xx or timeout
`proxy_cache_background_update on`	`routes[].cache.stale_while_revalidate: 10s`	Background revalidation while serving stale
`proxy_cache_revalidate on`	Built-in	Conditional requests (`If-None-Match`, `If-Modified-Since`)
`proxy_cache_key $scheme$host$request_uri`	Automatic	xxhash128 of scheme+host+path+sorted query
`proxy_cache_key $scheme$host$request_uri$http_accept`	`cache.key.include_headers: [Accept]`	Explicit header keying
`proxy_ignore_headers Vary`	`cache.key.include_headers: [...]`	Explicit header keying instead of Vary
`proxy_no_cache $variable`	`routes[].cache.enabled: false`	Per-route disable
`proxy_cache_bypass $variable`	Not needed	Use route matching to separate cached/uncached
`proxy_cache_lock on`	Built-in (request collapsing)	Single-flight per cache key
`proxy_cache_lock_timeout 5s`	Built-in	Subscribers wait for leader fetch
`proxy_cache_min_uses 3`	Not needed	bouine caches on first response (RFC 9111)
`add_header X-Cache-Status $upstream_cache_status`	Built-in	`X-Cache` header (HIT, MISS, STALE, BYPASS, REVALIDATED)
`proxy_next_upstream error timeout`	`upstream_pools[].health.passive`	Passive health checks with outlier ejection

Key differences

No zone configuration — bouine manages memory automatically with SIEVE eviction
No filesystem cache — bouine uses in-RAM hot tier + mmap warm tier (no proxy_cache_path on disk)
Clustering built-in — NGINX requires third-party modules for cache sharing; bouine has gossip + peer fetch
RFC 9111 native — bouine implements the spec directly, not via directives
Observability built-in — Prometheus /metrics, structured JSON access logs with cache_status
No proxy_pass needed — upstream pools are declared separately and referenced by name in routes
Declarative config — no if blocks, no map directives, no embedded Lua

Example: API gateway

NGINX:

从 Varnish 迁移

Mon, 01 Jan 0001 00:00:00 +0000

Status: Stable for production use. Assumes familiarity with VCL and bouine’s YAML configuration model.

Quick reference

Varnish concept	bouine equivalent	Notes
VCL subroutines	declarative YAML config	bouine uses config, not code
`vcl_recv`	`routes[].match`	routing and request matching
`vcl_hash`	automatic cache key (`xxhash64`)	scheme + host + path + query + method
`vcl_backend_fetch`	`upstream_pools[]`	backend pool config
`vcl_backend_response`	origin `Cache-Control`	bouine honors RFC 9111 strictly
`beresp.ttl`	`cache.ttl_default`	overridden by origin headers
`beresp.grace`	`cache.stale_while_revalidate`	SWR semantics
`ban()`	admin API `POST /v1/ban`	HTTP-based invalidation API
`purge`	admin API `POST /v1/purge`	exact-match invalidation
Varnish log (`-g request`)	structured JSON logs (stdout)	pipe to any log aggregator
`varnishstat`	`/metrics` (Prometheus)	Prometheus-compatible metrics
VSM/shared memory	in-process memory	no mmap, no VSM files

1. Conceptual mapping

The big picture

Varnish is a programmable cache — you write VCL to define cache behavior. bouine is a declarative cache — you write YAML to describe routes, backends, and cache policies, and bouine implements RFC 9111 rigorously.

反向代理示例

Mon, 01 Jan 0001 00:00:00 +0000

bouine in front of Caddy

Caddy typically serves static files or acts as a reverse proxy itself. Deploy bouine in front of Caddy to add caching without modifying Caddy’s config.

容量规划

Mon, 01 Jan 0001 00:00:00 +0000

Step 1: Estimate your working set

The working set is the total size of responses that need to stay cached for acceptable hit rates.

working_set ≈ unique_cacheable_urls × avg_response_size

Workload	Typical working set
REST API (100k endpoints, 2 KiB avg)	~200 MiB
E-commerce catalog (1M products, 5 KiB avg)	~5 GiB
Static site / CDN (50k assets, 50 KiB avg)	~2.5 GiB
Media-heavy site (10k pages, 200 KiB avg)	~2 GiB

If you cannot estimate, start with 2 GiB and monitor bouine_hot_store_bytes / bouine_hot_store_max_bytes. If it stays above 0.9 consistently, double hot_max_bytes.

基准测试

Mon, 01 Jan 0001 00:00:00 +0000

Disclaimer

Benchmarks are synthetic. They measure isolated behavior in artificial conditions. Production workloads have different allocation patterns, concurrency levels, GC pressure, network conditions, and hardware. The Varnish and NGINX configurations used in these tests could likely be improved — a differently tuned Varnish or NGINX may produce different results. Benchmarking is genuinely hard, and these numbers should be treated as directional indicators, not as definitive performance claims.

Production readiness checklist

Mon, 01 Jan 0001 00:00:00 +0000

Before deploying bouine to production, verify each item below. Items are grouped by area. Skip items that don’t apply to your deployment.

TLS and network security

Data-plane TLS configured (if terminating HTTPS at bouine)
Cluster mTLS enabled (cert + key + CA bundle for peer-to-peer)
Admin port not exposed externally (NetworkPolicy or firewall)
Admin token set via Secret or environment variable (not auto-generated)
insecure_skip_verify is not set in any upstream pool TLS config
Hop-by-hop headers stripped (handled automatically by bouine)

Resource sizing

resources.limits.memory set and GOMEMLIMIT auto-computed (Helm chart does this)
hot_max_bytes sized to fit in RAM without GC pressure (default: 75% of GOMEMLIMIT)
Warm tier PVC sized for working set (warmVolume.size)
warm_max_bytes set below PVC capacity to leave headroom
max_object_size configured per route to reject oversized responses
max_response_bytes configured to prevent memory exhaustion from large bodies

Cluster and high availability

replicaCount >= 3 for quorum
podDisruptionBudget.enabled: true with minAvailable >= 2
Topology spread constraints set across zones
hop_limit configured (default 2 is fine for most deployments)
terminationGracePeriodSeconds >= 40 to allow graceful drain
minReadySeconds >= 30 to let the ring converge before traffic

Caching policy

Every route has ttl_default set explicitly
stale_while_revalidate configured for routes that can serve stale
stale_if_error configured for origin-outage resilience
negative_ttl set for routes that return errors (prevents error storms)
jitter_percent > 0 to prevent synchronized revalidation bursts
allow_set_cookie is off unless you explicitly need Set-Cookie caching
Cache key configuration reviewed (query param stripping, header includes)

Upstream and origin

Active health checks enabled per pool
Passive health checks enabled (consecutive_5xx, eject_for)
Upstream connection timeout and response header timeout configured
max_connections set per pool to prevent FD exhaustion
Hedged requests enabled for latency-sensitive routes

Observability

Prometheus scraping enabled (ServiceMonitor or PodMonitor)
Grafana dashboards imported (RED, storage, cluster, ops)
Alerting rules deployed (hit rate, error rate, peer fetch, warm tier)
OpenTelemetry tracing endpoint configured (or disabled explicitly)
Access log sampling rate appropriate (default 1:100 for 200s)
pprof_enabled is off in production (default)

Kubernetes deployment

Helm chart deployed with production values (values-production.yaml as base)
NetworkPolicy.enabled: true to isolate admin and cluster ports
serviceAccount.automount: false (bouine doesn’t need K8s API access)
Probes configured: startup (30 min budget), readiness (/readyz), liveness (/healthz)
Rolling update strategy: maxUnavailable: 1 for sequential pod restarts
Config changes deployed via rolling update (no live config reload)

Operations

Purge and ban workflows documented for on-call
Runbook accessible (see operations docs)
Backup strategy for warm tier (PVC snapshots or rebuild from origin)
Drain procedure tested (/drain endpoint + preStop hook)
Config file stored in version control

Service Mesh 兼容性

Mon, 01 Jan 0001 00:00:00 +0000

bouine works with any service mesh that operates at L4/L7. The main consideration is the double-TLS problem: if the mesh enforces mTLS between sidecars, bouine must either terminate TLS itself or let the sidecar handle it.