mirror of
https://github.com/0xJacky/nginx-ui.git
synced 2026-06-19 07:36:59 +00:00
docs: improve host nginx deployment guides
This commit is contained in:
Hintay
@@ -23,6 +23,14 @@ export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
|
||||
{ text: 'Install Script', link: '/guide/install-script-linux' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Deployment',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{ text: 'Manage Host Nginx from Docker', link: '/guide/manage-host-nginx-from-docker' },
|
||||
{ text: 'Manage Multi-Host Nginx with Cluster', link: '/guide/manage-multi-host-nginx-with-cluster' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Development',
|
||||
collapsed: false,
|
||||
|
||||
@@ -28,6 +28,14 @@ export const zhCNConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
|
||||
{ text: '安装脚本', link: '/zh_CN/guide/install-script-linux' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: '部署指南',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{ text: '在 Docker 中管理宿主机 Nginx', link: '/zh_CN/guide/manage-host-nginx-from-docker' },
|
||||
{ text: '使用集群节点管理多主机 Nginx', link: '/zh_CN/guide/manage-multi-host-nginx-with-cluster' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: '开发',
|
||||
collapsed: false,
|
||||
|
||||
@@ -28,6 +28,14 @@ export const zhTWConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
|
||||
{ text: '安裝指令碼', link: '/zh_TW/guide/install-script-linux' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: '部署指南',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{ text: '在 Docker 中管理宿主機 Nginx', link: '/zh_TW/guide/manage-host-nginx-from-docker' },
|
||||
{ text: '使用叢集節點管理多主機 Nginx', link: '/zh_TW/guide/manage-multi-host-nginx-with-cluster' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: '開發',
|
||||
collapsed: false,
|
||||
|
||||
@@ -1,69 +0,0 @@
|
||||
# Cluster Node — Cross-Host Setup
|
||||
|
||||
When you want to manage nginx on multiple hosts from a single Nginx UI dashboard, the right tool is the **cluster Node** feature, not the host SSH mode.
|
||||
|
||||
## When to use what
|
||||
|
||||
| Need | host_via_ssh | cluster Node |
|
||||
|---|---|---|
|
||||
| Container on host A managing nginx on host A | ✓ | ✓ (overkill) |
|
||||
| Container on host A managing nginx on host B | ✗ | ✓ |
|
||||
| One Web UI viewing configs/logs across hosts | — | ✓ |
|
||||
| Per-host autonomy if peer unreachable | — | ✓ |
|
||||
|
||||
## Recommended topology
|
||||
|
||||
```
|
||||
┌──────────────┐
|
||||
│ Your browser │
|
||||
└──────┬───────┘
|
||||
│
|
||||
┌───────▼────────┐
|
||||
│ Host A │
|
||||
│ nginx-ui (lead)│
|
||||
│ └─► host_via_ssh ─► host A nginx (optional)
|
||||
└───────┬─────────┘
|
||||
│ cluster federation
|
||||
┌──────────────┼──────────────┐
|
||||
▼ ▼ ▼
|
||||
Host B Host C Host D
|
||||
nginx-ui nginx-ui nginx-ui
|
||||
└─► nginx └─► nginx └─► nginx
|
||||
```
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Install nginx-ui on every host
|
||||
|
||||
Use the official installer or the Docker image — same instance type as the lead.
|
||||
|
||||
### 2. Generate a Node Secret on each peer
|
||||
|
||||
Log into the peer's Web UI, go to **Settings → Node**, copy the **Node Secret**.
|
||||
|
||||
### 3. Register peers on the lead node
|
||||
|
||||
Edit the lead's `app.ini`:
|
||||
|
||||
```ini
|
||||
[cluster]
|
||||
Node = http://10.0.0.2:9000?name=host-b&node_secret=<host-b-secret>&enabled=true
|
||||
Node = http://10.0.0.3:9000?name=host-c&node_secret=<host-c-secret>&enabled=true
|
||||
```
|
||||
|
||||
Or via environment variables (Docker):
|
||||
|
||||
```yaml
|
||||
services:
|
||||
nginx-ui:
|
||||
environment:
|
||||
- NGINX_UI_CLUSTER_NODE_0=http://10.0.0.2:9000?name=host-b&node_secret=...&enabled=true
|
||||
```
|
||||
|
||||
### 4. Switch nodes from the Web UI
|
||||
|
||||
The node switcher in the top bar routes all subsequent operations to the selected node. Each operation happens **locally on that node** — no SSH involved between hosts.
|
||||
|
||||
## Combining cluster + host_via_ssh
|
||||
|
||||
You can have each cluster peer run host_via_ssh internally — the container manages its own host's nginx, while cluster federation handles cross-host coordination. This is the cleanest topology for "Docker-only" deployments with native nginx on multiple hosts.
|
||||
@@ -179,9 +179,11 @@ For deployments where Nginx UI runs in a Docker container but Nginx is installed
|
||||
|
||||
### 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).
|
||||
::: warning 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 [Manage Multi-Host Nginx with Cluster](manage-multi-host-nginx-with-cluster.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
|
||||
|
||||
@@ -203,8 +205,14 @@ nginx-ui host-setup test
|
||||
| `host_mode` | Set to `ssh` to enable this mode |
|
||||
| `host_address` | Remote `host:port` |
|
||||
| `host_user` | SSH user on the host |
|
||||
| `host_auth_method` | SSH authentication method. Use key authentication for the current host SSH setup |
|
||||
| `host_private_key_path` | Private key path inside the container |
|
||||
| `host_known_hosts_path` | known_hosts path inside the container |
|
||||
| `host_strict_host_key` | Enables strict host key checking. Enabled by default unless explicitly set to `false` |
|
||||
| `host_sudo_prefix` | Prefix used for privileged commands. Default `sudo -n` |
|
||||
| `host_systemd_unit_name` | Default `nginx.service` |
|
||||
| `host_systemctl_path` | Default `/bin/systemctl` |
|
||||
| `host_config_dir` | Host-side nginx config directory |
|
||||
| `host_log_dir` | Host-side nginx log directory |
|
||||
|
||||
See also: [Host SSH setup walkthrough](host-via-ssh-setup.md).
|
||||
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).
|
||||
|
||||
@@ -144,13 +144,19 @@ In skip installation mode, you can set the following environment variables to cr
|
||||
|
||||
## Host SSH Control
|
||||
|
||||
::: info
|
||||
These variables are used when Nginx UI controls a host-installed nginx service from a Docker container via SSH.
|
||||
:::
|
||||
|
||||
| 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_AUTH_METHOD` | SSH authentication method. Use key authentication for the current host SSH setup |
|
||||
| `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_STRICT_HOST_KEY` | Set to `false` only if you need to disable strict host key checking |
|
||||
| `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 |
|
||||
|
||||
@@ -1,94 +0,0 @@
|
||||
# Host SSH Setup — Walkthrough
|
||||
|
||||
This page walks through configuring Nginx UI (running in Docker) to manage an nginx instance installed natively on the same host.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Linux host with nginx installed and running under systemd
|
||||
- Docker installed on the same host
|
||||
- An unprivileged user dedicated to Nginx UI (we use `nginxui` in examples)
|
||||
|
||||
## Step 1 — Create the unprivileged user
|
||||
|
||||
```bash
|
||||
sudo useradd -r -s /bin/bash -m -G adm nginxui
|
||||
```
|
||||
|
||||
`-G adm` grants the user read access to /var/log files including nginx logs.
|
||||
|
||||
## Step 2 — Generate the keypair via Nginx UI
|
||||
|
||||
Open **Preferences → Nginx → Host via SSH → Open setup wizard**. Click **Generate keypair** in Step 1.
|
||||
|
||||
Copy the public key shown. It looks like:
|
||||
|
||||
```
|
||||
ssh-ed25519 AAAAC3...generated nginx-ui@generated
|
||||
```
|
||||
|
||||
Append it to the host user's authorized_keys:
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /home/nginxui/.ssh
|
||||
echo 'ssh-ed25519 AAAA...' | sudo tee -a /home/nginxui/.ssh/authorized_keys
|
||||
sudo chown -R nginxui:nginxui /home/nginxui/.ssh
|
||||
sudo chmod 700 /home/nginxui/.ssh
|
||||
sudo chmod 600 /home/nginxui/.ssh/authorized_keys
|
||||
```
|
||||
|
||||
## Step 3 — Install sudoers entry
|
||||
|
||||
The wizard Step 2b shows you 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.
|
||||
|
||||
## Step 4 — Apply ACLs (optional, for non-root user)
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## Step 5 — Update your docker-compose
|
||||
|
||||
The wizard Step 2a shows a compose snippet. Merge it into your existing `docker-compose.yml`. Then:
|
||||
|
||||
```bash
|
||||
docker compose up -d --force-recreate nginx-ui
|
||||
```
|
||||
|
||||
## Step 6 — Verify
|
||||
|
||||
Back in the wizard Step 4, click **Run verification**. Every check should pass:
|
||||
|
||||
- ✓ same_host: machine-id matched
|
||||
- ✓ ssh_connect: echo ok over ssh
|
||||
- ✓ sudo_available: sudo -n true succeeded
|
||||
- ✓ sudoers_coverage: all required entries present
|
||||
- ✓ systemctl_is_active: active
|
||||
- ✓ unit_has_execreload: ExecReload is declared
|
||||
- ✓ nginx_test: configuration file ok
|
||||
- ✓ config_dir_writable: /etc/nginx accessible
|
||||
- ✓ log_dir_readable: /var/log/nginx/access.log readable
|
||||
- ✓ pid_file_present: /var/run/nginx.pid present
|
||||
|
||||
Click **Save** and you're done.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**`sudo_available` fails with "sudo: a password is required"**
|
||||
- Check your sudoers file has `NOPASSWD:` not just `(root)`.
|
||||
- Check the file has correct line continuations (`\` at line endings).
|
||||
|
||||
**`ssh_connect` fails with "permission denied (publickey)"**
|
||||
- Verify authorized_keys has the right line, owner, and permissions.
|
||||
- Check sshd_config allows `PubkeyAuthentication yes`.
|
||||
|
||||
**`same_host` warns "remote host detected"**
|
||||
- Your `host_address` resolves to a different machine. SSH mode does NOT work cross-host; see [Cluster Node cross-host guide](cluster-node-cross-host.md).
|
||||
@@ -0,0 +1,143 @@
|
||||
# Manage Host Nginx from Docker
|
||||
|
||||
Use this guide when Nginx UI runs in Docker and needs to manage an nginx instance installed directly on the same host.
|
||||
|
||||
::: info Prerequisites
|
||||
- Linux host with nginx installed and running under systemd
|
||||
- Docker installed on the same host
|
||||
- An unprivileged user dedicated to Nginx UI (we use `nginxui` in examples)
|
||||
:::
|
||||
|
||||
## Step 1: Create the unprivileged user
|
||||
|
||||
```bash
|
||||
sudo useradd -r -s /bin/bash -m -G adm nginxui
|
||||
```
|
||||
|
||||
`-G adm` grants the user read access to /var/log files including nginx logs.
|
||||
|
||||
## Step 2: Generate the keypair via Nginx UI
|
||||
|
||||
Open **Preferences → Nginx → Host via SSH → Open setup wizard**. Click **Generate keypair** in Step 1.
|
||||
|
||||
Copy the public key shown. It looks like:
|
||||
|
||||
```
|
||||
ssh-ed25519 AAAAC3...generated nginx-ui@generated
|
||||
```
|
||||
|
||||
Append it to the host user's authorized_keys:
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /home/nginxui/.ssh
|
||||
echo 'ssh-ed25519 AAAA...' | sudo tee -a /home/nginxui/.ssh/authorized_keys
|
||||
sudo chown -R nginxui:nginxui /home/nginxui/.ssh
|
||||
sudo chmod 700 /home/nginxui/.ssh
|
||||
sudo chmod 600 /home/nginxui/.ssh/authorized_keys
|
||||
```
|
||||
|
||||
::: warning Host key verification
|
||||
Strict host key checking is enabled by default. If the wizard shows a new host fingerprint, verify it before trusting the key. Only set `NGINX_UI_NGINX_HOST_STRICT_HOST_KEY=false` in a controlled test environment.
|
||||
:::
|
||||
|
||||
## Step 3: Install the sudoers entry
|
||||
|
||||
The wizard Step 2b shows you 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.
|
||||
|
||||
## Step 4: Apply ACLs for a non-root user
|
||||
|
||||
::: 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
|
||||
```
|
||||
:::
|
||||
|
||||
## Step 5: Update docker-compose
|
||||
|
||||
The wizard Step 2a shows a compose snippet. Merge it into your existing `docker-compose.yml`. Then:
|
||||
|
||||
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.
|
||||
|
||||
```bash
|
||||
docker compose up -d --force-recreate nginx-ui
|
||||
```
|
||||
|
||||
## Step 6: Verify the setup
|
||||
|
||||
Back in the wizard Step 4, click **Run verification**. Every check should pass:
|
||||
|
||||
::: tip Expected verification result
|
||||
|
||||
- ✓ same_host: machine-id matched
|
||||
- ✓ ssh_connect: echo ok over ssh
|
||||
- ✓ sudo_available: sudo -n true succeeded
|
||||
- ✓ sudoers_coverage: all required entries present
|
||||
- ✓ systemctl_is_active: active
|
||||
- ✓ unit_has_execreload: ExecReload is declared
|
||||
- ✓ nginx_test: configuration file ok
|
||||
- ✓ config_dir_writable: /etc/nginx accessible
|
||||
- ✓ log_dir_readable: /var/log/nginx/access.log readable
|
||||
- ✓ pid_file_present: /var/run/nginx.pid present
|
||||
|
||||
:::
|
||||
|
||||
Click **Save** after the checks pass.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
::: details `sudo_available` fails with "sudo: a password is required"
|
||||
- Check your sudoers file has `NOPASSWD:` not just `(root)`.
|
||||
- Check the file has correct line continuations (`\` at line endings).
|
||||
:::
|
||||
|
||||
::: details `ssh_connect` fails with "permission denied (publickey)"
|
||||
- Verify authorized_keys has the right line, owner, and permissions.
|
||||
- Check sshd_config allows `PubkeyAuthentication yes`.
|
||||
:::
|
||||
|
||||
::: warning `same_host` warns "remote host detected"
|
||||
Your `host_address` resolves to a different machine. SSH mode does **not** work cross-host; see [Manage Multi-Host Nginx with Cluster](manage-multi-host-nginx-with-cluster.md).
|
||||
:::
|
||||
|
||||
## CLI reference
|
||||
|
||||
Generate a keypair for host SSH:
|
||||
|
||||
```bash
|
||||
nginx-ui host-setup keygen --out /etc/nginx-ui/host_key
|
||||
```
|
||||
|
||||
Print all setup snippets:
|
||||
|
||||
```bash
|
||||
nginx-ui host-setup print --host-address host.docker.internal:22 --host-user nginxui
|
||||
```
|
||||
|
||||
Print only Docker or host-side snippets:
|
||||
|
||||
```bash
|
||||
nginx-ui host-setup print --host-address host.docker.internal:22 --host-user nginxui --compose
|
||||
nginx-ui host-setup print --host-address host.docker.internal:22 --host-user nginxui --host
|
||||
```
|
||||
|
||||
Use `--json`, `--override`, or `--docker-run` when you need machine-readable output, a full compose override, or a docker run command.
|
||||
|
||||
Run verification against the current settings:
|
||||
|
||||
```bash
|
||||
nginx-ui host-setup test
|
||||
```
|
||||
|
||||
## Related docs
|
||||
|
||||
- [Nginx configuration reference](config-nginx.md#host-ssh-control)
|
||||
- [Manage Multi-Host Nginx with Cluster](manage-multi-host-nginx-with-cluster.md)
|
||||
@@ -0,0 +1,75 @@
|
||||
# Manage Multi-Host Nginx with Cluster
|
||||
|
||||
::: tip Recommended approach
|
||||
When you want to manage nginx on multiple hosts from a single Nginx UI dashboard, use the **cluster Node** feature instead of host SSH mode.
|
||||
:::
|
||||
|
||||
## When to use what
|
||||
|
||||
| Need | host_via_ssh | cluster Node |
|
||||
|---|---|---|
|
||||
| Container on host A managing nginx on host A | ✓ | ✓ (overkill) |
|
||||
| Container on host A managing nginx on host B | ✗ | ✓ |
|
||||
| One Web UI viewing configs/logs across hosts | No | ✓ |
|
||||
| Per-host autonomy if peer unreachable | No | ✓ |
|
||||
|
||||
## Recommended topology
|
||||
|
||||
| Layer | Role | Notes |
|
||||
|---|---|---|
|
||||
| Browser | Opens the lead Nginx UI instance | Use one dashboard for daily operation |
|
||||
| Lead node | Registers peer nodes and provides the node switcher | Can also manage its own local nginx |
|
||||
| Peer nodes | Run their own Nginx UI instance | Each peer manages nginx on the same host |
|
||||
| Cluster federation | Connects the lead node to peers | Requests run on the selected node |
|
||||
|
||||
The lead node does not SSH into other hosts. It forwards operations through the cluster node connection. If a node runs Nginx UI in Docker and manages nginx installed on the same host, configure [Manage Host Nginx from Docker](manage-host-nginx-from-docker.md) on that node only.
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Install nginx-ui on every host
|
||||
|
||||
Use the same deployment type on every node when possible. For a native Linux installation, run:
|
||||
|
||||
```bash
|
||||
bash -c "$(curl -L https://cloud.nginxui.com/install.sh)" @ install
|
||||
```
|
||||
|
||||
Docker deployments are also supported. See [Install Script](install-script-linux.md) and [Getting Started](getting-started.md#docker) for the available installation methods.
|
||||
|
||||
### 2. Generate a Node Secret on each peer
|
||||
|
||||
Log into the peer's Web UI, go to **Settings → Node**, copy the **Node Secret**.
|
||||
|
||||
### 3. Register peers on the lead node
|
||||
|
||||
Configure peer nodes from `app.ini` or Docker environment variables:
|
||||
|
||||
::: code-group
|
||||
|
||||
```ini [app.ini]
|
||||
[cluster]
|
||||
Node = http://10.0.0.2:9000?name=host-b&node_secret=<host-b-secret>&enabled=true
|
||||
Node = http://10.0.0.3:9000?name=host-c&node_secret=<host-c-secret>&enabled=true
|
||||
```
|
||||
|
||||
```yaml [docker-compose.yml]
|
||||
services:
|
||||
nginx-ui:
|
||||
environment:
|
||||
- NGINX_UI_CLUSTER_NODE_0=http://10.0.0.2:9000?name=host-b&node_secret=...&enabled=true
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### 4. Switch nodes from the Web UI
|
||||
|
||||
The node switcher in the top bar routes all subsequent operations to the selected node. Each operation happens **locally on that node**. There is no SSH connection between hosts.
|
||||
|
||||
## Combining cluster + host_via_ssh
|
||||
|
||||
You can have each cluster peer run host_via_ssh internally. In that layout, the container manages nginx on its own host, and cluster federation handles cross-host coordination.
|
||||
|
||||
See also:
|
||||
|
||||
- [Cluster configuration reference](config-cluster.md)
|
||||
- [Manage Host Nginx from Docker](manage-host-nginx-from-docker.md)
|
||||
@@ -1,69 +0,0 @@
|
||||
# 集群节点 — 跨主机配置
|
||||
|
||||
当您希望通过单个 Nginx UI 控制面板管理多台主机上的 nginx 时，正确的工具是**集群节点**功能，而非宿主机 SSH 模式。
|
||||
|
||||
## 如何选择
|
||||
|
||||
| 需求 | host_via_ssh | 集群节点 |
|
||||
|---|---|---|
|
||||
| 主机 A 上的容器管理主机 A 上的 nginx | ✓ | ✓（过于复杂） |
|
||||
| 主机 A 上的容器管理主机 B 上的 nginx | ✗ | ✓ |
|
||||
| 通过单个 Web 界面查看多台主机的配置/日志 | — | ✓ |
|
||||
| 对等节点不可达时各主机保持自主运行 | — | ✓ |
|
||||
|
||||
## 推荐拓扑
|
||||
|
||||
```
|
||||
┌──────────────┐
|
||||
│ Your browser │
|
||||
└──────┬───────┘
|
||||
│
|
||||
┌───────▼────────┐
|
||||
│ Host A │
|
||||
│ nginx-ui (lead)│
|
||||
│ └─► host_via_ssh ─► host A nginx (optional)
|
||||
└───────┬─────────┘
|
||||
│ cluster federation
|
||||
┌──────────────┼──────────────┐
|
||||
▼ ▼ ▼
|
||||
Host B Host C Host D
|
||||
nginx-ui nginx-ui nginx-ui
|
||||
└─► nginx └─► nginx └─► nginx
|
||||
```
|
||||
|
||||
## 配置步骤
|
||||
|
||||
### 1. 在每台主机上安装 nginx-ui
|
||||
|
||||
使用官方安装脚本或 Docker 镜像——与主节点保持相同的实例类型。
|
||||
|
||||
### 2. 在每个对等节点上生成 Node Secret
|
||||
|
||||
登录对等节点的 Web 界面，进入**设置 → 节点**，复制 **Node Secret**。
|
||||
|
||||
### 3. 在主节点上注册对等节点
|
||||
|
||||
编辑主节点的 `app.ini`：
|
||||
|
||||
```ini
|
||||
[cluster]
|
||||
Node = http://10.0.0.2:9000?name=host-b&node_secret=<host-b-secret>&enabled=true
|
||||
Node = http://10.0.0.3:9000?name=host-c&node_secret=<host-c-secret>&enabled=true
|
||||
```
|
||||
|
||||
或通过环境变量配置（Docker 方式）：
|
||||
|
||||
```yaml
|
||||
services:
|
||||
nginx-ui:
|
||||
environment:
|
||||
- NGINX_UI_CLUSTER_NODE_0=http://10.0.0.2:9000?name=host-b&node_secret=...&enabled=true
|
||||
```
|
||||
|
||||
### 4. 在 Web 界面中切换节点
|
||||
|
||||
顶栏的节点切换器会将后续所有操作路由到所选节点。每个操作都**在该节点本地执行**——主机间无需 SSH 通信。
|
||||
|
||||
## 集群与 host_via_ssh 组合使用
|
||||
|
||||
您可以让每个集群对等节点在内部运行 host_via_ssh——容器管理本机上的 nginx，同时由集群联邦处理跨主机协调。对于在多台主机上使用原生 nginx 的"纯 Docker"部署场景，这是最简洁的拓扑架构。
|
||||
@@ -180,9 +180,11 @@ services:
|
||||
|
||||
### 限制
|
||||
|
||||
- **仅限同一宿主机**：Nginx UI 容器与目标 nginx 进程必须在同一台物理机或虚拟机上。如需多主机管理，请参阅 [集群节点跨主机指南](cluster-node-cross-host.md)。
|
||||
::: warning 限制
|
||||
- **仅限同一宿主机**：Nginx UI 容器与目标 nginx 进程必须在同一台物理机或虚拟机上。如需多主机管理，请参阅 [使用集群节点管理多主机 Nginx](manage-multi-host-nginx-with-cluster.md)。
|
||||
- 宿主机上**需要 systemd**。该模式通过调用 `systemctl reload|restart <unit>` 来控制服务。
|
||||
- 宿主机的 nginx 用户必须允许一个专用的非特权用户（通常为 `nginxui`）通过 `sudo -n` 无密码执行一组受限命令。
|
||||
:::
|
||||
|
||||
### 快速开始
|
||||
|
||||
@@ -204,8 +206,14 @@ nginx-ui host-setup test
|
||||
| `host_mode` | 设置为 `ssh` 以启用此模式 |
|
||||
| `host_address` | 远程 `host:port` |
|
||||
| `host_user` | 宿主机上的 SSH 用户 |
|
||||
| `host_auth_method` | SSH 认证方式。当前宿主机 SSH 配置请使用密钥认证 |
|
||||
| `host_private_key_path` | 容器内的私钥路径 |
|
||||
| `host_known_hosts_path` | 容器内的 known_hosts 路径 |
|
||||
| `host_strict_host_key` | 启用严格主机密钥检查。默认启用，除非明确设置为 `false` |
|
||||
| `host_sudo_prefix` | 特权命令前缀。默认值为 `sudo -n` |
|
||||
| `host_systemd_unit_name` | 默认为 `nginx.service` |
|
||||
| `host_systemctl_path` | 默认为 `/bin/systemctl` |
|
||||
| `host_config_dir` | 宿主机侧 nginx 配置目录 |
|
||||
| `host_log_dir` | 宿主机侧 nginx 日志目录 |
|
||||
|
||||
另请参阅：[Host SSH 设置指引](host-via-ssh-setup.md)。
|
||||
另请参阅：[在 Docker 中管理宿主机 Nginx](manage-host-nginx-from-docker.md) 和 [使用集群节点管理多主机 Nginx](manage-multi-host-nginx-with-cluster.md)。
|
||||
|
||||
@@ -158,13 +158,19 @@
|
||||
|
||||
## 通过 SSH 控制宿主机
|
||||
|
||||
::: info
|
||||
这些变量用于 Nginx UI 在 Docker 容器中通过 SSH 控制宿主机上原生安装的 nginx 服务。
|
||||
:::
|
||||
|
||||
| 变量 | 描述 |
|
||||
|---|---|
|
||||
| `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_AUTH_METHOD` | SSH 认证方式。当前宿主机 SSH 配置请使用密钥认证 |
|
||||
| `NGINX_UI_NGINX_HOST_PRIVATE_KEY_PATH` | 容器内的私钥路径 |
|
||||
| `NGINX_UI_NGINX_HOST_KNOWN_HOSTS_PATH` | 容器内的 known_hosts 路径 |
|
||||
| `NGINX_UI_NGINX_HOST_STRICT_HOST_KEY` | 仅在需要关闭严格主机密钥检查时设置为 `false` |
|
||||
| `NGINX_UI_NGINX_HOST_SUDO_PREFIX` | 默认为 `sudo -n` |
|
||||
| `NGINX_UI_NGINX_HOST_SYSTEMD_UNIT_NAME` | 默认为 `nginx.service` |
|
||||
| `NGINX_UI_NGINX_HOST_SYSTEMCTL_PATH` | 宿主机上 systemctl 的绝对路径 |
|
||||
|
||||
+64
-15
@@ -1,14 +1,14 @@
|
||||
# 宿主机 SSH 配置 — 完整指南
|
||||
# 在 Docker 中管理宿主机 Nginx
|
||||
|
||||
本页介绍如何配置以 Docker 方式运行的 Nginx UI，使其管理安装在同一宿主机上的 nginx 原生实例。
|
||||
|
||||
## 前置条件
|
||||
当 Nginx UI 运行在 Docker 中，并需要管理同一宿主机上原生安装的 nginx 时，可按本文完成配置。
|
||||
|
||||
::: info 前置条件
|
||||
- 已安装 nginx 并通过 systemd 运行的 Linux 宿主机
|
||||
- 同一宿主机上已安装 Docker
|
||||
- 一个专用于 Nginx UI 的非特权用户（示例中使用 `nginxui`）
|
||||
:::
|
||||
|
||||
## 步骤 1 — 创建非特权用户
|
||||
## 步骤 1：创建非特权用户
|
||||
|
||||
```bash
|
||||
sudo useradd -r -s /bin/bash -m -G adm nginxui
|
||||
@@ -16,7 +16,7 @@ sudo useradd -r -s /bin/bash -m -G adm nginxui
|
||||
|
||||
`-G adm` 赋予该用户读取 /var/log 文件（包括 nginx 日志）的权限。
|
||||
|
||||
## 步骤 2 — 通过 Nginx UI 生成密钥对
|
||||
## 步骤 2：通过 Nginx UI 生成密钥对
|
||||
|
||||
打开**偏好设置 → Nginx → 通过 SSH 管理宿主机 → 打开配置向导**。在步骤 1 中点击**生成密钥对**。
|
||||
|
||||
@@ -36,7 +36,11 @@ sudo chmod 700 /home/nginxui/.ssh
|
||||
sudo chmod 600 /home/nginxui/.ssh/authorized_keys
|
||||
```
|
||||
|
||||
## 步骤 3 — 安装 sudoers 条目
|
||||
::: warning 主机密钥验证
|
||||
默认启用严格主机密钥检查。如果配置向导显示新的主机指纹，请先确认指纹再信任该密钥。只有在受控测试环境中，才建议设置 `NGINX_UI_NGINX_HOST_STRICT_HOST_KEY=false`。
|
||||
:::
|
||||
|
||||
## 步骤 3：安装 sudoers 条目
|
||||
|
||||
向导步骤 2b 会显示一段 sudoers 配置片段。复制后通过以下命令安装：
|
||||
|
||||
@@ -46,27 +50,33 @@ sudo visudo -f /etc/sudoers.d/nginx-ui
|
||||
|
||||
粘贴配置片段后保存并退出。如果语法有误，visudo 会拒绝保存该文件。
|
||||
|
||||
## 步骤 4 — 应用 ACL（可选，适用于非 root 用户）
|
||||
## 步骤 4：为非 root 用户应用 ACL
|
||||
|
||||
::: 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
|
||||
```
|
||||
:::
|
||||
|
||||
## 步骤 5 — 更新 docker-compose 配置
|
||||
## 步骤 5：更新 docker-compose 配置
|
||||
|
||||
向导步骤 2a 会显示一段 compose 配置片段。将其合并到现有的 `docker-compose.yml` 中，然后执行：
|
||||
|
||||
生成的片段会设置 `NGINX_UI_DISABLE_BUNDLED_NGINX=true`，避免容器在控制宿主机 nginx 时继续启动内置 nginx 服务。
|
||||
|
||||
```bash
|
||||
docker compose up -d --force-recreate nginx-ui
|
||||
```
|
||||
|
||||
## 步骤 6 — 验证
|
||||
## 步骤 6：验证配置
|
||||
|
||||
返回向导步骤 4，点击**运行验证**。所有检查项应全部通过：
|
||||
|
||||
::: tip 预期验证结果
|
||||
|
||||
- ✓ same_host: machine-id 匹配
|
||||
- ✓ ssh_connect: 通过 SSH 执行 echo ok 成功
|
||||
- ✓ sudo_available: sudo -n true 执行成功
|
||||
@@ -78,17 +88,56 @@ docker compose up -d --force-recreate nginx-ui
|
||||
- ✓ log_dir_readable: /var/log/nginx/access.log 可读
|
||||
- ✓ pid_file_present: /var/run/nginx.pid 存在
|
||||
|
||||
点击**保存**，配置完成。
|
||||
:::
|
||||
|
||||
所有检查通过后，点击**保存**。
|
||||
|
||||
## 故障排查
|
||||
|
||||
**`sudo_available` 报错 "sudo: a password is required"**
|
||||
::: details `sudo_available` 报错 "sudo: a password is required"
|
||||
- 检查 sudoers 文件中是否包含 `NOPASSWD:`，而不仅仅是 `(root)`。
|
||||
- 检查文件中行末续行符（`\`）是否正确。
|
||||
:::
|
||||
|
||||
**`ssh_connect` 报错 "permission denied (publickey)"**
|
||||
::: details `ssh_connect` 报错 "permission denied (publickey)"
|
||||
- 验证 authorized_keys 文件中的公钥内容、文件所有者及权限是否正确。
|
||||
- 检查 sshd_config 中是否启用了 `PubkeyAuthentication yes`。
|
||||
:::
|
||||
|
||||
**`same_host` 警告 "remote host detected"**
|
||||
- 您的 `host_address` 解析到了不同的机器。SSH 模式**不支持**跨主机使用；请参阅 [集群节点跨主机指南](cluster-node-cross-host.md)。
|
||||
::: warning `same_host` 警告 "remote host detected"
|
||||
您的 `host_address` 解析到了不同的机器。SSH 模式**不支持**跨主机使用；请参阅 [使用集群节点管理多主机 Nginx](manage-multi-host-nginx-with-cluster.md)。
|
||||
:::
|
||||
|
||||
## CLI 参考
|
||||
|
||||
生成宿主机 SSH 使用的密钥对：
|
||||
|
||||
```bash
|
||||
nginx-ui host-setup keygen --out /etc/nginx-ui/host_key
|
||||
```
|
||||
|
||||
输出全部配置片段：
|
||||
|
||||
```bash
|
||||
nginx-ui host-setup print --host-address host.docker.internal:22 --host-user nginxui
|
||||
```
|
||||
|
||||
只输出 Docker 或宿主机侧片段：
|
||||
|
||||
```bash
|
||||
nginx-ui host-setup print --host-address host.docker.internal:22 --host-user nginxui --compose
|
||||
nginx-ui host-setup print --host-address host.docker.internal:22 --host-user nginxui --host
|
||||
```
|
||||
|
||||
需要机器可读输出、完整 compose override 或 docker run 命令时，可以使用 `--json`、`--override` 或 `--docker-run`。
|
||||
|
||||
基于当前设置执行验证：
|
||||
|
||||
```bash
|
||||
nginx-ui host-setup test
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Nginx 配置参考](config-nginx.md#通过-ssh-控制宿主机-nginx)
|
||||
- [使用集群节点管理多主机 Nginx](manage-multi-host-nginx-with-cluster.md)
|
||||
@@ -0,0 +1,75 @@
|
||||
# 使用集群节点管理多主机 Nginx
|
||||
|
||||
::: tip 推荐方式
|
||||
当您希望通过单个 Nginx UI 控制面板管理多台主机上的 nginx 时，请使用**集群节点**功能，而不是宿主机 SSH 模式。
|
||||
:::
|
||||
|
||||
## 如何选择
|
||||
|
||||
| 需求 | host_via_ssh | 集群节点 |
|
||||
|---|---|---|
|
||||
| 主机 A 上的容器管理主机 A 上的 nginx | ✓ | ✓（过于复杂） |
|
||||
| 主机 A 上的容器管理主机 B 上的 nginx | ✗ | ✓ |
|
||||
| 通过单个 Web 界面查看多台主机的配置/日志 | 否 | ✓ |
|
||||
| 对等节点不可达时各主机保持自主运行 | 否 | ✓ |
|
||||
|
||||
## 推荐拓扑
|
||||
|
||||
| 层级 | 作用 | 说明 |
|
||||
|---|---|---|
|
||||
| 浏览器 | 打开主节点的 Nginx UI | 日常操作只需要进入一个控制台 |
|
||||
| 主节点 | 注册对等节点并提供节点切换器 | 也可以管理本机 nginx |
|
||||
| 对等节点 | 分别运行自己的 Nginx UI 实例 | 每个节点管理同一主机上的 nginx |
|
||||
| 集群联邦 | 连接主节点与对等节点 | 请求会在当前选中的节点上执行 |
|
||||
|
||||
主节点不会通过 SSH 连接到其他主机，而是通过集群节点连接转发操作。如果某个节点以 Docker 方式运行 Nginx UI，并管理同一宿主机上的 nginx，请只在该节点上配置 [在 Docker 中管理宿主机 Nginx](manage-host-nginx-from-docker.md)。
|
||||
|
||||
## 配置步骤
|
||||
|
||||
### 1. 在每台主机上安装 nginx-ui
|
||||
|
||||
建议每个节点尽量使用相同的部署方式。原生 Linux 安装可以执行：
|
||||
|
||||
```bash
|
||||
bash -c "$(curl -L https://cloud.nginxui.com/install.sh)" @ install -r https://cloud.nginxui.com/
|
||||
```
|
||||
|
||||
也可以使用 Docker 部署。可参考 [安装脚本](install-script-linux.md) 和 [快速开始](getting-started.md#docker) 了解可用的安装方式。
|
||||
|
||||
### 2. 在每个对等节点上生成 Node Secret
|
||||
|
||||
登录对等节点的 Web 界面，进入**设置 → 节点**，复制 **Node Secret**。
|
||||
|
||||
### 3. 在主节点上注册对等节点
|
||||
|
||||
可以通过 `app.ini` 或 Docker 环境变量配置对等节点：
|
||||
|
||||
::: code-group
|
||||
|
||||
```ini [app.ini]
|
||||
[cluster]
|
||||
Node = http://10.0.0.2:9000?name=host-b&node_secret=<host-b-secret>&enabled=true
|
||||
Node = http://10.0.0.3:9000?name=host-c&node_secret=<host-c-secret>&enabled=true
|
||||
```
|
||||
|
||||
```yaml [docker-compose.yml]
|
||||
services:
|
||||
nginx-ui:
|
||||
environment:
|
||||
- NGINX_UI_CLUSTER_NODE_0=http://10.0.0.2:9000?name=host-b&node_secret=...&enabled=true
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### 4. 在 Web 界面中切换节点
|
||||
|
||||
顶栏的节点切换器会将后续所有操作路由到所选节点。每个操作都**在该节点本地执行**。主机之间不需要 SSH 通信。
|
||||
|
||||
## 集群与 host_via_ssh 组合使用
|
||||
|
||||
您可以让每个集群对等节点在内部运行 host_via_ssh。在这种布局中，容器只管理本机 nginx，跨主机协调由集群联邦处理。
|
||||
|
||||
另请参阅：
|
||||
|
||||
- [Cluster 配置参考](config-cluster.md)
|
||||
- [在 Docker 中管理宿主机 Nginx](manage-host-nginx-from-docker.md)
|
||||
@@ -1,69 +0,0 @@
|
||||
# 叢集節點 — 跨主機設定
|
||||
|
||||
當您希望透過單一 Nginx UI 控制面板管理多台主機上的 nginx 時，正確的工具是**叢集節點**功能，而非宿主機 SSH 模式。
|
||||
|
||||
## 如何選擇
|
||||
|
||||
| 需求 | host_via_ssh | 叢集節點 |
|
||||
|---|---|---|
|
||||
| 主機 A 上的容器管理主機 A 上的 nginx | ✓ | ✓（過於複雜） |
|
||||
| 主機 A 上的容器管理主機 B 上的 nginx | ✗ | ✓ |
|
||||
| 透過單一 Web 介面檢視多台主機的設定/日誌 | — | ✓ |
|
||||
| 對等節點無法連線時各主機保持自主執行 | — | ✓ |
|
||||
|
||||
## 建議拓撲
|
||||
|
||||
```
|
||||
┌──────────────┐
|
||||
│ Your browser │
|
||||
└──────┬───────┘
|
||||
│
|
||||
┌───────▼────────┐
|
||||
│ Host A │
|
||||
│ nginx-ui (lead)│
|
||||
│ └─► host_via_ssh ─► host A nginx (optional)
|
||||
└───────┬─────────┘
|
||||
│ cluster federation
|
||||
┌──────────────┼──────────────┐
|
||||
▼ ▼ ▼
|
||||
Host B Host C Host D
|
||||
nginx-ui nginx-ui nginx-ui
|
||||
└─► nginx └─► nginx └─► nginx
|
||||
```
|
||||
|
||||
## 設定步驟
|
||||
|
||||
### 1. 在每台主機上安裝 nginx-ui
|
||||
|
||||
使用官方安裝腳本或 Docker 映像——與主節點保持相同的實例類型。
|
||||
|
||||
### 2. 在每個對等節點上產生 Node Secret
|
||||
|
||||
登入對等節點的 Web 介面，進入**設定 → 節點**，複製 **Node Secret**。
|
||||
|
||||
### 3. 在主節點上註冊對等節點
|
||||
|
||||
編輯主節點的 `app.ini`：
|
||||
|
||||
```ini
|
||||
[cluster]
|
||||
Node = http://10.0.0.2:9000?name=host-b&node_secret=<host-b-secret>&enabled=true
|
||||
Node = http://10.0.0.3:9000?name=host-c&node_secret=<host-c-secret>&enabled=true
|
||||
```
|
||||
|
||||
或透過環境變數設定（Docker 方式）：
|
||||
|
||||
```yaml
|
||||
services:
|
||||
nginx-ui:
|
||||
environment:
|
||||
- NGINX_UI_CLUSTER_NODE_0=http://10.0.0.2:9000?name=host-b&node_secret=...&enabled=true
|
||||
```
|
||||
|
||||
### 4. 在 Web 介面中切換節點
|
||||
|
||||
頂列的節點切換器會將後續所有操作路由到所選節點。每個操作都**在該節點本地執行**——主機間無需 SSH 通訊。
|
||||
|
||||
## 叢集與 host_via_ssh 組合使用
|
||||
|
||||
您可以讓每個叢集對等節點在內部執行 host_via_ssh——容器管理本機上的 nginx，同時由叢集聯邦處理跨主機協調。對於在多台主機上使用原生 nginx 的「純 Docker」部署場景，這是最簡潔的拓撲架構。
|
||||
@@ -173,9 +173,11 @@ services:
|
||||
|
||||
### 限制
|
||||
|
||||
- **僅限同一宿主機**：Nginx UI 容器與目標 nginx 程序必須在同一台實體機或虛擬機上。如需多主機管理，請參閱 [叢集節點跨主機指南](cluster-node-cross-host.md)。
|
||||
::: warning 限制
|
||||
- **僅限同一宿主機**：Nginx UI 容器與目標 nginx 程序必須在同一台實體機或虛擬機上。如需多主機管理，請參閱 [使用叢集節點管理多主機 Nginx](manage-multi-host-nginx-with-cluster.md)。
|
||||
- 宿主機上**需要 systemd**。此模式透過呼叫 `systemctl reload|restart <unit>` 來控制服務。
|
||||
- 宿主機的 nginx 使用者必須允許一個專用的非特權使用者（通常為 `nginxui`）透過 `sudo -n` 無密碼執行一組受限命令。
|
||||
:::
|
||||
|
||||
### 快速開始
|
||||
|
||||
@@ -197,8 +199,14 @@ nginx-ui host-setup test
|
||||
| `host_mode` | 設定為 `ssh` 以啟用此模式 |
|
||||
| `host_address` | 遠端 `host:port` |
|
||||
| `host_user` | 宿主機上的 SSH 使用者 |
|
||||
| `host_auth_method` | SSH 認證方式。目前宿主機 SSH 設定請使用金鑰認證 |
|
||||
| `host_private_key_path` | 容器內的私鑰路徑 |
|
||||
| `host_known_hosts_path` | 容器內的 known_hosts 路徑 |
|
||||
| `host_strict_host_key` | 啟用嚴格主機金鑰檢查。預設啟用，除非明確設定為 `false` |
|
||||
| `host_sudo_prefix` | 特權指令前綴。預設值為 `sudo -n` |
|
||||
| `host_systemd_unit_name` | 預設為 `nginx.service` |
|
||||
| `host_systemctl_path` | 預設為 `/bin/systemctl` |
|
||||
| `host_config_dir` | 宿主機側 nginx 設定目錄 |
|
||||
| `host_log_dir` | 宿主機側 nginx 日誌目錄 |
|
||||
|
||||
另請參閱：[Host SSH 設定指引](host-via-ssh-setup.md)。
|
||||
另請參閱：[在 Docker 中管理宿主機 Nginx](manage-host-nginx-from-docker.md) 和 [使用叢集節點管理多主機 Nginx](manage-multi-host-nginx-with-cluster.md)。
|
||||
|
||||
@@ -158,13 +158,19 @@
|
||||
|
||||
## 透過 SSH 控制宿主機
|
||||
|
||||
::: info
|
||||
這些變數用於 Nginx UI 在 Docker 容器中透過 SSH 控制宿主機上原生安裝的 nginx 服務。
|
||||
:::
|
||||
|
||||
| 變數 | 描述 |
|
||||
|---|---|
|
||||
| `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_AUTH_METHOD` | SSH 認證方式。目前宿主機 SSH 設定請使用金鑰認證 |
|
||||
| `NGINX_UI_NGINX_HOST_PRIVATE_KEY_PATH` | 容器內的私鑰路徑 |
|
||||
| `NGINX_UI_NGINX_HOST_KNOWN_HOSTS_PATH` | 容器內的 known_hosts 路徑 |
|
||||
| `NGINX_UI_NGINX_HOST_STRICT_HOST_KEY` | 僅在需要關閉嚴格主機金鑰檢查時設定為 `false` |
|
||||
| `NGINX_UI_NGINX_HOST_SUDO_PREFIX` | 預設為 `sudo -n` |
|
||||
| `NGINX_UI_NGINX_HOST_SYSTEMD_UNIT_NAME` | 預設為 `nginx.service` |
|
||||
| `NGINX_UI_NGINX_HOST_SYSTEMCTL_PATH` | 宿主機上 systemctl 的絕對路徑 |
|
||||
|
||||
+64
-15
@@ -1,14 +1,14 @@
|
||||
# 宿主機 SSH 設定 — 完整指南
|
||||
# 在 Docker 中管理宿主機 Nginx
|
||||
|
||||
本頁介紹如何設定以 Docker 方式執行的 Nginx UI，使其管理安裝在同一宿主機上的 nginx 原生實例。
|
||||
|
||||
## 前置條件
|
||||
當 Nginx UI 執行在 Docker 中，並需要管理同一宿主機上原生安裝的 nginx 時，可按本文完成設定。
|
||||
|
||||
::: info 前置條件
|
||||
- 已安裝 nginx 並透過 systemd 執行的 Linux 宿主機
|
||||
- 同一宿主機上已安裝 Docker
|
||||
- 一個專用於 Nginx UI 的非特權使用者（範例中使用 `nginxui`）
|
||||
:::
|
||||
|
||||
## 步驟 1 — 建立非特權使用者
|
||||
## 步驟 1：建立非特權使用者
|
||||
|
||||
```bash
|
||||
sudo useradd -r -s /bin/bash -m -G adm nginxui
|
||||
@@ -16,7 +16,7 @@ sudo useradd -r -s /bin/bash -m -G adm nginxui
|
||||
|
||||
`-G adm` 授予該使用者讀取 /var/log 檔案（包括 nginx 日誌）的權限。
|
||||
|
||||
## 步驟 2 — 透過 Nginx UI 產生金鑰對
|
||||
## 步驟 2：透過 Nginx UI 產生金鑰對
|
||||
|
||||
開啟**偏好設定 → Nginx → 透過 SSH 管理宿主機 → 開啟設定精靈**。在步驟 1 中點擊**產生金鑰對**。
|
||||
|
||||
@@ -36,7 +36,11 @@ sudo chmod 700 /home/nginxui/.ssh
|
||||
sudo chmod 600 /home/nginxui/.ssh/authorized_keys
|
||||
```
|
||||
|
||||
## 步驟 3 — 安裝 sudoers 項目
|
||||
::: warning 主機金鑰驗證
|
||||
預設啟用嚴格主機金鑰檢查。如果設定精靈顯示新的主機指紋，請先確認指紋再信任該金鑰。只有在受控測試環境中，才建議設定 `NGINX_UI_NGINX_HOST_STRICT_HOST_KEY=false`。
|
||||
:::
|
||||
|
||||
## 步驟 3：安裝 sudoers 項目
|
||||
|
||||
精靈步驟 2b 會顯示一段 sudoers 設定片段。複製後透過以下指令安裝：
|
||||
|
||||
@@ -46,27 +50,33 @@ sudo visudo -f /etc/sudoers.d/nginx-ui
|
||||
|
||||
貼上設定片段後儲存並退出。如果語法有誤，visudo 會拒絕儲存該檔案。
|
||||
|
||||
## 步驟 4 — 套用 ACL（選用，適用於非 root 使用者）
|
||||
## 步驟 4：為非 root 使用者套用 ACL
|
||||
|
||||
::: 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
|
||||
```
|
||||
:::
|
||||
|
||||
## 步驟 5 — 更新 docker-compose 設定
|
||||
## 步驟 5：更新 docker-compose 設定
|
||||
|
||||
精靈步驟 2a 會顯示一段 compose 設定片段。將其合併到現有的 `docker-compose.yml` 中，然後執行：
|
||||
|
||||
產生的片段會設定 `NGINX_UI_DISABLE_BUNDLED_NGINX=true`，避免容器在控制宿主機 nginx 時繼續啟動內建 nginx 服務。
|
||||
|
||||
```bash
|
||||
docker compose up -d --force-recreate nginx-ui
|
||||
```
|
||||
|
||||
## 步驟 6 — 驗證
|
||||
## 步驟 6：驗證設定
|
||||
|
||||
返回精靈步驟 4，點擊**執行驗證**。所有檢查項應全部通過：
|
||||
|
||||
::: tip 預期驗證結果
|
||||
|
||||
- ✓ same_host: machine-id 匹配
|
||||
- ✓ ssh_connect: 透過 SSH 執行 echo ok 成功
|
||||
- ✓ sudo_available: sudo -n true 執行成功
|
||||
@@ -78,17 +88,56 @@ docker compose up -d --force-recreate nginx-ui
|
||||
- ✓ log_dir_readable: /var/log/nginx/access.log 可讀
|
||||
- ✓ pid_file_present: /var/run/nginx.pid 存在
|
||||
|
||||
點擊**儲存**，設定完成。
|
||||
:::
|
||||
|
||||
所有檢查通過後，點擊**儲存**。
|
||||
|
||||
## 疑難排解
|
||||
|
||||
**`sudo_available` 報錯 "sudo: a password is required"**
|
||||
::: details `sudo_available` 報錯 "sudo: a password is required"
|
||||
- 檢查 sudoers 檔案中是否包含 `NOPASSWD:`，而不僅僅是 `(root)`。
|
||||
- 檢查檔案中行末續行符（`\`）是否正確。
|
||||
:::
|
||||
|
||||
**`ssh_connect` 報錯 "permission denied (publickey)"**
|
||||
::: details `ssh_connect` 報錯 "permission denied (publickey)"
|
||||
- 驗證 authorized_keys 檔案中的公鑰內容、檔案擁有者及權限是否正確。
|
||||
- 檢查 sshd_config 中是否啟用了 `PubkeyAuthentication yes`。
|
||||
:::
|
||||
|
||||
**`same_host` 警告 "remote host detected"**
|
||||
- 您的 `host_address` 解析到了不同的機器。SSH 模式**不支援**跨主機使用；請參閱 [叢集節點跨主機指南](cluster-node-cross-host.md)。
|
||||
::: warning `same_host` 警告 "remote host detected"
|
||||
您的 `host_address` 解析到了不同的機器。SSH 模式**不支援**跨主機使用；請參閱 [使用叢集節點管理多主機 Nginx](manage-multi-host-nginx-with-cluster.md)。
|
||||
:::
|
||||
|
||||
## CLI 參考
|
||||
|
||||
產生宿主機 SSH 使用的金鑰對：
|
||||
|
||||
```bash
|
||||
nginx-ui host-setup keygen --out /etc/nginx-ui/host_key
|
||||
```
|
||||
|
||||
輸出全部設定片段：
|
||||
|
||||
```bash
|
||||
nginx-ui host-setup print --host-address host.docker.internal:22 --host-user nginxui
|
||||
```
|
||||
|
||||
只輸出 Docker 或宿主機側片段：
|
||||
|
||||
```bash
|
||||
nginx-ui host-setup print --host-address host.docker.internal:22 --host-user nginxui --compose
|
||||
nginx-ui host-setup print --host-address host.docker.internal:22 --host-user nginxui --host
|
||||
```
|
||||
|
||||
需要機器可讀輸出、完整 compose override 或 docker run 指令時，可以使用 `--json`、`--override` 或 `--docker-run`。
|
||||
|
||||
基於目前設定執行驗證：
|
||||
|
||||
```bash
|
||||
nginx-ui host-setup test
|
||||
```
|
||||
|
||||
## 相關文件
|
||||
|
||||
- [Nginx 設定參考](config-nginx.md#透過-ssh-控制宿主機-nginx)
|
||||
- [使用叢集節點管理多主機 Nginx](manage-multi-host-nginx-with-cluster.md)
|
||||
@@ -0,0 +1,75 @@
|
||||
# 使用叢集節點管理多主機 Nginx
|
||||
|
||||
::: tip 建議方式
|
||||
當您希望透過單一 Nginx UI 控制面板管理多台主機上的 nginx 時，請使用**叢集節點**功能，而不是宿主機 SSH 模式。
|
||||
:::
|
||||
|
||||
## 如何選擇
|
||||
|
||||
| 需求 | host_via_ssh | 叢集節點 |
|
||||
|---|---|---|
|
||||
| 主機 A 上的容器管理主機 A 上的 nginx | ✓ | ✓（過於複雜） |
|
||||
| 主機 A 上的容器管理主機 B 上的 nginx | ✗ | ✓ |
|
||||
| 透過單一 Web 介面檢視多台主機的設定/日誌 | 否 | ✓ |
|
||||
| 對等節點無法連線時各主機保持自主執行 | 否 | ✓ |
|
||||
|
||||
## 建議拓撲
|
||||
|
||||
| 層級 | 作用 | 說明 |
|
||||
|---|---|---|
|
||||
| 瀏覽器 | 開啟主節點的 Nginx UI | 日常操作只需要進入一個控制台 |
|
||||
| 主節點 | 註冊對等節點並提供節點切換器 | 也可以管理本機 nginx |
|
||||
| 對等節點 | 分別執行自己的 Nginx UI 實例 | 每個節點管理同一主機上的 nginx |
|
||||
| 叢集聯邦 | 連接主節點與對等節點 | 請求會在目前選取的節點上執行 |
|
||||
|
||||
主節點不會透過 SSH 連線到其他主機，而是透過叢集節點連線轉發操作。如果某個節點以 Docker 方式執行 Nginx UI，並管理同一宿主機上的 nginx，請只在該節點上設定 [在 Docker 中管理宿主機 Nginx](manage-host-nginx-from-docker.md)。
|
||||
|
||||
## 設定步驟
|
||||
|
||||
### 1. 在每台主機上安裝 nginx-ui
|
||||
|
||||
建議每個節點盡量使用相同的部署方式。原生 Linux 安裝可以執行：
|
||||
|
||||
```bash
|
||||
bash -c "$(curl -L https://cloud.nginxui.com/install.sh)" @ install
|
||||
```
|
||||
|
||||
也可以使用 Docker 部署。可參考 [安裝指令碼](install-script-linux.md) 和 [快速開始](getting-started.md#docker) 了解可用的安裝方式。
|
||||
|
||||
### 2. 在每個對等節點上產生 Node Secret
|
||||
|
||||
登入對等節點的 Web 介面，進入**設定 → 節點**，複製 **Node Secret**。
|
||||
|
||||
### 3. 在主節點上註冊對等節點
|
||||
|
||||
可以透過 `app.ini` 或 Docker 環境變數設定對等節點：
|
||||
|
||||
::: code-group
|
||||
|
||||
```ini [app.ini]
|
||||
[cluster]
|
||||
Node = http://10.0.0.2:9000?name=host-b&node_secret=<host-b-secret>&enabled=true
|
||||
Node = http://10.0.0.3:9000?name=host-c&node_secret=<host-c-secret>&enabled=true
|
||||
```
|
||||
|
||||
```yaml [docker-compose.yml]
|
||||
services:
|
||||
nginx-ui:
|
||||
environment:
|
||||
- NGINX_UI_CLUSTER_NODE_0=http://10.0.0.2:9000?name=host-b&node_secret=...&enabled=true
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### 4. 在 Web 介面中切換節點
|
||||
|
||||
頂列的節點切換器會將後續所有操作路由到所選節點。每個操作都**在該節點本地執行**。主機之間不需要 SSH 通訊。
|
||||
|
||||
## 叢集與 host_via_ssh 組合使用
|
||||
|
||||
您可以讓每個叢集對等節點在內部執行 host_via_ssh。在這種佈局中，容器只管理本機 nginx，跨主機協調由叢集聯邦處理。
|
||||
|
||||
另請參閱：
|
||||
|
||||
- [Cluster 設定參考](config-cluster.md)
|
||||
- [在 Docker 中管理宿主機 Nginx](manage-host-nginx-from-docker.md)
|
||||
Reference in New Issue
Block a user