Umami API 获取访客数 / 浏览量 / 访问次数 / 在线人数

使用 Umami Server API 获取访客数 / 浏览量 / 访问次数 / 在线人数#

在 自部署 Umami（Docker + Nginx HTTPS） 场景下，通过 Server API 的方式，安全地获取以下统计数据：

访客数（Unique Visitors / UV）
浏览量（Pageviews / PV）
访问次数（Visits / Sessions）
在线人数（Active Visitors）

适用于：静态博客 + 后端代调 API（Go / Node / Java） 的架构。

Umami 文档
Umami API 参考

安全架构#

浏览器
   ↓
你自己的后端接口（如 /api/analytics）
   ↓
Umami Server API（携带 token）

Umami 只对内网或后端可见
前端永远只访问你自己的 API
后端可做缓存 / 限流 / 聚合

不推荐的做法

前端（浏览器）直接调用 Umami /api/*

在前端暴露 Umami 用户名 / 密码 / token

获取 API Token（登录）#

请求示例

curl -X POST "https://umami.example.com/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"your-username","password":"your_password"}'

响应示例

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  ...
}

后续所有 Server API 请求都需要携带：Authorization: Bearer <token>

获取 Website ID（站点 ID）#

每个站点在 Umami 中都有一个唯一的 websiteId。

请求示例

curl -X GET "https://umami.example.com/api/websites" \
  -H "Authorization: Bearer <token>"

响应示例

{
  "data": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "Example",
      "domain": "example.com",
      ...
    }
  ],
  ...
}

记录下 id 字段，后续 API 请求中需要使用。

websiteId = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

获取访客数 / 浏览量 / 访问次数（汇总统计）#

使用接口：Website Stats

GET /api/websites/{websiteId}/stats

参数说明

参数	说明
startAt	开始时间（毫秒时间戳）
endAt	结束时间（毫秒时间戳）
timezone	时区（如 `Asia/Shanghai`）
path（可选）	URL名称（单篇文章访问量）

请求示例（获取最近 7 天）

curl -X GET "https://umami.example.com/api/websites/{websiteId}/stats?startAt=1768899198000&endAt=1769503998000&timezone=Asia/Shanghai" \
  -H "Authorization: Bearer <token>"

响应示例

{
  "pageviews": 32,
  "visitors": 2,
  "visits": 4,
  ...
}

对应关系

指标	含义
`pageviews`	浏览量（PV）
`visitors`	访客数（UV，去重）
`visits`	访问次数（Sessions）

获取在线人数（Active Visitors）#

使用接口：Active

该接口用于获取 当前在线访客数（近一段时间内仍活跃的访客）。

GET /api/websites/{websiteId}/active

请求示例

curl -X GET "https://umami.example.com/api/websites/{websiteId}/active" \
  -H "Authorization: Bearer <token>"

响应示例

{
  "active": 2
}

Umami Server API 统计后端接口（Go）#

使用 Go 编写一个轻量后端，通过 Server API 安全获取并对外提供：

访客数（Unique Visitors / UV）
浏览量（Pageviews / PV）
访问次数（Visits）
在线人数（Active Visitors）

安装 Go#

cd /tmp
wget https://go.dev/dl/go1.22.6.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.22.6.linux-amd64.tar.gz

配置环境变量#

echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc
go version

项目结构#

umami-analytics-api/
├── main.go
├── go.mod
└── config.yaml

创建项目目录：

mkdir -p umami-analytics-api && cd umami-analytics-api
go mod init umami-analytics-api

配置说明#

变量名	示例	说明
`umami.base_url`	`http://umami:3000` 或 `http://127.0.0.1:3000`	Umami 地址（推荐容器内网）
`umami.username`	`admin`	Umami 管理员账号
`umami.password`	`xxxxxx`	Umami 管理员密码
`umami.website_id`	`1622d120-...`	站点 ID
`umami.timezone`	`Asia/Shanghai`	时区
`server.listen_addr`	`:8080`	后端监听地址
`server.cache_ttl_seconds`	`3`	微缓存秒数（建议 1~5）
`server.api_key`	`change_me`	可选：请求头鉴权（为空则关闭）

配置文件示例#

1
server:
2
  listen_addr: ":8080"          # 端口号
3
  api_key: "change_me"          # 为空则不校验
4
  cache_ttl_seconds: 3          # 微缓存 1~5 秒推荐
5

6
umami:
7
  base_url: "http://umami:3000"  # 容器内网地址
8
  username: "admin"
9
  password: "your_password"
10
  website_id: "1622d120-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
11
  timezone: "Asia/Shanghai"

读取 YAML 配置文件需要一个轻量依赖：gopkg.in/yaml.v3

1
module umami-analytics-api
2

3
go 1.22
4

5
require gopkg.in/yaml.v3 v3.0.1

后端代码#

1
package main
2

3
import (
4
  "bytes"
5
  "crypto/sha1"
6
  "encoding/hex"
7
  "encoding/json"
8
  "errors"
9
  "flag"
10
  "fmt"
11
  "io"
12
  "log"
13
  "net"
14
  neturl "net/url"
15
  "os"
16
  "strings"
17
  "sync"
18
  "time"
19

20
  "gopkg.in/yaml.v3"
21
  "net/http"
22
)
23

24
type AppConfig struct {
25
  Server struct {
26
    ListenAddr      string `yaml:"listen_addr"`
27
    APIKey          string `yaml:"api_key"`
28
    CacheTTLSeconds int    `yaml:"cache_ttl_seconds"`
29
  } `yaml:"server"`
30

31
  Umami struct {
32
    BaseURL   string `yaml:"base_url"`
33
    Username  string `yaml:"username"`
34
    Password  string `yaml:"password"`
35
    WebsiteID string `yaml:"website_id"`
36
    Timezone  string `yaml:"timezone"`
37
  } `yaml:"umami"`
38
}
39

40
type RuntimeConfig struct {
41
  UmamiBaseURL string
42
  Username     string
43
  Password     string
44
  WebsiteID    string
45
  Timezone     string
46

47
  ListenAddr string
48
  APIKey     string
49
  CacheTTL   time.Duration
50
}
51

52
func loadConfig(path string) (RuntimeConfig, error) {
53
  b, err := os.ReadFile(path)
54
  if err != nil {
55
    return RuntimeConfig{}, err
56
  }
57
  var c AppConfig
58
  if err := yaml.Unmarshal(b, &c); err != nil {
59
    return RuntimeConfig{}, err
60
  }
61

62
  rc := RuntimeConfig{
63
    UmamiBaseURL: strings.TrimRight(strings.TrimSpace(c.Umami.BaseURL), "/"),
64
    Username:     strings.TrimSpace(c.Umami.Username),
65
    Password:     c.Umami.Password,
66
    WebsiteID:    strings.TrimSpace(c.Umami.WebsiteID),
67
    Timezone:     strings.TrimSpace(c.Umami.Timezone),
68

69
    ListenAddr: strings.TrimSpace(c.Server.ListenAddr),
70
    APIKey:     strings.TrimSpace(c.Server.APIKey),
71
    CacheTTL:   time.Duration(c.Server.CacheTTLSeconds) * time.Second,
72
  }
73

74
  // defaults
75
  if rc.ListenAddr == "" {
76
    rc.ListenAddr = ":8080"
77
  }
78
  if rc.Timezone == "" {
79
    rc.Timezone = "Asia/Shanghai"
80
  }
81
  if c.Server.CacheTTLSeconds <= 0 {
82
    rc.CacheTTL = 0
83
  }
84

85
  // validate
86
  missing := []string{}
87
  if rc.UmamiBaseURL == "" {
88
    missing = append(missing, "umami.base_url")
89
  }
90
  if rc.Username == "" {
91
    missing = append(missing, "umami.username")
92
  }
93
  if rc.Password == "" {
94
    missing = append(missing, "umami.password")
95
  }
96
  if rc.WebsiteID == "" {
97
    missing = append(missing, "umami.website_id")
98
  }
99
  if len(missing) > 0 {
100
    return RuntimeConfig{}, fmt.Errorf("missing config fields: %s", strings.Join(missing, ", "))
101
  }
102

103
  return rc, nil
104
}
105

106
// ---------- Umami token ----------
107

59 collapsed lines
108
type TokenManager struct {
109
  mu    sync.Mutex
110
  token string
111
}
112

113
func (tm *TokenManager) Get(cfg RuntimeConfig, c *http.Client) (string, error) {
114
  tm.mu.Lock()
115
  defer tm.mu.Unlock()
116
  if tm.token != "" {
117
    return tm.token, nil
118
  }
119
  tok, err := login(cfg, c)
120
  if err != nil {
121
    return "", err
122
  }
123
  tm.token = tok
124
  return tok, nil
125
}
126

127
func (tm *TokenManager) Invalidate() {
128
  tm.mu.Lock()
129
  defer tm.mu.Unlock()
130
  tm.token = ""
131
}
132

133
func login(cfg RuntimeConfig, c *http.Client) (string, error) {
134
  body, _ := json.Marshal(map[string]string{
135
    "username": cfg.Username,
136
    "password": cfg.Password,
137
  })
138

139
  req, err := http.NewRequest("POST", cfg.UmamiBaseURL+"/api/auth/login", bytes.NewReader(body))
140
  if err != nil {
141
    return "", err
142
  }
143
  req.Header.Set("Content-Type", "application/json")
144

145
  resp, err := c.Do(req)
146
  if err != nil {
147
    return "", err
148
  }
149
  defer resp.Body.Close()
150

151
  if resp.StatusCode != 200 {
152
    b, _ := io.ReadAll(resp.Body)
153
    return "", fmt.Errorf("umami login failed: %s, body=%s", resp.Status, string(b))
154
  }
155

156
  var out struct {
157
    Token string `json:"token"`
158
  }
159
  if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
160
    return "", err
161
  }
162
  if out.Token == "" {
163
    return "", errors.New("umami login returned empty token")
164
  }
165
  return out.Token, nil
166
}
167

168
// ---------- tiny TTL cache ----------
169

31 collapsed lines
170
type cacheItem struct {
171
  val []byte
172
  exp time.Time
173
}
174

175
type ttlCache struct {
176
  mu    sync.Mutex
177
  items map[string]cacheItem
178
}
179

180
func newTTLCache() *ttlCache { return &ttlCache{items: make(map[string]cacheItem)} }
181

182
func (c *ttlCache) Get(key string) ([]byte, bool) {
183
  c.mu.Lock()
184
  defer c.mu.Unlock()
185
  it, ok := c.items[key]
186
  if !ok {
187
    return nil, false
188
  }
189
  if time.Now().After(it.exp) {
190
    delete(c.items, key)
191
    return nil, false
192
  }
193
  return it.val, true
194
}
195

196
func (c *ttlCache) Set(key string, val []byte, ttl time.Duration) {
197
  c.mu.Lock()
198
  defer c.mu.Unlock()
199
  c.items[key] = cacheItem{val: val, exp: time.Now().Add(ttl)}
200
}
201

202
// ---------- helpers ----------
203

95 collapsed lines
204
func clientIP(r *http.Request) string {
205
  xff := r.Header.Get("X-Forwarded-For")
206
  if xff != "" {
207
    parts := strings.Split(xff, ",")
208
    return strings.TrimSpace(parts[0])
209
  }
210
  host, _, err := net.SplitHostPort(r.RemoteAddr)
211
  if err == nil {
212
    return host
213
  }
214
  return r.RemoteAddr
215
}
216

217
func sha1Short(s string) string {
218
  h := sha1.Sum([]byte(s))
219
  return hex.EncodeToString(h[:])[:12]
220
}
221

222
func calcRangeMs(rng, tz string) (startAt, endAt int64) {
223
  loc, err := time.LoadLocation(tz)
224
  if err != nil {
225
    loc = time.FixedZone("UTC+8", 8*3600)
226
  }
227

228
  now := time.Now().In(loc)
229
  endAt = now.UnixMilli()
230

231
  switch rng {
232
  case "today":
233
    y, m, d := now.Date()
234
    start := time.Date(y, m, d, 0, 0, 0, 0, loc)
235
    startAt = start.UnixMilli()
236
  case "30d":
237
    startAt = now.AddDate(0, 0, -30).UnixMilli()
238
  case "7d":
239
    startAt = now.AddDate(0, 0, -7).UnixMilli()
240
  case "all":
241
    startAt = 0
242
  default:
243
    // 默认 7 天
244
    startAt = now.AddDate(0, 0, -7).UnixMilli()
245
  }
246
  return
247
}
248

249
func umamiGET(cfg RuntimeConfig, c *http.Client, tm *TokenManager, pathWithQuery string) ([]byte, int, error) {
250
  token, err := tm.Get(cfg, c)
251
  if err != nil {
252
    return nil, 0, err
253
  }
254

255
  req, err := http.NewRequest("GET", cfg.UmamiBaseURL+pathWithQuery, nil)
256
  if err != nil {
257
    return nil, 0, err
258
  }
259
  req.Header.Set("Authorization", "Bearer "+token)
260

261
  resp, err := c.Do(req)
262
  if err != nil {
263
    return nil, 0, err
264
  }
265
  defer resp.Body.Close()
266
  b, _ := io.ReadAll(resp.Body)
267

268
  // token 失效：自动刷新重试一次
269
  if resp.StatusCode == 401 {
270
    tm.Invalidate()
271
    token2, err := tm.Get(cfg, c)
272
    if err != nil {
273
      return nil, 0, err
274
    }
275
    req2, _ := http.NewRequest("GET", cfg.UmamiBaseURL+pathWithQuery, nil)
276
    req2.Header.Set("Authorization", "Bearer "+token2)
277
    resp2, err := c.Do(req2)
278
    if err != nil {
279
      return nil, 0, err
280
    }
281
    defer resp2.Body.Close()
282
    b2, _ := io.ReadAll(resp2.Body)
283
    return b2, resp2.StatusCode, nil
284
  }
285

286
  return b, resp.StatusCode, nil
287
}
288

289
func requireAPIKey(cfg RuntimeConfig, w http.ResponseWriter, r *http.Request) bool {
290
  if cfg.APIKey == "" {
291
    return true
292
  }
293
  if r.Header.Get("x-api-key") != cfg.APIKey {
294
    http.Error(w, "unauthorized", http.StatusUnauthorized)
295
    return false
296
  }
297
  return true
298
}
299

300
// ---------- main ----------
301

142 collapsed lines
302
func main() {
303
  configPath := flag.String("config", "./config.yaml", "path to config yaml")
304
  flag.Parse()
305

306
  cfg, err := loadConfig(*configPath)
307
  if err != nil {
308
    log.Fatal("load config failed: ", err)
309
  }
310

311
  httpClient := &http.Client{Timeout: 10 * time.Second}
312
  tm := &TokenManager{}
313
  cache := newTTLCache()
314

315
  mux := http.NewServeMux()
316

317
  // 1) stats（全站 or 单页）
318
  //
319
  // 全站：GET /api/analytics/stats?range=today|7d|30d|all
320
  // 单页：GET /api/analytics/stats?range=7d&path=/posts/xxx
321
  mux.HandleFunc("/api/analytics/stats", func(w http.ResponseWriter, r *http.Request) {
322
    if !requireAPIKey(cfg, w, r) {
323
      return
324
    }
325

326
    rng := r.URL.Query().Get("range")
327
    if rng == "" {
328
      rng = "7d"
329
    }
330

331
    // 用 path 语义更清晰（兼容你之前的 url 参数：如果你前端还在传 url，也照样能用）
332
    pagePath := r.URL.Query().Get("path")
333
    if pagePath == "" {
334
      pagePath = r.URL.Query().Get("url") // 兼容旧参数名
335
    }
336

337
    startAt, endAt := calcRangeMs(rng, cfg.Timezone)
338

339
    cacheKey := fmt.Sprintf("stats:%s:%d:%d:%s", rng, startAt, endAt, sha1Short(pagePath))
340
    if cfg.CacheTTL > 0 {
341
      if v, ok := cache.Get(cacheKey); ok {
342
        w.Header().Set("Content-Type", "application/json")
343
        w.Write(v)
344
        return
345
      }
346
    }
347

348
    // 组装 Umami 请求
349
    q := fmt.Sprintf("startAt=%d&endAt=%d&timezone=%s", startAt, endAt, neturl.QueryEscape(cfg.Timezone))
350
    if pagePath != "" {
351
      q += "&path=" + neturl.QueryEscape(pagePath)
352
    }
353

354
    upstreamPath := fmt.Sprintf("/api/websites/%s/stats?%s", cfg.WebsiteID, q)
355

356
    b, status, err := umamiGET(cfg, httpClient, tm, upstreamPath)
357
    if err != nil {
358
      http.Error(w, err.Error(), 502)
359
      return
360
    }
361

362
    w.Header().Set("Content-Type", "application/json")
363
    w.WriteHeader(status)
364
    w.Write(b)
365

366
    if status == 200 && cfg.CacheTTL > 0 {
367
      cache.Set(cacheKey, b, cfg.CacheTTL)
368
    }
369
  })
370

371
  // 2) active 在线人数
372
  // GET /api/analytics/active
373
  mux.HandleFunc("/api/analytics/active", func(w http.ResponseWriter, r *http.Request) {
374
    if !requireAPIKey(cfg, w, r) {
375
      return
376
    }
377

378
    cacheKey := "active"
379
    if cfg.CacheTTL > 0 {
380
      if v, ok := cache.Get(cacheKey); ok {
381
        w.Header().Set("Content-Type", "application/json")
382
        w.Write(v)
383
        return
384
      }
385
    }
386

387
    upstreamPath := fmt.Sprintf("/api/websites/%s/active", cfg.WebsiteID)
388
    b, status, err := umamiGET(cfg, httpClient, tm, upstreamPath)
389
    if err != nil {
390
      http.Error(w, err.Error(), 502)
391
      return
392
    }
393

394
    w.Header().Set("Content-Type", "application/json")
395
    w.WriteHeader(status)
396
    w.Write(b)
397

398
    if status == 200 && cfg.CacheTTL > 0 {
399
      cache.Set(cacheKey, b, cfg.CacheTTL)
400
    }
401
  })
402

403
  // 3) （可选）realtime 最近 30 分钟
404
  // GET /api/analytics/realtime
405
  mux.HandleFunc("/api/analytics/realtime", func(w http.ResponseWriter, r *http.Request) {
406
    if !requireAPIKey(cfg, w, r) {
407
      return
408
    }
409

410
    // realtime 适合更短缓存；这里复用 CacheTTL
411
    cacheKey := "realtime:" + clientIP(r)
412
    if cfg.CacheTTL > 0 {
413
      if v, ok := cache.Get(cacheKey); ok {
414
        w.Header().Set("Content-Type", "application/json")
415
        w.Write(v)
416
        return
417
      }
418
    }
419

420
    upstreamPath := fmt.Sprintf("/api/realtime/%s", cfg.WebsiteID)
421
    b, status, err := umamiGET(cfg, httpClient, tm, upstreamPath)
422
    if err != nil {
423
      http.Error(w, err.Error(), 502)
424
      return
425
    }
426

427
    w.Header().Set("Content-Type", "application/json")
428
    w.WriteHeader(status)
429
    w.Write(b)
430

431
    if status == 200 && cfg.CacheTTL > 0 {
432
      cache.Set(cacheKey, b, cfg.CacheTTL)
433
    }
434
  })
435

436
  // healthz
437
  mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
438
    w.Write([]byte("ok"))
439
  })
440

441
  log.Printf("analytics-api listen on %s\n", cfg.ListenAddr)
442
  log.Fatal(http.ListenAndServe(cfg.ListenAddr, mux))
443
}

运行方式#

安装依赖：

# 安装依赖
go mod tidy
# 如果网络环境有问题，可以设置 GOPROXY 来加速依赖下载
GOPROXY=https://goproxy.cn,direct GOSUMDB=sum.golang.google.cn go mod tidy

编译成二进制：

go build -o umami-analytics-api

创建 systemd 服务：

sudo nano /etc/systemd/system/umami-analytics-api.service

内容如下（根据实际路径改）：

1
[Unit]
2
Description=Umami Analytics API (Go)
3
After=network.target
4

5
[Service]
6
Type=simple
7
WorkingDirectory=/opt/umami-analytics-api
8
ExecStart=/opt/go/umami-analytics-api/umami-analytics-api -config /opt/go/umami-analytics-api/config.yaml
9
Restart=always
10
RestartSec=5
11
User=root
12

13
# 可选：限制资源
14
MemoryMax=200M
15
CPUQuota=50%
16

17
[Install]
18
WantedBy=multi-user.target

启动并设为开机自启：

sudo systemctl daemon-reload
sudo systemctl enable umami-analytics-api
sudo systemctl start umami-analytics-api
# 查看状态
sudo systemctl status umami-analytics-api

功能测试：

# 最近 7 天（默认）
curl -s "http://127.0.0.1:8080/api/analytics/stats" -H "x-api-key: change_me"
# 今天（today）
curl -s "http://127.0.0.1:8080/api/analytics/stats?range=today" -H "x-api-key: change_me"
# 最近 30 天
curl -s "http://127.0.0.1:8080/api/analytics/stats?range=30d" -H "x-api-key: change_me"
# 从建站至今（all）
curl -s "http://127.0.0.1:8080/api/analytics/stats?range=all" -H "x-api-key: change_me"
# 指定文章 path
curl -s "http://127.0.0.1:8080/api/analytics/stats?range=all&path=/xxx/xxx" -H "x-api-key: change_me"
# 当前在线人数
curl -s "http://127.0.0.1:8080/api/analytics/active" -H "x-api-key: change_me"

Nginx 配置#

# === Umami analytics proxy ===
location /api/analytics/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    # 防止 nginx 吞 querystring（关键）
    proxy_pass_request_headers on;

    # 可选：超时设置
    proxy_connect_timeout 5s;
    proxy_read_timeout 10s;

    # 可选：简单限流（建议）
    limit_req zone=analytics burst=10 nodelay;
}