互联同步部署指南Sync deployment guide
Windows、Docker、NAS、VPS 全路径Windows, Docker, NAS and VPS, every path

Wherever the server runs, something in front of it must terminate TLS (Caddy, Tailscale, a temporary tunnel, or self-signed + an installed CA). The server itself listens only on the local loopback; the plaintext port is never exposed to the network.

True no matter which you pick

• The data directory must be on a local disk. NFS / SMB network shares are a data-corruption risk (SQLite's WAL depends on shared memory and file locks), not a performance issue.
• The first run is always the same three steps: create the space (credentials shown once) → start the server → pair the desktop. Details in "Create a space and pair" below.
• The server listens on loopback or the internal network only, with TLS terminated by the reverse proxy in front; proxy and forwarded-header rules in "Reverse proxy and HTTPS".

How to choose

• An always-on Windows PC at hand → start with Windows direct-run; results in ten minutes, migrate to a NAS any time.
• A VPS or a Linux box at home → Docker Compose + Caddy; set up once, never manage certificates again.
• Already have a Synology / QNAP → go straight to Synology / QNAP; confirm the model is x86 / amd64 first.
• Nothing fits, or you want total control → the plain binary: the same code, the same environment variables as Docker.

What is inside Sync\

The Sync\ folder in the Novara install directory contains NovaraSync.exe and three scripts, with no separate .NET runtime needed:

All three scripts share one data directory, %LOCALAPPDATA%\Novara\Server\data — space creation and the server can never drift apart.

The double-click flow

1. Create the spaceDouble-click 1-建空间.cmd and follow the prompts; note the two printed credentials.
2. Start the serverDouble-click 2-启动服务端.cmd. Window open = server running; closing the window stops it.
3. Add an HTTPS pathPhone access needs an HTTPS route (domain + Caddy, Tailscale, a temporary tunnel or self-signed) — see "Reverse proxy and HTTPS".
4. Pair the desktopFill https://your-public-address (or the Tailscale address), the space id and the enrollment secret; leave the space key empty.

The server listens only on 127.0.0.1:5180 — unreachable from outside by design; external access always goes through the HTTPS route.

Manual commands (advanced)

To customize the data directory or run at startup, drive the commands directly. Space creation and the server must point at the same data directory:

Data directory, quota and retention are configured with environment variables — see "Server environment variables".

Docker Desktop as an alternative

A Windows machine with Docker Desktop can use the compose files from deploy/compose/ directly, behaving exactly like Linux (the same ./data, the same --profile https). Good for keeping everything container-managed, or for a later move to a NAS.

Upgrading

A newer Novara installer ships an updated server: install over the existing one normally and restart 2-启动服务端.cmd; the data directory is untouched. Before upgrading, copy %LOCALAPPDATA%\Novara\Server\data somewhere safe.

Install Docker

You need Docker Engine and the Compose v2 plugin. Verify with:

Normal output means you can continue; otherwise install Docker Engine and the compose plugin first.

Place the files and configure

Upload the project's docker-compose.yml and .env.example from deploy/compose/, plus the Caddyfile from the parent directory, into one directory on the server (compose mounts ../Caddyfile). Then:

Both variables take your domain (e.g. sync.example.com), and the domain's A/AAAA records should point at this machine.

Open the firewall

Allow 80/tcp (certificate challenge), 443/tcp (the HTTPS entry) and 443/udp (HTTP/3). Both the cloud provider's security group and the system firewall must cover them. Beyond that, do not expose 5180 to the public internet — compose publishes it only on 127.0.0.1:5180.

Start the stack and create the space

• The space id and enrollment secret are shown exactly once — save them on the spot.
• Caddy obtains and renews certificates automatically; wait a few dozen seconds; docker compose ps should show both services running and novara-sync (healthy).
• If ./data has the wrong owner, the server refuses to start and prints chown -R 1654:1654 ./data — just run it.

Pair

Desktop → Encrypted sync → Pair: https://your-domain + space id + enrollment secret, space key empty. Then issue phone credentials. If something fails, check the 403 and certificate entries in "Troubleshooting" first.

Prerequisites

• DSM 7.2+, with Container Manager installable from the Package Center.
• A domain (required for the https profile with automatic certificates; without one, see the self-signed path in "Reverse proxy and HTTPS").
• The data directory on a local volume — do not point ./data at an SMB/NFS network share; SQLite will corrupt.

Create the Compose project

1. Upload the filesPut the project's docker-compose.yml and .env.example from deploy/compose/, plus the Caddyfile from the parent directory, into one folder on the NAS (compose mounts it as ../Caddyfile).
2. Create the projectContainer Manager → Project → Create → choose "use an existing compose", pointing at the uploaded docker-compose.yml.
3. Configure .envCopy .env.example to .env in the same folder; at minimum fill NOVARA_DOMAIN=your-domain and NOVARA_SYNC_ALLOWED_HOSTS=your-domain.

The first-run three steps

Run these in Container Manager's terminal or over SSH. Step one creates the space with a one-off container — it mounts the same ./data as the server, so credentials cannot land in the wrong place:

• The space id and enrollment secret in the output are shown exactly once — save them on the spot.
• --profile https also starts Caddy and issues certificates automatically (80/443 must be reachable); give it a few dozen seconds.
• In docker compose ps both services should be running, with novara-sync (healthy).

Pairing and what follows

Desktop → Encrypted sync → Pair: fill in https://your-domain, the space id and the enrollment secret, and leave the space key empty. After pairing you can issue phone credentials.

The bind-mounted ./data keeps the host's ownership, while the container runs as a non-root user (uid 1654). With the wrong owner the server refuses to start and prints the exact command to run:

Do what it says — this is a designed error, not a crash. Verify by restarting the NAS: the data survives and sync continues.

Differences from Synology (5.2)

Read "Synology Container Manager" first for the full flow; the table below is every difference — everything else (local disk, same data directory, non-root container, HTTPS and forwarded headers) is word-for-word identical.

Quick flow (details in the Synology page)

1. Confirm the architectureInstall Container Station from the App Center; confirm the NAS is amd64.
2. Upload the filesdocker-compose.yml, .env.example and the parent Caddyfile into a shared folder on the local storage pool.
3. Create the applicationContainer Station → Applications → Create, pointing at the compose file; put .env in the same folder (at least NOVARA_DOMAIN and NOVARA_SYNC_ALLOWED_HOSTS).
4. First-run three stepsCreate the space (run --rm) → --profile https up -d → docker compose ps shows healthy.
5. PairFill the domain, space id and enrollment secret on the desktop; leave the space key empty.

Two things to double-check

• Architecture match: confirm the pulled image architecture matches the NAS; a mismatch keeps the container from starting with exec format error-style messages.
• Directory isolation: keep the data directory on the local storage pool, never on a cross-machine network share; the web root (Novara.Web) must not contain the data directory — these rules apply on QNAP too.
• Where to run the first-run commands: Container Station's terminal, or SSH into the NAS — exactly as on Synology.

What you get

• The server ships as a net10.0 self-contained single-file build — the target machine needs no .NET runtime installed.
• The build contains the NovaraSync main program and the Novara.Web\ site directory (phone-side pages).
• The same code as the Docker image: the same NOVARA_SYNC_* environment variables, the same Caddyfile (on bare metal NOVARA_UPSTREAM defaults to 127.0.0.1:5180; inside containers it is novara-sync:5180).

Run it

1. Place itPut the build somewhere with a writable data directory and the site directory intact.
2. Set environment variablesAt least consider NOVARA_SYNC_DATA (data directory) and NOVARA_SYNC_ALLOWED_HOSTS (recommended with a fixed domain; hostname only).
3. Create the space and startSame binary, same data directory, two commands:

The server listens on loopback only. The space id and enrollment secret print exactly once; then pair on the desktop (space key left empty).

To run Caddy on bare metal: caddy run --config deploy/Caddyfile — the same reverse-proxy config Docker uses; NOVARA_UPSTREAM already defaults to the loopback address, nothing to change.

The web-root red lines

• NOVARA_SYNC_WEB_ROOT defaults to Novara.Web under the application directory and rarely needs changing; if the path does not exist, the server runs API-only.
• The web root must never contain the data directory: otherwise static serving would publish the ciphertext vault and keywrap records under /web. The server checks at startup and refuses to start (refusing to start).
• Junctions / symbolic links inside the site tree are also refused — the static provider would follow them. Move external content into the site directory if you need it.

Verify

• After startup, http://127.0.0.1:5180/web should redirect to /web/ and render.
• Pair once, stop the process, start it again — the data survives; that confirms the data directory landed in the right place.
• Accept the public route per "Reverse proxy and HTTPS"; the repo's Tools/web_selfcheck.py can re-check redirects, forwarded headers and security headers.

Four ways to get TLS

Path C gives a temporary https://<random>.trycloudflare.com domain — trusted HTTPS with zero configuration, fine for "just confirm it works on my phone once". Cloudflare sees ciphertext, keywrap and token traffic, never plaintext. The temporary domain is publicly reachable — shut it down right after checking.

The Caddyfile, in full

The repo has exactly this one reverse-proxy sample, shared by containers and bare metal (the only difference is the NOVARA_UPSTREAM environment variable). The comments keep the "why":

Only one thing to change: the domain on the first line. The two header_up lines are the basis for every absolute URL the server emits — without them, the /web redirect would point at the internal listen address. When switching to another reverse proxy, you must reproduce these two forwarded headers.

Self-signed means installing the CA

With LAN self-signing (Caddy tls internal) the phone must trust that root certificate; otherwise the page is not a secure context, crypto.subtle is not exposed at all — and "continue anyway" will not help.

• The root certificate lives in Caddy's data directory at pki/authorities/local/root.crt (Windows: %AppData%\Caddy\; Linux: ~/.local/share/caddy/).
• iOS: after installing the profile under Settings → General → VPN & Device Management, you must also enable full trust in "About → Certificate Trust Settings" — the step most often missed.
• Android: Settings → Security → Encryption & credentials → Install a certificate → CA certificate.
• Access by domain, not IP — the certificate is bound to the domain.

If those steps feel like too much, pick path A or B.

TRUSTED_PROXIES: unset = 403 on every request

Proxies on the loopback are trusted by default, no configuration needed. The Compose deployment's default already includes the Caddy container address 172.28.0.250 and the gateway 172.28.0.1. The server judges the scheme after forwarded headers take effect, so an untrusted proxy cannot claim an HTTPS it does not actually provide.

Why this is a separate step

A freshly installed server has no spaces, so the desktop's "issue token" has nothing to point at. Creating a space is a one-time administrative action, possible only through the CLI; the two credentials it prints are the only gate for device registration.

The first-run three steps

1. Create the spacedocker compose run --rm novara-sync space create --name 我的空间 (Compose path) or NovaraSync space create --name my-space (bare metal). Note the space id and enrollment secret.
2. Start the serverdocker compose --profile https up -d, or double-click 2-启动服务端.cmd, or run NovaraSync.exe --urls http://127.0.0.1:5180 directly.
3. PairDesktop → Encrypted sync → Pair: address + space id + enrollment secret, space key left empty (the first device generates its own SpaceKey).

Why run --rm instead of exec: this step does not need the server running; run starts a one-off container, mounts the same ./data, writes and exits — credentials stay in one place with the server.

CLI subcommand reference

Every subcommand supports --json. Exit codes: 0 success; 1 the operation failed (bad credentials, missing space, etc.); 2 command usage problem (like delete without --yes).

After pairing

The first device generates and keeps the SpaceKey (shown in a dialog, savable from the card). Only now does read-only access come into play: issue a token, copy the link, send it to the phone — see "Read-only mobile access".

Two volume layouts

Either way: the data directory must be on a local disk. SQLite's WAL depends on shared memory and file locks; on NFS / SMB network shares it is a corruption risk, not a performance issue.

Backup and restore

Restoring is the same in reverse: stop the server → swap the backup directory back in → start. Copy the whole directory, including novara-sync.db and spaces/.

The data directory holds nothing but ciphertext — less sensitive than the client's local vault — but treat it as sensitive files anyway. The image deliberately ships no sqlite3 CLI (one less attack surface); to inspect the database, open ./data/novara-sync.db from the host with your own tools.

Upgrading

• The v4 container format and storage schema do not change; data is forward-compatible by construction.
• Back up before upgrading (previous section).
• If your regular setup includes Caddy (https profile), keep the same docker compose --profile https up -d form used at first start.
• Rollback = move the image back to the old tag and restore the pre-upgrade data-directory backup.

Post-upgrade checks

• docker compose ps: both services running, novara-sync (healthy).
• Run one manual sync from the desktop and confirm versions advance normally.
• Restart the container (or the NAS) — the data survives. That is the acceptance bar, not an optional extra.

The full table

Compose deployment only

In compose, NOVARA_SYNC_TRUSTED_PROXIES already defaults to the Caddy container address 172.28.0.250 and the gateway 172.28.0.1; normally untouched. If you changed the subnet in docker-compose.yml, update it to match.

Three practical reminders

• .env is read by compose only; on bare metal set system environment variables directly — the names are identical on both sides.
• Environment variable changes take effect when the container is recreated (up -d); restart does not re-read .env.
• Addresses listed in trusted proxies may declare a request's scheme — list only the proxy you actually run, nothing else.

Before you start

• First locate which side the symptom is on: a message on the phone/browser, or a server startup failure / API error.
• Exact error strings (like https is required for api requests) make the best search keywords — more precise than describing the symptom.
• For server problems, read the container log first: the first line of docker compose logs novara-sync is often the answer.

Phone / browser side

Server / API side

Desktop side

• The v4 container format and storage schema are unchanged, so data is forward-compatible by construction; still, back up before upgrading.
• Windows direct-run path: install the new build over the old one and restart 2-启动服务端.cmd; the data directory is untouched.
• There is no hard binding between an older desktop and a newer server — the contract and container format are unchanged, so a mixed transition period is safe.
• Rollback = move the image back to the old tag and restore the pre-upgrade data-directory backup.

• What to do after deployment (pairing, phone access, conflicts) → the encrypted sync guide
• Quick jumps on this page: pick a deployment · troubleshooting · environment variables