Skip to content

Commit f2c8cfd

Browse files
hezhuozhuohezhuozhuo
committed
docs: Add a new system upgrade guide for 1Panel and its Chinese translation, along with a Chinese translation for the general system upgrade guide.
1 parent e8da21d commit f2c8cfd

3 files changed

Lines changed: 347 additions & 61 deletions

File tree

‎docs/installation/system_upgrade_1panel.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
sidebar_position: 9
3+
---
4+
5+
6+
## System Upgrade Guide (1Panel)
7+
8+
Compare with the latest mirror version of the ThingsPanel community edition (mainly refer to the `docker-compose.yml` file in the [ThingsPanel Quick Start Guide](/docs/quick_start))
9+
10+
### Version Compatibility Note
11+
**Main Reference:** [ThingsPanel System Upgrade Guide](/docs/installation/system_upgrade)
12+
13+
:::caution IMPORTANT
14+
Direct upgrade from **0.5.4** to **1.0.0** is NOT supported. You need to **re-deploy**.
15+
:::
16+
17+
18+
---
19+
20+
## 2. Log in to the 1Panel Dashboard
21+
22+
---
23+
24+
## 3. Docker Deployment Upgrade Guide
25+
26+
:::caution IMPORTANT
27+
You can also choose to use cloud service snapshots for backup.
28+
:::
29+
30+
### 3.1 Pre-upgrade Preparation (Data Backup)
31+
32+
#### 3.1.1 Backup Database and Storage Volumes
33+
34+
Log in to the server terminal and execute the following backup commands:
35+
36+
```bash
37+
# 1. Create backup directory
38+
BACKUP_DIR="/data/backups/thingspanel/20260305"
39+
mkdir -p "$BACKUP_DIR"
40+
41+
# 2. Backup database (Note: replace with absolute container name if different)
42+
docker exec thingspanel-docker-postgres-1 \
43+
pg_dump -U postgres -d ThingsPanel \
44+
-F c -Z 6 \
45+
--no-tablespaces \
46+
> "$BACKUP_DIR/ThingsPanel.dump"
47+
48+
# Verify backup result: ls -lh "$BACKUP_DIR/ThingsPanel.dump" Ensure file size is not zero
49+
50+
# 3. Backup backend volumes (configs and files)
51+
# If the frontend configuration file has been modified, it also needs to be backed up
52+
docker cp thingspanel-docker-backend-1:/go/src/app/configs "$BACKUP_DIR/configs"
53+
docker cp thingspanel-docker-backend-1:/go/src/app/files "$BACKUP_DIR/files"
54+
```
55+
56+
#### 3.1.2 Backup docker-compose.yml
57+
58+
1. Go to the 1Panel dashboard -> **Containers** -> **Compose** -> Edit **thingspanel-docker** and copy the current configuration.
59+
![alt text](image.png)
60+
61+
2. Save a backup of this file from the terminal:
62+
```bash
63+
cd "$BACKUP_DIR"
64+
vi docker-compose.yml.bak
65+
# Paste the copied content, save and exit
66+
```
67+
68+
### 3.2 Choose Upgrade Method
69+
70+
You can choose one of the following two upgrade methods:
71+
- **Partial Container Upgrade** (Update specific services only)
72+
- **Full System Upgrade** (Update all components)
73+
74+
### 3.3 Partial Container Upgrade Process
75+
76+
#### Container and Service Mapping
77+
78+
- **Frontend Service:** `thingspanel-vue:nginx`
79+
- **MQTT Service:** `thingspanel-gmqtt:gmqtt`
80+
- **Backend Service:** `thingspanel-go:go`
81+
82+
#### Modify Configuration and Version
83+
84+
1. Log in to the 1Panel dashboard.
85+
2. Navigate to **Containers** -> **Compose** -> Edit **thingspanel-docker**.
86+
3. Change to the corresponding image versions.
87+
4. Click **Save** and wait for the container update and deployment to complete.
88+
89+
:::tip Tip
90+
If the new version uses the same image tag, please make sure to **delete the old image and pull again** in local image management to get the latest layers.
91+
:::
92+
93+
### 3.4 Update Configuration Files
94+
95+
Go to the official repository `thingspanel-backend-community/configs/` directory and check if there are any changes in the following files:
96+
- `configs/conf.yml`
97+
- `messages_str.yaml`
98+
- `messages.yaml`
99+
100+
If there are new additions or changes to the official version configuration, please compare the changes and synchronize them to the target server's `thingspanel-docker_go_configs` volume (edit in 1Panel dashboard **Containers** -> **Volumes**).
101+
102+
### 3.5 Restart Service
103+
104+
After any manual configuration updates, please restart the corresponding container service to apply the configuration.
105+
106+
---
107+
108+
## 4. Anomaly Recovery and Rollback
109+
110+
If an exception occurs or the upgrade fails, you can refer to the following steps to recover data.
111+
112+
### 4.1 Database Recovery Process
113+
114+
```bash
115+
# Step 1: Stop services connecting to the database (postgres must be kept running for subsequent queries)
116+
docker stop thingspanel-docker-backend-1 tp-images-test-gmqtt-1 tp-images-test-frontend-1
117+
118+
# Step 2: Rebuild database and initialize TimescaleDB extension
119+
docker exec -i thingspanel-docker-postgres-1 psql -U postgres << 'EOF'
120+
DROP DATABASE IF EXISTS "ThingsPanel";
121+
CREATE DATABASE "ThingsPanel";
122+
\c ThingsPanel
123+
CREATE EXTENSION IF NOT EXISTS timescaledb;
124+
EOF
125+
126+
# Step 3: Import recovery data (use --disable-triggers to avoid circular foreign key errors)
127+
docker exec -i thingspanel-docker-postgres-1 \
128+
pg_restore -U postgres -d ThingsPanel \
129+
--no-owner \
130+
--disable-triggers \
131+
-F c \
132+
< "$BACKUP_DIR/ThingsPanel.dump"
133+
```
134+
135+
### 4.2 Recover Backend Volume Data (As Needed)
136+
137+
If configuration is lost, you can use previous backups to recover it:
138+
139+
```bash
140+
# Copy backup configuration and files back to the container
141+
docker cp "$BACKUP_DIR/configs" thingspanel-docker-backend-1:/go/src/app/
142+
docker cp "$BACKUP_DIR/files" thingspanel-docker-backend-1:/go/src/app/
143+
```
144+
145+
### 4.3 Restart Services
146+
147+
After completing data recovery, restart the previously stopped services:
148+
149+
```bash
150+
# Start the related services stopped in the above process
151+
docker start thingspanel-docker-backend-1 tp-images-test-gmqtt-1 tp-images-test-frontend-1
152+
```

‎i18n/zh-Hans/docusaurus-plugin-content-docs/current/installation/system_upgrade.md‎

Lines changed: 43 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -12,25 +12,39 @@ ThingsPanel 从 0.5.4 版本升级到 1.0.0 版本是不支持直接升级的，
1212

1313
## Docker 部署版本升级指南
1414

15+
:::caution 重要提示
16+
也可选择使用云服务快照进行备份
17+
:::
18+
1519
### 升级前准备
1620

1721
1. **数据备份**
18-
- 备份数据库
19-
- 备份配置文件
20-
- 备份自定义插件和扩展
22+
23+
```bash
24+
# 1. 创建备份目录
25+
BACKUP_DIR="/data/backups/thingspanel/20260305"
26+
mkdir -p "$BACKUP_DIR"
27+
28+
# 2. 备份数据库（注意替换为实际容器名称）
29+
docker exec thingspanel-docker-postgres-1 \
30+
pg_dump -U postgres -d ThingsPanel \
31+
-F c -Z 6 \
32+
--no-tablespaces \
33+
> "$BACKUP_DIR/ThingsPanel.dump"
34+
35+
# 验证备份结果：ls -lh "$BACKUP_DIR/ThingsPanel.dump" 确认文件大小非零即可
36+
37+
# 3. 备份后端卷（configs 和 files）
38+
# 如果前端修改过配置文件，也需要一并备份
39+
docker cp thingspanel-docker-backend-1:/go/src/app/configs "$BACKUP_DIR/configs"
40+
docker cp thingspanel-docker-backend-1:/go/src/app/files "$BACKUP_DIR/files"
41+
```
2142

2243
2. **环境检查**
2344
- 确认系统资源充足
2445
- 验证存储空间
2546
- 检查现有服务状态
2647

27-
### 升级方式选择
28-
29-
您可以选择以下两种升级方式之一：
30-
31-
- 部分容器升级（只更新特定服务）
32-
- 全系统升级（更新所有组件）
33-
3448
### 部分容器升级流程
3549

3650
#### 1. 容器与卷的对应关系
@@ -43,73 +57,41 @@ MQTT服务: thingspanel-gmqtt:gmqtt
4357

4458
#### 2. 升级步骤
4559

46-
1. 更新源码
47-
48-
```bash
49-
cd thingspanel-docker
50-
git pull
51-
```
52-
53-
2. 停止并清理目标容器
54-
55-
```bash
56-
# 停止容器
57-
docker stop <ContainerID>
60+
由于应用使用 Docker Compose 部署，推荐直接使用 `docker-compose` 命令对特定服务进行独立升级，无需手动查找容器 ID 或镜像 ID。
5861

59-
# 删除容器
60-
docker rm <ContainerID>
62+
1. **修改docker-compose.yml文件**
6163

62-
# 删除镜像
63-
docker rmi <ImageID>
64-
```
64+
与 ThingsPanel 社区版最新镜像版本比对（主要参考 [ThingsPanel 快速开始文档](https://docs.thingspanel.cn/zh-Hans/docs/quick_start) 中的 `docker-compose.yml` 文件）
6565

66-
3. 清理卷
66+
2. **升级目标服务**（以 `backend` 后端服务为例）
6767

6868
```bash
69-
# 清理未使用的卷
70-
docker volume prune
69+
# 1. 停止目标服务
70+
docker-compose stop backend
7171

72-
# 查看现有卷
73-
docker volume ls
72+
# 2. 移除目标服务容器
73+
docker-compose rm -f backend
74+
75+
# 3. 拉取该服务的最新镜像
76+
docker-compose pull backend
7477

75-
# 删除特定卷（如需要）
76-
docker volume rm thingspanel-docker_nginx
77-
docker volume rm thingspanel-docker_gmqtt
78-
docker volume rm thingspanel-docker_go
78+
# 4. 重新以守护态启动该服务
79+
docker-compose up -d backend
7980
```
8081

81-
4. 重新部署服务
82+
3. **清理系统碎片**（可选）
8283

8384
```bash
84-
docker-compose -f docker-compose.yml up
85+
# 清理未被任何容器使用的构建缓存、悬空镜像和数据卷
86+
docker system prune -f
87+
docker volume prune -f
8588
```
8689

8790
:::tip 提示
88-
如果新版本使用相同的镜像标签，请确保删除本地镜像并重新拉取，以获取最新版本。
91+
将上述命令中的 `backend` 替换为您需要单独升级的服务名称（如 `nginx`, `gmqtt`，请参考 `docker-compose.yml` 中的服务名称）。
92+
如果新版本使用相同的镜像标签（如 `:latest`），执行 `docker-compose pull <服务名>` 步即可拉取最新版本。
8993
:::
9094

91-
### 全系统升级流程
92-
93-
1. **准备工作**
94-
- 比对新旧版本的 docker-compose.yml 文件，确认需要更新的服务
95-
- 更新源码到目标版本
96-
97-
```bash
98-
git pull
99-
```
100-
101-
2. **停止现有服务**
102-
103-
```bash
104-
docker-compose down
105-
```
106-
107-
3. **启动新版本**
108-
109-
```bash
110-
docker-compose -f docker-compose.yml up -d
111-
```
112-
11395
### 配置更新
11496

11597
如需修改卷中的配置：

0 commit comments

Comments
 (0)