Kamixitong/DEPLOYMENT_GUIDE.md

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

## 快速开始

### 1. 备份现有系统

```bash
# 备份数据库
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. 应用迁移

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

# 应用数据库迁移
flask db upgrade

# 或手动执行
alembic upgrade head
```

### 3. 重启应用

```bash
# 如果使用systemd
sudo systemctl restart kamixitong

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

# 如果直接运行
python run.py
```

### 4. 验证部署

```bash
# 运行测试脚本
python test_refactored_admin.py
```

## 详细部署步骤

### 步骤1: 准备工作

确认以下环境:
- Python 3.7+
- MySQL 5.7+ 或 PostgreSQL
- Flask-Migrate 已安装

```bash
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: 停止应用

确保没有活跃的用户连接:
```bash
# 查看活跃连接
lsof -i :5000

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

### 步骤4: 应用迁移

```bash
# 初始化迁移仓库(如果还没有)
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: 验证表结构

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

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

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

### 步骤6: 启动应用

```bash
# 启动应用
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: 验证新功能

```bash
# 访问审计日志表
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: 回滚数据库

```bash
# 查看迁移历史
flask db history

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

# 或完全回滚
flask db downgrade base
```

### 方案2: 恢复备份

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

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

# 重启应用
sudo systemctl restart kamixitong
```

### 方案3: 手动回滚

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

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

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

## 性能优化建议

### 1. 审计日志归档

```sql
-- 归档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. 添加索引

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

### 3. 监控查询性能

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

## 常见问题解决

### Q1: 迁移失败

**错误:** `Target database is not up to date`

**解决:**
```bash
# 标记当前版本
flask db stamp head

# 重新迁移
flask db upgrade
```

### Q2: 权限错误

**错误:** `Access denied for user`

**解决:**
```sql
-- 授权
GRANT ALL PRIVILEGES ON your_database.* TO 'your_user'@'localhost';
FLUSH PRIVILEGES;
```

### Q3: 审计日志记录失败

**错误:** `Table 'audit_log' doesn't exist`

**解决:**
```bash
# 手动应用迁移
alembic upgrade create_audit_log
```

### Q4: 登录失败

**错误:** `管理员不存在`

**解决:**
检查数据库中是否有超级管理员账号:
```sql
SELECT admin_id, username, role, status, is_deleted FROM admin WHERE role = 1 AND status = 1 AND is_deleted = 0;
```

如果没有，创建一个:
```sql
INSERT INTO admin (username, password_hash, email, role, status, is_deleted)
VALUES ('admin', '<hashed_password>', 'admin@example.com', 1, 1, 0);
```

## 监控和维护

### 日常检查

1. **查看应用日志**
   ```bash
   tail -f app.log | grep -E "ERROR|CRITICAL"
   ```

2. **检查数据库状态**
   ```sql
   SHOW PROCESSLIST;
   SHOW TABLE STATUS;
   ```

3. **监控审计日志增长**
   ```sql
   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作为备份
- 建议在低峰期进行部署