Files
ssw-mpc/docs/PG.md
T
admin 54781b3f83
ci / gate (push) Waiting to run
refactor: 项目改名 ssw-mpc,crate 统一到 mpc-* 前缀
- 项目与文档标题:nax-rs → ssw-mpc(尚数网-多方安全计算),二进制 nax → mpc
- 18 个 crate 及目录 nax-* → mpc-*,Rust 引用 nax_* → mpc_*
- 环境变量、C 符号、构建/部署脚本:NAX_* → MPC_*、libnax_ray.so → libmpc_ray.so
- 保留协议域分隔常量与 refs/nax 参考实现路径,维持 golden 向量与历史数据兼容
- 新增 [profile.dev] incremental=false
2026-11-05 15:06:12 +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 接入
`mpc sql-join --pg-url` 直连业务库取本方数据,靠的是 `crates/mpc-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`、游标 | 不做 |
| 密码来源 | 连接串 → 省略时取 `MPC_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 向量里验过**
## 出问题时先跑 `mpc pg`
`sql-join` 的报错来自分布式会话深处,「连不上库 / 列被丢 / 键不是整数 / 值不是数值」
四种错在终端上长得差不多。把库这条路单独跑通再排查:
```bash
mpc 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 侧已有分批流接口
(`mpc-data::source`),PG 侧还没有。
- **PGlite 是 PG 18**,生产是 15.18;两者 wire 协议同为 v3,但新版本的行为差异
(如参数默认值)不会被这套端到端测试覆盖。