overwatcher

管理 Overwatcher 项目

当 GitHub 仓库收到推送或其 CI 工作流成功时，Overwatcher 会在 VM 上部署 Docker Compose 服务。所有 API 操作都使用 owctl；不要自行编写 API 调用，也不要处理 Agent 令牌。

规则

1. 如果尚未安装 owctl，请先安装。 如果安装程序失败，请停止并报告；除非用户要求，否则不要从源代码构建。

   curl -fsSL "${OVERWATCHER_URL:-https://overwatcher-web-production.up.railway.app}/cli.sh" | sh
   export PATH="$HOME/.local/bin:$PATH"
   

2. 使用现有凭据。 owctl 会读取 OVERWATCHER_API_KEY 或已保存的 owctl login。如果它报告没有 API 密钥，请让用户在其终端中运行 owctl login，或设置 OVERWATCHER_API_KEY（在用户菜单 → API 密钥下创建）。绝不要回显密钥，也不要将其作为参数传递。

3. 检查协调器。 使用 --json；出现错误时停止。若存在同名项目，则复用，不要重复创建。

   owctl project list --json
   owctl agent list --json
   owctl project get <project> --json
   

4. 在询问其他问题之前，先检查 VM。 只询问 SSH 目标，使用 ssh -G <target> 解析别名，然后进行探测（只读；使用 sh -s 可避免 VM 上的 zsh 通配符错误）：

   ssh -T -o BatchMode=yes <target> sh -s <<'EOF'
   echo "user: $(id -un)"
   sudo -n true 2>/dev/null && echo "sudo: passwordless" || echo "sudo: needs password"
   command -v systemctl >/dev/null && echo "systemd: ok" || echo "systemd: missing"
   command -v curl >/dev/null && echo "curl: ok" || echo "curl: missing"
   systemctl show -p LoadState -p ActiveState overwatcher-agent 2>/dev/null
   docker compose version 2>/dev/null || echo "compose v2: missing"
   docker compose ls --all 2>/dev/null || echo "docker: no access for $(id -un)"
   EOF
   

   不要读取 /etc/overwatcher-agent.env；其中包含 Agent 令牌。然后只询问仍未知的信息，并说明已发现的情况：

   • LoadState=loaded：表示已存在 Agent。如果它出现在 agent list 中（匹配 name 或 remote_ip），请询问用户是否要将其绑定，而不是重新安装；否则询问用户。
   • 提供 docker compose ls 中的配置文件作为 Compose 路径。无法访问 Docker 时，请询问路径；安装程序会将用户添加到 docker 组。
   • 缺少 sudo、systemd、curl 或 Compose v2：先停止，直到问题修复。

5. 使用已确认的 Compose 路径创建项目。 文件必须已存在于 VM 上（ssh <target> test -r <path>）。

   owctl project create <project> --compose-file <path> --environment production --json
   

6. 从应用仓库推导服务信息。 每个字段都必须取自源文件，而不是使用默认值：image 来自 Compose 的 image: 行，workflow 来自推送镜像的 CI 文件，tag 来自其推送的标签，root_directory 来自其构建 context（在单体仓库中绝不能是 /）。参照现有项目。name 必须与 Compose 服务键相同。service set 会替换整个列表，因此要保留现有服务。

   owctl service set <project> -f - --json <<'EOF'
   services:
     - name: web
       repo: acme/my-app
       image: ghcr.io/acme/my-app-web
       tag: main
       branch: main
       root_directory: services/web
       workflow: build.yml
   EOF
   

   如果没有 workflow，推送时就会触发部署，而且可能拉取过期镜像。如果一个工作流构建多个镜像，每次运行都会重新部署所有镜像；请告知用户。

7. 绑定或安装 Agent。 绑定会将 Agent 从旧项目移走，并替换项目当前的 Agent；执行任一操作前都要先询问。

   owctl agent bind <agent-id> <project> --json
   owctl agent install --ssh <target> --project <project> --json
   

   安装会配置由 root 管理的 systemd 服务；添加 --yes 前必须获得明确批准。如果失败，owctl 会撤销 Agent，但 VM 文件可能仍然存在；请报告情况，不要盲目重试。Agent 以 SSH 用户身份运行，该用户需要登录镜像仓库才能访问私有镜像。

8. 检查 GitHub App 访问权限。 没有此权限，CI 虽然会通过，但不会触发部署。owctl 无法检查此项；请使用 gh（需要 read:user 范围；如果缺少，请让用户运行 gh auth refresh -h github.com -s read:user）：

   gh api user/installations --jq '.installations[] | select(.app_slug=="overwatcher-app") | {id, account: .account.login, repository_selection, events}'
   gh api user/installations/<id>/repositories --paginate --jq '.repositories[].full_name'
   

   仓库所有者需要一个 events 包含 push 的安装（使用 workflow_run 时也要包含 workflow_run）。如果 repository_selection 为 selected，则必须列出该仓库。否则，请引导用户前往该安装的配置 → 仓库访问，并且不要报告设置已完成。GitHub 不会重新发送之前的事件；获得访问权限后，请重新运行最新的 CI 运行。

验证

1. owctl project get <project> --json：检查 compose_file、enabled 以及每项服务的字段。
2. owctl agent list --json：Agent 的 project_id 匹配，且 status 为 connected。
3. 对每个仓库，规则 8 中的 GitHub App 检查均已通过。
4. 报告项目 ID、Agent 名称以及每项服务的触发方式。这并不能证明部署已成功。