From 413e13534a12e2a583034056fb1774df08369b51 Mon Sep 17 00:00:00 2001
From: Tang Zaozao <tangzz@radxa.com>
Date: Sat, 23 May 2026 19:37:42 +0800
Subject: [PATCH] docs(dragon/q6a): add FAQ entry warning about apt upgrade
 boot failure

Add FAQ entry to Q6A FAQ page warning that running 'sudo apt upgrade'
may cause system boot failure, and recommend using Rsetup tool instead.

Source: GitHub Issue #1773 - user feedback from FAQ page

Closes: #1773
---
 docs/dragon/q6a/faq.md                        | 20 +++++++++++++++++++
 .../current/dragon/q6a/faq.md                 | 20 +++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/docs/dragon/q6a/faq.md b/docs/dragon/q6a/faq.md
index 86e1f2360..5f211d5e4 100644
--- a/docs/dragon/q6a/faq.md
+++ b/docs/dragon/q6a/faq.md
@@ -137,6 +137,26 @@ vim /usr/share/glib-2.0/schemas/org.gnome.settings-daemon.plugins.power.gschema.
 - 系统会以 `EL2` 而不是 `EL1` 启动，此时**可以**使用 KVM
 - `/dev/mtd0` 会消失，因此不能直接在板子上更新 SPI 固件
 
+## 为什么运行 `sudo apt upgrade` 后系统无法启动？
+
+直接使用 `sudo apt upgrade` 命令升级系统可能会导致更新不完全或系统异常（如无法启动）。建议使用 Rsetup 工具进行系统更新：
+
+<NewCodeBlock tip="radxa@dragon-q6a$" type="device">
+
+```bash
+sudo rsetup
+```
+
+</NewCodeBlock>
+
+进入 Rsetup 后，选择 **System** -> **System Update** 完成更新。
+
+详细信息请参考：[系统更新](../system-config/system-update)。
+
+:::warning
+如果在更新过程中断电或更新失败，系统可能无法正常启动。此时需要重新刷写系统镜像。
+:::
+
 ## 7 寸屏显示花屏如何解决？
 
 7 寸屏默认会使用 1080p 分辨率，如果屏幕不支持该分辨率会导致花屏，需要手动设置屏幕分辨率。
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/dragon/q6a/faq.md b/i18n/en/docusaurus-plugin-content-docs/current/dragon/q6a/faq.md
index c26aa7b5c..232dd7714 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/dragon/q6a/faq.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/dragon/q6a/faq.md
@@ -135,6 +135,26 @@ After enabling the hardware encoder, the following changes apply:
 - The system boots in `EL2` instead of `EL1`, and KVM **can** be used
 - `/dev/mtd0` disappears, so you cannot update the SPI firmware directly on the board
 
+## Why does the system fail to boot after running `sudo apt upgrade`?
+
+Running `sudo apt upgrade` to upgrade the system may cause incomplete updates or system abnormalities (such as failure to boot). It is recommended to use the Rsetup tool for system updates:
+
+<NewCodeBlock tip="radxa@dragon-q6a$" type="device">
+
+```bash
+sudo rsetup
+```
+
+</NewCodeBlock>
+
+In Rsetup, select **System** -> **System Update** to complete the update.
+
+For more details, please refer to: [System Update](../system-config/system-update).
+
+:::warning
+If the power is interrupted or the update fails during the process, the system may fail to boot normally. In this case, you need to re-flash the system image.
+:::
+
 ## How to Fix 7-inch Display Garbled Screen Issue?
 
 The 7-inch display defaults to 1080p resolution. If the display does not support this resolution, it will cause a garbled screen, and you need to manually set the correct screen resolution.