NodeBridge

---

Architecture

Multi-node topology

flowchart TB
  a["Edge A: MySQL / Canal / SyncAgent"]
  b["Edge B: MySQL / Canal / SyncAgent"]
  n["Edge N: MySQL / Canal / SyncAgent"]
  hub["Central server: RabbitMQ / SyncAgent / MySQL / Canal"]
  a -->|Uplink| hub
  b -->|Uplink| hub
  n -->|Uplink| hub
  hub -->|Downlink| a
  hub -->|Downlink| b
  hub -->|Downlink| n

Star topology: each Edge has its own MySQL, Canal and SyncAgent. RabbitMQ carries uplink/downlink messages; arrows describe logical routes, not a requirement for one shared broker. Edges do not synchronize directly with each other.

Apply to central MySQL, then route.

Multi-node behavior

• Edge → Server only：Set dispatch_target: NONE. Each Edge uploads; the Server applies to its mapped database/table without forwarding.
• Server → selected Edges：Set SELECTED_EDGES with dispatch_node_ids. Server-local changes are captured by its Canal and sent only to selected targets.
• Edge → Server → other Edges：Use BIDIRECTIONAL with ACTIVE_EDGES, or explicitly enable forwarding. A change from A is applied at the Server, then forwarded to eligible B…N; A is skipped by default.
• Mappings and identity：Give each node a unique ID. Use source_node_ids to distinguish identical source table names across nodes; map database/table/columns explicitly. ACTIVE_EDGES refers to registered ACTIVE nodes, not simply machines that are currently online.

Example: A changes a row → Server commits it → B and N apply it. With NONE, the same change stops at Server. With SELECTED_EDGES = [B], N receives no downlink. MCP connects to each node separately for management.

Routing reference

Single-direction processing

flowchart LR
  source[(Source MySQL)] --> canal[Canal CDC]
  canal --> event[SyncAgent: SyncEvent]
  event --> mq[RabbitMQ]
  mq --> apply[SyncAgent: Apply]
  apply --> target[(Target MySQL)]

One direction is shown. Bidirectional rules also process the reverse flow, with routing and replay detection. MCP is a management interface, not a required hop in the data path.

Quick start: install the Windows release, prepare MySQL/binlog using the deployment guide, then configure connections and a table rule. Verify insert, update and delete operations with separate test data first.

A ready-to-run Docker demo is not yet released. See the future plan.

MCP · Bring your AI assistant into sync operations

Connect your MCP client to NodeBridge through local stdio or remote SSH. Inspect evidence, manage configuration and follow alignment tasks from one conversation.

Ask your assistant	NodeBridge capabilities
“Why has this node stopped syncing?”	Inspect Agent status, queues, logs and event receipts; export diagnostics.
“Check this mapping before saving.”	Read schema and rules, preflight local mappings, validate and save configuration with revision checks.
“Track our approved initial alignment.”	Start the confirmed task, poll progress and inspect the complete group before restarting synchronization.

MCP also supports Agent control, failed-event retries and structured business-data queries and changes. Data changes require a plan and explicit confirmation; arbitrary shell and raw SQL are not exposed.

Connect: save a complete configuration, enable MCP in NodeBridge, then run your client as the Windows account that owns that configuration. Each node gets its own client entry; SSH carries stdio without opening an MCP HTTP port.

& 'C:\Program Files\NodeBridge\app\SyncAgent.exe' mcp-stdio -config 'C:\ProgramData\NodeBridge\config.yaml'

Initial alignment requires stopped Agents on all participants, confirmation and open MCP sessions while polling. A task returning running is not complete. Rule preflight checks the local node; verify the saved and active revisions after changes.

MCP tools and client configuration · Multi-node AI handoff guide · Interactive MCP overview

Built for connected operations

A workspace that keeps the details in view

Actual NodeBridge frontend, shown with isolated test data. Prominent rule names, searchable navigation and compact editing.

Get started

1. Prepare. Install MySQL separately. Give every node a unique ID and back up configuration, rules and databases.
2. Install. Run the Windows x64 installer as administrator using the intended Windows account. It bundles NodeBridge, SyncAgent, Erlang/OTP, RabbitMQ, Java, Canal and WinSW.
3. Configure and verify. Define your mappings, check initial alignment and validate inserts, updates, deletes and recovery in your own environment.

Upgrading? These fixes require no extra business columns. Change display names without replacing rule IDs or deleting alignment records. Configured system database migration failures block installation completion.

Application: C:\Program Files\NodeBridge\app · Data: C:\ProgramData\NodeBridge. Closing the window keeps the app in the tray; explicit exit requires the configured password.

Release confidence

v0.48.7 Beta fixes reconnection, partially committed batch forwarding and bidirectional target database selection. Go test/vet/lint, installer checks and two isolated three-Agent reconnect runs passed. This is not a benchmark on three physical computers or a production SLA. The installer is unsigned.

Read the verification report (Chinese) · SHA256

Explore the project

• LAN deployment
• Initial alignment
• Routing policies
• Managed components
• Trial runbook
• MCP reference

go test ./...
go vet ./...
golangci-lint run ./...
cd frontend
npm ci
npm test
npm run build

---

Open source under the MIT license. English is the default README; select another language above.