Kamixitong/DEPLOYMENT.md

# KaMiXiTong 软件授权管理系统 - MySQL 部署指南

📖 **本指南专为小白用户设计，一步一步教你如何部署 KaMiXiTong 系统**

## 📋 目录

1. [系统要求](#系统要求)
2. [MySQL 数据库安装](#mysql-数据库安装)
3. [Python 环境配置](#python-环境配置)
4. [项目部署](#项目部署)
5. [启动服务](#启动服务)
6. [常见问题解决](#常见问题解决)
7. [维护与管理](#维护与管理)
8. [前端域名配置](#前端域名配置-1)

---

## 🔧 系统要求

### 操作系统支持
- ✅ Windows 10/11
- ✅ Windows Server 2016/2019/2022
- ✅ Ubuntu 18.04/20.04/22.04
- ✅ CentOS 7/8
- ✅ macOS 10.15+

### 硬件要求
- **内存**: 最少 2GB，推荐 4GB+
- **硬盘**: 最少 5GB 可用空间
- **网络**: 能够连接互联网（下载依赖包）

---

## 🗄️ MySQL 数据库安装

### Windows 系统安装 MySQL

#### 方法一：使用官方安装包（推荐新手）

1. **下载 MySQL**
   ```
   访问官网：https://dev.mysql.com/downloads/mysql/
   选择：MySQL Community Server
   下载：Windows (x86, 64-bit), MSI Installer
   ```

2. **安装步骤**
   - 双击下载的 `.msi` 文件
   - 选择 "Developer Default" 开发者默认配置
   - 点击 "Execute" 执行安装
   - 配置 root 密码（请记住这个密码！）
   - 启动 MySQL 服务

3. **验证安装**
   ```cmd
   # 打开命令提示符，输入：
   mysql --version
   # 应该显示版本信息
   ```

#### 方法二：使用 XAMPP（简单快捷）

1. **下载 XAMPP**
   ```
   访问官网：https://www.apachefriends.org/
   下载适合你系统的 XAMPP 版本
   ```

2. **安装和启动**
   - 安装 XAMPP（一路下一步即可）
   - 打开 XAMPP 控制面板
   - 启动 MySQL 和 Apache 服务

### Ubuntu 系统安装 MySQL

```bash
# 更新软件包列表
sudo apt update

# 安装 MySQL 服务器
sudo apt install mysql-server -y

# 安全配置
sudo mysql_secure_installation

# 启动 MySQL 服务
sudo systemctl start mysql
sudo systemctl enable mysql
```

### CentOS 系统安装 MySQL

```bash
# 下载 MySQL 仓库
sudo yum localinstall https://dev.mysql.com/get/mysql80-community-release-el7-3.noarch.rpm

# 安装 MySQL
sudo yum install mysql-community-server -y

# 启动 MySQL 服务
sudo systemctl start mysqld
sudo systemctl enable mysqld

# 查看临时密码
sudo grep 'temporary password' /var/log/mysqld.log
```

---

## 🐍 Python 环境配置

### 检查 Python 版本

```bash
# 检查 Python 版本（需要 3.7+）
python --version
# 或者
python3 --version

# 如果没有安装 Python，请访问 https://www.python.org/downloads/
```

### 安装项目依赖

#### 方法一：使用自动安装脚本（推荐新手）

```bash
# 进入项目目录
cd /path/to/KaMiXiTong

# 运行自动安装脚本
python install_deps.py
```

#### 方法二：手动安装

```bash
# 进入项目目录
cd /path/to/KaMiXiTong

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

**如果安装过程中遇到错误，试试这个：**
```bash
# 升级 pip
pip install --upgrade pip

# 重新安装依赖
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/

# 如果还是有问题，尝试单独安装关键依赖
pip install cryptography==41.0.4
pip install Flask==2.3.3
pip install Flask-SQLAlchemy==3.0.5
pip install PyMySQL==1.1.0
```

---

## 🚀 项目部署

### 第一步：配置数据库连接

1. **找到配置文件**
   ```
   在项目根目录找到 .env 文件
   如果没有，复制 .env.example 为 .env
   ```

2. **编辑数据库配置**
   ```bash
   # 用记事本或编辑器打开 .env 文件
   # 找到这一行：
   DATABASE_URL=mysql+pymysql://root:taiyi1224@localhost/kamaxitong

   # 修改为你的 MySQL 信息：
   # 格式：mysql+pymysql://用户名:密码@主机地址/数据库名
   ```

3. **配置说明**
   - `root`：MySQL 用户名
   - `taiyi1224`：MySQL 密码（替换成你自己的密码）
   - `localhost`：数据库地址（本地部署就用 localhost）
   - `kamaxitong`：数据库名称

### 第二步：配置前端域名（可选但推荐）

1. **为什么要配置前端域名**
   在本地开发环境中，系统默认通过 `http://localhost:5000` 访问。当部署到服务器并通过域名访问时，如果不配置前端域名，前端页面中的接口调用可能会仍然指向 `localhost:5000`，导致接口调用失败。

2. **配置方法**
   在 `.env` 文件中添加或修改以下配置：
   ```bash
   # 前端域名配置
   FRONTEND_DOMAIN=https://your-domain.com
   ```
   
   或者通过管理后台配置：
   - 登录系统管理后台
   - 进入"系统设置"页面
   - 在"基本设置"中找到"前端域名"配置项
   - 输入你的域名，例如：`https://your-domain.com`
   - 点击"保存设置"

   > 注意：如果两种方式都配置了，环境变量的优先级更高。

### 第二步：创建数据库

#### 方法一：使用命令行（推荐）

```bash
# 登录 MySQL
mysql -u root -p

# 输入密码后，创建数据库
CREATE DATABASE kamaxitong CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 查看数据库是否创建成功
SHOW DATABASES;

# 退出 MySQL
EXIT;
```

#### 方法二：使用图形界面工具

**phpMyAdmin 用户：**
1. 打开 phpMyAdmin 网页界面
2. 点击 "新建数据库"
3. 数据库名称：`kamaxitong`
4. 排序规则：`utf8mb4_unicode_ci`
5. 点击创建

**Navicat 用户：**
1. 连接到 MySQL 服务器
2. 右键点击连接，选择 "新建数据库"
3. 输入数据库名：`kamaxitong`
4. 字符集选择：`utf8mb4`
5. 排序规则选择：`utf8mb4_unicode_ci`

### 第三步：测试数据库连接

```bash
# 在项目目录下运行测试
python -c "
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}')
"
```

### 第四步：初始化数据库

```bash
# 运行数据库初始化脚本
python init_db.py
```

**如果成功，你会看到类似这样的输出：**
```
==================================================
KaMiXiTong 数据库初始化开始...
==================================================
1. 清理现有数据库表...
   ✓ 已删除所有现有表

2. 创建数据库表结构...
   ✓ 已创建所有数据表

3. 插入初始数据...
   创建默认管理员账号...
   ✓ 已创建管理员账号 (admin/admin123, test_admin/test123)
   创建示例产品...
   ✓ 已创建3个示例产品
   创建版本信息...
   ✓ 已创建6个版本信息
   创建示例许可证...
   ✓ 已创建6个示例许可证
   创建示例设备...
   ✓ 已创建6个示例设备
   创建示例工单...
   ✓ 已创建5个示例工单
   ✓ 所有初始数据插入完成

4. 数据库初始化完成！

==================================================
数据库初始化信息统计
==================================================
  管理员账号 :   2 条记录
  产品       :   3 条记录
  版本       :   6 条记录
  许可证     :   6 条记录
  设备       :   6 条记录
  工单       :   5 条记录

==================================================
默认登录信息
==================================================
  超级管理员: admin / admin123
  普通管理员: test_admin / test123
```

---

## 🌟 启动服务

### 开发模式启动（测试用）

```bash
# 方法一：使用 run.py
python run.py

# 方法二：使用 start.py
python start.py

# 方法三：直接启动 Flask
flask run
```

**启动成功后，访问：**
- 网页界面：http://localhost:5000
- 管理后台：http://localhost:5000

### 生产模式启动（正式部署）

```bash
# 使用 Gunicorn 启动（推荐）
gunicorn -w 4 -b 0.0.0.0:5000 run:app

# 或者使用 start.py（如果配置了生产模式）
python start.py
```

**参数说明：**
- `-w 4`：启动 4 个工作进程
- `-b 0.0.0.0:5000`：绑定到所有网络接口的 5000 端口

---

## 🔧 常见问题解决

### 问题 1：数据库连接失败

**错误信息：**
```
sqlalchemy.exc.OperationalError: (pymysql.err.OperationalError) (2003, "Can't connect to MySQL server")
```

**解决方案：**
1. **检查 MySQL 服务是否启动**
   ```bash
   # Windows
   net start mysql

   # Linux
   sudo systemctl status mysql
   sudo systemctl start mysql
   ```

2. **检查用户名和密码**
   ```bash
   # 测试连接
   mysql -u root -p
   ```

3. **检查防火墙设置**
   - 确保 3306 端口没有被防火墙阻止

### 问题 2：权限不足

**错误信息：**
```
Access denied for user 'root'@'localhost'
```

**解决方案：**
```sql
-- 登录 MySQL 后执行
GRANT ALL PRIVILEGES ON *.* TO 'root'@'localhost' IDENTIFIED BY '你的密码' WITH GRANT OPTION;
FLUSH PRIVILEGES;
```

### 问题 3：端口被占用

**错误信息：**
```
Address already in use
```

**解决方案：**
```bash
# 查看端口占用
netstat -tulpn | grep :5000

# 或者修改端口
# 编辑 .env 文件，修改 PORT=5000 为其他端口
```

### 问题 4：依赖包安装失败

**解决方案：**
```bash
# 清理 pip 缓存
pip cache purge

# 使用国内镜像源
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/

# 如果还有问题，尝试逐个安装
pip install Flask==2.3.3
pip install Flask-SQLAlchemy==3.0.5
# ... 其他包
```

### 问题 5：依赖包安装失败

**错误信息：**
```
ModuleNotFoundError: No module named 'Crypto'
ImportError: cannot import name 'app' from 'app'
```

**解决方案：**
```bash
# 方法一：使用自动安装脚本
python install_deps.py

# 方法二：手动安装关键依赖
pip install cryptography==41.0.4

# 方法三：清理并重新安装
pip cache purge
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/

# 方法四：逐个安装关键包
pip install cryptography==41.0.4
pip install Flask==2.3.3
pip install Flask-SQLAlchemy==3.0.5
pip install Flask-Login==0.6.3
pip install PyMySQL==1.1.0
pip install python-dotenv==1.0.0
```

### 问题 6：中文字符乱码

**解决方案：**
```sql
-- 确保数据库使用正确的字符集
ALTER DATABASE kamaxitong CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

---

## 📊 维护与管理

### 备份数据库

```bash
# 完整备份
mysqldump -u root -p kamaxitong > backup_$(date +%Y%m%d_%H%M%S).sql

# 恢复数据库
mysql -u root -p kamaxitong < backup_file.sql
```

### 更新系统

```bash
# 1. 备份数据库
mysqldump -u root -p kamaxitong > backup_before_update.sql

# 2. 拉取最新代码（如果使用 Git）
git pull origin main

# 3. 更新依赖包
pip install -r requirements.txt --upgrade

# 4. 重新初始化数据库（谨慎操作）
python init_db.py
```

### 查看日志

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

# 查看 MySQL 错误日志
# Windows: C:\ProgramData\MySQL\MySQL Server 8.0\Data\
# Linux: /var/log/mysql/error.log
```

### 性能优化

1. **数据库优化**
   ```sql
   -- 创建索引
   CREATE INDEX idx_license_key ON license(license_key);
   CREATE INDEX idx_machine_code ON device(machine_code);
   ```

2. **应用优化**
   - 修改 `.env` 文件中的配置
   - 调整 `ITEMS_PER_PAGE` 控制分页大小
   - 设置合适的 `LOG_LEVEL`

---

## 📞 技术支持

如果以上步骤都遇到了问题，请提供以下信息：

1. **系统信息**
   - 操作系统版本
   - Python 版本
   - MySQL 版本

2. **错误信息**
   - 完整的错误日志
   - 执行的具体命令

3. **配置信息**
   - `.env` 文件内容（请隐藏密码）

---

## 前端域名配置

### 问题描述

在本地开发环境中，系统默认通过 `http://localhost:5000` 访问。当部署到服务器并通过域名访问时，前端页面中的接口调用可能会仍然指向 `localhost:5000`，导致接口调用失败。

### 解决方案

系统已通过修改前端JavaScript中的 `apiRequest` 函数来自动检测当前访问的主机并构建正确的API调用地址。现在还支持通过环境变量或管理后台配置前端域名。

前端JavaScript现在会使用配置的域名或 `window.location.origin` 来获取当前访问的完整域名，并自动构建完整的API URL。

### 配置方法

1. **通过环境变量配置（推荐）**
   在 `.env` 文件中添加：
   ```bash
   FRONTEND_DOMAIN=https://your-domain.com
   ```

2. **通过管理后台配置**
   - 登录系统管理后台
   - 进入"系统设置"页面
   - 在"基本设置"中找到"前端域名"配置项
   - 输入你的域名，例如：`https://your-domain.com`
   - 点击"保存设置"

### 验证配置

1. 在浏览器中打开应用，按F12打开开发者工具
2. 切换到Network标签页
3. 刷新页面，观察API请求的URL是否为域名地址而非localhost

## 🎉 部署完成！

恭喜你！如果以上步骤都成功执行，你的 KaMiXiTong 系统已经成功部署了！

**下一步操作：**
1. 访问 http://localhost:5000
2. 使用默认账号登录：`admin` / `admin123`
3. **立即修改默认密码！**
4. 开始配置你的产品和许可证

**温馨提示：**
- 生产环境请务必修改默认密码
- 定期备份数据库
- 保持系统和依赖包的更新

祝你使用愉快！ 🎊