docs: replace the single-node report with the maintained migration entry point

Keep the original PR #228 report at a fixed commit link with contributor credit. Direct operators to the bilingual migration guide and its recovery requirements, and record the merged contribution. Signed-off-by: Feng Ruohang <rh@vonng.com>
2026-10-29 03:57:19 +03:00 · 2026-10-23 19:27:20 +08:00
parent e3e0c6215d
commit 789a2327ba
2 changed files with 20 additions and 78 deletions
@@ -23,7 +23,7 @@ When a proposal was incorporated through a later repair, its adoption is credite
 <a href="https://github.com/julienlau"><img src="https://silo.pgsty.com/images/contributors/julienlau.svg" width="60" height="60" alt="@julienlau" title="@julienlau — Fixed missing-commit-metadata error handling and stale metadata reuse; contributed replication reports and proposals"></a>
 <a href="https://github.com/Aeirx"><img src="https://silo.pgsty.com/images/contributors/Aeirx.svg" width="60" height="60" alt="@Aeirx" title="@Aeirx — Preserved Object Lock legal-hold headers in federated CopyObject"></a>
 <a href="https://github.com/AleksaMCode"><img src="https://silo.pgsty.com/images/contributors/AleksaMCode.svg" width="60" height="60" alt="@AleksaMCode" title="@AleksaMCode — Fixed the Lambda target-set emptiness check and added a regression test"></a>
-<a href="https://github.com/yupoet"><img src="https://silo.pgsty.com/images/contributors/yupoet.svg" width="60" height="60" alt="@yupoet" title="@yupoet — Improved checksum mismatch messages, verified erasure-coding documentation, and proposed an upgrade guide"></a>
+<a href="https://github.com/yupoet"><img src="https://silo.pgsty.com/images/contributors/yupoet.svg" width="60" height="60" alt="@yupoet" title="@yupoet — Improved checksum mismatch messages, verified erasure-coding documentation, and contributed a single-node migration case"></a>
 <a href="https://github.com/clown15"><img src="https://silo.pgsty.com/images/contributors/clown15.svg" width="60" height="60" alt="@clown15" title="@clown15 — Fixed native multipart-upload timestamp parsing during stale-upload cleanup"></a>
 <a href="https://github.com/botdeniska"><img src="https://silo.pgsty.com/images/contributors/botdeniska.svg" width="60" height="60" alt="@botdeniska" title="@botdeniska — Contributed multi-pool migration safety repairs and faster policy evaluation in silo-pkg"></a>
 <a href="https://github.com/magicxor"><img src="https://silo.pgsty.com/images/contributors/magicxor.svg" width="60" height="60" alt="@magicxor" title="@magicxor — Reported and proposed conditional DELETE support for If-Match"></a>
@@ -92,7 +92,7 @@ When a proposal was incorporated through a later repair, its adoption is credite
 | [@julienlau](https://github.com/julienlau) | Fixed missing-commit-metadata error handling and stale metadata reuse; contributed replication reports and proposals | Merged PRs: [pgsty/silo#232](https://github.com/pgsty/silo/pull/232), [pgsty/silo#233](https://github.com/pgsty/silo/pull/233)<br>Open PRs: [pgsty/silo#240](https://github.com/pgsty/silo/pull/240), [pgsty/silo#241](https://github.com/pgsty/silo/pull/241)<br>PRs closed without merging: [pgsty/silo#184](https://github.com/pgsty/silo/pull/184)<br>Closed issues: [pgsty/silo#152](https://github.com/pgsty/silo/issues/152), [pgsty/silo#153](https://github.com/pgsty/silo/issues/153)<br>The original PR was not merged directly. Its purge-state and recovery analysis, proposed fix, tests, and documentation helped shape [#196](https://github.com/pgsty/silo/pull/196); see the [maintainer acknowledgement](https://github.com/pgsty/silo/pull/184#issuecomment-5689295222). |
 | [@Aeirx](https://github.com/Aeirx) | Preserved Object Lock legal-hold headers in federated CopyObject | Merged PRs: [pgsty/silo#172](https://github.com/pgsty/silo/pull/172) |
 | [@AleksaMCode](https://github.com/AleksaMCode) | Fixed the Lambda target-set emptiness check and added a regression test | Merged PRs: [pgsty/silo#220](https://github.com/pgsty/silo/pull/220) |
-| [@yupoet](https://github.com/yupoet) | Improved checksum mismatch messages, verified erasure-coding documentation, and proposed an upgrade guide | Merged PRs: [pgsty/silo#229](https://github.com/pgsty/silo/pull/229)<br>Open PRs: [pgsty/silo#228](https://github.com/pgsty/silo/pull/228), [pgsty/silo#230](https://github.com/pgsty/silo/pull/230)<br>Also [cross-checked the two-drive EC:1 documentation](https://github.com/pgsty/silo/issues/197#issuecomment-5846341939). Open upgrade-guide and registry-mirror proposals are credited as proposals, not shipped features. |
+| [@yupoet](https://github.com/yupoet) | Improved checksum mismatch messages, verified erasure-coding documentation, and contributed a single-node migration case | Merged PRs: [pgsty/silo#228](https://github.com/pgsty/silo/pull/228), [pgsty/silo#229](https://github.com/pgsty/silo/pull/229)<br>Open PRs: [pgsty/silo#230](https://github.com/pgsty/silo/pull/230)<br>Also [cross-checked the two-drive EC:1 documentation](https://github.com/pgsty/silo/issues/197#issuecomment-5846341939). The single-node migration report in #228 was merged on 2026-10-23; it records a contributor-reported forward upgrade, not a downgrade guarantee. The registry-mirror proposal remains open. |
 | [@clown15](https://github.com/clown15) | Fixed native multipart-upload timestamp parsing during stale-upload cleanup | Merged PRs: [pgsty/silo#236](https://github.com/pgsty/silo/pull/236) |
 | [@botdeniska](https://github.com/botdeniska) | Contributed multi-pool migration safety repairs and faster policy evaluation in silo-pkg | Open PRs: [pgsty/silo#245](https://github.com/pgsty/silo/pull/245), [pgsty/silo#248](https://github.com/pgsty/silo/pull/248)<br>Merged PRs: [pgsty/silo-pkg#11](https://github.com/pgsty/silo-pkg/pull/11)<br>The migration repair from [#248](https://github.com/pgsty/silo/pull/248) was incorporated in [60c7179dd](https://github.com/pgsty/silo/commit/60c7179ddbfcbd41a1fe67707230f5b360a43020), retaining the original authorship and DCO. The original PR remains open; this does not imply that #245 shipped. |

@@ -1,80 +1,22 @@
-# Upgrading a Single-Node Deployment from the Archived MinIO Community Edition
+# Single-node migration from MinIO to SILO

-The MinIO community edition repository was archived on 2026-04-25 and its binary
-distribution channels (`dl.min.io`, the Docker Hub tags, quay.io) were withdrawn
-afterwards. Operators still running the final community release need a documented,
-validated path forward. This guide records a real-world, single-node upgrade from
-`RELEASE.2025-10-15T17-29-55Z` (the last community release) to Silo
-`RELEASE.2026-09-16T00-00-00Z`, performed in production on 2026-09-26.
+The maintained migration procedure and single-node case study belong to the
+companion documentation site:

-The [compatibility audit](https://silo.pgsty.com/compatibility/server/) covers
-the server behavior changes but does not specifically address the
-single-node/single-drive (FS mode) case. This document fills that gap with
-field data.
+- [English migration guide](https://silo.pgsty.com/compatibility/migration/)
+- [中文迁移指南](https://silo.pgsty.com/zh/compatibility/migration/)

-## Validated environment
+Follow the guide's deployment checks, consistent backup procedure, verification
+steps and [rollback requirements](https://silo.pgsty.com/compatibility/migration/#rollback).
+Modern single-node/single-drive erasure deployments are distinct from the retired
+filesystem backend; historical FS installations need the
+[filesystem migration procedure](https://silo.pgsty.com/operations/deployments/baremetal-migrate-fs-gateway/).

- Single node, single drive: `server /data` in FS mode, running under Docker Compose
- Root credentials only — no IAM sub-users, no OIDC, no notification targets, no reverse proxy
- ~5,900 objects / ~34,000 stored chunks accumulated over 15 months on the source version
- Source: `RELEASE.2025-10-15T17-29-55Z` → target: `RELEASE.2026-09-16T00-00-00Z`
-
-## Why this is a low-risk swap for standalone deployments
-
- **Zero data migration.** `.minio.sys`, erasure metadata, bucket/object layout and
-  encryption formats keep their names and schemas; the existing data volume is opened
-  in place, with no copy and no metadata rewrite.
- **Single nodes are unaffected by the removed private `ReadMultiple` storage REST
-  call** — that only constrains mixed-version multi-node clusters.
- **The IAM/password-policy tightening does not apply** to plain root-credential
-  standalone setups (no sub-users, no OIDC, no bucket policies in use).
-
-## Procedure
-
-1. **Back up the data volume first** (tar the volume or snapshot the disk). Even with
-   a compatible format, an upgrade window is the worst time to discover your only
-   copy is damaged.
-2. **Pin the exact target image tag** in your deployment tooling. Floating tags make
-   both upgrades and rollbacks ambiguous.
-3. **Stop dependent services before swapping the storage container**, so no writes
-   race the restart.
-4. **Recreate the storage container with the Silo image, keeping the data volume
-   unchanged.** Compatibility notes:
-   - `minio server …` invocations translate transparently; the official container
-     entrypoint handles the rename.
-   - Healthchecks that run `curl -f /minio/health/live` inside the container work
-     out of the box with the official images (curl is bundled). If you build custom
-     images, remember to include curl — the upstream release images shipped a static
-     curl, minimal bases may not have one.
-5. **Verify in layers**:
-   - Startup log: expect zero errors. Watch specifically for hardening rejections —
-     Silo refuses malformed historical objects (poisoned metadata, invalid erasure
-     geometry) that older code tolerated; such objects need manual remediation
-     before they will serve again.
-   - `GET /minio/health/live` and `/minio/health/ready` → 200.
-   - Application-level S3 smoke: upload → read back → delete, through the real client.
-
-## Observed results (2026-09-26 field run)
-
- In-place upgrade with zero migration steps; the 15-month-old data volume opened
-  with no errors and **no objects were rejected by the new hardening**.
- A full application regression against the storage (multipart upload, object read
-  by a parser service, listing, deletion) passed end to end.
- **Rollback path is image-swap only** (same on-disk schema), but note we did not
-  exercise a reverse downgrade in production. Our evidence is a staged forward
-  migration — the same data volume was opened read-write by three engine builds
-  in sequence (`2025-09` → `2025-10` → `2026-09`) with no format intervention —
-  plus the documented schema retention. Keep the previous image available locally:
-  registry tags you depend on may disappear, as the community tags already have.
-
-## Post-upgrade behavior changes to check
-
-These did not affect the validated standalone setup, but review them against your
-own clients before upgrading:
-
- **TLS defaults changed** across 20260903/20260916 — verify clients if you serve TLS
-  directly from the storage node or front it with older proxies/identity providers.
- **`If-Match` on `DeleteObject`** was ignored in 20260903 and is enforced in 20260916.
- **Multipart listing is capped at 1,000 entries** per request in newer releases.
- `MINIO_API_TRUSTED_PROXIES` still defaults to trusting every proxy header; set it
-  explicitly if the node sits behind a proxy.
+Paris Y. ([@yupoet](https://github.com/yupoet)) contributed the production report in
+[#228](https://github.com/pgsty/silo/pull/228), describing a 2026-09-26 forward
+upgrade to SILO 20260916. The
+[original report](https://github.com/pgsty/silo/blob/fec1e0804a7493f68ba409345da8e90f0f4d5fbb/docs/upgrade/single-node-from-archived-minio.md)
+is retained as historical evidence. Its FS terminology and unconditional
+metadata, healthcheck, multipart-listing and rollback claims are superseded by
+the maintained guide. The report is not independent verification of a newer
+release, a complete historical-object audit, or a reverse downgrade.