13 KiB

Raw Blame History

检查点操作详细日志指南

📋 概述

已为检查点功能添加详细的日志输出，让你能够实时查看每张表的数据变化和操作进度。

🔍 日志特点

日志级别

INFO - 正常操作信息
WARNING - 重要警告（恢复操作）
ERROR - 错误信息

日志格式

2025-10-30 14:30:15 [INFO] lawrisk.services.licensing_repo: [CHECKPOINT] Starting checkpoint creation: checkpoint_20251030_143015

关键标识

[CHECKPOINT] - 检查点相关操作
[API] - API 请求信息
[1/8] - 表恢复进度 (当前表/总表数)

📊 创建 Checkpoint 日志示例

================================================================================
[CHECKPOINT] Starting checkpoint creation: checkpoint_20251030_143015
[CHECKPOINT] Description: 测试备份
================================================================================
[CHECKPOINT] Found 8 tables to backup: regions, themes, business_scopes, permits, risks, region_themes, region_scopes, region_theme_permits
[CHECKPOINT] [1/8] Processing table: regions
[CHECKPOINT] Backing up table: regions
[CHECKPOINT] Backup complete: regions - 5 rows, 3 columns
[CHECKPOINT] [1/8] Table regions backed up: 5 rows
[CHECKPOINT] [2/8] Processing table: themes
[CHECKPOINT] Backing up table: themes
[CHECKPOINT] Backup complete: themes - 12 rows, 3 columns
[CHECKPOINT] [2/8] Table themes backed up: 12 rows
...
[CHECKPOINT] All tables backed up successfully, committing transaction...
[CHECKPOINT] Transaction committed
[CHECKPOINT] Saving checkpoint file: data/checkpoints/checkpoint_20251030_143015.json
================================================================================
[CHECKPOINT] Checkpoint creation COMPLETED: checkpoint_20251030_143015
[CHECKPOINT] Total rows backed up: 1247
[CHECKPOINT] File: data/checkpoints/checkpoint_20251030_143015.json
================================================================================

📈 恢复 Checkpoint 日志示例

================================================================================
[API] Received checkpoint restore request: checkpoint_20251030_143015
[API] Request parameters: {'create_auto_backup': 'true'}
[API] Auto-backup enabled: True
[API] Starting restore operation...
================================================================================
[CHECKPOINT] WARNING: Starting restore operation: checkpoint_20251030_143015
[CHECKPOINT] This will OVERWRITE all existing data in the database!
================================================================================
[CHECKPOINT] Creating auto-backup before restore...
================================================================================
[CHECKPOINT] Starting checkpoint creation: auto_backup_before_restore_checkpoint_20251030_143015
...
[CHECKPOINT] Auto-backup created: auto_backup_before_restore_checkpoint_20251030_143015
[CHECKPOINT] Auto-backup contains 1247 rows
================================================================================
[CHECKPOINT] Checkpoint details:
[CHECKPOINT]   ID: checkpoint_20251030_143015
[CHECKPOINT]   Tables: 8
[CHECKPOINT]   Total rows: 1247
[CHECKPOINT] Auto-backup: Yes (auto_backup_before_restore_checkpoint_20251030_143015)
================================================================================
[CHECKPOINT] Building table dependency graph...
[CHECKPOINT] Found 6 table dependencies
[CHECKPOINT] Calculating restore order...
[CHECKPOINT] Restore order: risks -> permits -> business_scopes -> themes -> regions -> region_themes -> region_scopes -> region_theme_permits
[CHECKPOINT] Acquiring exclusive locks on all tables...
[CHECKPOINT] All tables locked exclusively
================================================================================
[CHECKPOINT] Starting restore process...
================================================================================
[CHECKPOINT] [1/8] Preparing to restore table: risks
[CHECKPOINT] Truncating table: risks
[CHECKPOINT] Restoring 100 rows into risks (columns: id, risk_content, legal_basis, document_no, summary)
[CHECKPOINT] Progress: risks - 100/100 rows inserted
[CHECKPOINT] Restore complete: risks - 100 rows successfully inserted
[CHECKPOINT] [1/8] Table risks restored: 100 rows

[CHECKPOINT] [2/8] Preparing to restore table: permits
[CHECKPOINT] Truncating table: permits
[CHECKPOINT] Restoring 50 rows into permits (columns: id, name)
[CHECKPOINT] Progress: permits - 50/50 rows inserted
[CHECKPOINT] Restore complete: permits - 50 rows successfully inserted
[CHECKPOINT] [2/8] Table permits restored: 50 rows

...
[CHECKPOINT] [8/8] Preparing to restore table: region_theme_permits
[CHECKPOINT] Truncating table: region_theme_permits
[CHECKPOINT] Restoring 800 rows into region_theme_permits (columns: region_id, theme_id, permit_id)
[CHECKPOINT] Progress: region_theme_permits - 100/800 rows inserted
[CHECKPOINT] Progress: region_theme_permits - 200/800 rows inserted
[CHECKPOINT] Progress: region_theme_permits - 300/800 rows inserted
...
[CHECKPOINT] Progress: region_theme_permits - 800/800 rows inserted
[CHECKPOINT] Restore complete: region_theme_permits - 800 rows successfully inserted
[CHECKPOINT] [8/8] Table region_theme_permits restored: 800 rows

================================================================================
[CHECKPOINT] All tables restored successfully, committing transaction...
[CHECKPOINT] Transaction committed successfully
================================================================================
================================================================================
[CHECKPOINT] RESTORE COMPLETED SUCCESSFULLY: checkpoint_20251030_143015
[CHECKPOINT] Tables restored: 8/8
[CHECKPOINT] Total rows restored: 1247
[CHECKPOINT] Auto-backup available: auto_backup_before_restore_checkpoint_20251030_143015
================================================================================
[API] Restore completed successfully
[API] Tables restored: 8
[API] Total rows restored: 1247

🚀 如何查看日志

方法1: 查看控制台输出

启动应用时，所有日志会直接输出到控制台：

python app.py

方法2: 查看日志文件

如果将日志重定向到文件：

python app.py > checkpoint.log 2>&1
tail -f checkpoint.log

方法3: 实时监控日志

# Linux/Mac
tail -f /path/to/app.log | grep -E "(CHECKPOINT|API)"

# Windows (PowerShell)
Get-Content app.log -Wait | Where-Object { $_ -match "(CHECKPOINT|API)" }

📝 日志信息说明

创建 Checkpoint 时

日志内容	含义
`[CHECKPOINT] Starting checkpoint creation`	开始创建检查点
`[CHECKPOINT] Found X tables`	找到X个表
`[CHECKPOINT] [i/N] Processing table`	正在处理第i个表，共N个表
`[CHECKPOINT] Backup complete: table_name - X rows`	表备份完成，X行数据
`[CHECKPOINT] Transaction committed`	事务提交成功
`[CHECKPOINT] Checkpoint creation COMPLETED`	检查点创建完成

恢复 Checkpoint 时

日志内容	含义
`[CHECKPOINT] WARNING: Starting restore`	开始恢复操作警告
`[CHECKPOINT] Creating auto-backup`	创建自动备份
`[CHECKPOINT] Auto-backup created`	自动备份创建完成
`[CHECKPOINT] Building table dependency graph`	构建表依赖关系
`[CHECKPOINT] Calculating restore order`	计算恢复顺序
`[CHECKPOINT] Restore order: ...`	显示恢复顺序
`[CHECKPOINT] Acquiring exclusive locks`	获取表级锁
`[CHECKPOINT] [i/N] Preparing to restore table`	准备恢复第i个表
`[CHECKPOINT] Truncating table`	清空表数据
`[CHECKPOINT] Restoring X rows into table`	开始恢复X行数据
`[CHECKPOINT] Progress: table - Y/Z rows inserted`	恢复进度：已插入Y行，共Z行
`[CHECKPOINT] Restore complete: table - X rows`	表恢复完成，共X行
`[CHECKPOINT] Table table_name restored: X rows`	表恢复统计信息
`[CHECKPOINT] RESTORE COMPLETED SUCCESSFULLY`	恢复操作成功完成

错误日志

日志内容	含义
`[CHECKPOINT] ERROR: ...`	发生错误
`[CHECKPOINT] Restore FAILED`	恢复失败
`[CHECKPOINT] Transaction rolled back`	事务已回滚
`[CHECKPOINT] Recovery suggestion:`	恢复建议（使用自动备份）

🔧 故障排除

问题1: 日志看不到输出

原因: 日志被缓冲或重定向

解决方案:

确保使用了 -u 参数运行Python（禁用缓冲）
```
python -u app.py
```

或者设置环境变量

export PYTHONUNBUFFERED=1
python app.py

问题2: 日志信息不完整

原因: 日志级别设置过高

解决方案: 确保日志级别设置为INFO或DEBUG：

import logging
logging.getLogger().setLevel(logging.INFO)

问题3: 恢复操作卡住

原因: 可能正在处理大表，或者等待锁

解决方案:

查看日志中的进度信息
等待表锁释放
检查是否有其他会话占用表锁

📊 性能监控

通过日志可以监控：

备份/恢复速度

每行数据处理时间 = 总时间 / 行数

表大小分布
```
查看每个表的行数
```
依赖关系正确性
```
验证恢复顺序是否正确
```

事务效率

开始时间 -> 提交时间 = 事务持续时间

⚡ 快速查看命令

查看最新日志

tail -100 checkpoint.log | grep "CHECKPOINT"

统计处理的行数

grep "rows inserted" checkpoint.log | awk '{print $6}'

查看错误信息

grep -i "error\|failed" checkpoint.log

监控实时进度

tail -f checkpoint.log | grep "Progress:"

注意: 所有日志都会立即输出到控制台，无需等待操作完成即可查看进度。

🧱 针对许可风险的精细化快照

新增：基于 region_permit_risk_vw 视图的原子检查点

当用户编辑某条许可风险记录（唯一键为 region_id + permit_id + risk_id）时，可调用以下工具函数先写入快照：

from lawrisk.services.licensing_repo import create_permit_risk_snapshot

snapshot_meta = create_permit_risk_snapshot(
    region_id="7c2b…",
    permit_id="b93d…",
    risk_id="a01f…",
    edited_by="alice",
    change_summary="调整法律依据与责任主体"
)

返回示例：

{
    "snapshot_id": "5c4b…",
    "permit_risk_key": "7c2b…::b93d…::a01f…",
    "version": 3,
    "created_at": "2024-05-18T02:41:55.210412+00:00",
    "edited_by": "alice",
    "change_summary": "调整法律依据与责任主体",
    "payload": {...完整的视图行...}
}

快照数据存放在 permit_risk_snapshots 表中，payload 记录视图的完整列。
使用 list_permit_risk_snapshots(region_id=..., permit_id=..., risk_id=...) 查看历史版本。
通过 get_permit_risk_snapshot(snapshot_id) 获取任意版本的详细内容，以便比对或手工回滚。

带快照的原子修改

from lawrisk.services.licensing_repo import update_permit_risk_record

result = update_permit_risk_record(
    region_id="7c2b…",
    permit_id="b93d…",
    risk_id="a01f…",
    risk_content="新的风险提示要点",
    legal_basis="《某条例》第三条",
    permit_status="正常受理",
    edited_by="alice",
    change_summary="补充法规依据并更新状态"
)

print(result["snapshot"]["version"])   # 修改前版本
print(result["current"]["risk_content"])  # 修改后视图内容

函数会先锁定 region_permit_risks 目标行，写入快照，再执行字段更新。
risk_* 参数对应 risks 表字段；permit_* 参数对应 region_permit_details。
可传入 None 将字段清空；若不想修改某列则省略参数。

管理端快照列表 API

通过管理端路由 /fs-ai-asistant/api/workflow/lawrisk/admin/permit-risk-snapshots 获取快照历史，支持查询参数：

region_id / region：按区域筛选
permit_id / permit：按许可筛选
edited_by：按编辑人筛选
limit（默认20，最大200）、offset

返回结构：

{
  "success": true,
  "data": {
    "snapshots": [
      {
        "snapshot_id": "…",
        "region_name": "佛山市禅城区",
        "permit_name": "食品经营许可-餐饮服务",
        "risk_content": "1. 禁止在居民住宅楼…",
        "permit_status": "正常受理",
        "edited_by": "alice",
        "change_summary": "补充法规依据",
        "created_at": "2024-05-18T02:41:55.210412+00:00",
        "version": 3
      }
    ],
    "pagination": {
      "limit": 20,
      "offset": 0,
      "total": 128
    }
  }
}

可以直接在“检查点管理”按钮中调用此接口，将 snapshots 列表渲染成表格并展示“受影响许可”“编辑人”“创建时间”等信息。

13 KiB Raw Blame History Unescape Escape