简介Web应用部署是一项系统性工程涉及服务器配置、网络协议、数据库管理、负载均衡、安全性设置与容器化等环节。这份专为部署与运维场景打造的工具资源包适合需要搭建或维护Web应用的中初级运维人员、后端开发者及DevOps初学者可帮助理解从环境准备到上线部署的完整链路。压缩包共29个文件以Shell脚本11个与Python脚本10个为核心辅以YAML编排配置、properties属性配置、Markdown文档及Nginx等配置文件整体仅55KB轻量且聚焦。目前已有189人学习下载。内容包含部署入口脚本、多版本升级脚本、Docker Compose模板和公共配置示例覆盖环境检测、依赖检查、服务启停、配置同步等常用操作同时提供安装指南与英文README便于按文档对照实践有效降低部署过程中的重复配置与排错成本。1. webase-deploy.zip 到底是什么不是源码包是一键部署开关有人把 webase-deploy.zip 当成普通 Java 工程 zip一解压就想找可执行的 jar找不到就怀疑人生。实际上它是微众银行 WeBASE 平台的一键部署工具负责把 webase-front、webase-node-mgr、webase-sign、webase-transaction、webase-web 五个子服务一次性装到目标服务器上省去逐个拉代码、改配置、编译启动的过程。要跑通它你手头还得有一条已经启动的 FISCO BCOS 链、一个 MySQL 实例和匹配的 JDK。它解决的是“底层链有了但管理台和开发接口缺一个中间层”的问题适合自己搭联盟链、又想快速要一个管理后台的团队。只要 config.ini 写对它就是个贴心的部署工人写错一个 IP五个服务可能全部变成黑匣子这是下文要展开的重点。2. 部署前的三块地基JDK8、MySQL 和一条已经跑起来的链2.1 为什么 webase-deploy 不把 MySQL 和节点一起装好第一反应通常是既然是“一件部署”为什么不连数据库、连底层链一起装完非要我手动准备一堆东西我一开始也这么想后来被坑过两次就明白了。webase-deploy 只负责部署 WeBASE 自身默认假定你已经提供了 MySQL 和 FISCO BCOS 节点。原因很简单MySQL 的版本、字符集、权限体系每个团队差异很大让部署脚本自动装数据库极容易把你已有的数据库实例搞坏底层链又往往涉及多个机构、多个服务器共识节点不是一台机器能决定的如果部署工具擅自建链后面多机扩展会非常痛苦。所以你要把它理解成“中间件安装工”不是“全栈安装师”。它要做的事情是连接 MySQL 建库建表连接底层节点做前置代理然后把五个子服务串起来。它需要的输入非常明确一个能连上的数据库、一个能连上的节点、一个能跑的 JDK。这三样不稳定后面再怎么看配置都是在黑匣子里猜。在动手之前先看一眼 WeBASE 五个子服务的分工这样看日志时才知道是哪个环节出了问题。子系统默认端口职责webase-web5000管理台前端浏览器访问入口webase-node-mgr5001节点、私钥、用户、合约的管理服务webase-sign5004私钥签名服务负责交易签名webase-transaction5005交易上链服务把业务请求转成交易webase-front5002节点前置直连 FISCO BCOS 节点这五个服务都起来浏览器里才能看到完整的管理台任何一个端口没监听表现都是“某个页面转圈”或者“接口报错”。2.2 环境自检脚本JDK8、MySQL 客户端和 Python 一次查完我一般会在解压 zip 之前先跑一轮自检别等 deploy.sh 跑了一半才告诉你 java 版本不对。# JDK 版本WeBASE 对 JDK8 最友好 java -version # MySQL 连通性能进客户端就算过 mysql -h 127.0.0.1 -P 3306 -uwebase -pYourPass_2024 -e select version(); # python 版本deploy 脚本会调用 python 做文件替换和端口探测 python --version第一行看 java 和 javac 是否都在 PATH 里。很多翻车案例是 java 能运行但脚本调 javac 找不到因为只配了 JAVA_HOME忘了把 $JAVA_HOME/bin 写进 PATH。如果你是在 Linux 上用 JDK8 zip 下载方式安装的记得解压后把环境变量写进 /etc/profile别只在当前终端 export否则换个 session 部署脚本又找不到了。第二行是 MySQL 连通性测试注意用户名和密码要带引号密码里有特殊字符时尤其容易踩坑。第三行的 python 版本不用太苛刻2.7 和 3.x 都能用但别用太老的。这里有个小细节deploy.sh 里有 sed 替换逻辑依赖 python 处理编码如果 python 命令不存在脚本不会立刻报错而是等到初始化数据库时才变得莫名其妙所以这一步别省。2.3 建链脚本先跑通30300、20200、8545 三个端口都必须监听WeBASE 不是独立软件它要连到一个真实的链上。常见做法是先用 FISCO BCOS 的建链脚本生成四个节点然后启动所有节点。命令大致是这样# 假设已经从 release 页拿到了 build_chain.sh bash build_chain.sh -l 127.0.0.1:4 -p 30300,20200,8545 bash nodes/127.0.0.1/start_all.sh ss -lntp | grep -E 30300|20200|8545建链脚本的 -p 参数一次性指定了三组端口30300 是节点间 p2p 通信端口20200 是 channel 端口front 子服务靠它连节点8545 是 rpc 端口用于链上查询和发送交易。这三个端口只要有一个没监听webase-front 就会一直重试连接日志里反复出现connect to node failed。这里有个很容易犯的错如果你是多机部署-l 127.0.0.1:4表示只在当前机器建四个节点那么后续 config.ini 里的 node.ip 也必须填 127.0.0.1不能填外网 IP。deploy 脚本不会帮你做地址转换它拿着 node.ip 去拼接连接地址填错一个字段整个 channel 连接就断掉。建议先 curl 一下节点的 status 接口确认节点的 rpc 端口真的能响应再进入 zip 部署阶段。2.4 给 WeBASE 单独建库并授权兼顾 mysql zip 安装的坑MySQL 建议单独建一个库不要直接拿 root 让 webase 用。deploy.sh 要在库里建很多表如果 root 密码过期或者账号只能本地登录部署中途就会卡住。CREATE DATABASE IF NOT EXISTS webase DEFAULT CHARACTER SET utf8mb4; CREATE USER webase% IDENTIFIED BY YourPass_2024; GRANT ALL PRIVILEGES ON webase.* TO webase%; FLUSH PRIVILEGES;数据库名不要用默认的webase以外的复杂名字因为 config.ini 里要写写错一个字母后面全是 1054 unknown column 错误。字符集要选 utf8mb4WeBASE 的表里会存私钥描述、合约信息这类文本utf8 在特殊字符场景下会报 Incorrect string value。如果你的 MySQL 是用 mysql zip 安装方式装的绿色版注意官方 zip 解压后里面没有 data 目录必须先执行 mysqld --initialize-insecure 或者带随机密码的初始化否则服务能起来但 root 密码不是你预期的那个用 mysql -uroot -p 怎么试都进不去。这类问题不属于 webase-deploy但它是部署前最常见的拦路虎提前把它理顺后面跑 deploy.sh 会顺利很多。3. 解开 webase-deploy.zipconfig.ini 写对、wasm/solidity 选对、deploy.sh 别硬碰3.1 zip解压的正确姿势在 Linux 上直接解压别在 Windows 解压后再传zip 包拿到手第一件事是校验完整性。有人图方便在 Windows 上先解压再把目录传到 Linux 服务器结果 deploy.sh 执行到一半报找不到命令原因是脚本的可执行权限和软链接在 Windows 侧丢失了。我一般直接在 Linux 服务器上解压unzip webase-deploy.zip cd webase-deploy ls -lls 的输出里要能看到 deploy.sh、config.ini、common.properties 这些文件。如果你在解压时看到invalid zip archive: could not find eocd这种报错通常不是命令问题而是 zip 文件本身被截断了或者上传时用了 ASCII 模式把二进制搞坏了。解决方式是重新上传并且用unzip -t webase-deploy.zip先测一下压缩包完整性测试通过再解压。解压后先给脚本加可执行权限这不是多此一举很多部署失败都是这条没做chmod x deploy.sh *.sh3.2 config.ini 必须改的几个字段MySQL ip、节点 ip、org 名称webase-deploy 的解压目录里config.ini 是真正的入口。很多新手一上来就改端口号结果把内部服务端口改乱了。实际上你只需要关心下面这一组字段。[mysql] ip127.0.0.1 port3306 userwebase passwordYourPass_2024 dbwebase [node] ip127.0.0.1 agencyagencyA p2p_port30300 channel_port20200 rpc_port8545 [webase] encryptType0mysql 这一段的 ip 是你 MySQL 所在机器的地址如果你把 webase 装在 A 机器MySQL 装在 B 机器这里就不能写 127.0.0.1必须写 B 机器的 IP并且 B 机器 MySQL 要允许远程登录。检查方法很简单在你准备部署 webase 的那台机器上用 mysql 命令连一下能连上再进下一步。node 这一段最关键的是 channel_port它必须和建链时指定的 20200 一致。p2p_port 和 rpc_port 分别对应建链的 30300 和 8545。agency 是机构名单机构测试可以随便填但多机构部署时每个机构 webase-deploy 里的 agency 不能都写成 agencyA否则链上证书校验会出问题。encryptType 后面讲。3.3 理解 deploy.sh 的“一键”建表、拉依赖、启动服务配置改完先别急着跑要知道 deploy.sh 到底帮你做了什么。它的大致顺序是连接 MySQL 并初始化数据库表检查各子服务的依赖包启动 webase-front、webase-node-mgr、webase-sign、webase-transaction、webase-web。它不是一条命令从头静默跑到尾日志会持续滚动任何一步失败都会以非零退出码结束。bash deploy.sh最常见的手法是直接执行这个命令。脚本会先输出当前要部署的版本和前置检查结果看到connect database success再继续往下走。如果卡在start webase-front这一步不要反复重跑整个脚本先去看 webase-front 子目录下的日志绝大多数情况是 channel 端口连不上节点。deploy.sh 也支持参数常见做法是bash deploy.sh install all安装全部子服务或者指定安装某几个服务。这样做的好处是如果你只需要 node-mgr 和 web不想部署 sign 和 transaction可以手动指定减少不必要的进程占用。但前提是你清楚各服务之间的依赖关系否则管理台上看着有节点实际交易功能是缺的。3.4 wasm 与 solidity 的选择以及 encryptType 的一致性这个选项被很多人忽略等部署完才后悔。config.ini 里有一个和合约语言相关的选择它决定了后续上传合约时管理台按哪种字节码格式解析。FISCO BCOS 传统版本使用 solidity 合约而 3.x 版本支持 liquid 合约字节码格式完全不同。如果建链脚本生成的是支持 liquid 的链但你在 config.ini 里选了 solidity部署后 webase-front 虽然能起来上传合约时却会报合约格式错误。反过来全链都是 solidity 合约你把 wasm 选项打开前端页面也显示不出代码内容。这个参数必须在部署前定死中途改的话最好把数据库删掉重建因为已经写入的表结构不会自动变。判断方法很简单回到 build_chain.sh 建链参数看当初建链是否有-w之类的参数。没有特殊参数就选 solidity确认不了就默认选 solidity网上能找到的开源教程和现成合约大部分都是 solidity 格式。这台机器如果只是测试用途两个都试着部署一遍成本也不高但别在生产链路上一遍遍试。3.5 端口占用是部署期最容易翻车的地方五个子服务默认端口是 5000、5001、5002、5004、5005服务器上只要之前装过其他 Web 服务或者旧的 WeBASE这几个端口就很容易被占。deploy.sh 启动某个服务失败时日志会提示端口被占用但你不会第一时间看到。我一般会在部署前先做一次端口探测for port in 5000 5001 5002 5004 5005; do ss -lntp | grep :$port || echo $port free done如果端口被占优先改 config.ini 里对应的端口映射不要直接 kill 掉现有进程尤其当现有进程是另一个环境在用的时候。webase-web 的默认端口映射在 config.ini 里有专门字段改完重启相应服务即可。注意改端口后防火墙也要同步放行很多服务起来了但浏览器访问不了问题其实出在 firewalld 或安全组规则。4. 避坑zip 部署最容易翻车的五个点以及每一步怎么查日志4.1 MySQL 连接失败root 密码不是你记的那个现象deploy.sh 跑了两分钟日志里出现com.mysql.cj.jdbc.exceptions.CommunicationsException: Communications link failure或Access denied for user webaselocalhost。原因普遍有三个一是 config.ini 里 mysql.password 写错二是 MySQL 账号 host 是 localhostwebase 从本机以外的地址连接被拒三是数据库客户端和服务端版本差异导致认证插件不兼容。解决先在命令行手动验证一次连接。上一步建的 webase 账号如果还有问题回到 MySQL 执行确认SELECT user, host FROM mysql.user WHERE userwebase; ALTER USER webase% IDENTIFIED BY YourPass_2024; FLUSH PRIVILEGES;这里有个血泪经验密码不要包含#和config.ini 是 ini 格式特殊字符很容易被解析成注释或参数分隔符你看着密码没问题脚本拿到的是截断后的半截密码。部署环境的数据库密码最好用一段无特殊字符的长字符串省得后来排查半天。4.2 webase-front 起不来channel 端口连不上节点现象deploy.sh 卡在start webase-front查看webase-front/logs/下的日志反复出现connect to node failed或Channel connections error。原因config.ini 里 node.channel_port 和建链脚本的 -p 参数不一致。常见场景是建链用了 30300,20200,8545但部署时把 channel_port 写成了 30300front 拿 p2p 端口当 channel 端口去连节点当然不认。解决确认建链命令里第二个端口号比如-p 30300,20200,8545时 channel_port 就是 20200。然后直接用 nc 测一下端口连通性nc -vz 127.0.0.1 20200如果端口不通回到节点目录执行bash start_all.sh重新启动所有节点。还有一种情况是节点起来了但还在共识切换中等十几秒再试别立刻重跑 deploy.sh。这个坑之所以常见是因为很多人分不清 30300 和 20200 的区别建链时三个端口一眼扫过去只记住了第一个。4.3 依赖下载到一半失败gradle 和 maven 仓库超时现象deploy.sh 执行到某个子服务构建阶段日志停在Downloading...十几分钟不动最后报Could not resolve all dependencies。原因部署脚本会去远程仓库拉取 jar 包依赖。服务器网络不稳定或者默认仓库响应慢时很容易卡住。注意这里不是 zip 包解压问题而是 jar 包下载超时。解决把 Gradle 或 Maven 仓库地址换成镜像仓库webase-deploy 解压目录下能找到对应的构建配置文件修改其中的仓库地址。改完建议清掉缓存目录再重跑不然残留的损坏 jar 会导致同样的结果rm -rf ~/.gradle/caches bash deploy.sh install all依赖下载失败还有一个隐藏原因磁盘空间不足。zip 解压后本身不大但 gradle 缓存加子服务构建产物很容易堆到几个 GB用df -h看下根目录剩余空间低于 5GB 就要小心了。4.4 wasm 和 solidity 选错合约上传后管理台一片红现象部署和登录都正常但在管理台上传一个标准 solidity 合约时页面提示call contract error或交易回执状态为失败查看交易 hash 链上结果不是成功。原因这不是 webase-deploy 的 bug而是 config.ini 里的合约类型和底层链支持的合约格式不匹配。以太坊系的 solidity 合约在 liquid 链上无法按原格式解析字节码入口都不对。解决确认建链脚本是否有支持 liquid 的参数。如果已经部署完才发现选错最干净的做法是修改 config.ini 后把 WeBASE 数据库删掉重建然后重新bash deploy.sh。只改配置不重建库表结构里残留的合约类型标记还会影响后续交易。部署前花一分钟确认这件事比事后删库重建省太多时间。4.5 重启服务器后服务全没缺少守护进程现象everything works但机器一重启五个服务全部消失管理台打不开数据库还在节点却可能也没起来。原因deploy.sh 默认只是启动服务没有把它们注册成开机自启。很多人以为一键部署连自启都配好了实际并不是。解决把 WeBASE 各子服务和底层节点都托管给 systemd 或者 supervisord。下面是一个 systemd 单元的例子我一般按服务各写一个[Unit] Descriptionwebase-node-mgr Afternetwork.target mysqld.service [Service] Userapp ExecStart/data/webase-deploy/webase-node-mgr/start.sh Restartalways RestartSec5 [Install] WantedBymulti-user.target注意 ExecStart 的路径一定要写你实际解压目录里的那个 start.sh不要照抄。写完systemctl daemon-reload再systemctl enable webase-node-mgr。以后服务器重启至少中间件这一层不会再让你手动敲命令。5. 部署后的最后一个动作验证端口、进程、日志再跑通一次合约5.1 先花两分钟验证五个服务是不是真的活着部署脚本返回 success 不代表所有进程都稳定。我每次解压 deploy 完都会执行同一套命令ss -lntp | grep -E 5000|5001|5002|5004|5005 ps aux | grep webase | grep -v grep端口列表要能看到五个监听进程列表里至少能看到五个 java 进程。如果少了一个去对应目录下的 logs 里 tail 一下不要急着说部署成功。管理台能打开只是第一层接口能调通才是真成功。5.2 用一个 HelloWorld 合约走通完整链路打开浏览器访问 5000 端口用默认管理员账号登录后在管理台里新建一个用户然后上传一个最简单的HelloWorld.sol合约部署并调用一下查询方法。这一步看着简单但它验证的是 front 连节点、node-mgr 管用户、sign 做签名、transaction 上链的完整链路。只要管理台上能看到部署成功和返回的区块高度这套 webase-deploy.zip 的部署就算真正闭环了。如果第一次调用失败优先去 webase-transaction 的日志里看交易回执报错信息比管理台页面上的提示要具体得多。5.3 我的固定习惯把 config.ini 和 zip 一起归档部署完成不是终点我通常会把改好的 config.ini 单独备份。下次重建环境直接在 Linux 里用 zip 压缩到当前目录打包一份现场存档zip -r webase-backup.zip webase-deploy/config.ini之后不管是测试环境要复制一套还是线上环境误删了目录都能拿这份备份快速恢复。WebASE 这套东西其实不玄绝大多数坑都集中在 MySQL 连接、channel 端口、合约类型、服务自启这四个方面。只要部署前把地基打稳部署后把日志养成习惯它就能一直安静地跑下去。希望这些经验能帮你少走一次从头再来希望帮到你。本文还有配套的精品资源点击获取