Baby Gravatar

Gravatar 头像镜像服务 · 完全兼容官方 API · Nginx 代理缓存 + 上游降级策略

Mirror secure.gravatar.com avatars

代理 Gravatar 官方头像，只需替换域名

Use directly in <img src="...">

/avatar/ 路径可直接作为图片地址使用

Nginx proxy cache + stale fallback

成功响应缓存 1 天，上游异常时使用旧缓存

WordPress / Typecho / Discuz ready

一行配置替换 Gravatar 域名即可接入

Email MD5 hash, same as official

邮箱 MD5 哈希，参数与官方完全一致

工具说明

Baby Gravatar 是一个轻量级的 Gravatar 头像镜像与代理服务。将 secure.gravatar.com 的头像请求转发到本地节点，加速国内及亚太地区的头像加载，同时保持与官方 API 完全兼容。

适用于 WordPress 博客、论坛、评论系统等依赖 Gravatar 的场景； /avatar/{hash} 可直接作为 <img src="..."> 的图片地址使用，无需额外处理。

↑ 通过 /avatar/ 直出

接口说明

1. 头像直出（推荐）

GET /avatar/{email_md5}?s={size}&d={default}&r={rating}

直接返回头像图片二进制（如 image/jpeg、image/png），行为与 https://secure.gravatar.com/avatar/{hash} 完全一致。命中本地缓存时无需再次请求上游。

若邮箱未注册 Gravatar，按 d 参数返回默认头像。

打开图片示例

2. 域名替换方式

https://g.zhongxiaojie.cn/avatar/{hash}?s=80

将原有 Gravatar 地址中的域名替换为本站域名即可，路径与参数保持不变。

[
  官方: https://secure.gravatar.com/avatar/1b4f0e9851971998e73208fea88ece8?s=80
  镜像: https://g.zhongxiaojie.cn/avatar/1b4f0e9851971998e73208fea88ece8?s=80
]

3. WordPress 接入

在 functions.php 中添加过滤器，自动替换头像 URL：

add_filter('get_avatar_url', function ($url) {
  return str_replace(
    'https://secure.gravatar.com',
    'https://g.zhongxiaojie.cn',
    $url
  );
});

参数说明

hash：必填。邮箱地址的 MD5 哈希（小写）。
s：可选。头像尺寸（像素），如 ?s=80。
d：可选。默认头像类型：identicon、monsterid、wavatar、retro、robohash、mp、404 等。
r：可选。内容分级：g（默认）、pg、r、x。

在线演示

输入邮箱地址，实时预览镜像头像效果。

MD5：1b4f0e9851971998e73208fea88ece8

URL：/avatar/1b4f0e9851971998e73208fea88ece8?s=80&d=identicon

镜像：https://g.zhongxiaojie.cn/avatar/{hash}?s=80

缓存机制

Nginx 代理缓存：头像响应缓存 1 天（200/302），404 缓存 5 分钟，减少重复请求上游 Gravatar 服务器。

缓存锁：启用 proxy_cache_lock 防止惊群效应，同一头像并发请求时仅一个回源。

降级策略：上游超时或 5xx 时自动使用过期缓存（proxy_cache_use_stale），响应头 X-Cache-Status 可查看命中状态。

安装与启动

# 站点目录
/home/wwwroot/g.zhongxiaojie.cn

# 将 public/ 内容部署到站点根目录后，重载 Nginx
nginx -t && nginx -s reload

域名 g.zhongxiaojie.cn，Nginx 配置见项目 deploy/g.zhongxiaojie.cn.conf。缓存目录 /home/wwwroot/g.zhongxiaojie.cn/cache 需提前创建并赋予 Nginx 写权限。