Hyperledger Fabric 通道配置文件和容器环境变量详解
摘要
Fabric 网络启动的过程中需要进行大量配置，新学时对各个配置的作用一无所知，这导致我曾在网络出问题时先对配置文件的内容进行排列组合后再祈祷它能在某个时刻顺利运行，因此掌握 fabric 各个配置项的含义至关重要。本文对 configtxgen 的配置文件 configtx.yaml 进行了详细的分析解释，对 peer 、 orderer 、 fabric-ca 容器的常用环境变量也给除了详细说明，其中某些配置由于比较罕见因此并没有展开介绍，直接使用默认值即可，会在将来用上时再更新。
准备介绍
Fabric 节点的主配置路径为 FABRIC_CFG_PATH 环境变量所指向路径（默认为/etc/hyperledger/fabric）。在不显式指定配置路径时，会尝试从主配置路径下查找相关的配置文件。
| 项 | 配置文件路径 | 说明 |
|---|---|---|
peer |
$FABRIC_CFG_PATH/core.yaml |
指定 peer 节点运行时参数 |
orderer |
$FABRIC_CFG_PATH/orderer.yaml |
指定 orderer 节点运行时参数 |
fabric-ca |
$FABRIC_CA_SERVER_HOME/fabric-ca-server-config.yaml |
指定 CA 节点运行时参数 |
configtxgen |
$FABRIC_CA_SERVER_HOME/configtx.yaml |
指定 configtxgen 命令运行时参数 |
通常 fabric 服务有两种启动方式，一种是直接通过二进制命令直接在主机根据配置文件启动节点，另一种是使用docker根据环境变量和默认配置文件启动节点，其中除了 configtxgen 必须使用配置文件外，其余各服务都可以通过 docker 启动。因此本文将重点介绍 configtxgen 的配置文件及其它服务的 docker 环境变量。
configtx.yaml 详解
transaction 的英文缩写是TX(表示交易)， configtx 表示交易配置，所以和交易相关的配置，如应用通道、锚节点、 Orderer 服务等，都是在 configtx.yaml文件中配置的。 configtx.yaml 文件由6个部分组成，其中前5个部分的配置都是为了在 Profiles 被引用，在 Profiles 中引用其它部分的同时可以覆盖特定配置，本节示例文件来自于 configtx.yaml。1 2
Organizations
Organizations 用来定义不同的组织，其中 MSP(Membership Service Provider) 是一个组织的身份标识，在fabric中组织是由 MSPID 来唯一标识。
Organizations:
- &councilMSP # 定义一个组织引用，类似于变量，可在Profile部分被引用；所有带 & 符号的都是引用变量，使用 * 来引用
Name: councilMSP # 组织名称
ID: councilMSP # 组织ID
MSPDir: ../orgs/council.ifantasy.net/msp # 组织MSP文件夹的路径
Policies: # 组织策略
Readers:
Type: Signature
Rule: "OR('councilMSP.member')"
Writers:
Type: Signature
Rule: "OR('councilMSP.member')"
Admins:
Type: Signature
Rule: "OR('councilMSP.admin')"
# 此文件内的Orderer端口皆为容器内端口
OrdererEndpoints: # 定义排序节点（可多个），客户端和对等点可以分别连接到这些orderer以推送transactions和接收区块。
- "orderer1.council.ifantasy.net:7051"
- "orderer2.council.ifantasy.net:7054"
- "orderer3.council.ifantasy.net:7057"
AnchorPeers: # 定义锚节点，锚节点对外代表本组织通信
- Host: peer1.soft.ifantasy.net
Port: 7251
Capabilities
Capabilities 定义了 fabric 程序要加入网络所必须支持的特性，通过定义通道的能力，就明确了不满足该能力要求的 fabric 程序，将无法处理交易，除非升级到对应的版本。
Capabilities:
# Channel配置同时针对通道上的Orderer节点和Peer节点(设置为ture表明要求节点具备该能力)；
Channel: &ChannelCapabilities
V2_0: true # 要求Channel上的所有Orderer节点和Peer节点达到v2.0.0或更高版本
# Orderer配置仅针对Orderer节点，不限制Peer节点
Orderer: &OrdererCapabilities
V2_0: true # 要求所有Orderer节点升级到v2.0.0或更高版本
# Application配置仅应用于对等网络，不需考虑排序节点的升级
Application: &ApplicationCapabilities
V2_0: true
Application
Application 定义了应用内的访问控制策略和参与组织。
Application: &ApplicationDefaults
# 干预 创建链码的系统链码 的函数访问控制策略
_lifecycle/CheckCommitReadiness: /Channel/Application/Writers # CheckCommitReadiness 函数的访问策略
_lifecycle/CommitChaincodeDefinition: /Channel/Application/Writers # CommitChaincodeDefinition 函数的访问策略
_lifecycle/QueryChaincodeDefinition: /Channel/Application/Writers # QueryChaincodeDefinition 函数的访问策略
_lifecycle/QueryChaincodeDefinitions: /Channel/Application/Writers # QueryChaincodeDefinitions 函数的访问策略
# 关于 生命周期系统链码（lscc） 的函数访问控制策略
lscc/ChaincodeExists: /Channel/Application/Readers # getid 函数的访问策略
lscc/GetDeploymentSpec: /Channel/Application/Readers # getdepspec 函数的访问策略
lscc/GetChaincodeData: /Channel/Application/Readers # getccdata 函数的访问策略
lscc/GetInstantiatedChaincodes: /Channel/Application/Readers # getchaincodes 函数的访问策略
# 关于 查询系统链码（qscc） 的函数访问控制策略
qscc/GetChainInfo: /Channel/Application/Readers # GetChainInfo 函数的访问策略
qscc/GetBlockByNumber: /Channel/Application/Readers # GetBlockByNumber 函数的访问策略
qscc/GetBlockByHash: /Channel/Application/Readers # GetBlockByHash 函数的访问策略
qscc/GetTransactionByID: /Channel/Application/Readers # GetTransactionByID 函数的访问策略
qscc/GetBlockByTxID: /Channel/Application/Readers # GetBlockByTxID 函数的访问策略
# 关于 配置系统链码（cscc） 的函数访问控制策略
cscc/GetConfigBlock: /Channel/Application/Readers # GetConfigBlock 函数的访问策略
cscc/GetChannelConfig: /Channel/Application/Readers # GetChannelConfig 函数的访问策略
# 关于 peer 节点的函数访问控制策略
peer/Propose: /Channel/Application/Writers # Propose 函数的访问策略
peer/ChaincodeToChaincode: /Channel/Application/Writers # ChaincodeToChaincode 函数的访问策略
# 关于事件资源的访问策略
event/Block: /Channel/Application/Readers # 发送区块事件的策略
event/FilteredBlock: /Channel/Application/Readers # 发送筛选区块事件的策略
# 默认为空，在 Profiles 中定义
Organizations:
# 定义本层级的应用控制策略，路径为 /Channel/Application/Orderer
Orderer 定义了排序服务的相关参数，这些参数将用于创建创世区块或交易。
Orderer: &OrdererDefaults
OrdererType: etcdraft # 排序服务算法，目前可用：solo，kafka，etcdraft
Addresses: # 排序节点地址
- orderer1.soft.ifantasy.net:7051
- orderer2.web.ifantasy.net:7052
- orderer3.hard.ifantasy.net:7053
# 定义了 etcdRaft 排序类型被选择时的配置
EtcdRaft:
Consenters: # 定义投票节点
- Host: orderer1.council.ifantasy.net
Port: 7051
ClientTLSCert: ../orgs/council.ifantasy.net/registers/orderer1/tls-msp/signcerts/cert.pem # 节点的TLS签名证书
ServerTLSCert: ../orgs/council.ifantasy.net/registers/orderer1/tls-msp/signcerts/cert.pem
- Host: orderer2.council.ifantasy.net
Port: 7054
ClientTLSCert: ../orgs/council.ifantasy.net/registers/orderer2/tls-msp/signcerts/cert.pem
ServerTLSCert: ../orgs/council.ifantasy.net/registers/orderer2/tls-msp/signcerts/cert.pem
- Host: orderer3.council.ifantasy.net
Port: 7057
ClientTLSCert: ../orgs/council.ifantasy.net/registers/orderer3/tls-msp/signcerts/cert.pem
ServerTLSCert: ../orgs/council.ifantasy.net/registers/orderer3/tls-msp/signcerts/cert.pem
# 区块打包的最大超时时间 (到了该时间就打包区块)
BatchTimeout: 2s
# 区块链的单个区块配置（orderer端切分区块的参数）
BatchSize:
MaxMessageCount: 10 # 一个区块里最大的交易数
AbsoluteMaxBytes: 99 MB # 一个区块的最大字节数，任何时候都不能超过
PreferredMaxBytes: 512 KB # 一个区块的建议字节数，如果一个交易消息的大小超过了这个值, 就会被放入另外一个更大的区块中
# 参与维护Orderer的组织，默认为空（通常在 Profiles 中再配置）
Organizations:
# 定义本层级的排序节点策略，其权威路径为 /Channel/Orderer/Channel
Channel 定义要写入创世区块或配置交易的通道参数。
Channel: &ChannelDefaults
# 定义本层级的通道访问策略，其权威路径为 /Channel/Profiles
Profiles 配置用于 configtxgen 工具的配置入口，主要是引用其余五个部分的参数，其定义了一系列的配置模板，每个模板代表了特定应用场景下的自定义的通道配置，可以用来创建系统通道或应用通道。配置模板中可以包括 Application 、 Capabilities 、 Consortium 、 Consortiums 、 Policies 、 Orderer 等配置字段，根据使用目的不同，一般只包括部分字段。除了通道默认的配置，创建系统通道初始区块的模板一般需要包括 Orderer 、 Consortiums 字段信息（也可以包括 Applicaion 字段定义初始应用通道配置）：
Profiles:
# OrgsChannel用来生成channel配置信息，名字可以任意
# 需要包含Consortium和Applicatioon两部分。
OrgsChannel:
Consortium: SampleConsortium # 通道所关联的联盟名称
<<: *ChannelDefaults
Orderer:
<<: *OrdererDefaults
Organizations:
- *councilMSP
Capabilities: *OrdererCapabilities
Application:
<<: *ApplicationDefaults
Organizations:
- *softMSP
- *webMSP
- *hardMSP
Capabilities:
<<: *ApplicationCapabilities
peer 配置详解
当 Peer 节点启动时，会按照优先级从高到低的顺序依次尝试从命令行参数、环境变量和配置文件中读取配置信息，当从环境变量中读入配置信息时，除了日志使用单独的 FABRIC_LOGGING_SPEC 环境变量进行指定，其他都需要以 CORE_ 前缀开头，例如配置文件中的 peer.id 项，对应环境变量 CORE_PEER_ID 。
Peer 节点默认的配置文件读取路径为 $FABRIC_CFG_PATH/core.yaml ，如果没找到则尝试查找当前目录下的 ./core.yaml 文件，如果还没有找到则尝试查找默认的 /etc/hyperledger/fabric/core.yaml 文件。在结构上， core.yaml 文件中可以分为 peer 、 vm 、 chaincode 、 ledger 、 operations 、 metrics 六大部分， core.yaml 文件太过冗长在此不详细介绍，本节只介绍 Docker 环境下的常用环境变量（以后用到再更新），一个常用 示例配置 如下3：
peer-base:
image: hyperledger/fabric-peer:${FABRIC_BASE_VERSION}
environment:
- FABRIC_LOGGING_SPEC=info
- CORE_PEER_ID=peer1.soft.ifantasy.net
- CORE_PEER_LISTENADDRESS=0.0.0.0:7251
- CORE_PEER_ADDRESS=peer1.soft.ifantasy.net:7251
- CORE_PEER_LOCALMSPID=softMSP
- CORE_PEER_MSPCONFIGPATH=${DOCKER_CA_PATH}/peer/msp
- CORE_PEER_TLS_ENABLED=true
- CORE_PEER_TLS_CERT_FILE=${DOCKER_CA_PATH}/peer/tls-msp/signcerts/cert.pem
- CORE_PEER_TLS_KEY_FILE=${DOCKER_CA_PATH}/peer/tls-msp/keystore/key.pem
- CORE_PEER_TLS_ROOTCERT_FILE=${DOCKER_CA_PATH}/peer/tls-msp/tlscacerts/tls-council-ifantasy-net-7050.pem
- CORE_PEER_GOSSIP_USELEADERELECTION=true
- CORE_PEER_GOSSIP_ORGLEADER=false
- CORE_PEER_GOSSIP_EXTERNALENDPOINT=peer1.soft.ifantasy.net:7251
- CORE_VM_ENDPOINT=unix:///host/var/run/docker.sock
- CORE_VM_DOCKER_HOSTCONFIG_NETWORKMODE=${COMPOSE_PROJECT_NAME}_${DOCKER_NETWORKS}
working_dir: ${DOCKER_CA_PATH}/peer
volumes:
- /var/run:/host/var/run
networks:
- ${DOCKER_NETWORKS}
通常我们喜欢使用
extends方式分割通用容器，需要注意的是父容器的环境变量无法被子容器环境变量覆盖。
其中各项含义如下：
FABRIC_LOGGING_SPEC：指定日志级别CORE_PEER_ID： Peer 在网络中的 ID 信息，用于辨识不同的节点CORE_PEER_LISTENADDRESS：服务监听的本地地址，本地有多个网络接口时可指定仅监听某个接口CORE_PEER_ADDRESS：对同组织内其他节点的监听连接地址。当服务在NAT设备上运行时，该配置可以指定服务对外宣称的可访问地址。如果是客户端，则作为其连接的 Peer 服务地址CORE_PEER_LOCALMSPID：Peer 所关联的 MSPID ，一般为所属组织名称，需要与通道配置内名称一致CORE_PEER_MSPCONFIGPATH：MSP 目录所在的路径，可以为绝对路径，或相对配置目录的路径CORE_PEER_TLS_ENABLED：是否开启 server 端 TLS 检查CORE_PEER_TLS_CERT_FILE：server 端使用的 TLS 证书路径CORE_PEER_TLS_KEY_FILE：server 端使用的 TLS 私钥路径CORE_PEER_TLS_ROOTCERT_FILE：server 端使用的根CA的证书，签发服务端的 TLS证书CORE_PEER_GOSSIP_USELEADERELECTION：是否允许节点之间动态进行组织的代表（leader）节点选举，通常情况下推荐开启CORE_PEER_GOSSIP_ORGLEADER：本节点是否指定为组织的代表节点，与useLeaderElection不能同时指定为trueCORE_PEER_GOSSIP_EXTERNALENDPOINT：节点向组织外节点公开的服务地址，默认为空，代表不被其他组织所感知CORE_VM_ENDPOINT：docker daemon 的地址CORE_VM_DOCKER_HOSTCONFIG_NETWORKMODE：运行链码容器的网络
orderer 配置详解
排序节点在 Fabric 网络中为 Peer 提供排序服务。与Peer节点类似，排序节点支持从命令行参数、环境变量或配置文件中读取配置信息。环境变量中配置需要以 ORDERER_ 前缀开头，例如，配置文件中的 general.ListenAddress 项，对应到环境变量 ORDERER_GENERAL_LISTENADDRESS 。节点默认的配置文件读取路径为 $FABRIC_CFG_PATH/orderer.yaml ，如果没找到则尝试查找当前目录下的 ./orderer.yaml 文件，如果还没有找到则尝试查找默认的 /etc/hyperledger/fabric/orderer.yaml 文件。在结构上， orderer.yaml 文件中一般包括 General 、 FileLedger 、 RAMLedger 、 Kafka 、 Debug 、 Operations 、 Metrics 和 Consensus 八大部分， orderer.yaml 文件太过冗长再此不详细介绍，本节只介绍 Docker 环境下的常用环境变量（以后用到再更新），一个常用 示例配置 如下4：
orderer-base:
image: hyperledger/fabric-orderer:${FABRIC_BASE_VERSION}
environment:
- ORDERER_HOME=${DOCKER_CA_PATH}/orderer
- ORDERER_HOST=orderer1.council.ifantasy.net
- ORDERER_GENERAL_LOCALMSPID=councilMSP
- ORDERER_GENERAL_LISTENPORT=7051
- ORDERER_GENERAL_LISTENADDRESS=0.0.0.0
- ORDERER_GENERAL_BOOTSTRAPMETHOD=none
- ORDERER_CHANNELPARTICIPATION_ENABLED=true
# - ORDERER_GENERAL_GENESISMETHOD=file
# - ORDERER_GENERAL_GENESISFILE=${DOCKER_CA_PATH}/orderer/genesis.block
- ORDERER_GENERAL_LOCALMSPDIR=${DOCKER_CA_PATH}/orderer/msp
- ORDERER_GENERAL_LOGLEVEL=debug
- ORDERER_GENERAL_TLS_ENABLED=true
- ORDERER_GENERAL_TLS_CERTIFICATE=${DOCKER_CA_PATH}/orderer/tls-msp/signcerts/cert.pem
- ORDERER_GENERAL_TLS_PRIVATEKEY=${DOCKER_CA_PATH}/orderer/tls-msp/keystore/key.pem
- ORDERER_GENERAL_TLS_ROOTCAS=[${DOCKER_CA_PATH}/orderer/tls-msp/tlscacerts/tls-council-ifantasy-net-7050.pem]
- ORDERER_GENERAL_CLUSTER_CLIENTCERTIFICATE=${DOCKER_CA_PATH}/orderer/tls-msp/signcerts/cert.pem
- ORDERER_GENERAL_CLUSTER_CLIENTPRIVATEKEY=${DOCKER_CA_PATH}/orderer/tls-msp/keystore/key.pem
- ORDERER_GENERAL_CLUSTER_ROOTCAS=[${DOCKER_CA_PATH}/orderer/tls-msp/tlscacerts/tls-council-ifantasy-net-7050.pem]
- ORDERER_ADMIN_TLS_ENABLED=true
- ORDERER_ADMIN_TLS_CERTIFICATE=${DOCKER_CA_PATH}/orderer/tls-msp/signcerts/cert.pem
- ORDERER_ADMIN_TLS_PRIVATEKEY=${DOCKER_CA_PATH}/orderer/tls-msp/keystore/key.pem
- ORDERER_ADMIN_TLS_ROOTCAS=[${DOCKER_CA_PATH}/orderer/tls-msp/tlscacerts/tls-council-ifantasy-net-7050.pem]
- ORDERER_ADMIN_TLS_CLIENTROOTCAS=[${DOCKER_CA_PATH}/orderer/tls-msp/tlscacerts/tls-council-ifantasy-net-7050.pem]
- ORDERER_ADMIN_LISTENADDRESS=0.0.0.0:8888
- ORDERER_METRICS_PROVIDER=prometheus
- ORDERER_OPERATIONS_LISTENADDRESS=0.0.0.0:9999
- ORDERER_DEBUG_BROADCASTTRACEDIR=data/logs
networks:
- ${DOCKER_NETWORKS}
其中各项含义如下：
ORDERER_HOME：orderer 运行的根目录ORDERER_HOST：orderer 运行的主机ORDERER_GENERAL_LOCALMSPID： orderer 所关联的 MSPID ，一般为所属组织名称，需要与通道配置内名称一致ORDERER_GENERAL_LISTENPORT：服务绑定的监听端口ORDERER_GENERAL_LISTENADDRESS：服务绑定的监听地址，一般需要指定为所服务的特定网络接口的地址或全网（0.0.0.0）ORDERER_GENERAL_BOOTSTRAPMETHOD：获取引导块的方法，2.x版本中仅支持file或noneORDERER_CHANNELPARTICIPATION_ENABLED：是否提供参与通道的 APIORDERER_GENERAL_GENESISMETHOD：当 ORDERER_GENERAL_BOOTSTRAPMETHOD 为 file 时启用，指定创世区块类型ORDERER_GENERAL_GENESISFILE：指定创世区块位置ORDERER_GENERAL_LOCALMSPDIR：本地 MSP 文件路径ORDERER_GENERAL_LOGLEVEL：日志级别ORDERER_GENERAL_TLS_ENABLED：启用TLS时的相关配置ORDERER_GENERAL_TLS_CERTIFICATE：Orderer 身份证书ORDERER_GENERAL_TLS_PRIVATEKEY：Orderer 签名私钥ORDERER_GENERAL_TLS_ROOTCAS：信任的根证书ORDERER_GENERAL_CLUSTER_CLIENTCERTIFICATE：双向TLS认证时，作为客户端证书的文件路径，如果没设置会使用 TLS.CertificateORDERER_GENERAL_CLUSTER_CLIENTPRIVATEKEY：双向TLS认证时，作为客户端私钥的文件路径，如果没设置会使用 TLS.PrivateKeyORDERER_GENERAL_CLUSTER_ROOTCAS：信任的根证书ORDERER_ADMIN_TLS_ENABLED：是否启用 orderer 的管理服务面板ORDERER_ADMIN_TLS_CERTIFICATE：管理服务的证书ORDERER_ADMIN_TLS_PRIVATEKEY：管理服务的私钥ORDERER_ADMIN_TLS_ROOTCAS：管理服务的可信根证书ORDERER_ADMIN_TLS_CLIENTROOTCAS：管理服务客户端的可信根证书ORDERER_ADMIN_LISTENADDRESS：管理服务监听地址ORDERER_METRICS_PROVIDER：统计服务类型，可以为statsd(推送模式)，prometheus(拉取模式)，disabledORDERER_OPERATIONS_LISTENADDRESS：RESTful 管理服务的监听地址ORDERER_DEBUG_BROADCASTTRACEDIR：广播请求的追踪路径
fabric-ca 配置详解
在 fabric 官方示例中，通常使用 cryptogen 生成静态证书文件，但这种方式不适合用于生产环境，而 fabric-ca 可以在生产环境中为所有成员提供安全的证书服务。与其它类型节点类似， fabric-ca 支持从命令行参数、环境变量或配置文件中读取配置信息，且 fabric-ca 分为 fabric-ca-server 和 fabric-ca-client ，前者用于提供 CA 服务，后者用于向用户提供操作 fabric-ca-server 的方法。一个常用 示例配置 如下：
ca-base:
image: hyperledger/fabric-ca:${FABRIC_CA_VERSION}
environment:
- FABRIC_CA_SERVER_HOME=${DOCKER_CA_PATH}/ca/crypto
- FABRIC_CA_SERVER_TLS_ENABLED=true
- FABRIC_CA_SERVER_DEBUG=true
- FABRIC_CA_SERVER_CSR_CN=council.ifantasy.net
- FABRIC_CA_SERVER_CSR_HOSTS=council.ifantasy.net
networks:
- ${DOCKER_NETWORKS}
其中各项内容含义如下：
FABRIC_CA_SERVER_HOME：指定 fabric-ca-server 运行的根目录FABRIC_CA_SERVER_TLS_ENABLED：是否启用 TLSFABRIC_CA_SERVER_DEBUG：是否启用 debug 模式FABRIC_CA_SERVER_CSR_CN：指定证书主体的 cn 字段FABRIC_CA_SERVER_CSR_HOSTS：指定证书主体的 hosts 字段
参考
黑帽子技术. Hyperledger Fabric 通道配置文件解析. 掘金. [2022-03-22] ↩︎
chainbees. Fabric创建通道Channel的配置文件configtx.yaml详解. CSDN. [2021-12-17] ↩︎
黑帽子技术. Hyperledger Fabric Peer 配置解析. 掘金. [2022-03-22] ↩︎
黑帽子技术. Hyperledger Fabric Orderer 配置解析. 掘金. [2022-03-22] ↩︎