1. 平台搭建前的整体认知与思路拆解先说结论WeBASEWeBank Blockchain Service Enhancement是微众银行开源的区块链中间件平台定位是降低 FISCO BCOS 链的运维和开发门槛。它不是一个单一体服务而是一组子系统的集合包括前置服务WeBASE-Front、节点管理服务WeBASE-Node-Manager、WeBASE-Web、签名服务WeBASE-Sign、交易服务WeBASE-Transaction等。很多人第一次搭建时被“WeBASE 管理平台”这个名字误导以为装一个包就完事结果在依赖关系上踩了一堆坑。这篇文章我就按实际部署顺序把我自己反复装过几轮后整理的完整流程、报错对照和排错思路写出来给准备搭管理平台的朋友一个可以直接照着做的参考。1.1 先搞清楚 WeBASE 管理平台到底由哪几块组成在动手之前先把架构看清楚后面排查问题时你会省很多力气。WeBASE 管理平台最核心的调用链是这样的用户在浏览器打开 WeBASE-Web 页面页面请求 Node-Manager 服务Node-Manager 再通过 WeBASE-Front 与区块链节点通信最终把交易发到 FISCO BCOS 链上。签名服务 WeBASE-Sign 负责私钥管理和交易签名属于可选但强烈建议安装的组件因为在 webase 里发交易、部署合约都绕不开签名。如果你只用“节点管理 控制台”这种最简模式可以只装 Front 和 Web 吗可以但功能会缺失一块。我的建议是生产环境直接按全套装开发环境至少装 Node-Manager Front Web 三件套。原因在于管理平台的核心价值就是把“部署合约、发交易、查交易、管理私钥”这些操作图形化少一个服务业务流程就断一截。另外要注意版本匹配问题。WeBASE 各子系统的版本号需要和 FISCO BCOS 链的版本匹配具体版本对应关系在官方文档里有表格。我自己踩过的最痛的一次就是链用的是 2.7.2装上 1.5.x 的 WeBASE 后Front 怎么都连不上节点后来才发现版本不匹配换回 1.4.x 后重启即通。1.2 为什么推荐先在测试环境完整走一遍流程很多人拿到部署文档直接在生产服务器上开搞遇到问题边搜边改最后服务起来了但中间过程改了什么、为什么改完全没有记录。等下次扩容或者迁移环境又要把坑重新踩一遍。我的习惯是先在本地虚拟机或一台临时服务器上走完整流程确认所有步骤无误后再上生产。这不是浪费时间反而是最省时间的方式。测试环境建议准备一台 4C8G 的虚拟机操作系统选 CentOS 7.9 或 Ubuntu 20.04 都行。内存低于 4G 的话跑起 MySQL 多个 Java 服务会非常吃力频繁出现 OOM 或者服务假死。硬盘 50G 以上因为区块链节点数据会持续增长WeBASE 各服务的日志也会占空间。整个 WeBASE 会拉起来的服务数量不少如果网络下载依赖包很慢建议提前配好国内镜像源后面我会具体说。2. 环境准备阶段的高频踩坑点2.1 JDK 版本选择别用 Java 8 的最新小版本也别用 Java 11WeBASE 各子服务是基于 Java 开发的官方推荐 JDK 8。这里有个容易踩的坑如果你系统里装的是 JDK 11某些旧版本 WeBASE 服务启动时会出现奇怪的类加载报错比如java.lang.NoClassDefFoundError: javax/xml/bind/JAXBException。这是因为 JDK 11 把 Java EE 模块移除了而旧版 WeBASE 依赖这部分类库。解决思路有两个方向一是装回 JDK 8这是最省心的方案二是如果开发机有其他项目依赖 JDK 11可以考虑用 Docker 方式跑 WeBASE这样 JDK 版本隔离在容器里不影响宿主机其他应用。我第一次搭建时就在 JDK 版本上折腾了半个多小时后来老老实实装了 OpenJDK 8问题立刻消失。验证 JDK 是否装好用java -version命令看到输出中包含1.8.0_xxx字样才算对。另外别忘了配JAVA_HOME环境变量很多启动脚本会读取这个变量不配会直接启动失败。2.2 MySQL 版本与初始化配置的坑WeBASE 的 Node-Manager 服务和签名服务都需要 MySQL 存储数据。官方推荐 MySQL 5.7 或 8.0。这里我重点说三个高频问题第一个问题是数据库初始化脚本执行报错。WeBASE 的脚本会自动建库但如果你手动用 Navicat 之类工具执行 SQL 文件很可能会遇到表名大小写问题。MySQL 在 Linux 下默认区分大小写而 WeBASE 的建表语句是混合大小写的如果你的 MySQL 配置了lower_case_table_names0执行脚本时会出现找不到表的报错。解决方案是在/etc/my.cnf的[mysqld]段加上lower_case_table_names1然后重启 MySQL。这一点在官方文档里写得不明显我是在多次重试执行初始化脚本失败后才定位到的。第二个问题是 MySQL 8.0 的认证插件兼容性。WeBASE 早期版本用 MySQL 5.7 开发测试如果用 MySQL 8.0需要手动确认用户的认证插件是caching_sha2_password还是mysql_native_password。Webase 服务连接数据库时如果报Authentication plugin caching_sha2_password cannot be loaded就需要执行下面这个命令把认证插件改回来ALTER USER webase% IDENTIFIED WITH mysql_native_password BY 你的密码; FLUSH PRIVILEGES;第三个问题是数据库连接数限制。WeBASE 多个服务同时连接 MySQL默认连接数 151 偶尔不够用服务启动时偶尔报Too many connections。解决方案是在配置文件中调大 max_connections比如改成 500。2.3 端口规划与防火墙放行的必要性WeBASE 全家桶涉及大量端口我在下面的表里做了整理方便你提前规划好防火墙策略服务默认端口说明WeBASE-Web5000前端管理页面浏览器访问WeBASE-Node-Manager5001核心管理后端服务WeBASE-Front5002节点前置服务WeBASE-Sign5004签名服务WeBASE-Transaction5005交易服务MySQL3306数据库服务FISCO BCOS 节点20200/20201节点 Channel 端口和 P2P 端口如果你在云服务器上部署需要到云控制台的安全组里放行这些端口如果是本地虚拟机需要检查防火墙。CentOS 7 上常用命令是firewall-cmd --permanent --add-port5000/tcp firewall-cmd --permanent --add-port5001/tcp firewall-cmd --permanent --add-port5002/tcp firewall-cmd --permanent --add-port5004/tcp firewall-cmd --reload这里最容易犯的错是只放行了 Web 的 5000 端口结果页面能打开但在页面上新增合约或者发交易时一直转圈报错因为浏览器请求 Node-Manager 的 5001 端口和 Front 的 5002 端口没放行。我在协助朋友排查时遇到过好几次这种“页面能开、功能全废”的诡异情况本质上都是端口策略不完整。3. 主服务搭建流程与关键配置解析3.1 FISCO BCOS 链的快速搭起与检查WeBASE 管理平台本身不提供链它管理的是已经存在的 FISCO BCOS 链。所以需要先搭好一条链。官方提供了 build_chain.sh 脚本可以快速在本地搭建一条 4 节点的开发链。具体操作是curl -#LO https://github.com/FISCO-BCOS/FISCO-BCOS/releases/download/v2.8.0/build_chain.sh chmod ux build_chain.sh bash build_chain.sh -l 127.0.0.1:4 -p 30300,20200,8545这里-l指定节点 IP 和数量-p指定 P2P 端口、Channel 端口和 JSON-RPC 端口。脚本执行完成后会生成nodes/目录里面是每个节点的配置和数据目录。启动链的命令是bash nodes/127.0.0.1/start_all.sh启动后一定要验证节点是否正常出块使用控制台或者直接检查进程ps -ef | grep fisco-bcos tail -f nodes/127.0.0.1/node0/log/log_*.log日志里看到的打包日志说明链正常出块这时再继续部署 WeBASE。如果链没起来就装 WeBASEFront 服务连不上节点你会在日志里看到一堆连接超时或握手失败的错误很容易误判是 WeBASE 的问题。3.2 WeBASE-Node-Manager 与 WeBASE-Front 的配置细节在实际部署中官方提供了webase-deploy一键部署脚本它会把所有服务都拉起来并自动配置。但我还是建议你理解每个服务的配置文件方便后期手动维护。Node-Manager 的配置文件在conf/application.yml里面有 MySQL 连接信息、Redis 配置如果有以及服务端口。关键点是Node-Manager 需要知道 Front 的地址才能和链通信。在配置文件中找到类似这样的段front: host: 127.0.0.1 port: 5002如果你是多机部署这里的 IP 要写成 Front 所在机器的实际 IP。我第一次用多机部署时忘了改这个配置Node-Manager 一直尝试连接 127.0.0.1前端页面直接显示“节点不可用”排查了很久才反应过来。WeBASE-Front 的配置文件里需要指定节点证书路径以及节点的 Channel 端口。证书路径默认是conf/下需要把链节点生成的证书ca.crt、node.crt、node.key拷贝到 Front 的对应目录。证书权限也很讲究如果证书文件权限太开放部分版本的 Java 服务会拒绝加载。建议统一设置为 600chmod 600 nodes/127.0.0.1/sdk/*.crt nodes/127.0.0.1/sdk/*.key3.3 前端 Web 服务的部署和验证流程Web 服务是最简单的部分本质是一个静态资源服务。在webase-deploy脚本中它会自动把 Web 构建产物放到指定目录并用 Node.js 或内置服务器启动。如果你手动部署只需要把编译好的dist目录放到 Web 服务器的静态目录下配置好nginx反向代理即可。以 nginx 为例最小配置长这样server { listen 5000; server_name localhost; root /data/webase/web/dist; index index.html; location / { try_files $uri $uri/ /index.html; } }需要注意一点如果前端通过相对路径访问后端接口那么 Nginx 需要额外配置一层代理把/api开头的请求转发到 5001 端口location /api/ { proxy_pass http://127.0.0.1:5001/; }这个静态资源服务装好后在浏览器访问http://IP:5000能看到登录页面。默认账号密码是admin/Abcd1234登录后强烈建议立刻到用户管理里修改默认密码毕竟 WeBASE 管理着链上的私钥和节点权限默认密码挂着就跟门没锁一样。3.4 签名服务WeBASE-Sign的作用与初始化WeBASE-Sign 用于管理用户私钥和交易签名。在管理平台上创建用户、部署合约、发交易都用得到它。安装它需要单独的数据库初始化脚本在script/webase-sign.sql。部署时注意签名服务的配置文件里数据库名称、用户名、密码都要和初始化时对应上。有个容易被忽略的细节签名服务启动后Node-Manager 需要在配置文件里配置签名服务的地址两边配合好才能完成“创建用户 - 分配私钥 - 签名交易”的完整链路。如果 Node-Manager 和 Sign 配置脱节你在 Web 页面上创建用户时会发现用户创建成功但没有私钥地址后续所有操作都进行不下去。这个问题当时困扰了我一整个下午后来才发现 Node-Manager 的constant配置里签名服务地址写错了端口。4. 高频报错与问题排查实录这个部分我想按实际报错来写每一条都是我在部署过程中真实遇到的包括完整的报错信息、排查思路和最终解决办法。先整理成速查表方便你快速定位报错关键词常见原因快速解决办法Connection refused目标端口未监听或 IP 配置错误netstat -anp检查端口监听状态确认各服务配置文件里的 IP/端口Failed to execute SQLMySQL 初始化脚本执行异常检查 MySQL 大小写敏感配置确认建库成功后再执行脚本Auth pluginMySQL 8.0 认证插件不兼容将用户认证插件改为mysql_native_passwordNoClassDefFoundErrorJDK 版本过高切换 JDK 8或者用容器部署Connect to node failedFront 连不上链节点检查节点证书路径、Channel 端口和节点进程是否存活权限不够或者Permission denied证书或脚本文件权限问题chmod 600证书给脚本加执行权限OutOfMemoryError服务器内存不足优化 JVM 内存参数或扩内存4.1 Front 服务日志里最常见的“连不上节点”类报错这个报错基本上是 WeBASE 部署里出现频率最高的。现象是webase-front.log里有这样的堆栈org.fisco.bcos.channel.client.Service - initChannel - ... java.net.ConnectException: Connection refused (Connection refused)排查步骤我建议按下面的顺序来第一步确认链节点是否正常启动。在链节点目录下执行ps -ef | grep fisco-bcos如果进程不在先启动链并确认日志里有出块记录。第二步确认 Front 的证书是否正确。拿到节点目录下nodes/127.0.0.1/sdk里的ca.crt、node.crt、node.key放到 Front 的conf/目录下。很多人在这一步搞混了放成了节点自身的证书而不是 SDK 证书结果一直报证书验证失败。第三步确认 Front 配置中 Channel 端口是否匹配。链默认 Channel 端口是 20200如果 build_chain 时改过端口那么 Front 配置里也得同步修改。我遇到过一次最诡异的情况链在跑证书也放对了端口也没错但 Front 就是连不上。后来执行telnet 127.0.0.1 20200发现端口不通再排查才发现防火墙把 20200 端口拦了。所以前面说的防火墙放行真的很重要。4.2 MySQL 相关报错的三个分支排查WeBASE 相关服务启动时报数据库错误是第二高频的问题。场景一服务启动正常但第一次初始化时执行 SQL 脚本报错。这时候先确认 MySQL 里是否已经建好了对应数据库比如webase。如果没建用CREATE DATABASE建好再执行脚本。场景二服务启动后日志里有Communications link failure。这个报错往往是 MySQL 连接参数不对或者 MySQL 没监听 3306 端口。用netstat -anp | grep 3306查看监听状态用mysql -h 127.0.0.1 -P 3306 -u 用户名 -p手动测试连通性。场景三账号权限不足。WeBASE 初始化脚本里可能会用到GRANT ALL PRIVILEGES ON *.* TO 用户名%但如果你手动创建用户时只授权了部分库后面 Node-Manager 访问不了签名服务的库也会报权限错误。简单粗暴一点在测试环境直接给 WeBASE 相关账号授予所有库的权限可以少踩很多坑生产环境再收敛权限。4.3 Web 页面打开正常但接口报 502/504 的分析这种情况通常不是 WeBASE 本身的问题而是前后端代理配置的问题。502 表示 Nginx 无法连接后端 5001 端口要检查 Node-Manager 是否启动成功以及 Nginx 配置文件里的proxy_pass是否正确。504 则一般是后端处理超时可能的原因是链上交易等待时间过长或者节点负载过高。遇到这类问题打开浏览器开发者工具F12切换到 Network 标签看具体是哪个 API 请求失败。然后到 Node-Manager 日志中搜索对应的请求标识基本就能定位到是服务之间的通信问题还是链上执行问题。这种链路式排查思路在处理管理平台问题上非常高效。4.4 部署脚本执行到一半失败的通用处理法不管是用webase-deploy还是手动部署都可能出现脚本执行到一半失败的情况。我最推荐的处理方法是先把所有服务进程停掉清理已生成的日志和数据库从头再走一遍。很多人喜欢在失败现场反复重试结果越搞越乱最后出现一堆不可预期的残留进程占用端口反而更难排查。统一清理的命令思路是# 停掉所有 WeBASE 相关进程 ps -ef | grep webase | grep -v grep | awk {print $2} | xargs kill -9 # 清理可能残留的端口占用 netstat -tlnp | grep 500[1245]然后把数据库里的 WeBASE 相关库删掉重建再重新执行初始化脚本。这个“推倒重来”的策略在测试环境非常好用通常比在一堆半成品状态下修修补补要快得多。5. 部署完成后的功能验证与日常运维建议5.1 登录管理平台后必须做的三件事服务全部启动后先用浏览器登录管理平台。登录成功后建议按下面的流程做一轮完整验证避免后续开发时才发现问题第一创建或导入一个测试用户。在“用户管理”里新增用户如果签名服务正常系统会自动为该用户生成一对公私钥并能在用户详情里看到地址。如果创建后没有地址说明签名服务链路有问题回到第 3.4 节检查。第二上传一份测试合约并在页面上部署。WeBASE 支持 Solidity 合约的编辑、编译、部署和调用。上传一个简单的HelloWorld合约编译通过后部署到链上。部署成功后在“合约管理”里能看到合约地址在“交易管理”里能查到部署交易的回执。这一步能完整检验“Web - Node-Manager - Sign - Front - 节点” 整条链路的连通性。第三查看节点监控数据。在“节点管理”页面确认能实时显示节点的块高、共识状态、PBFT 视图等信息。如果节点监控是绿的说明 Front 与节点的连接稳定。5.2 日志文件位置与常规看日志技巧WeBASE 各子服务的日志都很有规律统一放在各服务的logs/目录下。常用日志文件如下Node-Managerlogs/WeBASE-Node-Manager.logFrontlogs/WeBASE-Front.logSignlogs/WeBASE-Sign.log部署脚本日志logs/deploy.log排查问题时我习惯用这种组合命令实时跟踪日志输出tail -f logs/WeBASE-Node-Manager.log | tee /tmp/nm.log如果日志刷得太快可以加上grep过滤关键错误码比如grep -i error。另外日志文件如果持续增长建议配置 logrotate 做日志轮转不然几个月后日志文件能轻松占用几个 G 磁盘空间。5.3 关于服务自启动与进程守护的建议手工启动的 Java 服务一旦服务器重启就需要手动重新拉起来。所以部署完成后强烈建议用 systemd 对各服务做进程守护。每个 WeBASE 服务写一个 systemd unit 文件例如 Node-Manager 的配置大致长这样[Unit] DescriptionWeBASE Node Manager Afternetwork.target mysqld.service [Service] WorkingDirectory/data/webase/WeBASE-Node-Manager ExecStart/usr/bin/java -jar /data/webase/WeBASE-Node-Manager/WeBASE-Node-Manager.jar Restartalways Userwebase Groupwebase StandardOutputappend:/data/webase/WeBASE-Node-Manager/logs/systemd.out StandardErrorappend:/data/webase/WeBASE-Node-Manager/logs/systemd.err [Install] WantedBymulti-user.target写好之后执行systemctl daemon-reload、systemctl enable 服务名、systemctl start 服务名。注意服务启动顺序很重要必须先启动 MySQL再启动链节点再启动 Front最后启动 Node-Manager。用 systemd 的After和Requires可以控制依赖顺序。5.4 多机部署与单机部署的选择心得官方的一键部署脚本默认是单机部署所有服务装在一台机器上。如果只是开发和演示单机完全够用。但生产环境如果追求高可用建议把 MySQL、链节点、WeBASE 服务分开部署到不同机器。这样做的核心原因是部署后便于扩容和故障隔离不会因为一台机器资源紧张导致所有服务互相影响。但多机部署时所有服务配置里的 IP 都不能用 127.0.0.1这个我在前面已经强调过。还有一个容易被忽略的点是不同机器之间的时间必须同步推荐配置 NTP 时间同步。WeBASE 的签名服务和节点之间对时间偏差比较敏感如果时间差太多可能出现交易签名验证失败的诡异问题。我在实际部署中还有另一个体会如果不是对性能有极致要求初期先把链节点和 WeBASE 放在同一台机器上能少很多网络层面的问题排查。等业务稳定了再逐步拆分到多机。循序渐进比一步到位更稳妥。6. 高频追问与版本兼容速查补充6.1 WeBASE 各版本与 FISCO BCOS 版本怎么对应版本兼容是新手最头疼的问题之一。我列一个我在实际使用中验证过的版本组合供参考FISCO BCOS 版本WeBASE 推荐版本备注2.0 ~ 2.21.2.x旧版本建议升级2.3 ~ 2.51.3.x较稳定2.6 ~ 2.81.4.x 或 1.5.x当前主流组合具体小版本号以官方 release note 为准。这里我有一个实用建议锁版本时不要追求最新要选已经被社区验证过一段时间的稳定版本例如 1.4.x。新版刚出来时可能有隐藏问题等社区反馈一轮后再升级更稳。6.2 Docker 方式部署的额外注意事项现在很多朋友喜欢用 Docker 部署确实能省掉 JDK、MySQL 这些环境配置的麻烦。用 Docker 时注意几个问题一是容器和宿主机之间的端口映射要做全尤其是5000-5005这些端口二是数据卷要挂载出来否则容器删了数据全没三是如果链节点也跑在容器里需要保证两个容器之间的网络互通建议使用 Docker 自定义网络。Docker 方式的排错思路和裸机部署是一样的只是多了一层容器网络隔离排查问题时多用docker logs 容器名和docker exec -it 容器名 bash进入容器内部看网络连通性。我曾遇到过一次容器里能访问外网但访问不了宿主机上的 MySQL后来发现是防火墙拦了容器网段的流量放行后解决。6.3 管理平台响应慢或页面卡顿的优化方向如果你发现管理平台用起来反应慢先排查服务器负载。Java 服务对内存敏感用top或jstat看 JVM 内存使用情况如果频繁 Full GC就需要调大堆内存。修改各服务启动脚本里的 JVM 参数比如-Xms2g -Xmx2g。其次看数据库是否有慢查询。WeBASE 的表数据量增长后某些列表查询会变慢可以在 MySQL 慢查询日志里确认。对常见的查询字段建好索引大多数性能问题都能解决。这里要特别提醒生产环境对链上数据进行归档时不要直接在管理平台的库里删数据可以通过停止交易后导出再清理的方式避免数据不一致。最后再分享一点实战体会整套 WeBASE 管理平台搭下来最大的感受是真正难的不是某一单个步骤而是多个组件之间的协作关系。链、Front、Node-Manager、Sign、Web 五个部分像一条完整的流水线任何一个环节断掉页面都会表现成“某个功能不可用”但报错往往指向别处。所以排查问题时一定要顺着链路逐个验证浏览器请求到 WebWeb 代理到 Node-ManagerNode-Manager 调用 Sign 签名通过 Front 发给链节点链节点执行后返回结果。每一跳都确认通了问题自然就定位了。我建议第一次搭建的朋友部署完成后亲手把“创建用户 - 部署合约 - 调用合约 - 查看交易”的完整流程走一遍哪怕只是 HelloWorld也比看十遍文档有用。只有亲手经历过一次全链路贯通后面遇到报错时心里才有全局地图。这个平台本身不复杂复杂的是它横跨了前端、后端、数据库、区块链节点好几种技术栈但只要把链路理清楚遇到问题逐层排查绝大多数坑都能在半小时内解决。 WeBASE管理平台搭建全指南：从环境准备到高频报错排查
1. 平台搭建前的整体认知与思路拆解先说结论WeBASEWeBank Blockchain Service Enhancement是微众银行开源的区块链中间件平台定位是降低 FISCO BCOS 链的运维和开发门槛。它不是一个单一体服务而是一组子系统的集合包括前置服务WeBASE-Front、节点管理服务WeBASE-Node-Manager、WeBASE-Web、签名服务WeBASE-Sign、交易服务WeBASE-Transaction等。很多人第一次搭建时被“WeBASE 管理平台”这个名字误导以为装一个包就完事结果在依赖关系上踩了一堆坑。这篇文章我就按实际部署顺序把我自己反复装过几轮后整理的完整流程、报错对照和排错思路写出来给准备搭管理平台的朋友一个可以直接照着做的参考。1.1 先搞清楚 WeBASE 管理平台到底由哪几块组成在动手之前先把架构看清楚后面排查问题时你会省很多力气。WeBASE 管理平台最核心的调用链是这样的用户在浏览器打开 WeBASE-Web 页面页面请求 Node-Manager 服务Node-Manager 再通过 WeBASE-Front 与区块链节点通信最终把交易发到 FISCO BCOS 链上。签名服务 WeBASE-Sign 负责私钥管理和交易签名属于可选但强烈建议安装的组件因为在 webase 里发交易、部署合约都绕不开签名。如果你只用“节点管理 控制台”这种最简模式可以只装 Front 和 Web 吗可以但功能会缺失一块。我的建议是生产环境直接按全套装开发环境至少装 Node-Manager Front Web 三件套。原因在于管理平台的核心价值就是把“部署合约、发交易、查交易、管理私钥”这些操作图形化少一个服务业务流程就断一截。另外要注意版本匹配问题。WeBASE 各子系统的版本号需要和 FISCO BCOS 链的版本匹配具体版本对应关系在官方文档里有表格。我自己踩过的最痛的一次就是链用的是 2.7.2装上 1.5.x 的 WeBASE 后Front 怎么都连不上节点后来才发现版本不匹配换回 1.4.x 后重启即通。1.2 为什么推荐先在测试环境完整走一遍流程很多人拿到部署文档直接在生产服务器上开搞遇到问题边搜边改最后服务起来了但中间过程改了什么、为什么改完全没有记录。等下次扩容或者迁移环境又要把坑重新踩一遍。我的习惯是先在本地虚拟机或一台临时服务器上走完整流程确认所有步骤无误后再上生产。这不是浪费时间反而是最省时间的方式。测试环境建议准备一台 4C8G 的虚拟机操作系统选 CentOS 7.9 或 Ubuntu 20.04 都行。内存低于 4G 的话跑起 MySQL 多个 Java 服务会非常吃力频繁出现 OOM 或者服务假死。硬盘 50G 以上因为区块链节点数据会持续增长WeBASE 各服务的日志也会占空间。整个 WeBASE 会拉起来的服务数量不少如果网络下载依赖包很慢建议提前配好国内镜像源后面我会具体说。2. 环境准备阶段的高频踩坑点2.1 JDK 版本选择别用 Java 8 的最新小版本也别用 Java 11WeBASE 各子服务是基于 Java 开发的官方推荐 JDK 8。这里有个容易踩的坑如果你系统里装的是 JDK 11某些旧版本 WeBASE 服务启动时会出现奇怪的类加载报错比如java.lang.NoClassDefFoundError: javax/xml/bind/JAXBException。这是因为 JDK 11 把 Java EE 模块移除了而旧版 WeBASE 依赖这部分类库。解决思路有两个方向一是装回 JDK 8这是最省心的方案二是如果开发机有其他项目依赖 JDK 11可以考虑用 Docker 方式跑 WeBASE这样 JDK 版本隔离在容器里不影响宿主机其他应用。我第一次搭建时就在 JDK 版本上折腾了半个多小时后来老老实实装了 OpenJDK 8问题立刻消失。验证 JDK 是否装好用java -version命令看到输出中包含1.8.0_xxx字样才算对。另外别忘了配JAVA_HOME环境变量很多启动脚本会读取这个变量不配会直接启动失败。2.2 MySQL 版本与初始化配置的坑WeBASE 的 Node-Manager 服务和签名服务都需要 MySQL 存储数据。官方推荐 MySQL 5.7 或 8.0。这里我重点说三个高频问题第一个问题是数据库初始化脚本执行报错。WeBASE 的脚本会自动建库但如果你手动用 Navicat 之类工具执行 SQL 文件很可能会遇到表名大小写问题。MySQL 在 Linux 下默认区分大小写而 WeBASE 的建表语句是混合大小写的如果你的 MySQL 配置了lower_case_table_names0执行脚本时会出现找不到表的报错。解决方案是在/etc/my.cnf的[mysqld]段加上lower_case_table_names1然后重启 MySQL。这一点在官方文档里写得不明显我是在多次重试执行初始化脚本失败后才定位到的。第二个问题是 MySQL 8.0 的认证插件兼容性。WeBASE 早期版本用 MySQL 5.7 开发测试如果用 MySQL 8.0需要手动确认用户的认证插件是caching_sha2_password还是mysql_native_password。Webase 服务连接数据库时如果报Authentication plugin caching_sha2_password cannot be loaded就需要执行下面这个命令把认证插件改回来ALTER USER webase% IDENTIFIED WITH mysql_native_password BY 你的密码; FLUSH PRIVILEGES;第三个问题是数据库连接数限制。WeBASE 多个服务同时连接 MySQL默认连接数 151 偶尔不够用服务启动时偶尔报Too many connections。解决方案是在配置文件中调大 max_connections比如改成 500。2.3 端口规划与防火墙放行的必要性WeBASE 全家桶涉及大量端口我在下面的表里做了整理方便你提前规划好防火墙策略服务默认端口说明WeBASE-Web5000前端管理页面浏览器访问WeBASE-Node-Manager5001核心管理后端服务WeBASE-Front5002节点前置服务WeBASE-Sign5004签名服务WeBASE-Transaction5005交易服务MySQL3306数据库服务FISCO BCOS 节点20200/20201节点 Channel 端口和 P2P 端口如果你在云服务器上部署需要到云控制台的安全组里放行这些端口如果是本地虚拟机需要检查防火墙。CentOS 7 上常用命令是firewall-cmd --permanent --add-port5000/tcp firewall-cmd --permanent --add-port5001/tcp firewall-cmd --permanent --add-port5002/tcp firewall-cmd --permanent --add-port5004/tcp firewall-cmd --reload这里最容易犯的错是只放行了 Web 的 5000 端口结果页面能打开但在页面上新增合约或者发交易时一直转圈报错因为浏览器请求 Node-Manager 的 5001 端口和 Front 的 5002 端口没放行。我在协助朋友排查时遇到过好几次这种“页面能开、功能全废”的诡异情况本质上都是端口策略不完整。3. 主服务搭建流程与关键配置解析3.1 FISCO BCOS 链的快速搭起与检查WeBASE 管理平台本身不提供链它管理的是已经存在的 FISCO BCOS 链。所以需要先搭好一条链。官方提供了 build_chain.sh 脚本可以快速在本地搭建一条 4 节点的开发链。具体操作是curl -#LO https://github.com/FISCO-BCOS/FISCO-BCOS/releases/download/v2.8.0/build_chain.sh chmod ux build_chain.sh bash build_chain.sh -l 127.0.0.1:4 -p 30300,20200,8545这里-l指定节点 IP 和数量-p指定 P2P 端口、Channel 端口和 JSON-RPC 端口。脚本执行完成后会生成nodes/目录里面是每个节点的配置和数据目录。启动链的命令是bash nodes/127.0.0.1/start_all.sh启动后一定要验证节点是否正常出块使用控制台或者直接检查进程ps -ef | grep fisco-bcos tail -f nodes/127.0.0.1/node0/log/log_*.log日志里看到的打包日志说明链正常出块这时再继续部署 WeBASE。如果链没起来就装 WeBASEFront 服务连不上节点你会在日志里看到一堆连接超时或握手失败的错误很容易误判是 WeBASE 的问题。3.2 WeBASE-Node-Manager 与 WeBASE-Front 的配置细节在实际部署中官方提供了webase-deploy一键部署脚本它会把所有服务都拉起来并自动配置。但我还是建议你理解每个服务的配置文件方便后期手动维护。Node-Manager 的配置文件在conf/application.yml里面有 MySQL 连接信息、Redis 配置如果有以及服务端口。关键点是Node-Manager 需要知道 Front 的地址才能和链通信。在配置文件中找到类似这样的段front: host: 127.0.0.1 port: 5002如果你是多机部署这里的 IP 要写成 Front 所在机器的实际 IP。我第一次用多机部署时忘了改这个配置Node-Manager 一直尝试连接 127.0.0.1前端页面直接显示“节点不可用”排查了很久才反应过来。WeBASE-Front 的配置文件里需要指定节点证书路径以及节点的 Channel 端口。证书路径默认是conf/下需要把链节点生成的证书ca.crt、node.crt、node.key拷贝到 Front 的对应目录。证书权限也很讲究如果证书文件权限太开放部分版本的 Java 服务会拒绝加载。建议统一设置为 600chmod 600 nodes/127.0.0.1/sdk/*.crt nodes/127.0.0.1/sdk/*.key3.3 前端 Web 服务的部署和验证流程Web 服务是最简单的部分本质是一个静态资源服务。在webase-deploy脚本中它会自动把 Web 构建产物放到指定目录并用 Node.js 或内置服务器启动。如果你手动部署只需要把编译好的dist目录放到 Web 服务器的静态目录下配置好nginx反向代理即可。以 nginx 为例最小配置长这样server { listen 5000; server_name localhost; root /data/webase/web/dist; index index.html; location / { try_files $uri $uri/ /index.html; } }需要注意一点如果前端通过相对路径访问后端接口那么 Nginx 需要额外配置一层代理把/api开头的请求转发到 5001 端口location /api/ { proxy_pass http://127.0.0.1:5001/; }这个静态资源服务装好后在浏览器访问http://IP:5000能看到登录页面。默认账号密码是admin/Abcd1234登录后强烈建议立刻到用户管理里修改默认密码毕竟 WeBASE 管理着链上的私钥和节点权限默认密码挂着就跟门没锁一样。3.4 签名服务WeBASE-Sign的作用与初始化WeBASE-Sign 用于管理用户私钥和交易签名。在管理平台上创建用户、部署合约、发交易都用得到它。安装它需要单独的数据库初始化脚本在script/webase-sign.sql。部署时注意签名服务的配置文件里数据库名称、用户名、密码都要和初始化时对应上。有个容易被忽略的细节签名服务启动后Node-Manager 需要在配置文件里配置签名服务的地址两边配合好才能完成“创建用户 - 分配私钥 - 签名交易”的完整链路。如果 Node-Manager 和 Sign 配置脱节你在 Web 页面上创建用户时会发现用户创建成功但没有私钥地址后续所有操作都进行不下去。这个问题当时困扰了我一整个下午后来才发现 Node-Manager 的constant配置里签名服务地址写错了端口。4. 高频报错与问题排查实录这个部分我想按实际报错来写每一条都是我在部署过程中真实遇到的包括完整的报错信息、排查思路和最终解决办法。先整理成速查表方便你快速定位报错关键词常见原因快速解决办法Connection refused目标端口未监听或 IP 配置错误netstat -anp检查端口监听状态确认各服务配置文件里的 IP/端口Failed to execute SQLMySQL 初始化脚本执行异常检查 MySQL 大小写敏感配置确认建库成功后再执行脚本Auth pluginMySQL 8.0 认证插件不兼容将用户认证插件改为mysql_native_passwordNoClassDefFoundErrorJDK 版本过高切换 JDK 8或者用容器部署Connect to node failedFront 连不上链节点检查节点证书路径、Channel 端口和节点进程是否存活权限不够或者Permission denied证书或脚本文件权限问题chmod 600证书给脚本加执行权限OutOfMemoryError服务器内存不足优化 JVM 内存参数或扩内存4.1 Front 服务日志里最常见的“连不上节点”类报错这个报错基本上是 WeBASE 部署里出现频率最高的。现象是webase-front.log里有这样的堆栈org.fisco.bcos.channel.client.Service - initChannel - ... java.net.ConnectException: Connection refused (Connection refused)排查步骤我建议按下面的顺序来第一步确认链节点是否正常启动。在链节点目录下执行ps -ef | grep fisco-bcos如果进程不在先启动链并确认日志里有出块记录。第二步确认 Front 的证书是否正确。拿到节点目录下nodes/127.0.0.1/sdk里的ca.crt、node.crt、node.key放到 Front 的conf/目录下。很多人在这一步搞混了放成了节点自身的证书而不是 SDK 证书结果一直报证书验证失败。第三步确认 Front 配置中 Channel 端口是否匹配。链默认 Channel 端口是 20200如果 build_chain 时改过端口那么 Front 配置里也得同步修改。我遇到过一次最诡异的情况链在跑证书也放对了端口也没错但 Front 就是连不上。后来执行telnet 127.0.0.1 20200发现端口不通再排查才发现防火墙把 20200 端口拦了。所以前面说的防火墙放行真的很重要。4.2 MySQL 相关报错的三个分支排查WeBASE 相关服务启动时报数据库错误是第二高频的问题。场景一服务启动正常但第一次初始化时执行 SQL 脚本报错。这时候先确认 MySQL 里是否已经建好了对应数据库比如webase。如果没建用CREATE DATABASE建好再执行脚本。场景二服务启动后日志里有Communications link failure。这个报错往往是 MySQL 连接参数不对或者 MySQL 没监听 3306 端口。用netstat -anp | grep 3306查看监听状态用mysql -h 127.0.0.1 -P 3306 -u 用户名 -p手动测试连通性。场景三账号权限不足。WeBASE 初始化脚本里可能会用到GRANT ALL PRIVILEGES ON *.* TO 用户名%但如果你手动创建用户时只授权了部分库后面 Node-Manager 访问不了签名服务的库也会报权限错误。简单粗暴一点在测试环境直接给 WeBASE 相关账号授予所有库的权限可以少踩很多坑生产环境再收敛权限。4.3 Web 页面打开正常但接口报 502/504 的分析这种情况通常不是 WeBASE 本身的问题而是前后端代理配置的问题。502 表示 Nginx 无法连接后端 5001 端口要检查 Node-Manager 是否启动成功以及 Nginx 配置文件里的proxy_pass是否正确。504 则一般是后端处理超时可能的原因是链上交易等待时间过长或者节点负载过高。遇到这类问题打开浏览器开发者工具F12切换到 Network 标签看具体是哪个 API 请求失败。然后到 Node-Manager 日志中搜索对应的请求标识基本就能定位到是服务之间的通信问题还是链上执行问题。这种链路式排查思路在处理管理平台问题上非常高效。4.4 部署脚本执行到一半失败的通用处理法不管是用webase-deploy还是手动部署都可能出现脚本执行到一半失败的情况。我最推荐的处理方法是先把所有服务进程停掉清理已生成的日志和数据库从头再走一遍。很多人喜欢在失败现场反复重试结果越搞越乱最后出现一堆不可预期的残留进程占用端口反而更难排查。统一清理的命令思路是# 停掉所有 WeBASE 相关进程 ps -ef | grep webase | grep -v grep | awk {print $2} | xargs kill -9 # 清理可能残留的端口占用 netstat -tlnp | grep 500[1245]然后把数据库里的 WeBASE 相关库删掉重建再重新执行初始化脚本。这个“推倒重来”的策略在测试环境非常好用通常比在一堆半成品状态下修修补补要快得多。5. 部署完成后的功能验证与日常运维建议5.1 登录管理平台后必须做的三件事服务全部启动后先用浏览器登录管理平台。登录成功后建议按下面的流程做一轮完整验证避免后续开发时才发现问题第一创建或导入一个测试用户。在“用户管理”里新增用户如果签名服务正常系统会自动为该用户生成一对公私钥并能在用户详情里看到地址。如果创建后没有地址说明签名服务链路有问题回到第 3.4 节检查。第二上传一份测试合约并在页面上部署。WeBASE 支持 Solidity 合约的编辑、编译、部署和调用。上传一个简单的HelloWorld合约编译通过后部署到链上。部署成功后在“合约管理”里能看到合约地址在“交易管理”里能查到部署交易的回执。这一步能完整检验“Web - Node-Manager - Sign - Front - 节点” 整条链路的连通性。第三查看节点监控数据。在“节点管理”页面确认能实时显示节点的块高、共识状态、PBFT 视图等信息。如果节点监控是绿的说明 Front 与节点的连接稳定。5.2 日志文件位置与常规看日志技巧WeBASE 各子服务的日志都很有规律统一放在各服务的logs/目录下。常用日志文件如下Node-Managerlogs/WeBASE-Node-Manager.logFrontlogs/WeBASE-Front.logSignlogs/WeBASE-Sign.log部署脚本日志logs/deploy.log排查问题时我习惯用这种组合命令实时跟踪日志输出tail -f logs/WeBASE-Node-Manager.log | tee /tmp/nm.log如果日志刷得太快可以加上grep过滤关键错误码比如grep -i error。另外日志文件如果持续增长建议配置 logrotate 做日志轮转不然几个月后日志文件能轻松占用几个 G 磁盘空间。5.3 关于服务自启动与进程守护的建议手工启动的 Java 服务一旦服务器重启就需要手动重新拉起来。所以部署完成后强烈建议用 systemd 对各服务做进程守护。每个 WeBASE 服务写一个 systemd unit 文件例如 Node-Manager 的配置大致长这样[Unit] DescriptionWeBASE Node Manager Afternetwork.target mysqld.service [Service] WorkingDirectory/data/webase/WeBASE-Node-Manager ExecStart/usr/bin/java -jar /data/webase/WeBASE-Node-Manager/WeBASE-Node-Manager.jar Restartalways Userwebase Groupwebase StandardOutputappend:/data/webase/WeBASE-Node-Manager/logs/systemd.out StandardErrorappend:/data/webase/WeBASE-Node-Manager/logs/systemd.err [Install] WantedBymulti-user.target写好之后执行systemctl daemon-reload、systemctl enable 服务名、systemctl start 服务名。注意服务启动顺序很重要必须先启动 MySQL再启动链节点再启动 Front最后启动 Node-Manager。用 systemd 的After和Requires可以控制依赖顺序。5.4 多机部署与单机部署的选择心得官方的一键部署脚本默认是单机部署所有服务装在一台机器上。如果只是开发和演示单机完全够用。但生产环境如果追求高可用建议把 MySQL、链节点、WeBASE 服务分开部署到不同机器。这样做的核心原因是部署后便于扩容和故障隔离不会因为一台机器资源紧张导致所有服务互相影响。但多机部署时所有服务配置里的 IP 都不能用 127.0.0.1这个我在前面已经强调过。还有一个容易被忽略的点是不同机器之间的时间必须同步推荐配置 NTP 时间同步。WeBASE 的签名服务和节点之间对时间偏差比较敏感如果时间差太多可能出现交易签名验证失败的诡异问题。我在实际部署中还有另一个体会如果不是对性能有极致要求初期先把链节点和 WeBASE 放在同一台机器上能少很多网络层面的问题排查。等业务稳定了再逐步拆分到多机。循序渐进比一步到位更稳妥。6. 高频追问与版本兼容速查补充6.1 WeBASE 各版本与 FISCO BCOS 版本怎么对应版本兼容是新手最头疼的问题之一。我列一个我在实际使用中验证过的版本组合供参考FISCO BCOS 版本WeBASE 推荐版本备注2.0 ~ 2.21.2.x旧版本建议升级2.3 ~ 2.51.3.x较稳定2.6 ~ 2.81.4.x 或 1.5.x当前主流组合具体小版本号以官方 release note 为准。这里我有一个实用建议锁版本时不要追求最新要选已经被社区验证过一段时间的稳定版本例如 1.4.x。新版刚出来时可能有隐藏问题等社区反馈一轮后再升级更稳。6.2 Docker 方式部署的额外注意事项现在很多朋友喜欢用 Docker 部署确实能省掉 JDK、MySQL 这些环境配置的麻烦。用 Docker 时注意几个问题一是容器和宿主机之间的端口映射要做全尤其是5000-5005这些端口二是数据卷要挂载出来否则容器删了数据全没三是如果链节点也跑在容器里需要保证两个容器之间的网络互通建议使用 Docker 自定义网络。Docker 方式的排错思路和裸机部署是一样的只是多了一层容器网络隔离排查问题时多用docker logs 容器名和docker exec -it 容器名 bash进入容器内部看网络连通性。我曾遇到过一次容器里能访问外网但访问不了宿主机上的 MySQL后来发现是防火墙拦了容器网段的流量放行后解决。6.3 管理平台响应慢或页面卡顿的优化方向如果你发现管理平台用起来反应慢先排查服务器负载。Java 服务对内存敏感用top或jstat看 JVM 内存使用情况如果频繁 Full GC就需要调大堆内存。修改各服务启动脚本里的 JVM 参数比如-Xms2g -Xmx2g。其次看数据库是否有慢查询。WeBASE 的表数据量增长后某些列表查询会变慢可以在 MySQL 慢查询日志里确认。对常见的查询字段建好索引大多数性能问题都能解决。这里要特别提醒生产环境对链上数据进行归档时不要直接在管理平台的库里删数据可以通过停止交易后导出再清理的方式避免数据不一致。最后再分享一点实战体会整套 WeBASE 管理平台搭下来最大的感受是真正难的不是某一单个步骤而是多个组件之间的协作关系。链、Front、Node-Manager、Sign、Web 五个部分像一条完整的流水线任何一个环节断掉页面都会表现成“某个功能不可用”但报错往往指向别处。所以排查问题时一定要顺着链路逐个验证浏览器请求到 WebWeb 代理到 Node-ManagerNode-Manager 调用 Sign 签名通过 Front 发给链节点链节点执行后返回结果。每一跳都确认通了问题自然就定位了。我建议第一次搭建的朋友部署完成后亲手把“创建用户 - 部署合约 - 调用合约 - 查看交易”的完整流程走一遍哪怕只是 HelloWorld也比看十遍文档有用。只有亲手经历过一次全链路贯通后面遇到报错时心里才有全局地图。这个平台本身不复杂复杂的是它横跨了前端、后端、数据库、区块链节点好几种技术栈但只要把链路理清楚遇到问题逐层排查绝大多数坑都能在半小时内解决。