سجلات الحزم الخاصة

يغطي هذا الدليل كيفية تهيئة مشروع CrewAI لتثبيت حزم Python من سجلات PyPI الخاصة (Azure DevOps Artifacts، GitHub Packages، GitLab، AWS CodeArtifact، إلخ.) عند النشر على CrewAI AMP.

متى تحتاج هذا

إذا كان مشروعك يعتمد على حزم Python داخلية أو خاصة مستضافة على سجل خاص بدلاً من PyPI العام، ستحتاج إلى:

إخبار UV أين يجد الحزمة (رابط فهرس)
إخبار UV أي حزم تأتي من ذلك الفهرس (تعيين مصدر)
تقديم بيانات اعتماد حتى يتمكن UV من المصادقة أثناء التثبيت

يستخدم CrewAI AMP UV لحل وتثبيت الاعتماديات. يدعم UV السجلات الخاصة المصادق عليها عبر تهيئة pyproject.toml مع متغيرات بيئة لبيانات الاعتماد.

الخطوة 1: تهيئة pyproject.toml

ثلاثة أجزاء تعمل معاً في pyproject.toml:

1أ. التصريح بالاعتمادية

أضف الحزمة الخاصة إلى [project.dependencies] كأي اعتمادية أخرى:

[project]
dependencies = [
    "crewai[tools]>=0.100.1,<1.0.0",
    "my-private-package>=1.2.0",
]

1ب. تعريف الفهرس

سجّل سجلك الخاص كفهرس مسمّى تحت [[tool.uv.index]]:

[[tool.uv.index]]
name = "my-private-registry"
url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/"
explicit = true

حقل name مهم — يستخدمه UV لبناء أسماء متغيرات البيئة للمصادقة (راجع الخطوة 2 أدناه).تعيين explicit = true يعني أن UV لن يبحث في هذا الفهرس عن كل حزمة — فقط الحزم التي تعيّنها صراحة له في [tool.uv.sources]. يتجنب ذلك الاستعلامات غير الضرورية ضد سجلك الخاص ويحمي من هجمات ارتباك الاعتماديات.

1ج. تعيين الحزمة للفهرس

أخبر UV أي حزم يجب حلها من فهرسك الخاص باستخدام [tool.uv.sources]:

[tool.uv.sources]
my-private-package = { index = "my-private-registry" }

مثال كامل

[project]
name = "my-crew-project"
version = "0.1.0"
requires-python = ">=3.10,<=3.13"
dependencies = [
    "crewai[tools]>=0.100.1,<1.0.0",
    "my-private-package>=1.2.0",
]

[tool.crewai]
type = "crew"

[[tool.uv.index]]
name = "my-private-registry"
url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/"
explicit = true

[tool.uv.sources]
my-private-package = { index = "my-private-registry" }

بعد تحديث pyproject.toml، أعد إنشاء ملف القفل:

uv lock

ارفع دائماً uv.lock المُحدّث مع تغييرات pyproject.toml. ملف القفل مطلوب للنشر — راجع التحضير للنشر.

الخطوة 2: تعيين بيانات اعتماد المصادقة

يصادق UV ضد الفهارس الخاصة باستخدام متغيرات بيئة تتبع اصطلاح تسمية بناءً على اسم الفهرس الذي حددته في pyproject.toml:

UV_INDEX_{UPPER_NAME}_USERNAME
UV_INDEX_{UPPER_NAME}_PASSWORD

حيث {UPPER_NAME} هو اسم فهرسك محوّلاً إلى أحرف كبيرة مع استبدال الشرطات بشرطات سفلية. على سبيل المثال، فهرس باسم my-private-registry يستخدم:

المتغير	القيمة
`UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME`	اسم مستخدم السجل أو اسم الرمز
`UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD`	كلمة مرور السجل أو الرمز/PAT

هذه المتغيرات يجب إضافتها عبر إعدادات Environment Variables في CrewAI AMP — إما عالمياً أو على مستوى النشر. لا يمكن تعيينها في ملفات .env أو ترميزها في مشروعك.راجع تعيين متغيرات البيئة في AMP أدناه.

مرجع مزودي السجلات

يوضح الجدول أدناه تنسيق رابط الفهرس وقيم بيانات الاعتماد لمزودي السجلات الشائعين. استبدل القيم المؤقتة بتفاصيل مؤسستك وخلاصتك الفعلية.

المزود	رابط الفهرس	اسم المستخدم	كلمة المرور
Azure DevOps Artifacts	`https://pkgs.dev.azure.com/{org}/_packaging/{feed}/pypi/simple/`	أي نص غير فارغ (مثل `token`)	Personal Access Token (PAT) بنطاق Packaging Read
GitHub Packages	`https://pypi.pkg.github.com/{owner}/simple/`	اسم مستخدم GitHub	Personal Access Token (classic) بنطاق `read:packages`
GitLab Package Registry	`https://gitlab.com/api/v4/projects/{project_id}/packages/pypi/simple/`	`__token__`	Project أو Personal Access Token بنطاق `read_api`
AWS CodeArtifact	استخدم الرابط من `aws codeartifact get-repository-endpoint`	`aws`	رمز من `aws codeartifact get-authorization-token`
Google Artifact Registry	`https://{region}-python.pkg.dev/{project}/{repo}/simple/`	`_json_key_base64`	مفتاح حساب الخدمة بتشفير Base64
JFrog Artifactory	`https://{instance}.jfrog.io/artifactory/api/pypi/{repo}/simple/`	اسم المستخدم أو البريد الإلكتروني	مفتاح API أو رمز الهوية
مستضاف ذاتياً (devpi، Nexus، إلخ.)	رابط Simple API لسجلك	اسم مستخدم السجل	كلمة مرور السجل

لـ AWS CodeArtifact، تنتهي صلاحية رمز التفويض دورياً. ستحتاج لتحديث قيمة UV_INDEX_*_PASSWORD عند انتهاء صلاحيتها. فكّر في أتمتة هذا في خط أنابيب CI/CD.

تعيين متغيرات البيئة في AMP

يجب تهيئة بيانات اعتماد السجل الخاص كمتغيرات بيئة في CrewAI AMP. لديك خياران:

واجهة الويب
النشر عبر CLI

سجّل الدخول إلى CrewAI AMP
انتقل إلى أتمتتك
افتح علامة تبويب Environment Variables
أضف كل متغير (UV_INDEX_*_USERNAME وUV_INDEX_*_PASSWORD) مع قيمته

راجع خطوة النشر على AMP — تعيين متغيرات البيئة للتفاصيل.

أضف المتغيرات إلى ملف .env المحلي قبل تشغيل crewai deploy create. سينقلها CLI بأمان إلى المنصة:

# .env
OPENAI_API_KEY=sk-...
UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token
UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat-here

crewai deploy create

لا ترفع أبداً بيانات الاعتماد إلى مستودعك. استخدم متغيرات بيئة AMP لجميع الأسرار. يجب إدراج ملف .env في .gitignore.

لتحديث بيانات الاعتماد في نشر حالي، راجع تحديث طاقمك — متغيرات البيئة.

كيف يعمل الكل معاً

عندما يبني CrewAI AMP أتمتتك، يعمل تدفق الحل هكذا:

بدء البناء

يسحب AMP مستودعك ويقرأ pyproject.toml وuv.lock.

UV يحل الاعتماديات

يقرأ UV [tool.uv.sources] لتحديد أي فهرس يجب أن تأتي منه كل حزمة.

UV يصادق

لكل فهرس خاص، يبحث UV عن UV_INDEX_{NAME}_USERNAME وUV_INDEX_{NAME}_PASSWORD من متغيرات البيئة التي هيأتها في AMP.

تثبيت الحزم

يحمّل UV ويثبّت جميع الحزم — العامة (من PyPI) والخاصة (من سجلك).

تشغيل الأتمتة

يبدأ طاقمك أو تدفقك مع توفر جميع الاعتماديات.

استكشاف الأخطاء وإصلاحها

أخطاء المصادقة أثناء البناء

العرض: فشل البناء بـ 401 Unauthorized أو 403 Forbidden عند حل حزمة خاصة. تحقق من:

أسماء متغيرات البيئة UV_INDEX_* تتطابق مع اسم فهرسك بالضبط (أحرف كبيرة، شرطات → شرطات سفلية)
بيانات الاعتماد معيّنة في متغيرات بيئة AMP، وليس فقط في .env محلي
الرمز/PAT لديه صلاحيات القراءة المطلوبة لخلاصة الحزم
الرمز لم تنتهِ صلاحيته (ذو صلة خاصة لـ AWS CodeArtifact)

الحزمة غير موجودة

العرض: No matching distribution found for my-private-package. تحقق من:

رابط الفهرس في pyproject.toml ينتهي بـ /simple/
إدخال [tool.uv.sources] يعيّن اسم الحزمة الصحيح لاسم الفهرس الصحيح
الحزمة منشورة فعلاً في سجلك الخاص
شغّل uv lock محلياً بنفس بيانات الاعتماد للتحقق من عمل الحل

تعارضات ملف القفل

العرض: فشل uv lock أو نتائج غير متوقعة بعد إضافة فهرس خاص. الحل: عيّن بيانات الاعتماد محلياً وأعد الإنشاء:

export UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token
export UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat
uv lock

ثم ارفع uv.lock المُحدّث.

أدلة ذات صلة

التحضير للنشر

تحقق من بنية المشروع والاعتماديات قبل النشر.

النشر على AMP

انشر طاقمك أو تدفقك وهيّئ متغيرات البيئة.

تحديث طاقمك

حدّث متغيرات البيئة وادفع التغييرات إلى نشر قائم.

​متى تحتاج هذا

​الخطوة 1: تهيئة pyproject.toml

​1أ. التصريح بالاعتمادية

​1ب. تعريف الفهرس

​1ج. تعيين الحزمة للفهرس

​مثال كامل

​الخطوة 2: تعيين بيانات اعتماد المصادقة

​مرجع مزودي السجلات

​تعيين متغيرات البيئة في AMP

​كيف يعمل الكل معاً

​استكشاف الأخطاء وإصلاحها

​أخطاء المصادقة أثناء البناء

​الحزمة غير موجودة

​تعارضات ملف القفل

​أدلة ذات صلة

التحضير للنشر

النشر على AMP

تحديث طاقمك

متى تحتاج هذا

الخطوة 1: تهيئة pyproject.toml

1أ. التصريح بالاعتمادية

1ب. تعريف الفهرس

1ج. تعيين الحزمة للفهرس

مثال كامل

الخطوة 2: تعيين بيانات اعتماد المصادقة

مرجع مزودي السجلات

تعيين متغيرات البيئة في AMP

كيف يعمل الكل معاً

استكشاف الأخطاء وإصلاحها

أخطاء المصادقة أثناء البناء

الحزمة غير موجودة

تعارضات ملف القفل

أدلة ذات صلة