diff --git a/src/.vuepress/sidebar/V1.3.x/en.ts b/src/.vuepress/sidebar/V1.3.x/en.ts index 4f50ef3d1..828ee130c 100644 --- a/src/.vuepress/sidebar/V1.3.x/en.ts +++ b/src/.vuepress/sidebar/V1.3.x/en.ts @@ -159,6 +159,7 @@ export const enSidebar = { { text: 'TsFile Import Export(V1.3.0/1/2)', link: 'TsFile-Import-Export-Tool' }, { text: 'Data Import(V1.3.3)', link: 'Data-Import-Tool' }, { text: 'Data Export(V1.3.3)', link: 'Data-Export-Tool' }, + { text: 'Full Backup Tool(V1.3.2)', link: 'Backup-Tool' }, { text: 'Health Check Tool(V1.3.2)', link: 'Health-Check-Tool' }, ], }, diff --git a/src/.vuepress/sidebar/V1.3.x/zh.ts b/src/.vuepress/sidebar/V1.3.x/zh.ts index f5693bb93..65ac38299 100644 --- a/src/.vuepress/sidebar/V1.3.x/zh.ts +++ b/src/.vuepress/sidebar/V1.3.x/zh.ts @@ -146,6 +146,7 @@ export const zhSidebar = { { text: 'TsFile导入导出(V1.3.0/1/2)', link: 'TsFile-Import-Export-Tool' }, { text: '数据导入(V1.3.3)', link: 'Data-Import-Tool' }, { text: '数据导出(V1.3.3)', link: 'Data-Export-Tool' }, + { text: '全量备份工具(V1.3.2)', link: 'Backup-Tool' }, { text: '健康检查工具(V1.3.2)', link: 'Health-Check-Tool' }, ], }, diff --git a/src/.vuepress/sidebar/V2.0.x/en-Tree.ts b/src/.vuepress/sidebar/V2.0.x/en-Tree.ts index a15581bf9..9802803f3 100644 --- a/src/.vuepress/sidebar/V2.0.x/en-Tree.ts +++ b/src/.vuepress/sidebar/V2.0.x/en-Tree.ts @@ -140,6 +140,7 @@ export const enSidebar = { { text: 'Cluster Management Tool', link: 'Maintenance-Tool_apache' }, { text: 'Data Import', link: 'Data-Import-Tool' }, { text: 'Data Export', link: 'Data-Export-Tool' }, + { text: 'Full Backup Tool', link: 'Backup-Tool' }, { text: 'Health Check Tool', link: 'Health-Check-Tool' }, ], }, diff --git a/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts b/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts index 4f5f8d65f..84b92e777 100644 --- a/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts +++ b/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts @@ -127,6 +127,7 @@ export const zhSidebar = { { text: '集群管理工具', link: 'Maintenance-Tool_apache' }, { text: '数据导入', link: 'Data-Import-Tool' }, { text: '数据导出', link: 'Data-Export-Tool' }, + { text: '全量备份工具', link: 'Backup-Tool' }, { text: '健康检查工具', link: 'Health-Check-Tool' }, ], }, diff --git a/src/.vuepress/sidebar_timecho/V1.3.x/en.ts b/src/.vuepress/sidebar_timecho/V1.3.x/en.ts index 1329b9383..e10c5233f 100644 --- a/src/.vuepress/sidebar_timecho/V1.3.x/en.ts +++ b/src/.vuepress/sidebar_timecho/V1.3.x/en.ts @@ -173,6 +173,7 @@ export const enSidebar = { { text: 'TsFile Import Export(V1.3.0/1/2)', link: 'TsFile-Import-Export-Tool' }, { text: 'Data Import(V1.3.3)', link: 'Data-Import-Tool' }, { text: 'Data Export(V1.3.3)', link: 'Data-Export-Tool' }, + { text: 'Full Backup Tool(V1.3.2)', link: 'Backup-Tool' }, { text: 'Health Check Tool(V1.3.2)', link: 'Health-Check-Tool' }, ], }, diff --git a/src/.vuepress/sidebar_timecho/V1.3.x/zh.ts b/src/.vuepress/sidebar_timecho/V1.3.x/zh.ts index ded1f7c05..7f1b9533b 100644 --- a/src/.vuepress/sidebar_timecho/V1.3.x/zh.ts +++ b/src/.vuepress/sidebar_timecho/V1.3.x/zh.ts @@ -156,6 +156,7 @@ export const zhSidebar = { { text: 'TsFile导入导出(V1.3.0/1/2)', link: 'TsFile-Import-Export-Tool' }, { text: '数据导入(V1.3.3)', link: 'Data-Import-Tool' }, { text: '数据导出(V1.3.3)', link: 'Data-Export-Tool' }, + { text: '全量备份工具(V1.3.2)', link: 'Backup-Tool' }, { text: '健康检查工具(V1.3.2)', link: 'Health-Check-Tool' }, ], }, diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts b/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts index e3b34874d..318e22315 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts @@ -154,6 +154,7 @@ export const enSidebar = { { text: 'Cluster Management Tool', link: 'Maintenance-Tool_timecho' }, { text: 'Data Import', link: 'Data-Import-Tool' }, { text: 'Data Export', link: 'Data-Export-Tool' }, + { text: 'Full Backup Tool', link: 'Backup-Tool' }, { text: 'Health Check Tool', link: 'Health-Check-Tool' }, ], }, diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts index 44847c82e..65a9dc222 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts @@ -137,6 +137,7 @@ export const zhSidebar = { { text: '集群管理工具', link: 'Maintenance-Tool_timecho' }, { text: '数据导入', link: 'Data-Import-Tool' }, { text: '数据导出', link: 'Data-Export-Tool' }, + { text: '全量备份工具', link: 'Backup-Tool' }, { text: '健康检查工具', link: 'Health-Check-Tool' }, ], }, diff --git a/src/UserGuide/Master/Tree/Tools-System/Backup-Tool.md b/src/UserGuide/Master/Tree/Tools-System/Backup-Tool.md new file mode 100644 index 000000000..5759f2a20 --- /dev/null +++ b/src/UserGuide/Master/Tree/Tools-System/Backup-Tool.md @@ -0,0 +1,135 @@ + + +# Backup Tool + +## 1. Overview + +The IoTDB Full Backup Tool is designed to create a full backup of a single IoTDB node’s data via hard links to a specified local directory. The backup can then be directly started and joined to the original cluster. The tool offers two modes: **Quick Mirror Mode** and **Manual Backup Path Mode**. + +> **Notes**: +> +> * **Stop the IoTDB service before starting the backup**. +> * The script runs in the background by default, and logs are saved to log files during execution. + + +## 2. Backup Modes + +### 2.1 Mode 1: Quick Mirror Mode + +#### Usage + +```bash +backup.sh/backup.bat -quick -node xxx +# Optional values for xxx are shown in the following examples + +backup.sh/backup.bat -quick -node +# Back up all nodes to the default path + +backup.sh/backup.bat -quick -node all +# Back up all nodes to the default path + +backup.sh/backup.bat -quick -node confignode +# Back up only the ConfigNode to the default path + +backup.sh/backup.bat -quick -node datanode +# Back up only the DataNode to the default path +``` + +#### Parameter Descriptions + +| **Parameter** | **Description** | **Required** | +| ----------------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---------------------- | +| `-quick` | Enables Quick Mirror Mode. | No | +| `-node` | Specifies the node type to back up. Options: `all`, `datanode`, or `confignode`. Default: `all`.
`all`: Back up both DataNode and ConfigNode.
`datanode`: Back up only the DataNode.
`confignode`: Back up only the ConfigNode. | No | + +**Process Details**: + +1. Check if the `_backup` folder already exists in the current IoTDB directory or paths specified in the configuration file. If it exists, the tool exits with the error: `The backup folder already exists`. +> When the backup folder already exists, you can try the following solutions: +> * Delete the existing _backup folder and retry the backup. +> * Modify the backup path to avoid conflicts. + +2. Create hard links from the original `dn_data_dirs` paths to the corresponding `_backup` paths. + * Example: If `dn_data_dirs=/data/iotdb/data/datanode/data`, the backup data will be stored in `/data/iotdb/data/datanode/data_backup`. +3. Copy other files from the IoTDB directory (e.g., `/data/iotdb`) to the `_backup` path (e.g., `/data/iotdb_backup`). + + +### 2.2 Mode 2: Manual Backup Path Mode + +#### Usage + +```bash +backup.sh -node xxx -targetdir xxx -targetdatadir xxx -targetwaldir xxx +``` + +#### Parameter Descriptions + +| **Parameter** | **Description** | **Required** | +| ----------------------- | -------------------------------------------------------------------------------------------- | ---------------------- | +| `-node` | Node type to back up (`all`, `datanode`, or `confignode`). Default: `all`. | No | +| `-targetdir` | Target directory for backing up the IoTDB folder. | **Yes** | +| `-targetdatadir` | Target path for `dn_data_dirs` files. Default: `targetdir/data/datanode/data`. | No | +| `-targetwaldir` | Target path for `dn_wal_dirs` files. Default: `targetdir/data/datanode/wal`. | No | + +**Process Details**: + +1. The `-targetdir` parameter is mandatory. If missing, the tool exits with the error: `-targetdir cannot be empty. The backup folder must be specified`. +2. Validate consistency between configuration paths (`dn_data_dirs`, `dn_wal_dirs`) and parameters (`-targetdatadir`, `-targetwaldir`): + + * If `-targetdatadir` or `-targetwaldir` is a single path, it is considered consistent. + * If the number of source paths (from configuration) does not match the target paths, the tool exits with the error: `-targetdatadir parameter exception: the number of original paths does not match the specified paths`. +3. Check if `-targetdatadir` paths are on the same disk as the original paths: + + * **Same disk**: Attempt to create hard links. If hard links fail, copy files instead. + * **Different disk**: Copy files directly. +4. Path Matching Rules + +* **Many-to-One**: Multiple source paths can be backed up to a single target path. +* **One-to-One**: A single source path can be backed up to a single target path. +* **Many-to-Many**: Multiple source paths can be backed up to multiple target paths, but the pattern must match. + +#### Examples + +| **Configuration Paths** | **`-targetdatadir` Paths** | **Result** | +| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | +| `/data/iotdb/data/datanode/data` | `/data/iotdb_backup/data/datanode/data` |**Consistent** | +| `/data/iotdb/data/datanode/data` | `/data/iotdb_backup/data/datanode/data1,/data/iotdb_backup/data/datanode/data2` | **Inconsistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2` | `/data/iotdb_backup/data/datanode/data` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2` | `/data/iotdb_backup/data/datanode/data3,/data/iotdb_backup/data/datanode/data4` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3` | `/data/iotdb_backup/data/datanode/data` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3` | `/data/iotdb_backup/data/datanode/data1;/data/iotdb_backup/data/datanode/data1` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3` | `/data/iotdb_backup/data/datanode/data1,/data/iotdb_backup/data/datanode/data3;/data/iotdb_backup/data/datanode/data` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3` | `/data/iotdb_backup/data/datanode/data1,/data/iotdb_backup/data/datanode/data3;/data/iotdb_backup/data/datanode/data1,/data/iotdb_backup/data/datanode/data4` | **Inconsistent** | + +#### Path Matching Rules Summary + +* **Paths separated by `;` only**: + * `-targetdatadir` can be a single path (no `;` or `,`). + * `-targetdatadir` can also use `;` to split paths, but the count must match the source paths. +* **Paths separated by `,` only**: + * `-targetdatadir` can be a single path (no `;` or `,`). + * `-targetdatadir` can also use `,` to split paths, but the count must match the source paths. +* **Paths with both `;` and `,`**: + * `-targetdatadir` can be a single path (no `;` or `,`). + * Split paths first by `;`, then by `,`. The number of paths at each level must match. + +> **Note**: The `dn_wal_dirs` parameter (for WAL paths) follows the same rules as `dn_data_dirs`. diff --git a/src/UserGuide/V1.3.x/Tools-System/Backup-Tool.md b/src/UserGuide/V1.3.x/Tools-System/Backup-Tool.md new file mode 100644 index 000000000..e3b721336 --- /dev/null +++ b/src/UserGuide/V1.3.x/Tools-System/Backup-Tool.md @@ -0,0 +1,136 @@ + + +# Backup Tool + +## 1. Overview + +The IoTDB Full Backup Tool is designed to create a full backup of a single IoTDB node’s data via hard links to a specified local directory. The backup can then be directly started and joined to the original cluster. The tool offers two modes: **Quick Mirror Mode** and **Manual Backup Path Mode**. + +> **Notes**: +> +> * **Stop the IoTDB service before starting the backup**. +> * The script runs in the background by default, and logs are saved to log files during execution. +> * **IoTDB version requirement**: Must be **v1.3.2 or higher**. + + +## 2. Backup Modes + +### 2.1 Mode 1: Quick Mirror Mode + +#### Usage + +```bash +backup.sh/backup.bat -quick -node xxx +# Optional values for xxx are shown in the following examples + +backup.sh/backup.bat -quick -node +# Back up all nodes to the default path + +backup.sh/backup.bat -quick -node all +# Back up all nodes to the default path + +backup.sh/backup.bat -quick -node confignode +# Back up only the ConfigNode to the default path + +backup.sh/backup.bat -quick -node datanode +# Back up only the DataNode to the default path +``` + +#### Parameter Descriptions + +| **Parameter** | **Description** | **Required** | +| ----------------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---------------------- | +| `-quick` | Enables Quick Mirror Mode. | No | +| `-node` | Specifies the node type to back up. Options: `all`, `datanode`, or `confignode`. Default: `all`.
`all`: Back up both DataNode and ConfigNode.
`datanode`: Back up only the DataNode.
`confignode`: Back up only the ConfigNode. | No | + +**Process Details**: + +1. Check if the `_backup` folder already exists in the current IoTDB directory or paths specified in the configuration file. If it exists, the tool exits with the error: `The backup folder already exists`. +> When the backup folder already exists, you can try the following solutions: +> * Delete the existing _backup folder and retry the backup. +> * Modify the backup path to avoid conflicts. + +2. Create hard links from the original `dn_data_dirs` paths to the corresponding `_backup` paths. + * Example: If `dn_data_dirs=/data/iotdb/data/datanode/data`, the backup data will be stored in `/data/iotdb/data/datanode/data_backup`. +3. Copy other files from the IoTDB directory (e.g., `/data/iotdb`) to the `_backup` path (e.g., `/data/iotdb_backup`). + + +### 2.2 Mode 2: Manual Backup Path Mode + +#### Usage + +```bash +backup.sh -node xxx -targetdir xxx -targetdatadir xxx -targetwaldir xxx +``` + +#### Parameter Descriptions + +| **Parameter** | **Description** | **Required** | +| ----------------------- | -------------------------------------------------------------------------------------------- | ---------------------- | +| `-node` | Node type to back up (`all`, `datanode`, or `confignode`). Default: `all`. | No | +| `-targetdir` | Target directory for backing up the IoTDB folder. | **Yes** | +| `-targetdatadir` | Target path for `dn_data_dirs` files. Default: `targetdir/data/datanode/data`. | No | +| `-targetwaldir` | Target path for `dn_wal_dirs` files. Default: `targetdir/data/datanode/wal`. | No | + +**Process Details**: + +1. The `-targetdir` parameter is mandatory. If missing, the tool exits with the error: `-targetdir cannot be empty. The backup folder must be specified`. +2. Validate consistency between configuration paths (`dn_data_dirs`, `dn_wal_dirs`) and parameters (`-targetdatadir`, `-targetwaldir`): + + * If `-targetdatadir` or `-targetwaldir` is a single path, it is considered consistent. + * If the number of source paths (from configuration) does not match the target paths, the tool exits with the error: `-targetdatadir parameter exception: the number of original paths does not match the specified paths`. +3. Check if `-targetdatadir` paths are on the same disk as the original paths: + + * **Same disk**: Attempt to create hard links. If hard links fail, copy files instead. + * **Different disk**: Copy files directly. +4. Path Matching Rules + +* **Many-to-One**: Multiple source paths can be backed up to a single target path. +* **One-to-One**: A single source path can be backed up to a single target path. +* **Many-to-Many**: Multiple source paths can be backed up to multiple target paths, but the pattern must match. + +#### Examples + +| **Configuration Paths** | **`-targetdatadir` Paths** | **Result** | +| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | +| `/data/iotdb/data/datanode/data` | `/data/iotdb_backup/data/datanode/data` |**Consistent** | +| `/data/iotdb/data/datanode/data` | `/data/iotdb_backup/data/datanode/data1,/data/iotdb_backup/data/datanode/data2` | **Inconsistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2` | `/data/iotdb_backup/data/datanode/data` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2` | `/data/iotdb_backup/data/datanode/data3,/data/iotdb_backup/data/datanode/data4` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3` | `/data/iotdb_backup/data/datanode/data` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3` | `/data/iotdb_backup/data/datanode/data1;/data/iotdb_backup/data/datanode/data1` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3` | `/data/iotdb_backup/data/datanode/data1,/data/iotdb_backup/data/datanode/data3;/data/iotdb_backup/data/datanode/data` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3` | `/data/iotdb_backup/data/datanode/data1,/data/iotdb_backup/data/datanode/data3;/data/iotdb_backup/data/datanode/data1,/data/iotdb_backup/data/datanode/data4` | **Inconsistent** | + +#### Path Matching Rules Summary + +* **Paths separated by `;` only**: + * `-targetdatadir` can be a single path (no `;` or `,`). + * `-targetdatadir` can also use `;` to split paths, but the count must match the source paths. +* **Paths separated by `,` only**: + * `-targetdatadir` can be a single path (no `;` or `,`). + * `-targetdatadir` can also use `,` to split paths, but the count must match the source paths. +* **Paths with both `;` and `,`**: + * `-targetdatadir` can be a single path (no `;` or `,`). + * Split paths first by `;`, then by `,`. The number of paths at each level must match. + +> **Note**: The `dn_wal_dirs` parameter (for WAL paths) follows the same rules as `dn_data_dirs`. diff --git a/src/UserGuide/dev-1.3/Tools-System/Backup-Tool.md b/src/UserGuide/dev-1.3/Tools-System/Backup-Tool.md new file mode 100644 index 000000000..e3b721336 --- /dev/null +++ b/src/UserGuide/dev-1.3/Tools-System/Backup-Tool.md @@ -0,0 +1,136 @@ + + +# Backup Tool + +## 1. Overview + +The IoTDB Full Backup Tool is designed to create a full backup of a single IoTDB node’s data via hard links to a specified local directory. The backup can then be directly started and joined to the original cluster. The tool offers two modes: **Quick Mirror Mode** and **Manual Backup Path Mode**. + +> **Notes**: +> +> * **Stop the IoTDB service before starting the backup**. +> * The script runs in the background by default, and logs are saved to log files during execution. +> * **IoTDB version requirement**: Must be **v1.3.2 or higher**. + + +## 2. Backup Modes + +### 2.1 Mode 1: Quick Mirror Mode + +#### Usage + +```bash +backup.sh/backup.bat -quick -node xxx +# Optional values for xxx are shown in the following examples + +backup.sh/backup.bat -quick -node +# Back up all nodes to the default path + +backup.sh/backup.bat -quick -node all +# Back up all nodes to the default path + +backup.sh/backup.bat -quick -node confignode +# Back up only the ConfigNode to the default path + +backup.sh/backup.bat -quick -node datanode +# Back up only the DataNode to the default path +``` + +#### Parameter Descriptions + +| **Parameter** | **Description** | **Required** | +| ----------------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---------------------- | +| `-quick` | Enables Quick Mirror Mode. | No | +| `-node` | Specifies the node type to back up. Options: `all`, `datanode`, or `confignode`. Default: `all`.
`all`: Back up both DataNode and ConfigNode.
`datanode`: Back up only the DataNode.
`confignode`: Back up only the ConfigNode. | No | + +**Process Details**: + +1. Check if the `_backup` folder already exists in the current IoTDB directory or paths specified in the configuration file. If it exists, the tool exits with the error: `The backup folder already exists`. +> When the backup folder already exists, you can try the following solutions: +> * Delete the existing _backup folder and retry the backup. +> * Modify the backup path to avoid conflicts. + +2. Create hard links from the original `dn_data_dirs` paths to the corresponding `_backup` paths. + * Example: If `dn_data_dirs=/data/iotdb/data/datanode/data`, the backup data will be stored in `/data/iotdb/data/datanode/data_backup`. +3. Copy other files from the IoTDB directory (e.g., `/data/iotdb`) to the `_backup` path (e.g., `/data/iotdb_backup`). + + +### 2.2 Mode 2: Manual Backup Path Mode + +#### Usage + +```bash +backup.sh -node xxx -targetdir xxx -targetdatadir xxx -targetwaldir xxx +``` + +#### Parameter Descriptions + +| **Parameter** | **Description** | **Required** | +| ----------------------- | -------------------------------------------------------------------------------------------- | ---------------------- | +| `-node` | Node type to back up (`all`, `datanode`, or `confignode`). Default: `all`. | No | +| `-targetdir` | Target directory for backing up the IoTDB folder. | **Yes** | +| `-targetdatadir` | Target path for `dn_data_dirs` files. Default: `targetdir/data/datanode/data`. | No | +| `-targetwaldir` | Target path for `dn_wal_dirs` files. Default: `targetdir/data/datanode/wal`. | No | + +**Process Details**: + +1. The `-targetdir` parameter is mandatory. If missing, the tool exits with the error: `-targetdir cannot be empty. The backup folder must be specified`. +2. Validate consistency between configuration paths (`dn_data_dirs`, `dn_wal_dirs`) and parameters (`-targetdatadir`, `-targetwaldir`): + + * If `-targetdatadir` or `-targetwaldir` is a single path, it is considered consistent. + * If the number of source paths (from configuration) does not match the target paths, the tool exits with the error: `-targetdatadir parameter exception: the number of original paths does not match the specified paths`. +3. Check if `-targetdatadir` paths are on the same disk as the original paths: + + * **Same disk**: Attempt to create hard links. If hard links fail, copy files instead. + * **Different disk**: Copy files directly. +4. Path Matching Rules + +* **Many-to-One**: Multiple source paths can be backed up to a single target path. +* **One-to-One**: A single source path can be backed up to a single target path. +* **Many-to-Many**: Multiple source paths can be backed up to multiple target paths, but the pattern must match. + +#### Examples + +| **Configuration Paths** | **`-targetdatadir` Paths** | **Result** | +| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | +| `/data/iotdb/data/datanode/data` | `/data/iotdb_backup/data/datanode/data` |**Consistent** | +| `/data/iotdb/data/datanode/data` | `/data/iotdb_backup/data/datanode/data1,/data/iotdb_backup/data/datanode/data2` | **Inconsistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2` | `/data/iotdb_backup/data/datanode/data` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2` | `/data/iotdb_backup/data/datanode/data3,/data/iotdb_backup/data/datanode/data4` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3` | `/data/iotdb_backup/data/datanode/data` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3` | `/data/iotdb_backup/data/datanode/data1;/data/iotdb_backup/data/datanode/data1` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3` | `/data/iotdb_backup/data/datanode/data1,/data/iotdb_backup/data/datanode/data3;/data/iotdb_backup/data/datanode/data` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3` | `/data/iotdb_backup/data/datanode/data1,/data/iotdb_backup/data/datanode/data3;/data/iotdb_backup/data/datanode/data1,/data/iotdb_backup/data/datanode/data4` | **Inconsistent** | + +#### Path Matching Rules Summary + +* **Paths separated by `;` only**: + * `-targetdatadir` can be a single path (no `;` or `,`). + * `-targetdatadir` can also use `;` to split paths, but the count must match the source paths. +* **Paths separated by `,` only**: + * `-targetdatadir` can be a single path (no `;` or `,`). + * `-targetdatadir` can also use `,` to split paths, but the count must match the source paths. +* **Paths with both `;` and `,`**: + * `-targetdatadir` can be a single path (no `;` or `,`). + * Split paths first by `;`, then by `,`. The number of paths at each level must match. + +> **Note**: The `dn_wal_dirs` parameter (for WAL paths) follows the same rules as `dn_data_dirs`. diff --git a/src/UserGuide/latest/Tools-System/Backup-Tool.md b/src/UserGuide/latest/Tools-System/Backup-Tool.md new file mode 100644 index 000000000..5759f2a20 --- /dev/null +++ b/src/UserGuide/latest/Tools-System/Backup-Tool.md @@ -0,0 +1,135 @@ + + +# Backup Tool + +## 1. Overview + +The IoTDB Full Backup Tool is designed to create a full backup of a single IoTDB node’s data via hard links to a specified local directory. The backup can then be directly started and joined to the original cluster. The tool offers two modes: **Quick Mirror Mode** and **Manual Backup Path Mode**. + +> **Notes**: +> +> * **Stop the IoTDB service before starting the backup**. +> * The script runs in the background by default, and logs are saved to log files during execution. + + +## 2. Backup Modes + +### 2.1 Mode 1: Quick Mirror Mode + +#### Usage + +```bash +backup.sh/backup.bat -quick -node xxx +# Optional values for xxx are shown in the following examples + +backup.sh/backup.bat -quick -node +# Back up all nodes to the default path + +backup.sh/backup.bat -quick -node all +# Back up all nodes to the default path + +backup.sh/backup.bat -quick -node confignode +# Back up only the ConfigNode to the default path + +backup.sh/backup.bat -quick -node datanode +# Back up only the DataNode to the default path +``` + +#### Parameter Descriptions + +| **Parameter** | **Description** | **Required** | +| ----------------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---------------------- | +| `-quick` | Enables Quick Mirror Mode. | No | +| `-node` | Specifies the node type to back up. Options: `all`, `datanode`, or `confignode`. Default: `all`.
`all`: Back up both DataNode and ConfigNode.
`datanode`: Back up only the DataNode.
`confignode`: Back up only the ConfigNode. | No | + +**Process Details**: + +1. Check if the `_backup` folder already exists in the current IoTDB directory or paths specified in the configuration file. If it exists, the tool exits with the error: `The backup folder already exists`. +> When the backup folder already exists, you can try the following solutions: +> * Delete the existing _backup folder and retry the backup. +> * Modify the backup path to avoid conflicts. + +2. Create hard links from the original `dn_data_dirs` paths to the corresponding `_backup` paths. + * Example: If `dn_data_dirs=/data/iotdb/data/datanode/data`, the backup data will be stored in `/data/iotdb/data/datanode/data_backup`. +3. Copy other files from the IoTDB directory (e.g., `/data/iotdb`) to the `_backup` path (e.g., `/data/iotdb_backup`). + + +### 2.2 Mode 2: Manual Backup Path Mode + +#### Usage + +```bash +backup.sh -node xxx -targetdir xxx -targetdatadir xxx -targetwaldir xxx +``` + +#### Parameter Descriptions + +| **Parameter** | **Description** | **Required** | +| ----------------------- | -------------------------------------------------------------------------------------------- | ---------------------- | +| `-node` | Node type to back up (`all`, `datanode`, or `confignode`). Default: `all`. | No | +| `-targetdir` | Target directory for backing up the IoTDB folder. | **Yes** | +| `-targetdatadir` | Target path for `dn_data_dirs` files. Default: `targetdir/data/datanode/data`. | No | +| `-targetwaldir` | Target path for `dn_wal_dirs` files. Default: `targetdir/data/datanode/wal`. | No | + +**Process Details**: + +1. The `-targetdir` parameter is mandatory. If missing, the tool exits with the error: `-targetdir cannot be empty. The backup folder must be specified`. +2. Validate consistency between configuration paths (`dn_data_dirs`, `dn_wal_dirs`) and parameters (`-targetdatadir`, `-targetwaldir`): + + * If `-targetdatadir` or `-targetwaldir` is a single path, it is considered consistent. + * If the number of source paths (from configuration) does not match the target paths, the tool exits with the error: `-targetdatadir parameter exception: the number of original paths does not match the specified paths`. +3. Check if `-targetdatadir` paths are on the same disk as the original paths: + + * **Same disk**: Attempt to create hard links. If hard links fail, copy files instead. + * **Different disk**: Copy files directly. +4. Path Matching Rules + +* **Many-to-One**: Multiple source paths can be backed up to a single target path. +* **One-to-One**: A single source path can be backed up to a single target path. +* **Many-to-Many**: Multiple source paths can be backed up to multiple target paths, but the pattern must match. + +#### Examples + +| **Configuration Paths** | **`-targetdatadir` Paths** | **Result** | +| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | +| `/data/iotdb/data/datanode/data` | `/data/iotdb_backup/data/datanode/data` |**Consistent** | +| `/data/iotdb/data/datanode/data` | `/data/iotdb_backup/data/datanode/data1,/data/iotdb_backup/data/datanode/data2` | **Inconsistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2` | `/data/iotdb_backup/data/datanode/data` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2` | `/data/iotdb_backup/data/datanode/data3,/data/iotdb_backup/data/datanode/data4` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3` | `/data/iotdb_backup/data/datanode/data` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3` | `/data/iotdb_backup/data/datanode/data1;/data/iotdb_backup/data/datanode/data1` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3` | `/data/iotdb_backup/data/datanode/data1,/data/iotdb_backup/data/datanode/data3;/data/iotdb_backup/data/datanode/data` | **Consistent** | +| `/data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3` | `/data/iotdb_backup/data/datanode/data1,/data/iotdb_backup/data/datanode/data3;/data/iotdb_backup/data/datanode/data1,/data/iotdb_backup/data/datanode/data4` | **Inconsistent** | + +#### Path Matching Rules Summary + +* **Paths separated by `;` only**: + * `-targetdatadir` can be a single path (no `;` or `,`). + * `-targetdatadir` can also use `;` to split paths, but the count must match the source paths. +* **Paths separated by `,` only**: + * `-targetdatadir` can be a single path (no `;` or `,`). + * `-targetdatadir` can also use `,` to split paths, but the count must match the source paths. +* **Paths with both `;` and `,`**: + * `-targetdatadir` can be a single path (no `;` or `,`). + * Split paths first by `;`, then by `,`. The number of paths at each level must match. + +> **Note**: The `dn_wal_dirs` parameter (for WAL paths) follows the same rules as `dn_data_dirs`. diff --git a/src/zh/UserGuide/Master/Tree/Tools-System/Backup-Tool.md b/src/zh/UserGuide/Master/Tree/Tools-System/Backup-Tool.md new file mode 100644 index 000000000..29a209f24 --- /dev/null +++ b/src/zh/UserGuide/Master/Tree/Tools-System/Backup-Tool.md @@ -0,0 +1,126 @@ + + +# 全量备份工具 + +## 1. 概述 + +IoTDB 全量备份工具,用于将 IoTDB 单个节点的数据通过硬链接的方式备份到本地指定地址,并可以直接启动加入原集群。备份工具提供了两种模式:快速镜像模式和手动指定备份路径模式。 + +> 注意: +> +> * 备份前请停止IoTDB服务。 +> * 脚本默认后台执行,执行过程中打印的相关信息会输出到日志文件中。 + +## 2. 备份模式 + +### 2.1 模式一:快速镜像模式 + +#### 使用方法 + +```Bash +backup.sh/backup.bat -quick -node xxx + # xxx可选值见如下示例 + +backup.sh/backup.bat -quick -node +# 备份所有节点到默认路径 + +backup.sh/backup.bat -quick -node all +# 备份所有节点到默认路径 + +backup.sh/backup.bat -quick -node confignode +# 仅备份confignode节点到默认路径 + +backup.sh/backup.bat -quick -node datanode +# 仅备份datanode节点到默认路径 +``` + +#### 参数说明 + +| **参数** | **说明** | **是否必填** | +| ---------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------| -------------------- | +| `-quick` | 快速镜像 | 非必填 | +| `-node` | 备份节点类型,可选项包括`all`/`datanode`/`confignode`,空值默认为`all`。
`all`:备份`datanode`和`confignode`节点
`datanode`:只备份`datanode`节点
`confignode`:只备份`confignode`节点 | 非必填 | + +说明: + +1. 校验当前 `IoTDB` 文件夹及根据配置文件列出所有配置路径是否已经存在`_backup`文件夹,如果存在则退出,信息为 `The backup folder already exists`(备份文件夹已经存在)。 +> 当备份文件夹已存在时,可以尝试通过如下方式解决: +> * 删除已有的 _backup 文件夹后重新执行备份。 +> * 修改备份路径避免冲突。 + +2. 给原 `dn_data_dirs` 配置路径新建硬连接到对应的 `_backup` 路径 例如:`dn_data_dirs=/data/iotdb/data/datanode/data` 则备份完后数据在 `/data/iotdb/data/datanode/data_backup` +3. 拷贝出`dn_data_dirs` 其他文件到原 `IoTDB`文件夹到对应的 `_backup` 路径中 例如:`/data/iotdb `备份后 `/data/iotdb_backup` + +### 2.2 模式二:手动指定模式 + +#### 使用方法 + +```Bash +backup.sh -node xxx -targetdir xxx -targetdatadir xxx -targetwaldir xxx +``` + +#### 参数说明 +| **参数** | **说明** | **是否必填** | +| ---------------------- | ------------------------------------------------------------------------------------------ | -------------------- | +| `-node` | 备份节点类型`all`/`datanode`/`confignode`默认值`all` | 非必填 | +| `-targetdir` | `IoTDB`要备份到的文件夹 | 必填 | +| `-targetdatadir` | 配置项`dn_data_dirs`路径下文件要备份到的路径,默认`targetdir/data/datanode/data` | 非必填 | +| `-targetwaldir` | 配置项`dn_wal_dirs`路径下文件要备份到的路径,默认`targetdir/data/datanode/wal` | 非必填 | + + +说明: + +1. 校验参数 `-targetdir` 为必填项 ,如果参数不存在,则输出 `-targetdir cannot be empty, The backup folder must be specified`(`-targetdir` 参数不能为空,必须指定备份文件夹路径)。 +2. 对比配置文件中`dn_data_dirs`,`dn_wal_dirs` 配置路径模式和参数 `-targetdatadir`,`-targetwaldir`是否一致,如果`-targetdatadir`, `-targetwaldir`参数为单一路径则认为一致,如果不一致,输出` -targetdatadir parameter exception, the number of original paths does not match the number of specified paths`(`-targetdatadir` 参数异常,原本路径个数跟现在指定路径个数不一致)。 +3. 校验 `-targetdatadir` 配置的路径是否和原配置路径在同一块盘,如果不是同一块盘,则拷贝 `dn_data_dirs` 配置的文件到参数 `-targetdatadir` 对应目录。如果是同一块盘,则优先打硬连接 `dn_data_dirs` 配置的文件到参数 `-targetdatadir` 对应目录,如果打硬连接失败就拷贝文件到`-targetdatadir` 对应目录 +4. 配置文件路径与目标路径匹配规则 + +* **多对一**:多个源路径可以备份到一个目标路径。 +* **一对一**:一个源路径可以备份到一个目标路径。 +* **多对多**:多个源路径可以备份到多个目标路径,但需要模式匹配。 + +#### 示例 + +| **配置文件路径** | **参数 `-targetdatadir` 路径** | **校验结果** | +|--------------------------------|-----------------------------------------------------------|---------------------| +| /data/iotdb/data/datanode/data | /data/iotdb\_backup/data/datanode/data | 一致 | +| /data/iotdb/data/datanode/data | /data/iotdb\_backup/data/datanode/data1,/data/iotdb\_backup/data/datanode/data2 | 不一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2 | /data/iotdb\_backup/data/datanode/data | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2 | /data/iotdb\_backup/data/datanode/data3,/data/iotdb\_backup/data/datanode/data4 | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3 | /data/iotdb\_backup/data/datanode/data | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3 | /data/iotdb\_backup/data/datanode/data1;/data/iotdb\_backup/data/datanode/data1 | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3 | /data/iotdb\_backup/data/datanode/data1,/data/iotdb\_backup/data/datanode/data3;/data/iotdb\_backup/data/datanode/data | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3 | /data/iotdb\_backup/data/datanode/data1,/data/iotdb\_backup/data/datanode/data3;/data/iotdb\_backup/data/datanode/data1,/data/iotdb\_backup/data/datanode/data4 | 不一致 | + +#### 匹配规则总结 + +* 当 `dn_data_dirs` 仅有 `;` 分割时: + **规则**:* `-targetdatadir` 可以只输入一个路径(路径中没有 `;` 和 `,`)。 + * `-targetdatadir` 也可以按照 `;` 分割多个路径,但数量必须和 `dn_data_dirs` 中的路径数量相等,且路径中不能有 `,`。 +* 当 `dn_data_dirs` 仅有 `,` 分割时: + **规则**:* `-targetdatadir` 可以只输入一个路径(路径中没有 `;` 和 `,`)。 + * `-targetdatadir` 也可以按照 `,` 分割多个路径,但数量必须和 `dn_data_dirs` 中的路径数量相等,且路径中不能有 `;`。 +* 当 `dn_data_dirs` 同时有 `;` 和 `,` 分割时: + **规则**:* `-targetdatadir` 可以只输入一个路径(路径中没有 `;` 和 `,`)。 + * `-targetdatadir` 也可以优先按照 `;` 分割多个路径,数量必须和 `dn_data_dirs` 中的路径数量相等。每个 `;` 分割的路径中可以只输入一个路径,也可以按照 `,` 分割多个路径,但`,`分割的路径数量必须相等。 + +> `wal` 路径通常通过 `dn_wal_dirs` 参数指定,规则同上 diff --git a/src/zh/UserGuide/V1.3.x/Tools-System/Backup-Tool.md b/src/zh/UserGuide/V1.3.x/Tools-System/Backup-Tool.md new file mode 100644 index 000000000..aee59d160 --- /dev/null +++ b/src/zh/UserGuide/V1.3.x/Tools-System/Backup-Tool.md @@ -0,0 +1,127 @@ + + +# 全量备份工具 + +## 1. 概述 + +IoTDB 全量备份工具,用于将 IoTDB 单个节点的数据通过硬链接的方式备份到本地指定地址,并可以直接启动加入原集群。备份工具提供了两种模式:快速镜像模式和手动指定备份路径模式。 + +> 注意: +> +> * 备份前请停止IoTDB服务。 +> * 脚本默认后台执行,执行过程中打印的相关信息会输出到日志文件中。 +> * IoTDB版本要求:不能低于v1.3.2 + +## 2. 备份模式 + +### 2.1 模式一:快速镜像模式 + +#### 使用方法 + +```Bash +backup.sh/backup.bat -quick -node xxx + # xxx可选值见如下示例 + +backup.sh/backup.bat -quick -node +# 备份所有节点到默认路径 + +backup.sh/backup.bat -quick -node all +# 备份所有节点到默认路径 + +backup.sh/backup.bat -quick -node confignode +# 仅备份confignode节点到默认路径 + +backup.sh/backup.bat -quick -node datanode +# 仅备份datanode节点到默认路径 +``` + +#### 参数说明 + +| **参数** | **说明** | **是否必填** | +| ---------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------| -------------------- | +| `-quick` | 快速镜像 | 非必填 | +| `-node` | 备份节点类型,可选项包括`all`/`datanode`/`confignode`,空值默认为`all`。
`all`:备份`datanode`和`confignode`节点
`datanode`:只备份`datanode`节点
`confignode`:只备份`confignode`节点 | 非必填 | + +说明: + +1. 校验当前 `IoTDB` 文件夹及根据配置文件列出所有配置路径是否已经存在`_backup`文件夹,如果存在则退出,信息为 `The backup folder already exists`(备份文件夹已经存在)。 +> 当备份文件夹已存在时,可以尝试通过如下方式解决: +> * 删除已有的 _backup 文件夹后重新执行备份。 +> * 修改备份路径避免冲突。 + +2. 给原 `dn_data_dirs` 配置路径新建硬连接到对应的 `_backup` 路径 例如:`dn_data_dirs=/data/iotdb/data/datanode/data` 则备份完后数据在 `/data/iotdb/data/datanode/data_backup` +3. 拷贝出`dn_data_dirs` 其他文件到原 `IoTDB`文件夹到对应的 `_backup` 路径中 例如:`/data/iotdb `备份后 `/data/iotdb_backup` + +### 2.2 模式二:手动指定模式 + +#### 使用方法 + +```Bash +backup.sh -node xxx -targetdir xxx -targetdatadir xxx -targetwaldir xxx +``` + +#### 参数说明 +| **参数** | **说明** | **是否必填** | +| ---------------------- | ------------------------------------------------------------------------------------------ | -------------------- | +| `-node` | 备份节点类型`all`/`datanode`/`confignode`默认值`all` | 非必填 | +| `-targetdir` | `IoTDB`要备份到的文件夹 | 必填 | +| `-targetdatadir` | 配置项`dn_data_dirs`路径下文件要备份到的路径,默认`targetdir/data/datanode/data` | 非必填 | +| `-targetwaldir` | 配置项`dn_wal_dirs`路径下文件要备份到的路径,默认`targetdir/data/datanode/wal` | 非必填 | + + +说明: + +1. 校验参数 `-targetdir` 为必填项 ,如果参数不存在,则输出 `-targetdir cannot be empty, The backup folder must be specified`(`-targetdir` 参数不能为空,必须指定备份文件夹路径)。 +2. 对比配置文件中`dn_data_dirs`,`dn_wal_dirs` 配置路径模式和参数 `-targetdatadir`,`-targetwaldir`是否一致,如果`-targetdatadir`, `-targetwaldir`参数为单一路径则认为一致,如果不一致,输出` -targetdatadir parameter exception, the number of original paths does not match the number of specified paths`(`-targetdatadir` 参数异常,原本路径个数跟现在指定路径个数不一致)。 +3. 校验 `-targetdatadir` 配置的路径是否和原配置路径在同一块盘,如果不是同一块盘,则拷贝 `dn_data_dirs` 配置的文件到参数 `-targetdatadir` 对应目录。如果是同一块盘,则优先打硬连接 `dn_data_dirs` 配置的文件到参数 `-targetdatadir` 对应目录,如果打硬连接失败就拷贝文件到`-targetdatadir` 对应目录 +4. 配置文件路径与目标路径匹配规则 + +* **多对一**:多个源路径可以备份到一个目标路径。 +* **一对一**:一个源路径可以备份到一个目标路径。 +* **多对多**:多个源路径可以备份到多个目标路径,但需要模式匹配。 + +#### 示例 + +| **配置文件路径** | **参数 `-targetdatadir` 路径** | **校验结果** | +|--------------------------------|-----------------------------------------------------------|---------------------| +| /data/iotdb/data/datanode/data | /data/iotdb\_backup/data/datanode/data | 一致 | +| /data/iotdb/data/datanode/data | /data/iotdb\_backup/data/datanode/data1,/data/iotdb\_backup/data/datanode/data2 | 不一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2 | /data/iotdb\_backup/data/datanode/data | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2 | /data/iotdb\_backup/data/datanode/data3,/data/iotdb\_backup/data/datanode/data4 | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3 | /data/iotdb\_backup/data/datanode/data | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3 | /data/iotdb\_backup/data/datanode/data1;/data/iotdb\_backup/data/datanode/data1 | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3 | /data/iotdb\_backup/data/datanode/data1,/data/iotdb\_backup/data/datanode/data3;/data/iotdb\_backup/data/datanode/data | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3 | /data/iotdb\_backup/data/datanode/data1,/data/iotdb\_backup/data/datanode/data3;/data/iotdb\_backup/data/datanode/data1,/data/iotdb\_backup/data/datanode/data4 | 不一致 | + +#### 匹配规则总结 + +* 当 `dn_data_dirs` 仅有 `;` 分割时: + **规则**:* `-targetdatadir` 可以只输入一个路径(路径中没有 `;` 和 `,`)。 + * `-targetdatadir` 也可以按照 `;` 分割多个路径,但数量必须和 `dn_data_dirs` 中的路径数量相等,且路径中不能有 `,`。 +* 当 `dn_data_dirs` 仅有 `,` 分割时: + **规则**:* `-targetdatadir` 可以只输入一个路径(路径中没有 `;` 和 `,`)。 + * `-targetdatadir` 也可以按照 `,` 分割多个路径,但数量必须和 `dn_data_dirs` 中的路径数量相等,且路径中不能有 `;`。 +* 当 `dn_data_dirs` 同时有 `;` 和 `,` 分割时: + **规则**:* `-targetdatadir` 可以只输入一个路径(路径中没有 `;` 和 `,`)。 + * `-targetdatadir` 也可以优先按照 `;` 分割多个路径,数量必须和 `dn_data_dirs` 中的路径数量相等。每个 `;` 分割的路径中可以只输入一个路径,也可以按照 `,` 分割多个路径,但`,`分割的路径数量必须相等。 + +> `wal` 路径通常通过 `dn_wal_dirs` 参数指定,规则同上 diff --git a/src/zh/UserGuide/dev-1.3/Tools-System/Backup-Tool.md b/src/zh/UserGuide/dev-1.3/Tools-System/Backup-Tool.md new file mode 100644 index 000000000..aee59d160 --- /dev/null +++ b/src/zh/UserGuide/dev-1.3/Tools-System/Backup-Tool.md @@ -0,0 +1,127 @@ + + +# 全量备份工具 + +## 1. 概述 + +IoTDB 全量备份工具,用于将 IoTDB 单个节点的数据通过硬链接的方式备份到本地指定地址,并可以直接启动加入原集群。备份工具提供了两种模式:快速镜像模式和手动指定备份路径模式。 + +> 注意: +> +> * 备份前请停止IoTDB服务。 +> * 脚本默认后台执行,执行过程中打印的相关信息会输出到日志文件中。 +> * IoTDB版本要求:不能低于v1.3.2 + +## 2. 备份模式 + +### 2.1 模式一:快速镜像模式 + +#### 使用方法 + +```Bash +backup.sh/backup.bat -quick -node xxx + # xxx可选值见如下示例 + +backup.sh/backup.bat -quick -node +# 备份所有节点到默认路径 + +backup.sh/backup.bat -quick -node all +# 备份所有节点到默认路径 + +backup.sh/backup.bat -quick -node confignode +# 仅备份confignode节点到默认路径 + +backup.sh/backup.bat -quick -node datanode +# 仅备份datanode节点到默认路径 +``` + +#### 参数说明 + +| **参数** | **说明** | **是否必填** | +| ---------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------| -------------------- | +| `-quick` | 快速镜像 | 非必填 | +| `-node` | 备份节点类型,可选项包括`all`/`datanode`/`confignode`,空值默认为`all`。
`all`:备份`datanode`和`confignode`节点
`datanode`:只备份`datanode`节点
`confignode`:只备份`confignode`节点 | 非必填 | + +说明: + +1. 校验当前 `IoTDB` 文件夹及根据配置文件列出所有配置路径是否已经存在`_backup`文件夹,如果存在则退出,信息为 `The backup folder already exists`(备份文件夹已经存在)。 +> 当备份文件夹已存在时,可以尝试通过如下方式解决: +> * 删除已有的 _backup 文件夹后重新执行备份。 +> * 修改备份路径避免冲突。 + +2. 给原 `dn_data_dirs` 配置路径新建硬连接到对应的 `_backup` 路径 例如:`dn_data_dirs=/data/iotdb/data/datanode/data` 则备份完后数据在 `/data/iotdb/data/datanode/data_backup` +3. 拷贝出`dn_data_dirs` 其他文件到原 `IoTDB`文件夹到对应的 `_backup` 路径中 例如:`/data/iotdb `备份后 `/data/iotdb_backup` + +### 2.2 模式二:手动指定模式 + +#### 使用方法 + +```Bash +backup.sh -node xxx -targetdir xxx -targetdatadir xxx -targetwaldir xxx +``` + +#### 参数说明 +| **参数** | **说明** | **是否必填** | +| ---------------------- | ------------------------------------------------------------------------------------------ | -------------------- | +| `-node` | 备份节点类型`all`/`datanode`/`confignode`默认值`all` | 非必填 | +| `-targetdir` | `IoTDB`要备份到的文件夹 | 必填 | +| `-targetdatadir` | 配置项`dn_data_dirs`路径下文件要备份到的路径,默认`targetdir/data/datanode/data` | 非必填 | +| `-targetwaldir` | 配置项`dn_wal_dirs`路径下文件要备份到的路径,默认`targetdir/data/datanode/wal` | 非必填 | + + +说明: + +1. 校验参数 `-targetdir` 为必填项 ,如果参数不存在,则输出 `-targetdir cannot be empty, The backup folder must be specified`(`-targetdir` 参数不能为空,必须指定备份文件夹路径)。 +2. 对比配置文件中`dn_data_dirs`,`dn_wal_dirs` 配置路径模式和参数 `-targetdatadir`,`-targetwaldir`是否一致,如果`-targetdatadir`, `-targetwaldir`参数为单一路径则认为一致,如果不一致,输出` -targetdatadir parameter exception, the number of original paths does not match the number of specified paths`(`-targetdatadir` 参数异常,原本路径个数跟现在指定路径个数不一致)。 +3. 校验 `-targetdatadir` 配置的路径是否和原配置路径在同一块盘,如果不是同一块盘,则拷贝 `dn_data_dirs` 配置的文件到参数 `-targetdatadir` 对应目录。如果是同一块盘,则优先打硬连接 `dn_data_dirs` 配置的文件到参数 `-targetdatadir` 对应目录,如果打硬连接失败就拷贝文件到`-targetdatadir` 对应目录 +4. 配置文件路径与目标路径匹配规则 + +* **多对一**:多个源路径可以备份到一个目标路径。 +* **一对一**:一个源路径可以备份到一个目标路径。 +* **多对多**:多个源路径可以备份到多个目标路径,但需要模式匹配。 + +#### 示例 + +| **配置文件路径** | **参数 `-targetdatadir` 路径** | **校验结果** | +|--------------------------------|-----------------------------------------------------------|---------------------| +| /data/iotdb/data/datanode/data | /data/iotdb\_backup/data/datanode/data | 一致 | +| /data/iotdb/data/datanode/data | /data/iotdb\_backup/data/datanode/data1,/data/iotdb\_backup/data/datanode/data2 | 不一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2 | /data/iotdb\_backup/data/datanode/data | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2 | /data/iotdb\_backup/data/datanode/data3,/data/iotdb\_backup/data/datanode/data4 | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3 | /data/iotdb\_backup/data/datanode/data | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3 | /data/iotdb\_backup/data/datanode/data1;/data/iotdb\_backup/data/datanode/data1 | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3 | /data/iotdb\_backup/data/datanode/data1,/data/iotdb\_backup/data/datanode/data3;/data/iotdb\_backup/data/datanode/data | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3 | /data/iotdb\_backup/data/datanode/data1,/data/iotdb\_backup/data/datanode/data3;/data/iotdb\_backup/data/datanode/data1,/data/iotdb\_backup/data/datanode/data4 | 不一致 | + +#### 匹配规则总结 + +* 当 `dn_data_dirs` 仅有 `;` 分割时: + **规则**:* `-targetdatadir` 可以只输入一个路径(路径中没有 `;` 和 `,`)。 + * `-targetdatadir` 也可以按照 `;` 分割多个路径,但数量必须和 `dn_data_dirs` 中的路径数量相等,且路径中不能有 `,`。 +* 当 `dn_data_dirs` 仅有 `,` 分割时: + **规则**:* `-targetdatadir` 可以只输入一个路径(路径中没有 `;` 和 `,`)。 + * `-targetdatadir` 也可以按照 `,` 分割多个路径,但数量必须和 `dn_data_dirs` 中的路径数量相等,且路径中不能有 `;`。 +* 当 `dn_data_dirs` 同时有 `;` 和 `,` 分割时: + **规则**:* `-targetdatadir` 可以只输入一个路径(路径中没有 `;` 和 `,`)。 + * `-targetdatadir` 也可以优先按照 `;` 分割多个路径,数量必须和 `dn_data_dirs` 中的路径数量相等。每个 `;` 分割的路径中可以只输入一个路径,也可以按照 `,` 分割多个路径,但`,`分割的路径数量必须相等。 + +> `wal` 路径通常通过 `dn_wal_dirs` 参数指定,规则同上 diff --git a/src/zh/UserGuide/latest/Tools-System/Backup-Tool.md b/src/zh/UserGuide/latest/Tools-System/Backup-Tool.md new file mode 100644 index 000000000..29a209f24 --- /dev/null +++ b/src/zh/UserGuide/latest/Tools-System/Backup-Tool.md @@ -0,0 +1,126 @@ + + +# 全量备份工具 + +## 1. 概述 + +IoTDB 全量备份工具,用于将 IoTDB 单个节点的数据通过硬链接的方式备份到本地指定地址,并可以直接启动加入原集群。备份工具提供了两种模式:快速镜像模式和手动指定备份路径模式。 + +> 注意: +> +> * 备份前请停止IoTDB服务。 +> * 脚本默认后台执行,执行过程中打印的相关信息会输出到日志文件中。 + +## 2. 备份模式 + +### 2.1 模式一:快速镜像模式 + +#### 使用方法 + +```Bash +backup.sh/backup.bat -quick -node xxx + # xxx可选值见如下示例 + +backup.sh/backup.bat -quick -node +# 备份所有节点到默认路径 + +backup.sh/backup.bat -quick -node all +# 备份所有节点到默认路径 + +backup.sh/backup.bat -quick -node confignode +# 仅备份confignode节点到默认路径 + +backup.sh/backup.bat -quick -node datanode +# 仅备份datanode节点到默认路径 +``` + +#### 参数说明 + +| **参数** | **说明** | **是否必填** | +| ---------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------| -------------------- | +| `-quick` | 快速镜像 | 非必填 | +| `-node` | 备份节点类型,可选项包括`all`/`datanode`/`confignode`,空值默认为`all`。
`all`:备份`datanode`和`confignode`节点
`datanode`:只备份`datanode`节点
`confignode`:只备份`confignode`节点 | 非必填 | + +说明: + +1. 校验当前 `IoTDB` 文件夹及根据配置文件列出所有配置路径是否已经存在`_backup`文件夹,如果存在则退出,信息为 `The backup folder already exists`(备份文件夹已经存在)。 +> 当备份文件夹已存在时,可以尝试通过如下方式解决: +> * 删除已有的 _backup 文件夹后重新执行备份。 +> * 修改备份路径避免冲突。 + +2. 给原 `dn_data_dirs` 配置路径新建硬连接到对应的 `_backup` 路径 例如:`dn_data_dirs=/data/iotdb/data/datanode/data` 则备份完后数据在 `/data/iotdb/data/datanode/data_backup` +3. 拷贝出`dn_data_dirs` 其他文件到原 `IoTDB`文件夹到对应的 `_backup` 路径中 例如:`/data/iotdb `备份后 `/data/iotdb_backup` + +### 2.2 模式二:手动指定模式 + +#### 使用方法 + +```Bash +backup.sh -node xxx -targetdir xxx -targetdatadir xxx -targetwaldir xxx +``` + +#### 参数说明 +| **参数** | **说明** | **是否必填** | +| ---------------------- | ------------------------------------------------------------------------------------------ | -------------------- | +| `-node` | 备份节点类型`all`/`datanode`/`confignode`默认值`all` | 非必填 | +| `-targetdir` | `IoTDB`要备份到的文件夹 | 必填 | +| `-targetdatadir` | 配置项`dn_data_dirs`路径下文件要备份到的路径,默认`targetdir/data/datanode/data` | 非必填 | +| `-targetwaldir` | 配置项`dn_wal_dirs`路径下文件要备份到的路径,默认`targetdir/data/datanode/wal` | 非必填 | + + +说明: + +1. 校验参数 `-targetdir` 为必填项 ,如果参数不存在,则输出 `-targetdir cannot be empty, The backup folder must be specified`(`-targetdir` 参数不能为空,必须指定备份文件夹路径)。 +2. 对比配置文件中`dn_data_dirs`,`dn_wal_dirs` 配置路径模式和参数 `-targetdatadir`,`-targetwaldir`是否一致,如果`-targetdatadir`, `-targetwaldir`参数为单一路径则认为一致,如果不一致,输出` -targetdatadir parameter exception, the number of original paths does not match the number of specified paths`(`-targetdatadir` 参数异常,原本路径个数跟现在指定路径个数不一致)。 +3. 校验 `-targetdatadir` 配置的路径是否和原配置路径在同一块盘,如果不是同一块盘,则拷贝 `dn_data_dirs` 配置的文件到参数 `-targetdatadir` 对应目录。如果是同一块盘,则优先打硬连接 `dn_data_dirs` 配置的文件到参数 `-targetdatadir` 对应目录,如果打硬连接失败就拷贝文件到`-targetdatadir` 对应目录 +4. 配置文件路径与目标路径匹配规则 + +* **多对一**:多个源路径可以备份到一个目标路径。 +* **一对一**:一个源路径可以备份到一个目标路径。 +* **多对多**:多个源路径可以备份到多个目标路径,但需要模式匹配。 + +#### 示例 + +| **配置文件路径** | **参数 `-targetdatadir` 路径** | **校验结果** | +|--------------------------------|-----------------------------------------------------------|---------------------| +| /data/iotdb/data/datanode/data | /data/iotdb\_backup/data/datanode/data | 一致 | +| /data/iotdb/data/datanode/data | /data/iotdb\_backup/data/datanode/data1,/data/iotdb\_backup/data/datanode/data2 | 不一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2 | /data/iotdb\_backup/data/datanode/data | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2 | /data/iotdb\_backup/data/datanode/data3,/data/iotdb\_backup/data/datanode/data4 | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3 | /data/iotdb\_backup/data/datanode/data | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3 | /data/iotdb\_backup/data/datanode/data1;/data/iotdb\_backup/data/datanode/data1 | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3 | /data/iotdb\_backup/data/datanode/data1,/data/iotdb\_backup/data/datanode/data3;/data/iotdb\_backup/data/datanode/data | 一致 | +| /data/iotdb/data/datanode/data1,/data/iotdb/data/datanode/data2;/data/iotdb/data/datanode/data3 | /data/iotdb\_backup/data/datanode/data1,/data/iotdb\_backup/data/datanode/data3;/data/iotdb\_backup/data/datanode/data1,/data/iotdb\_backup/data/datanode/data4 | 不一致 | + +#### 匹配规则总结 + +* 当 `dn_data_dirs` 仅有 `;` 分割时: + **规则**:* `-targetdatadir` 可以只输入一个路径(路径中没有 `;` 和 `,`)。 + * `-targetdatadir` 也可以按照 `;` 分割多个路径,但数量必须和 `dn_data_dirs` 中的路径数量相等,且路径中不能有 `,`。 +* 当 `dn_data_dirs` 仅有 `,` 分割时: + **规则**:* `-targetdatadir` 可以只输入一个路径(路径中没有 `;` 和 `,`)。 + * `-targetdatadir` 也可以按照 `,` 分割多个路径,但数量必须和 `dn_data_dirs` 中的路径数量相等,且路径中不能有 `;`。 +* 当 `dn_data_dirs` 同时有 `;` 和 `,` 分割时: + **规则**:* `-targetdatadir` 可以只输入一个路径(路径中没有 `;` 和 `,`)。 + * `-targetdatadir` 也可以优先按照 `;` 分割多个路径,数量必须和 `dn_data_dirs` 中的路径数量相等。每个 `;` 分割的路径中可以只输入一个路径,也可以按照 `,` 分割多个路径,但`,`分割的路径数量必须相等。 + +> `wal` 路径通常通过 `dn_wal_dirs` 参数指定,规则同上