tunasync Mirror Job Management Architecture and Setup

Why tunasync separates managers from mirror workers

tunasync addresses recurring mirror operations that need more control than a manually launched copy command. Its architecture divides the system into a Manager, described in the README as the central instance for status and job management, and Workers that run mirror jobs. This split gives an operator distinct control and execution roles. The Manager receives job control requests and records status, while the Worker stays close to the mirror configuration and provider.

The intended audience is infrastructure operators who already have mirror sources, providers, and a deployment environment. The README does not present tunasync as a general-purpose synchronization client or as a replacement for software that transfers files. It coordinates those mirror jobs and their lifecycle. That makes it relevant to administrators managing recurring repository mirrors, but less relevant to a developer who only needs to fetch one set of files once.

The API labels in the architecture diagram include Client API, Worker API, and Job/Status Management. Those labels imply more than a command-line launcher: the design exposes interfaces for clients and workers while retaining centralized job and status state. The README does not document individual HTTP routes, authentication requirements, request formats, or client setup, so those operational details cannot be inferred from the diagram alone.

How tunasync moves control data to worker execution

The architecture diagram shows two directions of communication. Job control travels from the management side toward the Worker, while job status travels back toward the Manager. The Manager is also connected to BoltDB, which the diagram places under Job/Status Management. This points to centralized management state, although the README does not explain BoltDB retention, schema, backup, or recovery procedures.

A mirror job is associated with a mirror configuration and a provider. The Worker executes the configured job, then updates status so that the Manager can represent its progress. The architecture also includes a Scheduler beneath the worker and job area. This separation suggests that scheduling belongs to the job-running side while management controls and observes work across the system. The diagram does not state whether only one Worker handles a job, how work is assigned when several Workers exist, or how failover is handled.

The process diagram defines a more explicit lifecycle. A job begins with `pre-job` work, moves into `pre-exec`, enters the `job run` and `post-exec` phases, and finishes through either `post-success` or `post-fail`. The diagram routes failed work into `post-fail` rather than directly to a terminal success state. The README does not define retry counts, timeout policy, cancellation semantics, or the exact status values exposed by the API. Operators should not assume a retry or rollback policy that the documentation does not state.

Obtaining tunasync binaries and building from source

For deployment, the README directs users to the GitHub releases page for prebuilt binaries. It specifically states that binaries are available for Linux x86_64 and ARM64. The README provides no direct download URL, checksum file, package repository instruction, container image, or Windows build. A first operational setup therefore begins by opening the linked Chinese get-started document and selecting the release artifact appropriate for the target Linux machine.

For a source build, the README specifies Go version 1.26, while `go.mod` requires `go 1.26.2`. The Makefile builds both `tunasync` and `tunasynctl`. For the native architecture, run the documented target:

make all

The Makefile selects `linux-amd64` by default through its `ARCH` value. Successful compilation produces files under `build-linux-amd64/`, including the two named binaries. For the other documented target, use:

make ARCH=linux-arm64 all

The README identifies `build-$ARCH/` as the output pattern, so this ARM64 invocation writes to `build-linux-arm64/`. The README does not include a first mirror creation, Manager startup, Worker registration, or API request. It also does not specify runtime configuration files. The linked `docs/zh_CN/get_started.md` is the first place to verify for those steps. Without that document, a successful compile would not show that Managers, Workers, providers, and mirror configuration have been connected correctly.

tunasync job phases and scheduler boundaries

The lifecycle diagram separates synchronization work from the phases around it. `pre-job` and `pre-exec` occur before the main `job run`. A normal path continues through `post-exec` and then `post-success`. The failure branch enters `post-fail`, and the diagram connects that branch back toward an earlier point. This shows that failure handling is part of the job model rather than an extra stage omitted from the design.

That model gives tunasync a defined execution structure. A scheduler decides when work should happen, while the displayed lifecycle includes explicit phases and success or failure outcomes. The exact commands placed in `pre-job`, `pre-exec`, `post-exec`, `post-success`, and `post-fail` are not included in the README. It also does not say whether these phases run as shell commands, internal Go operations, or provider-specific actions. Users who require controlled pre-sync and post-sync commands need the full configuration documentation before deciding whether the lifecycle matches their mirror policy.

The Scheduler is drawn separately from the management APIs. This supports a design where remote clients control jobs while local Worker logic determines execution timing. The README does not document clock synchronization, timezone handling, missed-run behavior, concurrent job limits, or Scheduler persistence. Those omissions matter for recurring mirrors, especially where overlapping runs could contend for the same destination.

Operational gaps in tunasync installation and coordination

The biggest documentation gap is deployment detail. No runtime configuration schema, service unit contents, API route, listening port, credential variable, provider example, or mirror job example appears in the README. The repository contains `systemd/`, `manager/`, and `worker/` directories, indicating that deployment and service integration have code in the project, but directory names do not establish a working installation procedure. Those areas should be inspected before assuming the binaries can start without additional files.

The architecture also leaves Worker coordination ambiguous. The diagram shows one Worker and one Scheduler, but it does not explain multi-Worker registration, job ownership, failover, or duplicate execution. BoltDB is shown on the management side, yet the README does not say how status changes are persisted, compacted, or recovered after an interrupted write. Nothing in the documented architecture establishes that status records form a complete audit log.

For a single scheduled copy, this architecture can be excessive. A manually managed script can invoke the transfer tool and report its exit status without introducing a Manager, Worker API, Scheduler, and persistent job-management layer. That alternative requires the operator to build scheduling, status collection, failure handling, and centralized control separately. The meaningful comparison is centralized job management versus direct execution, not a claim that either method always performs faster.

tunasync releases, Go requirements, and GPL-3.0 obligations

The repository is not archived, and its last push was on 2026-08-17. The listed releases are v0.10.0 on 2026-04-13, v0.9.3 on 2025-02-28, and v0.9.2 on 2025-02-27. This release record shows continued releases in 2026, but it does not establish a maintenance interval or a compatibility guarantee for future versions.

The declared license is GPL-3.0. That matters when distributing modified binaries or incorporating project source into another distributed program because GPL-3.0 contains copyleft requirements and license conditions. This is not legal advice, and the README does not document an exception for linked components or proprietary use. An organization should review `LICENSE` and its own distribution model before shipping a modified build.

Upgrade planning has a concrete toolchain component. The Makefile test target selects Go 1.26.2 through `GOTOOLCHAIN`, and `go.mod` declares the same Go version line. The README states Go version 1.26. Operators building from source therefore need a toolchain that satisfies the module requirement rather than assuming an older installed Go release will work. The README does not provide migration notes from v0.9.3 to v0.10.0 or a BoltDB upgrade procedure, so release upgrades should not be treated as configuration-free.

Where tunasync fits against simpler mirror automation

The direct alternative is a local script that invokes the mirror transfer tool, applies a schedule through the host scheduler, and interprets the process exit status. Its approach keeps configuration near the mirror and removes the Manager-to-Worker status protocol. That is a practical fit for one server, one mirror, and operators who are comfortable maintaining their own shell logic.

tunasync instead defines mirror configuration as an object associated with a provider, delegates job execution to a Worker, centralizes management, and exposes Client API, Worker API, and Job/Status Management interfaces. The Scheduler and explicit job phases provide a structure that a direct script would otherwise need to implement. That is the project's meaningful distinction. The README does not establish that tunasync transfers data faster, supports more providers, or recovers better than a script.

Adoption should follow operational complexity. Operators with recurring jobs, centralized status, and control across Manager and Worker processes have a concrete reason to inspect the architecture. Users seeking one unattended copy with no management plane can start with fewer components. Before migration, compare Scheduler semantics, status storage, failure handling, concurrency behavior, deployment files, and upgrade procedures.

Editorial conclusion

tunasync suits operators who need a Manager and Worker architecture for recurring mirror jobs, while a direct script remains simpler for isolated copies. Before adoption, verify `docs/zh_CN/get_started.md` for deployment prerequisites and configuration, then confirm that a release binary matches the target Linux architecture.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. tuna/tunasync on GitHub