Skip to content

Commit 25aafc6

Browse files
HFO4HFO4
committed
doc: upgrade
1 parent d05e894 commit 25aafc6

File tree

14 files changed

+358
-52
lines changed

14 files changed

+358
-52
lines changed

‎.vitepress/en.mts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,10 @@ export default defineConfig({
7979
{
8080
text: "Maintain",
8181
collapsed: false,
82-
items: [{ text: "Upgrade Cloudreve", link: "/en/maintain/upgrade" }],
82+
items: [
83+
{ text: "Upgrade Cloudreve", link: "/en/maintain/upgrade" },
84+
{ text: "Upgrade from V3", link: "/en/maintain/upgrade-from-v3" },
85+
],
8386
},
8487
],
8588
},

‎.vitepress/zh.mts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,10 @@ export default defineConfig({
8181
{
8282
text: "维护",
8383
collapsed: false,
84-
items: [{ text: "更新 Cloudreve", link: "/zh/maintain/upgrade" }],
84+
items: [
85+
{ text: "更新 Cloudreve", link: "/zh/maintain/upgrade" },
86+
{ text: "从 V3 升级", link: "/zh/maintain/upgrade-from-v3" },
87+
],
8588
},
8689
],
8790

‎en/maintain/upgrade-from-v3.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Upgrade from V3.x.x {#upgrade-from-v3}
2+
3+
::: warning Warning
4+
5+
The current upgrade tool is still in testing phase. Please make backups before proceeding and be prepared to revert to the original version in case of upgrade failure.
6+
7+
:::
8+
9+
When upgrading from V3.x.x to V4.0.x, the following data will be lost:
10+
11+
- Remote download and other background task records;
12+
- Order records;
13+
- Report abuse records;
14+
- User-customized sidebar;
15+
- User's hardware authenticators;
16+
- Theme color configurations;
17+
- Thumbnails from non-local storage policy generated by thumbnail proxy;
18+
- Other configuration items no longer supported in V4.
19+
20+
After the upgrade, V3 share links and direct links will remain valid.
21+
22+
## 1. Preparation {#prepare}
23+
24+
### Check Current Version {#check-current-version}
25+
26+
The V3 to V4 upgrade tool was developed based on Cloudreve V3.8.x. Other older versions have not been tested. It is recommended to upgrade Cloudreve to V3.8.x first before proceeding with the upgrade to V4.
27+
28+
### Close the Site {#close-site}
29+
30+
Please close the current site and Cloudreve V3 process first to prevent new data from being written to the database.
31+
32+
### Backup Database {#backup-database}
33+
34+
Please backup your existing database version first. You can use third-party tools such as [`mysqldump`](https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html) to create database backups. For SQLite databases, you can directly backup the `cloudreve.db` file.
35+
36+
The upgrade tool will only read the V3 database and convert it to V4 format without modifying the data in the V3 database. However, there is still a possibility of V3 database corruption due to operational errors or program defects. Please make sure you have a backup before proceeding with subsequent operations.
37+
38+
### Backup Configuration File {#backup-config-file}
39+
40+
Please backup the existing V3 version configuration file `conf.ini`.
41+
42+
## 2. Convert Database {#convert-database}
43+
44+
### 2.1 Obtain V4 Executable {#get-v4-executable}
45+
46+
Refer to [Quick Start](../overview/quickstart) to obtain the V4.0.x version of the main program. Name it `cloudreve_v4` and place it in the same directory as the current `cloudreve`.
47+
48+
::: warning Warning
49+
50+
In future versions of V4, this upgrade tool will be removed. Please upgrade to version V4.0.x first, then proceed with subsequent upgrades.
51+
52+
:::
53+
54+
```bash
55+
# Rename the current Cloudreve V3 executable to cloudreve_v3
56+
mv cloudreve cloudreve_v3
57+
58+
# Rename the V4 main program to cloudreve
59+
mv cloudreve_v4 cloudreve
60+
61+
# Create a data directory for storing V4 configuration files and data
62+
mkdir data
63+
```
64+
65+
### 2.2 Prepare V4 Configuration File and Database {#prepare-v4-config-and-database}
66+
67+
Refer to [Configuration File](../overview/configure) to prepare a configuration file `conf.ini` for V4 use, and place it in the `data` directory created in the previous step. In the V4 configuration file, please specify the database connection information for V4 in the `Database` configuration item. Please create a new database separate from V3.
68+
69+
You can also directly copy the V3 configuration file `conf.ini` to the `data` directory and modify the database connection information in it, changing the `Name` in the `Database` configuration item to the name of the V4 database, or specify a new SQLite database file location through the `DBFile` configuration item.
70+
71+
::: tip
72+
In V4, specifying the table prefix `TablePrefix` configuration item is no longer supported, so it is recommended here to specify a new database for V4, separate from V3.
73+
:::
74+
75+
```bash
76+
# Copy the V3 configuration file `conf.ini` to the data directory created in the previous step
77+
cp conf.ini data/conf.ini
78+
79+
# Modify the database connection information in the V4 configuration file
80+
# Please create a new database separate from V3
81+
nano data/conf.ini
82+
```
83+
84+
### 2.3 Run the Upgrade Tool {#run-upgrade-tool}
85+
86+
```bash
87+
# Run the upgrade tool
88+
./cloudreve migrate --v3-conf conf.ini -c data/conf.ini
89+
```
90+
91+
Specify the V4 configuration file path with the `-c` parameter and the V3 configuration file path with the `--v3-conf` parameter. The upgrade tool will read the data from the V3 database, convert it to V4 format, and write it to the V4 database.
92+
93+
Depending on the amount of data, the upgrade tool may take from several minutes to several hours to run.
94+
95+
## 3. Start V4 {#start-v4-site}
96+
97+
After the upgrade tool has finished running, you can start the V4 site.
98+
99+
```bash
100+
# Start V4
101+
./cloudreve
102+
```
103+
104+
## 4. Subsequent Steps
105+
106+
1. If you still see the V3 page when accessing the site after the upgrade is complete, please delete your browser cache and make sure you are not using a custom frontend.
107+
2. After checking that the V4 site is running normally, the database data used by V3 can be deleted.
108+
109+
## Common Issues {#common-issues}
110+
111+
::: details If the upgrade process is interrupted abnormally, how do I retry?
112+
113+
Simply re-run the upgrade tool. Cloudreve will save the upgrade progress to the `migration_state.json` file and continue from where it was interrupted when started again. If you need to start the upgrade from scratch:
114+
115+
1. Delete all data tables and data already generated in the V4 database;
116+
2. Delete the `migration_state.json` file, or use the `--force-reset` parameter to restart the upgrade.
117+
118+
:::

‎en/maintain/upgrade.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Upgrad Cloudreve {#upgrade-cloudreve}
2+
3+
The steps described in this section only apply to upgrading within V4.x.x versions.
4+
5+
## Preparation {#prepare}
6+
7+
Before beginning the upgrade, please backup your existing database. You can use third-party tools such as [`mysqldump`](https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html) to create database backups. For SQLite databases, you can directly backup the `cloudreve.db` file.
8+
9+
Although theoretically the upgrade process will not modify the current database, it is still recommended that you backup the database for safety.
10+
11+
## Upgrade {#upgrade}
12+
13+
:::tabs
14+
15+
== Bare Metal Deployment
16+
17+
Replace the Cloudreve executable file with the new version, then restart Cloudreve.
18+
19+
== Docker Single Container
20+
21+
<!--@include: ../parts/docker-upgrade.md-->
22+
23+
== Docker Compose
24+
25+
<!--@include: ../parts/docker-compose-upgrade.md-->
26+
27+
:::
28+
29+
## Afterward {#after}
30+
31+
If you are using slave nodes, please also upgrade the Cloudreve on the slave nodes to the same version.

‎en/overview/deploy/docker-compose.md‎

Lines changed: 1 addition & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -126,16 +126,7 @@ Please check whether you have correctly set the `CR_LICENSE_KEY` environment var
126126

127127
::: details How to upgrade Cloudreve?
128128

129-
```bash
130-
# Shut down the currently running containers
131-
docker compose down
132-
133-
# Update the Cloudreve image
134-
docker compose pull
135-
136-
# Start new containers
137-
docker compose up -d
138-
```
129+
<!--@include: ../../parts/docker-compose-upgrade.md-->
139130

140131
You also need to refer to the [Upgrade Cloudreve](../../maintain/upgrade) page to complete the subsequent process.
141132

‎en/overview/deploy/docker.md‎

Lines changed: 1 addition & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -215,21 +215,7 @@ Configuration items passed through environment variables when starting the conta
215215

216216
::: details How to upgrade Cloudreve?
217217

218-
Since Cloudreve stores all configuration and data in the `/cloudreve/data` Volume, we just need to create a new container with the new image and mount the same Volume.
219-
220-
```bash{9}
221-
# Stop the currently running container
222-
docker stop cloudreve
223-
224-
# Remove the currently running container
225-
docker rm cloudreve
226-
227-
# Create a new container with the new image and mount the same Volume
228-
docker run -d --name cloudreve -p 5212:5212 \
229-
-v ~/cloudreve/data:/cloudreve/data \ # Make sure this is the same as the previous startup
230-
# Other configuration parameters, the same as the previous startup
231-
cloudreve/cloudreve:latest
232-
```
218+
<!--@include: ../../parts/docker-upgrade.md-->
233219

234220
You also need to refer to the [Upgrade Cloudreve](../../maintain/upgrade) page to complete the subsequent process.
235221

‎en/parts/docker-compose-upgrade.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
```bash
2+
# Shut down the currently running containers
3+
docker compose down
4+
5+
# Update the Cloudreve image
6+
docker compose pull
7+
8+
# Start new containers
9+
docker compose up -d
10+
```

‎en/parts/docker-upgrade.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
Since Cloudreve stores all configuration and data in the `/cloudreve/data` Volume, we just need to create a new container with the new image and mount the same Volume.
2+
3+
```bash{9}
4+
# Stop the currently running container
5+
docker stop cloudreve
6+
7+
# Remove the currently running container
8+
docker rm cloudreve
9+
10+
# Create a new container with the new image and mount the same Volume
11+
docker run -d --name cloudreve -p 5212:5212 \
12+
-v ~/cloudreve/data:/cloudreve/data \ # Make sure this is the same as the previous startup
13+
# Other configuration parameters, the same as the previous startup
14+
cloudreve/cloudreve:latest
15+
```

‎zh/maintain/upgrade-from-v3.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# 从 V3.x.x 升级 {#upgrade-from-v3}
2+
3+
::: warning 警告
4+
5+
当前升级工具仍处于测试阶段，请在操作前做好备份，并做好因升级失败而回退到原始版本的准备。
6+
7+
:::
8+
9+
当你从 V3.x.x 升级到 V4.0.x 时，下列数据会丢失：
10+
11+
- 离线下载和其他后台任务记录；
12+
- 订单记录；
13+
- 举报记录；
14+
- 用户自定义侧边栏；
15+
- 用户绑定的外部验证器；
16+
- 主题色配置；
17+
- 非本机存储策略代理生成的缩略图；
18+
- 其他在 V4 中不再支持的配置项。
19+
20+
升级后，V3 的分享链接和直链仍然有效。
21+
22+
## 1. 准备 {#prepare}
23+
24+
### 检查当前版本 {#check-current-version}
25+
26+
V3 到 V4 的升级工具基于 Cloudreve V3.8.x 版本开发，其他更老版本未进行过测试，推荐先将 Cloudreve 升级到 V3.8.x 再进行到 V4 的升级。
27+
28+
### 关闭站点 {#close-site}
29+
30+
请先关闭当前站点和 Cloudreve V3 进程，避免数据库中写入新的数据。
31+
32+
### 备份数据库 {#backup-database}
33+
34+
请先备份现有版本的数据库。你可以使用诸如 [`mysqldump`](https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html) 一类的第三方工具来创建数据库备份。对于 SQLite 数据库，你可以直接备份 `cloudreve.db` 文件。
35+
36+
升级工具只会读取 V3 数据库并转换为 V4 格式，不会修改 V3 数据库中的数据，但仍有可能因为操作失误或程序缺陷导致 V3 数据库损坏，请做好备份后再进行后续操作。
37+
38+
### 备份配置文件 {#backup-config-file}
39+
40+
请备份现有 V3 版本的配置文件 `conf.ini`。
41+
42+
## 2. 转换数据库 {#convert-database}
43+
44+
### 2.1 获取 V4 主程序 {#get-v4-executable}
45+
46+
参考 [快速开始](../overview/quickstart) 获取 V4.0.x 版本的主程序。将其命名为 `cloudreve_v4` 并放置到与当前 `cloudreve` 相同的目录下。
47+
48+
::: warning 警告
49+
50+
在 V4 后续版本中，此升级工具会被移除。请先升级到 V4.0.x 版本，再进行后续升级。
51+
52+
:::
53+
54+
```bash
55+
# 将当前 Cloudreve V3 可执行文件重命名为 cloudreve_v3
56+
mv cloudreve cloudreve_v3
57+
58+
# 将 V4 主程序重命名为 cloudreve
59+
mv cloudreve_v4 cloudreve
60+
61+
# 创建 data 目录，用于存放 V4 的配置文件和数据
62+
mkdir data
63+
```
64+
65+
### 2.2 准备 V4 配置文件和数据库 {#prepare-v4-config-and-database}
66+
67+
参考 [配置文件](../overview/configure) 准备一份 V4 使用的配置文件 `conf.ini`, 将其放置到上一步创建的 `data` 目录下。在 V4 配置文件中，请在 `Database` 配置项中为 V4 指定数据库连接信息，请创建一个新的数据库，与 V3 区分开来。
68+
69+
你也可以直接复制 V3 的配置文件 `conf.ini` 到 `data` 目录下，并修改其中的数据库连接信息，将 `Database` 配置项中的 `Name` 修改为 V4 数据库的名称，或者通过 `DBFile` 配置项指定一个新的 SQLite 数据库文件的位置。
70+
71+
::: tip
72+
在 V4 中，不再支持指定数据表前缀 `TablePrefix` 配置项，所以在这里推荐为 V4 指定一个新的数据库，与 V3 区分开来。
73+
:::
74+
75+
```bash
76+
# 将 V3 的配置文件 `conf.ini` 复制到上一步创建的 data 目录下
77+
cp conf.ini data/conf.ini
78+
79+
# 修改 V4 配置文件中的数据库连接信息
80+
# 请创建一个新的数据库，与 V3 区分开来
81+
nano data/conf.ini
82+
```
83+
84+
### 2.3 运行升级工具 {#run-upgrade-tool}
85+
86+
```bash
87+
# 运行升级工具
88+
./cloudreve migrate --v3-conf conf.ini -c data/conf.ini
89+
```
90+
91+
通过 `-c` 参数指定 V4 的配置文件路径，通过 `--v3-conf` 参数指定 V3 的配置文件路径。升级工具会读取 V3 数据库中的数据，并转换为 V4 格式，写入到 V4 数据库中。
92+
93+
根据数据量的不同，升级工具需要运行数分钟到数小时不等。
94+
95+
## 3. 启动 V4 {#start-v4-site}
96+
97+
升级工具运行完成后，你就可以启动 V4 站点了。
98+
99+
```bash
100+
# 启动 V4
101+
./cloudreve
102+
```
103+
104+
## 4. 后续步骤
105+
106+
1. 如果你在升级完成后，访问站点仍然是 V3 的页面，请删除浏览器缓存，并确保没有使用自定义前端。
107+
2. 在检查 V4 站点正常运行后，V3 所使用的数据库数据可以删除。
108+
109+
## 常见问题 {#common-issues}
110+
111+
::: details 升级过程中异常中断，如何重试？
112+
113+
直接重新执行升级工具即可。Cloudreve 会把升级进度保存到 `migration_state.json` 文件中，再次启动时会从上次中断的位置继续执行。如果你需要从头开始重新升级：
114+
115+
1. 删除 V4 数据库中已经生成的所有数据表和数据；
116+
2. 删除 `migration_state.json` 文件，或者使用 `--force-reset` 参数重新开始升级。

‎zh/maintain/upgrade.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# 更新 Cloudreve {#upgrade-cloudreve}
2+
3+
本章节描述步骤仅适用于在 V4.x.x 版本内进行更新。
4+
5+
## 准备 {#prepare}
6+
7+
在更新开始前，请先备份现有版本的数据库。你可以使用诸如 [`mysqldump`](https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html) 一类的第三方工具来创建数据库备份。对于 SQLite 数据库，你可以直接备份 `cloudreve.db` 文件。
8+
9+
虽然理论上升级流程不会对数据库造成损坏，但为了保险起见，建议你还是先备份数据库。
10+
11+
## 更新 {#upgrade}
12+
13+
:::tabs
14+
15+
== 裸机部署
16+
17+
将 Cloudreve 可执行文件替换为新版本，然后重启 Cloudreve 即可。
18+
19+
== Docker 单容器
20+
21+
<!--@include: ../parts/docker-upgrade.md-->
22+
23+
== Docker Compose
24+
25+
<!--@include: ../parts/docker-compose-upgrade.md-->
26+
27+
:::
28+
29+
## 后续 {#after}
30+
31+
如果你正在使用从机节点，请将从机节点上的 Cloudreve 也升级到相同版本。

0 commit comments

Comments
 (0)