Electrum Windows 二进制构建指南:基于 Docker/Wine 的可复现构建、代码签名与完整性校验

原创2026-10-13 19:43:182,276 阅读
文章标签:区块链金融科技桌面应用

Electrum Windows 二进制构建指南:基于 Docker/Wine 的可复现构建、代码签名与完整性校验

导读

本文以 Electrum 仓库中 contrib/build-wine/README.md 为核心,完整梳理其在 Ubuntu/Docker 环境下构建 Windows 版二进制(.exe)的完整流程:从环境准备、可复现构建(Reproducible Build)到 Authenticode 代码签名与用户侧的二进制完整性校验。读完本文,你将掌握 build.sh / make_win.sh 等脚本的调用方式与关键环境变量、理解可复现构建的底层机制(时间戳固定、依赖哈希锁定、PE 头处理),并能独立验证官方 Windows 二进制确实由本仓库源码构建而来。

构建目标与支持范围

Electrum 仓库的 contrib/build-wine 目录专门用于产出 Windows 二进制。原文档明确了两点关键约束:

  • 可复现性承诺:这些二进制应该是可复现的(reproducible),即开发者应当能够生成与官方发布版本逐字节一致的二进制。
  • 最低目标系统(最终用户侧):x86_64 架构、Windows 10(1809)及以上。

构建主机假设为 Ubuntu(x86_64),但文档说明"不难移植到其他类似的系统"。整个构建流程以 Docker 容器隔离为基础,脚本均位于 contrib/build-wine 目录。

第一步:安装 Docker

Windows 构建的第一步是安装 Docker。官方给出的指引位于仓库内的 contrib/docker_notes.md,该文档强调"即使你已经装过 Docker 也值得读一遍"。

安装 Docker 的典型做法(Ubuntu x86_64 主机):

$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
$ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
$ sudo apt-get update
$ sudo apt-get install -y docker-ce

构建脚本需要与 docker 守护进程通信,因此要么通过 sudo 调用脚本,要么把当前用户加入 docker 组(加入后需重启或重新登录使其生效):

$ sudo usermod -aG docker ${USER}

文档特别提醒:较旧版本的 Docker 可能无法正常工作(项目曾遇到相关问题的记录),如果出现问题,建议至少升级到 docker 20.10。

第二步:构建 Windows 二进制

基础用法

在项目根目录的 contrib/build-wine 下执行:

$ ./build.sh

产物输出到 ./contrib/build-wine/dist 目录(即仓库根目录下的 contrib/build-wine/dist)。产物包括独立版(standalone).exe、便携版(portable).exe 以及 NSIS 安装包(-setup.exe)。

可复现构建用法

如果需要可复现性,则必须传入 ELECBUILD_COMMIT 环境变量,指定要构建的 git 引用:

$ ELECBUILD_COMMIT=HEAD ./build.sh

从 build.sh 源码看,ELECBUILD_COMMIT 的行为是:

  • 未设置:直接基于本地 git clone 构建,这类构建不可复现;
  • 非空:脚本会先删除旧的 /var/tmp/electrum_build/windows/fresh_clone/electrum(必要时借助 sudo),以 umask 0022 重新 git clone 当前仓库并 git checkout "$ELECBUILD_COMMIT",随后在全新 clone 中构建;构建完成后把产物 .exe 复制回 $PROJECT_ROOT/contrib/build-wine/dist/。

其他环境变量

环境变量 作用
ELECBUILD_COMMIT 非空时做一次全新 clone 并 checkout 到该 git 引用,保证构建输入与官方发布完全一致,是可复现构建的关键开关
ELECBUILD_NOCACHE 非空时强制 docker build --pull --no-cache 重建镜像(Dockerfile 变更后默认会自动重建,该变量用于显式强制)

此外 build.sh 会在有可用 /dev/tty 时给 docker run 附加 -it 参数以便交互;容器命名为 electrum-wine-builder-cont,工作目录为 /opt/wine64/drive_c/electrum/contrib/build-wine,并在容器内执行 ./make_win.sh。

可复现构建的底层机制

Electrum 的可复现构建并非"碰运气",而是由一系列确定性手段共同保证,下面从源码层面逐一拆解。

1. 基础镜像与 apt 源固定

Dockerfile 基于 debian:trixie(固定了 digest sha256:13f29b6806e531c3ff3b565bb6eed73f2132506c8c9d41bb996065ca20fb27f2),并通过两个文件把系统软件包固定到历史快照:

  • apt.sources.list 指向 https://snapshot.debian.org/archive/debian/<时间戳>/;
  • apt.preferences 以 Pin-Priority: 1001 强制优先使用 snapshot 源。

contrib/docker_notes.md 解释了原因:使用 snapshot.debian.org 有助于历史可复现性(该镜像有时较慢甚至超时,这是已知问题;如果不追求可复现性,可以换回默认 debian 源)。另外 Wine 通过官方 winehq 仓库安装,并校验了 winehq.key 的 SHA-256 哈希后再 gpg --dearmor 导入,安装版本被精确固定为 11.0.0.0~<codename>-1(Dockerfile 中通过 WINEVERSION 变量拼出)。

2. 用户与构建身份固定

Dockerfile 创建了 UID 1000 的普通用户 user(通过 --build-arg UID=$BUILD_UID 传入主机 UID),赋予其免密 sudo 权限,并设置 HOME_DIR=/home/user、WORK_DIR=/home/user/wspace。build.sh 中,当使用 fresh clone 构建时还会确保 FRESH_CLONE 目录归属 1000:1000,以消除不同环境带来的文件属主差异。

3. 构建工具链的确定性设置

build_tools_util.sh 中设置了多项全局确定性参数,这些参数会随脚本 source 进入整个构建过程:

export SOURCE_DATE_EPOCH=1530212462
export ZERO_AR_DATE=1            # 用于 macOS
export PYTHONHASHSEED=22
umask 0022

其中 PYTHONHASHSEED 固定了 Python 字符串哈希的随机种子,umask 0022 固定文件权限位——这些都是消除"同一输入、不同输出"的关键变量。

4. 依赖精确锁定

构建安装的 Python 依赖全部来自 contrib/deterministic-build 目录下的冻结清单。据 deterministic-build/README.md 说明:这些清单由 contrib/freeze_packages.sh 从 contrib/requirements 下的松散版本约束生成,输出文件为全部传递依赖并附带精确版本号与 SHA-256 哈希锁定,例如 aiohttp==3.14.3 \ --hash=sha256:9491...。构建脚本只使用这些哈希锁定的清单,从源头上杜绝了依赖漂移。

5. Wine 环境与 Python 安装

prepare-wine.sh 负责在 Wine 内搭建 Windows 构建环境:

  • 运行 wine 'wineboot' 初始化 Wine prefix;
  • 通过 GPG 校验(密钥 7ED10B6531D7C8E1BC296021FC624643487034E5.asc,存放于 contrib/build-wine/gpg_keys)后,用 wine msiexec 依次安装 Python 3.12.10 的 core / dev / exe / lib / pip 五个 MSI 包到 c:/python3;
  • 用 break_legacy_easy_install 禁用 setuptools 隐式联网安装;
  • 用哈希锁定的 requirements-build-base.txt、requirements-build-wine.txt 安装构建期依赖。

6. 自编译 PyInstaller 引导器

prepare-wine.sh 还会自行交叉编译 PyInstaller 的 bootloader(固定到 tag v6.13.0 对应 commit 306d4d9...),原因有二:

  1. PyInstaller 默认引导器在杀毒软件中有较高的误报率;
  2. 脚本会在 bootloader/src/pyi_main.c 中追加一行 electrum_tag(标记本次构建对应的 Electrum commit),确保每次发布构建出不同的引导器,进一步降低误报风险。

编译方式是用宿主机的 python3 ./waf all CC="${GCC_TRIPLET_HOST}-gcc" CFLAGS="-static" 交叉编译出 Windows 引导器。

7. 可复现打包细节

make_win.sh 是整个 Wine 构建的编排入口,其要点包括:

  • WIN_ARCH 默认 win64(win32 时使用 i686-w64-mingw32,win64 时使用 x86_64-w64-mingw32);
  • 构建缓存位于 contrib/build-wine/.cache/$WIN_ARCH/build,其中 libsecp256k1-*.dll、ZXing.dll、libusb-1.0.dll 已存在则跳过(分别由 make_libsecp256k1.sh、make_zxing.sh、make_libusb.sh 交叉编译);
  • 修正 C:\Python 下所有文件的修改时间为固定值 2000-11-11T11:11:11+00:00(因为 PyInstaller 存在相关 bug),这是消除时间戳差异的直接手段。

build-electrum-git.sh 完成最终的打包:

  • 版本号来自 git describe --tags --dirty --always;
  • 先清理 locale(build_cleanlocale.sh),二进制内只保留编译后的 .mo 文件;
  • 通过环境变量 AIOHTTP_NO_EXTENSIONS=1、YARL_NO_EXTENSIONS=1、ELECTRUM_ECC_DONT_COMPILE=1 等放弃编译 C 扩展,避免编译器版本差异破坏可复现性;
  • 以 --no-binary :all: 方式安装哈希锁定的 requirements(requirements.txt、requirements-binaries.txt、requirements-hw.txt),仅对 cffi、cryptography、PyQt6 等允许预编译 wheel;
  • 运行 pyinstaller.exe --noconfirm --clean pyinstaller.spec 产出 exe,再次把 dist 内所有文件时间戳统一为 2000-11-11T11:11:11;
  • 用 makensis -DPRODUCT_VERSION=$VERSION electrum.nsi 构建 NSIS 安装器并重命名为 electrum-$VERSION-setup.exe。

8. 末尾的 PE 头修补:8 字节对齐与 COFF 校验和

这是可复现构建中最容易忽略、却至关重要的一步。build-electrum-git.sh 在产出 exe 后用一段内嵌 Python 脚本对每个 .exe 做两件事:

  1. 补齐到 8 字节边界:向文件末尾追加 null 字节,使总字节数为 8 的倍数(osslsigncode 签名时正是以 8 字节边界进行填充,两相对齐后签名二进制与未签名二进制才能逐字节可比);
  2. 计算并写入 COFF 图像校验和:解析 PE 头(e_lfanew 偏移位于 0x3c,checksum 字段位于 PE 头偏移 +88),按 PE 规范算法逐 4 字节累加并写回。

这一步把"签名前后二进制差异最小化"做进了构建本身,为后文的完整性校验铺平了道路。脚本末尾输出 sha256sum dist/electrum*.exe 供人工核对。

9. PyInstaller spec 与 NSIS 脚本

pyinstaller.spec 定义了三种产物的打包方式:

  • standalone exe:把全部依赖打进单个可执行文件(console=False,避免弹出黑色控制台窗口);
  • portable exe:额外以 DATA 形式内置 is_portable 标记(来自 README.md),实现免安装便携模式;
  • setup exe 组件:exe_inside_setup_noconsole 与 exe_inside_setup_console(-debug.exe,保留控制台输出)加 COLLECT,供 NSIS 安装器使用。

spec 还通过 collect_submodules('electrum.plugins') 收集全部插件子模块,collect_dynamic_libs('PyQt6') 保留 qwindowsvista 平台插件(规避"Retro Look"问题),并将 electrum/*.dll(libsecp256k1、libusb、ZXing 等)一并打入;同时用 excludes 排除从未用到的 Qt 模块(如 QtBluetooth、QtQml、QtWebEngine 等),大幅减小体积。

electrum.nsi 是 NSIS 安装器脚本,负责生成 dist/electrum-setup.exe:安装到 $PROGRAMFILES64\Electrum、创建桌面/开始菜单快捷方式(含 Testnet 快捷方式)、注册 bitcoin:、lightning:、lnurlp:、lnurlw: 四种 URL 协议关联,并在卸载时清理这些注册表项。

代码签名:Authenticode + GPG 双重体系

Electrum 的 Windows 构建除了 GPG 签名外,还使用 Microsoft Authenticode™ 代码签名证书进行签名。原文档说明其优势:用户启动时不会收到 Windows SmartScreen 警告。

发布签名流程

签名过程由持证的签名者(Signer)与一个或多个受信任的验证者(Verifier)协作完成:

签名者(Signer) 验证者(Verifier)
用 make_win.sh 构建 .exe
用 ./sign.sh 签名 .exe
上传签名文件到下载服务器
用 make_win.sh 构建 .exe
用 unsign.sh 对比文件
用 gpg -b 为 .exe 签名
签名者与验证者共同完成
将签名上传到 'electrum-signatures' 仓库,命名格式为 $version/$filename.$builder.asc

sign.sh 详解

sign.sh 使用 osslsigncode 进行 Authenticode 签名,关键输入:

  • 环境变量 WIN_SIGNING_PASSWORD(证书私钥口令,缺失则直接退出);
  • CERT_FILE 与 KEY_FILE,默认分别为 ~/codesigning/cert.pem 和 ~/codesigning/key.pem;

签名命令核心参数(-h sha256 哈希算法、-n "Electrum" 应用名、-i "https://electrum.org/" 应用 URL、-t "http://timestamp.digicert.com/" RFC3161 时间戳服务器),对 dist 下每个 .exe 输出到 ../signed/$f。时间戳服务器的加入意味着签名在证书过期后依然有效。

验证签名二进制的完整性

由于 Authenticode 签名本身不可复现(签名过程会改写二进制),普通用户无法直接把官方签名二进制与本地构建产物直接比对。因此原文档给出了标准的"剥离签名再比对"流程,其原理是让签名二进制与未签名二进制的差异只由签名本身造成,然后将其剥离:

  1. 用 osslsigncode 或 signtool 移除签名二进制上的 Authenticode 签名;
  2. 将签名二进制的 COFF 镜像校验和置为 0x0(因为 pyinstaller 不生成校验和,而签名工具会重算并写回该字段);
  3. 向未签名二进制追加 null 字节,直到总字节数为 8 的倍数(对应 osslsigncode 的填充行为)。

这三步由脚本 unsign.sh 自动完成。其工作方式为:从 https://download.electrum.org/$version/ 下载官方签名 exe(版本号通过 print_electrum_version.py 从 electrum/version.py 读取),用 osslsigncode remove-signature 剥离签名后,与本地构建的对应文件执行 cmp -s 逐字节比较,一致则输出 Success: $f,否则输出 Failure: $f 并退出非零状态。

任何用户都可以用这一套流程,独立确认官方 Windows 二进制确实由本仓库源码构建。

FAQ:可复现性失败时如何定位差异

如果 unsign.sh 对比失败,原文档给出基于 PyInstaller 工具链的排查方法。先安装 pyinstaller 以获得 pyi-archive_viewer:

$ pip install pyinstaller

第一步,做档案清单的整体对比:

pyi-archive_viewer -l electrum-*.exe1 > f1
pyi-archive_viewer -l electrum-*.exe2 > f2
diff f1 f2 > d
cat d

第二步,进入交互式界面人工深挖某个 archive 的差异:

$ pyi-archive_viewer electrum-*.exe1
? help

pyi-archive_viewer 可以逐层查看 PyInstaller 归档内的文件清单与内容,从而定位是哪个依赖、哪个数据文件或哪个字节导致了差异。

相关文件索引

需要注意的是:本文描述的是仓库内 contrib/build-wine/README.md 所对应的当前版本构建流程(Dockerfile 固定了 debian trixie 快照、Wine 11.0、Python 3.12.10 与 PyInstaller v6.13.0 等版本);这些版本参数会随仓库演进而变化,实际使用时应以所检出的 commit 为准。构建过程需要访问 Docker Hub、snapshot.debian.org、winehq.org、python.org 等网络资源,离线或受限网络环境下无法直接完成。

登录后查看全文
electrum