نقش jq در Hyperledger Fabric

در Hyperledger Fabric وقتی می‌خواهیم کانفیگ کانال (Channel Configuration) را تغییر بدهیم، مثلاً Anchor Peer را تنظیم کنیم یا MSP یک سازمان را آپدیت کنیم، مراحل اصلی شامل این‌هاست:

استخراج بلوک کانال (Channel Block) از شبکه:

peer channel fetch config config_block.pb -o orderer.example.com:7050 -c mychannel

نتیجه یک فایل پروتوباف (protobuf) است که ساختار باینری دارد.

تبدیل پروتوباف به JSON قابل خواندن:

configtxlator proto_decode --input config_block.pb --type common.Block --output config_block.json

حالا کانفیگ کانال در قالب JSON قابل پردازش است.

استخراج بخش مشخصی از کانفیگ JSON: اینجاست که jq وارد می‌شود.

jq یک ابزار خط فرمان برای خواندن، فیلتر کردن و دستکاری JSON است.

مثلاً در Fabric معمولاً از آن برای گرفتن بخش "config" از بلوک کانال استفاده می‌کنیم:

jq '.data.data[0].payload.data.config' config_block.json > Org1MSPconfig.json

• این دستور فقط قسمت مربوط به کانفیگ سازمان مورد نظر را جدا می‌کند و به فایل دیگری می‌ریزد تا بعداً بتوان آن را ویرایش کرد و سپس بلاک تغییر کانفیگ ساخت.
• اعمال تغییرات و تولید فایل آپدیت
  بعد از اعمال تغییر، با configtxlator proto_encode دوباره JSON را به پروتوباف تبدیل می‌کنیم و به orderer ارسال می‌کنیم تا کانفیگ کانال آپدیت شود.

خلاصه نقش jq:

jq فقط برای خواندن و استخراج بخش‌های خاص JSON استفاده می‌شود تا بتوانیم تغییرات کانفیگ کانال را به شکل خودکار انجام دهیم.

بدون jq، استخراج بخش کانفیگ از بلوک کانال بسیار دشوار و دستی می‌شد.

بیایید یک مثال واقعی و ساده از یک فایل کانفیگ کانال پس از تبدیل به JSON بسازیم تا دقیقاً ببینی چطور jq در Fabric استفاده می‌شود. 

فرض کنید یک فایل باینری داریم: config_block.pb برای مشاهده محتوا، از configtxlator استفاده می‌کنیم:

configtxlator proto_decode --input config_block.pb --type common.Block --output config_block.json

{
 "header": {
   "number": "0",
   "previous_hash": "",
   "data_hash": "abcd1234"
 },
 "data": {
   "data": [
     {
       "payload": {
         "header": {
           "channel_header": {
             "channel_id": "mychannel",
             "type": 2
           },
           "signature_header": {
             "creator": {
               "mspid": "Org1MSP",
               "id_bytes": "..."
             }
           }
         },
         "data": {
           "config": {
             "channel_group": {
               "groups": {
                 "Application": {
                   "groups": {
                     "Org1MSP": {
                       "values": {
                         "MSP": {
                           "mod_policy": "Admins",
                           "value": {
                             "config": {
                               "name": "Org1MSP",
                               "root_certs": ["-----BEGIN CERTIFICATE-----..."]
                             }
                           }
                         }
                       },
                       "policies": {
                         "Admins": { "mod_policy": "Admins", "policy": {...} }
                       }
                     }
                   }
                 }
               }
             }
           }
         }
       },
       "signatures": []
     }
   ]
 },
 "metadata": {
   "last_config": {
     "index": 0
   }
 }
}

استخراج اطلاعات با jq

فرض کنیم می‌خواهیم فقط بخش کانفیگ Org1MSP را استخراج کنیم:

jq '.data.data[0].payload.data.config.channel_group.groups.Application.groups.Org1MSP' config_block.json > Org1MSPconfig.json

حالا فایل Org1MSPconfig.json شامل همه تنظیمات Org1 در کانال است:

{
 "values": {
   "MSP": {
     "mod_policy": "Admins",
     "value": {
       "config": {
         "name": "Org1MSP",
         "root_certs": ["-----BEGIN CERTIFICATE-----..."]
       }
     }
   }
 },
 "policies": {
   "Admins": { "mod_policy": "Admins", "policy": {...} }
 }
}

این همان کاری است که Fabric در اسکریپت configUpdate.sh انجام می‌دهد:

فایل باینری پروتوباف را به JSON تبدیل می‌کند.

با jq بخش مورد نظر هر سازمان را استخراج می‌کند.

تغییرات (مثلاً اضافه کردن anchor peer) را روی JSON اعمال می‌کند.

JSON جدید را دوباره با configtxlator به .pb تبدیل کرده و به کانال می‌فرستد.

نکته: به همین دلیل است که قبل از اجرای ./network.sh یا تغییر کانفیگ کانال، jq باید نصب باشد. بدون jq، اسکریپت نمی‌تواند JSON مورد نظر را پردازش کند و خطا می‌دهد.

پیشنهاد مطالعه: تعریف کلی Protobuf و کاربرد آن در هایپرلجر فابریک

ساختار کلی کانال و فایل‌های پروتوباف

کانال Hyperledger Fabric شامل چند بخش اصلیه:

Channel (mychannel)
│
├── Genesis Block (config_block.pb)  ← فایل پروتوباف
│    ├── Header
│    │    └── Channel ID, Type, Version
│    ├── Data
│    │    └── Transactions / Config Update
│    └── Metadata
│         └── Signatures, Policies
│
└── Anchor Peers (Org1MSPconfig.json)

config_block.pb → بلوک اول کانال یا همان Genesis Block است.

این فایل با فرمت protobuf ذخیره شده، یعنی داده‌ها به صورت باینری و ساختاریافته هستند.

کار jq شروع می‌شود وقتی می‌خوایم این فایل باینری را به JSON تبدیل کنیم تا بتوانیم تغییرات را روی آن اعمال کنیم.

  نقش configtxlator و jq

فرآیند معمول: استخراج فایل پروتوباف:

peer channel fetch config config_block.pb -o orderer:7050 -c mychannel --tls --cafile ca.crt

تبدیل .pb به JSON:

configtxlator proto_decode --input config_block.pb --type common.Block --output config_block.json

ایزوله کردن بخش کانفیگ با jq:

jq '.data.data[0].payload.data.config' config_block.json > Org1MSPconfig.json

jq دقیقاً این کار را انجام می‌دهد:
داده‌های باینری پروتوباف را که حالا به JSON تبدیل شده‌اند، فیلتر و استخراج می‌کند.

نتیجه‌ی این کار یک JSON کاملاً قابل خواندن و ویرایش برای تعریف anchor peers یا تغییرات دیگر کانال است.

اعمال تغییرات و بازگرداندن به پروتوباف:

configtxlator proto_encode --input updated_config.json --type common.Config --output updated_config.pb
configtxlator compute_update --channel_id mychannel --original config_block.pb --updated updated_config.pb --output config_update.pb

ارسال تغییرات به شبکه:

 peer channel update -f config_update.pb -c mychannel -o orderer:7050 --tls --cafile ca.crt