- boot/ (Java/Maven, JNPF 7.0) — 移除旧的 boot/.git,源码直接纳入仓库
- web/ (Vue 3 + Vite + Ant Design Vue, pnpm)
- docs/, scard/, nax/
- refs/INDEX.md + refs/国标/(其余 refs/* 开源子仓库不纳入)
- 已忽略: connector_data/, jweb/, log/, web/{dist,node_modules,.pnpm}, boot/*/target/, .DS_Store, .idea, .vscode
202 lines
13 KiB
Markdown
202 lines
13 KiB
Markdown
# 尚数网可信数据空间 — 工程总览
|
||
|
||
> 与 `docs/README.md`(文档索引)互补:本文件是**工程视角**的自包含总览,可随目录整体移动。
|
||
> 当前基线:架构升级 + 骨架可跑通(核心域 CRUD 跑通),2026-08-02 收尾验证完成;
|
||
> **2026-08-03 Nax 引擎接入**:`mpc` 算子从模拟切到真实 Nax 计算(详见 `docs/sswflow/NAX_ENGINE.md`);
|
||
> **2026-08-04 安全平面(scard)**:软 PKI 根证书 + 安全启动 PCR 度量 + 远程证明(enroll-nonce→quote→verify)闭环完成,并在 OrbStack Ubuntu 虚机内跨网络端到端跑通(详见 `docs/security/SECURITY_PLANE.md`);
|
||
> **2026-08-04 安全平面 → TDS 集成**:V1.3.2 DB 迁移(`tds_security_device` / `tds_attest_record` + `tds_connector` +4 列)+ Java 桥接(`SecurityPlaneClient` + `SyncService` `@Scheduled` 30s cron + `SecurityDevice/AuditController`)+ 前端 `/tds/security`,scard 管理面镜像至 SSWFlow 管理平面,撤销流程双向贯通。
|
||
|
||
## 1. 项目定位
|
||
|
||
在 SSWFlow 隐私计算流程编排平台基础上,升级为「尚数网可信数据空间」——对标国标的三大子系统:
|
||
|
||
| 代号 | 全称 | 定位 | 业务库 | API 前缀 |
|
||
| --- | --- | --- | --- | --- |
|
||
| **TDS** | 可信数据空间管理服务平台 | 空间运营方:空间/连接器/目录/合约/使用控制/审计 | `tds` | `/api/ssw/tds` |
|
||
| **TDC** | 数据接入连接器 | 数据提供/使用方:本地资源/产品封装/合约履行/交付 | `tdc` | `/api/ssw/tdc` |
|
||
| **SSWFLOW** | 隐私计算流程编排 | 密态计算引擎编排层 | `sswflow` | `/api/ssw/sswflow` |
|
||
|
||
需求基线:`docs/功能清单.md`(A)与 `docs/附件1:技术协议_可信数据空间_0512.docx`(B)必须全部实现。
|
||
|
||
## 2. 目录结构
|
||
|
||
```
|
||
ssw/
|
||
├── boot/ # 后端 Spring Boot 工程(ssw-admin 为运行入口)
|
||
│ ├── ssw-admin/ # - main + 启动配置 + yml
|
||
│ ├── ssw-tds/ # - TDS 子系统(entity/biz/controller,@DS("tds"))
|
||
│ ├── ssw-tdc/ # - TDC 子系统(@DS("tdc"))
|
||
│ ├── ssw-sswflow-{entity|biz|controller}/ # - 既有 SSWFlow(含 Nax 引擎 V0.13)
|
||
│ │ └── ssw-sswflow-biz/src/main/resources/nax/nax_adapter.py # ← Nax 进程适配器
|
||
│ └── db/ # 手动迁移 SQL(V1.0.0、V1.0.2、V1.0.3)
|
||
├── web/ # 前端 Vite + Vue3 + TS(独立 dev server 5173)
|
||
│ ├── src/api/ssw/{tds,tdc,sswflow}.ts
|
||
│ ├── src/views/ssw/{tds,tdc,sswflow}/ # 三个子系统视图页
|
||
│ ├── src/components/ssw/common/CrudPage.vue # 通用 CRUD 骨架
|
||
│ ├── src/router/modules/{tds,tdc,sswflow}.ts
|
||
├── scard/ # 安全平面(security-connector,Go):根密钥/安全启动/远程证明/隧道/国密;软实现与端到端跑通见 docs/security/SECURITY_PLANE.md
|
||
├── docs/ # 文档中心(README.md 为索引)
|
||
│ ├── arch/{ARCHITECTURE,REQUIREMENT_MATRIX,MIGRATION}.md
|
||
│ ├── tds/{REQUIREMENTS,DOMAIN_MODEL}.md
|
||
│ ├── tdc/{REQUIREMENTS,DOMAIN_MODEL}.md
|
||
│ ├── sswflow/{PROJECT,NAX_ENGINE}.md # NAX_ENGINE = V0.13 真实隐私计算执行层
|
||
│ ├── security/SECURITY_PLANE.md # 安全平面(scard):根密钥/安全启动/远程证明/隧道/国密,软实现与端到端跑通
|
||
│ ├── JNPF_BACKEND_GUIDE.md # 后端编码规范(JNPF 7.0 框架约定)
|
||
│ └── VERIFICATION_2026-08-02.md # 端到端验证报告
|
||
├── refs/ # 国标/参考实现(不动)
|
||
└── .claude/ # Claude Code 项目配置(memory/ 为软链)
|
||
└── .workbuddy/memory/ # 项目记忆(MEMORY.md 长期 + 每日 YYYY-MM-DD.md;通过 .claude/memory 软链访问)
|
||
```
|
||
|
||
## 3. 环境依赖
|
||
|
||
| 组件 | 版本 / 配置 |
|
||
| --- | --- |
|
||
| JDK | Java 21(编译 source/target=17) |
|
||
| Node | 22.22.2(managed)+ pnpm 10.12.1 |
|
||
| PostgreSQL | OrbStack 容器 `jnpf-postgres`(192.168.97.3:5432,user=dacli,pwd=dacli123) |
|
||
| Redis | OrbStack 容器 `jnpf-redis`(192.168.97.2) |
|
||
| 三业务库 | `sswflow` / `tds` / `tdc`(同 PostgreSQL 实例,各自独立 schema 隔离) |
|
||
| 加密 | `crypto-js`(前端)+ Java Sa-Token(后端鉴权) |
|
||
|
||
⚠️ Netty DNS 不走系统解析,`.orb.local` 不通,**一律用容器 IP**。宿主机 host 网络时改 `localhost`。
|
||
|
||
## 4. 启动命令
|
||
|
||
### 后端
|
||
```bash
|
||
cd boot && \
|
||
java -DDB_HOST=192.168.97.3 \
|
||
-DREDIS_HOST=192.168.97.2 \
|
||
-Dserver.port=30000 \
|
||
-jar ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar
|
||
```
|
||
- 必须 `-Dserver.port=30000`(`-Dspring.profiles.active=dev` 实测不生效)
|
||
- 后端编译:`mvn -pl ssw-admin -am package -DskipTests`
|
||
- 手动迁移 SQL:`boot/db/V*.sql`,用 `psycopg2` 或 `psql` 跑;先剥离 `--` 注释再按 `;` 切分
|
||
|
||
### 前端
|
||
```bash
|
||
cd web && pnpm dev # → http://localhost:5173
|
||
# vite.config.ts proxy: /api → http://localhost:30000
|
||
```
|
||
- 类型检查:`pnpm exec vue-tsc --noEmit`
|
||
- 生产构建:`pnpm build`(tds/tdc/sswflow 独立分包 + vendor)
|
||
|
||
⚠️ dev server 启动**用 `run_in_background`**,别用 `nohup ... &` 双重后台——进程会被回收,5173 不在监听会导致看似代理故障(实则 dev server 已死)。
|
||
|
||
## 5. 鉴权关键约定(必记)
|
||
|
||
- **密码加密**:`AES-256-ECB-PKCS7`,`key = md5(CIPHER_KEY)` 32字节 UTF8,`明文 = md5(plain)` 字符串,输出 `ciphertext.toString(Hex)`
|
||
- `CIPHER_KEY = EY8WePvjM5GGwQzn`(同 JNPF web `VITE_CIPHER_KEY`)
|
||
- **登录端点:`POST /api/oauth/Login`**,`Content-Type: application/x-www-form-urlencoded`,body `account=admin&password=<加密>&grant_type=password`
|
||
- 不是 `/api/ssw/login`
|
||
- 发 JSON 或漏 `grant_type` → 400「不支持此登录方式」
|
||
- token:登录返回 `data.token="bearer eyJ..."`,前端原样存 `localStorage`,请求头 `Authorization: <token>`
|
||
- Sa-Token `getTokenPrefix="bearer"` 只剥离**小写**前缀;大写 `Bearer` → 600 登录过期
|
||
- 必带头:`App-Code: sswflow` / `Jnpf-Origin: pc` / `Vue-Version: 3`
|
||
|
||
## 6. DB 关键约定
|
||
|
||
- ⚠️ 所有表在 **`public` schema**(DSN `currentSchema=public`),不要写 `sswflow.` 前缀;迁移 SQL 一律 `public.`
|
||
- 迁移脚本**手动执行**(无 Flyway):`boot/db/V1.0.0__schema.sql`(基线)、`V1.0.2__flow_run_scope.sql`、`V1.0.3__flow_schedule.sql`
|
||
- 三库隔离:`sswflow`/`tds`/`tdc` 同实例不同数据库;表前缀按子系统识别(`flow_*` / `tds_*` / `tdc_*`)
|
||
- 软删除:`f_delete_mark=1`,查询带 `f_delete_mark IS NULL`
|
||
|
||
## 7. 后端规范(对齐 JNPF 7.0)
|
||
|
||
详细见 [`docs/JNPF_BACKEND_GUIDE.md`](./JNPF_BACKEND_GUIDE.md),要点:
|
||
|
||
- 实体/Service/Mapper 必须各自 `@DS("<子库>")`
|
||
- Controller `@RestController("sswflowXxxController")`、Service `@Service("sswflowXxxService")` **显式 bean 名**(防与 JNPF 内部撞名)
|
||
- 实体 `@Alias("SswflowXxxEntity")`
|
||
- 实体基类用 **`SuperExtendEntity<String>`**(带 `sortCode`,已 `javap` 确认;非技能示例的 `SuperEntity<String>`)
|
||
- 业务 Service 统一 `extends SswflowServiceImpl<Mapper,Entity>`(已实现 `DynamicSourceGeneratorInterface`,`DS_KEY="sswflow"`)
|
||
- `SswAdminApplication.main()` 必须 `addInitializers(new jnpf.util.context.SpringContext())`
|
||
- `application.yml` 必须有 `allow-bean-definition-overriding:true` + `spring.mvc.pathmatch.matching-strategy: ant_path_matcher`
|
||
|
||
### 子系统基类
|
||
- **TDS**:`TdsCrudController<T>`(`spaceColumn()` 默认 `"f_space_id"`,自动加 ALIVE 条件)
|
||
- **TDC**:`TdcCrudController<T>`(`tenantColumn()` 默认 `"f_tenant_id"`,多虚拟连接器租户隔离)
|
||
|
||
## 8. 前端结构
|
||
|
||
- 技术栈:Vue3 + Vite + TS + ant-design-vue + pinia + vue-router;`@` 别名 → `src`
|
||
- 三级导航(`App.vue`):顶栏 `subsystems[]`(tds/tdc/sswflow)+ 侧栏由 `router.getRoutes()` 过滤 `meta.subsystem` 推导(避免菜单与路由漂移)
|
||
- 通用 CRUD 骨架:`components/ssw/common/CrudPage.vue`,props `{title, api, columns, filters, actions, extraQuery, defaults, prompt?}`;列表响应读 `res.list`(后端返回 `{pagination, list}`)
|
||
- axios 拦截器解开 `ActionResult.data`,重声明 `SswRequest` 解决类型报错
|
||
|
||
## 9. 算子协议(SSWFlow 子系统)
|
||
|
||
- 类别:`source`/`prep`/`stat`/`model`/`sink`
|
||
- operator 字段:`label`(非 name);key 形如 `source.dataset`/`prep.intersect`;params type:`DATASET/COLUMNS/STRING/SELECT/BOOL/INT/FLOAT/PARTY/SLIDER`
|
||
- 前端 `store.loadOperators` 拉 `/api/ssw/sswflow/Operator/Catalog` 并 merge 前端 icon/color(按 category 映射)
|
||
- 算子执行(V0.13 起):
|
||
- `engine="local"` → `SimulationComputeEngine`(兜底)
|
||
- `engine="mpc"` → `NaxComputeEngine`(首选,order=100)经 Python 子进程跑真实 Nax 算法
|
||
- `engine="tee"` → 预留(TEE 引擎,V0.14+)
|
||
- 新增算子:`stat.scql`(密态 SQL)/ `model.mlp.train`(密文 MLP)/ `model.fedavg.train`(横向联邦)
|
||
- 详见 `docs/sswflow/NAX_ENGINE.md`
|
||
|
||
## 10. P0+P1 功能清单(SSWFlow 子系统,2026-08-01 完成)
|
||
|
||
- P0-1 部分运行/续跑(`RunScope` FULL/SINGLE/SELECTED/UPSTREAM/DOWNSTREAM/RESUME)
|
||
- P0-2 流程模板库(5 预置流程)
|
||
- P1-3 结果可视化(报表/指标 KPI)
|
||
- P1-4 模型产物管理(Artifact 列表+下载)
|
||
- P1-5 轻量调度(`FlowScheduleTicker` 单线程 30s 轮询,避开 Quartz)
|
||
|
||
## 10.1 V0.13 Nax 引擎接入(2026-08-03 完成)
|
||
|
||
- `ComputeEngine` SPI 落地:`NaxComputeEngine implements ComputeEngine`,`supports("mpc")=true`,`order()=100`
|
||
- Python 适配器:`boot/ssw-sswflow/ssw-sswflow-biz/src/main/resources/nax/nax_adapter.py`(随 jar 打包)
|
||
- `StepContext` 富化:新增 `parties` / `datasets` / `workDir` 字段
|
||
- 算子覆盖(16 类):
|
||
- Nax 真实:PSI / 纵向 LR / MLP / FedAvg / SCQL / 安全统计 / 相关性 / IV / 分箱 / 采样 / 切分 / 填充
|
||
- 真实导出(落 CSV)
|
||
- 兜底(`SimulationComputeEngine`):source.dataset / sink.export / model.gbdt.train
|
||
- 独立烟测:PSI 真实命中 50/60(83.3%),纵向 LR AUC=0.8317,MLP AUC=0.8064,FedAvg AUC=0.8329,SCQL `SELECT COUNT/AVG` 真实计算;评估 AUC/Ks/ACC 一致
|
||
- 部署形态:默认 `LocalBackend`;`NAX_BACKEND=ray` 切到 Ray(V0.14 自动化 Party endpoint → Ray 资源映射)
|
||
- 已知限制与排错:见 `docs/sswflow/NAX_ENGINE.md` §6 §8
|
||
|
||
## 11. TDS+TDC 升级基线(2026-08-02 完成)
|
||
|
||
- TDS:空间/连接器/产品/合约/策略模板/审计日志(含 SHA-256 哈希链 + 180 天留存)/统计/状态机
|
||
- TDC:身份注册(mTLS 证书前置)/数据源/资源/产品发布/合约准入/交付任务(策略判定 + 结果回填)
|
||
- 后端 62/62 烟测全过(`/tmp/ssw_tds_tdc_smoke.js`)
|
||
- 前端 TDC 6 视图页 + vue-tsc 0 error + pnpm build 成功
|
||
- 详见:`docs/tds/DOMAIN_MODEL.md` / `docs/tdc/DOMAIN_MODEL.md` / `docs/arch/MIGRATION.md` / `docs/VERIFICATION_2026-08-02.md`
|
||
|
||
## 12. 路由一览
|
||
|
||
### TDS(`/api/ssw/tds/*`)
|
||
`Space` / `Connector` / `DataProduct` / `Contract` / `PolicyTemplate` / `AuditLog` / `Space/{id}/Online|Statistic` / `Connector/{id}/Audit|Heartbeat` / `DataProduct/{id}/Submit|Audit|Online|View` / `Contract/{id}/Sign|Effective|Terminate` / `AuditLog/Verify`
|
||
|
||
### TDC(`api/ssw/tdc/*`)
|
||
`Identity` / `Datasource` / `Resource` / `Product` / `Contract` / `DeliveryTask` + `Identity/{id}/Default|Register|RegisterCallback|Heartbeat` + `Datasource/{id}/Test|Sync` + `Resource/{id}/Sync|Classify` + `Product/{id}/Publish|PublishCallback|Offline` + `DeliveryTask/{id}/Policy|Finish|Report|Cancel`
|
||
|
||
### SSWFLOW(`api/ssw/sswflow/*`)
|
||
`Project` / `Party` / `Dataset` / `Datasource` / `Flow` / `FlowRun` / `Operator` / `Artifact` / `FlowSchedule` + 项目统计/批量运行控制
|
||
|
||
## 13. 验证脚本
|
||
|
||
- `/tmp/ssw_tds_tdc_smoke.js` — TDS+TDC 后端全链路 62/62
|
||
- `/tmp/ssw_login_test.js` — 通用登录+业务烟测(接受端口参数)
|
||
- `/tmp/cipher_check.mjs` — crypto-js 加密自检
|
||
- `/tmp/ssw_proxy_probe.cjs` — 经 5173 代理端到端验证
|
||
|
||
## 14. 移动目录注意事项
|
||
|
||
- 工作区相对路径全部存在 `.claude/memory`(软链到 `.workbuddy/memory`)与 `boot/db/`,**移动目录前**:
|
||
1. 停掉后端 java 进程(`kill <PID>`,lsof `:30000` 查 PID)
|
||
2. 停掉前端 vite 进程(lsof `:5173`)
|
||
3. 移动后 `/Users/xs/.workbuddy/SOUL.md`、`IDENTITY.md`、`USER.md` 不受影响(用户级 identity 文件独立存储)
|
||
- 不要破坏 `boot/ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar` —— 已编译产物;如需重新编译 `mvn -pl ssw-admin -am package -DskipTests`
|
||
- `pnpm` 依赖锁文件:`web/pnpm-lock.yaml`(含前端依赖的完整版本图,移动后 `pnpm install` 会快很多)
|
||
|
||
## 15. 记忆与上下文
|
||
|
||
- 长期笔记:`/Users/xs/Desktop/ssw/.claude/memory/MEMORY.md`(≤3000 字符/会话;物理位于 `.workbuddy/memory/`)
|
||
- 每日日志:`/Users/xs/Desktop/ssw/.claude/memory/YYYY-MM-DD.md`(append-only;物理位于 `.workbuddy/memory/`)
|
||
- 用户身份:`/Users/xs/.workbuddy/{SOUL,IDENTITY,USER}.md`(用户级,与项目无关)
|
||
- 对话历史检索:使用 `conversation_search` 工具(不依赖本地文件) |