单机模拟Kuscia多机部署点对点集群实践

单机搭建 kuscia多机部署点对点集群

官方文档：https://www.secretflow.org.cn/zh-CN/docs/kuscia/v1.0.0b0/deployment/Docker_deployment_kuscia/deploy_p2p_cn

官方文档写的是很详细的，不过它是基于多机进行部署的，然后搭建bob节点那没有详细写。这里我记录下，我用mac 单机来搭建kuscia 点对点集群。

注：文中步骤流程以及一些内容都是参照官方文档的。

1.前置准备

在部署 Kuscia 之前，请确保环境准备齐全，包括所有必要的软件、资源、操作系统版本和网络环境等满足要求，以确保部署过程顺畅进行，详情参考部署要求。

要求还是很低的，Docker 20.10.24及以上，有2G内存。节点默认使用 SQLite 作为存储，所以也不需要准备mysql。所以有了docker就可以直接开整啦。

2.部署流程（基于 TOKEN 认证）

新建一个kuscia文件夹，然后其中再新建两个文件夹alice和bob。后面就把这两个文件夹当作两个机器。

2.1 部署 alice 节点

到alice文件夹下打开一个终端窗口，后面所有在alice 节点的操作，都使用这个终端。

本文为叙述方便，假定节点 ID 为 alice ，对外可访问的 PORT 是 11080 。

指定 Kuscia 使用的镜像版本，这里使用 1.0.0b0 版本

1
export KUSCIA_IMAGE=secretflow-registry.cn-hangzhou.cr.aliyuncs.com/secretflow/kuscia:1.0.0b0

指定 Secretflow 版本：

1
export SECRETFLOW_IMAGE=secretflow-registry.cn-hangzhou.cr.aliyuncs.com/secretflow/secretflow-lite-anolis8:1.11.0b1

获取部署脚本，部署脚本会下载到当前目录：

1
docker pull ${KUSCIA_IMAGE} && docker run --rm ${KUSCIA_IMAGE} cat /home/kuscia/scripts/deploy/kuscia.sh > kuscia.sh && chmod u+x kuscia.sh

生成 alice 节点配置文件，kuscia init 参数请参考 Kuscia 配置文件：

1
docker run -it --rm ${KUSCIA_IMAGE} kuscia init --mode autonomy --domain "alice" > autonomy_alice.yaml 2>&1 || cat autonomy_alice.yaml

建议检查生成的文件，避免配置文件错误导致的部署启动问题。如果正常的话，alice文件夹下应当有这三个文件： kuscia.sh autonomy_alice.yaml {USER}-kuscia-autonomy-alice 。

启动节点，默认会在当前目录下创建 ${USER}-kuscia-autonomy-alice/data 目录用来存放 alice 的数据。部署节点需要使用 kuscia.sh 脚本并传入节点配置文件：

1
./kuscia.sh start -c autonomy_alice.yaml -p 11080 -k 11081

这里介绍下Kuscia 端口：

协议 端口号 说明 是否需要暴露给合作方 部署脚本对应参数
HTTP/HTTPS 1080 节点之间的认证鉴权端口。在创建节点之间路由时需要指定，可参考创建节点路由 是 -p
HTTP 80 访问节点中应用的端口。例如：可通过此端口访问 Serving 服务进行预测打分，可参考使用 SecretFlow Serving 进行预测 否 -q
HTTP/HTTPS 8082 节点 KusciaAPI 的访问端口，可参考如何使用 KusciaAPI 否 -k
GRPC/GRPCS 8083 节点 KusciaAPI 的访问端口，可参考如何使用 KusciaAPI 否 -g
HTTP 9091 节点 Metrics 指标采集端口，可参考 Kuscia 监控 否 -x

注意

  • 节点 ID 需要全局唯一并且符合 RFC 1123 标签名规则要求，详情请参考这里。default、kube-system 、kube-public 、kube-node-lease 、master 以及 cross-domain 为 Kuscia 预定义的节点 ID，不能被使用。
  • 目前 kuscia.sh 脚本仅支持导入 SecretFlow 镜像，scql、serving 以及其他自定义镜像请移步至注册自定义算法镜像
  • 如果节点之间的入口网络存在网关时，为了确保节点与节点之间通信正常，需要网关符合一些要求，详情请参考这里
  • alice、bob 节点默认使用 SQLite 作为存储，如果生产部署，需要配置链接到 MySQL 数据库的连接串，具体配置可以参考这里
  • 需要对合作方暴露的 Kuscia 端口，可参考 Kuscia 端口介绍。如果多个 Autonomy 节点部署在同一个物理机上，可以用 -p -k -g -q -x 参数指定下端口号（例如：./kuscia.sh start -c autonomy_alice.yaml -p 11080 -k 11081 -g 11082 -q 11083 -x 11084），防止出现端口冲突。
  • 非 root 用户部署请参考这里
  • 升级引擎镜像请参考指南

2.2 部署 bob 节点

一般这里可以在其他机器上部署bob节点。但是这里我们是学习和测试，论方便的话，还是在本机上部署。

我们假定节点 ID 为 bob ，对外可访问的 PORT 是 21080 。

到bob文件夹下打开一个终端窗口，然后执行以下操作

1
export KUSCIA_IMAGE=secretflow-registry.cn-hangzhou.cr.aliyuncs.com/secretflow/kuscia:1.0.0b0
1
export SECRETFLOW_IMAGE=secretflow-registry.cn-hangzhou.cr.aliyuncs.com/secretflow/secretflow-lite-anolis8:1.11.0b1
1
docker pull ${KUSCIA_IMAGE} && docker run --rm ${KUSCIA_IMAGE} cat /home/kuscia/scripts/deploy/kuscia.sh > kuscia.sh && chmod u+x kuscia.sh
1
docker run -it --rm ${KUSCIA_IMAGE} kuscia init --mode autonomy --domain "bob" > autonomy_bob.yaml 2>&1 || cat autonomy_bob.yaml
1
./kuscia.sh start -c autonomy_bob.yaml -q 280 -p 21080 -k 21081 -g28083 -x29091

步骤是一样的，区别在于这里的节点ID为 bob，然后我们需要区别指定端口，将alice所占用的端口都避开，不然启动不起来。

所以这里额外添加了 -q 280 -g28083 -x29091。

2.3 配置证书

在两个 Autonomy 节点建立通信之前，您需要先给这两个节点互换证书。

1）Alice 颁发证书给 Bob

在alice文件夹下终端进行以下操作

准备 Alice 的公钥，在 Alice 节点的机器上，可以看到包含公钥的 crt 文件：

1
docker cp ${USER}-kuscia-autonomy-alice:/home/kuscia/var/certs/domain.crt alice.domain.crt

将 alice 的公钥 alice.domain.crt 拷贝到 bob 容器的 /home/kuscia/var/certs/ 目录中：

1
docker cp alice.domain.crt ${USER}-kuscia-autonomy-bob:/home/kuscia/var/certs/

在 Bob 里添加 Alice 的证书等信息：

1
docker exec -it ${USER}-kuscia-autonomy-bob scripts/deploy/add_domain.sh alice p2p

2）Bob 颁发证书给 Alice

准备 Bob 的公钥，在 Bob 节点的机器上，可以看到包含公钥的 crt 文件：

1
docker cp ${USER}-kuscia-autonomy-bob:/home/kuscia/var/certs/domain.crt bob.domain.crt

将 Bob 的公钥 bob.domain.crt 拷贝到 alice 容器的 /home/kuscia/var/certs/ 目录中：

1
docker cp bob.domain.crt ${USER}-kuscia-autonomy-alice:/home/kuscia/var/certs/

在 Alice 里添加 Bob 的证书等信息：

1
docker exec -it ${USER}-kuscia-autonomy-alice scripts/deploy/add_domain.sh bob p2p

2.4 配置授权

如果要发起由两个 Autonomy 节点参与的任务，需要给这两个节点之间建立授权。

发起授权前，可以先试下网络通信是否畅通。可以进入到alice容器内，执行：

1
curl -kvvv https://192.168.231.196:21080

如果有如下响应，证明网络是畅通的。

1
{"domain":"bob","instance":"kxr-kuscia-autonomy-bob-kxrdemacbook-pro-local","kuscia":"v1.0.0b0","reason":"unauthorized."}

1）创建 Alice 到 Bob 的授权

1
docker exec -it ${USER}-kuscia-autonomy-alice scripts/deploy/join_to_host.sh alice bob https://192.168.231.196:21080

备注：这里的 192.168.231.196，请换成您本机的局域网ip。

2）创建 Bob 到 Alice 的授权

1
docker exec -it ${USER}-kuscia-autonomy-bob scripts/deploy/join_to_host.sh bob alice https://192.168.231.196:11080

备注：这里的 192.168.231.196，请换成您本机的局域网ip。

3）检查节点之间网络通信状态

  • 方法一：

    [Alice 终端] 执行以下命令：

    1
    docker exec -it ${USER}-kuscia-autonomy-alice kubectl get cdr alice-bob

    [Bob 终端] 执行以下命令：

    1
    docker exec -it ${USER}-kuscia-autonomy-bob kubectl get cdr bob-alice

当 “READR” 列为 “True” 时，说明 Alice 和 Bob 之间授权建立成功。

  • 方法二：

    [alice 机器] 执行以下命令：

    1
    docker exec -it ${USER}-kuscia-autonomy-alice kubectl get cdr alice-bob -o=jsonpath="{.status.tokenStatus.sourceTokens[*]}"

    [bob 机器] 执行以下命令：

    1
    docker exec -it ${USER}-kuscia-autonomy-bob kubectl get cdr bob-alice -o=jsonpath="{.status.tokenStatus.sourceTokens[*]}"

当命令执行成功得到返回结果时表示授权成功

3.准备测试数据

  • Alice 节点准备测试数据

    登录到安装 Alice 的机器上（alice文件夹下终端），将默认的测试数据拷贝到之前部署目录的 ${USER}-kuscia-autonomy-alice/data 下

    1
    2
    3
    docker pull ${KUSCIA_IMAGE} && docker run --rm ${KUSCIA_IMAGE} cat /home/kuscia/var/storage/data/alice.csv > /tmp/alice.csv
    docker cp /tmp/alice.csv ${USER}-kuscia-autonomy-alice:/home/kuscia/var/storage/data/
    rm -rf /tmp/alice.csv

    为 Alice 的测试数据创建 domaindata

    1
    docker exec -it ${USER}-kuscia-autonomy-alice scripts/deploy/create_domaindata_alice_table.sh alice

    为 Alice 的测试数据创建 domaindatagrant

    1
    2
    3
    4
    5
    6
    docker exec -it ${USER}-kuscia-autonomy-alice curl -X POST 'https://127.0.0.1:8082/api/v1/domaindatagrant/create' --header "Token: $(docker exec -it ${USER}-kuscia-autonomy-alice cat /home/kuscia/var/certs/token)" --header 'Content-Type: application/json' -d '{
     "grant_domain": "bob",
     "description": {"domaindatagrant":"alice-bob"},
     "domain_id": "alice",
     "domaindata_id": "alice-table"
    }' --cacert /home/kuscia/var/certs/ca.crt --cert /home/kuscia/var/certs/ca.crt --key /home/kuscia/var/certs/ca.key

  • Bob 节点准备测试数据

    登录到安装 Bob 的机器上，将默认的测试数据拷贝到之前部署目录的 ${USER}-kuscia-autonomy-alice/data 下

    1
    2
    3
    docker pull ${KUSCIA_IMAGE} && docker run --rm ${KUSCIA_IMAGE} cat /home/kuscia/var/storage/data/bob.csv > /tmp/bob.csv
    docker cp /tmp/bob.csv ${USER}-kuscia-autonomy-bob:/home/kuscia/var/storage/data/
    rm -rf /tmp/bob.csv

    为 Bob 的测试数据创建 domaindata

    1
    docker exec -it ${USER}-kuscia-autonomy-bob scripts/deploy/create_domaindata_bob_table.sh bob

    为 Bob 的测试数据创建 domaindatagrant

    1
    2
    3
    4
    5
    6
    docker exec -it ${USER}-kuscia-autonomy-bob curl -X POST 'https://127.0.0.1:8082/api/v1/domaindatagrant/create' --header "Token: $(docker exec -it ${USER}-kuscia-autonomy-bob cat /home/kuscia/var/certs/token)" --header 'Content-Type: application/json' -d '{
     "grant_domain": "alice",
     "description": {"domaindatagrant":"bob-alice"},
     "domain_id": "bob",
     "domaindata_id": "bob-table"
    }' --cacert /home/kuscia/var/certs/ca.crt --cert /home/kuscia/var/certs/ca.crt --key /home/kuscia/var/certs/ca.key

4.执行作业

创建并启动作业（两方 PSI 任务）, 以 Alice 节点机器上执行命令为例

1
docker exec -it ${USER}-kuscia-autonomy-alice scripts/user/create_example_job.sh

查看作业状态

1
docker exec -it ${USER}-kuscia-autonomy-alice kubectl get kj -n cross-domain

作业结果：

1
2
3
4
5
6
(base) kxr@kxrdeMacBook-Pro alice % docker exec -it ${USER}-kuscia-autonomy-alice kubectl get kj -n cross-domain
NAME                             STARTTIME   COMPLETIONTIME   LASTRECONCILETIME   PHASE
secretflow-task-20250928151824   8s                           8s                  Running
(base) kxr@kxrdeMacBook-Pro alice % docker exec -it ${USER}-kuscia-autonomy-alice kubectl get kj -n cross-domain
NAME                             STARTTIME   COMPLETIONTIME   LASTRECONCILETIME   PHASE
secretflow-task-20250928151824   5m8s        4m29s            4m29s               Succeeded