docs(upgrade): 列出安装器对下载物的校验与离线导入 registry 镜像的做法

  its gate runs) cannot be pulled from the registry they make up, so the installer

  labels both `io.cri-containerd.pinned=pinned` in containerd and kubelet's image

  GC never collects them. Check with `k3s ctr images ls | grep pinned`.

- **The registry image is pinned by digest**

  (`docker.io/library/registry:2.8.3@sha256:a3d8aaa6…`), and the installer

  caches it with `k3s crictl pull`. On an air-gapped node, carry it over with

  containerd's own export, which keeps the digest ref. On a connected machine

  with k3s or containerd (`R` is the full `docker.io/library/registry@sha256:…`

  ref from `internal/platform/identities.go`):

  `ctr images pull --all-platforms $R && ctr images export --all-platforms

  registry.tar $R`; on the node: `k3s ctr images import --all-platforms

  registry.tar`, then re-run the installer to pin it. A `docker save` round trip

  rewrites the manifest, and kubelet will not match it to the digest.

- **Selector quirk worth knowing:** the registry Service selector is only

  `name + component=registry` — it deliberately lacks the

  `part-of=felis-control-plane` label, so the registry is *invisible* to the

There is no in-place updater: an upgrade is re-running the installer

(`curl -fsSL <installer URL> | sudo bash`), which rebuilds/re-imports the image

and re-applies the bundle. (`sudo felis setup` is not this path; on a completed

and re-applies the bundle. `felis update --panel` prints that command with the

script read at the newest release's tag, so the installer and the binary it

downloads come from the same release. (`sudo felis setup` is not this path; on a completed

install it only opens the config console.) The channel is not persisted across

the re-run, so pass `FELIS_VERSION_BOOTSTRAP=dev` on a host that tracks main.

Two properties of the control plane matter when you do:

  wait fails after 180s and prints `kubectl describe` diagnostics: you see

  `ErrImagePull`/`ImagePullBackOff` there instead of a silent hang.

**What the installer checks before it runs anything it downloaded:**

| Download | Check |

|---|---|

| `felis-linux-<arch>` (release channel) | its sha256 must match the release's `SHA256SUMS`; a release without one, or a mismatch, is compiled from the same tag instead |

| k3s (fresh install only) | the install script is read at `FELIS_K3S_VERSION`'s tag (default `v1.36.4+k3s1`), and it checks the binary against that release's sha256 list |

| cloudflared (when absent) | release `FELIS_CLOUDFLARED_VERSION` (default `2026.9.1`) against a pinned sha256; another version needs `FELIS_CLOUDFLARED_SHA256` |

| Go toolchain (nano, source builds) | pinned sha256 per architecture; another version needs `FELIS_GO_SHA256` |

| the registry image | pinned by digest (`registry:2.8.3@sha256:a3d8…`) |

On a public repository each release also carries a signed build-provenance

attestation. Check a downloaded binary with

`gh attestation verify felis-linux-amd64 --repo FelisMC/Felis`; it names the

workflow run and commit that built it.

Roll back with:

```