# KaMiXiTong 部署文档

## 目录

- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [配置说明](#配置说明)
- [数据库配置](#数据库配置)
- [启动应用](#启动应用)
- [生产环境部署](#生产环境部署)
- [安全注意事项](#安全注意事项)
- [常见问题](#常见问题)

---

## 环境要求

### 系统要求

| 项目 | 最低要求 | 推荐配置 |
|------|----------|----------|
| 操作系统 | Linux/Windows/macOS | Ubuntu 22.04 LTS |
| Python | 3.9+ | 3.11+ |
| MySQL | 5.7+ | 8.0+ |
| 内存 | 512MB | 2GB+ |
| 磁盘 | 1GB | 10GB+ |

### 依赖服务

- **MySQL** - 主数据库
- **Redis** (可选) - 用于API限流和缓存
- **Nginx** (推荐) - 反向代理和静态文件服务

---

## 快速开始

### 1. 克隆代码

```bash
git clone <repository-url>
cd KaMiXiTong/master
```

### 2. 创建虚拟环境

```bash
# Linux/macOS
python3 -m venv venv
source venv/bin/activate

# Windows
python -m venv venv
venv\Scripts\activate
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 生成安全密钥

```bash
# 生成 SECRET_KEY
python -c "import secrets; print('SECRET_KEY=' + secrets.token_urlsafe(32))"

# 生成 AUTH_SECRET_KEY
python -c "import secrets; print('AUTH_SECRET_KEY=' + secrets.token_urlsafe(32))"
```

### 5. 创建配置文件

```bash
# 复制示例配置
cp .env.example .env

# 编辑配置文件
nano .env  # 或使用其他编辑器
```

### 6. 初始化数据库

```bash
# 创建数据库
mysql -u root -p -e "CREATE DATABASE kamixitong CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 导入初始结构
mysql -u root -p kamixitong < init_mysql.sql

# 初始化迁移（可选）
flask db upgrade
```

### 7. 启动应用

```bash
# 开发环境
python run.py

# 或使用 Flask CLI
flask run --host=0.0.0.0 --port=5088
```

访问 http://localhost:5088 进入系统。

---

## 配置说明

### 必需环境变量

以下环境变量**必须设置**，否则应用无法启动：

| 变量名 | 说明 | 示例 |
|--------|------|------|
| `SECRET_KEY` | Flask会话密钥 | `32位随机字符串` |
| `AUTH_SECRET_KEY` | API签名密钥 | `32位随机字符串` |
| `DB_PASSWORD` | 数据库密码 | `your-secure-password` |

### 完整配置文件示例

```bash
# .env 文件

# ==================== Flask 配置 ====================
FLASK_ENV=production
FLASK_DEBUG=False

# ==================== 数据库配置 ====================
# 方式一：使用完整URL
# DATABASE_URL=mysql+pymysql://user:password@localhost:3306/kamixitong?charset=utf8mb4

# 方式二：分离配置（推荐）
DB_HOST=localhost
DB_PORT=3306
DB_USER=kamixitong
DB_PASSWORD=your-secure-database-password
DB_NAME=kamixitong

# 连接池配置
DB_POOL_SIZE=10
DB_MAX_OVERFLOW=20
DB_POOL_RECYCLE=3600
DB_POOL_TIMEOUT=30

# ==================== 安全配置（必须设置） ====================
SECRET_KEY=your-32-character-secret-key-here
AUTH_SECRET_KEY=your-32-character-auth-key-here

# ==================== 域名配置 ====================
FRONTEND_DOMAIN=your-domain.com

# ==================== CORS配置 ====================
ALLOWED_ORIGINS=https://your-domain.com,https://www.your-domain.com

# ==================== 会话配置 ====================
SESSION_LIFETIME_HOURS=168
SESSION_COOKIE_SECURE=True
SESSION_COOKIE_HTTPONLY=True
SESSION_COOKIE_SAMESITE=Lax

# ==================== 记住我配置 ====================
REMEMBER_COOKIE_DURATION=30
REMEMBER_COOKIE_SECURE=True
REMEMBER_COOKIE_HTTPONLY=True
REMEMBER_COOKIE_SAMESITE=Lax

# ==================== 验证器配置 ====================
OFFLINE_CACHE_DAYS=7
MAX_FAILED_ATTEMPTS=5
LOCKOUT_MINUTES=10
MAX_UNBIND_TIMES=3

# ==================== 卡密配置 ====================
LICENSE_KEY_LENGTH=32
LICENSE_KEY_PREFIX=
TRIAL_PREFIX=TRIAL_

# ==================== API配置 ====================
API_VERSION=v1
ITEMS_PER_PAGE=20

# ==================== 文件上传配置 ====================
MAX_CONTENT_LENGTH=524288000
UPLOAD_FOLDER=static/uploads

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

# ==================== 支付配置（可选） ====================
PAYMENT_ENABLED=False
ALIPAY_APP_ID=
ALIPAY_PRIVATE_KEY=
ALIPAY_PUBLIC_KEY=
ALIPAY_NOTIFY_URL=
ALIPAY_RETURN_URL=

# ==================== Redis配置（可选） ====================
# REDIS_URL=redis://localhost:6379/0

# ==================== 调度器配置 ====================
DISABLE_SCHEDULER=False
```

---

## 数据库配置

### MySQL 配置优化

```sql
-- 创建数据库
CREATE DATABASE kamixitong 
    CHARACTER SET utf8mb4 
    COLLATE utf8mb4_unicode_ci;

-- 创建用户
CREATE USER 'kamixitong'@'%' IDENTIFIED BY 'your-secure-password';

-- 授权
GRANT ALL PRIVILEGES ON kamixitong.* TO 'kamixitong'@'%';
FLUSH PRIVILEGES;
```

### 数据库初始化

```bash
# 导入SQL结构
mysql -u kamixitong -p kamixitong < init_mysql.sql
```

### 数据库迁移

```bash
# 初始化迁移（首次）
flask db init

# 生成迁移脚本
flask db migrate -m "描述信息"

# 执行迁移
flask db upgrade
```

---

## 启动应用

### 开发环境

```bash
# 直接运行
python run.py

# 或使用 Flask CLI
flask run --host=0.0.0.0 --port=5088 --debug
```

### 生产环境

#### 方式一：Gunicorn（推荐）

```bash
# 安装 Gunicorn
pip install gunicorn

# 启动应用
gunicorn -w 4 -b 0.0.0.0:5088 --timeout 120 --access-logfile logs/access.log --error-logfile logs/error.log run:app
```

#### 方式二：uWSGI

```bash
# 安装 uWSGI
pip install uwsgi

# 创建配置文件 uwsgi.ini
[uwsgi]
module = run:app
master = true
processes = 4
socket = 0.0.0.0:5088
chmod-socket = 660
vacuum = true
die-on-term = true
logto = logs/uwsgi.log

# 启动
uwsgi --ini uwsgi.ini
```

#### 方式三：使用启动脚本

```bash
# 使用生产启动脚本
python run_production.py
```

### Systemd 服务配置

创建服务文件 `/etc/systemd/system/kamixitong.service`：

```ini
[Unit]
Description=KaMiXiTong Application
After=network.target mysql.service

[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/kamixitong
Environment="PATH=/var/www/kamixitong/venv/bin"
EnvironmentFile=/var/www/kamixitong/.env
ExecStart=/var/www/kamixitong/venv/bin/gunicorn -w 4 -b 127.0.0.1:5088 --timeout 120 run:app
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
# 启用服务
sudo systemctl daemon-reload
sudo systemctl enable kamixitong
sudo systemctl start kamixitong

# 查看状态
sudo systemctl status kamixitong
```

---

## 生产环境部署

### Nginx 配置

创建配置文件 `/etc/nginx/sites-available/kamixitong`：

```nginx
server {
    listen 80;
    server_name your-domain.com www.your-domain.com;
    
    # 强制 HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com www.your-domain.com;

    # SSL 证书
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    
    # SSL 配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;

    # 安全头
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # 日志
    access_log /var/log/nginx/kamixitong_access.log;
    error_log /var/log/nginx/kamixitong_error.log;

    # 静态文件
    location /static/ {
        alias /var/www/kamixitong/static/;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # 上传文件
    location /static/uploads/ {
        alias /var/www/kamixitong/static/uploads/;
        expires 7d;
        
        # 限制上传文件大小
        client_max_body_size 500M;
    }

    # API 代理
    location /api/ {
        proxy_pass http://127.0.0.1:5088;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # 超时设置
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }

    # 应用代理
    location / {
        proxy_pass http://127.0.0.1:5088;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket 支持（如果需要）
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

```bash
# 启用站点
sudo ln -s /etc/nginx/sites-available/kamixitong /etc/nginx/sites-enabled/

# 测试配置
sudo nginx -t

# 重载 Nginx
sudo systemctl reload nginx
```

### SSL 证书配置

```bash
# 安装 Certbot
sudo apt install certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d your-domain.com -d www.your-domain.com

# 自动续期
sudo certbot renew --dry-run
```

### 防火墙配置

```bash
# UFW 配置
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS
sudo ufw enable
```

---

## 安全注意事项

### 1. 密钥安全

```bash
# 生成强密钥
python -c "import secrets; print(secrets.token_urlsafe(32))"

# 永远不要在代码中硬编码密钥
# 不要将 .env 文件提交到版本控制
```

### 2. 文件权限

```bash
# 设置正确的文件权限
chmod 600 .env
chmod 700 logs/
chmod -R 755 static/
chmod -R 750 static/uploads/
```

### 3. 数据库安全

- 使用强密码
- 限制数据库用户权限
- 禁用远程root登录
- 定期备份

```bash
# 数据库备份脚本
mysqldump -u kamixitong -p kamixitong > backup_$(date +%Y%m%d).sql
```

### 4. 定期更新

```bash
# 更新 Python 依赖
pip install --upgrade -r requirements.txt

# 系统更新
sudo apt update && sudo apt upgrade
```

### 5. 监控日志

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

# 查看 Nginx 日志
tail -f /var/log/nginx/kamixitong_error.log

# 查看系统日志
journalctl -u kamixitong -f
```

---

## 常见问题

### Q1: 应用启动失败，提示 SECRET_KEY 未设置

**解决方案：** 确保 `.env` 文件中设置了 `SECRET_KEY` 环境变量：

```bash
# 检查 .env 文件
cat .env | grep SECRET_KEY

# 如果没有，生成并添加
echo "SECRET_KEY=$(python -c 'import secrets; print(secrets.token_urlsafe(32))')" >> .env
```

### Q2: 数据库连接失败

**解决方案：** 检查数据库配置和连接：

```bash
# 测试数据库连接
mysql -h DB_HOST -u DB_USER -pDB_PASSWORD DB_NAME

# 检查环境变量
echo $DB_HOST $DB_USER $DB_NAME
```

### Q3: API 返回 401 签名验证失败

**解决方案：** 确保客户端和服务端使用相同的 `AUTH_SECRET_KEY`：

```bash
# 检查配置
cat .env | grep AUTH_SECRET_KEY

# 如果需要，重新生成
echo "AUTH_SECRET_KEY=$(python -c 'import secrets; print(secrets.token_urlsafe(32))')" >> .env
```

### Q4: 文件上传失败

**解决方案：** 检查上传目录权限和大小限制：

```bash
# 创建上传目录
mkdir -p static/uploads

# 设置权限
chmod 755 static/uploads

# 检查 Nginx 配置
# 确保 client_max_body_size 设置正确
```

### Q5: 定时任务不执行

**解决方案：** 检查调度器状态：

```bash
# 检查环境变量
cat .env | grep DISABLE_SCHEDULER

# 确保没有禁用调度器
# DISABLE_SCHEDULER=False
```

### Q6: 内存占用过高

**解决方案：** 优化配置：

```bash
# 减少工作进程数
gunicorn -w 2 ...

# 减少数据库连接池
DB_POOL_SIZE=5
DB_MAX_OVERFLOW=10
```

### Q7: 前端页面能正常访问，但API调用失败怎么办？

**解决方案：** 检查以下几点：

1. 确认Nginx配置正确，特别是 `proxy_set_header` 指令
2. 确认Flask应用监听地址设置为 `0.0.0.0`
3. 检查浏览器开发者工具中的网络请求，确认API请求的URL是否正确

### Q8: 如何确认域名配置是否正确？

**解决方案：** 可以通过以下方式检查：

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

---

## 性能优化建议

### 1. 启用 Redis 缓存

```bash
# 安装 Redis
sudo apt install redis-server

# 配置环境变量
echo "REDIS_URL=redis://localhost:6379/0" >> .env
```

### 2. 数据库优化

```sql
-- 添加索引
CREATE INDEX idx_license_key ON license(license_key);
CREATE INDEX idx_machine_code ON device(machine_code);
CREATE INDEX idx_product_id ON product(product_id);
```

### 3. 静态文件 CDN

将静态文件托管到 CDN 可以显著提高加载速度。

### 4. 启用 Gzip 压缩

在 Nginx 配置中添加：

```nginx
gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml;
gzip_min_length 1000;
```

---

## 升级指南

### 版本升级步骤

```bash
# 1. 备份数据库
mysqldump -u kamixitong -p kamixitong > backup_before_upgrade.sql

# 2. 备份配置
cp .env .env.backup

# 3. 拉取新代码
git pull origin main

# 4. 更新依赖
pip install -r requirements.txt

# 5. 执行数据库迁移
flask db upgrade

# 6. 重启服务
sudo systemctl restart kamixitong
```

---

## 技术支持

如遇问题，请检查：

1. 应用日志：`logs/kamaxitong.log`
2. Nginx 日志：`/var/log/nginx/kamixitong_error.log`
3. 系统日志：`journalctl -u kamixitong`

---

*最后更新：2024年*