scholaraio: Skill for Claude Code

Backup / 数据备份

通过 scholaraio backup 统一执行远程 rsync 增量备份与完整实例恢复。

目标

• 不要让 agent 直接手写一长串 rsync 命令
• 优先复用 config.yaml / config.local.yaml 中的命名备份目标
• 对真实传输前，优先建议先做一次 --dry-run
• 区分兼容的 data 范围与可恢复的 instance 范围

使用方式

先查看已配置目标：

scholaraio backup list

执行某个备份目标：

scholaraio backup run <target>

预演模式：

scholaraio backup run <target> --dry-run

恢复完整实例：

scholaraio backup restore <target> --destination <instance-dir> --dry-run
scholaraio backup restore <target> --destination <instance-dir>

配置约定

在 config.yaml 中：

backup:
  source_dir: data
  targets:
    lab:
      host: backup.example.com
      user: alice
      path: /srv/scholaraio
      port: 22
      identity_file: ~/.ssh/id_ed25519
      scope: instance
      mode: default
      compress: true
      enabled: true
      exclude:
        - "*.tmp"

建议：

• scope: data 只同步 source_dir，保持旧行为；scope: instance 同步 config、data、workspace、published 和 control metadata，并生成恢复清单
• 真实 instance 备份会对组件树中的 .db / .sqlite / .sqlite3 使用 SQLite online backup，并在传输前执行 quick_check；不会把 live WAL/SHM/journal sidecar 当作恢复数据
• connect_timeout_seconds、io_timeout_seconds、process_timeout_seconds 分别限制 SSH 建连、空闲 I/O 和单个外部进程总时长
• 共享配置写在 config.yaml
• 主机相关或敏感项优先放 config.local.yaml
• 备份整棵 data/ 目录时优先使用 default
• 只有在明确备份对象是追加型文件时，才考虑 append / append-verify
• instance 范围必须使用 mode: default、不得配置 exclude，并应使用专用的空远端目录
• 密钥目标使用非交互 SSH（BatchMode=yes）；密码目标使用内部 SSH_ASKPASS；两种模式都不会交互确认 host key
• 如果远端只接受密码，可以只在 config.local.yaml 里为该 target 写 password；ScholarAIO 会自动切到内部 askpass 路径
• instance 会备份 config.local.yaml。SSH 只保护传输过程；API Key 和密码在远端仍是明文文件，因此必须保护远端账号和存储权限
• 仅存在于环境变量中的 API Key 不会进入备份；需要恢复的密钥必须持久化到 config.local.yaml
• 新机器恢复时，先提供能连接远端的最小 target 配置，再执行 restore；恢复后的 config.local.yaml 会覆盖 bootstrap 配置
• 可直接引导用户执行：ssh-keyscan -p <port> <host> >> ~/.ssh/known_hosts，再执行：ssh -i <identity_file> -p <port> <user>@<host> true

Agent 行为规范