From a41e8d9c22cf0a385e4788e1f15726aa9822d92d Mon Sep 17 00:00:00 2001
From: axuitomo <3157269069@qq.com>
Date: Sun, 20 Sep 2026 19:52:35 +0800
Subject: [PATCH 1/2] fix(security): clear CodeQL code scanning alerts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- go/zipslip：zip/tar 解压改用 filepath.IsLocal 正向守卫（CodeQL 只识别该形式），删掉 safeArchiveTargetPath，补两个穿越用例。

- java/android/implicit-pendingintents：通知用的 PendingIntent 改为 Intent() + setClass 显式组件，并删除两个从未被读取的自定义 action。

- node_modules 里的 Capacitor 源码随 Gradle 子项目进入 Kotlin 数据库：新增 .github/codeql/codeql-config.yml 的 paths-ignore 并在 init 步骤引用。
---
 .github/codeql/codeql-config.yml              |   9 ++
 .github/workflows/codeql.yml                  |   2 +
 internal/app/update.go                        | 150 +++++++++---------
 internal/app/update_test.go                   |  73 +++++++++
 .../AndroidKeepAliveForegroundService.kt      |  10 +-
 .../cfstgui/ProbeForegroundService.kt         |  10 +-
 6 files changed, 172 insertions(+), 82 deletions(-)
 create mode 100644 .github/codeql/codeql-config.yml

diff --git a/.github/codeql/codeql-config.yml b/.github/codeql/codeql-config.yml
new file mode 100644
index 00000000..bcb0e5f2
--- /dev/null
+++ b/.github/codeql/codeql-config.yml
@@ -0,0 +1,9 @@
+# CodeQL 扫描配置。
+#
+# node_modules 里的 Capacitor Android 源码会被 Gradle 作为子项目一起编译，因此进入 Kotlin/Java
+# 数据库并被扫描，报出的是第三方代码自身的问题（java/xss、java/error-message-exposure）。
+# 依赖源码的问题交给依赖升级和 Dependabot 跟踪，不在这里重复报出。
+name: "CFST-GUI CodeQL config"
+
+paths-ignore:
+  - "node_modules/**"
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
index 64965e23..8e551b9c 100644
--- a/.github/workflows/codeql.yml
+++ b/.github/workflows/codeql.yml
@@ -110,6 +110,8 @@ jobs:
         with:
           languages: ${{ matrix.language }}
           build-mode: ${{ matrix.build-mode }}
+          # 排除 node_modules 等第三方源码，见配置文件内的说明。
+          config-file: ./.github/codeql/codeql-config.yml
 
       # Android's Gradle project lives under mobile/android and needs the generated AAR.
       - name: Build Android project for CodeQL
diff --git a/internal/app/update.go b/internal/app/update.go
index 3fc5cdce..446bc946 100644
--- a/internal/app/update.go
+++ b/internal/app/update.go
@@ -585,34 +585,40 @@ func untarRegularFiles(reader io.Reader, targetDir string) ([]string, error) {
 		if header.Size > maxArchiveEntryBytes {
 			return nil, fmt.Errorf("更新包解压超限：%s 超过单文件上限 %d MiB", header.Name, maxArchiveEntryBytes>>20)
 		}
-		targetPath, ok := safeArchiveTargetPath(targetDir, header.Name)
-		if !ok {
+		name := filepath.Clean(strings.ReplaceAll(header.Name, "\\", "/"))
+		if name == "." {
 			continue
 		}
-		if err := os.MkdirAll(filepath.Dir(targetPath), 0o755); err != nil {
-			return nil, err
-		}
-		file, err := os.OpenFile(targetPath, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, header.FileInfo().Mode())
-		if err != nil {
-			return nil, err
-		}
-		copied, copyErr := io.Copy(file, io.LimitReader(tarReader, maxArchiveEntryBytes+1))
-		closeErr := file.Close()
-		if copyErr != nil {
-			return nil, copyErr
-		}
-		if closeErr != nil {
-			return nil, closeErr
-		}
-		if copied > maxArchiveEntryBytes {
-			return nil, fmt.Errorf("更新包解压超限：%s 超过单文件上限 %d MiB", header.Name, maxArchiveEntryBytes>>20)
-		}
-		totalBytes += copied
-		if totalBytes > maxArchiveTotalBytes {
-			return nil, fmt.Errorf("更新包解压超过总大小上限 %d MiB", maxArchiveTotalBytes>>20)
-		}
-		if header.FileInfo().Mode()&0o111 != 0 || strings.Contains(strings.ToLower(filepath.Base(targetPath)), "cfst-gui") {
-			entries = append(entries, targetPath)
+		// 解压目标必须落在 targetDir 内（tar slip）。这里保持 filepath.IsLocal 正向判断：
+		// 它是 Go 官方的逃逸检查，也是安全扫描（CodeQL go/zipslip）识别为净化的形式，
+		// 改成 `if !filepath.IsLocal(name) { continue }` 会让告警重新出现。
+		if filepath.IsLocal(name) {
+			targetPath := filepath.Join(targetDir, name)
+			if err := os.MkdirAll(filepath.Dir(targetPath), 0o755); err != nil {
+				return nil, err
+			}
+			file, err := os.OpenFile(targetPath, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, header.FileInfo().Mode())
+			if err != nil {
+				return nil, err
+			}
+			copied, copyErr := io.Copy(file, io.LimitReader(tarReader, maxArchiveEntryBytes+1))
+			closeErr := file.Close()
+			if copyErr != nil {
+				return nil, copyErr
+			}
+			if closeErr != nil {
+				return nil, closeErr
+			}
+			if copied > maxArchiveEntryBytes {
+				return nil, fmt.Errorf("更新包解压超限：%s 超过单文件上限 %d MiB", header.Name, maxArchiveEntryBytes>>20)
+			}
+			totalBytes += copied
+			if totalBytes > maxArchiveTotalBytes {
+				return nil, fmt.Errorf("更新包解压超过总大小上限 %d MiB", maxArchiveTotalBytes>>20)
+			}
+			if header.FileInfo().Mode()&0o111 != 0 || strings.Contains(strings.ToLower(filepath.Base(targetPath)), "cfst-gui") {
+				entries = append(entries, targetPath)
+			}
 		}
 	}
 	return entries, nil
@@ -710,46 +716,52 @@ func unzip(sourcePath, targetDir string) error {
 		if file.UncompressedSize64 > uint64(maxArchiveEntryBytes) {
 			return fmt.Errorf("更新包解压超限：%s 超过单文件上限 %d MiB", file.Name, maxArchiveEntryBytes>>20)
 		}
-		targetPath, ok := safeArchiveTargetPath(targetDir, file.Name)
-		if !ok {
+		name := filepath.Clean(strings.ReplaceAll(file.Name, "\\", "/"))
+		if name == "." {
 			continue
 		}
-		if file.FileInfo().IsDir() {
-			if err := os.MkdirAll(targetPath, file.FileInfo().Mode()); err != nil {
+		// 解压目标必须落在 targetDir 内（zip slip）。这里保持 filepath.IsLocal 正向判断：
+		// 它是 Go 官方的逃逸检查，也是安全扫描（CodeQL go/zipslip）识别为净化的形式，
+		// 改成 `if !filepath.IsLocal(name) { continue }` 会让告警重新出现。
+		if filepath.IsLocal(name) {
+			targetPath := filepath.Join(targetDir, name)
+			if file.FileInfo().IsDir() {
+				if err := os.MkdirAll(targetPath, file.FileInfo().Mode()); err != nil {
+					return err
+				}
+				continue
+			}
+			if err := os.MkdirAll(filepath.Dir(targetPath), 0o755); err != nil {
 				return err
 			}
-			continue
-		}
-		if err := os.MkdirAll(filepath.Dir(targetPath), 0o755); err != nil {
-			return err
-		}
-		input, err := file.Open()
-		if err != nil {
-			return err
-		}
-		output, err := os.OpenFile(targetPath, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, file.FileInfo().Mode())
-		if err != nil {
-			_ = input.Close()
-			return err
-		}
-		copied, copyErr := io.Copy(output, io.LimitReader(input, maxArchiveEntryBytes+1))
-		closeInputErr := input.Close()
-		closeOutputErr := output.Close()
-		if copyErr != nil {
-			return copyErr
-		}
-		if closeInputErr != nil {
-			return closeInputErr
-		}
-		if closeOutputErr != nil {
-			return closeOutputErr
-		}
-		if copied > maxArchiveEntryBytes {
-			return fmt.Errorf("更新包解压超限：%s 超过单文件上限 %d MiB", file.Name, maxArchiveEntryBytes>>20)
-		}
-		totalBytes += copied
-		if totalBytes > maxArchiveTotalBytes {
-			return fmt.Errorf("更新包解压超过总大小上限 %d MiB", maxArchiveTotalBytes>>20)
+			input, err := file.Open()
+			if err != nil {
+				return err
+			}
+			output, err := os.OpenFile(targetPath, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, file.FileInfo().Mode())
+			if err != nil {
+				_ = input.Close()
+				return err
+			}
+			copied, copyErr := io.Copy(output, io.LimitReader(input, maxArchiveEntryBytes+1))
+			closeInputErr := input.Close()
+			closeOutputErr := output.Close()
+			if copyErr != nil {
+				return copyErr
+			}
+			if closeInputErr != nil {
+				return closeInputErr
+			}
+			if closeOutputErr != nil {
+				return closeOutputErr
+			}
+			if copied > maxArchiveEntryBytes {
+				return fmt.Errorf("更新包解压超限：%s 超过单文件上限 %d MiB", file.Name, maxArchiveEntryBytes>>20)
+			}
+			totalBytes += copied
+			if totalBytes > maxArchiveTotalBytes {
+				return fmt.Errorf("更新包解压超过总大小上限 %d MiB", maxArchiveTotalBytes>>20)
+			}
 		}
 	}
 	return nil
@@ -776,20 +788,6 @@ func findFirstAppBundle(root string) (string, error) {
 	return found, nil
 }
 
-func safeArchiveTargetPath(baseDir, name string) (string, bool) {
-	cleanName := filepath.Clean(strings.ReplaceAll(name, "\\", "/"))
-	cleanName = strings.TrimPrefix(cleanName, string(filepath.Separator))
-	if cleanName == "." || strings.HasPrefix(cleanName, "..") {
-		return "", false
-	}
-	targetPath := filepath.Join(baseDir, cleanName)
-	rel, err := filepath.Rel(baseDir, targetPath)
-	if err != nil || rel == "." || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
-		return "", false
-	}
-	return targetPath, true
-}
-
 func shellQuote(value string) string {
 	return "'" + strings.ReplaceAll(value, "'", "'\\''") + "'"
 }
diff --git a/internal/app/update_test.go b/internal/app/update_test.go
index aa28d48b..a2667b9f 100644
--- a/internal/app/update_test.go
+++ b/internal/app/update_test.go
@@ -678,6 +678,79 @@ func TestUnzipRejectsOversizedEntry(t *testing.T) {
 	}
 }
 
+func TestUnzipSkipsEscapingEntries(t *testing.T) {
+	dir := t.TempDir()
+	zipPath := filepath.Join(dir, "traversal.zip")
+	var buffer bytes.Buffer
+	writer := zip.NewWriter(&buffer)
+	for _, name := range []string{"../escaped.txt", "safe/inside.txt"} {
+		entry, err := writer.Create(name)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if _, err := entry.Write([]byte(name)); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := writer.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(zipPath, buffer.Bytes(), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	outDir := filepath.Join(dir, "out")
+	if err := unzip(zipPath, outDir); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "escaped.txt")); err == nil {
+		t.Fatal("zip entry escaped the target directory")
+	}
+	body, err := os.ReadFile(filepath.Join(outDir, "safe", "inside.txt"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(body) != "safe/inside.txt" {
+		t.Fatalf("unexpected entry content: %s", body)
+	}
+}
+
+func TestUntarSkipsEscapingEntries(t *testing.T) {
+	var buffer bytes.Buffer
+	gzipWriter := gzip.NewWriter(&buffer)
+	tarWriter := tar.NewWriter(gzipWriter)
+	for _, name := range []string{"../escaped.txt", "safe/inside.txt"} {
+		body := []byte(name)
+		if err := tarWriter.WriteHeader(&tar.Header{Name: name, Mode: 0o755, Size: int64(len(body))}); err != nil {
+			t.Fatal(err)
+		}
+		if _, err := tarWriter.Write(body); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := tarWriter.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err := gzipWriter.Close(); err != nil {
+		t.Fatal(err)
+	}
+	gzipReader, err := gzip.NewReader(bytes.NewReader(buffer.Bytes()))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer gzipReader.Close()
+	outDir := filepath.Join(t.TempDir(), "out")
+	entries, err := untarRegularFiles(gzipReader, outDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(filepath.Join(filepath.Dir(outDir), "escaped.txt")); err == nil {
+		t.Fatal("tar entry escaped the target directory")
+	}
+	if len(entries) != 1 || filepath.Base(entries[0]) != "inside.txt" {
+		t.Fatalf("unexpected extracted entries: %v", entries)
+	}
+}
+
 type roundTripFunc func(req *http.Request) (*http.Response, error)
 
 func (f roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
diff --git a/mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/AndroidKeepAliveForegroundService.kt b/mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/AndroidKeepAliveForegroundService.kt
index b212dc9e..9e702ba8 100644
--- a/mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/AndroidKeepAliveForegroundService.kt
+++ b/mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/AndroidKeepAliveForegroundService.kt
@@ -88,9 +88,13 @@ class AndroidKeepAliveForegroundService : Service() {
     }
 
     private fun openAppIntent(): PendingIntent {
-        val intent = Intent(this, MainActivity::class.java).apply {
-            action = "io.github.axuitomo.cfstgui.action.OPEN_FROM_KEEP_ALIVE"
-            addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_SINGLE_TOP)
+        // 显式 setClass 指定目标组件，避免隐式 Intent 被其他应用劫持
+        // （CodeQL java/android/implicit-pendingintents 只识别 setClass 这类显式写法）。
+        val intent = Intent()
+        intent.setClass(this, MainActivity::class.java)
+        intent.apply {
+            addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP)
+            addFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP)
         }
         return PendingIntent.getActivity(
             this,
diff --git a/mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/ProbeForegroundService.kt b/mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/ProbeForegroundService.kt
index 8be9fe21..a1992151 100644
--- a/mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/ProbeForegroundService.kt
+++ b/mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/ProbeForegroundService.kt
@@ -264,9 +264,13 @@ class ProbeForegroundService : Service() {
     }
 
     private fun openAppIntent(): PendingIntent {
-        val intent = Intent(this, MainActivity::class.java).apply {
-            action = "io.github.axuitomo.cfstgui.action.OPEN_FROM_NOTIFICATION"
-            addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_SINGLE_TOP)
+        // 显式 setClass 指定目标组件，避免隐式 Intent 被其他应用劫持
+        // （CodeQL java/android/implicit-pendingintents 只识别 setClass 这类显式写法）。
+        val intent = Intent()
+        intent.setClass(this, MainActivity::class.java)
+        intent.apply {
+            addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP)
+            addFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP)
         }
         return PendingIntent.getActivity(
             this,

From b3b367445109dd850c8aff38f4d79fec615fdd73 Mon Sep 17 00:00:00 2001
From: axuitomo <3157269069@qq.com>
Date: Sun, 20 Sep 2026 19:52:43 +0800
Subject: [PATCH 2/2] fix(android): prevent white flashes and follow the app
 theme
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 渲染进程被系统回收后由 MainActivity 重建 WebView（进程、Go runtime 与运行中的探测任务不中断）；启动窗口、窗口背景与 WebView 底色取同一颜色，frontend/index.html 的内联首帧启动画面兜住 Vue 挂载前的空档。

- 主题跟随前端配置：frontend/src/lib/surfaceTheme.ts 把解析结果写入 localStorage 并调用 SetSurfaceTheme，AndroidSurfaceTheme 缓存到 SharedPreferences，MainActivity 在 super.onCreate 之前按缓存值 setTheme，切换主题时刷新窗口与 WebView 底色。

- Android 12+ 启动窗口图标改用 @mipmap/ic_launcher；values-night 覆盖系统深色模式下的启动窗口底色。
---
 docs/mobile/android-mobile.md                 |  4 ++
 frontend/index.html                           | 46 ++++++++++++
 frontend/src/App.vue                          |  2 +
 frontend/src/lib/bridge.ts                    | 12 ++++
 frontend/src/lib/surfaceTheme.test.ts         | 58 +++++++++++++++
 frontend/src/lib/surfaceTheme.ts              | 25 +++++++
 frontend/src/main.ts                          | 11 +++
 mobile/android/app/detekt-baseline-debug.xml  |  1 +
 .../axuitomo/cfstgui/AndroidSurfaceTheme.kt   | 25 +++++++
 .../io/github/axuitomo/cfstgui/CfstPlugin.kt  | 14 ++++
 .../github/axuitomo/cfstgui/MainActivity.kt   | 71 ++++++++++++++++++-
 .../app/src/main/res/values-night/styles.xml  | 13 ++++
 .../app/src/main/res/values/colors.xml        | 13 ++++
 .../app/src/main/res/values/styles.xml        | 11 +++
 .../cfstgui/AndroidSurfaceThemeTest.kt        | 37 ++++++++++
 15 files changed, 342 insertions(+), 1 deletion(-)
 create mode 100644 frontend/src/lib/surfaceTheme.test.ts
 create mode 100644 frontend/src/lib/surfaceTheme.ts
 create mode 100644 mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/AndroidSurfaceTheme.kt
 create mode 100644 mobile/android/app/src/main/res/values-night/styles.xml
 create mode 100644 mobile/android/app/src/main/res/values/colors.xml
 create mode 100644 mobile/android/app/src/test/java/io/github/axuitomo/cfstgui/AndroidSurfaceThemeTest.kt

diff --git a/docs/mobile/android-mobile.md b/docs/mobile/android-mobile.md
index 184f6239..23239768 100644
--- a/docs/mobile/android-mobile.md
+++ b/docs/mobile/android-mobile.md
@@ -162,6 +162,10 @@ Activity 使用 `adjustResize`；前端只通过 `visualViewport` 计算键盘 i
 
 Android 原生层会关闭 theme force dark、WebView `FORCE_DARK_OFF` 和 Android 13+ algorithmic darkening，避免 WebView 或系统深色策略把按钮背景自动变淡、把按钮文字改成低对比颜色。
 
+App 长时间留在后台后，系统在内存压力下可能只回收 WebView 渲染进程而保留 app 进程（常驻前台服务会先保住 app 进程）。`MainActivity` 处理 `WebViewClient.onRenderProcessGone` 并返回 true，因为默认行为会在渲染进程被系统杀掉时终止整个 app 进程，正在运行的探测任务会被任务快照标记成 `recovery_required`。原生侧只记录状态，等 app 回到前台时再 `recreate()` Activity，由新的 Capacitor bridge 和 WebView 重新加载前端；Go runtime、运行中的任务和事件序号保持不中断。
+
+重建与冷启动期间的白色由同一底色的三层覆盖，并跟随前端主题。启动窗口底色来自启动主题的 `windowSplashScreenBackground`，它同时是 `Theme.SplashScreen` 里 `android:windowBackground` 的取值来源（`@drawable/compat_splash_screen_no_icon_background`），因此 Activity 窗口自建立起就没有白底；`recreate()` 在 resumed 状态触发，系统按 `preserveWindow` 保留窗口，间隙显示的是被保留窗口的背景而不是新启动窗口；`MainActivity.refreshSurfaceColors()` 在 `onCreate` 和主题切换时把窗口背景与 WebView 底色设为同一颜色，覆盖 index.html 首帧之前的空白。颜色取 `res/values/colors.xml` 的 `app_background`（`#F5F7FC`）与 `app_background_dark`（`#09090B`），与前端 `styles.css` 的 `--app-bg` 同步。主题的真实来源是前端配置：`frontend/src/App.vue` 每次解析出主题后调用 `frontend/src/lib/surfaceTheme.ts`，后者把模式写入 `localStorage` 供启动画面读取，并调用原生方法 `SetSurfaceTheme`；原生侧 `AndroidSurfaceTheme` 把模式缓存到 `SharedPreferences`，`MainActivity` 在 `super.onCreate` 之前用缓存值 `setTheme` 选出 `AppTheme.NoActionBarLaunch.Dark`，并在切换时立即刷新窗口与 WebView 底色，不需要重建 Activity。冷启动第一帧的系统启动窗口早于 app 代码运行、读不到前端缓存，只能跟随系统深色模式（`res/values-night/styles.xml` 提供深色版本）：`auto_system_time` 档位下与运行期一致，前端强制浅色而系统为深色时首帧仍可能偏深。Vue 包加载与启动步骤这段时间由 `frontend/index.html` 内联的首帧启动画面覆盖（App 底色 + `/favicon.png`，`localStorage` 里记录的深色主题会让它取 `#09090b`，挂载后 `frontend/src/main.ts` 淡出移除，index.html 自带 10s 兜底），桌面端 / WebUI / Android 共用。启动主题同时把 `windowSplashScreenAnimatedIcon` 设为 `@mipmap/ic_launcher`，Android 12 及以上不再显示系统通用图标；未接入 `installSplashScreen()`，Android 11 及以下启动窗口仍只显示背景色。
+
 Android 原生 select 在部分 WebView 中会显示为系统白色大面板；前端会在 Android app 环境拦截 `select` 的 pointer/touch/click 事件，改用应用内底部 picker。该 picker 支持点外关闭、滚动区域选择、Esc 关闭、禁用项和基础 `role=listbox/option` ARIA 状态。
 
 ## Notes
diff --git a/frontend/index.html b/frontend/index.html
index 41110e33..241805c2 100644
--- a/frontend/index.html
+++ b/frontend/index.html
@@ -5,10 +5,56 @@
     <link rel="icon" type="image/png" href="/favicon.png" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
     <title>CFST-GUI</title>
+    <script>
+      // 首帧启动画面与页面底色跟随上次已知主题（src/lib/surfaceTheme.ts 写入同一个 key），
+      // 避免深色主题下先闪一帧浅色；真实主题由 src/App.vue 挂载后重新应用。
+      try {
+        if (window.localStorage.getItem("cfst.surface-theme") === "dark") {
+          document.documentElement.dataset.theme = "dark";
+        }
+      } catch {
+        // 存储不可用（隐私模式等）时保持默认浅色启动画面。
+      }
+    </script>
+    <style>
+      /* 首帧启动画面：内联样式，早于打包后的 CSS/JS 生效，让 WebView 重建和冷启动的等待
+         显示为 App 底色 + 图标，而不是一帧空白。挂载后由 src/main.ts 淡出移除，
+         下方兜底超时保证引导失败时不会永久遮挡界面。 */
+      #cfst-boot {
+        position: fixed;
+        inset: 0;
+        z-index: 9999;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        background: #f5f7fc;
+        transition: opacity 0.18s ease;
+      }
+      html[data-theme="dark"] #cfst-boot {
+        background: #09090b;
+      }
+      #cfst-boot[data-hidden="true"] {
+        opacity: 0;
+      }
+      #cfst-boot img {
+        width: 64px;
+        height: 64px;
+        border-radius: 14px;
+      }
+    </style>
   </head>
 
   <body>
     <div id="app"></div>
+    <div id="cfst-boot" aria-hidden="true">
+      <img src="/favicon.png" width="64" height="64" alt="" />
+    </div>
+    <script>
+      window.setTimeout(function () {
+        var boot = document.getElementById("cfst-boot");
+        if (boot) boot.remove();
+      }, 10000);
+    </script>
     <script type="module" src="/src/main.ts"></script>
   </body>
 </html>
diff --git a/frontend/src/App.vue b/frontend/src/App.vue
index ea5ce9f1..15b687be 100644
--- a/frontend/src/App.vue
+++ b/frontend/src/App.vue
@@ -1,6 +1,7 @@
 <script setup vapor lang="ts">
 import { computed, onBeforeUnmount, onMounted, reactive, ref, watch } from "vue";
 import { WindowCenter, WindowGetSize, WindowIsMaximised, WindowMaximise, WindowSetSize, WindowUnfullscreen, WindowUnmaximise, isWailsRuntimeAvailable } from "./lib/wailsRuntime";
+import { applySurfaceTheme } from "./lib/surfaceTheme";
 import {
   backupConfigToWebDAV,
   checkForUpdates,
@@ -2331,6 +2332,7 @@ function applyThemeMode() {
   const mode = resolvedThemeMode();
   document.documentElement.dataset.theme = mode;
   document.documentElement.classList.toggle("dark", mode === "dark");
+  applySurfaceTheme(mode);
 }
 
 function scheduleThemeRefresh() {
diff --git a/frontend/src/lib/bridge.ts b/frontend/src/lib/bridge.ts
index eef266b2..6a878224 100644
--- a/frontend/src/lib/bridge.ts
+++ b/frontend/src/lib/bridge.ts
@@ -390,6 +390,7 @@ interface CapacitorCfstPlugin {
   GetAndroidRuntimeStatus?: () => Promise<unknown>;
   Init: (payload?: Record<string, unknown>) => Promise<unknown>;
   SetKeepAliveEnabled?: (payload: { enabled: boolean }) => Promise<unknown>;
+  SetSurfaceTheme?: (payload: { dark: boolean }) => Promise<unknown>;
   OpenLogDirectory: (payload: Record<string, unknown>) => Promise<unknown>;
   OpenPath: (payload: { targetPath: string }) => Promise<unknown>;
   OpenBatteryOptimizationSettings?: (payload?: Record<string, unknown>) => Promise<unknown>;
@@ -1079,6 +1080,17 @@ export async function setKeepAliveEnabled(enabled: boolean) {
   });
 }
 
+/** 把当前主题同步给 Android 原生窗口与 WebView 底色；其他运行环境直接跳过。 */
+export async function setAndroidSurfaceTheme(dark: boolean): Promise<void> {
+  if (!shouldUseNativeBridge()) {
+    return;
+  }
+  await ensureNativeBridge();
+  if (typeof cfstNative.SetSurfaceTheme === "function") {
+    await cfstNative.SetSurfaceTheme({ dark });
+  }
+}
+
 export async function openBatteryOptimizationSettings(mode = "request") {
   if (shouldUseNativeBridge()) {
     await ensureNativeBridge();
diff --git a/frontend/src/lib/surfaceTheme.test.ts b/frontend/src/lib/surfaceTheme.test.ts
new file mode 100644
index 00000000..738f4f73
--- /dev/null
+++ b/frontend/src/lib/surfaceTheme.test.ts
@@ -0,0 +1,58 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const nativeSurface = vi.hoisted(() => ({ setAndroidSurfaceTheme: vi.fn(async () => undefined) }));
+
+vi.mock("./bridge", () => ({
+  setAndroidSurfaceTheme: nativeSurface.setAndroidSurfaceTheme,
+}));
+
+function stubBrowserStorage() {
+  const store = new Map<string, string>();
+  vi.stubGlobal("window", {
+    localStorage: {
+      getItem: (key: string) => store.get(key) ?? null,
+      setItem: (key: string, value: string) => {
+        store.set(key, value);
+      },
+    },
+  });
+  return store;
+}
+
+describe("applySurfaceTheme", () => {
+  beforeEach(() => {
+    nativeSurface.setAndroidSurfaceTheme.mockClear();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.resetModules();
+  });
+
+  it("caches the resolved mode and notifies the Android surface only on change", async () => {
+    const store = stubBrowserStorage();
+    const { applySurfaceTheme } = await import("./surfaceTheme");
+
+    applySurfaceTheme("light");
+    applySurfaceTheme("light");
+
+    expect(nativeSurface.setAndroidSurfaceTheme).toHaveBeenCalledTimes(1);
+    expect(nativeSurface.setAndroidSurfaceTheme).toHaveBeenCalledWith(false);
+    expect(store.get("cfst.surface-theme")).toBe("light");
+
+    applySurfaceTheme("dark");
+
+    expect(nativeSurface.setAndroidSurfaceTheme).toHaveBeenCalledTimes(2);
+    expect(nativeSurface.setAndroidSurfaceTheme).toHaveBeenLastCalledWith(true);
+    expect(store.get("cfst.surface-theme")).toBe("dark");
+  });
+
+  it("keeps working when the page has no web storage", async () => {
+    vi.stubGlobal("window", {});
+    const { applySurfaceTheme } = await import("./surfaceTheme");
+
+    applySurfaceTheme("dark");
+
+    expect(nativeSurface.setAndroidSurfaceTheme).toHaveBeenCalledWith(true);
+  });
+});
diff --git a/frontend/src/lib/surfaceTheme.ts b/frontend/src/lib/surfaceTheme.ts
new file mode 100644
index 00000000..df9da968
--- /dev/null
+++ b/frontend/src/lib/surfaceTheme.ts
@@ -0,0 +1,25 @@
+import { setAndroidSurfaceTheme } from "./bridge";
+
+/**
+ * 把解析后的主题同步到 Vue 之外的两层界面：
+ * 1. `localStorage`：`index.html` 内联的启动画面在打包代码加载前读它，避免深色主题先闪一帧浅色；
+ * 2. Android 原生窗口与 WebView 底色（`SetSurfaceTheme`）：覆盖 WebView 重建、冷启动和 relaunch 的空档。
+ * 只记录解析结果，不参与主题判断；浏览器 / WebUI / 桌面端第 2 步静默跳过。
+ */
+const STORAGE_KEY = "cfst.surface-theme";
+export type SurfaceThemeMode = "light" | "dark";
+
+let appliedMode: SurfaceThemeMode | null = null;
+
+export function applySurfaceTheme(mode: SurfaceThemeMode): void {
+  if (mode === appliedMode) {
+    return;
+  }
+  appliedMode = mode;
+  try {
+    window.localStorage.setItem(STORAGE_KEY, mode);
+  } catch {
+    // 隐私模式等场景下存储不可用：只影响下次冷启动的首帧底色。
+  }
+  void setAndroidSurfaceTheme(mode === "dark").catch(() => undefined);
+}
diff --git a/frontend/src/main.ts b/frontend/src/main.ts
index da04ef04..a3755312 100644
--- a/frontend/src/main.ts
+++ b/frontend/src/main.ts
@@ -10,8 +10,19 @@ import "./styles.css";
 // 先定通道再挂载：Wails 宿主的运行时是导航完成后才注入的，若在就绪前挂载，首批调用会
 // 误判成没有宿主（历史上表现为桌面端右下角弹出「WebUI 请求失败 (404)」，版本号停在占位
 // 值）。通道判定只在 Wails 宿主页面上等一次运行时注入，其余页面立即挂载且不发起网络请求。
+// index.html 内联的首帧启动画面：挂载完成后淡出移除，失败时由 index.html 的兜底超时移除。
+function dismissBootScreen(): void {
+  const boot = document.getElementById("cfst-boot");
+  if (!boot) {
+    return;
+  }
+  boot.dataset.hidden = "true";
+  window.setTimeout(() => boot.remove(), 240);
+}
+
 void resolveBridgeMode()
   .catch(() => undefined)
   .then(() => {
     createVaporApp(App).use(vaporInteropPlugin).mount("#app");
+    dismissBootScreen();
   });
diff --git a/mobile/android/app/detekt-baseline-debug.xml b/mobile/android/app/detekt-baseline-debug.xml
index df7acd15..ccdd7737 100644
--- a/mobile/android/app/detekt-baseline-debug.xml
+++ b/mobile/android/app/detekt-baseline-debug.xml
@@ -27,6 +27,7 @@
     <ID>FunctionNaming:CfstPlugin.kt:CfstPlugin$@PluginMethod fun RequestNotificationPermission</ID>
     <ID>FunctionNaming:CfstPlugin.kt:CfstPlugin$@PluginMethod fun SelectPath</ID>
     <ID>FunctionNaming:CfstPlugin.kt:CfstPlugin$@PluginMethod fun SetKeepAliveEnabled</ID>
+    <ID>FunctionNaming:CfstPlugin.kt:CfstPlugin$@PluginMethod fun SetSurfaceTheme</ID>
     <ID>LongMethod:AndroidTelegramNotificationSender.kt:AndroidTelegramNotificationSender$@JvmStatic fun send: JSObject</ID>
     <ID>LongMethod:CfstPlugin.kt:CfstPlugin$@PluginMethod fun Invoke</ID>
     <ID>LongMethod:ProbeForegroundService.kt:ProbeForegroundService$override fun onStartCommand: Int</ID>
diff --git a/mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/AndroidSurfaceTheme.kt b/mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/AndroidSurfaceTheme.kt
new file mode 100644
index 00000000..31dc88e3
--- /dev/null
+++ b/mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/AndroidSurfaceTheme.kt
@@ -0,0 +1,25 @@
+package io.github.axuitomo.cfstgui
+
+import android.content.Context
+import androidx.core.content.edit
+
+/**
+ * 记住前端当前的主题（浅色 / 深色），供启动窗口主题、Activity 窗口背景和 WebView 底色复用。
+ * 主题由前端配置决定，原生只做缓存：冷启动和 WebView 重建时读缓存，保证过渡帧不闪白。
+ */
+object AndroidSurfaceTheme {
+    private const val PREFS_NAME = "cfst_android_surface_theme"
+    private const val KEY_DARK = "dark"
+
+    @JvmStatic
+    fun dark(context: Context): Boolean {
+        return context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE).getBoolean(KEY_DARK, false)
+    }
+
+    @JvmStatic
+    fun setDark(context: Context, dark: Boolean) {
+        context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE).edit {
+            putBoolean(KEY_DARK, dark)
+        }
+    }
+}
diff --git a/mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/CfstPlugin.kt b/mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/CfstPlugin.kt
index bc7f9244..ed19a522 100644
--- a/mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/CfstPlugin.kt
+++ b/mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/CfstPlugin.kt
@@ -272,6 +272,20 @@ class CfstPlugin : Plugin() {
         }
     }
 
+    @PluginMethod
+    fun SetSurfaceTheme(call: PluginCall) {
+        try {
+            val dark = call.getBoolean("dark", false) == true
+            AndroidSurfaceTheme.setDark(context, dark)
+            (activity as? MainActivity)?.refreshSurfaceColors()
+            val message = "原生窗口底色已同步当前主题。"
+            val data = AndroidPluginCommands.command("ANDROID_SURFACE_THEME_UPDATED", JSObject(), message, true)
+            call.resolve(data)
+        } catch (error: Exception) {
+            rejectWithLog(call, "SetSurfaceTheme", error)
+        }
+    }
+
     @PluginMethod
     fun OpenBatteryOptimizationSettings(call: PluginCall) {
         executor.execute {
diff --git a/mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/MainActivity.kt b/mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/MainActivity.kt
index 4d1cf935..fd91b81d 100644
--- a/mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/MainActivity.kt
+++ b/mobile/android/app/src/main/java/io/github/axuitomo/cfstgui/MainActivity.kt
@@ -2,24 +2,47 @@ package io.github.axuitomo.cfstgui
 
 import android.content.pm.ApplicationInfo
 import android.graphics.Color
+import android.graphics.drawable.ColorDrawable
 import android.os.Build
 import android.os.Bundle
+import android.util.Log
 import android.view.WindowManager
+import android.webkit.RenderProcessGoneDetail
 import android.webkit.WebSettings
 import android.webkit.WebView
 import androidx.appcompat.app.AppCompatDelegate
+import androidx.core.content.ContextCompat
 import androidx.core.view.WindowCompat
 import androidx.core.view.WindowInsetsCompat
 import com.getcapacitor.BridgeActivity
+import com.getcapacitor.WebViewListener
 import java.io.File
 
 class MainActivity : BridgeActivity() {
+    private var rendererGone = false
+    private var resumed = false
+
     override fun onCreate(savedInstanceState: Bundle?) {
         AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO)
+        // 主题必须在 super.onCreate 之前确定；真实主题来自前端配置，原生只读缓存值。
+        setTheme(launchThemeRes())
         registerPlugin(CfstPlugin::class.java)
         val webViewDebuggingEnabled = applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE != 0
         WebView.setWebContentsDebuggingEnabled(webViewDebuggingEnabled)
         super.onCreate(savedInstanceState)
+        bridge?.addWebViewListener(
+            object : WebViewListener() {
+                override fun onRenderProcessGone(webView: WebView, detail: RenderProcessGoneDetail): Boolean {
+                    // An unhandled renderer exit makes WebViewClient kill this app process, which would
+                    // abort a running probe and mark its task snapshot as recovery_required.
+                    Log.w(TAG, "WebView renderer gone (crashed=${detail.didCrash()}), scheduling WebView rebuild")
+                    rendererGone = true
+                    // Rebuild outside the WebView callback; the dead WebView is only replaced once visible.
+                    webView.post { rebuildWebViewIfNeeded() }
+                    return true
+                }
+            },
+        )
         if (webViewDebuggingEnabled) {
             WebViewDevToolsRelay.start()
         }
@@ -28,6 +51,17 @@ class MainActivity : BridgeActivity() {
         applyWebViewColorPolicy()
     }
 
+    override fun onResume() {
+        super.onResume()
+        resumed = true
+        rebuildWebViewIfNeeded()
+    }
+
+    override fun onPause() {
+        resumed = false
+        super.onPause()
+    }
+
     override fun onWindowFocusChanged(hasFocus: Boolean) {
         super.onWindowFocusChanged(hasFocus)
         if (hasFocus) {
@@ -35,6 +69,16 @@ class MainActivity : BridgeActivity() {
         }
     }
 
+    private fun rebuildWebViewIfNeeded() {
+        if (!rendererGone || !resumed || isFinishing) {
+            return
+        }
+        // The WebView whose renderer exited cannot be reused, so a new activity recreates the
+        // Capacitor bridge and WebView while this process, and the Go core running the probe, stay alive.
+        rendererGone = false
+        recreate()
+    }
+
     private fun applyAndroidWindowInsets() {
         WindowCompat.setDecorFitsSystemWindows(window, false)
         window.statusBarColor = Color.TRANSPARENT
@@ -52,7 +96,11 @@ class MainActivity : BridgeActivity() {
 
     @Suppress("DEPRECATION")
     private fun applyWebViewColorPolicy() {
-        val webSettings = bridge?.webView?.settings ?: return
+        val webView = bridge?.webView ?: return
+        // Match the app background (res/values/colors.xml) so the frames before
+        // index.html paints are not Chromium's default white.
+        refreshSurfaceColors()
+        val webSettings = webView.settings
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
             webSettings.forceDark = WebSettings.FORCE_DARK_OFF
         }
@@ -61,8 +109,29 @@ class MainActivity : BridgeActivity() {
         }
     }
 
+    /** 启动窗口主题：与缓存主题一致，避免深色主题下冷启动/relaunch 先闪一帧白色窗口。 */
+    private fun launchThemeRes(): Int {
+        return if (AndroidSurfaceTheme.dark(this)) {
+            R.style.AppTheme_NoActionBarLaunch_Dark
+        } else {
+            R.style.AppTheme_NoActionBarLaunch
+        }
+    }
+
+    /** 刷新窗口与 WebView 底色；启动流程和前端主题切换都会调用。 */
+    fun refreshSurfaceColors() {
+        val colorRes = if (AndroidSurfaceTheme.dark(this)) R.color.app_background_dark else R.color.app_background
+        val background = ContextCompat.getColor(this, colorRes)
+        window.setBackgroundDrawable(ColorDrawable(background))
+        bridge?.webView?.setBackgroundColor(background)
+    }
+
     private fun cleanupExportCache() {
         val exportDir = File(cacheDir, "export")
         exportDir.listFiles()?.forEach { it.delete() }
     }
+
+    companion object {
+        private const val TAG = "MainActivity"
+    }
 }
diff --git a/mobile/android/app/src/main/res/values-night/styles.xml b/mobile/android/app/src/main/res/values-night/styles.xml
new file mode 100644
index 00000000..9b89cc59
--- /dev/null
+++ b/mobile/android/app/src/main/res/values-night/styles.xml
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <!--
+      系统处于深色模式时，系统启动窗口（冷启动第一帧，早于 MainActivity 运行，读不到前端
+      缓存的主题）也取深色底色。运行时的窗口与 WebView 底色由 MainActivity 按缓存主题设置，
+      两者在“跟随系统”档位下一致；前端强制浅色而系统为深色时，冷启动首帧仍可能偏深。
+    -->
+    <style name="AppTheme.NoActionBarLaunch" parent="Theme.SplashScreen">
+        <item name="android:background">@drawable/splash</item>
+        <item name="windowSplashScreenBackground">@color/app_background_dark</item>
+        <item name="windowSplashScreenAnimatedIcon">@mipmap/ic_launcher</item>
+    </style>
+</resources>
diff --git a/mobile/android/app/src/main/res/values/colors.xml b/mobile/android/app/src/main/res/values/colors.xml
new file mode 100644
index 00000000..951816c7
--- /dev/null
+++ b/mobile/android/app/src/main/res/values/colors.xml
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+
+    <!--
+      App 底色，与 frontend/src/styles.css 里 app-bg 变量的取值保持一致。
+      浅色用于启动窗口、Activity 窗口和 WebView 底色，避免 WebView 重建、冷启动、
+      Activity relaunch 期间先闪一帧纯白；深色由前端主题切换时选用
+      （见 AndroidSurfaceTheme 与 AndroidSurfaceThemeTest）。
+    -->
+    <color name="app_background">#F5F7FC</color>
+    <color name="app_background_dark">#09090B</color>
+
+</resources>
diff --git a/mobile/android/app/src/main/res/values/styles.xml b/mobile/android/app/src/main/res/values/styles.xml
index ba184664..bfc52bc4 100644
--- a/mobile/android/app/src/main/res/values/styles.xml
+++ b/mobile/android/app/src/main/res/values/styles.xml
@@ -18,5 +18,16 @@
 
     <style name="AppTheme.NoActionBarLaunch" parent="Theme.SplashScreen">
         <item name="android:background">@drawable/splash</item>
+        <item name="windowSplashScreenBackground">@color/app_background</item>
+        <!-- Android 12 起启动窗口默认显示系统通用图标，这里改用应用图标；配合上面的背景色，
+             启动画面到 WebView 首帧之间不会出现白屏或陌生图标。 -->
+        <item name="windowSplashScreenAnimatedIcon">@mipmap/ic_launcher</item>
+    </style>
+
+    <!-- 深色主题（前端配置驱动）下的窗口与启动背景，由 MainActivity.setTheme 选用。
+         覆盖 windowSplashScreenBackground 同时决定 API 31 以上的启动窗口底色、
+         以及各 API 级别下 Theme.SplashScreen 的 android:windowBackground。 -->
+    <style name="AppTheme.NoActionBarLaunch.Dark" parent="AppTheme.NoActionBarLaunch">
+        <item name="windowSplashScreenBackground">@color/app_background_dark</item>
     </style>
 </resources>
diff --git a/mobile/android/app/src/test/java/io/github/axuitomo/cfstgui/AndroidSurfaceThemeTest.kt b/mobile/android/app/src/test/java/io/github/axuitomo/cfstgui/AndroidSurfaceThemeTest.kt
new file mode 100644
index 00000000..6f8ecdef
--- /dev/null
+++ b/mobile/android/app/src/test/java/io/github/axuitomo/cfstgui/AndroidSurfaceThemeTest.kt
@@ -0,0 +1,37 @@
+package io.github.axuitomo.cfstgui
+
+import android.content.Context
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.RuntimeEnvironment
+import org.robolectric.annotation.Config
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [35])
+class AndroidSurfaceThemeTest {
+    @Before
+    fun resetPreferences() {
+        RuntimeEnvironment.getApplication()
+            .getSharedPreferences("cfst_android_surface_theme", Context.MODE_PRIVATE)
+            .edit()
+            .clear()
+            .commit()
+    }
+
+    @Test
+    fun themeDefaultsToLightAndPersistsTheLastKnownValue() {
+        val context = RuntimeEnvironment.getApplication()
+
+        assertFalse(AndroidSurfaceTheme.dark(context))
+
+        AndroidSurfaceTheme.setDark(context, true)
+        assertTrue(AndroidSurfaceTheme.dark(context))
+
+        AndroidSurfaceTheme.setDark(context, false)
+        assertFalse(AndroidSurfaceTheme.dark(context))
+    }
+}