OSX: Open Site Exchange

一、背景：

FATE1.X维护了多套通信架构，包括eggroll、spark+pulsar+nginx 、spark+rabbitmq+nginx。

下图为FATE1.X采用eggroll为计算引擎时的通信架构

下图为FATE1.X采用spark为计算引擎时的通信架构

如上所示，FATE1.X通信架构有一些弊端如下：

• 需要维护多套通信组件来支持不同的计算引擎
• 多种计算引擎组网困难，难以统一路由以及流控
• eggroll通信只支持同步rpc调用+流式传输，不支持消息队列类型的异步传输
• pulsar 以及rabbitmq等集群不易安装以及维护，程序不容易感知集群间传输时出现的网络异常
• 不容易对消息队列组件进行自定义开发等

为了解决以上问题，我们预备在FATE2.X中使用统一的通信组件OSX，统一支持不同计算引擎

二、OSX:

新组件特性：

• 传输接口兼容FATE1.X版本 FATE2.X版本

• 按照《金融业隐私计算互联互通平台技术规范》实现传输接口

• 支持多种计算引擎传输，包括eggroll、spark

• 传输模式支持rpc、消息队列

• 传输协议支持grpc（rpc、消息队列模式）、http1.1(消息队列模式)

• 支持作为exchange中心节点部署 ，支持FATE1.X 、FATE2.X 接入

• 路由配置与原eggroll基本一致，降低了移植难度

组件设计：

部署架构：

采用eggroll作为计算引擎时的部署架构:

上图为采用spark作为计算引擎时的部署架构:

与其他厂商互联互通互联互通

互联互通协议解析：

传输组件之间接口详解参见bfia-x.proto

算法与传输组件之间接口详解参见 bfia-y.proto

传输模式：

osx 支持两种传输模式：

• 流式（支持grpc，兼容FATE1.x版本传输，使用eggroll作为计算引擎）
• 队列（支持grpc、http1.x ，可以使用eggroll或者spark以及其他厂商计算引擎，按照《金融业隐私计算互联互通平台技术规范》实现的传输接口，推荐使用grpc协议，不同协议对应的路由表配置不一样，详情可见路由相关配置 ）

不同的传输模式使用不同的传输接口 ， 不需要在 osx中配置中指定，而是由FATE的配置决定，有多个参与方的情况下，双方需要预先商定使用的传输模式，只有在双方都使用一种传输模式的情况下才能正常工作。

配置：

以下为osx最简配置,配置文件位于 {部署目录}/conf/broker/broker.properties

grpc.port= 9377   （服务监听的grpc端口）
# （若使用eggroll作为计算引擎，此处填入eggroll cluster-manager 的ip）
eggroll.cluster.manager.ip = localhost
# （若使用eggroll作为计算引擎，此处填入eggroll cluster-manager 的端口）
eggroll.cluster.manager.port = 4670

全部配置：

路由：

路由配置相关文件为{部署目录}/conf/broker/route_table.json ，下面介绍在不使用证书的情况下的操作步骤：

，self_party=[“9999”]则代表本方partyId为9999，（若是与遵循互联互通协议的其他厂商隐私计算产品对接，此处对应于互联互通协议的nodeId）

本方partyId ：9999 （若是与遵循互联互通协议的其他厂商隐私计算产品对接，此处对应于互联互通协议的nodeId）

若对方partyId 为10000 （若是与遵循互联互通协议的其他厂商隐私计算产品对接，此处对应于互联互通协议的nodeId），则按照如下配置

{
  "route_table":
  {
    "9999":      //己方partyId 9999  ，  
    {
      "fateflow":[    //配置己方路由只需要配置fateflow 地址就可以，需要注意这里需要配置fateflow的grpc端口，默认是9360
        {
          "port": 9360,   
          "ip": "localhost"
        }
      ]
    },
    "10000":{  //对方partyId 10000
      "default":[{   //配置对方路由，只需要配置default 地址就可以  , 地址为对方的osx grpc端口
        "port": 9370,
        "ip": "192.168.xx.xx"  
      }]

    }
  },
  // self_party 为必填字段
	"self_party":[
		"9999"   //本方partyId 
	]
}

路由表修改之后不需要重启应用，系统会自动读取，需要保证该文件内容为可解析的json格式，否则会解析失败。

部署教程

1. 下载源码，打包机器需要安装好maven + jdk
2. 进入源码目录/deploy, 执行sh auto-package.sh, 执行完之后会在当前目录出现osx.tar.gz。

部署：

1. 部署机器需要安装jdk1.8+
2. 解压osx.tar.gz
3. 进入部署目录，执行sh service.sh start

日志分析

默认日志目录位于安装目录下 logs/broker 文件夹下，如下图所示

flow.log ： 记录请求日志

broker.log ： 记录所有日志

broker-error: 记录异常日志

broker-debug: debug日志默认不开启

正常启动后可以在broker.log中看到如下日志：

在收到请求后可以在flow.log中看到访问日志：

例如取其中几条日志分析

• 日志1

2023-11-27 23:53:42,320|grpc|1701100422_1009|MSG_REDIRECT|session:202311271901517083180_lr_0_0|topic:202311271901517083180_lr_0_0-host-10000-guest-9999-<dtype>-<dtype>|des:9999|code:E0000000000|cost:1|192.168.0.5:9370|size:224|msg:success

这条日志为使用队列模式传输时，osx收到了消息，且该osx不是该消息目的地时的日志，收到消息后osx采取的动作为MSG_REDIRECT，代表着将该消息传递至其他合作方。

它的格式为 时间戳|请求入口协议|流水号|处理动作|此次传输的sessionId|队列传输的topic|目的地partyId|返回码|耗时|目的地ip端口|传输数据大小|返回message

• 日志2

**2023-11-27 23:53:36,574|grpc|1701100416_9289|MSG_DOWNLOAD|session:202311271901517083180_lr_0_0|topic:202311271901517083180_lr_0_0-arbiter-10000-host-10000-g|offset-in-queue:100|des:10000|code:E0000000000|cost:0|size:2972|

这条日志为使用队列模式传输时，osx收到了消息，且该osx是该消息目的地时的日志，收到消息后osx采取的动作为MSG_DOWNLOAD，代表着将该消息本地持久化

它的格式为 时间戳|请求入口协议|流水号|处理动作|此次传输的sessionId|队列传输的topic|队列中消息数量|目的地partyId|返回码|耗时|数据大小|

• 日志3

2023-11-27 23:53:36,576|grpc|1701100416_7277|DEFUALT_CONSUME|session:202311271901517083180_lr_0_0|topic:202311271901517083180_lr_0_0-guest-9999-arbiter-10000-loss|req-offset:100|offset-in-queue:100|code:0|cost:0|

这条日志为使用队列模式传输时，osx收到了消费请求，osx采取的动作为DEFUALT_CONSUME，代表着从本地队列取出消息

它的格式为 时间戳|请求入口协议|流水号|处理动作|此次传输的sessionId|队列传输的topic|请求消费的序列号|队列中消息总数|返回码|耗时|

• 日志4

2023-11-27 23:54:23,318|grpc|UNARY_CALL|session:_fateflow_10000|topic:202311271901517083180|src:|des:10000|code:E0000000000|cost:18|127.0.0.1:9360|size:320|

这条日志为osx收到fateflow的请求，osx采取的动作为UNARY_CALL，代表着为fateflow所使用的接口

它的格式为 时间戳|请求入口协议|处理动作|此次传输的sessionId|topic|来源partid|目的partyId|返回码|目的地ip端口|数据大小|

• 日志5

2023-11-27 23:44:44,128|grpc|11|PUSH_REMOTE|session:202311271453035771030_sbt_0_0|topic:putBatch-__rsk#202311271453035771030_sbt_0_0#updated_data__table_persistent_0__#default.iterations-49.iterations-4#host#10000#guest#9999-12|src:10000|des:9999|code:E0000000000|cost:0|192.168.0.5:9370|size:90536|

这条日志为osx 在使用流式传输模式时，收到了流式传输请求，且osx不是该请求目的地，osx采取的动作为PUSH_REMOTE，代表着为将其请求转发至他处，其中的192.168.0.5:9370为目的地

• 日志6

2023-11-27 23:44:47,703|grpc|3|PUSH_EGGPAIR|session:202311271453035771030_sbt_0_0_host_10000|topic:putBatch-__rsk#202311271453035771030_sbt_0_0#new_sample_pos__table_persistent_0__#default.iterations-49.iterations-4#guest#9999#host#10000-1|code:E0000000000|cost:152|192.168.0.5:36110|size:98080|

这条日志为osx 在使用流式传输模式时，收到了流式传输请求，且osx为该请求目的地，osx采取的动作为PUSH_EGGPAIR，代表着为将其请求转发至eggroll 所启动的进程 eggpair，其中的192.168.0.5:36110为目的地

证书相关：

1） 方式一：使用keystore密码箱存储私钥、证书、信任证书方式（PS：生成证书命令详情文件：osx-tls.md）

OSX相关配置：

• grpcs：

  server端broker.property配置（使用keystore方式，即方式1）：

  # 打开grpcs server开关，并指定grpcs端口
  grpc.tls.port=9371
  open.grpc.tls.server= true
  # server端密码箱路径以及密码
  grpc.server.keystore.file= server/identity.jks 
  grpc.server.keystore.file.password= XXXXXX
  # server端信任证书keystore路径及密码
  grpc.server.trust.keystore.file= server/truststore.jks
  grpc.server.trust.keystore.file.password= XXXXXX
  

  相关client端路由表配置，在对应的partyid下面添加如下内容：

  "default": [
          {
            "protocol": "grpc",
            "keyStoreFile": "私钥密码箱绝对路径",
            "keyStorePassword": "私钥密码箱密码",
            "trustStoreFile": "信任证书绝对路径",
            "trustStorePassword": "信任证书密码",
            "useSSL": true,
            "useKeyStore" : true,
            "port": 9885,
            "ip": "127.0.0.1"
          }
        ]

• https：

  server端broker.property配置（使用keystore方式，即方式1）：

  # https端口
  https.port=8092
  # 打开https server开关
  open.https.server= true
  # keystore 类型
  http.ssl.trust.store.type=JKS
  # https server端密码箱路径以及密码
  https.server.keystore.file= server/identity.jks 
  https.server.keystore.file.password= XXXXXX
  # https server端信任证书keystore路径及密码
  https.server.trust.keystore.file= server/truststore.jks
  https.server.trust.keystore.file.password= XXXXXX
  

  相关client端路由表配置，在对应的partyid下面添加如下内容：

  "default": [
          {
            "protocol": "http",
            "url": "https://ip:8092/v1/interconn/chan/invoke",
            "keyStoreFile": "私钥密码箱绝对路径",
            "keyStorePassword": "私钥密码箱密码",
            "trustStoreFile": "信任证书绝对路径",
            "trustStorePassword": "信任证书密码",
            "useSSL": true,
            "useKeyStore" : true
          }
        ]

2）方式二：单独文件存储私钥、证书、信任证书方式（PS：生成证书命令详情文件：osx-tls.md）

OSX相关配置：

• grpcs：

  server端broker.property配置（使用非keystore方式，即方式2）：

  # 打开grpcs server开关，并指定grpcs端口
  grpc.tls.port=9371
  open.grpc.tls.server= true
  # server端公钥
  grpc.server.cert.chain.file= server.crt
  # sever端私钥
  grpc.server.private.key.file= server.pem
  # 信任证书
  grpc.server.ca.file= ca.crt
  

  相关client端路由表配置，在对应的partyid下面添加如下内容：

  "default": [
          {
            "protocol": "grpc",
            "certChainFile": "公钥路径",
            "privateKeyFile": "私钥路径",
            "caFile": "信任证书路径",
            "useSSL": true,
            "useKeyStore" : false,
            "port": 9371,
            "ip": "127.0.0.1"
          }
        ]

• https：

  server端broker.property配置（使用非keystore方式，即方式2）：

  # https端口
  https.port=8092
  # 打开https server开关
  open.https.server= true
  # server端公钥
  https.server.cert.chain.file= server.crt
  # sever端私钥
  https.server.private.key.file= server.pem
  # 信任证书
  https.server.ca.file= ca.crt

  相关client端路由表配置，在对应的partyid下面添加如下内容：

  "default": [
          {
            "protocol": "http",
            "url": "https://ip:8092/v1/interconn/chan/invoke",
            "certChainFile": "公钥路径",
            "privateKeyFile": "私钥路径",
            "caFile": "信任证书路径",
            "useSSL": true,
            "useKeyStore" : false
          }
        ]

常见问题：