# 运营数据导出

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

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

## 报告包含的 9 张表

| # | 表 | 内容 |
|---|---|---|
| 1 | 概览汇总 | 区间 KPI、系统快照、7 天趋势、周期对比、模型明细、Agent 活跃 Top 10 |
| 2 | Token 用量 | 按天 × `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)截断、显示成科学计数法。
- 报告内容随数据增长而变大;命令行导出大范围时建议直接重定向到文件而非管道给其它程序。

## 关联

- [Backstage 运行时控制台](./backstage) —— 看实时运行的 Agent / 子 Agent
- [安全与审批](./security) —— Tool Guard 与审计日志(Sheet 6 的来源之一)