EnovelCms 2.x → 3.0 分批升级工具（命令行版）
==========================================

适用：章节几百万到几千万、附件几十 G 到几百 G 的站点。
与网页版 upgrade_to_3.php 的区别：不备份整库、不打包附件、不在一个请求里跑完，
数据库按 id 区间分批搬运，文件按条目分批解压，随时可中断续跑。

原理：升级不改数据行，只改结构与分片归属，所以不需要全量备份。
      旧章节单表完成后原样改名保留，出问题一条 RENAME 即可回滚。


一、前置条件
------------
1. 站点仍是 2.x 结构（存在 chapters 单表），data/chapters 正文目录在。
2. install/install.sql 为 3.0 版本（升级包里自带）。
3. 3.0 程序包 zip 放在 data/upgrade-backup/pkg/ 下，文件名随意。
4. 磁盘只需能放下 3.0 程序文件，不需要几百 G 的备份空间。


二、Windows（Python）
---------------------
python -m pip install pymysql

查看进度：
python upgrade_to_3_win.py --root D:\wwwroot\site --status

正式执行（四阶段一次跑完）：
python upgrade_to_3_win.py --root D:\wwwroot\site --package D:\pkg\3.0.zip --batch 5000

只跑某一阶段：
python upgrade_to_3_win.py --root D:\wwwroot\site --phase shard
--phase 取值：schema 建表补字段 / shard 章节分片 / files 隔离解压封面 / final 配置锁与校验

先看计划不改数据：
python upgrade_to_3_win.py --root D:\wwwroot\site --dry-run


三、Linux（sh + PHP CLI）
-------------------------
sh upgrade_to_3.sh --root=/www/wwwroot/site --package=/tmp/3.0.zip --batch=5000

只跑某一阶段：
sh upgrade_to_3.sh --root=/www/wwwroot/site --phase=shard

找不到 php 时手动指定：
PHP_BIN=/www/server/php/84/bin/php sh upgrade_to_3.sh --root=/www/wwwroot/site

查看进度：
sh upgrade_to_3.sh --root=/www/wwwroot/site --status


四、参数
--------
--root        站点根目录，必填
--package     3.0 程序包 zip，留空则自动取 data/upgrade-backup/pkg 下最新的 zip
--batch       每批行数，默认 5000。行很宽或库很慢时降到 2000，SSD 可提到 20000
--phase       只执行某个阶段
--status      打印当前进度与游标
--dry-run     只打印计划
--db-host/--db-port/--db-name/--db-user/--db-pass/--db-prefix
              默认从 config/config.php 读取，命令行参数优先


五、中断与续跑
--------------
每批提交后把游标写进 data/upgrade-backup/cli_state.json，
进程被杀、断电、Ctrl+C 都只影响当前一批（MySQL 单语句原子，回滚干净）。
重新执行同一条命令即从游标继续，已搬过的行用 INSERT IGNORE 跳过，不会重复。

进度日志：data/upgrade-backup/cli_upgrade.log


六、执行后的产物
----------------
data/upgrade-backup/cli_state.json     进度与游标
data/upgrade-backup/cli_upgrade.log    全过程日志
old/<时间戳>/                          2.x 旧程序，原样保留
chapters_2x_legacy_<时间戳>            2.x 章节单表，原样保留
data/install.lock                      安装锁
config/config.php                      原文件保留，不存在时才生成


七、回滚
--------
程序：把 old/<时间戳>/ 下内容移回站点根。
数据：RENAME TABLE chapters_N TO chapters_N_bak; RENAME TABLE chapters_2x_legacy_x TO chapters;
      然后清空 chapters_0..N 分片表即可回到 2.x 单表状态。


八、注意
--------
1. 章节正文是 txt 文件，本工具不搬正文，只改表归属；data/chapters 不动。
2. uploads 与 data 不参与任何备份与覆盖。
3. 站点访问量大时，建议在低峰执行；迁移期间旧表仍在，前台不受影响。
4. 全部完成后删除 install 目录。
