写在前面

很多家庭服务器都是台式机的「退役再就业」：机箱风扇、CPU 散热器都带着 ARGB 灯。白天看着挺好看，到了夜里满屋子彩虹就有些扰人了。

OpenRGB 是一个跨平台的开源项目，可以在 Linux 下接管这些灯光。本文给出在一台没有显示器、没有桌面环境的 Debian 13 服务器上部署它的通用流程——不同主板、不同控制通道（i2c 或 USB）、不同设备数量都能照着走；文中出现的具体型号与数值都只是示例，请以你自己的输出为准。

适用前提：Debian 13（trixie，其他版本思路一致，安装包需选对应版本）；具备 sudo 或 root 权限；能通过 SSH 登录；主板或外设带 RGB／ARGB 灯。

一、安装：先确认源里有没有，再去项目的新家拿包

第一步永远是先自查，因为软件源的收录情况随时会变：

# 查看本机源里是否有这个包；没有会提示「无法定位软件包」
apt-cache policy openrgb

截至本文写作时（2026 年 9 月），Debian 13 官方源并未收录 openrgb（它只在 sid/unstable 中维护）。此时有两条路：

• 推荐：使用官方发布页提供的 Debian 预编译包；
• 参考：项目已从 GitLab 迁至 Codeberg，跟着旧教程 git clone 源码编译会卡在 CMake 一步（原因见文末踩坑栏）；如要自行编译，请以新仓库的 Documentation/Compiling.md 为准。

安装走官方预编译包：

# 官方发布页：https://codeberg.org/OpenRGB/OpenRGB/releases
# 在资产列表中挑选「与你系统匹配」的那一个：
#   Debian 代号：trixie（13）/ bookworm（12）
#   架构：amd64（x86_64）/ arm64 等
# 例如文件名形如 openrgb_<版本>_<架构>_<代号>_<校验串>.deb

# 进入下载目录后安装（文件名以你实际下载到的为准）
sudo apt install ./openrgb_<版本>_<架构>_<代号>_<校验串>.deb

# 验证
openrgb --version

安装过程中可能出现一句提示，大意是 _apt 用户无法访问 .deb 文件、已提权为 root 来完成安装。这是把安装包放在个人主目录下的常见现象，不影响安装结果；介意的话，装完后把 .deb 删掉即可。

日常维护同样简单：想升级就重复「下载新包 → apt install ./新包」；想彻底卸载，sudo apt remove openrgb 即可（dpkg 托管的包不会留下编译残留）。

如果你改用源码编译安装，可执行文件通常在 /usr/local/bin/openrgb：systemd 单元里的路径要相应调整，卸载也不能用 apt remove，需要手动删除安装的文件。

二、无头运行的关键：一个环境变量

服务器没有图形界面，而 OpenRGB 是基于 Qt 的图形程序。让它跑起来，只需要告诉 Qt 使用离屏模式：

# 列出被识别的设备；offscreen 让 Qt 在没有显示器时也能正常初始化
sudo QT_QPA_PLATFORM=offscreen openrgb --list-devices

# 若你的 sudoers 策略会清理环境变量导致上面的写法无效，可以显式传递：
sudo env QT_QPA_PLATFORM=offscreen openrgb --list-devices

三、读懂你的设备列表（通用读法）

下面是本文验证机型（某 X99 主板）的输出节选，字段含义是通用的：

0: <设备名称>
  Type:        Motherboard
  Location:    HID:/dev/hidraw0
  Modes: [Direct] Off Static Breathing ...
  Zones: 'ARGB Fan Header 1' ...

Location 常见的三类通道，以及各自的注意事项：

列表里看不到设备？ 按这个顺序排查：

1. 权限：是否以 root 运行；非 root 是否安装了官方 Documentation/UdevRules.md 中的 udev 规则；
2. i2c 类主板：ls /dev/i2c-* 是否有设备节点，没有则先 sudo modprobe i2c-dev；
3. 支持情况：到项目支持设备列表核对你的型号（未支持的设备需要等上游适配）；
4. 主板固件：部分主板需要先在 BIOS／厂商软件中把灯效控制交还或关闭同步，第三方软件才能接管；
5. 万金油：重新插拔设备或重启一次再试。

一台机器上有多个设备时，用名称指定最稳妥（名称含空格要加引号）：

sudo env QT_QPA_PLATFORM=offscreen openrgb -d "设备名称" -m Off

四、常用控制命令

把 <设备> 换成上一步列表中的序号或名称（只有一个设备时通常是 0）：

# 关闭指定设备的灯光
sudo env QT_QPA_PLATFORM=offscreen openrgb -d <设备> -m Off

# 一键置零所有设备的灯珠（部分设备对「置零」与「Off 模式」反应不同，若无效改用 -m Off）
sudo env QT_QPA_PLATFORM=offscreen openrgb -z

# 设为固定颜色（RRGGBB 十六进制）
sudo env QT_QPA_PLATFORM=offscreen openrgb -d <设备> -m Static -c 00ff00

# 呼吸灯：颜色、亮度（0-100）、速度（0-100）
sudo env QT_QPA_PLATFORM=offscreen openrgb -d <设备> -m Breathing -c ff0000 -b 50 -s 10

小提示：模式名或设备名里带空格时（例如 -m "Multicolor CYCLING"、-d "某 设备"）需要加引号，否则会被当成多个参数。

执行时可能看到 Connection attempt failed 一行。这是 CLI 先尝试连接常驻服务、失败后自动转为进程内执行的正常行为，命令实际上已经生效。

五、开机自动执行

对服务器来说，「重启之后自动安静」比手动执行更重要。用一个 oneshot 服务就够了——把设备与动作换成你自己的：

# 创建开机执行的服务单元
sudo tee /etc/systemd/system/openrgb.service > /dev/null <<'EOF'
[Unit]
Description=OpenRGB - apply lighting settings at boot
After=multi-user.target

[Service]
Type=oneshot
Environment=QT_QPA_PLATFORM=offscreen
ExecStart=/usr/bin/openrgb -d 0 -m Off
User=root

[Install]
WantedBy=multi-user.target
EOF

# 启用并立即生效
sudo systemctl daemon-reload
sudo systemctl enable --now openrgb
systemctl status openrgb --no-pager

三点容易误判的地方：

• Active: inactive (dead) 搭配 Process ... status=0/SUCCESS，是 oneshot 服务正常执行完毕的状态，不是失败；
• 想改成固定颜色或呼吸灯，只需修改 ExecStart 那一行，然后 daemon-reload 并重启服务；
• 设备较多时，可以在 ExecStart 后追加多条命令，或写一个调用多次 openrgb 的脚本再让服务执行。

六、三个常见疑问

需要配置 udev 规则吗？
以 root 运行的服务不需要。只有用普通用户直接操控设备（尤其是 USB／HID 类）时，才需要按官方 Documentation/UdevRules.md 安装规则。

需要加载 i2c-dev 内核模块吗？
取决于第三节里 Location 的通道类型：i2c/SMBus 类的主板灯控需要，USB 类不需要。需要时的做法：

# 立即加载
sudo modprobe i2c-dev

# 设为开机自动加载
printf 'i2c-dev\n' | sudo tee /etc/modules-load.d/i2c-dev.conf

# 确认能看到总线
ls /dev/i2c-*

调灯会影响风扇转速吗？
不会。灯效线（如 3-pin 5V ARGB）与风扇动力线（4-pin PWM）是两套相互独立的系统：OpenRGB 只管灯，风扇转速由主板或 fancontrol 之类的工具负责，互不干扰。风扇的软件调速实践，可以接着看本站的进阶篇。

七、进阶：局域网内远程调灯（可选）

如果希望用另一台电脑上的 OpenRGB 图形界面远程调灯，可以把服务改成常驻服务器模式：

# 将服务改为 Type=simple，并把 ExecStart 换成：
# ExecStart=/usr/bin/openrgb --server

之后在同网段的机器上执行 openrgb --connect <服务器IP>，或在 GUI 中选择「连接服务器」即可（默认端口 6742）。

需要注意：该协议不带认证，请只在可信内网使用，不要直接暴露到公网。

八、清理与回滚

# 停用开机服务
sudo systemctl disable --now openrgb
sudo rm /etc/systemd/system/openrgb.service
sudo systemctl daemon-reload

# 卸载程序本体
sudo apt remove openrgb

附：踩坑记录（含本文验证硬件）

1. apt install openrgb 报「无法定位软件包」——Debian 13 官方源确实没有该包，它只在 sid/unstable 中维护；动手前先用 apt-cache policy openrgb 自查。
2. 源码编译卡在 CMakeLists.txt 不存在——OpenRGB 已迁移至 Codeberg（codeberg.org/OpenRGB/OpenRGB，由作者本人发布），GitLab 旧仓库正处于过渡状态，其 master 分支已不是可直接 cmake 的旧结构。请跟随新仓库的 Documentation/Compiling.md，或直接使用官方 .deb。
3. _apt 无法访问 .deb 文件——把安装包放在 /home 下的常见提示，apt 会自行提权读取，可忽略。
4. Failed to open serial port /dev/ttyACM0 之类的警告——通常表示「逐颗灯珠自定义（Direct 模式）」不可用，内置灯效与开关灯不受影响；不同设备给出的警告文案不同，只要设备出现在列表里并且命令生效，就不必纠结。
5. 同一台机器上灯控与风扇控互不干扰——排查灯效问题时不要怀疑风扇设置，反之亦然。
6. 本文验证环境：精粤 JGINYUE X99M GAMING D3/ARGB 主板，ARGB 由板载 USB HID 控制器（hidraw）驱动，共 5 个 ARGB 接口、16 种灯效；CPU 为 Xeon E5-2698B v3；系统 Debian 13（trixie）；OpenRGB 1.0rc3（官方 Trixie 包）。

进阶阅读

灯管灯，风管风。如果你也希望风扇不再是「一个固定转速」，而是跟着温度自动调整，可以继续阅读进阶篇：《在 Debian 13 无头服务器上用 fancontrol 做温度曲线调速》。

愿你的机箱，在夜里安静下来。