# 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 配置保留
```