CLI 配置来源说明

本工具支持三种等价配置来源：命令行参数、环境变量、JSON/JSONC 配置文件。.env 文件会被加载成环境变量，因此字段仍然使用同一套 SIYUAN_RESTORE_* 名称。除 --config、--env-file 这种元参数外，恢复相关字段应在三种来源中保持一致。

优先级从高到低：

命令行参数
系统环境变量 / CI Secrets
.env 文件
JSON/JSONC 配置文件
默认值

字段对照表

配置文件字段	环境变量	CLI 参数	类型 / 可选值	默认值
`endpoint`	`SIYUAN_RESTORE_ENDPOINT`	`--endpoint <url>`	字符串	必填
`accessKey`	`SIYUAN_RESTORE_ACCESS_KEY`	`--access-key <key>`	字符串	必填
`secretKey`	`SIYUAN_RESTORE_SECRET_KEY`	`--secret-key <key>`	字符串	必填
`bucket`	`SIYUAN_RESTORE_BUCKET`	`--bucket <name>`	字符串	必填
`region`	`SIYUAN_RESTORE_REGION`	`--region <region>`	字符串	`us-east-1`
`pathStyle`	`SIYUAN_RESTORE_PATH_STYLE`	`--path-style` / `--no-path-style`	布尔值	`false`
`password`	`SIYUAN_RESTORE_PASSWORD`	`--password <pass>`	字符串	与 `aesKey` 二选一
`aesKey`	`SIYUAN_RESTORE_AES_KEY`	`--aes-key <key>`	Base64 32 字节密钥	与 `password` 二选一
`output`	`SIYUAN_RESTORE_OUTPUT`	`--output <dir>`	路径	`./restored`
`snapshotId`	`SIYUAN_RESTORE_SNAPSHOT_ID`	`--snapshot-id <id>`	快照 ID 或 `latest`	`latest`
`format`	`SIYUAN_RESTORE_FORMAT`	`--format <fmt>`	`sy` / `md` / `both`	`sy`
`concurrency`	`SIYUAN_RESTORE_CONCURRENCY`	`--concurrency <n>`	正整数	`8`
`rename`	`SIYUAN_RESTORE_RENAME`	`--rename <mode>`	`none` / `title` / `title-id`	`none`
`notebooks` / `notebook`	`SIYUAN_RESTORE_NOTEBOOKS` / `SIYUAN_RESTORE_NOTEBOOK`	`--notebooks <names-or-ids>` / `--notebook <name-or-id>`	笔记本名称或 ID；多个用英文逗号分隔，配置文件推荐数组	全部
`incremental`	`SIYUAN_RESTORE_INCREMENTAL`	`--incremental` / `--no-incremental`	布尔值	`false`
`interactive`	`SIYUAN_RESTORE_INTERACTIVE`	`--interactive` / `--no-interactive`	布尔值	`false`
`summaryFile`	`SIYUAN_RESTORE_SUMMARY_FILE`	`--summary-file <path>`	JSON 文件路径	无
-	`SIYUAN_RESTORE_TIME_ZONE`	无	IANA 时区名，用于摘要和提交信息时间显示	`Asia/Shanghai`
`exclude`	`SIYUAN_RESTORE_EXCLUDE`	`--exclude <patterns...>`	顶层目录名列表	无
`docsOnly`	`SIYUAN_RESTORE_DOCS_ONLY`	`--docs-only` / `--no-docs-only`	布尔值	`false`

AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_REGION、AWS_DEFAULT_REGION 也会作为环境变量 fallback，但推荐在 CI 中优先使用 SIYUAN_RESTORE_*。

密钥字段说明

password 和 aesKey 二选一即可：

password：思源同步密码，工具会派生 AES key。
aesKey：Base64 编码的 32 字节 AES key。

如果多个来源同时设置，优先级仍然是 CLI > 环境变量 > 配置文件。同一来源里同时设置 password 和 aesKey 时，password 优先。

空字符串会被视为“未设置”。因此 siyuan-restore.example.jsonc 中可以同时保留两个字段，只填其中一个。

布尔值写法

配置文件中使用 JSON 布尔值：

{
  "incremental": true,
  "interactive": false,
  "docsOnly": true,
  "pathStyle": false
}

环境变量支持：

真值：1、true、yes、y、on
假值：0、false、no、n、off

CLI 中布尔字段使用开关参数；如果需要覆盖配置文件或环境变量中的 true，使用 --no-*：

node dist/index.js --incremental --docs-only --path-style --interactive
node dist/index.js --no-incremental --no-docs-only --no-path-style --no-interactive

列表字段写法

配置文件：

{
  "exclude": ["history", "temp"]
}

环境变量使用逗号分隔：

SIYUAN_RESTORE_EXCLUDE=history,temp

CLI 使用空格分隔：

node dist/index.js --exclude history temp

JSON/JSONC 配置文件用法

复制模板：

cp siyuan-restore.example.jsonc siyuan-restore.jsonc

填写真实值后运行：

npm run build
node dist/index.js

默认会自动读取当前目录下的：

siyuan-restore.json
siyuan-restore.jsonc
.siyuan-restore.json
.siyuan-restore.jsonc

也可以显式指定配置文件：

node dist/index.js --config ./my-restore-config.jsonc

--config 只属于 CLI 元参数，不是恢复字段，因此没有对应的环境变量和 JSON 字段。

*.jsonc 可以写 //、/* */ 注释，也允许对象或数组结尾处的尾逗号，适合作为日常配置文件。*.json 仍然可用，适合不需要注释的机器生成配置。

快照和交互模式

默认行为是直接运行，不进入交互模式：

snapshotId 留空或设置为 latest：自动读取 S3 中的最新快照。
notebooks / notebook 留空：恢复全部笔记本和工作区文件。
指定多个笔记本时，本次执行只会同步指定笔记本；增量删除和 .restore-state.json 合并都只作用于本次笔记本 scope，不会删除或改写其他笔记本的同步状态和缓存。
interactive 默认为 false：不会弹出快照或笔记本选择器。

如果需要手动选择快照或笔记本，显式开启交互模式：

node dist/index.js --interactive

也可以通过配置文件或环境变量开启：

{
  "interactive": true,
  "snapshotId": "",
  "notebooks": []
}

SIYUAN_RESTORE_INTERACTIVE=true

注意：如果你已经显式传入 snapshotId、notebook 或 notebooks，即使开启了 interactive，这些已指定字段也不会再弹出选择。

最终摘要和 CI 提交信息

每次运行结束都会打印一段固定结构的关键摘要，包含：

本次使用的快照 ID 和快照创建时间
操作的笔记本：全部或指定笔记本
created、modified、deleted、unchanged 统计
变更文件列表，每个文件都会标出所属笔记本
输出格式、重命名模式、docsOnly 等关键选项

如果 CI 需要用这些信息生成 commit message，可以指定 summaryFile：

node dist/index.js --summary-file "$RUNNER_TEMP/siyuan-restore-summary.json"

或使用环境变量：

SIYUAN_RESTORE_SUMMARY_FILE="$RUNNER_TEMP/siyuan-restore-summary.json"

摘要文件是 JSON，包含 commit.title 和 commit.body 两个可直接复用的字段，也包含结构化字段：

{
  "status": "completed",
  "snapshot": {
    "id": "20260610151058-7rhrop8",
    "createdAt": "2026/06/10 15:10:58",
    "createdAtIso": "2026-06-10T07:10:58.000Z"
  },
  "notebook": {
    "mode": "selected",
    "name": "技能飞跃"
  },
  "counts": {
    "created": 2,
    "modified": 5,
    "deleted": 1,
    "unchanged": 120
  },
  "changes": {
    "files": [
      {
        "status": "modified",
        "path": "20260607133810-awpfqxj/20260610151058-7rhrop8.sy",
        "notebook": {
          "id": "20260607133810-awpfqxj",
          "name": "技能飞跃"
        }
      }
    ],
    "truncated": false
  },
  "commit": {
    "title": "chore: update siyuan notes (20260610)",
    "body": "Snapshot: ..."
  }
}

建议把摘要写到 $RUNNER_TEMP 或其他临时目录，不要写进 restored/ 后一起提交。摘要里包含快照 ID、笔记本名、变更文件路径和文件统计，按敏感信息处理。

环境变量用法

可以复制模板：

cp .env.demo .env

本工具会在启动时自动读取当前目录的 .env 文件。.env 适合本机保存私有配置，真实文件已被 .gitignore 排除，仓库里只提交 .env.demo 模板。

也可以显式指定其他 dotenv 文件：

node dist/index.js --env-file ./.env.local

.env 不会覆盖已经存在的系统环境变量或 CI Secrets。因此同名变量同时存在时，优先级是：

CLI 参数
系统环境变量 / CI Secrets
.env 文件
配置文件
默认值

PowerShell 示例：

$env:SIYUAN_RESTORE_ENDPOINT = "https://cos.ap-guangzhou.myqcloud.com/"
$env:SIYUAN_RESTORE_ACCESS_KEY = "your-s3-access-key"
$env:SIYUAN_RESTORE_SECRET_KEY = "your-s3-secret-key"
$env:SIYUAN_RESTORE_BUCKET = "your-s3-bucket"
$env:SIYUAN_RESTORE_REGION = "ap-guangzhou"
$env:SIYUAN_RESTORE_AES_KEY = "your-base64-32-byte-aes-key"
$env:SIYUAN_RESTORE_OUTPUT = "./restored"
$env:SIYUAN_RESTORE_SNAPSHOT_ID = "latest"
$env:SIYUAN_RESTORE_FORMAT = "both"
$env:SIYUAN_RESTORE_RENAME = "title"
$env:SIYUAN_RESTORE_INCREMENTAL = "true"
$env:SIYUAN_RESTORE_INTERACTIVE = "false"
$env:SIYUAN_RESTORE_SUMMARY_FILE = "$env:TEMP\siyuan-restore-summary.json"
$env:SIYUAN_RESTORE_DOCS_ONLY = "true"
node dist/index.js

GitHub Actions 中推荐用 env: 绑定 secrets，详见 docs/CI.md。

纯 CLI 用法

node dist/index.js \
  --endpoint "https://cos.ap-guangzhou.myqcloud.com/" \
  --access-key "your-s3-access-key" \
  --secret-key "your-s3-secret-key" \
  --bucket "your-s3-bucket" \
  --region "ap-guangzhou" \
  --aes-key "your-base64-32-byte-aes-key" \
  --output "./restored" \
  --snapshot-id latest \
  --format both \
  --rename title \
  --incremental \
  --no-interactive \
  --summary-file "$RUNNER_TEMP/siyuan-restore-summary.json" \
  --docs-only \
  --exclude history temp

如果需要只恢复某个笔记本：

node dist/index.js --notebook "技能飞跃"

如果需要一次恢复多个笔记本：

node dist/index.js --notebooks "技能飞跃,设计文档"

配置文件推荐写成数组：

{
  "notebooks": ["技能飞跃", "设计文档"]
}

如果需要固定快照，避免交互选择：

node dist/index.js --snapshot-id "your-snapshot-id"

CI 中建议使用默认非交互模式，并设置 --snapshot-id latest 或直接省略 snapshotId，让工具自动恢复最新快照。

FilesExpand file tree

CLI_USE.md

Latest commit

History