Electrum Windows 二进制构建指南:基于 Docker/Wine 的可复现构建、代码签名与完整性校验
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...),原因有二:
- PyInstaller 默认引导器在杀毒软件中有较高的误报率;
- 脚本会在
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 做两件事:
- 补齐到 8 字节边界:向文件末尾追加 null 字节,使总字节数为 8 的倍数(
osslsigncode签名时正是以 8 字节边界进行填充,两相对齐后签名二进制与未签名二进制才能逐字节可比); - 计算并写入 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 签名本身不可复现(签名过程会改写二进制),普通用户无法直接把官方签名二进制与本地构建产物直接比对。因此原文档给出了标准的"剥离签名再比对"流程,其原理是让签名二进制与未签名二进制的差异只由签名本身造成,然后将其剥离:
- 用
osslsigncode或signtool移除签名二进制上的 Authenticode 签名; - 将签名二进制的 COFF 镜像校验和置为 0x0(因为 pyinstaller 不生成校验和,而签名工具会重算并写回该字段);
- 向未签名二进制追加 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 归档内的文件清单与内容,从而定位是哪个依赖、哪个数据文件或哪个字节导致了差异。
相关文件索引
- 构建入口:build.sh、make_win.sh、prepare-wine.sh、build-electrum-git.sh
- 构建容器:Dockerfile、apt.sources.list、apt.preferences
- 打包配置:pyinstaller.spec、electrum.nsi
- 签名与校验:sign.sh、unsign.sh、gpg_keys
- 通用工具:build_tools_util.sh、docker_notes.md
- 依赖锁定:deterministic-build(含 README.md 说明清单生成机制)
需要注意的是:本文描述的是仓库内 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 等网络资源,离线或受限网络环境下无法直接完成。