Ubuntu 22.04 安装 git-annex 8.20210223 指南

Ubuntu 22.04 服务器 apt 安装 git-annex 8.20210223 全流程实测：版本实查、git annex version 逐行解读、双机目录仓库（repo-a/repo-b）init-add-clone-get-sync 全链路回显、SSH 多机形态与 assistant 自动同步配置。

git-annexgit-annexgit版本控制同步传输2026/10/30

Ubuntu 22.04 安装 git-annex 8.20210223 指南

实测环境：Ubuntu 22.04 LTS 服务器（jammy），apt 官方仓库安装，双机目录仓库（repo-a/repo-b）全链路同步验证。查询与实测日期：2026-10-30。

一、安装前准备

1.1 系统与前置软件要求

git-annex 是纯命令行工具，无 Web UI 主形态，对服务器的要求极低：

  • 操作系统：Ubuntu 22.04 LTS（本篇实测环境；Debian/Fedora/Arch 等主流发行版官方仓库均有收录）；
  • git：git-annex 的底层依赖，Ubuntu 22.04 安装 git-annex 时会自动带入；
  • 磁盘：二进制与依赖约 60 MB；annex 对象库随管理的文件总量增长，规划容量时按"最大单文件 × 副本数 + 元数据"预留；
  • 无守护进程要求：不启用 assistant 时，git-annex 不驻留内存，每次命令执行完即退出。

先确认系统版本与 git 可用性：

cat /etc/os-release | head -2
git --version

实测回显：

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
git version 2.34.1

1.2 版本实查：apt 仓库版本与上游最新版

安装前先实查 apt 仓库里 git-annex 的可用版本：

apt-cache policy git-annex

实测回显：

git-annex:
  Installed: (none)
  Candidate: 8.20210223-2ubuntu2
  Version table:
     8.20210223-2ubuntu2 500
        500 http://archive.ubuntu.com/ubuntu jammy/universe amd64 Packages

Ubuntu 22.04（jammy）官方仓库收录的是 8.20210223-2ubuntu2，位于 universe 组件。而上游（Hackage，作者 2026-10-06 上传）最新稳定版为 10.20261006。两者跨度约 5 年，但 8.x 已经覆盖 assistant、S3/WebDAV/rsync remote、numcopies 副本管理等核心能力（见 1.3 节 build flags 实查），对同步与备份场景完全够用；仓库版的优势是 apt 一键安装、依赖自动解决、随系统安全更新。若坚持上游最新版，见本文第五节的源码构建路径。

1.3 安装

apt-get install -y git-annex

实测回显（节选，依赖解析后自动安装 git-remote-gcrypt、gnupg 等关联组件）：

Setting up gnupg (2.2.27-3ubuntu2.5) ...
Setting up git-remote-gcrypt (1.4-1) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...
Processing triggers for ca-certificates (20260816ubuntu0.22.04.1) ...
Updating certificates in /etc/ssl/certs...
0 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.

1.4 安装验证：git annex version 全量解读

git annex version

实测回显（这是安装验证最重要的一步，逐行解读）：

git-annex version: 8.20210223
build flags: Assistant Webapp Pairing Inotify DBus DesktopNotify TorrentParser MagicMime Feeds Testsuite S3 WebDAV
dependency versions: aws-0.22 bloomfilter-2.0.1.0 cryptonite-0.26 DAV-1.3.4 feed-1.3.0.1 ghc-8.8.4 http-client-0.6.4.1 persistent-sqlite-2.10.6.2 torrent-10000.1.1 uuid-1.3.13 yesod-1.6.1.0
key/value backends: SHA256E SHA256 SHA512E SHA512 SHA224E SHA224 SHA384E SHA384 SHA3_256E SHA3_256 SHA3_512E SHA3_512 SHA3_224E SHA3_224 SHA3_384E SHA3_384 SKEIN256E SKEIN256 SKEIN512E SKEIN512 BLAKE2B256E BLAKE2B256 BLAKE2B512E BLAKE2B512 BLAKE2B160E BLAKE2B160 BLAKE2B224E BLAKE2B224 BLAKE2B384E BLAKE2B384 BLAKE2BP512E BLAKE2BP512 BLAKE2S256E BLAKE2S256 BLAKE2S160E BLAKE2S160 BLAKE2S224E BLAKE2S224 BLAKE2SP256E BLAKE2SP256 BLAKE2S512E BLAKE2S512 BLAKE2S384E BLAKE2S384 SHA1E SHA1 MD5E MD5 WORM URL X*
remote types: git gcrypt p2p S3 bup directory rsync web bittorrent webdav adb tahoe glacier ddar git-lfs httpalso borg hook external
operating system: linux x86_64
supported repository versions: 8
upgrade supported from repository versions: 0 1 2 3 4 5 6 7

关键行解读：

  • build flags：本二进制编译时启用的特性。Assistant（自动同步守护进程）、Webapp（网页控制台）、S3/WebDAV（云存储 remote）、TorrentParser（BT remote）均在列——jammy 的包是全功能构建；
  • key/value backends：内容寻址算法。SHA256E（E 后缀表示保留文件扩展名）是默认 backend，另有 SHA3/BLAKE2/SKEIN 家族与不做哈希的 WORM；
  • remote types：支持的特殊仓库类型，含云存储（S3/glacier/webdav）、目录（directory）、rsync、borg、git-lfs 等 22 种；
  • supported repository versions: 8：本版本创建/使用的仓库格式为 v8；可从 v0–v7 老仓库升级。

1.5 首次使用前的全局 git 身份

git-annex 的每次操作都会产生 git 提交（记录到 git-annex 元数据分支与工作分支），因此需要先配置 git 提交者身份，否则 commit 会失败：

git config --global user.email "root@annex-node-a"
git config --global user.name "root"

演示身份统一使用 root（服务器管理员常规账号）。多机部署时，每台机器用各自的 hostname 后缀区分邮箱（如 root@annex-node-b），便于在 git 历史里辨认提交来源。

二、双机仓库全链路实测：init → add → clone → get → sync

本节在一台 Ubuntu 22.04 服务器上用两个目录模拟两台机器的仓库（repo-a 与 repo-b），走通 git-annex 最核心的生命周期。生产环境中两台机器通常通过 SSH remote 互联，命令与本地路径 remote 完全一致。

2.1 初始化主仓库 repo-a 并执行 git annex init

mkdir -p /data
cd /data
git init repo-a
cd repo-a
git annex init "node-a"

实测回显：

hint: Using 'master' as the name for the initial branch. This default branch name
hint: is subject to change. To configure the initial branch name to use in all
hint: of your new repositories, which will suppress this warning, call:
hint: 
hint: 	git config --global init.defaultBranch <name>
hint: Names commonly chosen instead of 'master' are 'main', 'trunk' and
hint: 'development'. The just-created branch can be renamed via this command:
hint: 
hint: 	git branch -m <name>
Initialized empty Git repository in /data/repo-a/.git/
init node-a (scanning for unlocked files...)
ok
(recording state in git...)

git annex init "node-a" 做了三件事：给仓库分配全局唯一 UUID、把描述 node-a 写入元数据、创建 git-annex 元数据分支。回显末尾的 (recording state in git...) 是 git-annex 的标志性输出——所有状态变化都以 git 提交形式落账。

2.2 添加大文件：观察 annex 化行为

生成三个测试文件（5 MB、10 MB 二进制与一个 12 字节文本），然后 git annex add .：

dd if=/dev/urandom of=bigfile.bin bs=1M count=5 2>/dev/null
dd if=/dev/urandom of=dataset-2026.tar bs=1M count=10 2>/dev/null
echo "readme text" > notes.txt
git annex add .
git commit -m "add dataset files"
ls -la | grep -v "^total\|^d"

实测回显：

add bigfile.bin 
100%  5 MiB           306 MiB/s 0s                                    ok
add dataset-2026.tar 
100%  10 MiB          377 MiB/s 0s                                    ok
add notes.txt 
100%  12 B             66 KiB/s 0s                                     ok
(recording state in git...)
 create mode 120000 bigfile.bin
 create mode 120000 dataset-2026.tar
 create mode 120000 notes.txt
lrwxrwxrwx 1 root root  198 Oct 30 06:19 bigfile.bin -> .git/annex/objects/G8/4G/SHA256E-s5242880--ae44f8d466f0bbfbc9628d425fb385588c8ced97ef7d239db89f6fb29ee0438f.bin/SHA256E-s5242880--ae44f8d466f0bbfbc9628d425fb385588c8ced97ef7d239db89f6fb29ee0438f.bin
lrwxrwxrwx 1 root root  200 Oct 30 06:19 dataset-2026.tar -> .git/annex/objects/3W/GX/SHA256E-s10485760--a3d8bd185e442a72efe16d4f823f917cfd9279a9d72180e4c3e51ea34e0bcd9e.tar/SHA256E-s10485760--a3d8bd185e442a72efe16d4f823f917cfd9279a9d72180e4c3e51ea34e0bcd9e.tar
lrwxrwxrwx 1 root root  188 Oct 30 06:19 notes.txt -> .git/annex/objects/0X/2z/SHA256E-s12--a322137562ae5148a7d9a4a18520e8c7daf8d69e2bb12060b791751957f34700.txt/SHA256E-s12--a322137562ae5148a7d9a4a18520e8c7daf8d69e2bb12060b791751957f34700.txt

三个要点：

  1. 8.20210223 的默认行为是把所有文件 annex 化——连 12 字节的 notes.txt 也进了 annex 对象库。生产环境应配置 annex.largefiles 让小文件直接进 git（配置方法见 《git-annex 8.20210223 配置参数详解》）；
  2. 文件变成 mode 120000 的符号链接，指向 .git/annex/objects/<两位>/<两位>/<key>/<key> 的哈希命名对象——这就是"内容寻址"的落盘形态；
  3. key 前缀 SHA256E-s5242880-- 自解释：算法、字节数、内容哈希全在名字里。

2.3 克隆到第二仓库 repo-b：断链状态是常态

cd /data
git clone /data/repo-a repo-b
cd repo-b
git annex init "node-b"
ls -la | grep -v "^total\|^d"
cat bigfile.bin

实测回显：

Cloning into 'repo-b'...
done.
init node-b (merging origin/git-annex into git-annex...)
(recording state in git...)
(scanning for unlocked files...)
ok
(recording state in git...)
lrwxrwxrwx 1 root root  198 Oct 30 06:19 bigfile.bin -> .git/annex/objects/G8/4G/SHA256E-s5242880--ae44f8d466f0bbfbc9628d425fb385588c8ced97ef7d239db89f6fb29ee0438f.bin/SHA256E-s5242880--ae44f8d466f0bbfbc9628d425fb385588c8ced97ef7d239db89f6fb29ee0438f.bin
lrwxrwxrwx 1 root root  200 Oct 30 06:19 dataset-2026.tar -> .git/annex/objects/3W/GX/SHA256E-s10485760--a3d8bd185e442a72efe16d4f823f917cfd9279a9d72180e4c3e51ea34e0bcd9e.tar/SHA256E-s10485760--a3d8bd185e442a72efe16d4f823f917cfd9279a9d72180e4c3e51ea34e0bcd9e.tar
lrwxrwxrwx 1 root root  188 Oct 30 06:19 notes.txt -> .git/annex/objects/0X/2z/SHA256E-s12--a322137562ae5148a7d9a4a18520e8c7daf8d69e2bb12060b791751957f34700.txt/SHA256E-s12--a322137562ae5148a7d9a4a18520e8c7daf8d69e2bb12060b791751957f34700.txt
cat: bigfile.bin: No such file or directory

cat bigfile.bin 报 No such file or directory 不是故障，而是特性：clone 只复制了 git 元数据（symlink 与 git-annex 分支），文件内容仍在 node-a。git-annex 仓库的常态就是"账本先到，内容按需取"。

2.4 在 repo-b 拉取内容：git annex get

cd /data/repo-b
git annex get bigfile.bin

实测回显：

get bigfile.bin (from origin...) 
100%  5 MiB           329 MiB/s 0s                                    ok
(recording state in git...)

内容从 remote origin（即 repo-a）传输落盘。验证真实大小（注意 symlink 要用 stat -L 跟随链接）：

stat -Lc "%s bytes  %n" bigfile.bin

5242880 bytes  bigfile.bin

2.5 建立双向关系并同步：git annex sync

repo-a 侧把 repo-b 加为 remote 并首次同步：

cd /data/repo-a
git remote add node-b /data/repo-b
git annex sync

实测回显：

(merging node-b/git-annex into git-annex...)
push node-b 
To /data/repo-b
 * [new branch]      git-annex -> synced/git-annex
 * [new branch]      master -> synced/master
ok

git annex sync 自动完成元数据双向合并与推送（git-annex 与工作分支一起同步）。此后任意一侧执行 git annex sync 即可把副本位置、元数据变化双向收敛。

2.6 全链路验证：副本分布一目了然

git annex whereis bigfile.bin
git annex list
git annex info

实测回显：

whereis bigfile.bin (2 copies) 
  	0be16052-5128-42f8-9ae7-1ab9a32dfc83 -- [node-b]
   	da2dfc12-a5d2-4a5b-b7d0-7efc76ae9b07 -- node-a [here]
ok

here
|node-b
||web
|||bittorrent
||||
XX__ bigfile.bin
X___ dataset-2026.tar
X___ notes.txt

trusted repositories: 0
semitrusted repositories: 4
	00000000-0000-0000-0000-000000000001 -- web
 	00000000-0000-0000-0000-000000000002 -- bittorrent
 	0be16052-5128-42f8-9ae7-1ab9a32dfc83 -- [node-b]
 	da2dfc12-a5d2-4a5b-b7d0-7efc76ae9b07 -- node-a [here]
untrusted repositories: 0
transfers in progress: none
available local disk space: 216.69 gigabytes (+1 megabyte reserved)
local annex keys: 3
local annex size: 15.73 megabytes
annexed files in working tree: 3
size of annexed files in working tree: 15.73 megabytes
bloom filter size: 32 mebibytes (0% full)
backend usage: 
	SHA256E: 3
  • whereis：bigfile.bin 全网络 2 份副本（node-a + node-b），按 UUID 列出；
  • list：副本矩阵——列是仓库（here/node-b/web/bittorrent），行是文件，X 表示该仓库持有内容。dataset-2026.tar 只有 X___（仅本地）；
  • info：仓库全局视角——信任级别（默认 semitrusted）、本地 key 数与体积、backend 使用统计。

至此双机全链路走通：init（建账）→ add（内容入库+symlink 化）→ clone（元数据扩散）→ get（内容按需取）→ sync（账本双向收敛）。日常的 move/copy/drop/fsck 等命令族见 《git-annex 8.20210223 常用 CLI 命令详解》。

三、SSH 多机形态：把目录仓库换成真实第二台机器

生产环境两台服务器互联时，把 2.5 节的本地路径 remote 换成 SSH 地址即可，其余流程完全一致：

# 在 repo-a（node-a 机器）上，把第二台机器的仓库加为 remote
git remote add node-b root@annex-node-b:/data/repo-b
# 或使用 git-annex 原生 SSH 语法（自动启用连接复用）
git annex sync

前置条件只有两个：

  1. 两台机器已配置 SSH 免密（ssh-copy-id root@annex-node-b）；
  2. 对端机器已按本文第一节完成 git-annex 安装，且 /data/repo-b 已执行过 git init + git annex init。

git-annex 对 SSH remote 默认启用连接复用与缓存（annex.sshcaching），多次传输不再重复握手；若对端 git 未在 PATH（如非标准 shell），可用 annex.ssh-options 追加参数。

四、配置开机即用：assistant 自动同步（可选）

若希望服务器上的仓库自动同步（无需手工 git annex sync），可启用 assistant 守护进程：

cd /data/repo-a
git annex assistant --autostart

assistant 会监听文件变化、自动 add/commit/同步，并把日志写入 ~/.annex/。验证版本是否支持（1.4 节 build flags 含 Assistant 即可）：

git annex assistant --help

实测回显：

git-annex assistant - automatically sync changes

Usage: git-annex assistant [--foreground] [--stop] [--autostart] 
                           [--startdelay NUMBER] [--autostop]

停止方式：git annex assistant --stop。需要注意 assistant 是可选增强——纯手工 git annex sync 已能完成全部同步能力，无人值守场景再开启。

五、获取上游最新版 10.20261006（可选路径）

apt 仓库版本滞后的情况下，两条升级路径：

  1. 源码构建：从 Hackage 下载 git-annex-10.20261006 的 cabal 源码包（cabal install git-annex），需要 GHC 工具链，Haskell 全量编译耗时较长；
  2. 等待发行版回移：Ubuntu 24.04/Debian trixie 已收录 10.x 系列，服务器升级发行版后 apt 直接获得新版本。

生产建议：同步与备份场景下 8.20210223 仓库版足够稳定，无特殊需求不必追新——仓库格式 v8 在 8.x 与 10.x 间保持兼容（10.x 的 supported repository versions 仍包含 8）。

六、卸载与数据安全

卸载软件包不影响已有 annex 数据（数据都在各仓库的 .git/annex/ 内）：

apt-get remove --purge -y git-annex

若要彻底销毁某个仓库的数据，直接删除仓库目录即可（先确认其他机器副本充足：git annex whereis 查看副本分布，或 git annex fsck 全量校验后操作）。