用 REST API 和 curl 管理 VPS：狀態、電源、重灌、續約

透過 API 訂購伺服器只需一個請求，詳見用 4 次 API 呼叫訂購 VPS。本頁講的是之後的一切：平時在控制台裡點來點去的日常操作，寫成可以貼進腳本的 curl 指令。

下面每條指令都在發布前對我們的 API 實際執行過，回應是傳回結果的精簡版。

準備

兩個變數讓指令保持簡短：

export API=https://api.eqvps.com/api/v1/eqvps
export EQVPS_TOKEN='paste-your-token-here'

權杖來自 POST /auth/register，或控制台中的 Settings → API tokens。如果別人也用這台機器，別把它留在 shell 歷史中；用 export EQVPS_TOKEN=$(cat ~/.eqvps_token) 從檔案讀取即可。

找到您的伺服器

curl -s $API/services -H "Authorization: Bearer $EQVPS_TOKEN"

每筆記錄都有一個類似 47HZ7YF 的 id。這是其他所有呼叫都要用的服務代碼。接著是一台伺服器的完整資訊：

curl -s $API/services/47HZ7YF -H "Authorization: Bearer $EQVPS_TOKEN"

{ "data": {
    "id": "47HZ7YF", "status": "active", "queued": false,
    "product": { "slug": "nano", "name": "Nano" },
    "specs": { "vcpu": 2, "memory_mb": 1024, "disk_gb": 15 },
    "hostname": "agent-box",
    "vm": { "state": "running", "uptime": 5340 },
    "access": { "method": "ssh", "host": "203.0.113.10", "port": 21521, "user": "root", "nat": true, ... } } }

access 告訴您如何登入。在附獨立 IPv4 的方案上連接埠是 22；在 NAT 方案上是您的專屬轉發連接埠。這個呼叫只讀取，迴圈輪詢是安全的。

如果下單時沒有提供 SSH 金鑰，root 密碼只顯示一次：

curl -s "$API/services/47HZ7YF?reveal=1" -H "Authorization: Bearer $EQVPS_TOKEN"

伺服器還在開機時，回應為 password_pending，一次性顯示不會被消耗。等半分鐘再問一次。

電源：start、stop、reboot

curl -s -X POST $API/services/47HZ7YF/power \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"action": "reboot"}'

action 為 start、stop 或 reboot。尚未啟用的伺服器（仍在建立，或因欠費被暫停）會傳回 409 Service is not active。這不是您腳本的錯誤。先檢查 status。

監控數據

curl -s "$API/services/47HZ7YF/metrics?timeframe=day" -H "Authorization: Bearer $EQVPS_TOKEN"

以時間序列提供 CPU、記憶體、網路和磁碟數據。timeframe 為 hour（預設）、day、week 或 month。適合用 cron 工作在磁碟持續成長時提醒您。目前計費週期的流量計數見檢查速度和流量。

修改伺服器名稱

curl -s -X POST $API/services/47HZ7YF/hostname \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"hostname": "web-01"}'

新名稱由客體代理程式在執行中的系統內套用，Linux 上無需重新開機。如果伺服器已停止，或您移除了 qemu-guest-agent，呼叫會傳回 409 agent_unavailable，什麼也不會改變。

重灌系統

這會清空磁碟。API 要求您在 confirm 中輸入伺服器目前的主機名稱，這樣服務 id 寫錯的腳本就無法誤刪另一台機器：

curl -s -X POST $API/services/47HZ7YF/reinstall \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"os_id": 4, "confirm": "web-01"}'

os_id 來自 GET /products 中您方案的 available_os 清單，或伺服器本身的詳細資料。重灌在背景進行；輪詢 GET /services/{id}，直到 status 再次變為 active。

續約和餘額

伺服器每月從預付餘額自動續約。查看這台伺服器更長期限的價格：

curl -s $API/services/47HZ7YF/renew-options -H "Authorization: Bearer $EQVPS_TOKEN"

一次呼叫預付例如三個月：

curl -s -X POST $API/services/47HZ7YF/renew \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"months": 3}'

months 為 1、3、6 或 12，12 依含折扣的年繳價格計費。回應會顯示 paid_from_balance: true 並給出新的到期日。如果餘額不夠，什麼都不會扣：您會收到 paid_from_balance: false 和這張帳單的 checkout_url。儲值後，POST $API/invoices/{invoice_id}/pay 會用餘額支付這張帳單；如果仍然不夠，它會傳回同樣的 checkout_url，不扣任何費用。查看餘額和儲值：

curl -s $API/balance -H "Authorization: Bearer $EQVPS_TOKEN"

curl -s -X POST $API/balance/topup \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"amount": 25}'

儲值回應中包含 checkout_url。這是加密貨幣付款：Base、Ethereum 或 Polygon 上的 USDT、USDC 或 ETH。付款在鏈上確認後餘額入帳。付款是腳本唯一無法替您完成的步驟，除非它持有錢包。

也可以用 Monero，但只能作為人工核對的餘額儲值：您傳送 XMR、提交交易 id，我們核實後入帳。參見用 Monero 付款。

取消，以及反悔

安全的取消方式會讓伺服器一直運作到已付週期結束，只是不再續約：

curl -s -X POST $API/services/47HZ7YF/cancel \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"type": "end_of_period", "reason": "moving the project elsewhere"}'

reason 必填，寫幾個字就好。在日期之前改變主意了？

curl -s -X POST $API/services/47HZ7YF/cancel/undo -H "Authorization: Bearer $EQVPS_TOKEN"

還有 "type": "immediate"。它會立即刪除伺服器及資料，需要 "confirm": "<hostname>"，且無法撤銷。除非您真的這麼想，請使用 end_of_period。

讓權杖保持有效

新權杖預設有效一年。每個已驗證的回應都帶有 X-Token-Expires-At 標頭，腳本可以提前察覺。把權杖換成新的：

curl -s -X POST $API/auth/token/refresh -H "Authorization: Bearer $EQVPS_TOKEN"

舊權杖會立即失效，所以在做任何其他事之前先儲存新權杖。

值得處理的錯誤

想用 AI 用戶端而不是腳本來做？同樣的操作也有 MCP 工具——參見 AI 代理如何透過 MCP 自行維護 VPS 和 API 參考。還沒有伺服器？選擇方案。