# qnbt宝塔主机管理系统

**Repository Path**: zhuxiaohuaqn/qnbt

## Basic Information

- **Project Name**: qnbt宝塔主机管理系统
- **Description**: 本项目是一个基于宝塔控制面板 API 进行二次开发的虚拟主机系统。通过对宝塔控制面板 API 的调用和集成，我们实现了一个功能强大、易于使用的虚拟主机管理系统。
该系统提供了一个直观的用户界面，使你能够轻松地管理虚拟主机。你可以创建、配置、启停和删除虚拟主机，还可以进行文件管理、数据库管理、FTP 管理等操作。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://www.qingningz.cn/
- **GVP Project**: No

## Statistics

- **Stars**: 12
- **Forks**: 1
- **Created**: 2023-11-24
- **Last Updated**: 2026-01-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 宝塔主机

## README

<div align="center">

<br/>
<br/>

  <h1 align="center">
    🏠 QnBt 宝塔主机面板
  </h1>
  <h4 align="center">
    🚀 现代化的宝塔虚拟主机管理面板 ✨
  </h4> 

  [🌐 官方网站](https://qn.zlovey.cn/)  |  [📝 技术博客](https://www.qingningz.cn/)  |  [🐛 问题反馈](https://gitee.com/zhuxiaohuaqn/qnbt/issues)

  <br>

  ![Python](https://img.shields.io/badge/Python-3.10.2+-blue?style=for-the-badge&logo=python&logoColor=white)
  ![Flask](https://img.shields.io/badge/Flask-3.0.0-green?style=for-the-badge&logo=flask&logoColor=white)
  ![UV](https://img.shields.io/badge/UV-Package%20Manager-purple?style=for-the-badge&logo=python)
  ![Docker](https://img.shields.io/badge/Docker-Container-blue?style=for-the-badge&logo=docker&logoColor=white)
  ![License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)
  ![Status](https://img.shields.io/badge/Status-Active-brightgreen?style=for-the-badge)

</div>

<br>

<div align="center">
  <img width="92%" style="border-radius:10px;margin-top:20px;margin-bottom:20px;box-shadow: 2px 0 6px gray;" src="https://gitee.com/zhuxiaohuaqn/qnbt/raw/master/static/image/%E9%A6%96%E9%A1%B5.png" />
</div>

<br>

## 📋 项目介绍

**QnBt** 是一个基于宝塔控制面板 API 二次开发的现代化虚拟主机管理系统。通过深度集成宝塔控制面板 API，我们打造了一个功能强大、界面友好、操作简便的虚拟主机管理平台。


<div align="center">
  
### 🎯 演示环境配置
  
| 项目 | 配置 |
|------|------|
| 🌐 **访问地址** | [http://qnbt.zlovey.cn/](http://qnbt.zlovey.cn/) |
| 👤 **登录账号** | `admin` |
| 🔑 **登录密码** | `123456` |
| ⚙️ **面板版本** | 宝塔Linux面板 7.9 |
| 🐍 **Python版本** | 3.10.2 |
| 📦 **部署方式** | Docker + Gunicorn |


</div>

### ✨ 核心特性

- 🎯 **简化管理流程** - 提供直观的用户界面，让虚拟主机管理变得简单高效
- 🔧 **功能丰富** - 支持虚拟主机的创建、配置、启停、删除等全生命周期管理
- 📁 **文件管理** - 集成强大的文件管理器，支持在线编辑、上传下载
- 🗄️ **数据库管理** - 便捷的数据库创建、配置和管理功能
- 🔐 **安全可靠** - 完善的权限管理和安全控制机制
- 🎨 **现代化UI** - 基于 Bootstrap 和 layui 的响应式设计

### 🛠️ 主要功能模块

| 功能模块 | 描述 | 状态 |
|---------|------|------|
| 📁 **文件管理** | 支持文件上传、下载、在线编辑 | ✅ 完成 |
| 🗄️ **数据库管理** | 数据库的创建、配置和管理 | ✅ 完成 |
| 🌐 **DNS 管理** | 域名解析配置 | ✅ 完成 |
| 🔒 **SSL 管理** | SSL 证书的申请与配置 | ✅ 完成 |
| 📊 **流量统计** | 虚拟主机的流量监控与统计 | ✅ 完成 |
| 🚀 **一键部署** | 支持一键部署虚拟主机 | ✅ 完成 
| 🔄 **反向代理** | 支持反向代理配置 | ✅ 完成 |

## ⚡ 快速开始

### 📋 环境要求

- 🐍 **Python** 3.10.2 或更高版本
- 🌐 **宝塔面板** 7.0 或更高版本
- 💾 **内存** 推荐 512MB 以上
- 💿 **存储** 推荐 1GB 以上可用空间

## 🔧 应用配置（重要：必须在运行项目前完成配置）

在 `user_config.py` 文件中配置以下参数（必须配置，负责无法登录）：

| 参数 | 说明 | 示例值 |
|------|------|--------|
| `bt_url` | 宝塔面板地址 | `http://1.14.103.227:8888` |
| `bt_key` | 宝塔API密钥 | `YXb5OfgP2Cplav3xmws4pbMVzjTW3rYv` |
| `bt_fife` | 网站目录路径 | `/www/wwwroot/aa.com/` |
| `bt_web` | 网站域名 | `aa.com` |
| `web_size` | 网站空间大小(MB) | `800` |
| `sql_size` | 数据库空间大小(MB) | `500` |
| `traffic_size` | 流量大小(MB) | `500` |
| `siteId` | 站点ID | `1` |
| `sql_pwd` | 数据库密码 | `123456` |

> ⚠️ **安全提醒**: 生产环境中应将 `user_config.py` 文件加入 `.gitignore`，避免敏感信息泄露。

### 🔧 宝塔面板配置

1. **获取 API 密钥**
   - 登录宝塔面板
   - 进入「面板设置」→「API接口」
   - 开启 API 接口并记录密钥

2. **配置 IP 白名单**
   - 在 API 接口页面添加服务器 IP
   - 确保网络连通性

## 🎯 UV 包管理器优势

| 特性 | UV | pip | 说明 |
|------|----|----|------|
| ⚡ **速度** | 10-100x 更快 | 基准速度 | 基于 Rust，并行下载和安装 |
| 🔒 **安全** | 内置锁定文件 | 需要额外工具 | 自动生成 `uv.lock` 文件 |
| 🎯 **解析** | 快速依赖解析 | 较慢的解析 | 高效的 SAT 求解器 |
| 📦 **缓存** | 智能缓存 | 基础缓存 | 全局包缓存，减少重复下载 |
| 🔄 **兼容性** | 完全兼容 pip | - | 支持 pip 所有功能 |

## 🚀 使用 UV 包管理器安装（推荐）

> UV 是一个超快的 Python 包管理器，基于 Rust 编写，比传统的 pip 快 10-100 倍！

#### 1️⃣ 安装 UV

**Windows (PowerShell):**
```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**macOS/Linux:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Linux 网络问题解决方案:**
```
# 如果官方安装失败，使用 pip + 国内镜像
pip3 install -i https://pypi.douban.com/simple/ uv

# 或手动下载安装
wget https://github.com/astral-sh/uv/releases/latest/download/uv-x86_64-unknown-linux-gnu.tar.gz
tar -xzf uv-x86_64-unknown-linux-gnu.tar.gz
sudo mv uv /usr/local/bin/ && chmod +x /usr/local/bin/uv
```

**使用 pip:**
```bash
pip install uv
```

#### 2️⃣ 克隆项目
```bash
git clone https://gitee.com/zhuxiaohuaqn/qnbt.git
cd qnbt
```

#### 3️⃣ 使用 UV 安装依赖
```bash
# 创建虚拟环境并安装依赖
uv venv

# 激活虚拟环境 (Windows)
.venv\Scripts\activate

# 激活虚拟环境 (macOS/Linux)
source .venv/bin/activate

# 同步依赖
uv sync
```

#### 4️⃣ 运行项目
```bash
# 使用 UV 运行
uv run python app.py

# 或在虚拟环境中运行
python app.py
```

### 📦 传统安装方式

<details>
<summary>点击展开传统安装方式</summary>

#### 使用 pip
```
# 克隆项目
git clone https://gitee.com/zhuxiaohuaqn/qnbt.git
cd qnbt

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 运行项目
python app.py
```

</details>

## 🐳 Docker 部署

<details>
<summary>点击展开 Docker 部署说明</summary>

### 🏗️ 构建镜像

```bash
# 克隆项目
git clone https://gitee.com/zhuxiaohuaqn/qnbt.git
cd qnbt

# 构建 Docker 镜像
docker build -t qnbt .
```

### ▶️ 运行容器

```bash
# 运行容器（默认端口 5000）
docker run -d -p 5000:5000 --name qnbt qnbt

# 运行容器（自定义端口）
docker run -d -p 8000:5000 --name qnbt qnbt

# 运行容器（挂载配置文件）
docker run -d -p 5000:5000 -v ./config.py:/app/config.py --name qnbt qnbt
```

### ⚙️ 环境变量配置

| 环境变量 | 默认值 | 描述 |
|---------|--------|------|
| `BT_PANEL_URL` | `http://localhost:8888` | 宝塔面板地址 |
| `BT_API_KEY` | `your-api-key` | 宝塔API密钥 |
| `FLASK_ENV` | `production` | 运行环境 |
| `WORKERS` | `4` | Gunicorn工作进程数 |

### 📊 Docker Compose 部署

创建 `docker-compose.yml` 文件：

```
version: '3.8'

services:
  qnbt:
    build: .
    container_name: qnbt
    ports:
      - "5000:5000"
    environment:
      - BT_PANEL_URL=http://your-panel-url:8888
      - BT_API_KEY=your-api-key
      - FLASK_ENV=production
    restart: unless-stopped
    volumes:
      - ./logs:/app/logs
```

运行命令：
```bash
docker-compose up -d
```

### 🔧 性能优化配置

Gunicorn 配置参数：
- **工作进程数**: 4个（可根据CPU核心数调整）
- **超时时间**: 120秒
- **Keep-Alive**: 5秒
- **请求重启**: 每1000个请求重启worker防止内存泄漏

### 🌐 反向代理配置

推荐使用 Nginx 作为反向代理：

```
server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
```

</details>

## 📱 项目结构

```
qnbt/
├── 📁 static/                 # 静态资源文件
│   ├── 📁 css/               # 样式文件
│   ├── 📁 js/                # JavaScript 文件
│   ├── 📁 codemirror/        # 代码编辑器
│   ├── 📁 layui/             # LayUI 组件
│   └── 📁 v5/                # Bootstrap 5 资源
├── 📁 templates/              # HTML 模板文件
│   ├── 📄 index.html         # 主页模板
│   ├── 📄 fife.html          # 文件管理模板
│   └── 📄 ...                # 其他模板
├── 📄 app.py                  # 主应用入口
├── 📄 pyproject.toml         # 项目配置文件
├── 📄 requirements.txt       # 依赖列表（兼容性保留）
├── 📄 uv.lock               # UV 锁定文件
└── 📄 README.md              # 项目文档
```

## 🎨 界面预览

### 主控制台
<div align="center">
  <img src="https://gitee.com/zhuxiaohuaqn/qnbt/raw/master/static/image/首页.png" alt="主控制台" width="80%">
</div>

### 文件管理
<div align="center">
  <img src="https://gitee.com/zhuxiaohuaqn/qnbt/raw/master/static/image/文件管理.png" alt="文件管理" width="80%">
</div>

### SSL证书管理
<div align="center">
  <img src="https://gitee.com/zhuxiaohuaqn/qnbt/raw/master/static/image/证书管理.png" alt=证书管理" width="80%">
</div>

### 常见问题

**Q: UV 安装失败？**
A: 请检查网络连接，或使用镜像源：
```bash
UV_INDEX_URL=https://pypi.douban.com/simple/ uv sync
```

**Q: 宝塔 API 连接失败？**
A: 检查以下几点：
- 确认 API 接口已开启
- 检查 IP 白名单设置
- 验证 API 密钥正确性
- 确认网络连通性

### 日志查看

```bash
# 查看应用日志
tail -f logs/app.log

# 查看错误日志
tail -f logs/error.log
```

## 📄 许可证

本项目基于 [MIT 许可证](LICENSE) 开源。

## 🙏 致谢

- [宝塔面板](https://www.bt.cn/) - 提供强大的服务器管理功能
- [Flask](https://flask.palletsprojects.com/) - 轻量级 Web 框架
- [Bootstrap](https://getbootstrap.com/) - 现代化 UI 框架
- [LayUI](https://layui.dev/) - 经典模块化前端框架
- [UV](https://github.com/astral-sh/uv) - 超快的 Python 包管理器

## 📞 联系我们

<div align="center">
  <h3>💬 加入我们的社区</h3>
  <img width="300px" style="border-radius:10px;margin:20px;box-shadow: 2px 0 6px gray;" src="https://gitee.com/zhuxiaohuaqn/qnbt/raw/master/static/image/QQ.png" />
  <br>
  <p>🎯 <strong>QQ交流群</strong> - 与开发者和用户直接交流</p>
</div>

---

<div align="center">
  <p>如果这个项目对您有帮助，请给我们一个 ⭐ Star！</p>
  <p>Made with ❤️ by QnBt Team</p>
</div>