企业官网建设流程全解析

简介：webase-deploy.zip 是一套针对 Web 应用尤其是 WeBASE 平台部署场景整理的自动化运维工具包，面向具备基础 Linux 与 Docker 使用经验的开发运维人员，用于简化环境配置、服务编排及版本升级流程。压缩包共 29 个文件，约 55KB，核心由 11 个 shell 脚本与 10 个 Python 模块组成，分别对应一键部署、服务升级、健康检查等操作；另含 2 个 YAML 编排文件、2 个 properties 配置文件和 2 个 Markdown 说明文档，覆盖了从环境参数设定到容器化启动的关键环节。包内还提供 nginx.conf 反向代理配置示例，以及 upgrade-v1.5.0～v1.5.4 的逐版本升级脚本，便于追溯与演练。目前已有 189 人浏览学习，适合需要快速上手 WeBASE 部署、对照脚本理解自动化流程、并沉淀排查思路的读者，可以直接复用其中脚本与配置模板，减少重复劳动。

1. webase-deploy.zip：不是解压就能用，它把 WeBASE 全家桶和链一次编排起来

webase-deploy.zip 不是应用包，而是 FISCO BCOS 生态里 WeBASE 中间件平台的一键部署脚本包。它帮你把节点管理（node-mgr）、节点前置（front）、签名（sign）、交易（transaction）、事件（event）几个服务连同 MySQL 数据库、甚至一整条链编排起来。反直觉的是：这个包不是解压就能用，真正的成本在网络下载、MySQL 权限和证书匹配三处。它适合已经在跑 FISCO BCOS 链、想接入 WeBASE 做合约管理与节点监控的团队，也适合在本地快速起一套完整环境的个人；收益是把折腾一天的部署压到一顿午饭的时间，前提是改对 common.properties、读得懂 deploy.sh 日志。下文按环境准备、参数配置、执行排错、最终验证展开。

2. 解压 webase-deploy.zip 前的三件事：JDK8、MySQL 和端口占用

2.1 为什么依赖底线锁死在 JDK8 和 MySQL：先讲选型理由

WeBASE 全家桶本质是多个 Spring Boot 应用打成 jar，由 java -jar 拉起，JDK 版本直接决定服务能不能起来。我第一次图省事装了 JDK17，结果 node-mgr 起不来，日志里一大片 module 相关的报错，最后老老实实装回 1.8。常见做法是 openjdk 1.8 或 oracle jdk8 都行，关键是别追新。内存方面，四个服务光是堆内就吃掉两三个 G，再加上链上的节点进程，2G 机器启动到一半就会 OOM，建议至少 4G，实测 8G 才从容。这块没有玄学，不够就是不够，OOM 先杀的往往就是 java 进程。

数据库上，WeBASE 各服务启动时会自动建库建表，理论上只要给个有权限的账号就行。我一般装 MySQL 5.7，8.0 也能用但要处理认证插件兼容，那部分到避坑章单独讲。这里最容易漏的一环是 mysql-connector-java：webase-deploy 包里不带数据库驱动 jar，解压后第一件事就是下载 5.1.4x 系列的 connector（常见做法是 5.1.49），放进 webase-deploy 根目录；有的版本要求放 lib 子目录，以包内 README 为准。deploy.sh 会在部署时把它拷到每个服务的 lib 下。没放的话，服务起来后日志必然报找不到驱动，而这个错误通常在最后阶段才暴露，返工成本很高。

如果机器上 MySQL 还没有，建议直接装官方 rpm 或 deb 包，省得手动初始化。个人经验是别在 Linux 上折腾 zip 解压版的 MySQL：少了 systemd 托管和默认配置文件，后面排错时连日志目录都不好找。JDK8 同理，rpm 或 tar.gz 都比 zip 包干净，解压版还要自己配 PATH 和 JAVA_HOME，属于无谓的麻烦。

2.2 解压与目录识别：deploy.sh、common.properties、check-service.sh 各管什么

拿到包以后先确认 unzip 在不在，有些精简系统镜像连解压工具都没有。yum 系执行 yum install -y unzip，apt 系执行 apt install -y unzip，然后解压到固定目录。

cd /opt unzip webase-deploy.zip -d webase-deploy cd webase-deploy chmod +x *.sh ls -lF

解压后目录里起决定作用的就几个文件：

关于 chmod +x 这步：如果你把包从别的机器 scp 过来，或者在 Windows 下解压再上传，脚本的可执行位经常丢，bash deploy.sh 会直接报 Permission denied。另一个小坑是解压路径里别有空格和中文，脚本内部用相对路径拼接，路径一怪，后面下载、拷贝全乱，日志还看不懂。

2.3 先扫端口再动手：5000/5001/5002/5004 比你想的更容易撞车

WeBASE 默认占用的端口不少，撞车时不报错——服务照常启动，日志也正常，就是 HTTP 访问不通，属于最气人的一类问题。动手前先扫一遍：

ss -lntp | grep -E ':(500[0-5]|20200|30300)\b'

关键端口速查：

如果哪个端口被占，先别急着杀进程，试着在 common.properties 里改 5000-5005 错开，很多下游组件的 SDK 配置会跟着自动生成，改一处就行。注意 20200 属于链本身：复用的链如果是别人起的，这个端口被占是正常的，别去 kill。要是 5001 被个陌生进程占着，先看它是谁再决定，盲目 kill 可能把别人的服务带走。

3. common.properties：决定整套部署动作的必改参数与开关

3.1 MySQL 四件套：账号、密码、库名和授权逃不掉的坑

打开 common.properties，前几行就是 MySQL。不同小版本的字段名可能有一两个字母的差异，但套路一样：

# MySQL 连接 mysql.ip=127.0.0.1 mysql.port=3306 mysql.user=webase mysql.password=ChangeMe@1 mysql.database=webasenodemanager

mysql.database 是 node-mgr 主库的名字，默认 webasenodemanager。deploy 还会按需给 transaction、event 建 webasetransaction、webaseevents 之类的库，所以授权时别只授一个库，给 webase 开头的库一个通配授权最省心：

CREATE USER 'webase'@'%' IDENTIFIED BY 'ChangeMe@1'; GRANT ALL PRIVILEGES ON `webase%`.* TO 'webase'@'%'; ALTER USER 'webase'@'%' IDENTIFIED WITH mysql_native_password BY 'ChangeMe@1'; FLUSH PRIVILEGES;

最后那条 ALTER 只对 MySQL 8.0 有必要：8.0 默认的 caching_sha2_password 认证，5.1 系 connector 支持不了，不改成 mysql_native_password 就会在启动时报 Public Key Retrieval is not allowed。教训是：不想跟认证插件纠缠就直接用 5.7，少踩一个坑。

字符集也顺带提一嘴：库里如果有从别处导入的旧数据，统一 utf8mb4，避免合约名或中文备注变成问号。手工建库的话加上 DEFAULT CHARACTER SET utf8mb4，deploy 自动建库时一般已经处理了，但你不手工建库不代表连接串可以乱写，数据库名必须和这里的 mysql.database 一致。

提示：MySQL 8.0 的用户记得执行那条 ALTER，否则 node-mgr 启动必失败，而且报错信息极具迷惑性。

3.2 端口与启用开关：全量部署还是只跑最小组合

端口块长这样，每个服务一行：

webase.front.port=5002 webase.nodeMgr.port=5001 webase.web.port=5000 webase.sign.port=5004 webase.transaction.enable=true webase.transaction.port=5003 webase.event.enable=true webase.event.port=5005

这里最值得花时间的不是端口本身，而是你到底需要几个服务。很多人上来就全量部署，机器直接翻车。最小可用组合是 node-mgr + front + web 管理台：它能完成私钥管理、合约文件管理、上链调用、区块浏览这些八成日常操作。transaction 是你想用 WeBASE 统一处理后端交易时才需要；event 是给链上事件推送用的；sign 是独立签名服务，不单独调它的接口，最小组合也够。内存吃紧时把后三个 enable 设成 false，一台 4G 机器能省出 1.5G 左右，这对本地开发机相当关键。

端口改动的边界也要说清楚：5000-5005 随便改，改完重启对应服务即可；但 20200 这种链的通道端口不要去 common.properties 里动，链相关端口归链的 config.ini 管，不是这个文件的职责。改完端口记得同步改访问地址，我见过有人把 nodeMgr 改成 5009，浏览器还敲 5001，查了半天。

3.3 链从哪来：自动建链还是复用已有链，加密套件别选错

链是这套架构里最容易被想当然的部分。common.properties 里通常有两个关键选择——是否自动建链，以及 FISCO 版本和加密套件：

# 是否由脚本自动搭建本地链，false 表示复用已有链 if.build.chain=false # 链版本和加密套件：0 非国密，1 国密 fisco.version=v2.7.2 encryptType=0

如果选自动建链，deploy.sh 会拉取链的构建工具，在本地起一个默认四节点、单群组的链，对新手最友好，几乎不需要额外配置。但两个注意点：一是拉链的工具同样走下载，网络不好会卡在那一阶段；二是自动建的链是演示配置，节点数据和机构证书都是默认的，真要对外提供服务，链本身应该用正式方式单独搭建，再回来选复用。另外链的版本要和 webase-deploy 配套：3.x 的链要配支持 3.x 的部署包，混搭会在建链阶段直接失败。

如果选复用已有链，重点核对三件事：链节点的 channel 端口（默认 20200）是否可达、SDK 证书（ca.crt、sdk.crt、sdk.key）是否与链一致、加密套件是否与链上一致。encryptType 选错会在 front 连链时出现握手失败，这种问题表面看是网络，实际是证书或套件不匹配，最容易误判。SDK 证书在部署时会从你指定的节点配置目录拷贝，路径别只填节点 IP，要把节点的配置目录完整给出来，否则脚本找不到证书会跳过拷贝，最后 front 带着一份错证书硬连。

4. 执行 deploy.sh：按阶段读日志，按顺序起服务

4.1 deploy.sh 跑起来之后，屏幕上那些阶段到底在干什么

配置改完就能跑了。执行方式我习惯用 bash 而不是 sh，避免部分发行版 sh 指向 dash 带来的兼容问题：

bash deploy.sh

整个执行是分阶段的，把屏幕输出理解成：环境自检（Java 版本、MySQL 连通性、connector 是否就位）→ 下载/解压各服务安装包 → 按 common.properties 生成每个服务的配置 → 初始化数据库表 → 建链或连接已有链 → 按顺序启动服务。第一次跑，最可能出现症状的是下载阶段长时间不动。

判断它是真卡还是慢：卡死时 CPU 和网卡流量都接近零，且日志没有新行。这时候别急着 Ctrl+C 重来，先确认本地是否有同名服务包可以跳过下载——deploy 脚本通常支持把提前下载好的包放进同目录直接使用，这是最稳的路径，避免反复等半小时。日志方面，屏幕输出只是摘要，真正的细节在 ~/WeBASE 下每个子服务的 logs 目录里，出问题时一头扎进日志才是正道：

tail -f ~/WeBASE/*/logs/*.log

注意 deploy.sh 不是一个干净的一次性脚本：重复执行时，如果上次已经初始化了数据库，它会对已有库做增量处理；但如果你中途手动删过目录或库，脚本可能不会帮你恢复。最直接的办法是重来前把 ~/WeBASE 目录改名备份，再重新解压一份干净的包，别在原目录上反复横跳。

4.2 服务启动顺序的隐藏逻辑：node-mgr 先、front 最后

部署脚本对启动顺序有讲究：先 node-mgr，因为它要连 MySQL 并完成建库建表，是依赖的源头；接着是 sign、transaction、event 这类附属服务；最后才是 front。front 放最后是有原因的，它要直连链节点，如果链刚被脚本拉起来还在热身，front 太早启动会打出一连串连接重试，日志难看还容易误导排查方向。

手工重启全家桶时也要守这个顺序，否则会在 node-mgr 日志里看到一堆连不上 front 的干扰信息。我一般写成固定顺序的循环：

for s in node-mgr sign transaction event front; do if [ -d ~/WeBASE/webase-$s ]; then echo "restarting $s ..." bash ~/WeBASE/webase-$s/start.sh fi done

这个循环输出很安静，所以每启动一个我随手记一下时间，后面排错时好对照。start.sh 每个服务包里都有，负责 java -jar 拉起进程；对应地有 stop.sh。不要自己 ps 到 java 进程后手动 kill，服务间的注册信息会残留，重启后状态不一致，排查起来更乱。

4.3 部署完成后用两个命令确认全家桶活着

跑完 deploy.sh，理想情况是最后几行明确提示部署完成并给出访问地址。但这不等同于能用，下面这套检查我每次都会走一遍：

ls ~/WeBASE ps -ef | grep -E 'NodeManager|Front|Sign|Transaction|Event|fisco-bcos' | grep -v grep

~/WeBASE 下的目录和服务对应关系：

ps 输出里每个服务应该恰好一个 java 主进程，链上能看到 fisco-bcos 开头的节点进程，数量和你建的节点数一致。发现哪个服务没起来，直接看它自己的 logs；全起来但端口不通，回 2.3 的 ss 命令查端口。包里还有个 check-service.sh 值得养成习惯：它按端口维度列出每个服务的监听状态，比 ps 更直观，适合写进巡检脚本。

5. 部署翻车与排查：下载卡住、MySQL 连不上、节点注册失败、重启失联

5.1 现象：deploy.sh 卡在下载阶段，长时间没有新输出

现象：deploy.sh 执行到下载/解压阶段，屏幕停在一行 Downloading 之类的输出上，十几分钟没有新内容。原因九成是安装包托管在公网仓库，服务器到仓库的链路不稳定，下载进程在重试而不是报错；小概率是磁盘已满，解压写不进去导致挂起。

解决：先按 4.1 判断真卡还是慢，确认卡死后 Ctrl+C 终止。不要反复重跑同一段网络，正确做法是手动把需要的服务安装包提前下载到本机，再放进 webase-deploy 同目录，让脚本检测到本地包而跳过网络下载这一步。我自己的习惯是第一次部署前空档期就把包备好，省得现场干等。这个阶段的卡死本质是网络问题，别怀疑脚本逻辑，也别急着改脚本，绕过网络下载是最省事的路。

5.2 现象：日志里出现 Access denied 或 Public Key Retrieval is not allowed

现象：部署进入启动阶段后，node-mgr 起不来，日志里出现 Communications link failure、Access denied for user 或 Public Key Retrieval is not allowed。原因分三类：账号权限只授了一个库，服务建其他库时没权限；MySQL 8.0 默认认证插件与 5.1 系 connector 不兼容；密码、端口或数据库名写错。

解决：把 3.1 的三条 SQL 原样执行一遍，重点确认 ALTER USER 那条对 8.0 生效；然后重启 node-mgr 验证：

bash ~/WeBASE/webase-node-mgr/stop.sh bash ~/WeBASE/webase-node-mgr/start.sh

确认权限没问题还报 connect fail，用 mysql -uwebase -p 在服务器本地连一次，排除网络层因素。最后检查 mysql-connector jar 是否真的被拷进了服务 lib 目录——这个文件缺失的症状和账号错误极像，都是启动即失败。我见过有人花半小时查 SQL 权限，最后发现是 jar 没放，这种低级事故最容易发生在大半夜的首次部署。

5.3 现象：服务全部启动，管理台里却看不到节点和群组

现象：java 进程和 fisco-bcos 进程都在，端口也在监听，但登录管理台后节点列表为空、群组数量为 0，front 页面显示连不上链。原因集中在三类：复用已有链时 SDK 证书与链不匹配；encryptType 和链的加密套件不一致；front 比链先启动，链没就绪导致初始握手失败。

解决：一步一步排除。先确认 front 到链的通道，本地执行下面命令看 20200 是否通：

nc -vz 127.0.0.1 20200

通了就看 front 日志里有没有 ssl handshake 字样，有就是证书或套件问题——把链节点配置目录里生成的 ca.crt、sdk.crt、sdk.key 原样覆盖到 front 的 conf 下，再确认 common.properties 里 encryptType 与链一致，重启 front。如果链是脚本自动建的，基本可排除证书问题，那多半是启动顺序惹的祸：把 front 放到最后重启一次，等链日志稳定输出共识消息后再访问，页面通常就正常了。

注意：进程健康不代表业务链路通，必须以管理台能不能看到节点为准。这个坑最坑的地方在于它会撒谎——所有进程看起来都活着。

5.4 现象：机器重启之后 5001、5002 全部失联

现象：服务器重启后 5001/5002 全部无法访问，ps 里 java 进程要么没有，要么在但端口没监听。原因基本就一个：WeBASE 全家桶没有注册成开机自启服务，靠的是 start.sh 手动拉起；重启后没人跑它，自然起不来。连带问题往往是 MySQL 也没起，node-mgr 就算被拉起，也会因连不上库而退出。

解决：先让 MySQL 用 systemd 托管（装 rpm 包时默认就有），再给 WeBASE 加一个自启入口。我实际用的是一行 crontab 调一个启动脚本：

@reboot sleep 20 && bash /opt/webase/start-all.sh >> /var/log/webase-start.log 2>&1

sleep 20 是等 MySQL 先就绪，start-all.sh 就是 4.2 那个 for 循环存成脚本。环境有 systemd 规范的话，也可以为每个服务写 unit 文件，注意用顺序依赖，前面配一个负责拉起 MySQL 的 unit 比较稳妥。配好之后趁环境热着再重启一次机器验证，别等真要用了才发现自启没生效。我在这上面翻过车，所以把重启后自检写成了部署清单的固定一项。

6. 部署后的验证与日常习惯：从端口自检到数据备份

6.1 用一条循环命令做端口自检

部署完成不等于可用，我习惯先跑一遍端口自检，把每个入口的 HTTP 状态码打出来：

for p in 5000 5001 5002 5004; do code=$(curl -s -o /dev/null -w '%{http_code}' --connect-timeout 3 http://127.0.0.1:$p) echo "port $p -> $code" done

5001、5002 返回 200 或 302 都算正常，因为登录页会做重定向；连接超时或 000 才需要进日志。这只是第一层验证，第二层看每个服务日志里的 Started ... Application in x seconds，有这个输出才算真正走完 Spring Boot 启动流程。

6.2 管理台第一件事不是写合约，而是改口令和建账户

首次登录管理台用的初始账号在包内 README 或部署文档里能找到，进去第一件事是改成强口令，别留着默认账号裸奔。然后进入私钥管理或账户管理，建一个链上账户，再用自带的 HelloWorld 示例合约走一遍部署-调用流程。这一步是对整条链路的最终验收：前端页面 → node-mgr → front → 链节点，任何一环断了，调用都会失败。能把这个 demo 跑通，部署才算真正收尾。

6.3 重部署前把备份变成肌肉记忆

WeBASE 重装很常见——改端口、升版本、换服务器。重来之前，库和数据比脚本值钱得多，我的固定动作是先备库再备配置：

mysqldump -uwebase -p --databases webasenodemanager webasetransaction > webase-$(date +%F).sql cd /opt/webase-deploy && zip -r webase-deploy-conf-backup.zip common.properties

mysqldump 把业务数据带走，zip 把配置带走，两份文件存到机器之外的路径。uninstall.sh 是清道夫，它会停服务并删数据库，没备份就执行等于亲手把后悔药扔了。再说个反向习惯：只想重装服务、保留数据和配置时，不要跑 uninstall.sh，而是把 ~/WeBASE 目录改名备份，重新解压包再跑 deploy.sh，脚本检测到库已存在会走增量路径，数据原样保留。

这些流程重复十几次之后，我最大的体会是部署本身没什么玄学，所有翻车最后都能在日志里找到一句话；而所有能提前做的检查——端口、权限、jar、证书——都值得做在 deploy.sh 之前。把这些检查排成固定动作之后，我几乎不再为部署熬夜，希望这些实际踩过的坑和习惯也能帮到你。

本文还有配套的精品资源，点击获取