【保姆级教程】Ubuntu 本地二进制包搭建 FISCO BCOS 4节点联盟链

本文介绍在 Ubuntu 环境下使用本地预编译二进制包快速搭建一条 4 节点 FISCO BCOS 联盟链的完整流程。适用于网络环境受限、无法直接从 GitHub 下载二进制的场景全程附带命令说明与常见坑点排查。一、环境准备1. 系统要求Ubuntu 20.04 / 22.04 LTS基础网络连通仅用于安装系统依赖2. 安装系统依赖执行以下命令安装建链所需的基础工具sudo apt update sudo apt install -y curl openssl wget如果显示以下内容忽略:1 http://th.archive.ubuntu.com/ubuntu jammy InRelease 忽略:2 http://security.ubuntu.com/ubuntu jammy-security InRelease 忽略:3 http://th.archive.ubuntu.com/ubuntu jammy-updates InRelease 忽略:4 http://th.archive.ubuntu.com/ubuntu jammy-backports InRelease永久修改 DNS推荐Ubuntu 22.04 原生方式Ubuntu 22.04 默认使用systemd-resolved管理 DNS修改配置文件永久生效重启不丢失。1. 编辑 resolved 配置sudo nano /etc/systemd/resolved.conf找到[Resolve]段落修改为以下内容取消注释并填写 DNS 地址[Resolve] DNS223.5.5.5 114.114.114.114 #FallbackDNS #Domains #DNSSECno #DNSOverTLSno #MulticastDNSyes #LLMNRyes #Cacheyes #CacheFromLocalhostno2. 重启服务使配置生效sudo systemctl restart systemd-resolved3. 验证 DNS 是否生效nslookup mirrors.aliyun.com再次运行sudo apt update sudo apt install -y curl openssl wget说明curl/wget用于文件下载openssl用于生成节点证书与密钥。二、准备工作目录与资源1. 创建操作目录统一在用户主目录下创建工作文件夹后续所有操作都在该目录内执行cd ~ mkdir -p fisco cd fisco2. 获取官方建链脚本build_chain.sh是 FISCO BCOS 官方提供的一键建链脚本负责自动生成节点证书、配置文件与启停脚本。# 下载 v3.17.0 版本建链脚本 curl -#LO https://github.com/FISCO-BCOS/FISCO-BCOS/releases/download/v3.17.0/build_chain.sh # 下载完成后ls查看会生成以下文件 build_chain.sh # 添加执行权限 chmod ux build_chain.sh若 GitHub 访问缓慢可替换为 Gitee 对应版本的脚本地址。3. 准备本地二进制包如果服务器无法直接访问 GitHub 下载二进制可提前将fisco-bcos-linux-x86_64.tar.gz上传到当前fisco目录然后执行解压tar -zxvf fisco-bcos-linux-x86_64.tar.gz解压完成后执行ls确认当前目录出现fisco-bcos可执行文件。三、搭建 4 节点非国密联盟链在fisco目录下执行建链命令生成一条单群组 4 节点的联盟链bash build_chain.sh -l 127.0.0.1:4 -p 30300,20200 -e ./fisco-bcos参数详解参数说明-l 127.0.0.1:4指定节点部署 IP 为 127.0.0.1共部署 4 个节点-p 30300,20200P2P 通信起始端口为 30300RPC 服务起始端口为 20200-e ./fisco-bcos核心参数指定使用本地解压好的二进制文件跳过脚本自动联网下载步骤适合网络受限环境⚠️ 重要注意所有参数之间必须保留空格禁止连写如20200-e会导致参数失效-e后跟随的是二进制文件的相对/绝对路径必须确保文件真实存在且已解压执行成功后终端输出All completed并在当前目录生成nodes文件夹里面包含 4 个节点的完整配置。四、启动区块链网络1. 进入节点目录cd nodes/127.0.0.12. 一键启动所有节点bash start_all.sh3. 验证节点进程执行以下命令查看运行中的节点进程ps aux | grep fisco-bcos正常情况下会看到 4 个fisco-bcos进程分别对应 node0 ~ node3。4. 确认共识出块进入任意节点目录查看日志确认区块链共识正常tail -f node0/log/fisco-bcos.log日志中持续出现Report consensus success字样代表区块链共识正常开始持续出块。五、常用运维命令停止所有节点bash stop_all.sh重启所有节点bash stop_all.sh bash start_all.sh查看单个节点日志tail -f nodeX/log/fisco-bcos.logX 为节点编号 0-3查看节点连接数tail -f node0/log/fisco-bcos.log | grep connected peers六、常见问题排查1. 报错nodes DIR already exist原因nodes目录已存在脚本为防止覆盖旧配置直接终止。解决删除旧目录后重新执行建链命令rm -rf nodes bash build_chain.sh -l 127.0.0.1:4 -p 30300,20200 -e ./fisco-bcos2. 报错Download fisco-bcos failed原因脚本默认联网下载二进制网络访问 GitHub 失败。解决必须加上-e参数指定本地二进制路径并确保二进制文件已解压且路径正确。3. 解压报错not in gzip format原因下载的压缩包损坏实际为 404 错误页面。解决重新下载完整的二进制压缩包校验文件大小正常后再解压。4. 启动后看不到节点进程原因端口冲突、配置错误或二进制权限不足。解决检查端口占用情况给二进制添加执行权限chmod x fisco-bcos通过节点日志排查具体报错。至此一条本地 4 节点 FISCO BCOS 联盟链就搭建完成了后续可以基于 20200 端口的 RPC 接口部署智能合约开发存证、溯源、数据上链等业务应用。