Ubuntu 22.04 安装 Unison 2.54.0 指南

Ubuntu 22.04 双服务器安装 Unison 实测:apt 仓库版 2.51.5、官方二进制 2.54.0(sha256 校验)、源码编译 make tui(含 UISTYLE 弃用与 codeload 降级实录)三路径对比,ssh 免密与 -testserver 连通验证,版本不互通/host key/锁文件排障实录。

UnisonUnisonLinux文件传输CLI2026/11/01

Ubuntu 22.04 安装 Unison 2.54.0 指南

目标：在两台 Ubuntu 22.04 服务器上完成 Unison 安装（含发行版仓库版、官方二进制版、源码编译版三条路径），并配置 ssh 免密互通，最终通过 -testserver 连通性验证，具备双向同步条件。全部命令与回显已在两台 Ubuntu 22.04 服务器（node1/node2）实测通过。

一、环境信息

本文实测环境为两台全新 Ubuntu 22.04 服务器，配套信息如下：

  • 操作系统：Ubuntu 22.04（x86_64，GNU/Linux）
  • 服务器角色：node1（本地端）、node2（远端端），两台均安装 Unison
  • 目标软件：Unison 2.54.0（官方最新稳定版，2026-05-01 发布；查询日期 2026-11-01）
  • 发行版仓库版本：unison 2.51.5+1（Ubuntu 22.04 jammy 官方仓库，实测 apt-cache policy 确认）
  • 语言运行时（源码编译用）：OCaml 4.13.1（Ubuntu 22.04 仓库版）、make（GNU Make）
  • 数据目录：/srv/data（演示用同步目录）
  • 下载渠道：GitHub Releases 与 codeload.github.com（下载受阻时的降级实录见对应章节）
  • 两台服务器均使用 root 账户操作（演示环境；生产建议普通用户 + sudo）

二、前置条件

  1. 两台服务器网络互通：node1 能按主机名或 IP 访问 node2 的 22 端口（ssh 模式必需；socket 模式另有端口要求，见命令篇）。
  2. 基础工具齐备：wget（下载）、tar（解压）、openssh-client（ssh 连通），Ubuntu 22.04 默认自带；缺失时：
apt update
apt install -y wget tar openssh-client
# 输出节选（实测）：
# Setting up wget (1.21.2-2ubuntu1) ...

  1. 对时间一致性的建议：两端系统时间应一致（NTP 对时），Unison 按修改时间判断「较新」，时间漂移会影响 ]/[（按新旧取舍冲突）类操作的语义。Ubuntu 22.04 默认启用 systemd-timesyncd，无需额外配置。

  2. 磁盘空间：Unison 本体约 5.5 MB，另需为每对 root 预留 ~/.unison/ 下 archive 状态文件的空间（与被同步文件数量成正比，万级文件在数 MB 量级）。

三、版本选型说明

Unison 当前存在两条活跃版本线，选型前必须先看这张表：

版本来源实测版本串特点与适用
2.51.5+1Ubuntu 22.04 发行版仓库unison version 2.51.5 (ocaml 4.13.1)免编译开箱即用，但版本老（2017 年维护线）；只能与同为 2.51.x 的对端互通
2.54.0 官方二进制GitHub Releasesunison version 2.54.0 (ocaml 4.14.3)最新稳定版，官方 CI 构建，含 unison-fsmonitor；推荐生产使用
2.54.0 源码编译GitHub 源码包unison version 2.54.0 (ocaml 4.13.1)适合需要自定义（如无 GUI、特定 PREFIX）或架构无官方二进制的场景

⚠️ 注意（选型的决定性约束）：Unison 两端版本必须一致。官方 NEWS.md（v2.54.0）明确："Unison will no longer interoperate with versions before 2.52.0 and will no longer read pre-2.52.0 archive files"——2.54.0 与 2.51.5 无法互通（实测报错全文见「常见问题」）。所以选型的第一步是确认两端能装到同一版本：两台都是 Ubuntu 22.04 且走仓库 → 都用 2.51.5；想用 2.54.0 → 两台都按方案 B/C 装 2.54.0。

💡 技术拓展：版本共存的实际含义——同一台服务器可以同时存在两个 Unison（apt 的 2.51.5 在 /usr/bin/unison，官方 2.54.0 在 /usr/local/bin/unison），PATH 默认先命中 /usr/local/bin。但 ssh 模式下远端执行的 unison 也走远端 PATH，两端各存在两个版本时极易「本地 2.54 连到远端 2.51」，这正是版本不兼容报错的常见来源。建议明确保留一个版本，或用绝对路径调用。

四、安装方案 A：发行版仓库在线安装（apt，2.51.5）

4.1 方案说明

Ubuntu 22.04 官方仓库自带 unison 包，一条命令完成安装，依赖由 apt 解决。优点是快、稳、好卸载；缺点是版本停留在 2.51.5，与 2.54.0 的新特性（如官方二进制、新交互界面）无缘，且必须保证对端同为 2.51.x。

4.2 安装步骤

node1 与 node2 分别执行同一条安装命令（两端都要装，这是双向同步的前提）：

apt update && apt install -y unison
# 输出节选（实测，node1）：
# Setting up unison (2.51.5+1) ...

安装完成后查看仓库版本信息：

apt-cache policy unison | head -4

实测回显（node1）：

unison:
  Installed: 2.51.5+1
  Candidate: 2.51.5+1
  Version table:

4.3 验证

/usr/bin/unison -version

实测回显（node1，注意 apt 版装在 /usr/bin/unison）：

unison version 2.51.5 (ocaml 4.13.1)

node2 同样执行并确认同版本输出。两端版本串一致后，方案 A 的安装即告完成。

💡 说明：Unison 无常驻服务进程，不涉及 systemd 服务托管——安装即完成，systemctl 对它没有意义。定时同步的托管形态（cron / systemd timer）见本文「配置说明」一节。

五、安装方案 B：官方二进制安装（2.54.0，推荐）

5.1 方案说明

Unison 2.54.0 起官方在 GitHub Releases 提供 CI 构建的二进制。Linux 平台提供三个包（v2.54.0 Releases 资产清单，查询日期 2026-11-01）：

资产文件适用场景
unison-2.54.0-ubuntu-22.04-x86_64.tar.gzUbuntu 22.04 x86_64 标准版（本文采用）
`unison-2.54.0-ubuntu-22.04-x86_64-static.tar.gz静态链接版，glibc 老的系统也能跑
unison-2.54.0-ubuntu-22.04-i386.tar.gz32 位老系统

包内包含：bin/unison（主程序）、bin/unison-fsmonitor（-repeat watch 实时监控辅助程序）、bin/unison-gui（图形界面，需 GTK3 环境）、doc/unison-manual.pdf/.html/.txt（离线手册）、man/unison.1。

5.2 下载（含网络情况说明）

cd /tmp
wget -O u2540.tar.gz https://github.com/bcpierce00/unison/releases/download/v2.54.0/unison-2.54.0-ubuntu-22.04-x86_64.tar.gz

实测回显（node1，官方源直连成功）：

-u2540.tar.gz        100% [=================================>]   4.87M  --.-KB/s    in 0.1s

2026-11-01 07:05:51 (47.9 MB/s) - 'u2540.tar.gz' saved [5102308/5102308]

⚠️ 网络说明：官方 Releases 下载地址（github.com/bcpierce00/unison/releases/download/...）实测直连可用（约 4.9 MB，秒级完成）。若你的网络访问 GitHub 受阻，可换镜像加速站（如 docker.m.daocloud.io 同类的 GitHub 代理站）或为 wget 指定代理：wget -e use_proxy=yes -e https_proxy=http://<代理地址>:<端口> ...。

5.3 完整性校验与解压安装

下载完成后先做 sha256 校验（与同事间传递包或复查下载完整性时使用）：

sha256sum u2540.tar.gz

实测回显（node1）：

d3c41293069229238a4ea9320bc80dab4ee9f5e8171a24c5941a82a70b5c0abb  u2540.tar.gz

💡 说明：官方 Releases 页未发布逐文件的 sha256 清单，以上值是本次实测环境对所下载文件的实算结果；其价值在于「同一渠道重复下载时应得到同一指纹」，若指纹变化说明下载被截断或被替换，应重新下载。

解压查看内容并安装到 /usr/local/bin：

tar tzf u2540.tar.gz          # 先查看包内容（输出节选，实测）

unison-2.54.0-ubuntu-22.04-x86_64/
unison-2.54.0-ubuntu-22.04-x86_64/INSTALL.md
unison-2.54.0-ubuntu-22.04-x86_64/LICENSE
unison-2.54.0-ubuntu-22.04-x86_64/doc/unison-manual.pdf
unison-2.54.0-ubuntu-22.04-x86_64/bin/unison
unison-2.54.0-ubuntu-22.04-x86_64/bin/unison-fsmonitor
unison-2.54.0-ubuntu-22.04-x86_64/bin/unison-gui
unison-2.54.0-ubuntu-22.04-x86_64/NEWS.md

tar xzf u2540.tar.gz
install -m755 unison-2.54.0-ubuntu-22.04-x86_64/bin/unison \
              unison-2.54.0-ubuntu-22.04-x86_64/bin/unison-fsmonitor \
              /usr/local/bin/

顺手把离线手册放到系统文档目录，方便随时查阅：

install -m644 unison-2.54.0-ubuntu-22.04-x86_64/doc/unison-manual.txt /usr/share/doc/unison/

5.4 验证

which unison && unison -version

实测回显（node1；PATH 中 /usr/local/bin 优先，命中的是官方二进制）：

/usr/local/bin/unison
unison version 2.54.0 (ocaml 4.14.3)

⚠️ 注意：版本串中的 (ocaml 4.14.3) 是官方 CI 构建所用 OCaml 版本，与本地 apt 的 (ocaml 4.13.1) 不同——这不影响互通判定，互通看的是 Unison 主版本号（两台都 2.54.0 即可）。node2 按本节同样执行一遍，确认 unison -version 同样输出 2.54.0。

六、安装方案 C：源码编译安装（2.54.0）

6.1 方案说明与依赖

官方 INSTALL.md（v2.54.0）给出的构建前提：C99 编译器（gcc/clang）、OCaml ≥ 4.08、GNU make 及基础 POSIX 工具。Ubuntu 22.04 仓库的 OCaml 4.13.1 满足要求。纯命令行工具无需 GTK 依赖（有 lablgtk3 时 make 会连 GUI 一起构建；只要 CLI 用 make tui）。

apt install -y ocaml make

实测版本确认：

ocaml -version

The OCaml toplevel, version 4.13.1

6.2 下载源码（含下载受阻降级实录）

cd /tmp
wget -O src.tar.gz https://codeload.github.com/bcpierce00/unison/tar.gz/refs/tags/v2.54.0

实测回显（node1，codeload 直链直连成功）：

2026-11-01 07:15:13 (950 KB/s) - '/tmp/src.tar.gz' saved [1141341]

⚠️ 网络说明与降级实录：源码包经 https://github.com/bcpierce00/unison/archive/refs/tags/v2.54.0.tar.gz 下载时实测出现 0 字节空文件（该地址 302 跳转到 codeload.github.com，跳转后连接失败），改用 codeload 直链 https://codeload.github.com/bcpierce00/unison/tar.gz/refs/tags/v2.54.0 一次成功。遇到 0 字节下载时先删掉空文件再换 codeload 直链：

rm -f unison-2.54.0-src.tar.gz   # 清掉 0 字节残包，避免 tar 解压报错

tar xzf src.tar.gz
cd unison-2.54.0

6.3 编译（含 UISTYLE 报错排障实录）

先给一个错误示范（很多旧教程的写法）：

make UISTYLE=text

实测报错（2.54.0 已弃用该变量）：

cd src && make
make[1]: Entering directory '/tmp/unison-2.54.0/src'
Error: UISTYLE is no longer used. See build instructions.
make[1]: *** [Makefile:32: Makefile.cfg] Error 2
make[1]: Leaving directory '/tmp/unison-2.54.0/src'
make: *** [Makefile:22: src] Error 2

⚠️ 排障沉淀：UISTYLE 是 2.51 及更早版本的构建变量，2.54.0 起构建系统重写，官方 INSTALL.md 的正确方式是直接 make（自动检测 lablgtk3，有则连 GUI 一起构建）或 make tui（明确只要文本界面）、make gui（只要图形界面）、make fsmonitor（只要文件监控辅助程序）。

正确的编译命令（-j2 按 2 核并行，可按机器核数调整）：

make tui -j2

实测输出节选（编译过程共 200 余行 ocamlopt 调用，取首尾）：

ocamlopt -I +unix -I +str -c compat_digest.ml
ocaml make_tools.ml projectinfo NAME="unison" VERSION="2.54.0" MAJORVERSION="2.54" > ubase/projectInfo.ml
ocamlopt: osxsupport.c ---> osxsupport.o
...（中间为大量 .ml/.mli 编译行，输出节选）...

编译完成确认产物：

ls -la src/unison && ./src/unison -version

实测回显：

-rwxr-xr-x 1 root root 5489440 Nov  1 07:16 src/unison
unison version 2.54.0 (ocaml 4.13.1)

6.4 安装与验证

官方支持 make install 自定义 PREFIX 安装：

make install PREFIX=/opt/unison-2.54.0

实测输出（尾部）：

DESTDIR =
PREFIX = /opt/unison-2.54.0
install -d /opt/unison-2.54.0/bin
install src/unison /opt/unison-2.54.0/bin/unison

验证：

find /opt/unison-2.54.0 -type f | sort
/opt/unison-2.54.0/bin/unison -version

实测回显：

/opt/unison-2.54.0/bin/unison
unison version 2.54.0 (ocaml 4.13.1)

若要让它进入默认 PATH，做软链即可：

ln -sf /opt/unison-2.54.0/bin/unison /usr/local/bin/unison
unison -version
# unison version 2.54.0 (ocaml 4.13.1)

七、方案对比与选择建议

维度A：apt 仓库版B：官方二进制C：源码编译
版本2.51.5（老）2.54.0（最新）2.54.0（最新）
是否需联网需（apt 源）需（GitHub Releases）需（codeload + apt 依赖）
安装耗时秒级秒级（下载 4.9 MB）数分钟（OCaml 编译）
附带物仅主程序unison-fsmonitor + 离线手册 + man可定制 PREFIX，产物最精简
升级方式apt upgrade（跟随发行版节奏，慢）重新下载替换重新拉源码编译
适用两端都只能用 2.51.x 的存量环境生产推荐，绝大多数场景无对应架构二进制、或需定制安装路径

选择建议：能统一到 2.54.0 就统一到 2.54.0（两端同用方案 B 最省事）；只有当「对端是一台动不了的旧服务器且只能用仓库版」时，才两端一起退守方案 A 的 2.51.5。混装两版本是报错重灾区，见下一节。

八、SSH 服务与免密配置（ssh 模式前置）

ssh 是 Unison 最常用的远端通道（复用系统 sshd，无需另开端口）。本节把 node1 → node2 的免密打通，作为后续双向同步的基础。node2 需要装并启动 sshd（node1 若也要被反向同步，同样操作）。

8.1 远端安装并启动 sshd（node2）

apt install -y openssh-server
# 输出节选（实测）：
# Setting up openssh-server (1:8.9p1-3ubuntu0.13) ...

允许 root 登录（演示环境从简；生产环境建议普通用户 + sudo）并确认服务在监听：

sed -i 's/^#\?PermitRootLogin.*/PermitRootLogin yes/' /etc/ssh/sshd_config
systemctl restart ssh        # ⚠️ 需要 systemd 真机；无 systemd 的最小环境可用 /usr/sbin/sshd 直接拉起
systemctl is-active ssh

实测回显（真实服务器上）：

active

ss -ltn | grep ':22 '
# LISTEN 0      4096         0.0.0.0:22         0.0.0.0:*

8.2 密钥免密（node1 上执行）

ssh-keygen -t ed25519 -N '' -f /root/.ssh/id_ed25519

实测回显（节选）：

Generating public/private ed25519 key pair.
Your identification has been saved in /root/.ssh/id_ed25519
Your public key has been saved in /root/.ssh/id_ed25519.pub

把公钥推到 node2（首次会要求输入 node2 的 root 密码，演示环境为 q1w2e3r4）：

ssh-copy-id root@node2

实测回显（节选）：

Number of key(s) added: 1

免密验证：

ssh root@node2 'hostname'

实测回显：

node2

首次连接时若未先录入主机指纹，ssh 会卡在 Are you sure you want to continue connecting (yes/no/[fingerprint])? 交互——非交互场景（cron 里跑 Unison）会直接失败，报错与解决见「常见问题」。

8.3 连通性验证（-testserver）

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

实测回显（node1，两端均为 2.54.0）：

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

Connected 出现即代表「两端 unison 可执行 + ssh 通道 + 目录可访问」全部就绪，可以进入同步实测（见命令篇）。

九、配置说明

Unison 安装后的运行时布局与托管形态如下：

  1. 配置目录 ~/.unison/：首次运行自动创建，存放 profile（*.prf）、archive 状态文件（ar* 哈希命名）、锁文件（lk*）与日志（unison.log）。首跑后实测内容：
default.prf                        # 默认 profile（空模板）
ar474816c9dfc3975f1790bdb11c1a1b11 # archive 状态文件（按 root 路径哈希命名）
unison.log                         # 同步日志（log=true 时）

  1. 两端一致性清单：两端 Unison 主版本一致（unison -version 核对）；两端时钟同步（NTP）；两端都有 unison-fsmonitor（如用 -repeat watch）。

  2. 定时运行形态：Unison 无常驻服务，无人值守靠两种形态——

    cron（每 30 分钟同步一次，-batch 全自动）：

    crontab -e
# 追加一行：
*/30 * * * * /usr/local/bin/unison mydata -batch >> /var/log/unison-cron.log 2>&1

    或 systemd timer（⚠️ 需要 systemd 真机；单元文件标准形态，按此创建后 systemctl enable --now unison.timer 验证）：

    # /etc/systemd/system/unison.service
[Unit]
Description=Unison sync (mydata)
[Service]
Type=oneshot
ExecStart=/usr/local/bin/unison mydata -batch

    # /etc/systemd/system/unison.timer
[Unit]
Description=Run unison every 30 minutes
[Timer]
OnCalendar=*:0/30
Persistent=true
[Install]
WantedBy=timers.target

  3. profile 写法（root/path/ignore/batch 等参数详解见配置篇；此处仅示意文件位置与最小结构）：~/.unison/mydata.prf，一行一个参数，# 开头为注释。

十、常见问题

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

现象（node1 本地 2.51.5 连 node2 远端 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.

定位与解决：该报错的第一位原因就是两端版本不同（本地期望 2.51 协议头，远端回的是 2.54 的 Unison RPC 头）。先两端分别 unison -version（ssh 模式下注意远端命中的是 PATH 里哪个 unison，可用 ssh user@host unison -version 直接验证远端实际生效版本），然后把两端统一到同一主版本（都升 2.54.0 或都退 2.51.5）。报错中提到的第二、三位原因（远端登录 shell 打印横幅、连接被劫持）在排查完版本后再看：若 ssh user@host 'echo ok' 的输出里混进了 ok 以外的内容（如 motd/echo 语句），修掉登录脚本即可。

10.2 Host key verification failed

现象（node1 上清掉 ~/.ssh/known_hosts 后再连，实测全文）：

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

Error: Lost connection with the server

定位与解决：目标主机指纹不在 known_hosts 里，非交互的 Unison 无法回答 ssh 的指纹确认。解决：先手动建立信任——

ssh-keyscan -H node2 >> /root/.ssh/known_hosts   # 预录入主机指纹

或人工跑一次 ssh root@node2 hostname 并回答 yes。此后 -testserver 恢复 Connected。

10.3 archives are locked（锁文件残留）

现象（上一次 unison 进程被强杀后再次运行，实测全文）：

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.

定位与解决：报错已给出全部答案——确认没有其他 unison 进程在跑（pgrep -a unison），然后按提示逐个删除锁文件再重试：

pgrep -a unison            # 确认无残留进程
rm -f /root/.unison/lk*    # 按报错列出的文件删除（lk* 即全部锁文件）

10.4 make 报 Error: UISTYLE is no longer used

现象与解决见 6.3：2.54.0 构建已移除 UISTYLE 变量，改用 make / make tui / make gui，以官方 INSTALL.md 为准。

10.5 源码包下载 0 字节

现象与解决见 6.2：github.com/.../archive/...tar.gz 跳转失败时得到 0 字节文件，删除残包后改用 codeload.github.com 直链。

十一、升级与卸载清理

升级（方案 B 官方二进制）：下载新版本包 → 解压 → install -m755 .../bin/unison /usr/local/bin/ 覆盖 → 两端一起换（两端版本必须同步升级）→ unison -version 复核。⚠️ 跨大版本升级（如 2.51 → 2.54）后首次同步会提示 archive 格式变化并重建同步状态（首次运行的警告见命令篇），属正常现象；2.54.0 明确不再读取 pre-2.52.0 的 archive。

卸载（方案 A）：

apt remove --purge -y unison
# 输出节选（实测）：
# Removing unison (2.51.5+1) ...

卸载（方案 B/C）：删除二进制与附属文件：

rm -f /usr/local/bin/unison /usr/local/bin/unison-fsmonitor
rm -rf /opt/unison-2.54.0 /usr/share/doc/unison

清理状态数据（卸载后不需要保留同步状态时）：

rm -rf /root/.unison    # profile、archive、锁文件、日志全部在此

十二、参考链接

  1. Ubuntu 22.04 apt 仓库 unison 包信息（apt-cache policy unison，实测查询日期 2026-11-01）
  2. Unison v2.54.0 Releases（官方二进制下载）：https://github.com/bcpierce00/unison/releases/tag/v2.54.0
  3. 源码包直链（codeload）：https://codeload.github.com/bcpierce00/unison/tar.gz/refs/tags/v2.54.0
  4. 官方构建说明 INSTALL.md（随 v2.54.0 发布件与源码包分发，构建前提 OCaml ≥ 4.08）
  5. Unison 官方 Wiki - Obtaining Unison Sources and Binaries：https://github.com/bcpierce00/unison/wiki/Obtaining-Unison-Sources-and-Binaries
  6. 同专栏前置阅读：《Unison 介绍与选型指南》（版本节奏与选型对比）