Kamixitong/DEPLOYMENT_GUIDE.md

账号管理系统重构部署指南

快速开始

1. 备份现有系统

# 备份数据库
mysqldump -u root -p your_database > backup_$(date +%Y%m%d_%H%M%S).sql

# 备份应用文件
tar -czf app_backup_$(date +%Y%m%d_%H%M%S).tar.gz app/ migrations/

# 备份配置文件
cp config.py config.py.bak

2. 应用迁移

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

# 应用数据库迁移
flask db upgrade

# 或手动执行
alembic upgrade head

3. 重启应用

# 如果使用systemd
sudo systemctl restart kamixitong

# 如果使用gunicorn
sudo killall gunicorn
# 然后重新启动
gunicorn -w 4 -b 0.0.0.0:5000 run:app &

# 如果直接运行
python run.py

4. 验证部署

# 运行测试脚本
python test_refactored_admin.py

详细部署步骤

步骤1: 准备工作

确认以下环境:

• Python 3.7+
• MySQL 5.7+ 或 PostgreSQL
• Flask-Migrate 已安装

pip list | grep -E "Flask|flask-migrate|sqlalchemy"

步骤2: 检查代码文件

确认以下文件已存在:

• app/api/admin.py (重构后)
• app/models/audit_log.py (新建)
• app/web/templates/admin/list.html (重构后)
• migrations/versions/20241111_add_soft_delete_to_admin.py
• migrations/versions/20241111_create_audit_log.py

步骤3: 停止应用

确保没有活跃的用户连接:

# 查看活跃连接
lsof -i :5000

# 停止应用
sudo systemctl stop kamixitong
# 或
pkill -f "gunicorn.*run:app"

步骤4: 应用迁移

# 初始化迁移仓库(如果还没有)
flask db init

# 生成迁移文件(可选，文件已存在)
# flask db migrate -m "Add soft delete fields to admin"
# flask db migrate -m "Create audit_log table"

# 升级数据库
flask db upgrade

# 验证迁移
flask db current
# 应该看到: add_soft_delete_admin 和 create_audit_log

步骤5: 验证表结构

-- 连接到数据库
mysql -u root -p

-- 检查admin表
DESCRIBE admin;
-- 应该看到: is_deleted, delete_time 字段

-- 检查audit_log表
DESCRIBE audit_log;
-- 应该存在audit_log表

步骤6: 启动应用

# 启动应用
python run.py
# 或
gunicorn -w 4 -b 0.0.0.0:5000 run:app &

# 检查日志
tail -f app.log

步骤7: 功能测试

测试1: 登录系统

1. 访问登录页面
2. 使用超级管理员账号登录
3. 确认可以访问管理后台

测试2: 账号管理

1. 进入"账号管理"页面
2. 创建新账号
3. 编辑账号
4. 启用/禁用账号
5. 删除账号(验证软删除)
6. 查看审计日志

测试3: 验证新功能

# 访问审计日志表
mysql -u root -p -e "SELECT * FROM audit_log ORDER BY create_time DESC LIMIT 10;"

# 查看已删除的账号
mysql -u root -p -e "SELECT admin_id, username, is_deleted, delete_time FROM admin WHERE is_deleted = 1;"

回滚方案

如果遇到问题，可以回滚到原版本:

方案1: 回滚数据库

# 查看迁移历史
flask db history

# 回滚到特定版本
flask db downgrade add_soft_delete_admin

# 或完全回滚
flask db downgrade base

方案2: 恢复备份

# 恢复数据库
mysql -u root -p your_database < backup_YYYYMMDD_HHMMSS.sql

# 恢复应用文件
tar -xzf app_backup_YYYYMMDD_HHMMSS.tar.gz

# 重启应用
sudo systemctl restart kamixitong

方案3: 手动回滚

如果自动回滚失败，手动执行:

-- 删除audit_log表
DROP TABLE IF EXISTS audit_log;

-- 删除admin表字段
ALTER TABLE admin DROP COLUMN is_deleted;
ALTER TABLE admin DROP COLUMN delete_time;

性能优化建议

1. 审计日志归档

-- 归档6个月前的日志
CREATE TABLE audit_log_archive AS
SELECT * FROM audit_log
WHERE create_time < DATE_SUB(NOW(), INTERVAL 6 MONTH);

-- 清理旧日志
DELETE FROM audit_log
WHERE create_time < DATE_SUB(NOW(), INTERVAL 6 MONTH);

2. 添加索引

-- 为常用查询添加索引
CREATE INDEX idx_admin_status ON admin(status);
CREATE INDEX idx_admin_username ON admin(username);

3. 监控查询性能

-- 慢查询监控
SET long_query_time = 2;
SET slow_query_log = 1;

常见问题解决

Q1: 迁移失败

错误: Target database is not up to date

解决:

# 标记当前版本
flask db stamp head

# 重新迁移
flask db upgrade

Q2: 权限错误

错误: Access denied for user

解决:

-- 授权
GRANT ALL PRIVILEGES ON your_database.* TO 'your_user'@'localhost';
FLUSH PRIVILEGES;

Q3: 审计日志记录失败

错误: Table 'audit_log' doesn't exist

解决:

# 手动应用迁移
alembic upgrade create_audit_log

Q4: 登录失败

错误: 管理员不存在

解决: 检查数据库中是否有超级管理员账号:

SELECT admin_id, username, role, status, is_deleted FROM admin WHERE role = 1 AND status = 1 AND is_deleted = 0;

如果没有，创建一个:

INSERT INTO admin (username, password_hash, email, role, status, is_deleted)
VALUES ('admin', '<hashed_password>', 'admin@example.com', 1, 1, 0);

监控和维护

日常检查

1. 查看应用日志

   tail -f app.log | grep -E "ERROR|CRITICAL"
   

2. 检查数据库状态

   SHOW PROCESSLIST;
   SHOW TABLE STATUS;
   

3. 监控审计日志增长

   SELECT COUNT(*) FROM audit_log WHERE create_time > CURDATE();
   

定期维护

1. 每月归档审计日志
2. 清理过期的已删除账号 (可选)
3. 优化数据库表 (OPTIMIZE TABLE)
4. 备份数据库

联系支持

如果遇到问题:

1. 查看 REFACTOR_NOTES.md 了解详细变更
2. 运行 test_refactored_admin.py 进行诊断
3. 检查应用日志和数据库日志
4. 如需帮助，请提供:
   • 错误日志
   • 数据库版本
   • Python版本
   • 操作系统版本

---

重要提示:

• 部署前务必备份数据
• 在测试环境先进行验证
• 保留原有的admin_old.py和list_old.html作为备份
• 建议在低峰期进行部署