本文介绍如何修复出现数据库故障的 UniFi 网络应用。请注意，本指南仅适用于在 Windows/macOS/Linux 设备上自行托管最新版本 UniFi Network Server 的用户（Legacy/Gen1 方式除外）。

如果你通过传统方式运行 UniFi 网络应用（如使用 Vintage CloudKey Gen 1 或基于 32 位的 UniFi 网络服务器），请参考本文最后的章节。由于这些设备已不再受支持，我们强烈建议升级到最新版本的 UniFi 网络应用，或新增 UniFi 控制台，以便获得更轻松、高效的体验和可扩展性。

常见症状

统计数据仅记录数日后中断，或只间歇性可用。
无法生成包含统计数据的备份。
仅设置备份无法完成，或虽创建但因损坏无法还原。
打开 UniFi 网络应用时出现 400 错误。
UniFi 网络应用服务因数据库错误无法启动。

Debian 系 Linux 数据库修复方法

停止 UniFi 服务
```
service unifi stop
```

若 journal 文件损坏，可先执行如下命令将其移动备份：

mv -vi /usr/lib/unifi/data/db/journal /usr/lib/unifi/data/db/journal-$(date -I)

执行数据库修复：

mongod --dbpath /usr/lib/unifi/data/db --logpath /usr/lib/unifi/logs/mongod.log --repair

重启 UniFi 服务：
```
service unifi start
```
- 注意： 若以 root 身份执行上述操作，可能导致文件归属发生更改。可使用如下命令恢复权限：
```
chown -R unifi:unifi /usr/lib/unifi/data/db/
chown -R unifi:unifi /usr/lib/unifi/logs/
```

如果仍有数据库问题，建议迁移到 CloudKey Gen2 Plus 或 Dream Machine Pro，这些 UniFi 控制台不会出现类似数据库损坏问题。

macOS 数据库修复方法

创建临时工作目录，本例命名为 /repair：
```
  mkdir ~/repair
```
访问 MongoDB 官网，下载与你服务器 CPU 架构相符的 .tgz 包。
- （也可直接下载 2.4.14 版本：2.4.14.tgz）
将下载的软件包移入工作目录，并解压缩。
定位至 bin/mongo 可执行文件，复制到工作目录，其余文件可删除，仅此文件需要。
打开终端，切换到工作目录：
```
cd ~/repair
```
关闭或停止 UniFi。

执行数据库修复：

mongod --dbpath ~/Library/Application\ Support/UniFi/data/db --logpath ~/Library/Application\ Support/UniFi/logs/mongod.log --repair

通过 Finder 打开 UniFi 应用：
```
open -n /Applications/UniFi.app
```

如修复后仍有数据库问题，建议升级至 CloudKey Gen2 Plus 或 Dream Machine Pro，杜绝数据库损坏。

Windows 数据库修复方法

访问 MongoDB 官网，下载与你 CPU 架构相符的 .zip 包。
- 注意：最低需 3.6 版 MongoDB，最高支持至 4.4。
将 \bin\mongod.exe 解压到你选择的任意工作目录（本例中为 C:\repair\）。你可以忽略 .zip 压缩包中的其他所有文件。
关闭或停止 UniFi。
按 WINDOWS + R 打开运行窗口，输入 cmd 并回车，打开命令提示符。
切换至工作目录：
```
cd C:\repair\
```

执行数据库修复命令：

mongod.exe --dbpath "%userprofile%\Ubiquiti UniFi\data\db" --logpath "%programfiles%\Ubiquiti UniFi\logs\mongod.log" –repair

启动 UniFi 应用。

如修复后仍有数据库问题，建议升级至 CloudKey Gen2 Plus 或 Dream Machine Pro，这些产品不会出现数据库损坏。

传统说明

32位 MongoDB 限制
32位 MongoDB 的集合总大小限制为 2GB。在使用 MMAPv1 存储引擎时，这会导致在尝试缩小所有集合大小时出现问题。当在 MongoDB 上执行 compact 命令时，数据库会被重写和整理碎片，但不会进行错误修复。对于采用 MMAPv1 存储引擎的环境，此过程并不会为 UniFi 控制台释放可用磁盘空间。

若想在 32 位 MongoDB 实例上回收有价值的磁盘空间，必须执行数据库修复操作。若怀疑数据库存在无效条目、损坏或集合扩展异常等问题，也同样需要执行此修复。需要注意的是，要执行数据库修复，CloudKey 必须有“现有数据集大小+2GB”数量的可用磁盘空间。如果数据集已大到无法继续使用 db.repairDatabase() 命令进行修复，可参考下文的绕过方法。

注意：Legacy CloudKey (UC CK) 硬件规格如下：
- 32位架构
- MMAPv1
- MongoDB 2.4.10

Vintage CloudKey (Gen 1) 数据库修复方法
1. SSH 登录到 CloudKey。
2. 下载 mongo 剪枝脚本。该脚本仅保留最近 7 天的数据条目，并不会移除 UniFi 管理所需的内容。请按照以下命令下载：
```
cd /tmp/
wget https://help.ui.com/hc/en-us/article_attachments/360008640574/CK_repair.js
```
3. 停止 UniFi 服务：
```
service unifi stop
```
4. UniFi 服务会关闭 mongo 进程。请确保 UniFi 服务已完全停止。然后，执行数据库修复以整理数据条目并释放未使用的磁盘空间。
```
mongod --dbpath /usr/lib/unifi/data/db --logpath /usr/lib/unifi/logs/server.log --repair
```
  - 注意：若需大量清理数据库空间，可继续以下步骤（5-8，非必需）。
5. 重启 mongo 服务：
```
mongod --dbpath /usr/lib/unifi/data/db --logpath /usr/lib/unifi/logs/server.log --journal --bind_ip 127.0.0.1 --fork
```
  - 注意：您的 mongo 数据库可能并未启用 Journaling。如未启用，请在上述命令中移除 --journal 参数。
6. 执行脚本以清理导致问题的统计数据集合：
```
mongo < /tmp/CK_repair.js
```
7. 关闭 mongo 服务：
```
mongod --dbpath /usr/lib/unifi/data/db --logpath /usr/lib/unifi/logs/server.log --shutdown
```
  - 注意：CK_repair.js 脚本中的最后一条命令是 "db.repairDatabase()"；如果统计数据集合过大且 mongo 服务仍在运行，该命令可能会出错，遇到此类报错请回到第 3 步用命令行再次修复数据库。
8. 重启 UniFi 服务：
```
service unifi start
```
至此 CloudKey 应可继续运行网络应用。如仍有数据库问题，建议升级到 CloudKey Gen2 Plus，以消除此类问题。

MMAPv1 迁移到 WiredTiger
注意：本节不适用于 32 位架构主机（如 UC-CK G1）。

当 UniFi 网络恢复运行后，建议迁移到 WiredTiger 存储引擎。
- 查看空间占用执行：
```
du -shc /usr/lib/unifi/data/db/ace* /usr/lib/unifi/data/db/journal/* /usr/lib/unifi/data/db/local* | grep total
```
- 查看 MongoDB 版本：
```
mongod --version | grep "db version"
```
- 查看当前存储引擎类型：
```
mongo localhost:27117
db.serverStatus().storageEngine.name
```
迁移步骤
1. 在 设置 > 维护 > 备份 中创建本地备份。
2. 在 Windows 或 macOS 上卸载 UniFi；Debian 系 Linux 下用以下命令彻底删除：
```
sudo dpkg -P unifi
```
3. 重新安装 UniFi（Windows/macOS）；或在 Debian 系 Linux 下用命令：
```
cd /tmp/
wget <下载链接>
sudo dpkg -i unifi_sysvinit_all.deb
```
4. 在 UniFi 向导中，导入步骤 1 的备份完成恢复。