OrpheAgent 容器版：一鍵安裝指南

本指南說明如何使用一鍵安裝腳本部署 OrpheAgent 容器、透過 OrpheLink 供裝設備，以及重建映像檔與保留執行資料。

步驟一：下載最新版本

1. 將檔案下載至您的設備：從 O'Prueba 官網下載。

2. 解壓縮下載的 .tar.gz 檔案：

tar -zxvf orphe-agent-1.1.3-container.tar.gz

步驟二：在 OrpheLink 產生供裝金鑰（Provision Key）

1. 登入 OrpheLink 儀表板並導覽至 Provision 頁面。

2. 為設備產生並複製一組新的 Provision Key。

步驟三：使用一鍵安裝腳本進行安裝

1. 確保已安裝 curl。通常在官方儲存庫中可取得，並可透過以下指令安裝：

sudo apt install curl

2. 帶入適當的參數來執行腳本：

sudo bash install.sh ARCH DOCKER_USERNAME DOCKER_PASSWORD PROVISION_KEY

• 將 ARCH 替換為您的系統架構類型 (例如：amd64、arm64、armhf)。
• 將 DOCKER_USERNAME 與 DOCKER_PASSWORD 替換為您的 Docker Hub 憑證。
• 將 PROVISION_KEY 替換為您在 OrpheLink Provision 頁面產生的金鑰。
• 腳本將會自動在您的 docker-compose.yml 檔案中更新 PROVISION_KEY。

3. 該腳本將會自動執行以下操作：

• 如果尚未安裝 Docker 和 Docker Compose，將會自動安裝。
• 使用提供的憑證登入 Docker Hub。
• 在 docker-compose.yml 檔案中設定 PROVISION_KEY。
• 為指定的架構建置 Docker 映像檔。
• 使用 Docker Compose 啟動容器。

步驟四：在 OrpheLink 探索並供裝新的 Agent

1. 返回 OrpheLink Provision 頁面並點擊 Re-discover。新的 Agent 會出現在設備清單中。

2. 選擇該 OrpheAgent 設備，然後點擊底部的 Provision 按鈕，讓 OrpheLink 接管管理。

3. 供裝成功後，確認該設備已出現在 OrpheLink 的 Inventory 頁面。

使用一鍵腳本重建 Docker 映像檔並重新啟動容器

若要重建 Docker 映像檔並重新啟動容器，您可以使用 install.sh 腳本中的 rebuild 方法。請按照以下步驟操作：

1. 使用所需的架構 (例如：amd64、arm64 或 armhf) 執行 rebuild 方法：

sudo bash install.sh rebuild ARCH

將 ARCH 替換為您的系統架構類型。例如：

sudo bash install.sh rebuild amd64

2. 腳本將會自動執行以下操作：

• 為指定的架構建置 Docker 映像檔。
• 停止並移除現有的容器。
• 清理未使用的 Docker 資源。
• 使用更新後的設定重新啟動容器。

3. 預設情況下會建立三個具名儲存區 (Named Volumes)：

• orphe-agent-db：儲存 OrpheAgent 資料庫檔案。
• orphe-agent-logs：儲存 OrpheAgent 日誌檔案。
• orphe-agent-config：儲存 OrpheAgent 設定檔（例如 orphe-agent.yaml）。

檔案總覽

• Dockerfile：定義容器的建置過程。
• entrypoint.sh：用於初始化容器及設定 Agent 的腳本。
• bin/：包含不同架構 (amd64、arm64、armhf) 的預編譯 OrpheAgent 二進位檔案。
• docker-compose.yml：Docker Compose 用於管理容器的設定檔案。

環境變數

以下環境變數可用於設定 OrpheAgent：

• PROVISION_KEY：設定 Agent 的 Provision Key（預設為空）。
• HOST_NAME：設定 Agent 的主機名稱（預設為 orphe-agent）。
• MGMT_PORT_HTTP：設定 HTTP 管理通訊埠 (預設為 0)。
• MGMT_PORT_HTTPS：設定 HTTPS 管理通訊埠 (預設為 0)。
• CONTROLPLANE_TUN_PORT：設定控制層隧道通訊埠 (預設為 0)。
• DATAPLANE_TUN_PORT：設定資料層隧道通訊埠 (預設為 0)。
• DATAPLANE_SNAT_ENABLED：啟用實驗性資料層 SNAT 支援 (true 為啟用，false 為停用；預設為 false)。設定為 true 時，容器將自動使用啟用 SNAT 的方式（帶有 -s 旗標）啟動 OrpheAgent。

  !WARNING 這是一項實驗性功能，可能會導致不可預期的行為。

!NOTE 使用 0 讓系統自動分配隨機的通訊埠。

注意事項

• 容器在特權模式 (Privileged mode) 下運行，允許存取像是 iptables 與 iproute2 等網路功能。
• 使用 --net=host 選項可與容器共享主機網路。
• 日誌會寫入至容器內的 /var/log/orphe-agent.log。
• /etc/orphe-agent/ 目錄包含 OrpheAgent 設定檔（包括 orphe-agent.yaml）。可將此目錄掛載為儲存區，以保留設定變更。

已知限制與備註

• 僅支援 Linux 系統 (amd64、arm64、armhf)。
• 目前尚未支援自動 OTA 更新 (需手動升級)。
• 目前僅在原生的 Ubuntu 18.04、20.04、22.04 與 24.04 上進行測試。