3x-ui/docs/superpowers/progress/2026-04-10-multi-node-shared-control-progress.md

Multi-Node Shared Control Progress

Execution Strategy

• Tasks 1–3: Inline
• Tasks 4–7: Subagent-Driven
• Every task is a checkpoint and must end with its own git commit.
• After each task commit, record the short hash here before moving on.

Update Rules

• Change Status: [ ] Pending to Status: [x] Done only after the task’s checkpoint commit succeeds.
• Replace Commit: pending with the short commit hash for that task.
• If a task is blocked, update the Blockers: line on that task instead of opening a separate scratch section.
• Keep this file current before handing work from Inline execution to Subagent-Driven execution.

Task Tracker

Task 1: Add node config, runtime file paths, and startup validation

• Status: [x] Done
• Mode: Inline
• Commit: 36826706
• Depends on: none
• Scope: add NodeConfig, role validation, runtime file path helpers, CLI setters, and startup validation before DB init
• Primary files: config/config.go, config/config_test.go, main.go
• Checkpoints:
  • add focused failing tests for defaults, validation, and runtime file paths
  • implement GetNodeConfigFromJSON, ValidateNodeConfig, GetSharedCachePath, and GetTrafficPendingPath
  • wire startup validation and setting CLI flags into main.go
  • run focused ./config tests and package discovery
• Done when:
  • worker mode rejects missing nodeId and sqlite
  • setting -show prints node settings
  • Task 1 checkpoint commit is recorded
• Blockers: none

Task 2: Add shared metadata models and repository helpers

• Status: [x] Done
• Mode: Inline
• Commit: fd0af148
• Depends on: Task 1 committed
• Scope: add shared version and node heartbeat metadata tables plus repository helpers for version bump and node-state upsert
• Primary files: database/model/shared_state.go, database/model/node_state.go, database/shared_state.go, database/db.go, database/db_test.go
• Checkpoints:
  • add failing tests for metadata tables, version seeding, and node-state upsert
  • create SharedState and NodeState models
  • add GetSharedAccountsVersion, BumpSharedAccountsVersion, and UpsertNodeState
  • register models in DB init and seed shared_accounts_version
  • run focused ./database tests
• Done when:
  • metadata tables are auto-migrated by InitDB
  • shared version starts at 0 and bumps transactionally
  • Task 2 checkpoint commit is recorded
• Blockers: none

Task 3: Enforce master-only shared writes and transactional version bumping

• Status: [x] Done
• Mode: Inline
• Commit: 34b9f01d
• Depends on: Task 2 committed
• Scope: establish the shared write boundary in service code before any worker sync or shared traffic work lands
• Primary files: web/service/node_guard.go, web/service/node_guard_test.go, web/service/inbound.go
• Checkpoints:
  • add failing tests for RequireMaster and version rollback behavior
  • implement IsWorker, IsMaster, RequireMaster, and shared-mode detection
  • guard shared inbound/client mutation paths in InboundService
  • bump shared version only inside successful write transactions
  • run focused ./web/service guard tests
• Done when:
  • worker-side shared write attempts fail in service layer
  • successful shared writes advance shared_accounts_version
  • Task 3 checkpoint commit is recorded
• Blockers: none

Task 4: Add shared snapshot cache, worker sync loop, and snapshot-driven Xray rebuild

• Status: [x] Done
• Mode: Subagent-Driven
• Commit: 3cfa5547
• Depends on: Tasks 1–3 committed
• Scope: make workers survive from cached shared snapshots and rebuild local Xray from synchronized inbounds instead of live DB reads only
• Primary files: web/service/node_cache.go, web/service/node_sync.go, web/service/node_sync_test.go, web/service/xray.go, web/web.go
• Checkpoints:
  • add failing tests for snapshot round-trip, no-op sync, changed-version sync, and cache bootstrap
  • add SharedAccountsSnapshot load/save helpers
  • refactor XrayService to build config from an explicit inbound list
  • implement NodeSyncService with cache bootstrap, version polling, and node-state updates
  • start worker sync or master heartbeat loops from server startup
  • run focused sync tests
• Done when:
  • worker startup can apply shared-cache.json before the first DB poll
  • changed shared version leads to cache refresh plus local Xray rebuild
  • Task 4 checkpoint commit is recorded
• Blockers: none

Task 5: Add durable traffic delta persistence and safe shared-mode flushes

• Status: [x] Done
• Mode: Subagent-Driven
• Commit: 87282dde
• Depends on: Task 3 committed, Task 4 wiring available
• Scope: stop worker shared-mode traffic from mutating shared state directly; collect local deltas, flush atomically, and keep reconciliation master-only
• Primary files: web/service/traffic_pending.go, web/service/traffic_flush.go, web/service/traffic_flush_test.go, web/job/xray_traffic_job.go, web/service/inbound.go, web/web.go, xray/client_traffic.go
• Checkpoints:
  • add failing tests for delta merge, successful flush, and failed flush retention
  • implement TrafficPendingStore and TrafficDelta
  • add composite unique key on (inbound_id, email) for safe upserts
  • implement TrafficFlushService with atomic DB updates
  • extract ReconcileSharedTrafficState so only master performs enable/expiry mutations
  • route shared-mode traffic collection through pending-store accumulation and start flush loop
  • run focused flush tests and package discovery
• Done when:
  • worker shared-mode traffic no longer calls InboundService.AddTraffic()
  • pending deltas survive failures and clear only after successful flush
  • Task 5 checkpoint commit is recorded
• Blockers: none

Task 6: Expose node management in shell tools and the installer

• Status: [x] Done
• Mode: Subagent-Driven
• Commit: 6b58044e
• Depends on: Task 1 committed
• Scope: expose the new node settings to operators through x-ui.sh and install.sh without destabilizing upgrades
• Primary files: x-ui.sh, install.sh
• Checkpoints:
  • add node-setting readers and status display to x-ui.sh
  • add minimal node-role and node-id mutation actions via ./x-ui setting
  • prompt for MariaDB and node role during fresh installs only
  • run bash -n on both scripts and smoke-check ./x-ui setting -show true
• Done when:
  • shell scripts pass syntax checks
  • fresh-install path can capture MariaDB plus node role settings
  • Task 6 checkpoint commit is recorded
• Blockers: none

Task 7: Document the feature and run focused verification

• Status: [x] Done
• Mode: Subagent-Driven
• Commit: 85cd0b60
• Depends on: Tasks 4–6 committed
• Scope: publish operator-facing docs, verification steps, and final package-level checks after implementation is stable
• Primary files: docs/multi-node-sync.md, README.md, README.zh_CN.md
• Checkpoints:
  • write the operator runbook with role model, requirements, runtime loops, and failure behavior
  • add concise README sections in English and Chinese
  • append the manual verification checklist
  • run focused verification across ./config, ./database, and ./web/service, then package discovery
• Done when:
  • docs match the shipped runtime behavior
  • verification commands pass
  • Task 7 checkpoint commit is recorded
• Blockers: none