# 宝塔面板 Nginx 接管本机已装 Nginx

> 通过宝塔面板（BT Panel）Nginx 接管功能，将本机通过其他方式（源码 / yum / apt）安装的 Nginx 服务纳入面板管理，实现配置可视化、站点统一运维与插件免重装。

# Nginx 接管

本文将指导您通过面板的 Nginx 接管功能，轻松接管本机通过其他方式（如源码编译、yum/apt 命令安装、手动解压部署等）搭建的 Nginx 服务，实现面板统一管理，无需重新部署服务、不影响原有业务运行。

## 功能介绍

> 该功能为面板 v11.6 版本新增特性

核心作用：统一管控本机**非面板安装**的 Nginx 服务，无需卸载原有服务、无需修改网站配置，通过自动解析原生配置文件完成接管。

接管后可在面板实现全功能管理：

- Nginx 配置编辑、服务启停/重启
- 实时状态监控、日志在线查看
- 版本平滑升级、扩展模块管理

完美解决多方式部署 Nginx 导致的**管理分散、操作繁琐、配置冲突混乱**等问题，适用于所有已部署 Nginx 且需要统一面板管理的场景。

## 操作步骤

### 环境说明

- 操作系统：Debian 12
- Nginx 安装方式：apt 命令安装
- Nginx 原有版本：v1.22.1

站点访问截图：

![站点访问截图](https://docs.bt.cn/img/practical-tutorials/nginx-takeover/image-20260313005949576.png)

### 接管详细步骤

1. 安装面板。

   安装过程中检测到现有 Web 环境时，输入 `yes` 执行强制安装。

   > ⚠️ 重要提醒：强制安装存在一定风险，**接管前务必创建服务器快照**备份！

   ![安装面板时检测到现有 Web 环境](https://docs.bt.cn/img/practical-tutorials/nginx-takeover/image-20260313010418309.png)

2. 面板安装完成后，通过服务器外网 IP 访问面板并登录。

3. 登录后忽略【安装 LNMP 环境】提示，点击右上角关闭按钮。

   ![忽略安装 LNMP 环境提示](https://docs.bt.cn/img/practical-tutorials/nginx-takeover/image-20260313011111031.png)

4. 点击左侧菜单栏【网站】，选择【接管本地 nginx】。

   ![选择接管本地 nginx](https://docs.bt.cn/img/practical-tutorials/nginx-takeover/image-20260313011223130.png)

5. 在列表中选择本地已安装的 Nginx v1.22.1 版本。

   ![选择本地已安装的 Nginx 版本](https://docs.bt.cn/img/practical-tutorials/nginx-takeover/image-20260313011405940.png)

6. 点击【安装 nginx】。

   ![点击安装 nginx](https://docs.bt.cn/img/practical-tutorials/nginx-takeover/image-20260313011443114.png)

7. 根据需求选择目标版本及安装方式，此处选择 1.28.1 版本进行安装。

   > ✅ 推荐选择**编译模式**，业务运行更稳定。

   ![选择目标版本及安装方式](https://docs.bt.cn/img/practical-tutorials/nginx-takeover/image-20260313011647687.png)

8. 等待安装完成，面板会自动解析原有所有站点配置。

   ![面板自动解析站点配置](https://docs.bt.cn/img/practical-tutorials/nginx-takeover/image-20260313011843728.png)

9. 选择需要接管的网站，点击【保存选中网站】。

   ![保存选中网站](https://docs.bt.cn/img/practical-tutorials/nginx-takeover/image-20260313011959515.png)

10. 配置保存完成后，检查面板 Nginx 状态是否正常。若状态为关闭，需在终端手动停止系统中原有的 Nginx 服务，以避免端口冲突。

    > 也可手动修改端口后再启动。

    ```bash
    # 停止系统安装的 Nginx
    systemctl stop nginx
    # 检查是否还有残留进程
    ps aux | grep nginx
    # 如仍有残留进程，执行以下命令强制终止
    pkill -9 nginx
    ```

11. 返回面板，手动启动 Nginx 服务。

    ![手动启动 Nginx 服务](https://docs.bt.cn/img/practical-tutorials/nginx-takeover/image-20260313012609216.png)

12. 启动成功后，在【HTML 项目】中可以看到已接管的网站。

    ![HTML 项目中显示接管的网站](https://docs.bt.cn/img/practical-tutorials/nginx-takeover/image-20260313012736249.png)

13. 查看接管日志。

    ![接管日志](https://docs.bt.cn/img/practical-tutorials/nginx-takeover/image-20260313014500179.png)

## 常见问题

### 接管失败后，手动执行接管脚本进行接管

除通过面板可视化接管外，也可手动执行接管脚本。脚本为交互式操作，简单易上手。

**接管脚本使用方法：**

```bash
# 脚本执行命令
btpython /www/server/panel/script/nginx_site_helper.py

# 以下为操作示例
root@iZbp1ddiqohvy9r97sspwaZ:~# btpython /www/server/panel/script/nginx_site_helper.py
====================
[1] version: nginx/1.28.1
    nginx-bin: /www/server/nginx/sbin/nginx
    config-file:/www/server/nginx/conf/nginx.conf
    work-path:/www/server/nginx
--------------------
[2] version: nginx/1.22.1
    nginx-bin: /usr/sbin/nginx
    config-file:/etc/nginx/nginx.conf
    work-path:/usr/share/nginx
====================
请选择nginx实例(1-2/quit/q):2
配置/etc/nginx/nginx.conf中，共解析到1个网站
====================
[1] 网站类型：html      网站名称：8.136.211.123
域名：8.136.211.123
网站目录：/home/8.136.211.123
====================
是否保存以上配置(y/n):y
网站:[8.136.211.123]，保存成功
```

**脚本其他使用方法：**

1. 脚本未检测到 Nginx 时，或多版本 Nginx 共存的场景，先获取 Nginx 可执行文件的绝对路径，再指定路径执行接管：

   ```bash
   which nginx
   # 示例输出
   /usr/sbin/nginx

   # 执行脚本，指定路径接管
   btpython /www/server/panel/script/nginx_site_helper.py -b /usr/sbin/nginx
   ```

2. 恢复原生配置（撤销接管）：

   ```bash
   btpython /www/server/panel/script/nginx_site_helper.py recovery
   ```

3. 查看接管脚本帮助：

   ```bash
   btpython /www/server/panel/script/nginx_site_helper.py -h
   ```