Files
ssw-mpc/docs/PG.md
T
rong 471289fe55 feat: 按 SecretFlow 对比结论补齐六条优化 + PostgreSQL 数据接入
影响
- 传输层不再"知道端口就能冒充":PSK 挑战-应答,未配置时显式告警
- 参与方参数不一致可归因(逐字段对表,不再只说"指纹不同")
- 长跑不再整表进内存:CSV 真流式,PG 可直连
- 所有子命令支持 --report json,stdout 只出结构化结果,诊断走 stderr
- 作业支持 DAG 与落盘状态,失败/跳过/重来可追溯
- 计算域抽象落地,dry_run 开关第一次有消费者

改动
- nax-core: 新增 hmac(HMAC-SHA256 / ct_eq / derive_labeled);pg 的 HMAC 改为委托,删重复实现
- nax-node: 新增 auth(REQ/ACK/OK,ctx 绑定双方序号与双 nonce,双 label 防回打)、entropy(只读 /dev/urandom,不降级)
- nax-proto: 新增 Op::Manifest,显式拼字节避开长度前缀错位
- nax-vault: exchange_manifest 比对版本/参与方/fxp/键值清单,三种差异分别点名
- nax-data: 新增 source(TableSource/Batch/CsvSource,流式与整表逐位一致);新增 pg 客户端(自研 wire、trust/md5/SCRAM、零外部依赖)
- nax-orch: 新增 plan(文本计划 + 拓扑校验)、state(append-only JSONL)、run_jobs;协议加 SKIP,单作业模式逐字不变;每作业派生种子避免 Beaver 三元组复用
- nax-runtime: 新增 device(Value/Device/Plain/Secret);域是数据属性,单方搬不回明文;非线性算子在密态域显式拒绝而不是给出错掩码
- nax-cli: 新增 report 模块(Cell/table/kv/note!)、selfcheck(含 TEE 签名)、pg(列类型摊开)、orch run|status
- tools/pg-dev: PGlite + PG-wire 壳、两方种子库、e2e.sh 20 条断言

设计(明确拒绝的方案)
- 设备抽象不做 eval(op) 分发:线性算子对加性分片天然透明,多一层间接只多一个没人用的入口;非线性算子要换协议,不是换指针
- DAG 计划用文本不用 JSON:现场手改要能报"第 2 行:不认识的指令 retries",而 serde_json 与单二进制目标冲突
- 端到端用 PGlite 而非系统 PostgreSQL:同一份源码编成 WASM,无需常驻服务

回归
- cargo test --workspace --features secure → 338 通过 / 0 失败
- cargo build --workspace --all-targets --features secure → 零代码告警
- cargo build -p nax-core --no-default-features → no_std 守线通过
- tools/pg-dev/e2e.sh 两轮真 TCP + 真 PSI + 真密态聚合,两方输出逐字段一致
2026-10-31 21:08:21 +08:00

93 lines
4.7 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.
# PostgreSQL 接入
`nax sql-join --pg-url` 直连业务库取本方数据,靠的是 `crates/nax-data/src/pg`
里一份手写的 PG v3 前端协议客户端(**零外部依赖**)。这份文档说明它支持到哪、
怎么验、以及出问题时先看什么。
## 为什么要手写
铁律是「单二进制、能编进 TEE / Zynq」。`tokio-postgres` 会拖进 tokio +
bytes + futures;`postgres`(同步版)也是一串依赖 + 自己的 TLS 栈。
联邦学习这条路上真正需要的只有一件事:**执行一条只读 SELECT,把行取回来**。
没有参数化、没有预编译、没有连接池、没有通知、没有 COPY——这些都不要,
要的就手写。协议本身不难:StartupMessage + 认证 + Simple Query,一千多行。
## 支持矩阵
| 能力 | 状态 |
|---|---|
| 连接串 `postgres://user:pass@host:port/db?sslmode=disable` | 支持 |
| `sslmode=disable` / 省略 | 支持 |
| `sslmode=require` 及其他 | **明确报错**,不假装支持 |
| 认证 `trust` / `cleartext` / `md5` / `SCRAM-SHA-256` | 支持;`SCRAM-SHA-256-PLUS` 不支持(要 TLS) |
| Simple Query(`Q`),多语句返回多个结果集 | 支持 |
| Extended Query(prepare/bind/execute) | 不做 |
| 结果文本格式 → `Frame`(**只要数值列**) | 支持,非数值列先丢后报 |
| `COPY`、`LISTEN/NOTIFY`、游标 | 不做 |
| 密码来源 | 连接串 → 省略时取 `NAX_PG_PASSWORD`;**别写进 argv** |
被丢的列:`ResultSet::to_frame` 只收 `bool/int2/int4/int8/oid/float4/float8/numeric`
(OID 16/21/23/20/26/700/701/1700),`text/varchar/date/timestamp/json` 一律丢弃
并回报列名。`Frame` 的格子是 `f64`,这是刻意的——密态算子只认定点数。
join 键必须是**非负整数**(PSI 的 id 是 `u64`),且 < 2^53(`f64` 能精确表示的上界)。
## 三层验证
单元测试只能证明「我们自己写的服务端和客户端能对上」,等于自证。所以分三层:
1. **golden 向量**(`pg/crypto.rs` 的测试)——PBKDF2 / HMAC / MD5 / base64 / SCRAM
的中间值与 `python3 hashlib` 独立算出的结果逐位比对。
2. **假服务端**(`pg/mod.rs` 的 `tests::Server`)——真 TCP、三种认证、错误注入,
验证客户端的状态机(错密码、错误后连接仍可用、SCRAM 全流程)。
3. **真 Postgres**(`tools/pg-dev/`)——PGlite 是 Postgres 编到 WASM 的版本,
复用同一份 PG 源码,协议行为一致。`tools/pg-dev/e2e.sh` 起两个**独立的**库
(银行 / 商户),跑完整的两方密态聚合并断言结果。
```bash
tools/pg-dev/e2e.sh # 全自动,退出码 0 = 全部断言通过
tools/pg-dev/e2e.sh --keep # 跑完不关库,方便手工再看
```
它验的是:客户端连真库 → `SELECT uid, balance` 取数 → PSI 求交(`uid=6` 只在乙方、
`uid=5` 只在甲方,必须被挡掉)→ 列分片交换 → 密态聚合 → 两方结果一致。
```
第一轮(聚合 spend) COUNT=4 SUM=140 MIN=20 MAX=50
第二轮(WHERE spend>=30,聚合 balance) COUNT=3 SUM=1600 MIN=300 MAX=900
```
## 手工起一个本地库
```bash
cd tools/pg-dev && node server.mjs --port 5433 --init seed-bank.sql
```
- 默认 `memory://`,跑完即弃;要保住数据给 `--data-dir .data/bank`
- 就绪信号是 stdout 上的 `[pg-dev] ready 127.0.0.1:5433`
- 认证走 trust(PGlite 单用户),**所以 SCRAM 只在假服务端 + golden 向量里验过**
## 出问题时先跑 `nax pg`
`sql-join` 的报错来自分布式会话深处,「连不上库 / 列被丢 / 键不是整数 / 值不是数值」
四种错在终端上长得差不多。把库这条路单独跑通再排查:
```bash
nax pg --url postgres://[email protected]:5432/db \
--sql "select uid, balance, name from t" --frames
```
输出三块:原始结果集、**列类型表**(每列的 OID、类型名、会不会进 `Frame`)、
以及 `--frames` 时真正进密态计算的那几列。用户最常见的困惑「我查了 5 列,
怎么聚合只认 2 列」,答案永远在那张列类型表里。
## 已知限制(写清楚免得踩)
- **链路上不加密**。`sslmode=require` 直接拒绝,跨公网请套 SSH 隧道 / WireGuard。
- **密码以 md5 / SCRAM 证明过网**(trust 除外),明文只出现在 cleartext 模式。
- **整表物化**。Simple Query 一次返回全部 `DataRow`,百万行会吃掉内存;
真流式要 extended query + Execute 分页,属后续。CSV 侧已有分批流接口
(`nax-data::source`),PG 侧还没有。
- **PGlite 是 PG 18**,生产是 15.18;两者 wire 协议同为 v3,但新版本的行为差异
(如参数默认值)不会被这套端到端测试覆盖。