UniFi Voucher Site 镜像文档

镜像概述和主要用途

UniFi Voucher Site 是一个轻量级Web应用Docker镜像，专为UniFi网络环境设计，旨在简化访客WiFi凭证的创建流程。通过部署该镜像，管理员可快速搭建一个直观的网页界面，无需复杂操作即可生成、管理UniFi网络的访客访问凭证，有效降低网络管理复杂度。

核心功能和特性

• 极简操作界面：直观的用户界面设计，无需专业知识即可快速上手
• 快速凭证生成：一键创建指定数量和有效期的WiFi访问凭证
• UniFi控制器集成：与UniFi控制器无缝对接，自动同步网络配置信息
• 自定义配置支持：可灵活设置凭证有效期、使用次数等关键参数
• 轻量级部署：容器化设计，资源占用低，支持各类Docker环境快速部署

使用场景和适用范围

• 家庭网络管理员：为访客临时提供WiFi访问权限
• 小型办公环境：简化员工为访客创建网络凭证的流程
• 公共场所服务：如咖啡馆、商店等需要为顾客提供临时网络访问的场景
• 教育机构：为短期访客或活动参与者生成限时网络凭证

使用方法和配置说明

前提条件

• 已部署UniFi控制器（版本需兼容）
• 安装Docker Engine或Docker Compose环境
• 确保容器与UniFi控制器网络互通

快速启动（Docker Run）

docker run -d \
  --name unifi-voucher-site \
  -p 3000:3000 \
  -e UNIFI_HOST=192.168.1.1 \       # UniFi控制器IP/主机名（必填）
  -e UNIFI_PORT=8443 \              # UniFi控制器端口（默认8443）
  -e UNIFI_USERNAME=admin \         # UniFi管理员用户名（必填）
  -e UNIFI_PASSWORD=password \      # UniFi管理员密码（必填）
  -e VOUCHER_DURATION=3600 \        # 凭证有效期（秒，默认86400）
  -e VOUCHER_COUNT=5 \              # 单次生成凭证数量（默认5）
  glenndehaan/unifi-voucher-site:latest

Docker Compose 配置

创建docker-compose.yml文件：

version: '3.8'
services:
  unifi-voucher-site:
    image: glenndehaan/unifi-voucher-site:latest
    container_name: unifi-voucher-site
    ports:
      - "3000:3000"  # 应用访问端口
    environment:
      - UNIFI_HOST=192.168.1.1        # UniFi控制器IP/主机名（必填）
      - UNIFI_PORT=8443               # UniFi控制器端口
      - UNIFI_USERNAME=admin          # UniFi管理员用户名（必填）
      - UNIFI_PASSWORD=password       # UniFi管理员密码（必填）
      - VOUCHER_DURATION=3600         # 凭证有效期（秒），默认24小时(86400)
      - VOUCHER_COUNT=5               # 单次生成凭证数量，默认5个
      - PORT=3000                     # 容器内部应用端口（默认3000）
    restart: unless-stopped

启动服务：

docker-compose up -d

环境变量配置说明

访问与使用

容器启动后，通过 http://<主机IP>:3000 访问Web界面，按照页面指引：

1. 确认UniFi控制器连接状态
2. 设置所需凭证数量和有效期（如需修改默认值）
3. 点击"生成凭证"按钮获取访问凭证
4. 将生成的凭证提供给访客使用

注意事项

• 确保UniFi控制器用户具备"访客管理"权限
• 凭证生成后可在UniFi控制器的"访客网络"模块中查看和管理
• 网络环境变更（如控制器IP/端口修改）需重启容器并更新对应环境变量
• 建议使用Docker Secrets或环境变量文件管理敏感信息（如管理员密码）