望向天脉的技术记录

Nahimic 出厂音效续篇：变体判定与空间效果

Tue, 06 Oct 2026 00:00:00 GMT

上一篇《把 Nahimic 出厂音效搬到 Linux》结尾留了三件事：扬声器变体 A/B 没有判定、461 个参数里有 390 个不知道取值、空间效果没有落地。所以就有了后续。

先决条件

需要	本次环境
硬件	MECHREVO 蛟龙，Conexant SN6140（``VEN_14F1 DEV_1F87``，SUBSYS ``1D053010``）
系统	CachyOS，PipeWire 1.6.9
效果器	EasyEffects 8.3.0（Flatpak）
原厂数据	Windows 分区里的 A-Volute/Nahimic 驱动包（180 个明文 XML）
工具	Python 3、NumPy、``cabextract``、``objdump``

上一篇的环境是 PipeWire 1.6.8 与 EasyEffects 8.2.9。8.3.0 在 2026-09-29 发布，这一轮关于插件的结论都以 8.3.0 为准。

范围限制：只看笔记本内置扬声器。耳机、外置声卡、蓝牙设备都不在范围内。

一、变体由 SMBIOS 的 OEM 串决定

`Devices/` 里属于本机 SUBSYS 的扬声器档案有 8 个，分成两套曲线。上一篇停在「主板型号 `X6xR55xK` 对不上任何一个文件名，不能按文件数量猜」这一步。

判据就在设备档案末尾的 `<Data>` 块里：

```xml
<HWID>       <Value>SUBSYS_1D053010</Value> </HWID>
<FormFactor> <Value>Speakers</Value>        </FormFactor>
<ID>         <Value>{753ed818-…}</Value>    </ID>
<SMBIOS>     <Value>1D053010K5500103</Value></SMBIOS>
```

配置器要拿本机的一个字符串去比 `<SMBIOS>`。这个字符串的来源写在 `NahimicPnPAPO4ConfiguratorDaemonModule.dll` 里：

```text
SELECT OEMStringArray FROM Win32_ComputerSystem
```

`Win32_ComputerSystem.OEMStringArray` 就是 SMBIOS 的 Type 11（OEM Strings）。

把那张表读出来

Linux 这边三条常规入口都不通：

入口	结果
``/sys/firmware/dmi/tables/DMI``、``entries/11-0/raw``	权限 ``-r-------- root``
``/sys/class/dmi/id/*``	17 个字段里没有 OEM 串
Windows 侧 ``HKLM\SYSTEM\…\mssmbios\Data``	Windows 11 已不再缓存这张表

所以做一次只读的特权读取就够：

```bash
pkexec /usr/bin/cat /sys/firmware/dmi/tables/DMI > data/smbios/DMI.bin
python3 tools/read_smbios_oem.py data/smbios/DMI.bin
# → Type 11 OEM Strings (20 条):
#     [16] '1D053010K5500103'   <-- 形如 SUBSYS+型号键（候选选择键）
#   ✅ 命中: 1D053010K5500103
#      档案: 1D053010_1D053010K5500103_Speakers.nsx
```

完整脚本：read_smbios_oem.py 149 行 / 5.2 KB ｜直接下载

判据是三段拼接：`SUBSYS_1D053010` 取自 HWID，`K5500103` 是 OEM 键，两者与档案里的 `<SMBIOS>` 必须逐字符相同。本机命中即变体 B（`X6DR57TK`），不需要扫频，也不需要听感 A/B。

8 个候选其实只有 2 套曲线

把每个档案的 `<ID>`（GUID）与 `<SMBIOS>` 归一化之后算 md5：

档案	``<SMBIOS>``	归一化后 md5
``…K5500101`` – ``…K5500107``	各不相同	七个文件完全相同 ``c2b5d235…``
``…K5500100``	``1D053010K5500100``	``7cf30fdc…``

同一套调音挂在 7 个 OEM 键下面，不是 7 次独立采样。

顺带一提，档案头部的 `FT-NOTE` 注释不可信：`K5500101` 到 `K5500107` 的注释统统写 `SMBIOS-1D053010K5500103`，连 `0107` 也写 `0103`。只有 `<SMBIOS>` 字段算数。

二、390 个参数不在磁盘上

`NahimicAPO4API.dll` 里有 461 个 `kSet_*` 键。XML 只出现了其中 71 个（交集 67 个），剩下 394 个键在配置文件里从来没有出现过。

上一篇的猜测是：实际取值保存在运行态，`Settings/settings.dat` 是最像的地方。这一轮把候选逐一拆开看：

#	位置	实际内容
1	``Settings/settings.dat``（8192 B，注册表 hive）	只有 ``CurrentMicProfile='Chat\0'`` 与 ``ToastShown='[]\0'``
2	``LocalState/AppSettings.json``	应用启动状态
3	``LocalState/EQPresets.json``	每个场景选用的预设名（本机全为 ``Custom``）
4	``LocalState/Chat.nsx`` / ``Conference.nsx``	采集链的 6 个开关，属采集侧
5	``LocalState/Settings/v1/EQPresets/**``	UI 那 10 段图形 EQ，已转成 EasyEffects 预设
6	``HKCU\Software\A-Volute\Nahimic\{701C0AEE-…}``	守护模块登记表：每个 ``*DaemonModule.dll`` 的路径与 GUID
7	``HKCU\Software\Nahimic\…\ShortcutEngine\{7943271B-…}``	一个快捷键码 ``k000031a4 = 8``
8	``HKLM\SOFTWARE\…\MMDevices\Audio\Render\{端点}\FxProperties``	只有 APO 注册项
9	``HKLM\SYSTEM\…\Enum\SWD\…AVOLUTE_NH4APO&6&…``	设备枚举项，``[Device Parameters]`` 的 ``values=0 subkeys=0``

第 8、9 项本来最有希望：`FxProperties` 是第三方 APO 在 Windows 上持久化参数的常规位置，而那一项里只有一个 APO 注册和三个 mode CLSID。

结论是负的：这 390 个键不落盘，运行时参数由后台服务推送给 APO 的共享内存。想拿到它们，只剩静态提取 `NahimicAPO4.dll` 的内置默认值表一条路，所以我们又又延期了（详见第八节待办）。

这一轮顺带确认了两件事：当前生效的 APO 是 A-Volute/Nahimic（端点属性里 `{f363df17-…},11 = 'A-Volute.Nahimic'`），`Senary Audio` 只是 OEM 驱动的品牌名；另外 `Nahimic_Mirroring` 建了一个独立的镜像端点。

三、空间效果：只有开关，没有强度

出厂四个场景里，空间类效果的开关如下（来自同一份 XML）：

参数	音乐	电影	游戏	通讯
``SpkVirtualSurroundState``	0	1	1	0
``StereoWideningState``	0	1	1	0
``UpmixState``	0	1	1	0
``ReverbState``	0	1	1	0
``ReverbGainDB``	-10.0	-10.0	-10.0	-10.0

音乐场景不启用任何空间效果，只做设备校正加三段增益。电影与游戏则把四个开关全打开。

问题在于强度：461 个键里，`SpkVirtualSurround`、`StereoWidening`、`Upmix` 都只有 `State`，没有任何强度或角度参数。原厂只给了开关，给不出「开多大」。所以这边的做法是给一组分级试听预设，由耳朵选：

场景	预设
电影	加宽弱、加宽强、串扰、综合（4 个）
游戏	加宽弱、加宽强、串扰、综合（4 个）
音乐	加宽弱、加宽强

注意，原厂的音乐预设是没有加宽的，这里纯粹是我想试试效果所以加上去了

落地用的是两个插件：立体声扩展走 Calf 的 Stereo Tools（`stereo_tools`），串扰抵消走 EasyEffects 原生的 `crosstalk_canceller`。这两个插件的 JSON 键名是从上游 v8.3.0 的 kcfg 与源码里核对的，凭印象写键名会被静默忽略。

完整脚本：build_spatial_presets.py 197 行 / 8.1 KB ｜直接下载

四、串扰抵消在笔记本扬声器上不成立（至少现在不成立）

试听串扰预设时，我总感觉听起来很奇怪，塑料味道相当大。

第一件事是确认卷积器有没有在工作。厂校 FIR 在 800 Hz 有一个箱体共振凹陷，串上串扰之后这个凹陷只变化 -0.12 dB：

```text
  FIR 单独            : -12.88 dB
  FIR × RACE(H_direct): -13.00 dB
  -> 凹陷被填回 -0.12 dB
```

凹陷完好，卷积器在正常工作，问题出在串扰本身。

RACE 是什么

EasyEffects 的串扰抵消是 RACE（Recursive Ambiophonic Crosstalk Elimination，作者 Antti S. Lankila）。它是一个递归结构：中置声道经过一个反馈梳状滤波器（见下方公式）之后再混回左右。：

\frac{1}{1 + g \cdot H _{f b} ( z ) \cdot z ^{- D}}

$H_{f} b$ 是 6 个双二阶（biquad）级联：250 Hz 高通、3245 Hz 低通，加四个衰减峰（688 / 1066 / 2190 / 3792 Hz）。

延迟是量化过的：

D = round (\frac{delay_us}{1 0 ^{6}} \times rate)

313 µs 在 48 kHz 下等于 15 个采样，梳状间隔 `1/D` 是 3.2 kHz，第一个四分之一周期正好落在 800 Hz——厂校 FIR 挖凹陷的位置。

数值复核

先把解析模型（z 域）与逐样本时域仿真对着跑：两者的最大偏差 0.003 dB。这个自检有用，把模型里的符号写反时偏差立刻变成 2.1 dB。

然后看它对频响做了什么：

通路	结果
直达通路	全程 ±2 dB，峰 +3.11 dB @1449 Hz
交叉项（``phantom-center-only=true``）	250–3245 Hz 带内，1597 Hz 处 -8.98 dB
交叉项相位	与直达同相（800 Hz 处 87°）

同相的交叉项起不到抵消作用，它更像一份延迟 312 µs 的副本，加在原信号上形成梳状滤波——听感上的染色就来自这里。

完整脚本：analyze_crosstalk.py 347 行 / 14.3 KB ｜直接下载

为什么在笔记本上不成立

RACE 的几何前提接近 KEMAR 那种头型：两只扬声器与听者构成固定夹角，双耳时间差是已知量。笔记本内置扬声器的张角只有约 ±10°，插件里的 `delay-us` 下限 200 µs 对应约 9.6 个采样，很可能已经高于这种间距下的真实双耳时间差。再加上预设用的 `phantom-center-only=true` 只处理中置声道，染色正好落在人声与主奏上。

结论：这 4 个串扰与综合预设在本机判定为不可用。这里没有做声学测量，机制解释属于「最合理的解释」，频响数值是实算的。

五、校验器漏掉的 37 个插件块

生成预设之后要跑校验。上一轮的 `validate_presets.py` 里，插件分派写成一串 `if/elif`，最后没有 `else`。结果是：不认识的插件直接跳过，一个检查都不做，还照样报 OK。

统计下来有 37 个插件块从来没被校验过：`limiter` 19 个、`bass_enhancer` 17 个、`deepfilternet` 1 个。这个数量已经超过当时预设里被检查的部分。

补法是给这三个插件写真实检查，并加两条硬规则：

```python
    # 未知插件**必须报错**，不能静默放行 ——
    # 否则新增插件时"全部通过"是假的（这正是本档案陷阱 1 的形态）。
    chk(base in HANDLED_PLUGINS,
        "%s: 插件 %r 没有校验规则 —— 请先补 HANDLED_PLUGINS 与对应检查" % (name, base))
```

另一条是「键集完全一致」：每个插件块的键集合必须与 kcfg 枚举的集合逐键相同，多一个少一个都算错。以前只检查键值合法，键名写错、键漏掉都发现不了。

升级后立刻抓到两个真实缺陷：`-原厂-` 与 `-完整-` 两个预设的限幅器 `release = 100.0`，而这个键的合法上限是 20。两处限幅器都是旁路状态，所以对听感没有影响，但这类越界以前一个都报不出来。

新的校验器自己也做了五类注入测试（改枚举、删键、加键、改数值、换成不认识的插件），确认每类都能报错。整份脚本在源码仓库里：`tools/validate_presets.py`。

六、脉冲响应改名，以及 EasyEffects 的两个坑

卷积器只在 `kernel-name` 变化时才重新读 `.irs` 文件。如果原地覆盖同名文件，修正过的 FIR 不会生效，而且没有任何提示。所以脉冲响应改成带内容哈希的名字：

```text
Nahimic-Factory-X6DR57TK.irs  →  Nahimic-Factory-X6DR57TK-c03355d3.irs
```

改名过程中踩到两个坑：

flatpak 停不掉 现象：`systemctl --user stop` 那个 autostart 服务之后，服务显示 `inactive (dead)`，进程仍在（flatpak 另起了 transient scope）。处理：再停 `app-flatpak-com.github.wwmm.easyeffects-…scope`。
运行态不跟预设走 现象：重启后运行的还是旧 IR，EasyEffects 从 `db/convolverrc` 恢复，不重新读预设里的 `kernel-name`。处理：预设与 `convolverrc` 两边都改。

改完之后 `irs/` 目录里只有一个文件，运行态、预设、磁盘三者一致。预设数量在这一轮的轨迹：

阶段	数量
双变体时期（输出）	38
删掉 11 个 A 变体预设	27
加上 8 个空间预设（电影/游戏）	33
加上 2 个音乐加宽	35

35 = 输出 34 个 + 输入 1 个（采集链的降噪预设），统计时间是 2026-10-06。

七、如何获取本文的工具？

代码见仓库：nahimic-factory-audio-tuning

脚本认这几个环境变量：

变量	用途	默认值
``EASYEFFECTS_DATA``	EasyEffects 数据目录	``~/.var/app/com.github.wwmm.easyeffects/data/easyeffects``
``NAHIMIC_ARCHIVE``	档案根目录	脚本上两级目录
``NAHIMIC_DEVICES``	设备 ``.nsx`` 目录	``$NAHIMIC_ARCHIVE/data/Devices``
``NAHIMIC_DLL``	``NahimicAPO4.dll`` 路径	当前目录下的同名文件

八、还没做的

事项	状态
静态提取 ``NahimicAPO4.dll`` 的内置默认值表	未开始
``VirtualBassBoost`` 的 tanh 驱动量、前置滤波、混合比	未开始
``Ape::SBP::Clarity`` 的真身	未开始
4 个串扰/综合预设是否删除	待定
中频电平	受限：压缩后限制峰值的是 -4.06 dB 的高频段（高音增强 +4 dB 所致）

另外两条已知差异：`bass_enhancer` 是静态的，复现不了出厂那种随音量变化的低音补偿，所以小音量下低音比原厂少、大音量下比原厂多；`-响度` 变体的音量小得离谱（等响度插件多半把 `-12 dB` 当成了播放电平基准），在修好之前不建议使用。

九、省流

判定自己的变体（只读，需要一次 `pkexec`）：

```bash
pkexec /usr/bin/cat /sys/firmware/dmi/tables/DMI > data/smbios/DMI.bin
NAHIMIC_DEVICES="$PWD/data/Devices" \
  python3 tools/read_smbios_oem.py data/smbios/DMI.bin
```

命中哪一个 `<SMBIOS>`，就用哪一个设备档案，不用扫频。

校验预设：

```bash
python3 tools/validate_presets.py
```

选空间效果：先试加宽，串扰那一档在笔记本上大概率不合适。
如果要让 AI Agent 重做一遍，把上一篇那段提示词的第 9 步换掉——变体现在可以判定，不必「由我确认」：

```text
9. 判定扬声器变体：用 UEFI 的 SMBIOS Type 11 OEM 串，与 data/Devices/*.nsx
   里的 <SMBIOS> 精确匹配（tools/read_smbios_oem.py），不要按文件数量猜，
   也不要靠听感或扫频。读 /sys/firmware/dmi/tables/DMI 需要一次只读的 pkexec。
```

被人脸钱包密钥掉包的登录密码

Tue, 06 Oct 2026 00:00:00 GMT

在上次调试好人脸识别后用着还是挺舒服的，突然有一天反欺诈把真人频繁判成了假体。即便我在登录界面里输入正确密码，仍然提示认证失败，只有刷脸能进桌面。

先决条件

```text
CachyOS（Arch 系）｜KDE Plasma 6.7.5｜Plasma Login Manager 6.7.4
Wayland｜biopass-bin 1.4.1｜kwallet 6.30.0｜kwallet-pam 6.7.5
gcc 16.2.1｜pam 1.7.2｜Linux-PAM 1.7.2
```

前期配置（人脸登录、自建 `pam_walletkey` 模块、钱包密钥文件）见人脸登录后的 KWallet 自动解锁。本文只描述那次配置里错误的部分，以及它引发的后果。

注意

下面每一步都在改认证栈。动手前先开一个 root 的 TTY 放着别关（`Ctrl+Alt+F2` 登录），改坏之后就靠它进去了。 `login` / `sshd` 这两条栈里没有本文涉及的任何模块。

四条登录途径

同一台机器上有四个登录入口，我们可以先分清坏的是哪个。

路径	使用的 PAM 服务	状态
登录界面 · 输密码	``/etc/pam.d/plasmalogin``	❌ 认证失败
登录界面 · 人脸	``/etc/pam.d/plasmalogin``	✅ 正常
锁屏 · 输密码	``/etc/pam.d/kde``	✅ 正常
TTY / SSH · 输密码	``/etc/pam.d/login``、``sshd``	✅ 正常

最后两行是反证：同一个密码在 TTY 与 SSH 下能通过，说明密码本身没变，问题出在 `plasmalogin` 这一条栈里。

人脸的可用性会掩盖这个故障。只要人脸一直认得出来，日常使用看不出异常；直到人脸也失败的那天，用户才会去试密码，撞上另一条已经坏掉的入口。

本机人脸失效的原因写在「通用性」一节的旁支里，属另一个故障，不是根因。

排查时间线

提示

以下是第一人称视角的修复记录，您在阅读过程中可能会感觉自己被耍了，所以这里笔者先道歉。

如果你需要省流环节，可以直接跳转到最终方案章节

确定错误路径

先看日志，看看密码到底是在哪一步被拒绝。

```text
10月 05 12:41:55 plasmalogin-helper[2314]: [PAM] Authenticating...
10月 05 12:41:57 plasmalogin-helper[2314]: pam_unix(plasmalogin:auth): authentication failure
```

`pam_unix` 报了认证失败。这时候手上有两条线索：`plasmalogin` 栈里第一行是人脸模块，第二行才是管密码的 `system-login`；而 TTY 与 SSH 用同一个密码能进。

再看认证栈：

```plaintext
-auth       optional    pam_walletkey.so
-auth       optional    pam_kwallet5.so
auth        sufficient  libbiopass_pam.so
auth        include     system-login
```

第一个假设是“登录界面把密码预先塞进了 `PAM_AUTHTOK`，被 `pam_walletkey` 覆盖掉了”。按这个假设，加个“非空就不覆盖”的判断就能解决。

动手之前先把钱包模块的源码翻出来看它究竟做了什么：

```c
int r = pam_set_item(pamh, PAM_AUTHTOK, key);   /* key = 钱包密钥 R，48 位 hex */
```

无条件覆盖，没有“已存在就跳过”的判断。到此为止看起来都对上了。

第一轮：给模块加一个“非空就跳过”的判断

补丁按假设写出来：

```c
/* 若 PAM_AUTHTOK 非空，说明已有密码，绝不覆盖 */
const char *existing = NULL;
if (pam_get_item(pamh, PAM_AUTHTOK, (const void **)&existing) == PAM_SUCCESS
    && existing != NULL && existing[0] != '\0') {
    return PAM_IGNORE;
}
```

编译、双路径安装，再配一个对照脚本：Step 1 用当前模块复现故障，Step 2 换上新模块看是否转好。脚本跑完贴回来的是：

```text
【Step 1】旧模块  => Authentication failure (7)      ✓ 故障复现
【Step 2】新模块  => Authentication failure (7)      ✗ 仍然失败
pam_walletkey: wallet key injected for user neo
```

Step 2 失败了。第一反应是“补丁没装上”，于是核对 `md5`、`strings` 里搜补丁字符串，两样都对得上，模块确实是新的。但日志里那行注入照旧出现。

补丁模块既然装上了，就只可能是一件事：它执行的那一刻 `PAM_AUTHTOK` 是空的。 也就是说，密码并不是登录界面预先塞进去的。

回到 Linux-PAM 的源码去找密码是谁问出来的：

```c
/* 节选自 linux-pam/modules/pam_unix/pam_unix_auth.c */
retval = pam_get_authtok(pamh, PAM_AUTHTOK, &p, NULL);
retval = _unix_verify_password(pamh, name, p, ctrl);
```

密码是 `pam_unix` 自己通过 PAM 对话向界面要的。而 `pam_walletkey` 排在它前面，此刻 authtok 必然为空，条件永远不触发。

`pam_get_authtok()` 在 `PAM_AUTHTOK` 已非空时会直接复用、不再弹框。把两件事连起来，故障的链条是：

```text
用户输入密码  → 密码交给 PAM 对话
pam_walletkey → PAM_AUTHTOK = R       ← 抢在 pam_unix 之前
pam_unix      → 不弹框，直接拿 R 校验 → 认证失败
```

登录界面收到的只是“认证失败”，看不出密码被换过。

第二轮：补丁整套回退

判断转到“位置错了”之后，那个补丁在新位置上反而有害。推演一遍：

把模块挪到 `pam_unix` 之后，它执行时 authtok 里已经是用户登录密码；
补丁版会跳过注入，钱包于是拿到登录密码，而钱包是用密钥 R 重新加密的，解不开；
原版模块无条件注入 R，钱包拿到 R，解锁正常。

`pam_unix` 已经校验完密码，此刻覆盖 `PAM_AUTHTOK` 不影响认证结果，正好是 `pam_kwallet5` 需要的那份数据。结论是把补丁整套回退，模块保持原样，只动 PAM 栈。

第三轮：只改顺序，密码恢复

改动只有一行：把 `pam_walletkey` 挪到 `pam_unix` 之后。验证结果如下：

```text
实验 A1（walletkey 在 unix 前） => Authentication failure (7)   ← 复现故障
V1（复刻栈，真实密码）          => Success (0)
V2（真实 plasmalogin，真实密码）=> Success (0)
```

复现与修复各有一个真值，密码登录恢复。

顺手补一个追踪模块（`pam_sm_authenticate` 里读一次 `PAM_AUTHTOK`，把 `PAM_USER` 与口令长度写进 syslog，返回 `PAM_IGNORE`），把 authtok 的变化打出来：

```text
pam_trace_authtok[1-before-unix]:     authtok=NULL
pam_trace_authtok[2-after-unix]:      authtok=SET(len=25)       ← 25 位 = 用户密码
pam_walletkey: wallet key injected for user neo
pam_trace_authtok[3-after-walletkey]: authtok=SET(len=48)       ← 校验完才被钱包密钥覆盖
```

修复前在同一位置打出来的是 `authtok=SET(len=48)` 紧跟 `pam_unix: authentication failure`。两处长度不相等，`pam_unix` 手里拿的确实是钱包密钥。具体长度取决于当时的密码，不要拿数字本身当结论。

对真实 `plasmalogin` 服务跑过认证探针（`pam_authenticate()`，只做认证判定、不建立会话），用错误密码与正确密码各跑一轮，上面这些时序取自它。探针不改变任何会话状态。

第四轮：钱包又打不开了

这一轮的价值不大，笔者利用 AI 进行排查时走了弯路。

密码通了，注销再登录，KWallet 恼人的认证弹窗还是弹出。

翻这一轮的日志，`pam_kwallet5` 的 auth 阶段执行了，却没有存下口令：

```text
pam_kwallet5(plasmalogin:auth): pam_kwallet5: pam_sm_authenticate
```

原因在上一轮留下的位置：`pam_kwallet5` 被落在了 `pam_unix` 前面，它执行时 authtok 还是空的，`pam_sm_authenticate` 记下“没拿到密码”就返回， `kwallet5_key` 这个数据槽没人填。把它也挪到 `pam_walletkey` 之后：

```bash
journalctl -b 0 --no-pager | grep pam_kwallet5 | tail -3
# → pam_kwallet5: final socket path: /run/user/1000/kwallet5.socket
```

密码路径的钱包恢复正常。到这里得到两条硬约束：

`pam_walletkey` 必须在 `pam_unix` 之后。 排在前面，密码被 R 掉包，密码登录失败。
`pam_kwallet5` 必须在 `pam_walletkey` 之后。 排在前面，auth 阶段拿不到 R，钱包打不开。

两条拼起来，顺序只能是 `libbiopass` → `pam_unix` → `pam_walletkey` → `pam_kwallet5`。

第五轮：四条路径一测，窟窿露出来了

注销、登录、锁屏各试一遍，得到的是：

注销用人脸还是会弹 kwallet，注销用密码、锁屏用密码不会。

同一次会话里的两行日志：

```text
pam_walletkey: wallet key injected                                           ← 密码登录，钱包正常
pam_kwallet5(plasmalogin:session): open_session called without kwallet5_key  ← 人脸登录，钱包打不开
```

`libbiopass_pam.so` 标着 `sufficient`。它的语义是“成功即放行、并且终止整条栈”，人脸认得出来时，排在它后面的 `pam_walletkey` / `pam_kwallet5` 一行都不会执行。

两个方向，各坏一条路径
- 钱包行放 `sufficient` 之前：人脸路径正常，`pam_unix` 拿不到用户密码，密码登录失败。
- 钱包行放 `sufficient` 之后：密码路径正常，人脸成功即终止栈，`kwallet5_key` 没人填。

`sufficient` 短路与 `PAM_AUTHTOK` 覆盖，两件事在同一个线性 auth 栈里无法同时满足。配置本身没有写错，是 auth 栈这个结构装不下这两条需求。

第六轮：绕过 authtok，自己拉起 ksecretd

auth 栈里摆不开，就把这件事挪到 session 阶段去做。`pam_kwallet5` 的 session 阶段无非是“拿口令 → 派生密钥 → 拉起 `ksecretd`”，那就自己写个程序全做完：

读 `/etc/pam_walletkey.key` 拿钱包口令 R
读 `~/.local/share/kwalletd/kdewallet.salt`，用 PBKDF2-HMAC-SHA512（50000 轮，56 字节）派生主密钥，与 `pam_kwallet5` 同一套算法
`fork` + 降权到目标用户，`exec /usr/bin/ksecretd --pam-login <pipe_fd> <socket_fd>`，把 56 字节密钥写进管道

PAM 侧用 `pam_exec` 调它：

```plaintext
session     optional    pam_exec.so  quiet /usr/local/libexec/kwallet-pam-unlock
```

为了一致，`pam_kwallet.c` 的 `execute_kwallet()` 里那些细节都照抄了： pipe fd 作为参数传递而不是 `dup` 到标准输入、给无关 fd 设 `FD_CLOEXEC` 但保留 pipe fd、 socket 绑到 `$XDG_RUNTIME_DIR/kwallet5.socket`。还加了“已有活着的 `ksecretd` 就跳过”的护栏，避免两个实例同时操作 `kdewallet.kwl`。

装上执行，拿到的是：

```text
Configuration file "/root/.config/ksecretdrc" not writable.
Please contact your system administrator.
```

`setuid` 到目标用户了，但没改环境变量，`ksecretd` 继承的 `HOME` 还是 `/root`。补上 `setenv("HOME", pw->pw_dir, 1)` 以及 `USER`、`LOGNAME`、`SHELL`，再跑：

```text
kwallet-pam-unlock: ksecretd exited immediately (status=134) — wallet likely NOT unlocked
pam_exec(plasmalogin:session): /usr/local/libexec/kwallet-pam-unlock failed: exit code 1
```

`134 = 128 + 6`，SIGABRT。`ksecretd` 是 Qt 程序，PAM 的 session 阶段此时图形会话还没起来，没有 `WAYLAND_DISPLAY`、没有可用的 DBus 会话总线，它拿不到平台插件就 abort。

`ksecretd` 的 stderr 原文没有采集到（诊断脚本写好了没用上）， “缺图形环境”是从崩溃时机与 `status=134` 推出来的判断。

到这里停一下，回去翻这一整段时间的日志，里面有一行早就存在的记录：

```text
10月 05 22:58:22 neo ksecretd[48357]: Using kwallet without parent window!
```

`ksecretd` 本来就能被 D-Bus 自动拉起。这一轮在重新实现一件不需要重新实现的事，实现的细节还比原装实现更多。

第七轮：把缺的那一格数据补上

换思路：不碰 `ksecretd`，只补 `pam_kwallet5` 缺的那份数据。它的两段式设计是这样的：

`pam_sm_authenticate`: 用 `pam_get_item(PAM_AUTHTOK)` 取口令；为空则 `PAM_IGNORE`；取到后 `pam_set_data("kwallet5_key", 口令)`。
`pam_sm_open_session`: 读 `pam_get_data("kwallet5_key")`，派生密钥，拉起 `ksecretd`。

人脸路径上 auth 阶段被 `sufficient` 短路，session 阶段就扑空：

```text
pam_kwallet5(plasmalogin:session): open_session called without kwallet5_key
```

缺的是数据槽里那一格。 那就写一个只在 session 阶段干活的模块，位置排在 `pam_kwallet5` 之前：

```plaintext
session     optional    pam_session_walletkey.so        ← 新增：补 kwallet5_key
-session    optional    pam_kwallet5.so         auto_start
```

模块只做三件事：

幂等检查：`pam_get_data(pamh, "kwallet5_key")` 命中就直接跳过（密码路径已由 auth 阶段存过，于是零影响）
未命中则读 `/etc/pam_walletkey.key` 拿到 R
`pam_set_data(pamh, "kwallet5_key", strdup(R), cleanup_wipe)`，并用清理回调在句柄释放时擦除内存里的口令

取值语义核对过 KDE 上游 `pam_kwallet.c`：数据槽里放的是口令字符串，不是派生密钥，所以这里直接放 R，不做 PBKDF2。（`kwallet5_key` 这个键名必须与 `kwalletPamDataKey` 一致。）

装上之后，两条分支都在日志里出现了，输出见下面「验证」一节。

最终方案

`/etc/pam.d/plasmalogin` 最后长这样：

```ini
#%PAM-1.0

# ---- Biopass 人脸认证（Plasma Login Manager 专用；失败自动回退密码）----
# 钱包两行放在 sufficient 之后：人脸路径被它短路、根本走不到；
# 密码路径走到时 pam_unix 已经问完密码，此刻注入钱包密钥不影响认证结果。
auth        sufficient  libbiopass_pam.so
auth        include     system-login
-auth       optional    pam_walletkey.so
-auth       optional    pam_kwallet5.so
-auth       optional    pam_gnome_keyring.so

account     include     system-login

password    include     system-login
-password   optional    pam_gnome_keyring.so    use_authtok

session     optional    pam_keyinit.so          force revoke
session     include     system-login
-session    optional    pam_gnome_keyring.so    auto_start
# 人脸路径的 auth 阶段被 sufficient 短路，kwallet5_key 没人放；
# 这一行在 session 阶段把它补上，解锁仍由下面的 pam_kwallet5 完成。
session     optional    pam_session_walletkey.so
-session    optional    pam_kwallet5.so         auto_start
```

与 09-25 那版的差别只有两处：钱包两行移到 `system-login` 之后； session 段加一行。

安装

模块源码与安装脚本：

```c
/*
 * pam_session_walletkey.c — 在 session 阶段把钱包口令喂给 pam_kwallet5
 *
 * ── 它解决什么问题 ─────────────────────────────────────────────────
 * plasmalogin 的 auth 栈：
 *     auth  sufficient  libbiopass_pam.so   <- 人脸成功即【终止整个 auth 栈】
 *     auth  include     system-login
 *     -auth optional    pam_walletkey.so    <- 人脸路径到不了
 *     -auth optional    pam_kwallet5.so     <- 人脸路径到不了
 *
 * pam_kwallet5 是两段式设计：
 *     auth 阶段：pam_get_item(PAM_AUTHTOK) -> pam_set_data("kwallet5_key")
 *     session 阶段：pam_get_data("kwallet5_key") -> 派生密钥 -> 拉起 ksecretd
 *
 * 人脸路径被 sufficient 短路后，auth 阶段没跑，session 阶段就只说
 *     "open_session called without kwallet5_key"
 * 然后钱包锁死、弹窗。
 *
 * ── 本模块的做法 ───────────────────────────────────────────────────
 * 不重造 pam_kwallet5 的轮子（那要处理 ksecretd 的私有 pipe/socket 协议，
 * 实测 ksecretd 会因缺图形环境直接 SIGABRT）。改为在最合适的位置补上
 * 缺失的那一环：
 *
 *     在 session 阶段读 /etc/pam_walletkey.key，把口令用
 *     pam_set_data(pamh, "kwallet5_key", …) 放进 PAM 句柄
 *
 * 只要本模块排在 pam_kwallet5 的 session 行【之前】，后面的 pam_kwallet5
 * 就会正常派生密钥并拉起 ksecretd —— 用 KDE 自己的、经过考验的实现。
 *
 * ── 幂等性 ─────────────────────────────────────────────────────────
 * 若 auth 阶段已经存过 kwallet5_key（密码登录路径），本模块直接跳过，
 * 不覆盖已存在的值。因此对密码路径是零影响，只补人脸路径的缺口。
 *
 * ── PAM 用法 ───────────────────────────────────────────────────────
 *     session  optional  pam_session_walletkey.so
 *
 * 安装位置：/usr/lib/security/pam_session_walletkey.so
 *
 * 编译：
 *   gcc -O2 -fPIC -shared -o pam_session_walletkey.so \
 *       pam_session_walletkey.c $(pkg-config --cflags pam 2>/dev/null)
 *
 * SPDX-License-Identifier: MIT
 */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <syslog.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <pwd.h>

#include <security/pam_modules.h>
#include <security/_pam_types.h>

#define KEYFILE_DEFAULT "/etc/pam_walletkey.key"
#define MAXKEY          1024
#define DATA_KEY        "kwallet5_key"   /* 必须与 pam_kwallet.c 的 kwalletPamDataKey 一致 */

static void wipe(char *s)
{
    if (!s)
        return;
    volatile char *p = s;
    while (*p)
        *(p++) = 0;
}

/* pam_set_data 的清理回调：PAM 释放句柄时擦除我们放进去的口令 */
static void cleanup_wipe(pam_handle_t *pamh, void *data, int error_status)
{
    (void)pamh;
    (void)error_status;
    if (data) {
        wipe((char *)data);
        free(data);
    }
}

static int read_key(const char *path, char *buf, size_t bufsz)
{
    struct stat st;

    if (stat(path, &st) != 0 || !S_ISREG(st.st_mode)) {
        syslog(LOG_WARNING, "pam_session_walletkey: cannot stat %s", path);
        return -1;
    }
    /* 不检查 st_uid==0：PAM 在 user namespace 里读到的属主可能被映射，
     * 检查会误判。真正要紧的是没有 group/other 权限。 */
    if ((st.st_mode & (S_IRWXG | S_IRWXO)) != 0) {
        syslog(LOG_WARNING, "pam_session_walletkey: %s has group/other perms (mode=%o) — refusing",
               path, st.st_mode & 07777);
        return -1;
    }

    FILE *f = fopen(path, "r");
    if (!f) {
        syslog(LOG_WARNING, "pam_session_walletkey: cannot open %s", path);
        return -1;
    }
    if (!fgets(buf, (int)bufsz, f)) {
        fclose(f);
        syslog(LOG_WARNING, "pam_session_walletkey: cannot read %s", path);
        return -1;
    }
    fclose(f);

    size_t n = strcspn(buf, "\r\n");
    buf[n] = '\0';
    return n == 0 ? -1 : 0;
}

PAM_EXTERN int pam_sm_open_session(pam_handle_t *pamh, int flags,
                                   int argc, const char **argv)
{
    (void)flags;

    const char *keyfile = KEYFILE_DEFAULT;
    for (int i = 0; i < argc; i++) {
        if (strncmp(argv[i], "keyfile=", 8) == 0 && argv[i][8] != '\0')
            keyfile = argv[i] + 8;
    }

    const char *user = NULL;
    if (pam_get_user(pamh, &user, NULL) != PAM_SUCCESS || !user || !*user) {
        syslog(LOG_WARNING, "pam_session_walletkey: cannot get user; skipping");
        return PAM_IGNORE;
    }

    struct passwd *pw = getpwnam(user);
    if (pw && pw->pw_uid == 0) {
        /* root 不需要解锁钱包 */
        return PAM_IGNORE;
    }

    /* 幂等：auth 阶段已经存过就不动它（密码登录路径走这里） */
    const void *existing = NULL;
    if (pam_get_data(pamh, DATA_KEY, &existing) == PAM_SUCCESS && existing) {
        syslog(LOG_INFO,
               "pam_session_walletkey: %s already set by auth phase; leaving as-is", DATA_KEY);
        return PAM_IGNORE;
    }

    char key[MAXKEY] = {0};
    if (read_key(keyfile, key, sizeof(key)) != 0) {
        wipe(key);
        return PAM_IGNORE;   /* 绝不阻断登录 */
    }

    char *stored = strdup(key);
    wipe(key);
    if (!stored) {
        syslog(LOG_ERR, "pam_session_walletkey: out of memory");
        return PAM_IGNORE;
    }

    int r = pam_set_data(pamh, DATA_KEY, stored, cleanup_wipe);
    if (r != PAM_SUCCESS) {
        syslog(LOG_ERR, "pam_session_walletkey: pam_set_data failed (rc=%d)", r);
        cleanup_wipe(pamh, stored, 0);
        return PAM_IGNORE;
    }

    syslog(LOG_INFO,
           "pam_session_walletkey: injected wallet key into %s for user=%s (len=%zu)",
           DATA_KEY, user, strlen(stored));

    return PAM_SUCCESS;
}

PAM_EXTERN int pam_sm_close_session(pam_handle_t *pamh, int flags,
                                    int argc, const char **argv)
{
    (void)pamh; (void)flags; (void)argc; (void)argv;
    return PAM_SUCCESS;
}
```

```bash
#!/bin/bash
#
# install-session-walletkey.sh — 安装 pam_session_walletkey（session 阶段补 kwallet5_key）
#
# ── 它解决什么问题 ──────────────────────────────────────────────────
# plasmalogin 的 auth 栈里，libbiopass_pam.so 标着 sufficient：人脸成功即终止
# 整个 auth 栈。排在它后面的 pam_walletkey / pam_kwallet5 永远不执行，于是
# pam_kwallet5 的 session 阶段拿不到 kwallet5_key，钱包照样弹窗。
#
# 而把钱包两行挪到 sufficient 之前，pam_walletkey 会抢在 pam_unix 之前把
# PAM_AUTHTOK 换成钱包密钥，密码登录被打死。两条路都通不了。
#
# 解法是绕开 auth 阶段的顺序之争：认证方式定完以后，在 session 阶段把口令
# 直接补进 PAM 句柄，解锁仍由 KDE 自己的 pam_kwallet5 完成。
#
#     session  optional  pam_session_walletkey.so        <- 新增：补 kwallet5_key
#     -session optional  pam_kwallet5.so  auto_start     <- 原有：正常解锁
#
# 幂等：auth 阶段已经存过（密码登录路径）则跳过，对密码路径零影响。
#
# 用法：sudo bash install-session-walletkey.sh
#
# SPDX-License-Identifier: MIT

set -u

DEST="/usr/lib/security/pam_session_walletkey.so"
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SRC="${SCRIPT_DIR}/pam_session_walletkey.c"
OLD_HELPER="/usr/local/libexec/kwallet-pam-unlock"
STAMP="$(date +%F)"

if [[ $EUID -ne 0 ]]; then
    echo "需要 root，请用：sudo bash $0" >&2
    exit 1
fi

[[ -f "${SRC}" ]] || { echo "找不到 ${SRC}" >&2; exit 1; }

echo "==================================================================="
echo " 安装 pam_session_walletkey（session 阶段补 kwallet5_key）"
echo "==================================================================="

echo
echo "[1/6] 现场重编译并安装模块"
gcc -O2 -fPIC -shared -Wall -Wextra -o /tmp/pam_session_walletkey.so "${SRC}" 2>&1 \
    || { echo "编译失败，中止" >&2; exit 1; }
install -m 0755 -o root -g root /tmp/pam_session_walletkey.so "${DEST}"
rm -f /tmp/pam_session_walletkey.so
ls -la "${DEST}"

echo
echo "[2/6] 移除早前那版 pam_exec 钩子（若装过）"
for f in /etc/pam.d/plasmalogin /etc/pam.d/plasmalogin-autologin; do
    if grep -q "kwallet-pam-unlock" "$f"; then
        grep -v "kwallet-pam-unlock" "$f" > "${f}.tmp"
        mv "${f}.tmp" "$f"
        chown root:root "$f"; chmod 644 "$f"
        echo "  ${f}: 已移除旧钩子"
    else
        echo "  ${f}: 无旧钩子"
    fi
done
# 顺手清掉那个跑不起来的 helper（源码留在归档里备查）
if [[ -e "${OLD_HELPER}" ]]; then
    rm -f "${OLD_HELPER}"
    echo "  已删除 ${OLD_HELPER}"
fi

echo
echo "[3/6] 备份当前 PAM 文件"
for f in /etc/pam.d/plasmalogin /etc/pam.d/plasmalogin-autologin; do
    cp -a "$f" "${f}.pre-sessionwallet-${STAMP}"
    echo "  ${f}.pre-sessionwallet-${STAMP}"
done

echo
echo "[4/6] 在 pam_kwallet5 之前插入模块"
python3 - <<'PYEOF'
MODULE_LINE = "session     optional    pam_session_walletkey.so"

for path in ("/etc/pam.d/plasmalogin", "/etc/pam.d/plasmalogin-autologin"):
    lines = open(path, encoding="utf-8").read().splitlines()

    if any("pam_session_walletkey.so" in l for l in lines):
        print(f"  {path}: 已存在，跳过")
        continue

    out, inserted = [], False
    for ln in lines:
        # 在 pam_kwallet5 的 session 行之前插入
        s = ln.strip()
        if (not inserted) and s.startswith("-session") and "pam_kwallet5.so" in s:
            out.append(MODULE_LINE)
            inserted = True
        out.append(ln)

    if not inserted:
        # 没有 pam_kwallet5 的 session 行：追加到末尾
        out.append(MODULE_LINE)

    open(path, "w", encoding="utf-8").write("\n".join(out) + "\n")
    print(f"  {path}: 已插入")
PYEOF

for f in /etc/pam.d/plasmalogin /etc/pam.d/plasmalogin-autologin; do
    chown root:root "$f"; chmod 644 "$f"
done

echo
echo "[5/6] 结果"
for f in /etc/pam.d/plasmalogin /etc/pam.d/plasmalogin-autologin; do
    echo "  --- ${f} ---"
    grep -n -E "^\s*-?session" "$f" | sed 's/^/    /'
done

echo
echo "[6/6] 清掉可能残留的死 socket"
echo "-------------------------------------------------------------------"
target="${SUDO_USER:-$(id -un)}"
if pgrep -u "${target}" ksecretd >/dev/null 2>&1; then
    echo "  ${target} 名下已跑着 ksecretd（钱包已解锁），无需处理"
else
    runtime_dir="/run/user/$(id -u "${target}")"
    if [[ -e "${runtime_dir}/kwallet5.socket" ]]; then
        rm -f "${runtime_dir}/kwallet5.socket" && echo "  已清理 ${runtime_dir}/kwallet5.socket"
    else
        echo "  ${runtime_dir} 下没有残留 socket"
    fi
fi

cat <<EOF

===================================================================
 下一步验证（三条路径都要走一遍，缺一条就可能漏掉一个入口）：
   1. 注销 → 用【人脸】登录 → 观察是否还弹「KDE 密码库服务」
   2. 注销 → 用【密码】登录 → 必须仍然正常（不能退化）
   3. 锁屏 → 用密码解锁   → 必须仍然正常

 验证时留意日志中新模块的痕迹：
   journalctl -b 0 --no-pager | grep -E 'pam_session_walletkey|pam_kwallet5|ksecretd' | tail -30

 回滚（一条命令）：
   sudo cp -a /etc/pam.d/plasmalogin.pre-sessionwallet-${STAMP} /etc/pam.d/plasmalogin
   sudo cp -a /etc/pam.d/plasmalogin-autologin.pre-sessionwallet-${STAMP} /etc/pam.d/plasmalogin-autologin
   sudo rm -f ${DEST}
===================================================================
EOF
```

先确认模块能编译、且只依赖 libpam 与 libc：

```bash
gcc -O2 -fPIC -shared -Wall -Wextra -o pam_session_walletkey.so pam_session_walletkey.c
nm -D --defined-only pam_session_walletkey.so | grep pam_sm   # → pam_sm_open_session / pam_sm_close_session
nm -D --undefined-only pam_session_walletkey.so               # 只应有 libc 与 libpam 的符号
```

脚本要做 root 权限的事（装模块、改两个 PAM 文件、备份），所以用 `sudo` 跑：

```bash
sudo bash install-session-walletkey.sh
```

它会现场重编译、备份 `/etc/pam.d/plasmalogin{,-autologin}`、把新模块插到 `pam_kwallet5` 的 session 行之前。

验证

新模块的两条分支都要在日志里看到，它们分别证密码路径与人脸路径：

```bash
journalctl -b 0 --no-pager | grep -E 'pam_session_walletkey|pam_walletkey|pam_kwallet5|ksecretd' | tail -30
```

```text
# 人脸登录：auth 阶段被短路，本模块补上数据槽
pam_session_walletkey: injected wallet key into kwallet5_key for user=neo (len=48)
pam_kwallet5(plasmalogin:session): pam_kwallet5: pam_sm_open_session

# 密码登录：auth 阶段已经存过，本模块跳过
pam_walletkey: wallet key injected for user neo
pam_session_walletkey: kwallet5_key already set by auth phase; leaving as-is
pam_kwallet5(plasmalogin:session): pam_kwallet5: pam_sm_open_session
```

判据是两件事：

不再出现 `open_session called without kwallet5_key`
三条路径都要走一遍：人脸登录、密码登录、锁屏密码解锁。 只验钱包那一条会漏掉密码路径 —— 前面那次配置就是这么漏掉 10 天的。

钱包解锁成功的标志：

```text
pam_kwallet5: final socket path: /run/user/1000/kwallet5.socket
```

`final socket path` 是 `start_kwallet()` 被调用的痕迹。随后 `ksecretd` 的 `Failed to register with host portal ... Connection already associated with an application ID` 是 xdg-desktop-portal 的注册冲突，同一 app ID 已被旧实例占用，不影响钱包解锁。

另外，读者要在自己机器上判断“钱包这次到底开没开”，可以看这两个东西：

```bash
pgrep -a ksecretd                              # 有人脸/密码登录后应该能看到它
ls -l /run/user/$(id -u)/kwallet5.socket       # 存在且有监听者 = 已解锁
```

通用性

本文的故障机制 —— ✅ 通用。任何“在 `pam_unix` 之前往 `PAM_AUTHTOK` 写值”的模块都会打死密码登录。
`sufficient` 短路 —— ✅ 通用。它是 PAM 的调度语义，与发行版无关。
`kwallet5_key` 这个键名 —— ⚠️ 与 `kwallet-pam` 的版本绑定，升级后要重新核对上游 `kwalletPamDataKey`。
`ksecretd` 作为 Secret Service —— ⚠️ 本机是 Plasma 6 的默认守护进程。用 `kwalletd5` / `kwalletd6` 的环境，路径与 socket 名都不同。
自建模块的必要性 —— ⚠️ 只在“钱包密钥与登录密码不同值、且要保留钱包静态加密”时才需要。
本文的 PAM 文件 —— ❌ 别整份照抄。`libbiopass_pam.so`、`pam_exec` 闸门那些行是本机特有的。

改动只涉及两个 PAM 文件与该模块，`/etc/pam.d/kde`（锁屏）与 `login`、`sshd` 没动。

旁支：人脸为什么会突然不认

同一时间段里人脸也失败过，那是另一个故障。`~/.local/share/com.ticklab.biopass/logs/` 里当天的记录：

```text
[2026-10-05 12:40:12.792] [warning] FaceAuth: AI anti-spoofing detected spoof, score: 0.95140916
[2026-10-05 12:40:31.196] [warning] FaceAuth: AI anti-spoofing detected spoof, score: 0.8837554
[2026-10-05 11:46:19.760] [warning] FaceAuth: AI anti-spoofing detected spoof, score: 0.95708305
```

阈值是 `anti_spoofing.threshold: 0.8`，真人被判成假体，而且这类失败不重试（配置里的 `retries: 5` 对反欺诈失败不生效）。两天前的记录是正常的：

```text
[2026-10-03 14:49:09.256] [debug] FaceAuth: AI anti-spoofing check passed
[2026-10-03 14:49:09.299] [debug] FaceAuth: Recognition PASSED | score=0.5531
```

同样的相机和阈值，10-03 通过、10-05 判假。变化的原因没有查到，推测是有其他人出现在镜头中。

排错表

密码登录失败，日志里 `pam_unix(plasmalogin:auth): authentication failure` 后面没有 `wallet key injected`
- 可能原因：登录界面根本没把密码交给 `pam_unix`，或是 `pam_faillock` 已经把这个用户锁了。
- 怎么办：`faillock --user <用户名>` 看计数；`journalctl -b | grep -E 'faillock|pam_unix\(plasmalogin'` 对齐时间。
密码登录失败，且失败前有 `wallet key injected`
- 可能原因：`pam_walletkey` 又排到 `pam_unix` 前面去了，密码被钱包密钥顶掉。
- 怎么办：`grep -nE 'pam_walletkey|pam_unix' /etc/pam.d/plasmalogin`，钱包行必须在 `include system-login` 之后。
人脸登录后仍弹「KDE 密码库服务」
- 可能原因：`pam_session_walletkey` 没执行，或没排在 `pam_kwallet5` 之前。
- 怎么办：`journalctl -b | grep pam_session_walletkey`。没有任何输出说明这一行没生效；有输出但仍是 `open_session called without kwallet5_key`，说明插入位置在 `pam_kwallet5` 之后。
`pam_session_walletkey` 报 `has group/other perms ... refusing`
- 可能原因：`/etc/pam_walletkey.key` 权限被改宽了。模块按设计要求拒绝读它。
- 怎么办：`chmod 600 /etc/pam_walletkey.key`，属主 `root:root`。模块不检查属主 UID，因为在用户命名空间里读到的属主可能被映射。
登录后钱包还是锁的，但日志一切正常
- 可能原因：`~/.local/share/kwalletd/kdewallet.kwl` 的密码与 `/etc/pam_walletkey.key` 里的值不一致。
- 怎么办：按 KWallet 的提示手动解锁一次，然后把钱包密码重设成密钥文件里的值；两边一致之后再试一次登录。

回滚

只摘掉新增的那一行：

```bash
sudo sed -i '/pam_session_walletkey/d' /etc/pam.d/plasmalogin /etc/pam.d/plasmalogin-autologin
sudo rm -f /usr/lib/security/pam_session_walletkey.so
```

回到安装前的完整状态（安装脚本留下的备份）：

```bash
sudo cp -a /etc/pam.d/plasmalogin.pre-sessionwallet-<日期> /etc/pam.d/plasmalogin
sudo cp -a /etc/pam.d/plasmalogin-autologin.pre-sessionwallet-<日期> /etc/pam.d/plasmalogin-autologin
```

警告

不要回滚到 09-25 那份配置（钱包两行在 `sufficient` 之前的那版）。那份会让密码登录再次失效。

尚未验证的地方

`ksecretd` 的 SIGABRT 原文：没有采集到 stderr，“缺图形环境”是推断。
反欺诈为什么在 10-05 突然误判：没查明。
故障期的失败次数：`journalctl` 只保留到 10-05 中午， 09-25 到 10-05 之间的登录日志已经不在了，这段时间的失败次数无法从日志复核。能复核的是机制：只要配置是那样，密码路径就不可能通过。

参考

https://github.com/linux-pam/linux-pam/blob/master/libpam/pam_dispatch.c —— `sufficient` 与跳转的调度实现
https://github.com/linux-pam/linux-pam/blob/master/modules/pam_unix/pam_unix_auth.c —— `PAM_AUTHTOK` 由 `pam_get_authtok()` 写入
https://invent.kde.org/plasma/kwallet-pam/-/raw/master/pam_kwallet.c —— `kwallet5_key` 的写入与读取

人脸登录后的 KWallet 自动解锁

Fri, 25 Sep 2026 00:00:00 GMT

在很长一段时间里，虽然我已经利用 `biopass` 实现了人脸识别登录，但是我的使用率却相当低。虽然人脸已经识别成功，桌面也进去了，但是 KWallet 却弹出解锁框提示输入密码。即便把 `pam_kwallet5.so` 往前挪一行，通常也不会解决问题。

先决条件

```text
CachyOS（Arch 系）｜KDE Plasma 6.7.5｜Plasma Login Manager 6.7.4
Wayland｜biopass-bin 1.4.1｜kwallet 6.30.0｜kwallet-pam 6.7.5
gcc 16.2.1｜pam 1.7.2
```

本机使用 `ksecretd` 作为 Plasma 6 的 Secret Service 守护进程（它也是 kwallet-pam 6.7.5 编译时的默认守护进程），钱包名是 `kdewallet`。磁盘没有 LUKS，`/etc/crypttab` 为空，所以不存在“开机解锁磁盘时顺便拿到钱包密码”的条件。

需要编译一个小模块，所以机器上要有 C 编译器和 PAM 开发头文件（Arch 系在 `pam` 包里）。下面的 PAM 文件路径、用户名和密钥路径都是示例，实际安装前先确认发行版的 PAM 包、登录管理器和钱包版本；不要把本机的 `/etc` 配置原样覆盖到另一台机器。

现象

人脸登录成功后，PLM 的日志里能看到 `pam_kwallet5` 走到了 session 阶段，但紧接着是：

```text
pam_kwallet5(plasmalogin:session): open_session called without kwallet5_key
```

同一会话里还有两条旁证：环境变量 `PAM_KWALLET5_LOGIN` 不存在，`/run/user/<uid>/kwallet5.socket` 也不存在。这两样是钱包解锁成功才会有的东西。

```bash
# 钱包到底开没开（true = 已解锁）
busctl --user call org.kde.kwalletd6 /modules/kwalletd6 \
  org.kde.KWallet isOpen s kdewallet

journalctl -b -u plasmalogin | grep -i pam_kwallet5
```

先把认证栈和 `pam_kwallet5` 的取值路径对上，再决定要不要改钱包密码。

PAM 的两段：auth 与 session

要理解钱包为什么不开，得先分清 PAM 里两个阶段各自发生什么。`pam_kwallet5` 的工作是分开的（下面按官方 `pam_kwallet.c` 的行为描述）：

auth 阶段——拿密码，存起来：

`pam_get_item(PAM_AUTHTOK)` 取当前认证口令；
为空的话它会尝试自己弹窗问一次；
还是空，就直接返回 `PAM_IGNORE`，源码里的日志原文是 `Empty or missing password, doing nothing`；
拿到了，就用 `pam_set_data("kwallet5_key", 密码)` 把它挂在 PAM handle 上。

session 阶段（配置行里的 `auto_start`）——用密码开钱包：

把上一步的 `kwallet5_key` 取出来；
拿 `~/.local/share/kwalletd/kdewallet.salt` 当盐，做 PBKDF2（SHA512，50000 轮，输出 56 字节）派生钱包密钥；
以用户身份拉起 `ksecretd --pam-login <管道> <套接字>`，把密钥写进管道，完成解锁。

关键在第一步和第二步之间的唯一桥梁就是那串密码。也就是说，钱包的密码必须等于 `PAM_AUTHTOK` 里的东西，否则派生出来的密钥打不开钱包文件。这是后面所有方案的出发点。

钱包为什么拿不到密码

``sufficient`` 会把后面的模块整组跳过

`man pam.conf` 对 `sufficient` 的定义是：该模块成功时，如果前面没有 required 模块失败，PAM 立即向应用返回成功，跳过本组剩余模块。

本机原始的授权栈顺序是：

`auth sufficient libbiopass_pam.so` ← 人脸成功，授权栈就地结束
`auth include system-login`（`pam_unix` 密码）
`-auth optional pam_kwallet5.so` ← 永远走不到

所以只要刷脸成功，`pam_kwallet5` 的 auth 钩子根本不执行，密码也就没机会被存下来给 session 阶段用。

就算把顺序调过来，人脸也交不出密码

把 `pam_kwallet5` 挪到 biopass 前面，它能执行了，但 `pam_get_item(PAM_AUTHTOK)` 仍然取不到东西。原因在 biopass 的 PAM 模块（按符号表核对）：它只调用 `pam_get_item` 和 `pam_get_user`，然后 `fork` 加 `execl("/usr/bin/biopass-helper", "--service", <服务名>, "--username", <用户>, "auth")`，从头到尾没有调用过 `pam_set_item`。

人脸识别不产生任何可交给钱包的字符串。所以我们可以得出结论：

人脸或指纹登录 + 标准 `pam_kwallet5` = 钱包无法自动解锁。 除非密码从别处来——用户手输，或者我们自己注入。

官方与社区结论一致。Arch Wiki 的 KDE Wallet 条目明确列出这条限制（用指纹读卡器登录时钱包无法解锁），并说明自动解锁的前提是钱包名 `kdewallet`、blowfish 加密、且钱包密码等于用户登录密码。KDE bug 468069（CONFIRMED）还表明，即使在“钱包密码为空 + 没有 PAM 凭据”的情况下，KDE 也不保证自动打开钱包。

两条错误路径

只移动 ``pam_kwallet5``

这只能解决 `sufficient` 提前结束的问题，不能创造 `PAM_AUTHTOK`。如果日志从“模块没执行”变成“没有密码”，根因仍然是同一个。

借用 LUKS 的开机密码

有些方案让磁盘解密密码和钱包密码相同，再由 `pam_systemd_loadkey` 转交给钱包。本机 `/etc/crypttab` 为空，磁盘没有 LUKS，这条路径没有可借用的密钥。

方案选择

方案	结果	代价
清空钱包密码	不再需要输入密码	钱包文件等同未加密
保持现状	登录后手动解锁	每次都要输一次密码
自建 PAM 模块	注入独立密钥，保留加密	多维护一个模块，密钥须由 root 保护

本机采用第三种，理由是希望保留钱包文件的静态加密：非 root 的攻击者即使拿到 `kdewallet.kwl`，没有 `/etc/pam_walletkey.key` 也解不开。而“清空密码”那条路等于把钱包变成明文文件，任何人读到你的家目录或备份都能拿到里面的 WiFi 密码、浏览器登录态和令牌。

第三种方案的三条设计边界：

密钥和登录密码不是同一个值。 钱包改用一个随机长串，登录密码照旧。
密钥只存在于 root 可读的文件里。 普通用户读不到，模块本身也不打印它。
模块读不到密钥时返回 `PAM_IGNORE`，钱包回到手动解锁。 不能因为钱包配置错误把用户锁在登录界面外。

自建模块做什么

模块只做一件事：把一个受保护文件的第一行写进 `PAM_AUTHTOK`。它要满足的校验条件：

路径存在，而且是普通文件（不是符号链接、不是目录）；
属主必须是 root；
group 和 other 不能有任何权限位；
内容不能为空；
写进 PAM 之后立刻清掉本地临时缓冲区。

任何一条不满足，就记一条警告日志并返回 `PAM_IGNORE`，绝不阻断登录。PAM 行上的 `optional` 控制位是第二层保险。

```c
/*
 * pam_walletkey.so — 把 root 只读密钥文件中的 KWallet 密码注入 PAM_AUTHTOK
 *
 * 用途：biopass（人脸/指纹）登录不会产生密码，导致 pam_kwallet5 拿不到
 *      PAM_AUTHTOK，KWallet 无法自动解锁。本模块在 auth 阶段把预先约定的
 *      钱包密码写入 PAM_AUTHTOK，紧随其后的 pam_kwallet5 即可正常存下并
 *      在 session 阶段解锁 kdewallet。
 *
 * 安装位置：/usr/lib/security/pam_walletkey.so
 * 密钥文件：/etc/pam_walletkey.key （root:root 0600，单行，仅含钱包密码）
 * PAM 用法：-auth optional pam_walletkey.so [keyfile=/path]
 *
 * 失败时一律返回 PAM_IGNORE，绝不阻断登录（配合 optional 控制位双保险）。
 *
 * SPDX-License-Identifier: MIT
 */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <syslog.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <pwd.h>

#include <security/pam_modules.h>
#include <security/_pam_types.h>

#define PAM_WALLETKEY_DEFAULT_FILE "/etc/pam_walletkey.key"
#define PAM_WALLETKEY_MAX          1024

static void wipe(char *s)
{
    if (!s)
        return;
    volatile char *p = s;
    while (*p)
        *(p++) = 0;
}

/* 读取并校验密钥文件，成功返回 0 */
static int read_key(const char *path, char *buf, size_t bufsz)
{
    struct stat st;

    if (stat(path, &st) != 0 || !S_ISREG(st.st_mode))
        return -1;
    /* 必须是 root 所有，且不允许 group/other 有任何权限 */
    if (st.st_uid != 0)
        return -2;
    if ((st.st_mode & (S_IRWXG | S_IRWXO)) != 0)
        return -3;

    FILE *f = fopen(path, "r");
    if (!f)
        return -4;

    if (fgets(buf, (int)bufsz, f) == NULL) {
        fclose(f);
        return -5;
    }
    fclose(f);

    size_t n = strcspn(buf, "\r\n");
    buf[n] = '\0';

    return n == 0 ? -6 : 0;
}

PAM_EXTERN int pam_sm_authenticate(pam_handle_t *pamh, int flags, int argc, const char **argv)
{
    (void)flags;

    const char *keyfile = PAM_WALLETKEY_DEFAULT_FILE;

    for (int i = 0; i < argc; i++) {
        if (strncmp(argv[i], "keyfile=", 8) == 0 && argv[i][8] != '\0')
            keyfile = argv[i] + 8;
    }

    const char *user = NULL;
    if (pam_get_user(pamh, &user, NULL) != PAM_SUCCESS || user == NULL || *user == '\0')
        return PAM_IGNORE;

    /* root 不需要钱包解锁，直接跳过 */
    struct passwd *pw = getpwnam(user);
    if (pw != NULL && pw->pw_uid == 0)
        return PAM_IGNORE;

    char key[PAM_WALLETKEY_MAX] = {0};
    int rc = read_key(keyfile, key, sizeof(key));
    if (rc != 0) {
        syslog(LOG_WARNING,
               "pam_walletkey: cannot use key file %s (rc=%d); wallet unlock left to user",
               keyfile, rc);
        return PAM_IGNORE;
    }

    int r = pam_set_item(pamh, PAM_AUTHTOK, key);
    wipe(key);

    if (r != PAM_SUCCESS) {
        syslog(LOG_WARNING, "pam_walletkey: pam_set_item(PAM_AUTHTOK) failed (rc=%d)", r);
        return PAM_IGNORE;
    }

    syslog(LOG_DEBUG, "pam_walletkey: wallet key injected for user %s", user);
    return PAM_SUCCESS;
}

PAM_EXTERN int pam_sm_setcred(pam_handle_t *pamh, int flags, int argc, const char **argv)
{
    (void)pamh;
    (void)flags;
    (void)argc;
    (void)argv;
    return PAM_SUCCESS;
}
```

几处实现细节：

`S_ISREG` 检查挡住了符号链接和特殊文件。 少了它，攻击者可以用一个指向 `/dev/zero` 或别人可写文件的路径把密钥内容变成别的字符串。
`st_uid != 0` 加权限位检查缺一不可。 只查属主不查权限，一个 `0644` 的 root 文件仍然人人可读。
`getpwnam` 跳过 root 用户。 root 不需要解锁钱包，让它也走一遍只会多一次无谓的文件读取。
`pam_get_user` 失败就返回。 拿不到用户名说明 PAM 上下文不对，此时继续没有意义。
`wipe()` 用 `volatile char *` 写零。 不加 `volatile`，编译器有权把这段“写了没人读”的循环优化掉，密钥就会留在栈上。
`syslog` 只打返回码，不打密钥。 日志会进 journal，任何会记录密钥内容的东西都不该出现在这里。

`pam_sm_setcred` 是个空实现，直接返回 `PAM_SUCCESS`。PAM 加载模块时会找这个符号，不提供会报错，但本方案在 setcred 阶段确实无事可做。

安装

分三步：编译模块、生成密钥、跑安装脚本。

1. 编译模块

把上面的 `pam_walletkey.c` 存到某个目录，然后：

```bash
gcc -shared -fPIC -O2 -o pam_walletkey.so pam_walletkey.c
```

不需要 `-lpam`。本机实测编译出的 `.so` 里未定义的符号只有 `pam_get_user` 和 `pam_set_item` 两个 PAM 符号（其余都是 libc），它们由宿主 `libpam` 在加载时提供：

```bash
nm -D --undefined-only pam_walletkey.so    # 期望只看到 pam_get_user / pam_set_item
```

2. 生成钱包密钥

```bash
openssl rand -base64 24 > wallet-key.txt
chmod 600 wallet-key.txt
```

这个文件在安装时会被装到 `/etc/pam_walletkey.key`（`root:root 0600`）。它不要进 Git、不要贴进文章、不要出现在任何脚本参数或日志里。

3. 把 KWallet 的钱包密码改成这个密钥

这一步要在图形界面里做，而且必须在安装脚本之前完成——否则 PAM 注入的密钥和钱包密码对不上，派生出的密钥打不开钱包，症状仍然是“弹框问密码”。

`kwalletmanager` → `kdewallet` → 更改密码 → 新密码两栏填入 `wallet-key.txt` 的内容。

4. 跑安装脚本

脚本把下面这些改动一次做完，并且是幂等的，重复运行不会重复插入：

```bash
#!/usr/bin/env bash
#
# biopass + sudo/polkit 人脸认证 + pam_walletkey 安装脚本
#
#   用法： sudo bash install.sh
#
# 安装内容：
#   1. /usr/lib/security/pam_walletkey.so        （自建 PAM 模块，把钱包密钥注入 PAM_AUTHTOK）
#   2. /etc/pam_walletkey.key                    （root:root 0600，钱包密码；需与 KWallet 密码一致）
#   3. /etc/pam.d/sudo                           （顶部插入 biopass sufficient 行）
#   4. /etc/pam.d/plasmalogin                    （pam_walletkey + pam_kwallet5 上移到 biopass 之前）
#   5. /etc/pam.d/polkit-1                       （polkit/pkexec 走 biopass）
#   6. /etc/systemd/system/polkit-agent-helper@.service.d/override.conf （放开摄像头设备）
#
# 幂等：可重复运行；每次运行都会把原文件备份到 /var/backups/biopass-kwallet-<时间戳>/
#
set -euo pipefail

STAMP="$(date +%Y%m%d-%H%M%S)"
SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
BACKUP_DIR="/var/backups/biopass-kwallet-${STAMP}"
SUDO_PAM="/etc/pam.d/sudo"
PLASMALOGIN_PAM="/etc/pam.d/plasmalogin"
POLKIT_PAM="/etc/pam.d/polkit-1"
OVERRIDE_DIR="/etc/systemd/system/polkit-agent-helper@.service.d"

if [[ "${EUID}" -ne 0 ]]; then
    echo "错误：请用 root 运行 → sudo bash \"${BASH_SOURCE[0]}\"" >&2
    exit 1
fi

need() {
    if [[ ! -e "${SCRIPT_DIR}/$1" ]]; then
        echo "错误：缺少交付文件 ${SCRIPT_DIR}/$1" >&2
        exit 1
    fi
}
need pam_walletkey.so
need wallet-key.txt
need plasmalogin.pam.new
need polkit-1.pam.new
need polkit-agent-helper-override.conf

echo "==> 备份到 ${BACKUP_DIR}"
mkdir -p "${BACKUP_DIR}"
chmod 700 "${BACKUP_DIR}"
for f in "${SUDO_PAM}" "${PLASMALOGIN_PAM}" "${POLKIT_PAM}"; do
    [[ -e "${f}" ]] && cp -a "${f}" "${BACKUP_DIR}/$(basename "${f}")"
done
[[ -d "${OVERRIDE_DIR}" ]] && cp -a "${OVERRIDE_DIR}" "${BACKUP_DIR}/"
echo "    完成后如出问题：sudo bash \"${SCRIPT_DIR}/rollback.sh\" ${BACKUP_DIR}"

echo "==> [1/6] 安装 pam_walletkey.so 与钱包密钥"
install -m 0755 -o root -g root "${SCRIPT_DIR}/pam_walletkey.so" /usr/lib/security/pam_walletkey.so
install -m 0600 -o root -g root "${SCRIPT_DIR}/wallet-key.txt" /etc/pam_walletkey.key
echo "    /etc/pam_walletkey.key 已就位（请确保它与 KWallet 钱包密码完全一致）"

echo "==> [2/6] 为 sudo 添加 biopass 认证（幂等）"
if grep -qE '^[[:space:]]*auth[[:space:]]+sufficient[[:space:]]+libbiopass_pam\.so' "${SUDO_PAM}"; then
    echo "    已存在，跳过"
else
    tmp="$(mktemp)"
    awk 'BEGIN{done=0}
         /^[[:space:]]*auth[[:space:]]/ && !done {
             print "auth\t\tsufficient\tlibbiopass_pam.so";
             print "# biopass: 人脸认证成功即免密；失败自动回退下方 system-auth 的密码认证";
             done=1
         }
         { print }' "${SUDO_PAM}" > "${tmp}"
    install -m 0644 -o root -g root "${tmp}" "${SUDO_PAM}"
    rm -f "${tmp}"
    echo "    已插入"
fi

echo "==> [3/6] 更新 plasmalogin 的 PAM 栈（pam_walletkey + pam_kwallet5 前置）"
install -m 0644 -o root -g root "${SCRIPT_DIR}/plasmalogin.pam.new" "${PLASMALOGIN_PAM}"

echo "==> [4/6] 让 polkit / pkexec 走 biopass"
install -m 0644 -o root -g root "${SCRIPT_DIR}/polkit-1.pam.new" "${POLKIT_PAM}"

echo "==> [5/6] 安装 polkit-agent-helper systemd override（放开摄像头设备）"
install -D -m 0644 -o root -g root "${SCRIPT_DIR}/polkit-agent-helper-override.conf" \
        "${OVERRIDE_DIR}/override.conf"

echo "==> [6/6] 重载 systemd 并重启 polkit"
systemctl daemon-reload
systemctl restart polkit.service

echo
echo "==> 完成。请在【新终端】中验证（本终端不要关）："
echo "    sudo -k; sudo true          # 预期：人脸识别通过 → 直接执行"
echo "    pkexec id                   # 预期：弹窗中出现 biopass 人脸识别"
echo
echo "  验证钱包：注销后用 biopass 登录，然后执行"
echo "    journalctl -b -u plasmalogin | grep -i pam_kwallet5"
echo "  预期不再出现 'open_session called without kwallet5_key'"
echo
echo "  回滚： sudo bash \"${SCRIPT_DIR}/rollback.sh\" ${BACKUP_DIR}"
```

```bash
sudo bash biopass-install.sh
```

它会在动手前把原文件备份到 `/var/backups/biopass-kwallet-<时间戳>/`。执行前先另开一个 root 终端放着别关。

登录路径：plasmalogin

`/etc/pam.d/plasmalogin` 是 greeter 登录用的 PAM 服务。`pam_walletkey` 和 `pam_kwallet5` 必须位于 biopass 的 `sufficient` 行之前，这是整件事的根因所在：

```ini
#%PAM-1.0

# ---- Biopass 人脸认证（Plasma Login Manager 专用；失败自动回退密码）----
# pam_walletkey（自建模块）先把 KWallet 密码从 /etc/pam_walletkey.key 注入 PAM_AUTHTOK，
# 再由 pam_kwallet5 存入 pam_set_data，session 阶段才能真正解锁 kdewallet。
# 因此这两行必须放在 biopass 的 sufficient 行之前（sufficient 成功会终止整个 auth 栈）。
-auth       optional    pam_walletkey.so
-auth       optional    pam_kwallet5.so
auth        sufficient  libbiopass_pam.so
auth        include     system-login
-auth       optional    pam_gnome_keyring.so

account     include     system-login

password    include     system-login
-password   optional    pam_gnome_keyring.so    use_authtok

session     optional    pam_keyinit.so          force revoke
session     include     system-login
-session    optional    pam_gnome_keyring.so    auto_start
-session    optional    pam_kwallet5.so         auto_start
```

auth 阶段注入的 `PAM_AUTHTOK` 会被 `pam_kwallet5` 保存下来，session 阶段才能拿到 `kwallet5_key`，然后解锁 `kdewallet`。

如果同时使用 PLM Autologin，`/etc/pam.d/plasmalogin-autologin` 也要放入同样的两行；那条路径上的 `pam_exec` 人脸闸门和 fail-closed 顺序见PLM 免按键人脸登录。

sudo

`sudo` 的改动只有一行，插在 `system-auth` 之前：

```ini
# /etc/pam.d/sudo
#%PAM-1.0
auth        sufficient  libbiopass_pam.so
# biopass：人脸认证成功即免密；失败自动回退下方 system-auth 的密码认证
auth        include     system-auth
account     include     system-auth
session     include     system-auth
session     optional    pam_systemd.so class=none
```

放在 `system-auth` 之前而不是改 `system-auth` 本身，影响面最小：只有 `sudo` 走人脸，`login`、`su`、`sshd` 全都不变。人脸成功即免密；人脸失败、取消或没有摄像头，都会正常回落到下面的密码提示。

`sudo` 的时间戳保持默认（15 分钟，按 tty 和父进程记）。第一次 `sudo -k; sudo true` 会做人脸认证，缓存有效期内的后续命令不会重复调用摄像头。

polkit 与 pkexec

polkit 在默认配置里是用不了人脸的两处都要改，只改 PAM 文件不够。

1. PAM 服务

`/etc/pam.d/polkit-1` 覆盖包内的 `/usr/lib/pam.d/polkit-1`（前者优先）。注意上游那份里本来就有 `password include system-auth`，改写时不要漏掉：

```ini
#%PAM-1.0

# polkit / pkexec 的 PAM 服务：先试 biopass 人脸，失败自动回退密码。
# 本文件覆盖 /usr/lib/pam.d/polkit-1（/etc/pam.d 优先级更高）。
# 注意：还需要 systemd override（polkit-agent-helper-override.conf）放开摄像头设备，
#       并在 biopass 配置里把 polkit-1 / pkexec 从 ignore_services 移除。
auth       sufficient  libbiopass_pam.so
auth       include     system-auth
account    include     system-auth
password   include     system-auth
session    include     system-auth
```

2. systemd drop-in：放开摄像头设备

这一条容易漏，但它决定成败。`polkit-agent-helper@.service` 默认带 `PrivateDevices=yes`，进程在自己的设备命名空间里看不到 `/dev/video*`。biopass 拿不到摄像头，人脸自然失败：

```ini
[Service]
# biopass 需要访问摄像头（polkit-agent-helper 默认 PrivateDevices=yes 会屏蔽 /dev/video*）
PrivateDevices=no
DevicePolicy=auto
DeviceAllow=char-video4linux rw
DeviceAllow=char-media rw
DeviceAllow=char-drm rw
DeviceAllow=/dev/uinput rw

# 允许 biopass 把日志写到 ~/.local/share/com.ticklab.biopass/logs/
ProtectHome=no
```

`ProtectHome=no` 是为了让 biopass 能往 `~/.local/share/com.ticklab.biopass/logs/` 写日志；不加也能认证，只是丢日志。

3. 让 biopass 别再忽略 polkit

biopass 默认把 polkit 相关服务排除在外，要把它从忽略列表里去掉。改的是用户自己的配置：

```bash
# ~/.config/com.ticklab.biopass/config.yaml
strategy:
  ignore_services: []
```

本机改动前这一项是 `[polkit-1, pkexec]`。改完重启 polkit：

```bash
sudo systemctl daemon-reload
sudo systemctl restart polkit.service
```

验证结果

每改一层就验证一层，出了问题容易回到上一步：

```bash
# sudo：人脸通过应成功，失败应回到密码
sudo -k
sudo true

# polkit：确认 pkexec 走的是同一套人脸配置
pkexec id

# 登录后的钱包状态
busctl --user call org.kde.kwalletd6 /modules/kwalletd6 \
  org.kde.KWallet isOpen s kdewallet
```

本机验证结果如下：

`sudo` 人脸通过时无需密码，未识别时回退密码；TTY（`Ctrl+Alt+F3`）下也能用；
`pkexec id` 返回 root 身份（`uid=0`），未输入密码；
autologin 和 greeter 两条登录路径都执行了 `pam_kwallet5` 的 auth 和 session 阶段；
日志中不再出现 `open_session called without kwallet5_key`（0 条），取而代之的是 `pam_sm_authenticate` 加 `pam_sm_open_session`，且 `PAM_KWALLET5_LOGIN=/run/user/<uid>/kwallet5.socket` 与套接字都存在；
`isOpen("kdewallet")` 返回 `true`，整个登录过程没有再次输入钱包密码。

排错

钱包还是不自动解锁，日志里仍有 `without kwallet5_key`
- 可能原因：`pam_walletkey` 和 `pam_kwallet5` 排在了 `libbiopass_pam.so` 之后，`sufficient` 成功就跳过了它们。
- 怎么办：`grep -nE 'pam_walletkey|pam_kwallet5|libbiopass' /etc/pam.d/plasmalogin`，确认顺序是 walletkey → kwallet5 → biopass。
密钥对了，但钱包还是打不开
- 可能原因：KWallet 里的钱包密码和 `/etc/pam_walletkey.key` 的内容不一致（哪怕差一个换行）。
- 怎么办：模块会剥掉行尾的 `\r`/`\n`，但不会 trim 空格。重设一次钱包密码，确保是同一串字符。
日志里出现 `pam_walletkey: key file rejected (rc=-2)`
- 可能原因：`/etc/pam_walletkey.key` 的属主或权限不对（必须是 `root:root 0600`）。
- 怎么办：`ls -l /etc/pam_walletkey.key`，然后用 `install -m 0600 -o root -g root` 重装一次。
按网上说法加了 `kwalletd=/usr/bin/ksecretd` 参数，没变化
- 可能原因：本机 kwallet-pam 6.7.5 编译时的默认守护进程已经是 `/usr/bin/ksecretd`，这个参数是多余的。
- 怎么办：去掉它。要紧的是钱包名 `kdewallet` 和钱包密码。
`pkexec` 还是弹密码框
- 可能原因：三处改动少了一处——PAM 文件、systemd drop-in、biopass 的忽略列表。
- 怎么办：`systemctl show polkit-agent-helper@.service -p PrivateDevices` 应返回 `no`；再确认 `ignore_services` 里没有 `polkit-1`、`pkexec`。
`sudo` 变慢了
- 可能原因：人脸单次判定约 2 秒；第一次没在 2 秒内正对镜头就会回落到密码。
- 怎么办：在 biopass 图形界面里调大 `methods.face.retries` 或 `retry_delay`。终端里的 `sudo` 走 biopass 时没有摄像头预览窗口，看不到“正在识别”的反馈，这是第一次容易失败的主要原因。

通用性

“人脸不产生密码”这条限制 —— ✅ 所有走 PAM 的生物识别模块都一样。
`sufficient` 会跳过后续模块 —— ✅ Linux-PAM 的固定语义。
模块的校验逻辑与 `PAM_IGNORE` 兜底 —— ✅ 与发行版无关。
钱包密码必须等于注入的密钥 —— ✅ 硬性要求，任何方案都绕不过。
polkit 需要 systemd drop-in —— ✅ `PrivateDevices=yes` 是上游默认值。
钱包名、盐文件路径、PBKDF2 参数 —— ⚠️ 由具体的 pam_kwallet 版本决定，换版本要复核。
默认守护进程是 `ksecretd` —— ⚠️ kwallet-pam 6.7.5 的编译默认值，更早的版本可能是 `kwalletd5`。
`/etc/pam.d/…` 的具体路径与内容 —— ⚠️ 发行版差异；本机是 Arch 系的 `system-auth` / `system-login` 体系。

回滚

回滚脚本会还原三份 PAM 文件、移除自建模块与密钥文件、删掉 polkit 的 override，并重启 polkit：

```bash
#!/usr/bin/env bash
#
# 回滚脚本：撤销 install.sh 的所有系统改动
#
#   用法： sudo bash rollback.sh [备份目录]
#          不给参数时自动使用 /var/backups/biopass-kwallet-* 中最新的一份
#
set -euo pipefail

SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
OVERRIDE_DIR="/etc/systemd/system/polkit-agent-helper@.service.d"

if [[ "${EUID}" -ne 0 ]]; then
    echo "错误：请用 root 运行 → sudo bash \"${BASH_SOURCE[0]}\"" >&2
    exit 1
fi

if [[ $# -ge 1 ]]; then
    BACKUP_DIR="$1"
else
    BACKUP_DIR="$(ls -1dt /var/backups/biopass-kwallet-* 2>/dev/null | head -n 1 || true)"
fi

if [[ -z "${BACKUP_DIR:-}" || ! -d "${BACKUP_DIR}" ]]; then
    echo "错误：找不到备份目录，请手动指定：sudo bash rollback.sh /var/backups/biopass-kwallet-YYYYmmdd-HHMMSS" >&2
    exit 1
fi

echo "==> 使用备份：${BACKUP_DIR}"

echo "==> 还原 PAM 配置"
for name in sudo plasmalogin polkit-1; do
    if [[ -e "${BACKUP_DIR}/${name}" ]]; then
        install -m 0644 -o root -g root "${BACKUP_DIR}/${name}" "/etc/pam.d/${name}"
        echo "    /etc/pam.d/${name} 已还原"
    elif [[ "${name}" == "polkit-1" ]]; then
        rm -f /etc/pam.d/polkit-1
        echo "    /etc/pam.d/polkit-1（本次新建）已删除，回落 /usr/lib/pam.d/polkit-1"
    fi
done

echo "==> 移除自建模块与钱包密钥"
rm -f /usr/lib/security/pam_walletkey.so
rm -f /etc/pam_walletkey.key

echo "==> 还原 polkit-agent-helper override"
if [[ -d "${BACKUP_DIR}/polkit-agent-helper@.service.d" ]]; then
    mkdir -p "${OVERRIDE_DIR}"
    cp -a "${BACKUP_DIR}/polkit-agent-helper@.service.d/." "${OVERRIDE_DIR}/"
    echo "    已还原原有 override"
else
    rm -rf "${OVERRIDE_DIR}"
    echo "    已删除本次新增的 override 目录"
fi

echo "==> 重载 systemd 并重启 polkit"
systemctl daemon-reload
systemctl restart polkit.service

cat <<'EOF'

==> 回滚完成。请注意两件事：
    1) KWallet 密码仍是安装时设置的随机密钥：请在 kwalletmanager 里把钱包密码改回你自己记得的值。
    2) biopass 的「忽略服务」列表请手动把 polkit-1 / pkexec 加回去
       （~/.config/com.ticklab.biopass/config.yaml 的 strategy.ignore_services）。
EOF
```

```bash
sudo bash biopass-rollback.sh              # 不给参数 = 用最新那份备份
```

跑完之后还有两件事脚本没法替你做，它在结尾也会提醒：

KWallet 的密码仍是那串随机密钥，要在 `kwalletmanager` 里改回你自己记得的值；
biopass 的忽略列表要把 `polkit-1` 和 `pkexec` 加回去（`~/.config/com.ticklab.biopass/config.yaml` 的 `strategy.ignore_services`）。

方案的安全边界很明确：root 能读到密钥，就能解锁这个钱包；普通用户不能读密钥文件。它保留了钱包文件的静态加密，但没有把 PAM 变成密钥管理系统。

长期维护

这次改动会在系统升级时被绕过，而且两类文件的表现不一样，处理方式也不同。

包自己拥有的文件会生成 `.pacnew`。 `/etc/pam.d/sudo` 属于 `sudo` 包，升级时 pacman 会把它另存为 `/etc/pam.d/sudo.pacnew`：新版本里没有我们插入的那一行，需要手动合回去。

我们自己新建的文件不会有 `.pacnew`，但上游默认值会变。 `/etc/pam.d/plasmalogin`、`/etc/pam.d/polkit-1`、`/etc/pam.d/plasmalogin-autologin` 都不属于任何包（它们的上游版本在 `/usr/lib/pam.d/` 下），所以 pacman 不会碰它们。代价是包更新后 `/usr/lib/pam.d/` 那份变了，我们的文件不会跟着变，也不会有人提醒。

```bash
# 1) 有没有 pacnew
sudo find /etc/pam.d -name '*.pacnew'

# 2) 我们改过的文件和上游默认值差在哪
for f in plasmalogin polkit-1 plasmalogin-autologin; do
    echo "--- $f"
    diff -u "/usr/lib/pam.d/$f" "/etc/pam.d/$f"
done
```

注意

`install.sh` 只对 `/etc/pam.d/sudo` 是“插入一行”的幂等操作；对另外三个文件是整份覆盖，不是合并。上游默认值如果新增了模块或参数，重跑脚本会把它们丢掉。所以升级后先 diff，再决定是重跑脚本还是手工把那几行合进去。

上面这些路径是 Arch 系的布局（上游默认放 `/usr/lib/pam.d/`）。别的发行版可能把上游默认直接放在 `/etc/pam.d/` 里，那时它们会产生 `.pacnew`，第 2 步的 `diff` 也就没有意义了。

参考

PLM 免按键人脸登录

Fri, 25 Sep 2026 00:00:00 GMT

Plasma Login Manager（PLM）的登录界面里，人脸认证要先按 Enter，或者点击登录按钮。Windows Hello 式的“看向摄像头就开始识别”没有对应的配置开关。所以我多少有点标题党了，为了实现这个效果，我没有在 PLM 上死磕，而是转而使用了其他方法。

先决条件

```text
CachyOS（Arch 系）｜KDE Plasma 6.7.5｜Plasma Login Manager 6.7.4
Wayland｜biopass-bin 1.4.1｜pam 1.7.2
```

本机 biopass 只开人脸（`methods.face.enable: true`，指纹关闭），单次判定约 2 秒。下面所有配置里的 `<用户名>` 是占位符，安装前换成你自己的登录名。

整套改动落在三个地方，没有新增守护进程，也不需要编译任何东西：

#	位置	作用
1	``/usr/local/libexec/biopass-pam-auth``	人脸闸门包装脚本
2	``/etc/pam.d/plasmalogin-autologin``	覆盖上游的放行式 PAM 栈
3	``/etc/plasmalogin.conf``	``[Autologin]`` 段指定登录用户

现象

在 greeter 前坐定、把脸对着摄像头，界面不会有任何反应，必须先按一次 Enter 或点一次登录按钮，识别才开始。识别本身没问题：一次通过、约 2 秒进桌面。缺的是谁来发起这次认证。

greeter 为什么不自动认证

上游 `src/frontend/greeter/qml/Login.qml`（6.7）里，能发起认证的入口只有三个：

```qml
passwordBox.onAccepted:            startLogin()   // 密码框回车
loginButton.onClicked:             startLogin()   // 点登录按钮
loginButton.Keys.onReturnPressed:  clicked()      // 按钮聚焦时回车
```

而负责初始化界面的 `Component.onCompleted` 只做三件事：填充上次登录的用户名、把焦点放到密码框、同步界面状态。它没有调用 `startLogin()`。

想加一个触发点也走不通：

没有可替换的主题。 `src/frontend/greeter/CMakeLists.txt` 用 `ecm_add_qml_module(plasma-login-greeter URI "org.kde.plasma.login")` 加 `ecm_target_qml_sources(...)` 把 `Main.qml`、`Login.qml` 这些文件编进了二进制资源；`src/frontend/settings/models/` 下只有 `sessionmodel`、`usermodel`。SDDM 那种“放一个主题目录就换掉整个界面”的做法在这里不存在。
没有对应配置键。 上游 `src/common/mainconfig.kcfg`（6.7）里的键是全部：`X11.*`、`Wayland.SessionLogFile`、`Autologin.User/Session/Relogin`、`General.Namespaces`、`Users.DefaultPath`。`AutoAuth`、`Biometric`、`AutoStartAuth` 这一类键一个都没有。

所以这是当前设计，不是配置写错了。改 greeter 配置或主题都不会凭空多出一个认证触发点。

为什么不能直接把 biopass 标成 required

在动手前得先绕开一个坑，它决定后面为什么用一个包装脚本而不是直接引用 biopass 的 PAM 模块。

biopass 的 PAM 模块（上游 `auth/pam/pam.cc`）把助手的退出码映射成三种 PAM 返回值：

helper 退出码	PAM 返回值	什么时候出现
0	``PAM_SUCCESS``	人脸匹配
2	``PAM_IGNORE``	跑不起来：摄像头打不开、模型缺失、该用户无人脸
其他非 0	``PAM_AUTH_ERR``	人脸不匹配

问题出在 `PAM_IGNORE` 上。Linux-PAM 的 `pam_dispatch.c` 里，`required` 展开成 `[success=ok new_authtok_reqd=ok ignore=ignore default=bad]`，也就是说模块返回 `PAM_IGNORE` 时对应的动作是 ignore，直接跳过，完全不影响整个栈的成败。于是下面这种写法看起来是把人脸设成了必须项，实际不是：

```ini
auth required libbiopass_pam.so    # 摄像头坏了 → PAM_IGNORE → 不算失败
auth required pam_permit.so        # → 放行 → 无认证进入桌面
```

对 `sudo` 那种“先试人脸、失败回退密码”的场景，这个特性无害；对 autologin 这种无人值守的闸门就是漏洞，摄像头一坏，闸门自己开了。

规避办法是用 `pam_exec` 调 biopass 的助手。`pam_exec`（`man pam_exec`）只看进程退出码，0 是通过、非 0 是失败，它没有 `PAM_IGNORE` 这种中间态：

```plaintext
helper 退出码 0  → pam_exec 返回 PAM_SUCCESS
helper 退出码非 0 → pam_exec 返回 PAM_SERVICE_ERR / PAM_AUTH_ERR
```

于是映射关系变成干净的二分：能跑通并识别成功才算通过，其余一切情况——没识别到、摄像头不可用、助手缺失、脚本自身出错——都是失败。autologin 失败会回落到登录界面，用户还能输密码，不会把自己锁在外面。

代价是多一个包装脚本。后面会看到，它同时还要负责给钱包传递密钥。

选择 Autologin

PLM 的 Autologin 恰好把认证放在了 greeter 之前。上游 `src/daemon/Display.cpp` 的 `Display::start()`：

```cpp
if (m_autologinSession.isValid()) {
    m_auth->setAutologin(true);
    if (startAuth(m_autologinUser, QString(), m_autologinSession))
        return true;                          // ← 前两个参数：用户、空密码
    else
        return handleAutologinFailure();      // ← "Autologin failed!" → 拉起 greeter
}
```

三个性质正好都用得上：

不需要按键——认证发生在 greeter 和合成器启动之前，屏幕上还没有任何可点的东西。
失败不锁死——`handleAutologinFailure()` 会正常拉起登录界面，密码框和人脸重试都在。
失败是可见的——日志里留下 `Autologin failed!` 一行，排查时不用猜。

`PamBackend::start()` 里写明 autologin 用的 PAM 服务名就是 `plasmalogin-autologin`，所以闸门脚本要挂在 `/etc/pam.d/plasmalogin-autologin` 上，而不是 greeter 用的 `/etc/pam.d/plasmalogin`。

运行时序：

```text
开机 → plasmalogin 启动
  └─ Autologin：跑 plasmalogin-autologin 的 PAM 栈
       ├─ 通过 → 创建 Plasma 会话，直接进桌面
       └─ 失败 → Autologin failed! → 拉起 greeter
```

这里会出现两个代价，或许你需要自行抉择：

认证期间没有界面。 人脸那约 2 秒是黑屏，即便启用了开机动画也看不到。这是“在 greeter 之前认证”的必然结果。
开机时不能选会话。 会话由配置里的 `Session=` 固定。本机本来就固定用 Plasma，实际影响很小（但是诸位使用 Linux 的用户大概率是多会话用户，所以可能你需要做出妥协）。

人脸闸门脚本

脚本要做的事：从 PAM 拿当前用户名和服务名，调 biopass 助手，只把退出码原样交给 `pam_exec`。任何一步不成立都退出非 0。

`pam_exec` 会往子进程环境里放 `PAM_USER`、`PAM_SERVICE`、`PAM_TYPE`。脚本用前两个，并且在任何一个为空时直接拒绝放行。另外 `pam_exec` 默认以调用者的身份执行命令，而 autologin 时代的调用者是 root，所以这个脚本必须是 `root:root 0755`，不能让它可被普通用户改写。

```bash
#!/bin/bash
#
# biopass-pam-auth — 由 pam_exec.so 调用的"人脸闸门"
#
# 安装位置：/usr/local/libexec/biopass-pam-auth   (root:root 0755)
# 调用方式：PAM 文件中写
#     auth required pam_exec.so quiet /usr/local/libexec/biopass-pam-auth
#
# 设计原因（勿改成 auth required libbiopass_pam.so）：
#   biopass 的 PAM 模块在"无法运行"（摄像头打不开/模型缺失/该用户无人脸）时
#   helper 退出码为 2，模块会把它映射成 PAM_IGNORE；而 PAM 的 required 会忽略
#   PAM_IGNORE，配合 autologin 栈里原有的 pam_permit.so 就会变成"无认证放行"。
#   pam_exec 只看退出码：0 = 通过，非 0 = 失败（helper 缺失/脚本异常同样失败，fail-closed）。
#
# 环境变量由 pam_exec 注入：PAM_USER / PAM_SERVICE / PAM_TYPE 等。
#
# SPDX-License-Identifier: MIT

set -u

HELPER="/usr/bin/biopass-helper"
LOG_TAG="biopass-pam-auth"

user="${PAM_USER:-}"
service="${PAM_SERVICE:-plasmalogin-autologin}"

if [[ -z "${user}" ]]; then
    logger -t "${LOG_TAG}" -p auth.warning "PAM_USER 为空，拒绝放行（fail-closed）"
    exit 1
fi

if [[ ! -x "${HELPER}" ]]; then
    logger -t "${LOG_TAG}" -p auth.err "找不到可执行的 ${HELPER}，拒绝放行（fail-closed）"
    exit 1
fi

# 让 biopass 助手能定位该用户的数据目录（人脸库/配置）；失败也不影响，仅尽力而为
home="$(getent passwd "${user}" | cut -d: -f6)"
if [[ -n "${home}" && -d "${home}" ]]; then
    export HOME="${home}"
fi
export USER="${user}"
export LOGNAME="${user}"

start="${SECONDS}"
"${HELPER}" auth --username "${user}" --service "${service}"
rc=$?
elapsed=$(( SECONDS - start ))

if [[ "${rc}" -eq 0 ]]; then
    logger -t "${LOG_TAG}" -p auth.info "人脸认证通过 user=${user} service=${service} 用时 ${elapsed}s"
    exit 0
fi

# rc=2 表示"没有可用认证方式"（例如摄像头不可用）——必须按失败处理，绝不能放行
logger -t "${LOG_TAG}" -p auth.warning "人脸认证未通过 user=${user} service=${service} rc=${rc} 用时 ${elapsed}s"
exit "${rc}"
```

几个处理值得单独说明：

`PAM_USER` 为空就 exit 1。 拿不到用户名等于无法认证，此时放行是最坏的选择。
找不到助手就 exit 1。 助手路径写错、包被卸载，都应该表现为“认证失败并回落登录界面”，而不是静默通过。
`export HOME` 是尽力而为。 biopass 要靠家目录定位人脸库和配置；失败也不影响，所以没有把它当作硬条件。
退出码原样透传（`exit "$rc"`）。 `pam_exec` 只关心 0 与非 0，但日志里留下 1 和 2 的区别，排查时能立刻分清“没认出来”和“摄像头不可用”。
耗时写进日志。 那 2 秒黑屏的实际长度从这里能看到，后面调优不用靠感觉。

PAM 顺序

目标文件是 `/etc/pam.d/plasmalogin-autologin`。它在 `/etc/pam.d` 下，优先级高于包内默认的 `/usr/lib/pam.d/plasmalogin-autologin`，所以不会和包管理器抢文件，但升级后要留意上游默认值有没有变。

上游那份是这样的（包内默认，关键在 `pam_permit.so` 那一行）：

```ini
auth        required    pam_env.so
auth        required    pam_faillock.so preauth
auth        required    pam_shells.so
auth        required    pam_nologin.so
auth        required    pam_permit.so
-auth       optional    pam_gnome_keyring.so
-auth       optional    pam_kwallet5.so
account     include     system-local-login
password    include     system-local-login
session     include     system-local-login
-session    optional    pam_gnome_keyring.so auto_start
-session    optional    pam_kwallet5.so auto_start
```

改完后：

```ini
#%PAM-1.0

# ---- autologin 人脸闸门 + KWallet 自动解锁（本项目新增 2026-09-25）----
#
# 1) 人脸闸门用 pam_exec，只按退出码判定：0=通过，非 0=失败。
#    切勿改回 "auth required libbiopass_pam.so"：biopass 模块在摄像头不可用/无人脸/
#    模型缺失时返回 PAM_IGNORE（helper exit 2），而 required 会忽略 PAM_IGNORE，
#    与 pam_permit.so 组合就会变成"无认证直接进入桌面"。
#
# 2) 上游默认的 "auth required pam_permit.so" 已被有意删除：
#    没有它以后，认证结果只能来自真实模块；即使将来有人把 pam_exec 改成 optional
#    或误删该行，autologin 也只会失败并回落到登录界面（fail-closed），不会静默放行。
#    如需临时关闭人脸闸门：删掉 pam_exec 行并恢复 "auth required pam_permit.so"。
#
# 3) pam_walletkey 在认证阶段把 KWallet 密码（/etc/pam_walletkey.key）注入 PAM_AUTHTOK，
#    供 pam_kwallet5 在 session 阶段解锁 kdewallet（人脸登录没有密码可抓）。
auth        required    pam_env.so
auth        required    pam_faillock.so preauth
auth        required    pam_shells.so
auth        required    pam_nologin.so
auth        required    pam_exec.so quiet /usr/local/libexec/biopass-pam-auth
-auth       optional    pam_walletkey.so
-auth       optional    pam_gnome_keyring.so
-auth       optional    pam_kwallet5.so

account     include     system-local-login
password    include     system-local-login
session     include     system-local-login
-session    optional    pam_gnome_keyring.so auto_start
-session    optional    pam_kwallet5.so auto_start
```

两处改动：

加 `auth required pam_exec.so quiet …`。 它排在 `pam_nologin.so` 之后、`pam_permit.so` 原来的位置。`quiet` 让 `pam_exec` 不要把命令输出写进系统日志（`man pam_exec` 里 `stdout` 默认本来就丢进 `/dev/null`，这个标记省掉的是另一路噪音）。
删掉 `auth required pam_permit.so`。 这一行是上游给“谁都不用认证”的 autologin 用的。留着它，认证栈里就有一个永远成功的模块；一旦有人把 `pam_exec` 那行改成 `optional`、或者干脆删掉闸门行，结果不会是“进不去”，而是静默放行。删掉之后，认证结果只能来自真实模块，配置被改坏也只会 autologin 失败并回落登录界面。

顺带说明为什么 `pam_walletkey` 和 `pam_kwallet5` 这两行也在这一段的开头：它们是钱包自动解锁用的，属于人脸登录后的 KWallet 自动解锁那一篇的内容。只想先要免按键登录，可以先只加 `pam_exec` 那一行，把这两行留到之后再加。

Autologin 配置

`/etc/plasmalogin.conf` 只需要 `[Autologin]` 段里的三项：

```ini
[Autologin]
User=<用户名>
Session=plasma
Relogin=false
```

`User` 指定自动登录哪个账号。不写这一行，autologin 分支根本不会触发。
`Session=plasma` 会被 `Session::create()` 自动补成 `.desktop` 并在 `wayland-sessions` 下定位，所以写 `plasma` 和写 `plasma.desktop` 等价。
`Relogin` 决定注销之后的行为：`false`（默认值）停在登录界面，需要时再按 Enter；`true` 则注销后立刻再跑一次人脸。想保留“注销出来换个用户”的能力就保持 `false`。

安装

装之前先另开一个 root 终端放着别关。（我们接下来修改的是登录链路上的 PAM 文件，如果写坏了，还有一个已经通过认证的 root shell 可以用来改回来）

脚本会自动备份到 `/var/backups/plasmalogin-face-<时间戳>/`，并且是幂等的，重复执行不会重复插入：

```bash
#!/usr/bin/env bash
#
# Plasma Login Manager 免按键人脸登录 —— Autologin + pam_exec 人脸闸门 安装脚本
#
#   用法： sudo bash install.sh
#
# 安装内容：
#   1. /usr/local/libexec/biopass-pam-auth        人脸闸门包装脚本（调 biopass-helper）
#   2. /etc/pam.d/plasmalogin-autologin          覆盖 /usr/lib/pam.d 的上游默认（放行式）
#   3. /etc/plasmalogin.conf                     [Autologin] 段加 User=<你>（Relogin 保持默认 false）
#
# 不重启任何服务（重启 plasmalogin 会杀掉当前会话）。改动在下次开机/重启后生效。
# 幂等：可重复运行；每次都会把原文件备份到 /var/backups/plasmalogin-face-<时间戳>/
#
set -euo pipefail

STAMP="$(date +%Y%m%d-%H%M%S)"
SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
BACKUP_DIR="/var/backups/plasmalogin-face-${STAMP}"
PLM_CONF="/etc/plasmalogin.conf"
AUTOLOGIN_PAM="/etc/pam.d/plasmalogin-autologin"
WRAPPER_DST="/usr/local/libexec/biopass-pam-auth"
TARGET_USER="${TARGET_USER:-${SUDO_USER:-}}"

if [[ "${EUID}" -ne 0 ]]; then
    echo "错误：请用 root 运行 → sudo bash \"${BASH_SOURCE[0]}\"" >&2
    exit 1
fi

# 不写死用户名：优先用 TARGET_USER，其次用 sudo 记录的调用者。
if [[ -z "${TARGET_USER}" ]]; then
    echo "错误：无法确定目标用户（SUDO_USER 为空）" >&2
    echo "      请显式指定 → TARGET_USER=你的用户名 sudo -E bash \"${BASH_SOURCE[0]}\"" >&2
    exit 1
fi

if ! id "${TARGET_USER}" >/dev/null 2>&1; then
    echo "错误：用户 ${TARGET_USER} 不存在（可用 TARGET_USER=xxx sudo -E bash install.sh 覆盖）" >&2
    exit 1
fi

for f in biopass-pam-auth plasmalogin-autologin.pam.new; do
    if [[ ! -e "${SCRIPT_DIR}/${f}" ]]; then
        echo "错误：缺少交付文件 ${SCRIPT_DIR}/${f}" >&2
        exit 1
    fi
done

echo "==> 备份到 ${BACKUP_DIR}"
mkdir -p "${BACKUP_DIR}"
chmod 700 "${BACKUP_DIR}"
for f in "${PLM_CONF}" "${AUTOLOGIN_PAM}"; do
    [[ -e "${f}" ]] && cp -a "${f}" "${BACKUP_DIR}/$(basename "${f}")"
done
cp -a /usr/lib/pam.d/plasmalogin-autologin "${BACKUP_DIR}/plasmalogin-autologin.usr-lib.pam.d" 2>/dev/null || true
echo "    回滚： sudo bash \"${SCRIPT_DIR}/rollback.sh\" ${BACKUP_DIR}"

echo "==> [1/3] 安装人脸闸门脚本"
install -D -m 0755 -o root -g root "${SCRIPT_DIR}/biopass-pam-auth" "${WRAPPER_DST}"
echo "    ${WRAPPER_DST}"

echo "==> [2/3] 安装 plasmalogin-autologin 的 PAM 配置"
install -m 0644 -o root -g root "${SCRIPT_DIR}/plasmalogin-autologin.pam.new" "${AUTOLOGIN_PAM}"
echo "    ${AUTOLOGIN_PAM}（覆盖 /usr/lib/pam.d/plasmalogin-autologin，后者保持原样）"

echo "==> [3/3] 在 ${PLM_CONF} 的 [Autologin] 段写入 User=${TARGET_USER}（Relogin 不动，保持 false）"
before_hash="$(sha256sum "${PLM_CONF}" | awk '{print $1}')"
tmp="$(mktemp)"

if ! grep -q '^\[Autologin\]' "${PLM_CONF}"; then
    # 情况 0：[Autologin] 段不存在 → 追加一段
    cp -a "${PLM_CONF}" "${tmp}"
    printf '\n[Autologin]\nUser=%s\n' "${TARGET_USER}" >> "${tmp}"
    echo "    已追加 [Autologin] 段"
elif awk '
        /^\[Autologin\]/ { insec = 1; next }
        /^\[/            { insec = 0 }
        insec && /^[[:space:]]*User[[:space:]]*=/ { found = 1 }
        END { exit(found ? 0 : 1) }
    ' "${PLM_CONF}"; then
    # 情况 1：段内已有 User= → 原位替换（保持行位置，自动纠正旧值）
    awk -v user="${TARGET_USER}" '
        /^\[Autologin\]/ { insec = 1; print; next }
        /^\[/            { insec = 0 }
        insec && /^[[:space:]]*User[[:space:]]*=/ {
            if (!done) { printf "User=%s\n", user; done = 1 }
            next
        }
        { print }
    ' "${PLM_CONF}" > "${tmp}"
    echo "    已原位更新 User="
else
    # 情况 2：段存在但没有 User= → 紧跟段头插入
    awk -v user="${TARGET_USER}" '
        { print }
        /^\[Autologin\]/ && !done { printf "User=%s\n", user; done = 1 }
    ' "${PLM_CONF}" > "${tmp}"
    echo "    已在 [Autologin] 段头后插入 User="
fi

install -m 0644 -o root -g root "${tmp}" "${PLM_CONF}"
rm -f "${tmp}"
after_hash="$(sha256sum "${PLM_CONF}" | awk '{print $1}')"
if [[ "${before_hash}" == "${after_hash}" ]]; then
    echo "    （内容已是 User=${TARGET_USER}，无变化）"
fi

echo
echo "==> PAM 栈自检（应看到 pam_exec 行且顺序正确）："
grep -nE 'pam_exec|pam_walletkey|pam_permit' "${AUTOLOGIN_PAM}" | sed 's/^/    /'
echo "==> Autologin 配置："
sed -n '/^\[Autologin\]/,/^\[/p' "${PLM_CONF}" | head -n -1 | sed 's/^/    /'

cat <<EOF

==> 安装完成。验证方式（不需要注销，先验闸门脚本本身）：

  # 1) 直接以 root 触发一次人脸闸门（应打开摄像头并识别人脸）
  sudo env PAM_USER=${TARGET_USER} PAM_SERVICE=plasmalogin-autologin ${WRAPPER_DST}; echo "退出码=\$?"
  #    预期：人脸匹配时退出码 0；遮住脸时非 0；摄像头不可用时为 2（同样会被判为失败）
  #    注：fish 里没有 $?，请改用 "$status"
  journalctl -t biopass-pam-auth -b --no-pager | tail -n 5

  # 2) 确认当前会话/登录界面未被影响（本脚本不重启任何服务）
  #    真正的 autologin 效果需要重启系统：
  #    重启后人脸正常 → 无需任何按键直接进入桌面
  #    遮住脸/移开摄像头 → 出现登录界面（按 Enter 可重试人脸，或直接输密码）

  # 3) 重启后检查日志
  journalctl -b -u plasmalogin | grep -iE 'autologin|pam_exec'
  journalctl -b -u plasmalogin | grep -i pam_kwallet5      # 钱包应自动解锁

==> 回滚： sudo bash "${SCRIPT_DIR}/rollback.sh" ${BACKUP_DIR}
EOF
```

执行：

```bash
sudo bash plasmalogin-install.sh
```

脚本不会重启 plasmalogin，因为那会杀掉当前会话。改动在下次开机或重启后生效。

验证

分两层验。先验闸门脚本本身，无需注销或重启：

```bash
sudo env PAM_USER=<用户名> \
  PAM_SERVICE=plasmalogin-autologin \
  /usr/local/libexec/biopass-pam-auth
printf 'exit=%s\n' "$?"
journalctl -t biopass-pam-auth -b --no-pager | tail -n 5
```

`env PAM_USER=… PAM_SERVICE=…` 就是在手工模拟 `pam_exec` 提供的环境。预期是正脸返回 0、遮住脸返回非 0。

提示

`$?` 在 fish 里不存在，要用 `$status`。用 bash 跑这段最省事。

本机实测：

12:56:36，遮脸 → `人脸认证未通过 … rc=1 用时 2s`，退出码 1；
12:57:08，正脸 → `人脸认证通过 … 用时 2s`，退出码 0。

再验真实开机路径。重启后分两次：一次正常对着镜头，一次把摄像头挡上或移开。

```bash
journalctl -b -u plasmalogin | grep -iE 'autologin|Greeter'
journalctl -t biopass-pam-auth -b --no-pager
```

本机两次开机的结果：

人脸通过 —— ✅ 全程零按键进桌面，`Autologin failed` 0 条。 `13:00:10 人脸认证通过 … 用时 2s` → `Session started true`
人脸失败 —— ✅ 回落登录界面，没有放行。 `13:03:35 rc=1 用时 4s` → `13:03:37 Autologin failed!` → `Greeter starting...`
greeter 重试 —— ✅ 登录界面里按 Enter 仍能刷脸。 `13:03:46 Message received from greeter: Login` → `13:03:48 Authentication … successful`

还有两条顺手确认过：TTY（`Ctrl+Alt+F3`）下的 `sudo` 仍能走人脸；`sudo` 走的是 `libbiopass_pam.so` 直连，不经过这个闸门，所以 `journalctl -t biopass-pam-auth` 里不会出现 `service=sudo`——这是预期行为，不是故障。

排错

开机后直接出现登录界面，日志里有 `Autologin failed!`
- 可能原因：闸门退出码非 0（没认出脸、摄像头被占用、助手缺失），或 `/etc/plasmalogin.conf` 里没写 `User=`。
- 怎么办：`journalctl -t biopass-pam-auth -b` 看退出码和耗时；`sudo env PAM_USER=… PAM_SERVICE=plasmalogin-autologin /usr/local/libexec/biopass-pam-auth; echo $?` 手工复现一次，能立刻区分是脚本问题还是 PAM 顺序问题。
开机直接进桌面，完全没刷脸
- 可能原因：`pam_exec` 那行被改成了 `optional`，或者被删掉了——此时剩下的模块里如果还有 `pam_permit.so`，就是无认证放行。
- 怎么办：`grep -nE 'pam_exec|pam_permit' /etc/pam.d/plasmalogin-autologin`。正确状态是有 `pam_exec`、没有 `pam_permit`，两项都要满足。
`journalctl -t biopass-pam-auth` 一条都不出
- 可能原因：闸门脚本没被执行（PAM 文件没生效），或脚本内的日志标签被改过。
- 怎么办：确认 `/etc/pam.d/plasmalogin-autologin` 存在且是 `0644 root:root`；`logger -t biopass-pam-auth test` 确认 `journalctl -t` 过滤本身没问题。
认证一直失败，但手工跑脚本是好的
- 可能原因：`/usr/local/libexec/biopass-pam-auth` 权限不对（`pam_exec` 以 root 身份执行，脚本必须 `root:root 0755`），或脚本首行 shebang 指向的解释器不存在。
- 怎么办：`ls -l /usr/local/libexec/biopass-pam-auth`，然后 `sudo bash -x /usr/local/libexec/biopass-pam-auth` 跟一遍。
重启后确实免按键了，但钱包还是要手动解锁
- 可能原因：`pam_walletkey` 那两行没加，或顺序排在了 `libbiopass_pam.so` 之后。
- 怎么办：见人脸登录后的 KWallet 自动解锁。

通用性

`pam_exec` 只看退出码、不产生 `PAM_IGNORE` —— ✅ 所有用 Linux-PAM 的系统。
`Autologin` 在 greeter 之前认证 —— ✅ PLM 当前架构。
`pam_exec` 以 root 身份执行命令 —— ✅ Linux-PAM 的行为。
上游 `Login.qml` 没有自动认证入口 —— ✅ PLM 6.7 系列；新版本可能变化，动手前重新核对。
具体路径 `/etc/pam.d/…`、`/usr/local/libexec/…` —— ⚠️ 发行版差异；先确认你的 PAM 与 PLM 装在哪。
黑屏时长约 2 秒 —— ⚠️ 取决于摄像头与识别模型，本机实测 2–4 秒。
`biopass-helper` 的退出码语义 —— ⚠️ 换用别的生物识别模块要重新核对其退出码约定。
`ksecretd` 作为钱包守护进程 —— ⚠️ 由 kwallet-pam 版本决定（6.7.5 的编译默认值）。

回滚

回滚不需要手改文件，脚本会从备份还原，并且在 `/etc/pam.d/plasmalogin-autologin` 原本不存在时把它删掉、回落到 `/usr/lib/pam.d/` 的上游默认：

```bash
#!/usr/bin/env bash
#
# 回滚脚本：撤销 install.sh 的 autologin 人脸闸门改动
#
#   用法： sudo bash rollback.sh [备份目录]
#          不给参数时自动使用 /var/backups/plasmalogin-face-* 中最新的一份
#
set -euo pipefail

SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
PLM_CONF="/etc/plasmalogin.conf"
AUTOLOGIN_PAM="/etc/pam.d/plasmalogin-autologin"
WRAPPER_DST="/usr/local/libexec/biopass-pam-auth"

if [[ "${EUID}" -ne 0 ]]; then
    echo "错误：请用 root 运行 → sudo bash \"${BASH_SOURCE[0]}\"" >&2
    exit 1
fi

if [[ $# -ge 1 ]]; then
    BACKUP_DIR="$1"
else
    BACKUP_DIR="$(ls -1dt /var/backups/plasmalogin-face-* 2>/dev/null | head -n 1 || true)"
fi

if [[ -z "${BACKUP_DIR:-}" || ! -d "${BACKUP_DIR}" ]]; then
    echo "错误：找不到备份目录，请手动指定：sudo bash rollback.sh /var/backups/plasmalogin-face-YYYYmmdd-HHMMSS" >&2
    exit 1
fi

echo "==> 使用备份：${BACKUP_DIR}"

if [[ -e "${BACKUP_DIR}/plasmalogin.conf" ]]; then
    install -m 0644 -o root -g root "${BACKUP_DIR}/plasmalogin.conf" "${PLM_CONF}"
    echo "    ${PLM_CONF} 已还原（autologin User= 被移除）"
fi

if [[ -e "${BACKUP_DIR}/plasmalogin-autologin" ]]; then
    install -m 0644 -o root -g root "${BACKUP_DIR}/plasmalogin-autologin" "${AUTOLOGIN_PAM}"
    echo "    ${AUTOLOGIN_PAM} 已还原"
else
    # 安装前 /etc/pam.d 下没有这个文件（包内默认在 /usr/lib/pam.d）
    rm -f "${AUTOLOGIN_PAM}"
    echo "    ${AUTOLOGIN_PAM}（本次新建）已删除，回落到 /usr/lib/pam.d/plasmalogin-autologin"
fi

rm -f "${WRAPPER_DST}"
rmdir /usr/local/libexec 2>/dev/null || true
echo "    ${WRAPPER_DST} 已删除"

cat <<'EOF'

==> 回滚完成。说明：
    * 本脚本不重启 plasmalogin（那会杀掉当前会话）；下次开机即恢复"显示登录界面"的行为。
    * KWallet 相关改动属于另一个档案（biopass-sudo-kwallet），未在此回滚。
EOF
```

```bash
sudo bash plasmalogin-rollback.sh          # 不给参数 = 用最新那份备份
```

同样不会重启 plasmalogin，下次开机即恢复“显示登录界面”的行为。回滚只覆盖这一篇的改动；钱包那部分属于另一篇，要单独回滚。

什么时候可以退休

犹分省署直，何日是归休。 ——姚合《和膳部李郎中秋夕》

PLM 的这个缺口已经有上游跟踪项：KDE bug 506025（product `plasma-login-manager`，状态 CONFIRMED，wishlist）。那条报告针对的是指纹登录，诉求和这里一样：让登录服务能在 greeter 之外、由界面主动在后台启动一次生物识别，并允许它与密码认证并行。上游目前没有这个能力。

如果后续版本把它做了进去，判断标准是：登录服务能在 greeter 之外安全地启动生物识别，并在失败时回到正常登录流程。满足之后就没有理由继续用 Autologin 绕，届时：

删掉 `/etc/plasmalogin.conf` 里的 `[Autologin] User=`；
删掉 `/etc/pam.d/plasmalogin-autologin`，回落到 `/usr/lib/pam.d/` 的上游默认；
删掉 `/usr/local/libexec/biopass-pam-auth`。

这三步正好就是回滚脚本做的事，直接跑它也可以。

参考

Plasma Login Manager 源码（`src/frontend/greeter/qml/Login.qml`、`src/frontend/greeter/CMakeLists.txt`、`src/common/mainconfig.kcfg`、`src/daemon/Display.cpp`、`src/helper/backend/PamBackend.cpp`、`src/common/Session.cpp`）
KDE bug 506025
biopass PAM 文档
biopass PAM 模块源码（退出码到 PAM 返回值的映射）
Linux-PAM 调度实现
`man pam.conf`、`man pam_exec`

把 Nahimic 出厂音效搬到 Linux

Wed, 23 Sep 2026 00:00:00 GMT

每次从 Windows 回到 Linux 我都会有一种遗憾，因为 Linux 下没有厂商调教的音效配置，导致我的笔记本扬声器发出的声音宛若一头年轻的水牛（没有歧视水牛的意思），所以我决定研究研究 Nahimic 是怎样增强笔记本音效的。

首先，Nahimic 的音效参数不一定只能在 Windows 里使用。驱动包里有一部分明文配置，里面包含设备校正 FIR、场景参数和音圈保护数据。把它们找出来之后，就可以把其中一部分搬到 Linux 的 EasyEffects 里。

提示

如果这篇文章触犯了你的权益，请通过 `me@miprota.cc` 联系笔者删除

本文章没有解包相关的教程

本文章出现的脚本均可在 nahimic-factory-audio-tuning 中下载

先决条件

需要	本次环境
硬件	MECHREVO 蛟龙，Conexant SN6140
系统	CachyOS，PipeWire 1.6.8
效果器	EasyEffects 8.2.9（Flatpak）
原厂数据	Windows 分区里的 A-Volute/Nahimic 驱动包
工具	Python 3、``cabextract``、``objdump``、NumPy

下面的硬件匹配和听感只在这一组环境上验证过。换机型时，不能直接套用 FIR 或设备文件名。

一、先排除 EasyEffects 没生效

优先测试一下 EasyEffects 是否生效（虽然大概率不用测试）：

```bash
pw-play --target=<硬件输出端的名称> test.wav
```

播放仍然落在 `easyeffects_sink`，说明音频确实经过了 EasyEffects。

二、瞎猜的调教

在没有原厂数据前，我先按听感和常见的小扬声器问题手工搓了一条曲线：100 Hz 高通，220/420 Hz 附近衰减，再压一点 3.2 kHz。听起来比完全没有处理好一些，但那种塑料感还在。

问题在于，我不知道这块机器的箱体共振到底在哪。没有测量，也没有原厂曲线，继续改钟形（Bell）滤波器的 Q 值只是让一条猜出来的曲线变得更像“有依据”。这时才转向一个更直接的问题：Windows 上的 Nahimic 既然能按机型工作，调音数据应该存在哪里？

三、找到本机数据

先在 Linux 侧读取 codec、modalias 和子系统 ID：

```bash
cat /proc/asound/card2/codec#0 | grep -E "Vendor Id|Subsystem Id"
cat /sys/bus/hdaudio/devices/*/uevent | grep MODALIAS
```

本机得到的关键值是 `VEN_14F1 DEV_1F87` 和 `SUBSYS 1D053010`。Windows 驱动的 INF 里必须出现同一个 `HDAUDIO\\FUNC_01&VEN_14F1&DEV_1F87&SUBSYS_1D053010`，否则后面的 XML 不是这块声卡的调音数据。

调音档案按机型分文件，解析得越认真，假如硬件 ID 没对上，最后越可能是在认真研究别人的机器。

四、从 DriverStore 找到 XML

Nahimic 的配置在驱动包里，不在 Program Files。先在 Windows 分区定位 A-Volute 的扩展驱动：

```bash
find /mnt/windows/Windows/System32/DriverStore/FileRepository \\
  -maxdepth 2 -type f -iname '*.inf' -print \\
  | grep -iE 'avolute|nahimic|cnxt'
```

命令命中了 A-Volute 的 APO4 引擎和 CNXT（Conexant）扩展。INF 给出安装目录、设备匹配和 CAB 文件名。解包后得到 180 个明文 XML，结构大致分成：

`Global.nsx`：全局配置，采集链和全局开关
`AudioProfiles/*.nsx`：场景配置，音乐（Music）、电影（Movie）、游戏（Gaming）、通信（Communication）四个场景
`Devices/*_Speakers.nsx`：设备配置，按 SUBSYS/SMBIOS 区分的扬声器校正

提示

注意，不能只打开一个 `Music.nsx`：全局配置管采集链和全局开关，场景配置给出四个场景的差异，设备配置才是这台机器的扬声器校正。设备文件里最重要的是 `kSet_DeviceOptimizationFilterFL/FR`，它们是 2048 抽头的 float32 FIR，可以直接重放，不需要再猜一组 EQ 参数。

把 base64 解码后，每个通道正好是 8192 字节，也就是 2048 个 float32。能量集中在最前面的几个样本，符合最小相位校正滤波器的形状。到这里，小作坊手搓 EQ 已经有了一个明确的替代物：卷积器（Convolver）可以直接重放这条 FIR。

频响还有一个很直观的线索：两个设备变体都在 800 Hz 附近留下约 -2.7 dB 的凹陷。我的猜测曲线里没有这个位置，却在 3.2 kHz 做了衰减。出厂数据第一次把“听起来合理”与“确实是原厂曲线”分开了。

五、XML 导致的望文生义

XML 里有 `kSet_BassBoostGainDB`、`kSet_VoiceBoostGainDB` 这样的名字和值，但参数名不等于算法名。要知道一个旋钮接的是 EQ、动态压缩还是谐波生成，必须再看 DLL。

`NahimicAPO4.dll` 没有可用的 A-Volute 符号表，RTTI 里也只有标准库和 ATL 的类型。可行的路线是找阶段名字符串，再扫描 x64 的 RIP-relative `48 8D` 引用，定位它们被注册和读取的位置。过程中还踩过一次地址坑：objdump 输出的节区 VMA 已经包含映像基址，不能再额外加一遍 `0x180000000`。

这条路线能确认算法形态，但不能凭构造函数默认值宣称“所有运行时参数都找到了”。真实值仍然由 XML 经 `ApplyUserSettings` 写入。

低音增强（BassBoost）：从低架到钟形滤波，再到谐波增强

我在这里连续犯了两次错误。先把 `BassBoostFrequencyHz=250` 当成 EQ 的中心频率，做成了 +6 dB 的低架；又看到别的机型里有 `BassBoostBandWidthOctave=0.707`，推断它一定是 Q 约 2 的钟形滤波器。第二版的数学曲线能对上部分数字，却仍然解释不了“低音增强”为什么要凭空补出小扬声器放不出的基频。

第三次证据来自 DLL：类名是 `Ape::SBP::VirtualBassBoost`，内部还能看到 `ippsTanh_32f_A24`。它对低频做软饱和、生成奇次谐波，再把谐波混回去；静态 EQ 不会凭空产生新的频率成分。于是 EasyEffects 侧的对应物改成低音增强器（Bass Enhancer），且必须放在卷积器之前，让它先看到未经 FIR 切削的原始低频。

清晰度（Clarity）不等于人声增强（VoiceBoost）

早期还把清晰度当成了人声增强。反汇编读到的清晰度默认值是 200 / 8000 / 6 / 6，而 XML 里的人声增强频带是 500–4000 Hz，参数对不上。DLL 里也没有一个可以直接叫作 `voiceboost_stage` 的静态引用，所以这个等同关系撤回：人声增强的真实实现还没确认，预设不拿静态 EQ 硬凑。

六、从证据得到可复现的链路

现在才有足够依据列出哪些环节可以搬：

原厂环节	原厂实现	EasyEffects 处理	状态
设备优化滤波器	DeviceOptimizationFilter，2048 抽头 FIR	卷积器	已实现
低音增强	``VirtualBassBoost``，tanh 谐波生成	低音增强器	已实现
高音增强	TrebleBoost，``trebleboost_stage``	8 kHz 高架 EQ	已实现
人声增强	VoiceBoost，动态处理，算法未确认	不建模	跳过
DRC	动态增益/压缩	不使用自动增益	跳过
衰减器	Attenuator，频段音圈保护	无直接对应	跳过
限幅器	Limiter，原厂限幅阶段	保留插件但旁路	旁路

七、生成预设

完整工具在源码仓库中：

完整脚本：build_factory_preset.py 156 行 / 5.7 KB ｜直接下载

完整脚本：decode_nahimic.py 126 行 / 4.6 KB ｜直接下载

生成脚本默认从仓库根目录的 `data/Devices` 读原厂 XML，而仓库里不带 `data/`，解包出来的数据要自己放进去。路径可以用 `NAHIMIC_DEVICES`、`EASYEFFECTS_DATA` 覆盖，但只有部分脚本读这两个变量：其余脚本把 EasyEffects 数据目录写死在 Flatpak 路径下，换环境得改脚本。校正 FIR 必须关闭 `autogain`，否则 EasyEffects 会重新归一化掉原厂刻意保留的增益结构。

EasyEffects 的另一个易错点是扩展名：卷积器找的是 `.irs`，而脉冲响应的内容是 32 位 PCM WAV，照容器格式写成 `.wav` 就找不到了。`kernel-name` 同样不能带扩展名；两件事混在一起，结果就是对话框报错或卷积器悄悄进入直通。

八、四个场景和低频余量

音乐、电影、游戏、通信四个场景的差别主要在低音、高音、人声、空间效果和压缩器开关。当前场景脚本保留原厂场景参数，但不伪造人声增强；低频恢复使用 20–400 Hz 的多频段压缩，回收 FIR 带来的中频余量。

完整脚本：build_nahimic_music.py 184 行 / 6.9 KB ｜直接下载

完整脚本：add_bass_compressor.py 172 行 / 5.8 KB ｜直接下载

完整脚本：build_scenario_presets.py 289 行 / 11.5 KB ｜直接下载

完整脚本：build_official_eq_presets.py 153 行 / 5.0 KB ｜直接下载

完整脚本：build_capture_presets.py 143 行 / 6.2 KB ｜直接下载

提示

生成的 EasyEffects 预设里，链路顺序不能调换：低音增强器要在卷积器和 EQ 之前，否则谐波发生器拿到的低频已经被 FIR 切掉。出厂 FIR 在 80–400 Hz 有明显增益，整条链如果不处理余量，主观音量会被迫压低；因此加入只作用于 20–400 Hz 的多频段压缩器（Multiband Compressor），把低频峰值压下来，给中频和高频留出空间。限幅器保留在链里但旁路，防削顶由固定增益预算承担。

最终的音乐链路因此变成：

```text
低音增强器（虚拟低音增强的近似）
  → 卷积器（出厂 2048 抽头 FIR）
  → 高架 EQ（高音增强）
  → 多频段压缩器（仅 20–400 Hz）
  → 限幅器（旁路）
```

九、校验、失败和未决问题

预设生成后先跑校验：

完整脚本：validate_presets.py 183 行 / 8.1 KB ｜直接下载

完整脚本：validate_complete.py 93 行 / 3.4 KB ｜直接下载

其余工具分别用于 FIR 更新、HRTF 解码、SOFA/IRS 转换、反汇编和测量。它们按调查阶段分组：

完整脚本：update_irs.py 175 行 / 6.4 KB ｜直接下载

完整脚本：decode_hrtf.py 178 行 / 6.1 KB ｜直接下载

完整脚本：hrir_to_irs.py 164 行 / 6.0 KB ｜直接下载

完整脚本：hrir_to_sofa.py 277 行 / 11.6 KB ｜直接下载

完整脚本：build_headphone_presets.py 93 行 / 3.1 KB ｜直接下载

完整脚本：build_complete_preset.py 278 行 / 11.1 KB ｜直接下载

完整脚本：remove_limiter.py 162 行 / 5.3 KB ｜直接下载

完整脚本：measure.py 161 行 / 5.3 KB ｜直接下载

完整脚本：find_xrefs.py 110 行 / 3.4 KB ｜直接下载

完整脚本：disasm_window.py 96 行 / 2.7 KB ｜直接下载

HRTF 的 EasyEffects 路线已经撤销：单个立体声卷积核不能完成真正的多声道到双耳渲染，实测结果也不合格。扬声器 FIR 的 A/B 变体同样尚未根据本机主板精确判定，不能只凭文件数量猜测。

预设校验解决的是 JSON、插件键和值、FIR 文件名等机器可检查的问题；它不能替你判断 A/B 变体是否属于当前主板，也不能把 HRTF 的单方向卷积变成真正的多声道环绕。

文章里的脚本只保证代码与源码仓库同步；EasyEffects 插件版本、设备变体和实际听感仍需在使用者自己的环境中重新确认。

十、省流

我知道你不想看前面的长篇大论，只想看怎么执行步骤和结果，所以这里给出省流步骤：

克隆仓库

```bash
git clone https://github.com/LaT-SKY/nahimic-factory-audio-tuning --depth 1
```

仓库里只有 `tools/`，原厂数据要自己解包后放进去。

在 Windows 分区定位驱动包，解包后取出 `Global.nsx`、`AudioProfiles/`、`Devices/`、`MicProfile/`：

```bash
find /mnt/windows/Windows/System32/DriverStore/FileRepository \\
  -maxdepth 2 -type f -iname '*.inf' -print \\
  | grep -iE 'avolute|nahimic|cnxt'
```

确认硬件身份：

`/proc/asound/card*/codec#*` 里的 Vendor/Subsystem
`/sys/bus/hdaudio/devices/*/uevent` 里的 MODALIAS、INF 里的 `SUBSYS`

三处必须一致。

设置数据路径，再按需要覆盖路径（当然，你的路径可能与我不一致）：

```bash
export EASYEFFECTS_DATA="$HOME/.var/app/com.github.wwmm.easyeffects/data/easyeffects"
export NAHIMIC_DEVICES="$PWD/data/Devices"
```

只有 `build_factory_preset.py`、`build_complete_preset.py` 认这两个变量；其余脚本把路径写死在 Flatpak 数据目录下，换环境要改脚本。反汇编那两个认 `NAHIMIC_DLL`，`decode_nahimic.py` 认 `NAHIMIC_ARCHIVE`。

生成出厂卷积核与基础预设，当然，你大概率可以跳过这个步骤：

```bash
python3 tools/build_factory_preset.py
```

它从现有的 `output/Music.json` 里取限幅器键模板，所以先确认那个文件在。脚本里的设备文件名是本机的，换机型要改 `VARIANTS`。

按顺序搭音乐链路，后一个脚本会在前一个的产物上加多频段压缩器：

```bash
python3 tools/build_nahimic_music.py
python3 tools/add_bass_compressor.py
```

四个场景与采集链：

```bash
python3 tools/build_scenario_presets.py
python3 tools/build_capture_presets.py
```

另外 `build_official_eq_presets.py` 处理的是 Nahimic UWP 应用里的 10 段图形 EQ。它不在驱动包里，而在 Windows 用户目录的 `A-Volute.Nahimic_*/LocalState/Settings/v1/EQPresets/`，要自己复制到仓库的 `data/ui-eq-presets/` 下；这套参数与出厂 XML 不是一回事。

校验，然后在 EasyEffects 里核对三件事：

```bash
python3 tools/validate_presets.py
python3 tools/validate_complete.py
```

卷积器的 `autogain` 已关、`kernel-name` 不带扩展名、顺序是低音增强器 → 卷积器 → 高架 EQ → 多频段压缩器 → 限幅器（旁路）。

不要照抄的部分：人声增强、DRC、衰减器没有建模；HRTF 路线已撤销；扬声器 FIR 的 A/B 变体要按自己的主板判定。
你可以用 AI Agent 帮你完成上述步骤，你可以如下注入提示词：

```text
请帮我把 Windows 分区里的 Nahimic 出厂音效数据搬成 EasyEffects 预设。
按顺序做，每步先把命令和输出贴给我看，再进下一步；对不上就停下问我，不要猜。

0. 报告环境：发行版、PipeWire 版本、EasyEffects 版本与安装方式；
   当前目录没有仓库的话，先 git clone --depth 1 下面的仓库。
   https://github.com/LaT-SKY/nahimic-factory-audio-tuning
1. 读 /proc/asound/card*/codec#* 与 /sys/bus/hdaudio/devices/*/uevent，
   报出 Vendor Id、Subsystem Id 和 MODALIAS。
2. 在挂载好的 Windows 分区里找 A-Volute/Nahimic 的 INF
   （System32/DriverStore/FileRepository），读出里面的设备匹配串，
   确认 SUBSYS 与第 1 步一致；不一致就停，不要继续解包。
3. 解包 INF 指向的 CAB，把 Global.nsx、AudioProfiles/、Devices/、MicProfile/
   放进仓库的 data/ 目录，并告诉我实际路径。
4. 列出仓库里哪些脚本读环境变量、哪些把路径写死；写死的按我的实际路径改，
   改动逐条给我看。EasyEffects 若是 Flatpak，数据目录是
   ~/.var/app/com.github.wwmm.easyeffects/data/easyeffects
5. 依次跑 tools/build_factory_preset.py、build_nahimic_music.py、
   add_bass_compressor.py、build_scenario_presets.py、build_capture_presets.py。
   其中 build_factory_preset.py 要从已有的 output/Music.json 取限幅器键模板，
   缺这个文件就先告诉我。
6. 跑 tools/validate_presets.py 与 tools/validate_complete.py，把结果报给我。
7. 核对预设：卷积器的 autogain 已关、kernel-name 不带扩展名、顺序是
   低音增强器 → 卷积器 → 高架 EQ → 多频段压缩器 → 限幅器（旁路）。

底线：不要伪造参数，不要把没验证的算法写成结论。人声增强、DRC、衰减器没有建模，
不要自己补；HRTF 那条路已经撤销；扬声器 FIR 的 A/B 变体必须由我确认，
不能按文件数量猜。
```

TUN 的 fake-ip 让抓取工具拒绝了所有域名

Tue, 22 Sep 2026 00:00:00 GMT

网页抓取工具 `web_fetch` 在任意 URL 上都立即失败：

```plaintext
Error: URL hostname "example.com" resolves to a non-public IP address
```

失败是瞬时的，没有网络等待。同一时间 `web_search` 正常，浏览器和 `curl` 访问同一个 URL 也正常。

环境

项	值
系统	CachyOS（Arch）
代理	Clash Verge Rev，mihomo 内核，TUN 模式
DNS	systemd-resolved → NetworkManager 的 dnsmasq
工具	DSH ``web_fetch``（``@deepseek-ai/dsh-web-fetch-http``）

复现这个问题需要两个条件：内核开着 fake-ip（TUN 模式最容易碰到），以及被调用的工具会校验目标地址是不是公网地址。

这套做法在什么环境上验证过

```plaintext
CachyOS (Arch) ｜ Clash Verge Rev（mihomo 内核）｜ TUN 模式 ｜ 混合端口 7897
```

只在这一个组合上实测过。下面这些地方会因环境而异：

`198.18.0.0/15` 这个假地址段：⚠️ 取决于内核的 `fake-ip-range`。判断方法不变：解析结果落在保留段里就是它。
`enhanced-mode` 与 `IPV6` 两个键：✅ mihomo 系内核通用，键名一致。
用 Merge 覆写订阅配置：⚠️ 这是 Clash Verge Rev 的做法，别的客户端一般直接改配置本体。
拦截发生在工具侧：⚠️ 本次被测的是 DSH 的 `web_fetch`。换一个工具，只要它做公网地址校验就会复现；不做校验的工具不会。
`dns.ipv6: false` 从哪来：❌ 因 Verge 版本而异。本次是它的 IPv6 开关注入的，关掉那个开关这条就没了。

一、先看域名解析出来的是什么

```bash
getent hosts example.com
# 198.18.0.64     example.com

getent ahostsv4 www.baidu.com
# 198.18.0.65     STREAM www.baidu.com
```

`198.18.0.0/15` 是 RFC 2544 给网络设备基准测试留的保留段，不可能是真实网站地址。

这正是 Clash / mihomo 的 fake-ip 模式：给每个域名发一个假地址，应用连到假地址，由 TUN 网卡按域名转发。这台机器上那张网卡叫 `Meta`，地址是 `198.18.0.1/30`。

二、glibc 与 c-ares 走的是两条路

同一个域名，两次查询结果不同：

```bash
node -e "require('node:dns').lookup('example.com',{all:true},(e,a)=>console.log(e||a))"
# [ { address: '198.18.0.64', family: 4 } ]

node -e "require('node:dns').resolve4('example.com',(e,a)=>console.log(e?e.code:a))"
# [ '104.20.23.154', '172.66.147.243' ]
```

`dns.lookup()` 走 glibc 的 `getaddrinfo`，`dns.resolve4()` 是 c-ares 直接问 DNS 服务器。差别在 `nsswitch.conf` 的顺序：

```bash
grep '^hosts' /etc/nsswitch.conf
# hosts: mymachines resolve [!UNAVAIL=return] files myhostname dns
```

`resolve`（nss-resolve，问 systemd-resolved）排在 `dns`（127.0.0.1 上的 dnsmasq）前面。而 resolved 把 TUN 那条链路当成了默认 DNS 源：

```bash
resolvectl status Meta
#     Current DNS Server: 198.18.0.2
#            DNS Servers: 198.18.0.2
#             DNS Domain: ~.
#            Default Route: yes
```

`DNS Domain: ~.` 加上 `Default Route: yes`，意思是所有域名都交给 mihomo 的 DNS，于是全部返回 fake-ip。

绕开 resolved 直接问本机 dnsmasq，拿到的是真实地址：

```bash
dig +short @127.0.0.1 example.com A
# 104.20.23.154
# 172.66.147.243
```

三、工具为什么拒绝

`web_fetch` 在发请求前会先解析主机名，再逐个校验地址范围：

```js
if (parsed instanceof ipaddr.IPv4) return parsed.range() === "unicast";
```

`ipaddr.js` 把 `198.18.0.0/15` 归类为 `reserved`：

```bash
node -e "const i=require('ipaddr.js');console.log(i.parse('198.18.0.64').range())"
# reserved
```

校验不通过就抛错。这是有意的 SSRF 防护，目的是不让抓取工具去访问回环、内网和链路本地这些地址。fake-ip 让所有公网域名都“看起来”是保留地址，于是全被拦下。

同一个文件里还有一条给代理留的分支：请求若被判为走代理，就不再本地解析、也不做地址钉扎，域名交给代理去解析。

```js
const route = proxyRouteFor(url);
if (route.proxied && !isNonPublicIpLiteral(url.hostname))
  return await publicHttpNetwork.requestVia(route.dispatcher, url, headers, signal);
const addresses = await this.resolveAddresses(url.hostname, signal)
```

四、三条修法

给工具配出站代理。在工具的用户级环境文件里写 `HTTP_PROXY` / `HTTPS_PROXY`，走上面那条代理分支。改动最小、随时可回滚。代价是它依赖代理进程一直在跑：代理完全退出时这条工具会连不上，而且没有直连回退。另外 TUN 关掉、系统代理关掉时这条照样成立 —— 混合端口是内核自己的监听，与那两个开关无关。
改 `nsswitch.conf` 顺序，把 `dns` 提到 `resolve` 前面，让 glibc 走 dnsmasq 拿真实地址。从根上恢复真实解析。代价是它改变全系统的解析行为，而且需要 root；mihomo 每次重启都会重设 TUN 链路的 DNS。
关掉 fake-ip（本次采用）。在 Clash Verge 的全局扩展配置里把 DNS 的 `enhanced-mode` 覆写成 `redir-host`。改完不依赖任何代理进程存活，TUN 开着也正常。

五、关掉 fake-ip

mihomo 的 DNS `enhanced-mode` 有两个取值：`fake-ip` 和 `redir-host`，默认是 `redir-host`，所以这一步是回到默认行为，不是 hack。

Clash Verge Rev 的全局扩展配置（Merge）可以覆写订阅里的设置，`dns` 不在禁止覆写的名单里（名单是 mixed-port、log-level、external-controller 这一批）。

在 `Merge.yaml` 末尾追加：

```yaml
dns:
  enhanced-mode: redir-host
```

改完不会自动生效。实测：改完当时 `clash-verge.yaml` 的 mtime 没变，里面的 `enhanced-mode` 还是 `fake-ip`，`getent` 也还是返回 `198.18.0.64`。

让它生效的办法是重启 Clash Verge（实测有效：重启后 `clash-verge.yaml` 与 `config.yaml` 先后更新，`enhanced-mode: redir-host` 落盘）。

注意

只「重开内核」不生效 —— 实测重启内核不会重新读 profile，`enhanced-mode` 还是旧值。得让 Verge 本体重启一次。

六、第二个坑：AAAA 污染

`redir-host` 生效后普通站点恢复了，但 `www.google.com` 仍然报同一个错。原因跟 fake-ip 无关：

```bash
dig +short @198.18.0.2 www.google.com A      # 31.13.92.37   ← Facebook 的地址
dig +short @198.18.0.2 www.google.com AAAA   # 2001::1       ← Teredo 段
```

这台机器用的是订阅自带的 DNS（全是国内 DNS），也没有配 `fallback`：这类配置对部分境外域名的应答本身就可能被污染。

而校验的策略是整个应答集里只要有一个地址不是公网地址就整体拒绝：A 记录没问题，AAAA 记录把它拖垮了。同一批里 `youtube.com`、`www.facebook.com`、`www.wikipedia.org`、`twitter.com` 的 AAAA 也是 `2001::1`。

让 DNS 干脆不返回 AAAA 就行：`dns.ipv6: false`。这台机器上它是 Clash Verge 的 IPv6 开关注入的（`config.yaml` 与合并后的 `clash-verge.yaml` 里各有一处，而 `profiles/` 下所有文件都不含 `ipv6`）。

丢掉 AAAA 不损失可达性：本机没有全局 IPv6 地址，也没有 IPv6 默认路由。mihomo 文档里 `IPV6` 为 false 的行为是“回应 AAAA 的空解析”，是正规做法。

提示

两个条件缺一不可：`dns.enhanced-mode: redir-host` 消除 fake-ip， `dns.ipv6: false` 消除污染 IPv6。只做前者时，应答被污染的那些域名仍然会失败。

七、验证结果

在 TUN 开启（`Meta` 网卡在）的状态下实测：

`getent ahostsv4 example.com`：`104.20.23.154`，不再是 `198.18.x.x`
`resolvectl query example.com`：真实 IPv4（仍标注 `-- link: Meta`，内容是真实地址）
`web_fetch` 访问 `example.com` / `www.google.com` / `www.youtube.com` / `www.wikipedia.org` / `www.facebook.com` / `github.com` / mihomo 官方文档 / `raw.githubusercontent.com`：全部 200
`web_search`：正常
`env | grep -i proxy` 为空，`~/.dsh/.env` 不存在：修复不依赖代理进程
浏览器与 `curl` 侧回归：`google.com` / `youtube.com` / `baidu.com` / `github.com` 全部 200，标题正确

八、自检命令

```bash
# 是否还在 fake-ip：出现 198.18.x.x 就是中招
getent ahostsv4 example.com

# resolved 是否把 TUN 链路当成了全域名 DNS
resolvectl status Meta | grep -E 'DNS Server|DNS Domain|Default Route'
resolvectl query example.com

# 绕开 resolved 的真实解析
dig +short @127.0.0.1 example.com A

# AAAA 有没有被污染
dig +short @198.18.0.2 www.google.com AAAA

# 混合代理端口可用性（默认 7897）
curl -s -o /dev/null -w '%{http_code}\n' -x http://127.0.0.1:7897 https://example.com/
```

九、排错

改了 `Merge.yaml` 没变化

可能原因：Verge 不监听 profile 文件，改完不会自动重新应用。

怎么办：重启 Clash Verge（只重开内核不生效，见第五节）；然后用 `grep enhanced-mode` 看 `clash-verge.yaml` 里落盘的值。
普通站点好了，个别站点仍然报同一个错

可能原因：那个域名的 AAAA 应答被污染，整个应答集因此被判为非公网。

怎么办：`dig +short @<你的 DNS> <域名> AAAA` 看一眼；是 `2001::1` 之类就确认 `dns.ipv6: false` 生效了。
TUN 关掉后一切正常，开着就坏

可能原因：TUN 链路带来了 `DNS Domain: ~.` 的 DNS 源，也就是 fake-ip 的来源。

怎么办：按第五节改 `enhanced-mode`；只想临时绕开就先关 TUN。
`dns.lookup()` 与 `dns.resolve4()` 结果不一致

可能原因：前者走 glibc 的 nsswitch 链，后者走 c-ares 直接查 DNS。

怎么办：`grep '^hosts' /etc/nsswitch.conf` 看顺序。判断“解析是否被代理接管”要用前者的结果。

参考

mihomo DNS 文档 —— `enhanced-mode`、`IPV6`、`nameserver-policy` 的定义
Clash Verge Rev — Merge Configuration —— 全局扩展配置能覆写什么、不能覆写什么
RFC 2544 —— `198.18.0.0/15` 这个保留段的出处

树莓派插上网线就能连：给 eth0 加 link-local 回退

Tue, 22 Sep 2026 00:00:00 GMT

起因

朋友给了一台树莓派。我先把电脑开成一个同名热点，想让 Pi 自己连上来，没成。改用网线直连，还是有问题。于是有了这套调研。

这台树莓派 5（Ubuntu 24.04）原来只有一个 `dhcp4: true`：谁来发地址，谁就是单点故障。

中间接个交换机、或者换成一台默认不发地址的电脑直连，就拿不到 IPv4，只剩 mDNS 和 IPv6 那两条路可走。

现在的目标是插上网线就能连：

```bash
ssh pi          # 等价于 ssh pi@pi.local
```

下面把主机名与用户名都写成 `pi`，命令里换成你自己的即可。

先决条件

一台跑 Debian / Ubuntu 的单板机（本次是树莓派 5），网络栈是 netplan → systemd-networkd
有 `sudo`：要往 `/etc/netplan/` 写文件，再跑一次 `netplan apply`
客户端这边不用装什么：Linux 上 `.local` 要有 mDNS（`libnss-mdns` 与 `avahi-daemon`），装不了就走固定锚点
想用锚点地址的话，客户端要能给自己加一个 `192.168.77.2/24`

这套做法在什么环境上验证过

```plaintext
树莓派 5 ｜ Ubuntu 24.04 ｜ systemd 255（netplan → systemd-networkd）
客户端：CachyOS（Arch）—— 下面所有通路都是在这一台机器上测的
```

只在这一个组合上实测过。 下面这些地方会因环境而异：

「DHCP 失败才补 IPv4LL」的语义：✅ systemd-networkd 通用，出处见第三节的 man 引文。
覆盖文件的加载顺序：✅ netplan 按文件名字典序合并，`70-` 排在 `50-` 之后，所以它是补充而不是被顶掉。
`link-local: [ipv4, ipv6]` 这个键：✅ netplan 通用。不用 netplan 的话，对应的 systemd-networkd 设置是 `LinkLocalAddressing=`。
avahi 发布的 `名字.local`：✅ 通用，跟着主机名走，与地址无关。
IPv6 link-local 与 MAC 绑定：✅ 通用，换网卡或换机器就会变。
Windows / macOS 直连：⚠️ 没有实测。按它们的默认行为写（Win/mac 会自己配 IPv4LL、macOS 自带 Bonjour），照抄前自己确认一遍。
手机 + USB-C 网卡走锚点：⚠️ 没有实测，同上。
锚点地址 `192.168.77.1/24`：⚠️ 网段是自选的，只要不和家里网段撞就行。

一、以前与现在的差别

电脑开着网络共享：以前能连（NetworkManager 的共享模式会发 `10.42.0.x`），现在一样能连。
换一根网线：以前能连，现在能连（千兆口自动 MDIX，什么线都行）。
接交换机，没有人发地址：以前拿不到 IPv4，只能靠 mDNS/IPv6；现在约 10 秒后自动上 `169.254.x.x`，`ssh pi` 直接可用。
插到家里的路由器上：以前能连，现在一样能连。
换一台 Windows / macOS 电脑直连：以前那台电脑默认不发地址；现在它自己会配 `169.254.x.x`（Win/mac 的默认行为），mDNS 也能解析 `pi.local`。
手机加 USB-C 网卡直连：以前不行；现在 mDNS 支持差的设备可以用锚点 `192.168.77.1`（手机静态设 `192.168.77.2/24`）。

改动只有一件：给 eth0 加了 IPv4 link-local 回退，外加一个永久的固定锚点。

二、现在同时具备的四条通路

DHCP：对端有 DHCP 服务器时自动获得。不需要对端额外配置。
固定锚点 `192.168.77.1`：永远都在。需要客户端手工配 `192.168.77.2/24`，不用配网关。
IPv4 link-local `169.254.x.y`：DHCP 失败约 10 秒后自动加上，地址每次自动选、会变。需要客户端也支持 IPv4LL（Win / macOS / Linux 默认都支持）。
IPv6 link-local `fe80::…`：与网卡 MAC 绑定，永远都在、零配置。需要客户端有 IPv6，默认都有。

名字那条路是 `pi.local`（avahi / mDNS），它会同时发布上面所有地址，地址变了自动跟着变。所以平时只需要记住 `ssh pi`。

提示

第四条通路的地址由 MAC 派生，换网卡或换硬件就变；`pi.local` 不受影响。网络里如果出现第二台同名机器，avahi 会把它改名成 `pi-2.local`。

三、Pi 上改了什么

新增的文件只有一个，`/etc/netplan/70-eth0-fallback.yaml`：

```yaml
# 让 eth0 在有/没有 DHCP 服务器时都能连
# 优先级：DHCP（对端有服务器时，比如电脑共享或家里路由器）> 固定锚点 192.168.77.1 > IPv4 link-local 169.254.x.x
network:
  version: 2
  ethernets:
    eth0:
      dhcp4: true
      optional: true
      # 同时开启 IPv4/IPv6 链路本地地址，完全不依赖任何服务器
      link-local: [ipv4, ipv6]
      # 固定锚点地址：给不支持 mDNS 的客户端手工直连用
      addresses:
        - 192.168.77.1/24
```

原有的 `/etc/netplan/50-cloud-init.yaml` 没动，改之前备份了一份到 `/root/`。

应用方式：

```bash
sudo netplan generate && sudo netplan apply
```

注意这套网络栈是 netplan → systemd-networkd，eth0 在 NetworkManager 里是 `unmanaged`，所以用 `nmcli` 改是没有用的。

为什么 DHCP 正常时看不到 169.254

systemd 255 的 man 页写得很直接：

An IPv4 link-local address is configured when `yes` or `ipv4` and when DHCPv4 autoconfiguration has been unsuccessful for some time.

有 DHCP 就优先用 DHCP，失败才补 IPv4LL。这正是想要的语义：多一条兜底，不改动正常情况下的行为。

实测（用一对 veth 造了一条没有 DHCP 服务器的链路，不碰 eth0）：

`DHCP=ipv4` 加 `LinkLocalAddressing=ipv4`：10 秒内拿到 `169.254.112.168/16`。
在此基础上再加静态地址（模拟锚点）：两者共存，锚点不会顶掉回退。

四、两个脚本

上面那份配置手写也就十行，但「备份 → 写入 → 校验 → 应用 → 验证」这套动作值得脚本化，另外脚本里加了一道自动回滚保险。两个脚本都是幂等的，重复跑安全。

``setup-pi.sh``：在 Pi 上跑

它会先把 `/etc/netplan/` 里现有的配置备份到 `/root/`（带时间戳，不覆盖旧备份），再写新文件、`netplan generate` 校验语法，然后挂一个 180 秒的自动回滚定时器才应用 —— 如果新配置把网络弄断了，180 秒后它会自己删掉新文件并恢复。

```bash
# 在 Pi 上（或 ssh 进去）
ssh pi@pi.local 'sudo bash -s' < setup-pi.sh
```

```bash
#!/usr/bin/env bash
# 在树莓派上运行（或 ssh 进去运行）：让 eth0 在没有 DHCP 服务器时也能连上。
#
#   用法： ssh pi@pi.local 'sudo bash -s' < setup-pi.sh
#   幂等：重复运行安全；自带 180 秒自动回滚保险。
#
# 目的：不再依赖"某一台电脑负责发地址"。插上网线后，无论对端是
#   - 家里路由器（有 DHCP）        -> 拿路由器分配的地址
#   - 一台开着网络共享的电脑        -> 拿电脑分配的地址
#   - 交换机 / 另一台什么都没配的电脑 -> 自动上 169.254.x.x（IPv4 link-local）
#   - 永远都在                    -> 固定锚点 192.168.77.1 + IPv6 链路本地 fe80::
# 四种情况都能连。

set -euo pipefail

CONF=/etc/netplan/70-eth0-fallback.yaml
ANCHOR=192.168.77.1/24
STAMP=$(date +%F-%H%M%S)

[[ $EUID -eq 0 ]] || { echo "请用 sudo 运行：sudo bash $0" >&2; exit 1; }

echo "==> 1/5 备份现有 netplan 到 /root/"
for f in /etc/netplan/*.yaml; do
  [[ $f == "$CONF" ]] && continue
  dest="/root/$(basename "$f").bak-$STAMP"
  [[ -e $dest ]] || cp -a "$f" "$dest"   # 不覆盖已有备份
done
ls -1t /root/*.bak-* 2>/dev/null | head -5

echo "==> 2/5 写入 $CONF"
cat > "$CONF" <<'YAML'
# 由 setup-pi.sh 生成：让 eth0 在有/没有 DHCP 服务器时都能连
# 优先级：DHCP > 固定锚点 192.168.77.1 > IPv4 link-local 169.254.x.x
network:
  version: 2
  ethernets:
    eth0:
      dhcp4: true
      optional: true
      link-local: [ipv4, ipv6]
      addresses:
        - 192.168.77.1/24
YAML
chmod 600 "$CONF"

echo "==> 3/5 校验语法（失败则不动任何东西）"
netplan generate
echo "    语法 OK"

echo "==> 4/5 挂 180 秒自动回滚保险，然后应用"
systemd-run --on-active=180 --unit=netplan-rollback \
  /bin/bash -c "rm -f $CONF; netplan apply" >/dev/null 2>&1 || true
netplan apply
sleep 8

echo "==> 5/5 验证"
ip -brief addr show eth0 || true

if ip -4 addr show eth0 | grep -q "${ANCHOR%/*}"; then
  systemctl stop netplan-rollback.timer 2>/dev/null || true
  systemctl reset-failed netplan-rollback.timer netplan-rollback.service 2>/dev/null || true
  echo
  echo "✅ 成功：锚点 ${ANCHOR%/*} 已生效，回滚保险已取消。"
  echo "   现在这些通路都可用（mDNS 名称 pi.local 会同时发布它们）："
  echo "     - DHCP 地址        ：有 DHCP 服务器时自动获得"
  echo "     - 固定锚点         ：${ANCHOR%/*}  （客户端配 192.168.77.2/24 即可直连）"
  echo "     - IPv4 link-local  ：169.254.x.x  （无 DHCP 服务器时约 10 秒后自动获得）"
  echo "     - IPv6 link-local  ：fe80::...    （一直都在，无需任何服务器）"
  exit 0
else
  echo "⚠️  没看到锚点地址，180 秒后会按原配置自动回滚。" >&2
  exit 1
fi
```

``setup-client.sh``：在要连 Pi 的那台电脑上跑

不需要 `sudo`，不改系统配置，只往 `~/.ssh/config` 写两个别名（`pi` 走 mDNS、`pi-anchor` 走固定锚点），然后按优先级探测一遍，告诉你哪条通路通了。

```bash
bash setup-client.sh
```

⚠️ 跑之前先把脚本开头那两行改成你自己的主机名与用户名（`PI_NAME` / `PI_USER`，示例值是 `pi.local` 与 `pi`）。

```bash
#!/usr/bin/env bash
# 在一台新电脑上运行（Linux / macOS），配好连接树莓派所需的一切。
#
#   用法： bash setup-client.sh
#   不需要 sudo，不改系统配置，只写 ~/.ssh/config。
#
# ⚠️ 先改下面两行：主机名与用户名换成你自己的（下面是示例值）。
#
# 做的事：
#   1. 检查本机 mDNS（.local 域名）解析能力
#   2. 没有 SSH 密钥就生成一个
#   3. 往 ~/.ssh/config 写 pi / pi-anchor 两个别名
#   4. 按优先级探测树莓派，并说清哪条通路通了、哪条没通

set -uo pipefail

PI_NAME="pi.local"
PI_USER="pi"
PI_ANCHOR="192.168.77.1"
PI_ANCHOR_NET="192.168.77"
ANCHOR_CLIENT_IP="192.168.77.2"
KEY="$HOME/.ssh/id_ed25519"
CFG="$HOME/.ssh/config"

ok()   { printf '  \033[32m✅ %s\033[0m\n' "$*"; }
bad()  { printf '  \033[31m❌ %s\033[0m\n' "$*"; }
warn() { printf '  \033[33m⚠️  %s\033[0m\n' "$*"; }
step() { printf '\n==> %s\n' "$*"; }

OS=$(uname -s)
step "环境"
echo "  系统: $OS $(uname -r)"

# ---------- 1. mDNS ----------
step "1/4 检查 mDNS（.local 域名解析）"
case "$OS" in
  Darwin)
    ok "macOS 自带 Bonjour，$PI_NAME 可直接用" ;;
  Linux)
    if getent hosts "$PI_NAME" >/dev/null 2>&1; then
      ok "已能解析 $PI_NAME -> $(getent hosts "$PI_NAME" | awk '{print $1}' | tr '\n' ' ')"
    elif systemctl is-active --quiet avahi-daemon 2>/dev/null; then
      warn "avahi 在跑，但暂时解析不到 $PI_NAME（Pi 可能没插线/没开机）"
    else
      bad "本机缺少 mDNS 支持，$PI_NAME 解析不了"
      echo "     装一下（Debian/Ubuntu）： sudo apt install libnss-mdns avahi-daemon"
      echo "     或者退回固定锚点： 见下面 pi-anchor 别名"
    fi ;;
  *)
    warn "未知系统，跳过 mDNS 检查" ;;
esac

# ---------- 2. 密钥 ----------
step "2/4 检查 SSH 密钥"
mkdir -p "$HOME/.ssh"; chmod 700 "$HOME/.ssh"
if [[ -f "$KEY" ]]; then
  ok "已有 $KEY"
else
  if ssh-keygen -t ed25519 -N '' -f "$KEY" >/dev/null 2>&1; then
    ok "已生成新密钥 $KEY"
    warn "这是新电脑的新密钥：Pi 上默认没有它。两种办法登录——"
    echo "       (a) 用密码登录一次，然后 ssh-copy-id $PI_USER@$PI_NAME"
    echo "       (b) 直接把老电脑的 $KEY 拷过来"
  else
    bad "密钥生成失败，请手动 ssh-keygen -t ed25519"
  fi
fi

# ---------- 3. ssh config ----------
step "3/4 写入 ~/.ssh/config"
if grep -qE "^Host\s+.*\bpi\b" "$CFG" 2>/dev/null; then
  ok "已存在 pi 相关配置，跳过（没动你的文件）"
else
  {
    echo ""
    echo "# 连树莓派用的 SSH 别名 —— 由 setup-client.sh 添加"
    echo "# 用法: ssh pi        (走 mDNS 名称，换网线/换地址都自动跟随)"
    echo "#      ssh pi-anchor (走固定锚点，需要本机有 192.168.77.x 地址)"
    echo "Host pi $PI_NAME"
    echo "    HostName $PI_NAME"
    echo "    User $PI_USER"
    echo "    IdentityFile ~/.ssh/id_ed25519"
    echo "    IdentitiesOnly yes"
    echo "    ServerAliveInterval 30"
    echo "    StrictHostKeyChecking accept-new"
    echo ""
    echo "Host pi-anchor"
    echo "    HostName $PI_ANCHOR"
    echo "    User $PI_USER"
    echo "    IdentityFile ~/.ssh/id_ed25519"
    echo "    IdentitiesOnly yes"
    echo "    StrictHostKeyChecking accept-new"
  } >> "$CFG"
  chmod 600 "$CFG"
  ok "已写入 $CFG（pi / pi-anchor）"
fi

# ---------- 4. 探测 ----------
step "4/4 探测树莓派"
try_ssh() {
  ssh -o BatchMode=yes -o ConnectTimeout=6 -o StrictHostKeyChecking=accept-new \
      "$PI_USER@$1" 'echo $(hostname)' 2>/dev/null
}

CONNECTED=""
if H=$(try_ssh "$PI_NAME") && [[ -n "$H" ]]; then
  ok "mDNS 通路可用：ssh $PI_USER@$PI_NAME  (主机名 $H)"
  CONNECTED=1
else
  bad "mDNS 通路不通：$PI_USER@$PI_NAME"
fi

if [[ -z "$CONNECTED" ]]; then
  if ip -4 -o addr 2>/dev/null | grep -q "$PI_ANCHOR_NET\." || \
     ifconfig 2>/dev/null | grep -q "inet $PI_ANCHOR_NET\."; then
    if H=$(try_ssh "$PI_ANCHOR") && [[ -n "$H" ]]; then
      ok "锚点通路可用：ssh $PI_USER@$PI_ANCHOR  (主机名 $H)"
      CONNECTED=1
    else
      bad "锚点通路不通：$PI_USER@$PI_ANCHOR"
    fi
  else
    warn "本机没有 $PI_ANCHOR_NET.x 地址，锚点通路用不了"
    echo "     想用它就手工加一个地址（需要管理员权限）："
    case "$OS" in
      Darwin) echo "       sudo ifconfig \$(route -n get default | awk '/interface/{print \$2}') alias $ANCHOR_CLIENT_IP netmask 255.255.255.0" ;;
      *)      echo "       sudo ip addr add $ANCHOR_CLIENT_IP/24 dev <你的网卡名>" ;;
    esac
  fi
fi

if [[ -z "$CONNECTED" ]]; then
  echo
  warn "两条路都不通。快速排查："
  echo "     · 网线插好了吗？Pi 的网口灯亮吗？（Pi 5 千兆口支持任意网线，不需要交叉线）"
  echo "     · 看本机邻居表里有没有可疑的 Pi："
  case "$OS" in
    Darwin) echo "         arp -a | grep -E '169\\.254|$PI_ANCHOR_NET|10\\.42\\.'" ;;
    *)      echo "         ip neigh | grep -E '169\\.254|$PI_ANCHOR_NET|10\\.42\\.'" ;;
  esac
  echo "     · 找不到就用 IPv6 广播 ping 整条链路："
  echo "         ping6 -c3 ff02::1%<你的网卡名>   # macOS/Linux"
  echo "     · 还是没有：Pi 没开机，或者它卡在启动 / 别的问题"
  exit 2
fi

echo
ok "搞定。以后一条命令： ssh pi"
```

五、重启验证

断电重启是这个方案里没法在运行中验证的一环，所以单独测了一次：

确实重启了：开机时间从 `04:23:06` 变成 `05:21:51`。
eth0 地址：重启前是静态锚点、DHCP 地址、`fe80::…` 三个，重启后完全一致，全部自动恢复。
默认路由：`via 10.42.0.1`（走电脑共享上网），一致。
avahi 与 ssh：都是 active，且自启。
`ssh pi`：可用，Pi 出网也正常。
多余的 169.254：无。有 DHCP 时本来就不该有。

重启耗时：kernel `5.357s` + userspace `44.844s`，掉线到 SSH 恢复大约 30 秒。

结论：配置是持久的，拔电、换线、换电脑都不需要再动 Pi。

六、换一台新电脑怎么连

跑一遍 `setup-client.sh`（见上一节）。手动做的话是这三步：

```bash
# 1) 先看通路在不在
ping -c1 pi.local
arp -a | grep -E '169\.254|192\.168\.77|10\.42\.'    # .local 不通时用这个找地址

# 2) 新电脑的公钥还没装到 Pi 上时，先用密码登录一次
ssh-copy-id pi@pi.local

# 3) 写 ssh 别名，以后直接用 ssh pi
cat >> ~/.ssh/config <<'EOF'
Host pi
    HostName pi.local
    User pi
EOF
```

第三步里 `HostName` 用 `pi.local`；如果这台电脑解析不了 `.local`，把它改成 `192.168.77.1`（网卡先设静态 `192.168.77.2/24`）即可。

`.local` 解析需要 mDNS：Debian / Ubuntu 上 `sudo apt install libnss-mdns avahi-daemon`。Ubuntu 22.04 之后的 systemd-resolved 通常也能直接解析。装不了就用锚点地址。

Windows 10 / 11 自带 mDNS 解析和 OpenSSH，基本开箱可用：

```powershell
# 1) 探测
ping pi.local
ssh pi@pi.local                # 首次问指纹，输 yes；没有密钥就用密码
# 2) 万一 .local 不通，从邻居表里找地址
arp -a | findstr "169.254 192.168.77 10.42."
# 3) 写别名：%USERPROFILE%\.ssh\config
```

实在解析不了 `pi.local` 时，给网卡设静态地址 `192.168.77.2 / 255.255.255.0`，然后 `ssh pi@192.168.77.1`。

七、连不上时的排查顺序

```bash
# ① 名字能不能解析（能解析说明 avahi 在，只是路可能不通）
avahi-resolve -n pi.local

# ② 邻居表里找 Pi：三条通路各自的网段
ip neigh | grep -E '169\.254|192\.168\.77|10\.42\.'     # Linux
arp -a                                                  # macOS / Windows

# ③ 整条链路 IPv6 广播 ping，最底层的"有人吗"
ping6 -c3 ff02::1%<你的网卡名>        # 会列出链路上所有 IPv6 主机

# ④ mDNS 彻底不通时，用锚点（客户端先配 192.168.77.2/24）
ssh pi@192.168.77.1
```

网口灯不亮就是物理层问题，先换线换口。

实测遇到过一次 `ssh: Could not resolve hostname pi.local: Temporary failure in name resolution`。那是客户端 mDNS 解析的瞬时抖动，当时 Pi 完全正常（直连 IP 与 IPv6 广播 ping 都通），重试一次或者直接用 IP 连就好。 mDNS 只是方便，不是非它不可 —— 这也是锚点地址一直留着的理由。

八、几条运维备注

登录 shell 是 fish 的话：`ssh pi@pi.local '带*通配符的命令'` 会被 fish 解析而报错，脚本化时写成 `ssh pi@pi.local 'bash -s' <<'EOF'` 这种显式 bash 的形式。
两条默认路由的 metric：同时接了有线与 WiFi 时，metric 小的优先（netplan 里可以给 WiFi 设 50、有线设 100），于是插着网线也可能走 WiFi。自己按需要调。
换硬件或重刷系统之后 SSH 指纹会变：客户端执行 `ssh-keygen -R pi.local` 清掉旧记录。
`optional: true` 别省：没有它时，DHCP 等不到地址会拖慢开机（systemd-networkd 要等超时）。

九、怎么撤销

```bash
sudo rm -f /etc/netplan/70-eth0-fallback.yaml && sudo netplan apply

# 需要的话再还原云初始化的那份
sudo cp /root/50-cloud-init.yaml.bak /etc/netplan/50-cloud-init.yaml
```

参考

`systemd.network` — `LinkLocalAddressing=`：DHCP 失败才补 IPv4LL 那条语义的出处
netplan 文档：`link-local`、`optional` 等键的说明
RFC 3927：IPv4 link-local 地址（`169.254.0.0/16`）的规范

链接悬停填充：细线长满、文字翻色，以及一些奇怪的 BUG

Mon, 21 Sep 2026 00:00:00 GMT

文章正文里的链接，悬停时底部那条细线向上长满整个链接，文字同时从链接色翻成背景色。下面是这套效果的实现、实测数据，以及它在什么环境下不成立。

数字都在本机 Chromium 151（Chrome for Testing）上用 CDP 量的，量法写在「怎么复算」一节。最后，这是一篇记录向，可能对你没有帮助。

目标与参数

项	取值
静止态	一条 2px 细线，撑满链接宽度，位置与原来的下划线重合
悬停态	细线向上长满（``background-size: 100% 2px`` → ``100% 100%``）
文字	从 ``--rose-ink`` 翻成 ``--paper``
时长 / 缓动	``--dur-base``（260ms）/ ``--ease-out``
触屏	阉割
键盘	``:focus-visible`` 与 hover 走同一套

填充色与翻转色是既有链接色的反用：`--rose-ink` 压在 `--paper` 上是 5.12:1，反过来的对比度相同，所以没有引入新的配色对，`check:contrast` 的阈值不用改。

作用范围

`main` 里的链接都有这个效果，几处例外：

位置	效果
首页的「最近写的」、文章列表页的标题、项目页、关于页、标签页、404	✅
文章正文	✅
文章页的目录、上一篇 / 下一篇、返回列表	❌（显式标记 ``.no-fill``）
标签胶囊	❌（``.tag``，胶囊本身有底色）
页头导航、页脚与备案	❌（它们在 ``main`` 之外）

排除导航与页脚除了观感，还有一个具体原因：那些链接的静止色不是链接色，它们是 `--ink-muted` / `--ink-dim`。而 `Base.astro` 的 scoped 样式里写着 `.site-nav a:hover { color: var(--rose-ink) }`、`.site-footer__filing a:hover { color: var(--rose-ink) }`，这几条比新加的样式表优先级高（Astro 的 scoped 样式会带上属性选择器）。结果是悬停时文字颜色被设成填充色本身：

```plaintext
导航链接悬停 400ms 后：
  color = rgb(186, 56, 86)     ← --rose-ink，与填充同色
  background-size = 100% 100%  ← 填充已铺满
  → 玫瑰色字压在玫瑰色块上，那块看起来是空的
```

正文链接没有这条冲突（`a:hover` 那条优先级更低），悬停终态是 `rgb(247, 246, 241)`，也就是 `--paper`。

这类冲突不会报错、也不影响其它属性：只有颜色被顶掉，表现是“填充块里没有字”。改 hover 颜色时先查一遍有没有更高优先级的同名规则。

实现路线

路线一：整字翻色

文字颜色用一次普通的 `color` 过渡，与填充块的上升同时进行。块是链接自己的背景：

```css
a {
  background-image: linear-gradient(var(--fill), var(--fill));
  background-repeat: no-repeat;
  background-size: 100% 2px;
  background-position: 0 100%;
  transition: background-size 260ms, color 260ms;
}
a:hover {
  background-size: 100% 100%;
  color: var(--flip);
}
```

中间那 130ms 里，被盖住的下半个字是“玫瑰色字压在玫瑰色块上”。把填充阈值设为 65%、文字色取过渡中点后截屏，逐像素统计覆盖区域： 纸色像素 0.0%，字与底色同色。

路线二：精确裁切

字色不是 `color`，而是一张裁到字形上的渐变（下半是背景色、上半是链接色，硬断点在中间），用 `background-position` 让断点跟着填充块的上沿走：

```css
a {
  color: transparent;
  background-image: linear-gradient(to top, var(--paper) 50%, var(--rose-ink) 50%);
  background-size: 100% 200%;
  background-position: 0 0%;
  background-clip: text;
  transition: background-position 260ms var(--ease-out);
}
a:hover {
  background-position: 0 100%;
}

a::after {
  content: ''; position: absolute; inset: 0; z-index: -1;
  background: var(--rose-ink);
  transform: scaleY(0); transform-origin: bottom;
  transition: transform 260ms var(--ease-out);
}
a:hover::after {
  transform: scaleY(1);
}
```

两个量都是“进度 p 的线性函数”：块的上沿在 `(1−p)·H`，渐变里那条硬断点在窗口里的位置也在 `(1−p)·H`。同一条缓动、同一个时长，于是每一帧都重合。实测把填充阈值设为 50%：填充上沿落在图 y82，理论值 y84，差 0.5 CSS px；同一段覆盖区域里纸色像素 17.8%，字完整可见。

取舍

	路线一 · 整字翻色	路线二 · 精确裁切
中间态	有，覆盖区域里字与底色同色	无，逐帧重合
折行的链接	正常，逐行分别填充	坏：字形消失
带底色的容器	正常	坏：链接整个看不见
依赖	只有 ``background-size`` 过渡	``background-clip: text`` + ``z-index: -1``

本站用路线一。中间态只存在 260ms，而路线二要付出两种环境下失效的代价，而且失效是静默的：页面不会报错，只是看起来“这里没样式”。

精确裁切不成立的 BUG

注意，局限于笔者水平，您可能在实际编码过程中可以完美解决这些问题

折行的链接

`background-clip: text` 的渐变按每一行各自计算（每行都当成“上半链接色、下半背景色”），悬停终态下整个链接的字都会变成背景色，在纸面上就是字消失；同时 `inset: 0` 的伪元素在折行的行内元素上退化了，填充块也看不见。用 22ch 的窄容器把一条长链接逼成五行，实测：

路线	悬停终态
整字翻色	逐行分别长满，能读
精确裁切	字形消失，填充块退化

带底色的容器

路线二的填充块靠 `z-index: -1` 躲在字形下面，而“负 z-index 的子孙”画在 最近的层叠上下文里。链接与那个上下文之间只要有一块带背景的元素（表格单元格、提示块、`--paper-sunken` 面板），填充就会被那块背景盖住：

层	悬停时
容器背景	``--paper-sunken``
填充块	被盖住，不可见
文字	翻成 ``--paper-sunken``
结果	整条链接消失

绕法只有一条：给链接套一层自己开层叠上下文（`isolation: isolate`）的容器，把填充挂在那一层上。折行那条仍然绕不开。

快速划过 ``a`` 时不中断 hover 动画

现象

鼠标快速划过一个链接（悬停 50ms 就走）时，动画只播了个开头。实测（正常速度 260ms，每 80ms 采一次 `background-size`）：

```plaintext
悬停 60ms 后移开：
  + 40ms   填充 31.4%
  +120ms   填充  1.5%
  +200ms   填充  0.0%   → 回到细线
```

指针离开 `:hover` 之后过渡改向，CSS 还有一条“反向”规则会按比例缩短时长，于是只剩一闪。

为什么不用 CSS 解决

动画与过渡都挂在 `:hover` 上，选择器一失效就被撤掉，而 CSS 里没有任何东西能记住“刚才 hover 过”。三条看着可行的绕法都不成立：

绕法	实际结果
换成 ``@keyframes`` 动画	同样挂在 ``:hover`` 上，指针一走照样被撤掉
退场加 ``transition-delay``	延迟期间属性停在旧值，填充卡在半路不动
``animation-play-state: paused``	离开时是“暂停”不是“继续”，填充冻在半路

使用只监听类名的脚本

指针离开时，如果进场还没跑完，就把“悬停态”这个类名留到那一刻再摘；摘掉类名才开始退场，于是一进一出都完整。`.fx-hover` 与 `:hover` 共用同一份声明，脚本不碰任何样式属性：

```js
var until = new WeakMap(), timer = new WeakMap();

// ⚠️ CSS 时长读出来可能是 "260ms"，也可能是 "2.08s"
function ms(v) { var n = parseFloat(v) || 0; return String(v).indexOf('ms') >= 0 ? n : n * 1000; }
function dur(el) {
  if (matchMedia('(prefers-reduced-motion: reduce)').matches) return 0;  // 没有过渡就不必等
  return ms(getComputedStyle(el).getPropertyValue('--dur-base'));
}

document.querySelectorAll(SEL).forEach(function (el) {
  el.addEventListener('pointerenter', function () {
    clearTimeout(timer.get(el));
    el.classList.add('fx-hover');
    until.set(el, performance.now() + dur(el));
  });
  el.addEventListener('pointerleave', function () {
    var off = function () { el.classList.remove('fx-hover'); };
    var rest = (until.get(el) || 0) - performance.now();
    if (rest > 0) timer.set(el, setTimeout(off, rest));   // 进场没跑完 → 等它跑完
    else off();                                           // 已经跑完 → 立刻退场
  });
});
```

注意：读 CSS 时长进 JS 时的单位：同一个变量读出来可能是 `"260ms"`，也可能是 `"2.08s"`，浏览器会把 1 秒以上的时长换成秒表示。 `parseFloat("2.08s")` 等于 `2.08`，于是“等 2.08 毫秒”，类名当场被摘掉、补完功能静默失效；而普通速度下读到的是 `"260ms"`，看不出问题。把时长放大 8 倍观察才会暴露。所有把 CSS 时长读进 JS 的地方都要先判单位。

实测同一划法（悬停 50–60ms 后移开）：

```plaintext
有这段脚本：  90.7% → 99.5% → 100% → 停住 → 9.3% → 0.1% → 2px
没有：        31.4% →  1.5% →  0.0%（回到细线）
```

退场方向：继续向上

进场自下而上灌满，退场不原路退回、而是继续向上排空走掉 —— 这需要两个方向用不同的插值起点，而一个属性的过渡只有一个起点。做法是把填充拆成两层，两层同色：

```css
/* ① 进场层：链接自己的背景，细线 → 长满 */
a {
  background-image: linear-gradient(var(--fill), var(--fill));
  background-repeat: no-repeat;
  background-size: 100% 2px;
  background-position: 0 100%;
  /* 静止态的 transition 写成 0s：离开 hover 时它瞬间回细线，把退场让给下面那层 */
  transition: background-size 0s, color 260ms var(--ease-out);
}
a:hover {
  background-size: 100% 100%;
  transition: background-size 260ms var(--ease-out), color 260ms var(--ease-out);
}

/* ② 退场层：同色的伪元素，缩向顶端 = 向上排空 */
a::after {
  content: ''; position: absolute; inset: 0; z-index: -1;
  background: var(--fill);
  transform: scaleY(0);
  transform-origin: top;
  transition: transform 260ms var(--ease-out);
}
a:hover::after {
  transform: scaleY(1);
  /* ③ 延迟一个进场时长才补满，否则它一上来就盖满，进场的长上去就看不见了 */
  transition: transform 0s 260ms;
}
```

偏差在于 `transition` 的第四个位置（延迟）：进场期间退场层保持零高度，进场结束的那一刻它补满，离开时它缩向顶端。

实测（慢放 8 倍逐帧）：

时刻	进场层	退场层 scaleY
首屏 160ms	``100% 2px``	0
进场中	96%	0
悬停终态	100%	1
退场 +220ms	``100% 2px``	0.559
退场 +300ms	``100% 2px``	0.192
退场 +420ms	``100% 2px``	0.037

退场时填充块始终贴在元素顶端往下缩，底部细线同时已经回来。退化情况两条：快速划进划出时退场层可能还没补满，那时就是普通的“退回去”；链接落在带底色的容器里时，退场层被容器背景盖住，表现是填充直接消失。 本站没有采用这一版。

怎么复算

静止态可以直接在控制台里看：

```js
getComputedStyle(document.querySelector('main a:not(.tag, .no-fill)')).backgroundSize
// → "100% 2px"     细线
getComputedStyle(document.querySelector('main a:not(.tag, .no-fill)')).textDecorationLine
// → "none"         细线取代了原来的下划线
```

中间态要把它钉住再看（否则 260ms 一晃就过去了）。用 CDP 注入一段只改动目标值的样式， 等过渡跑完再截屏：

```css
html.has-hover .lk--c { background-position: 0 50% !important; }
html.has-hover .lk--c::after { transform: scaleY(0.5) !important; }
```

「快速划过」要发真实鼠标事件，不是 `dispatchEvent`：

```js
Input.dispatchMouseEvent({ type: 'mouseMoved', x, y })   // 移到链接上
// 等 50ms
Input.dispatchMouseEvent({ type: 'mouseMoved', x: 5, y: 5 })
```

通用性

项	结论
量测环境	Chromium 151.0.7922.34（Chrome for Testing），Linux
用到的特性	``background-size`` 过渡、``:is()``、``@media (hover: hover) and (pointer: fine)``、``WeakMap``
浏览器验证范围	⚠️ 只在 Chromium 里量过；Firefox 与 Safari 没验
触屏	按设计整段不生效（媒体查询），未在真机验收
``prefers-reduced-motion: reduce``	过渡时长归零（``base.css`` 有全局兜底），未单独验收

排错表

现象	可能原因	下一步
填充块里没有字，整块看起来是空的	有更高优先级的 ``:hover`` 规则把 ``color`` 设成了填充色	查该链接所在的容器有没有自己的 hover 颜色规则（``--rose-ink`` 这类），用 ``getComputedStyle(el).color`` 在悬停时对比
快速划过只闪一下	补完脚本没跑（JS 关了）、或它的选择器没覆盖到这条链接	看元素上有没有 ``.fx-hover``；确认选择器与样式表范围一致
悬停时长变了但类名立刻就摘	CSS 时长读进 JS 没判单位（``2.08s`` → ``2.08``）	打印 ``getComputedStyle(el).getPropertyValue('--dur-base')`` 看实际字符串
折行的链接悬停后字消失	用了精确裁切那一路	换整字翻色；这条路对折行不成立
带底色的块里链接悬停后看不见	同上，填充被容器背景盖住	换整字翻色，或给链接套一层 ``isolation: isolate``
静止态多出一条下划线	``text-decoration`` 没去掉	细线本身就是下划线，``text-decoration: none``

Markdown 支持清单

Mon, 21 Sep 2026 00:00:00 GMT

标题

```markdown
## 二级标题
```

二级标题

```markdown
### 三级标题
```

三级标题

```markdown
#### 四级标题
```

四级标题

```markdown
##### 五级标题
```

五级标题

```markdown
###### 六级标题
```

六级标题

终端：w3m 给每个标题前后各留一个空行，不按层级缩进，三级以下彼此分不出来；lynx 每级缩进两格，层级看得见。

自定义锚点

```markdown
### 一个不跟着文字改的锚点 {#stable-anchor}
```

一个不跟着文字改的锚点

终端：HTML 里是 `id="stable-anchor"`，改标题文字不影响这个锚点。

行内标记

粗体斜体 ~~删除线~~ `行内代码` 上标² 下标_n

```markdown
**粗体** *斜体* ~~删除线~~ `行内代码` 上标^2^ 下标~n~
```

转义：*这一对星号不是斜体*。实体：© — （不间断空格）。

终端：粗体、斜体、`<mark>`、`<kbd>` 的样式全部消失；删除线读作 `[DEL:删除线:DEL]`，上标读作 `^2`，下标读作 `[n]`（lynx 的方括号里多两个空格）；行内代码多出一对反引号。

链接

站内链接：全部文章。站外链接：Sätteri 的仓库。自动链接：https://astro.build。

终端：只有链接文字，看不到地址；但链接本身能跳转 —— w3m 里 Tab 选中、回车跟随（实测从本页的自动链接跳到了 astro.build）。

列表

```markdown
- 第一项
- 第二项
```

第一项
第二项，里面可以放 `代码` 与粗体

```markdown
1. 第一步
2. 第二步
```

第一步
第二步

```markdown
- 上层
    - 下层用四个空格缩进
```

上层
- 下层用四个空格缩进
- 第二项

```markdown
- [x] 已经做完的事
- [ ] 还没做的事
```

已经做完的事
还没做的事

终端：无序是 `•`，有序保留 `1. 2.`，嵌套第二层是 `□`。

引用与提示框

```markdown
> 引用里的第一段。
>
> 引用里的第二段。
```

引用里的第一段。

引用里的第二段。

```markdown
> [!NOTE]
> 这类框用来放补充说明。
```

提示

这类框用来放补充说明。

```markdown
> [!TIP]
> 这类框用来放技巧。
```

技巧

这类框用来放技巧。

```markdown
> [!IMPORTANT]
> 这类框用来放重要的事。
```

重要

这类框用来放重要的事。

```markdown
> [!WARNING]
> 这类框用来放容易踩的坑。
```

注意

这类框用来放容易踩的坑。

```markdown
> [!CAUTION]
> 这类框用来放警告。
```

警告

这类框用来放警告。

终端：块引用缩进四格，标题是一行真文字。

代码

```markdown
```bash
systemctl --user status kde-theme-sync.path
```
```

```bash
systemctl --user status kde-theme-sync.path
```

```markdown
```
没有语言标签的代码块。
```
```

```plaintext
没有语言标签的代码块，Shiki 按 plaintext 处理。
```

```bash
journalctl --user -u wireplumber --since '14 days ago' | grep -iE 'lua|not supported|error' | tail -40
```

```plaintext
这一行是四个空格缩进的代码块
渲染结果与不带语言的围栏一致
```

终端：上下各注入一行围栏，语言标签补在开围栏上；超长行要按 `>` 横向移动才能看全。

表格

项	通用性	说明
``ss -tlnp``	✅	任何 Linux 都能用
端口号	⚠️	随版本变，要自己确认

终端：不画表格线，靠列对齐；自然宽（汉字算两列、列间一个空格）超过 79 列就会折行，而折行之后读不出哪一格属于哪一列。宽表格改写成列表：

现象 —— 完全不生效
- 可能原因：`kde-theme-sync.path` 没启用
- 怎么办：`systemctl --user status kde-theme-sync.path`

脚注

这句话带一个脚注¹。

终端：脚注编号与文末列表都保留。

图片

终端：只读得到 `alt` 文字，上面这张图读作「站点的分隔线图形」。

数学

```markdown
行内：$a^2 + b^2 = c^2$
```

行内： $a^{2} + b^{2} = c^{2}$

```markdown
$$
\int_0^1 x^2 \, dx = \frac{1}{3}
$$
```

\int_{0}^{1} x^{2} d x = \frac{1}{3}

终端：公式只剩一串字符。行内读作 `a2+b2=c2`；块级读作 `∫01x2dx=31` —— 上下标、分式、根号在终端里全被拍平成字符顺序，KaTeX 的 MathML 那一层会让 lynx 直接吐出 XML 源码，所以构建期只输出 HTML。

定义列表

术语: 解释。缩进加不加都行，处理器认的是行首的 `: `。
终端浏览器: 块引用缩进、列表缩进、定义列表缩进。

终端：术语一行，解释缩进四格。

分隔线与原始 HTML

原始 HTML 原样保留：按 Ctrl 切换键盘，高亮的一段。

术语: 解释。

终端：`<kbd>` 与 `<mark>` 的样式消失，`<dl>` 是术语一行、解释缩进四格。

不支持的写法

冒号围栏 `:::note`：整块内容被静默丢掉，什么都不剩。替代品是 `> [!NOTE]`。
`[[双链]]`：开关关闭，开了只会生成死链。
图表：Mermaid 之类需要客户端 JS，不支持。

脚注由 GFM 提供，文末自动生成回链列表。 ↩

微信说「不在同一网络」，其实是被防火墙丢了包

Sat, 15 Aug 2026 00:00:00 GMT

手机和电脑连同一个热点，用微信导入聊天记录，电脑上弹出：

暂无法导入，请保持手机和电脑在同一网络

两台设备确实在同一个网段里。USB 网络共享试过，Wi-Fi 热点也试过，都能正常上网，但导入就是失败。

先决条件

需要	说明
微信 Linux 原生版	3.x 与 Wine 版的导入机制不同，本文针对 4.x
一台 Linux 电脑 + 一台手机	用手机热点或 USB 网络共享组成局域网

三个自查命令：

```bash
ip -br addr                    # 看手机那侧的接口名和网段
sudo ufw status verbose        # 防火墙是不是 UFW 在管
ss -tlnp | grep 8015           # 导入窗口打开时，这个端口在不在监听
```

这套排查在什么环境上验证过

```plaintext
CachyOS (Arch) ｜ KDE Plasma 6 ｜ Wayland
微信 Linux 原生版 4.1.8 ｜ UFW
```

项	是否通用	说明
8015 这个端口	⚠️ 是当时观测到的	微信版本变了可能变，用 ``ss -tlnp`` 自己确认
UFW 的默认 ``DROP`` 策略	⚠️ 取决于你的配置	``ufw status verbose`` 看自己的
``strace`` 的跟踪方式	✅ 通用	任何 Linux 都能用
手机热点的网段	❌ 每次都不同	由手机 DHCP 分配，必须现场查
接口名	❌ 会变	Wi-Fi 是 ``wlan0``，USB 共享是 ``enp6s0f4u2u2`` 这类名字

先说那个错误提示

「请保持手机和电脑在同一网络」是一句泛化提示。微信在这条路径上失败时都会这么说，不管真实原因是不同网段、防火墙丢包、还是别的。

所以它只能证明「这条链路没通」，不能证明两台设备不在同一子网。顺着字面意思去查网络拓扑，会走偏。

第一步：把「看着可疑但其实正常」的先排掉

一开始怀疑的是地址段：手机热点分给电脑的地址是 `10.112.4.254`，看着不像家里的 `192.168.x.x`，当时以为是 KDE 建了什么虚拟网卡，或者被 VPN 接管了。

```bash
ip -br addr                    # 看接口和地址
nmcli device                   # 看 NetworkManager 怎么认这个接口
```

实际拿到的：

```text
Wi-Fi 热点：  wlan0     10.112.4.254/24   手机网关 10.112.4.49
USB 共享：    enp6s0f4u2u2  10.146.37.73/24   手机网关 10.146.37.96
```

`10.0.0.0/8` 是标准 IPv4 私有地址段，和 `192.168.0.0/16` 是一回事。 地址由手机 DHCP 分配，不是异常拓扑。

第二步：两个直接验证，都不用停任何服务

验证一：微信到底有没有在监听

```bash
# 先找到微信主进程的 pid，再跟踪它的网络调用
sudo strace -ff -tt -e trace=network -p <微信pid>
```

打开导入窗口，抓到的是：

```text
socket(AF_INET, SOCK_STREAM, IPPROTO_TCP) = 305
bind(305, {sa_family=AF_INET, sin_port=htons(8015),
           sin_addr=inet_addr("0.0.0.0")}, 16) = 0
listen(305, 8) = 0
```

`bind` 和 `listen` 都返回 0，说明三件事：

导入模块已经进入网络阶段
它在所有 IPv4 接口上监听 8015
不存在「没权限绑端口」的问题

这一步把排查范围从「应用没起来」缩到了「入站路径不通」。用 `ss` 也能看到同样的结论，但 `strace` 能证明它是微信自己建的监听，而不是别的进程占了端口。

验证二：从对端访问这个端口（决定性的一步）

保持导入窗口开着，用手机浏览器访问电脑的那个端口：

```plaintext
http://<电脑的局域网IP>:8015
```

结果是：

```plaintext
ErrorTimeOut
```

超时，不是拒绝。

这两种失败指向的方向不一样：

结果	含义
连接被拒绝	端口没在监听，或者应用拒绝了
超时	报文被丢掉了，``DROP`` 的典型表现

顺带一个反面对照：这时候电脑是能 ping 通手机的。

```text
PING 10.112.4.49
3 packets transmitted, 3 received, 0% packet loss
```

ping 通只证明 ICMP 和基础路由可用，不代表特定 TCP 端口的入站被放行。 这两件事经常被当成一件。

第三步：查防火墙

```bash
sudo ufw status verbose
```

```text
Status: active
Default: deny (incoming), allow (outgoing), disabled (routed)
```

再看配置：

```text
/etc/default/ufw: DEFAULT_INPUT_POLICY="DROP"
```

默认入站是 DROP。 手机发往 8015 的包到了电脑就被丢了，应用层根本看不到，所以微信只能报一句「不在同一网络」。

⚠️ 一个容易漏的地方

```text
ufw.service: active (exited)
firewalld.service: inactive
nftables.service: inactive
```

UFW 的服务状态是 `active (exited)` —— 它是一次性服务，开机时把 Netfilter 规则写进内核就退出了，之后一直显示 `exited`。

只看 `firewalld` 或 `nftables.service` 的状态，会以为这台机器没有防火墙在管事。 它们不活动不等于没有规则，规则已经在内核里了。

修复

加一条最小放行规则：

```bash
sudo ufw allow in on wlan0 from 10.112.4.0/24 to any port 8015 proto tcp
```

这条规则限定得很死，只放行：

限定项	值
入站接口	``wlan0``
来源网段	手机热点的 ``/24``
协议	TCP
目标端口	8015

放行后重启微信，重新进导入页面，导入成功。

USB 共享时要换接口名和网段

USB 共享走的是另一个接口，名字和网段都不一样，所以规则也得重写一条。 先查，再写：

```bash
nmcli device
ip -br addr
```

比如这次 USB 共享是 `enp6s0f4u2u2`、网段 `10.146.37.0/24`：

```bash
sudo ufw allow in on enp6s0f4u2u2 from 10.146.37.0/24 to any port 8015 proto tcp
```

不要图省事写成 `sudo ufw allow 8015/tcp` —— 那等于对所有来源开放这个端口。

用完想删掉

```bash
sudo ufw delete allow in on wlan0 from 10.112.4.0/24 to any port 8015 proto tcp
```

被排除掉的七个假设

这一段值得留着看。当时怀疑过下面这些，每一个都是停掉服务实测过的：

假设	怎么排除的
FRP 隧道干扰	停掉 ``frpc.service``，问题依旧
strongSwan / IPsec	服务本来就是 ``inactive``，不是活动连接
KDE Connect 的 SSH TUN	停掉后 ``tun66`` 消失，导入仍失败
Clash Verge 代理	停服务 + 完全重启微信，仍失败
KDE Connect 用户守护进程	停掉后重启微信，仍失败
Docker 虚拟网卡让微信选错地址	停 Docker、containerd 和容器、清掉 veth，仍失败
微信数据目录权限	目录属主权限正常、可读写、无 immutable 属性、磁盘有 700 GB 空闲

七个全排除，才把注意力从「谁在干扰网络」转到「包到底有没有到」。

顺序值得注意：验证一和验证二都不需要停任何服务。先做那两个，范围就已经缩到防火墙了。上面这七个是在这之前做的，每一个都在短时间内把机器上的一个服务关掉，属于扩大了影响面。

这套排查里能带走的

泛化的错误提示不可信。 「不在同一网络」不代表真的不在同一网络。
`10.x` 不异常。 它是标准私有段，没证据就不要当成 VPN。
ping 通不等于端口通。 ICMP 和 TCP 入站是两条独立的路径，防火墙可以只放前者。
超时和拒绝是两种不同的失败。 超时指向丢包，拒绝指向没有监听。
`strace` 能把「应用没起来」和「网络不通」切开，比看日志直接。
查防火墙别只看 `firewalld` / `nftables.service`。 UFW 可以在自身 `active (exited)` 的状态下，规则早就进了内核。
先做直接的、无副作用的验证，再去停服务。 顺序反了，排查成本会成倍上升。

排错

现象	可能原因	下一步
手机浏览器访问端口超时	防火墙 ``DROP``	查 ``ufw status verbose`` 的默认入站策略
手机浏览器连接被拒绝	端口没在监听	确认导入窗口开着，用 ``ss -tlnp`` 查
放行了还是不行	接口名或网段写错	重新 ``ip -br addr`` 确认，规则要跟实际一致
Wi-Fi 能导入、USB 不能	两条路的接口和网段都不同	给 USB 接口单独加一条规则
换了手机热点就连不上	网段变了	规则里写死的是上一次的 ``/24``，重新查再改

参考

`strace` / `ss` / `nmcli` / `ip`，都是系统自带
`ufw status verbose`，看默认策略和已有规则
Arch Wiki: Uncomplicated Firewall

让 RustDesk 走我自己的服务器

Mon, 20 Jul 2026 00:00:00 GMT

TeamViewer、ToDesk、向日葵这类远控，连接都要过一次厂商的服务器。自建 RustDesk 服务端的意义在于把这个环节拿回来，代价是一条 `docker compose`。

它由两个组件组成，加起来不到 200 MB 内存。

以上是 AI 帮我写的，实际上，我用 RustDesk 的原因是： ChatGPT 力荐，我有一个ECS。

先决条件

需要	说明
一台有公网 IP 的服务器	客户端要能直接连上它，所以不能是纯内网机
Docker + Docker Compose	部署方式，两个容器
能改云服务商的安全组	端口要在安全组和服务器本机防火墙两处都开
RustDesk 客户端	Windows / macOS / Linux / Android / iOS 都有

三个自查命令：

```bash
docker --version              # 有 Docker 就行
docker compose version        # 注意是 compose 子命令，不是 docker-compose
```

这套做法在什么环境上验证过

```plaintext
部署时间：2026-07-20 ｜ 镜像 rustdesk/rustdesk-server:1.1.15
服务端：国内云服务器 ｜ Docker Compose ｜ network_mode: host
客户端：Linux (CachyOS) ｜ 自定义 ID 服务器 + 中继 + 密钥
```

项	是否通用	说明
hbbs / hbbr 的职责与端口	✅ 通用	RustDesk 自身设计
compose 文件结构	✅ 通用	与云厂商无关
国内拉镜像	⚠️ 只对国内服务器	有外网或已配加速器的可以跳过那一节
防火墙命令	⚠️ 因发行版而异	``ufw`` 还是 ``firewalld``，先看自己那台
镜像版本号	❌ 会过时	写这篇时是 1.1.15，装之前去看一眼 Releases

它由两个组件组成

组件	容器	作用
hbbs	``rustdesk-hbbs``	设备注册、NAT 类型测试、P2P 连接协调
hbbr	``rustdesk-hbbr``	P2P 直连失败时，负责中继转发

```plaintext
A 想连 B
 └─ 先问 hbbs：B 在哪？能直连吗？
     ├─ 能 ──→ 数据走 P2P，不经服务器
     └─ 不能 ──→ 走 hbbr 中继
                  （对称 NAT 之类）
```

大多数时候流量是不经过服务器的，服务器只负责牵线。这也是它便宜的原因：一台最低配的机器就够了，只有在中继时才吃带宽。

端口

端口	协议	归属	用途
21115	TCP	hbbs	NAT 类型测试
21116	TCP	hbbs	ID 注册与心跳
21116	UDP	hbbs	打洞 / NAT 穿透
21117	TCP	hbbr	中继服务
21118	TCP	hbbs	WebSocket，可选

21115 TCP、21116 TCP + UDP、21117 TCP 四个必须开。

21116 那个 UDP 最容易漏。只开 TCP 的话，客户端能注册上线，但打洞会失败，于是所有流量都被挤到中继上，速度明显不对。

第一步：写 compose 文件

```bash
mkdir -p /opt/rustdesk-server && cd /opt/rustdesk-server
```

写入 `compose.yml`：

```yaml
services:
  hbbs:
    container_name: rustdesk-hbbs
    image: rustdesk/rustdesk-server:1.1.15      # 必须写具体版本号
    command: hbbs -r <你的服务器IP>:21117 -k _
    volumes:
      - ./data:/root
    network_mode: host
    restart: unless-stopped
    depends_on:
      - hbbr

  hbbr:
    container_name: rustdesk-hbbr
    image: rustdesk/rustdesk-server:1.1.15      # 同上
    command: hbbr -k _
    volumes:
      - ./data:/root
    network_mode: host
    restart: unless-stopped
```

参数逐个说：

参数	含义
``-r <IP>:21117``	告诉客户端中继服务器在哪。填公网 IP
``-k _``	强制密钥认证。首次启动自动生成密钥对
``network_mode: host``	直接用宿主机网络栈，端口不用再做映射
``./data:/root``	持久化密钥和数据库。这个目录丢了，所有客户端都要重配

⚠️ 坑一：绝不能用 ``latest``

注意，这篇文章的更新时间虽然是`2026-9-20`，但实际上笔者在这一天并没有真正意义上去测试，所以这一条的时间线为`2026-07-20`

这是这篇里最值得记的一条。用 `latest` 拉到旧版本镜像后，容器起不来，日志里是：

```plaintext
ERROR: Registered email required (-m option).
Please pay and register on https://rustdesk.com/server
```

看着像「要付费注册」，其实是国内某些镜像源缓存了几年前的旧版本，而旧版本要求商业授权。写死版本号就能绕开。

装之前先去 Releases 看一眼当前版本，把 `1.1.15` 换成它。

⚠️ 坑二：国内服务器拉不动镜像

如果服务器在国内且没有代理，`docker compose pull` 会卡在 Docker Hub 上。两个办法：

办法一：直接用代理前缀拉，再打回原标签

```bash
docker pull docker.1ms.run/rustdesk/rustdesk-server:1.1.15
docker tag docker.1ms.run/rustdesk/rustdesk-server:1.1.15 \
           rustdesk/rustdesk-server:1.1.15
```

改完标签，compose 文件里的 `image` 不用动。

办法二：给 Docker 配加速器，一劳永逸

```bash
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.xuanyuan.me",
    "https://docker.m.daocloud.io"
  ]
}
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker
```

配多个源是为了容灾，某一个挂了还有别的。之后 `docker compose pull` 就能直接拉。

这些镜像代理的可用性会变，用之前先自己试一下。写这篇时三个都还能用。

第二步：启动并拿到密钥

```bash
cd /opt/rustdesk-server
docker compose up -d

# 拿公钥
cat ./data/id_ed25519.pub
```

密钥文件在 `./data/` 下，是首次启动时自动生成的。客户端要填的就是 `id_ed25519.pub` 里的那一串。

第三步：开端口

两处都要开，只开一处等于没开：

服务器本机防火墙

```bash
# ufw（Debian / Ubuntu）
sudo ufw allow 21115:21117/tcp
sudo ufw allow 21116/udp
sudo ufw reload
```

```bash
# firewalld（RHEL / CentOS / Fedora）
sudo firewall-cmd --permanent --add-port=21115-21117/tcp
sudo firewall-cmd --permanent --add-port=21116/udp
sudo firewall-cmd --reload
```

云服务商的安全组，在控制台里放行同样这几个端口。

第四步：配客户端

在 RustDesk 客户端里进 设置 → 网络，填三样：

字段	填什么
ID 服务器	你的服务器 IP
中继服务器	同一个 IP（端口不用写，默认 21117）
密钥	``id_ed25519.pub`` 的内容

点应用，状态变绿显示「就绪」就是通了。

手机上也要各填一遍。 这几项不会跟着账号走，换设备就得重填。

怎么验证

① 服务端在不在

```bash
docker compose ps            # 两个容器都应该是 Up
docker logs rustdesk-hbbs    # 没有报错
```

② 端口对外通不通

在另一台机器上跑，不要在服务器本机跑（本机跑测不出安全组）：

```bash
for p in 21115 21116 21117; do
  timeout 3 bash -c "echo > /dev/tcp/<你的服务器IP>/$p" 2>/dev/null \
    && echo "$p 开着" || echo "$p 不通"
done
```

三个都应该是「开着」。

③ 客户端连上后看状态

RustDesk 主界面左下角，状态是「就绪」就说明 ID 服务器通了。

④ 真正连一次

从手机连一次电脑，看画面能不能出来。这一步才作数 —— 前面三项目前全绿、最后连不上，通常是中继或者 UDP 打洞的问题。

排错

现象	可能原因	下一步
容器起不来，日志提「paid and register」	用了 ``latest``，拉到旧版本	改成具体版本号重新拉
``docker compose pull`` 卡住	国内直连 Docker Hub	用代理前缀，或配加速器
客户端显示「未就绪」	21116 没通	安全组和本机防火墙都查一遍
能连上但很卡	P2P 没打通，全走中继	检查 21116 UDP 开了没有
换服务器后客户端连不上	密钥变了	重新 ``cat ./data/id_ed25519.pub`` 填进去
重装服务器后全部客户端失效	``./data/`` 没了，密钥重新生成	把 ``./data/`` 备份出来

参考

怎么确认自己有没有中 AUR 投毒

Mon, 13 Jul 2026 00:00:00 GMT

2026 年 6 月，AUR 上有一批包被投毒，官方名单里是 1936 个包名。

这件事值得单独立一份自查清单，原因载荷：窃取浏览器 Cookie、SSH 密钥、各类 Token 之外，它在 root 权限下会加载一个 eBPF rootkit 来隐藏自己的进程、文件和网络连接。按公开分析的说法，那东西卸载软件包去不掉，只能重装系统。

所以自查这件事，做得越早越省事（当然，由于 AUR 投毒事件发生时我没有使用 Arch，而用回 Arch 的时候已经是 7 月了，所以在时间上看起来有些奇怪）。

先决条件

需要	说明
Arch 系发行版	CachyOS / EndeavourOS / Manjaro 同样适用
能读 ``/var/lib/pacman/``	查已装包与安装脚本，普通用户通常可读
几分钟	第一轮几秒，第二轮主要花在搜文件上

两个自查命令：

```bash
pacman -Qm                    # 列出所有非官方仓库的包（也就是 AUR 来的）
ls /sys/fs/bpf/               # eBPF 映射，rootkit 藏身的地方之一
```

事件经过

日期	发生了什么
6 月 11 日	第一波。载荷通过 ``npm install atomic-lockfile`` 拉取，1500+ 包
6 月 13 日	第二波。改用 ``bun install js-digest``，代码混淆规避检测
6 月 14 日	第三波。载荷高度混淆，靠 AI 模型辅助分析才发现
6 月 15 日	Arch 暂停 AUR 新用户注册，清理全部恶意包

官方仓库没有受影响，被渗透的是 AUR 这个社区仓库。

攻击是怎么做的

```plaintext
① 找孤儿包
   AUR 允许认领无人维护的包
        ↓
② 认领后改 PKGBUILD 与 .install
        ↓
③ 伪造提交元数据，看起来像原维护者
        ↓
④ 载荷不写在 PKGBUILD 里
   而是让 PKGBUILD 去 npm / bun 下载
```

第 ④ 步是这件事最难查的地方。你去读 PKGBUILD，上面没有一行恶意代码 —— 它只是调用了一次包管理器，而恶意内容在远端那个 npm 包里。

所以「我每次都读过 PKGBUILD」在这里不构成防线。要防的是另一件事： AUR 包为什么要从 npm / pip / bun 下载东西。

第一轮：比包名

拿到官方名单，和自己的 AUR 包列表做一次全等比对。

```bash
# 官方名单：https://md.archlinux.org/s/SxbqukK6IA
# 存成 package-list.txt，一行一个包名

pacman -Qm | awk '{print $1}' > /tmp/aur-mine.txt
comm -12 <(sort /tmp/aur-mine.txt) <(sort package-list.txt)
```

`comm -12` 输出的是两个文件的交集。有输出就是命中，没有输出就是干净。

用 `comm` 而不是 `grep -f`，是因为它按整行精确比对，不会把 `fcitx5` 匹配到名单里的 `fcitx`。

本机（2026-09-20）的结果：

```bash
pacman -Qm | wc -l        # → 27
```

27 个 AUR 包逐个比对，0 命中。

第二轮：扫 IOC

包名干净不等于没中 —— 包可能已经删掉，载荷还在。下面每一项都是可以独立跑的。

① eBPF rootkit 的映射

```bash
ls /sys/fs/bpf/ | grep hidden
# → 无输出
```

公开分析里提到的映射名是 `hidden_pids`、`hidden_names`、`hidden_inodes`。这几个名字本身就是「我要藏东西」的意思，正常系统上不会有。

② 恶意二进制

```bash
find /usr /opt /var/lib /tmp -maxdepth 4 -name deps -type f 2>/dev/null
# → 无输出
```

载荷是一个 Rust 写的、名叫 `deps` 的 ELF 文件。

③ npm 缓存里的恶意包

```bash
grep -rl 'atomic-lockfile\|js-digest\|lockfile-js\|nextfile-js' ~/.npm/_cacache/index-v5/
# → 无输出
```

四个恶意 npm 包名：

包名	版本	说明
``atomic-lockfile``	1.4.2	第一波，载荷文件 ``src/hooks/deps``
``js-digest``	4.2.2	第二波，载荷伪装成 ``lib/install-deps.mjs``
``lockfile-js``	1.4.2	变体
``nextfile-js``	1.4.2	变体

④ 持久化

```bash
ls ~/.config/systemd/user/*.service
# 逐个看：是不是你自己建的
```

载荷会往 systemd 里塞服务，特征是 `Restart=always` 配 `RestartSec=30`。

```bash
grep -rl 'RestartSec=30' /etc/systemd/system/
# → 无输出
```

⑤ 出站连接

```bash
pgrep -a tor
# → 无输出
```

C2 走的是 Tor v3 onion：

```plaintext
olrh4mibs62l6kkuvvjyc5lrercqg5tz543r4lsw3o6mh5qb7g7sneid.onion
```

同时也往 `temp.sh` 上传。系统上没有 Tor 进程，这条基本可以排除。

⑥ 安装脚本

```bash
find /var/lib/pacman/local/ -name '*.install'
```

本机 1763 个包目录里，`.install` 文件数是 0 —— 这条检查项在本机没有可检查的对象。写出来是因为它对你的机器可能不是 0。

复跑结果（2026-09-20）

上面两轮在本机重跑了一遍，不是复述七月的结论：

检查项	结果
AUR 包名比对（27 个 vs 1936 行名单）	0 命中
eBPF ``hidden_*`` 映射	0 处
恶意二进制 ``deps``	0 个
npm 缓存中的恶意包	0 处
用户级 systemd 服务	3 个，都是自己建的（主题同步、mip-paper、kdeconnect 监听）
Tor 进程	0 个
``/var/lib`` 下 ``atomic*`` 植入物	0 个
``RestartSec=30`` 的系统服务	0 个
pacman ``.install`` 脚本	全机 0 个

三个「看起来像、其实无关」的

自查时容易误报的几处：

看着可疑	实际情况
linux-cachyos 内核	CachyOS 内核来自官方仓库。投毒名单里的是 AUR 上的 ``linux-cachyos-native``，另一个东西
``fcitx`` 在名单里	那是旧版 ``fcitx``。官方仓库的 ``fcitx5`` 不受影响
有 ``proper-lockfile``	合法 npm 包，和恶意的 ``lockfile-js`` 不是一回事

装之前怎么防

第一轮和第二轮都是事后检查，而 eBPF rootkit 那一步是不可逆的。所以在装之前：

能用官方仓库就用官方仓库。 AUR 只留给确实没有替代的包，本机 1763 个包里只有 27 个来自 AUR，这个比例是刻意维持的。
AUR 包主动去 npm / pip / bun 下载依赖的，直接当可疑处理。 这是这次事件的核心手法。
警惕「最近换过维护者」的废弃包。 攻击入口就是孤儿包收养。
看 `source` 字段的上游 URL，是不是指向项目的官方地址。
别跳过 PKGBUILD 的 diff。 `yay` 默认会展示，认真读完再回车。

正常打包不会在安装阶段去网上抓代码。这么做既违反打包惯例，也绕开了读 PKGBUILD 这个动作 —— 而那是你手上仅有的审查点。

如果中了

按公开分析的描述，eBPF rootkit 会隐藏自己的进程、文件和套接字，卸载软件包去不掉。

处理顺序：

断网，别让它继续外传
备份数据，不要备份二进制和配置（`~/.ssh`、浏览器配置、各类 Token 都算泄露，要轮换而不是备份）
重装系统
重装后轮换所有凭据：SSH 密钥、GitHub Token、各类 API Key、浏览器登录态

参考

让 PipeWire 不再爆音

Thu, 09 Jul 2026 00:00:00 GMT

音乐播着播着会突然「啪」一下，或者有那么一两秒像电流声，然后又正常了。

间歇出现，几分钟到几小时一次。重启没用，换线没用，换播放器也没用。

这类问题的麻烦有两层：复现不了，也没法确认修好了没有。

这个教程只是提供我自己的解决方案实际效果因系统而异，不能确保可以 100% 解决你遇到的问题

先决条件

需要	说明
PipeWire	本文的命令都是它自带的：``pw-top`` / ``pw-metadata`` / ``wpctl``
能改 ``/etc/security/limits.d/``	第一次修复动的是这里，要 root
能重新登录	组权限只在登录时读一次

这套做法在什么环境上验证过

```plaintext
CachyOS (Arch) ｜ KDE Plasma 6 ｜ Wayland
PipeWire 1.6.7 ｜ WirePlumber 0.5.17
声卡：3 个 HDA-Intel 设备（NVIDIA HDMI + 2 个 AMD）
```

项	是否通用	说明
``pw-top`` / ``pw-metadata`` / ``wpctl``	✅ 通用	PipeWire 自带，与发行版无关
``realtime`` 组与 ``memlock``	⚠️ 因发行版而异	Arch 系是 ``/etc/security/limits.d/99-realtime-privileges.conf``；Debian 系组名和文件位置都不同，先查自己那份
``snd_hda_intel`` 省电参数	⚠️ 只对 HDA 声卡	USB 声卡、蓝牙耳机不适用
WirePlumber 配置格式	❌ 0.5 起换过了	见「一份没有生效的配置」
CPU governor	⚠️ 因内核而异	CachyOS 只有 ``powersave`` 和 ``performance`` 两档

三个自查命令：

```bash
pw-top -b -n 3                                                  # 看 ERR 列
cat /sys/module/snd_hda_intel/parameters/power_save             # 省电秒数
grep -h '^@realtime' /etc/security/limits.d/*.conf              # 组权限
```

第一步：把听感换成数字

`pw-top` 是 PipeWire 版的 `top`。要看的只有一列：ERR，也就是 xrun 的次数。

缓冲区没喂上，硬件只能拿旧数据顶上，听到的就是那声「啪」。所以 ERR 涨一次，耳朵那边就响一次，两者是对得上的。

`-b -n 3` 是批处理模式，跑三次就退出，把输出留在终端里：

```bash
pw-top -b -n 3
```

```plaintext
S   ID  QUANT   RATE    WAIT    BUSY   W/Q   B/Q  ERR
R   52   2048  48000   8.4us  26.2us  0.00  0.00    0
R  134   2400  48000  10.3us  14.3us  0.00  0.00    0
```

（原输出末尾还有 FORMAT 和 NAME 两列，这里截掉了。）

ERR 是 0，说明这段时间没出问题。数字一旦涨，后面就有可以对照的东西了：改配置、再看 ERR、看它涨没涨。听感靠不住，计数靠得住。

顺带记住 QUANT 那一列，它是当前的缓冲区大小（单位是帧）。后面两次定位都和它有关。

第一次定位：ERR 有 25 个

现象

Proton 跑 Windows 游戏时出现电流声。`pw-top` 里 alsa_output 那一行的 ERR 是 25。

排查

同一个界面里还有一列能看：进程的实时优先级。当时 PipeWire 显示的是 `-`，意思是没有实时优先级。

顺着权限往下查：

```bash
groups                                    # 用户组里有没有 realtime
grep -h '^@realtime' /etc/security/limits.d/*.conf
grep -h '^@audio'    /etc/security/limits.d/*.conf
```

拿到的结果：

```plaintext
@realtime - rtprio 98
@realtime - memlock unlimited
@realtime - nice -11
```

`@audio` 那份只给了 `rtprio`，没有 `memlock`。而用户当时在 `audio` 组里。

根因

`memlock unlimited` 决定进程能不能把音频缓冲区锁在物理内存里。

拿不到这个权限，缓冲区就可能被换出去，等要用的时候再换回来。换回来那一下的延迟，就是一次 xrun。

所以在 `audio` 组不等于够用，音频线程要的是 `realtime` 组。

修复

```bash
sudo usermod -aG realtime "$USER"
# 注销重新登录，组权限只在登录时读一次
```

结果

ERR 从 25 降到 1，电流声消失。

第二次定位：还剩偶发

过了几天，音乐播放时又出现偶发的电音，游戏那边的电流声倒是没有了。重新看 `pw-top`，ERR 不再是 0。

这一次没有单一根因，候选有四条：

#	候选	判断依据
1	``snd_hda_intel`` 省电	``power_save = 10``，10 秒没声音就让编解码器休眠，唤醒时爆音
2	CPU governor	所有核心跑在 ``powersave``，音频线程拿不到实时性
3	``min-quantum`` 过低	值是 32，也就是 0.67 ms，任何抖动都会 xrun
4	WirePlumber 链路失败	日志里有 ``1 of 1 PipeWire links failed to activate``

四条里改了哪几条（2026-09 实测）

候选	档案里的方案	现在的状态
1	``/etc/modprobe.d/audio-nosuspend.conf``	❌ 文件不存在，内核参数仍是 ``power_save=10``
2	``/etc/default/cpupower`` + 启用服务	❌ 文件不存在，governor 仍是 ``powersave``
3	``~/.config/pipewire/pipewire.conf.d/99-min-quantum.conf``	✅ 已生效，``pw-metadata`` 读出 ``min-quantum = 256``
4	WirePlumber 规则	⚠️ 文件在，但没有被读，见下一节

一份没有生效的配置

回头再看这台机器时，WirePlumber 的日志里有这么两行：

```plaintext
wireplumber: Old configuration file detected:
             ~/.config/wireplumber/main.lua.d/51-disable-suspension.lua
wireplumber: Lua configuration files are NOT supported in WirePlumber 0.5.
             You need to port them to the new format if you want to use them.
```

那份配置是 0.4 时代的写法，内容是禁用音频设备的自动挂起。它一直在磁盘上，看着像已经生效了，但 WirePlumber 0.5 起不再读 Lua 配置，所以从升级那天起，它就是个死文件。

判断配置有没有生效，要看守护进程怎么说、设备上的属性是什么，不能看文件在不在。

里面两个属性名也没了

那份 Lua 规则用了三个属性，在 0.5 里的情况：

属性	0.5 里还在吗
``session.suspend-timeout-seconds``	✅ 仍在 ``suspend-node.lua`` 里被读取，默认 5 秒
``api.alsa.disable-power-save``	❌ 脚本和二进制模块里都搜不到
``api.alsa.disable-suspend``	❌ 同上

所以就算把它转成新格式，能保留的也只有第一个。

新格式长什么样

WirePlumber 0.5 的配置放在 `~/.config/wireplumber/wireplumber.conf.d/*.conf`。官方自带的 `alsa-vm.conf` 就是现成样例：

```plaintext
monitor.alsa.rules = [
  {
    matches = [
      { node.name = "~alsa_output.pci.*" }
    ]
    actions = {
      update-props = {
        api.alsa.period-size   = 1024
        api.alsa.headroom      = 2048
      }
    }
  }
]
```

照这个格式，那条禁用挂起的规则搬过来是：

```plaintext
# ~/.config/wireplumber/wireplumber.conf.d/51-disable-suspend.conf
monitor.alsa.rules = [
  {
    matches = [
      { node.name = "~alsa_output.*" }
      { node.name = "~alsa_input.*" }
    ]
    actions = {
      update-props = {
        session.suspend-timeout-seconds = 0
      }
    }
  }
]
```

上面这一段没有在本机跑过。属性名确认过在 0.5 的脚本里还被读取，文件格式照抄的是官方样例，但「改完到底生效没有」这一步没验。

怎么验证

① 看数字

```bash
pw-top -b -n 3                            # ERR 列
```

② 看配置有没有落到设备上

```bash
pw-metadata -n settings | grep -iE 'quantum|rate'
```

本机现在的输出：

```plaintext
update: id:0 key:'clock.rate' value:'48000'
update: id:0 key:'clock.quantum' value:'1024'
update: id:0 key:'clock.min-quantum' value:'256'
update: id:0 key:'clock.max-quantum' value:'2048'
```

③ 看守护进程有没有抱怨

```bash
journalctl --user -u wireplumber --since '14 days ago' | grep -iE 'lua|not supported'
```

出现 `Old configuration file detected`，就说明那个文件是死的。

④ 回头看内核参数

```bash
cat /sys/module/snd_hda_intel/parameters/power_save              # 10
cat /sys/module/snd_hda_intel/parameters/power_save_controller   # Y
```

这两个值本机至今没有改过。省电那一层本来是靠 WirePlumber 兜的，而那份配置又没生效，所以这一层目前是空的。

现在的状态（2026-09-20 实测）

项	值
``pw-top`` 的 ERR（两个活动节点）	0
``clock.min-quantum``	256（原为 32）
用户组	含 ``realtime``
近 14 天 pipewire 日志里的 xrun	0 条
近 14 天 wireplumber 的 ``link failed``	11 条
``snd_hda_intel power_save``	10（未改）
CPU governor	powersave（未改）

`link failed` 那条线还活着，说明候选 4 没有结。不过 ERR 是 0、日志里也没有 xrun，所以它现在没有表现为听得见的爆音。

排错

现象	可能原因	下一步
ERR 一直涨	缓冲区喂不上	先看 ``pw-top`` 的 QUANT 是不是太小，再提高 ``min-quantum``
只在游戏里出现	Proton 的音频延迟	Steam 启动项加 ``PULSE_LATENCY_MSEC=60 %command%``
改了配置没变化	服务没重启	``systemctl --user restart wireplumber pipewire pipewire-pulse``
配置写了却没生效	格式不对，0.5 不读 Lua	看 ``journalctl --user -u wireplumber`` 有没有抱怨
ERR 是 0 但还有杂音	不是 xrun 引起的	问题不在缓冲区，往硬件、线材、DSP 链查

参考

`pw-top` / `pw-metadata` / `wpctl`，都是 PipeWire 与 WirePlumber 自带的命令
`/etc/security/limits.d/99-realtime-privileges.conf`，`realtime` 组的权限来源
`/usr/share/wireplumber/wireplumber.conf.d/alsa-vm.conf`，0.5 配置格式的官方样例
`/usr/share/wireplumber/scripts/node/suspend-node.lua`，`session.suspend-timeout-seconds` 的读取处
Arch Wiki: PipeWire

让 Linux 的时间方案与 Windows 一致

Mon, 06 Jul 2026 00:00:00 GMT

虽然我现在很少使用 Windows 了，但总还是会有回到 Win 上玩游戏的需求的，然而以前总是从 Windows 切回 Linux 后，我的系统时间就会出现错乱（两套系统会互相改写 RTC）所以，为了让两个系统不打架，同时考虑到 Linux 操作相对简单一些（Maybe？）

所以，来让 Linux RTC 使用本地时间吧！

背景

Windows 和 Linux 对硬件时钟（RTC）的默认处理方式不同：

系统	硬件时钟假设	行为
Windows	本地时间（local time）	RTC 直接存 +8 时间，不做偏移
Linux	UTC 时间	RTC 存 UTC，根据时区 +8 显示本地时间

双系统切换时，两套系统会互相改写 RTC，导致时间错乱 8 小时。

当前状态

```plaintext
RTC time: 2026-07-06 03:39:48 (UTC)
Local time: 2026-07-06 11:39:48 (CST, +0800)
RTC in local TZ: no
```

当前 Linux 将 RTC 视为 UTC，硬件时钟比本地时间少 8 小时。

解决方案

让 Linux 迁就 Windows，将 RTC 视为本地时间：

```bash
sudo timedatectl set-local-rtc 1
```

影响分析

优点：双系统时间一致，不再互相打架
缺点：
- 切换时区时 RTC 需要手动调整（对于我这种不会出国的用户基本没有影响）
- systemd 会在启动时自动处理，不会有实质性问题
- 可能产生一条 warning 日志，不影响使用

验证命令

```bash
timedatectl status | grep "RTC in local"
# 应显示：RTC in local TZ: yes
```

参考

Arch Wiki: System time

让 Kitty 和 Starship 跟着 KDE 一起换色

Sun, 05 Jul 2026 00:00:00 GMT

KDE 那边把 accent 调成了玫瑰粉，终端还停在上一套主题；Starship 的 git 分支胶囊又是另一个颜色。壁纸一换，三处全不对。

手动改当然可以，但每次换壁纸、每次切深浅色都要记得改一遍 —— 那就等于没改。

这篇讲的是一套自动方案：让终端配色跟着 KDE 走。读完你能得到两个零依赖的 Python 脚本、一条 systemd 自动同步链路，以及一个会静默失败的竞态陷阱的完整避坑方案。

配套代码与完整脚本：https://github.com/LaT-SKY/kde-terminal-theme-sync（MIT）

先决条件

需要	说明
KDE Plasma 6	配色数据源。昼夜自动切换需要 6.5+
Kitty	终端本体，支持 ``SIGUSR1`` 热重载
Starship	提示符。``[palettes.]`` 需要 1.20+*
Python 3.8+	两个脚本只用标准库，没有 pip 依赖
systemd –user	自动同步用它。Arch / Fedora / Ubuntu 默认有

这套东西在什么环境上验证过

```plaintext
CachyOS (Arch) ｜ KDE Plasma 6 ｜ Kitty ｜ Starship 1.26.0
Wayland ｜ Python 3.14
```

只在上面这一个组合上实测过。 下面这份清单说明哪些地方会因环境而异 —— 标 ✅ 的可以放心，标 ⚠️ 和 ❌ 的要自己确认一下：

配置文件路径（`~/.config/…`）—— ✅ 通用。XDG 规范，各发行版一致。
KDE 配色存储位置与优先级 —— ✅ 通用。同上。
`kdeglobals` 的内容 —— ⚠️ 因 Plasma 版本而异。见下面「一个会静默失败的陷阱」。
Python —— ✅ 3.8+ 都行。只用标准库。
`systemd --user` —— ⚠️ 需发行版启用。`systemctl --user status` 自查。
`PathModified=` 的触发时机 —— ✅ 通用。systemd 行为。
kitty 热重载 `SIGUSR1` —— ✅ 通用。kitty 自身特性。
starship 的 `SIGWINCH` 重绘 —— ❌ 只对 fish 有效。bash / zsh 要换做法，见「第三步：让它自己跑起来」。
昼夜自动切换 —— ⚠️ 需要 Plasma 6.5+。低版本没有这个功能。

三个自查命令：

```bash
python3 --version                    # 要 3.8 以上
systemctl --user status              # 能输出就说明有 systemd --user
ls ~/.config/kdeglobals              # 存在就说明有 KDE 配置
```

原理：KDE 把配色存在哪

搞清楚数据从哪来，后面所有事都好办了。KDE 的配色分散在三个地方，按优先级回退：

`~/.config/kdeglobals` —— 用户覆盖，优先级最高。accent 色这类个性化设置在这里
`~/.local/share/color-schemes/<名称>.colors` —— 用户自己装的配色
`/usr/share/color-schemes/<名称>.colors` —— 系统自带，最后兜底

当前用的是哪一套，从 `kdeglobals` 的 `[General] ColorScheme` 读。

⚠️ 一个反直觉的点

那个 `ColorScheme` 键不一定在 `kdeglobals` 里。

这不是配置写坏了。Plasma 在切换主题时是分阶段写文件的，而且写的地方不止一处 —— 方案名可能跑到了 `~/.config/kdedefaults/kdeglobals`。

自己确认一下：

```bash
# 看 kdeglobals 里有没有 ColorScheme
grep -n 'ColorScheme' ~/.config/kdeglobals

# 如果没有，看这里
grep -n 'ColorScheme' ~/.config/kdedefaults/kdeglobals 2>/dev/null
```

记住这个细节 —— 「一个会静默失败的陷阱」的根因就在这儿。

``.colors`` 基座文件是什么

`<名称>.colors` 是完整的配色方案文件，里面是 `[Colors:View]`、`[Colors:Window]` 这样的段。脚本读它的顺序是：

先读 `kdeglobals` 里的 `[Colors:*]` 段（那是用户覆盖后的结果）
再用 `.colors` 文件补齐缺失的段

这个「补齐」在正常情况下是好事 —— 少几个键不影响。但它也正是那个陷阱最难发现的地方，到时候会说。

第一步：读 KDE 配色，生成 Kitty 主题

先建一个目录放脚本。位置随意，但记住它 —— 后面 systemd 单元要指过来。

```bash
mkdir -p ~/.local/share/kde-terminal-theme-sync
cd ~/.local/share/kde-terminal-theme-sync
```

把 `generate-kitty-theme.py` 放进去。这个脚本 492 行，不铺在正文里 —— 下载或 clone 下来放到那个目录即可：

完整脚本：generate-kitty-theme.py 492 行 / 19.8 KB ｜直接下载

下面讲它的两处设计决策。不用对着源码读，看完再回去翻也来得及。

先跑一次看看它能不能读出你的配色：

```bash
python3 generate-kitty-theme.py
```

我这边（BreezeDark）的输出是这样，这是真实运行结果：

```plaintext
[*] 当前 KDE 配色方案: BreezeDark  (来源: ~/.config/kdeglobals)
[*] 读取基础配色文件: /usr/share/color-schemes/BreezeDark.colors
[*] 检测到 暗色 主题 (背景亮度=22)

foreground  #fcfcfc
background  #151a1e
cursor      #3daee9
```

两个设计决策，值得单独讲

脚本里有两处看起来可以「更统一」、但故意不统一的地方。

① ``background`` 为什么要掺 5% accent

纯搬 KDE 的 `BackgroundNormal` 得到的是一块死板的灰。它和 KDE 窗口放在一起，一眼能看出「不是一家人」。

所以脚本把 accent 按 5% 掺进背景 —— 上面那个 `#151a1e`，原始 `BackgroundNormal` 是 `(20, 22, 24)`，掺入 accent 之后变成了 `#151a1e`。差别很小，但整块背景「活」了。

② ANSI 蓝为什么不跟随 accent

这是更重要的一个。

如果你的 KDE `ForegroundLink` 被覆盖成了非蓝色（比如玫瑰粉）， `color4`（ANSI 蓝）不会跟着变 —— 脚本会检测色相，不是蓝就回退到标准蓝 `#2980b9`。

理由很实际：终端里太多程序用 ANSI 蓝表示「目录」「信息」「链接」。它变成粉色之后，`ls` 的输出会读不懂 —— 目录和普通文件分不出来。

功能语义色不能为了好看让路。 这和「配色统一」是两回事，脚本选了前者。

第二步：生成 Starship 调色板

同样放进那个目录（589 行，一样不铺在正文里）：

完整脚本：generate-starship-palette.py 589 行 / 22.4 KB ｜直接下载

为什么只改 ``[palettes.kde]`` 段

`starship.toml` 是你自己的配置文件，里面可能有大量手动调过的东西。脚本默认整份输出（第一次用），但加上 `--palette-only` 就只更新 `[palettes.kde]` 这一段，其它原样保留：

```bash
python3 generate-starship-palette.py --palette-only
```

```plaintext
[*] 首次备份到: ~/.config/starship.toml.bak
[✓] palette 段已更新: ~/.config/starship.toml
```

自动同步链路用的就是 `--palette-only` —— 自动化不该覆盖你的手动配置。

调色板是怎么派生的

从 KDE 拿到的只有一个 accent 色。脚本用混色派生出三个层次：

键	怎么来的	用在哪
``accent``	KDE ``DecorationFocus`` 原色	Git 分支胶囊（最醒目）
``accent_soft``	accent 与背景 55% 混合	主机名、用户名胶囊
``accent_dim``	accent 与背景 25% 混合	目录、命令耗时胶囊

这样几个胶囊之间有层次，而不是一片同样的颜色。

第三步：让它自己跑起来

手动跑脚本能解决问题，但每次换壁纸都要记得跑一次，那就等于没有。

用 systemd 的用户级 Path 单元监听 `kdeglobals`。

下面这三个文件很短，直接铺开 —— 正文要讲解的部分必须能当场对着看：

```ini
[Unit]
Description=Watch kdeglobals for KDE theme changes

[Path]
# 监听这个文件被改写。KDE 换壁纸取色 / 切配色方案 / 昼夜自动切换
# 都会改写它，所以三种情况都能触发同步。
PathModified=%h/.config/kdeglobals

[Install]
WantedBy=default.target
```

```ini
[Unit]
Description=Sync Kitty/Starship colors from KDE theme
After=graphical-session.target

[Service]
Type=oneshot
# ⚠️ 路径按你的安装位置改。%h 是 systemd 的家目录占位符，
#    所以这一份不用改就能用（前提是你把脚本放在这个目录）。
#    用 /usr/bin/bash 显式调用，省得依赖脚本的可执行位。
ExecStart=/usr/bin/bash "%h/.local/share/kde-terminal-theme-sync/auto-sync.sh"
```

同步入口：

```bash
#!/usr/bin/env bash
# KDE 配色变化 → 同步 Kitty/Starship（由 kde-theme-sync.path 触发，也可手动运行）
# 幂等：内容无变化则不写盘、不发信号
#
# 2026-09-19 竞态修复：
#   KDE 分阶段写 kdeglobals（先 General/ColorSchemeHash，颜色段随后落盘），
#   而 systemd PathModified 在写入瞬间就触发，旧实现会读到半成品 →
#   生成浅色主题 → 与已有文件逐字节相同 → 判定“无变化” → 永不重试，
#   结果切到暗色模式后 kitty 背景仍是浅色（starship 因稍后读取而正常）。
#   现在：生成前等内容稳定，生成后复核，若期间又变则整体重跑；且生成器
#   遇到必需颜色缺失会退出码 3、本脚本跳过本次同步而不是写入浅色垃圾。
set -euo pipefail

exec 9>/tmp/kde-theme-sync.lock
flock -n 9 || exit 0  # 已有实例在跑则直接退出，防并发

# 脚本自己所在目录 —— **不写死路径**，clone 到哪都能跑。
# （原版写死了作者的私人路径，发布前必须去掉这类东西。）
DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
KDEGLOBALS="$HOME/.config/kdeglobals"
KITTY_CONF="$HOME/.config/kitty/colors-kde.conf"

REDO_COUNT=0    # 本次同步内允许的“整体重跑”次数
MAX_REDO=2
SETTLE_WAIT=0.4 # 稳定采样间隔
SETTLE_TRIES=12 # 最多等 12×0.4s ≈ 4.8s

# 内容摘要：作为“kdeglobals 是否仍在变”的判据
file_sig() { md5sum "$1" 2>/dev/null | cut -d' ' -f1; }

# 等 kdeglobals 写完：连续两次采样摘要一致才继续（KDE 分阶段写盘）
settle_kdeglobals() {
    local prev="" cur i
    for ((i = 0; i < SETTLE_TRIES; i++)); do
        cur="$(file_sig "$KDEGLOBALS")"
        [[ -n "$cur" && "$cur" == "$prev" ]] && return 0
        prev="$cur"
        sleep "$SETTLE_WAIT"
    done
    echo "[$(date '+%F %T')] 警告：kdeglobals 在 $SETTLE_TRIES 次采样内未稳定，继续尝试" >&2
    return 0
}

# 返回 0 表示“内容在同步期间又变了，需要重跑”，1 表示稳定
kdeglobals_changed_since() {
    [[ "$(file_sig "$KDEGLOBALS")" != "$1" ]]
}

# ── 生成前：等 KDE 把 kdeglobals 写完 ──
settle_kdeglobals

while :; do
    SIG_BEFORE="$(file_sig "$KDEGLOBALS")"

    TMP_K="$(mktemp)"
    if ! python3 "$DIR/generate-kitty-theme.py" -o "$TMP_K"; then
        # 退出码 3 = kdeglobals 半成品（生成器已自行重试过）；其余为真实错误
        echo "[$(date '+%F %T')] kitty 配色生成失败（kdeglobals 尚未写完或数据异常），本次跳过" >&2
        rm -f "$TMP_K"
        exit 0
    fi

    # 1) Kitty：生成到临时文件比对，仅内容变化时落盘并 SIGUSR1 热重载
    if ! cmp -s "$TMP_K" "$KITTY_CONF"; then
        cp "$TMP_K" "$KITTY_CONF"
        pkill -USR1 -x kitty 2>/dev/null || true
        echo "[$(date '+%F %T')] kitty colors-kde.conf 已更新并发送 SIGUSR1"
    else
        echo "[$(date '+%F %T')] kitty 配色无变化"
    fi
    rm -f "$TMP_K"

    # 2) Starship：只更新 [palettes.kde] 段（脚本内部自带幂等）
    OUT="$(python3 "$DIR/generate-starship-palette.py" --palette-only 2>&1 || true)"
    if echo "$OUT" | grep -q "palette 段已更新"; then
        # 真正写入了新 palette → 通知所有 fish 重绘 prompt（等效窗口 resize；
        # SIGWINCH 默认忽略、无杀伤。fish 重绘时 starship 重读配置即换色，
        # 解决 transience 下已开终端 prompt 不刷新问题）
        pkill -WINCH -x fish 2>/dev/null || true
        echo "[$(date '+%F %T')] starship palette 已更新，已通知 fish 重绘"
    elif echo "$OUT" | grep -q "palette 无变化"; then
        echo "[$(date '+%F %T')] starship palette 无变化"
    else
        echo "[$(date '+%F %T')] starship 更新异常：$OUT" >&2
    fi

    # ── 生成后复核：若 kdeglobals 在本次同步期间又被改写（说明读到的可能仍是半成品），整体重跑 ──
    if kdeglobals_changed_since "$SIG_BEFORE"; then
        if ((REDO_COUNT < MAX_REDO)); then
            REDO_COUNT=$((REDO_COUNT + 1))
            echo "[$(date '+%F %T')] 检测到 kdeglobals 在同步期间再次变化，重跑同步（第 $REDO_COUNT 次）"
            settle_kdeglobals
            continue
        fi
        echo "[$(date '+%F %T')] 警告：kdeglobals 在 $MAX_REDO 次重跑后仍在变化，放弃本次同步" >&2
    fi
    break
done
```

整条链路是这样：

```plaintext
kdeglobals 变化
 └─ kde-theme-sync.path
     │  (systemd --user，监听文件修改)
     └─ kde-theme-sync.service  oneshot
         └─ auto-sync.sh
             ├─ 生成到临时文件
             ├─ 与现有配置逐字节比对
             ├─ 有变化才落盘
             ├─ kitty: SIGUSR1 热重载
             └─ starship: 只更新
                [palettes.kde] 段
```

这张图刻意每行不超过 44 列 —— 手机上不用横向滚动就能一眼看全。代码块本身是支持横向滚动的（超宽时在块内滑动，页面不动），但对树形图来说，能一眼看全比能滚动有用。

为什么用 ``PathModified=`` 而不是定时轮询

KDE 改配置是事件驱动的。轮询要么延迟高（间隔大），要么空转（间隔小）。 `PathModified=` 精确到「这个文件被写了」这个事件。

热重载：两个信号，各有各的原因

Kitty —— `SIGUSR1`。 Kitty 收到就重新读配置文件。没有它，你得重启终端。

Starship —— `SIGWINCH`。 这个稍微绕一点：

Starship 每次画 prompt 都会重读配置，所以新开的终端本来就会用新色。但已经开着的终端不会 —— 它会一直停在旧色上。

`SIGWINCH` 是终端窗口大小改变的信号。fish 收到会重绘 prompt，重绘时 Starship 重新读配置，于是已开终端也即时换色。

```bash
pkill -WINCH -x fish 2>/dev/null || true
```

⚠️ 注意 `-x`：它要求进程名精确匹配。不要用 `pkill -f` —— 那个模式串会匹配到命令行里任何含该字符串的进程，包括执行它的那个 shell 自己。

不用 fish 怎么办

上面那一行是唯一和 shell 绑定的地方。换 shell 就换它：

fish —— `pkill -WINCH -x fish`（本方案默认）
bash —— `pkill -WINCH -x bash`。但 bash 收到 `SIGWINCH` 不一定重绘 prompt，可能仍需新开终端
zsh —— 同理；可以用 `TRAPWINCH` + `zle reset-prompt`，但需要额外配置

其它部分与 shell 无关。 你也可以直接删掉那一行 —— 代价只是已开终端要新开一个才换色。

安装

```bash
# 1. 装 systemd 单元
cp kde-theme-sync.path kde-theme-sync.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now kde-theme-sync.path

# 2. Kitty 那边接上 include（~/.config/kitty/kitty.conf）
#    include colors-kde.conf

# 3. 看状态
systemctl --user status kde-theme-sync.path
journalctl --user -u kde-theme-sync.service -f
```

`.service` 里默认写的是 `%h/.local/share/kde-terminal-theme-sync/auto-sync.sh` （`%h` 是 systemd 的家目录占位符）。脚本放在别处就改那一行。

⚠️ 一个会静默失败的陷阱

这一节是全文最值钱的部分。 任何监听 KDE 配置文件的工具都可能踩进去，而且它失败的时候日志里一切正常。

现象

自动同步上线两周后，某天切到暗色模式：

kitty 背景仍是浅色，而 starship 已经正确变暗。

同一个桌面、同一次切换、同一份输入，一个跟上了，一个没跟上。

journal 里更奇怪：

```plaintext
9月 19 18:30:16  Starting Sync colors...
9月 19 18:30:16  kitty 配色无变化
                 ↑ 该更新却判定"无变化"
9月 19 18:30:16  starship palette 已更新
                 ↑ 同一份输入却变了
```

同一秒、同一份 `kdeglobals`，两个脚本得出相反结论。

根因链

六步，一步都不能少。

KDE 写 `kdeglobals` 是分阶段的。 不是一次写完 —— 可能先落 `[General]`，颜色段随后才写
`PathModified=` 在第一次写入事件就触发。 它不知道「文件还没写完」这回事
同步抢在颜色段落盘之前读文件。 读到的是「有 `[General]`、无 `[Colors:View]`」的中间态
取色函数拿不到值，回退到默认。 于是生成一份看起来正确的浅色主题
它与磁盘上已有的浅色文件逐字节相同 → 幂等比对判定「无变化」→ 不写盘、不发信号
颜色段真正落盘时，`PathModified` 不再触发（文件已经“改过”了）→ 永远不重试 → kitty 永久僵在浅色

而 starship 那个脚本晚了一点点拿到完整文件，所以它变暗了。

结论：这是同步链路的竞态 ——「读到半成品 + 只比较一次」，不在 kitty，也不在 starship。

为什么它特别隐蔽

三个「看起来正常」叠在一起：

脚本没报错（它确实成功生成了一个主题）
日志说**「配色无变化」**（从它的角度看，确实没变化）
终端里确实有一个配色（只是错的）

没有任何一个环节会亮红灯。 你只会觉得「这次怎么没跟上」，手动跑一次又好了 —— 于是永远查不到根因。

三条防线

一、生成前等它写完。 不抢跑，连续两次采样内容一致才继续：

```bash
settle_kdeglobals() {
    local f="$HOME/.config/kdeglobals" prev="" cur i
    for ((i = 0; i < 12; i++)); do
        cur="$(md5sum "$f" | cut -d' ' -f1)"
        [[ "$cur" == "$prev" ]] && return 0
        prev="$cur"; sleep 0.4
    done
    return 0   # 超时也继续，避免卡死整条链路
}
```

二、只接受完整输入。 `[Colors:View] BackgroundNormal` 缺失就视为「还没写完」，报错退出（退出码 3），让调用方跳过本次 —— 而不是拿默认值生成一份浅色垃圾。

三、生成后复核。 再校验一次摘要；如果期间又变了（说明 KDE 还在写），整体重跑，上限 2 次。

三层叠起来的效果一句话：

宁可这次不更新，也绝不写入错误的颜色。 不更新只是晚一点，写错了会一直错到下次切换。

退出码约定

调用方要据此决策，所以写进文档：

0 —— 成功（含「无变化」），正常。
2 —— 参数错误，修正调用。
3 —— KDE 配色数据不完整（半成品，重试后仍缺关键段）。`auto-sync.sh` 跳过本次，等下次变化再触发。

调试重试节奏用 `--wait <秒>` / `--attempts <次数>`；需要退回旧行为（缺失时用回退默认值）时加 `--allow-missing-colors` —— 但那个开关只该用来排错，不该进自动化链路。

⭐ 「浅色垃圾」到底是什么颜色

这里有个连我自己第一版都复现错的地方，值得讲清楚。

拿一个半成品 `kdeglobals`（只剩 `[General]`）配合 `--allow-missing-colors` 跑：

`[General] ColorScheme=BreezeDark`（方案名还在）
- 新行为：退出码 3，不写盘 ✅
- 旧行为：⚠️ 仍然正确 —— 方案名还在，从 `.colors` 兜底读到了
只剩 `ColorSchemeHash`（方案名也不在）
- 新行为：退出码 3，不写盘 ✅
- 旧行为：❌ 产出 `background #f5fafd`（近白）

关键在第二条。 只有方案名也缺失时，兜底路径才断掉，取色函数才会拿到默认值 `(255,255,255)` → 判为亮色 → 生成近白的浅色。

而那个近白的浅色，恰好与磁盘上已有的浅色文件逐字节相同 —— 于是触发第 5 步的「无变化」判定，永远不再重试。

这也解释了为什么这个问题那么难查：它需要两个条件同时成立 （颜色段缺失 + 方案名缺失）才会发生。偶发、难复现、日志正常。

第二个坑：判断「完整性」必须看原始文件

第一版我把「必需颜色是否齐全」的判断放在合并后的字典上。测试直接打脸：

`.colors` 基座文件会把缺失的 `[Colors:View]` 补齐 —— 防护形同虚设，真实缺色的 `kdeglobals` 照样生成了浅色主题。

必须判断原始的 `kdeglobals`。 因为「半成品」的定义就是 原始文件里颜色段还没落盘，跟合并后的结果没关系。

怎么验证它真的在工作

隔离测试：用假 ``HOME``，不碰真实配置

不要去动你自己的 `~/.config/kdeglobals`。造一个假的：

```bash
FAKE=/tmp/fakehome
mkdir -p $FAKE/.config

# 用系统自带的 BreezeDark 造一份"完整"的 kdeglobals
{
  echo '[General]'
  echo 'ColorScheme=BreezeDark'
  echo 'ColorSchemeHash=deadbeef'
  echo
  # 把系统配色文件里的 [Colors:*] 段搬进来
  awk '/^\[Colors:/{p=1} /^\[(?!Colors:)/{p=0} p' \
      /usr/share/color-schemes/BreezeDark.colors
} > $FAKE/.config/kdeglobals
```

然后 `HOME=$FAKE python3 generate-kitty-theme.py` —— 输出与真实环境一致。

手动复现那个陷阱

这是最值得跑一遍的测试。

```bash
# ① 只写 [General]，模拟"KDE 还在写"的中间态
printf '[General]\nColorSchemeHash=deadbeef\n' > $FAKE/.config/kdeglobals

# ② 跑一次 —— 应当退出码 3、一个字节都不写
HOME=$FAKE python3 generate-kitty-theme.py --wait 0.3 --attempts 2
echo "退出码: $?"
```

真实的输出：

```plaintext
[!] kdeglobals 尚未写完（缺 kdeglobals[Colors:View]/BackgroundNormal），0.3s 后重试 (2/2)
[✗] KDE 配色数据不完整，缺少: kdeglobals[Colors:View]/BackgroundNormal。
    通常是 kdeglobals 正在被写入的半成品状态。 本次跳过，不更新 Kitty 配色。
```

```plaintext
退出码: 3      ← stdout 零行，什么都没写
```

再试「写到一半又补上」 —— 也就是当初 bug 的原始场景：

```bash
# 先写半成品，1.2 秒后在后台补全
printf '[General]\nColorSchemeHash=deadbeef\n' > $FAKE/.config/kdeglobals
( sleep 1.2; cp /tmp/full-kdeglobals $FAKE/.config/kdeglobals ) &

HOME=$FAKE python3 generate-kitty-theme.py --wait 0.4 --attempts 6
```

```plaintext
[!] kdeglobals 尚未写完（缺 kdeglobals[Colors:View]/BackgroundNormal），0.4s 后重试 (2/6)
[!] kdeglobals 尚未写完（缺 kdeglobals[Colors:View]/BackgroundNormal），0.4s 后重试 (3/6)
[!] kdeglobals 尚未写完（缺 kdeglobals[Colors:View]/BackgroundNormal），0.4s 后重试 (4/6)
[*] 当前 KDE 配色方案: BreezeDark  (来源: ~/.config/kdeglobals)
[*] 检测到 暗色 主题 (背景亮度=22)
```

```plaintext
退出码: 0      ← 重试机制接住了，拿到正确的暗色
```

旧代码在这个场景下必然留下浅色。 现在它会重试到数据完整为止。

排错

完全不生效
- `kde-theme-sync.path` 没启用 → `systemctl --user status kde-theme-sync.path`
- systemd 单元里的路径不对 → 看 `.service` 的 `ExecStart`，路径要与脚本实际位置一致
- Kitty 没接上 → `~/.config/kitty/kitty.conf` 里要有 `include colors-kde.conf`
换了颜色但已开终端不变
- Starship 需要重绘 → 那一行 `SIGWINCH` 是否生效？新开一个终端验证是否正常
- 不是 fish → 见上面「不用 fish 怎么办」
亮暗切换时 kitty 不跟随 —— 就是那个竞态。确认脚本版本包含三条防线；手动跑一次 `bash auto-sync.sh`
脚本报退出码 3 —— `kdeglobals` 是半成品。正常防护，等下次变化；反复出现就加大 `--wait` / `--attempts`
颜色明显不对 —— 方案名读错了。`grep ColorScheme ~/.config/kdeglobals ~/.config/kdedefaults/kdeglobals`
ANSI 蓝没跟着 accent 变 —— 这是故意的。功能语义色不跟随，见「第一步」里「ANSI 蓝为什么不跟随 accent」

备选方案：kitty 自带的 ``auto-color-scheme``

Kitty 0.38 起自带这个功能：跑一次 `kitten themes`，把主题分别存成 light / dark / no-preference 三份 `*.auto.conf`，之后 kitty 自己查询系统配色并切换。

不需要任何外部脚本。 听起来应该直接换过去，但它有个要命的性质：

When these files exist, the colors in these files override all other colors, and also all background image settings, even those specified using the `kitty --override` command line flag.

它会完全压制 `include colors-kde.conf`。也就是说，用了它就等于放弃跟随 KDE 的 accent 和壁纸取色 —— 而那正是这套东西存在的理由。

什么时候它更合适：你只需要亮/暗跟随，不需要终端配色「从壁纸长出来」。

文件清单

`generate-kitty-theme.py`: 读 KDE 配色 → 生成 Kitty 主题。放在 `~/.local/share/kde-terminal-theme-sync/`。
`generate-starship-palette.py`: 读 KDE 配色 → 生成 Starship 调色板。同上。
`auto-sync.sh`: 同步入口：幂等比对 + 热重载信号。同上。
`kde-theme-sync.path`: 监听 `kdeglobals`。放在 `~/.config/systemd/user/`。
`kde-theme-sync.service`: oneshot 执行 `auto-sync.sh`。同上。

完整代码：https://github.com/LaT-SKY/kde-terminal-theme-sync（MIT，可直接 clone）

```bash
git clone https://github.com/LaT-SKY/kde-terminal-theme-sync
```

参考

kitty 配置文档：`/usr/share/doc/kitty/html/`
kitten-themes(1) man page
kitty 官方文档 themes.rst

让微信在 Wayland 下原生跑起来

Sun, 05 Jul 2026 00:00:00 GMT

同一个桌面、同一个 fcitx5、同一个用户。终端能使用中文输入法，微信不能。

这真的是一个很恼火的问题，而且对于小白来说也确实是使用 Linux 的第一关（Maybe？）。所以我准备了如下教程。

注意，如果你是一个 Hyprland / niri 用户，以下教程可能不适合你。笔者曾经使用 Hyprland 时找遍了网络的教程也没法调教好微信

先决条件

需要	说明
微信 Linux 版 4.x	3.x 及 Wine 版是另一回事，见附录
Fcitx5	输入法本体。``fcitx5-diagnose`` 跟着它一起装
Wayland 会话	``echo $XDG_SESSION_TYPE`` 要输出 ``wayland``
KDE / GNOME 等	靠 ``.desktop`` 文件启动应用的环境都适用

这套做法在什么环境上验证过

```plaintext
CachyOS (Arch) ｜ KDE Plasma 6 ｜ Wayland
wechat-bin 4.1.13.23 ｜ fcitx5 5.1.22
```

只在上面这一个组合上实测过。 下面这张表说明哪些地方会因环境而异：

项	是否通用	说明
用户级 ``.desktop`` 覆盖系统级	✅ 通用	XDG 规范，各桌面环境一致
``env VAR=值命令`` 的写法	✅ 通用	``env`` 是 coreutils，一定有
``text-input-unstable-v3`` 这个模块名	⚠️ 需要 Qt 自带	见「这两个参数各干什么」
``--ozone-platform=wayland``	⚠️ 只对有内嵌 Chromium 的应用有意义	同上
微信的具体版本	❌ 会变	写这篇时是 4.1.13.23

三个自查命令：

```bash
echo "$XDG_SESSION_TYPE"                    # 要输出 wayland
which fcitx5-diagnose                       # 诊断工具，随 fcitx5 一起装
ls ~/.local/share/applications/             # 用户级 launcher 放这
```

第一步：先搞清楚微信到底是什么

网上流传一个说法：「Linux 微信是 Wine / 兼容层跑的」。实际上，微信的官网上或者 AUR 上均可以下载到原生的 Linux版本

```bash
# ① 它链接了 Qt 吗？
ldd /opt/wechat/wechat | grep -c Qt              # → 0

# ② 那 Qt 在哪？
grep -a -o -m1 'Qt 6\.[0-9.]*' /opt/wechat/wechat   # → Qt 6.6.

# ③ 是 Chromium 套壳吗？
grep -a -c 'Electron/' /opt/wechat/wechat        # → 0
```

三条读下来：

结论	依据
它是 Qt 6.6 应用	主程序里能搜到 ``Qt 6.6.``
Qt 是静态链接进去的	``ldd`` 看不到任何 Qt 库，``/opt/wechat/`` 下也没有 ``libQt*.so`` —— 整个 Qt 被编进了那个 181 MB 的主程序
不是 Electron / Chromium 套壳	``Electron/``、``Chrome/`` 各 0 处
不是 Wine	同上。这是腾讯官方的 Linux 原生客户端

虽然现在的微信已经是原生的 Linux 程序了，但是我们还是会按照古法教程提供可能已经没有作用的环境变量设置

原理：Qt 应用在 Wayland 下有两条路

同一个 Qt 应用，在一个同时有 `DISPLAY` 和 `WAYLAND_DISPLAY` 的会话里，可能落在两个完全不同的地方：

```plaintext
① 兼容路径（XWayland）
   Qt → xcb 插件 → XWayland → X 服务器
   输入走 XIM：按【字符串】名字查服务

② 原生路径（Wayland）
   Qt → wayland 插件 → 合成器
   输入走 text-input：协议握手，不查名字
```

XIM 是按名字查的：应用拿着 `XMODIFIERS` 里那个字符串去找服务，差一个字符就连不上，而且失败时它不吭声（附录里有完整案例）。

原生 Wayland 没有这一层 —— 输入法由合成器统一调度，应用和输入法之间是协议握手，不存在「名字对不上」这种失败模式。

所以正解不是「把 XIM 修好」，是「别走 XIM」。

第二步：修改应用程序快捷方式

⚠️ 不要改 `/usr/share/applications/wechat.desktop`。，下次升级就会被覆盖回去了。

拷一份到用户级目录，改那份：

```bash
mkdir -p ~/.local/share/applications
cp /usr/share/applications/wechat.desktop ~/.local/share/applications/
```

然后把里面的 `Exec` 改成这一行：

```plaintext
Exec=env QT_IM_MODULE=text-input-unstable-v3 /opt/wechat/wechat %U --ozone-platform=wayland
```

用户级目录里的同名文件会覆盖系统级那个，不用删系统文件，也不用 root。

嫌手改麻烦就在桌面的菜单编辑器里改（KDE 是右键 → 编辑应用程序）。它会把改完的整份文件写到用户级目录 —— 效果一样，而且是同一个机制。

改完重新从菜单启动微信。已经在跑的进程不会变，得退干净再开。

这两个参数各干什么

分开说，因为它们的作用域完全不同。

``QT_IM_MODULE=text-input-unstable-v3``

让 Qt 用 Wayland 原生的 text-input 协议找输入法，而不是回退到 X11 那套。

这个值是谁认的？实测可以查：

```bash
grep -rl 'text-input-unstable-v3' /usr/lib/qt6/sbom/
```

输出里有 `qtbase-WaylandClient_Attribution_wayland-text-input-unstable-v3` —— 它是 QtBase 自带的 Wayland 客户端实现，编译在 Qt 里，不是外挂插件。

顺带排掉一个误解：它不是 fcitx5 提供的。系统里的 `/usr/lib/qt6/plugins/platforminputcontexts/` 只有 `compose`、`fcitx5`、`ibus` 三个插件，没有这个名字 —— 它走的是 Qt 自己那条路。

``--ozone-platform=wayland``

把应用里内嵌的 Chromium 组件推上原生 Wayland。

这里要诚实说一句实测结果：

```bash
grep -a -c ozone /opt/wechat/wechat        # → 0
grep -a -l ozone /opt/wechat/*.so          # → libmmcronet.so、libmmmojo.so
```

`ozone` 这个字符串在主程序里一个都没有，它只出现在 `libmmcronet.so` （Chromium 的网络栈）和 `libmmmojo.so`（Chromium 的 IPC）里。

也就是说：这个开关管的是微信内嵌网页渲染那一半，不是 Qt 主界面。打包者把它和上面那条一起给，两条配着用 —— 别只加一条。

⚠️ 为什么写成 ``env`` 前缀，而不是塞进 ``/etc/environment``

把 `QT_IM_MODULE=text-input-unstable-v3` 全局设上，会连 X11 应用一起改 —— 而那些应用恰恰相反，需要的是 `QT_IM_MODULE=fcitx`（Qt 的 X11 输入法模块）。

一个变量，两种应用，需求是相反的。 所以正确的粒度是按应用：

作用范围	怎么设	给谁
全局	``/etc/environment`` 或 ``~/.config/environment.d/``	走 XWayland 的 Qt 应用 → ``QT_IM_MODULE=fcitx``
单个应用	``.desktop`` 的 ``Exec`` 里用 ``env`` 前缀	走原生 Wayland 的 Qt 应用 → ``text-input-unstable-v3``

实测这台机器上就是这么配的，同一个手法用在两个应用上：

```plaintext
wechat.desktop   Exec=env QT_IM_MODULE=text-input-unstable-v3 /opt/wechat/wechat %U --ozone-platform=wayland
chatgpt.desktop  Exec=env QT_IM_MODULE=text-input-unstable-v3 chatgpt %U
```

这个模式可以推广：任何「Qt + 跑在 Wayland + 打不出中文」的应用，先别动全局变量，先给它单独加一个 `env QT_IM_MODULE=text-input-unstable-v3`。改错了只影响这一个应用。

怎么验证

① 能打字（这似乎是废话）

打开微信，`Ctrl`（实际切换键盘的按键因人而异），输入法面板弹出来、能输入中文。

② 想确认它真落在 Wayland 而不是 XWayland

```bash
# 看这个进程实际拿到的环境变量
pid=$(pgrep -f '/opt/wechat/wechat' | head -1)
tr '\0' '\n' < /proc/$pid/environ | grep -E 'QT_IM_MODULE|QT_QPA_PLATFORM'
```

期望看到 `QT_IM_MODULE=text-input-unstable-v3`。看不到就说明 launcher 没生效 —— 多半是还在用旧的桌面缓存，注销重登一次。

更彻底的办法是看它有没有出现在 X11 的客户端列表里（`xlsclients`，Arch 上是 `xorg-xlsclients` 包）。出现在那里 = 还在走 XWayland。这个工具本文没有实测，只作为线索。

附录：如果应用还在走 XWayland

老版本微信、不支持 Wayland 的 Qt 应用、纯 X11 程序 —— 它们还是得走 XIM。这时才轮到下面这套。

先跑 ``fcitx5-diagnose``

它是 fcitx5 自带的体检表，会逐环检查环境变量、X 服务器上的注册名、 Qt / GTK 的 IM module。报错会指名道姓地说哪个变量不对。

小节	管谁
``## Xim:``	X11 应用
``## Qt:`` / ``## Gtk:``	对应框架的程序

⚠️ 它会打印发行版、内核版本、进程名。脚本自己在结尾也提醒了 —— 贴到论坛之前先自己扫一遍。

⚠️ 莫大的陷阱：尾随空格

`/etc/environment` 里那一行长这样：

```plaintext
XMODIFIERS=@im=fcitx 
```

看着完全正常。但那最后一个空格会被原样当成服务名的一部分，而 X 服务器上注册的名字是 `fcitx`（不带空格）。名字对不上就查不到，查不到它也不报错 —— 表现就是「按了没反应」。

让它现形：用 `cat -A`，它把行尾这类不可见字符显示出来。

```bash
cat -A /etc/environment | grep XMODIFIERS
```

```plaintext
XMODIFIERS=@im=fcitx $      ← 出错：$ 前面多一个空格
XMODIFIERS=@im=fcitx$       ← 正确：$ 紧贴着 x
```

末尾那个 `$` 是 `cat -A` 给行尾打的标记。它前面挨着的是不是空格，就是全部区别。

怎么修：环境变量有两个独立注入点，别只改一处。

机制	文件	谁读它	要 root 吗
PAM	``/etc/environment``	``pam_env``，登录时	要
systemd –user	``~/.config/environment.d/*.conf``	systemd 用户管理器	不要

```bash
mkdir -p ~/.config/environment.d
cat > ~/.config/environment.d/fcitx5.conf <<'EOF'
XMODIFIERS=@im=fcitx
GTK_IM_MODULE=fcitx
QT_IM_MODULE=fcitx
SDL_IM_MODULE=fcitx
EOF
```

注意，如果你选择直接复制我的代码，那么建议自行输入最后的 EOF 并回车

改完必须重新登录 —— 环境变量只在会话建立时读一次，新开终端不算。

排错

现象	可能原因	下一步
改完没变化	应用还在跑旧进程	退干净再启动
还是没有	桌面缓存没刷新	注销重登，或 ``update-desktop-database ~/.local/share/applications``
Wayland 应用也打不出中文	输入法没起来	``pgrep -a fcitx5``；没进程就 ``fcitx5 -d``
只有 X11 应用不行	走的是 XIM	看上面的附录
``xprop`` 说没有 XIM_SERVERS	不在 X 会话里	``echo "$DISPLAY"`` 要有值

参考

`fcitx5-diagnose` —— fcitx5 自带的诊断工具，附录部分的第一手来源
AUR: wechat-bin —— 上面那行 `Exec` 的建议出处
Fcitx5 Wiki — 输入法相关环境变量

望向天脉的技术记录

Nahimic 出厂音效续篇：变体判定与空间效果

先决条件

一、变体由 SMBIOS 的 OEM 串决定

把那张表读出来

8 个候选其实只有 2 套曲线

二、390 个参数不在磁盘上

三、空间效果：只有开关，没有强度

四、串扰抵消在笔记本扬声器上不成立（至少现在不成立）

RACE 是什么

数值复核

为什么在笔记本上不成立

五、校验器漏掉的 37 个插件块

六、脉冲响应改名，以及 EasyEffects 的两个坑

七、如何获取本文的工具？

八、还没做的

九、省流

被人脸钱包密钥掉包的登录密码

先决条件

四条登录途径

排查时间线

确定错误路径

第一轮：给模块加一个“非空就跳过”的判断

第二轮：补丁整套回退

第三轮：只改顺序，密码恢复

第四轮：钱包又打不开了

第五轮：四条路径一测，窟窿露出来了

第六轮：绕过 authtok，自己拉起 ksecretd

第七轮：把缺的那一格数据补上

最终方案

安装

验证

通用性

旁支：人脸为什么会突然不认

排错表

回滚

尚未验证的地方

参考

人脸登录后的 KWallet 自动解锁

先决条件

现象

PAM 的两段：auth 与 session

钱包为什么拿不到密码

`sufficient` 会把后面的模块整组跳过

就算把顺序调过来，人脸也交不出密码

两条错误路径

只移动 `pam_kwallet5`

借用 LUKS 的开机密码

方案选择

自建模块做什么

安装

1. 编译模块

2. 生成钱包密钥

3. 把 KWallet 的钱包密码改成这个密钥

4. 跑安装脚本

登录路径：plasmalogin

sudo

polkit 与 pkexec

1. PAM 服务

2. systemd drop-in：放开摄像头设备

3. 让 biopass 别再忽略 polkit

验证结果

排错

通用性

回滚

长期维护

参考

PLM 免按键人脸登录

先决条件

现象

greeter 为什么不自动认证

为什么不能直接把 biopass 标成 required

选择 Autologin

人脸闸门脚本

PAM 顺序

Autologin 配置

安装

验证

排错

通用性

``sufficient`` 会把后面的模块整组跳过

只移动 ``pam_kwallet5``

``setup-pi.sh``：在 Pi 上跑

``setup-client.sh``：在要连 Pi 的那台电脑上跑

快速划过 ``a`` 时不中断 hover 动画