chore: prepare v2.1.12

app/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nginx-ui-app-next",
   "type": "module",
-  "version": "2.1.11",
+  "version": "2.1.12",
   "packageManager": "pnpm@10.12.4+sha512.5ea8b0deed94ed68691c9bad4c955492705c5eeb8a87ef86bc62c74a26b037b08ff9570f108b2e4dbd1dd1a9186fea925e527f141c648e85af45631074680184",
   "scripts": {
     "dev": "vite --host",

app/src/version.json

@@ -1 +1 @@
-{"version":"2.1.11","build_id":1,"total_build":450}
+{"version":"2.1.12","build_id":1,"total_build":451}

docs/.vitepress/config/en.ts

@@ -18,6 +18,7 @@ export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
           items: [
             { text: 'What is Nginx UI?', link: '/guide/about' },
             { text: 'Getting Started', link: '/guide/getting-started' },
+            { text: 'Install with Homebrew', link: '/guide/install-homebrew' },
             { text: 'Install Script', link: '/guide/install-script-linux' }
           ]
         },

docs/.vitepress/config/zh_CN.ts

@@ -23,6 +23,7 @@ export const zhCNConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
           items: [
             { text: '何为 Nginx UI?', link: '/zh_CN/guide/about' },
             { text: '即刻开始', link: '/zh_CN/guide/getting-started' },
+            { text: '使用 Homebrew 安装', link: '/zh_CN/guide/install-homebrew' },
             { text: '安装脚本', link: '/zh_CN/guide/install-script-linux' }
           ]
         },

docs/.vitepress/config/zh_TW.ts

@@ -23,6 +23,7 @@ export const zhTWConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
           items: [
             { text: '何為 Nginx UI?', link: '/zh_TW/guide/about' },
             { text: '即刻開始', link: '/zh_TW/guide/getting-started' },
+            { text: '使用 Homebrew 安裝', link: '/zh_TW/guide/install-homebrew' },
             { text: '安裝指令碼', link: '/zh_TW/guide/install-script-linux' }
           ]
         },

docs/guide/getting-started.md

@@ -30,10 +30,12 @@ information: [debian/conf/nginx.conf](https://salsa.debian.org/nginx-team/nginx/
 
 ## Installation
 
-We recommend using the [installation script](./install-script-linux) for Linux users, in which case you can directly
-control the host machine's Nginx. You can also [install via Docker](#install-with-docker), where our provided image
-includes Nginx and can be used bundled. For advanced users, you may also visit the [latest release](https://github.com/0xJacky/nginx-ui/releases/latest)
-to download the latest distribution and [run executable directly](#run-executable-directly), or [manually build it](./build).
+We provide several installation methods to suit different needs:
+
+- **macOS/Linux**: Use [Homebrew](./install-homebrew) for the easiest installation
+- **Linux**: Use the [installation script](./install-script-linux) to directly control the host machine's Nginx
+- **Docker**: [Install via Docker](#install-with-docker) with our bundled image that includes Nginx
+- **Advanced**: Download from [latest release](https://github.com/0xJacky/nginx-ui/releases/latest) and [run executable directly](#run-executable-directly), or [manually build it](./build)
 
 In the first runtime of Nginx UI, please visit `http://<your_server_ip>:<listen_port>`
 in your browser to complete the follow-up configurations.
@@ -41,6 +43,66 @@ in your browser to complete the follow-up configurations.
 In addition, we provide [an example](./nginx-proxy-example) of using Nginx to reverse proxy Nginx UI,
 which can be used after installation is complete.
 
+## Install with Homebrew
+
+For macOS and Linux users, you can install Nginx UI using Homebrew, which provides the easiest installation experience.
+
+::: tip
+
+This installation method is available for macOS and Linux. For other operating systems, please use alternative installation methods.
+
+:::
+
+### Install
+
+```bash
+brew install 0xjacky/tools/nginx-ui
+```
+
+### Start Service
+
+```bash
+# Start the service
+brew services start nginx-ui
+
+# Or run in foreground
+nginx-ui
+```
+
+### Stop Service
+
+```bash
+brew services stop nginx-ui
+```
+
+### Upgrade
+
+```bash
+brew upgrade nginx-ui
+```
+
+### Uninstall
+
+```bash
+# Stop the service first
+brew services stop nginx-ui
+
+# Uninstall the package
+brew uninstall nginx-ui
+
+# Optionally remove the tap
+brew untap 0xjacky/tools
+```
+
+::: warning
+
+After uninstalling, configuration files and data will be preserved in:
+- **macOS**: `~/Library/Application Support/nginx-ui/`
+- **Linux**: `~/.local/share/nginx-ui/` or `~/.config/nginx-ui/`
+
+If you want to completely remove all data, please delete these directories manually.
+
+:::
 
 ## Install with Docker
 

docs/guide/install-homebrew.md

@@ -0,0 +1,311 @@
+# Install with Homebrew
+
+This installation method is designed for macOS and Linux users who have already installed Homebrew.
+
+## Prerequisites
+
+- **macOS**: macOS 11 Big Sur or later (amd64 / arm64)
+- **Linux**: Most modern Linux distributions (Ubuntu, Debian, CentOS, etc.)
+- [Homebrew](https://brew.sh/) installed on your system
+
+If you don't have Homebrew installed, you can install it with:
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+## Installation
+
+### Install Nginx UI
+
+```bash
+brew install 0xjacky/tools/nginx-ui
+```
+
+This command will:
+- Add the `0xjacky/tools` tap to your Homebrew
+- Download and install the latest stable version of Nginx UI
+- Set up the necessary dependencies
+- Create default configuration files and directories
+
+### Verify Installation
+
+After installation, you can verify that Nginx UI is installed correctly:
+
+```bash
+nginx-ui --version
+```
+
+## Service Management
+
+Nginx UI can be managed as a system service using Homebrew's service management features.
+
+### Start Service
+
+```bash
+# Start the service and enable it to start at boot
+brew services start nginx-ui
+
+# Or start the service for the current session only
+brew services run nginx-ui
+```
+
+### Stop Service
+
+```bash
+brew services stop nginx-ui
+```
+
+### Restart Service
+
+```bash
+brew services restart nginx-ui
+```
+
+### Check Service Status
+
+```bash
+brew services list | grep nginx-ui
+```
+
+## Running Manually
+
+If you prefer to run Nginx UI manually instead of as a service:
+
+```bash
+# Run in foreground
+nginx-ui
+
+# Run with custom config
+nginx-ui serve -config /path/to/your/app.ini
+
+# Run in background
+nohup nginx-ui serve &
+```
+
+## Configuration
+
+The configuration file is automatically created during installation and located at:
+
+- **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`
+
+Data is stored in:
+- **macOS (Apple Silicon)**: `/opt/homebrew/var/nginx-ui/`
+- **macOS (Intel)**: `/usr/local/var/nginx-ui/`
+- **Linux**: `/home/linuxbrew/.linuxbrew/var/nginx-ui/`
+
+The default configuration includes:
+```ini
+[app]
+PageSize = 10
+
+[server]
+Host = 0.0.0.0
+Port = 9000
+RunMode = release
+
+[cert]
+HTTPChallengePort = 9180
+
+[terminal]
+StartCmd = login
+```
+
+## Updating
+
+### Update Nginx UI
+
+```bash
+brew upgrade nginx-ui
+```
+
+### Update Homebrew and all packages
+
+```bash
+brew update && brew upgrade
+```
+
+## Uninstallation
+
+### Stop and Uninstall
+
+```bash
+# Stop the service first
+brew services stop nginx-ui
+
+# Uninstall the package
+brew uninstall nginx-ui
+```
+
+### Remove the Tap (Optional)
+
+If you no longer need the tap:
+
+```bash
+brew untap 0xjacky/tools
+```
+
+### Remove Configuration and Data
+
+::: warning
+
+This will permanently delete all your configurations, sites, certificates, and data. Make sure to backup any important data before proceeding.
+
+:::
+
+```bash
+# 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/
+```
+
+## Troubleshooting
+
+### Port Conflicts
+
+If you encounter port conflicts (default port is 9000), you need to modify the configuration file:
+
+1. **Edit the configuration file:**
+   ```bash
+   # 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. **Change the port in the `[server]` section:**
+   ```ini
+   [server]
+   Host = 0.0.0.0
+   Port = 9001
+   RunMode = release
+   ```
+
+3. **Restart the service:**
+   ```bash
+   brew services restart nginx-ui
+   ```
+
+### Viewing Service Logs
+
+To troubleshoot service issues, you can view the logs using these commands:
+
+#### Homebrew Service Logs
+
+Nginx UI's Homebrew formula includes proper log configuration:
+
+```bash
+# View service status and log file paths
+brew services info nginx-ui
+
+# View standard output logs
+tail -f $(brew --prefix)/var/log/nginx-ui.log
+
+# View error logs
+tail -f $(brew --prefix)/var/log/nginx-ui.err.log
+
+# View both logs simultaneously
+tail -f $(brew --prefix)/var/log/nginx-ui.log $(brew --prefix)/var/log/nginx-ui.err.log
+```
+
+#### systemd Logs (Linux)
+
+For Linux systems using systemd:
+
+```bash
+# View service logs
+journalctl -u homebrew.mxcl.nginx-ui -f
+
+# View recent logs
+journalctl -u homebrew.mxcl.nginx-ui --since "1 hour ago"
+```
+
+#### Manual Debugging
+
+If you need to debug service issues, you can run manually to see output:
+
+```bash
+# Run in foreground to see all output
+nginx-ui serve -config $(brew --prefix)/etc/nginx-ui/app.ini
+
+# Check if the service is running
+ps aux | grep nginx-ui
+```
+
+### Permission Issues
+
+If you encounter permission issues when managing Nginx configurations:
+
+1. Make sure your user has the necessary permissions to read/write Nginx configuration files
+2. You might need to run Nginx UI with elevated privileges for certain operations
+3. Check file permissions:
+   ```bash
+   # Check configuration file permissions
+   ls -la $(brew --prefix)/etc/nginx-ui/app.ini
+
+   # Check data directory permissions
+   ls -la $(brew --prefix)/var/nginx-ui/
+   ```
+
+### Service Won't Start
+
+If the service fails to start:
+
+1. **Check the service status:**
+   ```bash
+   brew services list | grep nginx-ui
+   ```
+
+2. **Verify the configuration file exists and is valid:**
+   ```bash
+   # Check if config file exists
+   ls -la $(brew --prefix)/etc/nginx-ui/app.ini
+
+   # Test configuration
+   nginx-ui serve -config $(brew --prefix)/etc/nginx-ui/app.ini --help
+   ```
+
+3. **Try running manually to see error messages:**
+   ```bash
+   nginx-ui serve -config $(brew --prefix)/etc/nginx-ui/app.ini
+   ```
+
+4. **Check for port conflicts:**
+   ```bash
+   # Check if port 9000 is already in use
+   lsof -i :9000
+
+   # Check if HTTP challenge port is in use
+   lsof -i :9180
+   ```
+
+## Getting Help
+
+If you encounter any issues:
+
+1. Check the [official documentation](https://nginxui.com)
+2. Search for existing issues on [GitHub](https://github.com/0xJacky/nginx-ui/issues)
+3. Create a new issue if your problem isn't already reported
+
+## Next Steps
+
+After installation, you can:
+
+1. Access the web interface at `http://localhost:9000`
+2. Complete the initial setup wizard
+3. Start configuring your Nginx sites
+4. Explore the [configuration guides](./config-server) for advanced setups

docs/zh_CN/guide/getting-started.md

@@ -27,14 +27,77 @@ http {
 
 ## 安装
 
-我们建议Linux用户使用 [安装脚本](./install-script-linux)，这样您可以直接控制主机上的 Nginx。您也可以通过 [Docker 安装](#使用-docker)，
-我们提供的镜像包含 Nginx 并可以直接使用。对于高级用户，您也可以在 [最新发行 (latest release)](https://github.com/0xJacky/nginx-ui/releases/latest)
-中下载最新版本并 [通过执行文件运行](#通过执行文件运行)，或者 [手动构建](./build)。
+我们提供多种安装方式以满足不同需求：
+
+- **macOS/Linux**: 使用 [Homebrew](./install-homebrew) 最简单的安装方式
+- **Linux**: 使用 [安装脚本](./install-script-linux) 直接控制主机上的 Nginx
+- **Docker**: 通过 [Docker 安装](#使用-docker) 使用我们提供的包含 Nginx 的镜像
+- **高级用户**: 从 [最新发行版](https://github.com/0xJacky/nginx-ui/releases/latest) 下载并 [通过执行文件运行](#通过执行文件运行)，或者 [手动构建](./build)
 
 第一次运行 Nginx UI 时，请在浏览器中访问 `http://<your_server_ip>:<listen_port>` 完成后续配置。
 
 此外，我们提供了一个使用 Nginx 反向代理 Nginx UI 的 [示例](./nginx-proxy-example)，您可在安装完成后使用。
 
+## 使用 Homebrew 安装
+
+对于 macOS 和 Linux 用户，您可以使用 Homebrew 安装 Nginx UI，这是最简单的安装方式。
+
+::: tip 提示
+
+此安装方式适用于 macOS 和 Linux。对于其他操作系统，请使用其他安装方式。
+
+:::
+
+### 安装
+
+```bash
+brew install 0xjacky/tools/nginx-ui
+```
+
+### 启动服务
+
+```bash
+# 启动服务
+brew services start nginx-ui
+
+# 或者在前台运行
+nginx-ui
+```
+
+### 停止服务
+
+```bash
+brew services stop nginx-ui
+```
+
+### 升级
+
+```bash
+brew upgrade nginx-ui
+```
+
+### 卸载
+
+```bash
+# 首先停止服务
+brew services stop nginx-ui
+
+# 卸载软件包
+brew uninstall nginx-ui
+
+# 可选：移除 tap
+brew untap 0xjacky/tools
+```
+
+::: warning 警告
+
+卸载后，配置文件和数据将保留在：
+- **macOS**: `~/Library/Application Support/nginx-ui/`
+- **Linux**: `~/.local/share/nginx-ui/` 或 `~/.config/nginx-ui/`
+
+如果您想要完全删除所有数据，请手动删除这些目录。
+
+:::
 
 ## 使用 Docker
 

docs/zh_CN/guide/install-homebrew.md

@@ -0,0 +1,311 @@
+# 使用 Homebrew 安装
+
+此安装方法适用于已经安装了 Homebrew 的 macOS 和 Linux 用户。
+
+## 前提条件
+
+- **macOS**: macOS 11 Big Sur 或更高版本 (amd64 / arm64)
+- **Linux**: 大多数现代 Linux 发行版（Ubuntu、Debian、CentOS 等）
+- 系统已安装 [Homebrew](https://brew.sh/)
+
+如果您尚未安装 Homebrew，可以使用以下命令安装：
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+## 安装
+
+### 安装 Nginx UI
+
+```bash
+brew install 0xjacky/tools/nginx-ui
+```
+
+此命令将：
+- 将 `0xjacky/tools` tap 添加到您的 Homebrew
+- 下载并安装最新稳定版本的 Nginx UI
+- 设置必要的依赖项
+- 创建默认配置文件和目录
+
+### 验证安装
+
+安装完成后，您可以验证 Nginx UI 是否正确安装：
+
+```bash
+nginx-ui --version
+```
+
+## 服务管理
+
+Nginx UI 可以使用 Homebrew 的服务管理功能作为系统服务进行管理。
+
+### 启动服务
+
+```bash
+# 启动服务并设置开机自启
+brew services start nginx-ui
+
+# 或者仅为当前会话启动服务
+brew services run nginx-ui
+```
+
+### 停止服务
+
+```bash
+brew services stop nginx-ui
+```
+
+### 重启服务
+
+```bash
+brew services restart nginx-ui
+```
+
+### 检查服务状态
+
+```bash
+brew services list | grep nginx-ui
+```
+
+## 手动运行
+
+如果您更喜欢手动运行 Nginx UI 而不是作为服务：
+
+```bash
+# 在前台运行
+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/`
+
+默认配置包含：
+```ini
+[app]
+PageSize = 10
+
+[server]
+Host = 0.0.0.0
+Port = 9000
+RunMode = release
+
+[cert]
+HTTPChallengePort = 9180
+
+[terminal]
+StartCmd = login
+```
+
+## 更新
+
+### 更新 Nginx UI
+
+```bash
+brew upgrade nginx-ui
+```
+
+### 更新 Homebrew 和所有软件包
+
+```bash
+brew update && brew upgrade
+```
+
+## 卸载
+
+### 停止并卸载
+
+```bash
+# 首先停止服务
+brew services stop nginx-ui
+
+# 卸载软件包
+brew uninstall nginx-ui
+```
+
+### 移除 Tap（可选）
+
+如果您不再需要该 tap：
+
+```bash
+brew untap 0xjacky/tools
+```
+
+### 删除配置和数据
+
+::: warning 警告
+
+这将永久删除您的所有配置、站点、证书和数据。请确保在继续之前备份任何重要数据。
+
+:::
+
+```bash
+# 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. **编辑配置文件：**
+   ```bash
+   # 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]` 部分更改端口：**
+   ```ini
+   [server]
+   Host = 0.0.0.0
+   Port = 9001
+   RunMode = release
+   ```
+
+3. **重启服务：**
+   ```bash
+   brew services restart nginx-ui
+   ```
+
+### 查看服务日志
+
+要排查服务问题，您可以使用以下命令查看日志：
+
+#### Homebrew 服务日志
+
+Nginx UI 的 Homebrew 配方包含了正确的日志配置：
+
+```bash
+# 查看服务状态和日志文件路径
+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 系统：
+
+```bash
+# 查看服务日志
+journalctl -u homebrew.mxcl.nginx-ui -f
+
+# 查看最近的日志
+journalctl -u homebrew.mxcl.nginx-ui --since "1 hour ago"
+```
+
+#### 手动调试
+
+如果需要调试服务问题，可以手动运行以查看输出：
+
+```bash
+# 在前台运行以查看所有输出
+nginx-ui serve -config $(brew --prefix)/etc/nginx-ui/app.ini
+
+# 检查服务是否正在运行
+ps aux | grep nginx-ui
+```
+
+### 权限问题
+
+如果在管理 Nginx 配置时遇到权限问题：
+
+1. 确保您的用户具有读写 Nginx 配置文件的必要权限
+2. 对于某些操作，您可能需要以提升的权限运行 Nginx UI
+3. 检查文件权限：
+   ```bash
+   # 检查配置文件权限
+   ls -la $(brew --prefix)/etc/nginx-ui/app.ini
+
+   # 检查数据目录权限
+   ls -la $(brew --prefix)/var/nginx-ui/
+   ```
+
+### 服务无法启动
+
+如果服务启动失败：
+
+1. **检查服务状态：**
+   ```bash
+   brew services list | grep nginx-ui
+   ```
+
+2. **验证配置文件是否存在且有效：**
+   ```bash
+   # 检查配置文件是否存在
+   ls -la $(brew --prefix)/etc/nginx-ui/app.ini
+
+   # 测试配置
+   nginx-ui serve -config $(brew --prefix)/etc/nginx-ui/app.ini --help
+   ```
+
+3. **尝试手动运行以查看错误消息：**
+   ```bash
+   nginx-ui serve -config $(brew --prefix)/etc/nginx-ui/app.ini
+   ```
+
+4. **检查端口冲突：**
+   ```bash
+   # 检查端口 9000 是否已被占用
+   lsof -i :9000
+
+   # 检查 HTTP 质询端口是否被占用
+   lsof -i :9180
+   ```
+
+## 获取帮助
+
+如果遇到任何问题：
+
+1. 查看 [官方文档](https://nginxui.com)
+2. 在 [GitHub](https://github.com/0xJacky/nginx-ui/issues) 上搜索现有问题
+3. 如果您的问题尚未报告，请创建新问题
+
+## 下一步
+
+安装完成后，您可以：
+
+1. 访问 `http://localhost:9000` 的 Web 界面
+2. 完成初始设置向导
+3. 开始配置您的 Nginx 站点
+4. 探索 [配置指南](./config-server) 进行高级设置

docs/zh_TW/guide/getting-started.md

@@ -27,14 +27,77 @@ http {
 
 ## 安裝
 
-我們建議 Linux 使用者使用 [安裝指令碼](./install-script-linux)，這樣您可以直接控制主機上的 Nginx。您也可以透過 [Docker 安裝](#使用-docker)，
-我們提供的映象包含 Nginx 並可以直接使用。對於高階使用者，您也可以在 [最新發行 (latest release)](https://github.com/0xJacky/nginx-ui/releases/latest)
-中下載最新版本並 [透過執行檔案執行](#透過執行檔案執行)，或者 [手動建構](./build)。
+我們提供多種安裝方式以滿足不同需求：
+
+- **macOS/Linux**: 使用 [Homebrew](./install-homebrew) 最簡單的安裝方式
+- **Linux**: 使用 [安裝指令碼](./install-script-linux) 直接控制主機上的 Nginx
+- **Docker**: 透過 [Docker 安裝](#使用-docker) 使用我們提供的包含 Nginx 的映象
+- **高階使用者**: 從 [最新發行版](https://github.com/0xJacky/nginx-ui/releases/latest) 下載並 [透過執行檔案執行](#透過執行檔案執行)，或者 [手動建構](./build)
 
 第一次執行 Nginx UI 時，請在瀏覽器中存取 `http://<your_server_ip>:<listen_port>` 完成後續設定。
 
 此外，我們提供了一個使用 Nginx 反向代理 Nginx UI 的 [範例](./nginx-proxy-example)，您可在安裝完成後使用。
 
+## 使用 Homebrew 安裝
+
+對於 macOS 和 Linux 使用者，您可以使用 Homebrew 安裝 Nginx UI，這是最簡單的安裝方式。
+
+::: tip 提示
+
+此安裝方式適用於 macOS 和 Linux。對於其他作業系統，請使用其他安裝方式。
+
+:::
+
+### 安裝
+
+```bash
+brew install 0xjacky/tools/nginx-ui
+```
+
+### 啟動服務
+
+```bash
+# 啟動服務
+brew services start nginx-ui
+
+# 或者在前台執行
+nginx-ui
+```
+
+### 停止服務
+
+```bash
+brew services stop nginx-ui
+```
+
+### 升級
+
+```bash
+brew upgrade nginx-ui
+```
+
+### 解除安裝
+
+```bash
+# 首先停止服務
+brew services stop nginx-ui
+
+# 解除安裝軟體包
+brew uninstall nginx-ui
+
+# 可選：移除 tap
+brew untap 0xjacky/tools
+```
+
+::: warning 警告
+
+解除安裝後，設定檔案和資料將保留在：
+- **macOS**: `~/Library/Application Support/nginx-ui/`
+- **Linux**: `~/.local/share/nginx-ui/` 或 `~/.config/nginx-ui/`
+
+如果您想要完全刪除所有資料，請手動刪除這些目錄。
+
+:::
 
 ## 使用 Docker
 

docs/zh_TW/guide/install-homebrew.md

@@ -0,0 +1,311 @@
+# 使用 Homebrew 安裝
+
+此安裝方法適用於已經安裝了 Homebrew 的 macOS 和 Linux 使用者。
+
+## 前提條件
+
+- **macOS**: macOS 11 Big Sur 或更高版本 (amd64 / arm64)
+- **Linux**: 大多數現代 Linux 發行版（Ubuntu、Debian、CentOS 等）
+- 系統已安裝 [Homebrew](https://brew.sh/)
+
+如果您尚未安裝 Homebrew，可以使用以下命令安裝：
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+## 安裝
+
+### 安裝 Nginx UI
+
+```bash
+brew install 0xjacky/tools/nginx-ui
+```
+
+此命令將：
+- 將 `0xjacky/tools` tap 新增到您的 Homebrew
+- 下載並安裝最新穩定版本的 Nginx UI
+- 設定必要的相依性
+- 建立預設設定檔案和目錄
+
+### 驗證安裝
+
+安裝完成後，您可以驗證 Nginx UI 是否正確安裝：
+
+```bash
+nginx-ui --version
+```
+
+## 服務管理
+
+Nginx UI 可以使用 Homebrew 的服務管理功能作為系統服務進行管理。
+
+### 啟動服務
+
+```bash
+# 啟動服務並設定開機自啟
+brew services start nginx-ui
+
+# 或者僅為目前工作階段啟動服務
+brew services run nginx-ui
+```
+
+### 停止服務
+
+```bash
+brew services stop nginx-ui
+```
+
+### 重啟服務
+
+```bash
+brew services restart nginx-ui
+```
+
+### 檢查服務狀態
+
+```bash
+brew services list | grep nginx-ui
+```
+
+## 手動執行
+
+如果您更喜歡手動執行 Nginx UI 而不是作為服務：
+
+```bash
+# 在前台執行
+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/`
+
+預設設定包含：
+```ini
+[app]
+PageSize = 10
+
+[server]
+Host = 0.0.0.0
+Port = 9000
+RunMode = release
+
+[cert]
+HTTPChallengePort = 9180
+
+[terminal]
+StartCmd = login
+```
+
+## 更新
+
+### 更新 Nginx UI
+
+```bash
+brew upgrade nginx-ui
+```
+
+### 更新 Homebrew 和所有軟體包
+
+```bash
+brew update && brew upgrade
+```
+
+## 解除安裝
+
+### 停止並解除安裝
+
+```bash
+# 首先停止服務
+brew services stop nginx-ui
+
+# 解除安裝軟體包
+brew uninstall nginx-ui
+```
+
+### 移除 Tap（可選）
+
+如果您不再需要該 tap：
+
+```bash
+brew untap 0xjacky/tools
+```
+
+### 刪除設定和資料
+
+::: warning 警告
+
+這將永久刪除您的所有設定、站點、憑證和資料。請確保在繼續之前備份任何重要資料。
+
+:::
+
+```bash
+# 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. **編輯設定檔案：**
+   ```bash
+   # 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]` 部分更改連接埠：**
+   ```ini
+   [server]
+   Host = 0.0.0.0
+   Port = 9001
+   RunMode = release
+   ```
+
+3. **重啟服務：**
+   ```bash
+   brew services restart nginx-ui
+   ```
+
+### 查看服務日誌
+
+要排查服務問題，您可以使用以下命令查看日誌：
+
+#### Homebrew 服務日誌
+
+Nginx UI 的 Homebrew 配方包含了正確的日誌配置：
+
+```bash
+# 查看服務狀態和日誌文件路徑
+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 系統：
+
+```bash
+# 查看服務日誌
+journalctl -u homebrew.mxcl.nginx-ui -f
+
+# 查看最近的日誌
+journalctl -u homebrew.mxcl.nginx-ui --since "1 hour ago"
+```
+
+#### 手動調試
+
+如果需要調試服務問題，可以手動運行以查看輸出：
+
+```bash
+# 在前台運行以查看所有輸出
+nginx-ui serve -config $(brew --prefix)/etc/nginx-ui/app.ini
+
+# 檢查服務是否正在執行
+ps aux | grep nginx-ui
+```
+
+### 權限問題
+
+如果在管理 Nginx 設定時遇到權限問題：
+
+1. 確保您的使用者具有讀寫 Nginx 設定檔案的必要權限
+2. 對於某些操作，您可能需要以提升的權限執行 Nginx UI
+3. 檢查檔案權限：
+   ```bash
+   # 檢查設定檔案權限
+   ls -la $(brew --prefix)/etc/nginx-ui/app.ini
+
+   # 檢查資料目錄權限
+   ls -la $(brew --prefix)/var/nginx-ui/
+   ```
+
+### 服務無法啟動
+
+如果服務啟動失敗：
+
+1. **檢查服務狀態：**
+   ```bash
+   brew services list | grep nginx-ui
+   ```
+
+2. **驗證設定檔案是否存在且有效：**
+   ```bash
+   # 檢查設定檔案是否存在
+   ls -la $(brew --prefix)/etc/nginx-ui/app.ini
+
+   # 測試設定
+   nginx-ui serve -config $(brew --prefix)/etc/nginx-ui/app.ini --help
+   ```
+
+3. **嘗試手動執行以查看錯誤訊息：**
+   ```bash
+   nginx-ui serve -config $(brew --prefix)/etc/nginx-ui/app.ini
+   ```
+
+4. **檢查連接埠衝突：**
+   ```bash
+   # 檢查連接埠 9000 是否已被佔用
+   lsof -i :9000
+
+   # 檢查 HTTP 質詢連接埠是否被佔用
+   lsof -i :9180
+   ```
+
+## 獲取幫助
+
+如果遇到任何問題：
+
+1. 查看 [官方文件](https://nginxui.com)
+2. 在 [GitHub](https://github.com/0xJacky/nginx-ui/issues) 上搜尋現有問題
+3. 如果您的問題尚未回報，請建立新問題
+
+## 下一步
+
+安裝完成後，您可以：
+
+1. 存取 `http://localhost:9000` 的 Web 介面
+2. 完成初始設定精靈
+3. 開始設定您的 Nginx 站點
+4. 探索 [設定指南](./config-server) 進行進階設定