EEPW论坛

本文目标：在已经完成开箱和 SSH 配置的基础上，把 Debian 13 打造成一个中文友好、功能完善、空间充裕的开发桌面。

适用同学：希望让系统更好用，或者准备长期使用 Uno Q 做开发的同学。我会解释每个操作背后的原因，而不是只给命令。

---

一、升级系统：1.1 Debian 的包管理基础

Debian 使用 apt（Advanced Package Tool）作为包管理器。你经常看到的三条命令：

sudo apt update 
sudo apt upgrade 
sudo apt full-upgrade

它们做的事情各不相同：

• apt update：从软件源服务器下载最新的包列表（Packages.gz），更新本地索引。不会安装或升级任何软件。

• apt upgrade：根据更新后的索引，把已安装的包升级到最新版本。但有一个限制：如果升级需要删除其他包，它会跳过。

• apt full-upgrade：更激进的升级，允许删除旧包、安装新依赖来完成升级。相当于 apt-get dist-upgrade。

为什么需要三条都执行？

update 只是刷新索引，upgrade 做保守升级，full-upgrade 处理那些需要改变依赖关系的升级。对于开发板来说，我们通常是全新系统或接近全新，三条都执行最稳妥。

1.2 Arduino CLI 的升级

Uno Q 预装了 Arduino CLI，用于命令行编译和上传 Arduino 程序。升级方法：

# 如果你在公司网络或有代理，先设置代理 
export ARDUINO_NETWORK_PROXY=http://your-proxy:port 

# 更新板卡核心索引 
arduino-cli core update 

# 升级已安装的板卡核心 
arduino-cli core upgrade

什么是 "板卡核心"（core）？

Arduino CLI 支持多种硬件平台（AVR、ESP32、STM32 等）。每个平台都有一个 "core" 包，包含了编译器、链接器、烧录工具和板子定义。core update 只是刷新索引，core upgrade 才是真正下载新版本。

---

二、常用工具：三个实用软件的用途2.1 git —— 版本控制

如果你要写代码，git 是必须的。Debian 默认不预装 git：

sudo apt install git 
git --version

2.2 fastfetch —— 系统信息展示

fastfetch 是 neofetch 的继任者，可以在终端里显示漂亮的系统信息：

fastfetch 
# 输出类似： 
arduino@my-uno-q:~$ fastfetch
        _,met$$$$$gg.          arduino@my-uno-q
     ,g$$$$$$$$$$$$$$$P.       ----------------
   ,g$$P""       """Y$$.".     OS: Debian GNU/Linux 13 (trixie) aarch64
  ,$$P'              `$$$.     Host: Imola (1.0)
',$$P       ,ggs.     `$$b:    Kernel: Linux 7.0.0-g122c2c22d838
`d$$'     ,$P"'   .    $$$     Uptime: 8 hours, 37 mins
 $$P      d$'     ,    $$P     Packages: 1351 (dpkg)
 $$:      $$.   -    ,d$$'     Shell: bash 5.2.37
 $$;      Y$b._   _,d$P'       Cursor: Adwaita
 Y$$.    `.`"Y$$$$P"'          Terminal: /dev/pts/1
 `$$b      "-.__               CPU: qrb2210 (4) @ 2.02 GHz
  `Y$$b                        GPU: Qualcomm Turnip Adreno (TM) 702 [Integrated]
   `Y$$.                       Memory: 1.57 GiB / 3.58 GiB (44%)
     `$$b.                     Swap: 25.16 MiB / 1.79 GiB (1%)
       `Y$$b.                  Disk (/): 7.20 GiB / 9.72 GiB (74%) - ext4
         `"Y$b._               Disk (/home/arduino): 4.60 GiB / 17.89 GiB (26%) - ext4
             `""""             Local IP (wlan0): 192.168.1.198/24
                               Locale: zh_CN.UTF-8

【图片 9】fastfetch 系统信息：

这在写教程、截图分享时很有用。

2.3 rsync —— 文件同步神器

rsync 是一个增量文件传输工具，比 scp 更智能：

# 从电脑同步文件到 Uno Q 
rsync -avz --progress ./my-project/ arduino@my-uno-q.local:/home/arduino/my-project/ 

# -a：归档模式，保留权限、时间戳等 
# -v：详细输出 
# -z：传输时压缩 
# --progress：显示进度

rsync 的核心优势：只传输变化的部分。如果你同步一个 1GB 的目录，但只改了几个文件，rsync 只会传输那几个文件，而不是整个目录。

---

三、根目录空间迁移：3.1 eMMC 的分区结构

Uno Q 的 32GB eMMC 存储，实际分区如下（通过 lsblk 和 df -h 查看）：

$ lsblk 
NAME         SIZE TYPE MOUNTPOINTS 
mmcblk0     29.1G disk 
├─mmcblk0p67 512M part /boot/efi 
├─mmcblk0p68  10G part / 
└─mmcblk0p69  18G part /home/arduino

【图片 10】lsblk 分区结构截图：

注意：根目录 / 约 10GB，/home/arduino 约 18GB。Qualcomm 平台有大量小分区（bootloader、modem firmware 等）。

这个分区策略的问题在于：

• apt 的缓存和包数据在 /var/cache/apt/ 和 /var/lib/apt/

• Docker 的数据在 /var/lib/docker/

• 这些目录都在根目录下，很快就会把 10GB 占满

3.2 为什么不用 resize2fs 扩容？

理论上可以用 resize2fs 和 fdisk 重新分区，把 /home 的空间挪给根目录。但这有几个问题：

1. 风险高：调整分区需要卸载文件系统，对 eMMC 操作有风险

2. 不方便：如果以后想装 Docker、装大软件，还得再调整

3. Linux 有更好方案：用软链接（symbolic link）

3.3 软链接方案的原理

软链接类似于 Windows 的"快捷方式"，但比快捷方式更强大——应用程序完全感知不到自己在访问一个链接。

我们的策略：

1. 把 /var/lib/docker、/var/cache、/var/lib/apt 这些大目录物理移动到/home/arduino/system/ 下（这里有 22GB 空间）

2. 在原来的位置创建软链接，指向新位置

3. 系统和应用程序访问原来的路径时，实际上读写的是 /home 下的文件

# 迁移前 
/ (8GB) 
├── var/ 
│   ├── cache/      # apt 缓存 
│   ├── lib/ 
│   │   ├── apt/    # apt 包数据库 
│   │   └── docker/ # Docker 镜像和容器 

# 迁移后 
/ (8GB) 
├── var/ 
│   ├── cache -> /home/arduino/system/var/cache/      # 软链接 
│   └── lib/ 
│       ├── apt -> /home/arduino/system/var/lib/apt/   # 软链接 
│       └── docker -> /home/arduino/system/docker/     # 软链接 
/home (22GB) 
└── arduino/     
│    ├── system/         
│        ├── var/         
│           ├── cache/    # 实际数据在这里         
│           └── lib/         
│               └── apt/  # 实际数据在这里         
└──      docker/       # 实际数据在这里

3.4 具体操作步骤

# 1. 查看当前分区使用情况，确认根目录紧张 
df -h # 

2. 停止占用这些目录的服务 
sudo systemctl stop docker 
sudo systemctl stop apt-daily.service apt-daily-upgrade.service 

# 3. 创建目标目录结构 
mkdir -p /home/arduino/system/var/lib 

# 4. 迁移数据（使用 rsync 的 --remove-source-files 在确认无误后删除源文件） 
sudo rsync -av --remove-source-files /var/lib/docker/ /home/arduino/system/docker/ 
sudo rsync -av --remove-source-files /var/cache/ /home/arduino/system/var/cache/ 
sudo rsync -av --remove-source-files /var/lib/apt /home/arduino/system/var/lib/apt/ 

# 5. 清理旧的空目录 
sudo rm -rf /var/lib/docker /var/cache /var/lib/apt 

# 6. 创建软链接 
sudo ln -sf /home/arduino/system/docker /var/lib/docker 
sudo ln -sf /home/arduino/system/var/cache /var/cache 
sudo ln -sf /home/arduino/system/var/lib/apt /var/lib/apt 

# 7. 验证软链接 
ls -lh /var/lib/docker /var/cache /var/lib/apt 
# 应输出类似： 
# lrwxrwxrwx 1 root root 30 May 16 11:31 /var/cache -> /home/arduino/system/var/cache 
# lrwxrwxrwx 1 root root 32 May 16 11:32 /var/lib/apt -> /home/arduino/system/var/lib/apt 
# lrwxrwxrwx 1 root root 27 May 16 11:27 /var/lib/docker -> /home/arduino/system/docker 

# 8. 重启服务 
sudo systemctl start docker 
sudo systemctl start apt-daily.service apt-daily-upgrade.service 

# 9. 验证服务状态 
systemctl status docker 
systemctl status apt-daily.service apt-daily-upgrade.service 

# 10. 再次查看分区使用情况，根目录应该腾出大量空间 df -h

【图片 11】df -h 根目录空间查看：

3.5 注意事项

• 必须先停止服务：如果在 Docker 运行中迁移 /var/lib/docker，可能导致数据不一致

• rsync 的 trailing slash：/var/lib/docker/ 和 /var/lib/docker 有区别。带斜杠表示同步目录内容，不带斜杠表示同步目录本身。这里我们带斜杠。

• 软链接和硬链接的区别：软链接可以跨文件系统（从根目录的 ext4 到 /home 的 ext4 没问题），硬链接不行。我们用软链接是正确的选择。

---

四、中文界面：4.1 locale 是什么？

locale 决定了程序的语言、字符编码、日期格式、数字格式等。Debian 默认使用 en_US.UTF-8，这会导致：

• 终端显示中文是乱码（□□□）

• 文件管理器里中文文件名显示异常

• 某些程序默认是英文界面

4.2 配置 locale

【图片 12】locale 配置界面：dpkg-reconfigure locales 的 TUI 界面截图，显示 zh_CN.UTF-8 被选中。

sudo dpkg-reconfigure locales

在界面中：

1. 找到 zh_CN.UTF-8 UTF-8，按空格选中

2. 按 Tab 到 OK，回车

3. 选择默认 locale：zh_CN.UTF-8

为什么选 zh_CN.UTF-8 而不是 zh_CN.GBK？

UTF-8 是现代标准，支持全球所有语言字符。GBK 是中文旧标准，兼容性差。现代 Linux 发行版已经全部转向 UTF-8。

4.3 安装中文字体

光有 locale 还不够，系统中必须有中文字体才能正确显示。Debian 默认只带英文字体。

sudo apt update 

# 文泉驿字体（开源中文黑体，质量高） 
sudo apt install fonts-wqy-zenhei fonts-wqy-microhei 

# Google Noto 字体（支持中日韩，覆盖面广） 
sudo apt install fonts-noto-cjk 

# AR PL 系列（传统字体） 
sudo apt install fonts-arphic-bsmi00lp  # 中楷 
sudo apt install fonts-arphic-gbsn00lp  # 宋体

字体选择建议：

• 日常使用：文泉驿微米黑（fonts-wqy-microhei），屏幕显示效果清晰

• 编程终端：文泉驿正黑（fonts-wqy-zenhei）或等宽中文字体

• 兼容性：Noto Sans CJK（fonts-noto-cjk），Google 出品，覆盖面最全

4.4 XFCE 字体设置

【图片 13】XFCE 字体设置界面：右键桌面 -> 设置 -> 外观 -> 字体选项卡的截图。

安装字体后，需要在桌面环境中指定使用：

右键点击桌面 -> "应用程序" -> "设置" -> "外观" 
在打开的窗口中，切换到 "字体" 选项卡 
在"默认字体"下拉菜单中，选择 "文泉驿微米黑" 或 "文泉驿正黑"

提示：XFCE 的字体设置分好几项（默认字体、等宽字体、桌面字体），建议都改成中文字体，确保全局一致。

4.5 验证

【图片 14】中文界面效果：

# 终端中应该能正常显示中文了 
echo "中文测试" 

# 查看当前 locale locale 
# 应显示： #.UTF-8 # LC_ALL=zh_CN.UTF-8 # ...

---

五、HDMI 声音：5.1 Linux 音频系统的演进

Linux 音频系统经历了多次变革：

• ALSA（底层）：直接操作声卡硬件

• PulseAudio（中层）：提供软件混音、网络音频等功能

• PipeWire（新一代）：RedHat 主导，目标是统一音频和视频处理，取代 PulseAudio

Debian 13 已经默认使用 PipeWire 作为音频服务器，而 WirePlumber 是 PipeWire 的会话管理器（负责路由、策略等）。

5.2 为什么 HDMI 声音需要额外配置？

Uno Q 的 HDMI 音频输出在默认 PipeWire 配置下可能无法正常工作，原因通常是：

1. 采样率/格式不匹配：某些 HDMI 显示器只支持特定的音频格式（如 48kHz、S16LE）

2. ALSA 配置问题：底层 ALSA 驱动报告的参数和 PipeWire 默认配置不兼容

3. 缓冲区设置不当：导致音频卡顿或无声

参考 Arduino 官方论坛讨论：HDMI monitor with integrated speakers

5.3 修复方法

# 1. 安装 WirePlumber（如果未安装） 
sudo apt install wireplumber

创建配置文件：

mkdir -p ~/.config/wireplumber/wireplumber.conf.d/

创建配置文件：

参数解释：

参数含义

audio.format = "S16LE"	16 位有符号小端整数，最通用的音频格式
audio.rate = 48000	采样率 48kHz，HDMI 音频的标准采样率
api.alsa.period-size = 4096	ALSA 缓冲区周期大小，增大可减少卡顿
api.alsa.period-num = 6	周期数量，6 个周期提供足够的缓冲
api.alsa.headroom = 512	额外的预留空间
api.alsa.soft-mixer = true	启用软件混音，多应用同时播放音频
api.alsa.use-acp = true	使用 ALSA Control Plugin

# 重启 WirePlumber 使配置生效 
systemctl --user restart wireplumber 

# 验证：打开 Chromium，访问 B 站播放视频，应该有声音了

【图片 16】HDMI 音频播放验证：

5.4 如果还是没声音？

# 检查 PipeWire 是否识别了 HDMI 音频设备 
pactl list sinks 

# 检查默认输出设备 
pactl info | grep "Default Sink" 

# 手动切换默认输出到 HDMI 
pactl set-default-sink alsa_output.platform-hdmi-sound.stereo-fallback

---

六、远程桌面：6.1 为什么需要远程桌面？

虽然 SSH 已经能满足大部分需求，但有些场景需要图形界面：

• 调试 GUI 程序

• 使用 Arduino IDE 的图形界面（虽然可以用命令行，但 IDE 更方便）

• 在没有显示器的情况下操作桌面

6.2 RDP 协议简介

xrdp 是开源的 RDP（Remote Desktop Protocol）服务器，兼容 Windows 远程桌面客户端。它的工作流程：

1. 客户端（Windows 远程桌面 / macOS Microsoft Remote Desktop）通过 RDP 协议连接

2. xrdp 接收连接，进行认证

3. xorgxrdp 启动一个 Xorg 实例，作为虚拟显示驱动

4. XFCE 会话在这个虚拟显示器上运行

5. 画面通过 RDP 协议压缩传输到客户端

参考 Arduino 官方文档：UNO Q 的远程访问选项

6.3 安装与配置

# 如果之前安装过但有问题，先彻底清理 
sudo systemctl stop xrdp 
sudo apt purge xrdp xorgxrdp 
sudo rm -rf /etc/xrdp /etc/X11/xrdp/ 
sudo apt autoremove 

# 安装 xrdp 和 Xorg 驱动 
sudo apt install xrdp xorgxrdp dbus-x11 

# 开机自启 
sudo systemctl enable xrdp 

# 启动 
sudo systemctl start xrdp 

# 查看状态 
sudo systemctl status xrdp

6.4 黑屏问题排错

最常见的症状：连接后黑屏，只有鼠标指针。

原因：xrdp 默认启动的会话和 XFCE 桌面环境不兼容，通常是 DBUS_SESSION_BUS_ADDRESS 和 XDG_RUNTIME_DIR 环境变量未正确设置。

修复：

# 创建自定义的会话启动脚本 
sudo tee /etc/xrdp/startwm.sh << 'EOF' 
#!/bin/sh 
unset DBUS_SESSION_BUS_ADDRESS 
unset XDG_RUNTIME_DIR 
if [ -r /etc/profile ]; then
     . /etc/profile 
fi 
exec dbus-run-session -- xfce4-session 
EOF 

# 赋予执行权限 
sudo chmod +x /etc/xrdp/startwm.sh 

# 重启 
xrdp sudo systemctl restart xrdp

脚本解释：

• unset DBUS_SESSION_BUS_ADDRESS：清除可能存在冲突的 DBus 地址

• unset XDG_RUNTIME_DIR：清除运行时目录变量

• . /etc/profile：加载系统环境变量

• dbus-run-session -- xfce4-session：在独立的 DBus 会话中启动 XFCE

6.5 客户端连接

【图片 17】xrdp 远程桌面效果：

• Windows：搜索 "远程桌面连接"，输入 my-uno-q.local，用户名 arduino

• macOS：App Store 安装 "Windows App"

• Linux：Remmina 或 rdesktop

提示：RDP 默认使用 3389 端口。如果连接不上，检查是否成功启动：

sudo ss -tlnp | grep 3389 
# 应该显示 xrdp 在监听 0.0.0.0:3389

---

七、中文输入法：IBus + Rime

安装中文字体后，系统可以显示中文，但还无法输入中文。需要安装输入法框架。

7.1 为什么选 IBus + Rime？

Uno Q 预装 XFCE 桌面，IBus 与 XFCE 兼容性较好。当然，你也可以选择使用fcitx5，也很好用。
中文输入法引擎方面，我最喜欢Rime。Rime（中州韵）是一个高度可定制的中文输入法引擎，支持多种输入方案。

7.2 安装 IBus 和 Rime

sudo apt update 
sudo apt install ibus ibus-rime

• ibus-rime：Rime 中州韵输入法引擎（默认自带朙月拼音）

7.3 配置 IBus

1. 环境变量（创建 ~/.xprofile）：

cat > ~/.xprofile << 'EOF' 
export GTK_IM_MODULE=ibus 
export QT_IM_MODULE=ibus 
export XMODIFIERS=@im=ibus 
EOF

2. XFCE 自启动：

mkdir -p ~/.config/autostart 
cat > ~/.config/autostart/ibus.desktop << 'EOF' 
[Desktop Entry] 
Name=IBus 
Comment=Input Method Framework 
Exec=ibus-daemon -drx 
Type=Application 
Terminal=false 
EOF

3. 设置切换快捷键（避免与 macOS Spotlight 冲突）：

python3 -c "import subprocess; subprocess.run(['dconf', 'write', '/org/freedesktop/ibus/general/hotkey', \"['<Shift>space']\"])"

4. 添加输入法（运行图形配置工具）：

ibus-setup

在弹出窗口中：

• "输入法" 标签页 → 点击"添加" → 选择"汉语" → 添加"Rime"

• "常规" 标签页 → "输入法切换" → 确认快捷键为 Shift+Space

7.4 安装更多 Rime 输入方案（可选）

Rime 默认自带朙月拼音。如需更多方案（双拼、五笔、雾凇拼音等），可通过 plum 安装：

# 安装 plum（Rime 配置管理工具） 
cd ~ curl -fsSL https://git.io/rime-install | bash 

# 设置环境变量 
cat >> ~/.bashrc << 'EOF' 
export PATH=$HOME/plum:$PATH 
export rime_dir=$HOME/.config/ibus/rime 
EOF 

source ~/.bashrc 

# 安装常用方案 
rime_frontend=ibus-rime rime-install double-pinyin        # 自然码双拼 
rime_frontend=ibus-rime rime-install cubercsl/rime-flypy  # 小鹤音形 
rime_frontend=ibus-rime rime-install iDvel/rime-ice       # 雾凇拼音 
rime_frontend=ibus-rime rime-install rime/rime-luna-pinyin # 明月拼音 
rime_frontend=ibus-rime rime-install rime/rime-wubi       # 五笔86 
rime_frontend=ibus-rime rime-install hlizard/rime-wubi98  # 五笔98 
rime_frontend=ibus-rime rime-install emoji                # Emoji

配置默认方案列表：

编辑 ~/.config/ibus/rime/default.custom.yaml：

patch:
   schema_list:
        - {schema: double_pinyin}              # 双拼-自然码
        - {schema: flypy}                      # 小鹤音形
        - {schema: double_pinyin_flypy}        # 双拼-小鹤双拼
        - {schema: luna_pinyin}                # 拼音-明月拼音
        - {schema: rime_ice}                   # 拼音-雾凇拼音
        - {schema: wubi86}                     # 五笔-五笔86
        - {schema: wubi_pinyin}                # 五笔-五笔.拼音
        - {schema: wubi98}                     # 五笔-五笔98
        - {schema: wubi98_pinyin}              # 五笔-五笔98.拼音

修改后重新部署 Rime（右键托盘图标 → 重新部署，或按 F4 → 选"重新部署"）。

7.5 使用

【图片 18】IBus + Rime 输入法状态：

【图片 19】Mousepad 中文输入：

• 切换输入法：Shift + Space

• 选择输入法：右键托盘 IBus 图标 → 选择输入法

• Rime 方案选单：按 F4 或 Ctrl+~

• Rime 重新部署：修改配置后，右键托盘图标 → "重新部署"

---

八、验证清单

完成以上步骤后，建议逐项验证：

# 1. 根目录空间已释放 
df -h | grep "/$" 

# 2. locale 是中文 
locale | grep LANG 

# 3. 中文字体已安装 
fc-list | grep "WenQuanYi" 

# 4. WirePlumber 运行中 
systemctl --user status wireplumber 

# 5. xrdp 运行中 
systemctl status xrdp 

# 6. 软链接正确 
ls -la /var/lib/docker /var/cache /var/lib/apt 

# 7. IBus 输入法可用 
ibus version

全部通过？你的 Uno Q 现在是一个完整的中文开发环境了。下一篇将介绍开发工具的安装与使用。