CyberMind-FR
ccfb58124c
Add complete French (fr) and Chinese (zh) translations for all documentation: - Root files: README, CHANGELOG, SECURITY, BETA-RELEASE - docs/: All 16 core documentation files - DOCS/: All 19 deep-dive documents including embedded/ and archive/ - package/secubox/: All 123+ package READMEs - Misc: secubox-tools/, scripts/, EXAMPLES/, config-backups/, streamlit-apps/ Total: 346 translation files created Each file includes language switcher links for easy navigation between English, French, and Chinese versions. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
118 lines
4.4 KiB
Markdown
118 lines
4.4 KiB
Markdown
# VHost 管理器与反向代理说明
|
||
|
||
> **Languages:** [English](../../DOCS/embedded/vhost-manager.md) | [Francais](../../DOCS-fr/embedded/vhost-manager.md) | 中文
|
||
|
||
**版本：** 1.0.0
|
||
**最后更新：** 2025-12-28
|
||
**状态：** 活跃
|
||
|
||
SecuBox 包含 `luci-app-vhost-manager`（LuCI 仪表板 + RPC 后端）以及 `scripts/vhostctl.sh` 助手，使应用程序、向导和配置文件可以声明式地在 nginx 后面发布 HTTP 服务，并支持可选的 TLS 和 HTTP 认证。
|
||
|
||
---
|
||
|
||
## 前提条件
|
||
|
||
1. **软件包**：已安装 `luci-app-vhost-manager`（安装 RPCD 脚本 + LuCI 界面）和带 SSL 的 nginx（`nginx-ssl`）。
|
||
2. **证书**：通过 `acme.sh` 自动获取 ACME 证书，或使用手动 PEM 文件配合 `tls manual`。
|
||
3. **应用程序**：确保上游服务在 localhost 或 LAN 上监听（例如，Zigbee2MQTT 界面在 `http://127.0.0.1:8080`）。
|
||
4. **防火墙**：在 WAN 接口上允许入站端口 80/443。
|
||
|
||
---
|
||
|
||
## CLI（`scripts/vhostctl.sh`）
|
||
|
||
此助手操作 `/etc/config/vhosts`，可被未来的向导/App Store 安装程序调用。
|
||
|
||
```sh
|
||
# 列出现有映射
|
||
scripts/vhostctl.sh list
|
||
|
||
# 为 Zigbee2MQTT 界面添加 HTTPS 反向代理
|
||
scripts/vhostctl.sh add \
|
||
--domain zigbee.home.lab \
|
||
--upstream http://127.0.0.1:8080 \
|
||
--tls acme \
|
||
--websocket \
|
||
--enable
|
||
|
||
# 稍后启用/禁用或删除
|
||
scripts/vhostctl.sh disable --domain zigbee.home.lab
|
||
scripts/vhostctl.sh remove --domain zigbee.home.lab
|
||
|
||
# 修改后重新加载 nginx
|
||
scripts/vhostctl.sh reload
|
||
```
|
||
|
||
选项：
|
||
|
||
| 选项 | 用途 |
|
||
|------|------|
|
||
| `--domain` | 公共主机名（必填）。 |
|
||
| `--upstream` | 本地服务 URL（`http://127.0.0.1:8080`）。 |
|
||
| `--tls off|acme|manual` | TLS 策略。使用 `manual` + `--cert/--key` 配置自定义证书。 |
|
||
| `--auth-user/--auth-pass` | 启用 HTTP 基本认证。 |
|
||
| `--websocket` | 为 WebSocket 应用添加 `Upgrade` 头。 |
|
||
| `--enable` / `--disable` | 启用/禁用而不删除。 |
|
||
|
||
脚本具有幂等性：使用现有域名运行 `add` 会更新该条目。
|
||
|
||
---
|
||
|
||
## LuCI 仪表板
|
||
|
||
导航至 **服务 -> SecuBox -> VHost 管理器** 可以：
|
||
- 查看活跃/禁用的虚拟主机、TLS 状态、证书过期时间。
|
||
- 编辑或删除条目、请求 ACME 证书、查看访问日志。
|
||
- 使用表单创建条目（域名、上游、TLS、认证、WebSocket）。
|
||
|
||
LuCI 后端写入相同的 `/etc/config/vhosts` 文件，因此通过 `vhostctl.sh` 所做的更改会立即显示。
|
||
|
||
---
|
||
|
||
## 示例：发布 Zigbee2MQTT
|
||
|
||
1. 安装 Zigbee2MQTT（Docker）并确认界面在端口 8080 上监听（参见 `docs/embedded/zigbee2mqtt-docker.md`）。
|
||
2. 将其映射到 HTTPS 后面：
|
||
```sh
|
||
scripts/vhostctl.sh add \
|
||
--domain zigbee.secubox.local \
|
||
--upstream http://127.0.0.1:8080 \
|
||
--tls acme \
|
||
--websocket
|
||
scripts/vhostctl.sh reload
|
||
```
|
||
3. （可选）使用 LuCI 请求证书并监控日志。
|
||
|
||
---
|
||
|
||
## DMZ 模式 + VHost 工作流
|
||
|
||
启用新的 **路由器 + DMZ** 网络模式（管理 -> SecuBox -> 网络 -> 模式 -> DMZ）时：
|
||
|
||
1. 将 `eth2`（或其他物理端口）分配为 DMZ 接口，并为其分配子网，如 `192.168.50.1/24`。
|
||
2. 应用该模式；后端会创建一个专用防火墙区域（`dmz`），仅转发到 WAN。
|
||
3. 将服务器（如 Lyrion、Zigbee2MQTT 界面）连接到 DMZ 端口，使其可以访问互联网但无法访问 LAN。
|
||
4. 使用 `scripts/vhostctl.sh add ... --upstream http://192.168.50.10:32400` 通过带 TLS 的 nginx 暴露 DMZ 服务。
|
||
|
||
回滚只需一键：在 2 分钟窗口内使用网络模式的"确认/回滚"对话框自动恢复先前的配置。
|
||
|
||
---
|
||
|
||
## 故障排除
|
||
|
||
| 问题 | 解决方案 |
|
||
|------|----------|
|
||
| `scripts/vhostctl.sh add ...` 报错 "Unknown option" | 确保使用 busybox `sh`（`/bin/sh`）。 |
|
||
| ACME 证书缺失 | 确认已安装 `acme.sh`，域名解析到路由器，80/443 端口可访问。 |
|
||
| 502/504 错误 | 检查上游服务、防火墙，或将 `--upstream` 改为 LAN IP。 |
|
||
| TLS 手动模式失败 | 提供 PEM 文件的完整路径并验证权限。 |
|
||
| 更改不可见 | 运行 `scripts/vhostctl.sh reload` 或 `ubus call luci.vhost-manager reload_nginx`。 |
|
||
|
||
---
|
||
|
||
## 自动化说明
|
||
|
||
- 向导/App Store 可以调用 `scripts/vhostctl.sh` 在安装服务时注册它们。
|
||
- 配置文件可以保留声明式清单（域名 -> 上游）并在切换模式时调用 `vhostctl.sh add/remove`。
|
||
- `/etc/config/vhosts` 仍然是唯一的事实来源，由 LuCI 应用和 RPC 后端使用。
|