NGINX WEBUI Docker 容器化部署指南

1,073次阅读

共计 4399 个字符，预计需要花费 11 分钟才能阅读完成。

概述

NGINX WEBUI 是一款基于 Web 的图形化 Nginx 配置管理工具，旨在简化 Nginx 服务器的配置与管理流程。通过直观的网页界面，用户可快速配置反向代理、负载均衡、SSL 证书、TCP 转发等常用 Nginx 功能，无需手动编写复杂的配置文件。该工具集成了证书自动申请与续签、配置文件备份与回滚、远程服务器管理等实用功能，适用于需要高效管理 Nginx 服务器的个人用户与企业环境。

本文将详细介绍 NGINX WEBUI 的 Docker 容器化部署方案，包括环境准备、镜像管理、容器部署、功能测试及生产环境优化建议，帮助用户快速实现 NGINX WEBUI 的标准化部署。

环境准备

Docker 环境安装

部署 NGINX WEBUI 前需确保服务器已安装 Docker 环境。推荐使用以下一键安装脚本，自动完成 Docker 及相关组件的部署与配置：

bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

说明：该脚本适用于 Ubuntu、CentOS 等主流 Linux 发行版，执行过程中需 root 权限，建议在全新环境中运行。

镜像准备

镜像拉取命令

使用轩辕镜像加速地址拉取指定版本镜像（推荐标签为latest）：

# 拉取 NGINX WEBUI 镜像（使用轩辕加速地址）docker pull docker.xuanyuan.me/cym1102/nginxwebui:latest

镜像验证

拉取完成后，通过以下命令验证镜像信息：

# 查看本地镜像列表
docker images | grep nginxwebui

# 预期输出示例：# docker.xuanyuan.me/cym1102/nginxwebui   latest    xxxxxxxx    2 weeks ago    500MB

容器部署

基础部署命令

使用 docker run 命令启动 NGINX WEBUI 容器，关键参数说明如下：

docker run -itd \
  --name nginxwebui \  # 容器名称，便于管理
  -v /home/nginxWebUI:/home/nginxWebUI \  # 挂载数据卷，存放配置、证书、数据库等
  -e BOOT_OPTIONS="--server.port=8080" \  # Java 启动参数，可修改端口（默认 8080）--privileged=true \  # 赋予容器特权，确保证书管理等功能正常
  --net=host \  # 使用主机网络模式，映射所有端口（内部 Nginx 可能使用任意端口）docker.xuanyuan.me/cym1102/nginxwebui:latest  # 镜像地址（加速地址）

参数详解

数据卷挂载（-v /home/nginxWebUI:/home/nginxWebUI）：
该路径存放项目所有核心数据，包括 SQLite 数据库、Nginx 配置文件、SSL 证书、日志等。升级镜像时，保留此目录可确保数据不丢失，建议定期备份。
网络模式（–net=host）：
NGINX WEBUI 内部集成 Nginx 服务，可能动态使用多个端口（如 80、443 及用户自定义端口），使用主机网络模式可直接映射主机所有端口，避免端口映射冲突。
启动参数（-e BOOT_OPTIONS）：
支持自定义 Java 启动参数，例如修改端口：--server.port=9090；开启接口文档：--knife4j.production=false（访问 http://IP: 端口 /doc.html 查看接口文档）。

容器状态检查

部署完成后，验证容器运行状态：

# 查看容器运行状态
docker ps | grep nginxwebui

# 查看容器日志（验证服务启动情况）docker logs -f nginxwebui

日志默认路径：容器内/home/nginxWebUI/log/nginxWebUI.log，对应主机路径/home/nginxWebUI/log/nginxWebUI.log。

功能测试

访问 Web 界面

在浏览器中访问http:// 服务器 IP:8080（默认端口 8080，若修改需对应调整），首次访问将提示初始化管理员账号，按指引设置用户名和密码。

核心功能测试

1. 反向代理配置

登录后进入「反向代理」模块，点击「新增」
配置域名、目标服务器地址、端口等参数
点击「保存」并生成 Nginx 配置，验证代理是否生效

2. SSL 证书管理

进入「证书管理」模块，选择「申请证书」
输入域名，选择证书提供商（如 Let’s Encrypt）
配置 DNS 验证信息（如阿里云 AK/SK），提交申请
验证证书是否自动配置到对应域名

3. 配置文件管理

进入「生成 conf 文件」模块，查看自动生成的 Nginx 配置
支持手动编辑配置内容，确认无误后点击「覆盖并重启 Nginx」
检查 Nginx 服务是否正常重启，配置是否生效

4. 数据备份验证

进入「备份文件管理」模块，查看自动生成的配置文件备份
尝试回滚到历史版本，验证配置恢复功能是否正常

生产环境建议

数据备份策略

定期备份数据卷 ：
使用 crontab 定时执行备份脚本，压缩 /home/nginxWebUI 目录并存储至外部存储：# 示例：每日凌晨 3 点备份数据 0 3 * * * tar -zcvf /backup/nginxwebui_$(date +%Y%m%d).tar.gz /home/nginxWebUI
数据库独立备份 ：
单独备份 SQLite 数据库文件（/home/nginxWebUI/sqlite.db），避免数据损坏导致服务不可用。

安全加固

端口限制 ：
若无需开放所有端口，可替换 --net=host 为端口映射（需明确 Nginx 使用的端口）：# 示例：映射 80、443、8080 端口（需确保内部 Nginx 仅使用这些端口）-p 80:80 -p 443:443 -p 8080:8080
文件权限控制 ：
主机 /home/nginxWebUI 目录权限建议设置为700，仅 root 用户可读写，避免非授权访问：chmod -R 700 /home/nginxWebUI
防火墙配置 ：
使用 ufw 或firewalld限制端口访问，仅允许信任 IP 访问管理端口（如 8080）。

资源与性能优化

容器资源限制 ：
添加 --memory=2g --memory-swap=2g --cpus=1 限制容器资源使用，避免过度占用主机资源。
日志轮转 ：
配置日志轮转工具（如 logrotate），定期切割/home/nginxWebUI/log 目录下的日志文件，防止磁盘空间耗尽。

镜像更新策略

定期检查官方标签页面（DOC_URL_TAGS），更新镜像时遵循以下步骤：

拉取新版本镜像：docker pull docker.xuanyuan.me/cym1102/nginxwebui:latest
停止旧容器：docker stop nginxwebui
启动新容器（使用相同数据卷挂载）：docker run ...（同部署命令）
验证服务正常后，删除旧容器：docker rm 旧容器 ID

故障排查

容器无法启动

问题现象：

执行 docker run 后，容器状态为 Exited，或docker ps 中无容器记录。

排查步骤：

检查端口占用 ：
若修改了--server.port，确认端口未被占用：netstat -tulpn | grep 8080 # 替换为实际端口
检查挂载路径权限 ：
确保主机 /home/nginxWebUI 目录存在且权限正确：mkdir -p /home/nginxWebUI && chmod -R 777 /home/nginxWebUI # 临时赋予 777 权限测试
查看启动日志 ：
不使用 -d 参数（后台运行），直接前台启动查看错误：docker run -it --rm ...（其他参数）docker.xuanyuan.me/cym1102/nginxwebui:latest

服务无法访问

问题现象：

容器运行正常，但浏览器无法访问http://IP:8080。

排查步骤：

检查容器日志：docker logs nginxwebui | grep -i error # 查找错误信息
验证网络模式 ：
若未使用--net=host，确认端口映射正确；使用主机网络时，检查防火墙是否放行端口。
检查 Java 服务状态 ：
进入容器内部，验证 Java 进程是否运行：docker exec -it nginxwebui bash ps -ef | grep java # 查看是否有 nginxWebUI 进程

证书申请失败

问题现象：

在「证书管理」中申请 Let’s Encrypt 证书失败。

排查步骤：

确认网络连接 ：
容器内测试网络连通性：docker exec -it nginxwebui ping acme-v02.api.letsencrypt.org
验证权限 ：
确保容器已启用--privileged=true，并检查证书存放路径权限。
检查 DNS 配置 ：
若使用 DNS 验证模式（如阿里云），确认 AK/SK 正确且具有域名解析权限。

密码找回

若忘记管理员密码，通过以下步骤重置：

安装 SQLite 工具：apt install sqlite3 # Ubuntu/Debian # 或 yum install sqlite3 # CentOS/RHEL
修改数据库：# 进入 SQLite 命令行 sqlite3 /home/nginxWebUI/sqlite.db # 查看管理员表（默认表名 admin）SELECT * FROM admin; # 更新密码（示例：重置密码为 Admin123）UPDATE admin SET password = '21232f297a57a5a743894a0e4a801fc3' WHERE username = 'admin'; # 注：'21232f297a57a5a743894a0e4a801fc3' 为 MD5 加密后的 'admin'，若需自定义密码需生成对应 MD5 值 # 退出 .quit
重启容器：docker restart nginxwebui