返回

Hyperledger Fabric链码安装错误排查指南

Linux

Hyperledger Fabric 链码安装错误排查指南

在Hyperledger Fabric 网络中部署链码时，常常会遇到安装失败的问题。这类错误通常难以直接定位，它涉及复杂的网络配置、证书管理以及容器设置等多方面。这里，我们将深入分析可能导致“Error in installing the chaincode in Hyperledger Fabric”错误的原因，并提供有效的排查方法。

常见错误及原因分析

安装链码过程中最常出现的错误之一，是客户端无法与对等节点（peer）建立连接。以下面这个错误为例：

Error: failed to retrieve endorser client for install: endorser client failed to connect to peer0.hospital.health.cl:7056: failed to create new connection: context deadline exceeded

根据对等节点日志分析，我们发现深层原因在于TLS握手失败：

2024-10-07 10:45:02.348 UTC 0deb ERRO [core.comm] ServerHandshake -> Server TLS handshake failed in 666.832µs with error remote error: tls: bad certificate server=PeerServer remoteaddress=127.0.0.1:53694
...
2024-10-07 10:45:02.348 UTC 0dec DEBU [grpc] InfoDepth -> [core] Creating new client transport to "{Addr: \"127.0.0.1:7051\", ServerName: \"127.0.0.1:7051\", }": connection error: desc = "transport: authentication handshake failed: tls: failed to verify certificate: x509: cannot validate certificate for 127.0.0.1 because it doesn't contain any IP SANs"

这些日志指出对等节点在TLS握手过程中遇到以下几个关键问题：

  • 证书错误 (TLS: bad certificate) : 对等节点无法验证接收到的TLS证书，表明证书配置有问题。
  • IP SAN 缺失 : 证书缺少IP SAN(Subject Alternative Name)，这导致不能将127.0.0.1识别为有效的主机名。

还有一点需要关注：客户端容器可以 ping通对等节点容器，并且使用容器名称可以正常解析IP地址，这意味着网络连通性基础层面没有问题。更具体的是 TLS 证书验证流程有问题。同时，我们观察到 curl 测试也出现了连接被拒绝的现象，再次印证TLS证书验证或者端口转发可能配置不正确。

解决方案

方案一：校验证书SANs配置

原理

X.509证书必须包含正确的主机名和/或IP地址（通过SANs字段指定）才能通过TLS验证。 如果证书中不包含目标对等节点的正确主机名或IP，验证过程会失败。

操作步骤

  1. 修改crypto-config.yaml: 在crypto-config.yaml文件中，对PeerOrgs下的Template字段中TLS的Hosts配置项添加所有可能用来连接此对等节点的名称，务必同时添加节点的域名和IP地址，例如：

        PeerOrgs:
    - Name: Org1
        Domain: hospital.health.cl
        EnableNodeOUs: true
        Template:
        Count: 1
        TLS:
            Enabled: true
            Hosts:
            - peer0.hospital.health.cl
            - 127.0.0.1
            - 0.0.0.0
        Users:
        Count: 1

    增加 0.0.0.0 可以接受任意ip地址发起的连接请求，是一个通用的配置方法。

  2. 重新生成证书: 修改后，使用cryptogen工具重新生成网络证书：

  ./bin/cryptogen generate --config=./crypto-config.yaml

  1. 替换证书: 使用新的证书替换现有对等节点的证书，具体步骤取决于你的部署方式，对于使用docker的情况需要重新构建网络并更新映射的证书文件。

    • 对于docker-compose的情况，重新构建docker image。

      docker-compose down -v  #清理网络，可选
docker-compose up -d

  2. 重启对等节点 务必重启对等节点让更新后的配置生效。

额外安全建议

只在调试阶段使用 0.0.0.0，生产环境应该限制允许连接的ip地址或网络， 证书中的域名应该严格和服务器部署时使用域名保持一致。 建议通过设置负载均衡设备提供稳定服务入口。

方案二：检查端口转发和监听地址

原理

docker 的端口映射会将容器内部的端口映射到宿主机或指定的网卡，而网络请求是通过定义的 ip和port发送的。

操作步骤

  1. 确认 docker端口映射配置: 检查对等节点的 docker-compose.yaml 或者 docker run 命令， 确定是否正确映射了 7056 端口。特别注意宿主机（localhost）和容器内的IP与端口映射。确认 端口号没有被其他应用占用。

      ports:
  - "7056:7051"  # 外部7056 映射到内部7051，注意此处
  - "7060:7052"

  2. 核对监听地址:
    确保对等节点监听地址CORE_PEER_LISTENADDRESS 与容器网络接口和宿主机监听的网卡地址匹配。通常可以使用 0.0.0.0 来接受任意地址的连接，如果确认映射的端口没有问题，可以改为 0.0.0.0:7051。同时保证配置里的gossip端口也要一致。

     environment:
   - CORE_PEER_LISTENADDRESS=0.0.0.0:7051

  3. 使用容器ip访问 从客户端容器里通过 docker网段ip地址尝试访问对等节点，比如 curl -v https://<peer-container-ip>:7056 --cacert /var/hyperledger/peer/tls/ca.crt, 确认是否可以在容器之间网络畅通

  4. 更新配置文件: 根据修改的情况，同步修改网络定义配置文件，比如connection.yaml,使sdk和cli连接时使用的端口与更新后保持一致。

    • 重启 peer 服务
    • 使用cli 尝试重新安装链码
 peer lifecycle chaincode install patient-chaincode.tar.gz

方案三： 核对节点对等信息

  1. 确认 chaincode 安装目标 peer 是否正确。可以使用如下命令进行检查：
  peer channel getinfo -c <channelName>

查看结果中的 peer 信息， 确保 patient-chaincode 目标 peer 是否处于活动状态且为endorse node节点
2. 通过对等节点自身的grpc调试命令 peer node status 检查peer 状态信息是否正确

安全建议

确保所有组件之间的网络流量都使用 TLS 加密。 使用强密码管理所有秘钥。 配置访问控制规则， 只允许需要的组件间网络访问。 使用专业的网络负载均衡和防护措施。定期更新和审查配置。

结论

解决Hyperledger Fabric链码安装错误需要细致排查，定位问题的核心往往需要综合分析错误日志，并仔细核对网络、证书、端口及节点配置信息。 本文讨论了导致这类错误的常见原因以及相应的解决方案。遵循这些步骤和建议，可以大幅度提高部署成功率，减少后续维护负担。