Omarchy 排障手册实战指南从系统回滚到音频与安全锁定的完整排查方案【免费下载链接】omarchyBeautiful, Modern Opinionated Linux项目地址: https://gitcode.com/GitHub_Trending/om/omarchy本文是 Omarchy 桌面发行版官方故障排查手册的深度实践指南围绕 manual/45-troubleshooting.md 中记录的八类高频问题展开系统更新后损坏、HiDPI 显示过大、Caps Lock 失效、外设子系统突然停止工作、扬声器无声、登录被锁死以及 1Password 授权弹窗缺失。读完本文你将掌握 Omarchy 的三大系统级救援命令快照回滚、omarchy-debug、omarchy-reinstall的适用场景能独立定位显示缩放、compose 键映射、音频输出与 PAM 账户锁定的根因并在需要时深入对应配置源码完成修复。系统被更新弄坏后的三级救援方案Omarchy 针对一次更新把系统搞坏了给出了明确的处置阶梯先回滚再诊断最后重装兜底。第一级通过系统快照回滚更新导致故障时首选方案是回滚到更新前的快照版本完整流程见 manual/47-system-snapshots.md。其机制要点如下自动快照每次 Omarchy 更新前都会自动创建系统快照。也可以随时用omarchy-snapshot create手动创建对应 bin/omarchy-snapshot 脚本底层调用snapper为每个已配置的 snapper config 创建number类型快照并执行清理策略。启动与恢复在 Limine 引导加载器中按日期与版本选择一个快照进入Omarchy 版本号显示在屏幕左下角。进入快照环境后系统会弹出你正处于可引导快照中的通知点击即可开始恢复命令行方式则使用omarchy-snapshot restore它实际调用limine-snapper-restore。恢复边界回滚只恢复根文件系统root不会恢复/home。因此它能用来回退坏掉的系统更新但无法找回误删的个人文件。同理~/.config目录原样保留——如果你回滚到某个以新格式存储配置的应用/库的旧版本需要手动处理不兼容的配置文件。需要强调的是该功能仅对使用 Limine 引导加载器的安装可用自 Omarchy 2.0 起为默认GRUB 或 systemd-boot 安装无法使用。若此前开启了Setup Direct Boot直接引导到解密屏而不经过 Limine需先从 BIOS 引导菜单选择 Limine 才能进入快照列表。第二级用 omarchy-debug 收集诊断信息若回滚无法解决使用omarchy-debug打包诊断信息带到 Discord 的#omarchy-help频道求助。从源码看该命令bin/omarchy-debug支持--no-sudo与--print参数把诊断日志写入/tmp/omarchy-debug.log交互式执行omarchy debug还可以上传日志。同系列工具还包括 bin/omarchy-debug-idle用于跟踪空闲时的异常与omarchy-upload-log这组命令在 docs/file-layout.md 中被列为系统的诊断基础设施。第三级omarchy-reinstall 兜底若以上都无效运行omarchy-reinstall重新安装默认配置与软件包。查看 bin/omarchy-reinstall 源码可知其行为先确认提示gum confirm然后依次执行omarchy-reinstall-pkgs与omarchy-reinstall-configs完成后询问是否重启。脚本的警告信息写得很直白你所有的用户配置修改都会被覆盖因此请把它当作最后手段而非首选。部分应用在屏幕上显示过大Omarchy 默认按 2x 高分屏retina 级、PPI 约 218 以上来优化界面因此在 1x 屏幕上打开的应用会显得超大。根因GDK_SCALE 与 XWayland 渲染Omarchy 的显示相关默认值定义在 config/hypr/monitors.lualocal omarchy_gdk_scale 2 hl.env(GDK_SCALE, tostring(omarchy_gdk_scale))按文件内注释的解释GDK_SCALE是 GTK 绘制自身 UI 的倍率负责 X11/XWayland 窗口的尺寸。Omarchy 有意不给 XWayland 窗口做缩放而是靠这个整数值让它们保持清晰避免被合成器拉伸模糊。由于 GTK 只认整数GDK_SCALE应取显示器实际缩放比最接近的整数且修改后需要重启应用才会生效。如果你在 1x 显示器上把用户侧~/.config/hypr/monitors.lua对应本仓库的 config/hypr/monitors.lua也可通过 Omarchy 菜单Setup Monitors打开中的omarchy_gdk_scale从 2 改为 1然后重启所有过大的应用即可。更完整的缩放调优见 manual/33-monitors.md例如 4K 屏用omarchy_gdk_scale 2omarchy_monitor_scale 1.6的分数缩放组合、1080p/1440p 屏直接双双设为 1还可以用Super /与Super Alt /在 1x、1.25x、1.6x、2x、3x、4x 之间快速切换。Spotify 特例Spotify 是 Electron/CEF 类应用缩放行为独立于系统设置。如果只有它显得过大直接用Ctrl Minus缩小界面、Ctrl Plus放大即可无需改系统缩放。Caps Lock 为什么不亮了在 Omarchy 中 Caps Lock 被指定为xcompose 组合键这是 快捷 Emoji 输入 与 快捷补全 的底层机制。它换来了什么能力快捷 EmojiCapsLock M S输出 、CapsLock M C输出 、CapsLock M H输出 ❤️、CapsLock M 1输出 等一组以CapsLock M key为前缀的记忆化序列快捷补全CapsLock Space Space输出破折号 —CapsLock Space N输出你的名字、CapsLock Space E输出你的邮箱以安装时填写的信息为准。自定义补全可编辑~/.XCompose后运行omarchy-restart-xcompose让其生效。Omarchy 默认键盘选项在 default/hypr/input.lua 中定义kb_options compose:caps,shift:both_capslock_cancel多键盘布局用户还会追加grp:alts_toggle这正是把 compose 键绑定到 Caps Lock 的那一行。想恢复 Caps Lock 怎么办如果你确实怀念大写锁定功能可以把 compose 键改到别处。编辑~/.config/hypr/input.lua默认模板见 config/hypr/input.lua例如改绑到右 Althl.config({ input { kb_options compose:ralt, }, })可选的 compose 键位取值遵循 X11xkb语法如compose:caps、compose:ralt、compose:rctrl、compose:menu等按你的肌肉记忆挑选即可。相关键盘选项的综合说明还可参考 manual/34-keyboard-mouse-trackpad.md。Wi-Fi、蓝牙、音频或触控板突然失效遇到五分钟前还好好的这类外设失效耳机连不上、休眠后触控板没反应、拔掉显示器后声音消失先别急着重启整机——先单独重启对应的子系统。在 Omarchy 菜单的Update Hardware中提供 Wi-Fi、蓝牙、音频、触控板四个独立的重启入口。其动作定义在 default/omarchy/omarchy-menu.jsonc 中分别对应omarchy-restart-wifi、omarchy-restart-bluetooth、omarchy-restart-audio、omarchy-restart-trackpad等重启脚本并通过浮窗终端展示执行过程。文档指出仅重载出问题的那一个子系统就能解决绝大多数此类场景比重启整个系统快得多、代价也小得多。外接扬声器不出声大概率是它没有被设为默认输出。点击顶栏右侧的扬声器图标会打开音量弹窗在那里可以选择输出设备把外接扬声器/耳机设为默认同时逐应用per-app调节音量方便单独压低某个吵吵闹闹的应用。这个弹窗背后与 Omarchy 统一的音频输出解析逻辑联动。按 docs/audio-tuning.md 的说明音量键、输出切换 OSD 与音频面板都经由omarchy-audio-output-sink来解析当前输出真正对应哪个物理 sink从而保证各处显示一致。命令行也有等价工具例如 bin/omarchy-audio-output-set-default 支持omarchy audio output set default id sink这类用法。笔记本内置扬声器音色不对部分笔记本上Omarchy 会自动应用一套**扬声器调音speaker tuning**来校正内置扬声器的频响——因为笔记本扬声器出厂时是按 Windows 的 DSP 层来调音的Linux 拿不到这份处理。Omarchy 的调音以 PipeWire filter-chain 形式实现作为内置扬声器 sink 前面的一个独立处理节点。排查命令omarchy audio tuning status # 是否已安装调音是否在生效匹配了哪款硬件 omarchy audio tuning off # 关闭调音听原始扬声器 omarchy audio tuning on # 重新应用匹配的调音这三条子命令在 bin/omarchy-audio-tuning 中有明确定义。其工作机制在 docs/audio-tuning.md 中有完整说明值得了解的几个关键点调音图渲染到~/.config/pipewire/omarchy-speaker-tuning.conf.d/并通过独立的omarchy-speaker-tuning.service运行而不是加载进音频守护进程——这样切换调音只是启停一个小进程即使调音配置损坏也只会拖垮该服务不会导致 PipeWire 起不来on会自我校验等待调音 sink 出现、确认其输出已链接到预期的物理 sink任一步失败就整体回滚避免留下半应用的坏调音同时它会把默认 sink 切到调音并迁移现有应用流off则相反全部就绪时on是不做任何事的幂等操作迭代调音时可用--force调音覆盖模型通过match_skuDMI 产品 SKU全值匹配、match_dmiDMI 产品名/系列子串匹配、match_command自定义谓词判定安装由 install/hardware/speaker-tuning.sh 与 install/user/first-run/audio-tuning.sh 依据匹配结果自动完成没有匹配到调音的机器则完全不受影响。如果status显示有调音在生效而你更想听原始声音直接omarchy audio tuning off即可回到出厂裸音。密码登录或 sudo 失败账户锁定自救输入密码错误次数过多会被锁定。Omarchy 在 etc/security/faillock.conf 基础上启用了 PAMpam_faillock其触发阈值与解锁参数可通过 install/config/increase-lockout-limit.sh 调整该脚本把 preauth/authfail 两处规则的 deny 设为 10、unlock_time 设为 120同时 etc/sudoers.d/omarchy-passwd-tries 对 sudo 侧的尝试次数做了单独约束。简单说多次输错后任何使用密码的入口包括 sudo都会暂时拒绝你。自救流程若发生在锁屏界面按CTRL ALT F2切换到新的 TTY在 TTY 中以 root 登录重置锁定计数faillock --reset --user [your-username]把[your-username]替换成你的实际用户名。重置后即可恢复正常登录。这条命令同时适用于登录lock screen与 sudo 两侧的锁定状态因为二者共享pam_faillock的计数文件。1Password SSH Agent / CLI 的授权弹窗不出现如果你在 Omarchy 里用 1Password SSH Agent 或opCLI却看不到富文本授权确认弹窗原因通常有两个未开启硬件加速需要在 1Password 的Settings Advanced中打开Use Hardware Acceleration。这是富文本弹窗渲染的前提。注意开启后需要重启一次系统才开始生效启动后从未打开过 1Password开机后必须先启动一次 1Password 应用后续才会弹出授权确认。判定根因时先确认上述硬件加速开关是否开启再确认本次开机是否已手动启动过 1Password附快速定位相关手册与源码排查主题深入资料仓库相对路径快照回滚完整流程manual/47-system-snapshots.md、bin/omarchy-snapshot重装兜底命令行为bin/omarchy-reinstall诊断日志与上报bin/omarchy-debug显示器与缩放配置config/hypr/monitors.lua、manual/33-monitors.md键盘/compose 配置config/hypr/input.lua、default/hypr/input.lua、manual/07-hotkeys.md硬件子系统重启入口default/omarchy/omarchy-menu.jsonc音频输出解析bin/omarchy-audio-output-set-default扬声器调音机制docs/audio-tuning.md、bin/omarchy-audio-tuning账户锁定策略install/config/increase-lockout-limit.sh、etc/security/faillock.conf需要说明的是用户在桌面上编辑的是~/.config/hypr/下的用户配置本仓库中 config/hypr/ 与 default/hypr/ 分别对应模板与默认值来源大部分修复只需要按上文描述修改用户目录配置并重启相关进程即可无需触及仓库文件本身。【免费下载链接】omarchyBeautiful, Modern Opinionated Linux项目地址: https://gitcode.com/GitHub_Trending/om/omarchy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
