6分鐘閱讀

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>`）
Created	建立時間
Last fetched	容器使用權杖最後一次從 GIIP 獲取 env 的時間。這不是即時存活狀態，而是接近「最後啟動時間」。
Status	Active（綠色）或 Revoked（紅色）徽章
Actions	Revoke 按鈕 — 使權杖失效（不停止執行中的容器）

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

🛠️ 建立執行個體

點擊 + Create Docker instance。
填寫 3 個必填欄位：
- GIIP_LOGIN_ID: GIIP 登入帳戶（例如 user@example.com）
- GIIP_SK: GIIP 密鑰（與密碼不同）
- GIIP_CSN: CSN 編號（例如 47）
填寫可選欄位：
- 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 執行一次問題排程器
點擊 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 時可用。

在權杖顯示區域的 lssn 輸入框中輸入目標 PC 的 lssn。
點擊 [Provision now] 按鈕。
引導指令稿（mssn=6122）將被加入 CQE 佇列並立即強制執行（CQERunForce）。

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

⚠️ 指令稿所有權約束: 引導指令稿以特定所有者帳戶執行。如果從非註冊帳戶點擊此按鈕會失敗，但執行個體已建立且權杖仍然有效。此時請使用步驟 ①（手動）繼續。

⚠️ 最多需要 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 確認連線」的正確方式。

容器啟動時：

克隆 giipAgentLinux。
建立 giipAgent.cnf（sk=註冊的 GIIP_SK，lssn="0"）。
每分鐘執行 giipAgent3.sh。
GIIP 自動分配 lssn，之後在同一 lssn 下傳送心跳。
此後該容器將在 lsvrlist 中與其他伺服器一起顯示。

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

⚠️ 如果沒有 GIIP_SK 或 GIIP_ENABLE_AGENT=false，則不會發生此註冊，無法在 GIIP Web 上檢視容器狀態。

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

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

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

💡 注意事項

Last fetched ≠ 即時存活狀態: Last fetched 是「最後獲取 env 的時間」。容器停止後該值保持不變。即時狀態請查看 lsvrlist 心跳。
Revoke 不會刪除列: Revoke 僅使權杖失效，不會刪除列表列。作為稽核記錄，Revoked 徽章會保留在列表中。
Revoke 不會停止執行中的容器。 如需停止，必須在目標 PC 上執行 docker compose down。
容器名稱始終為 giip-fde-agent: 由 docker-compose.yml 的 container_name 固定。

問題解決

症狀	原因	解決方法
未複製權杖	無法重新取得	Revoke 現有執行個體並重新建立。
`docker compose up` 成功但 lsvrlist 中無顯示	(a) `GIIP_ENABLE_AGENT=false` (b) `GIIP_SK` 為空 (c) 首次輪詢尚未發生 (d) 認證錯誤(401)	檢查 `docker logs` 中 `/work/giipAgentLinux/log/cron.log` 的 401 錯誤
每次重啟都註冊新的 lssn	`/work` 磁碟區已遺失	確認 `docker-compose.yml` 的磁碟區是否對應到 `giip-fde-agent-data:/work`（整個 `/work` 持續化）
[Provision now] 失敗	引導指令稿所有者帳戶不符	使用步驟 ①（手動 `docker compose up`）。權杖仍然有效。
Slack 機器人未啟動	需要 `SLACK_BOT_TOKEN` 和 `SLACK_APP_TOKEN` 同時提供	缺少任一權杖則兩者均跳過。
存取時立即跳轉首頁	`uLevel` 低於 70	使用管理員帳戶（70+）登入。

版本: 1.0 最後更新: 2026-09-22 (giip #2847) 源檔案: giipv3/public/help/docker-instances.zh-TW.md