Fabric 2.x 外部链码部署（External Chaincode Service）实战攻略

在 Fabric 传统链码部署模式中，链码需要经过打包、编译、下载、批准和提交这几个步骤。如果要更新链码，还需要再走一遍整个流程。对于链码测试阶段的开发者来说非常繁琐，尤其在组织和节点较多的网络中更是如此。

好消息是：Fabric 2.0+ 支持 External Chaincode Service （外部链码服务）。

这种模式最大的特点是开发者只需在第一次执行 install、approve、commit，后续链码更新可以直接热重载，改即用，非常方便测试和开发。

环境说明

本文操作环境为 Linux 虚拟机运行 Fabric 网络，其中各节点以 Docker 容器形式运行。外部链码服务运行在 Windows 主机上，通过 192.168.1.5:9999 暴露服务给节点。

整体流程（Mermaid 简图）

打包 metadata.json+connection.json peer lifecycle chaincode install approveformyorg commit 外部链码进程 go run main.go

1. Docker Compose 配置

在每个 peer 节点容器中需要添加的环境变量示例：

yaml 复制代码

    environment:
      # 外部链码（Chaincode-as-a-Service）用到的 external builder
      - CORE_CHAINCODE_EXECUTETIMEOUT=300s
      - CORE_CHAINCODE_EXTERNALBUILDERS=[{"name":"myexternal","path":"/opt/hyperledger/external-builder","propagateEnvironment":["CHAINCODE_AS_A_SERVICE"]}]
      # 可选项：如果你自己在 peer 中起链码 server 可用下面这两个
      - CORE_CHAINCODE_LISTENADDRESS=0.0.0.0:7052
      - CORE_CHAINCODE_ADDRESSAUTODETECT=true
    volumes:
      - /var/run/docker.sock:/host/var/run/docker.sock   # Docker socket 映射
      - ../../chaincode-external/bin:/opt/hyperledger/external-builder/bin   # 外部链码构建器脚本

🔹CORE_CHAINCODE_EXTERNALBUILDERS：告诉 peer 不要用内置 Docker builder，而是交给你自己写的 external builder 脚本（detect/build/release）。

2. core.yaml 配置

每个 peer 节点的 core.yaml 中也要增加 externalBuilder 配置（注意缩进）：

yaml 复制代码

peer:
  id: peer1-bank1
  networkId: dev
  address: 0.0.0.0:7051
  localMspId: Bank1MSP
  BCCSP:
    Default: SW
    SW:
      Hash: SHA2
      Security: 256
      FileKeyStore:
        KeyStore: /etc/hyperledger/msp/keystore
chaincode:
  externalBuilders:
    - name: myexternal
      path: /opt/hyperledger/external-builder # 这是容器内部的路径

3. 链码目录结构与打包

示例文件树：

bash 复制代码

chaincode-external/
├── basic_1.0.tgz
├── bin
│   ├── build
│   ├── detect
│   └── release
├── connection.json
└── metadata.json

metadata.json

json 复制代码

{
  "label": "basic_1.0",
  "type": "external"
}

connection.json

json 复制代码

{
  "address": "192.168.1.5:9999",
  "dial_timeout": "10s",
  "tls_required": false
}

如果需要 TLS，可以把 "tls_required": true，并在 connection.json 中提供 client_cert、client_key、root_cert。

打包命令：

bash 复制代码

tar cfz code.tar.gz connection.json
tar cfz basic_1.0.tgz metadata.json code.tar.gz

4. External Builder 脚本

在本地 bin 目录中创建 detect、build、release 三个可执行脚本：

脚本名	功能
detect	判断该 builder 是否能处理当前链码 package（type 是否为 external）。
build	构建链码；外部链码通常只需拷贝 connection.json。
release	可选；做 release 或打包动作。

记得给脚本 chmod +x，peer 容器里需要有 jq 命令。

在官方 Peer 镜像中添加 jq（JP）工具

Fabric 官方 hyperledger/fabric-peer 镜像内默认没有 jq 工具（external builder 脚本里用到 jq 解析 JSON）。如果不提前加进去，Peer 容器执行 detect/build 时会报 jq: command not found。

自定义 Dockerfile

在 hyperledger/fabric-peer 的基础上构建你自己的镜像，例如：

bash 复制代码

FROM hyperledger/fabric-peer:2.5
USER root
RUN apt-get update && apt-get install -y jq && rm -rf /var/lib/apt/lists/*
USER 1000

然后构建并打上新标签：

bash 复制代码

docker build -t myfabric-peer:2.5 .

在 docker-compose.yaml 里把原来的镜像名改成 myfabric-peer:2.5。

detect

bash 复制代码

#!/bin/bash
set -euo pipefail
METADIR=$2
if [ "$(jq -r .type "$METADIR/metadata.json")" == "external" ]; then
    exit 0
fi
exit 1

build

bash 复制代码

#!/bin/bash
set -euo pipefail
SOURCE=$1
OUTPUT=$3

if [ ! -f "$SOURCE/connection.json" ]; then
    >&2 echo "$SOURCE/connection.json not found"
    exit 1
fi

cp $SOURCE/connection.json $OUTPUT/connection.json

if [ -d "$SOURCE/metadata" ]; then
    cp -a $SOURCE/metadata $OUTPUT/metadata
fi

exit 0

release

bash 复制代码

#!/bin/bash
set -euo pipefail
BLD="$1"
RELEASE="$2"

if [ -d "$BLD/metadata" ]; then
   cp -a "$BLD/metadata/"* "$RELEASE/"
fi

if [ -f $BLD/connection.json ]; then
   mkdir -p "$RELEASE"/chaincode/server
   cp $BLD/connection.json "$RELEASE"/chaincode/server
   exit 0
fi

exit 1

5. 安装与批准

安装链码：

bash 复制代码

peer lifecycle chaincode install ./chaincode-external/basic_1.0.tgz

批准与提交（approve/commit）步骤与传统链码一样，只要第一次做一次就行。之后修改外部链码代码无需重新 approve/commit，直接重启链码进程即可热更新。

6. 外部链码进程运行

在 GoLand（或其他 IDE）中启动你的链码程序之前，需要设置三个环境变量：

bash 复制代码

export CHAINCODE_ID=basic_1.0:<package_id>  # peer lifecycle chaincode queryinstalled 输出的 Package ID
export CHAINCODE_SERVER_ADDRESS=0.0.0.0:9999 # 与 connection.json 中一致
export CHAINCODE_TLS_DISABLED=true           # 如果 connection.json 启用 TLS，则改为 false

变量	作用
`CHAINCODE_ID`	必须。必须与 peer 上安装的 Package ID 完全一致，链码启动时用来向 peer 注册。
`CHAINCODE_SERVER_ADDRESS`	必须。链码监听的地址，Fabric peer 会根据 connection.json 去连你。
`CHAINCODE_TLS_DISABLED`	可选。不启用 TLS 时设为 true；启用 TLS 时设为 false，并提供 `CHAINCODE_SERVER_CERT`、`CHAINCODE_SERVER_KEY` 等。

7. 注意事项

网络互通：确保 Fabric 网络所在虚拟机能访问外部链码服务 IP/端口。Windows 上要放行防火墙端口。
权限：bin/detect、bin/build、bin/release 必须有执行权限。
热更新：外部链码修改代码后直接重启链码进程即可，peer 无需重新安装/批准/提交（除非 label 或 sequence 改了）。

这样配置好之后，你的链码开发就进入"热重载"模式：修改代码 → 重启链码进程 → 立即生效