bt-source/panel/mod/base/pynginx/btnginx/readme.md

第三方 Nginx 接入方案

方案概述

本方案核心目标是读取第三方 Nginx 实例及全量配置文件，通过解析、分类、重构，生成符合面板规范的配置（支持 PHP 项目、反向代理、静态 HTML 项目），实现第三方 Nginx 无缝对接面板管理。

---

一、模块架构

目录结构

mod/base/pynginx/
├── nginx_base.py        # 基础类定义（Token、Directive、Block等）
├── nginx_parser.py      # 词法/语法解析器
├── nginx_components.py  # Nginx组件实现（Http、Server、Location、Upstream等）
├── nginx_config.py      # Config和Include类
├── extension/           # 配置操作扩展工具
│   ├── config.py        # 配置查找工具（ConfigFinder、ConfigTools）
│   ├── server.py        # Server块操作工具（ServerTools）
│   ├── location.py      # Location块操作工具
│   ├── nginx_info.py    # Nginx信息获取
│   └── utils.py         # 工具函数
└── btnginx/             # 第三方Nginx接入实现
    ├── nginx_detector.py # Nginx实例探测器
    ├── site_detector.py  # 站点配置分离与分类
    ├── bt_formater.py    # 面板兼容配置格式化
    ├── create_site.py    # 面板站点创建工具
    ├── rel2real_path.py  # 相对路径转绝对路径
    └── panel_utils.py    # 面板工具函数

核心类关系

┌─────────────┐     解析      ┌─────────────┐
│ nginx.conf  │ ───────────▶  │   Config    │
└─────────────┘               └──────┬──────┘
                                     │
                    ┌────────────────┼────────────────┐
                    ▼                ▼                ▼
              ┌──────────┐    ┌──────────┐    ┌──────────┐
              │   Http   │    │ Upstream │    │ Include  │
              └────┬─────┘    └──────────┘    └──────────┘
                   │
                   ▼
              ┌──────────┐
              │  Server  │ ───▶ SiteInfo (站点信息)
              └────┬─────┘
                   │
        ┌──────────┼──────────┐
        ▼          ▼          ▼
   ┌──────────┐ ┌──────────┐ ┌──────────┐
   │ Location │ │ Location │ │  指令...  │
   └──────────┘ └──────────┘ └──────────┘

---

二、Nginx 实例定位策略

1. 进程名称匹配

直接扫描系统运行进程，匹配 nginx 进程标识。 通过进程信息反推核心路径：可执行文件路径 + 主配置文件（nginx.conf）路径。

2. 常见路径兜底扫描

若进程匹配未命中，遍历行业通用安装路径：

• /usr/sbin/nginx
• /usr/local/nginx/sbin/nginx
• /www/server/nginx/sbin/nginx
• /opt/nginx/sbin/nginx

使用示例

from mod.base.pynginx.btnginx.nginx_detector import ng_detect, ng_detect_by_bin

# 获取所有Nginx实例
instances = ng_detect()
for ins in instances:
    print(f"可执行文件: {ins.nginx_bin}")
    print(f"配置文件: {ins.nginx_conf}")
    print(f"版本: {ins.version}")
    print(f"运行状态: {ins.running}")

# 仅获取运行中的实例
running_instances = ng_detect(only_running=True)

# 通过可执行文件路径获取实例
ins = ng_detect_by_bin("/usr/local/nginx/sbin/nginx")

---

三、配置文件全量解析

解析能力

• 解析范围：主配置文件（nginx.conf）+ 所有通过 include 指令引入的子配置文件（含多级嵌套引入）。
• 解析目标：提取配置结构树（全局块、http 块、server 块、location 块等）、指令参数、注释信息。
• 特殊支持：Lua代码块（*_by_lua_block）解析。

使用示例

from mod.base.pynginx import parse_file, parse_string, dump_config

# 从文件解析（不解析include）
config = parse_file("/etc/nginx/nginx.conf")

# 从文件解析（递归解析include）
config = parse_file(
    "/etc/nginx/nginx.conf",
    parse_include=True,
    main_config_path="/etc/nginx"  # 用于定位include相对路径
)

# 从字符串解析
config = parse_string("""
server {
    listen 80;
    server_name example.com;
    root /var/www/html;
}
""")

# 查找所有server块
servers = config.find_servers()

# 查找http块
http = config.find_http()

# 查找所有upstream块
upstreams = config.find_upstreams()

# 导出配置为字符串
content = dump_config(config)

指令查找

from mod.base.pynginx import Config

# 查找指定指令
listen_dirs = server_block.find_directives("listen")

# 查找指令（包含include子块）
server_dirs = http_block.find_directives("server", include=True)

# 查找指令（包含所有子块）
all_proxy_pass = server_block.find_directives("proxy_pass", include=True, sub_block=True)

---

四、站点配置分离与分类

从解析后的全量配置中，提取所有 http -> server 虚拟主机块，按"服务类型"分类、"域名规则"聚合：

1. 服务类型判定标准

• PHP 项目：配置中存在 fastcgi_pass 指令（关联 PHP-FPM 服务）。
• 反向代理项目：配置中存在 proxy_pass 指令（指向后端服务地址）。
• 静态项目：不满足上述两类条件，默认判定为静态资源服务。

2. 虚拟主机聚合规则

• 相同 server_name 则合并为一个站点配置（统一管理 HTTP/HTTPS 规则）。

使用示例

from mod.base.pynginx import parse_file
from mod.base.pynginx.btnginx.site_detector import site_detector, SiteInfo

# 解析配置
config = parse_file("/etc/nginx/nginx.conf", parse_include=True)

# 检测站点
sites = site_detector(config)

for site in sites:
    print(f"域名: {site.server_names}")
    print(f"端口: {site.listen_ports}")
    print(f"类型: {site.site_type}")  # PHP/反向代理/静态

---

五、面板兼容配置生成

基于解析后的原始配置，进行"结构调整 + 功能增强"，生成符合面板使用规范的配置文件。

配置文件调整

1. 主配置文件调整

   • 直接保留：非 http 块的所有全局配置
   • 条件保留：http 块中不含 server 块的 include 文件
   • 强制注入：面板必需的基础指令和标记

2. 站点配置功能增强

   • 解析展开：将所有 include 引用的子配置直接展开
   • 插入关键标识位：SSL证书配置、PHP关联配置等
   • 结构重组：按规范顺序组织配置

使用示例

from mod.base.pynginx.btnginx.bt_formater import bt_nginx_format
from mod.base.pynginx.btnginx.nginx_detector import ng_detect

# 获取Nginx实例
nginx_ins = ng_detect(only_running=True)[0]

# 创建格式化器， 解析并生成面板兼容配置
result = bt_nginx_format(nginx_ins)

# result包含:
# - site_conf: 站点配置信息列表
# - tmp_path: 临时配置文件目录
# - main_conf_path: 主配置文件路径

---

六、核心API参考

nginx_base.py - 基础类

类/函数	说明
Token	词法标记，包含类型、内容、行号、列号
TokenType	标记类型枚举（EOF, KEYWORD, QUOTED_STRING等）
Directive	指令实现，包含name、parameters、block、comment等
Block	块实现，包含directives列表
IDirective	指令接口定义
IBlock	块接口定义

nginx_parser.py - 解析器

函数	说明
parse_file(path, parse_include, main_config_path, comment_line_count)	从文件解析配置
parse_string(content, parse_include, comment_line_count)	从字符串解析配置
dump_config(config, style)	导出配置为字符串
dump_block(block, style)	导出块为字符串

nginx_components.py - 组件类

类	说明
Http	HTTP块组件
Server	Server块组件
Location	Location块组件
Upstream	Upstream块组件
UpstreamServer	Upstream中的server指令
LuaBlock	Lua代码块组件

nginx_detector.py - Nginx探测器

函数	说明
ng_detect(only_running)	获取所有Nginx实例
ng_detect_by_bin(bin_path)	通过可执行文件路径获取实例

site_detector.py - 站点检测器

类/函数	说明
SiteInfo	站点信息数据类（server_names, listen_ports, site_type, server_blocks）
SiteDetector	站点检测器类
site_detector(config)	检测并分类所有站点配置

extension/config.py - 配置工具

类	说明
ConfigTools	配置基础工具（获取主server、导出字符串）
ConfigFinder	配置查找工具（查找域名、端口、IP限制等）

extension/server.py - Server块工具

类	说明
ServerTools	Server块操作工具（设置SSL端口、移除域名等）

---

七、完整工作流程

# 1. 探测Nginx实例
from mod.base.pynginx.btnginx.nginx_detector import ng_detect
nginx_instances = ng_detect(only_running=True)

if not nginx_instances:
    print("未找到运行中的Nginx实例")
    exit()

nginx_ins = nginx_instances[0]

# 2. 解析配置文件
from mod.base.pynginx.btnginx.bt_formater import bt_nginx_format

# 3. 格式化为面板兼容配置
result = bt_nginx_format(nginx_ins)

# 4. 查看识别到的站点
for site in result['site_conf']:
    print(f"站点: {site['name']}")
    print(f"  类型: {site['site_type']}")
    print(f"  域名: {site['domains']}")
    print(f"  端口: {site['ports']}")

# 5. 在面板中创建站点
from mod.base.pynginx.btnginx.create_site import CreateSiteUtil
util = CreateSiteUtil(result['tmp_path'])

for site in result['site_conf']:
    if site['site_type'] == 'PHP':
        util.create_php_site(site)
    elif site['site_type'] == 'proxy':
        util.create_proxy_site(site)
    else:
        util.create_static_site(site)

---

八、注意事项

1. 路径解析：解析include文件时需指定main_config_path参数，否则相对路径无法正确解析。
2. Lua块支持：支持*_by_lua_block指令的解析和格式化。
3. 注释保留：默认保留指令前1行注释，可通过comment_line_count参数调整。
4. 配置验证：探测器会执行nginx -t验证配置有效性。