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`

### 使用示例
```python
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`）解析。

### 使用示例
```python
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)
```

### 指令查找
```python
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 规则）。

### 使用示例
```python
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关联配置等
   - 结构重组：按规范顺序组织配置

### 使用示例
```python
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端口、移除域名等） |

---

## 七、完整工作流程

```python
# 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`验证配置有效性。