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 的时间。这不是实时存活状态，而是接近"最后启动时间"。
Status	Active（绿色）或 Revoked（红色）徽章。对于可能因所有权不一致导致 CQE 引导脚本无法执行的行，徽章旁会显示警告图标(⚠️)——悬停查看说明，点击可跳转到该 lssn 的运行列表(cqelsvrRunList)(giip 3062)
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 时可用。（giip 3043）下拉列表中只会列出 已安装 Docker Desktop 且至少上报过一次使用情况的 lssn —— 刚创建的实例自身的（代理从未连接过的） lssn 从一开始就不会出现在候选中。

在令牌显示区域的下拉列表中选择资源有余量的目标（会同时显示 CPU/Mem/Disk 使用率和正在运行的容器数）。如果没有任何候选项，会显示提示文字来代替下拉列表 —— 此时请改用方法①（手动）。
点击 [Provision now] 按钮。
引导脚本（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）。

容器启动时：

克隆 giipAgentLinux。
创建 giipAgent.cnf（sk=注册的 GIIP_SK，lssn=GIIP_LSSN 环境变量值）。
每分钟执行 giipAgent3.sh（但由于 lssn 不为 0，它维持现有 lsvr 而不是调用 CQEQueueGet 的自登记路径）。
此后该容器将在 lsvrlist 中与其他服务器一起显示。

确认路径: /zh-CN/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/服务器上安装 Docker	`docker version` 同时输出 Client 和 Server 版本
②	安装并注册 GIIP 代理（归属于实例的 csn）	在 lsvrdetail 中确认该 lssn 的 csn 与最近一次签到
③	确认已上报 `docker_usage`	kvslist 中 `kKey=<lssn>`、`kFactor=docker_usage` 的最新行含 `"dockerInstalled":true`
④	确认已显示为候选	Create 实例后，下拉列表中出现该服务器
⑤	执行 [Provision now]	参见方法 ②（远程 Provision now）

按操作系统安装 Docker

操作系统	安装对象	方法
Windows	Docker Desktop	从官方页面 https://docs.docker.com/desktop/setup/install/windows-install/ 安装，或使用 `winget install -e --id Docker.DockerDesktop`。需要 WSL 2 或 Hyper-V（启用虚拟化）。
macOS	Docker Desktop	官方页面 https://docs.docker.com/desktop/setup/install/mac-install/
Linux	Docker 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 的服务器"不是错误，而是候选列表为空。要成为候选，必须同时满足以下三点：

服务器（lssn）属于创建该实例的 csn。
该服务器的 GIIP 代理已上报 docker_usage，且最新值包含 "dockerInstalled":true。
候选列表 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-CN/guides/docker-instances，原文为 https://giip.littleworld.net/help/docker-instances.zh-CN.md）交给 AI 代理，AI 也可以按以下顺序新增目标服务器。

用户需要提供：① 工作 csn（创建实例所用的 csn）② 访问目标 PC/服务器的方式（AI 是否直接在该 PC 上执行，还是远程连接）。

先做只读检查。 确认目标 PC 的操作系统、Docker 安装与守护进程状态（docker version）、GIIP 代理的安装与运行状态，以及 giipAgent.cfg 中的 lssn（不要输出 sk）。
只安装/配置缺失的步骤。 对"如何新增目标服务器"中①~③里已满足的步骤不做改动。安装会更改用户的 PC，因此执行前先向用户说明将安装什么。
不要猜测 csn。 在 lsvrdetail 中确认该 lssn 的 csn，并确认与创建实例所用的 csn 一致。
确认已显示为候选后再报告。 在 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-CN.md