Files
tdc-rs/README.md
T
xstudio 885b108fe0 init: TDC 连接器 Rust MVP(pglite-rs 内嵌 + 静态 HTML 控制台)
从 ssw-mvp/boot/ssw-tdc(Spring Boot/JNPF,37 Controller)剥离重底座的本地优先实现:
- axum 单进程承担控制面/数据面/静态托管/TDC→TDS HTTP 契约网关
- pglite-rs 0.2 内嵌原生 PostgreSQL(进程内,非浏览器 WASM),19 张 tdc_* 表
- 静态 HTML + 原生 JS 控制台:schema 自省驱动 CRUD + 按表生命周期动作
- 红线:TDC↔TDS 只走 HTTP 契约,未配 SSW_TDS_BASE_URL 时 Noop 降级
- AGENTS.md 记录架构红线、命令速查与踩坑清单;docs/ 记录跨方契约细节
2026-10-24 10:31:06 +08:00

152 lines
8.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# TDC 数据接入连接器 · Rust + 静态 HTML + PGlite(MVP)
把 `ssw-mvp/boot/ssw-tdc`(Spring Boot / JNPF 重底座的「数据接入连接器」子系统)重做成
**本地优先、零外部服务**的 MVP:
- **Rust (axum)** —— 控制面 + 数据面 + 静态托管 + TDC→TDS 的 HTTP 契约网关
- **静态 HTML + 原生 JS** —— 操作员控制台(零构建,经 HTTP API 读写数据库)
- **PGlite(pglite-rs,进程内原生 PostgreSQL)** —— 内嵌在 Rust 进程里,承载全部 `tdc_*` 业务数据,
数据落在 `data/tdc.pg/`(磁盘持久化,非浏览器 WASM/IndexedDB)
> 关键点:PGlite 用的是 **pglite-rs**(`crate pglite-rs`,import 为 `pglite`)——
> 把 postgres-pglite 编译成原生静态库、链接进二进制,是**真实 PostgreSQL 语义**
> (类型 / MVCC / 事务 / 扩展 / 线协议),进程内单 backend 运行,无服务器、无 Docker。
> 前端控制台只发 REST 请求,不直接持有数据库。
> 红线:原 TDC 与 TDS **只走 HTTP 契约、不编译期耦合**;本实现用 `/api/ssw/tdc/tds/*`
> 代理网关还原该解耦,未配 `SSW_TDS_BASE_URL` 时走 **Noop 降级**(对应原 `NoopTdcTdsClient`)。
## 接入真实 TDS(跨方契约调试)
连接器与 TDS 的契约严格对齐原 `TdcTdsClient`(`HttpTdcTdsClient`)。**真实 TDS 的鉴权/契约细节**:
- **读概览 / 审计 / 留痕** `.../Bridge/**`:需请求头 **`App-Code: tdc`**(`TdsBridgeInternalController`
白名单只放行 `tdc`)。`X-Internal-Token` 仅在 `tds.internal-secret` 非空时校验(默认空=免 token)。
代理对 `Bridge/**` 自动注入 `App-Code`,并跳过客户端自带的该头以避免重复。
- **真实 TDS 用 HTTP 200 + body `code` 表达业务错误**(如 `code:600` 登录过期);连接器据此判定成败,不再只看 HTTP 状态。
- **注册** `POST .../Connector/Register`:**真实 TDS 并无此端点**(连接器由运营方 CRUD 侧建档)。
连接器如实返回 `registerStatus: UNSUPPORTED_BY_TDS`,不伪造成功。
- 其余:`POST {base}/api/ssw/tds/Bridge/{AuditChain,ChainEvidence,AuditRecord,AuditTrail}`、
`POST {base}/api/ssw/tds/NodeReport`。
### 启动真实 TDS(`ssw-mvp/boot/ssw-admin`,JNPF 底座)
TDS 不是独立服务,而是 `ssw-admin` 的**角色 profile**:`--spring.profiles.active=dev,full`
同时装载 TDS + TDC + SSWFLOW。依赖本机已有的 `jnpf-postgres`(15432) / `jnpf-redis`(16379) 容器
与 `j7 / tdc / tds / sswflow` 四库(PostgreSQL,均已在运行)。
```bash
# 1) 打包:full 是默认 profile,但用 -pl 时必须显式 -P full 才会把 ssw-tds 打进 fat jar
mvn -f boot/pom.xml -P full -pl ssw-admin -am package -DskipTests
# 2) 运行:端口避开连接器的 30000;中和 fisco / k8s / kbs 等本机未启的外部依赖
DB_HOST=127.0.0.1 DB_PORT=15432 REDIS_HOST=127.0.0.1 REDIS_PORT=16379 \
java -Xmx2g -jar boot/ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar \
--spring.profiles.active=dev,full --server.port=30040 \
--fisco.enabled=false --k8s.enabled=false --kbs.url= \
--ssw.security-plane.base-url=http://127.0.0.1:1
```
启动约 30s(`Started SswAdminApplication`);`Tomcat started on port 30040`。跨方算力(30011)、
scard 安全平面(8443) 等未启只报非致命告警,不影响 TDS 主链路。
### 连接器指向真实 TDS
```bash
SSW_TDS_BASE_URL=http://127.0.0.1:30040 PORT=30000 ./target/debug/tdc-connector
```
实测:`/api/ssw/tdc/tds/Bridge/Contract/{id}` 经连接器返回真实合约(如 `CT-CRT-yxkcm`);
`Bridge/Connector/{id}` 返回真实连接器(如「吉利汽车 TEE 连接器 / ONLINE」)——数据与 `tds` 库一致。
**本地 TDS 桩(无 TDS 时的降级对端):** `tds-stub/server.js` 零依赖实现上述契约:
```bash
cd tds-stub && node server.js # 监听 :30100
# SSW_TDS_BASE_URL=http://127.0.0.1:30100 SSW_TDS_TOKEN=internal-test-token PORT=30000 ./target/debug/tdc-connector
```
## 运行
```bash
cd tdc-rs
cargo build # 编译(自动走 sccache + 统一 registry 缓存)
PORT=30000 ./target/debug/tdc-connector
# 浏览器打开 http://localhost:30000
```
- 启动即初始化:Rust 进程内 `PGlite::open(data/tdc.pg)`,若 `tdc_identity` 不存在则执行
内嵌的 `migrate.sql`(`include_str!` 进二进制,19 张表 + 6 条内置脱敏规则 + 默认开发环境空间)。
- 侧边栏「生成身份」→ Rust 用 ed25519 本地签发连接器身份(私钥仅落盘 `data/node-identity.json`,API 不回传)。
- 数据全部落在 Rust 进程内嵌库;控制台通过 `/api/db/*` 读写。
## 编译缓存(按 dev-cache-layout 规范)
本机已统一:`~/.cargo/registry` → `~/.cache/cargo/registry`(软链),
sccache 0.18 经 `~/.cargo/config.toml` 的 `[build] rustc-wrapper` + `[env] SCCACHE_DIR`
启用,缓存实体在 `~/.cache/sccache`(经 `~/Library/Caches/Mozilla.sccache` 软链透明访问)。
`cargo build` 直接命中,无需额外操作。`pglite-rs` 为预编译原生库,依赖编译结果一并入缓存。
## 后端 API
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/health` | 健康检查(含 DB 模式) |
| GET | `/api/db/tables` | 列出 public 下所有表 |
| GET | `/api/db/table/{name}/columns` | 某表列信息(表名白名单校验,防注入) |
| GET | `/api/db/table/{name}/rows?limit=` | 某表行(`SELECT * LIMIT n`,不假定 `f_delete_mark` 列,默认 200 / 上限 1000) |
| POST | `/api/db/query` | 只读查询;任意 SELECT 用 `row_to_json(q)::text` 包成标准 JSON 数组返回 |
| POST | `/api/db/exec` | 写操作(INSERT/UPDATE/DELETE/DDL),原样 exec |
| GET/POST | `/api/ssw/tdc/node/identity` | 连接器身份(生成/读取,ed25519 软 PKI) |
| POST | `/api/ssw/tdc/node/identity/register` | 向 TDS 注册;真实 TDS 无 `/Connector/Register` 则如实返回 `UNSUPPORTED_BY_TDS`;Noop 模式本地置 APPROVED |
| POST | `/api/ssw/tdc/node/identity/heartbeat` | 心跳(置 ONLINE;配 base-url 时一并上报 TDS `NodeReport`) |
| ANY | `/api/ssw/tdc/tds/{*path}` | TDC→TDS 契约代理(剥离逐跳头 + `Bridge/**` 注入 `App-Code: tdc` + 可选 `X-Internal-Token`;无 base-url 时 501 Noop) |
> 查询结果统一用 `SELECT row_to_json(q)::text AS _row FROM (<sql>) q` 包裹,
> 后端 `get::<Option<String>>` 取文本后再 `serde_json::from_str`,**规避逐列类型映射**且得到标准 JSON。
> 内嵌库为单 in-process backend,所有 DB 访问由 `tokio::Mutex` 串行化。
## 已实现范围
**19 张表**(忠实移植原 `tdc_*` schema,含 9 系统列 / 逻辑删除 / partial 唯一索引):
身份、数据源、资源、资源字段、脱敏规则、产品、需求、订单、合约、使用控制策略、
策略校验记录、API 交付服务、交付任务、交付日志、TDS 同步日志、审计日志、环境空间、成员、机密文件。
**控制台能力**(schema 自省驱动的通用 CRUD + 按表生命周期操作):
- 通用:新建 / 编辑 / 逻辑删除 / 搜索(所有表)
- 数据源:测试连接、同步资源
- 资源:启用 / 停用
- 产品:发布 / 下架 / 提交审核
- 需求:发布 / 关闭
- 订单:通过 / 驳回 / 签署
- 合约:生效 / 终止
- 交付任务:策略校验(写 `tdc_policy_check_log`)/ 完成 / 取消 / 销毁(留证写 `tdc_delivery_log`)
- 身份(Rust 侧):生成 / 注册 / 心跳
## 明确不在 MVP 内(原 `ssw-tdc` 的隐私计算作业)
原 `NaxJob / Nax2PJob / TeeJob / Sandbox / Privacy / AnnotationTask / Notebook / VizChart /
Quality* / HostingJob` 等控制器依赖 **Nax 隐私计算引擎**与 **scard 安全平面(软 PKI + 软 TPM)**,
未纳入本次重做。若需这部分,应保留原 Java/Scala 服务,或将其作为独立后端通过 HTTP 契约接入本连接器。
## 目录
```
tdc-rs/
├── AGENTS.md # 给 AI 编码代理的项目约定(架构/红线/命令/踩坑)
├── Cargo.toml # 含 pglite-rs = "0.2"
├── src/main.rs # axum:内嵌 PGlite + 静态托管 + 身份 + TDS 代理 + /api/db/*
├── static/
│ ├── index.html # SPA 外壳(纯前端,无 import map)
│ ├── app.js # 调 /api/db/* 的通用 CRUD + 生命周期
│ ├── style.css
│ └── migrate.sql # tdc_* schema(编译期内嵌进二进制)
├── docs/
│ └── TDC-TDS-CONTRACT.md # TDC↔TDS 跨方契约参考(对齐原 HttpTdcTdsClient)
├── tds-stub/
│ └── server.js # 本地 TDS 契约桩(零依赖,仅供端到端调试)
└── data/ # 运行期:tdc.pg/(内嵌 PG 数据)+ node-identity.json(含私钥,已 gitignore)
```