UOFX CLI

🚀 在 Windows WSL 環境中快速部署和管理 UOFX 開發環境的命令列工具

✨ 主要功能

• ✅ 環境檢查與自動安裝 - 驗證系統需求，可自動安裝 WSL 環境
• 🐳 容器化隔離 - 使用 WSL + Kubernetes 建立完全隔離的開發環境
• 🎯 多實例管理 - 建立多個獨立環境，輕鬆切換專案
• 📊 即時狀態監控 - 查看實例運行狀態與資源使用
• 🔐 憑證管理 - 安全儲存並快速取得登入資訊
• 📝 詳細日誌 - 完整的操作記錄，協助除錯

📋 系統需求

| 項目 | 需求 | |------|------| | 作業系統 | Windows 10/11 | | Node.js | 18.20.0 或更高版本 | | 記憶體 | 最低 16 GB | | 網路 | 需要連線至容器倉庫 |

注意：WSL 可透過 CLI 自動安裝（需系統管理員權限）

🚀 安裝

npm install -g @uofx/cli

驗證安裝：

uofx --version

快速開始

1️⃣ 環境檢查

uofx env setup

如果 WSL 未安裝，請以系統管理員身份執行此指令進行自動安裝

2️⃣ 安裝開發環境

uofx env install --name dev

⏱️ 注意：安裝過程需要下載容器映像檔，通常需要 15 分鐘以上，實際時間依網路速度而定。

3️⃣ 取得連線資訊

uofx env list credentials --name dev --reveal

完成！現在你可以使用顯示的帳號密碼登入開發環境了。

💡 使用範例

查看所有實例

uofx env list

輸出示例：

NAME  STATUS   VERSION  CHART VERSION  ADMIN URL                    SQL SERVER
───────────────────────────────────────────────────────────────────────────────────
dev   Running        2  2.100.002      http://[ip]:16888            [ip],30022
test  Stopped        2  2.100.001      

多專案環境管理

# 建立專案 A 的環境
uofx env install --name project-a

# 建立專案 B 的環境
uofx env install --name project-b

# 切換到專案 A（會自動停止其他運行中的實例）
uofx env start --name project-a

# 停止實例
uofx env stop --name project-a

# 不再需要時刪除
uofx env delete --name project-a

指定版本安裝

# 查看可用版本
uofx env list charts

# 安裝特定版本
uofx env install --name dev --chart-version 1.2.0

除錯模式

# 啟用詳細日誌
uofx config set --log-level debug

# 查看日誌
uofx logs --level DEBUG --since 10m

# 過濾特定指令的日誌
uofx logs --command env.install

📖 指令參考

環境管理 (env)

env setup

檢查並驗證系統環境，若 WSL 未安裝可自動進行安裝。

uofx env setup

注意：若需要安裝 WSL，必須以系統管理員身份執行。

env install（別名 i）

安裝並部署 UOFX 開發環境。

uofx env install [選項]
uofx env i [選項]

⏱️ 安裝時間：需要下載容器映像檔，通常需要 15 分鐘以上，實際時間依網路速度而定。

選項：

• --name <name> - 實例名稱（預設：dev）
• --chart-version <version> - 指定 Helm chart（UOFX） 版本（預設：最新版本）
• --no-northwind - 跳過 Northwind 範例資料庫安裝

範例：

# 使用預設名稱
uofx env install

# 指定名稱和版本
uofx env install --name my-project --chart-version 1.2.0

# 不安裝 Northwind 範例資料庫
uofx env install --no-northwind

env list

顯示實例、憑證或相容版本資訊。

uofx env list [type] [選項]

類型（type）：

• instances - 列出所有實例（預設）
• charts - 列出相容的 chart（UOFX） 版本
• credentials - 顯示實例憑證（需要 --name）

選項：

• --name <name> - 實例名稱（credentials 類型必填）
• --reveal - 顯示完整憑證（搭配 credentials 使用）

範例：

uofx env list                                  # 列出所有實例
uofx env list charts                           # 列出相容的 UOFX 版本
uofx env list credentials --name dev --reveal  # 查看完整憑證

env start

啟動指定的 UOFX 實例。

uofx env start --name <name>

提示：若有其他實例正在運行，CLI 會詢問是否停止該實例。

env stop

停止指定的 UOFX 實例。

uofx env stop --name <name>

env delete

刪除指定的 UOFX 實例。

uofx env delete --name <name> [選項]

選項：

• -f, --force - 跳過確認提示

⚠️ 警告：請務必使用此指令來刪除實例，請勿直接使用 wsl --unregister 指令。

設定管理 (config)

config list

列出所有設定值。

uofx config list

config set

設定配置值。

uofx config set [選項]

選項：

• --log-level <level> - 日誌等級（debug、info、error）
• --acr.name <name> - ACR 名稱
• --acr.account <account> - ACR 帳號
• --acr.password <password> - ACR 密碼

範例：

# 設定日誌等級
uofx config set --log-level debug

# 設定 ACR 連線資訊
uofx config set --acr.name myregistry --acr.account user --acr.password secret

日誌查看 (logs)

查看和過濾 CLI 操作日誌。

uofx logs [選項]

選項：

• --lines <number> - 顯示行數（預設：50）
• --level <level> - 過濾日誌等級（DEBUG、INFO、ERROR）
• --since <range> - 時間範圍（例如：1h、2d、30m）
• --correlation <id> - 依關聯 ID 過濾
• --command <command> - 依指令過濾（例如：env.install）
• --command-group <group> - 依指令群組過濾（例如：env）

範例：

uofx logs                           # 查看最近日誌
uofx logs --level ERROR             # 只看錯誤
uofx logs --since 1h                # 過去一小時的日誌
uofx logs --command env.install     # 特定指令的日誌

開發工具 (dev)

dev template install（別名 i）

從 GitHub Release 或自訂 URL 安裝 Plugin 專案範本。template 可縮寫為 t。

uofx dev template install [選項]
uofx dev template i [選項]
uofx dev t i [選項]

選項：

• --url <url> - 自訂範本 URL（ZIP 檔案）
• --name <name> - 自訂範本名稱
• --no-sample - 安裝不含範例程式碼的基礎範本（使用 UOFX-Plugin-Base）

範例：

uofx dev template install
uofx dev template install --no-sample
uofx dev template install --url https://example.com/template.zip --name my-template

dev template list

列出已安裝的範本。

uofx dev template list
uofx dev t list

dev template delete

刪除指定的範本。

uofx dev template delete --name <name>
uofx dev t delete --name <name>

選項：

• --name <name> - 要刪除的範本名稱（必填）

dev project generate（別名 g）

從已安裝的範本建立新的 Plugin 專案。project 可縮寫為 p。

uofx dev project generate [選項]
uofx dev project g [選項]
uofx dev p g [選項]

選項：

• --template <template> - 指定使用的已安裝範本名稱（必填）
• --output <path> - 目標目錄（預設：當前目錄）
• --skip-install - 跳過 npm install（適用於離線環境或需要手動安裝依賴的情境）
• -f, --force - 跳過非空目錄檢查

範例：

uofx dev project generate --template v2025R4.123.2
uofx dev project g --template v2025R4.123.2 --output ./dest
uofx dev project g --template v2025R4.123.2 --skip-install
uofx dev project g --template v2025R4.123.2 --force

dev component generate（別名 g）

使用 @uofx/plugin-schematics 產生 Plugin 元件。component 可縮寫為 c。

uofx dev component generate [選項]
uofx dev component g [選項]
uofx dev c g [選項]

注意：此指令需搭配 v2026R1.128.1 或更新版本的樣板使用。請先透過 uofx dev template install 安裝符合版本需求的樣板，並使用 uofx dev project generate 建立專案。

元件類型：

| 類型 | 說明 | |------|------| | field | 自訂表單欄位 | | mobile-field | 行動端表單欄位 | | admin-panel | 管理端面板元件 | | user-panel | 使用者端面板元件 | | mobile-panel | 行動端面板元件 | | admin-page | 管理端頁面 | | user-page | 使用者端頁面 | | mobile-page | 行動端頁面 |

必填選項：

• --type <type> - 元件類型（見上表）
• --name <name> - 元件名稱

通用選項：

• --display-name <name> - UI 顯示名稱（預設：<name> 的 PascalCase）
• -f, --force - 跳過 dry-run 預覽與確認提示

Field / Panel 專用選項：（field、mobile-field、admin-panel、user-panel、mobile-panel）

• --code <code> - 元件代碼，camelCase 格式（預設：<name> 的 camelCase）

Field 專用選項：

• --group <group> - 欄位群組代碼（預設：group1）
• --no-design - 跳過 design 子元件
• --no-print - 跳過 print 子元件
• --no-view - 跳過 view 子元件

Page 專用選項：

• --layout <layout> - 頁面佈局類型（預設：basic）
  • admin-page：basic、container、sider、tab
  • user-page：basic、full、tab
  • mobile-page：basic、tab
• --func-id <id> - 授權功能 ID

範例：

uofx dev component g --type field --name hello-world
uofx dev component g --type mobile-field --name customer-info
uofx dev component g --type field --name hello-world --no-print
uofx dev component g --type admin-panel --name dashboard --display-name="Dashboard Panel"
uofx dev component g --type admin-page --name settings --layout container
uofx dev component g --type user-page --name profile --layout full
uofx dev component g --type mobile-page --name home --layout tab

dev project publish

發佈 Plugin 專案（版本更新 + dotnet publish + 整理輸出）。project 可縮寫為 p，publish 可縮寫為 p。

uofx dev project publish [選項]
uofx dev p publish [選項]
uofx dev p p [選項]

必填選項：

• --service-version <version> - Plugin 版本號（例如 1.0）
• --min-uofx-version <version> - 最低 UOFX 版本（例如 2.89.0）
• --service-name <name> - 服務名稱（例如 Ede.Sample）

選填選項：

• --output <path> - 輸出目錄（預設：../wwwroot）
• -f, --force - 跳過確認提示，並覆蓋已存在的輸出目錄與版本項目

範例：

uofx dev project publish --service-version=1.0 --min-uofx-version=2.89.0 --service-name=Ede.Sample
uofx dev project publish --service-version=1.1 --min-uofx-version=2.89.0 --service-name=Ede.Sample --output=./publish
uofx dev project publish --service-version=1.0 --min-uofx-version=2.89.0 --service-name=Ede.Sample --force

⚠️ 重要限制

實例互斥

由於 WSL 架構限制，所有 WSL 實例共用同一個 IP 位址，因此：

• ⚠️ 同一時間只能有一個實例處於「執行中」狀態
• ⚠️ 以下連接埠會被佔用，請確保沒有其他服務使用

| 服務 | 連接埠 | |------|--------| | 前台網站 (HTTP) | 80 | | 前台網站 (HTTPS) | 443 | | 後台管理 (HTTP) | 16888 | | 後台管理 (HTTPS) | 16890 | | 手機入口 | 9000 | | SQL Server | 30022 |

💡 提示：當啟動實例時，CLI 會自動檢測衝突並詢問是否停止其他實例

與本機服務的連接埠衝突

如果您的 Windows 主機上有其他服務正在使用相同連接埠（如 IIS、Apache、Nginx 等），將會發生衝突。

解決方式：停用 localhost 轉發

如果您需要同時運行本機服務和 UOFX，可以停用 WSL 的 localhost 轉發功能。

步驟：

1. 在 Windows 使用者目錄建立 .wslconfig 檔案：

   notepad $env:USERPROFILE\.wslconfig

2. 加入以下內容：

   [wsl2]
   localhostForwarding=false

3. 重啟 WSL：

   wsl --shutdown

4. 重新啟動 UOFX 實例：

   uofx env start --name dev

使用 WSL IP 存取：

停用 localhost 轉發後，您需要使用 WSL 的實際 IP 位址來存取服務：

# 查看實例資訊（包含 IP）
uofx env list

# 輸出範例：
# NAME  STATUS   VERSION  ADMIN URL              SQL SERVER
# dev   Running        2  http://[IP]:16888      [IP],30022

注意事項：

• ⚠️ 無法再使用 localhost 或 127.0.0.1 存取

🔧 常見問題

WSL 未安裝

問題：執行 uofx env setup 顯示 Runtime 未安裝

解決方案：

1. 以系統管理員身份開啟 PowerShell
2. 執行 uofx env setup
3. 依照提示完成 WSL 安裝
4. 重新啟動電腦

記憶體不足

問題：環境檢查顯示記憶體不足

解決方案：

• 關閉不必要的應用程式
• 確保至少有 16 GB 可用記憶體

實例無法啟動

問題：uofx env start 執行失敗

解決方案：

# 1. 檢查是否有其他實例運行
uofx env list

# 2. 停止衝突的實例
uofx env stop --name <其他實例>

# 3. 查看錯誤日誌
uofx logs --level ERROR --since 5m

安裝過程中斷

問題：安裝意外中斷

解決方案：

# 刪除失敗的實例
uofx env delete --name <實例名稱> --force

# 重新安裝
uofx env install --name <實例名稱>

取得詳細協助

# 啟用除錯模式
uofx config set --log-level debug

# 查看詳細日誌
uofx logs --since 1h

📚 運作原理

本工具採用「容器化」概念來隔離開發環境：

flowchart LR
    A[UOFX CLI] --> B[建立 WSL 實例]
    B --> C[安裝 MicroK8s]
    C --> D[部署 UOFX 服務]
    D --> E[開發環境就緒]
    
    style A fill:#4CAF50
    style E fill:#2196F3

兩個主要步驟：

1. 建立 WSL 實例 - 在 Windows 上建立獨立的 Ubuntu 環境（類似輕量級虛擬機）
2. 部署 UOFX 服務 - 在 WSL 內安裝 Kubernetes 並部署所有微服務

優點：

• ✅ 完全隔離，不影響本機環境
• ✅ 可建立多個獨立實例
• ✅ 刪除實例即可完全清除

📄 授權

請參閱 LICENSE 檔案

UOFX CLI v1.0.2