编排文档

Appearance

租户侧：安装代理（零基础） ​

先跑通安装代理，是成功的第一步：若卡在这里，很多人不会再试平台其它能力。文档与控制台帮助都按「能复制就不手写」来写，卡住时把终端最后约 20 行发给支持即可。

面向在自备 Linux 服务器上部署 vaiteam-install-agent 的客户：若只会 SSH、尚未安装 Docker，请按 复制粘贴 步骤操作。

获取源码：下载包与 Git 仓库（建议同时提供） ​

  • 压缩包 / 控制台直链：运营提供 vaiteam-install-agent-*.tar.gz，或由 SaaS GET /api/portal-mode 返回的 install_agent_download_links（ROOT 在「安装制品」中维护的 HTTPS 镜像）。解压后即为完整可构建目录，最快跑通，不必 git clone。历史路径 /api/go/install-agent 已不存在（404）。
  • Git 仓库：控制台配置 INSTALL_AGENT_SOURCE_REPO_URL 后与下载入口并列展示，便于 git clone、审计与跟踪更新；monorepo 需进入 saas/install-agent 子目录（以你们实际仓库为准）。

控制台内帮助 ​

登录 SaaS 控制台 → 安装代理 → 选定租户实例后，点击 「零基础安装说明」，与本文同旨，可边开网页边在 SSH 里粘贴命令。

一条链（与控制台 ①② 对齐） ​

下列顺序与 Portal「安装代理」页生成的命令、帮助页「零基础」、源码 portal-web/src/installAgentDockerCommands.ts 一致，勿跳步。

  1. 准备目录：解压安装代理小包（或 clone 后进入 saas/install-agent），cp docker.env.example docker.env，填写 VAITEAM_PORTAL_URL（与浏览器访问控制台根 URL 一致，无末尾 /）。
  2. 镜像就绪：源码包执行 docker compose build（可用 build --pull 只拉基础镜像）；离线二进制包在本目录执行 bash deploy.sh（或 load-image.sh）得到 vaiteam-install-agent:local，不要对本栈执行 docker compose pull。
  3. 配对：在控制台 生成配对码，在解压目录执行页面 ① 注册（docker run --rm … register --pairing-code '…'），成功后再执行 ② 常驻（docker run -d … run --cache-dir /data/cache）。
  4. 验收：控制台「已注册代理」出现本机且心跳在线 → 可由运营/ROOT 下发安装任务 → 代理拉制品执行 install.sh。内部验收清单见主仓库 saas/docs/INSTALL_AGENT_CLOSED_LOOP.md。

若 ① 报 400/409：配对码过期或同机指纹已注册（需 ROOT 吊销后重配）。命令报错请截取终端 最后约 20 行。

交付包 / 仓库文档（最全） ​

开源与交付小包中的完整说明（含公告板约定、FRP、排障等）见：

  • 仓库路径：saas/install-agent/README.md
  • 其中 「零基础客户」 一节：按 Ubuntu / Debian / CentOS / Rocky / Fedora 分块给出整段 shell，并说明 A → B → C（装 Docker → 进目录 → 改 docker.env + build / register / up）。

自动升级（推荐生产开启） ​

目的：避免「现场装了一版 install-agent 后，后续只能靠人手 SSH 换包」；与平台登记的 install_agent 制品、release_version（x.y.z）对齐后，由心跳下发升级提示，代理本机拉包、load-image、docker compose up -d 重建服务。

要点（与主仓库 saas/install-agent/README.md「自升级」一致）

  1. ROOT：在控制台「安装制品」维护 category=install_agent 的启用包，release_version 须高于 当前代理心跳里的 vaiteam_install_agent_version，且存在可下载地址（镜像或本地上传 + 公网 bundle 前缀等）。
  2. 现场：在 docker.env / compose 中把宿主 compose 工程目录挂进容器，并设置 VAITEAM_AGENT_COMPOSE_PROJECT_DIR 指向该挂载路径；须能访问 /var/run/docker.sock 以执行 compose。
  3. 开关：已配置 VAITEAM_AGENT_COMPOSE_PROJECT_DIR 且未显式写 VAITEAM_AGENT_AUTO_UPGRADE=0 时，默认会尝试自升级；若需彻底关闭，设 VAITEAM_AGENT_AUTO_UPGRADE=0。compose 文件名、服务名可用 VAITEAM_AGENT_COMPOSE_FILE、VAITEAM_AGENT_COMPOSE_SERVICE 覆盖默认值。
  4. 验收：升级成功后日志中会出现 [install-agent] 自升级：已完成 load-image 与 docker compose up；控制台「安装代理」列表中的版本号应与 ROOT 登记一致。全托管场景另见仓库 saas/docs/MANAGED_PROVISION_RUNBOOK.md「验收」第 5 条。

信任说明：升级包与下载地址仍来自你信任的 Portal / ROOT 登记制品；链路为出站 HTTPS，与 SaaS 信任与安全模型 总原则一致。

务必记住 ​

  1. 顺序：docker compose build → docker compose run … register → docker compose up -d，不要先 up -d。
  2. 不要对本栈执行 docker compose pull（镜像是本地 build，与 Dockerfile 基础镜像源不是一回事）。
  3. 国内网络建议配置 Docker registry-mirrors，构建代理镜像时已默认使用国内基础镜像转发；详见 README.md。