steynovich/unifi

UniFi Controller Docker镜像文档

镜像概述

本镜像为基于Linux系统的UniFi控制器（UniFi Controller），用于集中管理Ubiquiti Networks的UniFi系列网络设备，包括无线接入点（AP）、路由器、交换机、安全网关等。通过该镜像可快速部署UniFi控制器服务，实现网络设备的统一配置、监控与管理。

核心功能与特性

1. 设备集中管理

• 支持UniFi全系列网络设备的发现、配置与管理
• 提供设备状态实时监控（在线状态、连接客户端数、信号强度等）
• 支持批量设备配置与固件更新

2. 网络监控与分析

• 实时网络流量监控与统计
• 客户端连接历史记录与流量分析
• 网络异常事件告警（设备离线、连接中断等）

3. 配置管理

• 网络拓扑可视化展示
• 自定义网络配置（SSID、VLAN、QoS策略等）
• 配置备份与恢复功能

4. 多站点与用户管理

• 支持多站点网络独立管理
• 基于角色的用户权限控制（管理员、只读用户等）
• 跨站点设备迁移与配置同步

使用场景

• 企业网络管理：中小型企业网络设备集中管控，简化IT运维
• 家庭/小型办公网络：统一管理家庭或SOHO环境中的UniFi设备
• 多地点网络：连锁店、分支机构等多地点网络的远程统一管理
• 临时网络部署：展会、活动等临时场景的快速网络搭建与管理

使用方法与配置说明

1. 基本部署（docker run）

bash
docker run -d \
  --name=unifi-controller \
  --restart=always \
  -p 8080:8080 \  # 设备通信端口（TCP）
  -p 8443:8443 \  # Web管理界面（HTTPS，TCP）
  -p 8843:8843 \  # HTTPS备用端口（TCP）
  -p 8880:8880 \  # HTTP备用端口（TCP）
  -p 3478:3478/udp \  # STUN服务端口（UDP）
  -v /path/to/unifi/data:/var/lib/unifi \  # 数据持久化目录
  -e TZ=Asia/Shanghai \  # 设置时区
  linuxserver/unifi-controller:latest  # 镜像名称（以实际为准）

2. Docker Compose配置

yaml
version: '3'
services:
  unifi-controller:
    image: linuxserver/unifi-controller:latest
    container_name: unifi-controller
    restart: always
    ports:
      - "8080:8080"    # 设备通信
      - "8443:8443"    # Web管理界面（HTTPS）
      - "8843:8843"    # HTTPS备用
      - "8880:8880"    # HTTP备用
      - "3478:3478/udp" # STUN
    volumes:
      - ./unifi-data:/var/lib/unifi  # 本地数据目录
    environment:
      - TZ=Asia/Shanghai  # 时区设置
      - PUID=1000         # 运行用户ID（可选）
      - PGID=1000         # 运行用户组ID（可选）

3. 关键配置说明

3.1 数据持久化

• 必须挂载数据卷：/var/lib/unifi 目录包含控制器配置、设备信息、日志等关键数据，需通过 -v 参数挂载至宿主机目录，避免容器重启后数据丢失。

3.2 端口映射

3.3 环境变量

4. 访问与初始化

1. 部署完成后，通过浏览器访问 https://宿主机IP:8443 进入Web管理界面
2. 首次访问需完成初始化设置：创建管理员账户、设置站点名称、接受用户协议
3. 初始化后，控制器将自动发现网络中的UniFi设备，按照向导完成设备 adoption（认领）与配置

5. 升级与维护

• 镜像更新：

  bash
  docker pull linuxserver/unifi-controller:latest
  docker stop unifi-controller
  docker rm unifi-controller
  # 重新执行docker run命令或docker-compose up -d
  

• 数据备份：定期备份挂载的 /var/lib/unifi 目录，可通过 tar -zcvf unifi-backup.tar.gz /path/to/unifi/data 实现

注意事项

• 生产环境中建议启用HTTPS（8443端口），禁用HTTP（8880端口）
• 确保宿主机时间与控制器时间同步，避免证书或日志时间异常
• 大规模部署（>50台设备）建议增加内存资源（至少2GB RAM）
• 跨网段设备管理需确保8080端口在网络层可达