Linux 发布目标为通用 x86-64,最低支持 glibc 2.34;不强制要求 x86-64-v2。 正式支持的系统还必须处于发行版提供的维护期,满足 glibc 版本只是必要条件。 Alpine Linux 与其他 musl 系统暂不支持。
EOL 系统不承诺兼容,也不纳入正式测试矩阵。这是支持政策,不是运行时拦截规则: 不检查发行版名称、支持截止日期或人为提高最低符号版本,旧系统恰好可以运行时不刻意破坏兼容性。
- 使用仍在维护的 AlmaLinux 8 系
quay.io/pypa/manylinux_2_28_x86_64构建,发布产物所需 glibc 符号不得高于 2.34。 - 构建环境镜像预装 GCC Toolset 15,通过
/opt/rh/gcc-toolset-15/root/usr显式选择编译器及归档工具;gcc/g++ 主版本必须为 15,静态运行库必须来自该 Toolset,实际 RPM 版本记录在日志。2026-10-12 用户确认提交 7f96ba4 的 Actions 全部通过,完成 GCC 15.2.1 工具链、C++23 预检、全量构建、ELF 审计及发行版/CPU 矩阵验证。 - 程序和 Botan 均显式使用
-march=x86-64 -mtune=generic,不使用-march=native。 - Botan 3.13.0 从官方源码构建静态库,校验固定 SHA-256;不使用发行版预编译的 Botan。
- Zstandard 1.5.7 同样从官方源码构建静态库并校验固定 SHA-256,使用通用 x86-64 编译选项。
- 使用
-static-libstdc++ -static-libgcc优先静态链接 C++ 运行库,产物审计要求不再依赖它们的共享库。 - glibc 继续动态链接,不使用
-static,不尝试完全静态链接 glibc。
Linux 构建脚本为 .github/scripts/build-linux.sh。
Botan_USE_STATIC_LIBS=ON 要求通过 PKG_CONFIG_PATH 指向同一 Botan 安装前缀的
botan-3.pc,以读取静态传递依赖;普通开发构建默认仍查找共享库。
Botan 显式使用 GCC 15 的 g++,Zstandard 与主程序的 CMake 显式设置编译器和归档工具,并重新初始化编译器缓存。Zstandard 固定 C17,避免工具链升级同时改变依赖的 C 语言版本。
每次项目构建前编译并运行独立 C++23 预检,覆盖 print/format、append_range、ranges::to、enumerate/zip、expected/optional、byteswap/to_underlying/contains 及 out_ptr;使用通用 x86-64 和静态 C++/GCC 运行库。Linux 预检不额外链接 stdc++exp,也不要求安装该实验库;实际功能的编译、链接与运行仍须全部通过。预检程序纳入 ELF 审计,并在每个发行版和 qemu64 路径执行,不进入正式 Artifact。功能或运行库检查失败时停止,不回退到旧 GCC。
manylinux 的兼容承诺针对 Python wheel,本项目借用其构建环境,不将其视为 ELF 兼容认证。 构建环境低于项目支持下限是有意选择:RHEL 9 系预编译库(包括静态 C++ 运行库)可能以 x86-64-v2 为目标,选择 AlmaLinux 8 系工具链可避免把该要求带入程序。 构建环境的 glibc 2.28 不意味着项目承诺支持 glibc 2.28;正式支持下限仍为 2.34, 不人为引入 2.34 符号来阻止旧系统运行,也不将更旧系统纳入正式矩阵。 Botan 的可选指令集优化保留运行时 CPU 探测,不能全局强制启用 AVX、SSE4 等指令。
工作流先通过 Buildx 构建已准备的环境镜像,加载到当前 runner 后再执行项目脚本;不发布镜像,也无需镜像仓库凭据。环境定义位于 .github/docker,共享构建步骤位于 linux-environment。
- 构建镜像基于 manylinux,预装 GCC Toolset 15、固定版本 CMake/Ninja,以及经源码摘要校验构建的 Botan/Zstandard 静态依赖。依赖固定安装到
/opt/filecrypt/deps,版本与摘要由 linux-deps.env 统一维护。依赖源码和中间产物在镜像构建结束前清理。 - 六个发行版测试镜像预装 CMake 和 unzip;Ubuntu 22.04 同时预装 QEMU,供普通发行版与 CPU 基线复验共用。测试阶段不再重复安装工具。
- 每个环境使用独立的 GitHub Actions 缓存范围,保存最终镜像所需的层。Buildx 每次检查上游底座;底座、安装脚本或依赖配置变化时重建相关层,项目源码变化不使环境缓存失效。
- 使用 UTC ISO 周作为刷新参数,在新一周的首次运行重新安装环境软件包及构建依赖。普通构建的缓存导出失败不阻断项目测试;独立预热任务要求导出成功,避免把未保存的环境误认为已可复用。
Linux 环境预热工作流 在 main 的环境定义变化时运行,每周一 UTC 03:17 定时刷新,也支持选择默认分支手动运行。它只准备七个环境并导出缓存,不编译项目、不运行测试、不加载或发布镜像。手动选择其他分支或标签时跳过,确保预热结果保存到默认分支范围。
分支运行在镜像准备成功后即导出缓存,后续项目测试失败不妨碍环境复用。标签运行只读取缓存,未命中仍正常构建环境,但不另存逐标签缓存。缓存受 GitHub 的引用访问范围与仓库空间限制约束:标签可以读取默认分支缓存,不能读取其他开发分支或其他标签的缓存;标签指向 main 的提交不等于本次运行在 main 分支下。日志记录运行引用、缓存范围、刷新周期及基础镜像名称,具体底座摘要与缓存层命中情况见 Buildx 输出。
2026-10-14 核对远端记录时,main 尚无 Linux 环境缓存;最近的 main 手动运行 使用引入环境镜像前的提交 2420635。已生成的环境缓存分别属于开发分支、v1.0.0 和 v1.1.0,因此新发布标签无法沿用它们。预热工作流补齐默认分支的公共缓存来源,标签只读则避免每个版本重复占用整套缓存空间。
首次启用后应先等待默认分支预热成功,再验证新标签的复用。同次推送分支和标签不会建立任务依赖,标签可能在预热完成前开始;跨周、上游底座更新、环境定义变化或缓存被清理时也仍会重建。定时任务可能延迟,缓存不保证永久保留。首次构建和周期刷新仍需联网安装软件及下载依赖,耗时应与缓存命中的运行分别比较。
项目源码、可执行文件与测试结果不放入环境镜像。每次运行仍重新执行工具链检查、C++23 预检、项目全量构建、全部测试与 ELF 审计;发行版矩阵及 qemu64 复验继续运行本次编译的同一批程序。镜像缓存不作为验证通过的依据。
Linux 构建与发行版/CPU 复验脚本先选择已安装的 UTF-8 locale,并验证字符集,统一设置 LANG 和 LC_ALL;没有可用 UTF-8 locale 时明确失败。目录素材使用 Info-ZIP unzip 解包,避免 CMake/libarchive 将 NFD 文件名归一化为 NFC。
Linux 构建后执行 8 项单元测试、3 项正式程序冒烟测试和 3 项非冒烟集成测试,共 14 项。单元测试包含 Format 层 expected 接口。非冒烟集成测试包括文件/目录 API 流程及 cli_directory_corpus 素材往返,后者校验 93 文件、23 子目录的完整树、文件大小和 SHA-256。
冒烟测试直接调用正式可执行文件,验证格式生成与读取、两种算法的压缩及无压缩加解密、密码错误和已有输出保护;
CLI 测试同时覆盖中文、空格及 emoji 路径和重定向 UTF-8 输出。
CTest 单元测试使用 unit 标签,所有集成测试使用 integration 标签,冒烟测试额外使用 smoke 标签,素材测试额外使用 corpus 标签。构建流程通过 -L integration -LE smoke 选择 3 项非冒烟集成测试。
测试命令、标签和超时统一在 tests/register_tests.cmake 注册,常规构建与发行版复验共用。复验脚本配置 tests/runtime 的无编译器 CMake 项目,引用同一批已编译程序,再通过 CTest 执行全部测试;不重新编译、不维护第二份测试名称清单。每个发行版使用独立的测试配置和夹具目录。CPU 基线复验通过 QEMU 前缀运行单元/API 测试,并用 CLI 包装脚本确保子进程也使用 qemu64。
Linux 随后审计正式程序和测试程序的 ELF:
- ELF64、x86-64,使用
/lib64/ld-linux-x86-64.so.2动态加载器。 - 所需 glibc 符号不高于 2.34,不允许私有或未知 glibc ABI。
- 动态依赖仅允许 glibc 系统库,不允许 Botan、Zstandard、libstdc++、libgcc 或其他第三方共享库。
- ELF ISA 必需属性不能声明 x86-64-v2/v3/v4;属性检查不能替代实际运行验证。
同一批已编译程序会在以下正式矩阵中执行全部 14 项对应测试,包含目录素材往返,不重新编译:
| 发行版 | 测试版本 |
|---|---|
| Ubuntu | 22.04、24.04 |
| Debian | 12(LTS)、13 |
| AlmaLinux | 9 |
| Arch Linux | 当前滚动版本 |
矩阵按 2026 年 10 月的维护状态选取;版本进入 EOL 后移除或替换,不以付费延长支持作为正式支持前提。
额外在 Ubuntu 22.04 中使用 QEMU qemu64 CPU 执行同样测试,检查不满足完整 x86-64-v2 的机器路径。
素材测试在 QEMU 基线复验中允许 360 秒,原生环境仍为 180 秒;测试内容与算法组合保持一致。
容器测试共用宿主内核,不代表已经验证所有历史内核或所有 CPU;原生机器的实际测试仍有价值。
只有上述 Linux 验证全部通过后才上传 filecrypt-linux-x86_64 Artifact,保留 14 天,
内容只有正式可执行文件 filecrypt;测试程序、依赖源码、文档和构建信息均不上传。
构建版本、依赖校验信息及 ELF 审计结果留在 Actions 日志。
Artifact 下载不保留执行权限,解压后运行 chmod +x filecrypt 即可使用,
无需另外安装 Botan、Zstandard 或 C++ 运行库。
推送 v* 标签触发发布工作流。发布阶段从同次运行下载 Linux Artifact,将正式程序命名为 filecrypt-linux-x86_64,纳入 SHA256SUMS 并上传 GitHub Release。发布工作流要求全部构建验证任务成功,任一失败均不发布。
工作流使用 checkout v7.0.1、upload-artifact v7.0.2、download-artifact v8.0.1,均使用 Node 24。上传显式设置 archive: true 保留命名 ZIP Artifact,下载使用默认解压和摘要校验,只从同次运行获取产物。
main 合并提交 daf3efb 的远端构建、发行版矩阵及 CPU 模拟验证已由用户确认全部通过。缓存命中、周期刷新和耗时比较需按对应运行记录确认;verify 新增功能的验证范围见 TODO。