WeDPR v3.0 适配国密（SM）区块链节点部署实战：填坑官方文档未覆盖的配置

声明：本文基于 WeDPR v3.0.0 开源版本的实战部署经验整理。文中所有敏感信息均已脱敏处理，请根据实际环境替换相应配置。

目录

• 前言：为什么需要这篇文章？
• 一、环境准备
• • 1.1 基础环境要求
  • 1.2 检查环境
  • 1.3 下载部署脚本
  • 1.4 部署隐私计算合约
  • 1.5 目录结构概览
• 二、国密配置（核心章节）
• • 2.1 编辑主配置文件（config.toml）
  • 2.2 配置机构信息
  • 2.3 替换本机 IP
  • 2.4 生成所有组件配置
• 三、国密适配修复（踩坑记录）
• • 3.1 修复一：wedpr-site 的 useSMCrypto 配置
  • 3.2 修复二：validation-api 版本冲突（启动后修复）
• 四、服务部署
• • 4.1 部署顺序
  • 4.2 部署 Agency0 服务
  • 4.3 部署 Agency1 服务
• 五、启动后修复：validation-api 冲突
• • 5.1 移除冲突 JAR 并重启
• 六、验证部署
• • 6.1 检查容器状态
  • 6.2 测试 API 接口
  • 6.3 检查应用日志
  • 6.4 国密验证专项
• 七、访问与登录
• • 7.1 Web 管理平台
  • 7.2 默认登录信息
  • 7.3 数据库连接参考
• 八、常见问题排查
• • 8.1 国密相关问题速查表
  • 8.2 应用启动失败
  • 8.3 无法连接到 Gateway
  • 8.4 验证码 API 返回 404
  • 8.5 容器重启后配置丢失
• 九、端口映射总结
• • 9.1 Agency0 端口分配
  • 9.2 Agency1 端口分配
  • 9.3 端口规划原则
• 十、一键自动化部署脚本
• • 10.1 脚本内容
  • 10.2 使用方法
• 附录
• • A. 国密 vs 非国密配置对比
  • B. Docker 镜像清单
  • C. 数据库表结构概览
  • D. 日志文件位置
  • E. 常用运维命令
  • F. 参考资源

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

WeDPR 是由微众银行开源的一站式隐私计算解决方案，集成了隐私信息检索（PIR）、多方安全计算（MPC）、联邦学习（ML） 等核心能力。

官方文档（WeDPR 官方部署指南）详细介绍了标准部署流程，但存在一个重要缺失：

⚠️ 官方文档未覆盖国密（SM2/SM3）区块链节点的适配配置。

在国内金融、政务等场景中，国密算法是合规刚需。当底层 FISCO BCOS 链启用国密模式后，WeDPR 的部署并非"改个开关"那么简单——你会遇到一系列配置不匹配、证书识别失败、依赖冲突等问题。

本文的价值：

• 基于实际踩坑经验，梳理国密节点适配的完整流程
• 指出官方文档未提及的 2 个关键配置修复点
• 提供一键自动化部署脚本
• 附带完整的问题排查手册

💡 阅读建议：如果你还没有完成标准部署，建议先按照 官方文档 完成基础环境搭建，再回到本文进行国密适配。

一、环境准备

1.1 基础环境要求

⚠️ 国密前置条件：确保你的 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 https://github.com/WeBankBlockchain/WeDPR/releases/download/v3.0.0/wedpr-builder.tar.gz \\
&& tar -xvf wedpr-builder.tar.gz && cd wedpr-builder

pip3 install -i https://mirrors.aliyun.com/pypi/simple -r requirements.txt

1.4 部署隐私计算合约

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

📖 合约部署的详细步骤请参考 官方文档 – 部署隐私计算合约，此处不再赘述。

1.5 目录结构概览

/root/wedpr/wedpr-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 conf/config-example.toml config.toml

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

[env]
docker_mode = true

# Docker 镜像版本
wedpr_gateway_service_image_desc = "fiscoorg/wedpr-gateway-service:v3.0.0"
wedpr_node_service_image_desc = "fiscoorg/wedpr-pro-node-service:v3.0.0"
wedpr_mpc_service_image_desc = "fiscoorg/wedpr-mpc-service:v3.0.0"
wedpr_jupyter_worker_image_desc = "fiscoorg/wedpr-jupyter-worker:v3.0.0"
wedpr_model_image_desc = "fiscoorg/wedpr-model-service:v3.0.0"
wedpr_site_image_desc = "fiscoorg/wedpr-site:v3.0.0"
wedpr_pir_image_desc = "fiscoorg/wedpr-pir:v3.0.0"

deploy_dir = "wedpr-example"

# 区块链配置
[blockchain]
blockchain_group = "group0"
blockchain_peers = ["<your_server_ip>:20200", "<your_server_ip>:20201"]
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_ip>:2"]
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 's/127.0.0.1/<your_server_ip>/g' config.toml

2.4 生成所有组件配置

cd /root/wedpr/wedpr-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: conf/ca.crt

原因分析：构建脚本生成的 wedpr-site 配置中，useSMCrypto 默认为 "false"，但实际使用的是 SM 证书，导致证书文件路径不匹配。

修复方法：

find wedpr-generated -name "config.toml" -path "*/wedpr-site/*/conf/config.toml" \\
-exec sed -i 's/useSMCrypto = "false"/useSMCrypto = "true"/' {} \\;

验证修复：

grep -r "useSMCrypto" wedpr-generated/wedpr-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 /root/wedpr/wedpr-builder
G="wedpr-generated/wedpr-example/agency0/<your_server_ip>"

# 1. Gateway
echo -e "Y\\nY" | bash $G/wedpr-gateway/create_all_dockers.sh

# 2. Node
echo -e "Y\\nY" | bash $G/wedpr-node/create_all_dockers.sh

# 3. PIR
echo -e "Y\\nY" | bash $G/wedpr-pir/create_all_dockers.sh

# 4. MPC
echo -e "Y" | bash $G/wedpr-mpc/create_all_dockers.sh

# 5. Model
echo -e "Y\\nY" | bash $G/wedpr-model/create_all_dockers.sh

# 6. Jupyter-Worker
echo -e "Y" | bash $G/wedpr-jupyter-worker/create_all_dockers.sh

# 7. Site（最后部署）
echo -e "Y\\nY" | bash $G/wedpr-site/create_all_dockers.sh

4.3 部署 Agency1 服务

cd /root/wedpr/wedpr-builder
G="wedpr-generated/wedpr-example/agency1/<your_server_ip>"

echo -e "Y\\nY" | bash $G/wedpr-gateway/create_all_dockers.sh
echo -e "Y\\nY" | bash $G/wedpr-node/create_all_dockers.sh
echo -e "Y\\nY" | bash $G/wedpr-pir/create_all_dockers.sh
echo -e "Y" | bash $G/wedpr-mpc/create_all_dockers.sh
echo -e "Y\\nY" | bash $G/wedpr-model/create_all_dockers.sh
echo -e "Y" | bash $G/wedpr-jupyter-worker/create_all_dockers.sh
echo -e "Y\\nY" | bash $G/wedpr-site/create_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 /data/home/wedpr/wedpr-site/lib/validation-api-1.1.0.Final.jar \\
/data/home/wedpr/wedpr-site/lib/validation-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 http://<your_server_ip>:16002/api/wedpr/v3/pub
curl http://<your_server_ip>:26002/api/wedpr/v3/pub

# 测试验证码接口
curl http://<your_server_ip>:16002/api/wedpr/v3/pub/captcha

预期结果：

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

6.3 检查应用日志

# 确认 Site 应用启动成功
docker exec agency0-wedpr-site-wedpr.zone.default-node0 \\
grep "Started WeDPRApplication" \\
/data/home/wedpr/wedpr-site/logs/wedpr-site/wedpr-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 /data/home/wedpr/wedpr-gateway/conf/config.toml | grep -i "sm\\|ssl"

# 检查 Site 国密配置
docker exec agency0-wedpr-site-wedpr.zone.default-node0 \\
cat /data/home/wedpr/wedpr-site/conf/config.toml | grep -i "sm"

七、访问与登录

7.1 Web 管理平台

7.2 默认登录信息

首次登录使用默认账号，登录后请立即修改密码：

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

⚠️ 安全提醒：默认密码仅用于首次部署验证，生产环境务必修改为强密码！

7.3 数据库连接参考

八、常见问题排查

8.1 国密相关问题速查表

8.2 应用启动失败

# 查看启动日志
docker exec <container-name> tail -50 /data/home/wedpr/wedpr-site/start.out

# 搜索关键错误
docker exec <container-name> grep -i "exception\\|error" \\
/data/home/wedpr/wedpr-site/logs/wedpr-site/wedpr-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-generated/wedpr-example/agency0/<your_server_ip>/wedpr-gateway/create_all_dockers.sh

8.4 验证码 API 返回 404

# 确认应用已完全启动
docker exec agency0-wedpr-site-wedpr.zone.default-node0 \\
grep "Started WeDPRApplication" \\
/data/home/wedpr/wedpr-site/logs/wedpr-site/wedpr-site.log

# 检查 nginx 配置
docker exec agency0-wedpr-site-wedpr.zone.default-node0 \\
cat /etc/nginx/nginx.conf | grep -A5 "location /api"

💡 大多数情况下只需等待应用完全启动（约 10-15 秒）。

8.5 容器重启后配置丢失

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

解决方案：在容器启动脚本（create_docker.sh 或 start_docker.sh）中添加修复命令，或在自定义镜像中永久移除冲突的 JAR 包。

九、端口映射总结

9.1 Agency0 端口分配

9.2 Agency1 端口分配

9.3 端口规划原则

多机构部署时端口递增规则：

十、一键自动化部署脚本

💡 适合快速搭建测试环境，生产环境建议逐步手动部署以便排查问题。

10.1 脚本内容

创建文件 auto_deploy_sm.sh：

#!/bin/bash
set -e

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

WORK_DIR="/root/wedpr/wedpr-builder"
cd "$WORK_DIR"

# 步骤 1: 生成所有配置
echo ""
echo "步骤 1/6: 生成配置文件…"
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 > /dev/null 2>&1; then
echo " [OK] $component"
else
echo " [FAIL] $component"
exit 1
fi
done

# 步骤 2: 【国密修复】useSMCrypto 配置
echo ""
echo "步骤 2/6: [国密修复] 修复 useSMCrypto 配置…"
find wedpr-generated -name "config.toml" -path "*/wedpr-site/*/conf/config.toml" \\
-exec sed -i 's/useSMCrypto = "false"/useSMCrypto = "true"/' {} \\;
echo " [OK] useSMCrypto 已全部设为 true"

# 步骤 3: 部署服务
echo ""
echo "步骤 3/6: 部署 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-generated/wedpr-example/$agency/$SERVER_IP/$service/create_all_dockers.sh"

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

node_count=$(ls -d "wedpr-generated/wedpr-example/$agency/$SERVER_IP/$service"/* 2>/dev/null | wc -l)
confirmations=$(printf 'Y%.0s' $(seq 1 $node_count))

if echo "$confirmations" | bash "$script_path" > /dev/null 2>&1; then
echo " [OK] $service"
else
echo " [FAIL] $service"
fi
sleep 2
done
done

# 步骤 4: 等待容器启动
echo ""
echo "步骤 4/6: 等待容器启动…"
sleep 10

# 步骤 5: 【国密修复】validation-api 冲突
echo ""
echo "步骤 5/6: [国密修复] 修复 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 /data/home/wedpr/wedpr-site/lib/validation-api-1.1.0.Final.jar \\
/data/home/wedpr/wedpr-site/lib/validation-api-1.1.0.Final.jar.bak 2>/dev/null \\
&& echo " [OK] $container 已修复" \\
|| echo " [SKIP] $container 无需修复"
fi
done
done

# 步骤 6: 重启 Site 容器
echo ""
echo "步骤 6/6: 重启 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" > /dev/null 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: http://<your_server_ip>:16002"
echo " – Agency1: http://<your_server_ip>:26002"

10.2 使用方法

chmod +x auto_deploy_sm.sh
./auto_deploy_sm.sh

附录

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

💡 这张对比表就是本文的核心价值——官方文档只给出了左侧的默认配置，右侧的国密配置需要靠自己摸索。

B. Docker 镜像清单

C. 数据库表结构概览

D. 日志文件位置

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 仓库：https://github.com/WeBankBlockchain/WeDPR
• 官方文档：https://wedpr-document.readthedocs.io/
• FISCO BCOS 文档：https://fisco-bcos-documentation.readthedocs.io/
• 问题反馈：GitHub Issues

文档信息

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