---
title: "6. 缓存"
linkTitle: "6. 缓存"
weight: 170
description: "缓存段和代理段中的缓存限制与配置"
icon: fa-solid fa-box-archive
module: [HAPROXY]
categories: [参考]
aliases:
  - /haproxy/configuration/cache/
  - /docs/haproxy/configuration/cache/
  - /haproxy/cache/
upstream_link: "https://docs.haproxy.org/3.4/configuration.html"
upstream_name: "HAProxy 3.4 Configuration Manual"
upstream_ref: "v3.4.4, chapter 6"
---

<!-- Generated by scripts/generate-haproxy-docs.py from pinned upstream text. -->

HAProxy 提供一个缓存，专为小型对象（如 favicon、CSS 等）的缓存而设计。
这是一个极简且低维护成本的缓存，运行于内存中。

缓存基于所有线程共享的内存区域，并划分为 1kB 的块。

若某个对象不再被使用，即使未过期，也可被删除以腾出空间存储新对象。当尝试分配新对象时，将优先删除最旧的对象。

缓存使用主机头和 URI 的哈希值作为键。

可通过 Unix 套接字命令 "show cache" 查看缓存状态，详见管理指南 [第 9.3 节](/zh/docs/haproxy/filters/#section-9-3) "Unix 套接字命令"。

当缓存直接提供对象时，日志中的服务器名称将被替换为 "`<CACHE>`"。

## 6.1. 限制 {#section-6-1}

缓存不会在以下情况下存储或提供对象：

- 如果响应状态码不是 200

- 如果响应包含 Vary 头，且满足以下任一条件：process-vary 选项被禁用，或 Vary 值中指定了当前未管理的头（目前仅接受 accept-encoding、referer 和 origin 为已管理头）

- 如果 Content-Length 与头大小之和大于 "max-object-size"

- 如果响应不可缓存

- 如果响应未指定明确的过期时间（s-maxage 或 max-age Cache-Control 指令，或 Expires 头），且未提供验证器（ETag 或 Last-Modified 头）

- 如果 process-vary 选项已启用，且当前响应的主键已存在 max-secondary-entries 个相同主键的条目

- 如果 process-vary 选项已启用，响应使用了未知编码（未在 <https://www.iana.org/assignments/http-parameters/http-parameters.xhtml> 中列出），并以客户端 accept-encoding 头作为 Vary 条件

- 如果请求方法不是 GET

- 如果请求的 HTTP 版本小于 1.1

- 如果请求包含 Authorization 头

## 6.2. 配置 {#section-6-2}

要设置缓存，必须定义一个缓存段，并在代理中通过相应的 http-request 和 http-response 动作使用该缓存。

### 6.2.1. 缓存段 {#section-6-2-1}

<a id="entry-6-2-1-cache"></a>

**`cache <name>`**

```haproxy
cache <name>
```

声明一个缓存段，分配一个名为 `<name>` 的共享缓存内存，缓存大小为必填项（参见下方关键字 "total-max-size"）。

<a id="entry-6-2-1-max-age"></a>

**`max-age <seconds>`**

```haproxy
max-age <seconds>
```

定义最大过期时长。过期时间以 Cache-Control 响应头中 s-maxage 或 max-age（按此顺序）指令的最小值与该值之间的较小者为准。默认值为 60 秒，表示默认情况下无法缓存对象超过 60 秒。

<a id="entry-6-2-1-max-object-size"></a>

**`max-object-size <bytes>`**

```haproxy
max-object-size <bytes>
```

定义缓存对象的最大大小。不得大于 "total-max-size" 的一半。若未设置，其值等于缓存大小的 1/256。所有大小超过 "max-object-size" 的对象将不会被缓存。

<a id="entry-6-2-1-max-secondary-entries"></a>

**`max-secondary-entries <number>`**

```haproxy
max-secondary-entries <number>
```

定义缓存中具有相同主键的二级条目最大并发数量。
此设置需要启用 Vary 支持。默认值为 10，应设置为严格正整数。

<a id="entry-6-2-1-process-vary"></a>

**`process-vary <on/off>`**

```haproxy
process-vary <on/off>
```

启用或禁用对 Vary 头的处理。禁用时，包含该头的响应将永远不会被缓存。启用时，需对所有入站请求的请求头子集计算初步哈希值（可能带来 CPU 开销），该哈希值将用于为特定请求构建二级键（参见 RFC 7234#4.1）。目前，二级键由 'accept-encoding'、'referer' 和 'origin' 头的内容构成。根据 RFC，'origin' 和 'referer' 都是单值头，因此包含多个此类头实例的请求应视为格式错误。对于这类请求，HAProxy 不会构建二级键，也不会从缓存返回响应，而是交由服务器决定如何处理。默认值为 off（禁用）。

<a id="entry-6-2-1-total-max-size"></a>

**`total-max-size <megabytes>`**

```haproxy
total-max-size <megabytes>
```

定义缓存的 RAM 大小，单位为兆字节。该大小将被划分为 1kB 的块，供缓存条目使用。最大值为 4095。

### 6.2.2. 代理段 {#section-6-2-2}

使用缓存的代理段需在 "http-request" 规则集中包含 "cache-use" 动作，以从缓存中查找请求的对象；并在 "http-response" 规则集中包含 "cache-store" 动作，以将获取的对象存储或更新至缓存。这些动作均可选择性地附加条件。例如，可决定对某个已知不可缓存的子目录跳过 "cache-use" 动作，或对某些已知无价值的内容类型跳过 "cache-store" 动作。请注意，缓存索引键在执行 "cache-use" 动作时计算，因此若跳过该动作，响应路径上将不会尝试更新缓存。

示例：

```text
backend bck1
  mode http

  http-request cache-use foobar
  http-response cache-store foobar
  server srv1 127.0.0.1:80

cache foobar
  total-max-size 4
  max-age 240
```