mirror of
https://github.com/0xJacky/nginx-ui.git
synced 2026-06-19 07:36:59 +00:00
docs: document host_via_ssh mode in nginx config and env reference
This commit is contained in:
Hintay
@@ -172,3 +172,39 @@ If you are using the official Nginx UI container and want to control Nginx in an
|
||||
|
||||
For example: `-v /var/run/docker.sock:/var/run/docker.sock`
|
||||
:::
|
||||
|
||||
## Host SSH Control
|
||||
|
||||
For deployments where Nginx UI runs in a Docker container but Nginx is installed natively on the host machine (e.g. systemd-managed via apt/yum), Nginx UI provides a third control mode that uses SSH for command execution and bind-mounts for file I/O.
|
||||
|
||||
### Constraints
|
||||
|
||||
- **Same-host only**: the Nginx UI container and the target nginx process must be on the same physical/virtual machine. For multi-host management, see [the cluster Node cross-host guide](cluster-node-cross-host.md).
|
||||
- **systemd required** on the host. The mode invokes `systemctl reload|restart <unit>` for control.
|
||||
- The host nginx user must allow a dedicated unprivileged user (typically `nginxui`) to invoke a narrow set of commands via `sudo -n` without password.
|
||||
|
||||
### Quick start
|
||||
|
||||
1. From the Web UI, go to **Preferences → Nginx**, select **Host via SSH** mode, and open the setup wizard.
|
||||
2. Follow the four-step wizard: generate a keypair, paste the generated docker-compose snippet into your stack, apply the sudoers/authorized_keys snippets on the host, and run the verification.
|
||||
3. Once all checks pass, save the configuration.
|
||||
|
||||
Alternatively, use the CLI:
|
||||
|
||||
```bash
|
||||
nginx-ui host-setup print --host-address host.docker.internal:22 --host-user nginxui
|
||||
nginx-ui host-setup test
|
||||
```
|
||||
|
||||
### Configuration fields
|
||||
|
||||
| Field | Description |
|
||||
|---|---|
|
||||
| `host_mode` | Set to `ssh` to enable this mode |
|
||||
| `host_address` | Remote `host:port` |
|
||||
| `host_user` | SSH user on the host |
|
||||
| `host_private_key_path` | Private key path inside the container |
|
||||
| `host_systemd_unit_name` | Default `nginx.service` |
|
||||
| `host_systemctl_path` | Default `/bin/systemctl` |
|
||||
|
||||
See also: [Host SSH setup walkthrough](host-via-ssh-setup.md).
|
||||
|
||||
@@ -141,3 +141,19 @@ In skip installation mode, you can set the following environment variables to cr
|
||||
|
||||
- NGINX_UI_PREDEFINED_USER_NAME
|
||||
- NGINX_UI_PREDEFINED_USER_PASSWORD
|
||||
|
||||
## Host SSH Control
|
||||
|
||||
| Variable | Description |
|
||||
|---|---|
|
||||
| `NGINX_UI_NGINX_HOST_MODE` | Set to `ssh` to enable host SSH control |
|
||||
| `NGINX_UI_NGINX_HOST_ADDRESS` | Remote `host:port`, e.g. `host.docker.internal:22` |
|
||||
| `NGINX_UI_NGINX_HOST_USER` | SSH user on the host |
|
||||
| `NGINX_UI_NGINX_HOST_PRIVATE_KEY_PATH` | Private key path inside the container |
|
||||
| `NGINX_UI_NGINX_HOST_KNOWN_HOSTS_PATH` | known_hosts path inside the container |
|
||||
| `NGINX_UI_NGINX_HOST_SUDO_PREFIX` | Default `sudo -n` |
|
||||
| `NGINX_UI_NGINX_HOST_SYSTEMD_UNIT_NAME` | Default `nginx.service` |
|
||||
| `NGINX_UI_NGINX_HOST_SYSTEMCTL_PATH` | Absolute path to systemctl on the host |
|
||||
| `NGINX_UI_NGINX_HOST_CONFIG_DIR` | Host-side nginx config dir |
|
||||
| `NGINX_UI_NGINX_HOST_LOG_DIR` | Host-side nginx log dir |
|
||||
| `NGINX_UI_DISABLE_BUNDLED_NGINX` | Set to `true` to disable the container's bundled nginx (required in SSH mode) |
|
||||
|
||||
@@ -173,3 +173,39 @@ services:
|
||||
|
||||
例如：`-v /var/run/docker.sock:/var/run/docker.sock`
|
||||
:::
|
||||
|
||||
## 通过 SSH 控制宿主机 Nginx
|
||||
|
||||
对于 Nginx UI 运行在 Docker 容器中、而 Nginx 以原生方式安装在宿主机上的部署场景（例如通过 apt/yum 安装并由 systemd 管理），Nginx UI 提供了第三种控制模式，通过 SSH 执行命令并使用绑定挂载进行文件 I/O。
|
||||
|
||||
### 限制
|
||||
|
||||
- **仅限同一宿主机**：Nginx UI 容器与目标 nginx 进程必须在同一台物理机或虚拟机上。如需多主机管理，请参阅 [集群节点跨主机指南](cluster-node-cross-host.md)。
|
||||
- 宿主机上**需要 systemd**。该模式通过调用 `systemctl reload|restart <unit>` 来控制服务。
|
||||
- 宿主机的 nginx 用户必须允许一个专用的非特权用户（通常为 `nginxui`）通过 `sudo -n` 无密码执行一组受限命令。
|
||||
|
||||
### 快速开始
|
||||
|
||||
1. 在 Web 界面中，前往**偏好设置 → Nginx**，选择**通过 SSH 控制宿主机**模式，并打开配置向导。
|
||||
2. 按照四步配置向导操作：生成密钥对、将生成的 docker-compose 片段粘贴到您的 stack 中、在宿主机上应用 sudoers/authorized_keys 片段，然后执行验证。
|
||||
3. 所有检查通过后，保存配置。
|
||||
|
||||
也可以使用命令行：
|
||||
|
||||
```bash
|
||||
nginx-ui host-setup print --host-address host.docker.internal:22 --host-user nginxui
|
||||
nginx-ui host-setup test
|
||||
```
|
||||
|
||||
### 配置字段
|
||||
|
||||
| 字段 | 描述 |
|
||||
|---|---|
|
||||
| `host_mode` | 设置为 `ssh` 以启用此模式 |
|
||||
| `host_address` | 远程 `host:port` |
|
||||
| `host_user` | 宿主机上的 SSH 用户 |
|
||||
| `host_private_key_path` | 容器内的私钥路径 |
|
||||
| `host_systemd_unit_name` | 默认为 `nginx.service` |
|
||||
| `host_systemctl_path` | 默认为 `/bin/systemctl` |
|
||||
|
||||
另请参阅：[Host SSH 设置指引](host-via-ssh-setup.md)。
|
||||
|
||||
@@ -155,3 +155,19 @@
|
||||
|
||||
- NGINX_UI_PREDEFINED_USER_NAME
|
||||
- NGINX_UI_PREDEFINED_USER_PASSWORD
|
||||
|
||||
## 通过 SSH 控制宿主机
|
||||
|
||||
| 变量 | 描述 |
|
||||
|---|---|
|
||||
| `NGINX_UI_NGINX_HOST_MODE` | 设置为 `ssh` 以启用宿主机 SSH 控制 |
|
||||
| `NGINX_UI_NGINX_HOST_ADDRESS` | 远程 `host:port`，例如 `host.docker.internal:22` |
|
||||
| `NGINX_UI_NGINX_HOST_USER` | 宿主机上的 SSH 用户 |
|
||||
| `NGINX_UI_NGINX_HOST_PRIVATE_KEY_PATH` | 容器内的私钥路径 |
|
||||
| `NGINX_UI_NGINX_HOST_KNOWN_HOSTS_PATH` | 容器内的 known_hosts 路径 |
|
||||
| `NGINX_UI_NGINX_HOST_SUDO_PREFIX` | 默认为 `sudo -n` |
|
||||
| `NGINX_UI_NGINX_HOST_SYSTEMD_UNIT_NAME` | 默认为 `nginx.service` |
|
||||
| `NGINX_UI_NGINX_HOST_SYSTEMCTL_PATH` | 宿主机上 systemctl 的绝对路径 |
|
||||
| `NGINX_UI_NGINX_HOST_CONFIG_DIR` | 宿主机侧的 nginx 配置目录 |
|
||||
| `NGINX_UI_NGINX_HOST_LOG_DIR` | 宿主机侧的 nginx 日志目录 |
|
||||
| `NGINX_UI_DISABLE_BUNDLED_NGINX` | 设置为 `true` 以禁用容器内置的 nginx（SSH 模式下必需） |
|
||||
|
||||
@@ -166,3 +166,39 @@ services:
|
||||
|
||||
例如：`-v /var/run/docker.sock:/var/run/docker.sock`
|
||||
:::
|
||||
|
||||
## 透過 SSH 控制宿主機 Nginx
|
||||
|
||||
對於 Nginx UI 執行在 Docker 容器中、而 Nginx 以原生方式安裝在宿主機上的部署場景（例如透過 apt/yum 安裝並由 systemd 管理），Nginx UI 提供了第三種控制模式，透過 SSH 執行命令並使用綁定掛載進行檔案 I/O。
|
||||
|
||||
### 限制
|
||||
|
||||
- **僅限同一宿主機**：Nginx UI 容器與目標 nginx 程序必須在同一台實體機或虛擬機上。如需多主機管理，請參閱 [叢集節點跨主機指南](cluster-node-cross-host.md)。
|
||||
- 宿主機上**需要 systemd**。此模式透過呼叫 `systemctl reload|restart <unit>` 來控制服務。
|
||||
- 宿主機的 nginx 使用者必須允許一個專用的非特權使用者（通常為 `nginxui`）透過 `sudo -n` 無密碼執行一組受限命令。
|
||||
|
||||
### 快速開始
|
||||
|
||||
1. 在 Web 介面中，前往**偏好設定 → Nginx**，選擇**透過 SSH 控制宿主機**模式，並開啟設定精靈。
|
||||
2. 按照四步設定精靈操作：產生金鑰對、將產生的 docker-compose 片段貼到您的 stack 中、在宿主機上套用 sudoers/authorized_keys 片段，然後執行驗證。
|
||||
3. 所有檢查通過後，儲存設定。
|
||||
|
||||
也可以使用命令列：
|
||||
|
||||
```bash
|
||||
nginx-ui host-setup print --host-address host.docker.internal:22 --host-user nginxui
|
||||
nginx-ui host-setup test
|
||||
```
|
||||
|
||||
### 設定欄位
|
||||
|
||||
| 欄位 | 描述 |
|
||||
|---|---|
|
||||
| `host_mode` | 設定為 `ssh` 以啟用此模式 |
|
||||
| `host_address` | 遠端 `host:port` |
|
||||
| `host_user` | 宿主機上的 SSH 使用者 |
|
||||
| `host_private_key_path` | 容器內的私鑰路徑 |
|
||||
| `host_systemd_unit_name` | 預設為 `nginx.service` |
|
||||
| `host_systemctl_path` | 預設為 `/bin/systemctl` |
|
||||
|
||||
另請參閱：[Host SSH 設定指引](host-via-ssh-setup.md)。
|
||||
|
||||
@@ -155,3 +155,19 @@
|
||||
|
||||
- NGINX_UI_PREDEFINED_USER_NAME
|
||||
- NGINX_UI_PREDEFINED_USER_PASSWORD
|
||||
|
||||
## 透過 SSH 控制宿主機
|
||||
|
||||
| 變數 | 描述 |
|
||||
|---|---|
|
||||
| `NGINX_UI_NGINX_HOST_MODE` | 設定為 `ssh` 以啟用宿主機 SSH 控制 |
|
||||
| `NGINX_UI_NGINX_HOST_ADDRESS` | 遠端 `host:port`，例如 `host.docker.internal:22` |
|
||||
| `NGINX_UI_NGINX_HOST_USER` | 宿主機上的 SSH 使用者 |
|
||||
| `NGINX_UI_NGINX_HOST_PRIVATE_KEY_PATH` | 容器內的私鑰路徑 |
|
||||
| `NGINX_UI_NGINX_HOST_KNOWN_HOSTS_PATH` | 容器內的 known_hosts 路徑 |
|
||||
| `NGINX_UI_NGINX_HOST_SUDO_PREFIX` | 預設為 `sudo -n` |
|
||||
| `NGINX_UI_NGINX_HOST_SYSTEMD_UNIT_NAME` | 預設為 `nginx.service` |
|
||||
| `NGINX_UI_NGINX_HOST_SYSTEMCTL_PATH` | 宿主機上 systemctl 的絕對路徑 |
|
||||
| `NGINX_UI_NGINX_HOST_CONFIG_DIR` | 宿主機側的 nginx 設定目錄 |
|
||||
| `NGINX_UI_NGINX_HOST_LOG_DIR` | 宿主機側的 nginx 日誌目錄 |
|
||||
| `NGINX_UI_DISABLE_BUNDLED_NGINX` | 設定為 `true` 以停用容器內建的 nginx（SSH 模式下必需） |
|
||||
|
||||
Reference in New Issue
Block a user