Kamixitong/docs/BT_PANEL_DEPLOYMENT.md

# KaMiXiTong系统宝塔面板部署完整文档

## 一、准备工作

### 1. 环境要求
- 服务器：Linux系统（推荐CentOS 7.x或Ubuntu 18.04以上）
- 宝塔面板：7.0以上版本
- Python版本：3.7以上
- MySQL版本：5.7或8.0

### 2. 本地准备
1. 确保项目代码完整，包含以下关键文件：
   - `.env` 配置文件
   - `requirements.txt` 依赖文件
   - `kamaxitong_nginx.conf` Nginx配置文件
   - 数据库初始化脚本 `init_mysql.sql`

2. 将项目代码打包为zip文件，便于上传

## 二、宝塔面板基础环境配置

### 1. 安装宝塔面板
```bash
# CentOS系统安装命令
yum install -y wget && wget -O install.sh http://download.bt.cn/install/install_6.0.sh && sh install.sh

# Ubuntu/Debian系统安装命令
wget -O install.sh http://download.bt.cn/install/install-ubuntu_6.0.sh && sudo bash install.sh
```

安装完成后，会显示面板地址、用户名和密码，请妥善保存。

### 2. 安装必要软件
登录宝塔面板后，安装以下软件：
1. Nginx（推荐1.18或以上版本）
2. MySQL（推荐5.7或8.0版本）
3. Python项目管理器

安装步骤：
1. 点击左侧菜单"软件商店"
2. 搜索相应软件并点击安装
3. 保持默认配置，点击"一键安装"

## 三、服务器环境配置

### 1. 创建网站目录
1. 在宝塔面板中点击左侧菜单"文件"
2. 进入目录`/www/wwwroot`
3. 点击"新建目录"，输入目录名`kamaxitong`
4. 点击"确定"完成创建

### 2. 上传项目文件
1. 在`/www/wwwroot/kamaxitong`目录下点击"上传"
2. 选择本地打包好的项目zip文件
3. 上传完成后点击文件名，在右侧操作栏点击"解压"
4. 解压到当前目录

### 3. 安装Python环境
1. 在宝塔面板中点击左侧菜单"软件商店"
2. 搜索"Python项目管理器"并安装
3. 安装完成后点击"设置"
4. 在Python版本管理中安装Python 3.7或更高版本

## 四、数据库配置

### 1. 创建数据库
1. 在宝塔面板中点击左侧菜单"数据库"
2. 点击"添加数据库"
3. 填写以下信息：
   - 数据库名：`kamaxitong`
   - 用户名：`kamaxitong`（可自定义）
   - 密码：设置复杂密码并妥善保存
   - 访问权限：本地服务器（localhost）
4. 点击"提交"完成创建

### 2. 导入数据库结构
1. 在数据库列表中找到`kamaxitong`数据库
2. 点击"导入"按钮
3. 点击"从本地上传"，选择项目中的`init_mysql.sql`文件
4. 点击"开始上传"
5. 上传完成后点击"执行"导入数据库结构

## 五、项目配置

### 1. 配置环境变量
1. 在宝塔面板中点击左侧菜单"文件"
2. 进入目录`/www/wwwroot/kamaxitong`
3. 找到`.env`文件并点击编辑
4. 修改以下关键配置项：
```bash
# 数据库配置（根据实际创建的数据库信息修改）
DATABASE_URL=mysql+pymysql://kamaxitong:您设置的密码@localhost:3306/kamaxitong

# Flask环境
FLASK_ENV=production
FLASK_DEBUG=False

# 安全配置（请修改为复杂密码）
SECRET_KEY=your-complex-secret-key-here
AUTH_SECRET_KEY=your-auth-validator-secret-key

# 域名配置（根据实际情况修改）
FRONTEND_DOMAIN=http://your-domain.com

# 服务器配置
HOST=127.0.0.1
PORT=5000

# 日志配置
LOG_LEVEL=INFO
LOG_FILE=logs/kamaxitong.log
```

### 2. 安装Python依赖
1. 在宝塔面板中点击左侧菜单"终端"
2. 执行以下命令进入项目目录：
```bash
cd /www/wwwroot/kamaxitong
```

3. 安装项目依赖：
```bash
pip install -r requirements.txt
```

如果遇到网络问题，可以使用国内镜像源：
```bash
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 3. 初始化数据库
在项目根目录执行数据库初始化：
```bash
python -c "
import os
os.environ['FLASK_ENV'] = 'production'
from app import create_app, db
app = create_app()
with app.app_context():
    db.create_all()
    print('数据库表创建完成')
"
```

## 六、配置Python项目

### 1. 添加Python项目
1. 在宝塔面板中点击左侧菜单"网站"
2. 选择顶部标签"Python项目"
3. 点击"添加项目"
4. 填写以下信息：
   - 项目路径：`/www/wwwroot/kamaxitong`
   - 项目名称：`kamaxitong`
   - 运行文件：`run.py`
   - 项目端口：`5000`
   - Python版本：选择已安装的Python版本（如Python 3.7）
   - 框架：Flask
   - 运行方式：Gunicorn
   - 进程数：2（可根据服务器配置调整）
   - 线程数：4
   - 启动用户：www
   - 通信方式：Http
   - 安装依赖包：勾选（自动检测requirements.txt）

5. 点击"提交"完成项目创建

### 2. 配置项目参数
1. 在Python项目列表中找到刚创建的项目
2. 点击项目名称进入项目详情
3. 点击"配置文件"标签
4. 修改以下配置：
   - server_name：填写您的域名或服务器IP
   - root：填写项目根路径`/www/wwwroot/kamaxitong`

5. 点击"运行配置"标签
6. 在配置文本框中添加以下配置：
```ini
buffer-size=65536
callable=app
```

7. 点击"域名管理"标签
8. 添加域名：`your-domain.com:5000`（根据实际情况修改）
9. 点击"外网映射"开关，确保处于开启状态

## 七、Nginx配置

### 1. 创建网站
1. 在宝塔面板中点击左侧菜单"网站"
2. 点击"添加站点"
3. 填写以下信息：
   - 域名：填写您的域名（如km.yourdomain.com）
   - 备注：KaMiXiTong系统
   - 根目录：`/www/wwwroot/kamaxitong`
   - FTP：不创建
   - 数据库：不创建
   - 程序类型：PHP（暂时选择，后续会修改）

4. 点击"提交"完成站点创建

### 2. 配置反向代理
1. 在网站列表中找到刚创建的站点
2. 点击站点名称进入站点设置
3. 点击"反向代理"选项卡
4. 点击"添加反向代理"
5. 填写以下信息：
   - 代理名称：kamaxitong
   - 目标URL：http://127.0.0.1:5000
   - 发送域名：$host
   - 内容替换：不启用

6. 点击"提交"完成反向代理配置

### 3. 配置静态文件
1. 在站点设置中点击"配置文件"选项卡
2. 在server块中添加静态文件处理配置：
```nginx
# 静态文件直接由Nginx处理
location /static/ {
    alias /www/wwwroot/kamaxitong/static/;
    expires 1y;
    add_header Cache-Control "public, immutable";
    add_header Access-Control-Allow-Origin "*";
}

# 上传文件处理
location /static/uploads/ {
    alias /www/wwwroot/kamaxitong/static/uploads/;
    expires 1d;
    add_header Cache-Control "public";
}
```

3. 点击"保存"应用配置

## 八、安全配置

### 1. 放行端口
1. 在宝塔面板中点击左侧菜单"安全"
2. 点击"防火墙"选项卡
3. 点击"放行端口"
4. 添加以下端口：
   - 端口：5000
   - 备注：KaMiXiTong应用端口
   - 授权IP：默认（允许所有IP）

5. 点击"保存"

### 2. 服务器安全组
在云服务器控制台的安全组中放行以下端口：
- 80 (HTTP)
- 443 (HTTPS)
- 5000 (应用端口)
- 22 (SSH，如果需要)

配置步骤（以阿里云为例）：
1. 登录云服务器控制台
2. 找到安全组管理
3. 选择对应实例的安全组
4. 点击"配置规则"
5. 点击"添加安全组规则"
6. 添加规则：
   - 授权策略：允许
   - 协议类型：TCP
   - 端口范围：80/80
   - 授权对象：0.0.0.0/0

重复以上步骤添加443和5000端口。

## 九、启动服务

### 1. 启动Python项目
1. 在宝塔面板中点击左侧菜单"网站"
2. 选择顶部标签"Python项目"
3. 找到kamaxitong项目
4. 点击右侧"启动"按钮

等待项目启动完成，状态显示为"运行中"。

### 2. 重启Nginx
1. 在宝塔面板中点击左侧菜单"软件商店"
2. 找到Nginx服务
3. 点击"重启"按钮

### 3. 测试服务
在终端中执行以下命令测试服务是否正常：
```bash
curl -I http://localhost:5000
```

应该返回200状态码表示服务正常运行。

## 十、验证部署

### 1. 访问测试
通过浏览器访问您的域名：
1. 打开浏览器，输入您的域名（如http://km.yourdomain.com）
2. 检查以下内容：
   - 网站首页正常显示
   - 页面样式和图片正常加载
   - 导航链接可正常点击

### 2. 管理后台测试
1. 访问管理后台登录页面：http://km.yourdomain.com/admin
2. 使用默认账号登录：
   - 用户名：admin
   - 密码：admin123
3. 检查登录是否成功

### 3. API接口测试
1. 访问API文档页面：http://km.yourdomain.com/docs
2. 测试几个关键API接口：
   - 产品列表接口
   - 卡密验证接口

## 十一、常见问题及解决方案

### 1. 502 Bad Gateway错误
**问题原因**：Python项目未正常启动或端口配置错误

**解决方案**：
1. 检查Python项目状态：
   - 在宝塔面板"网站"->"Python项目"中查看项目状态
   - 如果未启动，点击"启动"按钮

2. 检查端口配置：
   - 确认项目配置中的端口为5000
   - 确认Nginx反向代理目标URL为http://127.0.0.1:5000

3. 查看项目日志：
   - 在Python项目详情中点击"日志"标签
   - 查看是否有错误信息

### 2. 数据库连接失败
**问题原因**：数据库配置错误或权限不足

**解决方案**：
1. 检查数据库配置：
   - 确认.env文件中DATABASE_URL配置正确
   - 确认用户名、密码、数据库名无误

2. 检查数据库权限：
   - 在宝塔面板"数据库"中检查用户权限
   - 确认用户可以从localhost访问数据库

3. 测试数据库连接：
   ```bash
   cd /www/wwwroot/kamaxitong
   python -c "
   import os
   os.environ['FLASK_ENV'] = 'production'
   from app import create_app, db
   app = create_app()
   with app.app_context():
       try:
           db.engine.execute('SELECT 1')
           print('数据库连接成功')
       except Exception as e:
           print(f'数据库连接失败: {e}')
   "
   ```

### 3. 静态文件无法访问
**问题原因**：Nginx静态文件配置错误

**解决方案**：
1. 检查Nginx配置：
   - 确认location /static/配置正确
   - 确认路径指向正确的static目录

2. 检查文件权限：
   ```bash
   chmod -R 755 /www/wwwroot/kamaxitong/static
   ```

### 4. 域名无法访问
**问题原因**：DNS解析或防火墙问题

**解决方案**：
1. 检查DNS解析：
   ```bash
   nslookup your-domain.com
   ```

2. 检查防火墙设置：
   - 确认宝塔面板安全设置中放行了相应端口
   - 确认云服务器安全组放行了80和443端口

## 十二、维护管理

### 1. 日常维护
1. 定期备份数据库：
   ```bash
   # 在宝塔面板"数据库"中点击备份按钮
   # 或使用命令行备份
   mysqldump -u kamaxitong -p kamaxitong > /backup/kamaxitong_$(date +%Y%m%d).sql
   ```

2. 监控系统日志：
   - 定期查看Python项目日志
   - 查看Nginx访问日志和错误日志

3. 更新安全补丁：
   - 定期更新系统安全补丁
   - 更新Python依赖包

### 2. 性能优化
1. 根据访问量调整Gunicorn工作进程数：
   - 在Python项目配置中调整进程数
   - 一般设置为CPU核心数的1-2倍

2. 配置Redis缓存（如需要）：
   - 在宝塔面板中安装Redis
   - 修改项目配置启用缓存

### 3. 故障排查
1. 查看Python项目日志：
   - 在宝塔面板Python项目详情中查看日志
   - 或查看logs目录下的日志文件

2. 检查Nginx错误日志：
   - 在宝塔面板"网站"->站点设置->日志中查看

3. 检查系统资源使用情况：
   - 在宝塔面板首页查看CPU、内存、磁盘使用情况
   - 使用top或htop命令查看进程资源占用