Unison 2.54.0 常用 CLI 命令与工具详解

Unison 2.54.0 CLI 全解:三种调用形态、交互界面两级菜单按键全表、-batch/-auto/-silent/-terse 四档非交互、-force/-path/-ignore 裁决过滤、ssh -testserver 与 socket 常驻(-socket 8143)、-repeat 定时与 watch 实时实测,锁文件/版本不互通/host key 排障实录。

UnisonUnisonLinux文件传输CLI2026/11/01

Unison 2.54.0 常用 CLI 命令与工具详解

目标：把 Unison 2.54.0 的命令行用法一次讲全——命令调用形态、两级交互界面按键、非交互参数、ssh/socket 两种远端通道、定时循环与日志排障，全部配实测回显。已在两台 Ubuntu 22.04 服务器（node1/node2，均为 2.54.0）实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04（x86_64）
  • Unison 版本：2.54.0（官方二进制，unison version 2.54.0 (ocaml 4.14.3)）
  • 拓扑：node1（本地端）↔ node2（远端端），ssh 免密互通；socket 演示端口 8143
  • 本地演示目录：/srv/data-a、/srv/data-b（单机两目录）、/srv/data（远端同步演示）
  • 远端演示目录：node2 的 /srv/data
  • 按键帮助文本来源：实测在交互界面按 ? 的真实回显（原文较长，本文按功能归类整理，内容逐条对应实测输出）
  • 安装与环境准备见 《Ubuntu 22.04 安装 Unison 2.54.0 指南》；参数的 profile 写法见 《Unison 2.54.0 配置参数详解》

二、工具概览

Unison 的发行物只有三个可执行文件（官方二进制包 bin/ 下，实测 tar tzf 清单）：

可执行文件用途本文覆盖
unison主程序：同步器本体，文本/图形双界面（无 GTK 环境自动落到文本界面）全文
unison-fsmonitor文件系统监控辅助进程，供 -repeat watch 使用（Linux 基于 inotify）4.8 节
unison-guiGTK3 图形界面（无显示环境无法运行）不涉及（服务器场景用文本界面）

Unison 没有子命令体系——它是一个「单命令多形态」的 CLI，所有能力通过调用形态（两个 root、profile 名）与参数开关（-batch、-repeat 等）表达。另外它内置了一整套手册（-doc），可以不依赖任何外部文档直接在命令行查阅。

三、前置条件

  1. 两端已装同版本 Unison 2.54.0（版本不互通的报错与解决见本文 6.2 节与安装篇）。
  2. ssh 形态需要免密互通（unison /srv/data ssh://node2//srv/data -testserver 返回 Connected）。
  3. 本地形态（两目录）零前置，任意目录对即可。

四、核心命令详解

4.1 版本、帮助与内置手册

版本确认（排障第一步，两端都要看）：

unison -version

unison version 2.54.0 (ocaml 4.14.3)

快速帮助（unison -help，实测共 152 行，开头与分组结构如下）：

unison -help

实测回显（节选）：

Usage: unison [options]
    or unison root1 root2 [options]
    or unison profilename [options]

Basic options:

  General:
   -doc xxx            show documentation ('-doc topics' lists topics)
   -version            print version and exit

  What to sync:
   -group              synchronize group attributes
   -ignore xxx         add a pattern to the ignore list
   -ignorenot xxx      add a pattern to the ignorenot list
   -nocreation xxx     prevent file creations on one replica
   -nodeletion xxx     prevent file deletions on one replica
   -noupdate xxx       prevent file updates and deletions on one replica
   -owner              synchronize owner
   -path xxx           path to synchronize
   -perms n            part of the permissions which is synchronized
   -root xxx           root of a replica (should be used exactly twice)
   -times              synchronize modification times

  How to sync:
   -batch              batch mode: ask no questions at all

Usage 三行就是三种调用形态：纯选项（配合默认 profile）、两个 root 直连、profile 名调用。

内置手册（2.54 起手册编译进了二进制，-doc 直接阅读）。主题列表（实测 unison -doc topics 全文）：

Documentation topics:
          about About Unison
         people People
      obtaining Obtaining Unison
    development Community, Maintenance, and Development
        copying Copying
            ack Acknowledgements
      upgrading Upgrading
       tutorial Tutorial
         basics Basic Concepts
       failures Invariants
        running Running Unison

Type "unison -doc <topic>" for detailed information about <topic>
or "unison -doc all" for the whole manual

抽查一个主题（实测 unison -doc running，节选）：

Running Unison

   There are several ways to start Unison.
     * Typing "unison profile" on the command line. Unison will look for a
       file profile.prf in the .unison directory. ...

unison -doc all 输出整本手册（上千行，可接 less 或重定向落盘慢慢查）。装了官方二进制 = 自带离线手册，断网服务器上查参数不必翻网站。

4.2 两种基本调用形态

形态一：两个 root 直连（适合临时/一次性同步）：

unison /srv/data-a /srv/data-b -batch

实测回显（首次同步，全文节选——首次会提示没有 archive 并说明将按「两侧均为空」推演）：

Unison 2.54.0 (ocaml 4.14.3): Contacting server...
Looking for changes
Warning: No archive files were found for these roots, whose canonical names are:
	/srv/data-a
	/srv/data-b
This can happen either
because this is the first time you have synchronized these roots,
or because you have upgraded Unison to a new version with a different
archive format.

...（中间为推演说明与 DHCP 主机名提示，输出节选）...

Reconciling changes
file     ---->            app.conf
data-a       : file               modified on 2026-11-01 at  7:02:03  size 3         rw-r--r--
data-b       : absent
file     ---->            readme.txt
data-a       : file               modified on 2026-11-01 at  7:02:03  size 13        rw-r--r--
data-b       : absent

2 items will be synced, 0 skipped
16 B to be synced from data-a to data-b
0 B to be synced from data-b to data-a
Propagating updates
Saving synchronizer state
Synchronization complete at 07:04:48  (2 items transferred, 0 skipped, 0 failed)

验证对侧落盘：

ls -l /srv/data-b/ && cat /srv/data-b/readme.txt

total 8
-rw-r--r-- 1 root root  3 Nov  1 07:04 app.conf
-rw-r--r-- 1 root root 13 Nov  1 07:04 readme.txt
hello unison

形态二：profile 名调用（日常推荐，参数沉淀在 ~/.unison/<名>.prf）：

unison myrepo

实测回显（首行）：

Unison 2.54.0 (ocaml 4.14.3): Contacting server...
Connected [//node1//srv/prof-a -> //node2//srv/prof-b]

双向传播实测（形态一基础上，两侧同时改，一次同步互传）：

echo 'hello unison v2' > /srv/data-a/readme.txt
echo 'notes from data-b' > /srv/data-b/notes.md
unison /srv/data-a /srv/data-b -batch

实测回显（节选——A 侧的修改向右传，B 侧的新文件向左传，一单完成）：

Reconciling changes
         <---- new file   notes.md
data-a       : absent
data-b       : new file           modified on 2026-11-01 at  7:04:59  size 18        rw-r--r--
changed  ---->            readme.txt
data-a       : changed file       modified on 2026-11-01 at  7:04:59  size 16        rw-r--r--
data-b       : unchanged file     modified on 2026-11-01 at  7:02:03  size 13        rw-r--r--

2 items will be synced, 0 skipped

验证两向都到齐：

cat /srv/data-b/readme.txt && cat /srv/data-a/notes.md

hello unison v2
notes from data-b

4.3 交互界面按键全解（reconciling 与 proceed 两级菜单）

不带 -batch 运行即进入交互文本界面，有两级菜单：先逐项确认传播方向（reconciling），确认后进入整批放行（proceed）。

第一级：reconciling 菜单。变更清单逐行列出，行尾 [f] 是 Unison 的推荐动作；此级按 ? 弹出完整按键帮助。实测按键全表（按功能归类，内容逐条来自实测回显）：

类别按键作用
基础确认<ret> / f / <spc>按推荐动作处理当前项
移动n/j/<down>/<tab>、p/b/k/<up>/<shift+tab>下一条 / 上一条
移动0/<home>、9/<end>、5/<pg down>、6/<pg up>跳到清单首/尾/中部前后
移动<del>/<bsp>撤销当前项并回退上一条
方向裁决> 或 . 或 <right>当前（或匹配）项从左向右传播
方向裁决< 或 , 或 <left>从右向左传播
方向裁决] 或 "、[ 或 '冲突按较新 / 较旧裁决
方向裁决c冲突按「已修改」一侧裁决
方向裁决i、R反转传播方向 / 反转清单顺序
查看详情d、x、L、l显示差异 / 详情 / 简明列表 / 详细列表
批量匹配A 或 *、1、2、C、P 或 =、M匹配后续全部 / 全部左→右 / 全部右→左 / 全部冲突 / 全部仅属性变化 / 全部合并项
匹配运算X 或 !、&、|、D 或 _、U 或 $取反 / 与 / 或 / 删除匹配条件 / 取消匹配
恢复默认r 或 u放弃人工方向，恢复 Unison 推荐
忽略I、E、N永久忽略此路径 / 此扩展名 / 以此结尾的路径（写入 profile）
跳过/ 或 :、%、-、+跳过当前 / 跳过后续全部 / 本会话丢弃 / 丢弃后续全部
推进退出s、g、q 或 <esc>停止调和进入放行菜单 / 立即传播 / 不传播直接退出
其他m、x合并当前项（需配置 merge 命令）/ 显示详情

实测样例（造一个左→右变更后按 ? 再按 >，节选）：

data-a         data-b
changed  ---->            readme.txt  [f] ?
Commands:
  <ret> or f or <spc>   follow unison's recommendation (if any)
  ...
  > or . or <right>     propagate from left to right (curr or match)
  < or , or <left>      propagate from right to left (curr or match)
  ...
changed  ---->            readme.txt  [f]

1 items will be synced, 0 skipped
8 B to be synced from data-a to data-b
0 B to be synced from data-b to data-a

Proceed with propagating updates? [] >

第二级：proceed 菜单。调和完成后询问「是否整批传播」，实测按 ? 的帮助全文：

Commands:
  y or g                Yes: proceed with updates as selected above
  n                     No: go through reconciliation process again
  p or b                go back to the last item of the reconciliation
  N                     sort by Name
  S                     sort by Size
  W                     sort neW first (toggle)
  D                     Default ordering
  R                     Reverse the sort order
  q or <esc>            exit unison without propagating any changes

实测确认传播（按 y 后）：

Proceed with propagating updates? [] y
Propagating updates
Starting...
Unison 2.54.0 (ocaml 4.14.3) started propagating changes at 07:06:09.40 on 01 Nov 2026
[BGN] Updating file readme.txt from /srv/data-a to /srv/data-b
[END] Updating file readme.txt
Saving synchronizer state
Synchronization complete at 07:06:09  (1 item transferred, 0 skipped, 0 failed)

⚠️ 注意（实测踩坑点）：proceed 菜单的回车不是默认确认——实测直接回车得到 No default command [type '?' or F1 for help]，必须显式按 y/g。另外 <ret>/f 在 reconciling 菜单对冲突项无效（冲突没有推荐动作，括号里是空的），必须人工给方向。

4.4 非交互模式：-batch / -auto / -silent / -terse

四档自动化程度，实测对比：

-batch：不问任何问题，非冲突自动传播、冲突跳过。冲突实测（两侧同改 readme.txt）：

unison /srv/data-a /srv/data-b -batch

Reconciling changes
changed  <-?-> changed    readme.txt
data-a       : changed file       modified on 2026-11-01 at  7:05:10  size 12        rw-r--r--
data-b       : changed file       modified on 2026-11-01 at  7:05:10  size 12        rw-r--r--

0 items will be synced, 1 skipped
0 B to be synced from data-a to data-b
0 B to be synced from data-b to data-a
No updates to propagate
Synchronization complete at 07:05:10  (0 items transferred, 1 skipped, 0 failed)

冲突文件两侧原样保留（0 transferred / 1 skipped），cron 场景必选。

-auto：非冲突项自动过，冲突项仍停在人工。实测（A 侧新文件 + B 侧新文件 + 冲突文件并存时）只把冲突项留在交互区：

data-a         data-b
new file  <-?-> new file   conf.txt  []

-terse：压掉状态消息，保留变更清单与传播结果。实测输出节选：

new file ---->            terse.txt
[BGN] Copying terse.txt from /srv/data-a to /srv/data-b
[END] Copying terse.txt

-silent：除错误外零输出（手册注明设置它自动置 batch=true），最安静的一档，适合 cron 重定向到日志文件的场景。

4.5 方向裁决与路径过滤：-force / -prefer / -path / -ignore

命令行版的方向裁决（profile 语义详见配置篇 5.5 节，此处给命令形态与实测结论）：

# 冲突场景下强制以左侧为准（实测：方向箭头变 ====>
unison /srv/data-a /srv/data-b -batch -force /srv/data-a

changed  ====> changed    readme.txt

1 items will be synced, 0 skipped

cat /srv/data-b/readme.txt
# edit from A

# 只同步指定子路径（可重复多条 -path）
unison /srv/data-a /srv/data-b -batch -path sub1

实测（节选）只出现 sub1/f1.txt，目录外文件不动：

new file ---->            sub1/f1.txt

1 items will be synced, 0 skipped

# 命令行临时忽略（本次生效）
unison /srv/data-a /srv/data-b -batch -ignore 'Name *.tmp'

4.6 ssh 远程同步：-testserver 与 ssh:// URI

先测连通（只握手不动数据，装好后第一件事就是它）：

unison /srv/data ssh://node2//srv/data -testserver

实测回显：

Unison 2.54.0 (ocaml 4.14.3): Contacting server...
Connected [//node1//srv/data -> //node2//srv/data]

URI 全形态（实测 ssh://root@node2:22//srv/data 的 -testserver 同样返回 Connected）：

ssh://node2//srv/data                    # 当前用户 + 默认 22 端口 + 绝对路径
ssh://root@node2:22//srv/data            # 指定用户与端口
ssh://node2/srv/data                     # 单斜杠 = 相对远端家目录的路径

同步执行（免密就绪后与本地形态无异）：

echo 'remote sync test' > /srv/data/remote.txt
unison /srv/data ssh://node2//srv/data -batch

实测回显（节选——调和清单里左右两列直接显示主机名）：

Reconciling changes
file     ---->            remote.txt
local        : file               modified on 2026-11-01 at  7:06:20  size 17        rw-r--r--
node2        : absent

1 items will be synced, 0 skipped
17 B to be synced from local to node2
0 B to be synced from node2 to local
Propagating updates
Synchronization complete at 07:06:21  (1 item transferred, 0 skipped, 0 failed)

远端落盘验证（node2 上）：

ls -l /srv/data/remote.txt && cat /srv/data/remote.txt

-rw-r--r-- 1 root root 17 Nov  1 07:06 remote.txt
remote sync test

ssh 免密与 host key 的前置配置（ssh-keygen/ssh-copy-id/ssh-keyscan）见安装篇第八章。

4.7 socket 模式常驻：-socket 服务端与 socket:// 客户端

socket 模式让远端以明文 TCP 常驻监听（内网性能敏感场景用；跨公网走 ssh）。服务端（node2，后台常驻并验证监听）：

nohup unison -socket 8143 >/tmp/unison-socket.log 2>&1 &

ss -ltn | grep 8143

实测回显：

LISTEN 0      1            0.0.0.0:8143       0.0.0.0:*
LISTEN 0      1               [::]:8143          [::]:*

客户端（node1，root 用 socket://主机:端口//绝对路径）：

echo 'socket mode test' > /srv/data/via-socket.txt
unison /srv/data socket://node2:8143//srv/data -batch

实测回显（节选）：

Unison 2.54.0 (ocaml 4.14.3): Contacting server...
Connected [//node1//srv/data -> //node2//srv/data]

Looking for changes
  Waiting for changes from server
Reconciling changes
new file ---->            via-socket.txt
local        : new file           modified on 2026-11-01 at  7:06:57  size 17        rw-r--r--
node2        : absent

1 items will be synced, 0 skipped
17 B to be synced from local to node2
0 B to be synced from node2 to local
Propagating updates
Synchronization complete at 07:06:57  (1 item transferred, 0 skipped, 0 failed)

远端验证（node2）：

ls -l /srv/data/via-socket.txt && cat /srv/data/via-socket.txt

-rw-r--r-- 1 root root 17 Nov  1 07:06 via-socket.txt
socket mode test

⚠️ 注意：-socket 监听的是明文协议且默认绑定所有网卡（0.0.0.0），不要暴露到公网；生产长期常驻建议用 systemd 托管该命令并配合防火墙限源。

4.8 定时循环：-repeat N / watch / 组合

-repeat 把一次同步变成前台循环。定秒循环实测（-repeat 5 每 5 秒一轮，运行中改文件验证第 2 轮捕获）：

unison /srv/data-a /srv/data-b -batch -repeat 5 &
sleep 7; echo repeat-round-2 > /srv/data-a/readme.txt
sleep 12

实测日志（grep -E 'Looking for changes|Synchronization complete'，12 秒内共 4 轮检测，第 2 轮把中途修改传播过去）：

Looking for changes
Looking for changes
Looking for changes
Synchronization complete at 07:07:20  (1 item transferred, 0 skipped, 0 failed)
Looking for changes

实时触发实测（-repeat watch，依赖 unison-fsmonitor）：

unison /srv/data-a /srv/data-b -batch -repeat watch &
sleep 6; echo watch-trigger > /srv/data-a/watch.txt

实测：写入后秒级触发（日志）：

Looking for changes
Synchronization complete at 07:07:55  (1 item transferred, 0 skipped, 0 failed)

ls /srv/data-b/watch.txt
# /srv/data-b/watch.txt

组合形态 watch+3600：实时响应 + 每小时一次全量兜底扫描（官方手册推荐写法，防 inotify 漏事件），profile 写法 repeat = watch+3600。进程前台运行、退出即停——长期无人值守交给 cron/systemd timer（见安装篇第九章）或 tmux/nohup。

4.9 日志查看：unison.log 与 logfile

log=true（默认开）时，每次同步的时间、roots 与每条变更都写入日志。默认位置 ~/.unison/unison.log，实测首部（cat /root/.unison/unison.log）：

Unison 2.54.0 (ocaml 4.14.3) log started at 2026-11-01 at  7:02:03

Roots:
  /srv/data-a
  /srv/data-b

自定义位置（profile 里 logfile = /var/log/unison-myrepo.log）后实测尾部：

[BGN] Copying shared from /srv/prof-a to //node2//srv/prof-b
[END] Copying shared
Unison 2.54.0 (ocaml 4.14.3) finished propagating changes at 07:08:31.93 on 01 Nov 2026, 0.003 s
Synchronization complete at 07:08:31  (1 item transferred, 0 skipped, 0 failed)

排障时最常用两条：

grep -c 'Synchronization complete' /var/log/unison-myrepo.log   # 历史成功轮数
tail -20 /var/log/unison-myrepo.log                             # 最近一轮结果

五、注意事项

  1. 先 -testserver 后同步：ssh/socket 形态首次使用先跑连通性测试，避免半路断链产生半同步状态。
  2. cron 里必须 -batch：-auto 会在冲突处等待输入挂死任务；-batch 冲突自动跳过、数据无损，事后人工处理。
  3. 交互界面冲突项没有默认动作：推荐动作 [f] 只对方向明确的变更存在；冲突项（<-?->）必须人工按键（>/</]/[ 或 / 跳过）。proceed 菜单回车无效，要显式 y。
  4. -force 是镜像语义：连非冲突变更一起单向摆平，双向备份场景误用会把对端合法变更覆盖掉；只裁决冲突用 -prefer。
  5. socket 模式是明文协议：只在内网用，且 -socket 默认绑 0.0.0.0，注意防火墙。
  6. 远端实际版本要单独确认：ssh 形态下远端执行的是远端 PATH 里的 unison（ssh root@node2 unison -version 确认），本机两个版本共存时极易连错。
  7. 强杀进程会留锁文件：报错会给文件名，按提示删除即可（见 6.1），不要养成 -9 杀 unison 的习惯。

六、常见问题

6.1 锁文件残留：the archives are locked

现象（上次进程被强杀后重跑，实测全文）：

Error: Warning: the archives are locked.
If no other instance of unison is running, the locks should be removed.
The file /root/.unison/lkc3c49bc1af286a2cec215596a66e576f on host node1 should be deleted
The file /root/.unison/lka231eee0b488e555a22c8746a1ab4c54 on host node1 should be deleted
Please delete lock files as appropriate and try again.

解决（报错已给出完整指引）：

pgrep -a unison          # 确认没有其他实例在跑
rm -f /root/.unison/lk*  # 删除锁文件（lk 前缀即全部锁）
unison /srv/data-a /srv/data-b -batch   # 重跑，恢复正常

6.2 两端版本不一致：Received unexpected header from the server

现象（本地 2.51.5 连远端 2.54.0，实测全文）：

Unison 2.51.5 (ocaml 4.13.1): Contacting server...
Fatal error: Received unexpected header from the server:
 expected "Unison 2.51 with OCaml >= 4.01.2\n" but received "Unison RPC\nVERSIONS 1\n",
which differs at "Unison R".
This can happen because you have different versions of Unison
installed on the client and server machines, or because
your connection is failing and somebody is printing an error
message, or because your remote login shell is printing
something itself before starting Unison.

解决：先两端与远端实际生效版本各查一遍（unison -version 与 ssh root@node2 unison -version），统一主版本（2.54.0 起不再与 2.52.0 之前互通，官方 NEWS 明示）。若版本一致仍报错，再按报错提示排查「远端登录 shell 是否打印了额外内容」：ssh root@node2 'echo ok' 输出里应只有 ok，多出来的 motd/echo 都会污染 Unison 的握手头。

6.3 Host key verification failed

现象（known_hosts 缺少对端指纹时，实测全文）：

Unison 2.54.0 (ocaml 4.14.3): Contacting server...
Host key verification failed.

Error: Lost connection with the server

解决：

ssh-keyscan -H node2 >> /root/.ssh/known_hosts   # 预录入指纹
unison /srv/data ssh://node2//srv/data -testserver
# Connected [//node1//srv/data -> //node2//srv/data]

或人工 ssh root@node2 hostname 一次并回答 yes。cron 里跑 Unison 必须先做这一步（非交互环境无法回答指纹确认）。

6.4 -repeat watch 无反应或报 fsmonitor 缺失

-repeat watch 依赖 unison-fsmonitor 辅助进程（与主程序同版本、同 PATH）。官方二进制包自带，确认已安装：

which unison-fsmonitor || install -m755 unison-2.54.0-ubuntu-22.04-x86_64/bin/unison-fsmonitor /usr/local/bin/

apt 仓库版（2.51.5）不附带该程序，实时监控建议用官方二进制（见安装篇方案 B）。

七、参考链接

  1. Unison v2.54.0 官方手册（unison -doc topics / -doc all 内置手册；随发布件 doc/unison-manual.txt）——交互按键语义权威出处
  2. unison -help（2.54.0，152 行，实测全文随附官方二进制）
  3. GitHub 仓库：https://github.com/bcpierce00/unison （v2.54.0，查询日期 2026-11-01）
  4. 同专栏前置阅读：《Unison 介绍与选型指南》、《Ubuntu 22.04 安装 Unison 2.54.0 指南》、《Unison 2.54.0 配置参数详解》