giip
SES 商機登記
14分鐘閱讀

Docker 執行個體管理指南

Docker 執行個體是 GIIP 的管理員功能，可將 GIIP 代理以容器方式部署到遠端 PC/伺服器，並在 GIIP Web 上進行建立、檢視和銷毀。將執行個體權杖傳遞給目標機器並啟動容器後，該機器將開始作為 GIIP 代理（每分鐘輪詢）和 slack-bot（可選）運行。

🏢 前往 Docker 執行個體管理頁面 →

📋 概述

Docker 執行個體管理頁面用於在遠端 PC/伺服器上部署 giip-fde-agent Docker 容器。建立執行個體時，GIIP 伺服器使用 AES-256-GCM 加密存儲憑證，並僅一次顯示 bootstrap 權杖。

⚠️ 此頁面僅限管理員存取。 需要 uLevel >= 70 才能存取。低於此級別的用戶將被重新導向到首頁。

🔍 頁面佈局

1. 頂部標題

  • 頁面標題: "Docker 執行個體管理"
  • + Create Docker instance 按鈕：打開建立模態框。

2. 執行個體列表

欄位說明
Label執行個體名稱（未設定時為 #<diSn>）
LSSN預登記的lsvr序列號。在建立後立即在權杖顯示區域和此清單中顯示。點擊跳轉到lsvrdetail
Created建立時間
Last fetched容器使用權杖最後一次從 GIIP 獲取 env 的時間。這不是即時存活狀態，而是接近「最後啟動時間」。
StatusActive（綠色）或 Revoked（紅色）徽章。對於可能因擁有權不一致導致 CQE 引導程式無法執行的行，徽章旁會顯示警告圖示(⚠️)——滑鼠停留查看說明，點擊可前往該 lssn 的執行清單(cqelsvrRunList)(giip 3062)
ActionsRevoke 按鈕 — 使權杖失效（不停止執行中的容器）

⚠️ 當 Last fetched 為 - 時：容器尚未啟動。尚未執行步驟 ①（手動）或 ②（Provision now）。

🛠️ 建立執行個體

  1. 點擊 + Create Docker instance。
  2. 填寫 3 個必填欄位：
    • GIIP_LOGIN_ID: GIIP 登入帳戶（例如 user@example.com）
    • GIIP_SK: GIIP 密鑰（與密碼不同）
    • GIIP_CSN: CSN 編號（例如 47）
  3. 填寫可選欄位：
    • Label: 執行個體名稱（例如 lowy-dp01-docker）
    • GIIP_PROJECT_NAME: 預設為 docker
    • GIIP_WORKDIR: 工作目錄（可選）
    • GIIP_REST_BRANCH: Git 分支（可選）
    • SLACK_BOT_TOKEN / SLACK_APP_TOKEN / SLACK_CHANNEL_ID: Slack 機器人（可選 — 需要兩個權杖）
    • Enable hourly-issue-scheduler: 核取方塊（預設開啟） — 每小時 :07 執行一次問題排程器
  4. 點擊 Create。

請立即複製權杖

建立後，僅顯示一次權杖。

GIIP_INSTANCE_TOKEN=<權杖>

關閉模態框後將無法再次檢視。 啟動容器需要此權杖，請在繼續操作前務必複製。

🛠️ 建立後啟動容器 — 方法 ①（手動，所有環境）

複製權杖後，在目標 PC/伺服器上執行以下操作：

# 1. 克隆 giip-fde-agent 儲存庫
git clone https://github.com/LowyShin/giip-fde-agent.git
cd giip-fde-agent/docker

# 2. 只在 .env 中寫入權杖
echo 'GIIP_INSTANCE_TOKEN=<複製的權杖>' > .env

# 3. 使用 Docker Compose 啟動
docker compose up -d --build
  • .env 中只需權杖一行。 其餘環境變數由 fetch-instance-env.sh 透過 dockerInstanceFetch API（權杖本身作為憑證）從伺服器自動獲取。
  • 如果直接在 .env 中新增其他鍵，這些值優先（支援部分覆寫）。

🛠️ 建立後啟動容器 — 方法 ②（遠端 "Provision now"）

僅在目標 PC 已執行 GIIP 代理且擁有 lssn 時可用。（giip 3043）下拉選單只會列出 已安裝 Docker Desktop 且至少回報過一次使用狀況的 lssn —— 剛建立的執行個體自身的（代理從未 連線過的）lssn 一開始就不會出現在候選清單中。

  1. 在權杖顯示區域的下拉選單中選擇資源有餘裕的目標（會一併顯示 CPU/Mem/Disk 使用率與執行中的 容器數）。若沒有任何候選項目，會改為顯示提示文字取代下拉選單 —— 此時請改用方法①（手動）。
  2. 點擊 [Provision now] 按鈕。
  3. 引導指令稿（mssn=6122）將被加入 CQE 佇列並立即強制執行（CQERunForce）。

⚠️ 此按鈕僅在已安裝 GIIP 代理的 PC 上有效。 如果目標 PC 上沒有代理，請使用步驟 ①。

ℹ️ 權限: [Provision now] 由伺服器（DockerInstanceProvision）驗證。只要是執行個體所屬 csn 與目標伺服器所屬 csn 的成員即可執行，不需要是指令稿的所有者。失敗時頁面會顯示原因（見下方疑難排解表），執行個體已建立且權杖仍然有效，可繼續使用手動步驟 ①。

⚠️ 最多需要 1 分鐘: 目標 PC 上的 GIIP 代理約每 60 秒輪詢一次，最長等待 1 分鐘。

🔍 建立後「連線」確認 — 3 種方法

GIIP Web 中沒有連接到容器的終端。 確認方式如下：

1. 容器 Shell 連線（目標 PC 上）

docker exec -it giip-fde-agent bash

容器名稱固定為 giip-fde-agent。

2. 日誌檢視（目標 PC 上）

docker compose logs -f          # 在 docker/ 目錄中執行
docker logs -f giip-fde-agent   # 任意位置

啟動正常時會看到：

  • [entrypoint] cloned ...
  • [fetch-instance-env] env applied from GIIP_INSTANCE_TOKEN
  • [entrypoint] registered giipAgentLinux cron (every 1 min)
  • [entrypoint] ready. tailing logs.

3. GIIP Web 確認 — lsvrlist（伺服器列表）

這是「透過 GIIP Web 確認連線」的正確方式。

執行個體建立時會預登記lsvr — 建立執行個體時lssn會立即發放並顯示在UI上，因此lsvr會在容器啟動前就顯示在lsvrlist中（giip 2856）。

容器啟動時：

  1. 克隆 giipAgentLinux。
  2. 建立 giipAgent.cnf（sk=註冊的 GIIP_SK，lssn=GIIP_LSSN 環境變數值）。
  3. 每分鐘執行 giipAgent3.sh（但由於 lssn 不為 0，它維持現有 lsvr 而不是調用 CQEQueueGet 的自登記路徑）。
  4. 此後該容器將在 lsvrlist 中與其他伺服器一起顯示。

確認路徑: /zh-TW/lsvrlist → 找到對應的 lssn → lsvrdetail → 透過 tLSvr.lsChkdt 心跳確認存活

⚠️ 如果沒有 GIIP_SK 或 GIIP_ENABLE_AGENT=false，則不會發生此註冊，無法在 GIIP Web 上檢視容器狀態。啟動日誌末尾的 [entrypoint] summary: 區塊透過 giip agent: on|off (原因) 可一眼判定此狀態（giip #2855）。

4. Slack 確認（配置 Slack 機器人時）

僅當 SLACK_BOT_TOKEN 和 SLACK_APP_TOKEN 均提供時，slack-bot 才會透過 pm2 啟動。如果機器人在指定頻道中回應，則執行正常。

⚠️ 如果缺少任一權杖則跳過 — 僅配置一個權杖而沒有任何反應是正常行為。

🧩 如何新增目標伺服器（安裝 Docker → 顯示為候選）

Provision now 下拉清單依**伺服器（lssn）**顯示候選，而不是依 csn 選擇；候選只來自建立執行個體時所用 csn 下的伺服器。要新增目標，請依以下順序準備 PC/伺服器。

步驟操作確認方法
①在目標 PC/伺服器上安裝 Dockerdocker version 同時輸出 Client 與 Server 版本
②安裝並註冊 GIIP 代理程式（隸屬於執行個體的 csn）在 lsvrdetail 中確認該 lssn 的 csn 與最近一次簽到
③確認已回報 docker_usagekvslist 中 kKey=<lssn>、kFactor=docker_usage 的最新列含 "dockerInstalled":true
④確認已顯示為候選Create 執行個體後，下拉清單中出現該伺服器
⑤執行 [Provision now]參見方法 ②（遠端 Provision now）

依作業系統安裝 Docker

作業系統安裝對象方法
WindowsDocker Desktop從官方頁面 https://docs.docker.com/desktop/setup/install/windows-install/ 安裝，或使用 winget install -e --id Docker.DockerDesktop。需要 WSL 2 或 Hyper-V（啟用虛擬化）。
macOSDocker Desktop官方頁面 https://docs.docker.com/desktop/setup/install/mac-install/
LinuxDocker Engine依官方文件 https://docs.docker.com/engine/install/ 中對應發行版的步驟安裝。安裝後將使用者加入 docker 群組（官方 "Linux post-installation steps"），重新登入後確認 docker version 能輸出伺服器版本。

安裝後 Docker 常駐程式必須處於執行狀態（Docker Desktop 需保持應用程式開啟）。

⚠️ 目前 Linux（Docker Engine）不會出現在候選清單中。 經確認，giipAgentLinux（origin/main）中沒有蒐集並回報 docker_usage 的程式碼，只有 Windows 代理程式（giipAgentWin 的 CollectDockerMetrics.ps1）會回報。因此在 Linux 伺服器上安裝 Docker 也不會成為下拉候選，此情況請使用**方法 ①（手動）**啟動。

候選判定條件（Windows 代理程式）

Windows 代理程式每次執行都會檢查 docker CLI 是否在 PATH 中，當 docker version --format '{{.Server.Version}}' 回傳伺服器版本時回報 dockerInstalled=true。CLI 不存在或常駐程式未執行時為 false。

安裝 GIIP 代理程式

代理程式安裝請參照以下指南，而非本文件。代理程式必須隸屬於建立執行個體時所用的 csn。

🤖 AI 代理程式連線手冊（Provision now 目標伺服器未顯示時）

AI 代理程式代替人員「將此 PC 連線為 Docker 執行個體目標」時遵循的步驟。所有步驟皆為唯讀，請直接查詢數值，不要猜測。

提示訊息的意義

「此 csn 中尚未偵測到 Docker Desktop 的伺服器」不是錯誤，而是候選清單為空。要成為候選，必須同時滿足以下三點：

  1. 伺服器（lssn）屬於建立該執行個體的 csn。
  2. 該伺服器的 GIIP 代理程式已回報 docker_usage，且最新值包含 "dockerInstalled":true。
  3. 候選清單 API（DockerCapableLsvrList）已在伺服器上部署。

1. 找出目標 PC 的 lssn 與 csn

  • 從代理程式設定檔 giipAgent.cfg 讀取 lssn（不要輸出 sk 的值）。Windows 代理程式請從工作排程器 GIIP Agent Task (v3) 的執行路徑找到資料夾，並查看其上層資料夾中的 giipAgent.cfg。
  • 在 GIIP 網頁 lsvrdetail 中確認該 lssn 的 csn，必須與建立執行個體的 csn 相同。

2. 檢查代理程式與 Docker 運作

  • Windows：Get-ScheduledTask 'GIIP Agent Task (v3)' | Get-ScheduledTaskInfo 中 LastTaskResult 應為 0（成功）或 267009（執行中）。
  • 代理程式記錄中每次執行都應有 [CollectDockerMetrics] ... Successfully collected and uploaded Docker resource usage。
  • Docker Desktop 必須處於執行狀態。確認 docker version 能輸出到伺服器版本。

3. 檢查已回報的 Docker 使用量

在 GIIP 網頁 kvslist 中以 kKey=<lssn>、kFactor=docker_usage 查詢。最新一列包含 "dockerInstalled":true 才會成為候選。若沒有或為 false，請回到第 2 步。

4. 一切正常但清單仍為空（管理員）

表示候選清單 API 未部署。以前這種情況也會顯示相同的提示，因而掩蓋原因；現在頁面會顯示「候選清單 API 回應異常」錯誤。管理員需確認預存程序 pApiDockerCapableLsvrListbyAK 是否存在，若不存在，請以 mgmt/execSQLFile.ps1 部署 giipdb 的 SP/pApiDockerCapableLsvrListbyAK.sql。

5. 沒有可連線的伺服器時

  • 目標 PC 上沒有 GIIP 代理程式時無法使用 [Provision now]。請先安裝並註冊代理程式，或使用手動流程 ①。
  • 代理程式從未連線過的 lssn（最後簽入為空）不是候選。建立執行個體時預先註冊的 lssn 就屬於這種情況，請不要選作目標。

AI 必須遵守

  • 不輸出或記錄 sk、執行個體權杖以及佇列腳本內容中的權杖。
  • 不使用其他 csn 的 SK 進行查詢或寫入（先確認 csn）。
  • 不猜測數值，僅依據上述查詢結果回報。

🤖 僅向 AI 代理程式傳遞本文件 URL 的情況

即使使用者只把本文件的 URL（https://giip.littleworld.net/zh-TW/guides/docker-instances，原文為 https://giip.littleworld.net/help/docker-instances.zh-TW.md）交給 AI 代理程式，AI 也可以依以下順序新增目標伺服器。

使用者需要提供：① 工作 csn（建立執行個體所用的 csn）② 存取目標 PC/伺服器的方式（AI 是否直接在該 PC 上執行，或是遠端連線）。

  1. 先做唯讀檢查。 確認目標 PC 的作業系統、Docker 安裝與常駐程式狀態（docker version）、GIIP 代理程式的安裝與執行狀態，以及 giipAgent.cfg 中的 lssn（不要輸出 sk）。
  2. 只安裝/設定缺少的步驟。 對「如何新增目標伺服器」中①~③裡已滿足的步驟不做變更。安裝會變更使用者的 PC，因此執行前先向使用者說明將安裝什麼。
  3. 不要猜測 csn。 在 lsvrdetail 中確認該 lssn 的 csn，並確認與建立執行個體所用的 csn 一致。
  4. 確認已顯示為候選後再回報。 在 kvslist 的 docker_usage 中確認 "dockerInstalled":true，並確認建立執行個體後下拉清單中出現該候選。對於 Linux 伺服器這類結構上無法成為候選的情況，回報這一事實以及方法 ①（手動）。

AI 必須遵守的事項與上文「AI 必須遵守」相同（不輸出 sk 與執行個體權杖，不使用其他 csn 的 SK，不猜測）。

💡 注意事項

  • Last fetched ≠ 即時存活狀態: Last fetched 是「最後獲取 env 的時間」。容器停止後該值保持不變。即時狀態請查看 lsvrlist 心跳。
  • Revoke 不會刪除列: Revoke 僅使權杖失效，不會刪除列表列。作為稽核記錄，Revoked 徽章會保留在列表中。
  • Revoke 不會停止執行中的容器。 如需停止，必須在目標 PC 上執行 docker compose down。
  • 容器名稱: 手動流程 ① 與既有執行個體使用 giip-fde-agent。[Provision now] 會為每個執行個體以 giip-fde-agent-<diSn>（compose 專案 giip-fde-<diSn>）啟動，因此一台 PC 可以執行多個執行個體。diSn 可在清單的 diSn 欄中查看。

問題解決

症狀原因解決方法
出現「此 csn 中尚未偵測到 Docker Desktop 的伺服器」(a) 目標 PC 的代理程式未執行或 Docker Desktop 已關閉，沒有 docker_usage (b) 伺服器的 csn 與執行個體的 csn 不同 (c) 候選清單 API 未部署到伺服器請依下方「AI 代理程式連線手冊」第 1～4 步檢查。要立即繼續，請使用手動流程 ①。
未複製權杖無法重新取得Revoke 現有執行個體並重新建立。
docker compose up 成功但 lsvrlist 中無顯示(a) GIIP_ENABLE_AGENT=false (b) GIIP_SK 為空 (c) 首次輪詢尚未發生 (d) 認證錯誤(401)檢查 docker logs 中 /work/giipAgentLinux/log/cron.log 的 401 錯誤
/work/giipAgentLinux 下只有 log/，看起來像「空殼 clone」跳過代理區塊（GIIP_SK 未解析或 GIIP_ENABLE_AGENT=false）啟動後的痕跡。正常 clone 時根目錄有 .git＋7 個目錄，ls -la 的連結數為 10；觀測值 3（.＋..＋單個 log/）表示只建立了日誌目錄而非 clone在 docker logs 中透過 skipping giip agent 與 [entrypoint] summary: 區塊的 giip agent: off (原因) 判定原因（通常為 GIIP_SK 未解析／權杖 fetch 失敗）。修復原因並重啟後，最新 entrypoint 會將殘留移至 .bak-<時間戳> 後自動重新 clone（giip #2855）。舊映像（此修復之前）需人工刪除磁碟區內該目錄才能解除 not an empty directory 拒絕
每次重啟都註冊新的 lssn/work 磁碟區已遺失確認 docker-compose.yml 的磁碟區是否對應到 giip-fde-agent-data:/work（整個 /work 持續化）
[Provision now] 失敗頁面顯示的原因：Forbidden: not a member of the instance csn / ...target server csn（不是該 csn 的成員）、Target server has not reported Docker Desktop（目標從未回報 Docker — 請檢查代理程式與 Docker Desktop）、still pending（上一個請求仍在等待 — 約 5 分鐘後重試）、Docker instance is revoked / not found（執行個體已撤銷或不存在）請依顯示的原因處理。要立即繼續，請使用手動步驟 ①（docker compose up）。權杖仍然有效。
[Provision now] 顯示成功訊息，但幾分鐘後 lsvrlist 和容器都沒有任何變化(a) 目標 lssn 的代理已停止，從一開始就沒有輪詢 (b) 僅此排程被隔離為無法配發（BLOCKED）（giip #2557 類問題）(a) 在 lsvrdetail 中確認該 lssn 的最後簽到時間 — 若已過期，先排查目標 PC 的代理/網路 (b) 請管理員依該 lssn/csn 確認是否有無法配發的排程。等待數分鐘仍無反應則改用步驟①（手動）
Slack 機器人未啟動需要 SLACK_BOT_TOKEN 和 SLACK_APP_TOKEN 同時提供缺少任一權杖則兩者均跳過。
存取時立即跳轉首頁uLevel 低於 70使用管理員帳戶（70+）登入。

版本: 1.3 最後更新: 2026-10-15（新增「如何新增目標伺服器」與「僅向 AI 代理程式傳遞本文件 URL 的情況」） 源檔案: giipv3/public/help/docker-instances.zh-TW.md

相關指南

資料中心管理如何管理資料中心和位置機架管理在機架中組織伺服器伺服器列表查看和管理所有伺服器
← Previous伺服器詳情Back to Overview知識中心