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

安裝並部署 UOFX 開發環境。

uofx env install [選項]

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

選項：

• --name <name> - 實例名稱（預設：dev）
• --chart-version <version> - 指定 Helm chart（UOFX） 版本（預設：最新版本）

範例：

# 使用預設名稱
uofx env install

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

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     # 特定指令的日誌

⚠️ 重要限制

實例互斥

由於 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.0