LinkPort/docs/database-snapshots.md

完整 SQLite 一致性备份与停服恢复

配置管理中的“下载一致性 SQLite 备份”调用 SQLite 在线备份接口，包含已提交 WAL 数据，不复制运行中的主文件。与口令加密配置导出不同，这份文件包含管理员、所有配置、审计、库内主密钥、自动 TLS 及设备同步状态。取得文件即可解密凭据，需按敏感材料保管。自定义外部文件路径对应的外部文件不在库内，不会被额外打包。

在线下载采用流式响应；恢复预览上传限 32 MiB。浏览器可检查结构完整性、库内密钥匹配并显示资源数量、SQLite user_version、格式及 SHA256。大文件用命令检查：

.\linkport.exe inspect-database "D:\backup\linkport.sqlite"

完整恢复

1. 检查备份文件并保存 SHA256；在界面勾选理解完整替换风险后显示恢复指令。
2. 停止整个 LinkPort 程序，不只是停止网关；保持与原服务相同的工作目录、LINKPORT_DATA 等数据路径配置。
3. 执行（将路径、SHA256 替换为实际值）：

.\linkport.exe restore-database "D:\backup\linkport.sqlite" --confirm-sha256 <SHA256>

4. 命令获取与服务相同的独占锁；运行中的服务持锁时拒绝恢复。私有暂存并再次核验备份，防止确认后文件变化。先在线备份当前数据库到 数据目录/backups/before-restore-时间-随机值/linkport.sqlite，完整性检查通过且源/目标 schema 指纹与 user_version 一致后，再由 SQLite 备份恢复事务原子替换页面，不重命名被锁 inode，也不直接覆盖 WAL。失败时保留已生成的保底备份，并打印位置。
5. 重新启动 LinkPort；账号、凭据、审计、TLS 及同步设置来自备份。网关启动行为按备份中的启用状态执行。跨版本 schema 不一致时拒绝恢复，先使用匹配版本处理，不能绕过检查。

源必须是完整、独立的普通 SQLite 文件，拒绝符号链接及带 WAL/SHM/journal 的输入。不会在检查时初始化、迁移或生成密钥。只能在已初始化的当前数据库上恢复。API 限管理会话并要求 CSRF，不允许 API token 导出或检查全库。Web 端不提供在线覆盖数据库的操作；真正恢复必须显式停服执行命令，避免在活动连接、登录会话和 TLS 上下文存在时换库。

验证

服务端快照、上传检查暂存和恢复暂存文件在写入内容前收紧权限：Unix 为 0600，Windows 使用受保护 DACL，仅当前进程用户与 SYSTEM 可访问。浏览器下载文件的最终权限由浏览器和下载目录决定，仍需用户自行保管。

隔离数据库测试覆盖在线快照、目标/管理员/命令审计/事件/自动 TLS、摘要不符拒绝、完整性检查、拒绝 WAL 输入、恢复后数据及保底快照、运行实例锁保护。浏览器覆盖下载、上传检查、资源预览和风险确认后才显示恢复命令。实际全量验证结果见 testing.md。未对真实 data 执行恢复或迁移。