让数据永不丢失:unifi-os-server 持久化与备份的 6 大关键目录
让数据永不丢失: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 就可以放心地跑下去了。数据在,一切皆可恢复。