zt-dsc/docs/数据总线用户使用指南.md

数据总线（Databus）用户使用指南

适用范围：zt-module-databus-server（管理与运行时）、zt-module-databus-api（对外协议），面向已部署 ztcloud 后端 + zt-vue-element 前端的环境。文档区分 业务管理员 与 第三方开发者 两类读者，帮助您从零到一完成配置、发布与调用。

1. 角色视角与总体流程

角色	核心目标	关键系统入口
业务管理员	在后台可视化界面中定义/编排 API，配置凭证、限流、访问日志，并确保版本可控	后台路径：系统管理 → 数据总线（或直接访问 /#/databus）
第三方开发者	按照后台下发的 apiCode + version + appId，满足安全约束后调用统一网关，解析响应并接入自身系统	对外入口：{protocol}://{host}{basePath}/{apiCode}/{version}（默认 Base Path /admin-api/databus/api/portal）

完整流程示意：

1. 管理员初始化（执行 DM8 脚本、开通菜单与权限）。
2. 管理员在“API 定义”中建模（步骤、变换、策略、版本发布）。
3. 管理员为业务方创建凭证（ZT-App-Id、密钥、IP 白名单、匿名用户等）。
4. 第三方拿到凭证后发起调用（签名 → 加密 → 发送 → 解密响应）。
5. 管理员通过限流/日志功能持续运维，必要时回滚版本或刷新缓存。

2. 通用准备事项

2.1 服务与配置

• 运行中服务：zt-server 网关、zt-module-databus-* 相关微服务、Redis（用于 nonce、防重放、限流计数）。
• 关键配置（摘自 application.yml）：
  • databus.api-portal.base-path：默认 /admin-api/databus/api/portal，如需兼容旧系统可保留 /databus/api/portal 别名。
  • allowed-ips/denied-ips：无白名单时留空即放行全部；建议第三方出口 IP 全量登记。
  • security：signature-type（MD5/SHA256）、encryption-type（AES/DES）、nonce-ttl、allowed-clock-skew-seconds、是否强制请求/响应加密。
  • enable-tenant-header：如开启多租，会自动从 ZT-Tenant-Id（可自定义）透传。

2.2 数据库与菜单初始化（DM8）

场景	脚本（目录 sql/dm/）	说明
初始化菜单与按钮权限	统一外部网关菜单_20251010.sql	建立“数据总线”一级菜单及 API/凭证/策略/访问日志页面的所有操作权限，支持重复执行。
访问日志菜单补充	数据总线API访问日志菜单权限_20251028.sql	若已执行主菜单脚本仍找不到访问日志入口，可追加该脚本。
API 版本历史表	数据总线API版本历史表结构_备忘录模式_20251030.sql	DM8 兼容语法，包含索引与字段注释，确保支持版本快照/回滚。
访问日志表	数据总线API访问日志表结构_20251028.sql	记录追踪 ID、请求/响应、步骤结果等，供后台“访问日志”页面检索。
示例/演示数据	../mysql/databus_sample_data.sql（MySQL）	可作为建模参考，字段一致，迁移到 DM 时仅需替换数据类型即可。

执行顺序建议：先运行菜单脚本 → 赋予管理员角色对应按钮权限 → 执行表结构脚本 → 根据需要导入示例数据。

3. 业务管理员操作路线

3.1 角色与权限校验

1. 通过 DM8 脚本写入菜单/按钮后，将 数据总线 相关权限分配给目标角色（如 system_admin）。
2. 确认角色拥有以下最少权限：databus:gateway:*、databus:credential:*、databus:policy:*、databus:gateway:access-log:query。

3.2 创建 API 定义

进入 数据总线 → API 定义，按以下步骤操作：

1. 点击“新建”填写基础信息：API 编码 (apiCode)、版本 (version)、描述、HTTP Method、URI Pattern（运行期仅用于文档，可自由描述）。
2. 选择 认证策略 与 限流策略：默认策略可复用，也可在对应菜单先新建。
3. 选择 状态 = 草稿，避免未完成配置就被调度。

提示：Start/End 步骤系统会自动校验唯一性，必须至少存在一条 Start 与 End 步骤。

3.3 配置编排步骤与变换

1. 在 API 详情页新增步骤：
   • 类型：HTTP / RPC / Script / Start / End。
   • 目标地址：HTTP 需写 METHOD http://host/path，并按需填写 Header/Body 映射表达式。
   • 映射表达式：支持 JSON 表达式，常用写法示例同 databus_sample_data.sql 中 JSON::(...)。
   • 重试/超时：以 JSON 形式配置 maxAttempts、delayMs。
2. 配置步骤级或 API 级 Transform：
   • 场景示例：请求前补链路追踪 ID（REQUEST_PRE）、响应前组装统一结构（RESPONSE_PRE）。
   • 校验规则：同一 phase 仅允许一条记录。

3.4 版本与发布

1. 保存即可生成版本快照：系统会在 databus_api_version 中写入 JSON 快照并标记 is_current=1。
2. 调试：在 API 列表点击“调试”，通过 POST /databus/gateway/invoke 模拟真实请求，可自带 Header/Body。
3. 上线：修改 状态=ONLINE 后保存，系统自动刷新运行时 Flow。若需全量刷新，可在列表右上点击“刷新缓存”。
4. 回滚：在“版本历史”侧栏选择目标版本 → 点击“回滚”，系统将历史快照恢复为现有配置并重新发布。

3.5 凭证与策略运营

1. 客户端凭证：
   • 进入“客户端凭证” → 新建 → 生成 appId、密钥、签名/加密算法。
   • 可绑定匿名用户（后台会在调用时自动模拟该用户登录）。
   • 支持 IP 白名单、描述及状态维护。
2. 限流策略：
   • 在“限流策略”菜单中新增 FIXED_WINDOW 类型，配置 limit、windowSeconds、keyTemplate。
   • 常见做法：${apiCode}:${header.X-Client-Id}，以不同客户端维度做计数。

3.6 监控与排障

1. 访问日志：菜单路径“访问日志”，支持按 traceId / apiCode / 时间 检索详情，字段对应 databus_api_access_log。
2. 常见问题定位：
   • 401 → 校验凭证/签名/时间戳。
   • 429 → 限流策略触发，可在日志中观察 status=1/errorCode=API_RATE_LIMIT_EXCEEDED。
   • 5xx → 检查步骤 stepResults 中的 error 描述、Integration Flow 日志。

4. 第三方开发者操作路线

4.1 凭证申请

向业务管理员提供以下信息：调用系统名称、出口 IP 列表、是否需要匿名账号、预期调用 API 列表。管理员创建凭证后会得到：

• ZT-App-Id
• encryptionKey + encryptionType（AES/DES）
• signatureType（MD5/SHA256）
• 可选：匿名内部用户、租户 ID

4.2 网络与安全要求

• 请求必须来自允许的 IP，且使用 HTTPS（推荐）或可信的内网段。
• 时间戳与服务器偏差 ≤ allowed-clock-skew-seconds（默认 300 秒）。
• nonce 在 nonce-ttl-seconds 内不得重复（默认 600 秒，服务器使用 Redis 去重）。
• 若开启 require-body-encryption，请求体必须是 加密后再 Base64 编码 的字符串。

4.3 构建请求的 7 个步骤

步骤	动作	关键点
1	生成 timestamp	long 类型毫秒值；建议每次现取。
2	生成 nonce	≥8 位随机字符串，推荐 UUID 去掉 -。
3	准备明文 Body	JSON 文本，记为 plainBody。GET 请求仍建议传空 JSON {}，以便签名。
4	计算签名	将 appId、timestamp、nonce、plainBody（或 Query）按 key 排序拼接 key=value，使用约定算法得出 signature。
5	加密 Body	以凭证密钥对 plainBody 执行 AES/DES 加密，再 Base64（需与服务端配置一致）。
6	组装请求头	至少包含 ZT-App-Id、ZT-Timestamp、ZT-Nonce、ZT-Signature、Content-Type，可附带 ZT-Tenant-Id、X-Client-Id。
7	发送请求	URL = {basePath}/{apiCode}/{version}，HTTP 方法与后台配置一致；响应若被加密需反向解密。

请求示例（伪代码）

POST https://gw.example.com/admin-api/databus/api/portal/order.create/v1
Headers:
  ZT-App-Id: demo-app
  ZT-Timestamp: 1732070400000
  ZT-Nonce: 0c5e2df9a1
  ZT-Signature: 8e377...
  X-Client-Id: mall
Body (Base64)：Q2hhcnNldGV4dC1CYXNlNjQgZW5jcnlwdGVkIGJvZHk=

响应处理

1. 读取 HTTP 状态与 code/message/traceId 字段。
2. 若后台开启响应加密，需使用同一密钥解密得到真正的 response JSON。
3. 保留 traceId 以便与管理员对齐日志。

4.4 常见故障排查

症状	常见原因	自助检查
401 + 签名校验失败	拼接顺序错误 / 对象未序列化一致	确认按字典序拼接 key=value，body 使用明文。
401 + 请求到达时间超出	客户端时间漂移	同步 NTP，或在发送前刷新服务器时间。
401 + 重复请求	nonce 重复或被重放	确保每次生成唯一随机串。
403	IP/应用被禁用	让管理员检查凭证状态、白名单。
429	限流策略触发	调整并发或与管理员协商提升 limit。
5xx + 步骤执行失败	后端步骤调用异常	提供 traceId，管理员可在访问日志中查看 stepResults 详细报错。

5. 策略、监控与日志

5.1 限流与审计

• 策略以 JSON 存储在 databus_policy_rate_limit，字段：limit（次数）、windowSeconds（窗口秒）及可选 keyTemplate。
• 当前默认策略实现为 Redis 固定窗口：Key 格式 databus:api:rl:{apiCode}:{version}:{X-Client-Id}。
• 触发限流时返回 HTTP 429，日志中 status=1 且 errorCode=API_RATE_LIMIT_EXCEEDED。
• 如需关闭限流，管理员可在 application.yml 中设置 databus.api-portal.enable-rate-limit=false 或在 API 上解除策略绑定。
• 审计日志由 ApiGatewayAccessLogger 写入 databus_api_access_log，可结合 ELK/BI 做分析。

5.2 访问日志使用

1. 建表：执行 sql/dm/数据总线API访问日志表结构_20251028.sql（已含主键、索引、字段注释）。
2. 后台入口：数据总线 → 访问日志，需 databus:gateway:access-log:query 权限。
3. 常见字段解释：
   • REQUEST_*：存储原始请求；如启用请求加密，会记录解密后的明文。
   • STEP_RESULTS：JSON 数组，展示每个步骤的 elapsed、request/response、error，用于定位链路问题。
   • TRACE_ID：可与链路追踪或日志平台联动。
4. TODO：如目标环境尚未执行该表脚本，请尽快在 DM 数据库运行，以免访问日志页面无法查询。

6. 演示数据与调试建议

• 使用 sql/mysql/databus_sample_data.sql 可一次性生成：
  • 3 个示例 API（聚合查询 / 用户画像 / 快速登录）。
  • 对应的步骤、变换、限流策略、发布记录。
• 若目标环境为 DM，可参考该脚本结构，将 AUTO_INCREMENT 改为手动 ID、datetime 改 timestamp，即可导入。
• 通过示例数据，管理员可演练以下操作：
  1. 打开 API 列表验证导入内容；
  2. 使用“调试”通过管理端发起调用，确认步骤链路；
  3. 让第三方按照真实流程调用，观察访问日志、限流表现。

7. 附录：常用 REST 接口速查

模块	方法	路径	用途
API 定义	GET	/databus/gateway/definition/page	列表检索
	POST	/databus/gateway/definition	新建/更新 API（PUT 更新）
	DELETE	/databus/gateway/definition/{id}	删除并注销 Flow
API 版本	GET	/databus/gateway/version/list?apiId=	历史版本
	PUT	/databus/gateway/version/rollback	回滚
客户端凭证	POST	/databus/gateway/credential/create	创建凭证
限流策略	POST	/databus/gateway/policy/rate-limit	创建/更新策略
调试/刷新	POST	/databus/gateway/invoke	管理端调试
	POST	/databus/gateway/cache/refresh	全量刷新 Flow
日志	GET	/databus/gateway/access-log/page	查看访问日志

---

如仍有未覆盖的业务场景，可在 docs/数据总线模块大致功能与调用介绍.md 中查阅更底层的架构说明，再结合本文步骤完成落地。祝使用顺利！