教程

在服务器 / NAS 上用命令行同步（obsync-cli）

手机电脑同步插件 · ·使用教程
命令行服务器NASheadless

一、这是什么，适合谁

obsync-cli 是「手机电脑同步」的命令行客户端——和手机 / 电脑上的插件用的是同一套端到端加密同步引擎，只是把它做成了一个在终端里跑的命令，安装后命令名是 obsync。

它适合这些场景：

  • 一台 Linux / macOS 服务器上放着一个笔记库，想让它和你手机、电脑上的笔记保持一致；
  • 用 cron 定时任务把服务器上生成的内容（脚本产物、日报、剪藏）同步进你的库；
  • NAS / 群晖上常驻一个同步进程；
  • CI / 自动化流程里读写同一个加密库。

你的笔记在离开这台机器之前就已经用你本地掌管的密钥加密，服务器上只存密文——和图形版插件完全一样的安全性。

这是一篇给会用命令行的用户的进阶教程。如果你只是想在手机和电脑之间同步，用图形界面插件就够了，见《介绍与安装使用入门》。

二、开始之前

你需要准备：

  1. Node.js ≥ 20（在这台机器上，node -v 能看到版本号）。
  2. 一个已经存在的同步库。命令行版只接入已有的库，不新建库——新建库请先用手机 / 电脑插件或网页版创建好，再用命令行接入。
  3. 接入这个库的凭据，二选一：
    • 这个库的恢复密钥（在插件里导出的那串密钥，最适合服务器，无需人工确认）；或
    • 一台已登录并在线的设备，用来在配对时批准 / 生成配对码。

三、安装

方式一：用 npm 从下载地址直接安装（推荐）

npm install -g https://shoujidiannao.bijitongbu.site/downloads/obsync-cli-latest.tgz

装完验证一下：

obsync --version      # 显示 obsync 0.1.0
obsync --help         # 列出所有命令

方式二：下载单文件放进 PATH（不想用 npm 时）

curl -fL -o /usr/local/bin/obsync \
  https://shoujidiannao.bijitongbu.site/downloads/obsync.cjs
chmod +x /usr/local/bin/obsync
obsync --version

这个单文件是自包含的，除了 Node.js 本身，不需要再装任何依赖。

四、第一次使用（四步）

第 1 步：登录

obsync login

它会打印一个 6 位验证码，你通过微信把这个码发给 「笔记同步助手」公众号即可完成登录——和插件里的登录是同一套流程，具体怎么发码见这里。登录成功后凭据会保存在 ~/.config/obsync/credentials.json。

💡 无人值守 / 自动化怎么办？ 登录的唯一入口就是微信 6 位码——但微信只需要做一次。在任意一台能用微信的机器上（也可以就是这台服务器）跑一次 obsync login，登录成功后会拿到一个长期有效的登录令牌（token），存在 ~/.config/obsync/credentials.json 里。把这个令牌拷到服务器，用 obsync login --token <你的令牌>（或设环境变量 OBSYNC_TOKEN）注入即可，之后这台机器就不用再碰微信了。也就是说：微信换一次令牌，后续自动化全靠这个令牌。

第 2 步：看看账号下有哪些库

obsync sync-list-remote

会列出你账号下所有可同步的库（id / 名称 / 机房 / 大小 / 创建时间），记下你要接入的那个库的名字。

第 3 步：把当前目录接入一个库

进入你要用作同步目录的文件夹，然后二选一接入：

A. 用恢复密钥接入（推荐，最适合服务器）

先在手机 / 电脑插件里导出这个库的恢复密钥，存成一个文本文件（比如 vault-key.txt），拷到服务器上，然后：

cd /srv/my-vault
obsync sync-setup --recovery-key-file vault-key.txt

B. 用配对码接入

在另一台已登录的设备上为这个库生成一个配对码，然后：

cd /srv/my-vault
obsync sync-setup --pairing-code 123456

这种方式会要求你在终端里核对一串安全码（形如 042-815 苹果 火车），必须和另一台设备屏幕上显示的完全一致才输入 y——这是防中间人的最后一道人工闸，别跳过。

接入成功后，会在这个目录下建一个 .obsync/ 状态目录（保存绑定信息和同步进度）。这个目录永远不会被上传，也不要把它复制到别的库里。

第 4 步：开始同步

同步一轮（下载 + 上传，跑到收敛后自动退出）：

obsync sync

想让它一直守着、有变化就自动同步：

obsync sync --continuous

五、让它自动、持续地同步

服务器场景一般希望它无人值守地跑。两种做法：

方式一：常驻进程（--continuous）

obsync sync --continuous 会一直运行、监听文件变化并持续同步。用 systemd 让它开机自启、崩了自动拉起（用户级 service 示例）：

# ~/.config/systemd/user/obsync.service
[Unit]
Description=obsync 持续同步 /srv/my-vault
After=network-online.target

[Service]
ExecStart=/usr/local/bin/obsync sync --continuous --path /srv/my-vault
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target
systemctl --user daemon-reload
systemctl --user enable --now obsync.service
systemctl --user status obsync.service

方式二：定时任务（cron）

如果不需要实时、只要定期同步，用 cron 每隔几分钟跑一轮就行：

# 每 10 分钟同步一次 /srv/my-vault
*/10 * * * * /usr/local/bin/obsync sync --path /srv/my-vault >> ~/obsync.log 2>&1

⚠️ cron 里怎么判断成功：退出码 0 = 已同步完成；退出码 5 = 这一轮没在预算内跑完（弱网 / 大库首次下载），这不是失败——下一次定时任务会从已保存的进度继续，不要把它当成报警。真正需要关注的是退出码 6（确有文件永久无法同步，会给出清单）。

六、命令一览

命令作用
obsync login微信 6 位码登录；--token 可直接注入登录态
obsync logout撤销服务端登录态 + 清本地凭据；--local-only 只清本地
obsync sync-list-remote列出账号下可同步的库
obsync sync-setup接入一个已有库：--recovery-key-file 或 --pairing-code
obsync sync同步一轮到收敛；--continuous 常驻持续同步
obsync sync-config读写本库配置：get / set <键> <值>
obsync sync-status只读查看同步状态
obsync sync-unlink本地解绑（删 .obsync/，不动任何笔记、不删服务端数据）

所有命令都支持 --json（机器可读输出，方便脚本处理）、--path <目录>（指定库目录，默认当前目录）。

七、常用配置

obsync sync-config get                        # 打印当前全部配置
obsync sync-config set conflictAction merge   # 冲突处理策略
obsync sync-config set excludedFolders '["templates",".trash"]'   # 不同步的文件夹
obsync sync-config set perFileMax 52428800    # 单文件大小上限（字节）
obsync sync-config set deviceName my-nas      # 本设备显示名

八、退出码（写脚本时可依赖）

退出码含义
0成功 / 已同步完成
2参数用法错误
3未登录 / 登录失效 → 重新 obsync login
4未接入 / 库不存在 / 密钥不匹配
5未跑完（瞬时，可重试）——不是失败，下次会续上
6确有文件永久无法同步（会列出清单）
7已有一个实例在同步这个库（同一库同一时刻只允许一个进程）
8触发了批量删除保护，需人工确认放行

九、数据安全

命令行版和图形版遵循同一条第一铁律：宁可不同步，绝不丢数据。

  • .obsync/ 状态目录被硬排除，永远不上传；
  • obsync sync-unlink 只删本地绑定状态，绝不触碰你的任何笔记文件、绝不删服务端数据；
  • 读到空文件 / 读失败时不会把它当成正常版本推上去覆盖别的设备；
  • 断网、超时这类瞬时错误会自动退避重试，不会谎报「同步失败」。

🔑 请务必保管好你的恢复密钥。 笔记是端到端加密的，密钥只在你手里——密钥丢了，服务器也无法帮你解开任何数据。

十、常见问题

  • obsync sync 返回退出码 5？ 正常，表示这一轮没在时间预算内跑完（弱网或大库首次下载），再跑一次会从已保存的进度继续，不是错误。
  • sync-status 显示 disconnected？ 只是当前没有活动连接，跑一次 obsync sync 即可。
  • 提示未登录（退出码 3）？ 登录态失效，重新 obsync login。
  • 提示已有实例在跑（退出码 7）？ 同一个库目录同一时刻只允许一个 obsync 进程；检查是不是有 --continuous 常驻进程或另一个定时任务在跑同一个库。