Why LoongFire Doesn't Support In-Place Upgrades

LoongFire is a community-driven firewall distribution. Like any project with limited resources, we have to make honest choices about what we can support well — and what we can't.

One of those choices is this: LoongFire does not provide in-place upgrades on existing installations. Instead, the supported path for moving to a new release is:

1. Back up your configuration
2. Perform a fresh install
3. Restore your backup

This is a deliberate policy, not an oversight. Here's why.

The Constraint

Supporting in-place upgrades means hosting software repositories for every version we've ever released, so that users on older releases can still fetch the packages they need to step forward. That requires storage, bandwidth, and the engineering effort to maintain and test upgrade paths between every version pair.

LoongFire doesn't have those resources. Rather than offer an upgrade path we can't test properly — and risk leaving users stranded halfway through a broken migration — we've chosen a model we can support reliably.

The Recommended Procedure

Before you begin

• Export your configuration backup and verify it exists and is readable
• Store it somewhere other than the device you're about to reinstall (network share, USB stick, another machine)
• Note any customisations: custom cron users, firewall rules in firewall.local, add-on configurations, certificates, VPN keys
• Have your install media ready

Install

• Perform a clean installation of the new LoongFire release
• Complete the basic setup so the web interface is reachable

Restore

• Upload your configuration backup through the web interface
• Restore the system
• Validate: check firewall rules, VPN tunnels, DHCP/DNS, custom scripts, cron jobs, and add-ons are all present and working

After

• Confirm connectivity and services
• Keep the backup until you're satisfied everything is running correctly

Optional: Staged Rollout with a Spare Device

If you have a spare device — or if the site is critical enough to justify keeping one — you can reduce production downtime by staging the work before cutover:

1. On the spare device, perform the fresh install, restore the backup, and run your full validation outside the production window.
2. Confirm the restored system is working correctly, including any hardware-specific configuration.
3. At cutover, swap the pre-staged device into production. Test the cutover itself (addressing, cabling, any hardware-specific settings) so the swap goes smoothly.

This moves the time-consuming and failure-prone steps out of the production window, leaving only a short swap. It doesn't remove downtime entirely — you still need a cutover — but it turns the upgrade into a brief, predictable change rather than an extended maintenance event. For critical sites, keeping a pre-staged spare is a sensible part of this policy.

Pros

• Reproducible, clean state — no accumulated cruft, no half-migrated configs, no leftover files from previous versions
• Smaller repository footprint — we only need to host the current release, which keeps the project sustainable
• Simpler and better-tested QA — we test "install + restore," not every possible upgrade permutation
• Reliable fallback by design — restoring a known-good backup is a mechanical recovery job, not guesswork. Users who follow good backup discipline report smooth, low-drama recoveries.
• A natural hardware-hygiene moment — rebuilding is a good time to notice failing disks, cables, or other hardware quietly degrading
• Predictable support — when something goes wrong, we know the state you started from
• Downtime can be minimised — with a spare device, most of the work happens before cutover, leaving only a short swap in the production window

Cons

• Higher downtime than an in-place upgrade — a fresh install plus restore takes longer than an in-place upgrade
  • Mitigation: stage the work on a spare device first, then swap it into production. This moves the time-consuming, failure-prone steps out of the production window, leaving only a short cutover. See "Staged Rollout" above. It doesn't eliminate downtime entirely, and you should test the cutover itself so the swap goes smoothly.
• Backup completeness is load-bearing — anything not captured in the backup is lost. You need to know what your backup covers and what it doesn't
• Restore must be rehearsed — assuming the backup will restore cleanly is not the same as having tested it. Practise the procedure before you need it
• Manual re-customisation may be needed — some hand-edited files or third-party tweaks may not be captured automatically
• Not a substitute for hardware monitoring — a healthy-looking disk can still sit behind a failing cable. Pair this policy with SMART and RAID alerting
• Requires discipline from users — the model only works if backups are taken regularly and stored safely
• Staging needs spare hardware — the staged-rollout option only helps if you have (or can justify) a spare device

The Honest Framing

This is a resource-driven choice, not a claim that in-place upgrades are inherently bad. Plenty of projects do them well. We're being upfront: given our constraints, backup → fresh install → restore is the model we can actually support, test, and stand behind. We'd rather offer a procedure that works than an upgrade path that might not.

If you follow the backup discipline, a rebuild becomes a routine job rather than a rescue mission. That's the trade we've made, and we think it's the right one for LoongFire.

为什么 LoongFire 不支持原地升级

LoongFire 是一个社区驱动的防火墙发行版。和任何资源有限的项目一样，我们必须诚实地选择哪些事情能够做好、哪些做不到。

其中一项选择就是：LoongFire 不为现有安装提供原地升级。迁移到新版本的支持路径是：

1. 备份配置
2. 全新安装
3. 恢复备份

这是一项有意的策略，而非疏忽。原因如下。

约束条件

支持原地升级意味着要为我们发布过的每一个版本托管软件仓库，以便旧版本用户仍能获取升级所需的软件包。这需要存储空间、带宽，以及维护和测试每两个版本之间升级路径的工程投入。

LoongFire 没有这些资源。与其提供一个我们无法充分测试的升级路径——并冒着让用户在迁移中途陷入困境的风险——我们选择了一个能够可靠支持的模式。

推荐流程

开始之前

• 导出配置备份，并确认文件存在且可读
• 将备份存放在即将重装的设备之外（网络共享、U 盘、另一台机器）
• 记录所有自定义内容：自定义 cron 用户、firewall.local 中的防火墙规则、插件配置、证书、VPN 密钥
• 准备好安装介质

安装

• 全新安装新版 LoongFire
• 完成基本设置，确保 Web 界面可访问

恢复

• 通过 Web 界面上传配置备份
• 恢复系统
• 验证：检查防火墙规则、VPN 隧道、DHCP/DNS、自定义脚本、cron 任务和插件是否齐全并正常工作

之后

• 确认连通性和服务正常
• 在确认一切正常之前保留备份

可选：使用备用设备分阶段实施

如果你有备用设备——或者站点足够关键，值得常备一台——可以通过在切换前分阶段完成工作来减少生产停机：

1. 在备用设备上，在生产窗口之外完成全新安装、恢复备份，并执行完整验证。
2. 确认恢复后的系统工作正常，包括任何硬件相关的配置。
3. 切换时，将预先准备好的设备换入生产环境。测试切换过程本身（地址、线缆、任何硬件相关设置），确保替换顺利进行。

这样可以把耗时且易出错的步骤移出生产窗口，只留下短暂的替换。它不能完全消除停机——你仍然需要切换——但可以把升级变成一次简短、可预测的变更，而不是一次漫长的维护事件。对于关键站点，常备一台预先准备好的备用设备是这项策略中合理的一部分。

优点

• 可复现的干净状态——没有累积的冗余、没有迁移到一半的配置、没有旧版本残留文件
• 更小的仓库占用——只需托管当前版本，项目更可持续
• 更简单、更充分的测试——我们测试的是"安装 + 恢复"，而不是所有可能的升级组合
• 设计上就有可靠的回退方案——从已知良好的备份恢复是一项机械性的工作，而非猜测。遵循良好备份习惯的用户反馈恢复过程平稳、少有波折。
• 天然的硬件检查时机——重装是发现磁盘、线缆或其他硬件悄悄劣化的好机会
• 可预测的支持——出问题时，我们清楚你从什么状态开始
• 停机时间可以最小化——借助备用设备，大部分工作在切换前完成，生产窗口中只留下短暂的替换

缺点

• 停机时间比原地升级更长——全新安装加恢复比原地升级耗时更多
  • 缓解措施：先在备用设备上分阶段完成工作，再换入生产环境。这样可以把耗时且易出错的步骤移出生产窗口，只留下短暂的切换。参见上文"分阶段实施"。它不能完全消除停机，而且你需要测试切换过程本身，确保替换顺利进行。
• 备份完整性至关重要——备份未覆盖的内容都会丢失。你需要清楚备份包含什么、不包含什么
• 恢复流程必须演练——假设备份能顺利恢复，和实际测试过并不是一回事。请在需要之前先练习一遍
• 可能需要手动重新自定义——某些手工编辑的文件或第三方调整可能不会被自动捕获
• 不能替代硬件监控——看起来健康的磁盘，背后可能是一条正在劣化的线缆。请将此策略与 SMART 和 RAID 告警配合使用
• 需要用户自律——只有定期备份并妥善保存，这个模式才成立
• 分阶段实施需要备用硬件——只有在拥有（或能够证明需要）备用设备时，分阶段方案才有帮助

诚实的定位

这是一个由资源决定的取舍，而非声称原地升级本身不好。很多项目做得很好。我们坦率说明：在现有约束下，备份 → 全新安装 → 恢复是我们真正能够支持、测试并负责的模式。我们宁愿提供一个可行的流程，也不愿提供一条可能行不通的升级路径。

如果你遵循备份纪律，重装就会成为一项常规工作，而不是一次救援行动。这就是我们做出的取舍，我们认为这对 LoongFire 是正确的。