nginx-ui/docs/zh_CN/guide/install-homebrew.md

使用 Homebrew 安装

此安装方法适用于已经安装了 Homebrew 的 macOS 和 Linux 用户。

前提条件

• macOS: macOS 11 Big Sur 或更高版本 (amd64 / arm64)
• Linux: 大多数现代 Linux 发行版（Ubuntu、Debian、CentOS 等）
• 系统已安装 Homebrew

如果您尚未安装 Homebrew，可以使用以下命令安装：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装

安装 Nginx UI

brew install 0xjacky/tools/nginx-ui

此命令将：

• 将 0xjacky/tools tap 添加到您的 Homebrew
• 下载并安装最新稳定版本的 Nginx UI
• 设置必要的依赖项
• 创建默认配置文件和目录

验证安装

安装完成后，您可以验证 Nginx UI 是否正确安装：

nginx-ui --version

服务管理

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-ui

手动运行

如果您更喜欢手动运行 Nginx UI 而不是作为服务：

# 在前台运行
nginx-ui

# 使用自定义配置运行
nginx-ui serve -config /path/to/your/app.ini

# 在后台运行
nohup nginx-ui serve &

配置

配置文件在安装过程中自动创建，位于：

• macOS (Apple Silicon): /opt/homebrew/etc/nginx-ui/app.ini
• macOS (Intel): /usr/local/etc/nginx-ui/app.ini
• Linux: /home/linuxbrew/.linuxbrew/etc/nginx-ui/app.ini

数据存储在：

• macOS (Apple Silicon): /opt/homebrew/var/nginx-ui/
• macOS (Intel): /usr/local/var/nginx-ui/
• Linux: /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

更新

更新 Nginx UI

brew upgrade nginx-ui

更新 Homebrew 和所有软件包

brew update && brew upgrade

卸载

停止并卸载

# 首先停止服务
brew services stop nginx-ui

# 卸载软件包
brew uninstall nginx-ui

移除 Tap（可选）

如果您不再需要该 tap：

brew untap 0xjacky/tools

删除配置和数据

::: warning 警告

这将永久删除您的所有配置、站点、证书和数据。请确保在继续之前备份任何重要数据。

:::

# macOS (Apple Silicon)
sudo rm -rf /opt/homebrew/etc/nginx-ui/
sudo rm -rf /opt/homebrew/var/nginx-ui/

# macOS (Intel)
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/

故障排除

端口冲突

如果遇到端口冲突（默认端口为 9000），您需要修改配置文件：

1. 编辑配置文件：

   # macOS (Apple Silicon)
   sudo nano /opt/homebrew/etc/nginx-ui/app.ini
   
   # macOS (Intel)
   sudo nano /usr/local/etc/nginx-ui/app.ini
   
   # Linux
   sudo nano /home/linuxbrew/.linuxbrew/etc/nginx-ui/app.ini
   

2. 在 [server] 部分更改端口：

   [server]
   Host = 0.0.0.0
   Port = 9001
   RunMode = release
   

3. 重启服务：

   brew services restart nginx-ui
   

查看服务日志

要排查服务问题，您可以使用以下命令查看日志：

Homebrew 服务日志

Nginx UI 的 Homebrew 配方包含了正确的日志配置：

# 查看服务状态和日志文件路径
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.log

systemd 日志 (Linux)

对于使用 systemd 的 Linux 系统：

# 查看服务日志
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 配置时遇到权限问题：

1. 确保您的用户具有读写 Nginx 配置文件的必要权限
2. 对于某些操作，您可能需要以提升的权限运行 Nginx UI

3. 检查文件权限：

   # 检查配置文件权限
   ls -la $(brew --prefix)/etc/nginx-ui/app.ini
   
   # 检查数据目录权限
   ls -la $(brew --prefix)/var/nginx-ui/
   

服务无法启动

如果服务启动失败：

1. 检查服务状态：

   brew services list | grep nginx-ui
   

2. 验证配置文件是否存在且有效：

   # 检查配置文件是否存在
   ls -la $(brew --prefix)/etc/nginx-ui/app.ini
   
   # 测试配置
   nginx-ui serve -config $(brew --prefix)/etc/nginx-ui/app.ini --help
   

3. 尝试手动运行以查看错误消息：

   nginx-ui serve -config $(brew --prefix)/etc/nginx-ui/app.ini
   

4. 检查端口冲突：

   # 检查端口 9000 是否已被占用
   lsof -i :9000
   
   # 检查 HTTP 质询端口是否被占用
   lsof -i :9180
   

获取帮助

如果遇到任何问题：

1. 查看 官方文档
2. 在 GitHub 上搜索现有问题
3. 如果您的问题尚未报告，请创建新问题

下一步

安装完成后，您可以：

1. 访问 http://localhost:9000 的 Web 界面
2. 完成初始设置向导
3. 开始配置您的 Nginx 站点
4. 探索 配置指南 进行高级设置