secoresearch/varnish

Varnish Docker镜像文档

1. 镜像概述和主要用途

Varnish Docker镜像是基于Varnish缓存服务器的容器化部署包。Varnish是一款高性能的HTTP反向代理缓存服务器，通过缓存频繁访问的Web内容，显著提升内容交付速度，降低后端服务器负载。

主要用途：

• 作为HTTP反向代理缓存服务器，加速静态/动态Web内容交付
• 减轻后端应用服务器压力，提高系统吞吐量
• 优化用户访问体验，减少页面加载时间

2. 核心功能和特性

• 自定义VCL配置：支持通过挂载自定义VCL（Varnish配置语言）文件，灵活定义缓存策略、请求路由等
• 动态VCL生成：未提供自定义VCL时，容器自动生成默认配置，支持通过环境变量控制缓存行为
• 缓存策略配置：可通过环境变量设置缓存Cookie、Authorization头处理规则，指定默认TTL（缓存时间）、后端服务IP和端口
• 资源配置：支持自定义缓存内存大小，适配不同负载场景
• 日志增强：可配置日志哈希记录，辅助调试缓存命中情况

3. 使用场景和适用范围

• 静态内容缓存：加速图片、CSS、JavaScript等静态资源交付，减少重复请求
• 动态内容加速：对动态生成的页面（如PHP、Python后端）进行缓存，缩短响应时间
• 高流量网站负载均衡：作为反向代理分发请求到多个后端服务器，同时缓存内容减轻整体负载
• 临时缓存方案：快速部署缓存层，无需复杂的服务器配置
• CDN边缘节点：作为边缘缓存，加速区域内容分发

4. 详细使用方法

4.1 构建镜像（可选）

如需基于源码自定义构建Varnish镜像，执行以下命令：

bash
docker build -t varnish .

说明：默认情况下可直接使用官方或预构建的Varnish镜像，无需手动构建。

4.2 运行容器（docker run）

4.2.1 使用自定义VCL配置

挂载本地自定义VCL文件（default.vcl）运行容器：

bash
docker run -it --rm \
  -u "$(id -u)" \  # 指定运行用户ID，避免权限问题
  -p 8080:8080 \    # 端口映射（宿主机端口:容器内端口，容器内默认HTTP端口通过VARNISH_HTTP_PORT配置）
  -v /path/to/default.vcl:/etc/varnish/default.vcl \  # 挂载自定义VCL文件
  -e VARNISH_MEM="2G" \  # 配置缓存内存大小为2G
  varnish

4.2.2 使用默认VCL配置

未提供自定义VCL时，容器自动生成默认配置，通过环境变量控制缓存策略：

bash
docker run -it --rm \
  -p 80:80 \  # 映射默认HTTP端口（容器内默认80，通过VARNISH_HTTP_PORT修改）
  -e VARNISH_MEM="1G" \  # 缓存内存1G
  -e VARNISH_DEFAULT_TTL="3600s" \  # 默认缓存时间1小时
  -e VARNISH_BACKEND_IP="192.168.1.100" \  # 后端服务IP
  -e VARNISH_BACKEND_PORT="8080" \  # 后端服务端口
  -e VARNISH_CACHE_COOKIES=1 \  # 缓存含Cookie的请求，并将Cookie纳入哈希
  varnish

4.3 docker-compose配置示例

创建docker-compose.yml文件，配置Varnish服务：

yaml
version: '3'
services:
  varnish:
    image: varnish
    ports:
      - "80:80"  # 宿主机80端口映射到容器HTTP端口
    volumes:
      - ./default.vcl:/etc/varnish/default.vcl  # 挂载自定义VCL（可选）
    environment:
      - VARNISH_MEM="2G"  # 缓存内存大小
      - VARNISH_HTTP_PORT="80"  # 容器内HTTP服务端口
      - VARNISH_DEFAULT_TTL="3600s"  # 默认TTL（仅默认VCL生效）
      - VARNISH_BACKEND_IP="backend-service"  # 后端服务名称/IP（需与后端服务网络互通）
      - VARNISH_BACKEND_PORT="8080"  # 后端服务端口（仅默认VCL生效）
    depends_on:
      - backend-service  # 依赖后端服务（需确保后端服务先启动）
  backend-service:
    image: your-backend-image  # 后端应用镜像
    ports:
      - "8080:8080"

5. 配置说明

5.1 基础配置环境变量

以下环境变量对自定义VCL和默认VCL均生效：

5.2 默认VCL生成环境变量（未提供自定义VCL时生效）

当未挂载自定义default.vcl时，容器通过以下环境变量生成默认VCL配置，变量未设置则不生效：

6. 注意事项

• 自定义VCL优先级：挂载自定义default.vcl后，5.2节中的默认VCL生成环境变量均不生效，需在VCL文件中手动定义缓存策略。
• Authorization头缓存风险：
  • VARNISH_CACHE_AUTH会缓存含Authorization头的请求，可能导致后端已失效的Authorization仍可访问缓存内容。
  • VARNISH_IGNORE_AUTH会忽略Authorization值，可能导致不同用户共享同一缓存内容，存在权限安全风险。
• 默认缓存行为：未配置时，含Authorization头的请求默认不缓存；含Cookie的请求默认不缓存。
• VCL语法校验：自定义VCL文件需确保语法正确，否则容器启动会失败，建议先通过varnishd -C -f default.vcl本地校验。