Unifi Docker 镜像文档

镜像概述与主要用途

本镜像为 Unifi 控制器软件的 Docker 封装，基于 webhippie/ubuntu 镜像构建。主要用途是提供便捷部署的 Unifi 控制器环境，用于集中管理 Ubiquiti 系列网络设备（如路由器、交换机、无线AP等），实现设备配置、网络监控、固件升级等功能。

核心功能与特性

• 基于 Ubuntu 系统：继承自稳定的 Ubuntu 基础镜像，确保运行环境兼容性
• 持久化存储支持：通过卷挂载实现数据、日志及运行时文件的持久化
• 灵活端口配置：默认暴露 Unifi 控制器核心网络端口，支持自定义端口映射
• 环境变量定制：提供丰富的环境变量参数，支持 JVM 配置、网络端口、MongoDB 集成等高级设置
• 轻量级部署：容器化设计简化部署流程，降低依赖管理复杂度

使用场景与适用范围

• 家庭网络管理：适用于家庭环境中通过少量 Ubiquiti 设备构建网络的集中控制
• 中小企业网络：满足企业环境下多设备（路由器、交换机、AP）的统一配置与监控需求
• 多地点网络部署：支持远程管理不同物理位置的 Ubiquiti 设备，实现分布式网络集中管控
• 测试与演示环境：快速搭建临时 Unifi 控制器实例，用于功能测试或产品演示

使用方法与配置说明

基本运行方法（docker run）

通过以下命令快速启动 Unifi 控制器容器：

docker run -d \
  --name unifi-controller \
  -p 8080:8080 \
  -p 8443:8443 \
  -v /host/path/to/data:/var/lib/unifi \  # 持久化数据存储
  -v /host/path/to/logs:/var/log/unifi \  # 日志存储
  -v /host/path/to/run:/var/run/unifi \   # 运行时文件
  -e UNIFI_JVM_MAX_HEAP_SIZE=2048M \      # 调整JVM最大堆内存（根据需求修改）
  webhippie/unifi:latest

Docker Compose 配置示例

创建 docker-compose.yml 文件，配置更复杂的部署环境：

version: '3.8'

services:
  unifi:
    image: webhippie/unifi:latest
    container_name: unifi-controller
    restart: unless-stopped
    ports:
      - "8080:8080"  # HTTP端口（设备通信）
      - "8443:8443"  # HTTPS端口（Web管理界面）
    volumes:
      - ./unifi-data:/var/lib/unifi    # 数据卷
      - ./unifi-logs:/var/log/unifi    # 日志卷
      - ./unifi-run:/var/run/unifi     # 运行时卷
    environment:
      - UNIFI_JVM_MAX_HEAP_SIZE=2048M  # JVM最大堆内存
      - UNIFI_HTTPS_PORT=8443          # HTTPS端口（默认8443）
      - UNIFI_SKIP_CHOWN=false         # 是否跳过目录权限修改（默认false）

启动服务：docker-compose up -d

卷挂载说明

端口映射说明

环境变量配置

核心环境变量

继承环境变量

本镜像继承 webhippie/ubuntu 镜像的所有环境变量，可通过该链接查看详细配置说明。

贡献指南

1. Fork 本仓库
2. 创建补丁或功能分支
3. 提交代码并推送到个人仓库
4. 发起 Pull Request

作者与版权信息

• 作者：Thomas Boerger
• 版权声明：Copyright (c) 2019 Thomas Boerger <[***]>

许可证

本项目采用 MIT 许可证，详情参见项目源码仓库。

参考链接

• Unifi 官方软件
• 基础镜像（webhippie/ubuntu）
• Docker Hub 镜像标签
• Quay.io 镜像标签
• GitHub 源码仓库