mirror of
https://github.com/0xJacky/nginx-ui.git
synced 2026-09-02 22:56:13 +08:00
docs: reflect the final host SSH behaviour
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
0xJacky
@@ -117,6 +117,10 @@ If the `--sbin-path` path can be obtained, Nginx UI will use the following comma
|
||||
start-stop-daemon --start --quiet --pidfile $PID --exec $SBIN_PATH
|
||||
```
|
||||
|
||||
::: tip Host via SSH mode
|
||||
In Host via SSH mode, a non-empty `TestConfigCmd`, `ReloadCmd` or `RestartCmd` is run on the host through `/bin/sh -c` as the SSH user. When they are empty, Nginx UI tests with the host nginx binary and reloads or restarts through systemd or launchd instead. See [Manage Host Nginx from Docker](manage-host-nginx-from-docker.md).
|
||||
:::
|
||||
|
||||
### StubStatusPort
|
||||
- Type: `uint`
|
||||
- Default: `51820`
|
||||
@@ -189,7 +193,7 @@ Nginx UI reads and writes Nginx configuration and log files through its own file
|
||||
|
||||
## Host SSH Control
|
||||
|
||||
For deployments where Nginx UI runs in a Docker container but Nginx is installed natively on the host machine, Nginx UI provides a third control mode that uses SSH for command execution and bind-mounts for file I/O. Linux systemd services and macOS Homebrew launchd services are supported.
|
||||
For deployments where Nginx UI runs in a Docker container but Nginx is installed natively on the host machine, Nginx UI provides a third control mode that uses SSH for command execution and either SFTP or bind-mounts for file I/O. Linux systemd services and macOS Homebrew launchd services are supported.
|
||||
|
||||
### Constraints
|
||||
|
||||
@@ -232,6 +236,6 @@ nginx-ui host-setup test
|
||||
| `host_launchctl_path` | Default `/bin/launchctl` |
|
||||
| `host_config_dir` | Host-side nginx config directory |
|
||||
| `host_log_dir` | Host-side nginx log directory |
|
||||
| `sbin_path` | In SSH mode, point this at the nginx binary on the host. The generated sudoers allow-list matches this path exactly |
|
||||
| `sbin_path` | Optional in SSH mode: the nginx binary on the host. When empty, Nginx UI resolves the service manager default (`/usr/sbin/nginx` for systemd, `/opt/homebrew/opt/nginx/bin/nginx` for launchd) and stores it when the control settings are saved. The generated sudoers allow-list matches the resolved path exactly |
|
||||
|
||||
See also: [Manage Host Nginx from Docker](manage-host-nginx-from-docker.md) and [Manage Multi-Host Nginx with Cluster](manage-multi-host-nginx-with-cluster.md).
|
||||
|
||||
@@ -169,5 +169,5 @@ These variables are used when Nginx UI controls a host-installed nginx service f
|
||||
| `NGINX_UI_NGINX_HOST_LAUNCHCTL_PATH` | Absolute path to launchctl. Default `/bin/launchctl` |
|
||||
| `NGINX_UI_NGINX_HOST_CONFIG_DIR` | Host-side nginx config dir |
|
||||
| `NGINX_UI_NGINX_HOST_LOG_DIR` | Host-side nginx log dir |
|
||||
| `NGINX_UI_NGINX_SBIN_PATH` | In SSH mode, the absolute path of the nginx binary on the host. The generated sudoers allow-list matches this path exactly |
|
||||
| `NGINX_UI_NGINX_SBIN_PATH` | Optional in SSH mode: the absolute path of the nginx binary on the host. When empty, Nginx UI resolves the service manager default (`/usr/sbin/nginx` for systemd, `/opt/homebrew/opt/nginx/bin/nginx` for launchd). The generated sudoers allow-list matches the resolved path exactly |
|
||||
| `NGINX_UI_DISABLE_BUNDLED_NGINX` | Set to `true` to disable the container's bundled nginx (required in SSH mode) |
|
||||
|
||||
@@ -7,6 +7,7 @@ Use this guide when Nginx UI runs in Docker and needs to manage an nginx instanc
|
||||
- Docker installed on the same host
|
||||
- Linux: an unprivileged user dedicated to Nginx UI (we use `nginxui` in examples)
|
||||
- macOS: the login user that owns the Homebrew nginx service
|
||||
- Two-factor authentication enabled for the Nginx UI administrator: the setup wizard requires a verified two-factor session and otherwise shows **Two-factor authentication required**
|
||||
:::
|
||||
|
||||
For macOS, select **macOS (Homebrew)** in the wizard's **Detect Platform** step. Apple Silicon defaults to `/opt/homebrew`. In that step, the wizard queries Homebrew and parses `nginx -V` over SSH to detect the installed nginx version and the actual executable, configuration, log, PID, and document-root paths. This also handles Intel Homebrew under `/usr/local`. Confirm the service is loaded before continuing:
|
||||
@@ -25,13 +26,11 @@ sudo useradd -r -s /bin/bash -m -G adm nginxui
|
||||
|
||||
On macOS, use the existing login user that runs `brew services`; do not create a separate service user.
|
||||
|
||||
## Step 2: Generate the keypair via Nginx UI
|
||||
## Step 2: SSH Target — generate the keypair via Nginx UI
|
||||
|
||||
Open **Preferences → Nginx → Nginx Control Mode → Edit**, select **Host via SSH**, then click **Open SSH setup wizard**. Editing the control mode requires a verified two-factor session.
|
||||
|
||||
The wizard has five steps: **SSH Target**, **Trust & Test**, **Detect Platform**, **Install** and **Verify**.
|
||||
|
||||
In **Detect Platform**, each path field is tagged **Auto-detected** when it matches what the host reported, or **Manual override** when you changed it. An overridden field shows the detected value and a **Restore detected value** action. After changing the nginx executable path, use **Re-detect paths from this executable** to run `nginx -V` again and refresh the config, log and PID paths.
|
||||
The wizard has five steps: **SSH Target**, **Trust & Test**, **Detect Platform**, **Access & Install** and **Verify**. The steps below follow the same order.
|
||||
|
||||
In **SSH Target**, choose a private key source:
|
||||
|
||||
@@ -65,50 +64,7 @@ sudo chmod 600 /home/nginxui/.ssh/authorized_keys
|
||||
Host SSH mode requires a `known_hosts` allow-list. When the wizard shows a new fingerprint, verify it from the host or another trusted channel before trusting it.
|
||||
:::
|
||||
|
||||
## Step 3: Install the sudoers entry (Linux only)
|
||||
|
||||
The wizard's **Install** step, **Host** tab, shows a sudoers snippet. Copy it and install via:
|
||||
|
||||
```bash
|
||||
sudo visudo -f /etc/sudoers.d/nginx-ui
|
||||
```
|
||||
|
||||
Paste the snippet, save, exit. visudo will reject the file if the syntax is bad.
|
||||
|
||||
Homebrew launchd services run in the login user's domain and do not require a sudoers entry.
|
||||
|
||||
## Step 4: Apply file permissions
|
||||
|
||||
::: details Optional ACL commands
|
||||
If your nginxui user is non-root, grant it write access to /etc/nginx:
|
||||
|
||||
```bash
|
||||
sudo setfacl -R -m u:nginxui:rwx /etc/nginx
|
||||
sudo setfacl -dR -m u:nginxui:rwx /etc/nginx
|
||||
```
|
||||
:::
|
||||
|
||||
On macOS, the wizard emits read/write checks for the Homebrew config and log paths instead of Linux ACL commands.
|
||||
|
||||
## Step 5: Update docker-compose
|
||||
|
||||
The wizard's **Install** step, **Container** tab, shows a compose snippet. Merge it into your existing `docker-compose.yml`.
|
||||
|
||||
The generated snippet sets `NGINX_UI_DISABLE_BUNDLED_NGINX=true` so the container does not start its bundled nginx service while it controls the host nginx service.
|
||||
|
||||
The snippet also bind-mounts the configured PID directory. Recreate the container after changing between Linux and macOS presets so the new paths are applied.
|
||||
|
||||
If verification detects paths that differ from the initial preset, return to the container step, regenerate the compose snippet, and recreate the container before running verification again.
|
||||
|
||||
::: tip Persist Nginx UI data
|
||||
Persist `/etc/nginx-ui` with a Docker volume or bind mount. The host key allow-list is stored at `/etc/nginx-ui/known_hosts` by default, and it should survive image upgrades and container rebuilds.
|
||||
:::
|
||||
|
||||
```bash
|
||||
docker compose up -d --force-recreate nginx-ui
|
||||
```
|
||||
|
||||
## Step 6: Trust the host identity
|
||||
## Step 3: Trust & Test — trust the host identity
|
||||
|
||||
Open the **Trust & Test** step and click **Scan host keys**. The wizard compares the SSH host keys presented by the host with the configured `known_hosts` file.
|
||||
|
||||
@@ -145,9 +101,82 @@ If automatic scanning is not available, run the `ssh-keyscan` command shown in t
|
||||
- **trusted**: the scanned key matches `known_hosts`.
|
||||
:::
|
||||
|
||||
## Step 7: Verify the setup
|
||||
After every presented key is trusted, click **Test SSH connection**. The wizard only continues once the connection succeeds.
|
||||
|
||||
Return to **Verify** and click **Run verification**. The main checks should pass:
|
||||
## Step 4: Detect Platform
|
||||
|
||||
In **Detect Platform**, pick the service manager (**Linux (systemd)** or **macOS (Homebrew)**). The wizard runs `nginx -V` over SSH and fills in the nginx executable, configuration, log and PID paths.
|
||||
|
||||
Each path field is tagged **Auto-detected** when it matches what the host reported, or **Manual override** when you changed it. An overridden field shows the detected value and a **Restore detected value** action. After changing the nginx executable path, use **Re-detect paths from this executable** to run `nginx -V` again and refresh the config, log and PID paths.
|
||||
|
||||
The nginx executable path becomes `sbin_path`. If you leave it empty, Nginx UI falls back to the service manager default (`/usr/sbin/nginx` for systemd, `/opt/homebrew/opt/nginx/bin/nginx` for launchd) and stores that default when the configuration is saved. The sudoers allow-list generated in the next step matches this resolved path exactly.
|
||||
|
||||
## Step 5: Access & Install — choose the file access mode
|
||||
|
||||
The **Access & Install** step starts with **File access mode**:
|
||||
|
||||
| Mode | Behaviour |
|
||||
| --- | --- |
|
||||
| **Compatibility (SFTP)** | Nginx UI reads and writes the host nginx configuration and logs entirely over SSH and SFTP. No host directories are mounted into the container. |
|
||||
| **High performance (mounted)** | Nginx UI reads configuration and logs from bind-mounted host directories. This is faster, but the container must be recreated with the generated mounts. |
|
||||
|
||||
The choice is persisted as the `host_access_mode` setting.
|
||||
|
||||
::: details What SFTP mode covers
|
||||
- Configuration files, log files and the certificates written by certificate issuance or renewal are read from and written to the host over SFTP.
|
||||
- The container cannot watch host files for changes over SFTP, so the configuration index and the certificate discovery are rescanned every 30 seconds instead. A change made on the host outside Nginx UI can take up to 30 seconds to appear in the UI.
|
||||
- The **shared config directory** self-check is skipped, because no directory is shared with the container.
|
||||
- Known limitation: the scan for importable certificates in the certificate directory still reads the container filesystem, so it does not find certificates that only exist on the host. Issue or renew certificates from Nginx UI, or use the mounted mode, if you rely on that scan.
|
||||
:::
|
||||
|
||||
## Step 6: Access & Install — install the sudoers entry (Linux only)
|
||||
|
||||
The **1. On the nginx host** tab shows a sudoers snippet. Copy it and install via:
|
||||
|
||||
```bash
|
||||
sudo visudo -f /etc/sudoers.d/nginx-ui
|
||||
```
|
||||
|
||||
Paste the snippet, save, exit. visudo will reject the file if the syntax is bad.
|
||||
|
||||
Homebrew launchd services run in the login user's domain and do not require a sudoers entry.
|
||||
|
||||
## Step 7: Access & Install — apply file permissions
|
||||
|
||||
::: details Optional ACL commands
|
||||
If your nginxui user is non-root, grant it write access to /etc/nginx:
|
||||
|
||||
```bash
|
||||
sudo setfacl -R -m u:nginxui:rwx /etc/nginx
|
||||
sudo setfacl -dR -m u:nginxui:rwx /etc/nginx
|
||||
```
|
||||
:::
|
||||
|
||||
On macOS, the wizard emits read/write checks for the Homebrew config and log paths instead of Linux ACL commands.
|
||||
|
||||
## Step 8: Access & Install — update the container
|
||||
|
||||
The **2. On the Nginx UI container** tab shows a compose snippet, a full override file and a docker run command. It appears when the container needs changes: the mounted access mode, or a Linux Docker Engine that needs the `host.docker.internal` host-gateway mapping. Merge the snippet into your existing `docker-compose.yml`.
|
||||
|
||||
The generated snippet sets `NGINX_UI_DISABLE_BUNDLED_NGINX=true` so the container does not start its bundled nginx service while it controls the host nginx service.
|
||||
|
||||
In the mounted access mode, the snippet also bind-mounts the configured config, log and PID directories. Recreate the container after changing between Linux and macOS presets so the new paths are applied. In SFTP mode, no directory mounts are added.
|
||||
|
||||
If verification detects paths that differ from the initial preset, return to the container tab, regenerate the compose snippet, and recreate the container before running verification again.
|
||||
|
||||
::: tip Persist Nginx UI data
|
||||
Persist `/etc/nginx-ui` with a Docker volume or bind mount. The host key allow-list is stored at `/etc/nginx-ui/known_hosts` by default, and it should survive image upgrades and container rebuilds.
|
||||
:::
|
||||
|
||||
```bash
|
||||
docker compose up -d --force-recreate nginx-ui
|
||||
```
|
||||
|
||||
After the host and container changes are applied, run **Setup checks** at the bottom of the step. It runs the platform and privilege checks listed in the next step.
|
||||
|
||||
## Step 9: Verify the setup
|
||||
|
||||
Open **Verify** and click **Run verification**. The main checks should pass:
|
||||
|
||||
::: tip Expected verification result
|
||||
|
||||
@@ -177,6 +206,10 @@ If `known_hosts_persistence` is shown as a warning, review your Docker volume or
|
||||
|
||||
Click **Save configuration** after the checks pass.
|
||||
|
||||
::: tip Custom control commands
|
||||
If `TestConfigCmd`, `ReloadCmd` or `RestartCmd` are set in the Nginx settings, Nginx UI runs them on the host through `/bin/sh -c` as the SSH user instead of the built-in systemd or launchd commands. Keep them empty unless the generated sudoers entry covers whatever they invoke.
|
||||
:::
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
::: details `sudo_available` fails with "sudo: a password is required"
|
||||
@@ -213,7 +246,7 @@ Generate a keypair for host SSH:
|
||||
nginx-ui host-setup keygen --out /etc/nginx-ui/host_key
|
||||
```
|
||||
|
||||
Print all setup snippets:
|
||||
Print all setup snippets (`--access-mode` is required):
|
||||
|
||||
```bash
|
||||
nginx-ui host-setup print --host-address host.docker.internal:22 --host-user nginxui --access-mode sftp
|
||||
@@ -234,6 +267,8 @@ Run verification against the current settings:
|
||||
nginx-ui host-setup test
|
||||
```
|
||||
|
||||
Unlike the wizard, `test` runs every check group: connection, platform, privileges and nginx.
|
||||
|
||||
## Related docs
|
||||
|
||||
- [Nginx configuration reference](config-nginx.md#host-ssh-control)
|
||||
|
||||
@@ -118,6 +118,10 @@ nginx
|
||||
start-stop-daemon --start --quiet --pidfile $PID --exec $SBIN_PATH
|
||||
```
|
||||
|
||||
::: tip 通过 SSH 管理宿主机模式
|
||||
在通过 SSH 管理宿主机模式下，非空的 `TestConfigCmd`、`ReloadCmd` 或 `RestartCmd` 会以 SSH 用户身份通过 `/bin/sh -c` 在宿主机上执行。留空时，Nginx UI 会使用宿主机的 nginx 可执行文件进行测试，并通过 systemd 或 launchd 重载或重启。参见 [在 Docker 中管理宿主机 Nginx](manage-host-nginx-from-docker.md)。
|
||||
:::
|
||||
|
||||
### StubStatusPort
|
||||
- 类型：`uint`
|
||||
- 默认值：`51820`
|
||||
@@ -190,7 +194,7 @@ Nginx UI 通过自身的文件系统读写 Nginx 配置和日志文件。请将
|
||||
|
||||
## 通过 SSH 控制宿主机 Nginx
|
||||
|
||||
对于 Nginx UI 运行在 Docker 容器中、而 Nginx 以原生方式安装在宿主机上的部署场景，Nginx UI 提供了第三种控制模式，通过 SSH 执行命令并使用绑定挂载进行文件 I/O。该模式支持 Linux systemd 服务和 macOS Homebrew launchd 服务。
|
||||
对于 Nginx UI 运行在 Docker 容器中、而 Nginx 以原生方式安装在宿主机上的部署场景，Nginx UI 提供了第三种控制模式，通过 SSH 执行命令，并使用 SFTP 或绑定挂载进行文件 I/O。该模式支持 Linux systemd 服务和 macOS Homebrew launchd 服务。
|
||||
|
||||
### 限制
|
||||
|
||||
@@ -233,6 +237,6 @@ nginx-ui host-setup test
|
||||
| `host_launchctl_path` | 默认为 `/bin/launchctl` |
|
||||
| `host_config_dir` | 宿主机侧 nginx 配置目录 |
|
||||
| `host_log_dir` | 宿主机侧 nginx 日志目录 |
|
||||
| `sbin_path` | SSH 模式下应指向宿主机上的 nginx 可执行文件。生成的 sudoers 允许列表会精确匹配该路径 |
|
||||
| `sbin_path` | SSH 模式下可选：宿主机上的 nginx 可执行文件。留空时，Nginx UI 会解析服务管理器的默认值（systemd 为 `/usr/sbin/nginx`，launchd 为 `/opt/homebrew/opt/nginx/bin/nginx`），并在保存控制设置时写入。生成的 sudoers 允许列表会精确匹配解析后的路径 |
|
||||
|
||||
另请参阅：[在 Docker 中管理宿主机 Nginx](manage-host-nginx-from-docker.md) 和 [使用集群节点管理多主机 Nginx](manage-multi-host-nginx-with-cluster.md)。
|
||||
|
||||
@@ -183,5 +183,5 @@
|
||||
| `NGINX_UI_NGINX_HOST_LAUNCHCTL_PATH` | launchctl 的绝对路径，默认为 `/bin/launchctl` |
|
||||
| `NGINX_UI_NGINX_HOST_CONFIG_DIR` | 宿主机侧的 nginx 配置目录 |
|
||||
| `NGINX_UI_NGINX_HOST_LOG_DIR` | 宿主机侧的 nginx 日志目录 |
|
||||
| `NGINX_UI_NGINX_SBIN_PATH` | SSH 模式下为宿主机上 nginx 可执行文件的绝对路径。生成的 sudoers 允许列表会精确匹配该路径 |
|
||||
| `NGINX_UI_NGINX_SBIN_PATH` | SSH 模式下可选：宿主机上 nginx 可执行文件的绝对路径。留空时，Nginx UI 会解析服务管理器的默认值（systemd 为 `/usr/sbin/nginx`，launchd 为 `/opt/homebrew/opt/nginx/bin/nginx`）。生成的 sudoers 允许列表会精确匹配解析后的路径 |
|
||||
| `NGINX_UI_DISABLE_BUNDLED_NGINX` | 设置为 `true` 以禁用容器内置的 nginx（SSH 模式下必需） |
|
||||
|
||||
@@ -7,9 +7,10 @@
|
||||
- 同一宿主机上已安装 Docker
|
||||
- Linux：一个专用于 Nginx UI 的非特权用户（示例中使用 `nginxui`）
|
||||
- macOS：拥有 Homebrew nginx 服务的登录用户
|
||||
- Nginx UI 管理员已启用两步验证：配置向导需要已验证的两步验证会话，否则会显示**需要两步验证**
|
||||
:::
|
||||
|
||||
在 macOS 上，请在向导的**检测平台**步骤中选择 **macOS (Homebrew)**。Apple Silicon 默认使用 `/opt/homebrew`。在该步骤中，向导会通过 SSH 查询 Homebrew 并解析 `nginx -V`，自动识别已安装的 nginx 版本以及实际的可执行文件、配置、日志、PID 和 Docroot 路径；这也能识别位于 `/usr/local` 的 Intel Homebrew。继续前请确认服务已加载：
|
||||
在 macOS 上，请在向导的**检测平台**步骤中选择 **macOS（Homebrew）**。Apple Silicon 默认使用 `/opt/homebrew`。在该步骤中，向导会通过 SSH 查询 Homebrew 并解析 `nginx -V`，自动识别已安装的 nginx 版本以及实际的可执行文件、配置、日志、PID 和 Docroot 路径；这也能识别位于 `/usr/local` 的 Intel Homebrew。继续前请确认服务已加载：
|
||||
|
||||
```bash
|
||||
brew services info nginx
|
||||
@@ -25,13 +26,11 @@ sudo useradd -r -s /bin/bash -m -G adm nginxui
|
||||
|
||||
macOS 应使用运行 `brew services` 的现有登录用户，不要创建单独的服务用户。
|
||||
|
||||
## 步骤 2：通过 Nginx UI 生成密钥对
|
||||
## 步骤 2：SSH 目标——通过 Nginx UI 生成密钥对
|
||||
|
||||
打开**偏好设置 → Nginx → Nginx 控制模式 → 编辑**，选择**通过 SSH 管理宿主机**，再点击**打开 SSH 配置向导**。修改控制模式需要已验证的两步验证会话。
|
||||
|
||||
向导包含五个步骤：**SSH 目标**、**信任与测试**、**检测平台**、**安装**、**验证**。
|
||||
|
||||
在**检测平台**步骤中，每个路径字段会标记为**自动检测**（与宿主机上报值一致）或**手动覆盖**（被你改过）。手动覆盖的字段会显示检测值以及**恢复检测值**操作。修改 nginx 可执行文件路径后，可点击**根据该可执行文件重新检测路径**，重新执行 `nginx -V` 并刷新配置、日志和 PID 路径。
|
||||
向导包含五个步骤：**SSH 目标**、**信任与测试**、**检测平台**、**访问与安装**、**验证**。下面的步骤按同样的顺序展开。
|
||||
|
||||
在 **SSH 目标**步骤中选择私钥来源：
|
||||
|
||||
@@ -65,52 +64,7 @@ sudo chmod 600 /home/nginxui/.ssh/authorized_keys
|
||||
宿主机 SSH 模式需要使用 `known_hosts` 允许列表。向导显示新指纹时，请先在宿主机或其他可信渠道确认，再信任该密钥。
|
||||
:::
|
||||
|
||||
## 步骤 3：安装 sudoers 条目（仅 Linux）
|
||||
|
||||
向导**安装**步骤的**宿主机**页签会显示一段 sudoers 配置片段。复制后通过以下命令安装：
|
||||
|
||||
```bash
|
||||
sudo visudo -f /etc/sudoers.d/nginx-ui
|
||||
```
|
||||
|
||||
粘贴配置片段后保存并退出。如果语法有误，visudo 会拒绝保存该文件。
|
||||
|
||||
Homebrew launchd 服务运行在登录用户域中，不需要 sudoers 条目。
|
||||
|
||||
## 步骤 4：配置文件权限
|
||||
|
||||
::: details 可选 ACL 命令
|
||||
如果 nginxui 用户为非 root 用户，请授予其对 /etc/nginx 的写入权限：
|
||||
|
||||
```bash
|
||||
sudo setfacl -R -m u:nginxui:rwx /etc/nginx
|
||||
sudo setfacl -dR -m u:nginxui:rwx /etc/nginx
|
||||
```
|
||||
:::
|
||||
|
||||
在 macOS 上，向导会输出 Homebrew 配置和日志路径的读写检查，而不是 Linux ACL 命令。
|
||||
|
||||
## 步骤 5：更新 docker-compose 配置
|
||||
|
||||
向导**安装**步骤的**容器**页签会显示一段 compose 配置片段。将其合并到现有的 `docker-compose.yml` 中。
|
||||
|
||||
生成的片段会设置 `NGINX_UI_DISABLE_BUNDLED_NGINX=true`，避免容器在控制宿主机 nginx 时继续启动内置 nginx 服务。
|
||||
|
||||
片段还会绑定挂载已配置的 PID 目录。在 Linux 与 macOS 预设之间切换后，请重建容器以应用新路径。
|
||||
|
||||
如果验证检测到的路径与初始预设不同，请返回容器步骤重新生成 compose 片段，重建容器后再运行验证。
|
||||
|
||||
::: tip 持久化 Nginx UI 数据
|
||||
请通过 Docker volume 或 bind mount 持久化 `/etc/nginx-ui`。宿主机密钥允许列表默认保存在 `/etc/nginx-ui/known_hosts`，它应在镜像升级和容器重建后继续存在。
|
||||
:::
|
||||
|
||||
macOS 上，`host_platform` 会报告 Darwin，`launchctl_service_loaded` 取代两个 systemd 检查，sudo 检查会显示不需要 sudo。配置、日志和 PID 检查默认使用 `/opt/homebrew` 路径。
|
||||
|
||||
```bash
|
||||
docker compose up -d --force-recreate nginx-ui
|
||||
```
|
||||
|
||||
## 步骤 6：信任主机身份
|
||||
## 步骤 3：信任与测试——信任主机身份
|
||||
|
||||
打开向导的**信任与测试**步骤，点击**扫描主机密钥**。向导会将 SSH 服务端提供的主机密钥与已配置的 `known_hosts` 文件进行比较。
|
||||
|
||||
@@ -147,9 +101,82 @@ ssh-keyscan -p 22 host.docker.internal
|
||||
- **trusted**：扫描到的密钥与 `known_hosts` 匹配。
|
||||
:::
|
||||
|
||||
## 步骤 7：验证配置
|
||||
信任所有扫描到的密钥后，点击**测试 SSH 连接**。连接成功后向导才允许继续。
|
||||
|
||||
返回**验证**，点击**运行验证**。主要检查项应通过：
|
||||
## 步骤 4：检测平台
|
||||
|
||||
在**检测平台**步骤中选择服务管理器（**Linux（systemd）**或 **macOS（Homebrew）**）。向导会通过 SSH 执行 `nginx -V`，并填入 nginx 可执行文件、配置、日志和 PID 路径。
|
||||
|
||||
每个路径字段会标记为**自动检测**（与宿主机上报值一致）或**手动覆盖**（被你改过）。手动覆盖的字段会显示检测值以及**恢复检测值**操作。修改 nginx 可执行文件路径后，可点击**根据该可执行文件重新检测路径**，重新执行 `nginx -V` 并刷新配置、日志和 PID 路径。
|
||||
|
||||
nginx 可执行文件路径会保存为 `sbin_path`。如果留空，Nginx UI 会回退到服务管理器的默认值（systemd 为 `/usr/sbin/nginx`，launchd 为 `/opt/homebrew/opt/nginx/bin/nginx`），并在保存配置时写入该默认值。下一步生成的 sudoers 允许列表会精确匹配这个解析后的路径。
|
||||
|
||||
## 步骤 5：访问与安装——选择文件访问模式
|
||||
|
||||
**访问与安装**步骤首先是**文件访问模式**：
|
||||
|
||||
| 模式 | 行为 |
|
||||
| --- | --- |
|
||||
| **兼容模式（SFTP）** | Nginx UI 完全通过 SSH 和 SFTP 读写宿主机的 nginx 配置和日志。不会把宿主机目录挂载到容器中。 |
|
||||
| **高性能模式（挂载）** | Nginx UI 从绑定挂载的宿主机目录读取配置和日志。速度更快，但必须按生成的挂载配置重建容器。 |
|
||||
|
||||
所选模式会保存为 `host_access_mode` 设置。
|
||||
|
||||
::: details SFTP 模式覆盖的范围
|
||||
- 配置文件、日志文件，以及证书签发或续期时写出的证书文件，都通过 SFTP 在宿主机上读写。
|
||||
- 容器无法通过 SFTP 监听宿主机文件变化，因此配置索引和证书发现会改为每 30 秒重新扫描一次。在宿主机上绕过 Nginx UI 所做的修改最多需要 30 秒才会显示在界面中。
|
||||
- **共享配置目录**自检会被跳过，因为容器与宿主机之间没有共享目录。
|
||||
- 已知限制：证书目录中可导入证书的扫描仍然读取容器文件系统，因此无法发现只存在于宿主机上的证书。如果依赖该扫描，请在 Nginx UI 中签发或续期证书，或改用挂载模式。
|
||||
:::
|
||||
|
||||
## 步骤 6：访问与安装——安装 sudoers 条目（仅 Linux）
|
||||
|
||||
**1. 在 nginx 宿主机上**页签会显示一段 sudoers 配置片段。复制后通过以下命令安装：
|
||||
|
||||
```bash
|
||||
sudo visudo -f /etc/sudoers.d/nginx-ui
|
||||
```
|
||||
|
||||
粘贴配置片段后保存并退出。如果语法有误，visudo 会拒绝保存该文件。
|
||||
|
||||
Homebrew launchd 服务运行在登录用户域中，不需要 sudoers 条目。
|
||||
|
||||
## 步骤 7：访问与安装——配置文件权限
|
||||
|
||||
::: details 可选 ACL 命令
|
||||
如果 nginxui 用户为非 root 用户，请授予其对 /etc/nginx 的写入权限：
|
||||
|
||||
```bash
|
||||
sudo setfacl -R -m u:nginxui:rwx /etc/nginx
|
||||
sudo setfacl -dR -m u:nginxui:rwx /etc/nginx
|
||||
```
|
||||
:::
|
||||
|
||||
在 macOS 上，向导会输出 Homebrew 配置和日志路径的读写检查，而不是 Linux ACL 命令。
|
||||
|
||||
## 步骤 8：访问与安装——更新容器
|
||||
|
||||
**2. 在 Nginx UI 容器中**页签会显示 compose 配置片段、完整的 override 文件和 docker run 命令。该页签只在容器需要修改时出现：使用挂载模式，或者 Linux Docker Engine 需要为 `host.docker.internal` 添加 host-gateway 映射。将片段合并到现有的 `docker-compose.yml` 中。
|
||||
|
||||
生成的片段会设置 `NGINX_UI_DISABLE_BUNDLED_NGINX=true`，避免容器在控制宿主机 nginx 时继续启动内置 nginx 服务。
|
||||
|
||||
在挂载模式下，片段还会绑定挂载已配置的配置、日志和 PID 目录。在 Linux 与 macOS 预设之间切换后，请重建容器以应用新路径。SFTP 模式下不会添加任何目录挂载。
|
||||
|
||||
如果验证检测到的路径与初始预设不同，请返回容器页签重新生成 compose 片段，重建容器后再运行验证。
|
||||
|
||||
::: tip 持久化 Nginx UI 数据
|
||||
请通过 Docker volume 或 bind mount 持久化 `/etc/nginx-ui`。宿主机密钥允许列表默认保存在 `/etc/nginx-ui/known_hosts`，它应在镜像升级和容器重建后继续存在。
|
||||
:::
|
||||
|
||||
```bash
|
||||
docker compose up -d --force-recreate nginx-ui
|
||||
```
|
||||
|
||||
宿主机和容器的修改都应用后，运行该步骤底部的**配置检查**。它会执行下一步列出的平台和权限检查。
|
||||
|
||||
## 步骤 9：验证配置
|
||||
|
||||
打开**验证**，点击**运行验证**。主要检查项应通过：
|
||||
|
||||
::: tip 预期验证结果
|
||||
|
||||
@@ -158,7 +185,7 @@ ssh-keyscan -p 22 host.docker.internal
|
||||
- ✓ ssh_connect: 通过 SSH 执行 echo ok 成功
|
||||
- ✓ nginx_test: 配置文件检查通过
|
||||
|
||||
平台和权限检查属于**访问与安装**步骤中的**安装检查**，应用片段后你已经运行过：
|
||||
平台和权限检查属于**访问与安装**步骤中的**配置检查**，应用片段后你已经运行过：
|
||||
|
||||
- ✓ host_platform: Linux host matches systemd
|
||||
- ✓ systemctl_is_active: 运行中
|
||||
@@ -173,10 +200,16 @@ ssh-keyscan -p 22 host.docker.internal
|
||||
|
||||
:::
|
||||
|
||||
macOS 上，`host_platform` 会报告 Darwin，`launchctl_service_loaded` 取代两个 systemd 检查，sudo 检查会显示不需要 sudo。配置、日志和 PID 检查默认使用 `/opt/homebrew` 路径。
|
||||
|
||||
如果 `known_hosts_persistence` 显示为 warning，请检查 Docker volume 或 bind mount。该警告不会阻止保存，但如果 `/etc/nginx-ui` 未被持久化，容器重建后可信主机密钥可能会丢失。
|
||||
|
||||
所有检查通过后，点击**保存配置**。
|
||||
|
||||
::: tip 自定义控制命令
|
||||
如果在 Nginx 设置中配置了 `TestConfigCmd`、`ReloadCmd` 或 `RestartCmd`，Nginx UI 会以 SSH 用户身份通过 `/bin/sh -c` 在宿主机上执行这些命令，而不是内置的 systemd 或 launchd 命令。除非生成的 sudoers 条目覆盖了这些命令所调用的程序，否则请保持为空。
|
||||
:::
|
||||
|
||||
## 故障排查
|
||||
|
||||
::: details `sudo_available` 报错 "sudo: a password is required"
|
||||
@@ -213,7 +246,7 @@ ssh-keyscan -p 22 host.docker.internal
|
||||
nginx-ui host-setup keygen --out /etc/nginx-ui/host_key
|
||||
```
|
||||
|
||||
输出全部配置片段：
|
||||
输出全部配置片段（`--access-mode` 为必填）：
|
||||
|
||||
```bash
|
||||
nginx-ui host-setup print --host-address host.docker.internal:22 --host-user nginxui --access-mode sftp
|
||||
@@ -234,6 +267,8 @@ nginx-ui host-setup print --host-address host.docker.internal:22 --host-user ngi
|
||||
nginx-ui host-setup test
|
||||
```
|
||||
|
||||
与向导不同，`test` 会运行全部检查组：连接、平台、权限和 nginx。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Nginx 配置参考](config-nginx.md#通过-ssh-控制宿主机-nginx)
|
||||
|
||||
@@ -111,6 +111,10 @@ start-stop-daemon --stop --quiet --oknodo --retry=TERM/30/KILL/5 --pidfile $PID
|
||||
start-stop-daemon --start --quiet --pidfile $PID --exec $SBIN_PATH
|
||||
```
|
||||
|
||||
::: tip 透過 SSH 管理宿主機模式
|
||||
在透過 SSH 管理宿主機模式下，非空的 `TestConfigCmd`、`ReloadCmd` 或 `RestartCmd` 會以 SSH 使用者身分透過 `/bin/sh -c` 在宿主機上執行。留空時，Nginx UI 會使用宿主機的 nginx 執行檔進行測試，並透過 systemd 或 launchd 重新載入或重新啟動。參見 [在 Docker 中管理宿主機 Nginx](manage-host-nginx-from-docker.md)。
|
||||
:::
|
||||
|
||||
### StubStatusPort
|
||||
- 類型：`uint`
|
||||
- 預設值：`51820`
|
||||
@@ -181,7 +185,7 @@ services:
|
||||
|
||||
## 透過 SSH 控制宿主機 Nginx
|
||||
|
||||
對於 Nginx UI 執行在 Docker 容器中、而 Nginx 以原生方式安裝在宿主機上的部署場景，Nginx UI 提供了第三種控制模式，透過 SSH 執行命令並使用綁定掛載進行檔案 I/O。此模式支援 Linux systemd 服務與 macOS Homebrew launchd 服務。
|
||||
對於 Nginx UI 執行在 Docker 容器中、而 Nginx 以原生方式安裝在宿主機上的部署場景，Nginx UI 提供了第三種控制模式，透過 SSH 執行命令，並使用 SFTP 或綁定掛載進行檔案 I/O。此模式支援 Linux systemd 服務與 macOS Homebrew launchd 服務。
|
||||
|
||||
### 限制
|
||||
|
||||
@@ -224,6 +228,6 @@ nginx-ui host-setup test
|
||||
| `host_launchctl_path` | 預設為 `/bin/launchctl` |
|
||||
| `host_config_dir` | 宿主機側 nginx 設定目錄 |
|
||||
| `host_log_dir` | 宿主機側 nginx 日誌目錄 |
|
||||
| `sbin_path` | SSH 模式下應指向宿主機上的 nginx 執行檔。產生的 sudoers 允許清單會精確比對該路徑 |
|
||||
| `sbin_path` | SSH 模式下選填：宿主機上的 nginx 執行檔。留空時，Nginx UI 會解析服務管理器的預設值（systemd 為 `/usr/sbin/nginx`，launchd 為 `/opt/homebrew/opt/nginx/bin/nginx`），並在儲存控制設定時寫入。產生的 sudoers 允許清單會精確比對解析後的路徑 |
|
||||
|
||||
另請參閱：[在 Docker 中管理宿主機 Nginx](manage-host-nginx-from-docker.md) 和 [使用叢集節點管理多主機 Nginx](manage-multi-host-nginx-with-cluster.md)。
|
||||
|
||||
@@ -183,5 +183,5 @@
|
||||
| `NGINX_UI_NGINX_HOST_LAUNCHCTL_PATH` | launchctl 的絕對路徑，預設為 `/bin/launchctl` |
|
||||
| `NGINX_UI_NGINX_HOST_CONFIG_DIR` | 宿主機側的 nginx 設定目錄 |
|
||||
| `NGINX_UI_NGINX_HOST_LOG_DIR` | 宿主機側的 nginx 日誌目錄 |
|
||||
| `NGINX_UI_NGINX_SBIN_PATH` | SSH 模式下為宿主機上 nginx 執行檔的絕對路徑。產生的 sudoers 允許清單會精確比對該路徑 |
|
||||
| `NGINX_UI_NGINX_SBIN_PATH` | SSH 模式下選填：宿主機上 nginx 執行檔的絕對路徑。留空時，Nginx UI 會解析服務管理器的預設值（systemd 為 `/usr/sbin/nginx`，launchd 為 `/opt/homebrew/opt/nginx/bin/nginx`）。產生的 sudoers 允許清單會精確比對解析後的路徑 |
|
||||
| `NGINX_UI_DISABLE_BUNDLED_NGINX` | 設定為 `true` 以停用容器內建的 nginx（SSH 模式下必需） |
|
||||
|
||||
@@ -7,6 +7,7 @@
|
||||
- 同一宿主機上已安裝 Docker
|
||||
- Linux：一個專用於 Nginx UI 的非特權使用者（範例中使用 `nginxui`）
|
||||
- macOS：擁有 Homebrew nginx 服務的登入使用者
|
||||
- Nginx UI 管理員已啟用多重因素驗證：設定精靈需要已驗證的雙因素工作階段，否則會顯示**需要多重因素驗證**
|
||||
:::
|
||||
|
||||
在 macOS 上，請在精靈的**偵測平台**步驟中選擇 **macOS (Homebrew)**。Apple Silicon 預設使用 `/opt/homebrew`。在該步驟中，精靈會透過 SSH 查詢 Homebrew 並解析 `nginx -V`，自動識別已安裝的 nginx 版本以及實際的執行檔、設定、日誌、PID 和 Docroot 路徑；這也能識別位於 `/usr/local` 的 Intel Homebrew。繼續前請確認服務已載入：
|
||||
@@ -25,13 +26,11 @@ sudo useradd -r -s /bin/bash -m -G adm nginxui
|
||||
|
||||
macOS 應使用執行 `brew services` 的現有登入使用者，不要建立單獨的服務使用者。
|
||||
|
||||
## 步驟 2：透過 Nginx UI 產生金鑰對
|
||||
## 步驟 2：SSH 目標——透過 Nginx UI 產生金鑰對
|
||||
|
||||
開啟**偏好設定 → Nginx → Nginx 控制模式 → 編輯**，選擇**透過 SSH 管理宿主機**，然後點擊**開啟 SSH 設定精靈**。變更控制模式需要已驗證的雙因素工作階段。
|
||||
|
||||
精靈共有五個步驟：**SSH 目標**、**信任與測試**、**偵測平台**、**安裝**與**驗證**。
|
||||
|
||||
在**偵測平台**中，每個路徑欄位在與宿主機回報的值一致時標示為**自動偵測**，被你改動後則標示為**手動覆寫**。被覆寫的欄位會顯示偵測到的值，並提供**還原偵測值**動作。變更 nginx 執行檔路徑後，可使用**依此執行檔重新偵測路徑**再次執行 `nginx -V`，以重新整理設定檔、日誌與 PID 路徑。
|
||||
精靈共有五個步驟：**SSH 目標**、**信任與測試**、**偵測平台**、**存取與安裝**與**驗證**。以下步驟依同樣的順序說明。
|
||||
|
||||
在 **SSH 目標**中選擇私鑰來源：
|
||||
|
||||
@@ -65,54 +64,9 @@ sudo chmod 600 /home/nginxui/.ssh/authorized_keys
|
||||
宿主機 SSH 模式需要使用 `known_hosts` 允許清單。精靈顯示新指紋時，請先在宿主機或其他可信管道確認，再信任該金鑰。
|
||||
:::
|
||||
|
||||
## 步驟 3：安裝 sudoers 項目（僅 Linux）
|
||||
## 步驟 3：信任與測試——信任主機身分
|
||||
|
||||
精靈**安裝**步驟的**宿主機**頁籤會顯示一段 sudoers 設定片段。複製後透過以下指令安裝：
|
||||
|
||||
```bash
|
||||
sudo visudo -f /etc/sudoers.d/nginx-ui
|
||||
```
|
||||
|
||||
貼上設定片段後儲存並退出。如果語法有誤，visudo 會拒絕儲存該檔案。
|
||||
|
||||
Homebrew launchd 服務執行於登入使用者域中，不需要 sudoers 項目。
|
||||
|
||||
## 步驟 4：設定檔案權限
|
||||
|
||||
::: details 選用 ACL 指令
|
||||
如果 nginxui 使用者為非 root 使用者，請授予其對 /etc/nginx 的寫入權限：
|
||||
|
||||
```bash
|
||||
sudo setfacl -R -m u:nginxui:rwx /etc/nginx
|
||||
sudo setfacl -dR -m u:nginxui:rwx /etc/nginx
|
||||
```
|
||||
:::
|
||||
|
||||
在 macOS 上，精靈會輸出 Homebrew 設定與日誌路徑的讀寫檢查，而不是 Linux ACL 指令。
|
||||
|
||||
## 步驟 5：更新 docker-compose 設定
|
||||
|
||||
精靈**安裝**步驟的**容器**頁籤會顯示一段 compose 設定片段。將其合併到現有的 `docker-compose.yml` 中。
|
||||
|
||||
產生的片段會設定 `NGINX_UI_DISABLE_BUNDLED_NGINX=true`，避免容器在控制宿主機 nginx 時繼續啟動內建 nginx 服務。
|
||||
|
||||
片段也會綁定掛載已設定的 PID 目錄。在 Linux 與 macOS 預設之間切換後，請重建容器以套用新路徑。
|
||||
|
||||
如果驗證偵測到的路徑與初始預設不同，請返回容器步驟重新產生 compose 片段，重建容器後再執行驗證。
|
||||
|
||||
::: tip 持久化 Nginx UI 資料
|
||||
請透過 Docker volume 或 bind mount 持久化 `/etc/nginx-ui`。宿主機金鑰允許清單預設保存在 `/etc/nginx-ui/known_hosts`，它應在映像升級和容器重建後繼續存在。
|
||||
:::
|
||||
|
||||
macOS 上，`host_platform` 會回報 Darwin，`launchctl_service_loaded` 取代兩個 systemd 檢查，sudo 檢查會顯示不需要 sudo。設定、日誌與 PID 檢查預設使用 `/opt/homebrew` 路徑。
|
||||
|
||||
```bash
|
||||
docker compose up -d --force-recreate nginx-ui
|
||||
```
|
||||
|
||||
## 步驟 6：信任主機身分
|
||||
|
||||
開啟設定精靈中的**主機身分**，點擊**掃描主機金鑰**。精靈會將 SSH 服務端提供的主機金鑰與已設定的 `known_hosts` 檔案進行比較。
|
||||
開啟精靈的**信任與測試**步驟，點擊**掃描主機金鑰**。精靈會將 SSH 服務端提供的主機金鑰與已設定的 `known_hosts` 檔案進行比較。
|
||||
|
||||
::: warning 信任前請先驗證
|
||||
只有在透過可信來源比對指紋後，才應信任金鑰。這個檢查用於避免在首次設定或金鑰輪換時連線到錯誤的主機。
|
||||
@@ -147,9 +101,82 @@ ssh-keyscan -p 22 host.docker.internal
|
||||
- **trusted**：掃描到的金鑰與 `known_hosts` 匹配。
|
||||
:::
|
||||
|
||||
## 步驟 7：驗證設定
|
||||
信任所有掃描到的金鑰後，點擊**測試 SSH 連線**。連線成功後精靈才允許繼續。
|
||||
|
||||
返回**驗證**，點擊**執行驗證**。主要檢查項應通過：
|
||||
## 步驟 4：偵測平台
|
||||
|
||||
在**偵測平台**步驟中選擇服務管理器（**Linux (systemd)** 或 **macOS (Homebrew)**）。精靈會透過 SSH 執行 `nginx -V`，並填入 nginx 執行檔、設定、日誌與 PID 路徑。
|
||||
|
||||
每個路徑欄位在與宿主機回報的值一致時標示為**自動偵測**，被你改動後則標示為**手動覆寫**。被覆寫的欄位會顯示偵測到的值，並提供**還原偵測值**動作。變更 nginx 執行檔路徑後，可使用**依此執行檔重新偵測路徑**再次執行 `nginx -V`，以重新整理設定檔、日誌與 PID 路徑。
|
||||
|
||||
nginx 執行檔路徑會保存為 `sbin_path`。若留空，Nginx UI 會回退到服務管理器的預設值（systemd 為 `/usr/sbin/nginx`，launchd 為 `/opt/homebrew/opt/nginx/bin/nginx`），並在儲存設定時寫入該預設值。下一步產生的 sudoers 允許清單會精確比對這個解析後的路徑。
|
||||
|
||||
## 步驟 5：存取與安裝——選擇檔案存取模式
|
||||
|
||||
**存取與安裝**步驟首先是**檔案存取模式**：
|
||||
|
||||
| 模式 | 行為 |
|
||||
| --- | --- |
|
||||
| **相容模式（SFTP）** | Nginx UI 完全透過 SSH 與 SFTP 讀寫宿主機的 nginx 設定與日誌。不會把宿主機目錄掛載到容器中。 |
|
||||
| **高效能模式（掛載）** | Nginx UI 從綁定掛載的宿主機目錄讀取設定與日誌。速度更快，但必須依產生的掛載設定重建容器。 |
|
||||
|
||||
所選模式會保存為 `host_access_mode` 設定。
|
||||
|
||||
::: details SFTP 模式涵蓋的範圍
|
||||
- 設定檔、日誌檔，以及憑證簽發或續期時寫出的憑證檔案，都透過 SFTP 在宿主機上讀寫。
|
||||
- 容器無法透過 SFTP 監聽宿主機檔案變化，因此設定索引與憑證探索會改為每 30 秒重新掃描一次。在宿主機上繞過 Nginx UI 所做的修改最多需要 30 秒才會顯示在介面中。
|
||||
- **共用設定目錄**自我檢查會被跳過，因為容器與宿主機之間沒有共用目錄。
|
||||
- 已知限制：憑證目錄中可匯入憑證的掃描仍然讀取容器檔案系統，因此無法發現只存在於宿主機上的憑證。如果依賴該掃描，請在 Nginx UI 中簽發或續期憑證，或改用掛載模式。
|
||||
:::
|
||||
|
||||
## 步驟 6：存取與安裝——安裝 sudoers 項目（僅 Linux）
|
||||
|
||||
**1. 在 nginx 主機上**頁籤會顯示一段 sudoers 設定片段。複製後透過以下指令安裝：
|
||||
|
||||
```bash
|
||||
sudo visudo -f /etc/sudoers.d/nginx-ui
|
||||
```
|
||||
|
||||
貼上設定片段後儲存並退出。如果語法有誤，visudo 會拒絕儲存該檔案。
|
||||
|
||||
Homebrew launchd 服務執行於登入使用者域中，不需要 sudoers 項目。
|
||||
|
||||
## 步驟 7：存取與安裝——設定檔案權限
|
||||
|
||||
::: details 選用 ACL 指令
|
||||
如果 nginxui 使用者為非 root 使用者，請授予其對 /etc/nginx 的寫入權限：
|
||||
|
||||
```bash
|
||||
sudo setfacl -R -m u:nginxui:rwx /etc/nginx
|
||||
sudo setfacl -dR -m u:nginxui:rwx /etc/nginx
|
||||
```
|
||||
:::
|
||||
|
||||
在 macOS 上，精靈會輸出 Homebrew 設定與日誌路徑的讀寫檢查，而不是 Linux ACL 指令。
|
||||
|
||||
## 步驟 8：存取與安裝——更新容器
|
||||
|
||||
**2. 在 Nginx UI 容器上**頁籤會顯示 compose 設定片段、完整的 override 檔案與 docker run 指令。該頁籤只在容器需要變更時出現：使用掛載模式，或者 Linux Docker Engine 需要為 `host.docker.internal` 加入 host-gateway 對應。將片段合併到現有的 `docker-compose.yml` 中。
|
||||
|
||||
產生的片段會設定 `NGINX_UI_DISABLE_BUNDLED_NGINX=true`，避免容器在控制宿主機 nginx 時繼續啟動內建 nginx 服務。
|
||||
|
||||
在掛載模式下，片段也會綁定掛載已設定的設定、日誌與 PID 目錄。在 Linux 與 macOS 預設之間切換後，請重建容器以套用新路徑。SFTP 模式下不會加入任何目錄掛載。
|
||||
|
||||
如果驗證偵測到的路徑與初始預設不同，請返回容器頁籤重新產生 compose 片段，重建容器後再執行驗證。
|
||||
|
||||
::: tip 持久化 Nginx UI 資料
|
||||
請透過 Docker volume 或 bind mount 持久化 `/etc/nginx-ui`。宿主機金鑰允許清單預設保存在 `/etc/nginx-ui/known_hosts`，它應在映像升級和容器重建後繼續存在。
|
||||
:::
|
||||
|
||||
```bash
|
||||
docker compose up -d --force-recreate nginx-ui
|
||||
```
|
||||
|
||||
宿主機與容器的變更都套用後，執行該步驟底部的**設定檢查**。它會執行下一步列出的平台與權限檢查。
|
||||
|
||||
## 步驟 9：驗證設定
|
||||
|
||||
開啟**驗證**，點擊**執行驗證**。主要檢查項應通過：
|
||||
|
||||
::: tip 預期驗證結果
|
||||
|
||||
@@ -158,7 +185,7 @@ ssh-keyscan -p 22 host.docker.internal
|
||||
- ✓ ssh_connect: 透過 SSH 執行 echo ok 成功
|
||||
- ✓ nginx_test: 設定檔檢查通過
|
||||
|
||||
平台和權限檢查屬於**存取與安裝**步驟中的**安裝檢查**，套用片段後你已經執行過：
|
||||
平台和權限檢查屬於**存取與安裝**步驟中的**設定檢查**，套用片段後你已經執行過：
|
||||
|
||||
- ✓ host_platform: Linux host matches systemd
|
||||
- ✓ systemctl_is_active: 執行中
|
||||
@@ -173,10 +200,16 @@ ssh-keyscan -p 22 host.docker.internal
|
||||
|
||||
:::
|
||||
|
||||
macOS 上，`host_platform` 會回報 Darwin，`launchctl_service_loaded` 取代兩個 systemd 檢查，sudo 檢查會顯示不需要 sudo。設定、日誌與 PID 檢查預設使用 `/opt/homebrew` 路徑。
|
||||
|
||||
如果 `known_hosts_persistence` 顯示為 warning，請檢查 Docker volume 或 bind mount。該警告不會阻止儲存，但如果 `/etc/nginx-ui` 未被持久化，容器重建後可信主機金鑰可能會遺失。
|
||||
|
||||
所有檢查通過後，點擊**儲存設定**。
|
||||
|
||||
::: tip 自訂控制指令
|
||||
如果在 Nginx 設定中設定了 `TestConfigCmd`、`ReloadCmd` 或 `RestartCmd`，Nginx UI 會以 SSH 使用者身分透過 `/bin/sh -c` 在宿主機上執行這些指令，而不是內建的 systemd 或 launchd 指令。除非產生的 sudoers 項目涵蓋了這些指令所呼叫的程式，否則請保持為空。
|
||||
:::
|
||||
|
||||
## 疑難排解
|
||||
|
||||
::: details `sudo_available` 報錯 "sudo: a password is required"
|
||||
@@ -213,7 +246,7 @@ ssh-keyscan -p 22 host.docker.internal
|
||||
nginx-ui host-setup keygen --out /etc/nginx-ui/host_key
|
||||
```
|
||||
|
||||
輸出全部設定片段：
|
||||
輸出全部設定片段（`--access-mode` 為必填）：
|
||||
|
||||
```bash
|
||||
nginx-ui host-setup print --host-address host.docker.internal:22 --host-user nginxui --access-mode sftp
|
||||
@@ -234,6 +267,8 @@ nginx-ui host-setup print --host-address host.docker.internal:22 --host-user ngi
|
||||
nginx-ui host-setup test
|
||||
```
|
||||
|
||||
與精靈不同，`test` 會執行全部檢查組：連線、平台、權限與 nginx。
|
||||
|
||||
## 相關文件
|
||||
|
||||
- [Nginx 設定參考](config-nginx.md#透過-ssh-控制宿主機-nginx)
|
||||
|
||||
Reference in New Issue
Block a user