معماری·۲ دقیقه مطالعه
پین‌کردن و IPFS Cluster
هر شیئی که zev ذخیره می‌کند نشانی محتوایی دارد، پس از پیش یک شیء واقعی IPFS است؛ اما محتوایی که فقط روی دیسک محلی یک گره است با یک خرابی سخت‌افزاری از دست می‌رود. پین‌کردن روشی است که zev با آن مطمئن می‌شود محتوا واقعاً در دسترس می‌ماند، و IPFS Cluster چیزی است که این پین‌کردن را میان بیش از یک گره هماهنگ می‌کند.
## پین‌کردن
پین‌کردن محتوا را در IPFS بارگذاری می‌کند و آن را از پاک‌سازی حافظه محافظت می‌کند. نتیجه یک CID استاندارد است که روی هر دروازه یا گره IPFS باز می‌شود؛ شناسه‌ای مخصوص zev نیست.
```bash
curl -X POST "https://your-server/v1/pins?name=my-file" \
--data-binary @my-file \
-H "Authorization: Bearer <pat>"
```
پاسخ یک گواهی امضاشده دارد (یک پیام و امضا که ثابت می‌کند سرور دقیقاً همان CID را، با همان اندازه و در همان زمان پین کرده است) که هر کسی بعداً می‌تواند بدون اعتماد به حرف سرور راستی‌آزمایی‌اش کند:
```bash
curl "https://your-server/v1/pins/<cid>/verify"
```
پین‌کردن سهمیهٔ فضای هر کاربر و سقف تعداد پین‌ها را که بر پایهٔ طرح حساب تعیین می‌شوند رعایت می‌کند و هر دو را پیش از پذیرش محتوای تازه بررسی می‌کند.
## IPFS Cluster
یک گره IPFS که محتوا را پین می‌کند هنوز یک نقطهٔ شکست تکی است. IPFS Cluster پین‌کردن را میان مجموعه‌ای از گره‌های IPFS هماهنگ می‌کند، تا همان محتوا روی بیش از یکی از آن‌ها تکثیر شود و وضعیت سراسری خوشه نشان دهد هر گره واقعاً پین را تمام کرده یا نه.
API پین zev با نقطهٔ پایانی `/add` خود خوشه کار می‌کند که محتوا را در یک گام اتمی به IPFS می‌افزاید و در کل خوشه پین می‌کند؛ به‌جای افزودن به یک گره و پین‌کردن جداگانه، که فاصله‌ای می‌گذارد که محتوا هست اما هنوز برای تکثیر ردیابی نمی‌شود.
### ضریب تکثیر
هر پین یک ضریب تکثیر دارد: چند گره از خوشه باید نسخه‌ای از آن داشته باشند. پین‌های طرح رایگان ضریب ثابت ۱ دارند. پین‌های طرح پریمیوم از `-1` استفاده می‌کنند که یعنی «روی همهٔ گره‌های موجود پین کن»، نه عددی ثابت؛ عمداً، چون حداقلی ثابت که از تعداد واقعی گره‌های خوشه بیشتر باشد باعث شکست پین می‌شود. `-1` با هر تعداد گره سازگار است، پس تکثیر پریمیوم به‌محض پیوستن گره‌های بیشتر به خوشه خودکار به افزونگی واقعی چندگره‌ای تبدیل می‌شود، بی‌آنکه در zev تغییری در کد یا پیکربندی لازم باشد.
### بررسی وضعیت
دو نقطهٔ پایانی وضعیت واقعی خوشه را نشان می‌دهند، نه داده‌ای شبیه‌سازی‌شده یا ذخیره‌شده:
```bash
curl "https://your-server/v1/pins/<cid>/cluster-status"
# {"cid":"...","status":"pinned","pinned_peers":1,"total_peers":1}
curl "https://your-server/v1/cluster/health"
# {"cluster_id":"...","peername":"...","peer_count":1,"total_freespace_bytes":9811005992}
```
`cluster-status` سلامت تکثیر هر پین را گزارش می‌دهد: چند گره از خوشه پین را `"pinned"` تأیید کرده‌اند، در برابر آن‌هایی که هنوز `"pinning"` یا در حالت `"error"` هستند. `cluster/health` کل خوشه را گزارش می‌دهد: تعداد فعلی گره‌ها و فضای آزاد کل همهٔ آن‌ها که در هر فراخوانی زنده از خوشه پرسیده می‌شود.
## چرا این طراحی
پین‌کردن و هماهنگی خوشه عمداً دو گام جدا نگه داشته شده‌اند تا تکثیر بتواند بدون تغییر هیچ چیز دیگری رشد کند. استقرار تک‌گره‌ای و ده‌گره‌ای دقیقاً همان کد پین را اجرا می‌کنند؛ تنها تفاوت در تعداد گره‌هایی است که در `cluster-status` و `cluster/health` دیده می‌شوند و اینکه تکثیر `-1` تا کجا واقعاً می‌رسد. هیچ بخشی از API پین، شیوهٔ گواهی یا سامانهٔ سهمیه لازم نیست بداند چند گره وجود دارد.