umami

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Umami Analytics

Umami分析

Fetch traffic summaries and analytics data from an Umami instance.

从Umami实例中获取流量摘要和分析数据。

Configuration

配置

Set these environment variables before running:

Variable	Required	Description
`UMAMI_API_URL`	Yes	Base URL of your Umami instance (e.g. `https://cloud.umami.is` )
`UMAMI_API_KEY`	One of these	API key for Umami Cloud. Used as Bearer token directly.
`UMAMI_USERNAME`	One of these	Username for self-hosted login via `/api/auth/login` .
`UMAMI_PASSWORD`	With username	Password for self-hosted login.

UMAMI_API_KEY

is set, it takes precedence over username/password.

运行前请设置以下环境变量：

变量名	是否必填	说明
`UMAMI_API_URL`	是	你的Umami实例的基础URL（例如： `https://cloud.umami.is` ）
`UMAMI_API_KEY`	二选一	Umami Cloud的API密钥，直接用作Bearer令牌。
`UMAMI_USERNAME`	二选一	用于自托管登录的用户名，登录接口为 `/api/auth/login` 。
`UMAMI_PASSWORD`	随用户名	自托管登录的密码。

如果设置了

UMAMI_API_KEY

，它的优先级高于用户名/密码组合。

Workflow: Daily Traffic Summary

工作流：每日流量摘要

Run the script:

bash

bash ~/Projects/skills/umami/scripts/umami-summary.sh

Parse the JSON output.
Format as a markdown table:

Website	Domain	Pageviews	Visitors	Visits	Bounces	Avg Time	Active
My Blog	blog.example.com	1,234 (980)	567 (510)	890 (801)	123 (110)	45s (38s)	3
Totals		1,234 (980)	567 (510)	890 (801)	123 (110)	45s (38s)	3

Show previous period values in parentheses after each metric (e.g. "1,234 (980)" means 1,234 current, 980 previous).
Format numbers with commas for readability.
Convert
```
totaltime
```
to human-readable duration (e.g. "1m 23s").
Calculate average time as
```
totaltime / visits
```
for each site, using
```
prev_totaltime / prev_visits
```
for the previous period.
Bold the totals row.

运行脚本：

bash

bash ~/Projects/skills/umami/scripts/umami-summary.sh

解析JSON输出。
格式化为Markdown表格：

网站名称	域名	页面浏览量	访客数	访问次数	跳出数	平均时长	活跃用户
我的博客	blog.example.com	1,234 (980)	567 (510)	890 (801)	123 (110)	45s (38s)	3
总计		1,234 (980)	567 (510)	890 (801)	123 (110)	45s (38s)	3

每个指标后用括号显示上一周期的值（例如："1,234 (980)" 表示当前值为1,234，上一周期为980）。
数字添加千位分隔符以提升可读性。
将
```
totaltime
```
转换为易读的时长格式（例如："1m 23s"）。
每个网站的平均时长计算公式为
```
总时长 / 访问次数
```
，上一周期的平均时长使用
```
上一周期总时长 / 上一周期访问次数
```
计算。
总计行使用加粗格式。

Workflow: Active Users Only

工作流：仅获取活跃用户

For "who is on my site right now?" queries, use the lightweight flag:

bash

bash ~/Projects/skills/umami/scripts/umami-summary.sh --active-only

This skips the stats API calls and only fetches current active visitor counts. Format as a simpler table:

Website	Domain	Active
My Blog	blog.example.com	3

当用户询问“当前谁在访问我的网站？”时，使用轻量模式参数：

bash

bash ~/Projects/skills/umami/scripts/umami-summary.sh --active-only

此模式会跳过统计API调用，仅获取当前活跃访客数。格式化为更简洁的表格：

网站名称	域名	活跃用户
我的博客	blog.example.com	3

Error Handling

错误处理

The script exits non-zero and writes JSON to stderr on failure:

Missing env vars:
```
{"error": "UMAMI_API_URL is not set"}
```

Auth failure:

{"error": "Authentication failed (HTTP 401)"}

Unreachable server:

{"error": "Could not connect to https://..."}

Report these errors clearly to the user with the specific message. Suggest checking their environment variables.

脚本执行失败时会返回非零退出码，并将错误信息以JSON格式写入标准错误输出：

缺少环境变量：
```
{"error": "UMAMI_API_URL is not set"}
```

认证失败：

{"error": "Authentication failed (HTTP 401)"}

服务器无法访问：

{"error": "Could not connect to https://..."}

需向用户清晰报告这些错误及具体信息，并建议检查环境变量设置。

API Reference

API参考

For queries beyond the daily summary (time series, metrics breakdowns, custom date ranges), see references/api.md.

如需进行每日摘要之外的查询（如时间序列、指标细分、自定义日期范围），请查看references/api.md。