本文仅适用于在 Windows/macOS/Linux 设备上自建 UniFi 网络服务器的 高级用户，帮助诊断并优化在高负载下运行的自建 UniFi 网络服务器。我们通常建议添加 UniFi 控制台，以获得最简便且可扩展的体验。

以下设置位于 UniFi 网络应用的 system.properties 文件中，该文件可在安装路径下的 \Ubiquiti UniFi\data 文件夹找到。如果文件中没有相关设置，可以直接作为新行添加。

注意事项与要求：

  • 请确保您正在运行最新版 UniFi Network（可在此处获取）。
  • 本文涉及高级配置选项，仅推荐 高级用户尝试。
  • 在按照本文说明操作前，请先创建备份。有关详细信息，请参阅 UniFi - 备份与迁移。

当自建 UniFi 网络服务器并连接上百台、跨多站点的 UniFi 设备时，请格外注意。这种高负载会导致系统性能下降，若未优化则情况更为明显。

症状：CPU 占用率高

需重点监控的重要指标之一是 UniFi 网络服务器的 CPU 使用率。CPU 利用率过高是出现问题的初步信号。不幸的是，没有简单的解决办法，单纯提升 CPU 并不总能解决问题。

  1. 分配更多内存

    在增加计算机物理内存之前，请先尝试提升 `XMX` 与 `XMS` 选项。默认情况下，UniFi 网络应用会将这两个参数设为 1GB。下面这两行将 xmx 与 xms 的值提升至 2GB（2048MB）：

    unifi.xmx=2048
unifi.xms=2048

    上述更改会将 UniFi 网络应用可用内存从 1GB 提升至 2GB。在考虑换用拥有更多 CPU 资源的服务器之前，推荐先用上述设置将现有机器的可用内存配置到最大，观察是否能降低 CPU 占用率。

    如果 2GB 不够，管理员可根据实际规模将上限提高至 4、8、16 甚至 32GB。此时，只需将上述参数按 1024 递增即可，例如 4GB=4096。

    注意：可使用 jstat -gcutil Java 命令检测计算机内存分配是否充足。详见 Oracle 文档。

  1. 提升 Mongo WiredTiger 引擎缓存

    如已将 UniFi 网络应用的内存设置提升到至少 4GB（xmx），则可能还需调整 Mongo WiredTiger 的默认引擎缓存。默认配置如下：

    db.mongo.wt.cache_size=256

    在 UniFi Network 6.5.13 及以上版本，可以通过如下设置修改该参数或者让 Mongo 自动选择默认值：

    db.mongo.wt.cache_size_default=true

    更多信息请参考 Mongo 文档。

  1. 启用高性能 Java 垃圾回收器

    如果增加内存后问题依旧，管理员可以在 system.properties 文件中添加如下行：

    unifi.G1GC.enabled=true

    该选项会启用新的 Java 垃圾回收器，帮助优化性能。但如果在上述更改后 CPU 占用率仍未降低，说明需要换用拥有更多 CPU 核心与更大内存的服务器来处理负载。

  1. 更改 Mongo 版本/引擎

    在问题长期存在的情况下，管理员可以考虑将 MongoDB 升级到更高版本，以提升 UniFi Network 部署的可扩展性。对于 UniFi Network 应用，支持的 MongoDB 最低版本为 3.6，最高版本为 4.4。

    请注意，根据您的当前 MongoDB 版本和目标版本，升级过程可能需要分阶段进行。更多信息请参阅 Mongo 升级手册：

症状：心跳丢失或上线缓慢

所有设备均通过与 UniFi Network 通信来工作。这些定时通知消息称为“心跳”。应用默认可同时处理 200 台设备的心跳，除非管理了数千台设备，否则一般不会丢失。可通过在 system.properties 文件中加入下列行并适当调整数值配置最大并发心跳数量，任意位置添加均可。

inform.num_thread=200
inform.max_keep_alive_requests=100

默认值为 200，max_keep_alive_requests 应始终低于 num_thread。可以逐步调整此参数。这样应能提升设备的稳定性，同时将配置下发到其他设备，也会变得更加稳定。

数据库连接参数调优

在大规模 UniFi 部署中，建议独立部署外部 Mongo 集群，实现数据库与 UniFi 网络应用解耦。相关讨论可在我们的社区 Beta 论坛找到。如果观察到 Mongo 进程的高 CPU 使用率，说明服务器需要更高配置，或如前述将 mongodb 进程拆分。调整如下参数，可以进一步提升应用性能：

db.mongo.connections_per_host=500

这样可以允许最多 500 个线程同时等待 Mongo 连接。需要注意的是，线程数越多会导致更高的 CPU 占用，因为 CPU 需在不同线程间切换。此配置可能增加数据库吞吐，但前提是 Mongo 进程有足够多的 CPU 资源以更快地处理请求。