UOFX CLI

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

---

✨ 主要功能

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

---

📋 系統需求

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

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

---

🚀 安裝

bash

npm install -g @uofx/cli





驗證安裝：

bash

uofx --version





---



快速開始



$3

bash

uofx env setup





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



$3

bash

uofx env install --name dev





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





$3

bash

uofx env list credentials --name dev --reveal





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



---



💡 使用範例



$3

bash

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

$3

bash

建立專案 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

$3

bash

查看可用版本

uofx env list charts



安裝特定版本

uofx env install --name dev --chart-version 1.2.0

$3

bash

啟用詳細日誌

uofx config set --log-level debug



查看日誌

uofx logs --level DEBUG --since 10m



過濾特定指令的日誌

uofx logs --command env.install





---



📖 指令參考



$3



####

env setup



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

bash

uofx env setup





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



####

env install



安裝並部署 UOFX 開發環境。

bash

uofx env install [選項]





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



選項：

-

--name - 實例名稱（預設：dev

）

-

--chart-version

 - 指定 Helm chart（UOFX） 版本（預設：最新版本）



範例：

bash

使用預設名稱

uofx env install



指定名稱和版本

uofx env install --name my-project --chart-version 1.2.0





####

env list



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

bash

uofx env list [type] [選項]





類型（type）：

-

instances

 - 列出所有實例（預設）

-

charts

 - 列出相容的 chart（UOFX） 版本

-

credentials - 顯示實例憑證（需要 --name

）



選項：

-

--name

 - 實例名稱（credentials 類型必填）

-

--reveal

 - 顯示完整憑證（搭配 credentials 使用）



範例：

bash

uofx env list                                  # 列出所有實例

uofx env list charts                           # 列出相容的 UOFX 版本

uofx env list credentials --name dev --reveal  # 查看完整憑證





####

env start



啟動指定的 UOFX 實例。

bash

uofx env start --name





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



####

env stop



停止指定的 UOFX 實例。

bash

uofx env stop --name





####

env delete



刪除指定的 UOFX 實例。

bash

uofx env delete --name  [選項]





選項：

-

-f, --force

 - 跳過確認提示



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

wsl --unregister

 指令。



---



$3



####

config list



列出所有設定值。

bash

uofx config list [選項]





####

config set



設定配置值。

bash

uofx config set [選項]





選項：

-

--log-level - 日誌等級（debug、info、error

）

-

--acr.name

 - ACR 名稱

-

--acr.account

 - ACR 帳號

-

--acr.password

 - ACR 密碼



範例：

bash

設定日誌等級

uofx config set --log-level debug



設定 ACR 連線資訊

uofx config set --acr.name myregistry --acr.account user --acr.password secret





---



$3



查看和過濾 CLI 操作日誌。

bash

uofx logs [選項]





選項：

-

--lines - 顯示行數（預設：50

）

-

--level - 過濾日誌等級（DEBUG、INFO、ERROR

）

-

--since - 時間範圍（例如：1h、2d、30m

）

-

--correlation

 - 依關聯 ID 過濾

-

--command - 依指令過濾（例如：env.install

）

-

--command-group - 依指令群組過濾（例如：env

）



範例：

bash

uofx logs                           # 查看最近日誌

uofx logs --level ERROR             # 只看錯誤

uofx logs --since 1h                # 過去一小時的日誌

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





---



⚠️ 重要限制



$3



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



- ⚠️ 同一時間只能有一個實例處於「執行中」狀態

- ⚠️ 以下連接埠會被佔用，請確保沒有其他服務使用



| 服務 | 連接埠 |

|------|--------|

| 前台網站 (HTTP) | 80 |

| 前台網站 (HTTPS) | 443 |

| 後台管理 (HTTP) | 16888 |

| 後台管理 (HTTPS) | 16890 |

| 手機入口 | 9000 |

| SQL Server | 30022 |



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



$3



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



解決方式：停用 localhost 轉發



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



步驟：



1. 在 Windows 使用者目錄建立

.wslconfig

 檔案：

powershell

   notepad $env:USERPROFILE\.wslconfig





2. 加入以下內容：

ini

   [wsl2]

   localhostForwarding=false





3. 重啟 WSL：

powershell

   wsl --shutdown





4. 重新啟動 UOFX 實例：

bash

   uofx env start --name dev





使用 WSL IP 存取：



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

bash

查看實例資訊（包含 IP）

uofx env list



輸出範例：

NAME  STATUS   VERSION  ADMIN URL              SQL SERVER

dev   Running        2  http://[IP]:16888      [IP],30022





注意事項：

- ⚠️ 無法再使用

localhost 或 127.0.0.1

 存取



---



🔧 常見問題



$3



問題：執行

uofx env setup

 顯示 Runtime 未安裝



解決方案：

1. 以系統管理員身份開啟 PowerShell

2. 執行

uofx env setup



3. 依照提示完成 WSL 安裝

4. 重新啟動電腦



$3



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



解決方案：

- 關閉不必要的應用程式

- 確保至少有 16 GB 可用記憶體



$3



問題：

uofx env start

 執行失敗



解決方案：

bash

1. 檢查是否有其他實例運行

uofx env list



2. 停止衝突的實例

uofx env stop --name <其他實例>



3. 查看錯誤日誌

uofx logs --level ERROR --since 5m





$3



問題：安裝意外中斷



解決方案：

bash

刪除失敗的實例

uofx env delete --name <實例名稱> --force



重新安裝

uofx env install --name <實例名稱>

$3

bash

啟用除錯模式

uofx config set --log-level debug



查看詳細日誌

uofx logs --since 1h





---



📚 運作原理



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

mermaid

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_

UOFX CLI

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

---

✨ 主要功能

📋 系統需求

🚀 安裝

bash

npm install -g @uofx/cli





驗證安裝：

bash

uofx --version





---



快速開始



$3

bash

uofx env setup





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



$3

bash

uofx env install --name dev





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





$3

bash

uofx env list credentials --name dev --reveal





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



---



💡 使用範例



$3

bash

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

$3

bash

建立專案 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

$3

bash

查看可用版本

uofx env list charts



安裝特定版本

uofx env install --name dev --chart-version 1.2.0

$3

bash

啟用詳細日誌

uofx config set --log-level debug



查看日誌

uofx logs --level DEBUG --since 10m



過濾特定指令的日誌

uofx logs --command env.install





---



📖 指令參考



$3



####

env setup



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

bash

uofx env setup





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



####

env install



安裝並部署 UOFX 開發環境。

bash

uofx env install [選項]





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



選項：

-

--name - 實例名稱（預設：dev

）

-

--chart-version

 - 指定 Helm chart（UOFX） 版本（預設：最新版本）



範例：

bash

使用預設名稱

uofx env install



指定名稱和版本

uofx env install --name my-project --chart-version 1.2.0





####

env list



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

bash

uofx env list [type] [選項]





類型（type）：

-

instances

 - 列出所有實例（預設）

-

charts

 - 列出相容的 chart（UOFX） 版本

-

credentials - 顯示實例憑證（需要 --name

）



選項：

-

--name

 - 實例名稱（credentials 類型必填）

-

--reveal

 - 顯示完整憑證（搭配 credentials 使用）



範例：

bash

uofx env list                                  # 列出所有實例

uofx env list charts                           # 列出相容的 UOFX 版本

uofx env list credentials --name dev --reveal  # 查看完整憑證





####

env start



啟動指定的 UOFX 實例。

bash

uofx env start --name





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



####

env stop



停止指定的 UOFX 實例。

bash

uofx env stop --name





####

env delete



刪除指定的 UOFX 實例。

bash

uofx env delete --name  [選項]





選項：

-

-f, --force

 - 跳過確認提示



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

wsl --unregister

 指令。



---



$3



####

config list



列出所有設定值。

bash

uofx config list [選項]





####

config set



設定配置值。

bash

uofx config set [選項]





選項：

-

--log-level - 日誌等級（debug、info、error

）

-

--acr.name

 - ACR 名稱

-

--acr.account

 - ACR 帳號

-

--acr.password

 - ACR 密碼



範例：

bash

設定日誌等級

uofx config set --log-level debug



設定 ACR 連線資訊

uofx config set --acr.name myregistry --acr.account user --acr.password secret





---



$3



查看和過濾 CLI 操作日誌。

bash

uofx logs [選項]





選項：

-

--lines - 顯示行數（預設：50

）

-

--level - 過濾日誌等級（DEBUG、INFO、ERROR

）

-

--since - 時間範圍（例如：1h、2d、30m

）

-

--correlation

 - 依關聯 ID 過濾

-

--command - 依指令過濾（例如：env.install

）

-

--command-group - 依指令群組過濾（例如：env

）



範例：

bash

uofx logs                           # 查看最近日誌

uofx logs --level ERROR             # 只看錯誤

uofx logs --since 1h                # 過去一小時的日誌

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





---



⚠️ 重要限制



$3



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



- ⚠️ 同一時間只能有一個實例處於「執行中」狀態

- ⚠️ 以下連接埠會被佔用，請確保沒有其他服務使用



| 服務 | 連接埠 |

|------|--------|

| 前台網站 (HTTP) | 80 |

| 前台網站 (HTTPS) | 443 |

| 後台管理 (HTTP) | 16888 |

| 後台管理 (HTTPS) | 16890 |

| 手機入口 | 9000 |

| SQL Server | 30022 |



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



$3



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



解決方式：停用 localhost 轉發



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



步驟：



1. 在 Windows 使用者目錄建立

.wslconfig

 檔案：

powershell

   notepad $env:USERPROFILE\.wslconfig





2. 加入以下內容：

ini

   [wsl2]

   localhostForwarding=false





3. 重啟 WSL：

powershell

   wsl --shutdown





4. 重新啟動 UOFX 實例：

bash

   uofx env start --name dev





使用 WSL IP 存取：



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

bash

查看實例資訊（包含 IP）

uofx env list



輸出範例：

NAME  STATUS   VERSION  ADMIN URL              SQL SERVER

dev   Running        2  http://[IP]:16888      [IP],30022





注意事項：

- ⚠️ 無法再使用

localhost 或 127.0.0.1

 存取



---



🔧 常見問題



$3



問題：執行

uofx env setup

 顯示 Runtime 未安裝



解決方案：

1. 以系統管理員身份開啟 PowerShell

2. 執行

uofx env setup



3. 依照提示完成 WSL 安裝

4. 重新啟動電腦



$3



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



解決方案：

- 關閉不必要的應用程式

- 確保至少有 16 GB 可用記憶體



$3



問題：

uofx env start

 執行失敗



解決方案：

bash

1. 檢查是否有其他實例運行

uofx env list



2. 停止衝突的實例

uofx env stop --name <其他實例>



3. 查看錯誤日誌

uofx logs --level ERROR --since 5m





$3



問題：安裝意外中斷



解決方案：

bash

刪除失敗的實例

uofx env delete --name <實例名稱> --force



重新安裝

uofx env install --name <實例名稱>

$3

bash

啟用除錯模式

uofx config set --log-level debug



查看詳細日誌

uofx logs --since 1h





---



📚 運作原理



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

mermaid

flowchart LR

    A[UOFX CLI] --> B[建立 WSL 實例]

    B --> C[安裝 MicroK8s]

    C --> D[部署 UOFX 服務]

    D --> E[開發環境就緒]

    

    style A fill:#4CAF50

    style E fill:#2196F3

📄 授權

請參閱 LICENSE 檔案

---

_UOFX CLI v1.0.0_