203 lines
12 KiB
Markdown
203 lines
12 KiB
Markdown
# 数据总线（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 方法与后台配置一致；响应若被加密需反向解密。 |
|
||
|
||
#### 请求示例（伪代码）
|
||
|
||
```text
|
||
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` 中查阅更底层的架构说明，再结合本文步骤完成落地。祝使用顺利！
|