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.
De ce ai nevoie
Secțiune intitulată „De ce ai nevoie”- O cheie API cu scope-ul
migrations:readpentru citire șimigrations:writepentru 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"
1. Adaugă și confirmă sursa
Secțiune intitulată „1. Adaugă și confirmă sursa”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.
2. Creează migrarea
Secțiune intitulată „2. Creează migrarea”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 ceresource_username;plan_id,owner_user_idșioptions(dns_modespe zonă,mail_passwords,ftp) sunt opționale.settingseste ș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,externalsausource_dns),rollback_days(1–30, implicit 14) șiclient_visible.- Răspunsul este migrarea cu valurile și elementele ei. Păstrează
id-ul migrării caMIGRATION_IDși noteazăid-ul fiecărui element (ITEM_IDmai 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).
3. Pornește și urmărește
Secțiune intitulată „3. Pornește și urmărește”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}]}'
statusal migrării:draft,running,paused,completedsaucancelled.pause_reasonspune de ce s-a oprit o migrare (de exemplu după un cont eșuat).stateal unui element trece de lapendingprinanalyzing,analyzed,provisioning,presync,verifyingșireadylacutover,post_verify,completedșifinalized; celelalte suntfailed,paused,skipped,cancelledșirolled_back.stepșiprogressarată pasul curent.gatespune ce poate face un element acum:can_cutover(cucutover_blockercând nu poate),can_rollback,runningșiambers_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).
4. Mută un cont sau revino la sursă
Secțiune intitulată „4. Mută un cont sau revino la sursă”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.
Evenimente
Secțiune intitulată „Evenimente”Nu se trimite niciun eveniment webhook pentru progresul migrării: interoghează migrarea ca la pasul 3. Lista evenimentelor arată ce se trimite.
Legături utile
Secțiune intitulată „Legături utile”- Migrare de pe cPanel/WHM: regulile, modurile de acces și cum se mută un cont.
- Referința API: fiecare operație
migration, cu câmpurile ei. - Convențiile API: erori, idempotență și ETag-uri.
- Autentificare și chei API: scope-uri și folosirea cheilor.