1508 字

8 分钟

修复Umami统计数据显示问题 - 适配新版API响应格式

2025-11-15

技术教程

Umami

/

Cloudflare Worker

/

API

/

故障排查

/

Bug修复

修复Umami统计数据显示问题 - 适配新版API响应格式#

从问题诊断到完美解决，记录一次API格式变更的修复之旅

🐛 问题现象#

在使用Cloudflare Worker代理Umami统计API时，突然发现网站的浏览量和访客数一直显示为0：

1
{
2
  "total": 0,
3
  "visitors": 0,
4
  "visits": 0,
5
  "bounces": 0,
6
  "totaltime": 0,
7
  "cached": false,
8
  "timestamp": 1763208601158
9
}

这显然不正常，因为网站实际上有大量的访问数据。

🔍 问题诊断#

初步排查#

首先检查了几个常见问题：

✅ API Token配置正确
✅ 网站ID正确
✅ Worker部署成功
✅ CORS配置正常

既然基础配置都没问题，那问题很可能出在数据解析上。

深入分析#

通过添加调试代码，我发现Umami API确实返回了数据，但Worker脚本无法正确提取。查看Umami官方文档后发现：

Umami API响应格式已经更新！

📊 API格式变化对比#

旧版格式（嵌套对象）#

1
{
2
  "pageviews": {
3
    "value": 34210,
4
    "change": 10
5
  },
6
  "visitors": {
7
    "value": 9401,
8
    "change": 7
9
  },
10
  "visits": {
11
    "value": 12726,
12
    "change": 8
13
  }
14
}

新版格式（扁平化）#

1
{
2
  "pageviews": 34210,
3
  "visitors": 9401,
4
  "visits": 12726,
5
  "bounces": 7918,
6
  "totaltime": 5214477,
7
  "comparison": {
8
    "pageviews": 30818,
9
    "visitors": 8776,
10
    "visits": 11756,
11
    "bounces": 7396,
12
    "totaltime": 1704355
13
  }
14
}

关键变化：

❌ 旧版：数据包装在 value 字段中
✅ 新版：数据直接作为顶层字段
➕ 新增：comparison 对比数据

🔧 修复方案#

问题代码#

旧代码尝试从 value 字段提取数据：

1
const result = {
2
  total: data.pageviews?.value || 0,  // ❌ 新版API中不存在value字段
3
  visitors: data.visitors?.value || 0,
4
  visits: data.visits?.value || 0,
5
  bounces: data.bounces?.value || 0,
6
  totaltime: data.totaltime?.value || 0,
7
};

修复后代码#

直接从顶层字段获取数据：

1
const result = {
2
  total: data.pageviews || 0,  // ✅ 直接获取数值
3
  visitors: data.visitors || 0,
4
  visits: data.visits || 0,
5
  bounces: data.bounces || 0,
6
  totaltime: data.totaltime || 0,
7
  cached: false,
8
  timestamp: Date.now(),
9
};

📝 完整修复步骤#

1. 修复总浏览量API#

修改 getTotalPageviews 函数：

1
async function getTotalPageviews(request) {
2
  const cacheUrl = new URL(request.url);
3
  cacheUrl.pathname = "/cache/total";
4
  const cacheKey = new Request(cacheUrl);
5

6
  // 尝试从缓存获取
7
  const cached = await getCache(cacheKey);
8
  if (cached) {
9
    return cached;
10
  }
11

12
  // 计算时间范围 (所有时间)
13
  const endDate = new Date();
14
  const startDate = new Date("2020-01-01"); // 获取全部历史数据
15

16
  const startAt = startDate.getTime();
17
  const endAt = endDate.getTime();
18

19
  // 调用 Umami API
20
  const apiUrl = `${CONFIG.UMAMI_API_URL}/websites/${CONFIG.UMAMI_WEBSITE_ID}/stats?startAt=${startAt}&endAt=${endAt}`;
21

22
  const response = await fetch(apiUrl, {
23
    headers: {
24
      Authorization: `Bearer ${CONFIG.UMAMI_API_TOKEN}`,
25
      "Content-Type": "application/json",
26
    },
27
  });
28

29
  if (!response.ok) {
30
    const errorText = await response.text();
31
    throw new Error(`Umami API error: ${response.status} - ${errorText}`);
32
  }
33

34
  const data = await response.json();
35

36
  // ✅ 直接从顶层字段获取数据
37
  const result = {
38
    total: data.pageviews || 0,
39
    visitors: data.visitors || 0,
40
    visits: data.visits || 0,
41
    bounces: data.bounces || 0,
42
    totaltime: data.totaltime || 0,
43
    cached: false,
44
    timestamp: Date.now(),
45
  };
46

47
  // 缓存结果
48
  await setCache(cacheKey, result, CONFIG.CACHE_TTL);
49

50
  return jsonResponse(result, 200, request);
51
}

2. 修复页面浏览量API#

修改 getPagePageviews 函数：

1
async function getPagePageviews(request, pageUrl) {
2
  const cacheUrl = new URL(request.url);
3
  cacheUrl.pathname = `/cache/page${pageUrl.startsWith("/") ? pageUrl : "/" + pageUrl}`;
4
  const cacheKey = new Request(cacheUrl);
5

6
  // 尝试从缓存获取
7
  const cached = await getCache(cacheKey);
8
  if (cached) {
9
    return cached;
10
  }
11

12
  // 计算时间范围 (所有时间)
13
  const endDate = new Date();
14
  const startDate = new Date("2020-01-01");
15
  const startAt = startDate.getTime();
16
  const endAt = endDate.getTime();
17

18
  // 使用 /stats API 并通过 url 参数过滤
19
  const apiUrl = `${CONFIG.UMAMI_API_URL}/websites/${CONFIG.UMAMI_WEBSITE_ID}/stats?startAt=${startAt}&endAt=${endAt}&url=${encodeURIComponent(pageUrl)}`;
20

21
  const response = await fetch(apiUrl, {
22
    headers: {
23
      Authorization: `Bearer ${CONFIG.UMAMI_API_TOKEN}`,
24
      "Content-Type": "application/json",
25
    },
26
  });
27

28
  if (!response.ok) {
29
    const errorText = await response.text();
30
    throw new Error(`Umami API error: ${response.status} - ${errorText}`);
31
  }
32

33
  const data = await response.json();
34

35
  // ✅ 直接从顶层字段获取数据
36
  const result = {
37
    url: pageUrl,
38
    pageviews: data.pageviews || 0,
39
    visitors: data.visitors || 0,
40
    cached: false,
41
    timestamp: Date.now(),
42
  };
43

44
  // 缓存结果
45
  await setCache(cacheKey, result, CONFIG.CACHE_TTL);
46

47
  return jsonResponse(result, 200, request);
48
}

3. 优化缓存机制#

将简单的内存缓存升级为Cloudflare Cache API：

1
/**
2
 * 使用 Cloudflare Cache API 进行缓存
3
 */
4
async function getCache(cacheKey) {
5
  const cache = caches.default;
6
  const response = await cache.match(cacheKey);
7
  if (!response) {
8
    return null;
9
  }
10

11
  // 检查缓存是否过期
12
  const expiry = response.headers.get("Cache-Expiry");
13
  if (expiry && Date.now() > parseInt(expiry, 10)) {
14
    caches.default.delete(cacheKey);
15
    return null;
16
  }
17
  return response;
18
}
19

20
async function setCache(cacheKey, data, ttlSeconds) {
21
  const cache = caches.default;
22
  const responseBody = JSON.stringify(data);
23
  const headers = {
24
    "Content-Type": "application/json",
25
    "Cache-Control": `public, max-age=${ttlSeconds}`,
26
    "Cache-Expiry": (Date.now() + ttlSeconds * 1000).toString(),
27
  };
28
  const response = new Response(responseBody, { headers });
29
  await cache.put(cacheKey, response);
30
}

✅ 修复效果#

修复后，API返回正常数据：

1
{
2
  "total": 34210,
3
  "visitors": 9401,
4
  "visits": 12726,
5
  "bounces": 7918,
6
  "totaltime": 5214477,
7
  "cached": false,
8
  "timestamp": 1763209211581
9
}

网站上的统计数据也正常显示了！

🎯 关键改进点#

1. API格式适配#

✅ 移除了对 .value 字段的依赖
✅ 直接从顶层获取数据
✅ 保持向后兼容性

2. 时间范围优化#

✅ 从”最近30天”改为”所有时间”
✅ 显示完整的历史统计数据

3. 缓存升级#

✅ 从内存Map升级到Cache API
✅ 更持久、更高效
✅ 支持边缘缓存

4. 错误处理增强#

✅ 添加详细的错误信息
✅ 包含HTTP状态码和响应文本
✅ 便于问题诊断

💡 经验总结#

遇到API数据异常时的排查思路#

确认基础配置
- API Token是否正确
- 端点URL是否正确
- 权限是否充足
检查API响应
- 添加调试日志
- 查看原始响应数据
- 对比API文档
验证数据解析
- 检查字段访问路径
- 确认数据类型
- 处理边界情况
测试修复效果
- 清除缓存
- 重新部署
- 验证各个端点

最佳实践建议#

版本兼容性

1
// 同时支持新旧格式
2
const value = data.field?.value || data.field || 0;

错误处理

1
if (!response.ok) {
2
  const errorText = await response.text();
3
  throw new Error(`API error: ${response.status} - ${errorText}`);
4
}

缓存策略

1
// 使用合适的TTL
2
const CACHE_TTL = 300; // 5分钟

调试信息

1
// 开发环境添加debug字段
2
if (isDev) {
3
  result.debug = { apiUrl, rawData: data };
4
}

🔗 相关资源#

📌 总结#

这次修复让我深刻体会到：

API文档很重要 - 定期查看官方文档，了解API变更
调试信息必不可少 - 添加适当的日志可以快速定位问题
错误处理要完善 - 详细的错误信息能节省大量排查时间
缓存要谨慎使用 - 确保缓存不会掩盖真实问题

希望这篇文章能帮助遇到类似问题的开发者快速解决问题！

创建日期: 2025年11月15日
最后更新: 2025年11月15日
版本: 1.0.0
状态: ✅ 已完成

修复Umami统计数据显示问题 - 适配新版API响应格式

https://www.freebird2913.tech/posts/umami-api-fix-cloudflare-worker/

作者

free bird

发布于

2025-11-15

许可协议

CC BY-NC-SA 4.0

Docker日志清理完全指南：从常规清理到紧急强制清理

1

修复Umami统计数据显示问题 - 适配新版API响应格式