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-CN/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-CN.md