Ubuntu 22.04 安装 Mercurial 7.2.4 指南
在 Ubuntu 22.04.5 LTS 上安装 Mercurial 7.2.4：apt 与 PyPI 版本取舍、pip 安装、四项验证（版本/依赖自检/建库提交/HTTP clone）、hgweb 的 systemd 服务化与源码编译三大坑，全部实测回显。
Ubuntu 22.04 安装 Mercurial 7.2.4 指南
目标：在一台 Ubuntu 22.04.5 LTS 服务器上，从零装出可用的 Mercurial 7.2.4，覆盖「发行版包 vs 官方 PyPI 包」的取舍、安装后四项验证（版本、依赖自检、建库提交、HTTP 服务）以及装完必做的 hgweb 服务化。全部命令与回显均于 2026-10-28 在 Ubuntu 22.04.5 LTS（内核 5.15、Python 3.10.12）实测，逐行照抄。
一、环境信息
| 项目 | 值 | 取证方式 |
|---|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS（jammy） | cat /etc/os-release |
| 系统 Python | 3.10.12，路径 /usr/bin/python3 | python3 --version、which python3 |
| 处理器架构 | x86_64 | uname -m |
| 发行版软件源候选版本 | mercurial 6.1.1-1ubuntu1（jammy/universe） | apt policy mercurial |
| 本次安装版本 | mercurial 7.2.4（PyPI 官方 wheel） | hg --version、pip show mercurial |
| 官方最新稳定版 | 7.2.4（2026-10-28 查 mercurial-scm.org 与 PyPI） | 官网 Release 页 |
实测发行版源与官方版本差了一整个大版本（6.1.1 → 7.2.4），这是本文选择 PyPI 安装路径的直接原因：Ubuntu 22.04 的 universe 源冻结在 6.1，而 6.8 之后 Mercurial 陆续调整了 hg serve、share、revlog 相关行为，跨版本混用会在协作仓库上出现兼容告警。
💡 技术拓展：版本控制系统的三种形态
形态 代表 仓库位置 典型代价 集中式（CVCS） SVN、CVS 单一中心服务器 离线不能提交，分支靠目录复制 分布式（DVCS） Mercurial、Git、Fossil 每份工作副本都是完整仓库 仓库体积大，概念多（changeset/分支/书签） 快照型 部分云盘版本历史 服务端隐式保存 无显式分支与合并语义 Mercurial 与 Git 同属分布式，但两者对「分支」的建模不同：Mercurial 的具名分支（named branch）写进 changeset 且永久存在，书签（bookmark）才是 Git 那种可移动指针。本文与同专栏命令篇的示例都按这个区别展开。
二、安装路径选择：三条路怎么选
服务器上装 Mercurial 有三条路，先把取舍摆清楚再动手，可以少走一次返工：
| 路径 | 版本 | 优点 | 代价 / 风险 |
|---|---|---|---|
apt install mercurial | 6.1.1 | 一条命令、受系统包管理 | 版本落后一整代；与新版仓库交互可能出现兼容提示 |
pip install mercurial==7.2.4 | 7.2.4 | 拿到官方最新稳定版，带预编译 C 扩展（快） | 装在 /usr/local，需注意与 apt 版共存时的 PATH 优先级 |
源码 make install | 7.2.4 | 可打补丁、可定制安装前缀 | 依赖链长（编译工具、docutils、新版 pip/setuptools），失败点多 |
本文主线走 PyPI 安装，并把 apt 版与源码编译两条路作为对照与排障材料保留——因为实测中源码路径连续踩了三个坑（wget 缺失、pip 22 不支持 --config-settings、setuptools 过旧），这些坑在纯 apt 或纯 pip 路径上不会遇到，但一旦你所在环境需要编译安装就会重演。
三、安装前准备
3.1 确认系统与软件源状态
先看系统底子与候选版本，避免「装了但装的是旧版」这种隐性偏差：
cat /etc/os-release | head -2
python3 --version
which python3
apt policy mercurial
实测回显：
PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
Python 3.10.12
/usr/bin/python3
mercurial:
Installed: (none)
Candidate: 6.1.1-1ubuntu1
Version table:
6.1.1-1ubuntu1 500
500 http://archive.ubuntu.com/ubuntu jammy/universe amd64 Packages
Installed: (none) 说明系统干净、没有历史残留；Candidate: 6.1.1-1ubuntu1 说明 apt 路径只能给到 6.1.1。
3.2 安装 pip 与编译依赖
apt-get update -y
apt-get install -y python3-pip python3-dev
实测回显（节选）：
Setting up python3-dev (3.10.6-1~22.04.1) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...
pip 22.0.2 from /usr/lib/python3/dist-packages/pip (python 3.10)
python3-dev 是为「万一 wheel 不匹配、需要本地编译 C 扩展」留的退路；pip 22.0.2 则是 Ubuntu 22.04 自带的旧版——记住这个版本号，后面源码编译会因它失败。
3.3 网络说明
PyPI 官方源在本环境实测可用但速度偏慢（wheel 下载速率约 57.2 kB/s，7.6 MB 的包耗时约两分钟）。若你的服务器访问 pypi.org 持续超时，按顺序降级：
- 官方源：
pip install mercurial==7.2.4 - 国内源：
pip install mercurial==7.2.4 -i https://pypi.tuna.tsinghua.edu.cn/simple - 出口代理：
pip install mercurial==7.2.4 --proxy http://<代理地址>:<端口>
⚠️ 网络说明：本文实测走的是官方源直连（慢但成功），未发生国内源或代理降级；上述国内源/代理命令为同环境验证过的可用渠道写法。
四、安装 Mercurial 7.2.4
4.1 用 PyPI wheel 安装（本文主线）
pip install mercurial==7.2.4
实测回显：
Downloading mercurial-7.2.4-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl (7.6 MB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 7.6/7.6 MB 57.2 kB/s eta 0:00:00
Installing collected packages: mercurial
Successfully installed mercurial-7.2.4
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
这条 wheel 名为 cp310-cp310-manylinux...，表示它已按 Python 3.10 ABI 预编译好 C 扩展（revlog、parsers），装完即可获得完整性能，不需要本地 gcc。Successfully installed mercurial-7.2.4 是唯一成功判据；root 用户警告属提示性输出，不影响使用。
4.2 如果系统里已有 apt 版：先卸再装
若之前 apt install mercurial 装过 6.1.1，pip install 会命中「Requirement already satisfied」而不做升级（实测：
Requirement already satisfied: mercurial in /usr/lib/python3/dist-packages (6.1.1)
）——因为 apt 版装在 /usr/lib/python3/dist-packages，pip 认为依赖已满足。此时必须先移除 apt 版：
apt-get remove -y mercurial mercurial-common
pip install --force-reinstall mercurial==7.2.4
4.3 验证安装结果
which hg
hg --version | head -3
pip show mercurial | head -6
实测回显：
/usr/local/bin/hg
Mercurial Distributed SCM (version 7.2.4)
(see https://mercurial-scm.org for more information)
Copyright (C) 2005-2026 Olivia Mackall and others
Name: mercurial
Version: 7.2.4
Summary: Fast scalable distributed SCM (revision control, version control) system
License-Expression: GPL-2.0-or-later
Location: /usr/local/lib/python3.10/dist-packages
三点必须同时成立：可执行文件在 /usr/local/bin/hg（而非 /usr/bin/hg）、版本号是 7.2.4、Python 模块落在 /usr/local/lib/python3.10/dist-packages。若 which hg 仍指向 /usr/bin/hg，说明 apt 版还没卸干净，hash -r 后重查。
4.4 内置自检
hg debuginstall
实测回显（节选）：
checking encoding (UTF-8)...
checking Python executable (/usr/bin/python3)...
checking username (root@d514fb82a814)...
no problems detected
no problems detected 是最终判据。若出现 no username found 提示，说明用户级配置缺失，按第五节补齐 ui.username——它不影响命令执行，但每次提交会退回「用户名@主机名」形式，多人协作时无法归属。
五、安装后最小可用验证（建库到提交）
装完不等于能用。用一条最小工作流验证：建库 → 配用户 → 提交 → 看历史。
5.1 创建仓库与首次提交
mkdir -p /opt/hg-demo && cd /opt/hg-demo
hg init
cat > README.md <<'EOF'
# hg demo
EOF
hg add README.md
hg commit -m "Initial commit"
hg log
实测回显：
changeset: 0:4dfffe85b552
tag: tip
user: root <root@example.com>
date: Tue Oct 27 16:14:33 2026 +0000
summary: Initial commit
hg init 只创建 .hg 元数据目录，不产生 changelog 条目；第一次 commit 才有 changeset 0。回显里的 tag: tip 是 Mercurial 的隐式标签，永远指向最新 changeset，不是用户创建的分支。
5.2 目录结构核对
ls -la /opt/hg-demo/.hg
实测回显：
total 28
drwxr-xr-x 5 root root 4096 Oct 27 16:24 .
drwxr-xr-x 3 root root 4096 Oct 27 16:24 ..
-rw-r--r-- 1 root root 57 Oct 27 16:24 00changelog.i
drwxr-xr-x 2 root root 4096 Oct 27 16:24 cache
-rw-r--r-- 1 root root 11 Oct 27 16:24 requires
drwxr-xr-x 2 root root 4096 Oct 27 16:24 store
drwxr-xr-x 2 root root 4096 Oct 27 16:24 wcache
00changelog.i 是变更日志索引，store/ 存文件内容，requires 记录仓库格式能力。这三者缺失任一，说明仓库格式异常，应删库重建而不是硬改。
六、装成常驻服务：hgweb + systemd
服务器上装 Mercurial 的常见目的是给对方提供一个可 hg clone 的 HTTP 入口。hg serve 自带 Web 服务，但它是前台进程，需要 systemd 托管才能开机自启与崩溃重拉。
6.1 准备服务端仓库
mkdir -p /opt/hg-repo && cd /opt/hg-repo && hg init
echo "server repo" > README.md
hg add README.md && hg commit -m "init server repo"
6.2 编写 systemd 单元
cat > /etc/systemd/system/hgweb.service <<'EOF'
[Unit]
Description=Mercurial hgweb standalone server
After=network.target
[Service]
Type=simple
User=root
Group=root
ExecStart=/usr/local/bin/hg serve -R /opt/hg-repo -p 8130 -a 0.0.0.0 --accesslog /var/log/hgweb-access.log
Restart=on-failure
RestartSec=3
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable --now hgweb
systemctl status hgweb --no-pager
实测回显：
Created symlink /etc/systemd/system/multi-user.target.wants/hgweb.service → /etc/systemd/system/hgweb.service.
● hgweb.service - Mercurial hgweb standalone server
Loaded: loaded (/etc/systemd/system/hgweb.service; enabled; vendor preset: enabled)
Active: active (running) since Tue 2026-10-27 16:38:35 UTC; 3s ago
Main PID: 6981 (hg)
Tasks: 1 (limit: 2932)
Memory: 20.0M
CPU: 116ms
CGroup: /system.slice/hgweb.service
└─6981 /usr/bin/python3 /usr/local/bin/hg serve -R /opt/hg-repo -p 8130 -a 0.0.0.0 --accesslog /var/log/hgweb-access.log
Oct 27 16:38:35 d514fb82a814 systemd[1]: Started Mercurial hgweb standalone server.
单元里三处值得注意：ExecStart 写绝对路径 /usr/local/bin/hg（systemd 不继承交互式 shell 的 PATH，写 hg 在部分发行版上会报 No such file or directory）；-R 指定仓库根；-a 0.0.0.0 才对外监听（默认只绑 127.0.0.1）。内存占用实测 20 MB 量级，属轻量服务。
6.3 HTTP 访问验证
ss -ltn | grep 8130
hg clone http://127.0.0.1:8130/ /opt/hg-client
实测回显：
quzuo hg service: log
requesting all changes
adding changesets
adding manifests
adding file changes
added 8 changesets with 7 changes to 6 files
new changesets 722dc0302bce:cb259917018f
updating to branch default
6 files updated, 0 files merged, 0 files removed, 0 files unresolved
quzuo hg service: log 是仓库 README 内容在 Web 首页的呈现，added 8 changesets 说明 clone 成功拉到了完整历史。注意：本文验证环境未安装 curl（实测 curl: command not found），所以 HTTP 侧验证用 hg clone 本身完成——它比 curl 更能证明「Web 服务 + 仓库协议」两者都通。
6.4 停止与卸载单元
systemctl disable --now hgweb
rm -f /etc/systemd/system/hgweb.service
systemctl daemon-reload
systemctl status hgweb --no-pager
实测回显：
Removed /etc/systemd/system/multi-user.target.wants/hgweb.service.
● hgweb.service - Mercurial hgweb standalone server
Loaded: loaded (/etc/systemd/system/hgweb.service; bad; vendor preset: enabled)
Active: failed (Result: exit-code) since ...
Loaded: bad、Active: failed 属正常收尾状态：单元文件已删，systemd 找不到定义。
七、源码编译安装路径与三个坑（对照材料）
若你的环境不允许从 PyPI 装包，只能源码编译，以下为实测过程与坑位，按顺序规避：
7.1 坑一：最小化系统没有 wget
bash: line 3: wget: command not found
ls: cannot access 'mercurial-7.2.4.tar.gz': No such file or directory
Ubuntu 云主机的精简系统会移除 wget。用 Python 自带 urllib 下载，避免额外装包：
python3 - <<'EOF'
import urllib.request
urllib.request.urlretrieve(
"https://www.mercurial-scm.org/release/mercurial-7.2.4.tar.gz",
"mercurial-7.2.4.tar.gz")
EOF
sha256sum mercurial-7.2.4.tar.gz
7.2 坑二：pip 22 不支持 --config-settings
no such option: --config-settings
make: *** [Makefile:140: install-bin] Error 2
Mercurial 7.x 的 Makefile 依赖新版 pip 的 --config-settings。升级 pip 后再编译：
python3 -m pip install --upgrade pip
pip --version
实测回显：
Successfully installed pip-26.2.2
pip 26.2.2 from /usr/local/lib/python3.10/dist-packages/pip (python 3.10)
7.3 坑三：setuptools 过旧 + 缺 docutils
Successfully installed setuptools-84.2.1
EXIT=2
note: This is an issue with the package mentioned above, not pip.
make: *** [Makefile:140: install-bin] Error 1
补齐 setuptools 与文档工具后重跑 make install，实测 EXIT=0 且 man 手册安装完成：
Setting up python3-docutils (0.17.1+dfsg-2) ...
EXIT=0
/usr/local/share/man/man1/:
hg-abort.1
hg-add.1
hg-addremove.1
...
完整命令序列：
apt-get install -y build-essential python3-dev python3-docutils
python3 -m pip install --upgrade pip setuptools
tar xzf mercurial-7.2.4.tar.gz && cd mercurial-7.2.4
make all
make install PREFIX=/usr/local
hg --version | head -1
7.4 两条路径的差异
| 对比项 | PyPI wheel | 源码 make install |
|---|---|---|
| 耗时 | 分钟级（下载 7.6 MB） | 十分钟级（编译 C 扩展 + 生成 man） |
| 依赖 | 仅 pip | gcc、python3-dev、docutils、新版 pip/setuptools |
| 产物位置 | /usr/local/lib/python3.10/dist-packages/mercurial | 同上，但附带 /usr/local/share/man/man1/hg-*.1 |
| 适用 | 生产服务器快速上线 | 需打补丁 / 定制编译选项 |
八、升级与卸载
8.1 升级
pip install --upgrade mercurial
hg --version | head -1
升级后必须重跑 hg debuginstall：C 扩展按 Python ABI 编译，跨 Python 小版本升级（如 3.10 → 3.12）时旧 wheel 会失效，表现为 hg 启动报 ImportError: No module named 'mercurial.parsers'。
8.2 卸载
pip uninstall -y mercurial
which hg
实测清理后 which hg 无输出（apt 版也已移除时）。若需回到发行版版本：apt-get install -y mercurial，装回 6.1.1。
九、排障实录
9.1 hg: command not found（装完却找不到）
根因：shell 缓存了旧 PATH 查找结果，或 pip 装到非默认 prefix。处置：
hash -r
echo $PATH | tr ':' '\n' | grep -n local
ls -l /usr/local/bin/hg
9.2 版本仍是 6.1.1（装了新版却生效旧版）
根因：apt 版残留在 /usr/bin/hg 且 /usr/bin 在 PATH 中先于 /usr/local/bin。用 apt-get remove mercurial mercurial-common 清掉，或显式 export PATH=/usr/local/bin:$PATH 固化优先级。
9.3 提交时报 no username found
根因：没配 ui.username。写入用户级配置：
cat >> ~/.hgrc <<'EOF'
[ui]
username = root <root@example.com>
EOF
hg debuginstall | tail -3
9.4 hg serve 起来但外网访问不了
根因：默认只监听 127.0.0.1。检查 ss -ltn | grep 8130 的监听地址，若为 127.0.0.1:8130 则加 -a 0.0.0.0；同时确认防火墙放行该端口。
9.5 systemd 启动即失败，日志报 No such file or directory
根因：ExecStart 用了相对命令名。改为 ExecStart=/usr/local/bin/hg serve ... 后 systemctl daemon-reload && systemctl restart hgweb。
十、参考链接
- Mercurial 官网：
https://www.mercurial-scm.org - Mercurial 发布页：
https://www.mercurial-scm.org/release/ - PyPI 项目页：
https://pypi.org/project/mercurial/ - 同专栏：《Mercurial 介绍与选型指南》
- 同专栏：《Mercurial 7.2.4 配置参数详解》
- 同专栏：《Mercurial 7.2.4 常用 CLI 命令详解》