Unifi-in-Docker (unifi-docker)

这是Ubiquiti Networks Unifi Controller的Docker化版本。

为什么需要它？

用Docker部署Unifi Controller，能省去版本兼容、Java依赖或操作系统更新的麻烦——容器把所有组件打包成一个经过充分测试的整体。安装只需几行命令，升级时停掉旧容器、启动新容器即可，就是这么简单。

该容器已在Ubuntu、Debian、macOS、Windows甚至树莓派上测试通过。

当前信息

最新“稳定版”为Unifi Controller 7.1.68，目前无影响该版本的热修复或CVE安全警告。

安装、运行、停止与升级

前提：安装Docker

先在“Docker主机”（运行Docker和Unifi Controller的机器）上安装Docker。可参考网上的安装指南，Windows用户可查看微软Docker安装教程。

第一步：创建目录（一次性操作）

在Docker主机上创建unifi目录，并在其中新建data和log子目录，用于存储配置和日志：

cd  # 默认使用当前用户的家目录
mkdir -p unifi/data
mkdir -p unifi/log

注：本文默认Linux/Unix/macOS用户使用家目录存放unifi目录。若需自定义路径，可参考下文“命令行选项”调整。

第二步：启动Unifi容器

每次启动Unifi时，执行以下命令（各参数说明见下文“命令行选项”）：

docker run -d --init \
   --restart=unless-stopped \
   -p 8080:8080 -p 8443:8443 -p 3478:3478/udp \
   -e TZ='Africa/Johannesburg' \
   -v ~/unifi:/unifi \
   --user unifi \
   --name unifi \
   jacobalberty/unifi

等待1-2分钟（Unifi Controller启动后），访问`[***]

启动注意事项

1. 证书警告：首次访问时浏览器会提示“不受信任的证书”，确认Docker主机地址正确后，同意继续连接。
2. 设置“Inform Host”IP：Unifi设备需要通过Docker主机的IP找到控制器，需按下文“设备接入”步骤配置。

第三步：停止容器

如需修改启动参数，先停止并删除容器，再用新参数重新运行（docker rm仅删除容器名称，无需重建）：

docker stop unifi
docker rm unifi

第四步：升级Unifi Controller

Unifi的配置和数据默认保存在Docker主机的~/unifi目录（容器内无数据留存）。升级只需拉取新版本容器，复用本地配置：

1. 务必备份：将配置备份到其他设备（每次升级必做）。
2. 按上述步骤停止当前容器。
3. 用新版本标签重新执行docker run命令（标签说明见下文“支持的标签”）。

命令行选项说明

docker run命令的关键参数如下：

支持的镜像标签

通过标签指定Unifi Controller版本，默认（无标签）为最新稳定版。常见标签如下：

多架构支持

所有镜像均支持amd64、armhf、arm64架构。armhf架构目前依赖MongoDB 3.4，因32位ARM缺乏MongoDB支持，后续可能逐步淘汰，但至少支持到Ubuntu 18.04停止维护。

设备接入与控制器发现

覆盖“Inform Host”IP

Unifi设备需通过Docker主机IP找到控制器（容器默认IP为172.17.x.x，设备连接的是主机外部IP），需手动覆盖Inform Host：

1. 登录Unifi Controller Web界面，进入设置 > 系统 > 其他配置 > 覆盖Inform主机（页面底部）。
2. 勾选“启用”，填入Docker主机的IP地址，保存设置。
3. 重启容器（docker stop unifi + docker run ...）。

其他接入方法可参考Side Projects。

卷说明

容器内/unifi目录包含以下关键子目录（数据持久化到主机~/unifi）：

环境变量

通过-e参数设置，常用变量如下：

暴露端口

必选端口（启动命令已包含）：

• 8080/tcp：设备控制
• 8443/tcp：Web界面+API
• 3478/udp：STUN服务

可选端口（按需添加-p映射）：

• 8843/tcp：HTTPS门户
• 8880/tcp：HTTP门户
• 6789/tcp：测速（仅unifi5）

更多端口说明见UniFi - Ports Used。

非root用户运行

默认容器以root运行，推荐用--user unifi（uid/gid 999/999）以非root用户启动。注意：

• 非root用户默认无法绑定1024以下端口，如需绑定，需添加--sysctl net.ipv4.ip_unprivileged_port_start=0参数。

证书配置

自定义SSL证书需挂载卷到/unifi/cert，文件命名规则：

• cert.pem：证书文件
• privkey.pem：私钥
• chain.pem：证书链

如需自定义文件名，通过环境变量CERTNAME（证书名）和CERT_PRIVATE_NAME（私钥名）指定，如-e CERTNAME=my-cert.pem。Let's Encrypt证书会自动添加Identrust X3 CA链，若证书已包含链，可设CERT_IS_CHAIN=true。

补充信息

本文已涵盖基础操作，更多技术细节可参考Side Projects and Background Info。

TODO

目前暂无待办事项，欢迎通过Issues提出建议。