v0.1.7

SSE 事件

最後更新


本頁說明 QemuRun-pve 長時間操作所使用的 Server-Sent Events 格式,以及如何在 Go 中消費。
使用 SSE 的端點:install、start、reboot、set/node。

事件格式


  1. data: {"step":"<階段>","status":"<狀態>","message":"<訊息>"}
  2. event: close
  3. data: {}

欄位說明
step步驟名稱;安裝流程為 <階段> > <步驟>,見 佈建流程
status見下表
message人類可讀訊息;成功步驟附耗時,例如 (3.21s)

status意義
processing步驟進行中,或 qm/初始化腳本的逐行輸出(行首兩個空白)
success步驟完成
info結束提示(start/reboot)
error步驟失敗,流程中止

message 前綴意義
[*]資訊
[+]成功
[-]失敗

注意事項


  • 回應一律為 HTTP 200,成功與否需讀取事件判斷
  • message 以字串拼接輸出、未做 JSON 跳脫;指令輸出含 " 或 \ 時該行可能無法以 JSON 解析,用戶端應略過解析失敗的行
  • 前置檢查失敗(ALLOW_IPS、VM 狀態)時只會收到一行 data: {"message": "..."},沒有 step/status
  • 用戶端中斷連線後,伺服器端流程繼續執行,只是不再推送事件

Go 用戶端範例


  1. package main
  2. import (
  3. "bufio"
  4. "bytes"
  5. "encoding/json"
  6. "fmt"
  7. "log"
  8. "net/http"
  9. "strings"
  10. )
  11. type event struct {
  12. Step string `json:"step"`
  13. Status string `json:"status"`
  14. Message string `json:"message"`
  15. }
  16. func main() {
  17. body, err := json.Marshal(map[string]any{
  18. "os": "ubuntu",
  19. "version": "24.04",
  20. "cpu": 2,
  21. "ram": 4096,
  22. "disk": "32G",
  23. })
  24. if err != nil {
  25. log.Fatal(err)
  26. }
  27. resp, err := http.Post("http://192.168.0.11:8080/api/vm/install", "application/json", bytes.NewReader(body))
  28. if err != nil {
  29. log.Fatal(err)
  30. }
  31. defer resp.Body.Close()
  32. if resp.StatusCode != http.StatusOK {
  33. log.Fatalf("install rejected: %s", resp.Status)
  34. }
  35. failed := false
  36. scanner := bufio.NewScanner(resp.Body)
  37. for scanner.Scan() {
  38. line := scanner.Text()
  39. if line == "event: close" {
  40. // 伺服器端流程結束
  41. break
  42. }
  43. payload, ok := strings.CutPrefix(line, "data: ")
  44. if !ok {
  45. continue
  46. }
  47. var e event
  48. if err := json.Unmarshal([]byte(payload), &e); err != nil {
  49. // 未跳脫的指令輸出,略過
  50. continue
  51. }
  52. fmt.Printf("[%s] %s %s\n", e.Status, e.Step, e.Message)
  53. if e.Status == "error" {
  54. failed = true
  55. }
  56. }
  57. if err := scanner.Err(); err != nil {
  58. log.Fatal(err)
  59. }
  60. if failed {
  61. log.Fatal("install failed")
  62. }
  63. }
EN