UniFi Controller Docker镜像

概述和主要用途

UniFi Controller Docker镜像是将Ubiquiti Networks的UniFi Controller软件打包为容器的解决方案，用于集中管理UniFi系列网络设备（无线接入点、交换机、安全网关等）。该镜像通过容器化部署简化了UniFi Controller的安装与维护流程，无需复杂系统配置即可快速搭建网络管理平台，支持设备配置、状态监控、固件更新及故障排查等核心功能。

核心功能和特性

• 容器化部署：基于Docker容器运行UniFi Controller，降低环境依赖，简化跨平台部署流程。
• 数据持久化：支持通过Docker数据卷挂载持久化存储配置文件、设备数据及日志，确保重启或升级后数据不丢失。
• 版本灵活控制：可通过环境变量指定UniFi Controller版本，支持不同版本控制器的部署与测试。
• 权限精细管理：通过PUID/PGID环境变量配置容器运行用户权限，避免主机权限冲突问题。
• 时区自定义：支持通过TZ环境变量设置控制器时区，确保日志与时间相关功能准确性。
• 网络端口映射：预设UniFi Controller所需网络端口（管理界面、设备通信、STUN服务等），支持自定义端口映射适配不同网络环境。

使用场景和适用范围

• 家庭网络管理：家庭用户部署UniFi无线接入点时，通过容器快速搭建控制器，简化家庭无线网络配置与设备管理。
• 小型企业网络：企业环境中无需专用服务器，通过容器化控制器集中管理办公网络设备，降低IT维护成本。
• 测试与演示环境：开发或测试场景下，快速部署不同版本控制器，验证网络配置方案或新功能兼容性。
• 多环境一致性：通过Docker确保开发、测试、生产环境中控制器配置一致，减少环境差异导致的问题。

使用方法和配置说明

前提条件

• 已安装Docker Engine（20.10+推荐）及Docker Compose（可选，用于编排）。
• 主机需满足UniFi Controller系统要求：建议至少2GB RAM、2 CPU核心，且未占用控制器所需端口。

基础部署（docker run命令）

通过以下命令启动UniFi Controller容器：

docker run -d \
  --name=unifi-controller \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Asia/Shanghai \
  -p 8080:8080 \
  -p 8443:8443 \
  -p 3478:3478/udp \
  -p 10001:10001/udp \
  -p 8843:8843 \
  -p 8880:8880 \
  -p 6789:6789 \
  -v /path/to/unifi/data:/config \
  --restart unless-stopped \
  nexusforge/unifi-controller

参数说明：

• -d：后台运行容器
• --name=unifi-controller：指定容器名称
• 环境变量：
  • PUID=1000/PGID=1000：容器运行用户/组ID（需与主机挂载目录权限匹配）
  • TZ=Asia/Shanghai：时区设置（格式示例：Europe/London、America/New_York）
• 端口映射（不可省略，设备通信必需）：
  • 8080/tcp：设备与控制器通信端口
  • 8443/tcp：Web管理界面HTTPS端口
  • 3478/udp：STUN服务端口
  • 10001/udp：设备发现端口
  • 8843/tcp/8880/tcp：备用HTTPS/HTTP端口（部分设备使用）
  • 6789/tcp：UniFi移动应用通信端口
• -v /path/to/unifi/data:/config：挂载数据卷（替换/path/to/unifi/data为实际主机目录，用于持久化配置）
• --restart unless-stopped：容器退出时自动重启（手动停止除外）
• nexusforge/unifi-controller：Docker镜像名称

Docker Compose部署

创建docker-compose.yml文件，内容如下：

version: '3'

services:
  unifi-controller:
    image: nexusforge/unifi-controller
    container_name: unifi-controller
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
      # 可选：指定控制器版本，如UNIFI_VERSION=7.5.176
      # - UNIFI_VERSION=7.5.176
    ports:
      - "8080:8080"
      - "8443:8443"
      - "3478:3478/udp"
      - "10001:10001/udp"
      - "8843:8843"
      - "8880:8880"
      - "6789:6789"
    volumes:
      - /path/to/unifi/data:/config
    restart: unless-stopped

启动服务：

docker-compose up -d

环境变量配置

访问与初始配置

1. 容器启动后，通过浏览器访问 https://<主机IP>:8443 打开Web管理界面（首次访问可能提示证书不安全，忽略警告继续）。
2. 按照向导完成初始配置：
   • 创建管理员账户
   • 设置网络名称（SSID）及密码
   • 发现并 adoption UniFi设备（确保设备与控制器网络互通）

注意事项

• 端口冲突：确保主机未占用8443、8080等关键端口，可通过netstat -tulpn检查端口占用情况。
• 目录权限：主机挂载目录需赋予容器运行用户读写权限，可执行chown -R 1000:1000 /path/to/unifi/data配置权限。
• 版本升级：修改UNIFI_VERSION环境变量指定新版本，重启容器后自动下载安装对应版本。
• 设备通信：UniFi设备需能访问控制器的8080端口以完成注册，建议设备与控制器在同一局域网或配置端口转发。