docs: 增加 V1 迁移文档

Author: wan92hen

docs/installation/v1_migrate.md

@@ -1,5 +1,92 @@
-!!! note ""
-	由于 V2 版本较 V1 版本有比较大的架构变动，目前不支持从 V1 版本直接在线升级至 V2 版本。
-    
-    1Panel V1 版本的用户，可以使用官方提供的[迁移工具](https://gitee.com/fit2cloud-feizhiyun/1panel-migrator)，将 1Panel V1 平滑升级至 1Panel V2。
 
+!!! note "升级须知"
+
+    由于 V2 版本较 V1 版本有比较大的架构变动，目前不支持从 V1 版本直接在线升级至 V2 版本。
+
+    1Panel V1 版本的用户，可以使用官方提供的[迁移工具 **1panel-migrator**](https://gitee.com/fit2cloud-feizhiyun/1panel-migrator)，将 1Panel V1 平滑升级至 1Panel V2。
+
+!!! warning "注意"
+    为确保迁移顺利、安全，请务必在执行前仔细阅读以下内容。
+
+### 建议提前创建快照
+
+为防止意外风险，强烈建议：
+
+- 登录 **1Panel 控制台 → 面板设置** 页面，手动创建系统快照；
+- 或通过云服务商平台创建云主机快照。
+
+### V1 版本要求
+
+仅支持 **1Panel `v1.10.29-lts` 及以上版本** 执行迁移操作。
+
+### 迁移后的 V2 版本
+
+执行迁移后，系统将升级至 **1Panel v2.0.0 版本**
+
+### 专业版与许可证
+
+- 原有许可证将被清除，统一迁移为 **社区版本**；
+- V1 的买断许可证无法在 V2 中使用，但可前往 [凌霞官网](https://www.lxware.cn/) 进行升级；
+- 许可证导入 V2 前，请先前往 [凌霞官网](https://www.lxware.cn/) 确认是否已成功解绑。
+
+### 网站
+
+#### 网站主目录迁移
+
+迁移完成后，**所有网站配置将存放于 `{1Panel 安装目录}/www`**
+
+> 例如：`/opt/1panel/www`
+
+#### OpenResty 版本
+
+系统将自动升级至 **OpenResty `1.27.1.2-0-1-focal`**
+
+#### OpenResty 主配置文件
+
+由于 `1panel-migrator upgrade website` 会重置 OpenResty 主配置文件，如有自定义修改，请提前备份。
+
+#### PHP 运行环境网站
+
+- 面板内置的 PHP 环境将被移除；
+- **已创建网站中的 PHP 容器不会删除**，将被迁移至 静态网站；
+- 后续可创建 V2 版本的 PHP 运行环境，在原网站设置中将迁移的静态网站切换为 PHP 网站。
+
+#### 反向代理网站
+
+由于 V2 重构了反代缓存机制，改为每个网站使用独立目录，因此在执行 `1panel-migrator upgrade website` 前，请确认所有网站的反代缓存已关闭。
+
+### 备份记录
+
+出于兼容性考虑：
+
+- 所有 **V1 的网站、应用和数据库备份记录将被清空**；
+- 请在迁移完成后重新配置备份策略。
+
+### 主机终端
+
+主机列表、分组和快速命令仅在升级为主节点时迁移；若升级为从节点，这部分数据将不会迁移。
+
+### 计划任务
+
+- **计划任务本身会迁移**；
+- **任务的执行记录不会保留**。
+
+### 快照
+
+由于版本机制差异，**V1 的快照记录无法迁移至 V2**。
+
+### 面板设置
+
+升级完成后，所有节点的面板设置将以当前 V2 主节点的配置为准。
+
+### WAF 和网站监控
+
+由于架构升级：
+
+- **V1 的 WAF 配置与网站监控记录大部分不兼容**，不会被迁移；
+- WAF 仅保留：黑白名单、IP组、自定义规则；
+- 迁移后请重新配置相关功能。
+
+### 问题反馈
+
+如果您在使用过程中遇到任何问题或有其他反馈，请在 [1Panel 主仓库](https://github.com/1Panel-dev/1Panel/issues) 提交 Issue。

docs/installation/v1_migrate_steps.md

@@ -0,0 +1,112 @@
+
+!!! warning "注意"
+
+    由于 V2 版本较 V1 版本有比较大的架构变动，目前不支持从 V1 版本直接在线升级至 V2 版本。
+
+    为确保迁移顺利、安全，请务必在执行前仔细阅读本文档的[升级说明](v1_migrate.md)。
+
+## 1. 安装 1panel-migrator
+
+### 1.1 安装包获取
+
+请访问 Gitee 发布页，手动下载适用于您服务器架构的安装包，并将其放置到 `/tmp` 目录：
+
+> 🔗 https://gitee.com/fit2cloud-feizhiyun/1panel-migrator/releases/
+
+每个版本会提供以下架构的安装包（文件名示例）：
+
+- `1panel-migrator-linux-amd64`
+- `1panel-migrator-linux-arm64`
+- `1panel-migrator-linux-arm`
+- `1panel-migrator-linux-ppc64le`
+- `1panel-migrator-linux-s390x`
+
+### 1.2 安装步骤（以 amd64 架构为例）
+
+```bash
+# 1. 进入临时目录
+cd /tmp
+
+# 2. 添加执行权限
+chmod +x 1panel-migrator-linux-amd64
+
+# 3. 移动至系统 PATH 中并重命名
+mv 1panel-migrator-linux-amd64 /usr/local/bin/1panel-migrator
+```
+
+## 2. 升级说明
+
+升级过程分为两步：**升级服务** 和 **升级网站**。
+
+> 请务必先完成服务升级，再进行网站升级。
+
+服务升级分为两种角色：
+
+- **主节点**：包含 `1panel-core` 和 `1panel-agent` 两个服务，开放对外端口，支持通过浏览器访问；
+- **从节点**：仅包含 `1panel-agent` 服务，不开放对外端口，需要通过主节点的 ``节点管理`` 页面添加并管理。
+
+### 2.1 升级为主节点
+
+#### 2.1.1 升级服务
+
+```bash
+1panel-migrator upgrade core
+```
+
+#### 2.1.2 升级网站
+
+> 注意：请确保 V2 服务启动成功后再执行该命令。
+
+```bash
+1panel-migrator upgrade website
+```
+
+### 2.2 升级为从节点
+
+#### 2.2.1 升级服务
+
+```bash
+1panel-migrator upgrade agent
+```
+
+#### 2.2.2 在主节点添加从节点
+
+前往主节点 **节点管理** 页面，添加该从节点。系统会自动识别并处理 V1 的历史数据。
+
+#### 2.2.3 升级网站
+
+> 注意：添加完成后，请在从节点服务器上执行网站升级命令。
+
+```bash
+1panel-migrator upgrade website
+```
+
+## 3. 回滚说明
+
+!!! note ""
+
+    当升级过程出现问题时，可以使用回滚操作恢复到之前的 1Panel V1 版本。
+
+回滚过程也分为两步：**回滚 1Panel 服务** 和 **回滚网站**。
+
+!!! warning "注意"
+
+    请务必先完成服务的回滚，再进行网站回滚。
+
+### 3.1 服务回滚
+
+不区分主从节点，直接在目标服务器执行以下命令：
+
+```bash
+1panel-migrator rollback service
+```
+
+### 3.2 网站回滚
+
+同样在目标服务器执行以下命令：
+
+> 注意：请确保 V1 服务启动成功后再执行该命令。
+
+```bash
+1panel-migrator rollback website
+```

mkdocs.yml

@@ -44,7 +44,9 @@ nav:
     - 在线安装: installation/online_installation.md
     # - 离线包安装: installation/package_installation.md
     - 在线升级: installation/online_upgrade.md
-    - 从 V1 版本升级: installation/v1_migrate.md
+    - 从 V1 版本升级:
+      - 升级说明: installation/v1_migrate.md
+      - 操作步骤: installation/v1_migrate_steps.md
     - 命令行工具: installation/cli.md
   - 功能手册:
     - 应用商店: