最近在帮客户做隐私计算平台落地，底层用的是微众银行开源的 WeDPR v3.0，对接一条已经启用国密模式的 FISCO BCOS 链。本以为按照官方文档走一遍就行，结果硬是折腾了两天——官方文档压根没覆盖国密节点的适配配置，只能自己一个坑一个坑地填。

这篇文章就是我这两天踩坑的完整记录，希望后面有同学遇到同样的问题时能少走弯路。

另外说明一下，文中所有敏感信息都已经脱敏，你操作的时候记得替换成自己环境的实际值。本文基于 WeDPR v3.0.0 开源版本。

---

前言：为什么需要这篇文章？

先简单介绍下背景。WeDPR 是微众银行开源的一站式隐私计算方案，集成了隐私信息检索（PIR）、多方安全计算（MPC）、联邦学习（ML）这些核心能力。如果你在做金融或者政务场景，大概率会遇到这个项目。

官方文档（WeDPR 官方部署指南）写得很详细，标准部署流程跟着走基本没问题。但有一个关键缺失：官方文档完全没提到国密（SM2/SM3）区块链节点怎么适配。

在国内做金融、政务项目，国密算法是合规刚需，这不用我多说。但当你底层 FISCO BCOS 链开了国密模式之后，WeDPR 的部署远不是改个开关那么简单——配置不匹配、证书识别失败、依赖冲突，一个接一个。

这篇文章主要解决这几个问题：

• 国密节点适配的完整配置流程（基于实战经验）
• 官方文档没提到的 2 个关键修复点（都是血泪教训）
• 一键自动化部署脚本（文末附上）
• 完整的问题排查手册

如果你还没完成标准部署，建议先按照官方文档把基础环境搭好，再回来做国密适配。不然直接上国密容易把自己搞晕。

---

一、环境准备

1.1 基础环境要求

组件 版本要求 说明

操作系统 CentOS 7+ Ubuntu 18.04+ 推荐 Ubuntu 20.04 LTS
Docker 20.10+ 必须已安装并正常运行
Python 3.6+ 用于构建脚本
MySQL 5.7+ 或 8.0+ 需提前部署
Java OpenJDK 1.8+ 运行时依赖
内存 ≥ 8GB RAM 推荐 16GB
磁盘 ≥ 50GB 推荐 SSD

这里要特别提醒一点：开始之前务必确认你的 FISCO BCOS 链已经启用了国密模式（sm_crypto = true），并且已经生成了对应的 SM 证书。这个是前置条件，不然后面所有操作都是白搭。

1.2 检查环境

先把基础环境确认一遍：

docker --version && docker ps
python3 --version
mysql --version
java -version

1.3 下载部署脚本

如果还没下载 wedpr-builder，执行以下命令：

mkdir -p ~wedpr && cd ~wedpr

curl -#LO httpsgithub.comWeBankBlockchainWeDPRreleasesdownloadv3.0.0wedpr-builder.tar.gz 
  && tar -xvf wedpr-builder.tar.gz && cd wedpr-builder

pip3 install -i httpsmirrors.aliyun.compypisimple -r requirements.txt

1.4 部署隐私计算合约

按照官方文档的步骤，通过 FISCO BCOS 控制台部署 ResourceSequencer 和 ResourceLogRecordFactory 合约，并记录合约地址（后续配置需要用到）。

合约部署的详细步骤参考官方文档 - 部署隐私计算合约，这里就不重复了。

1.5 目录结构概览

先看下整体目录结构，后面改配置的时候心里有个数：

rootwedprwedpr-builder
├── config.toml                    # 主配置文件（国密适配的核心）
├── build_wedpr.py                 # 构建脚本
├── db                             # 数据库初始化脚本
├── wedpr_builder                  # 构建工具包
├── wedpr_generated                # 生成的配置目录
│   └── wedpr-example
│       ├── agency0                # 机构0 配置
│       │   └── server_ip
│       │       ├── wedpr-gateway
│       │       ├── wedpr-node
│       │       ├── wedpr-site
│       │       ├── wedpr-pir
│       │       ├── wedpr-mpc
│       │       ├── wedpr-model
│       │       └── wedpr-jupyter-worker
│       └── agency1                # 机构1 配置
│           └── server_ip
│               └── ...

---

二、国密配置（核心章节）

接下来的内容是整篇文章的重点，也是官方文档完全没覆盖的部分。请按顺序操作，别跳步。

2.1 编辑主配置文件（config.toml）

先把配置模板拷贝一份：

cp confconfig-example.toml config.toml

然后编辑 config.toml，国密相关的关键配置如下：

[env]
docker_mode = true

# Docker 镜像版本
wedpr_gateway_service_image_desc = fiscoorgwedpr-gateway-servicev3.0.0
wedpr_node_service_image_desc = fiscoorgwedpr-pro-node-servicev3.0.0
wedpr_mpc_service_image_desc = fiscoorgwedpr-mpc-servicev3.0.0
wedpr_jupyter_worker_image_desc = fiscoorgwedpr-jupyter-workerv3.0.0
wedpr_model_image_desc = fiscoorgwedpr-model-servicev3.0.0
wedpr_site_image_desc = fiscoorgwedpr-sitev3.0.0
wedpr_pir_image_desc = fiscoorgwedpr-pirv3.0.0

deploy_dir = wedpr-example

# 区块链配置
[blockchain]
blockchain_group = group0
blockchain_peers = [your_server_ip20200, your_server_ip20201]
blockchain_cert_path = sdk
recorder_factory_contract_address = your_recorder_contract_address
sequencer_contract_address = your_sequencer_contract_address

# ============================================
# 国密（SM）配置 —— 这是与官方文档的关键差异
# ============================================
[crypto]
gateway_disable_ssl = false    # 启用 SSL（国密场景必须）
sm_crypto = true               # 启用 SM 国密算法
gateway_sm_ssl = true          # Gateway 使用 SM SSL
rpc_sm_ssl = true              # RPC 使用 SM SSL

这里有个大坑要注意：官方文档的配置模板默认 sm_crypto = false，而且压根没提 [crypto] 段的完整配置。如果你的底层链是国密节点，上面这四个参数必须全部设为 true，一个都不能漏，否则证书识别失败、连接异常，各种报错能让你怀疑人生。

2.2 配置机构信息

[[agency]]
name = agency0
wedpr_api_token = 

    [agency.gateway]
    deploy_ip = [your_server_ip2]
    listen_ip = 0.0.0.0
    listen_port = 40300
    grpc_listen_ip = 0.0.0.0
    grpc_listen_port = 40600

    [agency.mysql]
    host = your_db_host
    port = 3306
    user = your_db_user
    password = your_db_password
    database = agency0

deploy_ip 里面那个 2 表示部署 2 个节点，你可以根据实际需求调整。多机构的配置也类似，改改 name 和数据库信息就行。

2.3 替换本机 IP

# 获取内网 IP
ifconfig

# 将配置中的 127.0.0.1 替换为实际内网 IP
sed -i 's127.0.0.1your_server_ipg' config.toml

2.4 生成所有组件配置

cd rootwedprwedpr-builder

for component in wedpr-gateway wedpr-node wedpr-site wedpr-pir wedpr-mpc wedpr-model wedpr-jupyter-worker; do
    echo  正在生成 $component 配置...
    python3 build_wedpr.py -t $component
done

echo  所有组件配置生成完毕！

---

三、国密适配修复（踩坑记录）

接下来这两步修复是我觉得整个部署过程中最坑的地方——不做的话服务直接起不来，而官方文档里一个字都没提。

3.1 修复一：wedpr-site 的 useSMCrypto 配置

问题现象：

File not found, path confca.crt

原因分析： 构建脚本生成的 wedpr-site 配置里，useSMCrypto 默认是 false，但实际用的又是 SM 证书，导致证书文件路径对不上。说白了就是构建脚本没考虑国密场景。

修复方法：

find wedpr-generated -name config.toml -path wedpr-siteconfconfig.toml 
  -exec sed -i 'suseSMCrypto = falseuseSMCrypto = true' {} ;

验证一下：

grep -r useSMCrypto wedpr-generatedwedpr-example  
   grep wedpr-site
# 应该全部显示：useSMCrypto = true

这里有个麻烦的地方：这是构建脚本本身的问题，每次重新跑 build_wedpr.py 之后都得重新执行一次这个修复。所以建议把这条命令记下来，或者直接写进自动化脚本里。

3.2 修复二：validation-api 版本冲突（启动后修复）

问题现象：

NoSuchMethodError javax.validation.BootstrapConfiguration.getClockProviderClassName()

原因分析： wedpr-site 镜像里面打包了 validation-api-1.1.0.Final.jar，跟运行时依赖的其他 validation-api 版本冲突了，Spring Boot 应用直接启动失败。这个问题挺无语的，属于镜像打包的依赖管理问题。

注意，这个修复得在容器启动之后才能操作（第四章部署完了再来），这里先记着，后面会用到。

---

四、服务部署

4.1 部署顺序

各服务之间有依赖关系，必须按下面这个顺序来，别乱：

Gateway → Node → PIR → MPC → Model → Jupyter-Worker → Site（最后）

4.2 部署 Agency0 服务

cd rootwedprwedpr-builder
G=wedpr-generatedwedpr-exampleagency0your_server_ip

# 1. Gateway
echo -e YnY  bash $Gwedpr-gatewaycreate_all_dockers.sh

# 2. Node
echo -e YnY  bash $Gwedpr-nodecreate_all_dockers.sh

# 3. PIR
echo -e YnY  bash $Gwedpr-pircreate_all_dockers.sh

# 4. MPC
echo -e Y  bash $Gwedpr-mpccreate_all_dockers.sh

# 5. Model
echo -e YnY  bash $Gwedpr-modelcreate_all_dockers.sh

# 6. Jupyter-Worker
echo -e Y  bash $Gwedpr-jupyter-workercreate_all_dockers.sh

# 7. Site（最后部署）
echo -e YnY  bash $Gwedpr-sitecreate_all_dockers.sh

4.3 部署 Agency1 服务

cd rootwedprwedpr-builder
G=wedpr-generatedwedpr-exampleagency1your_server_ip

echo -e YnY  bash $Gwedpr-gatewaycreate_all_dockers.sh
echo -e YnY  bash $Gwedpr-nodecreate_all_dockers.sh
echo -e YnY  bash $Gwedpr-pircreate_all_dockers.sh
echo -e Y    bash $Gwedpr-mpccreate_all_dockers.sh
echo -e YnY  bash $Gwedpr-modelcreate_all_dockers.sh
echo -e Y    bash $Gwedpr-jupyter-workercreate_all_dockers.sh
echo -e YnY  bash $Gwedpr-sitecreate_all_dockers.sh

---

五、启动后修复：validation-api 冲突

这里就是第三章提到的第二个修复了，容器起来之后赶紧处理。

5.1 移除冲突 JAR 并重启

# 对所有机构的 Site 容器执行修复
for agency in agency0 agency1; do
    for node in node0 node1; do
        container=${agency}-wedpr-site-wedpr.zone.default-${node}

        if docker ps  grep -q $container; then
            echo  修复 $container ...
            docker exec $container 
                mv datahomewedprwedpr-sitelibvalidation-api-1.1.0.Final.jar 
                    datahomewedprwedpr-sitelibvalidation-api-1.1.0.Final.jar.bak

            docker restart $container
            echo     [OK] 已修复并重启
        fi
    done
done

# 等待应用完全启动
sleep 15

---

六、验证部署

部署完了别急着走，先验证一下。

6.1 检查容器状态

# 查看所有 WeDPR 容器
docker ps --format table {{.Names}}t{{.Status}}

# 统计数量（预期 24 个，每个机构 12 个）
docker ps  grep wedpr  wc -l
docker ps  grep agency0  wc -l
docker ps  grep agency1  wc -l

6.2 测试 API 接口

# 测试公钥接口
curl httpyour_server_ip16002apiwedprv3pub
curl httpyour_server_ip26002apiwedprv3pub

# 测试验证码接口
curl httpyour_server_ip16002apiwedprv3pubcaptcha

预期结果：

• 公钥接口返回 JSON 格式的公钥数据（SM2 公钥）
• 验证码接口返回 accessKeyID 提示信息

6.3 检查应用日志

# 确认 Site 应用启动成功
docker exec agency0-wedpr-site-wedpr.zone.default-node0 
    grep Started WeDPRApplication 
    datahomewedprwedpr-sitelogswedpr-sitewedpr-site.log

# 检查 Gateway 运行状态
docker logs agency0-wedpr-gateway-wedpr.zone.default-node0  tail -20

# 检查 Site 端口监听
docker exec agency0-wedpr-site-wedpr.zone.default-node0 
    netstat -tlnp  grep 16000

6.4 国密验证专项

确认国密配置是否真的生效了：

# 检查 Gateway SSL 配置
docker exec agency0-wedpr-gateway-wedpr.zone.default-node0 
    cat datahomewedprwedpr-gatewayconfconfig.toml  grep -i smssl

# 检查 Site 国密配置
docker exec agency0-wedpr-site-wedpr.zone.default-node0 
    cat datahomewedprwedpr-siteconfconfig.toml  grep -i sm

---

七、访问与登录

7.1 Web 管理平台

机构 访问地址

Agency0 httpyour_server_ip16002
Agency1 httpyour_server_ip26002

7.2 默认登录信息

首次登录用默认账号，进去之后第一件事就是把密码改了：

用户名：admin
默认密码：请查看官方文档或初始化配置

生产环境千万别用默认密码，这是常识。

7.3 数据库连接参考

配置项 Agency0 Agency1

Host your_db_host your_db_host
Port 3306 3306
User your_db_user your_db_user
Database agency0 agency1

---

八、常见问题排查

我把部署过程中遇到的问题和解决方案整理了一下，方便后面查阅。

8.1 国密相关问题速查表

问题 现象 根因 解决方案

useSMCrypto 未修复 File not found, path confca.crt Site 配置未启用国密 第三章 3.1 节修复
SSL 证书不匹配 Gateway 启动失败，SSL 握手错误 crypto 段配置不完整 确保 [crypto] 四个参数均为 true
validation-api 冲突 NoSuchMethodError ...getClockProviderClassName() JAR 版本冲突 第三章 3.2 节 第五章修复
区块链连接失败 Node 无法连接链节点 国密链的证书路径配置错误 检查 blockchain_cert_path 和 SM 证书

8.2 应用启动失败

# 查看启动日志
docker exec container-name tail -50 datahomewedprwedpr-sitestart.out

# 搜索关键错误
docker exec container-name grep -i exceptionerror 
    datahomewedprwedpr-sitelogswedpr-sitewedpr-site.log  tail -20

8.3 无法连接到 Gateway

现象：Site 日志显示 connections to all backends failing

docker ps  grep gateway
docker logs agency0-wedpr-gateway-wedpr.zone.default-node0
docker exec agency0-wedpr-gateway-wedpr.zone.default-node0 
    netstat -tlnp  grep 40600
telnet your_server_ip 40600

解决方法：

docker restart agency0-wedpr-gateway-wedpr.zone.default-node0

# 或重新创建
docker rm -f agency0-wedpr-gateway-wedpr.zone.default-node0
echo Y  bash wedpr-generatedwedpr-exampleagency0your_server_ipwedpr-gatewaycreate_all_dockers.sh

8.4 验证码 API 返回 404

# 确认应用已完全启动
docker exec agency0-wedpr-site-wedpr.zone.default-node0 
    grep Started WeDPRApplication 
    datahomewedprwedpr-sitelogswedpr-sitewedpr-site.log

# 检查 nginx 配置
docker exec agency0-wedpr-site-wedpr.zone.default-node0 
    cat etcnginxnginx.conf  grep -A5 location api

大多数情况下就是应用还没完全启动，等个 10-15 秒就好了。

8.5 容器重启后配置丢失

现象：容器重启后 validation-api 问题又出现了。

解决方案：在容器启动脚本（create_docker.sh 或 start_docker.sh）里加上修复命令，或者干脆自己打一个镜像，把冲突的 JAR 包永久移除掉。个人推荐后一种方式，一劳永逸。

---

九、端口映射总结

这部分是端口规划参考，部署之前最好先确认端口没被占用。

9.1 Agency0 端口分配

服务 节点数 端口范围 说明

Gateway 2 40300-40301, 40600-40601 网关服务
Node 2 10200-10201, 40402-40403 计算节点
Site 2 16000-16005 Web 管理平台
PIR 2 17000-17004 隐私信息检索
MPC 1 20000 多方安全计算
Model 2 18000-18004 机器学习服务
Jupyter-Worker 1 19000-19120 Jupyter 计算节点

9.2 Agency1 端口分配

服务 节点数 端口范围 说明

Gateway 2 40320-40321, 40620-40621 网关服务
Node 2 10220-10221, 40422-40423 计算节点
Site 2 26000-26005 Web 管理平台
PIR 2 27000-27004 隐私信息检索
MPC 1 30000 多方安全计算
Model 2 28000-28004 机器学习服务
Jupyter-Worker 1 29000-29120 Jupyter 计算节点

9.3 端口规划原则

多机构部署的时候端口是按固定规则递增的，了解这个规则有助于你排查端口冲突：

服务类型 起始端口 每机构递增量

Gateway 40300+ 40600+ +20
Node RPC 10200+ +20
Node GRPC 40400+ +20
Site 16000+ +10000
PIR 17000+ +10000
MPC 20000+ +10000
Model 18000+ +10000
Jupyter 19000+ +10000

---

十、一键自动化部署脚本

如果你是要快速搭个测试环境，可以直接用下面这个脚本。不过生产环境我还是建议一步步手动来，出了问题好排查。

10.1 脚本内容

创建文件 auto_deploy_sm.sh：

#!binbash
set -e

echo =========================================
echo   WeDPR v3.0 国密节点自动部署脚本
echo =========================================

WORK_DIR=rootwedprwedpr-builder
cd $WORK_DIR

# 步骤 1 生成所有配置
echo 
echo 步骤 16 生成配置文件...
for component in wedpr-gateway wedpr-node wedpr-site wedpr-pir wedpr-mpc wedpr-model wedpr-jupyter-worker; do
    echo   - 生成 $component 配置...
    if python3 build_wedpr.py -t $component  devnull 2&1; then
        echo     [OK] $component
    else
        echo     [FAIL] $component
        exit 1
    fi
done

# 步骤 2 【国密修复】useSMCrypto 配置
echo 
echo 步骤 26 [国密修复] 修复 useSMCrypto 配置...
find wedpr-generated -name config.toml -path wedpr-siteconfconfig.toml 
    -exec sed -i 'suseSMCrypto = falseuseSMCrypto = true' {} ;
echo   [OK] useSMCrypto 已全部设为 true

# 步骤 3 部署服务
echo 
echo 步骤 36 部署 Docker 容器...
SERVER_IP=your_server_ip
for agency in agency0 agency1; do
    echo   - 部署 $agency ...

    services=(wedpr-gateway wedpr-node wedpr-pir wedpr-mpc wedpr-model wedpr-jupyter-worker wedpr-site)

    for service in ${services[@]}; do
        script_path=wedpr-generatedwedpr-example$agency$SERVER_IP$servicecreate_all_dockers.sh

        if [ ! -f $script_path ]; then
            echo     [SKIP] $service (脚本不存在)
            continue
        fi

        node_count=$(ls -d wedpr-generatedwedpr-example$agency$SERVER_IP$service 2devnull  wc -l)
        confirmations=$(printf 'Y%.0s' $(seq 1 $node_count))

        if echo $confirmations  bash $script_path  devnull 2&1; then
            echo     [OK] $service
        else
            echo     [FAIL] $service
        fi
        sleep 2
    done
done

# 步骤 4 等待容器启动
echo 
echo 步骤 46 等待容器启动...
sleep 10

# 步骤 5 【国密修复】validation-api 冲突
echo 
echo 步骤 56 [国密修复] 修复 validation-api 冲突...
for agency in agency0 agency1; do
    for node in node0 node1; do
        container=${agency}-wedpr-site-wedpr.zone.default-${node}
        if docker ps  grep -q $container; then
            docker exec $container 
                mv datahomewedprwedpr-sitelibvalidation-api-1.1.0.Final.jar 
                    datahomewedprwedpr-sitelibvalidation-api-1.1.0.Final.jar.bak 2devnull 
                && echo   [OK] $container 已修复 
                 echo   [SKIP] $container 无需修复
        fi
    done
done

# 步骤 6 重启 Site 容器
echo 
echo 步骤 66 重启 Site 容器...
for agency in agency0 agency1; do
    for node in node0 node1; do
        container=${agency}-wedpr-site-wedpr.zone.default-${node}
        if docker ps  grep -q $container; then
            docker restart $container  devnull 2&1
            echo   [OK] $container 已重启
        fi
    done
done

echo 
echo 等待应用启动（约 15 秒）...
sleep 15

# 验证部署
echo 
echo =========================================
echo   部署验证
echo =========================================

total=$(docker ps  grep wedpr  wc -l)
echo 容器状态 $total  24

if [ $total -eq 24 ]; then
    echo [OK] 所有容器已正常启动！
else
    echo [WARN] 部分容器未启动，请检查日志
fi

echo 
echo =========================================
echo   部署完成！
echo =========================================
echo 
echo 访问地址：
echo   - Agency0 httpyour_server_ip16002
echo   - Agency1 httpyour_server_ip26002

10.2 使用方法

chmod +x auto_deploy_sm.sh
.auto_deploy_sm.sh

---

附录

A. 国密 vs 非国密配置对比

配置项 非国密（默认） 国密（本文）

sm_crypto false true
gateway_sm_ssl false true
rpc_sm_ssl false true
gateway_disable_ssl true false
useSMCrypto（Site） false true

这张表就是这篇文章的核心价值所在——官方文档只给了你左边那一列的默认配置，右边这些国密配置全靠自己踩坑摸索出来的。

B. Docker 镜像清单

镜像名称 版本 用途

fiscoorgwedpr-gateway-service v3.0.0 网关服务
fiscoorgwedpr-pro-node-service v3.0.0 计算节点
fiscoorgwedpr-site v3.0.0 Web 管理平台
fiscoorgwedpr-pir v3.0.0 隐私信息检索
fiscoorgwedpr-mpc-service v3.0.0 多方安全计算
fiscoorgwedpr-model-service v3.0.0 机器学习
fiscoorgwedpr-jupyter-worker v3.0.0 Jupyter 计算节点

C. 数据库表结构概览

表名 说明

wedpr_user 用户表
wedpr_user_role 用户角色表
wedpr_group 用户组表
wedpr_group_detail 用户组详情表
wedpr_published_service 已发布服务表
wedpr_authorization_template_table 授权模板表

D. 日志文件位置

服务 日志路径

Site datahomewedprwedpr-sitelogswedpr-sitewedpr-site.log
启动日志 datahomewedprwedpr-sitestart.out
Gateway Node 容器标准输出（docker logs）

E. 常用运维命令

docker logs container-name                  # 查看日志
docker logs -f container-name               # 实时跟踪
docker exec -it container-name bash         # 进入容器
docker restart container-name               # 重启
docker stop container-name                  # 停止
docker rm -f container-name                 # 删除
docker stats container-name                 # 资源占用
docker ps  grep wedpr                        # 查看所有 WeDPR 容器

F. 参考资源

• GitHub 仓库：httpsgithub.comWeBankBlockchainWeDPR
• 官方文档：httpswedpr-document.readthedocs.io
• FISCO BCOS 文档：httpsfisco-bcos-documentation.readthedocs.io
• 问题反馈：GitHub Issues

---

文档信息

• 适用于：WeDPR v3.0.0 + 国密（SM2SM3）区块链节点
• 最后更新：2026-04-02
• 声明：本文基于开源版本实战经验整理，所有敏感配置已脱敏，请根据实际环境替换