# bouine

> Bouine is a cloud-native HTTP cache in Go - RFC9111 compliant, zero-alloc hit path, gossip clustering, no external K/V store.

- [对比 bouine](https://bouine.org/zh/compare/): Side-by-side comparison of bouine against Envoy, NGINX, HAProxy, Varnish, and Caddy — across DevOps, SRE, and Software Engineer criteria.
- [文档](https://bouine.org/zh/docs/): 面向用户和贡献者的完整文档：安装、配置、运维、故障排查和安全扩展 bouine。

## 对比 bouine

> Side-by-side comparison of bouine against Envoy, NGINX, HAProxy, Varnish, and Caddy — across DevOps, SRE, and Software Engineer criteria.


## 文档

> 面向用户和贡献者的完整文档：安装、配置、运维、故障排查和安全扩展 bouine。

- [入门](https://bouine.org/zh/docs/getting-started/): 安装 bouine，本地运行，缓存您的第一个响应，使用 Docker 或 Kubernetes 部署，并适配配置示例。
- [配置](https://bouine.org/zh/docs/configuration/): bouine YAML 配置参考：监听器、存储、upstream pool、路由、缓存、集群、TLS 和可观测性。
- [运维](https://bouine.org/zh/docs/operations/): 运维 bouine 的运行手册：生命周期、认证、缓存失效、监控、仪表板、Kubernetes 运维和故障排查。
- [架构](https://bouine.org/zh/docs/architecture/): How bouine is structured internally: listeners, pipeline, storage, cache engine, origin pools, clustering, and observability.
- [指南](https://bouine.org/zh/docs/guides/): 从 Varnish 或 NGINX 迁移、集成模式和容量规划的分步指南。
- [贡献](https://bouine.org/zh/docs/contributing/): 贡献者指南，涵盖本地设置、开发流程、提交格式、PR 检查和项目标准。
- [参考](https://bouine.org/zh/docs/reference/): CLI、管理 API 和响应头参考。
- [常见问题](https://bouine.org/zh/docs/faq/): Frequently asked questions about bouine.

### 入门

> 安装 bouine，本地运行，缓存您的第一个响应，使用 Docker 或 Kubernetes 部署，并适配配置示例。

- [安装](https://bouine.org/zh/docs/getting-started/install/): 从 Docker Hub、GitHub release 二进制文件或源码安装 bouine，了解每种方法的要求。
- [快速开始](https://bouine.org/zh/docs/getting-started/first-cache/): Start a small origin server, put bouine in front of it, and verify MISS then HIT behavior through headers and metrics.
- [Docker](https://bouine.org/zh/docs/getting-started/docker/): 运行 bouine 官方 Docker 镜像，挂载自定义配置，并本地构建快速的多架构镜像。
- [Kubernetes](https://bouine.org/zh/docs/getting-started/kubernetes/): 使用 Helm 将 bouine 部署到 Kubernetes，配置 StatefulSet gossip，验证节点发现，并执行滚动更新。
- [Example configurations](https://bouine.org/zh/docs/getting-started/examples/): Ready-to-adapt bouine YAML examples for static sites, self-served static files, API gateways, bouine-in-front-of-Cloudflare, and e-commerce routes.

### 配置

> bouine YAML 配置参考：监听器、存储、upstream pool、路由、缓存、集群、TLS 和可观测性。

- [缓存策略](https://bouine.org/zh/docs/configuration/cache-policy/): Understand how bouine chooses TTLs, overrides them per-route, serves stale content, applies negative caching, jitters expirations, refreshes proactively before expiry, and builds cache keys.
- [流式与实时响应](https://bouine.org/zh/docs/configuration/streaming/): bouine 如何流式传输响应体、服务 Server-Sent Events，以及在源站缓慢时卸载过量负载。
- [Storage tiers](https://bouine.org/zh/docs/configuration/storage/): Understand bouine's hot and warm storage tiers, SIEVE eviction, capacity planning, and operational tuning.
- [静态文件服务](https://bouine.org/zh/docs/configuration/static-files/): Serve files directly from a local directory without a separate origin server. Path traversal defense, MIME types, ETags, range requests, and optional cache integration.
- [TLS](https://bouine.org/zh/docs/configuration/tls/): Configure TLS termination with certificate management, SNI, and automatic reload.
- [Clustering](https://bouine.org/zh/docs/configuration/cluster-modes/): Configure bouine clustering: consistency modes, gossip membership, peer fetch, mTLS, invalidation propagation, and metrics.
- [Helm chart reference](https://bouine.org/zh/docs/configuration/helm/): All configurable values for the bouine Helm chart with defaults, descriptions, and production deployment tips.
- [实验性功能](https://bouine.org/zh/docs/configuration/experimental/): Opt-in experimental features that may become stable in future releases.

### 运维

> 运维 bouine 的运行手册：生命周期、认证、缓存失效、监控、仪表板、Kubernetes 运维和故障排查。

- [生命周期](https://bouine.org/zh/docs/operations/lifecycle/): Start, stop, and drain bouine in production and Kubernetes.
- [认证](https://bouine.org/zh/docs/operations/authentication/): Configure and retrieve the admin bearer token protecting all write endpoints.
- [缓存失效](https://bouine.org/zh/docs/operations/cache-invalidation/): Purge by URL, predicate ban, surrogate-key invalidation, and soft-purge refresh — and how they propagate across cluster peers.
- [集群一致性模式](https://bouine.org/zh/docs/operations/cluster-modes/): Verify, diagnose, and switch between strong and eventual cluster consistency modes.
- [监控](https://bouine.org/zh/docs/operations/monitoring/): Prometheus metrics, access log fields, OpenTelemetry tracing, and admin API endpoints for observing bouine.
- [Kubernetes 运维](https://bouine.org/zh/docs/operations/kubernetes/): Scale, update, and verify cluster health for bouine running on Kubernetes.
- [可观测性指南](https://bouine.org/zh/docs/operations/observability/): End-to-end guide for wiring Prometheus, Loki, Tempo, and Grafana Alloy to collect metrics, logs, and traces from a bouine cluster.
- [仪表板](https://bouine.org/zh/docs/operations/dashboard/): Access the built-in operator dashboard for live cache metrics, route performance, cluster health, and one-click invalidation.
- [Cloudflare CDN 传播](https://bouine.org/zh/docs/operations/cloudflare/): Forward bouine cache invalidation operations to Cloudflare's edge so both caches stay in sync.
- [故障排查](https://bouine.org/zh/docs/operations/troubleshooting/): Troubleshoot common bouine production issues: cache misses, cluster problems, rolling restart failures, invalidation, and origin health.

### 架构

> How bouine is structured internally: listeners, pipeline, storage, cache engine, origin pools, clustering, and observability.


### 指南

> 从 Varnish 或 NGINX 迁移、集成模式和容量规划的分步指南。

- [从 NGINX 迁移](https://bouine.org/zh/docs/guides/nginx-migration/): Migrate from NGINX proxy_cache to bouine by mapping directives, cache keys, stale serving, and observability concepts.
- [从 Varnish 迁移](https://bouine.org/zh/docs/guides/varnish-migration/): Complete migration guide from Varnish Cache to bouine: conceptual mapping, VCL vs YAML side-by-side, parity tables, behavioral differences, and FAQ.
- [反向代理示例](https://bouine.org/zh/docs/guides/reverse-proxies/): Deploy bouine in front of Caddy, Traefik, HAProxy, and nginx with ready-to-adapt configuration examples.
- [容量规划](https://bouine.org/zh/docs/guides/capacity-planning/): Size bouine for your workload: estimate hot and warm tier capacity, choose cluster mode and replica count, and plan for growth.
- [基准测试](https://bouine.org/zh/docs/guides/benchmarks/): Benchmark methodology and results comparing bouine against Varnish, NGINX, and Envoy across cache hit, miss, and mixed workloads.
- [Production readiness checklist](https://bouine.org/zh/docs/guides/production-checklist/): Checklist to review before deploying bouine to production.
- [Service Mesh 兼容性](https://bouine.org/zh/docs/guides/service-mesh/): Run bouine alongside Istio, Linkerd, and Cilium service meshes.

### 贡献

> 贡献者指南，涵盖本地设置、开发流程、提交格式、PR 检查和项目标准。

- [Codebase guide](https://bouine.org/zh/docs/contributing/codebase/): Contributor-oriented map of bouine packages, layers, good first tasks, and rules for safely changing cache behavior.
- [安全](https://bouine.org/zh/docs/contributing/security/): Security reporting, supported scope, high-impact vulnerability classes, and operational hardening checklist for bouine.

### 参考

> CLI、管理 API 和响应头参考。

- [CLI](https://bouine.org/zh/docs/reference/cli/): bouine command-line interface reference.
- [管理 API](https://bouine.org/zh/docs/reference/api/): Admin API endpoints, authentication, and response formats.
- [响应头](https://bouine.org/zh/docs/reference/headers/): bouine 添加的 HTTP 响应头。
- [Go SDK](https://bouine.org/zh/docs/reference/go-sdk/): Use the bouine Go SDK to manage cache invalidation, check health, and inspect cluster peers programmatically.