linuxserver/unifi Docker镜像文档

镜像概述和主要用途

⚠️ 注意：该镜像已废弃。请使用多架构镜像 linuxserver/unifi-controller
更多信息：[***]

linuxserver/unifi 是由 LinuxServer.io 团队开发的Docker容器，用于运行 UniFi® Controller 软件。UniFi Controller是一款功能强大的企业级无线管理软件引擎，主要用于集中管理UniFi系列网络设备（如无线接入点、交换机、安全网关等）。

核心功能与特性

• 企业级网络管理：提供对UniFi设备的集中配置、监控和维护能力
• 高密度部署支持：优化用于高客户端密度环境，确保低延迟和高可用性
• 多设备兼容：支持UniFi接入点、交换机、安全网关等全系列产品
• 灵活的网络配置：支持VLAN、QoS、负载均衡、访客网络等企业级功能
• 数据可视化：提供网络流量、设备状态、客户端活动等实时监控报表

使用场景与适用范围

• 企业办公网络：集中管理办公室内多个无线接入点和网络设备
• 高密度环境：会议中心、学校、体育馆等需要支持大量并发客户端的场景
• 多地点网络：通过广域网集中管理分布在不同物理位置的UniFi设备
• 测试与演示环境：快速部署UniFi Controller进行功能测试或方案演示

使用方法

Docker Run 命令

bash
docker run -d \
  --name=unifi \
  -v <宿主机数据路径>:/config \
  -e PUID=<用户ID> -e PGID=<组ID> \
  -p 3478:3478/udp \
  -p ***:***/udp \
  -p 8080:8080 \
  -p 8081:8081 \
  -p 8443:8443 \
  -p 8843:8843 \
  -p 8880:8880 \
  -p 6789:6789 \
  --restart unless-stopped \
  linuxserver/unifi

Docker Compose 配置

yaml
version: "2.1"
services:
  unifi:
    image: linuxserver/unifi
    container_name: unifi
    volumes:
      - <宿主机数据路径>:/config
    environment:
      - PUID=<用户ID>
      - PGID=<组ID>
    ports:
      - 3478:3478/udp
      - ***:***/udp
      - 8080:8080
      - 8081:8081
      - 8443:8443
      - 8843:8843
      - 8880:8880
      - 6789:6789
    restart: unless-stopped

镜像标签说明

配置参数说明

端口映射

环境变量

数据卷

应用设置

首次访问与配置

1. 容器启动后，通过 https://<宿主机IP>:8443 访问Web管理界面
2. 首次登录将启动设置向导，按提示完成基本网络配置
3. 设置管理员账户和密码，配置网络名称（SSID）和安全策略

设备 Adoption（接入）

自动发现配置

1. 进入 设置 > 控制器 > 控制器设置
2. 将 控制器主机名/IP 设置为宿主机可被设备访问的IP地址
3. 保存设置后，新设备将自动出现在"未接入设备"列表中

手动接入设备

若自动发现失败，可通过SSH手动接入：

bash
# 登录接入点（默认用户名：ubnt，密码：ubnt）
ssh ubnt@<接入点IP>

# 进入mca-cli模式
mca-cli

# 设置控制器地址（替换<宿主机IP>为实际IP）
set-inform http://<宿主机IP>:8080/inform

常见问题解决

安全网关（USG）下客户端无法获取IP地址

问题原因：DHCP服务配置错误
解决方法：

1. 进入 设置 > 网络 > <网络名称>
2. 将 DHCP网关IP 设置为可访问的网关IP地址（通常为USG的LAN口IP）
3. 保存配置并重启DHCP服务

附加信息

Shell访问

bash
docker exec -it unifi /bin/bash

实时日志查看

bash
docker logs -f unifi

版本查询

• 容器版本：

  bash
  docker inspect -f '{{ index .Config.Labels "build_version" }}' unifi
  

• 镜像版本：

  bash
  docker inspect -f '{{ index .Config.Labels "build_version" }}' linuxserver/unifi
  

版本历史

• 14.09.18: 更新至5.6.40版本
• 06.07.18: 更新至5.6.39版本
• 26.04.18: 更新至5.6.37版本
• 24.03.18: 更新至5.6.36版本
• 14.03.18: 添加5.7.x不稳定分支支持
• 19.02.18: 添加6789端口支持吞吐量测试
• 09.02.18: 更新至5.6.30版本
• 08.01.18: 更新至5.6.29版本
• 15.12.17: 更新至5.6.26版本
• 12.11.17: 添加STUN服务器端口3478映射
• 11.11.17: 更新至5.6.22版本
• 05.10.17: 更新至5.5.24版本
• 03.08.17: 更新至5.5.20版本
• 15.07.17: 切换为.deb包安装方式
• 02.11.15: 初始版本发布