Sari la conținut

Rulează o migrare cPanel

Adaugă o sursă cPanel, planifică o migrare în valuri, pornește-o, urmărește fiecare cont și mută-l sau revino la sursă prin API.

Ghidul arată cum rulezi prin API o migrare cPanel/WHM: conectezi o sursă, creezi o migrare, o pornești, o urmărești și muți fiecare cont. Parcurge aceiași pași ca Migration Center din panou. Migrările sunt disponibile administratorilor și revânzătorilor; un revânzător vede și migrează doar conturile lui.

  • O cheie API cu scope-ul migrations:read pentru citire și migrations:write pentru orice modificare (scope-uri).
  • Id-ul serverului de destinație (GET /api/v1/servers), un server al cărui agent are motorul de migrare.
  • Acces la sursă: un token API WHM, SSH ca root (parolă sau cheie) sau o arhivă cpmove. Credențialele sunt păstrate criptat, nu sunt întoarse niciodată de API și sunt distruse când se încheie migrările care folosesc sursa.
  • Un id de plan pentru conturile pe care le creezi (GET /api/v1/plans). Fără el se folosește planul implicit al organizației.
export PLUSPANEL_URL="https://panel.example.com"
export PLUSPANEL_API_KEY="ppk_…"
export SERVER_ID="3a3a3a3a-1111-4222-8333-444455556666"

POST /api/v1/migration-sources adaugă o sursă. Pentru o sursă WHM dai gazda, tokenul API și serverul al cărui agent o sondează (probe_server_id, de obicei destinația). kind este whm, ssh sau archive; portul este implicit 2087 pentru WHM și 22 pentru SSH, iar utilizatorul este implicit root.

curl -fsS -X POST "$PLUSPANEL_URL/api/v1/migration-sources" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"kind": "whm", "name": "old-cpanel", "host": "whm.old-host.example", "token": "'"$WHM_TOKEN"'", "probe_server_id": "'"$SERVER_ID"'"}'

Prima sondare doar observă identitatea sursei, deci răspunsul are "status": "awaiting_confirmation" și un fingerprint (al cheii de gazdă SSH sau al certificatului WHM). Păstrează id-ul sursei ca SOURCE_ID. Compară amprenta cu cea reală, apoi confirmă exact valoarea aceea:

curl -fsS -X POST "$PLUSPANEL_URL/api/v1/migration-sources/$SOURCE_ID/confirm" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
  -d '{"fingerprint": "SHA256:…"}'

Pornește sondarea completă. Citește GET /api/v1/migration-sources/{id} până când status este ready; accounts listează atunci conturile cPanel (user, domain, disk_bytes, suspended). Starea error vine cu un error_code; POST …/probe reîncearcă.

Pentru o sursă de tip arhivă, dai archive_url (un link HTTPS) sau încarci mai întâi fișierul: POST /api/v1/migration-sources/upload cu {"filename": "…", "size": …} răspunde cu o adresă temporară de încărcare (valabilă o oră); trimite fișierul la ea cu PUT, cu antetele din headers ale răspunsului, apoi creează sursa cu kind: "archive" și cu object din răspuns ca archive_object.

POST /api/v1/migrations creează o ciornă: o sursă, un server de destinație și conturile, în valuri ordonate.

curl -fsS -X POST "$PLUSPANEL_URL/api/v1/migrations" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Autumn move",
    "source_id": "'"$SOURCE_ID"'",
    "server_id": "'"$SERVER_ID"'",
    "waves": [
      {"name": "Pilot", "items": [{"source_username": "shopuser"}]},
      {"name": "The rest", "items": [{"source_username": "blog"}, {"source_username": "docs"}]}
    ],
    "settings": {"parallelism": 2, "rollback_days": 14, "dns_mode_default": "external"}
  }'
  • name, source_id, server_id și cel puțin un val sunt obligatorii. Fiecare element cere source_username; plan_id, owner_user_id și options (dns_modes pe zonă, mail_passwords, ftp) sunt opționale.
  • settings este și el opțional. Cele care merită știute: parallelism (1–10), auto_pause (oprește la primul cont eșuat), auto_cutover, windows (când pot rula pașii grei), dns_mode_default (pluspanel_ns, external sau source_dns), rollback_days (1–30, implicit 14) și client_visible.
  • Răspunsul este migrarea cu valurile și elementele ei. Păstrează id-ul migrării ca MIGRATION_ID și notează id-ul fiecărui element (ITEM_ID mai jos).

PATCH /api/v1/migrations/{id} schimbă setările și valurile, inclusiv în timp ce migrarea rulează (se mai pot muta doar elementele care nu au pornit); o migrare încheiată sau anulată îl refuză. O ciornă poate fi și ștearsă. Ca să vezi ce s-ar muta înainte să se copieze ceva, analizează un element cu POST /api/v1/migration-items/{id}/analyze și citește GET /api/v1/migration-items/{id}/preflight (format este md, pdf sau json).

curl -fsS -X POST "$PLUSPANEL_URL/api/v1/migrations/$MIGRATION_ID/start" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Idempotency-Key: $(uuidgen)"

PlusPanel analizează, pregătește, copiază și verifică apoi conturile val cu val. Urmărește-o cu GET /api/v1/migrations/{id}:

curl -fsS "$PLUSPANEL_URL/api/v1/migrations/$MIGRATION_ID" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" \
  | jq '{status, current_wave, pause_reason, items: [.waves[].items[] | {id, source_username, state, step, gate}]}'
  • status al migrării: draft, running, paused, completed sau cancelled. pause_reason spune de ce s-a oprit o migrare (de exemplu după un cont eșuat).
  • state al unui element trece de la pending prin analyzing, analyzed, provisioning, presync, verifying și ready la cutover, post_verify, completed și finalized; celelalte sunt failed, paused, skipped, cancelled și rolled_back. step și progress arată pasul curent.
  • gate spune ce poate face un element acum: can_cutover (cu cutover_blocker când nu poate), can_rollback, running și ambers_acked.

GET /api/v1/migration-items/{id} adaugă planul de pre-verificare, ce a creat pregătirea contului, starea DNS pe domeniu și numele de gazdă de previzualizare; …/checks listează verificările, iar …/steps cronologia. pause, resume și cancel pe /api/v1/migrations/{id} controlează întreaga migrare. GET /api/v1/migrations/{id}/report dă raportul agregat (format este md, pdf sau json).

Când un element este ready și gate.can_cutover este true, mută-l:

curl -fsS -X POST "$PLUSPANEL_URL/api/v1/migration-items/$ITEM_ID/cutover" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Idempotency-Key: $(uuidgen)"

Mutarea face o ultimă sincronizare, schimbă DNS-ul fiecărui domeniu după modul DNS al elementului, apoi verifică rezultatul. O verificare roșie blochează mutarea. Verificările galbene cer mai întâi POST …/ack-ambers (un reason opțional se păstrează în jurnalul de audit). Citește GET …/dns pentru instrucțiunile pe care trebuie să le aplici tu în modul external și folosește POST …/dns/check pentru a verifica propagarea acum.

În fereastra de revenire, POST /api/v1/migration-items/{id}/rollback readuce DNS-ul la sursă; contul din destinație rămâne. Alte acțiuni pe element: presync (o nouă sincronizare incrementală), verify, retry (după o eroare) și skip.

Status Cod Ce înseamnă
401 invalid_api_key Cheia lipsește, a expirat sau a fost revocată.
403 Cheia nu are scope migrations, sau utilizatorul nu poate migra acest cont.
404 Sursa, migrarea sau elementul nu există ori nu este vizibil pentru tine.
409 migration_unsupported_agent Agentul serverului nu are motor de migrare.
409 migration_source_not_ready Sursa nu este încă ready.
409 migration_state Acțiunea nu se potrivește cu starea curentă (de exemplu pornirea de două ori).
409 migration_running Un element sau o migrare în desfășurare blochează schimbarea sau ștergerea.
409 migration_red_checks, migration_ambers_unacknowledged Mutarea este blocată de verificări roșii sau de verificări galbene pe care nimeni nu le-a confirmat.
409 migration_verify_stale Verificarea este depășită; verifică din nou înainte de mutare.
409 migration_rollback_expired Fereastra de revenire a elementului a expirat.
422 migration_invalid_source, migration_fingerprint_mismatch Gazda sau credențialele sursei nu sunt acceptate, ori amprenta diferă de cea observată.
503 migration_vault_unavailable, migration_uploads_unavailable Credențialele sau încărcarea arhivelor nu sunt disponibile pe această instalare.

Erorile sunt problem details: decide după code.

Nu se trimite niciun eveniment webhook pentru progresul migrării: interoghează migrarea ca la pasul 3. Lista evenimentelor arată ce se trimite.