# شروع کار با بسته‌ها

> مسیری راهنما از «بسته چیست؟» تا انتشار ایمن: یک رجیستری برای npm، PyPI، Cargo، Zig و کانتینرها، انتشار و نصب با ابزارهای همیشگی، آینه‌هایی که هر فایل را می‌سنجند، بسته‌های خصوصی و هشدارها. اول تصویر، هر گام با توضیح.

Source: https://zaryn.xyz/docs/fa/get-started-packages

یک بار منتشر کنید، با نام نصب کنید، با همان ابزارهایی که می‌شناسید. Zaryn یک رجیستری برای npm، PyPI، Cargo، Zig، کانتینرها و فایل‌های ساده است، و یک آینه برای رجیستری‌های عمومی. همه‌چیز در صفحهٔ [Packages](/packages) است.

## ۱. بسته چیست

```diagram
type: flow
title: یک بار منتشر کنید، با نام نصب کنید
---
کد شما | یک کتابخانه، یک ابزار، ایمیج یک برنامه | | 📦
~ npm publish، cargo publish، docker push…
رجیستری Zaryn | ذخیره‌شده با هشش، کنار مخزنی که آن را ساخت | accent | ▣
~ npm install، pip install، cargo add…
پروژهٔ هر کسی | یک فرمان، با همان ابزاری که از قبل دارند | good | ✓
```

**بسته** کدی است که بسته‌بندی شده تا دیگران با یک فرمان از آن استفاده کنند. یک **مدیر بسته** (npm، pip، cargo، zig، docker) آن را نصب می‌کند و **رجیستری** جایی است که از آن دانلود می‌کند. Zaryn برای همهٔ آن‌ها رجیستری است، پس فقط به ابزارتان می‌گویید Zaryn کجاست.

## ۲. پنج واژه‌ای که می‌بینید

```diagram
type: cards
---
🔢 | نسخه | `1.4.2`. نسخهٔ منتشرشده هرگز عوض نمی‌شود: اصلاح یعنی `1.4.3` | accent
#️⃣ | هش | اثر انگشت بایت‌های یک فایل؛ ابزارتان در هر نصب آن را می‌سنجد | good
🔗 | وابستگی | بسته‌ای که پروژه‌تان به کار می‌برد؛ مدیر بسته آن را می‌آورد |
🔑 | توکن | گذرواژه‌ای برای ابزارها: انتشار به توکنی با `package:write` نیاز دارد | warn
🙈 | Yank | پنهان کردن نسخه‌ای خراب از پروژه‌های تازه؛ پروژه‌های موجود کار می‌کنند |
```

## ۳. چرا می‌توانید به آنچه نصب می‌کنید اعتماد کنید

```diagram
type: graph
title: سه قفل روی هر نصب
alt: نسخهٔ منتشرشده جایگزین نمی‌شود، هر فایل با هشش ذخیره و سنجیده می‌شود، و نامی که روی Zaryn هست همیشه از Zaryn می‌آید، پس هم‌نامی از رجیستری عمومی نمی‌تواند جا بزند
height: 36
---
node pub | 1.4.2 منتشرشده | 12 18 | file | accent | هرگز جایگزین نمی‌شود: همان بایت‌ها، سال بعد هم
node hash | هشش | 50 18 | hash | good | زیر آن ذخیره می‌شود؛ نصب‌کننده دوباره می‌سنجدش
node you | نصب شما | 88 18 | laptop | good | دقیقاً همان چیزی را می‌گیرد که منتشر شد
link pub hash | | path
link hash you | سنجیده | path
```

سه چیز با هم: یک نسخه **جایگزین نمی‌شود**، هر فایل در ورود و خروج **با هشش سنجیده می‌شود**، و نامی که روی Zaryn هست **همیشه از Zaryn می‌آید**، پس هیچ‌کس نمی‌تواند بسته‌ای هم‌نام در یک رجیستری عمومی منتشر کند و در نصب‌های شما جا بزند (*سردرگمی وابستگی*).

## ۴. یک توکن انتشار بگیرید

```diagram
type: flow
title: یک بار
---
صفحهٔ Packages | zaryn.xyz/packages | | ▣
~ Create a publish token
توکن | همین حالا کپی‌اش کنید؛ `package:write` دارد | warn | 🔑
~ به ابزارتان بدهید
آماده | `.npmrc`، `~/.pypirc`، `cargo login`، `docker login` | good | ✓
```

با توکن مثل گذرواژه رفتار کنید: آن را از مخزن‌های عمومی دور نگه دارید (ابزارها می‌توانند از متغیر محیطی بخوانندش) و اگر لو رفت تازه‌اش را بسازید.

## ۵. ابزارتان را برگزینید

```diagram
type: cards
title: یک ایده، شش ابزار
---
🟩 | npm | scope `@you` در `.npmrc`، سپس `npm publish --access public` | accent
🐍 | PyPI | `python -m build`، سپس `twine upload` به index زرین |
🦀 | Cargo | یک بار `[registries.zaryn]`، سپس `cargo publish --registry zaryn` |
⚡ | Zig | بسته را بارگذاری کنید؛ Zaryn نشانی و هشی را که `zig fetch` می‌خواهد می‌دهد |
🐳 | کانتینرها | `docker push zaryn.xyz/you/app:1.0` | good
📄 | هر فایلی | `curl -T` به یک نشانی ثابت: برنامه، دیتاست، فرم‌ور |
```

هر ابزار راهنمای خودش را با همهٔ گام‌ها دارد: [npm](/docs/fa/packages-npm)، [PyPI](/docs/fa/packages-pypi)، [Rust](/docs/fa/packages-rust)، [Zig](/docs/fa/packages-zig)، [کانتینرها](/docs/fa/packages-containers)، [فایل‌ها](/docs/fa/packages-files).

## ۶. نخستین بسته‌تان را منتشر کنید

یک بستهٔ npm، از آغاز تا پایان:

```ini
# .npmrc in your project
@your-username:registry=https://api.zaryn.xyz/v1/packages/npm/
//api.zaryn.xyz/v1/packages/npm/:_authToken=${NPM_TOKEN}
```

```json
{ "name": "@your-username/hello", "version": "0.1.0", "main": "index.js" }
```

```bash
npm publish --access public
```

```diagram
type: graph
title: فقط scope شما به Zaryn می‌رود
alt: npm بسته‌های @your-username را به Zaryn و بقیه را به npmjs.com می‌فرستد
height: 36
---
node npm | npm | 12 18 | laptop | accent | `.npmrc` را می‌خواند تا بداند هر بسته از کجا بیاید
node z | Zaryn | 60 6 | cloud | good | `@your-username/…`
node pub | npmjs.com | 60 30 | cloud | | بقیه، مثل قبل
link npm z | @your-username/hello | path
link npm pub | react, lodash… | path2
```

برای انتشار یک اصلاح، `version` را بالا ببرید و دوباره منتشر کنید. بدون `--access public`، npm یک بستهٔ خصوصی می‌خواهد که پریمیوم لازم دارد.

## ۷. نصبش کنید

```bash
npm install @your-username/hello          # npm, pnpm, yarn
pip install your-package                  # with Zaryn's index set once
cargo add your-crate --registry zaryn
docker pull zaryn.xyz/you/app:1.0
```

کاربرانتان یک بار، همان‌طور که شما کردید، Zaryn را تنظیم می‌کنند و سپس مثل همیشه نصب می‌کنند. بسته‌ها و ایمیج‌های عمومی برای نصب توکن نمی‌خواهند.

## ۸. نصب مستقیم از یک مخزن

```diagram
type: flow
title: بی گام انتشار
---
یک کامیت | هر کامیت از مخزنی با package.json، pyproject یا build.zig.zon | | ⎇
~ زبانهٔ install
یک نشانی | آرشیو ثابتی از دقیقاً همان کامیت | accent | 🔗
~ npm install …، pip install …
سنجاق‌شده | پروژهٔ شما دقیقاً همان کامیت را به کار می‌برد | good | 📌
```

زبانهٔ **install** مخزن، کنار فرمان‌های کلون، خط هر ابزار را می‌دهد. برای آزمودن یک اصلاح پیش از انتشار خوب است.

## ۹. نصب سریع‌تر از راه آینه‌ها

```diagram
type: graph
title: یک فرمان، همهٔ ابزارها از راه Zaryn
alt: zev mirror on ابزارهای pip، npm، go، cargo و rustup را به آینه‌های Zaryn می‌فرستد که هر فایل را با هش منتشرشده‌اش می‌سنجند
height: 40
---
node zev | zev mirror on | 12 20 | ci | accent | یک بلوک نشان‌دار به تنظیمات هر ابزار می‌افزاید؛ `zev mirror off` آن را برمی‌دارد
node tools | pip, uv, npm, go, cargo, rustup, zig | 50 20 | laptop | |
node m | آینه‌های Zaryn | 88 20 | cloud | good | هر فایل با هشی که pypi.org، npm یا crates.io فهرست کرده سنجیده می‌شود
link zev tools | | path
link tools m | | path2
```

```bash
zev mirror on        # or pick some: zev mirror on pip cargo
```

نصب از pypi.org، npmjs.com، crates.io یا گیت‌هاب کند است یا جایی که هستید مسدود است؟ آینه‌ها یک بار می‌آورند و از Zaryn می‌دهند، و چون هر فایل با هشی سنجیده می‌شود که ابزارهایتان از قبل می‌شناسند، آینه نمی‌تواند چیزی را عوض کند. [آینه‌ها](/docs/fa/package-mirrors).

## ۱۰. ایمیج‌های کانتینر

```diagram
type: flow
title: از لپ‌تاپ تا خوشه
---
docker build | `zaryn.xyz/you/app:1.0`: رجیستری، مالک، ایمیج، برچسب | | 🛠
~ docker push
روی Zaryn | فقط لایه‌هایی که Zaryn ندارد بارگذاری می‌شوند | accent | ⇡
~ docker pull، Kubernetes
در حال اجرا | ایمیج عمومی بی‌ورود؛ خصوصی با یک کلید فقط‌خواندنی | good | ▶
```

چارت‌های Helm و دیگر artifactهای OCI کنار ایمیج‌ها می‌مانند. ایمیجی که [CI](/docs/fa/get-started-ci) بسازد گواهی منشأ امضاشده و SBOM هم می‌گیرد.

## ۱۱. برنامه‌ها، دیتاست‌ها، فرم‌ور

```bash
curl -T mytool-1.0.0-linux.tar.gz -H "Authorization: Bearer $ZARYN_TOKEN" \
  https://api.zaryn.xyz/v1/packages/generic/mytool/1.0.0/mytool-1.0.0-linux.tar.gz
```

هر چه بستهٔ یک زبان نیست به یک **نشانی ثابت** می‌رود: نام، نسخه، فایل. پس از بارگذاری، آن نشانی همیشه همان بایت‌ها را می‌دهد و پاسخ SHA-256 را هم دارد تا کنار دانلود منتشرش کنید.

## ۱۲. بسته‌های خصوصی، و فضا

```diagram
type: stats
---
500 MB | رایگان: بسته‌ها و ایمیج‌ها | بسته‌های عمومی؛ آینه‌ها رایگان‌اند | 1 |
100 GB | پریمیوم | بسته‌ها و ایمیج‌های خصوصی هم | 100 | accent
0 | هزینهٔ بسته‌های دیگران برای شما | نصب بسته‌های عمومی هرگز حساب نمی‌شود | | good
```

در پریمیوم یک بسته یا ایمیج می‌تواند خصوصی باشد: فقط شما یا سازمانتان می‌توانید ببینید یا نصبش کنید، با همان توکن. [طرح‌ها](/docs/fa/billing-and-credits).

## ۱۳. وقتی چیزی که به کار می‌برید ناامن است

```diagram
type: flow
title: هشداری به پروژهٔ شما می‌رسد
---
ثبت‌شده | مالکی کامیت‌های آسیب‌دیده را علامت می‌زند: دادهٔ مسموم، در پشتی، مجوز نادرست | bad | ⚠
~ تبار دنبال می‌شود
خبردار می‌شوید | مالکان هر چه از آن‌ها ساخته شده، با یک حکم، خبر می‌گیرند | warn | 🔔
~ در CI
مسدود | `"advisories": {"fail_on": "high"}` ساخت روی آن را متوقف می‌کند | good | 🛡
```

Zaryn تبار ثبت‌شده را دنبال می‌کند (آموزش‌دیده روی، fine-tune شده از، برگرفته از، به کار می‌برد)، پس یک هشدار به هر مخزنی که از کامیت‌های آسیب‌دیده ساخته شده می‌رسد و [CI](/docs/fa/get-started-ci) می‌تواند تا وقتی یکی به مخزن شما می‌رسد از ساخت خودداری کند. [هشدارها](/docs/fa/advisories).

## ۱۴. نام‌ها، نسخه‌ها، yank

```diagram
type: cards
---
🏷 | نام‌ها | هر که زودتر آمد، جدا برای هر نوع؛ فقط شما نسخه‌های تازهٔ نام خودتان را منتشر می‌کنید | accent
🔢 | نسخه‌ها | هرگز جایگزین نمی‌شوند: اصلاح یعنی نسخهٔ تازه |
🙈 | Yank | پنهان کردن نسخه‌ای خراب از نصب‌های تازه؛ پروژه‌هایی که به آن سنجاق‌اند کار می‌کنند | warn
📦 | یک جا | همهٔ بسته‌ها و ایمیج‌هایتان، با فضایشان، در صفحهٔ Packages | good
```

بعد: راهنمای ابزارتان، [آینه‌ها](/docs/fa/package-mirrors) با جزئیات، و [هشدارها](/docs/fa/advisories).