ChuSQL/docs/bootstrap.md

Bootstrap 安装引导与离线修复

← 返回 README

本页导航： 安装引导 · 三种维护策略 · 副本、备份与恢复边界

csql-bootstrap 初始化系统目录，也能在服务无法启动时离线修复。

Warning

维护前必须停止使用同一数据目录的所有进程。数据目录锁拒绝并发维护，但不能依赖旧版进程具备该锁。

安装引导

csql-bootstrap --config settings.toml --user root --password-stdin

口令从标准输入的一行读取，哈希后保存。程序创建系统目录、启用且可登录的 SUPERUSER，以及现有内置类型登记项。重复引导保留已有口令和身份属性，拒绝冲突的类型定义及已降权的引导身份。安装脚本调用此入口。只有明确指定 --passwordless 才选择免密初始化。

三种维护策略

命令	行为	数据影响
repair	修复已知系统表的目录结构、列定义及结构元数据	不重放 WAL，不补初始化数据；原有 .db 文件必须保持字节一致
recover	修复结构、重放可用的已提交 WAL，补齐必要初始化内容	可能改变系统表数据；尽量保留现有身份、口令与授权
reset	重建初始系统目录，创建指定管理员及内置类型登记项	清除原系统目录中的身份、口令、角色关系、授权及其他系统内容

recovery 是 recover 的兼容别名。三个命令均保留业务数据库目录；reset 后业务数据仍在，但原访问授权已清除，需要重新创建身份并授权。

csql-bootstrap repair --config settings.toml
csql-bootstrap recover --config settings.toml
csql-bootstrap reset --config settings.toml --user root --password-stdin

优先使用 repair。若必须恢复数据、补内置类型或初始化管理员，它会中止，保持原系统目录不变，并用英文提示使用 recover 或 reset。需要初始化缺失管理员时，recover 要求 --password-stdin。已有管理员的口令不会因提供该参数而重设。reset 要求提供口令输入选项或显式选择 --passwordless。

维护入口直接使用存储库，不依赖数据库服务能够启动，不提供 SQL 或 TCP 远程维护接口。运行时输出、错误和服务启动修复提示均使用英文。

副本、备份与恢复边界

程序在数据目录下的 bootstrap-work-<时间戳>/system 副本中执行并验证。验证失败时不替换原目录；候选副本保留供检查。成功时将原系统目录移为 system-backup-<时间戳>，再发布新目录。输出给出备份与候选路径。备份包含口令哈希和授权，应按数据库数据同等保护。

发布第二次目录移动失败时会尝试回滚。若发布期间进程或机器崩溃，先停止所有进程，检查输出及上述目录；保存候选与当前目录后，可将完整的备份恢复为数据目录下的 system。不要把不同版本或不同时间点的零散文件混合覆盖。

WAL 只能恢复尚且可用的已提交记录，不能保证恢复已截断、丢失或损坏的历史。已知缺失表的记录数无法恢复完整时会拒绝发布。损坏的数据页也可能使 recover 失败，此时需要完整备份或选择清除系统内容的 reset。

目录元数据严重损坏时，只能依据程序内置定义重建已知系统表。存在无法识别结构的系统表文件时拒绝重建，应从备份恢复或使用 reset。身份目录计数器损坏后只能依据现存身份编号重建，无法还原已删除身份的历史编号上限。业务数据库自身的结构、数据页和 WAL 不由这些命令修复。