让数据永不丢失:unifi-os-server 持久化与备份的 6 大关键目录

原创2026-11-01 18:00:451,939 阅读

让数据永不丢失:unifi-os-server 持久化与备份的 6 大关键目录

如果你正在用 unifi-os-server 以 Docker 或 Kubernetes 方式自建 UniFi OS Server,那么"数据持久化"就是你必须掌握的第一课:容器可以随时重建,但你的站点配置、设备台账和数据库绝不能随容器消失。本文带你快速掌握 UniFi OS Server 持久化的 6 大关键目录、三种部署方式的挂载配置,以及一份可落地的备份策略,让你的 UniFi 自建服务真正做到数据永不丢失。

🧭 为什么自建 UniFi OS Server 必须关注数据持久化?

UniFi OS Server 是自建 UniFi 的新标准(取代旧的 UniFi Network Server),它内部由 systemd 统一管理 MongoDB、RabbitMQ、Network 应用等多个组件。这些组件把"命根子"数据分散写在不同的系统目录里:

  • 数据库文件在 /var/lib/mongodb
  • 系统身份标识(uos_uuid)在 /data
  • 网络配置(system_ip)在 /var/lib/unifi
  • 运行日志在 /var/log

如果没有正确挂载持久化卷,一次容器重建 = 所有设备失联、配置清零。而 uos-entrypoint.sh 在启动时还会生成并持久化 UOS_UUID,它是整个系统的唯一身份,丢失后需要重新注册、重建信任关系。

📊 6 大关键目录速览

以下 7 个挂载点(其中 2 个合并为一组)就是全部需要持久化的内容,也是 docker-compose.yaml 中 volumes 段的完整清单:

# 容器内路径 存了什么 丢失后果 重要度
1 /var/lib/mongodb MongoDB 数据库:站点、设备、全部配置 所有数据全丢,灾难级 ⭐⭐⭐⭐⭐
2 /data 系统数据、uos_uuid 身份文件 系统身份丢失 ⭐⭐⭐⭐
3 /persistent UniFi OS 持久存储区 应用数据丢失 ⭐⭐⭐⭐
4 /var/lib/unifi system.properties(含 system_ip) 设备 inform 地址错乱 ⭐⭐⭐
5 /var/log nginx、MongoDB、RabbitMQ 等日志 排查问题无据可依 ⭐⭐
6 /srv + /etc/rabbitmq/ssl 服务文件与 RabbitMQ SSL 证书 服务文件/证书丢失 ⭐⭐

🔍 逐个拆解:每个目录为什么重要?

1️⃣ /var/lib/mongodb:一切数据的"心脏"

MongoDB 是 UniFi OS Server 的核心数据库,站点结构、AP/交换机台账、用户、策略全部存在这里。启动脚本会专门初始化它的目录归属和日志目录(见 uos-entrypoint.sh)。

备份建议:这是备份的第一优先级。最稳妥的做法是备份前停容器(保证数据库文件完整),或使用 mongodump 做逻辑备份。

2️⃣ /data:系统身份与核心数据

/data 存放系统级数据,其中最重要的是 uos_uuid 文件——uos-entrypoint.sh 首次启动时若找不到它会随机生成一个 V5 UUID 并写入。该文件丢失意味着系统"换了身份"。同时 Home Assistant 场景下的应用选项 options.json 也位于此路径下,供启动脚本读取 UOS_SYSTEM_IP。

3️⃣ /persistent:持久化存储区

/persistent 是 UniFi OS 自身的持久化存储区,各组件的应用级数据会落在这里。它是官方安装路径中"数据与系统分离"的核心目录,务必单独挂载、单独备份。

4️⃣ /var/lib/unifi:系统配置与 system_ip

/var/lib/unifi/system.properties 记录了 system_ip,即设备 adopt 时使用的 inform 地址。uos-entrypoint.sh 会依据环境变量 UOS_SYSTEM_IP 自动写入或更新该值。挂载此目录后,即使更换容器,system_ip 配置也不会丢失,设备无需重新 set-inform。

5️⃣ /var/log:运行日志

MongoDB、RabbitMQ、nginx 的日志都汇聚在这里(启动脚本会为 nginx 与 mongodb 初始化日志目录,见 uos-entrypoint.sh)。日志不属于核心数据,但排查"设备离线""服务崩溃"等问题时必不可少,建议一并纳入定期备份。

6️⃣ /srv 与 /etc/rabbitmq/ssl:服务文件与 SSL 证书

srv 存放服务运行文件,/etc/rabbitmq/ssl 存放 RabbitMQ 的 SSL 证书。两者单独丢失影响有限,但由于挂载配置中默认包含它们(见 docker-compose.yaml),备份时顺手带上即可,成本几乎为零。

🛠️ 三种部署方式的持久化挂载实操

Docker Compose:一键挂载全部目录

仓库自带的 docker-compose.yaml 已把 7 个路径全部映射到宿主机,只需把 /path/to/unifi-os-server 改为你实际存放数据的目录:

volumes:
  - /path/to/unifi-os-server/persistent:/persistent
  - /path/to/unifi-os-server/var-log:/var/log
  - /path/to/unifi-os-server/data:/data
  - /path/to/unifi-os-server/srv:/srv
  - /path/to/unifi-os-server/var-lib-unifi:/var/lib/unifi
  - /path/to/unifi-os-server/var-lib-mongodb:/var/lib/mongodb
  - /path/to/unifi-os-server/etc-rabbitmq-ssl:/etc/rabbitmq/ssl

💡 小贴士:/run、/tmp 等目录被特意配置为 tmpfs(docker-compose.yaml),因为它们只存运行时临时数据,不需要持久化。

Home Assistant:自动持久化 + 自动备份

如果你通过 Home Assistant 应用安装,持久化和备份基本是"零操作"的:所有目录(/data、/persistent、/var/log、/srv、/var/lib/unifi、/var/lib/mongodb、/etc/rabbitmq/ssl)都会绑定挂载到应用的 config 文件夹(addon_configs/<slug>),并自动纳入 Home Assistant 的全局备份。详见 ha-app/DOCS.md。

⚠️ 注意:卸载应用时,除非你勾选删除数据,否则该文件夹会被保留——这其实是个"天然备份点"。

Kubernetes:一个 PVC 统一托管

K8s 方案(kubernetes/ 目录)用一个 PersistentVolumeClaim 管理全部数据。kubernetes/pvc.yaml 默认申请 32Gi 空间(基于 longhorn 存储),kubernetes/deployment.yaml 通过 subPath 把 PVC 切分成 6 个数据子目录分别挂载。

这样做的好处:备份、扩容、迁移时只需操作一个卷,且 Deployment 使用 Recreate 策略,避免新旧 Pod 争抢同一数据目录。

📦 备份策略:三步让数据永不丢失

第一步:整体打包,简单可靠。 6 个目录可以统一放进一个父目录,用 tar 或 rsync 一键打包。由于目录结构是固定的,恢复时按原结构放回挂载路径即可。

第二步:数据库备份要讲究一致性。 /var/lib/mongodb 在数据库写入过程中直接拷贝文件可能损坏。推荐两种做法(二选一):

  • 停容器 → 打包 → 启容器(最简单,中断时间短)
  • 用 mongodump 做逻辑备份(不停机,但需要进入容器执行)

第三步:异地 + 定时 + 验证。

  • 📅 定时:用 crontab 或备份软件每天/每周自动执行
  • ☁️ 异地:至少保留一份在异地或对象存储上("3-2-1 备份原则":3 份数据、2 种介质、1 份异地)
  • ✅ 验证:每季度做一次恢复演练——备份只有能被恢复才算数

❓ 常见误区自查清单

误区 正确做法
只备份 /persistent 就够了 7 个挂载点一个都不能少,/var/lib/mongodb 才是核心
容器重建后重新 adopt 设备即可 数据库没了意味着全部配置、历史数据清零
把日志目录 /var/log 也忽略掉 建议纳入备份,排障时价值极高
备份完从不恢复测试 定期恢复演练,确认备份真正可用

总结

unifi-os-server 的数据持久化并不神秘:记住 /var/lib/mongodb、/data、/persistent、/var/lib/unifi、/var/log、/srv + /etc/rabbitmq/ssl 这 6 大关键目录,把 docker-compose.yaml 的挂载配置抄起来(或直接用 Home Assistant / K8s 的现成方案),再配合"定时打包 + 数据库一致性备份 + 异地存放"的组合拳,你的 UniFi OS Server 就可以放心地跑下去了。数据在,一切皆可恢复。

登录后查看全文
unifi-os-server