49 lines
2.3 KiB
Markdown
49 lines
2.3 KiB
Markdown
# Harbor state recovery
|
|
|
|
Harbor keeps the existing data directory and `state.json` path. The current persisted format is `schemaVersion: 5`: schema v2 introduced local route rules, v3 added rule enabled state, v4 added stable server IDs, and v5 embeds the canonical `profiles[]` collection with desired/applied profile identity.
|
|
|
|
## Atomic writes
|
|
|
|
Persistent files are written to a unique temporary file in the same directory, flushed with `fsync`, closed and atomically renamed over the target. A failure before rename leaves the previous target untouched and removes the temporary file.
|
|
|
|
Profile/server switching prepares candidate config and runtime before the final state publication. If any later step fails, Harbor restores the previous config, runtime and canonical state.
|
|
|
|
## Migration to profiles
|
|
|
|
On startup, a legacy state is normalized before the process starts. Harbor creates one profile named `Основной`, moves the provider URL/config and metadata into it, and preserves unambiguous desired/applied server identity. A legacy state explicitly marked stopped clears stale applied residue.
|
|
|
|
Before replacing state Harbor saves the original beside it:
|
|
|
|
```text
|
|
state.json.backup-v4-2026-08-11T12-00-00-000Z
|
|
```
|
|
|
|
After a valid profile has been committed, the raw legacy cache is saved and removed as a second owner:
|
|
|
|
```text
|
|
subscription-cache.json.backup-v1-2026-08-11T12-00-00-000Z
|
|
```
|
|
|
|
An invalid legacy provider config is backed up but not started. Harbor removes stale generated config and returns to a stopped first-run state.
|
|
|
|
## Corrupt JSON
|
|
|
|
If `state.json` cannot be parsed, Harbor renames the exact damaged bytes to:
|
|
|
|
```text
|
|
state.json.corrupt-2026-08-11T12-00-00-000Z
|
|
```
|
|
|
|
It then creates a valid empty current-schema state and reports storage recovery. A corrupt legacy subscription cache is preserved with the same suffix and is never used to start stale config.
|
|
|
|
## Manual recovery and downgrade
|
|
|
|
Perform recovery while Harbor is stopped:
|
|
|
|
1. Copy the whole data directory.
|
|
2. Inspect the intended backup with `jq . <backup-file>`.
|
|
3. Restore only matching state/cache backups to their original filenames.
|
|
4. Start Harbor and verify `GET /api/state` before applying a profile.
|
|
|
|
A pre-v5 binary cannot interpret canonical profiles. Downgrade therefore requires both pre-migration backups; deploying old code alone is not a safe rollback.
|