harbor-net/docs/recovery/state-recovery.md

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:

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:

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:

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.