指南

开始之前

任何 64 位 x86 电脑都可以。安装器至少需要 1.7 GB 内存和 18 GB 硬盘空间；下面这些数值是系统用起来比较从容的配置。

同一个镜像同时支持 UEFI 和传统 BIOS。Secure Boot 可以保持开启。

下载与校验

镜像只有一个文件 moonlightos-26.04.5-bengunur-amd64.iso，旁边还有一个文件记录它的 SHA-256 校验值。写入之前请先核对：下载不完整做出来的 U 盘能启动，但随后会以各种莫名其妙的方式失败。

在 Linux 或 macOS 上，进入保存下载的文件夹后执行：

sha256sum -c moonlightos-26.04.5-bengunur-amd64.iso.sha256

在 Windows 的 PowerShell 中执行，并把输出的哈希与 .sha256 文件中的值对比：

Get-FileHash .\moonlightos-26.04.5-bengunur-amd64.iso -Algorithm SHA256
Get-Content .\moonlightos-26.04.5-bengunur-amd64.iso.sha256

第一条命令会输出 OK；第二条会输出一个哈希值，必须与文件中的一致。出现其他结果都说明下载已损坏。

下载 26.04.5

把镜像写入 U 盘

这是一个混合 ISO，直接按块复制即可：不需要专门的工具，同一个 U 盘在 UEFI 和 BIOS 电脑上都能启动。U 盘上的数据会被全部清除，容量至少需要 8 GB。

在 Linux 或 macOS 上，先确认设备名（Linux 用 lsblk，macOS 用 diskutil list），然后执行：

sudo dd if=moonlightos-26.04.5-bengunur-amd64.iso of=/dev/sdX bs=4M status=progress oflag=direct conv=fsync

sudo dd if=moonlightos-26.04.5-bengunur-amd64.iso of=/dev/rdiskN bs=4m   # macOS

设备名一定要核对两遍：dd 会老老实实写进你指定的那个设备。

Windows

使用 DD 镜像模式的 Rufus、balenaEtcher 或 Ventoy。如果 Rufus 询问以 ISO 还是 DD 模式写入，请选 DD。

从 U 盘启动

插好 U 盘后开机，打开一次性启动菜单（视厂商而定，常见的是 F12、F8、F2、Esc 或 Del），或者在固件设置中把 USB 设备设为第一启动项。Secure Boot 不需要改动。

启动菜单

• Try or Install MoonLightOS

  常规选项。带启动动画进入实时会话。

• Try or Install MoonLightOS (safe graphics)

  同上，但关闭内核模式设置。屏幕一直黑着或显示错乱时请用这一项。

• MoonLightOS in RAM (needs 6 GB+)

  把整个系统复制到内存中，之后就可以拔掉 U 盘。

• Check this medium for defects

  用构建时记录的校验值逐个核对 U 盘上的文件。

• Verbose boot (no splash, logs to serial)

  把每条消息都输出到屏幕和第一个串口。如果启动在显示可用之前就失败，这是唯一能看到原因的办法。

• UEFI firmware settings

  重启进入固件设置界面。

实时会话

最先看到的是初始设置向导：选择系统语言，确认键盘布局（可在输入框里试打），连接 Wi-Fi，然后决定是体验还是安装。它设置的每一项都是真实的系统设置，安装器也会沿用同样的选择。

实时会话就是完整且未经删改的系统：同样的桌面、同样的工具、同样的设置页面。实时会话的用户名是 moonlight，没有密码。在你运行安装器之前，这里的任何操作都不会碰硬盘。

要安装，双击桌面上的 Install MoonLightOS，或者重新打开初始设置向导并选择安装。

安装

安装器是 Calamares。走完七个页面，就开始往硬盘复制。

1. 欢迎

   安装器的语言，以及指向本指南的链接。

2. 地区

   你所在的地区和时区；区域设置和数字格式由此决定。

3. 键盘

   已经按你在向导里的选择设好。可以在输入框里试打确认。

4. 分区

   默认是清空硬盘，建立带交换文件的 ext4 文件系统；也可以选择 btrfs、xfs、f2fs，或手动分区。勾选“加密系统”即可启用 LUKS2 全盘加密并设置密码短语：这个密码每次开机都要输入，一旦忘记无法找回。在 UEFI 电脑上会创建一个 512 MiB 的 EFI 分区。

5. 用户

   你的姓名、电脑名称、用户名，以及一个至少八位、涵盖两类字符的密码。第一个账户通过 sudo 管理这台电脑；root 账户保持锁定，除非你自己开启，否则不会自动登录。

6. 摘要

   把安装器即将执行的所有操作列成一张清单。此时还没有写入任何内容。

7. 安装

   系统被复制到硬盘，安装引导程序（在 UEFI 上以 MoonLightOS 的名字写入固件启动项），并清除实时会话留下的痕迹。完成后重启并拔出 U 盘。

电脑上的其他操作系统会在首次启动时由 os-prober 检测出来，并加入 GRUB 菜单。

首次启动

刚装好的系统，与其他所有安装一样，都是同一个镜像的精确副本。凡是必须属于这台电脑独有的东西，都在首次启动、登录界面出现之前生成，由一个随后自行停用的服务完成：

• 新的机器 ID，让网络上的旁观者无法把两台安装关联起来；
• 新的 SSH 主机密钥，因为所有下载过镜像的人共用一把密钥，主机校验就没有意义了；
• GRUB 菜单，此时真实的硬盘和其中的其他操作系统才看得见；
• 按实际硬件重新生成的 initramfs，体积更小，启动动画也出现得更早；
• 图标、字体和桌面缓存，避免首次登录变慢；
• 重新启用防火墙。

它的输出写在 /var/log/moonlight-firstboot.log 中。随后出现登录界面，首次登录后会弹出欢迎窗口。

最先要做的事

• 挑选外观

  深色还是浅色，直接在欢迎程序里选。其余都在 MoonLight Tweaks 里：桌面布局、壁纸、切换时间和小部件。

• 驱动

  欢迎 → 驱动 会打开驱动管理器。如果电脑装了 NVIDIA 显卡，专有驱动就在 ISO 里，没有网络也能装上。

• 软件

  商店会把 snap、Ubuntu 仓库和 Flathub 一并列出。Thunderbird、Steam、Spotify 等搜一下就能装。

• 指纹与人脸

  欢迎 → 指纹，或者 系统设置 → 你的账户，可以录入指纹或设置人脸解锁。

• 备份

  Timeshift 会按计划为系统创建快照。请在需要它之前就配置好。

• 安全

  系统设置 → 安全 会列出这台电脑哪些有防护、哪些没有，每一行都带着能修好它的按钮。

• 开发者组件

  虚拟机、PHP 加数据库和 LaTeX，在欢迎程序里各点一下即可，都从已经配置好的仓库安装。

• Windows 程序

  把 Windows 应用打开一次：它会把 Wine 连同 DXVK、VKD3D、字体和运行库一并准备好。之后 .exe 文件直接双击就能开。

虚拟机

VirtualBox

VirtualBox 有三项设置必须改掉默认值，否则这个镜像根本起不来。失败的样子像是内存不足，其实不是：GRUB 要切到图形模式来绘制带主题的菜单，而 VirtualBox 默认只有 16 MB 显存，于是失败并给出“Out of memory. You need to load the kernel first.”这条消息。

用命令行的话：

VBoxManage modifyvm "MoonLightOS" \
    --ostype Ubuntu24_LTS_64 --memory 4096 --cpus 4 \
    --vram 128 --graphicscontroller vmsvga --accelerate3d on \
    --boot1 dvd --boot2 disk

VirtualBox 把这个介质标成“Ubuntu”，是因为它在里面找到了 /casper 目录。这只是 VirtualBox 界面上的一个标签，介质本身标识的是 MoonLightOS。不过客户机类型还是选 Ubuntu 为好，因为这样会选中正确的芯片组和显示默认值。

QEMU

UEFI，也就是大多数电脑的启动方式。先创建可写的固件变量和一块目标硬盘：

cp /usr/share/OVMF/OVMF_VARS.fd .
qemu-img create -f qcow2 disk.qcow2 30G
qemu-system-x86_64 \
  -enable-kvm -m 4096 -smp 4 \
  -machine q35 -cpu host \
  -device virtio-vga-gl -display gtk,gl=on \
  -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE.fd \
  -drive if=pflash,format=raw,file=OVMF_VARS.fd \
  -drive file=moonlightos-26.04.5-bengunur-amd64.iso,media=cdrom \
  -drive file=disk.qcow2,if=virtio

真正开启 Secure Boot，使用已写入 Microsoft 密钥的固件。启动后，mokutil --sb-state 会显示 SecureBoot enabled，设置 → 关于 里也是同样的结果：

cp /usr/share/OVMF/OVMF_VARS_4M.ms.fd OVMF_VARS.fd
qemu-system-x86_64 \
  -enable-kvm -m 4096 -smp 4 -machine q35,smm=on -cpu host \
  -global driver=cfi.pflash01,property=secure,value=on \
  -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE_4M.secboot.fd \
  -drive if=pflash,format=raw,file=OVMF_VARS.fd \
  -drive file=moonlightos-26.04.5-bengunur-amd64.iso,media=cdrom

传统 BIOS：ISO 是混合的，所以同一个文件也能按老办法启动：

qemu-system-x86_64 -enable-kvm -m 2048 -cdrom moonlightos-26.04.5-bengunur-amd64.iso

想验证 2 GB 这个说法，可以关掉加速、按最低内存启动，然后在实时会话里确认 zram 已作为交换区出现，并且内存压力保持在低位：

qemu-system-x86_64 -enable-kvm -m 2048 -smp 2 -vga std -cdrom moonlightos-26.04.5-bengunur-amd64.iso

# in the live session:
free -h                      # zram appears as swap
swapon --show                # /dev/zram0, zstd
cat /proc/pressure/memory    # "some avg10" under about 10 means it is keeping up
systemctl is-active earlyoom

VirtualBox、QEMU/SPICE 和 VMware 的增强工具已经在镜像里了，显示自适应和剪贴板共享正是靠它们。

快捷键

完整的表格在功能页面。第一天最值得先记住的是这几个：

完整表格

排查问题

• 过了启动菜单后屏幕一直是黑的

  选择 safe graphics 那一项。如果能起来，就从那里安装，之后再到驱动页面启用专有驱动。

• “Out of memory. You need to load the kernel first.”

  这是显存只有 16 MB 的 VirtualBox。把显存改成 128 MB 并开启 3D 加速；参见上面的虚拟机一节。

• 桌面用起来发卡

  在 设置 → 关于 中查看 OpenGL 渲染器。如果是软件渲染，动画会在登录时自动关闭；也可以在 Tweaks → 性能 中手动关闭。

• U 盘能启动，之后却莫名其妙地出错

  在启动菜单里运行 Check this medium for defects，并核对下载文件的 SHA-256 校验值。

• 没有 Wi-Fi

  打开驱动页面：Broadcom 的驱动已包含在镜像里。其他网卡可以在网络菜单中查看内核识别到了什么。

• 检测不到指纹识别器

  打开指纹工具。它会说明传感器的厂商，判断它属于原生支持、芯片内比对还是厂商二进制那一类，并解释可行的做法。

• 查看日志

  启动过程中报了什么、登录管理器的日志、首次启动的日志，以及当前启动主题的名称：

journalctl -b -p warning          # what the boot complained about
journalctl -b -u lightdm
cat /var/log/moonlight-firstboot.log
plymouth-set-default-theme        # should print: moonlightos

报告缺陷时，关于 → 复制报告 会把版本和硬件信息放进剪贴板，moonlight-selftest 则会输出桌面实际的运行状况。

moonlight-selftest | less

自行构建

整个发行版就是一个仓库：美术素材全部由一个源标志衍生，主题由一套配色生成，一个脚本就能把这一切变成支持 Secure Boot 的可启动 ISO。你需要 Docker（任何操作系统都行，因为构建在容器里进行）和大约 25 GB 的空闲空间。

ISO 会写到 out/ 目录，旁边附带 SHA-256 校验值。在 Windows 上，请从 Git Bash 运行，或者改用 build.ps1。

构建是怎么组织的

生成 ISO 之前，构建会在镜像内部运行 120 多项强制检查：内核、签名的 shim、两套主题、每一个 MoonTool、解码器、无线驱动、翻译，以及确认人脸解锁和紧急密码处于关闭状态。任何一项不通过，构建就会停下。临时空间用的是 Docker 卷而不是 bind mount，因为在 Windows 和 macOS 上，文件归属、符号链接和设备节点在 bind mount 中无法保留。

自定义

• 版本标识

  config/moonlight.conf 里是定义这个发行版的全部文本。

• 美术素材

  替换源标志或某张壁纸，再跑一次 tools/gen-branding.py，启动动画、GRUB、登录界面、图标和安装器的素材都会重新生成。

• 配色

  tools/gen-themes.py 里有一套深色和一套浅色配色，并按同样的规则生成两套完整主题。

• 安装的软件包

  写在 packages/*.list 中，一行一个包，按文件名顺序安装；99-purge.list 列出之后要移除的内容。

• 桌面默认设置

  放在 rootfs/etc/dconf/db/moonlight.d/，使用 dconf 的 keyfile 格式。这些是默认值而非锁定项，用户可以随意更改。

• 快速重建

  改动 rootfs/ 或软件包清单之后，build.sh rootfs 会在缓存的基础镜像上重做 chroot 阶段，build.sh image 则重新打包 ISO；build.sh finish 适合用来调启动菜单。

获取帮助与报告缺陷

一份有用的报告会说明你期望发生什么、实际发生了什么，以及是在什么样的电脑上发生的。第三点 MoonLightOS 帮你做好了：

• 关于 MoonLightOS → 复制报告，会把版本、硬件、图形渲染器和 Secure Boot 状态以文本形式放进剪贴板。
• moonlight-selftest 会输出当前生效的主题设置、外壳样式表是否正确加载、哪个显卡驱动在工作、哪些服务启动失败。
• 如果是启动方面的问题，Verbose boot 选项会把每条消息都写到屏幕和第一个串口。
• 如果是安装器的问题，请查看已安装系统上的 /var/log/moonlight-firstboot.log，以及 journalctl -b -p warning。

发往何处

公开的问题追踪和支持渠道会在这里公布。在此之前请先把报告保存好：它需要的全部内容，上面两个工具都能提供。