نشر محوّل
تحتاج إلى openssl وjq، وإلى حساب مالك أو مسؤول في منشأتك على
Adapter Studio.
المسار السريع: أمر zaitrack
يُنتج الأمر الملفات نفسها التي يقبلها Adapter Studio: adapter.json وmanifest.canonical.json وsignature.b64.
zaitrack adapter scaffold connector --name acme-fleet-export --display-name "Acme fleet export" \
--licence MIT --publisher acme --out ./work
zaitrack adapter test ./work/acme-fleet-export
zaitrack adapter pack ./work/acme-fleet-export
zaitrack adapter keygen --out ./keys
zaitrack adapter sign ./work/acme-fleet-export --key ./keys/key.pem
zaitrack adapter verify ./work/acme-fleet-export --public-key ./keys/key.pub.pem
zaitrack adapter submit ./work/acme-fleet-export --registry https://<registry> \
--token ZAITRACK_REGISTRY_TOKEN --key ./keys/key.pem --create-project
اسم المجلد هو معرّف المشروع (slug) وid في البيان. الترخيص والملخص والوصف تخص المشروع لا البيان. --token اسم متغير
البيئة الذي يحمل رمز Bearer لمالك أو مسؤول، ولا يُطبع الرمز أبدًا. يسجّل submit المفتاح العام إن لم يعرفه
السجل، ثم يرسل الإصدار. البديل: سجّل key.pub.pem في Adapter Studio والصق adapter.json وsignature.b64 في
نموذج «إرسال إصدار». الخطوات اليدوية أدناه تنتج الملفات نفسها.
1. أنشئ مفتاح توقيع
تقبل ZAITRACK خوارزمية واحدة: ECDSA على المنحنى P-256 مع SHA-256، والتوقيع بصيغة ASN.1 DER مرمّزًا بـ base64.
openssl ecparam -name prime256v1 -genkey -noout -out key.pem
openssl ec -in key.pem -pubout -out key.pub.pem
احفظ key.pem سرًّا: من يملكه يستطيع توقيع الإصدارات باسمك. في Adapter Studio، مفاتيح التوقيع ← تسجيل
مفتاح، أعطه اسمًا (من 2 إلى 80 حرفًا) والصق key.pub.pem. يعرض الاستوديو بصمة المفتاح:
SHA256: متبوعة بقيمة SHA-256 للمفتاح العام بصيغة DER مرمّزة بـ base64.
2. أنشئ المشروع
المشاريع ← مشروع جديد: معرّف مختصر (slug) (أحرف لاتينية صغيرة وأرقام وشرطات)، والفئة (codec أو
connector أو datasource أو action أو ai)، واسم العرض، وملخص ووصف، وترخيص SPDX
(LicenseRef-… لترخيصك الخاص)، ومستوى الظهور: public (تستطيع أي منشأة رؤية إصداراته المعتمدة
وتثبيتها) أو tenant-only (منشأتك فقط).
3. اكتب البيان
يحدد adapter.json هوية المحوّل، وما يستطيع فعله، والصلاحيات التي يطلبها، والإعدادات التي يجب أن يعطيها
التثبيت:
{
"id": "acme-fleet-export",
"family": "connector",
"version": "1.0.0",
"displayName": "Acme fleet export",
"capabilities": ["export"],
"permissions": ["trips:read"],
"config": [
{"key": "sftpHost", "type": "url", "required": true, "label": "SFTP host"},
{"key": "password", "type": "secret", "required": true, "label": "Password"}
]
}
id: من 3 إلى 64 حرفًا، أحرف لاتينية صغيرة وأرقام وشرطات، يبدأ بحرف ولا ينتهي بشرطة. يجب أن يكون الإصدار جديدًا على المشروع.version: ترقيم دلالي (1.0.0،1.1.0-rc.1).displayName: 3 أحرف على الأقل.config[].key: حرف، ثم أحرف أو أرقام أو_(48 على الأكثر)، وكل مفتاح مرة واحدة.config[].type:textأوnumberأوurlأوsecretأوport. الإعداد من نوعsecretلا يُعرض مرة أخرى بعد إعطائه.
4. وقّع البيان القانوني
يوقّع سجل المحوّلات البيان القانوني ويتحقق منه: المفاتيح مرتّبة، بلا مسافات بيضاء غير لازمة، وبلا سطر جديد
في النهاية. أنشئه بـ jq، ثم وقّعه:
jq -cSj . adapter.json > manifest.canonical.json
openssl dgst -sha256 -sign key.pem manifest.canonical.json | base64 -w0 > signature.b64
أبقِ الرموز & و< و> خارج نصوص البيان: يكتبها سجل المحوّلات بالشكل & و< و>
ولا يفعل jq ذلك، فلا يتطابق التوقيع. على macOS، استخدم base64 بدون -w0 (فهو لا يقسّم الأسطر).
5. قدّم الإصدار
المشاريع ← مشروعك ← تقديم إصدار: الصق adapter.json ومحتوى signature.b64 واختر المفتاح. يمكنك
اختياريًا إعطاء عنوان الحزمة (https:// أو oci://). يحوّل سجل المحوّلات البيان إلى شكله القانوني، ويحسب
بصمته بـ SHA-256، ويتحقق من التوقيع بمفتاحك. يُرفض التوقيع الخاطئ أو المفتاح الملغى. ينتظر الإصدار بالحالة
pending-review.
6. المراجعة
يشغّل فريق ZAITRACK مجموعة اختبارات المطابقة ويسجّل نتيجتها: نسبة التغطية وعدد الفحوص الناجحة والفاشلة. لا يُعتمد الإصدار إلا بتشغيل تغطيته 85 % على الأقل بلا إخفاقات؛ يوافق الفريق مع ملاحظة، أو يرفض مع ذكر السبب.
7. التثبيتات
تثبّت المنشآت إصدارًا معتمدًا وتملأ الإعدادات التي يعلنها بيانك. تستطيع الترقية إلى إصدار معتمد آخر، وتغيير الإعدادات، والإيقاف المؤقت، والاستئناف، وإلغاء التثبيت. ترى تثبيتًا واحدًا لكل منشأة، مع إصداره وحالته.
حالة التثبيت النشط في السجل لا تثبت اتصال الجهاز أو تهيئة بيئة التشغيل. قبل النشر، اتبع جاهزية برامج الترميز، وافصل أدلة الاعتماد والتثبيت واختبار الجهاز.
إلغاء مفتاح
مفاتيح التوقيع ← إلغاء، مع ذكر السبب. في خطوة واحدة يُلغي كل إصدار وقّعه ذلك المفتاح ويوقف تثبيتاتها مؤقتًا؛ ويُضاف المفتاح إلى قائمة الإلغاء مع وقت الإلغاء وسببه. يُستأنف التثبيت بعد ترقيته إلى إصدار غير ملغى: وقّع الإصدار التالي بمفتاح جديد.