# Cloud daemon 分发与校验

Cloud 接入使用独立的公开下载页 `/download`。它不是 GitHub `latest` 的无条件跳转器，而是一个 fail-closed 发布目录：只有版本、来源和每个平台摘要都完整可信时才出现直接下载按钮。

## 为什么不能直接链接 latest

自托管 daemon 的最新公开版本不一定已经实现 Cloud 稳定端点合同。Cloud 注册要求 daemon 支持协议 1.3、只保存一个 `server_url`、识别 `ready | provisioning`，并按结构化错误在同一 `/ws/daemon` 退避；不得轮询控制面或接受替换用 Relay URL。最低兼容版本固定为 `0.2.6`。

截至 2026-08-12，GitHub 最新稳定 Release 是 `v0.2.5`。它包含三个 daemon 平台包和 `checksums.txt`，但没有新的稳定端点合同，因此下载页不会展示它。该版本用于自托管不受影响。

## 发布目录配置

只有完成兼容 Release 验证后才设置：

| 环境变量 | 要求 |
|---|---|
| `NEKONEST_CLOUD_DAEMON_RELEASE_VERSION` | 稳定语义版本 `X.Y.Z`，不得低于 `0.2.6` |
| `NEKONEST_CLOUD_DAEMON_RELEASE_BASE_URL` | 可选；无用户名、密码、query 或 fragment 的 HTTPS 目录；默认指向该精确 GitHub tag |
| `NEKONEST_CLOUD_DAEMON_WINDOWS_AMD64_SHA256` | `nekonest-daemon-windows-amd64.zip` 的 64 位十六进制摘要 |
| `NEKONEST_CLOUD_DAEMON_LINUX_AMD64_SHA256` | `nekonest-daemon-linux-amd64.tar.gz` 的 64 位十六进制摘要 |
| `NEKONEST_CLOUD_DAEMON_LINUX_ARM64_SHA256` | `nekonest-daemon-linux-arm64.tar.gz` 的 64 位十六进制摘要 |

任一项不完整或不合法时，三个直接下载入口一起关闭，避免只给部分用户分发未核对的构建。页面不会回退到旧版本或 `releases/latest/download`。

## 上架步骤

1. 从干净、已验收且三个版本面一致的源码创建不可变 tag；等待 Release workflow 完整通过。
2. 运行 `npm run release:verify -- vX.Y.Z`。核验器只接受不低于最低兼容版本的稳定精确 tag，并下载三个 daemon 压缩包与 `checksums.txt`；它会同时比较 Release 身份、精确 URL、重复/缺失资产、GitHub API digest、声明大小、清单摘要和实际下载字节。
3. 只有核验全部通过时，工具才在标准输出给出五个 Cloud 环境配置值；它不会自动写 `.env`、修改 Sites 环境、提交或部署。需要机器读取时使用 `--json`。GitHub API 限速场景可临时设置 `GITHUB_TOKEN`，令牌只发送给固定的 GitHub API 请求，不附带到公开资产下载，也不出现在结果或错误信息中。
4. 在 Windows amd64、Linux amd64、Linux arm64 上分别核对压缩包内 `VERSION` 和 `nekonest-daemon -version`。
5. 使用临时 Cloud 环境完成注册、设备令牌保存、`provisioning` 同端点重试、结构化拒绝和稳定 Connect 重连回归。
6. 若使用境内 HTTPS 镜像，从已经核对的同一压缩包复制；镜像文件摘要必须与 GitHub 精确 tag 保持一致。
7. 设置工具输出的环境变量并重新构建/部署 Cloud；打开 `/download` 复核版本、文件名、链接和摘要。
8. 从真实 Windows/Linux 主机执行页面给出的校验、解压、注册和启动旅程。

## 当前信任边界

- SHA-256 证明下载字节与 Cloud 发布目录登记值一致，不证明作者身份。
- 当前 GitHub workflow 生成 `checksums.txt`，但没有对清单或 Windows 二进制做 Authenticode 等发布者签名。
- 未完成代码签名前，不得把页面描述为“已签名安装包”，也不提供关闭 SmartScreen、杀毒软件或系统安全策略的引导。
- 自建镜像不能自行重新打包；否则摘要变化，目录应保持关闭，直到完成新的受控发布。
- Cloud 环境配置是公开分发控制，不包含私密令牌；敏感凭据不得放入下载 URL。
- 公开下载清单未就绪时，新增主机页会要求闭测参与者明确确认已经从管理员处取得并核验不低于最低版本的构建，才允许生成十分钟配对码；该确认只防止误操作，不替代管理员对闭测文件的来源和 SHA-256 核验。
- 核验器不使用 `latest`、不接受 prerelease 或 draft，也不会把 API 返回的下载地址当作任意可信镜像；所有 GitHub URL 必须与仓库、精确 tag 和固定文件名完全一致。

## 注册版本上报

`POST /api/devices/register` 可选接收 `daemon_version`。已上报值必须是规范稳定版本 `X.Y.Z`，并且不得低于本页同一最低兼容版本；格式异常返回 `invalid_daemon_version`，明确低版本返回 `daemon_version_incompatible`。通过认领后，版本与主机记录在同一 D1 写入中保存；恢复已有主机时，缺失版本不会覆盖已经保存的值。

当前闭测阶段仍兼容缺失的版本字段；未知不代表已经通过兼容性验证。正式 daemon 先稳定发送版本并完成安装、升级与降级拒绝回归，Cloud 才能把缺失值改成强制拒绝；在此之前不能用版本门禁阻断既有闭测参与者。

## 尚未完成

- 发布最低 `v0.2.6` 的兼容资产并填入真实摘要；
- 让正式 daemon 在 Cloud 注册时发送自身稳定版本；覆盖升级后上报、旧版拒绝和版本缺失迁移后，再决定是否强制上报；
- Windows 发布者代码签名和签名证书运营；
- 境内下载可用性、失败回退和带宽成本实测；
- 三个平台真实安装、升级、降级拒绝和卸载/残留检查。