linuxserver/unifi
LinuxServer.io提供的Unifi容器，用于运行Unifi控制器以管理Ubiquiti网络设备。
让 AI 帮你使用轩辕镜像？ · 展开查看说明 · 点击收起说明
如果你使用 DeepSeek、元宝 AI、Copilot、ChatGPT 等 AI 工具，协助配置轩辕镜像、编写 docker pull 命令、修改 Docker Compose 镜像地址、配置镜像加速、排查镜像拉取失败、分析报错日志等问题，请先让 AI 阅读并遵守轩辕镜像的规则文档。
只需在 AI 对话中先发送下面这句话即可：
请先完整阅读并严格遵守以下文档中的全部规则与要求：
https://xuanyuan.cloud/agents.md
在未充分阅读并理解该文档前，不要生成任何命令、配置、修改建议、故障排查方案或技术回答。后续所有输出都必须严格以该文档中的规范为最高优先级执行。查看 agents.md 用法指南与完整示范。国内用户首推 元宝 AI、DeepSeek 的深度思考模式，不推荐豆包 AI；Cursor 等编辑器可在对话 @ 该链接，或加入 User Rules。 若 AI 无法访问外链，可 打开说明文档 复制全文粘贴。文档会随站点更新，复制内容可能过期，建议定期检查。
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 镜像，适用于 不同场景 等不同场景：
- jacobalberty/unifi Docker 镜像说明（UniFi 网络管理系统，适合企业级网络管理）
- derektamsen/unifi Docker 镜像说明（Unifi 容器镜像，适合 derektamsen 维护的 Unifi 工作负载部署）
镜像拉取方式
您可以使用以下命令拉取该镜像。请将 <标签> 替换为具体的标签版本。如需查看所有可用标签版本，请访问 标签列表页面。
DockerHub 原生拉取命令
docker pull linuxserver/unifi:<标签>
镜像拉取常见问题
功能
错误码
用户好评
来自真实用户的反馈，见证轩辕镜像的优质服务
oldzhang
运维工程师
Linux服务器
5
"Docker访问体验非常流畅，大镜像也能快速完成下载。"