写在前面#

Umami 是一个开源的分析工具，它可以帮助你了解你的网站的流量来源、用户行为、页面访问等信息。

Umami官方地址 umami

Umami官方文档: Umami - Doc

Umami官方API: Umami - API

正文#

这里需要注意一点，使用官方的api 只需要申请一个API KEY 就可以调用api了，如果使用自建服务器，需要先获取token，再进行调用。

认证#

POST /api/auth/login

首先你需要获得一个令牌，才能发起 API 请求。你需要向端点发送以下请求：POST/api/auth/login

1
{
2
  "username": "admin",
3
  "password": "umami"
4
}

如果成功，你应该会收到如下回复：

1
{
2
  "token": "eyTMjU2IiwiY...4Q0JDLUhWxnIjoiUE_A",
3
  "user": {
4
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
5
    "username": "admin",
6
    "role": "admin",
7
    "createdAt": "2000-00-00T00:00:00.000Z",
8
    "isAdmin": true
9
  }
10
}

保存标记值，并发送一个包含所有数据请求的头部，地址为。你的请求头应该是这样的：AuthorizationBearer

1
Authorization: Bearer eyTMjU2IiwiY...4Q0JDLUhWxnIjoiUE_A

每次需要权限的 API 调用都必须有授权令牌。

实现认证方式#

1
/**
2
 * 获取登录 Token (通过用户名/密码)
3
 * @param {string} baseUrl
4
 * @param {string} apiKey - 此处实际为 password
5
 */
6
async function fetchTokenData(baseUrl, apiKey) {
7
  const cached = localStorage.getItem(cacheTokenKey);
8
  if (cached) {
9
    try {
10
      const parsed = JSON.parse(cached);
11
      if (Date.now() - parsed.timestamp < cacheTTL) {
12
        return parsed.value;
13
      }
14
    } catch {
15
      localStorage.removeItem(cacheTokenKey);
16
    }
17
  }
18
  const res = await fetch(`${baseUrl}/api/auth/login`, {
19
    method: "POST",
20
    headers: {
21
      "Content-Type": "application/json",
22
    },
23
    body: JSON.stringify({
24
      username: "admin",
25
      password: apiKey,
26
    }),
27
  });
28
  if (!res.ok) {
29
    throw new Error("获取 Umami 登录信息失败");
30
  }
31
  const data = await res.json();
32
  localStorage.setItem(
33
    cacheTokenKey,
34
    JSON.stringify({ timestamp: Date.now(), value: data.token }),
35
  );
36
  return data.token;
37
}

IMPORTANT
使用这种方式会在浏览器中暴露请求的用户名和密码，建议创建一个单独的用户，只用于获取统计数据。

邪修玩法#

我们可以采用share key 认证方式，这样就不会暴露用户名和密码了。

原理：在umami网站中，我们可以将统计数据分享出去，使用户可以免登录查看统计数据。

分享页面请求了一下 /api/share/{shareId} 接口，返回了一个token，并且后面所有对api的请求都会带一个header x-umami-share-token，并且值和之前返回的token一致。

我们可以直接将上面的认证方法替换为x-umami-share-token，不需要使用用户名密码了。

1
/**
2
 * 获取分享 Token 数据
3
 * @param {string} baseUrl - Umami 实例地址
4
 * @param {string} shareId - 分享 ID
5
 */
6
async function fetchShareData(baseUrl, shareId) {
7
  const cached = localStorage.getItem(cacheShareKey);
8
  if (cached) {
9
    try {
10
      const parsed = JSON.parse(cached);
11
      if (Date.now() - parsed.timestamp < cacheTTL) {
12
        return parsed.value;
13
      }
14
    } catch {
15
      localStorage.removeItem(cacheShareKey);
16
    }
17
  }
18
  // 请求分享 API
19
  const res = await fetch(`${baseUrl}/api/share/${shareId}`);
20
  if (!res.ok) {
21
    throw new Error("获取 Umami 分享信息失败");
22
  }
23
  const data = await res.json();
24

25
  // 写入 LocalStorage 缓存
26
  localStorage.setItem(
27
    cacheShareKey,
28
    JSON.stringify({ timestamp: Date.now(), value: data }),
29
  );
30
  return data;
31
}

如果这篇文章对你有帮助，欢迎分享给更多人！

发现错误或想要改进这篇文章？

在 GitHub 上编辑此页

自建umami的相关配置

https://m.olinl.com/posts/umami-config/

作者

顾拾柒

发布于

2026-01-24

许可协议

CC BY-NC-SA 4.0

Nginx配置

Mizuki 入门指南