Files
ssw-mpc/crates/nax-cli/src/main.rs
T
rong 65e199c406 feat(sql): MIN/MAX 换树形归约,轮数从线性变对数
影响:`MIN`/`MAX` 的往返数不再随行数线性增长,1000 行的五聚合查询从
约 9995 轮降到 115 轮。**这是本仓第一次改增长阶,不是压常数因子。**

- `secure_graph::minmax` 从「best 与每一行比一次」改成逐层两两归约:
  叶子层是 `len` 个本地 slice,每层 9 轮比较 + 1 轮选择 = 10 轮,
  深度 ⌈log₂ len⌉。奇数个元素时最后一个轮空(补哑元素要多一次比较)。
- 每行翻一倍正好 +10 轮:4/8/16/32/64/128/256 行 → 23/33/43/53/63/73/83。
- 5 行 55 → 45 轮;1000 行 ~9995 → 115;10000 行 ~99995 → 155。

数值上等价:min/max 可结合,全程只有 cmp + select、不经过 truncate,
换结合顺序不引入任何差。`where_aggregate_matches_legacy_for_every_cmp_op`
仍要求 `MIN`/`MAX` 与手写序列逐位相同。

顺带修 `nax-cli` 的阶段表:本地算子列改成同名折叠(`slice ×2000`)。
1000 行时原来会把上千个 slice 逐个列出来,表格 300 KB 且不可读;
折叠之后树的结构反而一眼可见(`cmp ×1000 → ×500 → ×250 → ×124 → …`)。

修正一处自己写错的论断:`minmax` 原注释与 `docs/IR.md` 说「树形不省轮数,
因为串行依赖不变」—— 深度不同,`行数−1` vs `⌈log₂行数⌉`,而且同层比较
互不依赖可以合批。文档已改,另加 2 条测试钉住增长阶与非 2 的幂的正确性。

验证:471 用例全绿(+2),-Dwarnings 零告警,no_std 守线过,rustfmt 无 diff。
变异 3 条全部按预期红后还原:退回线性链(4→8 行多 40 轮)、落单元素不轮空
(n=3 MAX 错)、比较方向取反(n=2 MIN 错)。
2026-11-02 11:39:43 +08:00

2916 lines
109 KiB
Rust
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.
//! `nax` —— 单二进制入口。
//!
//! 这一版只有 `selftest`:在**本机单进程**里把算子核的关键路径跑一遍,
//! 用来确认"二进制能起来、密码学没写错、TEE 抽象可用"。
//!
//! 真正的多进程集群(`nax node` / `nax run`)在 P1/P2 落地,
//! 见 `docs/ARCHITECTURE.md` 的路线图。
use std::process::ExitCode;
use std::time::Duration;
use nax_core::prg::Stream;
use nax_core::ring;
use nax_core::share::{reconstruct_into, split_into, Dealer};
use nax_node::{
run_lr_session, run_lr_vertical_session, run_psi_session, run_session, Frame, LrConfig,
NodeError, PsiConfig, SessionConfig, TcpMesh, TcpTransport, Transport, VerticalLrConfig,
VaultError,
};
use nax_orch::{Agent, Assign, JobPlan, Orchestrator, Report, StateLog};
use nax_orch::state as orch_state;
use nax_fl::fedavg::{ClientData, FedAvg};
use nax_tee::mock::MockTee;
use nax_tee::Tee;
/// 进度/诊断行 —— `println!` 的替代品。
///
/// `--report json` 时会自动改走 stderr,让 stdout 保持纯 JSON 流。
/// 用的地方和执行顺序都跟原来的 `println!` 一致,文本模式观感不变。
///
/// 定义在 `mod` 声明之前:`macro_rules!` 是按文本顺序生效的,
/// 放在后面的话 `sql_demo` / `sql_join` 这些子模块就看不见它。
macro_rules! note {
($($t:tt)*) => { $crate::report::note(format_args!($($t)*)) };
}
#[cfg(feature = "secure")]
mod pg_source;
mod report;
#[cfg(feature = "secure")]
mod sql_demo;
#[cfg(feature = "secure")]
mod sql_join;
const VERSION: &str = env!("CARGO_PKG_VERSION");
fn main() -> ExitCode {
let raw: Vec<String> = std::env::args().skip(1).collect();
// `--report` 是全局开关,出现在子命令前后都认;摘掉再分发,
// 免得 `nax --report json fl` 把 "--report" 当成命令名。
let (args, json) = match split_report_flag(&raw) {
Ok(v) => v,
Err(e) => {
eprintln!("失败: {e}");
return ExitCode::from(2);
}
};
report::set_json(json);
let cmd = args.first().map(String::as_str).unwrap_or("help");
let r = match cmd {
"selftest" => selftest(),
"selfcheck" => cmd_selfcheck(&args[1..]),
"trust" => cmd_trust(&args[1..]),
"plan" => cmd_plan(&args[1..]),
"node" => cmd_node(&args[1..]),
"cluster" => cmd_cluster(&args[1..]),
"orch" => cmd_orch(&args[1..]),
"agent" => cmd_agent(&args[1..]),
"psi" => cmd_psi(&args[1..]),
"lr" => cmd_lr(&args[1..]),
"lr-vertical" => cmd_lr_vertical(&args[1..]),
"fl" => cmd_fl(&args[1..]),
#[cfg(feature = "secure")]
"sql" => sql_demo::run(&args[1..]),
#[cfg(feature = "secure")]
"sql-plan" => cmd_sql_plan(&args[1..]),
#[cfg(feature = "secure")]
"sql-join" => cmd_sql_join(&args[1..]),
#[cfg(feature = "secure")]
"pg" => pg_source::cmd(&args[1..]),
"version" | "-V" | "--version" => {
note!("nax {VERSION}");
Ok(())
}
"help" | "-h" | "--help" => {
usage();
Ok(())
}
other => {
eprintln!("未知命令: {other}\n");
usage();
return ExitCode::from(2);
}
};
match r {
Ok(()) => ExitCode::SUCCESS,
Err(e) => {
eprintln!("失败: {e}");
ExitCode::FAILURE
}
}
}
fn usage() {
note!(
"nax {VERSION} —— N-arty Arithmetic eXecution
用法:
nax selftest 跑一遍算子核与 TEE 抽象的端到端自检
nax selfcheck 报出本二进制的 SHA-256 / 体积(产物自校验,可 --expect 复核)
nax trust 按各方 TEE 状况算出可信度方案 L0–L3(不联网)
nax plan 把纵向 LR 梯度图编译成执行计划,报出交互轮数(不联网)
nax node 启动一方节点,与对端跑一次密文会话
nax psi 启动一方节点,与其余方做一次隐私求交(n 方 ECDH-PSI)
nax lr-vertical 真纵向 LR:各方持不同客户/不同特征列,n 方(PSI → 对齐 → 密态训练)
nax fl 横向联邦平均(FedAvg)本地演示(无网络,合成数据)
nax orch run 按计划文件跑多作业(DAG),状态可落盘
nax orch status 从状态目录读回作业进展(不依赖进程还活着)
nax sql in-process 2 方密态 SQL 演示(编译需 --features secure)
nax sql-plan 把一条聚合查询编译成执行计划,报出交互轮数(不联网,需 --features secure)
nax sql-join 真两进程 TCP 的 JOIN×PSI×密态 SQL(编译需 --features secure)
nax sql / nax sql-plan 都支持 --group-mode exact|coded(默认 exact):
coded 走整数分组码前缀和,8 组时 13 → 12 轮;要求分组码是 0..n-1 的整数,
且不支持 MIN/MAX(前缀和还原不出分组极值)
nax pg 连一条 PostgreSQL 跑一条 SQL,把列类型摊开(排障用,需 --features secure)
nax version 打印版本
nax help 显示本帮助
全局开关(可放在子命令前后):
--report text|json
text(默认)给人看;json 输出 NDJSON,一行一个对象。
对象字段固定为 kind / title / header / rows(table),或 kind / rows(kv),
进度行改走 stderr,因此 `nax fl --report json | jq .` 直接可用。
nax selfcheck 参数:
--file PATH 校验指定文件而不是自身(核对分发出去的产物)
--expect HEX 与已知摘要比对,不一致则非零退出
--out PATH 写一份清单 JSON(tool/version/size/sha256/platform/tee)
--tee-sign 额外用 TEE 设备密钥对摘要签名(当前仅 mock 平台)
nax trust 参数:
--parties A=K[:tcb][+attested],B=none,... 各方 TEE 状况(必填)
K 取 none / optee / sev-snp / tdx / hygon-csv
`+attested` 表示该方已通过远端证明验证(不做默认假设)
--min-tcb N 可接受的最低 TCB 版本(默认 0)
--allow-plaintext-merge 明示允许 L2 把明文合到一处算(默认不允许)
打开它等于放弃 MPC 那层数学保障,只信 TEE 隔离
nax node 参数:
--site NAME 本方站点名(必填)
--sites A,B 全体站点,逗号分隔(必填,各方必须一致)
--listen ADDR 监听地址(两方被动方 / n 方必填)
--connect ADDR 连接对端地址(仅两方主动方)
--peers A=ADDR,B=ADDR,... n 方地址表(与 --listen 搭配)
--data V,V,... 本方持有的数据(浮点,逗号分隔)
--fxp N 定点小数位(默认 18)
--seed HEX 会话主种子,64 位十六进制(默认全 0,仅测试)
--psk-file PATH 身份认证用的预共享密钥(64 位十六进制,推荐;文件设 0600)
--psk HEX 同上,但会出现在 ps / 进程列表里(排障用,别上生产)
也可用环境变量 NAX_PSK。配了即双向认证 + 全链路加密(ChaCha20-Poly1305);
不配 = 既不认证也不加密,启动会明确警告
接 Ray 做成员目录(需 `cargo build --features ray`):
设了 NAX_RAY_RAYLET 就会先把本进程注册成 Ray cluster 的一个 driver,
拿到 raylet 分配的 node id,再跑下面的会话。Ray 只提供「我在哪台机、
带什么标签」,计算仍走 nax 自己的 TCP 帧。
NAX_RAY_GCS GCS 的 redis 地址,如 127.0.0.1:6400(1.0.1 用 redis,不是 gRPC 端口)
NAX_RAY_RAYLET 本节点 raylet socket 路径(必填,设了它就启用)
NAX_RAY_PLASMA 本节点 plasma socket 路径(必填)
NAX_RAY_NM_PORT raylet 的 node_manager 端口(必填)
NAX_RAY_NODE_IP 本机 IP,默认 127.0.0.1
NAX_RAY_JOB job id 整数,默认 1
两进程示例:
nax node --site bob --sites alice,bob --listen 127.0.0.1:9444 --data 4,5,6 &
nax node --site alice --sites alice,bob --connect 127.0.0.1:9444 --data 1,2,3
# 两侧都会算出 (x·y+1) 的求和 = 35
三进程示例(网状直连,算出 x·y·z + 1 的求和):
nax node --site alice --sites alice,bob,carol --listen 127.0.0.1:9450 \
--peers alice=127.0.0.1:9450,bob=127.0.0.1:9451,carol=127.0.0.1:9452 --data 2 &
nax node --site bob --sites alice,bob,carol --listen 127.0.0.1:9451 \
--peers alice=127.0.0.1:9450,bob=127.0.0.1:9451,carol=127.0.0.1:9452 --data 3 &
nax node --site carol --sites alice,bob,carol --listen 127.0.0.1:9452 \
--peers alice=127.0.0.1:9450,bob=127.0.0.1:9451,carol=127.0.0.1:9452 --data 5
# 三方都输出 2·3·5 + 1 = 31
nax psi 参数:
--site / --sites / --listen / --connect / --peers / --seed 同 nax node
--ids 1,2,3,... 本方的 ID 集合(非负整数,逗号分隔)
两进程示例:
nax psi --site bob --sites alice,bob --listen 127.0.0.1:9445 --ids 3,4,5,6,7 &
nax psi --site alice --sites alice,bob --connect 127.0.0.1:9445 --ids 1,2,3,4,5
# 交集 = 3,4,5
三进程示例(环协议,n 方求交):
S=alice,bob,carol
P=alice=127.0.0.1:9450,bob=127.0.0.1:9451,carol=127.0.0.1:9452
nax psi --site alice --sites $S --listen 127.0.0.1:9450 --peers $P --ids 1,2,3,4,5 &
nax psi --site bob --sites $S --listen 127.0.0.1:9451 --peers $P --ids 3,4,5,6,7 &
nax psi --site carol --sites $S --listen 127.0.0.1:9452 --peers $P --ids 4,5,6,7,8
# 三方都输出 4,5(两两求交会多出 3 和 6,7)
nax lr 参数:
--site / --sites / --listen / --connect / --seed / --fxp 同上
--data-x V,V,... 本方特征矩阵(平铺 n×d,行主序)
--data-y V,V,... 标签(长度 n;两方都要传同样的标签)
--n N 样本数
--d N 特征数
--epochs N 训练轮数(默认 40)
--lr F 学习率(默认 0.5)
两进程示例:
nax lr --site bob --sites alice,bob --listen 127.0.0.1:9446 \
--data-x 1,2,3,4,5,6 --data-y 0,1,0 --n 3 --d 2 &
nax lr --site alice --sites alice,bob --connect 127.0.0.1:9446 \
--data-x 1,2,3,4,5,6 --data-y 0,1,0 --n 3 --d 2
# 双方都输出训练后的权重(--data-x 是 n×d 个,--data-y 是 n 个)
nax lr-vertical 参数:
--site / --sites / --listen / --connect / --peers / --seed / --fxp 同上
--col-blocks A:OFF:LEN,B:... 各方列块(site:offset:len),必须铺满 0..d_total
例 alice:0:1,bob:1:1,carol:2:1 —— 三方各持 1 列,按序拼接
--label-owner NAME 标签由哪一方提供(必须恰好一方,其余方不要给 --data-y)
--data-ids V,V,... 本方的 join 键(长度 = 样本数)
--data-x V,V,... 本方特征(平铺 样本数×本方列数,行主序)
--data-y V,V,... 标签(只有 label-owner 给)
--epochs N / --lr F 训练轮数(默认 40)/ 学习率(默认 0.3)
密态通道走 --listen / --peers 的**端口 +1**,不用再给一组地址。
n 方用 --listen + --peers;两方才可用 --connect。
三方示例:
nax lr-vertical --site alice --sites alice,bob,carol --listen 127.0.0.1:39301 \
--peers alice=127.0.0.1:39301,bob=127.0.0.1:39311,carol=127.0.0.1:39321 \
--col-blocks alice:0:1,bob:1:1,carol:2:1 --label-owner bob \
--data-ids 7,2,4,1,8,3,9,5 --data-x 0,-0.75,-0.25,-1,0.75,-0.5,1,0
# 其余两方类似(bob 额外给 --data-y)
nax orch run 参数(多作业 DAG):
--plan FILE 计划文件(文本,格式见下)
--sites A,B 全体站点(必填,与运行时上线的 agent 一致)
--listen ADDR 监听地址(默认 0.0.0.0:9447)
--state-dir DIR 状态落盘目录(强烈建议给;不给就只在内存里)
--fxp / --seed / --timeout 同 nax cluster
nax orch status 参数:
--state-dir DIR 与 run 时同一个目录
--job NAME 只看这一个作业(多打一张各方明细表)
计划文件格式(# 开头是注释,空行忽略):
job A ← 作业名
deps - ← 依赖,- 表示没有;多个写 deps A,B
expect 35 ← 可选:算完之后的后置条件,不符即判失败
data alice=1,2,3 bob=4,5,6 ← 各方输入;不写就用该方 agent 自己的 --data
job B
deps A
expect 999
job C
deps B ← B 失败时 C 会被跳过,并记下原因
三终端示例:
nax orch run --plan demo.plan --sites alice,bob --state-dir /var/lib/nax/state
nax agent --site alice --orch 127.0.0.1:9447 --listen 127.0.0.1:9451
nax agent --site bob --orch 127.0.0.1:9447 --listen 127.0.0.1:9452
# 跑完看进展(进程退了也能看):
nax orch status --state-dir /var/lib/nax/state
nax fl 参数(本地演示,无需网络):
--clients N 客户端数(默认 3)
--features D 特征维数(默认 4,权重 = D+1 含偏置)
--per-client M 每客户端样本数(默认 40)
--rounds R 联邦轮数(默认 12)
--local-epochs E 每轮本地训练轮数(默认 2)
--lr F / --l2 F 学习率(0.5)/ L2 正则(0.0)
--clip F / --noise F DP 裁剪阈值 / 高斯噪声乘数(默认 0 = 关闭)
--seed HEX 主种子,64 位十六进制(默认全 0)
示例:
nax fl --clients 4 --features 6 --per-client 50 --rounds 15 --lr 0.6
# 合成可分离数据上跑横向 FedAvg,逐轮打印 loss/acc/auc
nax sql-join 参数(需 --features secure):
--site / --sites / --listen / --connect / --seed / --fxp 同 nax node
--schema C1,C2,... 全局列序(两方必须完全一致)
--agg-col NAME 要聚合的列(必须在 schema 里)
--pred A>=B 可选,密态 WHERE(列 vs 列 / 列 vs 常量)
本方数据二选一:
--ids 1,2,3 --data balance=700,200,... 手输
--pg-url postgres://u@host:5432/db --pg-query \"SELECT uid, balance FROM t\" \
[--pg-id-col uid] 直连业务库(整数键 + 数值列)
--pg-url 也可以用环境变量 NAX_PG_URL;密码放 NAX_PG_PASSWORD(别写进 argv)
示例(两终端,一方读库一方手输):
nax sql-join --site bob --sites alice,bob --listen 127.0.0.1:9449 \
--pg-url postgres://[email protected]:5432/shop \
--pg-query \"SELECT uid, spend FROM orders\" \
--schema balance,spend --agg-col spend
nax sql-join --site alice --sites alice,bob --connect 127.0.0.1:9449 \
--ids 2,3,4 --data balance=200,400,300 \
--schema balance,spend --agg-col spend
nax pg 参数(排障用,需 --features secure):
--url postgres://u@host:5432/db 或环境变量 NAX_PG_URL
--sql \"SELECT ...\" 只跑一条(Simple Query)
--frames 额外打印「真正进密态计算的那几列」
用途:sql-join 连不上/列被丢/键不是整数时,先用它把「库这条路」单独跑通
示例: nax pg --url postgres://[email protected]:5432/db --sql \"select uid, balance from t\" --frames
本地没有 Postgres?tools/pg-dev/ 里有 PGlite(真 Postgres 的 WASM 版):
tools/pg-dev/e2e.sh 一键起两个库 + 跑完整两方密态聚合 + 断言
规划中 (见 docs/ARCHITECTURE.md):
nax run <plan.yaml> 执行计算计划
nax audit show 查看审计链"
);
}
// ---------------------------------------------------------------------------
fn selftest() -> Result<(), String> {
note!("nax {VERSION} selftest");
// 每步返回「一行说明」,由 selftest 统一成表 —— 文本模式和
// `--report json` 用的是同一份数据,不会出现两边口径不一致。
type Step = (&'static str, fn() -> Result<String, String>);
let steps: [Step; 5] = [
("定点编码往返", step_fixed_point),
("两方分片 / 重建", step_share_roundtrip),
("两方 Beaver 乘法", step_beaver_mul),
("TEE 密封 / 解封 / 证明", step_tee_seal),
("明文域 / 密态域一致性", step_device),
];
let mut rows: Vec<Vec<report::Cell>> = Vec::new();
let mut failed: Option<String> = None;
for (i, (name, f)) in steps.iter().enumerate() {
match f() {
Ok(detail) => rows.push(vec![
report::Cell::int((i + 1) as i64),
report::Cell::txt(*name),
report::Cell::flag(true),
report::Cell::txt(detail),
]),
Err(e) => {
rows.push(vec![
report::Cell::int((i + 1) as i64),
report::Cell::txt(*name),
report::Cell::flag(false),
report::Cell::txt(e.clone()),
]);
failed = Some(e);
break;
}
}
}
report::table("自检步骤", &["#", "步骤", "通过", "说明"], &rows);
match failed {
Some(e) => Err(e),
None => {
note!("\n全部通过");
Ok(())
}
}
}
fn step_fixed_point() -> Result<String, String> {
let vals = [0.0f64, 1.0, -1.0, 3.14159265358979, -987.654, 0.125];
for v in vals {
let e = ring::encode(v, 18).map_err(|e| e.to_string())?;
let d = ring::decode(e, 18);
if (d - v).abs() > 1e-4 {
return Err(format!("{v} -> {d} 误差过大"));
}
}
// 银行家舍入必须与 numpy 的 np.rint 一致
if ring::encode(2.5, 0).map_err(|e| e.to_string())? != 2 {
return Err("银行家舍入错误:2.5 应舍到 2".into());
}
if ring::encode(3.5, 0).map_err(|e| e.to_string())? != 4 {
return Err("银行家舍入错误:3.5 应入到 4".into());
}
Ok("含银行家舍入,与 np.rint 一致".into())
}
fn step_share_roundtrip() -> Result<String, String> {
let n = 2usize;
let secret: Vec<u64> = (0..64).map(|i| (i * 7919) as u64).collect();
let mut s = Stream::new(&[42u8; 32]);
let mut shares = vec![0u64; n * secret.len()];
split_into(&secret, n, &mut s, &mut shares, 18).map_err(|e| e.to_string())?;
let mut back = vec![0u64; secret.len()];
reconstruct_into(&shares, n, secret.len(), &mut back).map_err(|e| e.to_string())?;
if back != secret {
return Err("重建结果与原始秘密不一致".into());
}
if shares[..secret.len()] == secret[..] {
return Err("单方分片等于秘密本身,分片没起作用".into());
}
Ok(format!("{} 个元素,单方分片 ≠ 秘密", secret.len()))
}
/// 两方 Beaver 乘法 —— MPC 的核心协议,在这里一步不省地跑一遍。
///
/// 全程只有两次 `open`(把带随机掩码的差值公开),其余都是本地运算。
fn step_beaver_mul() -> Result<String, String> {
let n = 2usize;
const FXP: u32 = 0; // 用整数域验证协议本身,避免截断干扰
let x: u64 = 12345;
let y: u64 = 6789;
let mut dealer = Dealer::new([7u8; 32], n, FXP);
// 离线:Beaver 三元组 a*b=c
let mut a_sh = vec![0u64; n];
let mut b_sh = vec![0u64; n];
let mut c_sh = vec![0u64; n];
dealer
.mul_triple(1, &mut a_sh, &mut b_sh, &mut c_sh)
.map_err(|e| e.to_string())?;
// 输入分片:x 拆给两方,y 也拆给两方
let mut s = Stream::new(&[11u8; 32]);
let mut x_sh = vec![0u64; n];
let mut y_sh = vec![0u64; n];
split_into(&[x], n, &mut s, &mut x_sh, FXP).map_err(|e| e.to_string())?;
split_into(&[y], n, &mut s, &mut y_sh, FXP).map_err(|e| e.to_string())?;
// 第一轮 open:d = x − a, e = y − b(各方本地算分片,然后公开求和)
let mut d_sh = vec![0u64; n];
let mut e_sh = vec![0u64; n];
ring::sub_into(&x_sh, &a_sh, &mut d_sh).map_err(|e| e.to_string())?;
ring::sub_into(&y_sh, &b_sh, &mut e_sh).map_err(|e| e.to_string())?;
let mut d = [0u64; 1];
let mut e = [0u64; 1];
reconstruct_into(&d_sh, n, 1, &mut d).map_err(|x| x.to_string())?;
reconstruct_into(&e_sh, n, 1, &mut e).map_err(|x| x.to_string())?;
// 本地乘:z_i = c_i + d·b_i + e·a_i (i==0 再补 d·e)
let mut z_sh = vec![0u64; n];
for (i, zi) in z_sh.iter_mut().enumerate() {
let mut acc = c_sh[i];
acc = acc.wrapping_add(d[0].wrapping_mul(b_sh[i]));
acc = acc.wrapping_add(e[0].wrapping_mul(a_sh[i]));
if i == 0 {
acc = acc.wrapping_add(d[0].wrapping_mul(e[0]));
}
*zi = acc;
}
// 第二次 open:还原结果
let mut z = [0u64; 1];
reconstruct_into(&z_sh, n, 1, &mut z).map_err(|x| x.to_string())?;
let want = x.wrapping_mul(y);
if z[0] != want {
return Err(format!("Beaver 乘法结果错: {:#x} != {:#x}", z[0], want));
}
Ok(format!("{x} × {y} = {},两次 open", z[0]))
}
fn step_tee_seal() -> Result<String, String> {
let tee = MockTee::new([3u8; 32]);
let plaintext = "alice 的明文密钥材料".as_bytes();
let blob = tee.seal(plaintext, b"session-1").map_err(|e| e.to_string())?;
let back = tee.unseal(&blob, b"session-1").map_err(|e| e.to_string())?;
if back != plaintext {
return Err("解封结果与明文不一致".into());
}
// 换了 aad 必须解不开
if tee.unseal(&blob, b"session-2").is_ok() {
return Err("aad 不匹配却解封成功".into());
}
let att = tee.attest(&[7u8; 64]).map_err(|e| e.to_string())?;
tee.verify_attestation(&att).map_err(|e| e.to_string())?;
Ok(format!(
"平台={},aad 绑定生效,报告可验",
tee.platform().kind
))
}
/// 明文域 / 密态域的同一份表达式是否给出同一结果。
///
/// 这一步存在的意义:`nax-runtime::device` 是「双阶段执行」那句话的实现,
/// 如果只在库里躺着、没人跑过,它就还是注释。selftest 是每次发版都会跑的地方,
/// 放这里才叫真的接上了。
fn step_device() -> Result<String, String> {
use nax_runtime::device::{DeviceKind, Plain, Secret, Value};
const FXP: u32 = 18;
let vals = [120.5, 300.25, 500.0, 12.75];
// 公开掩码(k-匿名抑制那类场景:阈值是合规方公开给定的)
let keep = [true, true, false, true];
let plain = Value::plain(FXP, &[("amount", &vals)]).map_err(|e| e.to_string())?;
let want: Vec<f64> = plain
.mask_public("amount", &keep)
.map_err(|e| e.to_string())?
.sum("amount")
.map_err(|e| e.to_string())?
.decode("sum(amount)")
.map_err(|e| e.to_string())?;
// 同一个表达式,放到两方密态域上各算一遍,再重建
let dev = Secret::new(2, [0x5au8; 32]);
let mut shares = Vec::new();
for site in 0..2 {
let s = plain.to(&dev.at(site)).map_err(|e| e.to_string())?;
if s.kind() != DeviceKind::Secret {
return Err(format!("第 {site} 方没进密态域"));
}
shares.push(
s.mask_public("amount", &keep)
.map_err(|e| e.to_string())?
.sum("amount")
.map_err(|e| e.to_string())?,
);
}
let got = Value::reconstruct(&shares)
.map_err(|e| e.to_string())?
.decode("sum(amount)")
.map_err(|e| e.to_string())?;
if got[0].to_bits() != want[0].to_bits() {
return Err(format!(
"两域结果不一致:明文 {} vs 密态 {}",
want[0], got[0]
));
}
// 非线性算子必须被显式挡住(换算法,不是换指针)
let sec = plain.to(&Secret::new(2, [0x5au8; 32])).map_err(|e| e.to_string())?;
match sec.lt_mask("amount", 400.0) {
Err(e) if e.is_unsupported() => {}
Err(e) => return Err(format!("密态域比较的错误类型不对:{e}")),
Ok(_) => return Err("密态域竟然允许逐元素比较,这会静默算错".into()),
}
// 明文域上它是能算的
let mask = plain
.lt_mask("amount", 400.0)
.map_err(|e| e.to_string())?
.raw("(amount < 400)")
.ok_or("明文域比较没产出掩码列")?
.to_vec();
// 空转一下 Plain,确认 trait 对象路径也通
let again = plain.to(&Plain).map_err(|e| e.to_string())?;
if again != plain {
return Err("to(Plain) 不是恒等映射".into());
}
Ok(format!(
"两域逐位一致 sum={};掩码 {mask:?};密态域拒绝非线性算子",
want[0]
))
}
// ---------------------------------------------------------------------------
// nax selfcheck —— 产物自校验
// ---------------------------------------------------------------------------
/// 读文件、算 SHA-256,边读边算(不把二进制整个读进内存)。
fn sha256_file(path: &std::path::Path) -> Result<(String, u64), String> {
use std::io::Read;
let mut f =
std::fs::File::open(path).map_err(|e| format!("打开 {} 失败: {e}", path.display()))?;
let mut h = nax_core::hash::Sha256::new();
let mut buf = vec![0u8; 64 * 1024];
let mut size = 0u64;
loop {
let n = f
.read(&mut buf)
.map_err(|e| format!("读 {} 失败: {e}", path.display()))?;
if n == 0 {
break;
}
h.update(&buf[..n]);
size += n as u64;
}
Ok((hex_bytes(&h.finalize()), size))
}
/// 解析一方的 TEE 声明:`site=kind[:tcb][+attested]` 或 `site=none`。
///
/// 例:`alice=sev-snp:5+attested`、`bob=optee`、`carol=none`。
///
/// 没有把 `attested` 的默认值做成 `true` —— 默认"已验证"等于默认少做一步,
/// 而这一步恰恰是 L2 唯一的依据。
fn parse_party_tee(spec: &str) -> Result<nax_tee::PartyTee, String> {
let (site, rest) = spec
.split_once('=')
.ok_or_else(|| format!("{spec:?} 缺少 `=`,应形如 alice=sev-snp:5+attested"))?;
let site = site.trim();
if site.is_empty() {
return Err(format!("{spec:?} 的 site 名为空"));
}
let rest = rest.trim();
if rest == "none" {
return Ok(nax_tee::PartyTee::without_tee(site));
}
let (body, attested) = match rest.strip_suffix("+attested") {
Some(b) => (b, true),
None => (rest, false),
};
let (kind_s, tcb) = match body.split_once(':') {
Some((k, t)) => {
let tcb: u32 = t
.parse()
.map_err(|_| format!("{spec:?} 的 tcb {t:?} 不是非负整数"))?;
(k, tcb)
}
None => (body, 0),
};
let kind = match kind_s {
"optee" => nax_tee::PlatformKind::Optee,
"sev-snp" | "snp" => nax_tee::PlatformKind::SevSnp,
"tdx" => nax_tee::PlatformKind::Tdx,
"hygon-csv" | "csv" => nax_tee::PlatformKind::HygonCsv,
other => {
return Err(format!(
"未知平台 {other:?}(可选 none / optee / sev-snp / tdx / hygon-csv)"
))
}
};
if kind == nax_tee::PlatformKind::None {
return Err("平台 none 请写成 `site=none`".into());
}
Ok(nax_tee::PartyTee::with_tee(site, kind, tcb, attested))
}
/// `nax trust`:按各方的 TEE 状况算出可信度方案(L0–L3)。
///
/// 这个命令**不发起任何连接**,只做判定 —— 它的用途是让"这一轮到底靠什么
/// 保证安全"在开工前就写在纸上,而不是跑完以后靠回忆解释。
fn cmd_trust(args: &[String]) -> Result<(), String> {
let spec = parse_flag(args, "--parties").ok_or("缺少 --parties")?;
let mut parties: Vec<nax_tee::PartyTee> = Vec::new();
for tok in spec.split(',') {
let tok = tok.trim();
if tok.is_empty() {
continue;
}
parties.push(parse_party_tee(tok)?);
}
if parties.is_empty() {
return Err("--parties 为空".into());
}
let min_tcb: u32 = match parse_flag(args, "--min-tcb") {
Some(v) => v.parse().map_err(|_| format!("--min-tcb {v:?} 不是整数"))?,
None => 0,
};
let policy = nax_tee::TrustPolicy {
min_tcb,
allow_plaintext_merge: args.iter().any(|a| a == "--allow-plaintext-merge"),
};
let plan = nax_tee::TrustPlan::for_parties(&parties, policy).map_err(|e| e.to_string())?;
let mut rows: Vec<Vec<report::Cell>> = Vec::with_capacity(parties.len());
for p in &parties {
let (platform, tcb) = match &p.platform {
Some(pl) => (pl.kind.to_string(), pl.tcb as i64),
None => ("none".to_string(), -1),
};
rows.push(vec![
report::Cell::txt(p.site.clone()),
report::Cell::txt(platform),
if tcb < 0 {
report::Cell::txt("—")
} else {
report::Cell::int(tcb)
},
report::Cell::flag(p.attested),
report::Cell::flag(p.is_trusted(policy.min_tcb)),
]);
}
report::table(
"各方 TEE 状况",
&["site", "platform", "tcb", "attested", "trusted"],
&rows,
);
let untrusted = plan.untrusted_sides(&parties);
report::kv(
"可信度方案",
&[
("grade", report::Cell::txt(plan.grade().to_string())),
("needs_mpc", report::Cell::flag(plan.needs_mpc())),
("needs_tee", report::Cell::flag(plan.needs_tee())),
(
"allow_plaintext_merge",
report::Cell::flag(plan.allows_plaintext_merge()),
),
(
"untrusted_sides",
report::Cell::txt(if untrusted.is_empty() {
"—".to_string()
} else {
untrusted.join(", ")
}),
),
("summary", report::Cell::txt(plan.summary())),
],
);
// L2 是唯一跳过 MPC 的方案,把它的前提再念一遍 ——
// 这条路径一旦开错,泄露的是全体明文,不是精度。
if plan.allows_plaintext_merge() && !policy.allow_plaintext_merge {
return Err("内部矛盾:未明示允许合并却算出 L2".into());
}
Ok(())
}
/// 把一张算子图编译成「几轮交互」,并打印调度结果。
///
/// # 为什么是一个命令而不是一句文档
///
/// 隐语 SPU 的价值有一半在编译器:同样的数学,写得好是 5 轮、写得差是 9 轮,
/// 而这件事在代码里看不出来。nax 之前没有这层,轮数只能靠人读代码数。
///
/// 把 `nax-ml` 的**真实**纵向 LR 迭代图编译成执行计划,报出交互轮数。
///
/// 这里不另写一份示例图 —— 用的就是 `VerticalLR::build_epoch`,也就是
/// `nax lr / nax lr-vertical` 真跑时用的那张图。所以这几个数字可以直接
/// 拿去估算一次训练要多久:**每轮迭代 N 个往返 × 迭代数**。
///
/// 迁移前没有这个能力:轮数只能靠人数代码里出现了几次 `matmul_trunc`,
/// 而 `scale_public` 后面那次截断特别容易漏。
fn cmd_plan(args: &[String]) -> Result<(), String> {
let rows: usize = match parse_flag(args, "--rows") {
Some(v) => v.parse().map_err(|_| format!("--rows {v:?} 不是整数"))?,
None => 8,
};
let dims: usize = match parse_flag(args, "--features") {
Some(v) => v.parse().map_err(|_| format!("--features {v:?} 不是整数"))?,
None => 4,
};
let lr: f64 = match parse_flag(args, "--lr") {
Some(v) => v.parse().map_err(|_| format!("--lr {v:?} 不是浮点"))?,
None => 0.5,
};
let epochs: usize = match parse_flag(args, "--epochs") {
Some(v) => v.parse().map_err(|_| format!("--epochs {v:?} 不是整数"))?,
None => 40,
};
let l2: f64 = match parse_flag(args, "--l2") {
Some(v) => v.parse().map_err(|_| format!("--l2 {v:?} 不是浮点"))?,
None => 0.0,
};
let degree: usize = match parse_flag(args, "--sigmoid-degree") {
Some(v) => {
v.parse()
.map_err(|_| format!("--sigmoid-degree {v:?} 不是整数"))?
}
None => 7,
};
if rows == 0 || dims == 0 {
return Err("--rows / --features 必须大于 0".into());
}
// 全仓统一的定点位数;真实训练用 `vault.fxp()`,这里不联网所以写死。
const FXP: u32 = 18;
let cfg = nax_ml::VerticalLR {
lr,
epochs,
l2,
sigmoid_degree: degree,
fit_intercept: true,
};
let eg = cfg
.build_epoch(rows, dims, FXP)
.map_err(|e| e.to_string())?;
let plan = eg.plan;
let mut table: Vec<Vec<report::Cell>> = Vec::with_capacity(plan.stages().len());
{
let g = plan.graph();
let names = |vs: &[usize]| {
if vs.is_empty() {
"—".to_string()
} else {
vs.iter()
.map(|&v| g.node(v).op.name())
.collect::<Vec<_>>()
.join(", ")
}
};
for st in plan.stages() {
table.push(vec![
report::Cell::int(st.round as i64 + 1),
report::Cell::txt(names(&st.comm)),
report::Cell::txt(names(&st.local)),
report::Cell::int(st.comm.len() as i64),
]);
}
}
report::table(
"一次迭代的执行阶段(同阶段的交互算子合并成一个往返)",
&["起始轮", "交互算子", "本地算子", "交互数"],
&table,
);
let mut lifts = 0usize;
for n in plan.graph().nodes() {
if matches!(n.op, nax_ir::Op::Lift { .. }) {
lifts += 1;
}
}
let per = plan.rounds();
report::kv(
"编译结果",
&[
(
"算子总数",
report::Cell::int(plan.graph().nodes().len() as i64),
),
("交互算子", report::Cell::int(plan.comm_ops() as i64)),
("本地算子", report::Cell::int(plan.local_ops() as i64)),
("公开值抬升", report::Cell::int(lifts as i64)),
("每轮迭代往返", report::Cell::int(per as i64)),
("迭代数", report::Cell::int(epochs as i64)),
(
"训练总往返",
report::Cell::int((per * epochs) as i64),
),
(
"口径",
report::Cell::txt(
"上界:同阶段的乘/截断/open/比较各自合成一批;matmul 的 2 轮尚未进批",
),
),
],
);
note!("{}", plan.summary());
Ok(())
}
/// 把一条聚合查询编译成执行计划,报出交互轮数。**不联网、不需要数据。**
///
/// 图只依赖形状(行数、分组数、聚合种类、谓词结构),所以「这条查询要跑几个
/// 往返」在拿到数据之前就能回答。迁移前这个数字只能靠人数代码里出现了几次
/// `bit_lt` —— 而掩码聚合的调用序列有六七步,数错一处就估歪。
///
/// 口径是**上界**,见 [`nax_sql::secure::query_rounds`] 的两处估计。
#[cfg(feature = "secure")]
fn cmd_sql_plan(args: &[String]) -> Result<(), String> {
// 全仓统一的定点位数;真实会话用 `vault.fxp()`,这里不联网所以写死。
const FXP: u32 = 18;
let rows: usize = match parse_flag(args, "--rows") {
Some(v) => v.parse().map_err(|_| format!("--rows {v:?} 不是整数"))?,
None => 6,
};
if rows == 0 {
return Err("--rows 必须大于 0".into());
}
let groups: Option<usize> = match parse_flag(args, "--groups") {
Some(v) => {
let n: usize = v.parse().map_err(|_| format!("--groups {v:?} 不是整数"))?;
if n == 0 {
return Err("--groups 必须大于 0(不分组的整表聚合请省略这个参数)".into());
}
Some(n)
}
None => None,
};
let aggs = parse_agg_list(&parse_flag(args, "--aggs").unwrap_or_else(|| "count,sum".into()))?;
let pred = match parse_flag(args, "--where") {
Some(s) => Some(parse_simple_pred(&s)?),
None => None,
};
let mode = match parse_flag(args, "--group-mode").as_deref() {
None | Some("exact") => nax_sql::secure::GroupMode::Exact,
Some("coded") => nax_sql::secure::GroupMode::IntegerCode,
Some(other) => {
return Err(format!(
"--group-mode {other:?} 不认识(可选 exact / coded)"
))
}
};
let plan = nax_sql::secure::query_rounds(rows, FXP, 1, pred.as_ref(), groups, &aggs, mode)
.map_err(|e| e.to_string())?;
let coded = mode == nax_sql::secure::GroupMode::IntegerCode && groups.is_some();
report::table(
if coded {
"前缀段(谓词 → 分组码搬家 → N+1 个单调前缀 → 累积和)"
} else {
"掩码段(谓词 → 0/1 位 → 掩码后列 → 命中数)"
},
&["起始轮", "交互算子", "本地算子", "交互数"],
&stage_rows(&plan.mask),
);
if let Some(a) = &plan.aggs {
report::table(
"聚合段(SUM / AVG / MIN / MAX)",
&["起始轮", "交互算子", "本地算子", "交互数"],
&stage_rows(a),
);
}
let agg_names: Vec<&str> = aggs
.iter()
.map(|a| match a {
nax_sql::secure::Agg::Count => "COUNT",
nax_sql::secure::Agg::Sum => "SUM",
nax_sql::secure::Agg::Avg => "AVG",
nax_sql::secure::Agg::Min => "MIN",
nax_sql::secure::Agg::Max => "MAX",
})
.collect();
report::kv(
"编译结果",
&[
("行数", report::Cell::int(rows as i64)),
(
"分组",
match groups {
Some(n) => report::Cell::int(n as i64),
None => report::Cell::txt("无(整表)"),
},
),
(
"分组模式",
report::Cell::txt(if coded {
"整数码(前缀和)"
} else {
"逐组比较"
}),
),
("聚合", report::Cell::txt(agg_names.join(", "))),
(
"谓词",
match &pred {
Some(p) => report::Cell::txt(format!("{p:?}")),
None => report::Cell::txt("无 WHERE"),
},
),
("掩码段往返", report::Cell::int(plan.mask.rounds() as i64)),
("聚合段往返", report::Cell::int(plan.agg_rounds() as i64)),
("总往返", report::Cell::int(plan.rounds() as i64)),
(
"口径",
report::Cell::txt(
"上界:同阶段同类批量(比较 9 轮封顶);AVG 除数按非整数算(多计 1 轮);MIN/MAX 按命中数非零算",
),
),
],
);
note!("{}", plan.summary());
Ok(())
}
/// 计划 → 阶段表。`nax plan` 与 `nax sql-plan` 共用同一种排版。
#[cfg(feature = "secure")]
fn stage_rows(plan: &nax_ir::Plan) -> Vec<Vec<report::Cell>> {
let g = plan.graph();
// 同名算子折叠成 `slice ×1024`。本地算子常常上千个(MIN/MAX 每行一个
// `slice`),逐个列出来会把表格撑到几百 KB —— 而且信息量为零。
let names = |vs: &[usize]| {
if vs.is_empty() {
return "—".to_string();
}
let mut order: Vec<(&str, usize)> = Vec::new();
for &v in vs {
let name = g.node(v).op.name();
match order.iter_mut().find(|(n, _)| *n == name) {
Some((_, c)) => *c += 1,
None => order.push((name, 1)),
}
}
order
.iter()
.map(|(n, c)| {
if *c == 1 {
(*n).to_string()
} else {
format!("{n} ×{c}")
}
})
.collect::<Vec<_>>()
.join(", ")
};
plan.stages()
.iter()
.map(|st| {
vec![
report::Cell::int(st.round as i64 + 1),
report::Cell::txt(names(&st.comm)),
report::Cell::txt(names(&st.local)),
report::Cell::int(st.comm.len() as i64),
]
})
.collect()
}
/// `--aggs count,sum,avg,min,max` → 聚合列表。
#[cfg(feature = "secure")]
fn parse_agg_list(s: &str) -> Result<Vec<nax_sql::secure::Agg>, String> {
use nax_sql::secure::Agg;
let mut out = Vec::new();
for part in s.split(',') {
let p = part.trim().to_ascii_lowercase();
if p.is_empty() {
continue;
}
out.push(match p.as_str() {
"count" => Agg::Count,
"sum" => Agg::Sum,
"avg" => Agg::Avg,
"min" => Agg::Min,
"max" => Agg::Max,
other => {
return Err(format!(
"--aggs 里的 {other:?} 不认识(可用 count / sum / avg / min / max)"
))
}
});
}
if out.is_empty() {
return Err("--aggs 不能为空".into());
}
Ok(out)
}
/// `--where "0<400"` → `Pred::Cmp`。
///
/// 只认「列下标 + 比较符 + 字面量」这一种形状。复合谓词(AND/OR/NOT/列 vs 列)
/// 请直接调 [`nax_sql::secure::query_rounds`],命令行不做半截 SQL 解析 ——
/// 一个只会认一半的解析器比没有更糟。
#[cfg(feature = "secure")]
fn parse_simple_pred(s: &str) -> Result<nax_sql::secure::Pred, String> {
use nax_sql::secure::CmpOp;
// 两字符运算符优先,否则 "<=" 会被当成 "<" 加一个 "+" 开头的字面量
for (tok, op) in [
("<=", CmpOp::Le),
(">=", CmpOp::Ge),
("==", CmpOp::Eq),
("!=", CmpOp::Ne),
("<>", CmpOp::Ne),
("<", CmpOp::Lt),
(">", CmpOp::Gt),
("=", CmpOp::Eq),
] {
if let Some((l, r)) = s.split_once(tok) {
let col: usize = l
.trim()
.parse()
.map_err(|_| format!("--where 左边要列下标,收到 {l:?}"))?;
let threshold: f64 = r
.trim()
.parse()
.map_err(|_| format!("--where 右边要字面量,收到 {r:?}"))?;
return Ok(nax_sql::secure::Pred::Cmp {
col,
op,
threshold,
});
}
}
Err(format!(
"--where {s:?} 认不出:格式是 <列下标><运算符><字面量>,例如 \"0<400\" 或 \"1>=0.5\""
))
}
/// 自校验:报出这份二进制(或 `--file` 指定的文件)的 SHA-256 与体积。
///
/// # 为什么需要它
///
/// Kuscia 那边靠 `AppImage.ID` 在起 pod 前后比对镜像没被换过;nax 是单二进制
/// 分发,那层校验就落在二进制自己身上:
///
/// - 部署期用 `--out` 产出清单钉进配置/审计,运行期用 `--expect` 复核;
/// - `--tee-sign` 再用 TEE 设备密钥对摘要签名,得到「这台机器上跑的确实是
/// 这份代码」的凭据 —— 正好是 `TrustPlan` 里输入一致性那条链的锚点。
///
/// 注意:**只报事实,不做安全承诺**。摘要能证明文件没变,不能证明它没被换;
/// 后者要靠 `--tee-sign`(真 TEE 平台)或外部发布的期望值。
fn cmd_selfcheck(args: &[String]) -> Result<(), String> {
let path = match parse_flag(args, "--file") {
Some(p) => std::path::PathBuf::from(p),
None => std::env::current_exe().map_err(|e| format!("取自身路径失败: {e}"))?,
};
let (digest, size) = sha256_file(&path)?;
let mut rows: Vec<(&str, report::Cell)> = vec![
("tool", report::Cell::txt("nax")),
("version", report::Cell::txt(VERSION)),
("binary", report::Cell::txt(path.display().to_string())),
("size", report::Cell::int(size as i64)),
("sha256", report::Cell::txt(digest.clone())),
(
"platform",
report::Cell::txt(format!(
"{}/{}",
std::env::consts::OS,
std::env::consts::ARCH
)),
),
];
// 可选:TEE 设备密钥对摘要签名。当前只有 Mock 实现(平台字段如实写 mock),
// 真平台接进来后语义不变,只是 platform 变成 sev-snp / optee。
let mut tee_json = String::from("null");
if args.iter().any(|a| a == "--tee-sign") {
let tee = MockTee::new([0u8; 32]);
let sig = tee.sign(digest.as_bytes()).map_err(|e| e.to_string())?;
// report_data 是 64 字节定长(按 SNP 的字段定的),摘要 32 字节就填两遍
let mut user_data = [0u8; 64];
let h = nax_core::hash::sha256(digest.as_bytes());
user_data[..32].copy_from_slice(&h);
user_data[32..].copy_from_slice(&h);
let att = tee.attest(&user_data).map_err(|e| e.to_string())?;
tee.verify_attestation(&att).map_err(|e| e.to_string())?;
// 平台名如实写 mock:`PlatformKind::None` 单看是 "none",
// 放进部署清单容易被误读成「这里没有 TEE 可用」,其实就是个纯软件替身
let platform = format!("mock({})", tee.platform().kind);
rows.push(("tee.platform", report::Cell::txt(platform.clone())));
rows.push(("tee.alg", report::Cell::txt(sig.alg)));
rows.push(("tee.signature", report::Cell::txt(hex_bytes(&sig.bytes))));
rows.push(("tee.attestation", report::Cell::flag(true)));
tee_json = format!(
"{{\"platform\":\"{platform}\",\"alg\":\"{}\",\"signature\":\"{}\",\"report_bytes\":{},\"verified\":true}}",
sig.alg,
hex_bytes(&sig.bytes),
att.report.len()
);
}
// --out:写一份清单,供部署期钉住、运行期 --expect 复核
if let Some(out) = parse_flag(args, "--out") {
let doc = format!(
"{{\"tool\":\"nax\",\"version\":\"{VERSION}\",\"binary\":{},\"size\":{size},\"sha256\":\"{digest}\",\"platform\":\"{}/{}\",\"tee\":{tee_json}}}\n",
json_str(&path.display().to_string()),
std::env::consts::OS,
std::env::consts::ARCH
);
std::fs::write(out, doc).map_err(|e| format!("写 {out} 失败: {e}"))?;
note!(" 清单已写入 {out}");
}
report::kv("nax selfcheck", &rows);
// --expect:与已知摘要比对,不一致就非零退出 —— 只打印不判断等于没校验
if let Some(want) = parse_flag(args, "--expect") {
let want = want.trim().to_ascii_lowercase();
if want != digest {
return Err(format!(
"摘要不符:期望 {want},实际 {digest}(二进制被替换,或版本不对)"
));
}
note!(" 摘要与 --expect 一致");
}
Ok(())
}
fn hex_bytes(b: &[u8]) -> String {
let mut s = String::with_capacity(b.len() * 2);
for x in b {
s.push_str(&format!("{x:02x}"));
}
s
}
fn json_str(s: &str) -> String {
let mut out = String::from("\"");
for c in s.chars() {
match c {
'"' => out.push_str("\\\""),
'\\' => out.push_str("\\\\"),
c if (c as u32) < 0x20 => out.push_str(&format!("\\u{:04x}", c as u32)),
c => out.push(c),
}
}
out.push('"');
out
}
// ---------------------------------------------------------------------------
// nax node
// ---------------------------------------------------------------------------
pub(crate) fn parse_flag<'a>(args: &'a [String], name: &str) -> Option<&'a str> {
args.iter()
.position(|a| a == name)
.and_then(|i| args.get(i + 1))
.map(String::as_str)
}
/// 从 argv 里摘出全局的 `--report text|json`,返回(剩余参数, 是否 JSON)。
///
/// 支持 `--report json` 与 `--report=json` 两种写法,位置不限。
/// 摘掉而不是留给子命令忽略 —— 因为子命令的参数解析(`parse_flag`)是
/// 「找第一个同名字符串」,留着会占掉一个位置,容易和真实参数混淆。
fn split_report_flag(raw: &[String]) -> Result<(Vec<String>, bool), String> {
let mut out = Vec::with_capacity(raw.len());
let mut json = false;
let mut i = 0;
while i < raw.len() {
let a = raw[i].as_str();
let val = if a == "--report" {
let v = raw
.get(i + 1)
.ok_or("--report 后面要跟 text 或 json")?;
i += 2;
Some(v.as_str())
} else if let Some(v) = a.strip_prefix("--report=") {
i += 1;
Some(v)
} else {
out.push(raw[i].clone());
i += 1;
None
};
if let Some(v) = val {
json = match v {
"json" => true,
"text" => false,
other => return Err(format!("--report 只认 text / json,得到 {other:?}")),
};
}
}
Ok((out, json))
}
// ---------------------------------------------------------------------------
// 建连认证的预共享密钥
// ---------------------------------------------------------------------------
/// 解析 PSK,优先级:`--psk-file` > `--psk` > 环境变量 `NAX_PSK`。
///
/// # 为什么推荐 `--psk-file`
///
/// `--psk` 和 `--seed` 一样会出现在 `ps` / `/proc/<pid>/cmdline` 里,
/// 同机任何用户都能读到。文件可以设 0600;环境变量略好于 argv 但仍对同用户可见。
/// 三种入口都留着是为了让测试和现场排障不必先造文件。
fn parse_psk(args: &[String]) -> Result<Option<[u8; 32]>, String> {
let raw = if let Some(path) = parse_flag(args, "--psk-file") {
let s = std::fs::read_to_string(path)
.map_err(|e| format!("读 --psk-file {path} 失败: {e}"))?;
Some(s)
} else if let Some(v) = parse_flag(args, "--psk") {
Some(v.to_string())
} else {
std::env::var("NAX_PSK").ok()
};
let Some(s) = raw else { return Ok(None) };
let hex = s.trim();
if hex.len() != 64 {
return Err(format!(
"PSK 必须是 64 个十六进制字符(32 字节),实际长度 {}",
hex.len()
));
}
let bytes = hex.as_bytes();
let mut out = [0u8; 32];
for i in 0..32 {
let hi = hex_val(bytes[i * 2]).ok_or_else(|| {
format!("PSK 第 {} 个字符不是十六进制", i * 2 + 1)
})?;
let lo = hex_val(bytes[i * 2 + 1]).ok_or_else(|| {
format!("PSK 第 {} 个字符不是十六进制", i * 2 + 2)
})?;
out[i] = (hi << 4) | lo;
}
Ok(Some(out))
}
fn hex_val(b: u8) -> Option<u8> {
match b {
b'0'..=b'9' => Some(b - b'0'),
b'a'..=b'f' => Some(b - b'a' + 10),
b'A'..=b'F' => Some(b - b'A' + 10),
_ => None,
}
}
/// 若环境里给了 raylet socket,就把本进程注册成 Ray 集群的一个 driver。
///
/// 为什么要这一步:nax 自己不做集群成员管理(谁在线、各带什么资源标签),
/// 这活交给 Ray。注册完成后 nax 才「知道自己在哪个节点上」,后续按
/// `sites` 与资源标签把各方钉到机器上。计算仍然走 nax 自己的 TCP 帧。
#[cfg(feature = "ray")]
fn attach_ray(site: &str) -> Result<Option<nax_ray::RayCluster>, String> {
if std::env::var("NAX_RAY_RAYLET").is_err() {
return Ok(None);
}
let cfg = nax_ray::config_from_env(&format!("nax_{site}"))?;
note!(
" 接入 Ray 集群: gcs={} raylet={} nm_port={}",
cfg.gcs_addr, cfg.raylet_socket, cfg.node_manager_port
);
let c = nax_ray::RayCluster::connect(&cfg)?;
if let Some(nid) = c.node_id() {
note!(" Ray 节点已确认: node_id={nid}(由 raylet 分配)");
}
if let Some(wid) = c.worker_id() {
note!(" Ray worker_id={wid}");
}
Ok(Some(c))
}
#[cfg(not(feature = "ray"))]
fn attach_ray(_site: &str) -> Result<Option<()>, String> {
if std::env::var("NAX_RAY_RAYLET").is_ok() {
return Err(
"这个 nax 构建没开 ray feature。要用 Ray 做成员目录,请 `cargo build --features ray`"
.into(),
);
}
Ok(None)
}
fn cmd_node(args: &[String]) -> Result<(), String> {
let site = parse_flag(args, "--site").ok_or("缺少 --site")?.to_string();
let sites_raw = parse_flag(args, "--sites").ok_or("缺少 --sites")?;
let sites: Vec<String> = sites_raw
.split(',')
.map(|s| s.trim().to_string())
.filter(|s| !s.is_empty())
.collect();
if sites.len() < 2 {
return Err(format!("--sites 至少 2 方,得到 {} 个", sites.len()));
}
if !sites.contains(&site) {
return Err(format!("--site {site} 不在 --sites {sites:?} 里"));
}
let listen = parse_flag(args, "--listen");
let connect = parse_flag(args, "--connect");
let peers_raw = parse_flag(args, "--peers");
// Ray 只在部署期起作用:把本进程注册成集群里的一个 driver,拿到成员目录。
// 计算不出这个进程——下面的 transport/MPC 完全是 nax 自己的帧。
let _ray = attach_ray(&site)?;
// 建连认证:`--psk-file` > `--psk` > `NAX_PSK`。没配就明说,不假装有。
let psk = parse_psk(args)?;
if psk.is_none() {
note!(" ⚠ 未配置 PSK(--psk-file / --psk / NAX_PSK):本次连接既不认证身份、也不加密链路");
}
// 三种连法:两方 --connect(主动)、两方 --listen(被动)、n 方 --listen + --peers
let transport = match (listen, connect, peers_raw) {
(Some(_), Some(_), _) => {
return Err("--listen 与 --connect 只能选一个".into());
}
(None, None, _) => return Err("必须给 --listen 或 --connect".into()),
(Some(l), None, None) if sites.len() == 2 => {
note!(" 等待对端连接...");
let t = match &psk {
Some(p) => TcpTransport::accept_with_psk(l, p),
None => TcpTransport::accept(l),
}
.map_err(|e| e.to_string())?;
AnyTransport::Single(t)
}
(None, Some(c), None) if sites.len() == 2 => {
note!(" 连接对端...");
let t = match &psk {
Some(p) => TcpTransport::connect_with_psk(c, 50, p),
None => TcpTransport::connect(c, 50),
}
.map_err(|e| e.to_string())?;
AnyTransport::Single(t)
}
(None, Some(_), Some(_)) => {
return Err("--peers 只与 --listen 搭配(网状连接需要本方监听地址)".into());
}
(Some(l), None, Some(p)) => {
// 注意:Vault 内部按**字典序**给参与方编号,这里的 addrs 也必须
// 用同一顺序,否则第 p 片的投递对象会整体错位。
let mut sorted = sites.clone();
sorted.sort();
let me = sorted
.iter()
.position(|s| *s == site)
.ok_or_else(|| format!("--site {site} 不在 --sites 里"))?;
let map = parse_peers(p)?;
let mut addrs: Vec<String> = Vec::with_capacity(sorted.len());
for (i, s) in sorted.iter().enumerate() {
if i == me {
addrs.push(String::new()); // 本方那格不用
} else {
let a = map.get(s).ok_or_else(|| {
format!("--peers 缺少站点 {s} 的地址(需要全部 {sorted:?})")
})?;
addrs.push(a.clone());
}
}
note!(" 建立网状连接({} 方,本方 {me} 号)...", sorted.len());
AnyTransport::Mesh(
TcpMesh::connect_mesh_with_psk(me, l, &addrs, psk.as_ref())
.map_err(|e| e.to_string())?,
)
}
(Some(_), None, None) => {
return Err(format!(
"{} 方必须用 --listen + --peers 建网状连接(--connect 只用于两方)",
sites.len()
));
}
(None, Some(_), None) => {
return Err(format!(
"{} 方不能用 --connect(它只连一个对端),请改用 --listen + --peers",
sites.len()
));
}
};
note!(" 已连接");
let data_str = parse_flag(args, "--data").unwrap_or("0");
let fxp: u32 = parse_flag(args, "--fxp")
.unwrap_or("18")
.parse()
.map_err(|_| "--fxp 不是合法整数")?;
let seed = match parse_flag(args, "--seed") {
Some(h) => parse_seed(h)?,
None => [0u8; 32],
};
// 数据按浮点解析,再编码到定点环
let mut data = Vec::new();
for tok in data_str.split(',') {
let tok = tok.trim();
if tok.is_empty() {
continue;
}
let v: f64 = tok.parse().map_err(|_| format!("--data 里的 {tok:?} 不是浮点"))?;
data.push(nax_core::ring::encode(v, fxp).map_err(|e| e.to_string())?);
}
if data.is_empty() {
return Err("--data 为空".into());
}
note!("nax node · site={site} · {} 方 · {} 个元素 · fxp={fxp}", sites.len(), data.len());
let cfg = SessionConfig {
site: site.clone(),
sites,
master_seed: seed,
fxp,
data,
};
let out = run_session(transport, &cfg, true).map_err(|e: NodeError| e.to_string())?;
let value = nax_core::ring::decode(out[0], fxp);
report::kv(
"会话结果",
&[
("site", report::Cell::txt(site)),
("fxp", report::Cell::int(fxp as i64)),
("value", report::Cell::nump(value, 6)),
],
);
Ok(())
}
// ---------------------------------------------------------------------------
// nax cluster / nax agent —— 编排层
//
// 这一层替代 Ray 在 nax 里的作用,只做两件事:**全局视图** 和
// **把进程放对机器**。不用 ray 包的理由见 `nax-orch` 的模块注释
// (64MB wheel、无 armv7 支持、数据面对 nax 无用)。
// ---------------------------------------------------------------------------
fn cmd_cluster(args: &[String]) -> Result<(), String> {
let listen = parse_flag(args, "--listen").unwrap_or(nax_orch::DEFAULT_ORCH_ADDR);
let sites_raw = parse_flag(args, "--sites").ok_or("缺少 --sites(逗号分隔的全体站点)")?;
let sites: Vec<String> = sites_raw
.split(',')
.map(|s| s.trim().to_string())
.filter(|s| !s.is_empty())
.collect();
if sites.len() < 2 {
return Err(format!("--sites 至少 2 方,得到 {} 个", sites.len()));
}
let fxp: u32 = parse_flag(args, "--fxp")
.unwrap_or("18")
.parse()
.map_err(|_| "--fxp 不是合法整数")?;
let seed = match parse_flag(args, "--seed") {
Some(h) => parse_seed(h)?,
None => [0u8; 32],
};
let timeout: u64 = parse_flag(args, "--timeout")
.unwrap_or("120")
.parse()
.map_err(|_| "--timeout 不是合法整数")?;
let orch = Orchestrator::bind(listen, sites.len(), fxp, seed, Duration::from_secs(timeout))?;
let addr = orch.local_addr()?;
note!("nax cluster · 监听 {addr} · 等 {} 方 · fxp={fxp}", sites.len());
note!(
" 各机器执行: nax agent --site <NAME> --orch <本机IP:{}> --listen 0.0.0.0:0 --data ...",
addr.port()
);
let reports = orch.run(true)?;
// 汇总表:每方一行。失败方也要出现在表里 —— 缺行会让「少了一方」
// 和「这一方没上报」看起来一样。
let mut values = Vec::new();
let mut rows: Vec<Vec<report::Cell>> = Vec::new();
for r in &reports {
let (val, status) = match (&r.value, &r.err) {
(Some(v), _) => {
values.push(*v);
(report::Cell::nump(*v, 6), report::Cell::txt("ok"))
}
(None, Some(e)) => (report::Cell::empty("无"), report::Cell::txt(e)),
(None, None) => (report::Cell::empty("无"), report::Cell::txt("未回报")),
};
rows.push(vec![report::Cell::txt(r.site.clone()), val, status]);
}
report::table("各方结果", &["site", "value", "状态"], &rows);
if values.len() != sites.len() {
return Err(format!(
"{} / {} 方没跑完(有失败或未回报)",
sites.len() - values.len(),
sites.len()
));
}
// 各方必须算出同一个数。不一致说明分片投错方、种子不同步或编号错位,
// 而且这种错不会在协议内部报出来 —— 只能在这里兜住。
let first = values[0];
for v in &values[1..] {
if (v - first).abs() > 1e-9 {
return Err(format!(
"各方结果不一致: {first} vs {v} —— 分片/种子/编号有一处对不上"
));
}
}
note!(" 一致({} 方同值 {first})", values.len());
Ok(())
}
// ---------------------------------------------------------------------------
// nax orch —— 多作业(DAG)编排与状态查询
// ---------------------------------------------------------------------------
fn cmd_orch(args: &[String]) -> Result<(), String> {
match args.first().map(String::as_str) {
Some("run") => orch_run(&args[1..]),
Some("status") => orch_status(&args[1..]),
Some(other) => Err(format!("未知子命令 {other}(只认 run / status)")),
None => Err("nax orch 需要子命令:run <计划文件> / status".into()),
}
}
fn orch_run(args: &[String]) -> Result<(), String> {
let plan_path = parse_flag(args, "--plan").ok_or("缺少 --plan <计划文件>")?;
let src = std::fs::read_to_string(plan_path)
.map_err(|e| format!("读计划 {plan_path} 失败: {e}"))?;
let plan = JobPlan::parse(&src).map_err(|e| format!("{plan_path}: {e}"))?;
let sites_raw = parse_flag(args, "--sites").ok_or("缺少 --sites(逗号分隔的全体站点)")?;
let sites: Vec<String> = sites_raw
.split(',')
.map(|s| s.trim().to_string())
.filter(|s| !s.is_empty())
.collect();
if sites.len() < 2 {
return Err(format!("--sites 至少 2 方,得到 {} 个", sites.len()));
}
// 计划里写了某个站的 data,那个站就必须在 --sites 里,否则那份数据永远用不上
for j in &plan.jobs {
for s in j.data.keys() {
if !sites.contains(s) {
return Err(format!(
"作业 {} 给了站点 {s} 的数据,但它不在 --sites {sites:?} 里",
j.name
));
}
}
}
let listen = parse_flag(args, "--listen").unwrap_or(nax_orch::DEFAULT_ORCH_ADDR);
let fxp: u32 = parse_flag(args, "--fxp")
.unwrap_or("18")
.parse()
.map_err(|_| "--fxp 不是合法整数")?;
let seed = match parse_flag(args, "--seed") {
Some(h) => parse_seed(h)?,
None => [0u8; 32],
};
let timeout: u64 = parse_flag(args, "--timeout")
.unwrap_or("120")
.parse()
.map_err(|_| "--timeout 不是合法整数")?;
let state_dir = parse_flag(args, "--state-dir").map(std::path::PathBuf::from);
let orch = Orchestrator::bind(listen, sites.len(), fxp, seed, Duration::from_secs(timeout))?;
let addr = orch.local_addr()?;
note!(
"nax orch · 监听 {addr} · 等 {} 方 · {} 个作业 · fxp={fxp}",
sites.len(),
plan.jobs.len()
);
if let Some(d) = &state_dir {
note!(" 状态目录: {}", d.display());
} else {
note!(" ⚠ 未给 --state-dir:状态只在内存里,进程退出后查不到");
}
let summaries = orch.run_jobs(&plan, state_dir.as_deref(), true)?;
let rows: Vec<Vec<report::Cell>> = summaries
.iter()
.map(|s| {
vec![
report::Cell::txt(s.job.clone()),
report::Cell::txt(s.status.clone()),
match s.value {
Some(v) => report::Cell::nump(v, 6),
None => report::Cell::empty("无"),
},
match &s.detail {
Some(d) => report::Cell::txt(d.clone()),
None => report::Cell::txt(""),
},
]
})
.collect();
report::table("作业结果", &["job", "状态", "值", "说明"], &rows);
// 有作业没成功就非零退出 —— 编排器是给流水线调用的,退出码就是它的返回值
let bad = summaries.iter().filter(|s| s.status != "ok").count();
if bad > 0 {
return Err(format!("{bad} / {} 个作业没成功", summaries.len()));
}
Ok(())
}
fn orch_status(args: &[String]) -> Result<(), String> {
let dir = parse_flag(args, "--state-dir").ok_or("缺少 --state-dir")?;
let dir = std::path::Path::new(dir);
// 指定了 --job 就看单作业明细,否则列全部
if let Some(job) = parse_flag(args, "--job") {
let (evs, skipped) = StateLog::load(dir, job)?;
if skipped > 0 {
note!(" ⚠ 有 {skipped} 行解析失败(多半是写到一半被杀的残行),已跳过");
}
let sums = orch_state::summarize(&evs);
let s = sums
.first()
.ok_or_else(|| format!("作业 {job} 的日志里没有任何事件"))?;
report::kv(
&format!("作业 {}", s.job),
&[
("status", report::Cell::txt(s.status.clone())),
(
"value",
match s.value {
Some(v) => report::Cell::nump(v, 6),
None => report::Cell::empty("无"),
},
),
(
"detail",
match &s.detail {
Some(d) => report::Cell::txt(d.clone()),
None => report::Cell::txt(""),
},
),
("events", report::Cell::int(evs.len() as i64)),
],
);
let rows: Vec<Vec<report::Cell>> = s
.sites
.iter()
.map(|(site, st, v, d)| {
vec![
report::Cell::txt(site.clone()),
report::Cell::txt(st.clone()),
match v {
Some(x) => report::Cell::nump(*x, 6),
None => report::Cell::empty("无"),
},
match d {
Some(x) => report::Cell::txt(x.clone()),
None => report::Cell::txt(""),
},
]
})
.collect();
report::table("参与方", &["site", "状态", "值", "说明"], &rows);
return Ok(());
}
let jobs = StateLog::list_jobs(dir)?;
if jobs.is_empty() {
return Err(format!("{} 里没有任何作业状态", dir.display()));
}
let mut rows: Vec<Vec<report::Cell>> = Vec::new();
let mut total_skipped = 0usize;
for job in jobs {
let (evs, skipped) = StateLog::load(dir, &job)?;
total_skipped += skipped;
for s in orch_state::summarize(&evs) {
rows.push(vec![
report::Cell::txt(s.job),
report::Cell::txt(s.status),
match s.value {
Some(v) => report::Cell::nump(v, 6),
None => report::Cell::empty("无"),
},
match s.detail {
Some(d) => report::Cell::txt(d),
None => report::Cell::txt(""),
},
]);
}
}
if total_skipped > 0 {
note!(" ⚠ 有 {total_skipped} 行解析失败(残行),已跳过");
}
report::table("作业状态(读自状态目录)", &["job", "状态", "值", "说明"], &rows);
Ok(())
}
// ---------------------------------------------------------------------------
// nax agent
// ---------------------------------------------------------------------------
/// 连 orchestrator,循环领作业:跑会话 → 回报 → 领下一个,直到 `BYE`。
fn cmd_agent(args: &[String]) -> Result<(), String> {
let site = parse_flag(args, "--site").ok_or("缺少 --site")?.to_string();
let orch = parse_flag(args, "--orch").ok_or("缺少 --orch(orchestrator 的 host:port)")?;
let listen = parse_flag(args, "--listen").unwrap_or("0.0.0.0:0");
let timeout: u64 = parse_flag(args, "--timeout")
.unwrap_or("120")
.parse()
.map_err(|_| "--timeout 不是合法整数")?;
// 端口 0 要先探一个真实端口出来:HELLO 里必须报对端能连的端口。
let listen_addr = resolve_listen(listen)?;
let advertise = match parse_flag(args, "--advertise") {
Some(a) => a.to_string(),
// 默认拿本机出口 IP + 监听端口。NAT / 多网卡场景对端未必可达,
// 那时必须显式 --advertise。
None => nax_orch::advertise_from_listen(&listen_addr)?,
};
note!("nax agent · site={site} · orchestrator={orch} · 监听 {listen_addr} · 对外 {advertise}");
let mut agent = Agent::connect(orch, &site, &advertise, Duration::from_secs(timeout))?;
note!(" 已注册,等待计划下发…");
let psk = parse_psk(args)?;
if psk.is_none() {
note!(" ⚠ 未配置 PSK:与其它方的连接既不认证身份、也不加密链路");
}
let mut ran = 0usize;
loop {
let plan = match agent.next_assign()? {
Assign::Done => break,
Assign::Skip { job, reason } => {
note!(" 跳过作业 {job}:{reason}");
continue;
}
Assign::Run(p) => p,
};
note!(
" 作业 {} · {} 方 · 本方 {} 号 · fxp={} · peers={}",
plan.job,
plan.sites.len(),
plan.me,
plan.fxp,
plan.peers_arg()
);
// 计划里带了本方输入就用它(多作业模式下每作业不同),否则用自己的 --data。
let data = if plan.data.is_empty() {
let data_str = parse_flag(args, "--data").unwrap_or("0");
let mut v = Vec::new();
for tok in data_str.split(',') {
let tok = tok.trim();
if tok.is_empty() {
continue;
}
let x: f64 = tok
.parse()
.map_err(|_| format!("--data 里的 {tok:?} 不是浮点"))?;
v.push(ring::encode(x, plan.fxp).map_err(|e| e.to_string())?);
}
v
} else {
plan.data.clone()
};
if data.is_empty() {
let msg = "本方没有任何输入数据(计划里没给,--data 也是空)".to_string();
let _ = agent.report(&Report::fail(&site, &msg));
return Err(msg);
}
note!(" 建立网状连接({} 方)…", plan.sites.len());
let addrs = plan.addrs_for_mesh();
// 一条作业失败不代表后面全废:别的分支可能不依赖它,所以回报后继续领下一个。
let transport = match TcpMesh::connect_mesh_with_psk(
plan.me,
&listen_addr,
&addrs,
psk.as_ref(),
) {
Ok(t) => t,
Err(e) => {
let msg = format!("建连失败: {e}");
let _ = agent.report(&Report::fail(&site, &msg));
note!(" 作业 {} 失败:{msg}", plan.job);
continue;
}
};
let cfg = SessionConfig {
site: site.clone(),
sites: plan.sites.clone(),
master_seed: plan.seed,
fxp: plan.fxp,
data,
};
match run_session(transport, &cfg, true) {
Ok(out) => {
let value = ring::decode(out[0], plan.fxp);
agent.report(&Report::ok(&site, value))?;
report::kv(
"会话结果(已上报 orchestrator)",
&[
("job", report::Cell::txt(plan.job.clone())),
("site", report::Cell::txt(site.clone())),
("me", report::Cell::int(plan.me as i64)),
("fxp", report::Cell::int(plan.fxp as i64)),
("value", report::Cell::nump(value, 6)),
],
);
ran += 1;
}
Err(e) => {
// 失败也要回报,否则 orchestrator 会一直等,另外几方也卡在 open 上。
let msg = e.to_string();
let _ = agent.report(&Report::fail(&site, &msg));
note!(" 作业 {} 失败:{msg}", plan.job);
}
}
}
note!(" 全部作业结束,共跑了 {ran} 个");
Ok(())
}
/// `--listen` 端口写 0 时先绑一次拿到真实端口再放开。
///
/// 拿到端口到真正 `TcpMesh` 绑上去之间有个极短窗口,理论上可能被别的进程抢;
/// 抢的后果是绑定时报错(不会静默用错端口),可以接受。
fn resolve_listen(listen: &str) -> Result<String, String> {
let (host, port) = listen
.rsplit_once(':')
.ok_or_else(|| format!("--listen {listen:?} 不是 host:port"))?;
let port: u16 = port
.parse()
.map_err(|_| format!("--listen {listen:?} 的端口不是整数"))?;
if port != 0 {
return Ok(listen.to_string());
}
let l = std::net::TcpListener::bind(listen).map_err(|e| format!("试绑 {listen} 失败: {e}"))?;
let p = l.local_addr().map_err(|e| e.to_string())?.port();
drop(l);
Ok(format!("{host}:{p}"))
}
/// 解析 `alice=1.2.3.4:9441,bob=...` 形式的地址表。
fn parse_peers(raw: &str) -> Result<std::collections::HashMap<String, String>, String> {
let mut map = std::collections::HashMap::new();
for entry in raw.split(',') {
let entry = entry.trim();
if entry.is_empty() {
continue;
}
let (name, addr) = entry
.split_once('=')
.ok_or_else(|| format!("--peers 里 {entry:?} 不是 name=addr 形式"))?;
let (name, addr) = (name.trim(), addr.trim());
if name.is_empty() || addr.is_empty() {
return Err(format!("--peers 里 {entry:?} 的站点名或地址为空"));
}
if map.insert(name.to_string(), addr.to_string()).is_some() {
return Err(format!("--peers 里站点 {name} 重复"));
}
}
if map.is_empty() {
return Err("--peers 为空".into());
}
Ok(map)
}
/// 单连接与网状连接的统一包装 —— `run_session` 对泛型 `T: Transport` 只要求接口一致。
enum AnyTransport {
Single(TcpTransport),
Mesh(TcpMesh),
}
impl Transport for AnyTransport {
fn send_to(&mut self, party: usize, frame: Frame) -> Result<(), VaultError> {
match self {
Self::Single(t) => t.send_to(party, frame),
Self::Mesh(m) => m.send_to(party, frame),
}
}
fn recv_from(&mut self, party: usize) -> Result<Frame, VaultError> {
match self {
Self::Single(t) => t.recv_from(party),
Self::Mesh(m) => m.recv_from(party),
}
}
}
/// 按 `--listen` / `--connect` / `--listen + --peers` 三种形态建一条通道。
///
/// n 方纵向 LR 要建**两条**(PSI 一条、密态一条),所以抽出来共用。
/// 两条都必须是同一套下标语义 —— `sorted_sites` 的顺序即 party 编号。
fn connect_any(
label: &str,
listen: Option<&str>,
connect: Option<&str>,
peers_raw: Option<&str>,
sorted_sites: &[String],
my_idx: usize,
psk: &Option<[u8; 32]>,
) -> Result<AnyTransport, String> {
let n = sorted_sites.len();
let t = match (listen, connect, peers_raw) {
(Some(_), Some(_), _) => return Err("--listen 与 --connect 只能选一个".into()),
(None, None, _) => return Err("必须给 --listen 或 --connect".into()),
(Some(l), None, None) if n == 2 => {
note!(" [{label}] 等待对端连接({l})...");
let t = match psk {
Some(p) => TcpTransport::accept_with_psk(l, p),
None => TcpTransport::accept(l),
}
.map_err(|e| e.to_string())?;
AnyTransport::Single(t)
}
(None, Some(c), None) if n == 2 => {
note!(" [{label}] 连接对端({c})...");
let t = match psk {
Some(p) => TcpTransport::connect_with_psk(c, 50, p),
None => TcpTransport::connect(c, 50),
}
.map_err(|e| e.to_string())?;
AnyTransport::Single(t)
}
(None, Some(_), Some(_)) => {
return Err("--peers 只与 --listen 搭配(网状连接需要本方监听地址)".into());
}
(Some(l), None, Some(p)) => {
let map = parse_peers(p)?;
let mut addrs: Vec<String> = Vec::with_capacity(n);
for (i, s) in sorted_sites.iter().enumerate() {
if i == my_idx {
addrs.push(String::new());
} else {
let a = map.get(s).ok_or_else(|| {
format!("[{label}] --peers 缺少站点 {s} 的地址(需要全部 {sorted_sites:?})")
})?;
addrs.push(a.clone());
}
}
note!(" [{label}] 建立网状连接({n} 方,本方 {my_idx} 号)...");
AnyTransport::Mesh(
TcpMesh::connect_mesh_with_psk(my_idx, l, &addrs, psk.as_ref())
.map_err(|e| e.to_string())?,
)
}
(Some(_), None, None) => {
return Err(format!(
"[{label}] {n} 方必须用 --listen + --peers 建网状连接(--connect 只用于两方)"
));
}
(None, Some(_), None) => {
return Err(format!(
"[{label}] {n} 方不能用 --connect(它只连一个对端),请改用 --listen + --peers"
));
}
};
note!(" [{label}] 已连接");
Ok(t)
}
/// 地址端口 +1。纵向 LR 的第二条通道(密态)用 `--listen` 的下一个端口。
///
/// 为什么用"端口 +1"而不是再加一组参数:n 方要一次给出 n 组地址,
/// 加成 4 组参数(PSI 的 listen/peers + 密态的 listen/peers)容易配漏一个,
/// 而配漏的表现是连不上或串会话,不是清晰报错。
fn bump_port(addr: &str) -> Result<String, String> {
let (host, port) = addr
.rsplit_once(':')
.ok_or_else(|| format!("地址 {addr:?} 缺少端口"))?;
let p: u16 = port
.parse()
.map_err(|_| format!("地址 {addr:?} 的端口 {port:?} 不是整数"))?;
if p == 0 {
return Err(format!(
"地址 {addr:?} 用了随机端口 0 —— 两条通道要分别监听,不能随机"
));
}
if p == u16::MAX {
return Err(format!("地址 {addr:?} 端口已是 65535,没有下一个端口可用"));
}
Ok(format!("{host}:{}", p + 1))
}
/// 把 `--peers` 表里每个地址的端口都 +1。
fn bump_peers(raw: &str) -> Result<String, String> {
let mut out: Vec<String> = Vec::new();
for item in raw.split(',') {
let item = item.trim();
if item.is_empty() {
continue;
}
let (k, v) = item
.split_once('=')
.ok_or_else(|| format!("--peers 里的 {item:?} 缺少 `=`(应形如 alice=host:port)"))?;
out.push(format!("{}={}", k.trim(), bump_port(v.trim())?));
}
if out.is_empty() {
return Err("--peers 为空".into());
}
Ok(out.join(","))
}
/// 解析 `--col-blocks`:`alice:0:1,bob:1:1,carol:2:1`(site:offset:len)。
fn parse_col_blocks(raw: &str) -> Result<Vec<nax_node::ColBlock>, String> {
let mut out: Vec<nax_node::ColBlock> = Vec::new();
for item in raw.split(',') {
let item = item.trim();
if item.is_empty() {
continue;
}
let parts: Vec<&str> = item.split(':').map(str::trim).collect();
if parts.len() != 3 {
return Err(format!(
"--col-blocks 里的 {item:?} 不是 site:offset:len 三段"
));
}
let offset: usize = parts[1]
.parse()
.map_err(|_| format!("{item:?} 的 offset {:?} 不是非负整数", parts[1]))?;
let len: usize = parts[2]
.parse()
.map_err(|_| format!("{item:?} 的 len {:?} 不是非负整数", parts[2]))?;
if out.iter().any(|b| b.site == parts[0]) {
return Err(format!("--col-blocks 里 site {} 重复", parts[0]));
}
out.push(nax_node::ColBlock::new(parts[0], offset, len));
}
if out.is_empty() {
return Err("--col-blocks 为空".into());
}
Ok(out)
}
/// 从 (会话主种子, 本方 site) 派生该方的 PSI 种子。
///
/// # 为什么不让用户直接给 PSI 种子
///
/// ECDH-PSI 的隐私性全部押在"每方私钥不同"上。用户可以给同一个
/// `--seed`(默认值更是每人一样),若直接拿它当 PRG 种子,所有方的
/// 私钥就完全相同 —— 交集**仍然算得对**,但任一方都能从自己那份
/// 盲化点反推别人的原始 ID。不报错、不崩、数也对,是最难发现的一种失败。
///
/// 所以种子一律从 `(主种子, site)` 派生:主种子可以共享(它只是会话
/// 标识),派生结果天然每方不同。
fn derive_psi_seed(seed: [u8; 32], site: &str) -> [u8; 32] {
let mut out = seed;
for (i, b) in site.bytes().enumerate() {
let k = i % 32;
out[k] = out[k].wrapping_add(b).wrapping_mul(31).wrapping_add(i as u8);
}
out
}
fn parse_seed(hex: &str) -> Result<[u8; 32], String> {
let clean: String = hex.chars().filter(|c| !c.is_whitespace()).collect();
if clean.len() != 64 {
return Err(format!("--seed 需要 64 个十六进制字符,实际 {}", clean.len()));
}
let mut out = [0u8; 32];
for i in 0..32 {
out[i] = u8::from_str_radix(&clean[i * 2..i * 2 + 2], 16)
.map_err(|_| format!("--seed 第 {} 字节不是十六进制", i))?;
}
Ok(out)
}
// ---------------------------------------------------------------------------
// nax sql-join(需 --features secure)
// ---------------------------------------------------------------------------
#[cfg(feature = "secure")]
fn cmd_sql_join(args: &[String]) -> Result<(), String> {
let site = parse_flag(args, "--site").ok_or("缺少 --site")?.to_string();
let sites_raw = parse_flag(args, "--sites").ok_or("缺少 --sites")?;
let sites: Vec<String> = sites_raw
.split(',')
.map(|s| s.trim().to_string())
.filter(|s| !s.is_empty())
.collect();
if sites.len() != 2 {
return Err(format!("sql-join 目前只支持两方,--sites 得到 {} 个", sites.len()));
}
if !sites.contains(&site) {
return Err(format!("--site {site} 不在 --sites {sites:?} 里"));
}
let listen = parse_flag(args, "--listen");
let connect = parse_flag(args, "--connect");
let addr = match (listen, connect) {
(Some(_), Some(_)) => return Err("--listen 与 --connect 只能选一个".into()),
(None, None) => return Err("必须给 --listen 或 --connect".into()),
(Some(a), None) | (None, Some(a)) => a.to_string(),
};
let seed = match parse_flag(args, "--seed") {
Some(h) => parse_seed(h)?,
None => [0u8; 32],
};
let fxp: u32 = parse_flag(args, "--fxp")
.unwrap_or("18")
.parse()
.map_err(|_| "--fxp 不是合法整数")?;
// 本方数据源:`--ids`/`--data`(手输),或 `--pg-url`/`--pg-query`(直连业务库)
let pg_url = parse_flag(args, "--pg-url")
.map(|s| s.to_string())
.or_else(|| std::env::var("NAX_PG_URL").ok().filter(|s| !s.trim().is_empty()));
let (ids, cols) = match pg_url {
Some(url) => {
if parse_flag(args, "--ids").is_some() || args.iter().any(|a| a == "--data") {
return Err("--pg-url 与 --ids/--data 互斥:本方数据只能有一个来源".into());
}
let q = parse_flag(args, "--pg-query")
.ok_or("给了 --pg-url 就要 --pg-query(一条 SELECT)")?;
let loaded = pg_source::load(&url, q, parse_flag(args, "--pg-id-col"))?;
if !loaded.dropped.is_empty() {
eprintln!(" 注意:非数值列已丢弃 {:?}", loaded.dropped);
}
note!(
" PG 数据源 {} · join 键 {} · {} 行 × {} 列",
pg_source::redact(&url),
loaded.id_col,
loaded.ids.len(),
loaded.cols.len()
);
(loaded.ids, loaded.cols)
}
None => {
// --ids:join 键
let ids_raw = parse_flag(args, "--ids").ok_or("缺少 --ids(或给 --pg-url)")?;
let mut ids = Vec::new();
for tok in ids_raw.split(',') {
let tok = tok.trim();
if tok.is_empty() {
continue;
}
let v: u64 = tok
.parse()
.map_err(|_| format!("--ids 里的 {tok:?} 不是非负整数"))?;
ids.push(v);
}
if ids.is_empty() {
return Err("--ids 为空".into());
}
// --data name=v1,v2,...(可重复)
let mut cols: Vec<(String, Vec<f64>)> = Vec::new();
for i in 0..args.len() {
if args[i] == "--data" && i + 1 < args.len() {
cols.push(sql_join::parse_col(&args[i + 1])?);
}
}
(ids, cols)
}
};
if cols.is_empty() {
return Err("至少要有一列数据(--data name=... 或 --pg-query 里的数值列)".into());
}
// --schema col1,col2,...(两方必须一致的全局列序)
let schema_raw = parse_flag(args, "--schema").ok_or("缺少 --schema")?;
let schema = sql_join::parse_schema(schema_raw)?;
let agg_col = parse_flag(args, "--agg-col").ok_or("缺少 --agg-col")?;
let pred = parse_flag(args, "--pred");
note!(
"nax sql-join · site={site} · {addr} · {} 行 × {} 列 · 聚合列={agg_col}",
ids.len(),
cols.len()
);
note!(" schema: {}", schema.join(","));
if let Some(p) = pred {
note!(" 谓词: WHERE {p}");
}
// 建连认证:与 `nax node` 用同一套解析(--psk-file > --psk > NAX_PSK)。
let psk = parse_psk(args)?;
if psk.is_none() {
note!(" ⚠ 未配置 PSK(--psk-file / --psk / NAX_PSK):本次连接既不认证身份、也不加密链路");
}
let mut transport = if listen.is_some() {
note!(" 等待对端连接...");
match &psk {
Some(p) => TcpTransport::accept_with_psk(&addr, p),
None => TcpTransport::accept(&addr),
}
.map_err(|e| e.to_string())?
} else {
note!(" 连接对端...");
match &psk {
Some(p) => TcpTransport::connect_with_psk(&addr, 50, p),
None => TcpTransport::connect(&addr, 50),
}
.map_err(|e| e.to_string())?
};
note!(" 已连接");
// PSI 种子从 (vault_seed, site) 派生 —— 同一 --seed 下两方自动取不同值,
// 否则 ECDH 私钥相同,PSI 的隐私性直接破坏(但交集仍会算对,很隐蔽)。
let psi_seed = derive_psi_seed(seed, &site);
let (aligned, vals) = sql_join::run(
&site,
&sites,
&mut transport,
&ids,
&cols,
&schema,
agg_col,
pred,
psi_seed,
seed, // Vault 种子:两方必须一致
fxp,
true,
)?;
note!(" 对齐后的键: {aligned:?}");
let mut rows: Vec<(&str, report::Cell)> =
vec![("aligned_rows", report::Cell::int(aligned.len() as i64))];
rows.extend(sql_join::result_cells(&vals));
report::kv("密态聚合结果(已 reveal)", &rows);
Ok(())
}
// ---------------------------------------------------------------------------
// nax psi
// ---------------------------------------------------------------------------
fn cmd_psi(args: &[String]) -> Result<(), String> {
let site = parse_flag(args, "--site").ok_or("缺少 --site")?.to_string();
let sites_raw = parse_flag(args, "--sites").ok_or("缺少 --sites")?;
let sites: Vec<String> = sites_raw
.split(',')
.map(|s| s.trim().to_string())
.filter(|s| !s.is_empty())
.collect();
if sites.len() < 2 {
return Err(format!("--sites 至少 2 方,得到 {} 个", sites.len()));
}
if !sites.contains(&site) {
return Err(format!("--site {site} 不在 --sites {sites:?} 里"));
}
let listen = parse_flag(args, "--listen");
let connect = parse_flag(args, "--connect");
let peers_raw = parse_flag(args, "--peers");
let base_seed = match parse_flag(args, "--seed") {
Some(h) => parse_seed(h)?,
None => [0u8; 32],
};
let ids_raw = parse_flag(args, "--ids").ok_or("缺少 --ids")?;
let mut ids: Vec<Vec<u8>> = Vec::new();
let mut id_values: Vec<u64> = Vec::new();
for tok in ids_raw.split(',') {
let tok = tok.trim();
if tok.is_empty() {
continue;
}
let v: u64 = tok.parse().map_err(|_| format!("--ids 里的 {tok:?} 不是非负整数"))?;
ids.push(nax_psi::id_from_u64(v));
id_values.push(v);
}
if ids.is_empty() {
return Err("--ids 为空".into());
}
// party 编号一律按**字典序**:`TcpMesh` 建的连接按这个顺序编号,
// 填错不会报错,只会把帧送到错误的人手里(表现为交集莫名不对)。
let mut sorted_sites = sites.clone();
sorted_sites.sort();
let my_idx = sorted_sites
.iter()
.position(|s| *s == site)
.ok_or_else(|| format!("--site {site} 不在 --sites 里"))?;
note!(
"nax psi · site={site}({}/{})· {} 个 ID",
my_idx + 1,
sites.len(),
ids.len()
);
let psk = parse_psk(args)?;
if psk.is_none() {
note!(" ⚠ 未配置 PSK(--psk-file / --psk / NAX_PSK):本次连接既不认证身份、也不加密链路");
}
// 三种连法,与 `nax node` 一致:两方 --connect / 两方 --listen / n 方 --listen + --peers
let transport = connect_any(
"PSI",
listen,
connect,
peers_raw,
&sorted_sites,
my_idx,
&psk,
)?;
// 种子按 site 派生:n 方共用同一个 --seed 也不会撞私钥(见 derive_psi_seed)
let cfg = PsiConfig {
site: site.clone(),
sites,
my_idx,
ids,
seed: derive_psi_seed(base_seed, &site),
// session 取共享的 --seed(全体一致);上面那把是每方不同的私钥种子
session: nax_psi::strict::session_id(&base_seed),
};
let idx = run_psi_session(transport, &cfg, true).map_err(|e| e.to_string())?;
// 交集按 ID 大小输出(`idx` 是本方 --ids 的下标序,不是数值序)
let mut hit: Vec<u64> = idx.iter().map(|&i| id_values[i]).collect();
hit.sort_unstable();
let rows: Vec<Vec<report::Cell>> = hit.iter().map(|v| vec![report::Cell::int(*v as i64)]).collect();
report::table(
&format!("交集 {} 条", hit.len()),
&["id"],
&rows,
);
Ok(())
}
// ---------------------------------------------------------------------------
// nax lr
// ---------------------------------------------------------------------------
fn cmd_lr(args: &[String]) -> Result<(), String> {
let site = parse_flag(args, "--site").ok_or("缺少 --site")?.to_string();
let sites_raw = parse_flag(args, "--sites").ok_or("缺少 --sites")?;
let sites: Vec<String> = sites_raw
.split(',')
.map(|s| s.trim().to_string())
.filter(|s| !s.is_empty())
.collect();
if sites.len() != 2 {
return Err(format!("LR 目前只支持两方,--sites 得到 {} 个", sites.len()));
}
if !sites.contains(&site) {
return Err(format!("--site {site} 不在 --sites {sites:?} 里"));
}
let listen = parse_flag(args, "--listen");
let connect = parse_flag(args, "--connect");
let addr = match (listen, connect) {
(Some(_), Some(_)) => return Err("--listen 与 --connect 只能选一个".into()),
(None, None) => return Err("必须给 --listen 或 --connect".into()),
(Some(a), None) | (None, Some(a)) => a.to_string(),
};
let seed = match parse_flag(args, "--seed") {
Some(h) => parse_seed(h)?,
None => [0u8; 32],
};
let fxp: u32 = parse_flag(args, "--fxp")
.unwrap_or("18")
.parse()
.map_err(|_| "--fxp 不是合法整数")?;
let n: usize = parse_flag(args, "--n")
.ok_or("缺少 --n")?
.parse()
.map_err(|_| "--n 不是合法整数")?;
let d: usize = parse_flag(args, "--d")
.ok_or("缺少 --d")?
.parse()
.map_err(|_| "--d 不是合法整数")?;
let epochs: usize = parse_flag(args, "--epochs")
.unwrap_or("40")
.parse()
.map_err(|_| "--epochs 不是合法整数")?;
let lr: f64 = parse_flag(args, "--lr")
.unwrap_or("0.5")
.parse()
.map_err(|_| "--lr 不是浮点")?;
let parse_f64_list = |name: &str| -> Result<Vec<f64>, String> {
let raw = parse_flag(args, name).ok_or(format!("缺少 {name}"))?;
raw.split(',')
.map(|t| t.trim().parse::<f64>().map_err(|_| format!("{name} 里的 {t:?} 不是浮点")))
.collect()
};
let x = parse_f64_list("--data-x")?;
let y = parse_f64_list("--data-y")?;
if x.len() != n * d {
return Err(format!("--data-x 长度 {} ≠ n×d = {}", x.len(), n * d));
}
if y.len() != n {
return Err(format!("--data-y 长度 {} ≠ n = {}", y.len(), n));
}
note!("nax lr · site={site} · {addr} · n={n} d={d} · {epochs} 轮 · lr={lr}");
let transport = if listen.is_some() {
note!(" 等待对端连接...");
TcpTransport::accept(&addr).map_err(|e| e.to_string())?
} else {
note!(" 连接对端...");
TcpTransport::connect(&addr, 50).map_err(|e| e.to_string())?
};
note!(" 已连接");
let cfg = LrConfig {
site: site.clone(),
sites,
seed,
fxp,
x,
n,
d,
y,
epochs,
lr,
};
let w = run_lr_session(transport, &cfg, true).map_err(|e| e.to_string())?;
let rows: Vec<Vec<report::Cell>> = w
.iter()
.enumerate()
.map(|(i, &v)| {
vec![
report::Cell::txt(format!("w[{i}]")),
report::Cell::nump(nax_core::ring::decode(v, fxp), 6),
]
})
.collect();
report::table(&format!("训练权重({} 个)", w.len()), &["权重", "值"], &rows);
Ok(())
}
// ---------------------------------------------------------------------------
// nax lr-vertical
// ---------------------------------------------------------------------------
/// `nax lr-vertical`:真纵向 LR —— 各方持不同客户、不同特征列,n 方。
///
/// 与 `nax lr` 的区别:那个是横向 demo(各方同列、行已对齐);
/// 这个从 PSI 开始 —— 行由求交决定、列由 `--col-blocks` 的公开 schema 定位。
///
/// # 两条通道
///
/// PSI 与密态会话必须走两条独立连接(帧的 op 不同,混在一条会串)。
/// 这里密态通道用 `--listen` / `--peers` 的**端口 +1**,少给两组参数。
fn cmd_lr_vertical(args: &[String]) -> Result<(), String> {
let site = parse_flag(args, "--site").ok_or("缺少 --site")?.to_string();
let sites_raw = parse_flag(args, "--sites").ok_or("缺少 --sites")?;
let mut sorted_sites: Vec<String> = sites_raw
.split(',')
.map(|s| s.trim().to_string())
.filter(|s| !s.is_empty())
.collect();
if sorted_sites.len() < 2 {
return Err(format!("--sites 至少 2 方,得到 {} 个", sorted_sites.len()));
}
if !sorted_sites.contains(&site) {
return Err(format!("--site {site} 不在 --sites {sorted_sites:?} 里"));
}
// party 编号 = 字典序,与 `TcpMesh` / `nax node` / `nax psi` 一致
sorted_sites.sort();
let my_idx = sorted_sites
.iter()
.position(|s| *s == site)
.ok_or_else(|| format!("--site {site} 不在 --sites 里"))?;
// ---- 列块清单:n 方纵向切分的定义 ----
let blocks_raw = parse_flag(args, "--col-blocks").ok_or(
"缺少 --col-blocks(各方列块,形如 alice:0:1,bob:1:1,carol:2:1)",
)?;
let mut blocks = parse_col_blocks(blocks_raw)?;
for b in &blocks {
if !sorted_sites.contains(&b.site) {
return Err(format!(
"--col-blocks 里的 {} 不在 --sites {sorted_sites:?} 里",
b.site
));
}
}
if blocks.len() != sorted_sites.len() {
return Err(format!(
"--col-blocks 有 {} 条,--sites 有 {} 个 —— 必须一一对应",
blocks.len(),
sorted_sites.len()
));
}
// 重排成与 sorted_sites 同序(party 下标即 blocks 下标)
blocks.sort_by_key(|b| {
sorted_sites
.iter()
.position(|s| s == &b.site)
.unwrap_or(usize::MAX)
});
let d_total: usize = blocks.iter().map(|b| b.len).sum();
let mine = blocks[my_idx].clone();
// ---- 数据 ----
let ids_raw = parse_flag(args, "--data-ids").ok_or("缺少 --data-ids")?;
let mut ids: Vec<Vec<u8>> = Vec::new();
for tok in ids_raw.split(',') {
let tok = tok.trim();
if tok.is_empty() {
continue;
}
let v: u64 = tok
.parse()
.map_err(|_| format!("--data-ids 里的 {tok:?} 不是非负整数"))?;
ids.push(nax_psi::id_from_u64(v));
}
if ids.is_empty() {
return Err("--data-ids 为空".into());
}
let n = ids.len();
let parse_f64_list = |name: &str| -> Result<Vec<f64>, String> {
let raw = parse_flag(args, name).ok_or(format!("缺少 {name}"))?;
raw.split(',')
.map(|t| {
t.trim()
.parse::<f64>()
.map_err(|_| format!("{name} 里的 {t:?} 不是浮点"))
})
.collect()
};
let x = parse_f64_list("--data-x")?;
if x.len() != n * mine.len {
return Err(format!(
"--data-x 长度 {} ≠ 样本数 {} × 本方列数 {}",
x.len(),
n,
mine.len
));
}
let label_owner =
parse_flag(args, "--label-owner").ok_or("缺少 --label-owner(标签由哪一方提供)")?;
if !sorted_sites.iter().any(|s| s == label_owner) {
return Err(format!(
"--label-owner {label_owner} 不在 --sites {sorted_sites:?} 里"
));
}
let y = if site == label_owner {
let v = parse_f64_list("--data-y")?;
if v.len() != n {
return Err(format!("--data-y 长度 {} ≠ 样本数 {n}", v.len()));
}
v
} else {
if parse_flag(args, "--data-y").is_some() {
return Err(format!(
"本方 {site} 不是 label_owner({label_owner}),不该给 --data-y —— \
多方都会加,标签会被重复计数"
));
}
Vec::new()
};
let fxp: u32 = parse_flag(args, "--fxp")
.unwrap_or("18")
.parse()
.map_err(|_| "--fxp 不是合法整数")?;
let epochs: usize = parse_flag(args, "--epochs")
.unwrap_or("40")
.parse()
.map_err(|_| "--epochs 不是合法整数")?;
let lr: f64 = parse_flag(args, "--lr")
.unwrap_or("0.3")
.parse()
.map_err(|_| "--lr 不是浮点")?;
let base_seed = match parse_flag(args, "--seed") {
Some(h) => parse_seed(h)?,
None => [0u8; 32],
};
let listen = parse_flag(args, "--listen");
let connect = parse_flag(args, "--connect");
let peers_raw = parse_flag(args, "--peers");
let vault_listen = listen.map(bump_port).transpose()?;
let vault_connect = connect.map(bump_port).transpose()?;
let vault_peers = peers_raw.map(bump_peers).transpose()?;
note!(
"nax lr-vertical · site={site}({}/{})· {n} 行 × {d_total} 列",
my_idx + 1,
sorted_sites.len()
);
note!(
" 本方列块 [{}, {}) · 标签方 {label_owner} · {} 轮 · lr={lr}",
mine.offset,
mine.end(),
epochs
);
let psk = parse_psk(args)?;
if psk.is_none() {
note!(" ⚠ 未配置 PSK(--psk-file / --psk / NAX_PSK):本次连接既不认证身份、也不加密链路");
}
// 两条通道按**同样顺序**建立:各方都在 PSI 建完后才建密态,
// 所以进度差被 PSI 的全互连握手挡住了,不会有一方提前等密态超时。
let psi_t = connect_any(
"PSI",
listen,
connect,
peers_raw,
&sorted_sites,
my_idx,
&psk,
)?;
let vault_t = connect_any(
"密态",
vault_listen.as_deref(),
vault_connect.as_deref(),
vault_peers.as_deref(),
&sorted_sites,
my_idx,
&psk,
)?;
let cfg = VerticalLrConfig {
site: site.clone(),
sites: sorted_sites.clone(),
seed: base_seed, // 密态主种子:全体必须一致
fxp,
ids,
psi_seed: derive_psi_seed(base_seed, &site),
x,
d_own: mine.len,
col_offset: mine.offset,
d_total,
blocks,
label_owner: label_owner.to_string(),
y,
epochs,
lr,
};
let (order, w) = run_lr_vertical_session(psi_t, vault_t, &cfg, true)
.map_err(|e| e.to_string())?;
let mut rows: Vec<(&str, report::Cell)> =
vec![("aligned_rows", report::Cell::int(order.len() as i64))];
rows.push((
"col_blocks",
report::Cell::txt(
sorted_sites
.iter()
.map(|s| s.as_str())
.collect::<Vec<_>>()
.join(","),
),
));
report::kv("纵向会话", &rows);
let wrows: Vec<Vec<report::Cell>> = w
.iter()
.enumerate()
.map(|(i, &v)| {
vec![
report::Cell::txt(format!("w[{i}]")),
report::Cell::nump(nax_core::ring::decode(v, fxp), 6),
]
})
.collect();
report::table(&format!("训练权重({} 个)", w.len()), &["权重", "值"], &wrows);
Ok(())
}
// ---------------------------------------------------------------------------
/// 生成可线性分离的合成数据:真实权重全 1、偏置 0,样本 x∈(0,1),
/// 标签 `y = 1` 当 `Σx > d/2`。确定性(由 `seed` 驱动)。
fn gen_fl_data(
k: usize,
d: usize,
per: usize,
seed: u64,
) -> std::collections::HashMap<String, ClientData> {
use nax_core::prg::Stream;
let mut sb = [0u8; 32];
sb[..8].copy_from_slice(&seed.to_le_bytes());
let mut s = Stream::new(&sb);
let mut out: std::collections::HashMap<String, ClientData> = std::collections::HashMap::new();
for c in 0..k {
let mut x = Vec::with_capacity(per);
let mut y = Vec::with_capacity(per);
for _ in 0..per {
let mut buf = [0u64; 32];
s.fill_u64(&mut buf);
let mut row = Vec::with_capacity(d);
let mut sum = 0.0;
for j in 0..d {
// u64 → [0,1) 浮点
let f = (buf[j] >> 11) as f64 / (1u64 << 53) as f64;
sum += f;
row.push(f);
}
y.push(if sum > d as f64 / 2.0 { 1.0 } else { 0.0 });
x.push(row);
}
out.insert(format!("c{c}"), ClientData { x, y });
}
out
}
fn cmd_fl(args: &[String]) -> Result<(), String> {
let k: usize = parse_flag(args, "--clients")
.unwrap_or("3")
.parse()
.map_err(|_| "--clients 不是整数")?;
let d: usize = parse_flag(args, "--features")
.unwrap_or("4")
.parse()
.map_err(|_| "--features 不是整数")?;
let per: usize = parse_flag(args, "--per-client")
.unwrap_or("40")
.parse()
.map_err(|_| "--per-client 不是整数")?;
let rounds: usize = parse_flag(args, "--rounds")
.unwrap_or("12")
.parse()
.map_err(|_| "--rounds 不是整数")?;
let local_epochs: usize = parse_flag(args, "--local-epochs")
.unwrap_or("2")
.parse()
.map_err(|_| "--local-epochs 不是整数")?;
let lr: f64 = parse_flag(args, "--lr")
.unwrap_or("0.5")
.parse()
.map_err(|_| "--lr 不是浮点")?;
let l2: f64 = parse_flag(args, "--l2")
.unwrap_or("0.0")
.parse()
.map_err(|_| "--l2 不是浮点")?;
let clip: f64 = parse_flag(args, "--clip")
.unwrap_or("0.0")
.parse()
.map_err(|_| "--clip 不是浮点")?;
let noise: f64 = parse_flag(args, "--noise")
.unwrap_or("0.0")
.parse()
.map_err(|_| "--noise 不是浮点")?;
let seed_bytes = match parse_flag(args, "--seed") {
Some(h) => parse_seed(h)?,
None => [0u8; 32],
};
let seed = u64::from_le_bytes(seed_bytes[0..8].try_into().unwrap());
if k < 1 {
return Err("--clients 至少为 1".into());
}
if d < 1 {
return Err("--features 至少为 1".into());
}
let data = gen_fl_data(k, d, per, seed.wrapping_add(0x9E3779B97F4A7C15));
let clients: Vec<String> = (0..k).map(|c| format!("c{c}")).collect();
let client_refs: Vec<&str> = clients.iter().map(|s| s.as_str()).collect();
note!(
"nax fl · 横向 FedAvg · {} 客户端 × {} 样本 × {} 特征 · {} 轮 · lr={} · 本地{}轮",
k, per, d, rounds, lr, local_epochs
);
let fa = FedAvg::new(&client_refs, d, clip, noise, 0.0, seed);
note!(" 聚合链: {}", fa.describe());
let (w, hist) = fa.fit(
&data, rounds, lr, local_epochs, l2, None, seed, 1,
);
// 逐轮曲线:一行一轮,JSON 模式下 jq 可以直接画图
let rows: Vec<Vec<report::Cell>> = (0..hist.rounds.len())
.map(|i| {
vec![
report::Cell::int(hist.rounds[i] as i64),
report::Cell::nump(hist.loss[i], 4),
report::Cell::nump(hist.acc[i], 4),
report::Cell::nump(hist.auc[i], 4),
]
})
.collect();
report::table("逐轮指标", &["轮次", "loss", "acc", "auc"], &rows);
let wr: Vec<Vec<report::Cell>> = w
.iter()
.enumerate()
.map(|(i, &v)| vec![report::Cell::txt(format!("w[{i}]")), report::Cell::nump(v, 6)])
.collect();
report::table(&format!("最终全局权重({} 个,含偏置)", w.len()), &["权重", "值"], &wr);
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
/// 各方 PSI 私钥必须不同 —— 同种子 = 同私钥,交集仍对但隐私全失
#[test]
fn psi_seed_differs_per_site() {
let base = [7u8; 32];
let a = derive_psi_seed(base, "alice");
let b = derive_psi_seed(base, "bob");
let c = derive_psi_seed(base, "carol");
assert_ne!(a, b, "alice 与 bob 派生出相同 PSI 种子");
assert_ne!(b, c, "bob 与 carol 派生出相同 PSI 种子");
assert_ne!(a, c, "alice 与 carol 派生出相同 PSI 种子");
// 同一 site 必须可复现(重连换私钥会让对照复现失效)
assert_eq!(a, derive_psi_seed(base, "alice"));
// 主种子参与派生
assert_ne!(a, derive_psi_seed([8u8; 32], "alice"));
// 不能让派生结果等于主种子:那样等于没派生
assert_ne!(a, base);
// n 方场景:即便方数很多,也不该出现碰撞
let seeds: std::collections::HashSet<[u8; 32]> = (0..64)
.map(|i| derive_psi_seed(base, &format!("site-{i}")))
.collect();
assert_eq!(seeds.len(), 64, "64 个不同站点名派生出重复种子");
}
/// 摘要算法错了会让 `--expect` 与 `sha256sum` 对不上,
/// 而那种错在自校验场景里等于「校验永远失败」,很难察觉是算法问题。
#[test]
fn sha256_file_matches_known_digest() {
let mut p = std::env::temp_dir();
p.push(format!("nax-selfcheck-{}.bin", std::process::id()));
std::fs::write(&p, b"abc").expect("写临时文件");
let (d, n) = sha256_file(&p).expect("算摘要");
let _ = std::fs::remove_file(&p);
assert_eq!(n, 3);
// FIPS 180-4 / NIST 向量:sha256("abc")
assert_eq!(
d,
"ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
);
}
fn v(s: &[&str]) -> Vec<String> {
s.iter().map(|x| x.to_string()).collect()
}
#[test]
fn report_flag_can_appear_anywhere() {
// 子命令后面
let (a, j) = split_report_flag(&v(&["fl", "--report", "json", "--rounds", "3"])).unwrap();
assert!(j);
assert_eq!(a, v(&["fl", "--rounds", "3"]));
// 子命令前面 + `=` 写法
let (a, j) = split_report_flag(&v(&["--report=json", "fl"])).unwrap();
assert!(j);
assert_eq!(a, v(&["fl"]));
// 显式 text 不改行为
let (a, j) = split_report_flag(&v(&["fl", "--report", "text"])).unwrap();
assert!(!j);
assert_eq!(a, v(&["fl"]));
// 缺值 / 乱值都要报错,而不是悄悄当 text
assert!(split_report_flag(&v(&["fl", "--report"])).is_err());
assert!(split_report_flag(&v(&["fl", "--report", "yaml"])).is_err());
}
}