Nginx UI 通过 Homebrew 安装指南：macOS / Linux 从安装到服务化运维

后端前端运维MCP 服务【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址https://gitcode.com/gh_mirrors/ngi/nginx-ui点击查看免费下载本指南面向已安装 Homebrew 的 macOS 与 Linux 用户完整讲解 Nginx UI 的安装、服务管理、手动运行、配置说明、升级、卸载与常见故障排查。读完本文你将掌握brew install/brew services的完整用法理解安装后生成的app.ini配置文件各段含义并能独立解决端口冲突、日志查看、权限与服务无法启动等日常运维问题。适用平台与前置条件Homebrew 安装方式专为两类用户设计macOSmacOS 11 Big Sur 或更高版本支持amd64Intel与arm64Apple Silicon两种架构Linux大多数主流发行版Ubuntu、Debian、CentOS 等Homebrew 通常以 Linuxbrew 形式安装在/home/linuxbrew/下。前提是系统上已安装 Homebrew。如果尚未安装官方提供的一键脚本为/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)注意文档中的外部安装脚本、官方文档与 GitHub 链接仅用于说明 Homebrew 生态与上游项目本文后续所有操作与配置均以当前仓库nginx-ui的实际实现为准。安装 Nginx UI执行如下命令即可完成安装brew install 0xjacky/tools/nginx-ui该命令会依次完成将0xjacky/toolstap 添加到你的 Homebrew下载并安装 Nginx UI 的最新稳定版本配置好运行时所需的依赖创建默认配置文件与数据目录。验证安装安装完成后用版本命令验证二进制是否可用nginx-ui --version从源码看该版本输出由 internal/cmd/version.go 中的VersionPrinter生成格式包含程序名、版本号、构建 ID、短哈希以及 Go 运行时与目标平台信息例如nginx-ui 2.x.x 123(456) abcdef1 (go1.x.x linux/amd64)Nginx UI 的 CLI 根命令定义在 internal/cmd/main.go根命令名为nginx-ui默认子命令为serve即不带参数直接运行nginx-ui等价于nginx-ui serve此外还提供了reset-password、cert、ctl、host-setup、upgrade-docker-step2等子命令--config全局参数用于指定配置文件路径默认值为app.ini。服务管理Nginx UI 可以借助 Homebrew 的服务管理能力作为系统服务运行。启动服务# 启动服务并设置为开机自启 brew services start nginx-ui # 仅当前会话运行不设置开机自启 brew services run nginx-ui停止服务brew services stop nginx-ui重启服务brew services restart nginx-ui查看服务状态brew services list | grep nginx-uibrew services info nginx-ui则可以查看更详细的服务状态与日志文件路径见下文“查看服务日志”。手动运行如果你更倾向于手动运行而非注册为系统服务# 前台运行默认读取 ./app.ini nginx-ui # 指定自定义配置文件 nginx-ui serve -config /path/to/your/app.ini # 后台运行 nohup nginx-ui serve 补充说明serve子命令还支持-p/--pidfile参数指定 PID 文件路径见 internal/cmd/main.go 中的 Flag 定义便于外部进程管理工具跟踪进程若以 root 之外的普通用户运行请确保该用户对 Nginx 配置文件目录与 Nginx UI 数据目录具有读写权限。配置说明安装过程会自动生成默认配置文件app.ini其位置因平台而异平台配置文件路径数据目录macOSApple Silicon/opt/homebrew/etc/nginx-ui/app.ini/opt/homebrew/var/nginx-ui/macOSIntel/usr/local/etc/nginx-ui/app.ini/usr/local/var/nginx-ui/Linux/home/linuxbrew/.linuxbrew/etc/nginx-ui/app.ini/home/linuxbrew/.linuxbrew/var/nginx-ui/安装后默认生成的最小配置如下[app] PageSize 10 [server] Host 0.0.0.0 Port 9000 RunMode release [cert] HTTPChallengePort 9180 [terminal] StartCmd login结合仓库源码可以更深入地理解这些配置项的实际作用[app] PageSize列表页默认分页大小。该值在 settings/server_v1.go 的serverV1.PageSize中被读取并映射到 V2 配置结构的App.PageSize。[server] Host / Port / RunModeWeb 服务监听地址、端口与运行模式。源码在 settings/settings.go 的Init中显式兜底当Port 0时强制设为默认端口9000保证即使配置缺失也能正常启动。[cert] HTTPChallengePortACME HTTP-01 挑战端口默认9180。对应 settings/cert.go 中CertSettings的HTTPChallengePort: 9180默认值证书签发相关实现见 api/certificate 与 internal/cert。[terminal] StartCmdWeb 终端启动时执行的命令。对应 settings/terminal.goWindows 平台默认为cmd.exe其余平台默认login与安装文档给出的login一致。需要说明的是Nginx UI 的配置系统存在 V1 → V2 的自动迁移机制当app.ini中检测到旧的[server]段如jwt_secret非空时会由 settings/server_v1.go 中的migrate函数自动完成字段映射并回写文件同时将旧的环境变量如SERVER_HTTP_HOST自动迁移到新命名如NGINX_UI_SERVER_HOST。因此升级后如果配置文件“变了样”属正常现象。此外所有配置段都支持以NGINX_UI_SECTION_KEY形式的环境变量覆盖例如NGINX_UI_SERVER_PORT9001。更完整的配置项数据库、认证、Nginx 控制、证书、集群等可参考 docs/guide/config-server.md、docs/guide/config-app.md、docs/guide/config-database.md、docs/guide/config-cert.md 与 docs/guide/config-terminal.md。更新仅更新 Nginx UIbrew upgrade nginx-ui更新 Homebrew 与所有包brew update brew upgrade更新后若配置发生不兼容变化启动时通常会有提示建议更新前先备份app.ini与数据目录。卸载停止服务并卸载# 先停止服务 brew services stop nginx-ui # 卸载软件包 brew uninstall nginx-ui移除 Tap可选如果不再需要该 tapbrew untap 0xjacky/tools移除配置与数据谨慎操作::: warning以下操作将永久删除你的全部配置、站点、证书与数据执行前务必先做好备份可使用 Web 界面的备份功能或直接拷贝var/nginx-ui/目录。:::# macOSApple Silicon sudo rm -rf /opt/homebrew/etc/nginx-ui/ sudo rm -rf /opt/homebrew/var/nginx-ui/ # macOSIntel sudo rm -rf /usr/local/etc/nginx-ui/ sudo rm -rf /usr/local/var/nginx-ui/ # Linux sudo rm -rf /home/linuxbrew/.linuxbrew/etc/nginx-ui/ sudo rm -rf /home/linuxbrew/.linuxbrew/var/nginx-ui/故障排查端口冲突默认 Web 端口为9000若被占用需修改配置文件编辑配置文件# macOSApple Silicon sudo nano /opt/homebrew/etc/nginx-ui/app.ini # macOSIntel sudo nano /usr/local/etc/nginx-ui/app.ini # Linux sudo nano /home/linuxbrew/.linuxbrew/etc/nginx-ui/app.ini修改[server]段的端口[server] Host 0.0.0.0 Port 9001 RunMode release重启服务brew services restart nginx-ui查看服务日志Homebrew 服务日志Nginx UI 的 Homebrew formula 已内置日志配置# 查看服务状态与日志文件路径 brew services info nginx-ui # 查看标准输出日志 tail -f $(brew --prefix)/var/log/nginx-ui.log # 查看错误日志 tail -f $(brew --prefix)/var/log/nginx-ui.err.log # 同时查看两份日志 tail -f $(brew --prefix)/var/log/nginx-ui.log $(brew --prefix)/var/log/nginx-ui.err.logsystemd 日志LinuxLinux 系统若使用 systemd 管理# 实时查看服务日志 journalctl -u homebrew.mxcl.nginx-ui -f # 查看最近一小时日志 journalctl -u homebrew.mxcl.nginx-ui --since 1 hour ago手动调试前台运行以直接观察输出# 前台运行并指定配置便于看到全部输出 nginx-ui serve -config $(brew --prefix)/etc/nginx-ui/app.ini # 检查进程是否在运行 ps aux | grep nginx-ui权限问题管理 Nginx 配置时遇到权限报错按以下步骤处理确认当前用户对 Nginx 配置文件具备读写权限部分操作如修改/etc/nginx下的文件可能需要以更高权限运行 Nginx UI检查文件权限# 检查配置文件权限 ls -la $(brew --prefix)/etc/nginx-ui/app.ini # 检查数据目录权限 ls -la $(brew --prefix)/var/nginx-ui/服务无法启动按顺序排查检查服务状态brew services list | grep nginx-ui确认配置文件存在且参数合法# 检查配置文件是否存在 ls -la $(brew --prefix)/etc/nginx-ui/app.ini # 查看 serve 子命令帮助 nginx-ui serve -config $(brew --prefix)/etc/nginx-ui/app.ini --help前台运行以查看具体报错nginx-ui serve -config $(brew --prefix)/etc/nginx-ui/app.ini检查端口占用# 检查 9000 端口是否被占用 lsof -i :9000 # 检查 HTTP 挑战端口9180是否被占用 lsof -i :9180获取帮助与下一步遇到问题时优先参考仓库内文档docs/guide 目录下的安装与配置系列文档例如 install-script-linux.mdLinux 脚本安装、config-server.md服务端配置、config-nginx.mdNginx 控制等如果问题仍未解决可在上游项目的 Issues 中检索是否已有相同问题或提交新的 Issue 并附上日志与复现步骤。安装并启动成功后建议按以下顺序完成初始化浏览器访问http://localhost:9000若修改过端口则以实际端口为准完成首次启动设置向导创建管理员账号等在“站点”中配置你的 Nginx 站点或在“Nginx 配置”中直接编辑按需深入阅读 docs/guide/config-cert.md证书管理、docs/guide/config-cluster.md多主机集群等文档进行进阶配置。赞分享后端前端运维MCP 服务【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址https://gitcode.com/gh_mirrors/ngi/nginx-ui点击查看免费下载相关推荐在macOS上通过Homebrew安装escrcpy项目指南在macOS上通过Homebrew安装escrcpy项目指南 escrcpy是一款优秀的开源项目它为用户提供了在电脑上显示和控制Android设备的功能。对于桌面应用移动开发开发工具Vector 在 Windows 上的安装与运维指南从 ZIP/MSI 安装到 Windows 服务化运行Vector 在 Windows 上的安装与运维指南从 ZIP/MSI 安装到 Windows 服务化运行 Vector GitHub_Trending/v可观测性数据工程数据集成日志分析Eclipse Mosquitto 在 macOS 上通过 Homebrew 安装与使用指南Eclipse Mosquitto 在 macOS 上通过 Homebrew 安装与使用指南 本指南围绕 Eclipse Mosquitto 项目官方发布的一则后端消息队列消息路由创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考