访客地球 Visitor Globe

Hexo Butterfly 主题侧边栏 · Vercel 无服务器 API

把访客的位置，转到这颗地球上

这是一个可直接部署到 Vercel 的访客地球 API 项目。访客打开你的博客时，前端小组件会自动向 API 签到，服务端通过 IP 解析出城市级的大致位置（不存储原始 IP，仅存加盐哈希），地球上的光点即每一位访客所在的城市。 旁边的预览卡片就是真实运行的组件。

  • 点阵大陆 + 大气光晕，简洁立体
  • 自动旋转，支持拖拽，访客城市朝向镜头
  • 显示累计访客数 / 当前在线数
  • 轮播展示城市名与该城访客数量
  • Vercel 内置 GeoIP，零第三方密钥
  • Upstash Redis 持久化（可选，免费）
1

部署 API 到 Vercel

将本项目推送到 GitHub 仓库，然后在 Vercel 中 Add New… → Project 导入并直接 Deploy（Next.js 项目无需任何额外配置）。国内访问建议在 Vercel 项目设置里绑定自定义域名。

部署后即可工作（数据保存在函数内存中）。如需多实例共享、重启不丢失，请继续第 2 步接入 Upstash Redis；只是想先跑起来，可跳过。

2

（可选）接入 Upstash Redis 持久化

到 upstash.com 免费创建一个 Redis 数据库，把两个连接变量配置到 Vercel 项目环境变量中即可，API 会自动切换为 Redis 存储（访客会话为 30 分钟滑动窗口）：

env
# Vercel 项目 → Settings → Environment Variables
UPSTASH_REDIS_REST_URL=https://xxx.upstash.io
UPSTASH_REDIS_REST_TOKEN=AXxxxxxxxxxxxxxxx
VISITOR_GLOBE_SALT=换一个只有你知道的随机字符串
3

Butterfly 主题接入（一行代码）

打开博客根目录的 _config.butterfly.yml，在 inject.bottom 中添加脚本（主题文档 「Inject」一节的标准注入方式）。组件会自动把卡片挂载到侧边栏 #aside-content 的顶部，并兼容 pjax。

yaml
# _config.butterfly.yml
inject:
  bottom:
    # 只需要这一行（自动挂载到侧边栏 #aside-content 顶部）
    - <script defer src="https://YOUR-API-DOMAIN.vercel.app/widget/visitor-globe.js"></script>

如果想放到指定位置或自定义参数（高度、标题、转速、配色等），这样写：

yaml
# 想挂到指定容器 / 自定义参数时：
inject:
  bottom:
    - <div id="my-globe"></div>
    - <script>window.VISITOR_GLOBE={mount:'#my-globe',height:260,title:'访客地球',rotateSpeed:0.12}</script>
    - <script defer src="https://YOUR-API-DOMAIN.vercel.app/widget/visitor-globe.js"></script>

提示：把 YOUR-API-DOMAIN.vercel.app 换成你的实际域名。组件所需的 three.js 由 API 域名自带提供（/widget/three.min.js），无需再引 CDN；陆地点阵内嵌在脚本中，全站零外部图片请求。

4

API 接口一览

POST/api/visitors

浏览器端自动调用。服务端读取 IP → Vercel GeoIP（或 ipwho.is 回退）→ 记录 30 分钟会话， 返回分布数据与访客自身位置 me。

GET/api/visitors

获取当前访客分布：累计访客 total、活跃会话 active、按城市聚合的 cities（名称 / 国家 / 坐标 / 数量）。

GET /api/visitors 实时响应：

加载中…

实时预览 · 与博客侧边栏完全一致

演示环境使用内存存储并预置了演示数据；部署到 Vercel 后显示的即是真实访客。 本地开发时你的真实位置可能无法解析（内网 IP），属正常现象。