企业官网建设流程全解析

1. 平台搭建前的整体认知与思路拆解

先说结论：WeBASE（WeBank 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 11

WeBASE 各子服务是基于 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_names=0，执行脚本时会出现找不到表的报错。解决方案是在/etc/my.cnf的[mysqld]段加上lower_case_table_names=1，然后重启 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 全家桶涉及大量端口，我在下面的表里做了整理，方便你提前规划好防火墙策略：

如果你在云服务器上部署，需要到云控制台的安全组里放行这些端口；如果是本地虚拟机，需要检查防火墙。CentOS 7 上常用命令是：

firewall-cmd --permanent --add-port=5000/tcp firewall-cmd --permanent --add-port=5001/tcp firewall-cmd --permanent --add-port=5002/tcp firewall-cmd --permanent --add-port=5004/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 u+x 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。如果链没起来就装 WeBASE，Front 服务连不上节点，你会在日志里看到一堆连接超时或握手失败的错误，很容易误判是 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 服务会拒绝加载。建议统一设置为 600：

chmod 600 nodes/127.0.0.1/sdk/*.crt nodes/127.0.0.1/sdk/*.key

3.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. 高频报错与问题排查实录

这个部分我想按实际报错来写，每一条都是我在部署过程中真实遇到的，包括完整的报错信息、排查思路和最终解决办法。先整理成速查表，方便你快速定位：

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-Manager：logs/WeBASE-Node-Manager.log
• Front：logs/WeBASE-Front.log
• Sign：logs/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] Description=WeBASE Node Manager After=network.target mysqld.service [Service] WorkingDirectory=/data/webase/WeBASE-Node-Manager ExecStart=/usr/bin/java -jar /data/webase/WeBASE-Node-Manager/WeBASE-Node-Manager.jar Restart=always User=webase Group=webase StandardOutput=append:/data/webase/WeBASE-Node-Manager/logs/systemd.out StandardError=append:/data/webase/WeBASE-Node-Manager/logs/systemd.err [Install] WantedBy=multi-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 版本怎么对应

版本兼容是新手最头疼的问题之一。我列一个我在实际使用中验证过的版本组合，供参考：

具体小版本号以官方 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 五个部分像一条完整的流水线，任何一个环节断掉，页面都会表现成“某个功能不可用”，但报错往往指向别处。所以排查问题时，一定要顺着链路逐个验证：浏览器请求到 Web，Web 代理到 Node-Manager，Node-Manager 调用 Sign 签名，通过 Front 发给链节点，链节点执行后返回结果。每一跳都确认通了，问题自然就定位了。

我建议第一次搭建的朋友，部署完成后亲手把“创建用户 -> 部署合约 -> 调用合约 -> 查看交易”的完整流程走一遍，哪怕只是 HelloWorld，也比看十遍文档有用。只有亲手经历过一次全链路贯通，后面遇到报错时心里才有全局地图。这个平台本身不复杂，复杂的是它横跨了前端、后端、数据库、区块链节点好几种技术栈，但只要把链路理清楚，遇到问题逐层排查，绝大多数坑都能在半小时内解决。