secubox-openwrt/package/secubox/luci-app-vhost-manager/README.zh.md

VHost Manager - 反向代理和SSL证书管理

版本： 2.0.0 最后更新： 2026-01-01 状态： 活跃

用于管理nginx反向代理虚拟主机和通过Let's Encrypt获取SSL证书的LuCI应用程序，集成了服务模板和重定向管理功能。

功能特性

内部服务目录 (v2.0+)

• 预配置服务模板 - 19个即用型内部服务
• 一键激活 - 使用最佳SSL、认证和WebSocket设置部署服务
• 实时状态 - 自动刷新仪表板显示活跃/已配置服务
• 智能功能检测 - 自动SSL、认证和WebSocket配置
• 分类组织 - 按类型分组的服务（物联网、媒体、安全、生产力等）
• 自动刷新 - 每10秒实时更新
• 现代网格界面 - 响应式卡片布局，带功能徽章

重定向规则管理 (v2.0+)

• 预建重定向模板 - 6种常见重定向模式（CDN缓存、隐私重定向、故障转移）
• HTTP重定向代码 - 支持301（永久）、302（临时）、307（临时，保留方法）
• 模板激活 - 一键部署重定向规则
• 活跃重定向仪表板 - 已配置重定向的实时状态
• 分类组织 - 按用例分组的模板（生产力、媒体、安全、网络）
• 自动刷新 - 每10秒实时更新

虚拟主机管理 (v1.0+)

• 创建和管理nginx反向代理配置
• 支持HTTP和HTTPS虚拟主机
• 部署前后端连接测试
• WebSocket协议支持
• HTTP Basic认证
• 配置更改时自动重载nginx
• 启用/禁用开关 - 无需删除即可快速控制服务
• 删除按钮 - 带确认的清洁VHost删除

SSL证书管理 (v1.0+)

• 通过acme.sh提供Let's Encrypt证书
• 证书状态监控和过期跟踪
• 颜色编码的过期警告（红色 < 7天，橙色 < 30天）
• 证书详情查看器
• 自动证书续期支持

访问日志监控 (v1.0+)

• 实时nginx访问日志查看器
• 按域名过滤日志
• 可配置行数显示（50-500行）
• 终端风格日志显示

配置文件激活系统 (v2.0+)

• 基于模板部署 - 从预配置模板创建VHost
• 智能功能配置 - 根据服务需求自动设置SSL/认证/WebSocket
• 模板说明 - 激活时显示上下文信息
• 确认对话框 - 部署前审查设置
• 激活/停用 - 带视觉反馈的简易模板管理

安装

opkg update
opkg install luci-app-vhost-manager
/etc/init.d/rpcd restart
/etc/init.d/uhttpd restart

依赖

• luci-base：LuCI框架
• rpcd：用于后端通信的RPC守护进程
• nginx-ssl：带SSL支持的Nginx Web服务器
• acme：用于Let's Encrypt证书的ACME客户端
• curl：用于后端测试的HTTP客户端

配置

UCI配置 (/etc/config/vhosts)

虚拟主机现在位于/etc/config/vhosts，允许其他SecuBox组件声明式安装代理。安装时会放置一个默认文件；像其他UCI配置一样编辑它：

config global 'global'
	option enabled '1'
	option auto_reload '1'

config vhost 'myapp'
	option domain 'app.example.com'
	option upstream 'http://127.0.0.1:8080'
	option tls 'acme'          # off|acme|manual
	option cert_path '/etc/custom/fullchain.pem'   # tls=manual时使用
	option key_path '/etc/custom/privkey.pem'
	option auth '1'
	option auth_user 'admin'
	option auth_pass 'secretpassword'
	option websocket '1'
	option enabled '1'

旧版安装可能仍提供/etc/config/vhost_manager以保持向后兼容，但RPC后端现在专门从/etc/config/vhosts生成/etc/nginx/conf.d/*.conf。

选项

全局部分

• enabled：启用/禁用VHost Manager（默认：1）
• auto_reload：配置更改时自动重载nginx（默认：1）
• log_retention：访问日志保留天数（默认：30）

VHost部分

• domain：此虚拟主机的域名（必需）
• upstream：要代理的后端URL（必需，例如 http://192.168.1.100:8080）
• tls：TLS策略（off、acme或manual）
• cert_path / key_path：tls=manual时需要指向PEM文件
• auth：启用HTTP Basic认证（默认：0）
• auth_user / auth_pass：auth=1时使用的凭据
• websocket：启用WebSocket头（默认：0）
• enabled：禁用vhost但不删除（默认：1）

使用方法

Web界面

在LuCI中导航至 服务 -> VHost Manager。

概览选项卡

• 系统状态（Nginx运行中、ACME可用性）
• 虚拟主机统计（SSL启用、认证保护、WebSocket）
• 证书数量和过期状态
• 最近虚拟主机列表

虚拟主机选项卡

• 添加新虚拟主机
• 编辑现有配置
• 保存前测试后端连接
• 启用/禁用SSL、认证、WebSocket
• 删除虚拟主机

证书选项卡

• 请求新的Let's Encrypt证书
• 查看已安装证书及过期日期
• 证书详情查看器
• 颜色编码的过期警告

日志选项卡

• 按域名查看nginx访问日志
• 选择显示行数（50-500）
• 实时日志流

内部服务选项卡 (v2.0+)

内部服务选项卡为流行的自托管应用程序提供19个预配置服务模板的目录。

仪表板指标：

• 活跃 - 当前启用并运行的服务
• 已配置 - 有VHost条目的服务总数
• 可用 - 目录中的模板总数

活跃服务网格：

每个已配置服务显示：

• 服务图标和名称
• 状态徽章（活跃/禁用）
• 类别和描述
• 域名、后端URL和端口
• 功能徽章（SSL、认证、WebSocket）
• 三个操作按钮：
  • 编辑 - 导航到VHost配置
  • 启用/禁用 - 切换服务状态
  • 删除 - 删除VHost配置（带确认）

服务模板：

模板按类别组织：

类别	服务
核心服务	LuCI UI
监控	Netdata
安全	CrowdSec、Vaultwarden
网络	NoDogSplash、AdGuard Home、Uptime Kuma
物联网与家庭自动化	Domoticz、Zigbee2MQTT、Home Assistant、MagicMirror
媒体	Lyrion Music Server、Jellyfin
AI与机器学习	LocalAI
生产力	Citadel、ISPConfig、Mail-in-a-Box、Nextcloud、Gitea
托管与控制面板	Portainer

模板激活工作流程：

1. 点击任意模板上的 激活
2. 查看激活对话框显示：
   • 服务名称和图标
   • 域名和后端URL
   • 所需功能（SSL、认证、WebSocket）
   • 特殊说明（例如"Nextcloud处理自己的认证"）
3. 点击 激活 创建VHost
4. 服务自动配置最佳设置

示例：激活Nextcloud

模板配置：

图标：云
名称：Nextcloud
域名：cloud.local
后端：http://127.0.0.1:80
端口：80
类别：生产力
功能：
  - 需要SSL/TLS
  - WebSocket支持
说明："Nextcloud处理自己的认证。在config.php中配置可信域名。"

激活后：

• 在cloud.local创建VHost
• 自动配置SSL（ACME模式）
• 启用WebSocket头
• 后端代理到端口80
• 服务在仪表板中标记为"活跃"

重定向选项卡 (v2.0+)

重定向选项卡管理nginx HTTP重定向规则，提供常见用例的预建模板。

仪表板指标：

• 活跃 - 当前启用的重定向规则
• 总计 - 所有已配置的重定向
• 模板 - 可用重定向模板

活跃重定向网格：

每个已配置重定向显示：

• 重定向图标
• 域名
• 状态徽章（活跃/禁用）
• 源域名
• 目标URL
• HTTP代码徽章（301、302、307）
• 三个操作按钮：
  • 编辑 - 导航到VHost配置
  • 启用/禁用 - 切换重定向状态
  • 删除 - 删除重定向规则（带确认）

重定向模板：

模板	HTTP代码	类别	用例
Nextcloud到LAN	301	生产力	强制远程用户使用LAN托管的Nextcloud
Steam CDN缓存	302	媒体	将下载重定向到本地缓存
YouTube到Invidious	307	媒体	隐私友好的YouTube重定向
邮件故障转移	302	生产力	故障转移到备用邮件服务
广告拦截重定向	301	安全	将广告服务器重定向到localhost
CDN到本地缓存	302	网络	本地缓存CDN资源

HTTP重定向代码：

• 301（永久） - 浏览器缓存重定向，用于永久移动
• 302（临时） - 浏览器不缓存，用于临时重定向
• 307（临时，保留方法） - 类似302但保留HTTP方法（POST/GET）

命令行

列出虚拟主机

ubus call luci.vhost-manager list_vhosts

获取VHost Manager状态

ubus call luci.vhost-manager status

添加虚拟主机

ubus call luci.vhost-manager add_vhost '{
  "domain": "app.example.com",
  "backend": "http://192.168.1.100:8080",
  "tls_mode": "acme",
  "auth": true,
  "auth_user": "admin",
  "auth_pass": "secret",
  "websocket": true,
  "enabled": true
}'

测试后端连接

ubus call luci.vhost-manager test_backend '{
  "backend": "http://192.168.1.100:8080"
}'

请求SSL证书

ubus call luci.vhost-manager request_cert '{
  "domain": "app.example.com",
  "email": "admin@example.com"
}'

列出证书

ubus call luci.vhost-manager list_certs

重载Nginx

ubus call luci.vhost-manager reload_nginx

获取访问日志

ubus call luci.vhost-manager get_access_logs '{
  "domain": "app.example.com",
  "lines": 100
}'

Nginx配置

VHost Manager在/etc/nginx/conf.d/中生成nginx配置文件。

生成的配置示例（仅HTTP）

server {
    listen 80;
    server_name app.example.com;

    access_log /var/log/nginx/app.example.com.access.log;
    error_log /var/log/nginx/app.example.com.error.log;

    location / {
        proxy_pass http://192.168.1.100:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

生成的配置示例（带WebSocket的HTTPS）

server {
    listen 80;
    server_name app.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name app.example.com;

    ssl_certificate /etc/acme/app.example.com/fullchain.cer;
    ssl_certificate_key /etc/acme/app.example.com/app.example.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    access_log /var/log/nginx/app.example.com.access.log;
    error_log /var/log/nginx/app.example.com.error.log;

    location / {
        proxy_pass http://192.168.1.100:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket支持
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 86400;
    }
}

带认证的示例

server {
    listen 443 ssl http2;
    server_name app.example.com;

    ssl_certificate /etc/acme/app.example.com/fullchain.cer;
    ssl_certificate_key /etc/acme/app.example.com/app.example.com.key;

    location / {
        auth_basic "受限访问";
        auth_basic_user_file /etc/nginx/htpasswd/app.example.com;

        proxy_pass http://192.168.1.100:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

SSL证书工作流程

1. DNS配置：确保您的域名指向路由器的公网IP
2. 端口转发：将端口80和443转发到您的路由器
3. 请求证书：使用证书选项卡请求Let's Encrypt证书
4. 配置VHost：为虚拟主机启用SSL
5. 监控过期：证书90天后过期，在证书选项卡中监控

ACME证书位置

• 证书：/etc/acme/{domain}/fullchain.cer
• 私钥：/etc/acme/{domain}/{domain}.key
• ACME账户：/etc/acme/account.conf

ubus API参考

status()

获取VHost Manager和nginx状态。

返回：

{
  "nginx_running": true,
  "nginx_version": "1.23.3",
  "acme_available": true,
  "acme_version": "3.0.5",
  "vhost_count": 5
}

list_vhosts()

列出所有已配置的虚拟主机。

get_vhost(domain)

获取特定虚拟主机的详细信息。

参数：

• domain：域名

add_vhost(payload)

添加新虚拟主机。

参数：

• domain：域名（必需）
• backend：后端URL（必需）
• tls_mode：off、acme或manual（必需）
• auth：启用认证（布尔值）
• auth_user / auth_pass：启用auth时的凭据
• websocket：启用WebSocket（布尔值）
• enabled：禁用vhost但不删除（布尔值）
• cert_path / key_path：tls_mode=manual时必需

update_vhost(payload)

更新现有虚拟主机。

参数： 与add_vhost相同。省略的字段保留其先前的值。

delete_vhost(domain)

删除虚拟主机。

test_backend(backend)

测试到后端服务器的连接。

request_cert(domain, email)

请求Let's Encrypt SSL证书。

list_certs()

列出所有已安装的SSL证书。

reload_nginx()

重载nginx配置。

get_access_logs(domain, lines)

获取域名的nginx访问日志。

故障排除

Nginx无法启动

检查nginx配置语法：

nginx -t

查看nginx错误日志：

logread | grep nginx

证书请求失败

确保：

1. 域名DNS指向您的公网IP
2. 端口80和443已转发到您的路由器
3. 防火墙允许端口80和443的入站连接
4. 没有其他服务使用端口80（acme.sh需要它进行验证）

检查ACME日志：

cat /var/log/acme.log

后端无法访问

手动测试后端：

curl -I http://192.168.1.100:8080

检查后端是否在监听：

netstat -tuln | grep 8080

WebSocket不工作

确保：

1. 在虚拟主机配置中启用了WebSocket支持
2. 后端应用程序支持WebSocket
3. 代理超时时间不要太短（默认：86400秒）

认证不工作

检查htpasswd文件是否存在：

ls -l /etc/nginx/.luci-app-vhost-manager_{domain}

安全注意事项

1. SSL证书：生产服务始终使用HTTPS
2. 强密码：HTTP Basic认证使用强密码
3. 后端安全：确保后端服务不能从互联网直接访问
4. 防火墙规则：配置防火墙只允许必要的端口
5. 日志监控：定期检查访问日志以发现可疑活动
6. 证书续期：监控证书过期并确保自动续期正常工作

许可证

Apache-2.0

维护者

SecuBox Project support@secubox.com

版本

2.0.0