docs: enhance Write Back section with filer.remote.sync comparison

Enhanced the "Write Back changes to Remote Storage" section to explain
both continuous sync (filer.remote.sync) and on-demand sync (remote.copy.local)
options. Added a detailed comparison table showing when to use each approach,
including features, use cases, and resource considerations.
Chris Lu committed 2026-01-15 01:02:52 -08:00
1 parent 5972a14549
commit adea875b7e
1 file changed
+39 -3
+39 -3
@@ -51,18 +51,54 @@ This will update local metadata accordingly and still keep file contents that ar
If the data on the cloud can changed often, you can create a cronjob to run it. Or you can add this command to the admin scripts defined in `master.toml`, to run it regularly.
## Write Back changes to Remote Storage
## Write Back Changes to Remote Storage
If the mounted directory is only for reading, you can skip this step.
If local changes need to be synchronized to the cloud storage, a separate process `weed filer.remote.sync -dir=xxx` should be started.
This process will listen to filer change events, and write any changes back to the remote storage.
If local changes need to be synchronized to the cloud storage, you have two options:
### Option 1: Continuous Sync with `weed filer.remote.sync`
For **continuous, real-time synchronization**, start a separate process `weed filer.remote.sync -dir=xxx`. This process will listen to filer change events and write any changes back to the remote storage automatically.
```
weed filer.remote.sync -filer=<filerHost>:<filerPort> -dir=xxx
```
The process is designed to be worry-free. It should automatically resume if stopped, and can reconnect automatically.
**Use this when:**
- You need real-time synchronization of all changes
- Files are being continuously created, modified, or deleted
- You want automatic background synchronization
### Option 2: On-Demand Sync with `remote.copy.local`
For **on-demand, batch synchronization** of local-only files, use the `remote.copy.local` command in `weed shell`. This is useful for one-time or scheduled backups.
**Use this when:**
- You have existing local files that were never synced to remote
- You deleted filer logs and need to re-sync existing files
- You want to run periodic batch backups via cron
- You need fine-grained control over which files to sync (using filters)
### Comparison: `filer.remote.sync` vs `remote.copy.local`
| Feature | `weed filer.remote.sync` | `remote.copy.local` |
|---------|-------------------------|---------------------|
| **Type** | Long-running daemon process | One-time command |
| **Synchronization** | Continuous, real-time | On-demand, batch |
| **Trigger** | Automatic (on file changes) | Manual or cron-based |
| **File Selection** | All changes in directory | Selective (with filters) |
| **Use Case** | Active write workloads | Batch backups, recovery |
| **Setup** | Requires separate process | Run in weed shell |
| **Filters** | No (syncs everything) | Yes (`-include`, `-exclude`, size filters) |
| **Dry Run** | No | Yes (`-dryRun`) |
| **Force Update** | Automatic | Optional (`-forceUpdate`) |
| **Resource Usage** | Continuous (low overhead) | Temporary (during execution) |
| **Best For** | Production environments | Maintenance, recovery, scheduled backups |
## Copy Local-Only Files to Remote
The `remote.copy.local` command synchronizes local-only files to remote storage. This is useful when you have files that were created locally and need to be backed up to remote storage.