应用程序开发 - 应用程序设计元素 - 连接配置文件
连接配置文件描述了一组组件，包括 Hyperledger Fabric 区块链网络中的对端节点，交易排序器和证书颁发机构。它还包含与这些组件有关的通道和组织信息。应用程序主要使用连接配置文件来配置处理所有网络交互的 网关，从而使其能够专注于业务逻辑。连接配置文件通常由了解网络拓扑的管理员创建。
在本主题中，我们将介绍：
- 为什么连接配置文件很重要
- 应用程序如何使用连接配置文件
- 如何定义连接配置文件
1. 场景
连接配置文件用于配置网关。网关之所以重要，其原因有很多，主要是简化应用程序与网络通道的交互。
发行和购买这两个应用程序使用配置有连接配置文件 1＆2 的网关 1＆2。每个配置文件都描述了 MagnetoCorp 和 DigiBank 网络组件的不同子集。每个连接配置文件都必须包含足够的信息，以使网关能够代表发行和购买应用程序与网络交互。请参阅文本以获取详细说明。
连接配置文件包含对网络视图的描述，以技术语法表示，可以是 JSON 或 YAML。在本主题中，我们使用 YAML 表示法，因为它使你更容易阅读。静态网关比动态网关需要更多的信息，因为动态网关可以使用 服务发现 来动态扩展连接配置文件中的信息。
连接配置文件不应该是网络通道的详尽描述。它只需要包含足够的信息即可使用它的网关。在上面的网络中，连接配置文件 1 需要至少包含签发交易的背书组织和对端节点，以及标识将交易提交到帐本时将通知网关的对端节点。
将连接配置文件描述为描述网络视图最容易。它可能是一个全面的视图，但是由于以下几个原因，这是不现实的：
- 根据需要添加和删除对端节点，交易排序器，证书颁发机构，通道和组织。
- 组件可能会启动和停止，或者发生意外故障 (例如断电)。
- 网关不需要查看整个网络，而仅需要成功处理交易提交或事件通知所需的内容。
- 服务发现可以扩充连接配置文件中的信息。具体来说，可以使用最少的 Fabric 拓扑信息来配置动态网关。其余的可以发现。
静态连接配置文件通常由详细了解网络拓扑的管理员创建。这是因为静态配置文件可以包含很多信息，并且管理员需要在相应的连接配置文件中捕获此信息。相反，动态配置文件将所需的定义量减到最少，因此对于想要快速上手的开发人员或想要创建响应速度更快的网关的管理员来说，是一个更好的选择。使用所选的编辑器以 YAML 或 JSON 格式创建连接配置文件。
2. 使用
稍后我们将介绍如何定义连接配置文件。我们首先来看一个示例 MagnetoCorp issue 应用程序如何使用它：
const yaml = require('js-yaml');
const { Gateway } = require('fabric-network');
const connectionProfile = yaml.safeLoad(fs.readFileSync('../gateway/paperNet.yaml', 'utf8'));
const gateway = new Gateway();
await gateway.connect(connectionProfile, connectionOptions);
加载了某些必需的类之后，请查看如何从文件系统加载 paperNet.yaml 网关文件，如何使用 yaml.safeLoad() 方法转换为 JSON 对象，以及如何使用其 connect() 方法来配置网关。
通过使用此连接配置文件配置网关，发行应用程序将为网关提供应用于处理交易的相关网络拓扑。这是因为连接配置文件包含有关 PaperNet 通道，组织，对端节点，交易排序器和 CA 的足够信息，以确保可以成功处理交易。
对于任何给定的组织，连接配置文件都可以定义多个对端节点，这是一个好习惯 - 可以防止单点故障。这种做法也适用于动态网关。为服务发现提供多个起点。
DigiBank buy 应用程序通常会将其网关配置为具有相似的连接配置文件，但有一些重要的区别。有些元素是相同的，例如通道；有些元素会重叠，例如背书对端节点。其他元素将完全不同，例如通知对端节点或证书颁发机构。
传递给网关的 connectionOptions 补充了连接配置文件。它们允许应用程序声明网关如何使用连接配置文件。SDK 会对它们进行解释，以控制与网络组件的交互模式，例如选择要与之连接的身份或用于事件通知的对端节点。阅读有关可用连接选项的列表以及何时使用它们的信息。
3. 结构
为了帮助你了解连接配置文件的结构，我们将逐步介绍上述网络的示例。它的连接配置文件基于 PaperNet 商业票据示例，并 存储 在 GitHub 存储库中。为了方便起见，我们在下面复制了它。现在，你会发现将其显示在另一个浏览器窗口中很有帮助：
-
Line 9: name: "papernet.magnetocorp.profile.sample"
这是连接配置文件的名称。尝试使用 DNS 样式名称；它们是传达意义的非常简单的方法。
-
Line 16: x-type: "hlfv1"
用户可以添加自己的特定于应用程序的 x- 属性，就像使用 HTTP 标头一样。它们主要提供给将来使用。
-
Line 20: description: "Sample connection profile for documentation topic"
连接配置文件的简短描述。尝试使此功能对可能是第一次看到此内容的读者有所帮助！
-
Line 25: version: "1.0"
此连接配置文件的模式版本。当前仅支持 1.0 版，并且没有预见到该模式会经常更改。
-
Line 32: channels:
这是第一条真正重要的行。
channels:标识此连接配置文件描述的所有通道如下。但是，优良作法是将不同的通道保留在不同的连接配置文件中，尤其是当它们彼此独立使用时。 -
Line 36: papernet:
Papernet的详细信息 (此连接配置文件中的第一个通道) 将随之出现。 -
Line 41: orderers:
Papernet所有交易排序器的详细信息如下。你可以在第 45 行中看到，此通道的交易排序器为orderer1.magnetocorp.example.com。这只是一个逻辑名称；稍后在连接配置文件 (第 134 - 147 行) 中，将详细介绍如何连接到此交易排序器。请注意，orderer2.digibank.example.com不在此列表中。应用程序使用自己组织的交易排序器，而不是其他组织的交易排序器，这是很有意义的。 -
Line 49: peers:
papernet所有对端节点的详细信息如下。你可以从 MagnetoCorp 中看到三个对端节点：
peer1.magnetocorp.example.com，peer2.magnetocorp.example.com和peer3.magnetocorp.example.com。无需像这里所做的那样列出 MagnetoCorp 中的所有对端节点。你只能从 DigiBank 中看到一个对端节点：peer9.digibank.example.com。现在我们将确认，包括该对端节点在内的其他人开始暗示背书策略要求 MagnetoCorp 和 DigiBank 背书交易。最好有多个对端节点，以避免单点故障。在每个对端节点之下，你可以看到四个非排他性的角色：endorsingPeer，chaincodeQuery，ledgerQuery 和 eventSource。了解 peer1 和 peer2 在托管
papercontract时如何执行所有角色。与 peer3 相比，peer3 仅可用于通知或访问账本的区块链组件而不是世界状态的账本查询，因此不需要安装智能合约。请注意，peer9 不应仅用于背书，因为 MagnetoCorp 的对端节点可以更好地发挥这些角色。再次，看看如何根据其逻辑名称和角色来描述对端节点。在 Profile 的后面，我们将看到这些对端节点的物理信息。
-
Line 97: organizations:
所有组织的详细信息将在所有通道中显示。请注意，尽管
papernet当前是唯一列出的通道，但这些组织适用于所有通道。这是因为组织可以在多个通道中，并且通道可以有多个组织。而且，某些应用程序操作与组织有关，而不是与通道有关。例如，应用程序可以使用连接选项从其组织内的一个或所有对端节点或网络内的所有组织请求通知。为此，需要一个组织到对端节点的映射，本节将提供它。 -
Line 101: MagnetoCorp:
列出了被视为 MagnetoCorp 一部分的所有对端节点：peer1，peer2 和 peer3。证书颁发机构也是如此。再次，请注意逻辑名称的用法，与
channel:部分相同，物理信息将在配置文件的后面。 -
Line 121: DigiBank:
DigiBank 仅列出了 peer9，没有证书颁发机构。这是因为这些其他对端节点和 DigiBank CA 与该连接配置文件的用户无关。
-
Line 134: orderers:
现在列出了交易排序器的物理信息。由于此连接配置文件仅提及了一个
papernet交易排序器，因此你会看到列出了orderer1.magnetocorp.example.com详细信息。其中包括其 IP 地址和端口，以及 gRPC 选项，可以在需要时覆盖与交易排序器进行通信时使用的默认值。与对端节点一样：为了获得高可用性，指定多个交易排序器是一个好主意。 -
Line 152: peers:
现在列出了所有先前对端节点的物理信息。该连接配置文件具有 MagnetoCorp 的三个对端节点：peer1，peer2 和 peer3；对于 DigiBank，单个对端节点 peer9 列出了其信息。对于每个对端节点，如交易排序器一样，将列出其IP 地址和端口以及 gRPC 选项，这些选项可以覆盖与特定对端节点进行通信时使用的默认值(如有必要)。
-
Line 194: certificateAuthorities:
现在列出了证书颁发机构的物理信息。连接配置文件为 MagnetoCorp (ca1-magnetocorp) 列出了一个 CA，其物理信息如下。除了 IP 详细信息之外，注册商信息还允许将此 CA 用于证书签名请求 (Certificate Signing Requests, CSR)。这些用于请求本地生成的公钥/私钥对的新证书。
现在，你已经了解了 MagnetoCorp 的连接配置文件，你可能想看看 DigiBank 的 相应配置文件。找到配置文件与 MagnetoCorp 相同的位置，查看其相似之处，最后找到不同之处。考虑一下为什么这些差异对于 DigiBank 应用程序有意义。
这就是你需要了解的有关连接配置文件的所有信息。总之，连接配置文件为应用程序定义了足够的通道，组织，对端节点，交易排序器和证书颁发机构，以配置网关。网关允许应用程序专注于业务逻辑，而不是网络拓扑的细节。
4. 示例
该文件是从 GitHub 商业票据 示例 中直接复制的。
1: ---
2: #
3: # [Required]. A connection profile contains information about a set of network
4: # components. It is typically used to configure gateway, allowing applications
5: # interact with a network channel without worrying about the underlying
6: # topology. A connection profile is normally created by an administrator who
7: # understands this topology.
8: #
9: name: "papernet.magnetocorp.profile.sample"
10: #
11: # [Optional]. Analogous to HTTP, properties with an "x-" prefix are deemed
12: # "application-specific", and ignored by the gateway. For example, property
13: # "x-type" with value "hlfv1" was originally used to identify a connection
14: # profile for Fabric 1.x rather than 0.x.
15: #
16: x-type: "hlfv1"
17: #
18: # [Required]. A short description of the connection profile
19: #
20: description: "Sample connection profile for documentation topic"
21: #
22: # [Required]. Connection profile schema version. Used by the gateway to
23: # interpret these data.
24: #
25: version: "1.0"
26: #
27: # [Optional]. A logical description of each network channel; its peer and
28: # orderer names and their roles within the channel. The physical details of
29: # these components (e.g. peer IP addresses) will be specified later in the
30: # profile; we focus first on the logical, and then the physical.
31: #
32: channels:
33: #
34: # [Optional]. papernet is the only channel in this connection profile
35: #
36: papernet:
37: #
38: # [Optional]. Channel orderers for PaperNet. Details of how to connect to
39: # them is specified later, under the physical "orderers:" section
40: #
41: orderers:
42: #
43: # [Required]. Orderer logical name
44: #
45: - orderer1.magnetocorp.example.com
46: #
47: # [Optional]. Peers and their roles
48: #
49: peers:
50: #
51: # [Required]. Peer logical name
52: #
53: peer1.magnetocorp.example.com:
54: #
55: # [Optional]. Is this an endorsing peer? (It must have chaincode
56: # installed.) Default: true
57: #
58: endorsingPeer: true
59: #
60: # [Optional]. Is this peer used for query? (It must have chaincode
61: # installed.) Default: true
62: #
63: chaincodeQuery: true
64: #
65: # [Optional]. Is this peer used for non-chaincode queries? All peers
66: # support these types of queries, which include queryBlock(),
67: # queryTransaction(), etc. Default: true
68: #
69: ledgerQuery: true
70: #
71: # [Optional]. Is this peer used as an event hub? All peers can produce
72: # events. Default: true
73: #
74: eventSource: true
75: #
76: peer2.magnetocorp.example.com:
77: endorsingPeer: true
78: chaincodeQuery: true
79: ledgerQuery: true
80: eventSource: true
81: #
82: peer3.magnetocorp.example.com:
83: endorsingPeer: false
84: chaincodeQuery: false
85: ledgerQuery: true
86: eventSource: true
87: #
88: peer9.digibank.example.com:
89: endorsingPeer: true
90: chaincodeQuery: false
91: ledgerQuery: false
92: eventSource: false
93: #
94: # [Required]. List of organizations for all channels. At least one organization
95: # is required.
96: #
97: organizations:
98: #
99: # [Required]. Organizational information for MagnetoCorp
100: #
101: MagnetoCorp:
102: #
103: # [Required]. The MSPID used to identify MagnetoCorp
104: #
105: mspid: MagnetoCorpMSP
106: #
107: # [Required]. The MagnetoCorp peers
108: #
109: peers:
110: - peer1.magnetocorp.example.com
111: - peer2.magnetocorp.example.com
112: - peer3.magnetocorp.example.com
113: #
114: # [Optional]. Fabric-CA Certificate Authorities.
115: #
116: certificateAuthorities:
117: - ca-magnetocorp
118: #
119: # [Optional]. Organizational information for DigiBank
120: #
121: DigiBank:
122: #
123: # [Required]. The MSPID used to identify DigiBank
124: #
125: mspid: DigiBankMSP
126: #
127: # [Required]. The DigiBank peers
128: #
129: peers:
130: - peer9.digibank.example.com
131: #
132: # [Optional]. Orderer physical information, by orderer name
133: #
134: orderers:
135: #
136: # [Required]. Name of MagnetoCorp orderer
137: #
138: orderer1.magnetocorp.example.com:
139: #
140: # [Required]. This orderer's IP address
141: #
142: url: grpc://localhost:7050
143: #
144: # [Optional]. gRPC connection properties used for communication
145: #
146: grpcOptions:
147: ssl-target-name-override: orderer1.magnetocorp.example.com
148: #
149: # [Required]. Peer physical information, by peer name. At least one peer is
150: # required.
151: #
152: peers:
153: #
154: # [Required]. First MagetoCorp peer physical properties
155: #
156: peer1.magnetocorp.example.com:
157: #
158: # [Required]. Peer's IP address
159: #
160: url: grpc://localhost:7151
161: #
162: # [Optional]. gRPC connection properties used for communication
163: #
164: grpcOptions:
165: ssl-target-name-override: peer1.magnetocorp.example.com
166: request-timeout: 120001
167: #
168: # [Optional]. Other MagnetoCorp peers
169: #
170: peer2.magnetocorp.example.com:
171: url: grpc://localhost:7251
172: grpcOptions:
173: ssl-target-name-override: peer2.magnetocorp.example.com
174: request-timeout: 120001
175: #
176: peer3.magnetocorp.example.com:
177: url: grpc://localhost:7351
178: grpcOptions:
179: ssl-target-name-override: peer3.magnetocorp.example.com
180: request-timeout: 120001
181: #
182: # [Required]. Digibank peer physical properties
183: #
184: peer9.digibank.example.com:
185: url: grpc://localhost:7951
186: grpcOptions:
187: ssl-target-name-override: peer9.digibank.example.com
188: request-timeout: 120001
189: #
190: # [Optional]. Fabric-CA Certificate Authority physical information, by name.
191: # This information can be used to (e.g.) enroll new users. Communication is via
192: # REST, hence options relate to HTTP rather than gRPC.
193: #
194: certificateAuthorities:
195: #
196: # [Required]. MagnetoCorp CA
197: #
198: ca1-magnetocorp:
199: #
200: # [Required]. CA IP address
201: #
202: url: http://localhost:7054
203: #
204: # [Optioanl]. HTTP connection properties used for communication
205: #
206: httpOptions:
207: verify: false
208: #
209: # [Optional]. Fabric-CA supports Certificate Signing Requests (CSRs). A
210: # registrar is needed to enroll new users.
211: #
212: registrar:
213: - enrollId: admin
214: enrollSecret: adminpw
215: #
216: # [Optional]. The name of the CA.
217: #
218: caName: ca-magnetocorp
Reference
- Docs » Developing Applications » Application design elements » Connection Profile, https://hyperledger-fabric.readthedocs.io/en/release-1.4/developapps/connectionprofile.html
- Docs » Developing Applications » Application design elements » Gateway, https://hyperledger-fabric.readthedocs.io/en/release-1.4/developapps/gateway.html
- Docs » Developing Applications » Application design elements » Gateway, https://hyperledger-fabric.readthedocs.io/en/release-1.4/developapps/gateway.html
- Docs » Architecture Reference » Service Discovery, https://hyperledger-fabric.readthedocs.io/en/release-1.4/discovery-overview.html
项目源代码
项目源代码会逐步上传到 Github，地址为 https://github.com/windstamp。
Contributor
- Windstamp, https://github.com/windstamp
