数据源接入

数据源定义了报表中心「从哪里取数」。所有数据源在「报表中心 → 数据源」（/report/datasources）维护，可被多个数据集复用。

支持的数据源类型

类型	说明	取数方式
内置只读主库（sql）	应用自身的 PostgreSQL 主库，开箱即用，无需任何连接配置	只读事务执行 SQL
API（api）	远程 HTTP 接口返回的 JSON 数组	走统一 HTTP 客户端（防 SSRF），按数组路径提取
MySQL	外部 MySQL 数据库	只读连接池 + 行上限 + 语句超时
PostgreSQL	外部 PostgreSQL 数据库	只读连接（连接级 statement_timeout + read_only）
SQL Server	外部 Microsoft SQL Server	只读连接池 + 自动包装 OFFSET … FETCH NEXT 行上限
静态数据（static）	内置容器，承载粘贴的 JSON 或上传的 Excel/CSV	直接读取内联数据

内置「内置主库」「静态数据」两个数据源由系统预置，可直接使用。

新建内置库 / SQL 数据源

内置主库无需连接信息，选择类型「SQL（内置只读主库）」即可保存。SQL 语句在数据集中编写，而非数据源。这是最快的上手方式 —— 直接查询应用自身的业务表（用户、菜单、订单等）。

新建外部数据库（MySQL / PostgreSQL / SQL Server）

1. 点击「新增」，类型选择对应外部库。

2. 填写连接信息：

   字段	说明
   host	数据库主机地址
   port	端口（默认 MySQL 3306 / PostgreSQL 5432 / SQL Server 1433）
   database	库名
   user	账号
   password	密码（AES‑256‑GCM 加密存储；列表/详情不返回明文，仅返回 hasPassword 标记，password 为 null）
   SSL	是否启用 SSL 连接

3. 点击「测试连接」验证连通性（返回延迟毫秒数）。

4. 保存。编辑时密码留空表示不修改、沿用原密码。

安全说明

外部库取数强制只读：仅允许 SELECT / WITH 查询，自动包裹行数上限（默认 5000），并设置语句超时（15s）。PostgreSQL 在连接级设置 statement_timeout 与只读事务；MySQL / SQL Server 通过只读 SQL 规范化与分页包装限制结果。连接按 类型+主机+库+账号 缓存复用，连接池最大 3 个连接，空闲约 5 分钟回收。

报表出站连接默认拒绝 localhost、私网、链路本地、云元数据和保留地址，且不自动跟随 HTTP 重定向。确需连接可信内网 API 或数据库时，由运维通过 REPORT_OUTBOUND_PRIVATE_ALLOWLIST 显式配置主机名、IP 或 CIDR 白名单。

新建 API 数据源

1. 类型选「API（远程 HTTP）」。
2. 填写：
   • URL：以 http:// 或 https:// 开头。
   • 方法：GET / POST。
   • 请求头：选填 JSON 键值，如 { "Authorization": "Bearer xxx" }。
3. 保存。具体「数组路径」「附加参数」在数据集中配置。

密钥保护

请求头中的敏感字段（Authorization、Cookie、X-Api-Key、Token 等）会被加密存储，读取时脱敏为 ******，仅在实际取数时解密发送。编辑时保留 ****** 即沿用原值。

静态数据 / 文件数据源

类型「静态数据」是一个容器，本身无连接配置。真正的数据在数据集里维护：

• 直接粘贴一段 JSON 数组，或
• 上传 Excel（.xlsx）/ CSV 文件，系统解析为表格。

.xls 旧格式当前不支持，请先另存为 .xlsx 或导出为 .csv 后再上传。适合无数据库的临时报表、外部导出数据的快速可视化。详见 数据集与数据加工。

健康检查

• 单个测试并留痕：行操作「测试」（POST /api/report/datasources/{id}/test）对已保存的数据源执行连通性测试，并把结果持久化到 lastTestStatus（success / failed / unknown）、lastTestAt、lastTestLatencyMs、lastTestError 与连续失败次数，列表集中展示健康状态、延迟和错误摘要。API 数据源单测会按配置发起一次 GET/POST 请求。
• 批量健康检查：多选后点「健康检查」（POST /api/report/datasources/health-check）提交异步任务 report-datasource-health-check 到任务中心，逐个测试所选数据源并更新健康字段；API 类型数据源会跳过（避免对远程接口产生副作用）。任务进度、逐项结果与失败明细在任务中心查看，支持取消，按数据源集合与更新时间幂等防重复提交。

复制与批量操作

• 复制数据源（POST /api/report/datasources/{id}/clone）：克隆连接配置生成新数据源（含加密凭据），名称自动加「副本」后缀（可指定新名称），健康状态重置为 unknown。
• 批量启停（PUT /api/report/datasources/batch-status）：多选后一键启用 / 停用。

状态与删除

• 每个数据源可「启用 / 停用」。停用后不可用于新的取数。
• 被数据集引用的数据源无法删除，需先删除或改绑相关数据集。
• 多租户模式下，报表数据源按租户隔离；内置主库仅平台超级管理员可用。
• 行操作「权限与转移」可直达资源治理管理该数据源的 ACL 与所有权。

权限

操作	权限码
查看	report:datasource:list
新增 / 保存前测试连接 / 复制	report:datasource:create
编辑 / 批量启停 / 单测留痕 / 批量健康检查	report:datasource:update
删除	report:datasource:delete