<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>开源 on Tech Philosopher</title><link>https://blog.bktus.com/tags/%E5%BC%80%E6%BA%90/</link><description>Recent content in 开源 on Tech Philosopher</description><generator>Hugo</generator><language>zh-CN</language><lastBuildDate>Thu, 19 Nov 2026 21:06:01 +0100</lastBuildDate><atom:link href="https://blog.bktus.com/tags/%E5%BC%80%E6%BA%90/index.xml" rel="self" type="application/rss+xml"/><item><title>GpgFrontend 新的版本模型与发布机制</title><link>https://blog.bktus.com/archives/2e68mf/</link><pubDate>Thu, 19 Nov 2026 21:06:01 +0100</pubDate><guid>https://blog.bktus.com/archives/2e68mf/</guid><description>&lt;p>更新一直是 GpgFrontend 的一大痛点。从最初的版本开始，GpgFrontend 就一直依赖 GitHub Release 来发版和检查更新，这样用了很多年。从 2.2.5 开始，包括现在的主线，版本号的规则、发布的流程，还有客户端检查更新的方式，都换成了一套新的模型和机制。具体怎么用、怎么验证，用户手册里已经写了，但是为什么要这样做，我当时是怎么想的，这些在文档里体现不出来。&lt;/p></description><content:encoded><![CDATA[<p>更新一直是 GpgFrontend 的一大痛点。从最初的版本开始，GpgFrontend 就一直依赖 GitHub Release 来发版和检查更新，这样用了很多年。从 2.2.5 开始，包括现在的主线，版本号的规则、发布的流程，还有客户端检查更新的方式，都换成了一套新的模型和机制。具体怎么用、怎么验证，用户手册里已经写了，但是为什么要这样做，我当时是怎么想的，这些在文档里体现不出来。</p>
<p>对于 GpgFrontend 这样的安全软件来说，透明是一个基本的要求。更新这件事情又直接关系到用户电脑上装的到底是什么东西，客户端在背后访问了哪里、发送了什么，用户有理由怀疑。所以我觉得有必要把它说清楚，让用户知道更新相关的东西究竟是什么样子的。GpgFrontend 一路过来的经历，可以看我<a href="https://blog.bktus.com/archives/5l9c2j/">之前的文章</a>。</p>
<h2 id="用了很多年的-github-release">用了很多年的 GitHub Release</h2>
<p>一开始，GitHub Release 其实挺好用的，至少到前两年为止都是这样。一个是它可以免费分发，另外一个是它的模型足够简单，release 和 Git 的 tag 绑定在一起。发版的时候，只要打一个 tag，写一份 Release Note，然后把 GitHub Actions 构建出来的安装包一股脑传上去，就 OK 了。</p>
<p>后来，项目的迭代速度加快了，特别是引入了 AI 相关的代码辅助之后，包括现在的 agent，功能也增加了很多。这些功能平时不一定感受得到，但是真正去用的话，还是会发现一些问题。按照原来 tick-tock 的节奏，是两个月发一版。很多时候，发版前没发现的问题，会在发版后的一两天、两三天之内被我自己或者其他人发现，这个时候我就很难马上再发一版，因为节奏就是两个月一个版本，中途要发版就很麻烦。</p>
<p>但是反过来，天天发版也不好。大部分用户在意的是稳定，并不想尝鲜，他们可能两个月才检查一次更新，或者更久。反正新功能大部分用户一般都是用不到的，他们用的是加密、解密、生成密钥这些。比如说邮件这块，以前基本上只能操作 EML 文件，我自己都承认它比较难用，现在邮件模块做了比较大的改动，基本上能覆盖日常使用邮件的场景了，但用它的人还是少数。</p>
<p>所以，对于大部分用户来说，等两个月应该没有什么感觉，因为我发版前会检查，基本的功能不会出问题。但是真的遇到问题的用户，要等两个月才能收到修复后的版本，那就比较难受了。我自己就能感受到这一点，不过我发现问题可以直接去修，然后自己编译自己用，反正我没有什么影响。但是我想象一下，如果没有条件自己编译，或者是一个非技术用户，那就要等两个月。</p>
<p>所以后面引入了 Nightly Build，它跟随我的开发主线，原来是跟随 develop 分支，现在是跟随 main 分支。我只要 commit，然后 push 到 GitHub 上，就会自动触发流水线进行构建。Nightly 和稳定版肯定是有区别的，稳定版再怎么说，都是经过验证的一些功能的集合，而主线上会引入很多新的功能。这些新功能大部分时候不会和稳定的功能冲突，但有些时候我会做一些架构上的调整或者优化，这个时候还没法验证它不会影响稳定性。所以 Nightly 用的是和稳定版不同的 profile，它作为一个单独的应用 GpgFrontend Testing 运行，有自己的密钥和设置。</p>
<p>发布方式上，Nightly 只有一个 <code>nightly</code> tag。流水线运行的时候，会拉取分支上最新的 commit 进行构建，然后强制覆盖现有的 <code>nightly</code> tag，再用相应的 action 插件创建 release，自动填好 Nightly Build 的 Release Note 模板。稳定版还是原来 <code>vX.Y.Z</code> 那样的 tag。这样 Nightly 和稳定版在 GitHub Release 上共存，至少用了一两年，感觉还行。不过 Nightly 没有 1、2、3 这样的编号，用户只能看到最新的那一个。</p>
<h2 id="转折点22-与多条版本线">转折点：2.2 与多条版本线</h2>
<p>真正的转折点是 2.2 版本。2.2 引入了第二个引擎，GnuPG 引擎和 RPGP 引擎可以同时使用，这是一次比较大的架构调整。当时需要时间来证明，引入 RPGP 带来的这些调整，不会影响现有的以 GnuPG 为主的用户。所以当时保留了 2.1 这条线，它是原来单引擎的版本线，照常更新，2.2 这条线也继续往前走。</p>
<p>这个时候，2.1 的用户很可能想留在 2.1 上。那么对于他们，只能优先推 2.1 的更新，等 2.2 稳定以后，再推荐他们升级到 2.2。如果用 GitHub Release 来做这件事情，就只能把客户端的逻辑加厚：客户端去访问 GitHub Release 的 API，判断 2.2 有哪些版本，2.1 有哪些版本，拿到每个版本的元数据，然后在本地计算 2.1 是不是有新版本了，2.2 是已经稳定了还是处于 pre-release 状态，有没有撤回之类的，最后再通知用户。这样实现起来虽然可行，但我一直感觉比较别扭。</p>
<p>GitHub 的 release 模型虽然能够表达两条版本线，但是它，怎么说呢，少了一些灵活性。比如说，发布 release 的时候可以把某个 release 标记成 latest，但是这个 latest 是所有版本里的 latest。对于某条旧的版本线，比如说为了兼容系统版本比较低的用户而保留的那条线，它的最新版并不是整个项目的最新版。</p>
<p>另外一个是 EOL（End of Life）的问题。比如说我打算让 2.1 在某一年的 12 月 31 号终止，用 GitHub Release 的话，总不能把 2.1 全部下架吧，这些东西都是要归档、要存底的。那就只能在客户端里写死：12 月 31 号以后 2.1 就是 EOL，推荐升级到 2.2。可是客户端是装在用户电脑上的软件，一旦发布出去，这个值就很难改了。如果我想把支持期往后延，或者提前，除非在某个地方远程读取这个值，否则就没有办法。</p>
<p>还有就是 Rate Limit。GitHub 的 API 是有访问频率限制的。我以前在公司里，用自己的电脑下载了 GpgFrontend，想检查一下更新，结果整个公司的出口 IP 已经达到了上限，根本没法用。挂 VPN 很多时候也一样，除非登录，可是客户端又登录不了，这就很尴尬。再就是它和平台绑得太紧了，只能用 GitHub 分发。如果我想在网站上自动判断用户的平台，给一个下载链接，那也只能链到 GitHub 上，下载也不是很稳定，挂 VPN 的时候速度会比较慢，用起来不是很爽。（至于很多人因为 GitHub 被微软收购了，不想访问 GitHub 相关的东西，这个是题外话，不是主要原因。）</p>
<p>当然，这些在 GitHub Release 上也不是完全做不到。比如说在 Release Note 里写一些约定好的东西，客户端去读取，再根据这个来判断。但是一个是不规范，另外一个是脆弱。就像一把菜刀，什么地方都能用，但是遇到一些特殊情况，用起来就是磕磕绊绊的。</p>
<p>也正是因为 GitHub 这一套要加的逻辑太多，而且很容易出错，我干脆没加，把更新检查的插件做得非常简单：只访问 GitHub，只读一些简单的元数据，然后做判断。结果就是这个插件并不好用，也几乎没有做验证。客户端怎么知道一个新推出的版本是经过签名的？从 GitHub 上很难方便地拿到这些签名，以及签名背后那个“根”之类的元数据。其实我自己平时都不太用这个更新插件。</p>
<h2 id="新的版本号规则">新的版本号规则</h2>
<p>在说新的发布机制之前，先说一下版本号的变化。原来的规则下，最后一位变了，并不代表这只是一个补丁，它代表在某个方向上又往前走了一步。比如说 2.1 这个方向，就是在单引擎上不断完善各种功能；2.2 是多引擎，2.2.1、2.2.2 只是在多引擎这个方向上继续探索，并不代表这次更新很小。确实有人提过这个问题，当时我就是这么解释的。从 1.0 一直到 2.2.4，我的想法都是这样。</p>
<p>从 2.2.5 开始，为了适应新的发布模型，或者说让它更合理一些，最后一位现在真的就只是补丁：</p>
<ul>
<li>第一位是“代”（Generation），比如从 1.0 到 2.0 那种变化。只有非常重大的架构调整，或者整个产品的思路变了，才会动它，和引入了多少行代码没有关系。</li>
<li>第二位是功能版本，也就是原来的“方向”。2.2 到 2.3，2.3 到 2.4，是真的有大的改动，大约两个月一次。</li>
<li>第三位是修复版本。2.3.1 到 2.3.2，2.3.2 到 2.3.3，回归它本来的意思，以安全更新和修复为主，可能会带一些特性，但尽可能少带，除非真的有必要。</li>
</ul>
<p>这样的好处在于，稳定的用户不需要新特性，也能享受到修复。比如说一个用户不想用双引擎，但想要 GnuPG 引擎相关的安全修复，或者他想停留在用得比较顺的 2.2 上，不想到 2.3 去。对我来说，也可以比较容易地控制各条版本线的节奏，把主线上的修复 cherry-pick 到各条线上，再通过现在的更新机制推送给对应的用户。2.2 到 2.3 只是推荐而已，你依然可以留在 2.2 这条线上接收补丁。</p>
<p>不过我一个人很难维护很多条版本线。一般是这样的情况：我想从 2.2 往 2.3 推进，但 2.3 引入了很多新东西，没那么快稳定下来，那 2.2 肯定还要继续存在一段时间，这个时候就是两条线。再加上 2.1 这条比较重要的单引擎线，就是三条，最多就维护三条。目前的状态是：2.3 是主线，2.2 是稳定版，2.1 是 legacy，只接收安全修复，到 2027 年 12 月 31 日为止，它也是最后一个能用 Qt 5 构建的系列。在新的机制下，我可以偶尔更新一下 2.1，按原来的节奏更新 2.2，然后继续把 2.3 往前推。这些状态都写在仓库的 <code>release/policy.toml</code> 里。</p>
<p>另外，Nightly 的版本号也变了。以前我把版本号，比如 2.3.0，写在 CMake 工程里，所有的 Nightly Build 都是 2.3.0，不管是在哪个 commit 上构建的。用户虽然可以在构建信息里看到 commit，但是引用起来并不方便。现在 Nightly 的版本号由 git 推出来，形如 <code>2.3.0-alpha.138+g&lt;commit&gt;</code>，<code>alpha</code> 后面的数字是从最近一个基准 tag 到现在的提交数量。这样别人好引用，我也好找，不用再去翻那么长的 commit message、再去仓库里对应，看到 alpha.250，大概就知道是哪一天的版本。用户也可以保留最近三四个 Nightly，新的不好用，就暂时退回原来的版本，等新的开发阶段过了再更新。</p>
<p>除了稳定版和 Nightly，还有 beta 和 RC（Release Candidate）。比如说我准备发 2.4 了，感觉主线上的功能差不多了，但还不是很稳定，想让愿意试用的用户先试一试，这个时候就会有 <code>2.4.0-rc.1</code> 这样的 RC 版本。beta 是某条线下一个修复版本的测试构建，版本号类似 <code>2.3.2-alpha.3</code>。beta 和 RC 只推给在设置里主动勾选了“Also offer beta versions”的用户，这个选项默认是关的。</p>
<h2 id="发布机制三个存储桶和一台更新服务器">发布机制：三个存储桶和一台更新服务器</h2>
<p>说完了版本模型的背景，再说发布机制。我现在不太想用 GitHub Release 作为主要的发布渠道了，最大的痛点还是前面说的，一个是速度比较慢，另外一个是有 Rate Limit 限制。</p>
<p>我其实一直对对象存储比较感兴趣，感觉应该用 AWS S3 这样的对象存储来托管。用一个普通的网页其实也可以，但是相比之下，客户端只需要获取一个元数据文件，比如一个 JSON，并不需要网页附带的 JS、CSS 这些东西。而且网页服务器有可能允许别人扫描目录，这就比较麻烦，我并不希望别人能一下子拿到全量的东西。我更希望元数据是隔离开的，客户端先拿到根上的元数据，需要别的东西时，由这个元数据指示下一个索引在哪里，再去访问。很多技术上的东西，用不同的方法都能做，但有些时候会有一种直觉，哪一种更好一些，更让我舒服一些。</p>
<p>本来想用 S3，但是它的出流量是单独计费的，我很难把控。这个软件会不会遇到 DDoS 攻击，一下子被拉走几百 TB 的流量？靠捐赠的那点钱，天天几百 TB，那是负担不起的。后来我发现 Cloudflare 的 R2 不对分发的流量收费，而且 Cloudflare 的 CDN 我一直在用，虽然它前段时间出过一些事故，但是对于软件分发这种不需要高可用的服务来说，还是 OK 的。所以就选了 R2。</p>
<p>然后就是在存储桶里存什么，以及谁来往里面放东西。我给自己定的宗旨是：新的机制一定要把我个人的精力解放出来，让发版变得更快，特别是稳定版。原来发一个稳定版，我要把安装包一个个下载下来，在我的 Windows 电脑上做 Authenticode 证书签名，然后再全部做一遍 OpenPGP 签名，再一个个上传，要搞两三个小时，还容易出错，有时候文件名都弄错了。从 2.0 开始我就用脚本了，后来又让 AI 帮我写了一个脚本，自动从 GitHub 下载，让我确认后输入密码做证书签名，再输入密码做 GPG 签名，整理到一个文件夹里，再慢慢传到 GitHub Release，这样快了不少。但是我还是要等流水线构建，一只眼睛看着流水线，一只眼睛做自己的事情。而且我现在住的地方访问 GitHub Release 比较慢，带宽不高，VPN 还限速，就比较痛苦。另外一个痛点是 Nightly 一直没有签名，我不可能每次都下载下来用自己的 GPG 签名，更不可能把 GPG 私钥放到流水线上。</p>
<p>现在的结构是这样的：</p>
<pre class="mermaid">
  flowchart LR
  CI[GitHub Actions] --&gt;|builds| Staging[(Staging bucket)]
  Staging --&gt;|stable builds| Me[Maintainer machine]
  Me --&gt;|signed| Staging
  Staging --&gt; Server[Release server]
  Repo[GpgFrontend repository] --&gt;|policy, trust, scripts| Server
  Server --&gt;|promote| Builds[(Builds bucket)]
  Server --&gt;|signed index| Update[(Update bucket)]
  Builds --&gt; Client[GpgFrontend]
  Update --&gt; Client
</pre>
<p>逐个说明一下：</p>
<ul>
<li>流水线：构建完成后，把产物和 <code>SHA256SUMS.txt</code> 传到 staging 存储桶。它还会用 Sigstore（cosign）对 <code>SHA256SUMS.txt</code> 签名，证明这些文件确实是 GpgFrontend 仓库的 <code>build.yml</code> 流水线在对应的 commit 上构建出来的。这种签名不需要我把任何私钥交给流水线，Nightly 终于有了签名。</li>
<li>staging 存储桶：私有的，不对用户开放，放的是还没有经过检查的东西。</li>
<li>我的电脑：只在稳定版的时候参与。从 staging 下载稳定版的构建，在本地用硬件 token 里的证书给 Windows 安装包做 Authenticode 签名，再用我的 OpenPGP 密钥签名，然后传回 staging。这个证书在硬件 token 里，没法导出，不可能放到云上签名，那样也不安全。</li>
<li>更新服务器：检查 staging 中的东西，检查通过后搬到 builds 存储桶，再更新索引并签名。</li>
<li>builds 存储桶（<code>builds.bktus.com</code>）：放安装包、每个版本的描述文件和 Release Note，用户从这里下载。</li>
<li>update 存储桶（<code>update.bktus.com</code>）：放签过名的索引 <code>index.json</code>，以及根和 index-keys 这些信任相关的文件。</li>
</ul>
<p>为什么要把 builds 和 update 分开？一个是不要把所有东西放在一个篮子里，构建产物和元数据分开放；另外一个是好管理，一个专门放元数据，一个专门放安装包，不会混在一起。再加上 staging，三个存储桶是比较合适的。</p>
<p>更新服务器在中间帮用户把一道关。对于 Nightly、beta 和 RC，它用 cosign 验证 Sigstore 的签名，确认构建来自 <code>build.yml</code>，并且 ref 和 commit 都对得上；每个文件都要和签过名的 <code>SHA256SUMS.txt</code> 一致，不能多出文件；版本号由它自己根据 git 推出来，不相信构建自己声称的版本号。对于稳定版，它还会检查我的 OpenPGP 签名和签过名的 tag，以及 Windows 安装包的 Authenticode 签名者。另外，它会读取仓库里的指导文件 <code>release/policy.toml</code>，比如 2.1 什么时候 EOL，2.2、2.3 现在处于什么状态，生成客户端容易读的元数据，也就是索引。</p>
<p>更新服务器很重要，它决定了客户端能看到什么。但它并不是最致命的一环。它不直接接受客户端的请求，所以也不需要什么高并发、防 DDoS，它只是把东西从未验证的地方搬到已验证的地方，再更新相关的元数据。高可用、高并发、DDoS 防御这些交给 Cloudflare 的基础设施，我自己专门写代码去做这些是一个大工程，也没有必要。所以负载放在存储桶，管理和准入放在更新服务器。而且客户端自己也会做验证，它对更新服务器也是以一种怀疑的态度去看待的，这个后面再说。</p>
<h2 id="签名的根2-of-3-与-minisign">签名的根：2-of-3 与 minisign</h2>
<p>还有一个问题是签名的根。签名的密钥不可能一直不轮换，我总不能 30 年都用同一把密钥。那么怎么管理？我没有用 CA 证书，那样反而更复杂。X.509 我知道它很灵活，可以加各种各样的字段，但是管理它本身就要用到很多工具，OpenSSL 什么的，过于灵活，功能也过多了。只是一个软件更新而已，不需要像 Apple 那样，搞一个 CA 根，自签名，做一个什么仪式，再用 CA 证书去签中间证书，中间证书再去签别的。虽然可以做到，但是没必要。平时用 2-of-3 加上 minisign，就已经完全可以搞定这些东西了。</p>
<p>具体来说：</p>
<ul>
<li>根由 3 把密钥组成，只要其中 2 把签名，就可以进入下一个版本的根。根的有效期是两年，也就是大概两年做一次根的更新，新的根要由旧根和新根里足够数量的密钥签名。</li>
<li>根并不直接签更新服务器的密钥。它指定另外一把离线的密钥，这把密钥不允许是根里的密钥，专门用来签一份 index-keys 列表。这份列表的有效期是一年，里面写明更新服务器可以用哪把密钥来签索引。</li>
<li>更新服务器上只有签索引的那一把 minisign 密钥，没有根密钥，也没有我的 OpenPGP 密钥和 Authenticode 证书。索引的有效期是 14 天，服务器每天重新签一次。</li>
</ul>
<p>所以整条链是：根 → 离线密钥 → index-keys 列表 → 更新服务器上的索引密钥 → <code>index.json</code>。更新服务器的密钥出了问题，或者平时有事没事想换一下，只需要用离线密钥重新签一份列表，不用动根。</p>
<p>这一套我自己不可能手写 JSON，也不可能手动生成三把密钥，再一个个配置上去，所以写了一系列脚本，按照这套机制的设计帮我自动生成，我只需要输入密码。生成的东西会写进项目仓库的 <code>release/root/</code> 和 <code>release/index-keys/</code> 下面，旁边还有可读性更好的文件，面向人类，也就是给我自己，或者其他审查代码的人看的。目前根里的三把密钥是 <code>4E179325A34DCF45</code>、<code>27458E01B54EAF5D</code> 和 <code>4D875241843652E8</code>。</p>
<p>为什么用 minisign，而不是 OpenPGP？GpgFrontend 本身就是一个 OpenPGP 的工具，这个问题很自然。问题在于 OpenPGP 需要先准备一个上下文（context）才能用，密钥管理相对比较复杂，而且它一般是和人的身份绑定的，不是随便就能生成一把新的，用子密钥就更复杂了。说到底，OpenPGP 主要还是给个人用户在各种场景下用的。对于机器读、客户端自己验证这种场景，最好就是依赖的上下文尽量小。minisign 的验证用 libsodium 就可以实现，不需要引入整个 GnuPG 或者 RPGP，也不需要 GpgFrontend 自己的 context 去加载什么，轻量的就可以用。而且这里只需要验证，只认密钥本身，不需要像个人身份那样还要看 User ID。所以最终用了 minisign。</p>
<p>但是底线还在。稳定版最终还是会用我离线的 OpenPGP 密钥签名，不管怎么自动化，稳定版都要我本人确认这个版本，手动输入密码，用硬件 token 里的密钥做签名。这把 OpenPGP 密钥和我的身份绑定在一起，是受到别人信任的，指纹是 <code>12F7E8858CF15BEC9975FF3C5CA3DA246843FD03</code>。这是最后一道防线，回到这个项目的宗旨上，我觉得已经足够了。</p>
<h2 id="客户端不盲信更新服务器">客户端：不盲信更新服务器</h2>
<p>在新的机制下，客户端的逻辑可以少一些，更多地由更新服务器提供的元数据来决定：现在有哪些版本线，哪条线处于什么状态，有哪些 beta 可以用，该推荐哪个版本。更新服务器可以根据安全或者其他方面的考量调整这些，以后版本号或者版本线变化了，也可以比较容易地指导客户端，而不会出现规则一变，旧的客户端就用不了的情况。</p>
<p>但是客户端不能盲目听信更新服务器。更新服务器本身可能被攻破，它的签名密钥也可能被窃取。所以客户端在编译的时候就自带了根，拿到索引以后自己验证：</p>
<ul>
<li>从自带的根出发，一步步走到最新的根，每一步都要满足 2-of-3，再检查 index-keys 列表，确认签索引的那把密钥在列表里；</li>
<li>验证 <code>index.json</code> 的 minisign 签名，检查它有没有过期；</li>
<li>检查索引的序号，不允许回滚到旧的索引；</li>
<li>用索引里的 sha256 检查每个版本的描述文件和 Release Note，下载的文件再用描述文件里的 sha256 检查。</li>
</ul>
<p>如果更新服务器被攻破了，或者做了什么恶意的事情，客户端验证不通过，大不了拒绝它。你只是没法方便地自动更新了，但还是可以手动去下载页或者 GitHub 上下载。</p>
<p>Release Note 现在也独立出来了，不再在 GitHub Release 里管理，而是放在仓库的 <code>release/notes/</code> 目录下。它需要用我的 OpenPGP 密钥签名后才能发布，它的 hash 写在签过名的索引里。里面的链接也有管控，只允许 https 的 <code>bktus.com</code> 及其子域名，还有 GitHub 上的 GpgFrontend 仓库，不能随便链接到其他无关的、可能是恶意的网址，不符合要求的链接只会显示成纯文本。</p>
<p>自动安装方面，目前 Linux 上 Nightly 的 AppImage 已经可以在更新窗口里点“安装”，下载的文件必须和描述文件里的大小、sha256 一致才会替换。稳定版以后再看看怎么安全地做自动安装，这样既方便用户，又能确保安全。</p>
<h2 id="同一套脚本gfrelease">同一套脚本：gfrelease</h2>
<p>这一套模型有一系列脚本，就放在 GpgFrontend 的仓库里（<code>scripts/gfrelease</code>），它是整个模型的具体实现。更新服务器直接复用这套脚本做检查、处理元数据；我自己也用同一套脚本，比如更新根、更新 index-keys 列表，还有把稳定版的构建下载到本地签名再传回 staging。也就是说，不是更新服务器自己有一套实现，我另外有一套，而是我们共同使用同一套基于这个模型的实现。更新服务器自己只有一些外围的东西，比如让它不要挂掉的部分、Dockerfile，还有一个可以让我一眼看到当前状态的 Web 页面。核心的东西，包括模型本身的实现、各种验证、OpenPGP 的验证，都在代码仓库里，所有人都能看到，都能审查。</p>
<p>更新服务器本身的仓库，我刚开始是想开源的，但后来又不想了。因为它涉及到我自己服务器上的一些配置，有人掌握了这些配置，可能在攻破之后更容易找到其他的东西。Dockerfile 本身没什么问题，但是 compose 文件里有环境变量，万一意外上传了什么密钥之类的，就比较麻烦。它本身就是很薄的一层，所以选择不开源。</p>
<p>那么我承诺它用的是仓库里的这套脚本，这个承诺算不算数呢？我也没法自证。虽然理论上我可以不用这些脚本，但实际上我是会用的，不过个人的承诺并不算什么。在安全软件这方面，没有“我说它是安全的，你就要无条件听我的”这种事情，这是不成立的。所以你可以去审查仓库里存的根和相关的公钥，检查你的客户端里带的是不是仓库中你认可的那个 commit 的公钥，也可以自己去验证更新服务器推到存储桶里的东西。不管更新服务器有没有被攻破，你都能看得到。</p>
<h2 id="更新检查会发什么不会发什么">更新检查会发什么，不会发什么</h2>
<p>这一部分我觉得需要单独说清楚：</p>
<ul>
<li>更新检查默认是关闭的。第一次启动时的设置向导里有一个检查更新的选项，默认不勾。打开以后，它一天检查一次。你也可以在 Help &gt; Check for Updates 里手动检查。</li>
<li>客户端只发 HTTPS GET 请求，访问的是 <code>update.bktus.com</code> 和 <code>builds.bktus.com</code> 这两个存储桶的域名，不访问 GitHub，也没有其他额外的服务器。</li>
<li>请求里没有用户 ID，也没有机器 ID，没有请求体，User-Agent 是一个固定的、通用的浏览器字符串。操作系统版本、架构这些信息只在本地用来挑选合适的文件，不会发出去。</li>
<li>需要注意的一点：最后一个请求是 <code>commits/&lt;commit&gt;</code>，路径里带着你这个构建的 commit，用来确认这个构建是不是来自官方仓库。所以服务器那边能知道你运行的是哪个构建，也就能知道是哪个版本，虽然版本号本身不会发送。</li>
<li>和任何 HTTPS 请求一样，服务器能看到你的 IP 地址。存储桶在 Cloudflare 上，Cloudflare 会按照它自己的规则处理和保留这些请求数据。我自己没有做任何访问数据的收集和分析，也没有必要做这样的事情。</li>
</ul>
<p>现在我人在欧盟，在欧盟的法律框架下，这些需要公开说明。所以后续我会更新一版新的隐私政策，让它符合法律，并在文档中解释更新检查到底会访问什么、会发送什么请求。</p>
<h2 id="这套东西是怎么做出来的">这套东西是怎么做出来的</h2>
<p>从最初的版本发布模型到现在的实现，你可以在提交记录里看到，即使有 AI 辅助，我也来来回回搞了好几轮。先是提出一个想法，让 AI 看看能不能先做一个简单的实现；后面发现这个实现有些地方不符合软件架构的原则，或者有 bug，让它修；修完之后在 Nightly 上用，发现好像不太 OK，再改；后来又想到以后其他版本线或者 beta 怎么办，再改。改完之后，还要让它重新检查一遍有没有问题，代码写得好不好，比如某个地方已经有可以用的东西了，它又在另外一个地方写了一份，又写了一个计算哈希的函数，这些都需要让它自查。</p>
<p>我自己也会看它提交的代码，看有没有坏味道（code smell），是不是符合我对这个模型的认知。AI 在几轮下来的过程中，可能会用另一种你不喜欢的方式去实现你想的东西，或者直接误解了你的意思，这个是需要自己把关的。</p>
<h2 id="后记">后记</h2>
<p>从 2.2.5 开始，包括现在的主线，最主要的版本管理都已经转移到了新的模型和机制上。仓库里的指导文件、流水线、更新服务器、存储桶、客户端，再加上我自己的电脑，各自分工，高内聚、低耦合，这也算是我个人经验的一个体现。GitHub Release 现在作为镜像继续保留。我感觉这套机制是够用的，未来很长一段时间应该都不用再大改，小修小补可能会有。</p>
<p>具体的使用方法和细节，可以看用户手册里的<a href="https://gpgfrontend.bktus.com/appendix/version-policy/">版本号规则</a>、<a href="https://gpgfrontend.bktus.com/appendix/release-updates/">发布与更新的工作方式</a>、<a href="https://gpgfrontend.bktus.com/appendix/code-binary-verify/">如何验证下载的文件</a>，还有<a href="https://gpgfrontend.bktus.com/overview/downloads/">下载页</a>。</p>
<p>大概就是这些。这篇文章主要解释为什么要做新的版本模型和机制，以及背后的一些基础想法。文章是我口述的，再让 AI 整理，整理过后我检查了是不是符合我的想法、有没有偏离原意，并不是让 AI 扫一下仓库一键生成的。我不太喜欢打字，现在可以口述，写文章也比较容易了，所以也不需要一次把所有东西都说完。后续有什么新的想法，会继续写文章，这些文章也会链接到 Release Note 或者用户手册里，帮助用户理解每天这么多 commit 到底在更新些什么，我又在想些什么。如果有错误或者疑问，欢迎指出。</p>
]]></content:encoded></item><item><title>GpgFrontend的前世今生：我与一个开源加密工具的成长之路</title><link>https://blog.bktus.com/archives/5l9c2j/</link><pubDate>Wed, 12 Nov 2025 22:21:17 +0100</pubDate><guid>https://blog.bktus.com/archives/5l9c2j/</guid><description>&lt;h2 id="缘起遇到-gnupggpg">缘起：遇到 GnuPG（GPG）&lt;/h2>
&lt;p>我第一次接触 GPG 是在 2021 年 4 月左右。那时候我还只是一个对计算机世界充满好奇的学生，对密码学的理解也只停留在“密码就是加密字符串”这样的表层。直到我读到非对称加密的原理：一个公钥可以让所有人加密信息，但只有拥有私钥的人才能解密。这让我非常惊讶。这种“数学意义上的信任”很吸引我，它优雅、严谨，而且不可逆。我当时觉得，这种技术的美感其实并不比任何艺术作品差。所以我开始学习 GPG 命令行的各种操作，从生成密钥到签名验证，反复去试，去琢磨其中的逻辑。&lt;/p></description><content:encoded><![CDATA[<h2 id="缘起遇到-gnupggpg">缘起：遇到 GnuPG（GPG）</h2>
<p>我第一次接触 GPG 是在 2021 年 4 月左右。那时候我还只是一个对计算机世界充满好奇的学生，对密码学的理解也只停留在“密码就是加密字符串”这样的表层。直到我读到非对称加密的原理：一个公钥可以让所有人加密信息，但只有拥有私钥的人才能解密。这让我非常惊讶。这种“数学意义上的信任”很吸引我，它优雅、严谨，而且不可逆。我当时觉得，这种技术的美感其实并不比任何艺术作品差。所以我开始学习 GPG 命令行的各种操作，从生成密钥到签名验证，反复去试，去琢磨其中的逻辑。</p>
<p>但是，我也发现了一个问题：命令行的门槛实在太高了。特别是有的时候，我只是想快点做一些简单的操作，却要输入一长串命令，说实话感觉挺不爽的。对于不熟悉技术的用户来说，GPG 的命令行几乎就是一片晦涩的荒原，基本上把想尝试的人都挡在了外面。所以我开始想，如果能给 GPG 做一个简单易用的图形界面，让它像一台看得见、摸得着的“密码机”那样直观、方便，每个人都可以很简单地拥有一台耐用又小巧的“密码机”，也许就会有更多人愿意去尝试。这个想法在当时看起来微不足道，但是后来好几年的技术折腾，其实都是从它开始的。</p>
<blockquote>
<p>“密码机”让人立刻联想到某种坚固、可靠的小设备，就像早期的机械密码机（如
Enigma）那样充满仪式感。它承载的不仅是技术，更是一种对安全的信念。这种机器功能不求繁多，却必须精准可靠。用户按下一个按钮，期望它执行的动作必须**可预期且安全
**。这种对“可控性”的追求，就是“密码机”的灵魂。</p></blockquote>
<p>我开始去找现成的方案。那个时候已经有一些 GUI 工具了，比如 Kleopatra。但是它们很多界面复杂、功能太多，有的还引入了 X.509 证书体系，这在当时一下子就把我劝退了。我想要的是一个更轻、更纯粹的东西。后来我发现了一个叫 <a href="https://git.bktus.com/gpgfrontend/gpg4usb/">gpg4usb</a> 的项目，它非常接近我理想中的样子：轻量、可携带、跨平台。但是很遗憾，它早就停止更新了，只支持 GPG 1.4 版本。这就意味着它和现代系统之间的兼容性问题几乎无法回避，也没办法支持子密钥。</p>
<p>所以我开始琢磨：能不能在它的基础上重写一部分，让它重新活过来？大概在 5 月份，我花了半个月左右的时间，在宿舍里读它的源码，摸索 GPG 接口的调用方式，研究 Qt 框架和跨平台的兼容问题。这个过程比较孤独，但是非常充实。每次让一个新功能成功跑起来，心里的那种成就感都很难形容。等我终于让它在 GPG 2 的环境下运行起来，并且修掉了不少原有的 Bug 之后，我决定给这个焕然一新的项目起一个新名字：<a href="https://gpgfrontend.bktus.com/">GpgFrontend</a>，也就是 GPG 的图形前端。这也是我人生中第一个完整的开源项目。</p>
<p><img alt="GpgFrontend" loading="lazy" src="https://img.bktus.com/P7a8YV8G.webp"></p>
<h2 id="亮相从宿舍里的代码到-github">亮相：从宿舍里的代码到 GitHub</h2>
<p>把第一个版本上传到 GitHub 之后，我其实没有期待太多关注。毕竟这是一个非常小众的领域，GPG 本身就不是大众常用的东西。但是几天之后，我收到了第一个 issue。一位用户说程序在某个操作系统上没办法运行，这位用户附上了日志，还提了修改的建议。那个时候，我第一次感受到了一种力量，让我愿意继续为这个项目投入时间。</p>
<p>之后，越来越多的人开始用 GpgFrontend。他们提问题、提建议，还有人帮忙翻译。每一个反馈都让我发现，这个项目已经不只是我个人的“技术玩具”，它是一个真的有人在用的工具。从那以后，我对“开源”的理解发生了很大的变化。开源不只是把代码共享出来，它更像是一个不断有反馈、不断演化的生态。</p>
<p>在后来的两三年里，我慢慢明白，GpgFrontend 不可能，也不需要成为一个“大而全”的工具。它要做的事情很清楚：帮助用户更方便地加密、解密、签名和验证。它的价值不在于功能有多少，在于好不好用、可不可靠。到现在，我已经很明确地把它定义成一个“轻量级、安全的密码机”，就和我当初刚接触 GPG 的时候想要的一样。</p>
<p>对于熟悉命令行的老用户，它是一个节省时间的辅助工具；对于初学者，它是一座通向密码学世界的桥。所以在 UI 设计上，我尽量保持简洁，让所有核心操作一目了然；在底层实现上，我让每个操作都直接对应 GPG 原生的命令，以保证稳定和兼容。后来我发现，这种“小而专”的定位，反而成了 GpgFrontend 最大的特点。别的项目在追求更多功能的时候，我选择让它保持专注。</p>
<h2 id="演进把项目当成技术的试验田">演进：把项目当成技术的试验田</h2>
<p>随着版本一个个推进，GpgFrontend 成了我学习新技术的练兵场。我在工作和学习中学到的新东西，都会尝试放进这个项目里。比如说，我研究了 Chromium 的多线程架构，把线程调度和任务隔离的机制引入到 GpgFrontend，这样执行加密的时候界面不会再卡住，竞态和多线程常见的一些 Bug 也尽可能地减少了。然后，我为它设计了插件系统和 SDK 接口，让第三方可以在运行时动态扩展功能。我还优化了构建脚本，引入了 CI/CD，让不同平台的打包流程更自动、更可靠。另外，通过这个项目的跨平台支持，我也了解了 Windows、macOS、Linux 之间的各种实现差异，以及在不同操作系统和发布平台下打包的流程。</p>
<p>这些尝试让工具本身变得更好，也让我学到了真正的工程经验：怎么设计一个可维护的架构，怎么在稳定和创新之间平衡，怎么在不破坏旧功能的前提下重构。GpgFrontend 就这样从一个简单的实验项目，慢慢变成了一个结构比较合理、稳定可靠的开源工具。</p>
<p>在我上网络安全课的那段时间，教授讲到了数据安全和密钥管理的重要性。我突然发现，自己在项目早期的一些实现其实是有隐患的。比如说，密钥派生算法过于简单，存储缺少轮转机制，还有部分内存没有加保护。所以我开始做一次全面的安全重构。</p>
<p>在 <a href="https://github.com/saturneric/GpgFrontend/releases/tag/v2.1.9">2.1.9</a> 版本中，我加入了安全等级、启动自检、AES-GCM 加密模式、密钥轮转机制和安全内存。另外，我重新设计了程序的数据结构，让临时的机密信息在用完之后，能够尽可能安全地从内存中擦除。这些改动看起来都在“幕后”，但实际上让 GpgFrontend 的安全性和可靠性提升了不少。我一直觉得，安全并不是某一个功能，它是一种态度。只有在设计的时候就把安全考虑进去，工具才能经得起时间，才能让人一直信任。</p>
<p>维护这个项目的这些年，我慢慢感受到一种技术以外的满足感。GpgFrontend 虽然不是什么“热门项目”，但它确实帮到了一些真实的用户。有人用它验证软件包的签名，有人在工作中用它快速处理安全通信，还有人告诉我，它是自己学习 GPG 的第一扇门。我不记录用户，也不专门去汇总各个平台的下载量。说实话，我也不知道到底有多少人在用它。但是我挺喜欢这种“不知道”的，它让我觉得 GpgFrontend 是一份很纯粹的贡献。说得具体一点，它就是一台“小密码机”，随手就能拿到，可以跟着人到任何地方，在需要它的场景里默默地干活。</p>
<h2 id="展望稳定专注与长期主义">展望：稳定、专注与长期主义</h2>
<p>接下来的几年，我不会让 GpgFrontend 有很大的变化。更新会一直进行，但主要集中在使用体验、稳定性、Bug 修复和一些小的优化上。我更倾向于让它保持轻量和可控。现在的软件行业到处都在讲“快速迭代”，我反而希望它能成为一个例外，做一个稳重、可靠、值得信赖的工具。也许它永远不会流行，也不会上技术新闻的头条，但只要它能一直帮到那些真正需要它的人，我觉得就都值得了。</p>
<p>最近几年，Rust 在安全领域越来越受关注，我也一直在留意。我研究了几个用 Rust 实现的 GPG 替代库，比如 RPGP、Sequoia 等。它们在内存安全和并发管理上做得更好，也支持 OpenPGP 的一些最新特性，我认为这应该是以后的方向。但是，我也必须面对现实：Rust 的生态还不完全成熟，和现有 GPG 生态之间的兼容性也还有待验证。</p>
<p>所以，我计划以后建立一个独立的分支，用实验的方式接入 Rust 版本的加密库，并通过一个新的密钥数据库层来做封装。这种渐进式的迁移，能让我在不破坏主线稳定的前提下，看看新技术到底是不是可行。我一直认为，稳一点的更新比盲目的创新更重要。毕竟对于一个安全工具来说，它的价值不在于新，在于能不能被信任。而这种信任的积累，可能要以 10 年为单位来算。</p>
]]></content:encoded></item><item><title>让树莓派 5 跑上“香草”主线内核：精简裁剪、交叉编译与部署全流程</title><link>https://blog.bktus.com/archives/mv9qo5/</link><pubDate>Sat, 14 Jun 2025 01:09:13 +0200</pubDate><guid>https://blog.bktus.com/archives/mv9qo5/</guid><description>&lt;h2 id="摘要">摘要&lt;/h2>
&lt;p>本文系统记录了我如何将树莓派 5 打造成主线 Linux 内核（Vanilla Kernel）的极简开发与测试平台——包括仓库极简裁剪思路、定制化内核配置、交叉编译与自动部署脚本、overlay 移除技巧，以及长期与主线社区同步维护的实战心得。适合关注 Linux 主线、ARM64 适配、内核开发、Upstream 贡献或喜欢折腾内核的极客们参考和实践。&lt;/p></description><content:encoded><![CDATA[<h2 id="摘要">摘要</h2>
<p>本文系统记录了我如何将树莓派 5 打造成主线 Linux 内核（Vanilla Kernel）的极简开发与测试平台——包括仓库极简裁剪思路、定制化内核配置、交叉编译与自动部署脚本、overlay 移除技巧，以及长期与主线社区同步维护的实战心得。适合关注 Linux 主线、ARM64 适配、内核开发、Upstream 贡献或喜欢折腾内核的极客们参考和实践。</p>
<h2 id="背景与动机">背景与动机</h2>
<p>最近一段时间，我在深入研究 Linux Kernel 的理论和架构，准备正式切入操作系统内核领域。因此，特意购买了树莓派 5 作为开发板，用于学习和实践内核开发。然而刚上手就发现，目前树莓派 5 并不能直接跑主线 Linux 内核，只能依赖<a href="https://github.com/raspberrypi/linux">树莓派团队维护的内核仓库</a>。当时最新的分支是 rpi-6.14.y（现在是
rpi-6.16.y），仓库的维护方式是“动态拉取上游主线代码+rebase+大量自定义补丁”，涉及上万行的修改和历史反复变动。</p>
<p>这些定制补丁对于官方内核在树莓派上稳定运行、兼容所有功能确实非常重要，但对我这种<strong>纯粹想研究主线内核特性</strong>、关注内核本身的开发者来说，这些补丁反而变成了负担：</p>
<ul>
<li>主线同步困难，merge 经常出冲突，</li>
<li>版本历史频繁重写，难以回溯和比较，</li>
<li>验证主线新特性或做反馈变得不直观。</li>
</ul>
<p>我对比了 x86 开发板，发现它们大多能直接运行主线内核，但价格昂贵，性价比远不如树莓派 5。因此，我开始思考，如何让树莓派 5 也能顺畅运行主线内核，真正实现随时体验和测试内核最新特性，并为 ARM64 平台反馈问题、贡献补丁提供便利。我的目标很明确：
用最少的补丁、最贴近 upstream 的方式，让树莓派 5 成为个人主线内核实验和学习的理想 ARM64 平台。</p>
<h2 id="仓库结构与修改范围">仓库结构与修改范围</h2>
<p>我的做法十分简单却又直奔核心——只保留最必要的驱动与补丁，其余全部紧跟主线。仅对
drivers/ 目录做补丁，聚焦核心硬件支持，主要包括：</p>
<ul>
<li>
<p><strong>SD 卡驱动</strong>：保证树莓派能正常引导，内核能加载根文件系统。虽然启动固件自带部分初始化功能，但主线内核仍需驱动挂载根文件系统。</p>
</li>
<li>
<p><strong>有线网卡（Ethernet）</strong>：方便通过 SSH 实现远程登录、下载新内核镜像、远程开发和调试，是内核开发过程中最重要的 IO 通道之一。</p>
</li>
<li>
<p><strong>UART 串口</strong>：作为内核调试和 early print 的输出窗口，可以直接观察内核日志，判断启动和运行状态。</p>
</li>
<li>
<p><strong>USB 控制器</strong>：用于外部设备挂载或偶尔传输离线数据，兼容更多实验场景。</p>
</li>
<li>
<p><strong>基本 GPIO、电源管理</strong>等与 RPi5 硬件紧密相关的部分。</p>
</li>
<li>
<p>剔除官方内核中与 <strong>Wi-Fi、蓝牙、GPU（VideoCore）、HDMI、音视频加速</strong>等非内核开发必需的子系统支持，这些对内核本身的研究和测试意义不大。</p>
</li>
</ul>
<p><strong>维护 arch/arm64/boot/dts/ 下的树莓派 5 DTS（Device Tree）配置</strong></p>
<ul>
<li>重点保证启动时能正确识别 RPi5 的各项硬件资源、CPU 配置和外设映射，确保主线内核能顺利运行。</li>
</ul>
<p><strong>其余全部与 Linus 主线保持 1:1 同步</strong></p>
<ul>
<li>除上述极少量补丁外，仓库其它部分完全保持与 <a href="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git">官方主线仓库</a> 一致。</li>
<li>定期（如每月或每两周）从主线拉取最新代码，只需应用极少量补丁并解决小范围冲突。</li>
</ul>
<p>通过以上做法，仓库极简、易维护，也为后续的配置精简与快速主线跟进打下了基础。</p>
<h2 id="定制化内核配置示例">定制化内核配置示例</h2>
<p>在实际部署过程中，我为树莓派 5 主线内核准备了一套自定义 .config 配置文件，目标是在<strong>最大限度裁剪无关功能、最小化编译体积和时间</strong>的基础上，满足我个人的开发、测试与服务需求。这个过程也伴随着不断试错和优化。</p>
<h3 id="第一阶段极致裁剪只留核心">第一阶段：极致裁剪，只留核心</h3>
<p>最初版本的 .config 文件，几乎关掉了所有我认为不需要的驱动和功能模块，包括：</p>
<ul>
<li><strong>所有非板载网卡驱动</strong>（只保留树莓派 5 板载 Cadence 网卡驱动）</li>
<li><strong>虚拟化支持</strong>（KVM 等）</li>
<li><strong>图形子系统、声卡、HDMI、多媒体加速等</strong></li>
<li><strong>所有网络文件系统</strong></li>
<li><strong>除了 ext4 和 SD 卡（mmcblk）以外的文件系统</strong></li>
<li>与上述模块相关的<strong>部分加密算法和内核机制</strong></li>
<li>甚至<strong>关闭了 cgroup</strong></li>
</ul>
<p>经过几轮调试和实测，虽然最终配置未必是理论上“最精简”，但已经让内核编译时间大幅下降，同时可以稳定启动和完成我需要的基础功能。</p>
<h3 id="第二阶段实用扩展支持-docker-负载与日常服务">第二阶段：实用扩展，支持 Docker 负载与日常服务</h3>
<p>随着内核实验的深入，我意识到：</p>
<ul>
<li>需要借助 Docker 跑一些实际负载以验证 kernel 的稳定性和兼容性；</li>
<li>需要支持局域网文件服务器（NAS）等日常场景；</li>
<li>还想用另一个树莓派长期运行自编译内核，部署不那么关键的服务。</li>
</ul>
<p>因此，新的配置文件又逐步<strong>扩展了部分功能</strong>，如：</p>
<ul>
<li><strong>cgroup、iptables、fuse、overlayfs、wireguard、macvlan、NFS、Samba</strong> 等常见内核模块（用于支持 Docker 及文件服务）</li>
<li>大多数新增特性编译为模块（module），按需加载，进一步优化启动和运行效率</li>
</ul>
<p>这一步虽然让编译时间略有增加，但相比主线默认配置仍非常精简，也更贴合我的实际使用和验证需求。</p>
<p><strong>配置文件仓库托管在：</strong> <a href="https://git.bktus.com/Linux/kernel-configs/">https://git.bktus.com/Linux/kernel-configs/</a></p>
<p>部分关键配置文件及时间线：</p>
<ul>
<li>eric-rpi-v1_defconfig</li>
<li>eric-vanilla-c-6.13_defconfig</li>
<li>eric-vanilla-c-6.14_defconfig</li>
<li>eric-vanilla-c-6.15_defconfig</li>
<li>eric-vanilla-v1_defconfig</li>
<li>eric-vanilla-v2_defconfig</li>
<li>eric-vanilla-v3_defconfig</li>
</ul>
<p>可以通过这些配置文件，看到我从极致裁剪到逐步扩展的调试和优化历程。</p>
<h2 id="优势与应用场景">优势与应用场景</h2>
<h3 id="贴近主线快速体验和验证新特性">贴近主线，快速体验和验证新特性</h3>
<p>保持极简补丁的最大好处在于：你可以几乎“零成本”地将 linux-next 分支的最新补丁，乃至 Linus Merge Window 期间的新功能直接拉到 RPi5 上跑起来。无论是新调度器、文件系统新特性、虚拟化和安全子系统增强（如 KVM、eBPF、LSM），还是 Zstd 压缩、新的内存管理机制，只要主线有变化，你都能<strong>第一时间在真机上测试、验证其兼容性和性能表现，
并及时为上游 ARM64 社区反馈问题和优化建议</strong>。</p>
<p>更重要的是，<strong>通过运行“香草”内核（Vanilla Kernel），你能最大程度还原和理解主线内核本身的实现逻辑</strong>，避免树莓派官方补丁引入的“副作用”，也不用担心误把 vendor
patch 的问题当成主线 bug。</p>
<p>采用 merge 而非 rebase 的方式维护补丁，仓库历史更加清晰，主线与本地差异一目了然，每次合并主线几乎“秒通过”，让你能始终跟进内核最新开发进度——比如随时 pull
linux-next 测试，或者 benchmark 内核新功能，体验感和参与感都极强。</p>
<p>这种方式对内核开发者、upstream 爱好者甚至“硬核”hacker 都非常有价值——你遇到的
bug、提交的 patch，就是主线环境下的真实问题，<strong>可以直接和内核社区无缝对接。</strong></p>
<h3 id="维护与开发更高效">维护与开发更高效</h3>
<ul>
<li><strong>补丁极少、冲突极少</strong>：只聚焦 RPi5 必需硬件支持，每次上游合并只需关注
drivers/net/arm/…、drivers/usb/…、drivers/bus/… 和
arch/arm64/boot/dts/broadcom/… 这几处，冲突极有限，维护量低。</li>
<li><strong>调试与回滚极其方便</strong>：如果主线引入了回归或异常，只需排查极少补丁即可回退或调整，无需在成千上万行 vendor patch 里大海捞针。</li>
<li><strong>便于贡献上游</strong>：你做的驱动补丁和 bug 修复非常“干净”，可直接整理成 patch，推送到 kernel mailing list，方便社区 review，不会因为 vendor patch 干扰而被卡住。</li>
</ul>
<h3 id="理想的开发测试与学习平台">理想的开发、测试与学习平台</h3>
<ul>
<li><strong>新特性探索与验证</strong>：RPi5 作为一台低成本、主流 ARM64 开发板，可以轻松测试
linux-next 或任意主线分支，为 upstream 社区贡献测试与反馈。</li>
<li><strong>性能调优与驱动测试</strong>：可以做性能 benchmark、驱动优化、功耗实验等，评估主线新功能在 ARM64 上的真实表现。</li>
<li><strong>教学与自学环境</strong>：对于学习 Linux 驱动、设备树和 HAL 的同学来说，极简环境最大限度减少“环境噪声”，专注理解主线驱动框架和硬件抽象。</li>
</ul>
<p>官方仓库在驱动齐全性、厂商适配性方面占据绝对优势，适合需要“开箱即用、多媒体完整体验”的用户；而我的主线仓库则专注于“紧贴上游、简化维护、便于开发”的需求。如果你只是想用树莓派 5 看视频、玩游戏、运行 GUI 桌面，官方仓库或许更方便；但对于内核工程师、开发者或热衷实验的同学，“轻量化主线仓库”则能让你更专注于内核本身。</p>
<h2 id="如何使用与贡献">如何使用与贡献</h2>
<p>理论上，树莓派 5 相比与树莓派 4 性能有了可观的提升，它自己来编译自己的内核是完全可以的，体验上也不错（内存大于 4GB 的情况下）。但是如果你需要进行内核或者内核模块开发，然后开启代码索引等能力的话，它的性能就不足了。</p>
<p>我还尝试过给它加上官方的 SSD Kit（512GB），虽然解决了 I/O 方面的吞吐问题，但最终还是遇到了 CPU 瓶颈，因为它只有 4 个 core！所以，如果你纯粹是需要一个可以跑的最新内核，并不经常编译，你可以在树莓派上编译安装。但是需要进行更进一步的开发调试的话，我还是强烈建议使用交叉编译，也就是在 PC 或者工作站（一般是 x86 平台）上编译内核和内核模块等，然后再通过网络拷贝到树莓派上（也通过 SD 卡实现）。比如，我的工作站有 12 个 core，跑编译时间缩短了好几倍（相对于 RPi5 的 4 个 core 来说）。所以，下面我就拿我用的交叉编译环境来举例子。</p>
<p>在此之前，你需要先安装 ARM64 的交叉编译环境。我建议安装 ccache 来进一步缩短重复编译的时间，如果你不想用 ccache 的话，那请去掉后续章节给出的所有命令中关于
ccache 的部分。</p>
<pre tabindex="0"><code>sudo apt install bc bison flex libssl-dev make libc6-dev libncurses5-dev
sudo apt install crossbuild-essential-arm64
sudo apt install ccache
</code></pre><h3 id="克隆仓库并检出最新分支">克隆仓库并检出最新分支</h3>
<p>我仓库是在我自己私有 Git 上的，但你可以使用我在 GitHub 的镜像。我会定期追踪
linus 的主线仓库并更新 main 分支。</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span>git clone https://git.bktus.com/Linux/kernel-configs.git
</span></span><span style="display:flex;"><span>git clone https://github.com/saturneric/linux <span style="color:#f92672">(</span>recommand<span style="color:#f92672">)</span> or https://git.bktus.com/linux/kernel.git
</span></span><span style="display:flex;"><span>cd linux
</span></span><span style="display:flex;"><span>git checkout main
</span></span></code></pre></div><p>注意：第一条命令是克隆我前面给出的<a href="https://git.bktus.com/Linux/kernel-configs/">内核配置文件仓库</a>，所以注意<strong>后续配置不要再用树莓派团队提供的配置文件</strong>（启用了大量特性），这大概率会导致后续编译好的内核无法启动。</p>
<p>其中，https://github.com/saturneric/linux 这个地址是属于GitHub的，理论上速度最快，所以没有什么特别的要求的话尽量从这里克隆。https://git.bktus.com/linux/kernel.git 是我自己服务器托管的仓库，而上面提到的GitHub的仓库是这个的镜像。</p>
<h3 id="进行简单配置">进行简单配置</h3>
<p>你需要在 kernel-configs 仓库选取一个适合当前版本的配置文件，重命名为<code>.config</code>，
然后拷贝到内核仓库的根目录下。</p>
<pre tabindex="0"><code>cp ../kernel-configs/eric-vanilla-c-6.16_defconfig .config
</code></pre><p>你可以在我提供的配置基础上进一步裁减内核，或者增加功能。</p>
<pre tabindex="0"><code>make ARCH=arm64 CROSS_COMPILE=&#34;ccache aarch64-linux-gnu-&#34; menuconfig
</code></pre><h3 id="编译">编译</h3>
<p>在准备好交叉编译环境直接编译。根据你的具体配置和机器性能，实际编译时间长短不一。我自己的编译时间大概是 10 分钟左右。</p>
<pre tabindex="0"><code>make ARCH=arm64 CROSS_COMPILE=&#34;ccache aarch64-linux-gnu-&#34; -j$(nproc)
</code></pre><h3 id="拷贝内核和内核模块到树莓派">拷贝内核和内核模块到树莓派</h3>
<p>你可以使用我提供的脚本，方便快速地把刚刚编译好的内核镜像与内核模块传输到树莓派的默认用户的家目录下。强烈建议内核镜像与设备树不要和树莓派 5 的默认内核同名，使用类似 <code>kernel-vanilla.c.img</code>和<code>bcm2712d0-rpi-5-b.vanilla.c.dtb</code>这样的名字，这样即使出了什么问题，我们也可以通过配置文件快速切换回原来的可用内核或者设备树。另外，
脚本用到的 rsync 需确保免密 SSH，建议提前配置好公钥。</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span><span style="color:#75715e">#!/bin/bash
</span></span></span><span style="display:flex;"><span><span style="color:#75715e"></span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># ====== 可配置参数（请根据实际情况修改） ======</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 本地存放内核编译产物的目录</span>
</span></span><span style="display:flex;"><span>LOCAL_KERNEL_ARTIFACTS<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;./kernel-artifacts&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 目标树莓派的 SSH 连接信息（如 pi@192.168.1.100）</span>
</span></span><span style="display:flex;"><span>REMOTE_HOST<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;pi@192.168.1.100&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 树莓派上的目标存放路径（建议使用绝对路径，如 /home/pi/kernel）</span>
</span></span><span style="display:flex;"><span>REMOTE_KERNEL_ARTIFACTS<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;/home/pi/kernel&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 目标内核文件名（可自定义，默认 kernel_2712.img）</span>
</span></span><span style="display:flex;"><span>KERNEL_IMG<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;kernel-vanilla.c.img&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 设备树文件名（可自定义）</span>
</span></span><span style="display:flex;"><span>DTB_FILE<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;bcm2712d0-rpi-5-b.vanilla.c.dtb&#34;</span>
</span></span><span style="display:flex;"><span>DTB_SOURCE<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;arch/arm64/boot/dts/broadcom/bcm2712d0-rpi-5-b.dtb&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># ==============================================</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>set -e
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; 清理并准备本地目录 &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>rm -rf <span style="color:#e6db74">&#34;</span>$LOCAL_KERNEL_ARTIFACTS<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>mkdir -p <span style="color:#e6db74">&#34;</span>$LOCAL_KERNEL_ARTIFACTS<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; 安装内核模块到本地输出目录 &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>make ARCH<span style="color:#f92672">=</span>arm64 CROSS_COMPILE<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;aarch64-linux-gnu-&#34;</span> INSTALL_MOD_PATH<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;</span>$LOCAL_KERNEL_ARTIFACTS<span style="color:#e6db74">&#34;</span> modules_install
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; 拷贝内核镜像和设备树 &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>cp -v -f arch/arm64/boot/Image.gz         <span style="color:#e6db74">&#34;</span>$LOCAL_KERNEL_ARTIFACTS<span style="color:#e6db74">/</span>$KERNEL_IMG<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>cp -v -f <span style="color:#e6db74">&#34;</span>$DTB_SOURCE<span style="color:#e6db74">&#34;</span>                    <span style="color:#e6db74">&#34;</span>$LOCAL_KERNEL_ARTIFACTS<span style="color:#e6db74">/</span>$DTB_FILE<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; 上传内核产物至树莓派 &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>ssh <span style="color:#e6db74">&#34;</span>$REMOTE_HOST<span style="color:#e6db74">&#34;</span> <span style="color:#e6db74">&#34;sudo mkdir -p </span>$REMOTE_KERNEL_ARTIFACTS<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>rsync -avz --progress --delete <span style="color:#e6db74">&#34;</span>$LOCAL_KERNEL_ARTIFACTS<span style="color:#e6db74">/&#34;</span> <span style="color:#e6db74">&#34;</span>$REMOTE_HOST<span style="color:#e6db74">:</span>$REMOTE_KERNEL_ARTIFACTS<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; 上传完成！你可以登录树莓派并配置/切换启动内核 &lt;&lt;&lt;&#34;</span>
</span></span></code></pre></div><p>这样，在执行完脚本后，待会你要安装的所有文件都先拷贝到树莓派上了，但注意只是拷贝上面去而已，还没有真正应用这个新内核。</p>
<h3 id="安装树莓派内核与内核模块">安装树莓派内核与内核模块</h3>
<p>使用下面的脚本，你可以方便地将刚刚拷贝到树莓派上的文件（设备树、内核与内核模块）
安装到预想的位置上。<strong>注意：该脚本涉及系统多个关键目录，请务必确认参数避免误删或者覆盖重要文件。</strong></p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span><span style="color:#75715e">#!/bin/bash
</span></span></span><span style="display:flex;"><span><span style="color:#75715e"></span><span style="color:#75715e"># ==============================================</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># RPi5 主线内核本地部署/刷机脚本</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 用于将内核镜像、设备树、内核模块，统一安装到 /boot 和 /lib/modules</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 请确保在树莓派上、且拥有 sudo 权限运行</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># ==============================================</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>set -e
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># ====== 可配置参数（请根据实际情况修改） ======</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 上传产物存放目录（刚才 rsync 下来的）</span>
</span></span><span style="display:flex;"><span>REMOTE_KERNEL_ARTIFACTS<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;/home/pi/kernel&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 内核镜像名（和上一个上传脚本保持一致）</span>
</span></span><span style="display:flex;"><span>KERNEL_IMG<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;kernel-vanilla.c.img&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 设备树文件名</span>
</span></span><span style="display:flex;"><span>DTB_FILE<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;bcm2712d0-rpi-5-b.vanilla.c.dtb&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 内核镜像与设备树所在位置</span>
</span></span><span style="display:flex;"><span>BOOT_FIRMWARE_PATH<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;/boot/firmware&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 内核模块实际安装目录（目标）</span>
</span></span><span style="display:flex;"><span>LIB_MODULES_PATH<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;/lib/modules&#34;</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># ==============================================</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; 1. 安装内核镜像和设备树 &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>sudo cp -v <span style="color:#e6db74">&#34;</span>$REMOTE_KERNEL_ARTIFACTS<span style="color:#e6db74">/</span>$KERNEL_IMG<span style="color:#e6db74">&#34;</span> <span style="color:#e6db74">&#34;</span>$BOOT_FIRMWARE_PATH<span style="color:#e6db74">/</span>$KERNEL_IMG<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>sudo cp -v <span style="color:#e6db74">&#34;</span>$REMOTE_KERNEL_ARTIFACTS<span style="color:#e6db74">/</span>$DTB_FILE<span style="color:#e6db74">&#34;</span> <span style="color:#e6db74">&#34;</span>$BOOT_FIRMWARE_PATH<span style="color:#e6db74">/</span>$DTB_FILE<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; 2. 设置镜像和 DTB 权限 &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>sudo chown root:root <span style="color:#e6db74">&#34;</span>$BOOT_FIRMWARE_PATH<span style="color:#e6db74">/</span>$KERNEL_IMG<span style="color:#e6db74">&#34;</span> <span style="color:#e6db74">&#34;</span>$BOOT_FIRMWARE_PATH<span style="color:#e6db74">/</span>$DTB_FILE<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>sudo chmod <span style="color:#ae81ff">644</span> <span style="color:#e6db74">&#34;</span>$BOOT_FIRMWARE_PATH<span style="color:#e6db74">/</span>$KERNEL_IMG<span style="color:#e6db74">&#34;</span> <span style="color:#e6db74">&#34;</span>$BOOT_FIRMWARE_PATH<span style="color:#e6db74">/</span>$DTB_FILE<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; 3. 安装内核模块 &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 会自动覆盖同版本号模块</span>
</span></span><span style="display:flex;"><span>sudo rsync -av --progress <span style="color:#e6db74">&#34;</span>$REMOTE_KERNEL_ARTIFACTS<span style="color:#e6db74">/lib/modules/&#34;</span> <span style="color:#e6db74">&#34;</span>$LIB_MODULES_PATH<span style="color:#e6db74">/&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; 4. 设置内核模块权限 &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>sudo chown -R root:root <span style="color:#e6db74">&#34;</span>$LIB_MODULES_PATH<span style="color:#e6db74">/&#34;</span>
</span></span><span style="display:flex;"><span>find <span style="color:#e6db74">&#34;</span>$LIB_MODULES_PATH<span style="color:#e6db74">/&#34;</span> -type d -exec sudo chmod <span style="color:#ae81ff">755</span> <span style="color:#f92672">{}</span> <span style="color:#ae81ff">\;</span>
</span></span><span style="display:flex;"><span>find <span style="color:#e6db74">&#34;</span>$LIB_MODULES_PATH<span style="color:#e6db74">/&#34;</span> -type f -exec sudo chmod <span style="color:#ae81ff">644</span> <span style="color:#f92672">{}</span> <span style="color:#ae81ff">\;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; 内核与模块部署完成！如有需要请更新/boot/config.txt 指定新内核 &lt;&lt;&lt;&#34;</span>
</span></span></code></pre></div><h3 id="配置树莓派固件引导新内核">配置树莓派固件引导新内核</h3>
<p>你需要编辑<code>/boot/firmware/config.txt</code>来确保树莓派固件引导新的内核并传递相应的设备树，然后使用内核树，最主要是修改或添加下面的两行。</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ini" data-lang="ini"><span style="display:flex;"><span><span style="color:#75715e"># DTB</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">device_tree</span><span style="color:#f92672">=</span><span style="color:#e6db74">bcm2712d0-rpi-5-b.vanilla.c.dtb</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Kernel</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">kernel</span><span style="color:#f92672">=</span><span style="color:#e6db74">kernel-vanilla.c.img</span>
</span></span></code></pre></div><h2 id="移除树莓派的-dts-overlay-特性并避免常见启动问题">移除树莓派的 DTS Overlay 特性（并避免常见启动问题）</h2>
<p>树莓派团队为其平台引入了 DTS Overlay 机制，这一设计允许在加载主设备树（Device
Tree）时，根据固件或用户需求动态叠加额外的 overlay 片段，从而灵活开启/调整外设、参数或特性。比如，你为树莓派增加了某个新模块或功能，仅需配置一个 overlay 即可激活，非常方便。</p>
<p>然而，这套机制目前<strong>并不被主线 Linux 内核支持</strong>！</p>
<p>如果在 <code>/boot/firmware/config.txt</code> 开启了 overlay 相关配置，而 overlay 文件与主线内核设备树（DTB）版本不兼容，极易出现启动异常、设备识别失败等问题。这对于追求极简、纯主线内核体验的内核开发者来说，往往带来更多困扰而非便利。</p>
<h3 id="处理思路">处理思路</h3>
<p>对我个人而言，DTS Overlay 的灵活性虽强，但主线内核并未原生支持，且对内核调试和纯粹环境带来很多干扰。因此我选择<strong>彻底移除 overlay 功能</strong>，只保留主设备树文件。这么做直接的副作用是：<strong>某些硬件参数（如 CPU 启动参数）原本依赖 overlay 机制注入，
直接去掉 overlay 会导致树莓派无法正常启动。</strong></p>
<p><strong>解决办法</strong>：我通过直接将所需的 CPU 参数写入主设备树文件来绕过了这个问题。实际上，bcm2712d0-rpi-5-b.dtb 这份官方设备树文件就是为无 overlay 场景准备的，只要使用它作为主设备树，系统即可正常引导，无需任何 overlay。</p>
<h3 id="如何移除-overlay-配置操作指南">如何移除 overlay 配置（操作指南）</h3>
<p>编辑 /boot/firmware/config.txt，确保只设置 device_tree，并移除或注释所有 overlay
配置（如 dtoverlay= 相关行）。示例如下：</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ini" data-lang="ini"><span style="display:flex;"><span><span style="color:#75715e"># 指定主设备树文件（建议直接使用 bcm2712d0-rpi-5-b.vanilla.c.dtb）</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">device_tree</span><span style="color:#f92672">=</span><span style="color:#e6db74">bcm2712d0-rpi-5-b.vanilla.c.dtb</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 不加载任何 overlay</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e">#dtoverlay=xxx      # 请全部注释或删除</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 其它 overlay 自动检测功能建议关闭</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">camera_auto_detect</span><span style="color:#f92672">=</span><span style="color:#e6db74">0</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">display_auto_detect</span><span style="color:#f92672">=</span><span style="color:#e6db74">0</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 启动内核镜像</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">kernel</span><span style="color:#f92672">=</span><span style="color:#e6db74">kernel-vanilla.c.img</span>
</span></span></code></pre></div><h3 id="检查其它与-overlay-相关的配置">检查其它与 overlay 相关的配置</h3>
<ul>
<li>推荐关闭 camera_auto_detect 和 display_auto_detect。</li>
<li>确认没有任何 dtoverlay= 配置项被启用。</li>
</ul>
<h3 id="重启树莓派">重启树莓派</h3>
<p>确保上述修改生效后，重启设备，系统将直接加载主设备树文件，<strong>不会再应用任何
overlay</strong>，从而最大程度保持主线内核的纯净性和可控性。如果后续没有任何问题的话，
可以移除<code>/boot/firmware/overlays</code>这个目录来节省空间，这也能确保后续启动如论如何都不会加载这些 overlay 导致环境污染。</p>
<h3 id="推荐-configtxt-最小配置模板">推荐 config.txt 最小配置模板</h3>
<pre tabindex="0"><code># 仅指定主设备树和主线内核镜像
device_tree=bcm2712d0-rpi-5-b.vanilla.c.dtb
kernel=kernel-vanilla.c.img

# 关闭 overlay 自动检测
camera_auto_detect=0
display_auto_detect=0

# 其它通用参数可保留
disable_fw_kms_setup=1
arm_64bit=1
disable_overscan=1
arm_boost=1
</code></pre><h2 id="提交补丁或-issue">提交补丁或 Issue</h2>
<ul>
<li>如果你在参考本文章操作时遇到任何问题，或者发现某个环节导致流程无法跑通，欢迎随时反馈。</li>
<li>如果你修复了某个兼容性问题，或在使用过程中发现了 bug，也欢迎直接提交 Issue，与我和其他使用者共同交流、完善项目。</li>
<li>如果你在本仓库基础上新增了硬件支持、做了性能优化，或移植了主线内核的新补丁，建议按照 scripts/format-patch.sh 生成标准化补丁，然后直接发往上游 Linux 内核
mailing list，推动改进被社区采纳。</li>
</ul>
<p>GitHub 仓库地址: <a href="https://github.com/saturneric/linux">https://github.com/saturneric/linux</a></p>
<h2 id="长期维护说明">长期维护说明</h2>
<p>本仓库和这篇文章都不是一次性的“快闪项目”。由于我将长期研究 Linux 内核和操作系统相关理论，会持续关注并跟进主线内核的每一次重大版本发布（包括 rc1 … rcX 等阶段性
release），并将关键改动和适配及时合入 main 分支。每次主线同步前，我都会先在我的工作站（Debian Testing）上编译然后在树莓派 5 上实机验证，确保仓库始终可用、流程通畅。</p>
<p>如果你也在用树莓派做主线内核开发，或遇到相关兼容性、适配问题，欢迎评论交流！也期待你加入主线内核社区，推动 ARM64 平台持续进步。</p>
]]></content:encoded></item></channel></rss>