本项目是对 B 站录播姬 CDN 节点概览页面的致敬与精神延续。采用公开 DNS 扫描的方式，力求尽可能全面地揭示目前 B 站视频云自建节点的网络分布情况。

本项目旨在深入观察 B 站自建节点的架构分布，因此不包含以下内容：

• 已知位于公有云的节点（如 gotcha 类），此类信息请直接参阅录播姬的原文档。
• 任何形式的如 PCDN/MCDN 的边缘节点，鉴于此类节点分布规律的高度不确定性，暂不纳入统计范围。

本页面内容仅供技术学习与交流使用，旨在为 CDN 建设与规划提供参考。请勿将本项目数据用于任何非法用途。

更新日志

• 2026-02-05：因为发现节点有较多变动，重新从头扫描，本轮共收 1483 个节点，将面板从 lab.hanlin.press 移动到这里并添加对比功能。
• 2025-10-08：基于第三方解析数据，新增 twsx、office、bn 三个数据源，目前共收录 1456 个节点。
• 2025-10-07：项目数据正式上线，首批收录 1415 个节点。

数据展示

💡提示： 为提升检索效率，下方采用了数据异步加载的嵌入式页面。如遇内容渲染异常，请尝试刷新页面重试。

当前页面支持的功能如下：

• 浏览层级： 首页按“服务商/来源”汇总；点击进入后按“地区”汇总；再点击进入可查看具体“域名节点”。
• 搜索： 支持按“域名 / IP / 地区 / 服务商”全文检索（输入后自动筛选）。
• 详情展开： 点击域名行可展开详细信息。
  • IP：点击 IP 可复制；如存在更多来源信息，可展开查看。
  • ALT：如存在别名解析（ALT），会按 IP 分组展示，并支持一键复制别名域名。
• 版本切换： 右侧“版本”下拉框可切换不同数据版本。
• 版本对比： 点击“对比”展开对比面板，选择 A/B 两个版本后点击“开始对比”进入差异视图。
  • 请注意，所谓的新增和删除差异是按 B 版本作为新版本判定。
  • 差异类型包含：域名新增/移除、IP 增删、来源/别名（ALT）变化（来源/别名仅统计同一 IP 在两个版本中的差异）。

所谓的历史进程，大概就是一边看着新东西涌进来，一边目送旧东西离开。

引子

历史的进程

在用 hexo new 指令创建这一篇文章之前，我看了一下目录——这应该是我第四年开始专门写文章形式的年度总结了。四年来年度报告的形式各不相同，但是却一年比一年长。虽然很显然从每年的年度报告里可以回忆到我当时的精神状态，但现在真要回顾对比起来，却又只敢在 VS Code 里点开源文件，然后在右侧的小图里粗略瞅一瞅篇幅，生怕细看一下现在看起来颇显幼稚的话，然后再想起一些别的东西。

但若细细回顾这一年，与24年相对比，脑海里蹦出来的第一句话反而是长者的名句：「一个人的命运啊，当然要靠自我奋斗，但是也要考虑到历史的行程。」不管你的心态是变或者不变，自22年刹住的巨轮，似乎在这几年来又开始慢慢恢复转动，推动着数不尽的变。

我们在年初的跨年夜用大模型生成贺年词时，似乎也想不到，一条蓝色的海豚将在新年的火药味里横空出世，然后带着一车动物朋友们彻底涌入几乎所有人的日常生活。又比如，我4月23日时在某个地方感叹：「还得是你们新互联网人会造词，沟槽的原来这就是所谓 vibe coding」，然后各种乱七八糟的 Code 又变成了大伙的年度热词，人人都成为了驯服大模型写代码的斗牛师。

类似这样的事情还有很多。ChatGPT 的产品版本发布在2022 年 11 月，Stable Diffusion 1.5 发布在 2022 年 10 月。彼时在大家的眼里，ChatGPT 写的代码错误百出根本没法运行，Stable Diffusion 和 NovelAI 生图天天多好几根手指，修图和保持特征一致性和迁移特点更是难上加难（我当时为了研究这个可没少跑各种各样乱七八糟的训练）。而把时间拨到2025年，人们都已经不屑于按 Tab 自动补全，有的甚至编辑器都不开，直接在命令行里让大模型自己干活；而 Nano Banana Pro 的横空出世，也终于较好地解决了困扰我已久的迁移问题——我终于可以给我的AI头像换一套像样的衣服了。

在这种越来越快的进程面前，能够很明显地感受到，想法如果不很快落地，就会发馊变质。我在学校期间搞的一个项目就是这样，记得当时出想法时搜了一大圈并没有雷同点，然后半鸽半推地做了半年，老板想摇下一届一起做的时候，下一届的说：老师我们不想做了，我们在 GitHub 上找到了差不多功能的（时间确实在我有想法的很往后），几百 Star 了。

结构化解剖

就连算不了数和没有数理的问题都被这堆大模型解决了一大截——大模型可以走工具调用（Tool Call）嘛！这堆大模型现在调工具偷懒的能力一个比一个精，ChatGPT 内置的环境甚至能手撕一组二进制文件。

在我前文所述的项目里，我曾经为了 JSON 的问题头疼半天。当时的大模型虽然已经引入了形如 json_output 的参数，但是实测一下就发现每家都有新花样，在读入输出时总会出一些奇奇怪怪的问题，有换行的、有括号引号对不上的、还有键值牛头不对马嘴的，暴露了这堆太奶奶模型纯靠前文硬猜的底层局限性。而在 2025 年，我把一个 JSON 喂给 GPT 5.2 Thinking 后，只能见到它一个 with zf.open('result.json') as f 起手，然后嘎嘎写 Python 脚本，可用性提升得不是一点半点。

既然如此，想到某个倒垃圾的小频道有基于 JSON 的消息导出功能，干脆直接导出来喂给了 GPT 和 Gemini. 不知道降没降智的 GPT 先生运转了大约半个小时，吐出了下面这一段：

你会看到一个很“像人生”的结构：
7 月爆发（生活+技术双峰）→ 8–10 月维持高强度（信息策展更重）→ 11–12 月更像“打包归档 + 技术深挖 + 年终盘点”。

技术好奇心很强、动手能力重，喜欢把信息“搬回自己的库里”，平时用梗和吐槽快速表达立场，但真正重要的事你会认真复盘、写给未来的自己。
你在“线上内容圈层（群友/赛事/梗文化）”和“线下城市漫游（照片）”之间来回切换，把两者都当成生活。

某种情况下确实符合我今年的生活曲线。

过去的碎片与远方

过去

在写年度报告的过程中，我发现了比较有意思的一点：有的人对年度报告有一种近乎抵触的态度，认为这其中可能存在着回溯性建构的倒果为因的过程。而我自己对于年度报告的看法却比较复杂，一是如上所述，年度报告能够从一种特殊的角度留存你在那一年的精神状态，每一年都会有些新的细微的变化；二是，这篇年度报告在我的笔记本上躺了有接近半个月多，十多天来这篇博客的内容在我的脑海中不断地重构，一些文段在我的脑海中转瞬即逝——如果不记下来可能就真忘了。

11 月底，我收到了谷歌的一封邮件，说有个账号将被按不活跃删除，于是费了老大劲来恢复这个账号，点进去发现——这个账号居然是 2013 年注册的，那时候的谷歌还是老图标：

于是顺藤摸瓜地找，便发现了一车神秘妙妙的自己的互联网遗产，纳闷于当时的自己的是怎么和这些过去的事物扯上的关系，体验了一把被自己的子弹从背后击中的感觉。

甚至能在邮箱的未读列表里发现这样的邮件：

在记忆中，过去的事情并不总是连续的，更多的是像这样的零散碎片。由这个碎片起始可以联想出很多东西，但是如果不加唤醒，这个碎片的结局要么是像这次一样因某个契机而唤醒，要么是被不断涌入的新事物挤压而沉睡。

特别纪念

从碎片出发，我觉得有必要特别纪念两个可以被抬到台面上的发生在今年的公共事件，他们都是在今年再次回顾时，让我从不同程度想起了一些东西，值得扩展成一段来说说。

HIT FM：广播与座机里的音乐

12 月 20 日，加菲众发布了一条长推文，给出了中国国际广播电台旗下的 HIT FM 将要停播的消息。12 月 22 日，HIT FM 在白天时段正式播出了停播通知：

各位听众，劲曲调频广播频率北京地区FM88.7和上海地区FM87.9将于12月23日零时起不再播出新的内容。未来的时间里，各位听众可以在中央人民广播电台音乐之声和央视频客户端等相关新媒体平台上继续欣赏精彩的国际流行音乐内容，欢迎大家继续关注……

晚间在播送完 Owl City 最经典 Good Time 之后，HIT FM 依旧转入「明天会更加精彩」的零点报时引导，只是这次，在嘟嘟的报时声之后，再也没有了象征零点到来的滴声。

作为欧美音乐的爱好者，在很长一段的时间里 HIT FM 一直是我的干活专用电台，Potplayer 里一直有个 http://sk.cri.cn/887.m3u8，想听的时候就点开挂到后台。
但与大部分纪念的听众不同，我实际上是在比较晚的时候才从网络上接触到 HIT FM 的，究其原因也很简单：我并不是京爷沪爷，我所在的地方只有中国之声覆盖。但不得不说，在互联网还没有深度渗透，上网仍然需要2G手机卡的年代，如果你也和我共享着「担心家里人回来摸电视发热」的集体记忆，那么广播便是你绕不开的获取外界新鲜事的途径。
我用来听广播的设备也并不是什么专业收音机，而是一个白色的带脚垫的，当时我看来一手也能抓住的蓝牙音箱。那音箱应该也是淘宝1元拍卖来的，分为FM、蓝牙、插卡和插线四种模式，音箱上的那个半圆的 CD 纹按键早已被磨得发亮，大约是在那段时光里替我按住了时间的流速。
地方的广播台质量也不是特别好，不是评书就是卖药；而中国之声也并不总是我喜欢的节目，摸鱼的时间总要找个宣泄出口的。这时不知道从哪里听说了 12530，于是想到家里当时摆的移动座机。
12530 是咪咕的音乐台，本来只是用来设彩铃用的，但是同时也兼具付费点歌台的作用，当时的记忆是按几个键，然后说话就可以点歌，能点到的歌有的会完整放，有的只放一小段，总之就是引导你去花钱设那个彩铃。很显然，走 2G 语音信道传过来的音质可谓是差中之差，比广播听的质量还差，但多少也是填补了广播不在的那一部分。那一大段时间里天天跪在座机旁边，一听就是几十分钟，直到后面发现话费少了很多，才发现原来那个台是付费的。
刚刚写的时候才发现 B 站上居然也有人录，可以来体验一下：https://www.bilibili.com/video/BV1sd4y1S79H/

Crypko.ai：早期的拼凑时光

如果你一直对生图领域感兴趣，那你可能会对 Crypko.ai 有所了解。
这个玩意儿在 2018 年横空出世，特点是将 GAN（对抗神经网络）生图与区块链相结合，生成的动漫女孩可以进行融合与交易，当时在知乎上有这么一篇文章，标题写得格外吓人：人工智能+区块链首次成功着陆居然在二次元领域

AlphaGo 战胜了全世界所有最强旗手，掀起人们对人工智能（AI）的狂热关注。

AlphaZero 只通过34小时训练，战胜了战胜所有人类王者的 AlphaGo。

以比特币代表的区块链技术，引发了人们对新一代互联网革命的运动。

——人工智能+区块链，两大顶尖技术联起手来，打破了二次元人口结界。

这是他们的官图：

与现在的各路模型对比起来，这种 GAN 生成的图片看起来自然瑕疵百出，清晰度也不高。但在当时，第一代 Crypko.ai 跑在测试链上，并不需要真金白银就可以体验到当时看起来还很新鲜的生图玩意儿，那吸引力自然也是非常大的。

比如这是我存档里的一张图，看上去好像是买的别人融合的：

1
2
3
4
5
6

Crypko #708605
Iter: 18
Name: 优良miku素材请看族谱
Bio: 虽然长得不是非常miku但是拥有超优良基因
Hashtags: None
Origins: #704727, #704591

这一张像是自己融的，充满了古早互联网二次元头像的风格：

1
2
3
4
5
6

Crypko #708469
Iter: 362
Name: None
Bio: None
Hashtags: None
Origins: #708378, #706700

如果你对这张图的两个「祖先」（Origins）感兴趣：

那段拿着手机合新图片的过程大抵也是快乐的，只是后来项目方突然宣布第一代停止公测，把大伙账户里的 Crypkos 导出来发邮箱里（正如上面那样），然后沉寂了好久。

突然在 2022 年，我偶然刷到一条广告，才知道原来第二代来了。第二代离开了测试链，开始真金白银地分模型对生图操作收费，于是就不再关注。看上去他们的模型进步了不少，但我因为不再关注，只留下了后面调研时截在 PPT 里的一张图：

然后就是在今年，我在给最近图像生成技术作综述时，得知了它将在 2025 年 6 月 30 日停止运营的消息。如今早已过去半年，官网 也不再有更多告示，只留下了三国语言的「Crypko Service Has Ended」，多少有一点赛博坟墓的感觉。
很明显，Crypko.ai 也没能抵过新一代生图模型的浪潮。跑过 GAN 生图的大约都知道，其和 Stable Diffusion 的资源消耗就不是在同一个量级的，生成的效果更是被后者吊打。随着资源和收支的不平衡，作为新浪潮的牺牲品也是历史的必然，它不是第一个，也必然不是最后一个。
只是，它多少也是寄托了早期的一段时光，在那段时光里，你对着现在看上去错漏百出的图，大脑里也能拟合出一些幻想，那时你看着前面知乎文章里吹的「新一代互联网革命」茫然不知所以，却想着这些图哪些可以融合，什么时候他们会整出更多的花样。
又想到了 will7101 ，很不幸在换了好几台电脑后我这台电脑本地上已搜不到任何和他相关的记录，只记得我和他一起玩 Crypko.ai ，他用了好长一段生成的图当头像，如今其他的记忆已经模糊，只记下了这一串 ID。

同样也是去找图的时候，想到这个团队的前作是 MakeGirlsMoe，Crypko.ai 已经倒闭，这个网站因为 GAN 模型加载在前端，居然还能正常生图，令人唏嘘。

如果说 HIT FM 是旧时代的落幕，Crypko.ai 我觉得就是新时代死在沙滩上的前浪。

向远方去

在去年窜访南京之后，很荣幸今年的旅程进一步延伸到了武汉和上海。
在武汉主要是去打比赛，因为半公费的关系时间卡得非常紧，仅仅在最后一天参观了一下光谷步行街的假路牌以及华为大教堂，未能成功轰入飞鸟老师的音游窝，倍感遗憾。

然后就是7月末去上海，参加了 AOSCC 2025 ，于是便在会前会后见到了好多好多好多之前仅在网络上见过的群友，详细的面基情况甚至不太好计量。 .

说是面基，实际上更多是对自己心里建立的形象作一次大补全（比如发现 rvalue 老师完全符合头像和表情包），同时进行更多的延伸和探索（比较羞愧的一点是在大桌上和 Asuna 老师约了饭，此前没有啥正面交互，后来一想鼓起勇气加个 contact 吧，回头一翻人家 21 年就在频道了）。

只是有必要强调的是，那一整段的时间里上海的天气并不算好，顶着台风天换酒店赶路多少也是狼狈了一些。然后就在回来后过了好长一段时间的某天晚上，被某张街道图（后来被群友补充其实是中科大门口，现在看来似乎有点不太适合发挥）trigger 了一下，倒了一大段垃圾，本着展现原生状态的原则全文抄录在这里：

刚刚点开某个群友的小频道，看见他拍的一张夜景街道图，突然就意识到：自己在渐渐地对着「外面」的一些东西祛魅。看上去外面城市的道路也就那样，外面的道路也是下了雨湿漉漉的地，也是一片一片霓虹灯，一排共享单车后面是一堆楼，楼里的灯也没亮几个。对于这种场景，我内心里看到的只是孤独：这道路还没我这门口宽呢，我只想躲进熟悉的被窝里睡一觉。
又想起来自己无论是在南京，武汉还是上海，都曾干过独自探索城市的行为，要找他们的共性也很容易：时间往往是深夜，我坐着空荡荡的公交车，在雨天，跑在城市的大外环上。
最近一次在上海的最为夸张：我举着云台开着手机上的延时摄影，在车上迷迷糊糊了一个小时，手机可以清楚地看到因公交车急刹车而被甩来甩去的视角。到站了，公交车右转进某个大空地，大约是下班了。我被扔在昏黄的路灯底下，打开手机想找共享单车，空旷的场地稀稀拉拉几辆，拖着腿走过去，扫上车开始蹬，头顶又下起了雨。回到酒店后，迷迷糊糊地打开携程改签酒店跑路。
然而事后再看录下来的延时，发现也就是那样：快速路，高架桥，并不繁华的路段，稀稀拉拉的灯光。一座现代城市不可能把自己的每个角落都做成旅游资源，你真的跑到了城市的边角，容易发现也就是那样，城市的城建建设大约都是趋于同质化，到最后甚至可能没你家门口楼下的社区市场热闹。
刚刚看到那张照片，心里产生了这么一些破碎的想法，也对下面这段好久之前就看到的话有了点肤浅的认知：
旅游就是从自己活腻了的地方，跑到别人活腻了的地方，去花掉自己的钱，让别人富起来，然后满身疲惫、口袋空空的再回到自己活腻了的地方，继续顽强的活下去。

可以说是为「远方」提供了一个新的角度。

但有时候我也在想，向「远方」去探索带来的新鲜感，是否有一部分是来源于回应那个当年趴在座机旁听 12530、对‘外面’充满噪点般幻想的小学时的自己？你可以说是给自己心里的某张图加边，构建新的联系；也可以说是呼应那时候听电台的自己对外面世界的幻想，给想象一个新的注解。

倒垃圾的部分暂且结束，如下是一些零散的数据总结。

数据们

2025 年从大基调上来看，整体上是一个充满探索与回顾的一年。由于某个大伙可能猜得到的原因，这一年的综合娱乐活动整体上处于暂停状态，在年底才有补锅的机会。

• 今年的博客数据与去年基本持平，访问量略有下降。主要来源于今年的两篇大型文章，开往的跳转，以及自建 QQ Bot 项目。虽然文章量少了访问量自然会掉，但是能维持住这么一个量级还是挺让我惊喜的。

• 今年的 Tai 统计数据多少也能看出些端倪，很明显反恐的数据远不如去年：

• 在音乐软件方面，可以分享的一点是网易云居然凑了个整：你怎么知道我听 3456 首歌听了 23333 Min ：

Spotify 侧的画风和网易云截然不同，还是软件分开听惹的祸：

• TG 频道今年合计多了两千多号人，具体图就不在这里附了。

• 还需要补充的是邮政类，今年合计收到 32 张明信片，期待明年再创新高。

年度们

我们来推歌好了，以下列表的主体是这一年时间内我特殊分享出来的歌：

• 来吧，甜蜜的吐槽(ED) - 卢恒宇/李姝洁 ：很显然这首歌是 neta 了隔壁那首「now the guilt is all mine」（我相信大伙多少都有一点ptsd了）。我个人应该是先听了这一首点了红心，过了好多年才被推到EVA上的原版。这首歌我觉得和甩饼歌一样，带着早期中文互联网那种优酷时代的网络歌曲痕迹（比较典型的就是各类翻唱填词），我觉得这应该是改编的比较好的，能够让你每次听完之后后劲都挺大的那一类。不得不承认还是母语歌潜意识里带来的情感调动更大。
• Human Again - Boxplot：11分钟的 DNB 作品，11分钟的循序渐进与情感调动，强烈推荐。
• The Big Goodbye - AJR：AJR 今年的新作，一如既往的特色编曲，经典的回顾性歌词——「Why my town feels like home for the first time in years, Why’d I need to be known, they fucking know me here」。
• UNDERCOVER (feat. Shinpei Nasuno) - 電音部/Shinpei Nasuno/蔀祐佳/天音みほ/堀越せな：电音部的耐听王，单纯是过了两年被 Spotify 推到发现还是很耐听。
• Nothing’s Gonna Stop Us Now - Starship：经典老歌，陪我扛过了今年情绪低谷的一个时期。
• It’s All Coming Back to Me Now - Céline Dion：同上，感觉今年对经典老歌没抵抗力。
• Ariana - Tony Anderson：今年非常喜欢听的一首纯音乐，适合情绪舒缓与冥想。
• 流沙 (Reimagined) - 陶喆：陶喆重置歌的新编曲很棒。
• Full Heart Fancy (Instrumental) - Lucky Chops：入选《地平线5》的一首纯音乐，时常让人想起派对的欢乐场景。

Update on 2026-03-17: 使用某下载器对 TOGENASHI TOGEARI - Fragile Violet - Single 进行了复测，发现解码失败的问题仍然存在，而且元信息里的 Encoded date 仍然是 2025-06-23，证明苹果并没有重新编码。鉴于内录测试已经证明了下载器的可靠性，故此次并没有重新使用内录法测试，有兴趣的可自行验证。

TL;DR for non-Chinese readers:
Since around May 2025, We’ve discovered that many lossless ALAC files sourced from Apple Music are fundamentally corrupted—an issue that remains unfixed as of March 2026. Through rigorous internal recording tests, where We captured raw audio directly from the official Windows client (shout out to @TheM14) and compared it with pristine tracks from platforms like MORA and Tidal, We’ve proven that this is not a third-party downloader or DRM decryption glitch, but a defect originating directly from Apple’s own source files or encoders.
Because these corrupted files consistently fail standard integrity checks in software like foobar2000 and throw specific processing errors in FFmpeg, I’ve included automated batch scripts (for Windows, Bash, and PowerShell) below to help you easily scan your own local library.
Ultimately, Apple Music’s lossless tracks can no longer be blindly trusted for high-fidelity archiving; I strongly advise you to verify your files, be cautious of converted FLACs that might mask these underlying errors, and always cross-reference your music with known good sources.

背景

本文是对频道一段时间前的发送的这条推文的整理与补充，方便追踪、讨论与评论区拍砖：

在大约今年5月份之后，Apple Music 某个节点上的无损音乐编码器似乎坏掉了，导致他们提供的音乐源文件就是爆的，相比于其他来源会出现丢失采样的问题。根据社区的实验，内录官方客户端并分析采样，会发现问题依然存在，因此该问题似乎与社区中热门的第三方下载实现无关。

叠甲在先：

0. 尽管 Apple Music 的下载方案已从去年 DRM 被公开破拆之后成为马奇诺防线，并可在多个国内平台看到教程，但本文并不提供任何下载指导，也不鼓励任何形式的侵权行为。
1. 本文的方法论建立在对几张典型专辑的实际测试之上，我并非 Apple Music 的利益相关者，我甚至并不知道当前的情况是 Apple Music 官方的编码器压坏了，还是 Apple 故意为之，推出了某个很新的妙妙 DRM 方案。众所周知，Apple Music 的编码器会对音频进行一些特殊处理（比如将部分数字母带™的响度调高），如果这次发现的音频问题在内录后依然存在，那么我认为它就不应被归类为 DRM，而是一种事实上的音频水印。

现象

正文开始，以下是编写时发现仍有问题的专辑，你可以用来进行测试：

• TOGENASHI TOGEARI - Fragile Violet - Single
• Nate Sib - for us
• Pleasure - JOLIN蔡依林

基于如上的叠甲，本文不会讨论更多的原理，只说对速查有用的现象：

1. 出问题的音乐大多数是在今年（即 2025 年）之后被 Apple 重编码，通过一个现代的播放器（如 Potplayer）你可以在音频文件的 Encoded date 里找到 2025 年之后的日期。

2. 如果使用带有校验功能的下载工具，会发现这些文件无法通过测试。使用 foobar2000 等第三方软件进行验证完整性，也无法通过：

使用 foobar2000 内置的 FLAC 转换也会报错：

3. 使用 ffmpeg 进行转码时会报错，根据你不同的 ffmpeg 版本，报错通常会是如下的其中一种或多种：

• Invalid data found when processing input
• Not yet implemented in FFmpeg
• Syntax element
• patch welcome / patches welcome

其中，对于一大组文件，我认为使用 ffmpeg 进行检测是最为方便的方法，尤其是当你需要批量处理时。你可以使用以下命令来模拟：

1

ffmpeg -i "m4a文件" -f wav -hide_banner -loglevel info NUL 2>&1

以如上的 TOGENASHI TOGEARI - Fragile Violet - Single 为例，输出会是这样的：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Stream #0:0(und): Audio: pcm_s16le ([1][0][0][0] / 0x0001), 44100 Hz, stereo, s16, 1411 kb/s (default)
    Metadata:
      encoder         : Lavc62.13.101 pcm_s16le
      creation_time   : 2025-06-23T04:06:21.000000Z
      handler_name    : Fragile Violet
      vendor_id       : [0][0][0][0]
[alac @ 00000289a4f48580] invalid element channel count
[aist#0:0/alac @ 00000289a2cc8fc0] [dec:alac @ 00000289a2cc9180] Error submitting packet to decoder: Invalid data found when processing input
[alac @ 00000289a2cee6c0] invalid element channel count
[alac @ 00000289a4f48580] invalid element channel count
[aist#0:0/alac @ 00000289a2cc8fc0] [dec:alac @ 00000289a2cc9180] Error submitting packet to decoder: Invalid data found when processing input
    Last message repeated 1 times
[alac @ 00000289a4f79a40] Syntax element 4 is not implemented. Update your FFmpeg version to the newest one from Git. If the problem still occurs, it means that your file has a feature which has not been implemented.
[aist#0:0/alac @ 00000289a2cc8fc0] [dec:alac @ 00000289a2cc9180] Error submitting packet to decoder: Not yet implemented in FFmpeg, patches welcome
[out#0/wav @ 00000289a2c23080] video:0KiB audio:32168KiB subtitle:0KiB other streams:0KiB global headers:0KiB muxing overhead: 0.000929%
size=   32168KiB time=00:03:07.10 bitrate=1408.4kbits/s speed=3.54e+03x elapsed=0:00:00.05  

速查工具

出于验证的需求，我找 Gemini 生了个批处理脚本并改了改，可以用于批量校验这些文件。 你可以直接下载使用，或是在附录找到源代码，自己看一眼再跑。在运行脚本时请确保您的环境中已安装并配置好 ffmpeg，并且可以在命令行中直接调用。

• Windows 的批处理脚本（版本 20250911），支持递归检测当前文件夹与拖放检测。
• Bash 的脚本（版本 20250911），支持递归检测当前文件夹与命令行。

验证

此前的发现在社区内引发了广泛讨论，其中不乏有观点认为这是 Apple Music 的一种防盗版机制。为了厘清这一问题，本段将提供一份客户端内录的验证记录，让每位读者都能亲手检验——这些音频瑕疵究竟是源于 DRM 保护，还是 Apple 自身的编码器缺陷。
在动手前，请务必再次阅读以下声明：首先，出于版权考量，本文不会涉及任何下载教学，我们假设您已合法拥有需要验证的音乐。其次，我们判断的逻辑很简单，也已在上文中叙述：如果所谓的“问题”在内录后仍然存在，那它就和 DRM 无关了，而是一种被编码进音频里的“事实水印”，是该和国内的流媒体坐一桌的。

此处非常感谢 @TheM14 老师进行了严谨的测试，为本文提供了非常重要的参考依据。

准备工作

首先，我们需要证明内录的结果是正确的，这里需要提前进行以下处理：

1. 寻找一个内录通道，这里使用的是 Minifuse 声卡驱动自带的内录通道（主要是方便），像 VoiceMeeter 的虚拟内录通道也是可以的。
2. 将输出的采样率和位深设置成和原曲相同。
3. 干掉 Windows 自带的 CAudioLimiter。 这是 Windows 操作系统音频引擎中一个内置的音频处理组件。它的主要功能是作为一个峰值限制器（limiter），防止音频信号在输出时超过最大电平（0 dBFS），从而避免产生削波（clipping）失真。但为了忠实地还原音频，我们需要确保录制的音频不经过任何额外处理。你可以参考 B 站上的 BV1GPNezjEsM 来干掉它。（在进行任何有关注册表的操作前，请手动备份注册表）

内录与验证

接下来进行内录，此处以「結束バンド」的「僕と三原色」这首歌为例。

1. 先在 Apple Music 的 Windows 客户端中寻找对应的歌曲并进行下载（以免网络不良的情况下播放成 lossy 的 AAC）.
2. 使用内录通道配合 Reaper 内录（录制的时候要设置好工程的采样率），之后导出 48/24 （与已知采样率一致）的 WAV .

在进行后续对比之前，我们必须首先确保录音能够精确还原 Apple Music 输出的原始音频流。我们可以使用 foobar2000 的 Binary Comparator 组件（下称 bitcompare）来进行对比，你可以在 foobar2000 的组件库 中找到它并安装，请注意一下这个组件只有 32 位格式。
此处，我们手里有三份音源，一份是通过工具下载解密 DRM 获得的 ALAC（decrypted.m4a），一份是内录的 WAV（recorded.wav），另一份是通过 MORA 自购下载的无损 FLAC（mora.flac）。

首先将 decrypted.m4a 与 mora.flac 进行比较：

此处 bitcompare 没有找到差别，证明了下载解密工具本身没有问题，两个来源的音源是一致的。

接下来对比 mora.flac 与 recorded.wav：

注意到 bitcompare 的提示：
Differences found in compared tracks; the tracks became identical after applying offset and truncating first/last samples.
Extra leading/trailing sections contained only null samples.

我们显然不能在内录的时候做到和原曲完全同步，因此 bitcompare 通过对齐和裁剪的方式来忽略掉了前后多余的采样点（事实上全是空的），然后发现中间的部分是完全一致的。
通过如上的对比，我们可以得出结论：**内录是没问题的，解密也是没问题的。**因为可以和 MORA 自购下载的文件对齐每个采样点的数值，如果不是完美解密这根本不可能。

问题专辑

接下来，我们再来对比一下已知有问题的蔡依林「Pleasure」专辑里的 Safari，首先我们使用解密工具下载一版，然后尝试使用 foobar2000 来进行完整性验证：

为了排除发行方对不同渠道的影响，此处从 Tidal 和 Amazon Music HD 也分别购买下载了同一首歌的同音质音频，并进行 bitcompare 测试：

结果是一模一样且无错误的，可以证明并非发行商的问题。

然后参照上述的步骤对这首歌进行内录，然后直接使用 Adobe Audition 与来自 Amazon/Tidal 的音源进行反相相消比较，可以发现右声道似乎出现了一个孤零零的音频信号：

这里就是 Apple 经过内录和 Amazon/Tidal 的音源不同的地方了，此处出现了一个采样值的错误，这个错误很有可能由于解码器的不支持，导致直接丢弃这个数据块，从而从一个采样点的错误衍生到 4096 个采样点的错误（一个 block）。

验证就到这里，**我们可以得出结论：Apple Music 的无损音源确实存在问题，这个问题在内录后依然存在。**出于版权考量，本文不会提供相关的源文件下载，读者可以参考上述的步骤自行实验。

结语

所以从音乐收藏和发布的角度来说，我们可以得出什么结论？

1. Apple Music 的无损音源现在已经不再能和 Amazon 和 Qobuz 一样可信（这应该会给各路喜欢用 Apple Music 搞视听的 HiFi 爱好者一记闷棍），从各路来源获取的时候应该格外谨慎。（实际上真正应该得到的教训是从多个来源交叉验证）
2. 无论来源如何，任何 ALAC 文件，尤其是已被转码为 FLAC 的文件，都应被视为潜在的污染源，尤其是已被转码过的 FLAC 文件，因为在转码完毕后他们的编码错误被掩盖了。
3. 务必优先采用亲手获取、来源清晰的音频。切勿信赖第三方的链接解析站或下载机器人，因为它们分发的文件缺乏来源保证（有的甚至在静默转码到 FLAC 的时候忽略了上述问题），可能继承了原始文件存在的所有风险。
4. 如果你正在使用社区里比较流行的下载实现，请务必把他们提供的完整性验证功能打开（原理实际上和本文是类似的）。在排除了网络、账户等个人因素后，若校验持续失败，则应判定 Apple Music 的官方音源本身已损坏。此时，请果断放弃该来源，以避免收藏或传播有问题的音频。

本文提供的方法与结论仅供参考。此方法可有效识别并排除部分存在问题的专辑，但无法保证通过验证的专辑绝对无误。若您获取了 Apple Music 的 ALAC 音频文件，最可靠的验证方式仍是与其他无损且已知无音频水印与后处理的音源（如通过对比未压缩音轨的 MD5 哈希值）进行交叉比对。在撰写本文时，我对一些文件进行了此类交叉验证，目前尚未发现响度匹配而 MD5 值不同的案例，欢迎评论区补充拍砖。  

附录

以下是速查脚本的源代码，理论上与可以直接下载的版本一致，你可以自行验证与修改：

Windows 批处理脚本

请注意：因为批处理中使用 CHCP 65001 设置了 UTF-8 代码页，请保证你在保存时选择使用 UTF-8 编码。如果你不知道这是什么且在运行的时候遇见了编码错误（比如乱码），请把下列代码中的 CHCP 65001 >NUL 这一行删除。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

@ECHO OFF
SETLOCAL ENABLEDELAYEDEXPANSION

REM https://blog.hanlin.press/2025/09/ALAC-Verification-Guide/
REM --- 脚本初始化 ---
REM 切换到 UTF-8 代码页(65001)以正确显示和处理中文字符
CHCP 65001 >NUL

REM --- 获取当前日期和时间 (格式: YYYY-MM-DD 和 HH-MM-SS)，使用 WMIC 以避免区域设置问题 ---
FOR /F "tokens=2 delims==" %%I IN ('wmic os get LocalDateTime /value') DO SET "dt=%%I"
SET "CURRENT_DATE=%dt:~0,4%-%dt:~4,2%-%dt:~6,2%"
SET "CURRENT_TIME=%dt:~8,2%-%dt:~10,2%-%dt:~12,2%"

REM 定义报告文件的基础名和完整路径
SET "report_basename=ALAC_Scan_Report_%CURRENT_DATE%_%CURRENT_TIME%.txt"
SET "report_file=%~dp0%report_basename%"
SET "temp_log=%TEMP%\ffmpeg_scan_error.log"

REM 初始化计数器
SET /A problem_count=0
SET /A total_files_scanned=0

ECHO.
ECHO =======================================================
ECHO == ALAC 编码问题扫描工具 20250911         ==
ECHO =======================================================
ECHO.

REM --- 环境检查: FFMPEG ---
WHERE ffmpeg >NUL 2>NUL
IF %ERRORLEVEL% NEQ 0 (
    ECHO [错误] 未在您的 PATH 中找到 FFMPEG。
    ECHO 请先安装 FFMPEG 并确保可以从命令行调用它。
    PAUSE
    GOTO :EOF
)

REM --- 准备报告文件 ---
IF EXIST "%report_file%" DEL "%report_file%"
ECHO ALAC 文件扫描报告 > "%report_file%"
ECHO 生成时间: %DATE% %TIME% >> "%report_file%"
ECHO ====================================================== >> "%report_file%"

REM --- 判断执行模式 (拖放或直接运行) ---
IF "%~1"=="" (
    ECHO [模式] 未拖放文件或文件夹，将递归扫描当前目录。
    ECHO.
    CALL :ScanDirectory "."
) ELSE (
    ECHO [模式] 检测到拖放操作，将处理指定的文件或文件夹。
    ECHO.
    FOR %%A IN (%*) DO (
        IF EXIST "%%~A\" (
            CALL :ScanDirectory "%%~A"
        ) ELSE (
            IF /I "%%~xA"==".m4a" (
                 CALL :ProcessFile "%%~A"
            ) ELSE (
                 ECHO [跳过] "%%~nxA" 不是 M4A 文件。
            )
        )
    )
)

REM --- 扫描结束，生成总结 ---
ECHO.
ECHO --------------------------------------------------
ECHO.
ECHO 扫描完成！

ECHO 总共扫描了 !total_files_scanned! 个文件。

SET "summary="
IF %problem_count% == 0 (
    SET "summary=结果: 未发现任何存在编码问题的文件。"
    ECHO !summary!
) ELSE (
    SET "summary=结果: 共发现 !problem_count! 个文件存在编码问题。"
    ECHO !summary!
)

REM 将总结也写入报告文件底部
ECHO. >> "%report_file%"
ECHO ====================================================== >> "%report_file%"
ECHO 扫描总结: >> "%report_file%"
ECHO 总共扫描了 %total_files_scanned% 个 M4A 文件。 >> "%report_file%"
ECHO %summary% >> "%report_file%"
ECHO ====================================================== >> "%report_file%"

:AfterChecksum
ECHO 详细的综合报告已生成:
ECHO "%report_file%"
IF %problem_count% GTR 0 (
    ECHO.
    ECHO 因为发现了问题文件，正在为您自动打开报告...
    START "" "%report_file%"
)

ECHO.
PAUSE
GOTO :EOF


REM --- 子程序: 扫描整个目录 (递归) ---
:ScanDirectory
    SET "target_dir=%~1"
    ECHO --- 正在递归扫描文件夹: "%target_dir%" ---
    FOR /R "%target_dir%" %%F IN (*.m4a) DO (
        CALL :ProcessFile "%%F"
    )
GOTO :EOF


REM --- 子程序: 处理单个文件 ---
:ProcessFile
    SET "current_file=%~1"
    SET /A total_files_scanned+=1
    ECHO.
    ECHO [!total_files_scanned!] 正在检查: "!current_file!"

    REM 核心逻辑: 运行 ffmpeg -i，将所有输出(包括分析和错误)都重定向到临时文件
    ffmpeg -i "!current_file!" -f wav -hide_banner -loglevel info NUL 2> "%temp_log%"
    
    REM 在临时文件中查找指定的错误字符串
    findstr /C:"Invalid data found when processing input" /C:"Not yet implemented in FFmpeg" /C:"Syntax element" /C:"patch welcome" /C:"patches welcome" "%temp_log%" >NUL
    
    ECHO. >> "%report_file%"
    ECHO ---------------------------------------- >> "%report_file%"
    ECHO [文件] "!current_file!" >> "%report_file%"

    IF !ERRORLEVEL! == 0 (
        REM 发现问题
        SET /A problem_count+=1
        ECHO   [状态] 发现问题！
        
        REM --- 将详细错误信息写入报告文件 ---
        ECHO [状态] 发现问题！ >> "%report_file%"
        ECHO [详情] FFmpeg 完整输出: >> "%report_file%"
        TYPE "%temp_log%" >> "%report_file%"
        
    ) ELSE (
        REM 文件正常
        ECHO   [状态] 正常
        ECHO [状态] 正常 >> "%report_file%"

        REM --- 提取音频流信息并输出 ---
        FOR /F "tokens=*" %%L IN ('findstr " Audio:" "%temp_log%"') DO (
            REM 在控制台输出单行分析
            ECHO   [信息] %%L
            REM 将单行分析写入报告
            ECHO [信息] %%L >> "%report_file%"
        )
    )

    REM 清理临时日志文件
    IF EXIST "%temp_log%" DEL "%temp_log%"
GOTO :EOF

Bash 脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

#!/usr/bin/env bash

# https://blog.hanlin.press/2025/09/ALAC-Verification-Guide/
set -o pipefail
export LC_ALL=${LC_ALL:-C.UTF-8}
export LANG=${LANG:-C.UTF-8}
CURRENT_DATE=$(date +%Y-%m-%d)
CURRENT_TIME=$(date +%H-%M-%S)
script_dir=$(cd "$(dirname "$0")" && pwd)
report_basename="ALAC_Scan_Report_${CURRENT_DATE}_${CURRENT_TIME}.txt"
report_file="${script_dir}/${report_basename}"
temp_log=$(mktemp -t ffmpeg_scan_error.XXXXXX.log)

problem_count=0
total_files_scanned=0

echo
echo "======================================================="
echo "== ALAC 编码问题扫描工具 20250911                    =="
echo "======================================================="
echo

if ! command -v ffmpeg >/dev/null 2>&1; then
  echo "[错误] 未在 PATH 中找到 ffmpeg"
  exit 1
fi

: > "$report_file"
{
  echo "ALAC 文件扫描报告"
  echo "生成时间: $(date '+%Y-%m-%d %H:%M:%S')"
  echo "======================================================"
} >> "$report_file"

append_report() {
  printf '%s\n' "$@" >> "$report_file"
}

process_file() {
  local file="$1"
  total_files_scanned=$((total_files_scanned + 1))
  echo
  echo "[$total_files_scanned] 正在检查: \"$file\""
  : > "$temp_log"
  ffmpeg -i "$file" -f wav -hide_banner -loglevel info -y /dev/null 2> "$temp_log"

  if grep -F -e "Invalid data found when processing input" \
             -e "Not yet implemented in FFmpeg" \
             -e "patch welcome" \
             -e "patches welcome" \
             -e "Syntax element" "$temp_log" >/dev/null 2>&1; then
    problem=true
  else
    problem=false
  fi

  append_report ""
  append_report "----------------------------------------"
  append_report "[文件] \"$file\""

  if $problem; then
    problem_count=$((problem_count + 1))
    echo "  [状态] 发现问题！"
    append_report "[状态] 发现问题！"
    append_report "[详情] FFmpeg 完整输出:"
    cat "$temp_log" >> "$report_file"
  else
    echo "  [状态] 正常"
    append_report "[状态] 正常"
    if grep -F " Audio:" "$temp_log" >/dev/null 2>&1; then
      while IFS= read -r line; do
        echo "  [信息] $line"
        append_report "[信息] $line"
      done < <(grep -F " Audio:" "$temp_log")
    fi
  fi
}

scan_directory() {
  local target_dir="$1"
  echo "--- 正在递归扫描文件夹: \"$target_dir\" ---"
  while IFS= read -r -d '' f; do
    process_file "$f"
  done < <(find "$target_dir" -type f -iname '*.m4a' -print0)
}

if [[ $# -eq 0 ]]; then
  echo "[模式] 未提供参数，将递归扫描当前目录。"
  echo
  scan_directory "."
else
  echo "[模式] 检测到传入参数，将处理指定的文件或文件夹。"
  echo
  for path in "$@"; do
    if [[ -d "$path" ]]; then
      scan_directory "$path"
    elif [[ -f "$path" ]]; then
      ext="${path##*.}"
      ext="${ext,,}"
      if [[ "$ext" == "m4a" ]]; then
        process_file "$path"
      else
        echo "[跳过] \"$(basename "$path")\" 不是 M4A 文件。"
      fi
    else
      echo "[跳过] \"$path\" 无法访问。"
    fi
  done
fi

echo
echo "--------------------------------------------------"
echo
echo "扫描完成！"
echo "总共扫描了 $total_files_scanned 个文件。"

if [[ $problem_count -eq 0 ]]; then
  summary="结果: 未发现任何存在编码问题的文件。"
else
  summary="结果: 共发现 $problem_count 个文件存在编码问题。"
fi
echo "$summary"

append_report ""
append_report "======================================================"
append_report "扫描总结:"
append_report "总共扫描了 ${total_files_scanned} 个 M4A 文件。"
append_report "$summary"
append_report "======================================================"

echo "详细的综合报告已生成:"
echo "\"$report_file\""

if [[ $problem_count -gt 0 ]]; then
  if command -v xdg-open >/dev/null 2>&1; then
    xdg-open "$report_file" >/dev/null 2>&1 &
  elif command -v open >/dev/null 2>&1; then
    open "$report_file" >/dev/null 2>&1 &
  fi
fi

rm -f "$temp_log"
echo

PowerShell 7 脚本

由 Nullpointer 提供，支持多线程处理，适合大批量文件的扫描。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

#requires -Version 7.0
param(
  [Parameter(Position = 0)]
  [string[]]$Path
)

Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

if (-not (Get-Command ffmpeg -ErrorAction SilentlyContinue)) {
  Write-Host "[错误] 未在 PATH 中找到 ffmpeg，请先安装。" -ForegroundColor Red
  exit 1
}

function Get-M4AFiles {
  param([string[]]$Paths)

  if (-not $Paths -or @($Paths).Count -eq 0) {
    Write-Host "[模式] 未提供参数，将递归扫描当前目录。"
    return Get-ChildItem -Path '.' -Filter '*.m4a' -File -Recurse -ErrorAction SilentlyContinue
  }

  Write-Host "[模式] 处理指定的文件/文件夹。"
  $list = New-Object System.Collections.Generic.List[System.IO.FileInfo]
  foreach ($p in $Paths) {
    $resolved = (Resolve-Path -LiteralPath $p -ErrorAction SilentlyContinue)?.Path
    if (-not $resolved) { Write-Host "[跳过] 找不到路径：$p"; continue }
    if (Test-Path -LiteralPath $resolved -PathType Container) {
      Get-ChildItem -LiteralPath $resolved -Filter '*.m4a' -File -Recurse -ErrorAction SilentlyContinue |
      ForEach-Object { [void]$list.Add($_) }
    }
    elseif (Test-Path -LiteralPath $resolved -PathType Leaf) {
      if ([IO.Path]::GetExtension($resolved).ToLowerInvariant() -eq '.m4a') {
        [void]$list.Add([IO.FileInfo]$resolved)
      }
      else {
        Write-Host "[跳过] `"$([IO.Path]::GetFileName($resolved))`" 不是 M4A 文件。"
      }
    }
  }
  return $list
}

$targets = @( Get-M4AFiles -Paths $Path | Sort-Object FullName )
if ($targets.Count -eq 0) {
  Write-Host "未找到任何 .m4a 文件。"
  exit 0
}

$stamp = (Get-Date).ToString('yyyy-MM-dd_HH-mm-ss')
$report = Join-Path $PSScriptRoot "ALAC_Scan_Report_$stamp.txt"

$ErrorPatterns = @(
  'Invalid data found when processing input',
  'Not yet implemented in FFmpeg',
  'Syntax element',
  'patch welcome',
  'patches welcome'
)

"ALAC 文件扫描报告" | Out-File -LiteralPath $report -Encoding UTF8
"生成时间: $(Get-Date -Format 'yyyy/MM/dd HH:mm:ss')" | Out-File -LiteralPath $report -Encoding UTF8 -Append
"=====================================================" | Out-File -LiteralPath $report -Encoding UTF8 -Append

$maxParallel = [Math]::Max(2, [Environment]::ProcessorCount)
$total = $targets.Count
$problemCount = 0

Write-Host ""
Write-Host "======================================================="
Write-Host "== ALAC 编码问题扫描工具"
Write-Host "======================================================="
Write-Host ""

$sw = [System.Diagnostics.Stopwatch]::StartNew()

$results = $targets | ForEach-Object -Parallel {
  $filePath = $_.FullName
  $ErrorPatterns = $using:ErrorPatterns
  
  $log = [System.IO.Path]::GetTempFileName()
  try {
    & ffmpeg -v info -hide_banner -i $filePath -f null - 1>$null 2> $log
    $text = if (Test-Path $log) { Get-Content $log -Raw -Encoding UTF8 } else { "" }
    $hasProblem = $false
    foreach ($p in $ErrorPatterns) {
      if ($text -match [Regex]::Escape($p)) { $hasProblem = $true; break }
    }
    $audio = @()
    if ($text) {
      $audio = ($text -split "`r?`n") | Where-Object { $_ -match '\bAudio:' }
    }
    
    $fileName = [System.IO.Path]::GetFileName($filePath)
    Write-Host "处理完成: $fileName" -ForegroundColor Green
    
    [pscustomobject]@{
      File    = $filePath
      Problem = $hasProblem
      Log     = $text
      Audio   = $audio
    }
  }
  finally {
    if (Test-Path $log) { Remove-Item $log -Force -ErrorAction SilentlyContinue }
  }
} -ThrottleLimit $maxParallel

$sw.Stop()

foreach ($r in $results) {
  Add-Content $report ""
  Add-Content $report "----------------------------------------"
  Add-Content $report "[文件] `"$($r.File)`""
  if ($r.Problem) {
    $problemCount++
    Add-Content $report "[状态] 发现问题！"
    Add-Content $report "[详情] FFmpeg 完整输出:"
    Add-Content $report $r.Log
  }
  else {
    Add-Content $report "[状态] 正常"
    foreach ($line in $r.Audio) {
      Add-Content $report "[信息] $line"
    }
  }
}

Add-Content $report ""
Add-Content $report "====================================================="
Add-Content $report "扫描总结:"
Add-Content $report "总共扫描了 $total 个 M4A 文件。"
Add-Content $report ("耗时: {0:N1} 秒" -f $sw.Elapsed.TotalSeconds)
if ($problemCount -eq 0) {
  Add-Content $report "结果: 未发现任何存在编码问题的文件。"
}
else {
  Add-Content $report "结果: 共发现 $problemCount 个文件存在编码问题。"
}

Write-Host ""
Write-Host ("扫描完成！共 {0} 个文件，{1} 个有问题。" -f $total, $problemCount) `
  -ForegroundColor ($problemCount -eq 0 ? 'Green' : 'Yellow')
Write-Host "报告位置：$report"
if ($problemCount -gt 0) {
  Start-Process -FilePath $report
}

导语

「我打包？真的假的」

刚刚落下帷幕的 AOSCC 2025 气氛热烈（尽管从一个广为流传的投票来看，似乎参会的半数以上人都没用过 AOSC），相信通过这次盛会，有更多朋友认识了 AOSC OS——这个以「简明可靠」为目标的社区主导型 Linux 发行版。
作为一个充满活力的开源项目，AOSC OS 的每一点进步都离不开社区成员的热情参与。当你下载安装，并亲身体验了一段时间的 AOSC OS 后，心里或许已经萌生了不少想法：你可能对它活跃的社区支持印象深刻，也可能对某些功能有了自己独特的改进点子，甚至……你已经开始摩拳擦掌，想要亲自为这个“共建”的系统添砖加瓦了！
而在遇见 AOSC OS 之前，你也许已经和许多 Linux 发行版打过交道了——从稳重的 CentOS，到流行的 Ubuntu，再到一滚到底的 Arch Linux。大多数时候，你可能只是默默地作为一名用户，看过了一车车繁杂的交互，淹没在了无尽的邮件列表中。于是来到了 AOSC OS ，当有人提到了**「打包」**这个词后，你的心中或许会产生一些疑问：我能给一个 Linux 发行版贡献软件包，真的假的？

**当然可以！**本篇文章将会从一个不太严谨的角度，介绍一下如何为 AOSC OS 的软件包添砖加瓦。你会发现，只需通过你熟悉的 GitHub，就能轻松参与其中，并亲眼见证自己的代码通过系统更新，被送到每一位用户手中！

本篇由本人入门经历总结而成，希望能为你提供一份友好的实践向导。更全面和权威的信息，推荐随时查阅 AOSC OS 官方维基。

前置知识

参与 AOSC OS 的软件包维护，通常有三条路径：你可以引入一个全新的软件包，为系统拓展功能；可以重构或改进现有软件包，让它变得更好用；当然，你也可以从最常见、最容易上手的更新现有软件包开始。本文将聚焦于最后这一种，它也是感受社区协作、积累贡献经验的绝佳起点。
为了让整个过程更顺利，本篇默认你对 Git 和 GitHub 的基础操作有所了解，已经使用了 AOSC OS 一段时间，具备一定的调试和找代码读日志经验。
并且正如上所说，本文将带你走完一次完整的软件包更新流程，并不会涉及过多的软件包新增重构方面的复杂工作。如果你完成了「新手任务」，可以继续参考更详细的 AOSC OS 软件包样式指南 来了解软件包构建这方面的具体细节。

包从哪里来

核心工作流「主题制」

在动手之前，我们需要先了解一下 AOSC OS 管理软件包的独特方式。
首先我们要明白一点：AOSC OS 目前还没有演进到「有社区共识的第三方库」的阶段，因此你一般情况下不会见到类似 PPA 或是 AUR 这样的第三方软件源。所有的包都来自于 AOSC OS 的官方仓库，用户可以通过系统自带的包管理工具（实际上就是 oma）来安装和更新软件。
AOSC 使用 Monorepo 的方式来管理软件构建，所有软件包的构建脚本和配置文件都集中在一个名为 aosc-os-abbs 的仓库中。

其中，你一点仓库就会看到的 stable 分支就是经过审查的 AOSC OS 稳定源，也是你会从软件源中默认获取到的包。而同仓库的其他分支在 AOSC OS 中被称作主题(topic) 。在 AOSC OS 里，主题是更新、重建或修改一个或多个软件包的独立流程。通过创建不同分支的方式，每个主题可以在分支内独立进行调研、讨论、打包、测试和发布，避免与其他更新相互影响。你可以在目前还是英文的AOSC OS 主题制维护指南了解更多细节。

如果你是最终用户，可以通过 oma topics 命令来查看当前可用的测试源主题，并且可以选择性地加入测试，提前尝鲜，并帮助开发者发现问题。（注意：要使用测试源，请保证你的 oma mirrors 选项中包含了至少一个主仓库 AOSC main repository ）

1
2
3
4
5
6
7
8
9
10
11
12

root@jerry-aosc-vmware [ ~ ] # oma topics
? 打开测试源以获取实验性更新，关闭测试源以回滚到稳定版本：
    cmake: update to 4.0.3 (cmake-4.0.3)
    ······
    rocm: add new subpackage (rocm-641-add-package)
    ······
    [PREVIEW] Python 3.14 (python-3.14)
    ······
    f3d: new, 3.0.0 (f3d-new)
    AVR Survey (May, 2025) (avr-survey-20250512)
▼   photils-cli: new, 0.4.1 (photils-new)
按 [Space]/[Enter] 切换开关状态，按 [Esc] 应用更改，按 [Ctrl-c] 退出。

而作为开发者如何进行主题制维护，我们将在后续章节中详细介绍。

寻找更新

除了 GitHub 外，你还可以在 https://packages.aosc.io/ 查看目前 AOSC OS 的所有软件包。首页显示了最近被推送到 stable 分支的包更新，点击某个包名可以查看该包的详细信息。在右上角可进行软件包搜索，在下方 Repositories 列表可以按架构查看包的列表。
当然，这肯定是个工具站，仅适用于你明确了想更新哪个软件包的情况下搜索使用。
那么，如果你只是想随便看看，当当扫地机器人，有没有哪个站提供了上游更新的信息呢？
有的有的，请转到 https://anicca.aosc.io/ ，这里会给出由 aosc-findupdate 工具自动生成的 AOSC OS 包更新列表。你可以在这里查看到所有包的最新版本信息，来找找有没有你感兴趣的更新。
注意看 Warnings 里的 Compliance mode enabled，这代表了版本号可能会被合规处理过。根据样式指南，有些来自上游的版本号可能需要进行修改以符合规范，具体的规则我们之后介绍。

善其事，利其器

现在可以把手里的 AOSC OS 终端开起来了，我们将在本节中介绍软件包维护中通常会接触到的工具。
根据 软件包维护入门：基础教程 的介绍，我们可以获知：在软件包维护的过程中总共需要和下面三个工具打交道：

• Ciel
  • 用于管理独立的 AOSC OS 构建环境（systemd-nspawn(1) 容器）。
• ACBS
  • 用于管理软件包树（如主树 https://github.com/AOSC-Dev/aosc-os-abbs）及各类构建配置。
  • 运行时，调用 Autobuild 读取软件包构建配置并执行构建脚本。
• Autobuild
  • 用于读取软件包构建配置并执行构建脚本。

通常而言，从打包者的角度来说你只需要接触第一个 Ciel 工具，因为后续的 Autobuild 和 ACBS 都会在 Ciel 的调度下在容器中运行。

在你开始软件包维护之前，请**务必确保你已经通过各种妙妙的方式，保证你的 AOSC OS 到国际的互联不会产生什么太大的问题。**从 AOSC OS 的基础 tarball 镜像、到基于 GitHub 的 abbs 仓库，甚至于软件包构建过程中访问外部代码包，都需要顺畅的国际互联支持，本方面点到为止。

在你配置好自己的网络环境或是确保自己的互联不会出现问题后，请通过 sudo -i 等方式进入 root 用户，然后通过 oma 安装 ciel ：

1

oma install ciel

然后找一个地方创建一个专门的目录作为 ciel 的工作目录，比如 ~/ciel ，然后在该目录下运行 ciel new 以创建一个新的构建环境。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

root@jerry-aosc-vmware [ ~ ] # mkdir ~/ciel/
root@jerry-aosc-vmware [ ~ ] # cd ciel/
root@jerry-aosc-vmware [ ciel ] # ciel new
info: Welcome to ciel!
info: Before continuing, I need to ask you a few questions:
✔ Target Architecture · mainline: amd64
✔ Maintainer Information · abc1763613206 <wowjerry@aosc.io>
✔ Enable DNSSEC · no
✔ Edit sources.list · no
✔ Enable local sources caching · yes
✔ Enable local packages repository · yes
✔ Use different OUTPUT dir for different branches · yes
✔ Use volatile mode for filesystem operations · no
info: Ciel now uses oma as the default package manager for base system updating tasks.
info: You can choose whether to use oma instead of apt while configuring.
✔ Use apt as package manager · no
✔ Do you want to add a new instance now? · yes
✔ Name of the instance · main
info: Understood. `main` will be created after initialization is finished.
info: Initializing workspace...
info: Initializing container OS...

Target Architecture 请根据自己的实际情况选择合适的架构，比如 amd64 或 arm64。
然后是该环境的维护者信息，照前面的格式填写即可。实际上现在 AOSC OS 采用 BuildIt! 全自动构建，分发到软件源的包并不会在你的环境上被构建，所以此处填其他的问题也不算太大。
其他选项保持默认即可，但请注意在 Do you want to add a new instance now? 这个问题上选择 yes，并为实例命名，比如 main。

如果你很不幸网络条件不佳，可能会在如下的地方卡住或是速度极慢：

1
2
3

info: Searching for latest AOSC OS buildkit release...
info: Ciel has picked buildkit for amd64, released on 20250606
info: Downloading base OS rootfs...

ciel 允许你使用 --from-tarball 的选项来让你从一个第三方源加载 AOSC OS 的根文件系统镜像。
如果你卡得受不了，就可以考虑利用国内开源镜像站的镜像来加速下载了**（尽管如此，我还是建议你在进行如下的步骤之前配置好相关的网络工具）**。
观察如上的 info ，然后来拼出一个 tarball 地址：

1
2
3
4
5

# 比方说这里是 amd64 的 20250606 ，就可以直接使用下面的链接
# 如果修改架构的话，注意需要修改两处地方，注意最终的格式须为 squashfs
https://mirrors.cernet.edu.cn/anthon/aosc-os/os-amd64/buildkit/aosc-os_buildkit_20250606_amd64.squashfs
# 如果 MirrorZ 给你分配的镜像站表现过差，也可以考虑直接指定一个
# https://mirrors.bfsu.edu.cn/anthon/aosc-os/os-amd64/buildkit/aosc-os_buildkit_20250606_amd64.squashfs

然后，将下得极慢的进程给 Ctrl-C 终止掉，删掉整个文件夹里的内容（ciel 在初始化不完整时会报错，恢复空白环境可以规避掉一些问题）。
然后重新运行 ciel new ，这次加上 --from-tarball 选项，并将上面的 tarball 地址粘贴进去，此时会跳过让你选择架构的过程，直接下载：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

root@jerry-aosc-vmware [ ciel ] # rm -rf .ciel * 
root@jerry-aosc-vmware [ ciel ] # ciel new --from-tarball https://mirrors.cernet.edu.cn/anthon/aosc-os/os-amd64/buildkit/aosc-os_buildkit_20250606_amd64.squashfs
info: Welcome to ciel!
info: Before continuing, I need to ask you a few questions:
✔ Maintainer Information · abc1763613206 <wowjerry@aosc.io>
······
✔ Do you want to add a new instance now? · yes
✔ Name of the instance · main
info: Understood. `main` will be created after initialization is finished.
info: Initializing workspace...
info: Initializing container OS...
info: Using custom squashfs from https://mirrors.cernet.edu.cn/anthon/aosc-os/os-amd64/buildkit/aosc-os_buildkit_20250606_amd64.squashfs
info: Downloading base OS rootfs...
info: Initializing ABBS tree...                                                                                                                                                                              
info: Applying configurations...                                                                                                                                                                             
info: Configurations applied.
info: Setting up local repository ...
info: Scanning 0 packages...

info: Local repository ready.
info: main: instance initialized.
info: main: filesystem mounted.
info: Scanning 0 packages...

info: main: local repository initialized.

在工作区配置完成后，请首先运行 ciel update-os 来尽可能地更新容器内的系统环境，否则以后在每次构建时都要更新一遍，浪费时间。

1
2
3
4
5
6
7

root@jerry-aosc-vmware [ ciel ] # ciel update-os
info: Updating base OS...
info: update-ce9206ea: instance created.
info: update-ce9206ea: filesystem mounted.
info: update-ce9206ea-7ec908fe: waiting for container to start...
info: update-ce9206ea-7ec908fe: setting up mounts...
     INFO Refreshing local database ...

接下来，你就可以使用 ciel build -i main 来构建软件包了，可以像官方 Wiki 那样，打一个 flac 包试一试：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

root@jerry-aosc-vmware [ ciel ] # ciel build -i main flac
······
[INFO]:  Archiving package(s) ...
[INFO]:  Using abpm_aosc_archive as autobuild archiver ...
'flac_1.5.0-0_amd64.deb' -> '/debs/f/flac_1.5.0-0_amd64.deb'
'flac-dbg_1.5.0-0_amd64.deb' -> '/debs/f/flac-dbg_1.5.0-0_amd64.deb'
[INFO]: Asking ciel to refresh repository...
[INFO]: Waiting for ciel to refresh repository...
info: Scanning 2 packages...
..
[INFO]: Ciel finished refreshing repository...

========================================
    ACBS Build Successful
========================================

Package(s) built:
flac (amd64 @ 1.5.0-0)                  0:00:34.624463

info: main: stopping...
info: main: instance stopped.
info: main: filesystem un-mounted.
info: main: mount point removed.
info: main: rolling back instance...
info: main: instance has been rolled back.                                                                                                                                                                   
BUILD SUCCESSFUL - 1 packages in 00:00:51

通常而言，看到了 ACBS Build Successful ，就说明构建过程没有问题，可以找到生成的包了。
因为我们没有切换分支，所以我们此时构建的包在 OUTPUT-stable 目录下，具体到 flac 包就是 OUTPUT-stable/debs/f/flac_1.5.0-0_amd64.deb 。
你可以使用 oma install 命令来亲手试用这个包：

1

oma install OUTPUT-stable/debs/f/flac_1.5.0-0_amd64.deb

小试牛刀

第一个主题

在上一章中，我们已经搭建好了名为 ciel 的工作间，完成了一些说大不大说小不小的准备工作，现在是时候把它投入使用了。
请注意，本节的流程是为首次贡献的朋友们设计的。当你成功提交代码并成为社区贡献者后，部分操作会变得更加简化，我们到时再谈。

使用 ls 命令查看当前目录，通常你现在看到的会类似这样：

1
2

root@jerry-aosc-vmware [ ciel ] # ls
aosc-os_buildkit_20250606_amd64.squashfs  CACHE  OUTPUT-stable  SRCS  TREE

注意看那个 TREE 目录，它就是之前我们提到的 aosc-os-abbs，也就是存放构建配置的主仓库。
作为 Newcomer 我们自然还没有向这个仓库推送的权限，因此先去 https://github.com/AOSC-Dev/aosc-os-abbs/fork ，创建一个自己的 Fork ，比如说我的创建后就是 https://github.com/abc1763613206/aosc-os-abbs。

然后 cd 到 TREE 目录下，把 origin 暂时指向到自己的 Fork （当然你如果精通 Git 操作的话，形式上创建一个 upstream 是一个更好的实践）：

1
2
3

root@jerry-aosc-vmware [ ciel ] # cd TREE
root@jerry-aosc-vmware [ TREE@stable ] # git remote set-url origin https://github.com/abc1763613206/aosc-os-abbs.git
root@jerry-aosc-vmware [ TREE@stable ] # git pull # 更新本地代码

然后就可以挑选包了！我们以写稿时挂在 Anicca 首页的 7-zip 为例：

7-zip

可以看到，7-zip 的目录是 app-utils ，当前仓库里的版本是 25.00 ，但是最新版来到了 25.01。
确定了目标，我们就可以在「主题制」维护机制下，亲手创建属于自己的第一个主题了。
正如上所说，主题是更新、重建或修改一个或多个软件包的独立流程。参考 AOSC OS 主题制维护指南 ，我们可以总结出如下的主题（对应到 Git 中也就是分支）命名规则：

• 更新：$PKGNAME-$PKGVER（如 nano-5.4）。
• 非更新（PURPOSE 说明意图）：$PKGNAME-$PKGVER-$PURPOSE（如 gnome-shell-3.38.1-build-fix）。

还有个复杂的例外：如果一次主题涉及多个软件包、多个版本，并且这些软件包之间没有明确的主从关系或统一版本号时，主题名将使用主包名（或统称）+ -survey + 日期，例如：rime-data-survey-20200928。
你可以回到之前那一段，看看 oma topics 的输出，来验证分别属于哪种类型。

对应到我们这个例子，我们要创建的主题名就是 7-zip-25.01。
进入到 TREE 目录，使用 git checkout -b 7-zip-25.01 创建一个新的分支，然后开工！

1
2
3
4

root@jerry-aosc-vmware [ ciel ] # cd TREE
root@jerry-aosc-vmware [ TREE@stable ] # git checkout -b 7-zip-25.01
切换到一个新分支 '7-zip-25.01'
root@jerry-aosc-vmware [ TREE@7-zip-25.01 ] # 

检包、拆包

进入到 TREE ，这个包处在 app-utils/7-zip 目录下，用 tree 命令看一眼这个文件夹的架构：

1
2
3
4
5
6
7
8

root@jerry-aosc-vmware [ TREE@7-zip-25.01 ] # tree app-utils/7-zip/
app-utils/7-zip/
├── autobuild
│   ├── build
│   ├── defines
│   └── patches
│       └── 0001-fix-CPP-missing-predefined-compiler-flags.patch
└── spec

通常而言，这个包就代表了大部分最简软件包的架构（当然了，有些顺风顺水的软件包连补丁 patches 文件夹都没有）。
对于软件包的全部细节，请直接参照 AOSC OS 软件包样式指南 ，事实上在打包的全流程中，你应该把这个指南作为参考，在遇到问题时查阅，未覆盖的地方再求助于社区。

我们以实践出真知的精神，来具体看看包里都有啥。

spec

对于 7-zip 而言，spec 文件的内容长这样：

1
2
3
4

VER=25.00
SRCS="git::commit=tags/$VER::https://github.com/ip7z/7zip"
CHKSUMS="SKIP"
CHKUPDATE="anitya::id=17875"

虽然略显简陋，但是构成软件包的必要信息都在这里了。
第一行的 VER 变量定义了软件包的版本号，然后 SRCS 变量定义了软件包的源代码上游，CHKSUMS 变量定义了软件包的校验值，CHKUPDATE 变量定义了软件包的更新来源。
CHKUPDATE 变量是用于给 Anicca 这类工具提供更新信息的，仅在新增软件包时会用到，通常情况下你不需要修改它。我们重点说一下其他三个。

首先是 VER 变量，在 AOSC OS 的软件包中 VER 直接指向软件包的版本号，这就带来了几个问题：

1. 之前说过的 Compliance mode enabled 怎么回事？
   请参考 AOSC OS 软件包样式指南 里的「软件包版本」一节。通常而言，当上游的版本号只带有半角句号时，可以直接被使用；如果上游的版本号带有其他符号（如 + 或 _ 等），则需要进行规范化处理。具体参见样式指南里的表格。
2. 如果一个软件包里复合了多个上游软件包，或者说被规范化后的版本号无法直接被下面的 SRCS 变量所使用，怎么办？
   SRCS 不一定非要引用 VER 变量，实际上你可以按需要在 spec 文件中定义任意多个变量来满足你的需求。比如对 lang-golang/go 软件包而言，它复合了多个上游软件包，版本号也比较复杂，因此它的 spec 文件变成了这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

UPSTREAM_VER=1.24.2
# Versions of Golang, net library and Go tools
GO_VER=${UPSTREAM_VER/\~/}
TOOLS_VER=0.31.0
NET_VER=0.38.0
REL=3

VER="${UPSTREAM_VER}+tools${TOOLS_VER}+net${NET_VER}"
SRCS="tbl::https://go.dev/dl/go${GO_VER}.src.tar.gz \
      git::commit=tags/v${TOOLS_VER};rename=tools::https://go.googlesource.com/tools \
      git::commit=tags/v${NET_VER};rename=net::https://github.com/golang/net"
CHKSUMS="sha256::9dc77ffadc16d837a1bf32d99c624cb4df0647cee7b119edd9e7b1bcc05f2e00 \
         SKIP \
         SKIP"
CHKUPDATE="anitya::id=1227"
SUBDIR="go"

它目前的软件包版本为 1.24.2+tools0.31.0+net0.38.0 ，使用 + 符号复合了不同的来源，在 SRCS 里的不同来源也引用了不同变量。

而 SRCS 可在 ACBS - Specification Files 文档中查看详情，我们和下面的 CHKSUMS 一起看。
源码的来源一般分为两种情况：

• 来源于基于 Git 的代码仓库，使用 git::commit=tags/xxx::https://github.com/xxx/xxx 这种形式，这种情况下 CHKSUMS 变量请使用 SKIP。
• 来源于基于 tarball 的代码包，使用 tbl::https://xxx/xxx.tar.gz 这种形式，这种情况下 CHKSUMS 变量需要提供一个校验值，比如说 SHA256。

如果是复合引用的软件包，你通常需要对其他来源进行重命名，这时请在 SRCS 里使用 rename 选项。
此时，你通常可能需要显式指定一个子目录作为构建的主目录，使得 build 构建工作流能够进入正确的文件夹发起构建，此时请在 spec 文件中使用 SUBDIR 变量来指定目录。
在如上的 lang-golang 包中，因为有多个上游复合，所以显式指定了 SUBDIR="go" 。这里的指定需要根据不同包的情况灵活变通，通常需要自己打开相关 tarball 查看具体的结构，例如在 nginx 中，这里的值就变成了 SUBDIR="nginx-$NGINX_VER" 。如果你的源码包只有单个/零个文件夹且没有复合来源的情况，你通常不需要考虑这个值。

除此之外，还有一个如上 spec 文件中没有体现，但仍需要重点说明的变量：REL 。

REL 变量定义了软件包的修订号，该变量用于处理上游软件包未发生改变，但是在 AOSC OS 生态中需要进行修订的情况（通常是之前适配出现了 BUG 或者应急响应其他补丁）。此变量的默认值为 0，在主版本 (VER) 不变的情况下，每次修订应为该值递增 1。当软件包的主版本（VER）发生变化时，REL 变量应重置为 0，体现在实践中时，你应当直接把含有 REL 变量的行删除。

比如这是一个 ninja 的更新：

1
2
3
4
5
6

- VER=1.12.1
+ VER=1.13.1
SRCS="git::commit=tags/v$VER::https://github.com/ninja-build/ninja"
CHKSUMS="SKIP"
CHKUPDATE="anitya::id=2089"
- REL=1

回到 7-zip 包的 spec 文件，很幸运我们并不需要处理如上大部分复杂的操作，也不存在需要我们删除的 REL 行，所以直接修改一下版本号即可。

1
2
3
4
5

- VER=25.00
+ VER=25.01
SRCS="git::commit=tags/$VER::https://github.com/ip7z/7zip"
CHKSUMS="SKIP"
CHKUPDATE="anitya::id=17875"

autobuild

我们已经仔细研究了软件包的「身份证」 spec，现在，让我们来参观一下它的「引擎室」—— autobuild 目录。这个目录里的文件，共同决定了软件包是如何从一堆源代码，被 Autobuild 一步步加工成可安装文件的。
不过，在开始导览前，请先松一口气：对于大多数常规的版本更新，这个目录里的文件你可能一个字都不用改。 我们即将采用的策略是「先信任，后验证」——首先假设现有的构建流程在新版本上依然有效，只有在后续构建失败时，我们才需要回到这里来排查问题。
首先是 defines 文件，该文件定义软件包的各项核心配置。

1
2
3
4

PKGNAME=7-zip
PKGSEC=utils
PKGDEP="gcc-runtime glibc"
PKGDES="A file archive manager with support for multiple formats"

该文件详细的定义请参考 Wiki 上的入门教程 文档。
通常对于软件包维护更新而言，我们需要关注的是软件包的依赖关系在更新后有没有发生变化，分为构建依赖 BUILDDEP 和运行时依赖 PKGDEP，其中前者是仅在构建过程中需要的。你可以在样式指南查看更多细节，但对于软件包更新而言，一个比较符合直觉的工作流是：通过之后构建时的表现以及最后运行时的测试来验证这些依赖关系是否仍然有效，是否需要添加新的依赖。

patches 目录下存放了软件包的补丁文件，通常用于修复上游代码中的问题或适配 AOSC OS 的特定需求。对于 7-zip 包而言，我们可以看到一个名为 0001-fix-CPP-missing-predefined-compiler-flags.patch 的补丁文件，这个补丁是为了修复编译器预定义标志缺失的问题。
patches 目录下的补丁文件请带序号依次保存，具体制作补丁的方式请参考 AOSC OS 软件包样式指南 。通常而言，建议补丁文件的命名应符合下面的格式：

1

NNNN-$CATEGORY-$CONTENT.patch

其中：

• NNNN 与前面的示例补丁名称一样，是用于为补丁排序的“序列号”。
• $CATEGORY 定义了补丁的类别，例如 bugfix、feature 等。
• $CONTENT 定义了补丁的作用，例如 fix-build-with-openssl-1.1。

当然，在软件包更新中，我们经常会遇到因为软件包代码段更新而导致补丁失效的情况。这时，我们需要根据实际情况对补丁进行调整，确保其能够正确应用。
具体而言，你可以拉取下对应的 Git 仓库，参考现有的 patch 文件人工完成相应的修改，然后使用类似 git diff > xxx.patch 的命令生成新的补丁文件。对于有补丁的软件包而言，这是更新过程中经常会遇到的情况。

build 文件定义了软件包构建的具体细节，它被 Autobuild 读取并执行，你可以在Wiki 上的进阶教程中获取一些细节。

1
2
3
4
5
6
7

abinfo "Building 7-zip ..."
cd "${SRCDIR}/CPP/7zip/Bundles/Alone2"
make -f ../../cmpl_gcc.mak

abinfo "Installing 7-zip ..."
install -v -Dm755 "${SRCDIR}/CPP/7zip/Bundles/Alone2/b/g/7zz" "${PKGDIR}/usr/bin/7zz"
install -v -Dm644 "${SRCDIR}/DOC/"* -t "${PKGDIR}/usr/share/doc/${PKGNAME}"

此外，还可能会出现构建前会运行的 prepare 文件，用于初始化一些构建环境；构建后会运行的 beyond 文件，用于打扫一下构建现场。还可能会出现一个 overrides 文件夹，该文件夹存放了一些源代码中不存在，但是对最终软件包有用的文件，通常是一些安装到桌面的文件和预设配置，你可以在 Wiki 上的进阶教程中获取一些细节。

但通常如上文所说，对于大多数软件包的常规更新，autobuild 目录中的配置都相对稳定。因此在实际操作中，我们不必过早陷入 autobuild 目录的全部细节。对于绝大多数增量更新，首要的策略是仅修改 spec 文件中的版本号（VER）与校验和（CHKSUMS），然后大胆尝试构建。除非遇到涉及底层重构的重大版本更迭，否则构建脚本通常能平稳运行。只有当构建失败或是后续测试出现问题时，才有必要回过头来，依据错误信息深入排查 autobuild 目录中的具体配置。

构建一下试试？

我们可以在 ciel 文件夹下的任意目录，使用 ciel build -i main 7-zip 来尝试构建一下我们更新的 7-zip 包：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

root@jerry-aosc-vmware [ TREE@7-zip-25.01 ] # ciel build -i main 7-zip
······
[INFO]:  Using free-formed build script
[INFO]:  Applying patch 0001-fix-CPP-missing-predefined-compiler-flags.patch ...
patching file CPP/7zip/7zip_gcc.mak
······
========================================
    ACBS Build Successful
========================================

Package(s) built:
7-zip (amd64 @ 25.01-0)                 0:00:37.503451

info: main: stopping...
info: main: instance stopped.
info: main: filesystem un-mounted.
info: main: mount point removed.
info: main: rolling back instance...
info: main: instance has been rolled back.
BUILD SUCCESSFUL - 1 packages in 00:00:53

可以看到，这里的构建过程顺利完成，没有遇到任何问题。
而如果你看到的不是 Build Successful 的信息，那就要专门看一眼日志了。

比如在更新软件包时最常出现的补丁失效情况，本着实验的精神，我们来故意破坏一下 7-zip 目录下的那个补丁，然后重新运行构建：
构建自然会失败，然后你往上翻一翻日志会看见这一段：

1
2
3
4
5
6
7
8
9
10
11

[INFO]:  Applying patch 0001-fix-CPP-missing-predefined-compiler-flags.patch ...
patching file CPP/7zip/7zip_gcc.mak
Hunk #1 FAILED at 44.
1 out of 4 hunks FAILED -- saving rejects to file CPP/7zip/7zip_gcc.mak.rej
In file included from /usr/bin/autobuild:13
                 from /usr/lib/autobuild4/proc/40-patch.sh:23
/usr/lib/autobuild4/lib/builtin.sh:17: In function `ab_apply_patches':
/usr/lib/autobuild4/lib/builtin.sh:17: error: command exited with 1
   16 |                         abinfo "Applying patch $(basename "$i") ..."
>  17 |                         patch "${PATCHFLAGS[@]}" -i "$i" || abdie "Applying patch $i failed"
   18 |                 fi

这段日志就具体地告诉了我们哪个补丁应用失败，这时我们就要结合具体情况，考虑人工修改补丁或是重做补丁。
当然这里是我们人工破坏的，玩够了还原回去就好。

重新构建完成后回到 ciel 的根工作目录，我们会发现现在变成了这样：

1
2

root@jerry-aosc-vmware [ ciel ] # ls
aosc-os_buildkit_20250606_amd64.squashfs  CACHE  OUTPUT-7-zip-25.01  OUTPUT-stable  SRCS  STATES  TREE

可以看到，输出目录多出来了个以主题名命名的 OUTPUT-7-zip-25.01 目录，这个目录下存放了我们刚刚构建的 7-zip 包：

1
2
3
4
5
6
7
8
9
10
11

root@jerry-aosc-vmware [ ciel ] # tree OUTPUT-7-zip-25.01/
OUTPUT-7-zip-25.01/
└── debs
    ├── 7
    │   ├── 7-zip_25.01-0~pre20250807T182427Z~dirty_amd64.deb
    │   ├── 7-zip-dbg_25.01-0~pre20250807T182427Z~dirty_amd64.deb
    ├── fresh.lock
    ├── Packages
    └── Release

3 directories, 7 files

具体到这个软件包，我们可以使用 oma install 来安装它：

1

oma install OUTPUT-7-zip-25.01/debs/7/7-zip_25.01-0~pre20250807T182427Z~dirty_amd64.deb

接着，我们就可以对软件包进行基础的功能测试了，具体到 7-zip 这个包，我们可以直接使用它自带的 7zz b 来首先跑一个 Benchmark：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

root@jerry-aosc-vmware [ ciel ] # 7zz b

7-Zip (z) 25.01 (x64) : Copyright (c) 1999-2025 Igor Pavlov : 2025-08-03
 64-bit locale=zh_CN.UTF-8 Threads:128 OPEN_MAX:1024

Compiler:  ver:14.3.0 20250523 (AOSC OS, Core) GCC 14.3.0 : SSE2
Linux : 6.14.11-aosc-main : #1 SMP PREEMPT_DYNAMIC Tue Jul 22 02:28:29 UTC 2025 : x86_64 : VMwareVMware :  : 0.0.0.0.0.0
PageSize:4KB THP:always hwcap:2 hwcap2:2
12th Gen Intel(R) Core(TM) i7-12700H
(906A3)

1T CPU Freq (MHz):  3992  4019  3887  3878  3861  3891  3874
2T CPU Freq (MHz): 200% 3869   199% 3885  
4T CPU Freq (MHz): 362% 3497   357% 3502  

RAM size:    3690 MB,  # CPU hardware threads:   4 / 128 : 0000000000000000000000000000000F
RAM usage:    889 MB,  # Benchmark threads:      4

                       Compressing  |                  Decompressing
Dict     Speed Usage    R/U Rating  |      Speed Usage    R/U Rating
         KiB/s     %   MIPS   MIPS  |      KiB/s     %   MIPS   MIPS

22:      28211   356   7708  27445  |     187602   370   4321  16005
23:      20539   320   6546  20928  |     182650   374   4231  15804
24:      16914   296   6141  18187  |     165834   364   4002  14553
25:      15152   307   5629  17300  |     160144   351   4061  14253
----------------------------------  | ------------------------------
Avr:     20204   320   6506  20965  |     174058   365   4154  15154
Tot:             342   5330  18059

测试压缩操作，也没有问题：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

root@jerry-aosc-vmware [ ciel ] # 7zz a 7zip.7z OUTPUT-7-zip-25.01/

7-Zip (z) 25.01 (x64) : Copyright (c) 1999-2025 Igor Pavlov : 2025-08-03
 64-bit locale=zh_CN.UTF-8 Threads:128 OPEN_MAX:1024

Scanning the drive:
3 folders, 8 files, 21114503 bytes (21 MiB)

Creating archive: 7zip.7z

Add new data to archive: 3 folders, 8 files, 21114503 bytes (21 MiB)

                                                                                        
Files read from disk: 8
Archive size: 11040172 bytes (11 MiB)
Everything is Ok

版本也确实是更新后的 25.01 ，本地的测试没有问题，就可以准备发起 PR 了。

发起贡献

在发起构建之前，首先需要了解一下 AOSC OS 中的 Commit 规范：Commit 面向最终用户，通常情况下对于同一个包的所有更改应该在同一条 Commit 中完成。
你可以在 软件包样式指南 中找到所有的规范，Commit 的消息通常遵从 <包名>: <动词短语> [附加说明] [; #<issue号>] 的格式，最常用的如下：

• 引入新包：$PKGNAME: new, $PKGVER，比如 cherry-studio: new, 1.5.2
• 版本更新：
  • 普通更新：$PKGNAME: update to $PKGVER，比如 7-zip: update to 25.01
  • 安全更新：$PKGNAME: update to $PKGVER; #NNN，比如 7-zip: update to 25.00; #11761，其中 #NNN 是对应安全通告的 issue 编号。
• 软件包改动：$PKGNAME: $PURPOSE，通常这种情况下之前说过的 REL 也要递增。

如果你的 Commit 干了不止跳版本的一件事，你可以在 Commit 中换行，分条详细说明，参见软件包样式指南。

具体到我们这个例子，我们直接添加所有改动，使用 7-zip: update to 25.01 作为 Commit，然后推送即可：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

root@jerry-aosc-vmware [ TREE@7-zip-25.01 ] # git add .
root@jerry-aosc-vmware [ TREE@7-zip-25.01 ] # git status
位于分支 7-zip-25.01
要提交的变更：
  （使用 "git restore --staged <文件>..." 以取消暂存）
        修改：     app-utils/7-zip/spec
root@jerry-aosc-vmware [ TREE@7-zip-25.01 ] # git commit -m "7-zip: update to 25.01"
[7-zip-25.01 aaa13645db] 7-zip: update to 25.01
 1 file changed, 1 insertion(+), 1 deletion(-)
root@jerry-aosc-vmware [ TREE@7-zip-25.01 ] # git push
致命错误：当前分支 7-zip-25.01 没有对应的上游分支。
为推送当前分支并建立与远程上游的跟踪，使用

    git push --set-upstream origin 7-zip-25.01

为了让没有追踪上游的分支自动配置，参见 'git help config' 中的 push.autoSetupRemote。
root@jerry-aosc-vmware [ TREE@7-zip-25.01 ] ! git push --set-upstream origin 7-zip-25.01
枚举对象中: 9, 完成.
对象计数中: 100% (9/9), 完成.
使用 4 个线程进行压缩
压缩对象中: 100% (5/5), 完成.
写入对象中: 100% (5/5), 452 字节 | 452.00 KiB/s, 完成.
总共 5（差异 3），复用 0（差异 0），包复用 0（来自  0 个包）
remote: Resolving deltas: 100% (3/3), completed with 3 local objects.
remote:
remote: Create a pull request for '7-zip-25.01' on GitHub by visiting:
remote:      https://github.com/abc1763613206/aosc-os-abbs/pull/new/7-zip-25.01
remote:
To https://github.com/abc1763613206/aosc-os-abbs.git
 * [new branch]            7-zip-25.01 -> 7-zip-25.01
分支 '7-zip-25.01' 设置为跟踪 'origin/7-zip-25.01'。

之后，你就可以回到 GitHub ，参照模板创建一个 Pull Request 了。
在本例之中，模板填写完了长这样：

从这一步之后，你就可以来到 AOSC OS 现有的社区群组 ，发送自己的 Pull Request 链接，来等待贡献者们进行 Review 。
很快，审阅者会为你触发一系列 CI，以验证你的软件包在所有支持的设备架构上都能成功构建。有时，他们可能也会请你在本地环境中进行一些额外的测试（譬如执行类似 oma topics --opt-in 的命令来测试你的包在测试源上的构建表现）。请将你的测试结果以评论的形式回复在 PR 中，并与审阅者保持积极沟通，直到所有的检查项都顺利通过，让下面的 checks 绿起来：

All checks have passed

从这一刻起，你将从「闭门造车」转向与社区的协同合作。请记住，这并非一场考试，而是一次开放、平等的技术交流。你需要与审阅者积极互动，清晰地解释你的修改思路，回答他们的问题，并根据收到的反馈进行调整。有效的沟通是保证贡献能被顺利合入的关键。

最终，在与审阅者达成共识后，你的 PR 将被合并。你亲手更新的 7-zip 软件包，将很快通过软件源分发到成千上万的用户手中。

在这一刻，你不仅完成了一次版本更新，更成为了 AOSC OS 开源社区的一名贡献者。恭喜你，欢迎加入！

Final Checklist

打包的旅程并非一帆风顺，以下是你在打包过程中可能会遇到的一些情况，在打包提交之前不妨先来看看：

和一条 Commit 打架

前文已经提到，AOSC OS 的 Commit 规范要求每个软件包的更新都应在一条 Commit 中完成。这就自然而然带来两个问题：

1. 我如果已经提交了多个 Commit，如何合并成一条？

• 一个比较文明的方式是使用 git rebase -i 命令，进入交互式变基模式，然后把所有 Commit 都改成 squash（缩写为 s），然后保存并退出，会弹出另一个编辑器让你修改合并后的 commit message。
  不过这种方式不太适合你本地还有未提交的更改的情况，就通常的 AOSC OS 仓库维护实践而言，我推荐你使用一个不太文明但是简便的方法：
• 直接使用 git reset --soft HEAD~N 命令（其中 N 是你想要回退的 Commit 数量），然后使用 git commit -a -m "Commit message" 来重新提交所有更改。这样就可以把多个 Commit 合并成一条了。--soft 的选项代表回退到指定的 Commit，但保留所有更改在暂存区中。

不管你执行了哪种操作，都别忘了使用 git push -f 来强制推送你的更改。

2. 审阅者指出了我的错误，我该如何修改上一条提交过的 Commit？

• 如果您仅需要修改 Commit 的消息内容，可以直接使用 git commit --amend -m "New commit message" 命令来修改最后一次提交的消息。如果您去掉 -m 选项，Git 会打开一个编辑器，让您修改消息内容。
• 但您如果想修改文件内容，请直接在工作区进行修改，然后直接使用 git add . 来将修改添加到暂存区，最后使用 git commit --amend 来更新这个 Commit。 同样这次会打开一个编辑器，让您修改 Commit 的消息，如果不需要修改消息，可以直接保存并退出，此时修改就会合并到这个 Commit 中。（附加上 --no-edit 选项可以跳过编辑器）
• 需要修改更早之前的 Commit 涉及到了 rebase 变基，请自行在网络上查找相关资料。

同样的，完成全部修改后使用 git push -f 来强制推送更改。

强制推送会覆盖远程历史，是一项有风险的操作。 如果你在一个多人协作的分支中工作，请务必确保你在推送之前已经与团队成员进行了充分的沟通，并且了解可能带来的影响。

安全更新与 TUM

你可能会注意到，在发起 PR 时的模板中有一个 Security Update? 的小标题，这是用来标识你的更新是否涉及到安全性修复的。
这就意味着，如果你发现你更新的软件包碰巧修复了某个安全漏洞，就应该多做一些工作。

你可以从以下几个途径尝试了解：

• #oss-security 的邮件列表，你可以在谷歌上通过 site:openwall.com/lists/oss-security/ 后面带关键词来搜索安全通告。
• 在官方 CVE 数据库 上搜索软件包的名称，查看是否有相关的安全漏洞。
• 观察 Release Notes 或者 Changelog 中是否有提及安全修复。

一旦发现安全漏洞，且你确定你正在更新的软件包会修复该漏洞，你就要在更新软件包之外，额外做安全通报工作。正巧 7-zip 的 25.00 版本出现了这个情况，下面将以这个更新作举例说明：

1. 在 aosc-os-abbs 中创建一个 Issue，模板选择 Security Vulnerabilities Report，按照指示填写相关信息并提交。（在本例中我创建了 Issue #11761）
2. 回到你更新的软件包的 PR 页面，在 Security Update? 的小标题下方填写 Yes，并附上你刚刚创建的安全通报 Issue 的编号并标注 fixes 以便 PR 合并时自动关闭。（参见 PR #11760）
3. 准备发布一个 TUM（Topic Update Manifest）。这意味着当用户更新到你的软件包时，oma 会提示该软件包修复了什么漏洞。
   TUM 的位置位于 TREE/topics 目录下，你应该创建一个名为 $PKGNAME-$PKGVER.toml 的文件，本例中我们创建了 7-zip-25.00.toml，内容如下：

1
2
3
4
5
6
7
8
9
10
11
12

security = true

[name]
default = "7-Zip 25.00"
zh_CN = "7-Zip 25.00"

[caution]
default = "Fixes a heap buffer overflow vulnerability - CVE-2025-53816 (Severity: Medium); Fixes a null pointer dereference vulnerability - CVE-2025-53817 (Severity: Medium)"
zh_CN = "修复一处堆缓冲区溢出漏洞，漏洞编号 CVE-2025-53816（严重性：中）；修复一处空指针解引用漏洞，漏洞编号 CVE-2025-53817（严重性：中）"

[packages]
"7-zip" = "25.00"

在完成 TUM 的编写后，请将这个 TUM 单独作为一个 Commit 提交，格式为 topics: add <TUM 文件名>。（本例中应为 topics: add 7-zip-25.00.toml，实际上应当加上后面的 .toml）

在你如此操作之后，用户在通过 oma 完成 7-zip 的更新后，会看到类似下面的提示：

TUM 提示

下一步？

再次由衷地恭喜你，你的贡献已正式成为 AOSC OS 的一部分！在你成为 AOSC OS 贡献者之后，你将获得一系列新的权限，旨在让你未来的贡献之旅更加顺畅、高效：

• 主仓库的写入权限：你将可以直接向官方 aosc-os-abbs 仓库推送你的开发分支。
• BuildIt! 的调用权限：你将可以使用 AOSC OS 强大的自动化构建与测试系统。你将获得 AOSC OS 构建服务器的访问权限、主仓库的写入权限、构建 CI BuildIt! 的调用权限。

在你开始新的冒险之前，有一个重要的一次性设置需要完成。在确保你加入 AOSC-Dev 组织后，请将你本地 TREE 目录的 Git 远程地址，从你个人的 Fork 仓库修改回 AOSC OS 的主仓库：

1

git remote set-url origin https://github.com/AOSC-Dev/aosc-os-abbs.git

从此，你创建的所有新分支都应直接推送到主仓库，而不再需要通过个人 Fork 中转。
以及，以后的发起 PR 与构建操作请通过 BuildIt! 完成，BuildIt! 的主操作接口是 TG 上的 @aosc_buildit_bot。请在完成授权后，发送 /help 查看简要帮助。
通常从贡献者的角度，你需要依次完成如下操作：

1. 通过 BuildIt! 创建一个 PR：/openpr PR标题;分支名;涉及到的包 ，例如 /openpr 7-zip: update to 25.01;7-zip-25.01;7-zip。如果涉及到的包有构建顺序要求，请保证按顺序排列并用空格隔开。
2. 在创建成功后，BuildIt! 会返回对应的 PR 链接。打开链接确认无误后，通过 BuildIt! 触发构建：/pr PR编号，例如 /pr 11760。
3. 监控构建状态，并根据需要进行调整或是重复发起构建。
4. 在构建完成后进行测试。首先发送 /dickens PR编号 生成自动化报告，例如 /dickens 11760 。
5. 如果你作为贡献者发起 PR，此时的构建包将会自动作为主题推送到测试源。请稍等片刻后在自己的系统中，使用 oma topics --opt-in 主题名（主题名也就是分支名）来加入自己构建的测试源，在尽量多的架构进行更新与测试，并附在 PR 之中。
6. 在 PR 合并后，再次在 BuildIt! 中发送 /pr PR编号 触发构建，此时包将从 stable 发起构建，然后推送到正式的软件源。

掌握这套流程后，你的贡献效率将大大提升。欢迎来到贡献者的新世界，期待你为 AOSC 带来更多精彩！

本指南参考 AOSC OS 官方维基 编写，完稿于 2025 年 8 月 8 日，如果你发现本文描述的情况与维基或是社区实际情况不符，或者遇到了本指南没有覆盖到的情况，请以维基与社区为准，并积极与贡献者们沟通。编写代码、修复 Bug 只是开源贡献的起点，而如何与来自五湖四海的伙伴们有效沟通、协同共进，则是一门更深、也更有魅力的艺术。

*封面与如下 meme 图来自 《天使降临到我身边》 第 12 集的约 13:15 秒处。

REVIEW PLEASE!

事情越多，事情越少

打碎滤镜，仍见波澜壮阔

2024年12月9日，在和某个先前文章中曾经出现过的友人通话时，友人感慨道：今年对你来说真是波澜壮阔的一年。
在那时，我的频道群里正被一车来路不明的人骚扰，尽管与其他人交换了详情，但置顶警告的行为宛如打草惊蛇，之后相同的团体就再没出现，调查的弦就此断了线。
话题扯得有一点远，我们不妨还是回来讨论下：如何定义一年是「波澜壮阔」的一年？

从一方面讲，人在回忆过去的事情时，会对更久远的事物带上一层滤镜，选择性地忽略某些不重要的事，而对最近发生的事复现更深，导致意识上「这一年的事比上一年的多」。而另一方面，2024年又的的确确发生了许许多多的，堪称我人生中**「第一次」**的事，以至于超出了我自己的预期，又或者是处理范围。

• 第一次大胆和前端代码硬碰硬。学 JavaScript 以及其配套生态的想法在我脑海中至少存活了六年，但每次都停留在图书馆借了一两本书以及搜了点 PDF 下载下来。前年在 freeCodeCamp 跟着学了下 HTML 架构，但到了实践环节又半途而废。直到开始给隔壁项目 爆改代码，才发现：已经是 AI 加持的 2024年了，学习一个新领域并没有想象中的那么难，难的是试水的第一步。执行力是最终成事的关键。于是有了对着 Bento 描的新主页，以及对博客主题的爆改。

• 第一次收到国际邮件，Giffgaff 的免费电话卡漂洋过海兜兜转转顺利飘进了学校收发室，跑通了来往的邮路，至此暂时了却了我从小到大喜欢集邮，却无处收发邮件的一桩心结。

• 第一次出相对远的门，清晨迷迷糊糊着坐动车到南京，在湿热的天气中度过了一小段插曲般的时光。当你抛开旅游的滤镜，拿最趁手的交通工具走走城市的角落，你便会惊讶地发现：原来北方城市的调性大同小异。大城市是大城市，古城却还是那个古城。

  在此完整放送朋友圈原文：

  火车，地铁，汽车，公交车，自行车——可以自豪地说，在南京完成了交通工具的半数制霸。
  雨天和一个沉重双肩包打乱了一串旅行计划，不得已买了几天骑行卡，逃难般地在大雨天坐上一个小时的公交车，听着公交车上的大妈拿当地话和我加密通话，才发现了在旅游局设计的动线之外，还有一串「无聊」的细节。
  可以看到比济南还「随性」的交通——四处停放的共享单车，店铺前停着路中央也停着；左转直行混起来的红绿灯到处都是，最终的后果就是路中央挤成一团。可以看到大城市共有的新旧共存，高楼旁边是旧房，巷子两边围满了施工墙。窄巷里的路坑坑洼洼，购物中心的喷泉有三层楼高，中学大门非常显眼的学生业余电台，这些景象竟能在几公里的路线依次展现。
  大城终有大城的悠久与繁华，但褪去了未知的光环后，不得不说这座城市仍比我想象中的松弛得多。

• 第一次去到线下的 Livehouse，在美好的夜晚后再度坚定了成为 ChiliChill 粉丝的决心。

• 第一次为了 DDL 赶工到凌晨五点看见朝阳，第一次不靠交通工具徒步走进城市的角落…还有一大些可以称作「第一次」的小事。

要说这其中最大的感想，我们不妨往高了些的方向升华：每一次滤镜的打碎都伴随着世界观的重塑。

独断舍离，难掩旧日远去

这一章的大标题，我定为了「事情越多，事情越少」。如果说上面那一节讲的是波澜壮阔的「第一次」让事情变多的话，那么这一节大概讲的就是相对的，事情如何变少了吧。

事情变少的这件事也可以拿来辩证。有的事情是「主观」地减少，通过主动舍弃掉来缓解自己的压力；有的事情是「客观」地变少，当你发现时想找也找不回来。

独断舍离，又或者就是「切割」，已被提前到这篇博文去说，这里不再重复那些在发布文章后仍被不断验证着的观点。

旧日远去，则与三年前的 Project NANO 相关，可以说博客站开站以来的第一篇正式文章就是这个。

24年12月末，北京大学谜题协会的 COL 老师找到我，说要在校内主讲一篇主题为《网络解谜的前世今生》的例会，他的理由如下：

聊天末，他提到了我在 NANO 通关群提出来的 NANOv2 企划，问要不要在例会的最后推介一下。

能推介固然是好的，那么这个项目后来怎么样了呢？

我的回答如下：

我仍旧觉得我在之前「切割」一文中的话说的不错：「切割」行为在近两年看上去发生频率高的原因，是后疫情时代社交关系的回正。

网络解谜社群兴盛的时段，与疫情居家的时间存在着非常大的重合。在效率较低的「正事」之外，在居家的温馨（又或者是压抑？）的小空间里，物理活动之外，赛博空间成为了我们各方面活动的施展天地。大伙都在网上呢，IM 也得一直开着「等通知」，社交活动的实体浓缩为社交平台上带着头像的账号，想要找人或者发起一个小活动轻轻松松。

如此乌托邦直到潮水褪去，这时你会发现：你再也找不到一群可以随时随地和你交互的人了。

用更新潮的话来说，大伙都去「现充」去了，连空闲的时间档期都挤不出来，有些企划就自然地难产了。

我曾在 2023 年的年度报告里提到了疫情的全面放开，现在看来，疫情的结束终究还是带走了一些曾经较为亲近的东西，我也成为了「被切割」的一个。

一些「年度」与一些数据

年度游戏

很遗憾，今年与去年相比并没有什么让我耳目一新的新游戏进账。

从网游手游来看，我终于是发现了我与开放世界以及米哈游类的高耗时收集性游戏相性不符，因此今年掀起过水花的网游们——《鸣潮》《绝区零》《无限暖暖》，都仅仅是体验级别。从 Tai 的计时来看，今年有效时间最多的游戏还是《Counter-Strike 2》。

有效时间第二多的是《极限竞速：地平线4》，我在买了个黑武士4手柄后重新下回了两个《地平线》（当然也有《地平线4》版权到期下架的影响），然后发现**《地平线》系列有手柄和没手柄是两个游戏**。乐高 DLC 还挺好玩的。新硬盘也来了，等待并心怀期望着《地平线6》。

音乐游戏的话，还是依旧：

我超，______

年度音乐

由于今年把音乐库的构建全面转到了本地，加之 Spotify+网易云+AM 三端（他们必然统计不到本地数据）同时听，这三个音乐软件的年度报告自然就仅能作为参考，此处不表，仅列举主观上推荐的歌。

• 年度专辑：
  • ChiliChill《混入人类计划》 ：伟大无需多言。
  • 赵雷《署前街少年》：本年度心情低落时常听专辑。
• 年度推歌：
  • 石头歌 - 三无Marblue ：原因后面会详讲。
  • The Good Part - AJR：初听和再听都非常震撼。
  • Corners of Your Mind - Far West：来自于 Team Spirit 的夺冠 Vlog，非常振奋精神的一首歌。
  • Have It All - Elephante&Nevve：听了心情会非常好的一首歌。
  • 【POPY】小镇姑娘【2024VOCALOID吧调音大赛·AC030】 ：后半段直接刷新我对 SynthV 调 AI 的印象了，华侃如你做的好啊。
  • イントロダクション － Poppin’Party 中文填词版 未来前奏 feat. 夢ノ結唱 POPY (2024)：有高性能引擎也有优秀的填词，营养非常充足。

频道与网站

TG 频道：与去年相比，今年的话痨程度直接把年度推送数拉高 150。

所以是有活还是没活呢？

博客今年的数据自不必说，终于下定决心开始写「充实」些的博客，加之有比较爆的话题，数据肯定是比去年好一大截的。

两次尖峰一次是七牛，一次是 HTP，都是天上掉下来的流量。

时间都去哪里了

今年5月，在某人的安利下装了个 Tai 统计笔记本上的应用时长，以下是它的反馈：

娱乐活动还是 CS2 多

重装电脑后忘了装配套插件，于是12月网页的数据顺理成章地没了

有博客的更新与其他乱七八糟项目撑着，今年的 GitHub 还是比去年绿油油很多的：

还有一点值得铭记的：

• 今年 Postcrossing 方面，合计收到7张明信片，外寄出11张。
• 新创建的 #meetup 面基高达四个，来年继续努力。

再仔细一想，好像其他就没什么跨度到达一年的报告可供展示了，我总不能再没活了真贴流媒体的报告截图，然后顺利成为七牛的刷流对象吧？

变与不变，做个石头

我今年下半年特别爱听《石头歌》，尤其爱听篇首那几句。

转眼间，这已经是在这个所谓的「新」博客中的第三篇年度报告了，有些东西在变，有些东西始终没变。

比方说，隔了好多年测我的赛博星座，仍然是 ENFP-T ，但对于今年年度总结的主题而言，我觉得得稍有些改变。

上半年的「切割」多少磨平了点我的性子，我终于意识到：既已知自己技不如人，有时候避其锋芒，做一个一动不动的石头，也是一种不错的选择。

有些时候的事件进展并不完全由我们掌控，但我们可以选择如何应对。你大可说这是一种「精神胜利法」精神，但比起无尽的精神内耗和辩经，另一个道理显得更为明确：时间是属于一个人自己的，一个人的时间是不能被其他人定义的。

我们仍然不知道明年会发生什么，我们仍然不知道今年相比于我们的一生是怎么样的一年。对自己不重要的事情有个「石头」般的态度，方能在重要的事情上集中精力。

这一段话写给在今年暴论颇多，仍然是 ENFP-T 的自己：
当下行的情绪蔓延，轻松愉快的群聊也变成了针锋相对的辩经大会。「放下助人情结，尊重他人命运」这句话听起来难听，但却是节省精力的良方，你没必要处处去当演说家，对于意见无法达成一致的，还是随他去吧。

最后的最后，感谢你读到最后听了我这么多的废话。
愿博客的读者，愿我的朋友，新的一年都能摆脱精神内耗，真正找到自己喜欢做的事，真正找到有意义的事。

封面来源于学校里的🐱学长：

2024 年度报告封面

「北院路上这只🐱都比我有精神」

在溜了一圈比如向绑定 Email 发送通知的方案后，有人提出了通过利用「浏览器通知」来推送消息的方式。无奈一窝人都不是 W3C 协议研究大师，之前光见到过具体表现也没研究过实现机制。因而花了几天时间 （upd：完稿时已经接近两个月了）仔细研究，发现了一些既可以被称作「冷知识」又可以被称作「烫知识」的东西。就在这里做一些不专业的分享，如果有专业 Web 从业人士指正就更好了。

这是什么？

众所周知，运行在现代浏览器的网页在弹窗获取用户授权同意之后，拥有推送桌面通知到用户的权限。

很多时候，这项功能会被用作网页的订阅推送或是消息推送，比如下图是萌娘百科的一个典型调用实例：

「萌娘百科」站点的推送触发实例

而具体到推送本身，从推送特点来看大致可分为两类：Notification 和 Push API。虽然在找最终用户要权限的时候他们弹出的窗口都一模一样，但他们的区别却比较鲜明：

• Notification 的推送方式比较简单，它的存在就是为了使用户在切换到其他标签页或应用程序时也能收到较高层级的通知，但它的缺点也比较显著：它的推送依赖由网页相对前台的异步逻辑直接触发，因此只能在用户打开网页时推送消息，在用户关闭/休眠网页后推送就会消失。
• Push API 则是一种更加强大和贴近手机通知逻辑的推送方式，它的推送不依赖于网页的打开状态，而是通过浏览器后台的 Service Worker 来推送消息。这种推送方式的优势非常明显：用户不需要打开网页就能收到消息，我们本篇主要讨论这种方式。

有些网页恨不得往自己的前台塞爆各种引擎和逻辑，活跃的网页开得一多就容易使浏览器变成内存厂战略合作伙伴。把所有无关的逻辑扔掉，不用打开网页就能收到通知，听起来是非常美好的一件事。

那么，代价是什么呢？

先别急，我在下面放了两个按钮，他们分别对应了两种推送方式，您可以直接使用 F12 审查元素查看接下来按钮紧接的源代码，然后在进入后续章节前先点击体验一番。
注意：对于推送通知而言，由于不同浏览器的实现方式不同，所需要处理的 Edge Case 非常多，如下的按钮并不一定每次都能奏效。本来这里打算直接引一个专业的方案来实操模拟的，想了想还是算了 :P

从底层说起

所以说，在点击了「同意通知」后，从最终用户的浏览器到远程之间，究竟发生了哪些事情？
我们先不去管文档的事，其中的大致逻辑，仔细想想自然也可以猜出大概：

• 首先，浏览器自然没有办法掏出一种外星科技，来让每个服务器都能直接穿过层层防火墙和转发直达最终用户。要想让通知服务器直接实现主动推送到最终用户，大约是不太可能。
• 要想让所有用户在理论情况下都有收到通知的能力，只能让浏览器主动去拉取消息更新，就像大部分实践一样。但是一方面对于浏览器来说，同时维护到不同服务器之间的连接是一个不小的负担；另一方面对于服务器来说，每个网站都要与一车用户维护连接（即使并没有消息更新）也是不能接受的负担。
• 那么最容易想到的实现也就呼之欲出了：摇一个中间商出来不就好了。让中间商统一管理通知服务器和浏览器之间的信息交互。一方面，在统一标准之下，浏览器在通知方面的连接可以被简化到中间商一条；另一方面，服务器也没必要和中间商维护长连接，仅需要在有消息更新时通知中间商即可。

恭喜你，现在你已经会发明「推送服务」了，现在快去成为那个中间商吧。

现在，我们可以去看看真实的文档了。与 Push API 强相关的规范性文件共有如下两份文件：

• W3C 仍在处于草稿状态 (Working Draft) 的「Push API」标准。
• RFC8030 描述的推送协议实现。

我们可以用 RFC8030 文首的抽象框图来描述一个最简的推送链条：

+-------+           +--------------+       +-------------+|  UA   |           | Push Service |       | Application |+-------+           +--------------+       |   Server    |    |                      |               +-------------+    |      Subscribe       |                      |    |--------------------->|                      |    |       Monitor        |                      |    |<====================>|                      |    |                      |                      |    |          Distribute Push Resource           |    |-------------------------------------------->|    |                      |                      |    :                      :                      :    |                      |     Push Message     |    |    Push Message      |<---------------------|    |<---------------------|                      |    |                      |                      |

从这个框图中可以很轻易地看出，UA (User Agent) 代表了最终用户端的浏览器，Push Service 代表了作为中间商的推送服务，Application Server 代表了网页服务端的应用服务器。
Push Service 承担了最终用户与服务器之间的中继桥梁：

1. 在订阅发起时，UA 向 Push Service 发起订阅请求。
2. Push Service 会向 UA 提供一个可以唯一对应到该 UA 本次申请的订阅的端点对象，通常是一个 URL。
3. UA 将这个端点对象发送给 Application Server，这个端点对象通常关联在 Push Service 之下。
4. 之后，UA 仅需要维护与 Push Service 的连接，而 Application Server 仅需要在有消息更新时通知 Push Service 即可。

整体来看，和我们上述预想的方案是非常接近的。

而更贴近的推送链条，也不过是对于这个链条中各个环节的扩展整合。比如如上示例中的 OneSignal 是将 Application Server 从真正有内容的服务器前置到了专业的推送服务商，又如谷歌系的 Push Service 事实上与他们的 Firebase 服务紧密关联（这点我们之后还会讲）。由此来看，我们事实上已经得知了这套 Push API 的抽象实现逻辑。

一条消息的诞生

Service Worker 的骨架

接下来，我们从抽象的逻辑展开，以 Google Chrome 为载体，看看在用户点击「同意推送」之后，整条消息推送的链路发生了什么。

因为 W3C 对于 Push API 的期望是「不仅仅能推送消息」，因此 Push API 能拿到的信息远不仅仅是「标题+内容」这种标准的通知格式，倒从功能上说，「让浏览器显示通知」仅仅是 Push API 的一个子集（但事实上 Chrome 等浏览器对该 API 的适用范围施加了限制，后面会说）。
因此，真正和 Push Service 完成交互的，反而是用户点击「同意」之后驻留在浏览器后台的 Service Worker。Service Worker 作为一个独立的线程，可以在浏览器关闭后继续运行，因此在浏览器 UA 从长连接着的 Push Service 接收到消息后，Service Worker 会被唤醒，然后根据消息内容决定是否显示通知。

所以，对于 Application Server 而言，它首先便需要注册一个 Service Worker，然后在里面完成消息的处理流程。
我们可以使用如下的代码注册一个 Service Worker：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

if ('serviceWorker' in navigator && 'PushManager' in window) {
  console.log('Service Worker and Push API is supported');

  navigator.serviceWorker.register('/uploads/Something-About-Web-Push-API/sw.js')
  .then(function(swReg) {
    console.log('Service Worker is registered', swReg);
    swRegistration = swReg;
    swRegistration.update(); // 强制更新 Service Worker
    swRegistration.pushManager.subscribe({
      userVisibleOnly: true,
      applicationServerKey: applicationServerKey
    })
  })
  .catch(function(error) {
    console.error('Service Worker Error', error);
  });
} else {
  alert("您的访问环境不支持 Service Worker 或 Push API :(");
}

成功注册 Service Worker 后，打开 F12 开发者选项，我们可以在 Console 中观察到，被注册的 ServiceWorkerRegistration 自带了一个 pushManager 接口，而这就是我们后期发起推送消息时所需要调用的：

在准备好 Service Worker 之后，我们还需要准备一组 VAPID 密钥对，用于在订阅时对消息进行签名，阻止期望外的其他人向用户推送消息。从形式上而言，它就是经典的公钥加私钥，外带一个 mailto: 或是 http 开头的联系方式，用于标识发送方：

1
2
3
4
5
6
7

{
  "vapid": {
    "publicKey": "这里放公钥",
    "privateKey": "这里放私钥",
    "subject": "mailto:" // 或是 "https://"
  }
}

具体到实现而言，VAPID 使用了 ES256 算法，使用 ECDSA 在 NIST P-256 曲线上创建一组密钥对，然后对 JWT 进行签名验证。
VAPID 密钥对通常仅需要生成一次，而且到处都可以找到一个在线生成站。当然，您可以使用下面的按钮刷新几组，这里的代码来自于 Google 的 Web Push Codelab：

接下来，我们将目光转向真正处理通知请求的 Service Worker 中。实际上对于它而言，最短的形态可以长这样：

1
2
3
4

self.addEventListener('push', function(event) {
    const payload = event.data ? event.data.text() : 'no payload';
    console.log('[Service Worker] Push Received.', payload);
});

从上面的代码可以看出，这个 Service Worker 目前只干了一件事：接收到消息后，将消息内容打印到自己的控制台。

我们可以把这个 Service Worker 按正常的推送流程注册一下，看看会发生什么：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

function base64UrlToUint8Array(base64UrlData) {
  const padding = '='.repeat((4 - base64UrlData.length % 4) % 4);
  const base64 = (base64UrlData + padding)
    .replace(/\-/g, '+')
    .replace(/_/g, '/');

  const rawData = window.atob(base64);
  const buffer = new Uint8Array(rawData.length);

  for (let i = 0; i < rawData.length; ++i) {
    buffer[i] = rawData.charCodeAt(i);
  }
  return buffer;
}

const applicationServerKey = base64UrlToUint8Array('这里放公钥'); // 请将这里替换为您的 VAPID 公钥

// 这段代码放在注册流程之后
// 即上文中的 swRegistration.update(); 之后
swRegistration.pushManager.subscribe({
  userVisibleOnly: true, // 强制规范，表示该订阅仅能用于显示用户通知
  applicationServerKey: applicationServerKey}).
  then(function(subscription) {
    console.log('User is subscribed:', subscription);
    console.log(JSON.stringify(subscription));
  }).catch(function(err) {
    console.log('Failed to subscribe the user: ', err);
  });

强耦合的 Push Service 与 UA

从这一步开始，真正有意思的地方开始展开眉目。
我们运行上面的代码，将粗糙的 Service Worker 狠狠注册入浏览器，然后打开抓包软件和控制台，点击「同意推送」的按钮。

然后我们可以在控制台看见这样的输出：

换句话说，我们完成 Service Worker 的注册之后，得到了如下所示的一串 JSON ：

1
2
3
4
5
6
7
8

{
    "endpoint": "https://fcm.googleapis.com/fcm/send/dZiga:APA91bGM5iYsrYjRUjjn4lpmLtEW6",
    "expirationTime": null,
    "keys":{
        "p256dh":"BCUoPTSKzN3QWTEhmRrf",
        "auth":"AjkZRuLhkK"
    }
}

• endpoint 是一个指向 Push Service 的链接，指向 Push Service 为该 UA 上的该网页所准备的订阅端点。后面使用这个端点便能为此次申请的订阅发送消息。
• expirationTime 是一个过期时间，表示这个订阅的有效期。在这个时间之后，这个订阅将会被自动删除。
  • 至少对于 Chromium 系浏览器而言，查看源代码 可以发现，这一项默认都是禁用的，也就是说返回值一般都是 null 。
• keys 是一个包含了两个子项的对象，分别是 p256dh 和 auth 。这两个子项是用于在推送消息时对消息进行加密的密钥对。
  • p256dh 是一个 P-256 公钥。
  • auth 是一个 Base64 密钥，这是 UA 为 Application Server 生成的鉴权密码，与 endpoint 配合使用。

对于 keys 需要额外补充的一点：IETF 的 RFC8030 要求服务端对推送消息进行RFC8291 加密，并通过 RFC8188 定义的 aes128gcm 进行加密传输，摘抄如下，感兴趣的可回到原标准进一步研究：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

-- For a user agent:
    ecdh_secret = ECDH(ua_private, as_public)
    auth_secret = random(16)
    salt = <from content coding header>

-- For an application server:
    ecdh_secret = ECDH(as_private, ua_public)
    auth_secret = <from user agent>
    salt = random(16)

-- For both:

    ## Use HKDF to combine the ECDH and authentication secrets
    # HKDF-Extract(salt=auth_secret, IKM=ecdh_secret)
    PRK_key = HMAC-SHA-256(auth_secret, ecdh_secret)
    # HKDF-Expand(PRK_key, key_info, L_key=32)
    key_info = "WebPush: info" || 0x00 || ua_public || as_public
    IKM = HMAC-SHA-256(PRK_key, key_info || 0x01)

    ## HKDF calculations from RFC 8188
    # HKDF-Extract(salt, IKM)
    PRK = HMAC-SHA-256(salt, IKM)
    # HKDF-Expand(PRK, cek_info, L_cek=16)
    cek_info = "Content-Encoding: aes128gcm" || 0x00
    CEK = HMAC-SHA-256(PRK, cek_info || 0x01)[0..15]
    # HKDF-Expand(PRK, nonce_info, L_nonce=12)
    nonce_info = "Content-Encoding: nonce" || 0x00
    NONCE = HMAC-SHA-256(PRK, nonce_info || 0x01)[0..11]

相信有心的读者已经对 endpoint 里的 fcm.googleapis.com 有了一些敏感度，而结果也确实如此：这个端点，实际上是谷歌的 Firebase Cloud Messaging 服务。这也就意味着，我们的消息实际上是通过谷歌的推送服务来传递的。

这时我们回到抓包软件，会发现在点击推送按钮的同时，Chrome 发送了一个有意思的请求：

至此，整个推送链条的第二环浮出水面：此处的 Push Service (FCM) 与 UA(Chrome) 实际上是强耦合的关系。

向 Push Service 的更深一步

接下来我们来研究一下这个请求，部分字段进行了脱敏处理但是可以保证一对一映射：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

POST /c2dm/register3 HTTP/2
host: android.clients.google.com
content-length: 268
authorization: AidLogin 114514:1919810
content-type: application/x-www-form-urlencoded
sec-fetch-site: none
sec-fetch-mode: no-cors
sec-fetch-dest: empty
user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36
accept-encoding: gzip, deflate, br, zstd
accept-language: zh-CN,zh;q=0.9,en;q=0.8,zh-TW;q=0.7
priority: u=4, i

app=com.chrome.windows&X-subtype=wp:https://blog.hanlin.press/%235008CBF7-830C-43E6-9F8E-76ADF5AA4-V2&device=114514&scope=GCM&X-scope=GCM&gmsv=131&appid=dZiga&sender=BBdRH5vr

token=dZiga:APA91bGM5iYsrYjRUjjn4lpmLtEW6

我们可以把请求和返回拆开来猜测一下：

• app: com.chrome.windows 看样子指向了 Chrome 浏览器的 Windows 版本。
• c3ad4ca2-cced-4d75-82f7-c2128563beda
• X-subtype: wp:https://blog.hanlin.press/#5008CBF7-830C-43E6-9F8E-76ADF5AA4-V2 是一个特意构造的 URL，应该是用于标识这个域名下的唯一订阅。
• device: 114514 是一个设备 ID，与标头的 authorization 对应。
• appid 和 token：与上文返回的 JSON 里的 endpoint 完全对应。
• sender：与上文中提交的 VAPID 公钥完全对应。

由此可见，Chrome 浏览器一定是从这个请求中获取到了与 Push Service 通信的必要信息，然后将这个信息进一步返回到 PushSubscription 对象中。

如果我们尝试翻翻 Chromium 的源码 ，不难发现，这个地址 https://android.clients.google.com/c2dm/register3 是硬编码进去的：

继续搜索，会发现这是谷歌声明早已在 2015 年彻底弃用的 C2DM 推送服务所使用的端点，它甚至是 GCM 的前辈，可以被称作 FCM 的爷爷。可能出于历史遗留向下兼容的问题，在 2024 年运行的 Chrome 中还能看见这个地址。

因为实在不想再去读一遍 Chromium 的源代码，我去 Wayback Archive 里找到了描述注册流程的文档：

这个文档里描述了 app 和 sender 两个必要的对象，接下来是时候看看 Chromium 的源码 了，关键的部分摘抄在下面：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// -- chrome/browser/push_messaging/push_messaging_constants.cc

const char kPushMessagingGcmEndpoint[] =
    "https://fcm.googleapis.com/fcm/send/";

// -- chrome/browser/push_messaging/push_messaging_service_impl.cc

// Chrome does not yet support silent push messages, and requires websites to
// indicate that they will only send user-visible messages.
const char kSilentPushUnsupportedMessage[] =
    "Chrome currently only supports the Push API for subscriptions that will "
    "result in user-visible messages. You can indicate this by calling "
    "pushManager.subscribe({userVisibleOnly: true}) instead. See "
    "https://goo.gl/yqv4Q4 for more details.";

• 目前返回的推送 API 固定为 https://fcm.googleapis.com/fcm/send/ 开头，指向上面说的 FCM 服务。
• 参见上文的强制规范：Chrome 强制网页声明 Push API 仅能用于用户可见的通知用途。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

// -- chrome/browser/push_messaging/push_messaging_service_impl.cc

void PushMessagingServiceImpl::SubscribeFromWorker(
    const GURL& requesting_origin,
    int64_t service_worker_registration_id,
    int render_process_id,
    blink::mojom::PushSubscriptionOptionsPtr options,
    RegisterCallback register_callback) {
  render_process_id_ = render_process_id;
  PushMessagingAppIdentifier app_identifier =
      PushMessagingAppIdentifier::FindByServiceWorker(
          profile_, requesting_origin, service_worker_registration_id);

  // If there is no existing app identifier for the given Service Worker,
  // generate a new one. This will create a new subscription on the server.
  if (app_identifier.is_null()) {
    app_identifier = PushMessagingAppIdentifier::Generate(
        requesting_origin, service_worker_registration_id);
  }

  if (push_subscription_count_ + pending_push_subscription_count_ >=
      kMaxRegistrations) {
    SubscribeEndWithError(std::move(register_callback),
                          blink::mojom::PushRegistrationStatus::LIMIT_REACHED);
    return;
  }

  if (!IsPermissionSet(requesting_origin, options->user_visible_only)) {
    SubscribeEndWithError(
        std::move(register_callback),
        blink::mojom::PushRegistrationStatus::PERMISSION_DENIED);
    return;
  }

  if (!options->user_visible_only) {
    origins_requesting_user_visible_requirement_bypass.insert(
        app_identifier.origin());
  }

  DoSubscribe(std::move(app_identifier), std::move(options),
              std::move(register_callback),
              /* render_process_id= */ -1, /* render_frame_id= */ -1,
              blink::mojom::PermissionStatus::GRANTED);
}

// -- chrome/browser/push_messaging/push_messaging_app_identifier.cc

constexpr char kPushMessagingAppIdentifierPrefix[] = "wp:";
constexpr char kInstanceIDGuidSuffix[] = "-V2";

// sizeof is strlen + 1 since it's null-terminated.
constexpr size_t kPrefixLength = sizeof(kPushMessagingAppIdentifierPrefix) - 1;
constexpr size_t kGuidSuffixLength = sizeof(kInstanceIDGuidSuffix) - 1;

// Ok to use '#' as separator since only the origin of the url is used.
constexpr char kPrefValueSeparator = '#';
constexpr size_t kGuidLength = 36;  // "%08X-%04X-%04X-%04X-%012llX"


// static
PushMessagingAppIdentifier PushMessagingAppIdentifier::Generate(
    const GURL& origin,
    int64_t service_worker_registration_id,
    const std::optional<base::Time>& expiration_time) {
  // All new push subscriptions use Instance ID tokens.
  return GenerateInternal(origin, service_worker_registration_id,
                          true /* use_instance_id */, expiration_time);
}

// static
PushMessagingAppIdentifier PushMessagingAppIdentifier::GenerateInternal(
    const GURL& origin,
    int64_t service_worker_registration_id,
    bool use_instance_id,
    const std::optional<base::Time>& expiration_time) {
  // Use uppercase GUID for consistency with GUIDs Push has already sent to GCM.
  // Also allows detecting case mangling; see code commented "crbug.com/461867".
  std::string guid =
      base::ToUpperASCII(base::Uuid::GenerateRandomV4().AsLowercaseString());
  if (use_instance_id) {
    guid.replace(guid.size() - kGuidSuffixLength, kGuidSuffixLength,
                 kInstanceIDGuidSuffix);
  }
  CHECK(!guid.empty());
  std::string app_id = kPushMessagingAppIdentifierPrefix + origin.spec() +
                       kPrefValueSeparator + guid;

  PushMessagingAppIdentifier app_identifier(
      app_id, origin, service_worker_registration_id, expiration_time);
  app_identifier.DCheckValid();
  return app_identifier;
}

结合之前的抓包，不难得出这一段展示了之前 X-subtype 的生成逻辑：wp:+网页的 Origin 段（通常是请求头带域名）+#+随机生成的 UUID （最后三位替换成-V2）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

// -- chrome/browser/push_messaging/push_messaging_service_impl.cc

// Message displayed in the console (as an error) when a GCM Sender ID is used
// to create a subscription, which is unsupported. The subscription request will
// have been blocked, and an exception will be thrown as well.
const char kSenderIdRegistrationDisallowedMessage[] =
    "The provided application server key is not a VAPID key. Only VAPID keys "
    "are supported. For more information check https://crbug.com/979235.";

void PushMessagingServiceImpl::DoSubscribe(
    PushMessagingAppIdentifier app_identifier,
    blink::mojom::PushSubscriptionOptionsPtr options,
    RegisterCallback register_callback,
    int render_process_id,
    int render_frame_id,
    blink::mojom::PermissionStatus permission_status) {
  if (permission_status != blink::mojom::PermissionStatus::GRANTED) {
    SubscribeEndWithError(
        std::move(register_callback),
        blink::mojom::PushRegistrationStatus::PERMISSION_DENIED);
    return;
  }

  std::string application_server_key_string(
      options->application_server_key.begin(),
      options->application_server_key.end());

  // TODO(peter): Move this check to the renderer process & Mojo message
  // validation once the flag is always enabled, and remove the
  // |render_process_id| and |render_frame_id| parameters from this method.
  if (!push_messaging::IsVapidKey(application_server_key_string)) {
    content::RenderFrameHost* render_frame_host =
        content::RenderFrameHost::FromID(render_process_id, render_frame_id);
    if (base::FeatureList::IsEnabled(
            features::kPushMessagingDisallowSenderIDs)) {
      if (render_frame_host) {
        render_frame_host->AddMessageToConsole(
            blink::mojom::ConsoleMessageLevel::kError,
            kSenderIdRegistrationDisallowedMessage);
      }
      SubscribeEndWithError(
          std::move(register_callback),
          blink::mojom::PushRegistrationStatus::UNSUPPORTED_GCM_SENDER_ID);
      return;
    } else if (render_frame_host) {
      render_frame_host->AddMessageToConsole(
          blink::mojom::ConsoleMessageLevel::kWarning,
          kSenderIdRegistrationDeprecatedMessage);
    }
  }

  IncreasePushSubscriptionCount(1, true /* is_pending */);

  // Set time to live for GCM registration
  base::TimeDelta ttl = base::TimeDelta();

  if (base::FeatureList::IsEnabled(
          features::kPushSubscriptionWithExpirationTime)) {
    app_identifier.set_expiration_time(
        base::Time::Now() + kPushSubscriptionExpirationPeriodTimeDelta);
    DCHECK(app_identifier.expiration_time());
    ttl = kPushSubscriptionExpirationPeriodTimeDelta;
  }

  GetInstanceIDDriver()
      ->GetInstanceID(app_identifier.app_id())
      ->GetToken(
          push_messaging::NormalizeSenderInfo(application_server_key_string),
          kGCMScope, ttl, {} /* flags */,
          base::BindOnce(&PushMessagingServiceImpl::DidSubscribe,
                         weak_factory_.GetWeakPtr(), app_identifier,
                         application_server_key_string,
                         std::move(register_callback)));
}

void PushMessagingServiceImpl::DidSubscribe(
    const PushMessagingAppIdentifier& app_identifier,
    const std::string& sender_id,
    RegisterCallback callback,
    const std::string& subscription_id,
    InstanceID::Result result) {
  DecreasePushSubscriptionCount(1, true /* was_pending */);

  blink::mojom::PushRegistrationStatus status =
      blink::mojom::PushRegistrationStatus::SERVICE_ERROR;

  switch (result) {
    case InstanceID::SUCCESS: {
      const GURL endpoint = push_messaging::CreateEndpoint(subscription_id);

      // Make sure that this subscription has associated encryption keys prior
      // to returning it to the developer - they'll need this information in
      // order to send payloads to the user.
      GetEncryptionInfoForAppId(
          app_identifier.app_id(), sender_id,
          base::BindOnce(
              &PushMessagingServiceImpl::DidSubscribeWithEncryptionInfo,
              weak_factory_.GetWeakPtr(), app_identifier, std::move(callback),
              subscription_id, endpoint));
      return;
    }
    case InstanceID::INVALID_PARAMETER:
    case InstanceID::DISABLED:
    case InstanceID::ASYNC_OPERATION_PENDING:
    case InstanceID::SERVER_ERROR:
    case InstanceID::UNKNOWN_ERROR:
      DLOG(ERROR) << "Push messaging subscription failed; InstanceID::Result = "
                  << result;
      status = blink::mojom::PushRegistrationStatus::SERVICE_ERROR;
      break;
    case InstanceID::NETWORK_ERROR:
      status = blink::mojom::PushRegistrationStatus::NETWORK_ERROR;
      break;
  }

  SubscribeEndWithError(std::move(callback), status);
}
void PushMessagingServiceImpl::DidSubscribeWithEncryptionInfo(
    const PushMessagingAppIdentifier& app_identifier,
    RegisterCallback callback,
    const std::string& subscription_id,
    const GURL& endpoint,
    std::string p256dh,
    std::string auth_secret) {
  if (p256dh.empty()) {
    SubscribeEndWithError(
        std::move(callback),
        blink::mojom::PushRegistrationStatus::PUBLIC_KEY_UNAVAILABLE);
    return;
  }

  app_identifier.PersistToPrefs(profile_);

  IncreasePushSubscriptionCount(1, false /* is_pending */);

  SubscribeEnd(std::move(callback), subscription_id, endpoint,
               app_identifier.expiration_time(),
               std::vector<uint8_t>(p256dh.begin(), p256dh.end()),
               std::vector<uint8_t>(auth_secret.begin(), auth_secret.end()),
               blink::mojom::PushRegistrationStatus::SUCCESS_FROM_PUSH_SERVICE);
}

更深的内置到 GCM 的推送服务细节无法追溯，但是此处的细节已经可以猜出个大概：Chrome 将 sender 设置为之前传入的 VAPID 公钥（参照 CRBUG #979235， 他们曾经还使用过需要注册账号的 GCM 服务进行推送），app 设置为 com.chrome.windows （在注释中还看到过 com.chrome.macosx），然后执行了一次较为标准的 GCM 通知注册流程。

这整个过程与面向移动应用的推送服务的流程非常相似，但是与后者比起来，Web Push 显得开放却又隐秘。

• 从开放方面来说，Web Push 不需要经过发布商或是运营商的审核，只要获得了用户的许可和一个正常的网络，任何网站都能向用户推送消息。即使有 VAPID 这种机制，也仅仅是作为标识使用，它的生成本身并不需要任何审核，更不需要向任何一个组织递交申请书。
• 从隐秘方面来说，Web Push 的加密机制也在协议上保证了消息的隐私性。消息的加密和解密都是在 UA 和 Application Server 之间进行的，Push Service 无法窥探消息的内容。

Service Worker 只要监听就好了

Web Push 是这样的，被注册的 Service Worker 仅需要监听 push 事件，然后做出对应的处理就好了，而我们浏览器 UA 所需要干的可就多了。

研究了 Push Service 半天，我们还没来得及认真看一看我们注册了有一段时间的 Service Worker。

打开 F12 开发者选项，选择 Application 栏 → 左侧 Service Workers 菜单，可以查看这个 Worker 的注册状态。

顺带一提，在 Worker 右侧可以看见一个 Unregister 按钮，点击就可以卸载掉这个 Service Worker，顺带退订掉该 Worker 处理的通知。在抓包软件里也可能看到，Chrome 向 https://android.clients.google.com/c2dm/register3 再次发送了一次请求，只不过这次在大致相同的请求里追加了 delete=true 项。

这时注意到下方的 Push 栏，这里是预留的测试入口，仅需在框里输入内容，然后点击右侧的「Push」按钮，即可在无 Push Service 的情况下模拟一次推送事件。
这时切换到 Console 栏查看控制台输出，可以观测到成功触发了监听到的 push 事件。

可以看到，这里将测试栏里的 Test push message from DevTools. 和 {} 原样输出了出来。

接下来该试试真正的推送了，我们拿好上文生成的 VAPID 公钥和私钥，构造一个真正的 Application Server （前文所提及的都仅仅能称作前端），我无心运营真正的消息推送平台，所以我拿 Cloudflare Worker 模拟了一个：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111