教學：使用 Rayfin CLI 管理開發與生產環境

在這個教學中，你只使用 Rayfin CLI 來為 Fabric 應用程式設定一個雙工作空間的生命週期。 你可以將功能變更部署到開發工作區，驗證它們，然後將同一專案升遷到生產工作區。 此工作流程採用手動推廣步驟，讓您掌控變更何時以及如何進入生產環境。

在這個教學中，你會學到如何：

  • 為同一個專案建立一個開發用和一個生產用的 Fabric 工作區。
  • 將功能變更部署到開發工作區。
  • 可透過 Rayfin CLI 在部署間切換。
  • 將已驗證的專案推廣到生產工作區。

先決條件

  • 一個 Fabric 帳戶
  • Node.js 本地安裝。
  • Rayfin CLI 可透過 npx rayfin 取得。 詳情請參閱 Rayfin CLI 參考文獻。

部署流程概述

  1. 從你本機開始，建立一個 Fabric 應用程式。
  2. 為應用程式建立功能。
  3. 先在本地測試，然後用 npx rayfin up -workspace <dev-workspace>. 部署到開發工作區。
  4. 當程式碼變更經過充分測試後，直接使用 npx rayfin up switch -workspace <prod-workspace>. 重新部署到生產工作區。 switch 允許你在環境與部署環境間切換。

這張截圖顯示開發與生產環境的部署流程。

步驟 1：在 Fabric 中建立開發與生產工作區

在 Fabric portal 手動建立兩個工作區：

  1. 在Fabric入口網站中，建立一個名為 my-app-dev 的工作區。 記錄它的工作區 ID。
  2. 建立第二個工作區，名為 my-app-prod。記錄它的工作區 ID。

步驟 2：登入 Fabric

請用你的 Entra ID 帳號登入，讓 CLI 部署到你的租戶：

npx rayfin login

若要指定特定租戶，請傳遞 --tenant：

npx rayfin login --tenant <tenant id>

隨時驗證已登入帳號：

npx rayfin login status

步驟 3：在本地建立專案

用模板搭建一個新的 Fabric 應用程式。 為專案執行一次這個指令：

npm create @microsoft/rayfin@latest my-app --workspace my-app-dev
cd my-app

如果你是把 Rayfin 加入現有專案，那就直接執行 npx rayfin init 吧。

步驟 4：部署到 Dev 工作區

從你的專案根目錄，將應用程式部署到 my-app-dev：

npx rayfin up --workspace my-app-dev

CLI 會在開發工作區建立 Fabric 應用程式項目，套用你的資料庫結構，並在啟用靜態主機時上傳靜態內容。 部署記錄在 rayfin/.env，開發工作空間成為後續 npx rayfin up 呼叫的主動部署。

若要在不套用變更的情況下預覽部署，請執行：

npx rayfin up --dry-run --verbose

步驟五：針對開發工作區進行開發與迭代

在開發功能開發時，將開發工作區作為目標：

  1. 在本地執行前端開發伺服器：

    npm run dev

  2. 編輯你的程式碼、資料模型或rayfin/rayfin.yml

  3. 必要時，僅套用結構描述變更：

    npx rayfin up db apply

  4. 重新部署完整應用程式給開發者：

    npx rayfin up

重複這個循環直到功能準備好推廣為止。

步驟 6：將專案升級到 prod workspace

當你準備好發佈時，將同一個專案部署到 my-app-prod：

npx rayfin up --workspace my-app-prod

CLI 會在生產工作區建立獨立的 Fabric 應用程式項目，並記錄第二次部署。 Prod 會成為新的作用中部署，而 rayfin/.env 會被重寫為指向它。

步驟 7：在開發與生產部署間切換

用 npx rayfin up switch 來在兩個已錄製的部署間切換，無需重新輸入工作區 ID。

列出此專案記錄的部署：

npx rayfin up list

選擇要切換至的部署：

npx rayfin up switch --list

切換回 dev 以繼續進行功能開發：

npx rayfin up switch my-app-dev

切換到生產環境以進行緊急修正或驗證：

npx rayfin up switch my-app-prod

切換後，純 npx rayfin up 指令會針對新啟用的工作區。

步驟 8：驗證生產部署

部署到生產環境後，確認部署運作正常：

npx rayfin up status

打開 CLI 列印的主機 URL，確認應用程式是否如預期運作。 如果你發現問題：

  1. 切換回 dev：

    npx rayfin up switch my-app-dev

  2. 在開發工作區中重現並修正該問題。

  3. 重新部署到開發區，驗證後切換到生產環境並執行 npx rayfin up 以釋出修正。

  • 將原始碼納入版本控制。 請將其 rayfin/.env 視為當地的現役部署指標，而非真實來源。
  • 使用功能分支處理進行中的工作，並於開發部署驗證後才合併到主分支。
  • 僅在 CLI 明確建議時使用 npx rayfin up --force。 避免例行性地在正式環境中執行。
  • 在進行任何正式環境部署前，請先使用 --dry-run 預覽 CLI 會執行的動作。
  • 在推送到正式環境之前，請先在 rayfin.yml 中確認驗證設定。對於已部署的應用程式，僅支援 Fabric 代理驗證（Entra SSO）。 詳情請參見 將 Fabric 應用程式部署至 Fabric。

相關內容

  • 上次更新時間：