LinuxServer.io提供的Unifi容器,用于运行Unifi控制器以管理Ubiquiti网络设备。
linuxserver/unifi Docker镜像文档
镜像概述和主要用途
⚠️ 注意:该镜像已废弃。请使用多架构镜像 linuxserver/unifi-controller
更多信息:https://blog.linuxserver.io/2019/02/18/changes-to-our-unifi-image/
linuxserver/unifi 是由 https://linuxserver.io 团队开发的Docker容器,用于运行 UniFi® Controller 软件。UniFi Controller是一款功能强大的企业级无线管理软件引擎,主要用于集中管理UniFi系列网络设备(如无线接入点、交换机、安全网关等)。
核心功能与特性
- 企业级网络管理:提供对UniFi设备的集中配置、监控和维护能力
- 高密度部署支持:优化用于高客户端密度环境,确保低延迟和高可用性
- 多设备兼容:支持UniFi接入点、交换机、安全网关等全系列产品
- 灵活的网络配置:支持VLAN、QoS、负载均衡、访客网络等企业级功能
- 数据可视化:提供网络流量、设备状态、客户端活动等实时监控报表
使用场景与适用范围
- 企业办公网络:集中管理办公室内多个无线接入点和网络设备
- 高密度环境:会议中心、学校、体育馆等需要支持大量并发客户端的场景
- 多地点网络:通过广域网集中管理分布在不同物理位置的UniFi设备
- 测试与演示环境:快速部署UniFi Controller进行功能测试或方案演示
使用方法
Docker Run 命令
bashdocker run -d \ --name=unifi \ -v <宿主机数据路径>:/config \ -e PUID=<用户ID> -e PGID=<组ID> \ -p 3478:3478/udp \ -p 10001:10001/udp \ -p 8080:8080 \ -p 8081:8081 \ -p 8443:8443 \ -p 8843:8843 \ -p 8880:8880 \ -p 6789:6789 \ --restart unless-stopped \ docker.xuanyuan.run/linuxserver/unifi
Docker Compose 配置
yamlversion: "2.1" services: unifi: image: docker.xuanyuan.run/linuxserver/unifi container_name: unifi volumes: - <宿主机数据路径>:/config environment: - PUID=<用户ID> - PGID=<组ID> ports: - 3478:3478/udp - 10001:10001/udp - 8080:8080 - 8081:8081 - 8443:8443 - 8843:8843 - 8880:8880 - 6789:6789 restart: unless-stopped
镜像标签说明
| 标签 | 说明 |
|---|---|
latest | 基于5.6.x "LTS Stable" 稳定分支 |
unstable | 基于5.9.x "Unstable" 测试分支 |
配置参数说明
端口映射
| 宿主机端口 | 容器端口 | 协议 | 用途说明 |
|---|---|---|---|
| 3478 | 3478 | UDP | STUN服务器端口 |
| *** | *** | UDP | 接入点发现端口 |
| 8080 | 8080 | TCP | 设备通信端口(inform接口) |
| 8081 | 8081 | TCP | 内部服务端口 |
| 8443 | 8443 | TCP | Web管理界面HTTPS端口 |
| 8843 | 8843 | TCP | 备用HTTPS端口 |
| 8880 | 8880 | TCP | 备用HTTP端口 |
| 6789 | 6789 | TCP | 吞吐量测试端口 |
环境变量
| 参数 | 说明 |
|---|---|
| PUID | 运行容器的用户ID,用于权限控制,通过 id <用户名> 命令获取 |
| PGID | 运行容器的组ID,用于权限控制,通过 id <用户名> 命令获取 |
数据卷
| 宿主机路径 | 容器路径 | 说明 |
|---|---|---|
<宿主机数据路径> | /config | 存储UniFi Controller的配置、日志和数据库 |
应用设置
首次访问与配置
- 容器启动后,通过
https://<宿主机IP>:8443访问Web管理界面 - 首次登录将启动设置向导,按提示完成基本网络配置
- 设置管理员账户和密码,配置网络名称(SSID)和安全策略
设备 Adoption(接入)
自动发现配置
- 进入 设置 > 控制器 > 控制器设置
- 将 控制器主机名/IP 设置为宿主机可被设备访问的IP地址
- 保存设置后,新设备将自动出现在"未接入设备"列表中
手动接入设备
若自动发现失败,可通过SSH手动接入:
bash# 登录接入点(默认用户名:ubnt,密码:ubnt) ssh ubnt@<接入点IP> # 进入mca-cli模式 mca-cli # 设置控制器地址(替换<宿主机IP>为实际IP) set-inform http://<宿主机IP>:8080/inform
常见问题解决
安全网关(USG)下客户端无法获取IP地址
问题原因:DHCP服务配置错误
解决方法:
- 进入 设置 > 网络 > <网络名称>
- 将 DHCP网关IP 设置为可访问的网关IP地址(通常为USG的LAN口IP)
- 保存配置并重启DHCP服务
附加信息
Shell访问
bashdocker exec -it unifi /bin/bash
实时日志查看
bashdocker 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: 初始版本发布
更多相关 Docker 镜像与资源
以下是 linuxserver/unifi 相关的常用 Docker 镜像,适用于 不同场景 等不同场景:
镜像拉取方式
您可以使用以下命令拉取该镜像。请将 <标签> 替换为具体的标签版本。如需查看所有可用标签版本,请访问 标签列表页面。
DockerHub 原生拉取命令
docker pull linuxserver/unifi:<标签>
用户好评
来自真实用户的反馈,见证轩辕镜像的优质服务