在上一篇文章里我们把 FISCO BCOS 链跑起来之后第一个实际需求几乎都是同一个怎么直观地看链上的数据。命令行敲curl调 RPC 接口能查但每次都去拼 JSON、数区块号、翻交易哈希时间一长真的会怀疑自己是不是在用上个世纪的数据库。这个时候给 FISCO BCOS 配一个区块链浏览器就是最自然的选择。区块链浏览器本质上就是一条链的“前台页面”你不需要懂 SDK 协议、不需要写代码打开浏览器就能看到当前块高、最新交易、节点状态、合约部署记录排查问题的时候能省下大量时间。这篇是基于 FISCO BCOS 官方浏览器组件的一次完整落地记录从架构拆解、部署步骤、核心工作原理到踩坑清单都会讲到适合刚把链搭完、正在犹豫要不要上浏览器的读者也适合已经部署过但遇到数据不同步、页面打不开等问题的朋友。1. 为什么需要区块链浏览器链上数据不是给人看的先说一个真实的痛点。FISCO BCOS 节点本身会把所有数据存下来但你能直接接触到的只有两类出口控制台命令行以及节点暴露出来的 JSON-RPC 接口。查看最新区块高度控制台里敲getBlockNumber可以查一笔交易先得把交易哈希复制出来再调getTransactionByHash拿回来的是一个六七百字节的 JSON 对象里边的input字段还是一长串十六进制。如果只是为了确认“这笔交易到底成功了没有”整个过程至少要 5 分钟而且非常容易看花眼。区块链浏览器解决了三件事。第一把区块、交易、回执、合约这些链上对象变成人可以读的列表。你打开页面就能看到“第 10002 个区块是哪个节点打包的包含 20 笔交易其中 18 笔成功”而不是面对一堆0x开头的哈希。第二把链的运行状态变成持续更新的监控面板。当前块高是否在涨、出块间隔是否稳定、节点之间是否断连、最近一小时 TPS 是多少这些指标直接决定一条链有没有“活着”。没有浏览器之前你只能写脚本定时轮询多个 RPC 节点再汇总工作量不小。第三为业务方提供一种低门槛的自助查询方式。联盟链里不只有核心开发还有运营、审计、合约对接方的技术同学。让他们直接连节点敲命令不现实但给一个浏览器地址什么问题都能自己来看。所以给 FISCO BCOS 搭一个区块链浏览器不是“锦上添花”而是链上基础设施的一部分。如果你维护的是一条生产环境或者准生产环境的链我建议在链稳定运行的第一周内就把它配上。2. 浏览器组件拆解与选型思路FISCO BCOS 生态范围里的区块链浏览器不止一个版本我在实际项目里主要用的是官方开源的browser组件它的代码结构比较清晰分为browser-backend、browser-frontend、browser-db三个部分。三者各司其职理解清楚之后部署和排错都会容易很多。2.1 后端服务连接节点并处理数据browser-backend是一个基于 Spring Boot 的 Java 服务也是整个浏览器的核心。它做的事情可以概括为通过 FISCO BCOS 的 Java SDK 与节点建立连接实时接收新区块通知然后把区块、交易、回执等原始数据解析出来落进 MySQL 数据库同时对外提供一组 RESTful API给前端页面查询使用。这里有一个需要特意强调的关键点浏览器后端连接的是节点的Channel 端口默认 20200不是 JSON-RPC 的端口。FISCO BCOS 的节点在启动时会同时监听多个端口其中 P2P 端口负责节点间通信RPC 端口提供 HTTP 形式的接口Channel 端口则专门给 SDK 使用支持更高效的双向通信和消息订阅。浏览器为了拿到“新区块产生”的实时推送必须走 Channel。很多第一次部署的朋友在这里踩坑——配置里填的是 8545 或者 30300 这种端口后端一直连不上日志里全是 connect timeout就是这个原因。后端还负责管理同步状态。节点上区块一直在出浏览器不可能每次重新从头扫一遍它需要记录自己已经同步到哪个块高了。启动时先从数据库读取上次的位置再继续往后拉如果中间因为停机或者网络波动漏掉了一些块后端会启动一个补偿机制把缺失的区块重新拉取。这一点我们在第 4 部分会详细分析。2.2 前端页面查询展示与交互入口browser-frontend是典型的 Vue 前端工程。它通过 HTTP 调用后端提供的接口把数据库里已经整理好的数据渲染成页面。主要页面包括首页大盘、区块列表、区块详情、交易列表、交易详情、账户列表、合约列表、节点列表等。首页大盘是运维人员最常看的页面。上面会展示当前块高、区块生产速度平均出块时间、交易总量、账户数量、节点数量以及最近一段时间内的交易走势曲线。这些指标不是直接读链上实时状态而是后端在入库时顺带做了统计更新到若干张聚合表中。页面定时刷新通常几秒一次所以可以当作链的“仪表盘”来用。区块详情页和交易详情页则承担了日常排查的功能。点进任意一笔交易你能看到交易哈希、所属区块高度、交易时间、发送方、接收方、Gas 消耗、执行状态成功还是失败、以及具体执行的合约函数和参数。如果交易失败了页面上会直接显示 revert 原因省去了去翻日志的功夫。2.3 数据存储MySQL 结构设计以及为什么不用链上数据库browser-db维护的是一套 MySQL 建表脚本所有链上数据都被转存到 MySQL 中。有些读者可能会问FISCO BCOS 不是已经把数据存在节点本地了吗为什么浏览器还要再存一份核心原因是数据形态不同。节点本地存的是 Merkle 树、区块文件、交易池等面向密码学校验和快速落盘的数据结构这些结构对“按哈希精确查找”非常友好但对“按时间范围统计”“按账户维度聚合”这类查询支持不够直接。浏览器的场景恰恰需要大量维度分析比如展示最近 24 小时交易量曲线、统计某一天部署了多少合约、列出某个账户所有发出的交易。如果每次都通过 SDK 去节点上现查不仅速度慢还会给节点带来很大的压力。所以浏览器选择用一张张关系表承载这些数据让所有页面查询都落在 MySQL 上又快又稳。数据库里比较核心的几张表包括区块表、交易表、回执表、账户表、合约表、节点信息表、统计聚合表、同步状态表。同步状态表特别重要它记录了浏览器的同步进度是判断浏览器“是否跟得上链”的关键依据。2.4 版本选型时要注意的坑FISCO BCOS 2.x 和 3.x 的浏览器组件不通用。如果你用的是 FISCO BCOS 3.x 的链务必选择配套的 3.x 分支或对应的浏览器版本反过来也一样。这个坑我见过不止一次有人把 2.x 的浏览器部署在 3.x 链上后端启动没问题但拉不到任何区块因为两者 SDK 的 Channel 协议差异很大数据编码格式完全不同。所以部署前第一件事是确认自己的链版本再去找对应的浏览器版本。3. 部署实操从零把浏览器跑起来这里以 FISCO BCOS 3.x 链 官方浏览器组件为例按我实际部署时走过的完整流程逐步说明。假设你已经有一台可以访问到节点 Channel 端口的服务器并且存在一个 MySQL 5.7 实例。3.1 环境准备与前置检查浏览器后端需要 JDK建议使用 JDK 8 或 JDK 11。前端构建需要 Node.js一般用 10.x 或 12.x 都可以如果离线的服务器上没有 Node也可以不构建前端只部署后端然后通过后端自带的静态页面访问取决于版本不过大部分时候还是建议把前端也部署好。数据库是必须的MySQL 5.7 以上字符集建议设置为utf8mb4因为链上数据可能包含各种编码内容用 utf8 偶尔会出现乱码或者插入失败。服务器上先做几个检查# 确认 jdk 版本 java -version # 确认 mysql 能连 mysql -h你的数据库地址 -uroot -p # 测试节点 Channel 端口是否通假设节点 IP 是 192.168.10.10 telnet 192.168.10.10 20200telnet检查是最容易被忽略但最有效的一步。如果 Channel 端口都不通后面后端怎么配置都是白搭。常见原因包括节点机器防火墙没放行、节点的config.ini里 Channel 监听地址写成了127.0.0.1、云主机安全组没加规则。这些在部署之前确认好能省出一个下午。节点端需要准备 SDK 证书。FISCO BCOS 使用了 TLS 加密通信Java SDK 必须持有合法的证书才能与节点握手。证书一般在链安装目录下的nodes/节点IP/sdk中里面包含ca.crt、sdk.crt、sdk.key三个文件。你需要把这几个文件从链节点所在的机器拷贝到浏览器后端服务器的配置目录中。3.2 下载源码并初始化数据库官方浏览器后端和前端都是开源项目可以直接用 Git 拉取对应版本的源码。版本号务必与链版本对齐。拿到源码后先处理数据库。# 进入数据库脚本目录执行建表脚本 mysql -uroot -p browser-db/install.sql执行完成后用下面的命令确认核心表是否都已经建好use browser; show tables;有tb_block、tb_transaction、tb_receipt、tb_account、tb_contract、tb_sync_status之类的表出现就说明初始化成功了。如果没有看到同步状态表建议检查一下脚本版本是不是和后端代码配套不配套会在启动后出现“某列不存在”的报错。数据库连接账号建议单独建一个不要直接给浏览器用 root虽然自己测试无所谓但线上的数据安全还是要注意CREATE USER browser% IDENTIFIED BY 你的密码; GRANT ALL PRIVILEGES ON browser.* TO browser%; FLUSH PRIVILEGES;3.3 修改后端配置后端的主要配置文件是application.yml也可能根据启动脚本加载application.properties。需要改的地方有三块数据源、节点连接、服务端口。数据源配置里最关键的是 URL除了数据库地址还要加上时区参数否则容易出现The server time zone value的报错。示例如下spring: datasource: url: jdbc:mysql://192.168.10.20:3306/browser?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai username: browser password: yourpassword driver-class-name: com.mysql.cj.jdbc.Driver节点连接部分FISCO BCOS 3.x 的 SDK 配置常写成类似bcos: sdk: account: keystorePath: conf accountFilePath: conf nodes: - nodeStr: node0 ip: 192.168.10.10 channelPort: 20200这里有一个细节channelPort填的是节点的 Channel 端口不是 RPC 端口。如果你部署的是多节点多群组环境每个群组的 Channel 端口可能一样因为它们属于同一套节点进程但如果你的浏览器只关心特定群组的数据一定确认清楚要连接哪一个群组这个配置往往在 SDK 的连接配置或者浏览器后端自己的群组 ID 配置里。如果填的群组不存在后端虽然能启动但拉不到数据。证书文件的路径一般也是conf目录启动时后端会在类路径下找ca.crt、sdk.crt、sdk.key。把前面准备好的三个 sdk 证书文件放到这个目录里。注意文件名不能错常见的一个问题是从节点目录拷贝过来时带着sdk.crt等名字还好但如果手动改名成node.crt之类的SDK 会报证书加载失败。3.4 编译并启动后端代码基于 Gradle 构建。在命令行里执行gradle build -x test构建完成后在build/libs目录下会生成一个可执行的 jar 包。启动前先确认当前目录下有conf目录包含application.yml和证书文件然后运行nohup java -jar browser-backend-xxxx.jar browser.log 21 启动过程观察日志是关键。正常启动时会看到类似“Start application success”的提示。如果出现异常优先查看日志里的堆栈下面几个是高频问题connect timed out网络不通或 Channel 端口、IP 填错。SSLHandshakeException证书不对检查证书是否与节点匹配。Access denied for user数据库账号密码错误。启动成功后后端默认监听 8080 端口具体端口以配置为准。可以先用 curl 调一个接口验证curl http://127.0.0.1:8080/block/timeOut如果能返回 JSON说明后端服务已经正常工作了。这时候打开数据库里的tb_sync_status表能看到已有同步记录的初始数据。3.5 前端部署与页面访问前端是 Vue 工程部署很简单。首先进入前端源码目录如果后端没有放在本机需要修改前端的API访问地址。具体文件一般在src/common/config.js或.env里把server或BASE_URL改后端的访问地址例如http://192.168.10.20:8080。然后安装依赖并构建npm install npm run build构建完成后会在dist目录生成静态文件把这些文件放到 Nginx 的 html 目录下。为了开发方便也可以直接npm run dev起来但线上推荐 Nginx 托管。记得在 Nginx 配置里把前端静态请求和后端 API 请求分开比如把/api开头的请求反向代理到后端 8080 端口否则直接用跨域方式访问后端浏览器控制台会报一串 CORS 错误。一个最小可用的 Nginx 关键片段location / { root /usr/share/nginx/html; index index.html; try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }一切就绪后浏览器访问 Nginx 所在机器的地址就能看到登录页。默认账号密码一般会在 README 里给出通常是admin/123456。首次登录后第一件事就是确认首页展示的当前块高和链上真实块高是否一致。如果不一致可以参考第 5 节的排查方法。4. 核心原理浏览器后端是怎样同步数据的很多人在部署成功后就以为结束了直到某一天发现浏览器显示的块高比链上低了1000多个块才开始研究浏览器到底是怎么工作的。这里把浏览器后端同步数据的机制讲透后续遇到问题就不会慌。4.1 基于SDK的实时区块消息订阅FISCO BCOS 的 Java SDK 支持通过 Channel 协议向节点订阅事件包括新块事件、交易通知事件等。浏览器后端启动时会向节点注册一个区块监听器。节点每生成一个新块就会通过 Channel 连接主动推送给浏览器后端。监听器拿到“新块高度”之后后端马上发起一次区块数据拉取。这样从新区块产生到浏览器页面出现这个区块延迟一般在一秒以内。如果把节点比作生产流水线浏览器后端就是流水线终点的质检员。节点每产出一个区块就像机器“叮”了一声质检员听到声音后跑过去把产品拿过来检查、登记。如果机器声音正常质检员的工作节奏非常及时。但如果机器一次连出多个块或者背压没有处理好质检员就可能跟不上速度堆积下来的区块就要靠后面讲的补偿机制来处理。4.2 区块拉取与数据落库流程收到新块通知后后端并不是只拉这一个块而是会做一次“批量补拉”判断。因为它不能保证通知一定不丢比如后端重启期间、网络闪断期间节点产生的块没有人听到“叮”声。所以每轮拉取前后端都会从tb_sync_status读取当前已处理的块高和目标块高可能是刚刚通知的块高也可能是节点的最新块高进行比较。如果发现小于目标高度就把中间缺失的区块一次性补拉回来。拉取一个区块时后端会同时拉取区块头和区块体内所有交易。对于每一笔交易再通过 SDK 获取它的交易回执回执里包含了执行结果、Gas 使用量、交易日志等关键信息。然后把这些数据分批插入到 MySQL 对应的表里。批量插入可以显著减少数据库 IO尤其是区块交易数量较大的场景。如果你在数据库执行过show processlist会看到隔几十毫秒就有一批INSERT或UPDATE语句这是正常的。同步状态表里的字段非常关键它记录了已同步到的块高、最新块高、状态以及更新时间。如果发现浏览器展示的块高长时间不动直接去看这张表能区分出是“节点没有新块”还是“浏览器收不到消息”还是“数据库写入失败”。4.3 为什么会有统计数据不准的现象浏览器首页的 TPS、交易趋势图等统计值并不是直接从链上某接口一次性拉出来的而是后端在落库时按时间窗口分钟、小时、天聚合写入统计表。如果你看到首页统计数据和实际交易记录对不上大概率是“统计表更新滞后”而不是“数据丢失”。这种情况一般等下一轮统计任务执行完就会恢复。但如果在生产环境对准确性要求很高建议还是定期核对统计表与基础表的数据量并监控统计任务的执行日志。理解了同步原理之后再去看部署时的各种配置就会明白为什么需要 JDK、为什么需要 Channel 端口、为什么需要证书这些都是为了建立一条稳定高效的链上数据管道。5. 实际操作中的典型问题与排查技巧部署运维这类组件经验往往比教程更能救命。这一部分我整理了从最初部署到现在遇到的高频问题每一个都有真实场景作为背景按“问题现象—排查思路—解决方案”的方式列出方便你按图索骥。5.1 后端启动但页面一直看不到区块这是最常见的问题表现是浏览器能打开后端日志也没报错但页面上的块高停留在 0 或者一直不变。第一步连上数据库执行select * from tb_sync_status;如果表里显示sync_status为异常、或者最新块高长期不变说明后端同步进程没有正常推进。这时候看后端日志重点搜索sync、block、error关键字。我遇到过的一种情况是后端连接了错误的群组它订阅的群组根本没有产生新块导致所有流程都“正常”但就是没数据。处理方法是在配置里明确指定正确的群组 ID。如果同步状态表为空说明后端还没开始写同步记录。检查一下后端启动日志里是否出现了“load group error”之类的警告如果有那就是 SDK 连接群组失败很大概率是群组不存在或者没有权限。5.2 SDK 证书加载失败报错信息通常包含Failed to load key store或CertificateException。原因包括证书文件缺失、文件名不对、证书与节点不一致、证书过期。FISCO BCOS 的节点证书有有效期如果链已经运行很久要确认证书是否还在有效期内。另外每次重新生成链后旧的 sdk 证书必须同步更新成新证书否则握手必然失败。判断证书是否匹配可以对比节点安装目录下sdk目录中ca.crt的哈希值与后端conf目录中ca.crt的哈希值。不一致就重新拷贝一次。5.3 页面能打开但接口报跨域错误前端部署在 Nginx 的 80 端口后端部署在 8080前端浏览器请求后端接口时会被 CORS 拦截。虽然在后端的 Spring Boot 配置里可能已经允许了跨域但生产环境最稳妥的做法是通过 Nginx 反向代理把所有/api请求转发到后端这样浏览器看到的所有请求都走同源不再存在跨域问题。如果你不想在后端暴露接口给外部更推荐这种方式。5.4 数据库连接池抛异常浏览器的写入频率不低如果数据库连接数设置得太小或者后端所在容器与数据库之间的网络不稳定可能会报connection pool exhausted或Communications link failure。解决方案分两步一是检查application.yml中的数据库连接池参数适当调大maximum-pool-size二是检查数据库端max_connections是否足够并确认没有其他应用把连接数占满。另外生产环境建议把数据库和后端部署在同一个局域网内避免公网远程连接的不稳定性。5.5 页面时间显示少了8小时这是典型的时区问题。后端服务默认使用服务器的时区但 Java 在序列化时间时可能采用 UTCMySQL 连接串如果没有指定serverTimezone也可能按服务器本地时区返回两边不一致就会出现差8小时。统一做法是在 MySQL 连接 URL 上明确指定serverTimezoneAsia/Shanghai同时启动后端的 Java 参数加上-Duser.timezoneAsia/Shanghai。这样无论操作系统时区怎样展示给用户的时间都是北京时间。5.6 浏览器长时间运行后占用内存高浏览器后端每拉一个块都会创建一批对象如果 JVM 堆内存配置太小加上 SDK 内部有一些缓存容量时间长了容易出现频繁 GC 或者 OOM。建议启动时给足内存java -Xms1g -Xmx2g -jar browser-backend-xxxx.jar具体内存大小根据链的区块频率和交易量决定。如果链上每秒产生的交易很多建议监控 JVM 老年代使用率超过 70% 就考虑扩容或者调整拉取批量大小。6. 部署之外日常使用中值得养成的几个习惯浏览器部署完只是开始日常运维中我还有几个小建议。第一定期检查同步状态表。可以把tb_sync_status的更新时间、最新块高做成一个监控指标接入告警平台一旦发现同步延迟大于 1 分钟就提醒。区块链浏览器是这个链路里最容易“悄悄掉队”的组件节点还在正常出块浏览器却因为数据库查询慢、磁盘空间满等原因停在了原地如果不看同步状态用户看到的永远是过期数据。第二前端页面默认账号密码一定要改。很多内部系统部署完就不管了默认密码挂在外网上这是很不安全的行为。即使只是内网使用也建议换成强口令并限制登录失败次数。第三备份数据库。浏览器的 MySQL 中存了链上所有数据的镜像虽然链本身是数据源头但如果浏览器被误删了想要重新从链上恢复完整数据需要重新初始化再从头扫一遍。链高度高、交易量大时这个过程非常漫长。所以定期对browser库做备份是性价比极高的操作。备份命令很简单mysqldump -uroot -p browser browser_backup_$(date %F).sql根据块高的增长速度可以每天或每周备份一次保留最近若干份即可。就区块链浏览器的使用体验来说我觉得最舒服的一点是它把一条联盟链的“数字脉搏”真正可视化了。以前判断链是否健康只能看监控指标现在随便让一个运营同学打开页面看一眼首页的块高和时间曲线就能说出“链上现在活跃不活跃”这对团队协作非常有帮助。如果后续你的链上合约数量变多还可以进一步浏览器的功能做二次开发比如把合约事件解析结果直接展示在交易详情页上让业务人员不用看十六进制就能理解每一笔交易发生了什么。总之先让浏览器稳定跑起来你会在实际使用中发现更多可以迭代的空间。
