git-pkgs proxy

وكيل تخزين مؤقت (caching proxy) لسجلات الحزم (package registries). يسرّع تنزيلات الحزم عبر تخزين الملفات (artifacts) محليًا، مما يقلل استهلاك النطاق الترددي ويحسّن الموثوقية.

فترة التهدئة للإصدارات (Version Cooldown)

تعتمد معظم هجمات سلسلة التوريد على السرعة: يُنشر إصدار خبيث ويُستهلك بواسطة خطوط الأنابيب الآلية في غضون دقائق، قبل أن يلاحظه أحد. تضيف ميزة فترة التهدئة فترة حجر صحي للإصدارات المنشورة حديثًا. عند تفعيلها، يزيل الوكيل الإصدارات من استجابات البيانات الوصفية (metadata) حتى تتجاوز عمرها حدًا زمنيًا قابلًا للتهيئة.

cooldown:
  default: "3d"              # hide versions published less than 3 days ago
  ecosystems:
    npm: "7d"                # npm gets a longer window
    cargo: "0"               # disable for cargo
  packages:
    "pkg:npm/lodash": "0"    # exempt trusted packages

يعني التهدئة لمدة 3 أيام أنه عندما ينشر lodash الإصدار 4.18.0، تظل عمليات البناء لديك تستخدم 4.17.21 حتى تمر 3 أيام. إذا تبيّن أن الإصدار الجديد مخترق، فلن تكون قد تعرضت له إطلاقًا.

ترتيب الأولوية: تجاوز الحزمة، ثم تجاوز النظام البيئي، ثم الافتراضي العام. يتيح لك ذلك تعيين افتراضي متحفظ واستثناء حزم تحتاج فيها إلى تحديثات أسرع. راجع docs/configuration.md للحصول على المرجع الكامل للإعدادات.

فحص المخرجات

لا تنظر التهدئة إلا إلى الطابع الزمني لنشر الإصدار — فهي لا تفحص البايتات الفعلية أبدًا. يسدّ فحص المخرجات هذه الفجوة: عند تمكينه، تُنقل كل مخرجات إلى التخزين وتُفحص بواسطة خدمة خارجية واحدة أو أكثر (trivy، أو ClamAV، أو Wiz، أو أي شيء آخر يتحدث عقد HTTP/JSON صغير) قبل تثبيتها في ذاكرة التخزين المؤقت وتقديمها للعملاء.

scanning:
  enabled: true
  signing_key: ${PROXY_SCANNING_SIGNING_KEY}
  scanners:
    - name: clamav
      url: http://clamav-adapter:8080/scan
      mode: block             # a block verdict deletes the artifact and returns 403
    - name: trivy
      url: http://trivy-adapter:8081/scan
      mode: monitor            # findings are logged, never gate caching
      ecosystems: [npm, pypi]

لا يقوم الوكيل أبدًا بتحميل بايتات المخرجات إلى الماسح الضوئي. يتم إخطار كل ماسح ضوئي ببيانات وصفية للحزمة بالإضافة إلى رابط موقّع قصير الأجل؛ يقوم الماسح الضوئي بسحب البايتات بنفسه من تخزين الوكيل الخاص. تعمل الماسحات الضوئية بشكل متزامن، وأول ماسح ضوئي في وضع block يبلغ عن حكم غير مسموح به يفوز فورًا، مما يلغي الباقي. راجع docs/configuration.md للحصول على المرجع الكامل للتكوين وعقد HTTP الخاص بالماسح الضوئي.

السجلات المدعومة

السجل	اللغة/المنصة	فترة التهدئة	مكتمل
npm	JavaScript	نعم	✓
Cargo	Rust	نعم	✓
RubyGems	Ruby	نعم	✓
Go proxy	Go		✓
Hex	Elixir	نعم*	✓
pub.dev	Dart	نعم	✓
PyPI	Python	نعم	✓
Maven	Java		✓
Gradle Build Cache	Java/Kotlin		✓
NuGet	.NET	نعم	✓
Composer	PHP	نعم	✓
Conan	C/C++		✓
Conda	Python/R	نعم	✓
CRAN	R		✓
Julia	Julia		✓
Swift	Swift		✓
Container	Docker/OCI		✓
Homebrew	macOS/Linux		✓
Debian	Debian/Ubuntu		✓
RPM	RHEL/Fedora		✓
Alpine	Alpine Linux		✓
Arch	Arch Linux		✗
Chef	Chef		✗
Generic	Any		✓
Helm	Kubernetes		✓
Vagrant	Vagrant		✗

تتطلب فترة التهدئة طوابع زمنية للنشر في البيانات الوصفية. السجلات التي لا تحتوي على "نعم" في عمود فترة التهدئة إما لا تكشف عن الطوابع الزمنية أو لم يتم ربطها بعد.

* تتطلب فترة التهدئة الخاصة بـ Hex تعطيل التحقق من توقيع السجل (HEX_NO_VERIFY_REPO_ORIGIN=1) نظرًا لأن الوكيل يعيد ترميز حمولة protobuf.

التثبيت

brew install git-pkgs/git-pkgs/proxy

أو قم بتنزيل ملف ثنائي من صفحة الإصدارات.

Helm

قم بتثبيت المخطط من GHCR، مع تعيين عنوان URL العام الذي ستستخدمه عملاء مدير الحزم للوصول إلى الوكيل:

helm install proxy oci://ghcr.io/git-pkgs/charts/proxy \
  --set config.data.base_url=https://proxy.example.com

يوزع المخطط الافتراضي نسخة واحدة مدعومة بوحدة تخزين دائمة بسعة 10 GiB، باستخدام SQLite وتخزين الملفات على نظام الملفات تحت /data. راجع deploy/charts/proxy/values.yaml لخيارات إعداد الدخول وقاعدة البيانات الخارجية وتخزين الكائنات.

البدء السريع

# Build from source
go build -o proxy ./cmd/proxy

# Run with defaults (listens on :8080)
./proxy

# Run with custom settings
./proxy -listen :3000 -base-url https://proxy.example.com

الوكيل يعمل الآن. قم بتهيئة مديري الحزم لديك لاستخدامه.

OpenAPI (Swagger)

يستخدم هذا المستودع swaggo لإنشاء مواصفة OpenAPI من المعالجات المعلّقة.

إنشاء المواصفة:

go install github.com/swaggo/swag/cmd/swag@latest
go generate ./internal/server

تُكتب الملفات المُنشأة إلى docs/swagger/.

عندما يكون الوكيل قيد التشغيل، اجلب المواصفات الحية من:

• http://localhost:8080/openapi.json

أو استبدل http://localhost:8080 بعنوان URL الأساسي المُهيأ لديك. يظهر هذا الرابط أيضًا على لوحة التحكم.

تهيئة مديري الحزم

npm

أنشئ أو حرّر ~/.npmrc:

registry=http://localhost:8080/npm/

أو قم بتعيينه لكل مشروع في .npmrc:

registry=http://localhost:8080/npm/

أو استخدم متغير البيئة:

npm_config_registry=http://localhost:8080/npm/ npm install

npm audit وpnpm audit وyarn npm audit وnpm audit signatures تعمل عبر الوسيط: يتم تمرير نقاط نهاية التدقيق ومفاتيح التوقيع إلى السجل upstream المُهيأ، مع تطبيق مصادقة upstream. وبالتالي تأتي التنبيهات من قاعدة بيانات upstream، وليس من بيانات الثغرات الخاصة بالوسيط، ولا تُستبعد الإصدارات التي يحجبها cooldown من التقرير.

Cargo

أنشئ أو حرّر ~/.cargo/config.toml:

[source.crates-io]
replace-with = "proxy"

[source.proxy]
registry = "sparse+http://localhost:8080/cargo/"

أو قم بتعيينه لكل مشروع في .cargo/config.toml في جذر مشروعك.

RubyGems / Bundler

قم بتعيين مصدر الـ gem في ملف Gemfile الخاص بك:

source "http://localhost:8080/gem"

أو قم بالتهيئة بشكل عام:

gem sources --add http://localhost:8080/gem/
bundle config mirror.https://rubygems.org http://localhost:8080/gem

وحدات Go

قم بتعيين متغير البيئة GOPROXY:

export GOPROXY=http://localhost:8080/go,direct

أو في ملف تعريف shell الخاص بك للاستمرارية.

Homebrew

وجّه واجهة JSON API ونطاق artifacts الخاص بـ Homebrew إلى البروكسي:

export HOMEBREW_API_DOMAIN=http://localhost:8080/homebrew
export HOMEBREW_ARTIFACT_DOMAIN=http://localhost:8080

يعمل نطاق artifact كوكيل (proxy) لبيانات manifests وكتل bottle تحت /v2/homebrew/core/. يقتصر توجيه GHCR على هذا المستودع. تستخدم أرشيفات المصدر، وتنزيلات تطبيقات cask، وartifacts الخاصة بـ tap المخصصة، ومرايا bottle المسطحة القديمة عناوين URL الاحتياطية العادية الخاصة بـ Homebrew. أبقِ الاحتياط مفعّلًا من خلال ترك HOMEBREW_ARTIFACT_DOMAIN_NO_FALLBACK غير مضبوط.

فعّل cache_metadata أو اضبط PROXY_CACHE_METADATA=true للاحتفاظ بردود Homebrew JSON API من أجل الاحتياط دون اتصال. تُخزَّن كتل bottle وmanifests الخاصة بـ OCI مؤقتًا دون هذا الإعداد.

تكون upstreams افتراضيًا على https://formulae.brew.sh/api لـ JSON API وhttps://ghcr.io لـ artifacts. لتسلسل هذا الوكيل مع وكيل آخر، اضبط نقاط نهاية Homebrew الخاصة به كـ upstreams:

upstream:
  homebrew_api: "https://upstream-proxy.example.com/homebrew"
  homebrew_artifact: "https://upstream-proxy.example.com"

متغيرات البيئة المكافئة هي PROXY_UPSTREAM_HOMEBREW_API و PROXY_UPSTREAM_HOMEBREW_ARTIFACT.

Hex (Elixir)

قم بالتهيئة في ~/.hex/hex.config:

{default_url, <<"http://localhost:8080/hex">>}.

أو قم بتعيين متغير البيئة:

export HEX_MIRROR=http://localhost:8080/hex

pub.dev (Dart/Flutter)

قم بتعيين متغير البيئة PUB_HOSTED_URL:

export PUB_HOSTED_URL=http://localhost:8080/pub

PyPI (pip)

قم بتهيئة pip لاستخدام البروكسي: