git-pkgs proxy

पैकेज रजिस्ट्रियों के लिए एक कैशिंग प्रॉक्सी। आर्टिफैक्ट्स को स्थानीय रूप से कैश करके पैकेज डाउनलोड को तेज़ करता है, बैंडविड्थ उपयोग को कम करता है और विश्वसनीयता में सुधार करता है।

वर्शन कूलडाउन

अधिकांश सप्लाई चेन हमले गति पर निर्भर करते हैं: एक दुर्भावनापूर्ण वर्शन प्रकाशित होता है और कुछ ही मिनटों में ऑटोमेटेड पाइपलाइनों द्वारा उपभोग कर लिया जाता है, इससे पहले कि कोई इसे नोटिस करे। कूलडाउन सुविधा नई प्रकाशित वर्शनों पर एक क्वारंटीन अवधि जोड़ती है। सक्षम होने पर, प्रॉक्सी मेटाडेटा प्रतिक्रियाओं से वर्शनों को तब तक हटा देती है जब तक कि वे एक कॉन्फ़िगर करने योग्य थ्रेशोल्ड से अधिक पुराने न हो जाएँ।

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 प्रकाशित करता है, तो आपके बिल्ड 3 दिन बीतने तक 4.17.21 का उपयोग करते रहते हैं। यदि नया रिलीज़ समझौता किया गया निकलता है, तो आप कभी उजागर नहीं हुए।

समाधान क्रम: पैकेज ओवरराइड, फिर इकोसिस्टम ओवरराइड, फिर वैश्विक डिफ़ॉल्ट। यह आपको एक रूढ़िवादी डिफ़ॉल्ट सेट करने और उन पैकेजों के लिए अपवाद बनाने की सुविधा देता है जहाँ आपको तेज़ अपडेट की आवश्यकता होती है। पूर्ण कॉन्फ़िग संदर्भ के लिए 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]

प्रॉक्सी कभी भी आर्टिफैक्ट बाइट्स को स्कैनर पर अपलोड नहीं करता। प्रत्येक स्कैनर को पैकेज मेटाडेटा और एक अल्पकालिक हस्ताक्षरित URL के साथ सूचित किया जाता है; स्कैनर स्वयं प्रॉक्सी के अपने स्टोरेज से बाइट्स खींचता है। स्कैनर समवर्ती रूप से चलते हैं, और पहला block-मोड स्कैनर जो not-allowed का निर्णय रिपोर्ट करता है, तुरंत जीत जाता है, बाकी को रद्द कर देता है। पूर्ण कॉन्फ़िग संदर्भ और स्कैनर HTTP अनुबंध के लिए docs/configuration.md देखें।

समर्थित रजिस्ट्रियाँ

रजिस्ट्री	भाषा/प्लेटफ़ॉर्म	कूलडाउन	पूर्ण
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

या releases page से बाइनरी डाउनलोड करें।

Helm

GHCR से चार्ट इंस्टॉल करें, और वह सार्वजनिक URL सेट करें जिसका उपयोग पैकेज-मैनेजर क्लाइंट प्रॉक्सी तक पहुँचने के लिए करेंगे:

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

डिफ़ॉल्ट चार्ट /data के अंतर्गत SQLite और फ़ाइलसिस्टम आर्टिफ़ैक्ट स्टोरेज का उपयोग करते हुए, 10 GiB पर्सिस्टेंट वॉल्यूम द्वारा समर्थित एक रेप्लिका तैनात करता है। इनग्रेस, बाहरी डेटाबेस और ऑब्जेक्ट-स्टोरेज कॉन्फ़िगरेशन विकल्पों के लिए 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)

यह रेपो एनोटेटेड हैंडलरों से OpenAPI स्पेक जनरेट करने के लिए swaggo का उपयोग करता है।

स्पेक जनरेट करें:

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

Generated फ़ाइलें docs/swagger/ में लिखी जाती हैं।

जब proxy चल रहा हो, तो live spec यहाँ से fetch करें:

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

या http://localhost:8080 को अपने configured base URL से बदलें। यह लिंक dashboard पर भी दिखाया जाता है।

Package Managers को Configure करना

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 प्रॉक्सी के माध्यम से काम करते हैं: audit और signing-key endpoints को कॉन्फ़िगर किए गए upstream registry को पास किया जाता है, साथ में upstream authentication लागू होता है। इसलिए advisories upstream के डेटाबेस से आते हैं, प्रॉक्सी के अपने vulnerability डेटा से नहीं, और cooldown द्वारा रोके गए versions रिपोर्ट से बाहर नहीं रखे जाते।

Cargo

~/.cargo/config.toml बनाएँ या संपादित करें:

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

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

या अपने प्रोजेक्ट रूट में .cargo/config.toml में प्रति-प्रोजेक्ट सेट करें।

RubyGems / Bundler

अपने Gemfile में gem स्रोत सेट करें:

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

या विश्व स्तर पर कॉन्फ़िगर करें:

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

Go मॉड्यूल

GOPROXY environment variable सेट करें:

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

या फिर अपने shell profile में स्थायित्व के लिए।

Homebrew

Homebrew के JSON API और artifact domain को proxy की ओर इंगित करें:

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

The artifact domain /v2/homebrew/core/ के अंतर्गत manifests और bottle blobs को proxy करता है। GHCR routing उसी repository तक सीमित है। Source archives, cask application downloads, custom tap artifacts, और legacy flat-file bottle mirrors Homebrew के सामान्य fallback URLs का उपयोग करते हैं। HOMEBREW_ARTIFACT_DOMAIN_NO_FALLBACK को unset छोड़कर fallback सक्षम रखें।

Offline fallback के लिए Homebrew JSON API responses को बनाए रखने हेतु cache_metadata सक्षम करें या PROXY_CACHE_METADATA=true सेट करें। Bottle blobs और उनके OCI manifests इस सेटिंग के बिना भी cached रहते हैं।