MateClaw

中文

English

中文

English

Appearance

运营数据导出 ​

把一份跨域的运营数据报告一次性导出成 Excel(.xlsx 打包为 .zip),供运营、审计、对账离线使用。两种入口:Dashboard 一键导出(图形界面)和命令行导出(无 UI、可 docker exec)。

仅全局管理员可用。报告含全工作区的会话内容、Token 用量、审计记录等敏感数据。

报告包含的 9 张表 ​

#表内容
1概览汇总区间 KPI、系统快照、7 天趋势、周期对比、模型明细、Agent 活跃 Top 10
2Token 用量按天 × runtime_provider 拆分,含平均 Token/对话
3技能统计技能清单 + 调用次数、最近调用时间、绑定 Agent
4用户统计按(工作区, 用户)聚合的 Token、时长、最近活跃
5用户对话用户—助手消息配对的明细行
6安全与审计跨 6 个来源的统一视图(Guard 规则、审计日志、审批、授权、配置、业务审计事件)
7渠道统计每渠道的对话数、Token、去重用户
8模型配置已启用 + 已配置 API Key 的模型及参数
9定时任务执行记录,含时长与 Token 用量

入口一:Dashboard 一键导出 ​

  1. 进入仪表盘,右上角(数据库标签旁)点「导出运营数据」(仅全局管理员可见)。
  2. 在弹窗里选时间范围——可点快捷「近 7 / 30 / 90 天」,或自定义;最长 90 天,不可选未来日期。
  3. 点「生成报告」——圆形进度环显示 9 步进度(概览 → … → 定时任务)。
  4. 完成后出现「报告已就绪」,点「下载」拿到 ops_data_<起>_<止>.zip。

关于安全与生命周期:

  • 生成 / 进度 / 下载三个端点都由 @RequireGlobalAdmin 鉴权——非管理员调用返回 403。
  • 一次只允许一个生成任务(并发返回 409 忙碌),前端 5 分钟死线。
  • 下载用一次性令牌,原子单次有效——同一令牌第二次下载返回 410。
  • 生成文件在 24 小时后或下载后自动清理。

入口二:命令行导出 ​

适合「大范围、无超时、脚本化、docker exec」的场景。新增了项目级 CLI 框架,导出命令为 --cli.command=export:

bash
# 本地 jar
java -jar app.jar --cli.command=export \
  --cli.start=2026-01-01 --cli.end=2026-06-30 > report.zip

# 容器内
docker exec <容器名> java -jar /app/app.jar --cli.command=export \
  --cli.start=2026-01-01 --cli.end=2026-06-30 > report.zip

# 模拟运行(不实际生成)
java -jar app.jar --cli.command=export --cli.start=... --cli.end=... --cli.dry-run

# 查看所有命令
java -jar app.jar --cli.command=help
参数必填说明
--cli.command=export是执行导出命令
--cli.start=YYYY-MM-DD是开始日期(含)
--cli.end=YYYY-MM-DD是结束日期(含)
--cli.dry-run否模拟运行,不实际生成

要点:

  • ZIP 字节直接写入 stdout(用 > report.zip 重定向),诊断信息走 stderr,所以重定向得到的是干净的二进制。
  • 后端入口无 90 天上限、无超时,适合大范围离线导出。
  • CLI 仅运维侧可达(本地 / docker exec),不经 HTTP、不绕过管理员鉴权。
  • 正常 web 启动(没有 --cli.command)时 CLI 保持静默,不影响服务启动。

备注 ​

  • Excel 中 19 位雪花 ID 以文本写出,避免被 Excel 数值精度(2^53)截断、显示成科学计数法。
  • 报告内容随数据增长而变大;命令行导出大范围时建议直接重定向到文件而非管道给其它程序。

关联 ​