Service Updates & Migration
Relevant source files
The following files were used as context for generating this wiki page:
- packages/onebots/src/service-migration-preparation.spec.ts
- packages/onebots/src/service-migration-file-plan.ts
- packages/onebots/src/service-migration-journal.ts
- packages/onebots/src/service-migration-manager-candidate.ts
- packages/onebots/src/service-migration-recovery.spec.ts
- packages/onebots/src/service-migration-files.spec.ts
- packages/onebots/src/service-migration.spec.ts
Service Updates & Migration manages the transition of independent OneBots gateway processes into a managed "control" runtime. The system captures the legacy service state, prepares a new management candidate, and executes a transactionally safe file migration. This process ensures that the management console remains available even if individual gateway instances fail or stop.
Sources: README.en.md:68-80, AGENTS.md:12-25
Migration Lifecycle
The migration process follows a strict state machine to prevent data loss or service corruption. The system uses a journaled approach to track progress through various phases, allowing for recovery or rollback in the event of an interruption.
Migration Phases
| Phase | Description |
|---|---|
prepared | Initial intent is saved and validation is complete. |
capturing-runtime | Legacy binaries and Node.js environments are archived. |
preparing-manager | The new manager software artifacts are installed and verified. |
writing-target | New configuration and service definitions are written to disk. |
target-written | Files are successfully updated; service handover is imminent. |
completed | The service is fully migrated to the new control runtime. |
Sources: packages/onebots/src/service-migration-journal.ts:77-110, packages/onebots/src/service-migration-recovery.spec.ts:108-115
Migration Flow Diagram
The following diagram illustrates the standard progression from a legacy service to a managed control service.
The diagram shows the sequence of checks and operations required to move a service into the managed runtime.
Sources: packages/onebots/src/service-migration-journal.ts:98-250, packages/onebots/src/service-migration-files.spec.ts:133-145
Preparation and Validation
Before any file modifications occur, the system performs "read-only" preparation. It validates the legacy YAML configuration and checks for destination conflicts.
- Conflict Detection: The system throws an error if target configuration files already exist or if dangling symlinks occupy the target path.
- Credential Stripping: During preparation, the system extracts administrative credentials (e.g.,
password) from the configuration document to prevent them from leaking into the new gateway configuration, while retaining protocol-specific tokens. - Integrity Checks: If the legacy YAML is damaged, the system preserves the original bytes but refuses to generate a new configuration candidate.
Sources: packages/onebots/src/service-migration-preparation.spec.ts:36-65
File Migration Planning
The createServiceMigrationFilePlan function generates a mapping between legacy files and their managed counterparts. It strictly manages three primary roles: definition, metadata, and configuration.
Target File Roles
- Configuration: Maps the legacy config to a new
config.yamlwithin the workspace. - Definition: Renders a new system service definition (Systemd unit or Launchd plist) pointing to the manager.
- Metadata: Stores the
ManagerServiceSpecwhich defines the scope, workspace, and node environment.
Sources: packages/onebots/src/service-migration-file-plan.ts:21-65
Transactional File Operations
The ServiceMigrationFiles class handles the physical movement of files using a Compare-And-Swap (CAS) approach.
- Staging: Files are first written to a private staging directory (e.g.,
.onebots-migration-temp) with restricted permissions (0o700). - Permission Sync: The system prepares file modes (e.g.,
0o600for configs) before moving them to the final destination. - Atomic Move: Files are moved using atomic renames to ensure the system never enters an inconsistent state.
- Integrity Validation: The system checks all original files before applying changes; it rejects operations if hardlinks or unexpected modifications are detected in the source.
Sources: packages/onebots/src/service-migration-files.spec.ts:184-210, packages/onebots/src/service-migration-journal.ts:333-355
Runtime Retention and Rollback
To ensure service continuity, the system captures the legacy runtime environment. This includes the specific Node.js binary and the software tree used by the previous installation.
Rollback Coordination
If the migration fails after the files have been written, the system uses a ServiceMigrationRollbackCoordinator. This component:
- Restores original file bytes and permission modes.
- Restarts the legacy service using the retained runtime to maintain original service state.
- Verifies that the restored service identity matches the pre-migration state.
Sources: packages/onebots/src/service-migration-retained-runtime.spec.ts:173-210, packages/onebots/src/service-migration-recovery.spec.ts:133-155
Rollback Logic Sequence
This sequence ensures that a failed update does not leave the system without a functioning gateway.
Sources: packages/onebots/src/service-migration-files.spec.ts:40-65, packages/onebots/src/service-migration-retained-runtime.spec.ts:250-300
Cold Recovery
When a migration is interrupted (e.g., system crash), the system enters a "cold recovery" state. The recoverInterruptedServiceMigrationV2 function reconciles the state by inspecting the journal. If a target service was never started, the recovery logic quiesces the workspace and performs a full restoration to the legacy state.
Sources: packages/onebots/src/service-migration-recovery.spec.ts:160-185, packages/onebots/src/service-migration-journal.ts:48-65
Service Updates & Migration provide a robust framework for upgrading the OneBots infrastructure. By combining atomic file operations with runtime retention, the project ensures that gateways can be centralized under a management service without risking service availability or configuration integrity.
Sources: AGENTS.md:12-25, packages/onebots/src/service-migration.spec.ts:310-335