# AutoDL GPU Runner Controller

该仓库只管理算力，不包含 Evidence Extractor 研究代码。控制流程运行在阿里云的常驻
`ces-control:host` Gitea Runner 上，并通过 AutoDL Pro API 创建和关闭 GPU 实例。

## 边界

- 本仓库：AutoDL Pro 生命周期、模型传输、GPU Runner 注册和产物回收。
- 阿里云：常驻控制 Runner、SigLIP2 权重以及训练产物的持久存储。
- AutoDL：临时 GPU 执行节点。
- 研究仓库：训练代码、配置和 Gitea Actions workflow 的唯一来源。

## Repository Secrets

在本仓库 `Settings → Actions → Secrets` 配置：

- `AUTODL_API_TOKEN`：AutoDL 控制台的开发者 Token。
- `TRAINING_RUNNER_REGISTRATION_TOKEN`：研究仓库 `Create new Runner` 页面显示的
  Registration Token。

Secret 只注入阿里云控制任务，不落盘、不打印。AutoDL SSH 私钥保存在阿里云
`/root/.config/ces-controller/autodl_ed25519`，不进入 Gitea。

## 首次启动

阿里云需要先作为本仓库的常驻 Runner 注册一次，且只使用标签：

```text
ces-control:host
```

该 bootstrap 使用的是“本控制器仓库”的 Runner Registration Token，不是 Secret 中用于
AutoDL GPU Runner 的 `TRAINING_RUNNER_REGISTRATION_TOKEN`。

Runner online 后，第一次 push 只执行 `Controller CI`，不会创建实例或产生 AutoDL 费用。

## 阿里云长期部署

每次 push 到 `main` 后，`Controller CI` 会先运行测试，再把通过验证的控制器安装到：

```text
/opt/ces-controller/releases/<git-commit>/
```

`/opt/ces-controller/current` 原子指向当前版本，并安装 Terminal 入口
`/usr/local/bin/ces-controller`。管理 workflow 只执行这个长期部署的版本，并拒绝执行与当前
workflow commit 不一致的旧版本。部署目录不保存 AutoDL Token 或 Runner Registration Token；
Secret 仍只在单次 Actions 任务中注入。

通过 SSH 可以检查版本或查看帮助：

```bash
cat /opt/ces-controller/current/VERSION
ces-controller --help
```

## 管理 workflow

从 Actions 手动运行 `Manage AutoDL GPU runner`：

- `discover`：列出账号私有镜像和内置公共基础镜像，不产生 GPU 费用；
- `instances`：只读列出当前 Token 账号下的 Pro 实例；
- `provision`：创建 PRO6000、传输模型并注册 GPU Runner；必须填写镜像 UUID，并把确认值
  填为 `CREATE`；
- `resume`：对失败后已关机的现有实例继续配置；同样必须填写 `CREATE`；
- `status`：查询实例和 Runner 进程状态；
- `shutdown`：回收训练产物并关闭实例，不释放系统盘。

`provision` 在创建实例前会检查 SigLIP2 的两个权重分片是否完整、AutoDL SSH 私钥权限是否为
`0600`，并预下载及校验 `gitea-runner`。任何配置失败都会尝试关闭刚创建的实例，避免继续计费。

控制器固定使用官方 `gitea-runner 3.5.0` Linux AMD64 二进制及其 SHA-256，下载和校验均在
创建付费实例之前完成。

`discover` 同时输出账号私有镜像和控制器内置的 AutoDL 公共基础镜像目录。`provision` 可以
直接接收 `image_uuid`，也可以通过 `framework`、`framework_version` 和 `cuda_version` 三项
精确选择公共镜像；没有精确匹配时会停止，不会自动降级到旧框架或旧 CUDA。

AutoDL GPU Runner 注册为 host runner，并提供：

```text
ubuntu-latest:host
ces-ci:host
gpu:host
```