keyclic/cache-googlemaps-api_varnish

Varnish Google Maps API缓存镜像

镜像概述和主要用途

本镜像是基于Varnish缓存服务器的Docker镜像，专门优化用于缓存Google Maps API的重复请求。通过在应用与Google Maps API之间部署此镜像，可有效拦截并缓存频繁的重复调用，从而减少实际API请求次数，降低API配额消耗和使用成本，同时通过缓存响应提升应用的响应速度和稳定性。

核心功能和特性

• 高效缓存机制：基于Varnish高性能HTTP缓存引擎，针对Google Maps API请求特点优化缓存策略
• 智能参数处理：自动识别并处理API请求参数（如地理位置、缩放级别、API密钥等），生成唯一缓存键
• 可配置缓存策略：支持自定义缓存TTL（生存时间），可根据API类型（静态地图、地理编码等）调整缓存周期
• 缓存失效管理：支持基于时间和条件的缓存失效机制，确保数据新鲜度
• 轻量级部署：Docker容器化设计，资源占用低，部署简单，易于集成到现有架构
• 兼容性：支持Google Maps API各类接口（静态地图、地理编码、路线规划等）

使用场景和适用范围

适用场景

• 频繁调用Google Maps API的Web应用（如地图展示、位置搜索服务）
• 移动应用后端服务，需处理大量重复地理位置查询
• 对API响应速度有较高要求的实时位置服务
• 需要控制Google Maps API使用成本的企业或开发者

适用范围

• 所有使用Google Maps API的开发者和组织
• 兼容主流容器化部署环境（Docker、Kubernetes）
• 支持多种Google Maps API类型（静态地图、地理编码、路线规划等）

使用方法和配置说明

前提条件

• 已安装Docker Engine（20.10+推荐）
• 已获取有效的Google Maps API密钥
• （可选）HTTPS反向代理服务（如Nginx）用于SSL终止

基本使用示例

Docker Run命令

bash
docker run -d \
  --name varnish-gmaps \
  -p 80:80 \
  -v $(pwd)/vcl:/etc/varnish \
  -e VARNISH_TTL=3600 \
  -e BACKEND_HOST=maps.googleapis.com \
  -e BACKEND_PORT=443 \
  [镜像名称]

Docker Compose配置

yaml
version: '3'
services:
  varnish-gmaps:
    image: [镜像名称]
    container_name: varnish-gmaps
    ports:
      - "80:80"
    volumes:
      - ./vcl:/etc/varnish  # 挂载自定义VCL配置
    environment:
      - VARNISH_TTL=3600        # 缓存默认TTL（秒）
      - BACKEND_HOST=maps.googleapis.com  # Google Maps API主机
      - BACKEND_PORT=443         # API端口（HTTPS）
      - VARNISH_MEMORY=256m      # 缓存内存大小
    restart: unless-stopped

配置参数说明

环境变量

核心VCL配置示例

默认配置针对Google Maps API优化，关键部分如下：

vcl
vcl 4.0;

backend default {
    .host = env.BACKEND_HOST;
    .port = env.BACKEND_PORT;
    .connect_timeout = 5s;
    .first_byte_timeout = 10s;
}

sub vcl_recv {
    # 仅缓存GET请求
    if (req.method != "GET") {
        return (pass);
    }
    
    # 移除随机参数，确保重复请求被正确缓存
    set req.url = regsuball(req.url, "&random=[^&]+", "");
    
    # 设置缓存TTL
    set req.ttl = 3600s;
}

sub vcl_backend_response {
    # 仅缓存200状态码响应
    if (beresp.status != 200) {
        return (discard);
    }
    
    # 强制缓存标记
    set beresp.cacheable = true;
    
    # 限制最大TTL
    set beresp.ttl = std.min(beresp.ttl, 3600s);
}

注意事项

• 针对实时性要求高的API（如交通信息），建议缩短TTL至30-300秒
• 确保API密钥安全，避免通过缓存响应泄露密钥
• 定期监控缓存命中率（可通过Varnish自带工具varnishstat查看）
• 对于HTTPS请求，需在前端部署反向代理处理SSL终止后再转发至Varnish