网站流量数据洞察专家

基于Umami官方API的只读数据分析工具，通过环境变量安全配置，支持云版与自托管双模式，为运营决策提供实时流量、事件追踪与归因分析能力。

基本信息

• 技能名称?umami-stats
• 中文名称?网站流量数据洞察专家
• 作者?hfichter
• 分类?专业技能
• 版本?v1.0.0
• 标签?data-analytics, api, productivity, operations, content-media, backend

使用方法

使用说明
Umami Stats 是一款专为网站数据分析设计的只读API技能，旨在帮助用户安全、高效地获取Umami Cloud或自托管实例中的流量统计、页面访问、事件追踪及会话数据。作为数据访问层的轻量化实现，该技能通过Python标准库构建，无需额外依赖，即可实现与Umami v2 API的无缝对接。
核心用法
该技能采用环境变量驱动的配置模式，用户需设置 UMAMI_API_KEY 作为身份凭证，可选配置 UMAMI_BASE_URL 、 UMAMI_WEBSITE_ID 及部署模式（cloud/self-hosted）。通过 scripts/umami_query.py 脚本，用户可灵活调用各类只读端点，如获取网站列表、统计数据、页面浏览量、事件序列及归因报告。脚本内置时间预设（today、last7d、last30d等）和自定义时间戳功能，支持路径自动映射（云版 /v1/ 与自托管 /api/ 的智能转换），极大简化了跨平台使用的复杂度。
显著优点
安全性设计突出 ：仅执行GET只读操作，从根本上杜绝了数据误删或篡改风险；API密钥通过环境变量管理，避免硬编码泄露。 零依赖架构 ：仅使用Python标准库（urllib、argparse、json等），消除了外部供应链攻击面，部署极其轻量。 双模式兼容 ：无论是Umami Cloud用户还是自托管用户，均可通过 --deployment 参数无缝切换，自动适配不同的认证头（Cloud使用 x-umami-api-key ，自托管使用 Authorization: Bearer ）。 查询灵活性高 ：支持参数化查询、自动默认值填充（如metrics端点自动补充type=url），以及完善的错误处理和超时机制（默认30秒）。
局限性与约束
作为只读工具，该技能无法执行任何数据修改操作（如创建网站、更新设置或删除记录），仅适用于数据分析和监控场景。此外，其来源为T3级社区项目（openclaw/skills），虽代码质量通过A级安全认证，但非Umami官方维护，长期更新与兼容性保障需依赖社区贡献。用户还需自行准备有效的Umami API密钥，对于无技术背景的用户存在一定配置门槛。
目标用户群体
该技能特别适合 网站运营人员 进行日常流量监控和趋势分析， 产品经理 验证功能使用情况和用户行为路径， 数据分析师 获取原始JSON数据进行深度加工，以及 开发者 在CI/CD流程中集成网站健康检查。对于需要定期生成营销效果报告、A/B测试数据支持或实时监控大屏数据的团队，此工具提供了可靠的自动化数据获取能力。
使用风险与注意事项
尽管安全评级为A级，用户仍需注意： API密钥管理 是关键风险点，应确保环境变量不被意外提交到版本控制，并在团队成员间安全共享； 网络依赖性 方面，脚本执行受限于Umami服务可用性和网络状况，虽有过期机制但仍可能因服务端问题导致查询失败； 数据隐私 上，虽然脚本本身不收集用户数据，但查询结果可能包含敏感的业务指标，需妥善处理返回的JSON数据； 权限范围 上，Umami Cloud的普通用户API密钥可能无法访问 /v1/users/* 端点（返回403），这属于预期的权限限制，非技能缺陷。建议在正式环境使用前，先在测试环境验证API密钥权限和查询参数的正确性。
data-analytics api productivity operations content-media backend