把香橙派5 Plus/Max从英文/无输入法的状态配置成一套顺手的中文环境再点上第一颗LED灯整个过程对我来说其实折腾了整整一个周末。中间踩过的坑不少但回头复盘真正需要知道的关键点其实就那几个镜像选型、语言环境、输入法以及GPIO控制方式。这篇东西我会把完整过程和踩坑记录整理出来给同样入手这块板的读者做一个参考。1. 香橙派5 Plus/Max Ubuntu 24.04的组合值不值1.1 5 Plus和5 Max的核心区别香橙派5 Plus和5 Max都是围绕瑞芯微RK3588这颗SoC设计的中高端单板计算机严格来说它们属于同一代产品线。RK3588的性能在单板机里属于第一梯队4颗Cortex-A76大核加上4颗Cortex-A55小核应付桌面办公、NAS、轻量级AI推理、视频推流等场景都绰绰有余。相比树莓派4B它的CPU多核性能有明显优势而且支持PCIe NVMe固态硬盘系统盘性能比SD卡好太多。5 Plus和5 Max的主要差异在形态和接口规划。5 Plus的板型更宽eMMC、NVMe、双路HDMI、USB 3.1这些接口齐全适合当一台正经的小主机。5 Max则把板子面积缩小了但保留NVMe插槽和丰富的显示接口更偏嵌入式部署和桌面迷你机场景。两者在GPIO排针上的物理排列有差异所以后面做LED实验时我说过一句话不要只看我文章里的引脚号一定要对照你手头板子的原理图或丝印。1.2 为什么推荐Ubuntu 24.04而不是22.04或Debian24.04是LTSLong Term Support版本官方支持周期到2029年对于一台想长期跑服务的板子来说生命周期比22.04更新内核版本也更友好。香橙派官方在5 Plus/Max的下载页面里提供了Ubuntu 24.04的桌面版镜像这意味着驱动适配基本由官方打包完成不用像用通用树莓派镜像那样去手动怼设备树、内核模块和boot参数。从实际使用的角度看Ubuntu 24.04默认带了较新的Linux 6.8内核对RK3588的GPU、NPU、PCIe、USB等都是开箱即用的状态。特别是GPIO子系统新内核已经完全切换到了chardev接口/dev/gpiochipX传统的/sys/class/gpio虽然在兼容模式下还能用但官方更推荐的libgpiod工具链在24.04里已经非常成熟。这部分我后面会详细展开。如果你手头已经有树莓派想用树莓派跑Ubuntu Server那是另一条路线但在这块RK3588板子上香橙派官方提供的24.04桌面镜像其实就是最省心的选择。Debian虽然稳定但硬件支持度不如Linux发行版官方适配得好中文环境和桌面软件也还是Ubuntu生态更齐全。2. 从下载镜像到首次开机避掉那些初学知识点2.1 镜像下载的正确路径我第一次找镜像的时候其实走了点弯路。直接去Ubuntu官网下载桌面版ISO烧录到SD卡结果插到板子上根本开不了机。原因很简单单板机不像PC那样有通用的UEFI引导它需要专用的引导固件、设备树和内核打包在一起而Ubuntu官方ISO并没有针对香橙派做适配。正确的做法是去香橙派官网的下载页面找到Orange Pi 5 Plus或Orange Pi 5 Max对应的Linux镜像选择Ubuntu 24.04桌面版直接下载官方打包好的镜像压缩包。这个镜像里已经包含了引导加载器、设备树、内核和根文件系统烧录完直接能启动。下载的时候留意两个点确认页面型号和你板子完全一致5 Plus和5 Max镜像不能互相通用。下载后校验一下文件的SHA256值官网一般都会提供校验码避免下载损坏导致启动异常。2.2 制作启动盘烧录工具我推荐balenaEtcher跨平台、操作简单Windows/Linux/macOS都有。也可以用dd命令在Linux下烧录但新手我怕选错设备号把硬盘清了所以Etcher更稳妥一点。步骤很简单准备一张16GB以上的TF卡或者直接用NVMe固态硬盘。把下载的镜像压缩包解压出.img文件有的包本身就是.img不用解压。打开Etcher选择镜像文件选择目标磁盘点击Flash。等待烧录完成然后插入香橙派接上HDMI显示器和电源开机。这里有个经验如果打算用NVMe SSD当系统盘部分镜像需要你先在TF卡上启动一次或者官方提供专门烧录到NVMe的镜像版本。我之前直接用镜像写入NVMe后无法启动后来查了官方说明才知道5 Max的NVMe启动需要特定固件和分区表。有条件的建议先TF卡跑通再考虑把系统迁移到NVMe。2.3 首次开机首次开机如果一切正常HDMI会输出桌面环境香橙派默认Ubuntu 24.04桌面大概率是XFCE或GNOME桌面看官方打包版本。默认账户通常是orangepi密码orangepi或者在你第一次启动时由系统引导界面让你设置。如果家里有路由器用网线连接板子路由器后台能看到板子的IP后续完全可以通过SSH操作。用户名和初始密码同上登录后第一件事建议先改密码passwd没有显示器时我给自己留了一条建议别用无线连第一次配置无线网络需要桌面环境或手动改配置很麻烦。直接插网线SSH连上去所有配置都能在命令行下完成。2.4 联网和基础更新连接网络后先把系统基础包更新到最新状态。这一步很关键因为官方镜像发布后可能已经有很多上游安全更新和bug修复。sudo apt update sudo apt upgrade -y升级过程中如果遇到内核更新导致重启那就先重启一次再继续。系统重启后确认一下内核版本和系统版本uname -a lsb_release -a当我看到内核和Ubuntu版本都正常时整个基础环境就算准备好了。3. 中文环境配置的完整链路语言包、字体、输入法一次到位3.2 镜像下载的正确路径续这里多插一句。国内用户下载官方镜像速度可能一般。虽然官方没有提供专用的国内镜像站但我实测通过一些高校镜像站或百度网盘可以加速不过优先还是官网下载毕竟版本和校验码有保障。后面的apt源我也会换成国内镜像来提升软件安装速度。3.1 语言包安装与locale切换系统刚装好的时候是全英文界面中文内容显示为方块或乱码。要解决这个问题第一步安装中文语言包sudo apt install -y language-pack-zh-hans language-pack-zh-hans-base如果使用的是完整桌面环境还可以安装GNOME或XFCE对应的语言包sudo apt install -y language-pack-gnome-zh-hans安装完成后设置系统默认语言sudo update-locale LANGzh_CN.UTF-8或者用更现代的localectl命令sudo localectl set-locale LANGzh_CN.UTF-8设置完后可以验证一下locale正常情况会看到LANGzh_CN.UTF-8同时LC_TIME、LC_PAPER等也会跟随变成中文格式。重启后桌面菜单、提示信息、对话框都会变成中文。唯一要注意的是如果你用SSH登录终端里的locale可能受到客户端环境变量影响。SSH登录时如果显示locale: Cannot set LC_CTYPE to default locale之类的错误说明你的SSH客户端比如Windows的PuTTY或macOS的Terminal把本地语言环境变量传过去了而服务器没有对应语言包。解决办法有两种一是安装完语言包后退出重登二是把客户端环境变量改成en_US.UTF-8或zh_CN.UTF-8保持两端一致。3.2 换国内APT软件源这一步虽然不是中文环境配置的直接组成部分但没有它后面安装字体、输入法、GPIO工具库时会非常难受。默认源是Ubuntu官方源在国内的下载速度往往只有几十KB/s一个输入法相关的包可能就要装半天。Ubuntu 24.04有一个重大变化默认的APT源配置不再是/etc/apt/sources.list文件而是改成了deb822格式的/etc/apt/sources.list.d/ubuntu.sources。很多网上教程还在让你改/etc/apt/sources.list照抄了就会发现根本没这个文件或者改了不生效。先备份原文件sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak然后用sed把官方源替换为阿里云镜像源sudo sed -i s|http://archive.ubuntu.com/ubuntu/|http://mirrors.aliyun.com/ubuntu/|g; s|http://security.ubuntu.com/ubuntu/|http://mirrors.aliyun.com/ubuntu/|g /etc/apt/sources.list.d/ubuntu.sources也可以直接用编辑器打开文件把URIs字段改成镜像地址。我习惯用清华源或阿里云源两者都稳定Types: deb URIs: http://mirrors.aliyun.com/ubuntu/ Suites: noble noble-updates noble-backports Components: main universe restricted multiverse Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg改完后执行sudo apt update如果更新过程没有报错速度也正常那后面装什么都会舒服很多。3.3 中文字体安装语言包只解决软件界面语言不解决字体显示问题。我遇到过一种典型情况界面已经是中文了但打开网页和文档中文显示成方框这叫豆腐块本质是系统里没有中文字体。解决办法很简单安装Noto CJK字体Google出品也是Ubuntu默认推荐的sudo apt install -y fonts-noto-cjk fonts-noto-cjk-extra如果嫌体积大也可以装文泉驿微米黑轻量一点但显示效果我个人觉得不如Noto系列。装了Noto CJK后GNOME/XFCE桌面还会自动从字体配置文件里识别中文字体不用再手动设置。顺便也把emoji字体装上否则有些应用里emoji显示成框sudo apt install -y fonts-noto-color-emoji字体装好后重启桌面或重新登录一次中文显示应该就正常了。3.4 输入法这是所有中文用户最关心的部分网上热词搜索里“ubuntu 24.04 shurufa”被搜得非常频繁说明输入法配置是大家普遍的痛点。我在香橙派上试了两套方案这里把经验都写出来。方案一系统自带IBus 智能拼音如果你的桌面是GNOME或Ubuntu原版桌面IBus是默认输入法框架。只需要安装拼音引擎sudo apt install -y ibus-libpinyin然后重启进入“设置 - 区域与语言 - 输入源”点击“”添加输入源搜索“Chinese”或“Intelligent Pinyin”选中文智能拼音即可。这个方案在纯净Ubuntu桌面下很顺滑。但如果是香橙派官方打包的XFCE桌面IBus的集成度不够好经常出现托盘图标不显示、切换键失灵的问题。我在5 Plus的官方XFCE镜像上就遇到过这种情况所以更推荐方案二。方案二Fcitx5推荐在香橙派上使用Fcitx5是新一代输入法框架相比IBus在轻量级桌面上更可靠配置也更直观。安装过程如下sudo apt install -y fcitx5 fcitx5-chinese-addons fcitx5-config-qt安装完成后把默认输入法框架切换为Fcitx5sudo apt install -y im-config im-config -n fcitx5这一步会修改系统输入法框架配置。然后写入环境变量编辑用户级文件~/.xprofilecat ~/.xprofile EOF export GTK_IM_MODULEfcitx export QT_IM_MODULEfcitx export XMODIFIERSimfcitx EOF重启后Fcitx5进程应该会自动启动。如果没启动可以手动执行fcitx5 -d运行配置工具fcitx5-configtool在“输入法”标签页里添加“拼音”即可。默认切换快捷键一般是CtrlSpace如果需要调整在“全局选项”里改。这里有个经验不要在没重启之前就急着添加拼音因为环境变量没生效时即使添加了拼音后续切换也可能不稳定。重启一次桌面或者重新登录一次配置才会真正吃透。3.5 时区设置中文环境还应该包括时区。如果板子后续要跑定时任务、看日志时间时区错误会带来很大困扰。我直接设置为上海时区和北京时间对齐sudo timedatectl set-timezone Asia/Shanghai验证timedatectl会看到Local time那一行变成北京时间Time zone为Asia/Shanghai这样系统日志的时间戳就和我的日常时间一致了。4. LED灯亮灭背后的GPIO原理与实操4.1 硬件准备与连接中文环境配好之后就进入硬件控制了。LED灯实验是GPIO的入门动作却能验证整套硬件链路是否跑通。需要的硬件如下香橙派5 Plus或5 Max一块面包板一块发光二极管LED一颗颜色随意电阻一颗220Ω到470Ω都可以杜邦线两条接线方式记住一个原则LED必须串联限流电阻不能直接接3.3V和GND否则电流过大LED会烧掉。我把LED的正极长脚通过电阻连接到GPIO引脚负极短脚连接到GND。这样GPIO输出高电平时LED亮输出低电平时LED灭。电阻的用处是限制通过LED的电流我一般用330Ω在3.3V电平下能把电流控制在10mA左右既足够亮又不至于损坏GPIO引脚。RK3588的GPIO引脚理论上最大灌电流/拉电流虽然能达到几十毫安但长期大电流工作肯定不是好事保守一点总没错。4.2 识别GPIO引脚别拿树莓派引脚表硬套用GPIO前第一件事是确认引脚。香橙派40针排针的物理布局和树莓派很像但GPIO功能编号完全不同。网上有很多教程直接拿树莓派的BCM引脚号来驱动香橙派这在新内核时代会非常容易出问题。正确做法是查看香橙派5 Plus/5 Max官方原理图或GPIO引脚定义表格。每个引脚会标注对应的RK3588引脚名例如GPIO1_D5、GPIO3_C1这种。这些名字的含义是GPIO1表示第一个GPIO bankGPIO0、GPIO1、GPIO2、GPIO3、GPIO4每个bank有32个引脚D表示组号A/B/C/D四组每组8个引脚5表示组内第5个引脚从0开始计数对应的数字编号计算为全局引脚号 bank * 32 组偏移 引脚序号其中A0B8C16D24。所以GPIO1_D5对应的编号就是32 24 5 61。但这个编号只是理论视角实际使用时还需要知道它落在哪个/dev/gpiochipX上。RK3588驱动的每个GPIO bank都注册为一个独立的gpiochip不同板子和镜像下chip编号可能不一样。实操中我用的是libgpiod工具篮来探测gpiodetect这会输出系统里所有的GPIO控制器gpiochip0 [gpio0] (32 lines) gpiochip1 [gpio1] (32 lines) ... gpiochip4 [gpio4] (32 lines)然后查看具体每个chip的引脚状态和当前占用情况gpioinfo gpiochip1如果你想确认某个引脚的名字可以搜索gpiofind GPIO1_D5如果没有输出说明设备树里没有给这个引脚命名那就只能对照官方引脚表在gpioinfo的输出里找到对应的line编号。我在这部分一定会提醒不同型号的香橙派同一个物理针脚对应的GPIO编号可能不一样。我文章里所有示例都假设你使用的引脚是设备树或原理图默认映射实际以你板子的官方资料为准。这是避免烧板子、避免折腾半天的黄金法条。4.3 先用命令行点亮LED安装libgpiod命令行工具和Python库sudo apt install -y gpiod python3-gpiod先尝试用gpioset直接控制。假设接线是GPIO1_D5对应的line也就是gpiochip1的第29行24 5 29sudo gpioset gpiochip1 291执行后LED应该亮起来。如果灭了试着再看一下是不是接错引脚、LED正负极接反或者限流电阻选太大。如果把291改成290LED应该灭掉。这里我想提一个和传统教程不一样的注意点较老的教程会让你用gpio export和/sys/class/gpio/gpio61/direction这样的sysfs方式但Linux 6.8内核虽然保留了sysfs接口很多官方镜像里已经默认拿掉了或提示deprecated。我不建议新接触的读者再花时间学sysfs方式直接用libgpiod是正确的方向。4.4 Python脚本控制LED闪烁命令行能控制LED后就可以写一个Python脚本来做流水灯或呼吸灯了。Ubuntu 24.04里的python3-gpiod是libgpiod v2版本API和网上一大堆v1教程完全不同这是个重要的坑。先看一个能用v2 API跑起来的闪烁脚本#!/usr/bin/env python3 import time import gpiod from gpiod.line import Direction, Value # 根据你的实际引脚修改 CHIP /dev/gpiochip1 LINE_OFFSET 29 def main(): req gpiod.request_lines( CHIP, consumerled-blink, config{ LINE_OFFSET: gpiod.LineSettings( directionDirection.OUTPUT, output_valueValue.INACTIVE, ) }, ) try: while True: req.set_value(LINE_OFFSET, Value.ACTIVE) time.sleep(0.5) req.set_value(LINE_OFFSET, Value.INACTIVE) time.sleep(0.5) except KeyboardInterrupt: pass finally: req.release() if __name__ __main__: main()把文件保存为led_blink.py然后运行sudo python3 led_blink.py如果脚本里不用sudo大概率会提示权限不足。更好的做法是把当前用户加入gpio组这样后续不用每次sudosudo usermod -aG gpio $USER newgrp gpio然后确认一下当前用户组groups退出重新登录一次再运行脚本就能不用sudo了。4.5 让LED脚本开机自启配置好一个能用的LED效果后有些人会想让它开机自动运行。我有两种推荐方式方式一用桌面环境自启配置。如果登录的是桌面环境直接创建~/.config/autostart/led_blink.desktop文件[Desktop Entry] TypeApplication NameLED Blink Exec/home/orangepi/led_blink.py X-GNOME-Autostart-enabledtrue注意给脚本加可执行权限chmod x /home/orangepi/led_blink.py这种方式适合桌面开机场景。方式二用systemd服务配合cron。如果板子是无桌面启动的我会用cron的rebootcrontab -e在文件里添加reboot /home/orangepi/led_blink.py这种方式简单直接但前提是脚本在开机时能正确访问GPIO。如果启动顺序有问题可能需要在脚本里加一个几秒的延时比如sleep(10)等GPIO子系统完全初始化后再工作。5. 我踩过的几个坑随手记下来5.1 中文显示成方块这个坑我在第一次配置时就遇到了。原因非常简单系统只装了语言包没有装中文字体。中文界面里菜单文字都是方块甚至连字体选择器都显示异常。解决方案就是前面说的fonts-noto-cjk。另外一个相似问题是在SSH终端里中文显示成乱码这个不是字体问题而是SSH客户端的编码设置问题。Windows的PuTTY需要在Window - Translation里把Remote character set改成UTF-8用MobaXterm的话默认就是UTF-8基本不用改。5.2 GPIO提示“could not open /dev/gpiochip0”这个报错是因为没有权限。有两种解决方式一是所有命令都用sudo执行二是把自己加入gpio组。使用systemd服务或cron自启时脚本的执行用户可能不是你的个人用户权限问题还会变化。如果cron脚本没有执行先检查日志/var/log/syslog看看是不是crond用户无法访问/dev/gpiochipX。更省心的方案是在cron命令里加上sudo路径或者写一个systemd服务文件指定User你的用户。5.3 Fcitx5系统托盘不显示我试过在XFCE桌面下安装好fcitx5后重启托盘里始终看不到输入法图标。排查后发现是缺少托盘插件。解决方式是确认设置了环境变量再安装fcitx5-material-color这类皮肤包或者检查是否已经启动fcitx5进程ps aux | grep fcitx5如果确实没有进程就加自动启动。XFCE的Session and Startup里添加fcitx5 -d环境变量问题也是老生常谈。有些应用启动时没有加载~/.xprofile导致GTK/QT应用无法使用输入法表现为浏览器能打字但某些原生程序里调不出拼音。这时可以在/etc/environment里也加上那三行环境变量对全局生效虽然稍显粗暴但在香橙派这种单用户设备上可接受。5.4 apt源更新报错和签名过期Ubuntu 24.04的deb822格式是很多人没适应的点。如果你照着老教程去编辑/etc/apt/sources.list可能发现文件已经不存在了或是空文件真正的内容在/etc/apt/sources.list.d/ubuntu.sources。这个问题我在另一台设备上就遇到过当时折腾了半小时才反应过来。如果换源后出现Release file is not valid yet之类的报错多半是系统时间不对。重新设置时区并同步时间sudo apt install -y systemd-timesyncd sudo timedatectl set-ntp true等时间同步完成再执行apt update就正常了。5.5 关于Max和Plus镜像不通用的问题我最后还想强调一下型号区分。Orange Pi官方对5 Plus和5 Max提供了不同的镜像包。虽然有RK3588同芯片的底子但设备树和boot分区内容不完全一样强行混用可能出现开机无显示、网口不识别或GPIO无法使用。下载镜像前一定要看清板子型号。这个坑如果踩了往往不是靠配环境能解决的最有效的办法就是重新烧录对应镜像。配置完这套环境后我对Orange Pi 5 Plus/Max的日常可用性有了实打实的判断Ubuntu 24.04的中文环境只要按locale、字体、输入法这条线走基本不会有硬伤GPIO控制则建议直接拥抱libgpiod别再学老一代sysfs写法。后面我打算继续在板子上跑一个小的物联网项目把LED控制和温度传感器结合起来让这颗LED不再只是闪烁而是真正反映环境数据。如果你也是刚入手这块板子建议先把这个最基础的链路跑通后面接传感器、接继电器时就都是在同一个模式上做扩展了。
