synology-backup

通过 SMB 将 OpenClaw 工作区、配置和代理数据备份和恢复到 Synology NAS。使用场合：备份工作区文件、从快照恢复、检查备份状态/运行状况或设置自动备份。支持 Tailscale 以实现安全的远程 VPS 到 NAS 连接。

# Synology Backup

Backup OpenClaw data to a Synology NAS over SMB. Designed for secure, automated daily snapshots with configurable retention.

## Setup

### 1. Network Connectivity

For VPS-to-NAS backups, use [Tailscale](https://tailscale.com) for secure connectivity without exposing SMB to the internet:

1. Install Tailscale on the Synology (Package Center → search "Tailscale")
2. Install Tailscale on the VPS — see [Tailscale's official install guide](https://tailscale.com/download) for your platform
3. Join both to the same tailnet
4. Use the Synology's Tailscale IP in config

For local network setups, use the NAS local IP directly.

### 2. Synology Preparation

1. Create a dedicated user on the Synology (e.g., `openclaw-backup`) with minimal permissions
2. Create or choose a shared folder (e.g., `backups`)
3. Grant the user read/write access to **only** that folder

### 3. Credentials File

Create an SMB credentials file with restricted permissions — **never store credentials in config or scripts**:

```bash
# Create the file and set permissions (replace placeholders with your values)
touch ~/.openclaw/.smb-credentials
chmod 600 ~/.openclaw/.smb-credentials
# Edit the file and add two lines:
#   username=<your-synology-user>
#   password=<your-synology-password>
nano ~/.openclaw/.smb-credentials
```

### 4. Configuration

Create `~/.openclaw/synology-backup.json`:

```json
{
  "host": "100.x.x.x",
  "share": "backups/openclaw",
  "mountPoint": "/mnt/synology",
  "credentialsFile": "~/.openclaw/.smb-credentials",
  "smbVersion": "3.0",
  "backupPaths": [
    "~/.openclaw/workspace",
    "~/.openclaw/openclaw.json",
    "~/.openclaw/cron",
    "~/.openclaw/agents"
  ],
  "includeSubAgentWorkspaces": true,
  "retention": 7,
  "schedule": "0 3 * * *"
}
```

**Note on sensitive files:** The `.env` file (containing API keys) is **not** included in the default backup paths. If you want to back it up, add `"~/.openclaw/.env"` to `backupPaths` — but ensure your Synology share has restricted access and the dedicated user has minimal permissions.

| Field | Description | Default |
|-------|-------------|---------|
| `host` | Synology IP (Tailscale or local) | required |
| `share` | SMB share path | required |
| `mountPoint` | Local mount point | `/mnt/synology` |
| `credentialsFile` | Path to SMB credentials file | required |
| `smbVersion` | SMB protocol version | `3.0` |
| `backupPaths` | Paths to backup | workspace + config |
| `includeSubAgentWorkspaces` | Auto-include `workspace-*` dirs | `true` |
| `retention` | Days of snapshots to keep | `7` |
| `schedule` | Cron expression (host timezone) | `0 3 * * *` |

### 5. Install Dependencies

```bash
apt-get install -y cifs-utils rsync
```

### 6. Mount Setup

For persistent mounts across reboots, add to `/etc/fstab`:

```
//<host>/<share> /mnt/synology cifs credentials=<credentials-file>,vers=3.0,_netdev,nofail 0 0
```

## Usage

### Backup Now

```bash
scripts/backup.sh
```

Runs an incremental backup. First run copies everything; subsequent runs only sync changes.

### Restore a Snapshot

```bash
scripts/restore.sh [date]
```

Restores from a specific date's snapshot (e.g., `2026-02-20`). Without a date, lists available snapshots.

### Check Status

```bash
scripts/status.sh
```

Shows last backup time, snapshot count, total size, and mount health.

## What Gets Backed Up

- `~/.openclaw/workspace/` — memory, SOUL, AGENTS, skills, all workspace files
- `~/.openclaw/workspace-*/` — all sub-agent workspaces (if enabled)
- `~/.openclaw/openclaw.json` — main config
- `~/.openclaw/cron/` — cron job definitions
- `~/.openclaw/agents/` — agent configurations
- `~/.openclaw/.env` — **opt-in only** (contains API keys — add to backupPaths manually if desired)

## Snapshot Structure

```
backups/
├── 2026-02-20/
│   ├── manifest.json
│   ├── workspace/
│   ├── workspace-email/
│   ├── workspace-news/
│   ├── agents/
│   ├── cron/
│   └── openclaw.json
├── 2026-02-19/
└── ...
```

## Security Notes

- **Credentials**: Always use a dedicated credentials file with restricted permissions (`chmod 600`). Never inline secrets in config files, scripts, or fstab.
- **Network**: Use Tailscale or a VPN for remote backups. Never expose SMB (port 445) to the public internet.
- **Sensitive data**: The `.env` file contains API keys and is excluded from default backup paths. Only include it if your NAS share is properly secured with restricted user permissions.
- **NAS user**: Create a dedicated Synology user with access to only the backup share — not an admin account.
- **Retention**: Old snapshots are pruned by moving them to the Synology trash (if supported) or deleting them. Increase retention for critical environments.

---

## 中文说明

# Synology 备份

通过 SMB 将 OpenClaw 数据备份到 Synology NAS。专为安全、自动化的每日快照而设计，并支持可配置的保留策略。

## 设置

### 1. 网络连通性

对于 VPS 到 NAS 的备份，使用 [Tailscale](https://tailscale.com) 实现安全连接，而无需将 SMB 暴露到互联网：

1. 在 Synology 上安装 Tailscale（套件中心 → 搜索 "Tailscale"）
2. 在 VPS 上安装 Tailscale —— 请参阅适用于你平台的 [Tailscale 官方安装指南](https://tailscale.com/download)
3. 将两者加入同一个 tailnet
4. 在配置中使用 Synology 的 Tailscale IP

对于本地网络设置，直接使用 NAS 的本地 IP。

### 2. Synology 准备

1. 在 Synology 上创建一个专用用户（例如 `openclaw-backup`），并授予最小权限
2. 创建或选择一个共享文件夹（例如 `backups`）
3. **仅**授予该用户对该文件夹的读/写访问权限

### 3. 凭据文件

创建一个具有受限权限的 SMB 凭据文件 —— **切勿将凭据存储在配置或脚本中**：

```bash
# Create the file and set permissions (replace placeholders with your values)
touch ~/.openclaw/.smb-credentials
chmod 600 ~/.openclaw/.smb-credentials
# Edit the file and add two lines:
#   username=<your-synology-user>
#   password=<your-synology-password>
nano ~/.openclaw/.smb-credentials
```

### 4. 配置

创建 `~/.openclaw/synology-backup.json`：

```json
{
  "host": "100.x.x.x",
  "share": "backups/openclaw",
  "mountPoint": "/mnt/synology",
  "credentialsFile": "~/.openclaw/.smb-credentials",
  "smbVersion": "3.0",
  "backupPaths": [
    "~/.openclaw/workspace",
    "~/.openclaw/openclaw.json",
    "~/.openclaw/cron",
    "~/.openclaw/agents"
  ],
  "includeSubAgentWorkspaces": true,
  "retention": 7,
  "schedule": "0 3 * * *"
}
```

**关于敏感文件的说明：** `.env` 文件（包含 API 密钥）**不**包含在默认备份路径中。如果你想备份它，请将 `"~/.openclaw/.env"` 添加到 `backupPaths` —— 但要确保你的 Synology 共享具有受限访问权限，且专用用户拥有最小权限。

| 字段 | 描述 | 默认值 |
|-------|-------------|---------|
| `host` | Synology IP（Tailscale 或本地） | 必填 |
| `share` | SMB 共享路径 | 必填 |
| `mountPoint` | 本地挂载点 | `/mnt/synology` |
| `credentialsFile` | SMB 凭据文件的路径 | 必填 |
| `smbVersion` | SMB 协议版本 | `3.0` |
| `backupPaths` | 要备份的路径 | 工作区 + 配置 |
| `includeSubAgentWorkspaces` | 自动包含 `workspace-*` 目录 | `true` |
| `retention` | 保留快照的天数 | `7` |
| `schedule` | Cron 表达式（主机时区） | `0 3 * * *` |

### 5. 安装依赖

```bash
apt-get install -y cifs-utils rsync
```

### 6. 挂载设置

为了在重启后保持挂载，添加到 `/etc/fstab`：

```
//<host>/<share> /mnt/synology cifs credentials=<credentials-file>,vers=3.0,_netdev,nofail 0 0
```

## 用法

### 立即备份

```bash
scripts/backup.sh
```

执行增量备份。首次运行会复制所有内容；后续运行仅同步更改。

### 恢复快照

```bash
scripts/restore.sh [date]
```

从特定日期的快照恢复（例如 `2026-02-20`）。不指定日期时，列出可用的快照。

### 检查状态

```bash
scripts/status.sh
```

显示上次备份时间、快照数量、总大小和挂载运行状况。

## 备份的内容

- `~/.openclaw/workspace/` —— 记忆、SOUL、AGENTS、技能、所有工作区文件
- `~/.openclaw/workspace-*/` —— 所有子代理工作区（如果已启用）
- `~/.openclaw/openclaw.json` —— 主配置
- `~/.openclaw/cron/` —— cron 任务定义
- `~/.openclaw/agents/` —— 代理配置
- `~/.openclaw/.env` —— **仅在选择加入时**（包含 API 密钥 —— 如需要请手动添加到 backupPaths）

## 快照结构

```
backups/
├── 2026-02-20/
│   ├── manifest.json
│   ├── workspace/
│   ├── workspace-email/
│   ├── workspace-news/
│   ├── agents/
│   ├── cron/
│   └── openclaw.json
├── 2026-02-19/
└── ...
```

## 安全说明

- **凭据**：始终使用具有受限权限（`chmod 600`）的专用凭据文件。切勿在配置文件、脚本或 fstab 中内联机密。
- **网络**：对远程备份使用 Tailscale 或 VPN。切勿将 SMB（端口 445）暴露到公共互联网。
- **敏感数据**：`.env` 文件包含 API 密钥，已从默认备份路径中排除。仅当你的 NAS 共享通过受限用户权限得到妥善保护时才包含它。
- **NAS 用户**：创建一个仅可访问备份共享的专用 Synology 用户 —— 而非管理员账户。
- **保留策略**：旧快照会通过移入 Synology 回收站（如支持）或删除来进行清理。对于关键环境，可增加保留天数。