taiyi/KaMixitong

Fork 0

Files

wsb1224 0f8ac68d4d 第一次提交

2026-03-25 15:24:22 +08:00

14 KiB

Raw Blame History

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. 克隆代码

git clone <repository-url>
cd KaMiXiTong/master

2. 创建虚拟环境

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

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

3. 安装依赖

pip install -r requirements.txt

4. 生成安全密钥

# 生成 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. 创建配置文件

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

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

6. 初始化数据库

# 创建数据库
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. 启动应用

# 开发环境
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`

完整配置文件示例

# .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 配置优化

-- 创建数据库
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;

数据库初始化

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

数据库迁移

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

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

# 执行迁移
flask db upgrade

启动应用

开发环境

# 直接运行
python run.py

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

生产环境

方式一：Gunicorn（推荐）

# 安装 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

# 安装 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

方式三：使用启动脚本

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

Systemd 服务配置

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

[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

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

# 查看状态
sudo systemctl status kamixitong

生产环境部署

Nginx 配置

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

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";
    }
}

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

# 测试配置
sudo nginx -t

# 重载 Nginx
sudo systemctl reload nginx

SSL 证书配置

# 安装 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

防火墙配置

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

安全注意事项

1. 密钥安全

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

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

2. 文件权限

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

3. 数据库安全

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

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

4. 定期更新

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

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

5. 监控日志

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

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

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

常见问题

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

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

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

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

Q2: 数据库连接失败

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

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

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

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

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

# 检查配置
cat .env | grep AUTH_SECRET_KEY

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

Q4: 文件上传失败

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

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

# 设置权限
chmod 755 static/uploads

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

Q5: 定时任务不执行

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

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

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

Q6: 内存占用过高

解决方案： 优化配置：

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

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

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

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

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

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

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

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

性能优化建议

1. 启用 Redis 缓存

# 安装 Redis
sudo apt install redis-server

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

2. 数据库优化

-- 添加索引
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 配置中添加：

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

升级指南

版本升级步骤

# 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

技术支持

如遇问题，请检查：

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

最后更新：2024年

14 KiB Raw Blame History Unescape Escape