چک‌لیست موجودی زنده کلود VPS (per-module)

> version: 3.2 | last_updated: 2026-09-23 | audience: admin / agent

اصل (ADR-053 — بدون پرسش فیلدبه‌فیلد)

هر ارائه‌دهنده قرارداد API خودش را دارد — **کپی کور آروان ممنوع**.
ولی **لایه‌بندی محصول برای همه یکی است**:

```
اتصال (سرور بیرونی = فقط احراز)
→ گروه سرور + موجودی API همان ارائه‌دهنده
→ قفل محصول: پلن/Flavor (+ شبکه/اعتبار اختیاری) در تب Provision
→ انتخاب مشتری: فقط hostname و در صورت نیاز region + image
→ create/changePackage: server_type از محصول؛ region/image از CF سپس محصول
```

| لایه | مثال فیلد | مشتری می‌بیند؟ |
|------|-----------|----------------|
| اتصال | api_token, api_url | خیر |
| قفل محصول | server_type (Flavor), network_id?, password_type | فقط ادمین |
| سفارش | hostname, region?, image? | بله |

**ممنوع در CF مشتری:** `server_type` / plan / flavor / size (مگر قیمت جدا برای هر پلن؛ در BSS معمولاً محصول جدا)
**ممنوع در فرم محصول کلود با پلن ثابت:** cores, ram_mb, disk_gb, bandwidth به‌عنوان فیلد اصلی (منابع = flavor)

---

مرجع WHMCS برای همهٔ ارائه‌دهنده‌ها (ADR-054)

قبل از اصلاح هر ماژول: وجود ماژول WHMCS را چک کن؛ از مستند/سورس آزاد الگو بگیر؛ کد proprietary را کپی نکن.

| کلید BSS | WHMCS؟ | منبع | محصول (ConfigOptions) | سفارش (Configurable) | BSS |
|----------|--------|------|------------------------|----------------------|-----|
| `arvancloud` | ❌ | API آروان | — | — | ✅ |
| `hetzner` | ✅ | [lastwall](https://github.com/lastwall/whmcs-hetzner-cloud-automation) · [PUQ docs](https://github.com/puqcloud/WHMCS-Module-Hetzner-Datacenter) · [MG](https://www.modulesgarden.com/products/whmcs/hetzner-cloud-servers) | Type+Location+Image؛ backups؛ FIP | Location+OS؛ Type فقط با قیمت | ✅ |
| `digitalocean` | ✅ | [ModulesGarden DO](https://www.modulesgarden.com/products/whmcs/digitalocean-droplets) | Size+Region+Image+flags | Region/Image/(Size) | ✅ |
| `linode` | ✅ کهنه | [ganquancode](https://github.com/ganquancode/whmcs-linode) (API v3) | DC+plan+dist | ضعیف | ✅ v4 + **تست زنده کامل پنل** |
| `vultr` | ✅ | [vultr/whmcs-vultr](https://github.com/vultr/whmcs-vultr) · [MG Vultr](https://www.modulesgarden.com/products/whmcs/vultr-vps) | **plan** روی محصول | OS/region | ✅ |
| `contabo` | ✅ | [contabovps](https://github.com/sskafandri/contabovps) · Marketplace | OAuth addon؛ region/plan/OS | location+OS+productId | ✅ |
| `ovh` | ✅ | [WHMCS_ovhresell](https://github.com/ReasonPrototype/WHMCS_ovhresell) · [MG OVH](https://www.modulesgarden.com/products/whmcs/ovhcloud-vps-and-dedicated-servers) | planCode / flavor | DC+OS | ✅ |
| `abrasiatech` / فاز۴ | ❌ | — | plan روی محصول | region+image | ✅ provisional |
| `aws` | ✅ تجاری | [MG EC2](https://www.modulesgarden.com/products/whmcs/amazon-ec2) | region+type+AMI | type/AMI/volume | ✅ |
| `gcp` / `azure` | محدود | MG bundle / شخص ثالث | مدل جدا | — | ✅ |

درس مشترک ([lastwall](https://github.com/lastwall/whmcs-hetzner-cloud-automation)): اگر پلن روی محصول قفل است، picker پلن در سبد نگذار.

وضعیت ستون‌ها:

| نماد | معنی |
|------|------|
| ✅ | پیاده و قابل تست زنده |
| 🔧 | Client/عملیات پایه هست؛ موجودی زنده / CF مشتری نیست |
| ⏳ | REST اسکلت؛ تا تست زنده مسیر API قطعی نیست |
| ❌ | عمداً خارج از الگوی «VPS ساده» یا نیاز به طراحی جدا |

---

ترتیب پیشنهادی پیاده‌سازی موجودی زنده

1–10. ~~فاز اصلی~~ ✅ · 11. ~~Alibaba~~ ✅ · 12. ~~Aruba~~ ✅ provisional · 13. ~~فاز۴ اسکلت~~ ✅ path-based · 14. ~~AWS/GCP/Azure~~ ✅ (کاتالوگ محدود AMI/Marketplace)

تمام کلیدهای `INVENTORY_MODULES` موجودی دارند. اسکلت‌های فاز۴ با `inventory_paths` قابل override هستند.

---

چک‌لیست مشترک برای هر ماژول (باید تیک بخورد)

A. اتصال (سرور بیرونی)

☐ `connectionFields` فقط احراز + پیش‌فرض‌های لازم

☐ `connectionFieldDefaults` پر از `api_url` / timeout / verify_ssl (و فیلدهای خاص احراز)

☐ `testConnection` واقعی

☐ سند: از کجا توکن گرفته شود

B. موجودی API (Inventory)

☐ متد(های) `list*` روی Client — شکل پاسخ واقعی همان API (حدس نزن)

☐ شاخه در `PublicCloudInventoryOptions::supports` + `fetchInventory` مخصوص همان ماژول

☐ وابستگی‌ها مشخص (مثلاً image وابسته به region هست یا نه)

☐ کش کوتاه (۳۰–۶۰ث) + پیام خطای خوانا اگر گروه/توکن نباشد

☐ تست `Http::fake` برای parse پاسخ

C. محصول (تب Provision) — قفل محصول

☐ `productFields()` **باریک و اختصاصی** همان ماژول (نه کیسهٔ کامل publicCloud)

☐ Select زنده برای `server_type` (الزامی) و در صورت نیاز region پیش‌فرض / network

☐ گروه سرور الزامی وقتی inventory زنده است

☐ cascade درست (عوض کردن region → رفرش پلن/ایمیج اگر وابسته است)

☐ helperText: Flavor برای ارتقا/تمدید است، نه انتخاب مشتری

D. سفارش مشتری (Custom Field) — فقط انتخاب خرید

☐ فقط فیلدهایی که مشتری باید انتخاب کند: معمولاً `hostname` + `image`؛ `region` فقط اگر چند DC می‌فروشید

☐ **هرگز** `server_type` در CF

☐ گزینه‌ها `id:Label`؛ sync + persist + overlay checkout

☐ پاک‌سازی CFهای اشتباه قدیمی (مثل plan) در persist

E. Provision

☐ `resolveRegion` / `resolveImage`: CF → محصول → سرور

☐ `resolveServerType`: **فقط** محصول/سرور

☐ create/suspend/unsuspend/terminate/changePackage/reboot درست

☐ docs آپدیت + SESSION_LOG + rule ADR-053

---

۱) آروان کلود — `arvancloud` ✅

| مورد | جزئیات |
|------|--------|
| احراز | `api_token` → `Authorization: Apikey …` |
| api_url پیش‌فرض | `https://napi.arvancloud.ir` |
| لیست API | `regions` → per-region: `sizes`, `images?type=distributions` (تو در تو)، `images/marketplace`, `networks` |
| وابستگی | size/image/network **وابسته به region** |
| Select محصول | region, server_type←sizes, image, network_id |
| فیلدهای Provision محصول | فقط: region, server_type, image, network_id, num_ips, ssh_key_id, guest_username, password_type, root_password (بدون cores/ram/disk) |
| CF مشتری | region, image, hostname — **بدون** server_type (پلن فقط روی محصول) |
| اجباری create | region + flavor_id + image_id |
| خاص | گروه سرور الزامی؛ network_id اختیاری؛ floating IP اضافه؛ reboot جدا |
| نکته UI | بدون گروه سرور Selectها خالی‌اند و پیام «ابتدا گروه سرور…» می‌آید |

---

۲) Hetzner Cloud — `hetzner` ✅

| مورد | جزئیات |
|------|--------|
| احراز | Bearer `api_token` |
| api_url | `https://api.hetzner.cloud/v1` |
| لیست API | `GET /locations` · `GET /server_types` · `GET /images?type=system` |
| وابستگی | لیست‌ها **عملاً مستقل** |
| قفل محصول | `server_type` الزامی؛ `region`/`image` پیش‌فرض؛ `num_ips`؛ `ssh_key`؛ اعتبار — بدون cores/ram/disk |
| CF مشتری | `hostname` + `region` + `image` — **بدون** server_type |
| اجباری create | server_type + image + location |
| خاص | Floating IP؛ user_data برای رمز؛ change_type برای ارتقا |
| وضعیت | موجودی زنده + productFields باریک + CF ADR-053 ✅ |

---

۳) DigitalOcean — `digitalocean` ✅

| مورد | جزئیات |
|------|--------|
| احراز | Bearer |
| api_url | `https://api.digitalocean.com/v2` |
| لیست API | `GET /regions` · `/sizes` · `/images?type=distribution` |
| وابستگی | size بر اساس `regions[]` فیلتر می‌شود وقتی region انتخاب شده |
| قفل محصول | `server_type`←size · region/image پیش‌فرض · backups/ipv6 · بدون cores/ram/disk |
| CF مشتری | hostname + region + image — **بدون** server_type |
| اجباری create | size + image + region |
| خاص | Floating IP؛ image با slug |
| وضعیت | موجودی زنده + ADR-053 ✅ |

---

۴) Linode / Akamai — `linode` ✅ تست زنده کامل (2026-09-23)

| مورد | جزئیات |
|------|--------|
| احراز | Bearer |
| api_url | `https://api.linode.com/v4` |
| لیست API | `GET /regions` · `/linode/types` · `/images` |
| قفل محصول | server_type←type · region/image پیش‌فرض · بدون cores/ram/disk |
| CF مشتری | hostname + region + image — بدون type |
| اجباری create | type + image + region + root_pass |
| پنل بومی | پاور · reboot · وضعیت · reinstall · رمز · Weblish کنسول |
| ورود SSH | `root` / `Administrator` (نه hostname) |
| تعویض IP | در پنل نیست |
| وضعیت | موجودی زنده + ADR-053 + **تست زنده کامل** ✅ |

---

۵) Vultr — `vultr` ✅

| مورد | جزئیات |
|------|--------|
| احراز | Bearer |
| api_url | `https://api.vultr.com/v2` |
| لیست API | `GET /regions` · `/plans` · `/os` |
| وابستگی | plan بر اساس `locations[]` فیلتر می‌شود |
| قفل محصول | server_type←plan (مثل [vultr/whmcs-vultr](https://github.com/vultr/whmcs-vultr)) |
| CF مشتری | hostname + region + image(os_id) — بدون plan |
| اجباری create | plan + region + os_id |
| وضعیت | موجودی زنده + ADR-053 ✅ |

---

۶) Contabo — `contabo` ✅

| مورد | جزئیات |
|------|--------|
| احراز | OAuth: client_id + client_secret + api_user + api_password |
| api_url | `https://api.contabo.com` |
| لیست API | `GET /v1/data-centers` · `/v1/compute/images?type=standard` |
| پلن | API کاتالوگ create ندارد → کاتالوگ ثابت productId (مثل WHMCS Contabo) |
| قفل محصول | server_type←productId · period · region/image پیش‌فرض |
| CF مشتری | hostname + region + image — بدون productId |
| اجباری create | region + imageId + productId |
| WHMCS | [contabovps](https://github.com/sskafandri/contabovps) |
| وضعیت | موجودی زنده + ADR-053 ✅ |

---

۷) OVHcloud — `ovh` ✅

| مورد | جزئیات |
|------|--------|
| احراز | application_key + application_secret + consumer_key |
| api_url | `https://eu.api.ovh.com/1.0` |
| لیست API | `GET /cloud/project/{id}/region` · `/flavor?region=` · `/image?region=` |
| وابستگی | همه زیر **project_id** (اتصال)؛ flavor/image وابسته به region |
| قفل محصول | server_type←flavorId · monthly_billing · num_ips · region/image پیش‌فرض |
| CF مشتری | hostname + region + image — بدون flavorId |
| اجباری create | project_id + flavorId + imageId + region |
| خاص | امضای OVH؛ monthly_billing |
| WHMCS | [WHMCS_ovhresell](https://github.com/ReasonPrototype/WHMCS_ovhresell) · ModulesGarden |
| وضعیت | موجودی زنده + ADR-053 ✅ |

---

۸) ابر آسیاتک — `abrasiatech` ✅ (مسیر provisional)

| مورد | جزئیات |
|------|--------|
| احراز | Bearer + `api_url` قابل تنظیم |
| api_url پیش‌فرض | `https://api.asiatech.cloud` |
| لیست API | `GET v1/regions` · `v1/plans?region=` · `v1/images?region=` (فرض از قرارداد create؛ با `inventory_paths` قابل override) |
| قفل محصول | server_type←plan · region/image پیش‌فرض · num_ips |
| CF مشتری | hostname + region + image — بدون plan |
| اجباری create | plan + image (region اختیاری در کد فعلی) |
| وضعیت | موجودی wired + ADR-053 ✅ — **تأیید شکل پاسخ با توکن زنده هنوز لازم است** (سرور فعلی توکن ندارد / API از این host در دسترس نبود) |

---

۹) Gcore — `gcore` ✅

| مورد | جزئیات |
|------|--------|
| احراز | `Authorization: apikey <token>` |
| api_url | `https://api.gcore.com` |
| لیست API | `GET /cloud/v1/regions` · `/flavors/{project}/{region}` · `/images/{project}/{region}` |
| وابستگی | **project_id** روی اتصال؛ flavor/image وابسته به region_id عددی |
| قفل محصول | server_type←flavor_name · region/image پیش‌فرض |
| CF مشتری | hostname + region + image — بدون flavor |
| اجباری create | project_id + region_id + flavor + image |
| وضعیت | موجودی زنده + ADR-053 ✅ |

---

۱۰) IONOS — `ionos` ✅

| مورد | جزئیات |
|------|--------|
| احراز | Bearer token یا Basic (email + token) |
| api_url | `https://api.ionos.com/cloudapi/v6` |
| لیست API | `GET /datacenters` · `/templates` · `/images` |
| خاص | **region در UI = datacenter UUID**؛ ایمیج بر اساس location دیتاسنتر فیلتر می‌شود |
| قفل محصول | server_type←templateUuid · datacenter پیش‌فرض |
| CF مشتری | hostname + region(datacenter) + image — بدون template |
| اجباری create | datacenter + image + (template یا cores/ram) |
| وضعیت | موجودی زنده + ADR-053 + بدنه create v6 ✅ |

---

۱۱) Alibaba ECS — `alibaba` ✅

| مورد | جزئیات |
|------|--------|
| احراز | AccessKeyId + AccessKeySecret (HMAC-SHA1 RPC) |
| لیست | DescribeRegions · DescribeInstanceTypes · DescribeImages |
| قفل محصول | InstanceType |
| CF | region + ImageId |
| وضعیت | موجودی زنده + ADR-053 ✅ |

---

۱۲) Aeza — `aeza` ✅

| مورد | جزئیات |
|------|--------|
| احراز | `X-API-Key` |
| api_url | `https://my.aeza.net/api` |
| لیست API | `GET /services/groups` · `/services/products` · `/os` |
| قفل محصول | server_type←productId · period |
| CF مشتری | hostname + region(group) + image(os) |
| اجباری create | productId + os · سفارش: `POST /services/orders` |
| مرجع | terraform-provider-aeza |
| وضعیت | موجودی زنده + ADR-053 ✅ |

---

۱۳) Aruba Cloud — `aruba` ✅ provisional

| مورد | جزئیات |
|------|--------|
| مسیرها | `v1/regions` · `v1/plans` · `v1/images` (inventory_paths) |
| وضعیت | path-based + ADR-053 ✅ — تأیید با توکن زنده |

---

۱۴) LightNode — `litenode` ✅ تست زنده کامل (2026-09-23)

| مورد | جزئیات |
|------|--------|
| api_url | `https://openapi.lightnode.com` |
| احراز | هدر `x-open-token` (= `api_token` سرور) |
| لیست API | `GET /region/list` · `/package/list` · `/image/list` |
| قفل محصول | server_type←packageCode |
| CF مشتری | hostname + region(`regionCode\|zoneCode`) + image(imageResourceUUID) |
| create | `POST /instance/create` → `asyncTaskInfo.ecsResourceUUID` |
| پاور / reinstall | start/stop/restart · `reinstallSystem` (async + صف awaiting_power_off) |
| ورود SSH | `root` / `Administrator` (نه hostname) |
| تعویض IP | OpenAPI ندارد |
| مرجع | [apidoc.lightnode.com](https://apidoc.lightnode.com/en) |
| وضعیت | موجودی زنده + ADR-053 + **تست زنده کامل** ✅ |

---

۱۵–۲۳) فاز ۴ اسکلت — ✅ path-based

`trabia` · `natro` · `digiturc` · `teknosos` · `liteserver` · `bluevps` · `m247` · `itldc` · `ipxon`

همه در `PATH_INVENTORY_MODULES` با مسیر پیش‌فرض `v1/regions|plans|images` و override از `inventory_paths` روی سرور. productFields باریک از `AbstractConfigurableCloudModule`. با توکن زنده مسیر واقعی را در `inventory_paths` بگذارید.

---

۲۴) Amazon EC2 — `aws` ✅

| مورد | جزئیات |
|------|--------|
| احراز | access_key + secret_key (SigV4) |
| لیست | DescribeRegions · DescribeInstanceTypes · DescribeImages (کاتالوگ محدود Ubuntu/AL2023) |
| قفل محصول | InstanceType |
| CF | region + AMI |
| وضعیت | موجودی زنده + ADR-053 ✅ |

---

۲۵) Google Compute — `gcp` ✅

| مورد | جزئیات |
|------|--------|
| احراز | api_token یا service_account_json + project_id |
| لیست | zones · machineTypes · images (debian/ubuntu families) |
| قفل محصول | machineType |
| CF | zone + image family |
| وضعیت | موجودی زنده + ADR-053 ✅ |

۲۶) Azure VM — `azure` ✅

| مورد | جزئیات |
|------|--------|
| احراز | tenant/client/secret + subscription_id |
| لیست | locations · vmSizes · کاتالوگ محدود Marketplace |
| قفل محصول | vmSize |
| CF | location + image ref |
| وضعیت | موجودی زنده + ADR-053 ✅ |

---

ماتریس وضعیت سریع

| کلید | عملیات پایه | api_url پیش‌فرض | موجودی API+Select | CF مشتری | پنل بومی تست‌شده |
|------|-------------|-----------------|-------------------|----------|-------------------|
| arvancloud | ✅ | ✅ | ✅ | ✅ | |
| hetzner | ✅ | ✅ | ✅ | ✅ | |
| digitalocean | ✅ | ✅ | ✅ | ✅ | |
| linode | ✅ | ✅ | ✅ | ✅ | ✅ کامل |
| vultr | ✅ | ✅ | ✅ | ✅ | |
| contabo | ✅ | ✅ | ✅ | ✅ | |
| ovh | ✅ | ✅ | ✅ | ✅ | |
| abrasiatech | ✅ | ✅ | ✅ | ✅ provisional | |
| gcore | ✅ | ✅ | ✅ | ✅ | |
| ionos | ✅ | ✅ | ✅ | ✅ | |
| aeza | ✅ | ✅ | ✅ | ✅ | |
| alibaba | ✅ | ✅ | ✅ | ✅ | |
| aruba | ✅ | ✅ | ✅ | ✅ provisional | |
| litenode | ✅ | ✅ openapi.lightnode.com | ✅ | ✅ | ✅ کامل |
| trabia…ipxon | ✅ اسکلت | ✅ | ✅ | ✅ path-based | |
| aws | ✅ | ✅ | ✅ | ✅ | |
| gcp | ✅ | ✅ | ✅ | ✅ | |
| azure | ✅ | ✅ | ✅ | ✅ | |

---

تعریف «کامل» برای یک ماژول VPS ابری

ماژول وقتی کامل است که:

تست اتصال سبز

ادمین بدون تایپ UUID کور، از Select انتخاب کند

مشتری در checkout فقط انتخاب‌های معنادار ببیند

create با همان انتخاب‌ها روی API واقعی موفق شود

پاور (روشن/خاموش/ریبوت) و terminate و changePackage مطابق API همان ارائه‌دهنده کار کند

docs همان ماژول به‌روز باشد

---

گام بعدی پیشنهادی (اجرا)

پس از تأیید این چک‌لیست: شروع با **Hetzner** طبق بخش ۲ (list locations + وایر inventory + CF image/region).

مرتبط: [cloud-vps-provisioning.md](./cloud-vps-provisioning.md) · [vps-provisioning.md](./vps-provisioning.md)