feat: add upgrade and migration flow for native fnOS

docs/upgrade-and-migration.md

@@ -0,0 +1,129 @@
+# Havline Native 升级与迁移
+
+> 适用版本：Native 1.9.1 及以后
+> 迁移来源：飞牛 Docker 应用版 Havline
+
+## 一、数据目录
+
+Docker 版和 Native 版使用同一个飞牛应用数据目录：
+
+```text
+${TRIM_PKGVAR}
+```
+
+主要数据：
+
+```text
+havline.db
+session_secret
+nginx/
+certs/
+frp/
+cloudflared/
+logs/
+ssh_known_hosts
+```
+
+Native 版启动时设置：
+
+```text
+HAVLINE_DATA_DIR=${TRIM_PKGVAR}
+```
+
+因此正常情况下不需要复制数据。
+
+## 二、推荐迁移路径
+
+```text
+1. 在飞牛应用中心备份或导出重要配置
+2. 卸载 Docker 版 Havline，选择“保留数据”
+3. 确认旧容器已停止，6893/18080/9443 端口已释放
+4. 安装 havline-native-1.9.1.fpk
+5. Native 安装回调检查数据目录
+6. 启动后主程序自动执行数据库迁移
+7. 登录验证反向代理、证书、FRP、Cloudflare 配置
+```
+
+卸载时不要选择“删除全部数据”。
+
+## 三、直接覆盖升级
+
+如果飞牛应用中心允许同一 `appname=havline` 直接升级：
+
+```text
+Docker 版 1.9.0
+  -> Native 版 1.9.1
+```
+
+升级回调会执行：
+
+```text
+检查 havline.db 可读
+检查 session_secret 可读
+迁移旧数据布局
+备份数据库到 ${TRIM_PKGVAR}/backups
+保留全部数据
+```
+
+如果应用中心不允许跨包类型直接升级，请使用推荐迁移路径。
+
+## 四、旧数据布局兼容
+
+部分早期 Docker 包可能使用：
+
+```text
+${TRIM_PKGVAR}/data/havline.db
+```
+
+Native 版检测到该布局且根目录没有 `havline.db` 时，会把
+`${TRIM_PKGVAR}/data` 下的内容迁移到 `${TRIM_PKGVAR}`。
+
+迁移规则：
+
+```text
+只迁移目标不存在的文件
+不覆盖已有数据
+保留原数据目录中的未迁移内容
+```
+
+## 五、升级前备份
+
+`upgrade_callback` 会把数据库复制到：
+
+```text
+${TRIM_PKGVAR}/backups/havline-pre-upgrade-<时间戳>.db
+```
+
+备份失败会导致升级失败，不会静默继续。
+
+## 六、回滚
+
+如果需要回滚到 Docker 版：
+
+```text
+1. 停止 Native 版 Havline
+2. 保留 ${TRIM_PKGVAR}
+3. 安装旧 Docker 版 FPK
+4. 启动后验证数据
+```
+
+`session_secret` 必须保持不变，否则已加密的 API Token、DDNS 凭据、
+通知密码和 Cloudflare 凭据将无法解密。
+
+## 七、验证清单
+
+```text
+[ ] 旧应用已停止
+[ ] 端口 6893/18080/9443 已释放
+[ ] ${TRIM_PKGVAR}/havline.db 存在
+[ ] ${TRIM_PKGVAR}/session_secret 存在
+[ ] Native 安装成功
+[ ] Native 启动成功
+[ ] 数据库迁移成功
+[ ] 升级前备份已生成
+[ ] 管理员可以登录
+[ ] 反向代理规则保留
+[ ] 证书保留
+[ ] FRP 配置保留
+[ ] Cloudflare 配置保留
+```