Umami Status Public API

中文版 README | English README

一个基于 Cloudflare Worker 的 Umami 网站统计数据公共 API 服务，提供网站访问统计数据的 RESTful API 接口。支持私有化部署。

功能特性

• 🚀 基于 Cloudflare Worker 技术，响应速度快
• 📊 提供今日、昨日、近30天、近一年的访问统计数据
• 💾 内置缓存机制，减少对 Umami 服务器的请求压力（默认10分钟）
• 🔒 支持 CORS 跨域访问
• 🐳 支持 Docker 部署
• ⚡ 使用 workerd 运行时，支持 Docker 私有化部署，性能优异

API 接口

获取统计数据

请求方式： GET /

响应格式：

{
  "today_uv": 123,        // 今日独立访客数
  "today_pv": 456,        // 今日页面浏览量
  "yesterday_uv": 98,     // 昨日独立访客数
  "yesterday_pv": 234,    // 昨日页面浏览量
  "last_month_pv": 12345, // 近30天页面浏览量
  "last_year_pv": 123456  // 近一年页面浏览量
}

快速开始

使用 CloudFlare Workers 部署

1. 登录 Cloudflare 控制台，创建一个新的 Worker 项目。
2. 复制 worker/status.js 文件的内容到 Worker 项目的 index.js 文件中。
3. 修改 index.js 文件中的 CONFIG 对象配置 Umami 信息：
   • API_BASE_URL: Umami 服务器的基础 URL
   • USERNAME: Umami 登录用户名
   • PASSWORD: Umami 登录密码
   • WEBSITE_ID: 要统计的网站 ID（可在 Umami 后台获取）
   • CACHE_TIME: 数据缓存时间，单位为秒（默认 600 秒）
4. 部署 Worker 项目。
5. 配置域名：
   • 在 Cloudflare 控制台为 Worker 项目配置一个自定义域名（如 api.umami-status.domain.com）
   • 添加 DNS 记录，将域名指向 Worker 项目的域名

使用 Docker 部署

1. 克隆项目

git clone https://github.com/iWangJiaxiang/umami-status-public-api
cd umami-status-public-api

2. 配置参数 编辑 worker/status.js 文件中的 CONFIG 对象：

const CONFIG = {
  API_BASE_URL: 'https://your-umami-domain.com',  // 你的 Umami 服务器地址
  USERNAME: 'your-username',                       // Umami 用户名
  PASSWORD: 'your-password',                       // Umami 密码
  WEBSITE_ID: 'your-website-id',                   // 网站 ID
  CACHE_TIME: 600                                  // 缓存时间（秒）
}

3. 启动服务

docker-compose up -d

4. 访问 API 服务将在 http://localhost:8080 启动，你可以通过以下方式测试：

curl http://localhost:8080

5. 配置公网访问

使用反向代理将服务的端口映射到公网端口。

Enjoy!

本地开发

如果你想在本地开发环境中运行：

1. 安装 workerd

npm install -g @cloudflare/workerd

2. 运行服务

workerd serve worker/worker.capnp

配置说明

worker/status.js 文件中的 CONFIG 对象

• API_BASE_URL: Umami 服务器的基础 URL
• USERNAME: Umami 登录用户名
• PASSWORD: Umami 登录密码
• WEBSITE_ID: 要统计的网站 ID（可在 Umami 后台获取）
• CACHE_TIME: 数据缓存时间，单位为秒（默认 600 秒）

缓存机制

• API 内置了 10 分钟的缓存机制
• 缓存包括认证 token 和统计数据
• 有效减少对 Umami 服务器的请求频率

项目结构

umami-status-public-api/
├── docker-compose.yml          # Docker 编排文件
└── worker/
    ├── status.js              # 主要的 Worker 脚本
    └── worker.capnp           # workerd 配置文件

技术栈

• 运行时: Cloudflare workerd
• 语言: JavaScript (ES6+)
• 容器化: Docker
• API: RESTful API

注意事项

1. 安全性: 请确保 Umami 的用户名和密码安全，建议使用专门的 API 用户
2. 访问频率: 内置缓存机制可以减少对 Umami 服务器的压力
3. CORS: 已配置允许跨域访问，适合前端直接调用
4. 错误处理: API 包含完整的错误处理机制

许可证

本项目基于开源许可证发布，具体许可证信息请查看 LICENSE 文件。

贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目！

鸣谢

关于本项目的诞生，请参考博客文章：部署Umami展示API，为博客提供PV数据和Umami：自建网站访问统计服务，突破浏览器广告拦截

JS 脚本移植自 PHP 版本，原始参考: 使用Docker搭建Umami统计，显示近一年的pv、uv数据的API搭建

私有化部署版本的 workerd 运行时: https://github.com/JacobLinCool/workerd-docker

参考

• Cloudflare Workers 文档
• Umami Analytics 文档