diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..2c35003
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,73 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: Test & Build
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - name: Rust cache
+        uses: swatinem/rust-cache@v2
+        with:
+          workspaces: src-tauri -> target
+
+      - name: Install Linux dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libwebkit2gtk-4.1-dev \
+            libappindicator3-dev \
+            librsvg2-dev \
+            patchelf \
+            libssl-dev \
+            libgtk-3-dev \
+            libsoup-3.0-dev \
+            libjavascriptcoregtk-4.1-dev
+
+      - name: Rust format check
+        working-directory: src-tauri
+        run: cargo fmt --check
+
+      - name: Rust clippy
+        working-directory: src-tauri
+        run: cargo clippy --all-targets -- -D warnings
+
+      - name: Rust tests
+        working-directory: src-tauri
+        run: cargo test
+
+      - name: Install frontend dependencies
+        run: npm ci
+
+      - name: Frontend tests
+        run: npm run test:run
+
+      # 语言包重复 key 会被 JSON.parse 静默折叠，界面上直接显示裸 key，
+      # 肉眼看不出问题，只能靠脚本兜底
+      - name: i18n key integrity check
+        run: npm run check:i18n
+
+      - name: Frontend type-check & build
+        run: npm run build
diff --git a/AGENTS.md b/AGENTS.md
index 4eb1e2c..c7bab8e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -70,24 +70,24 @@
 
 ### 4. 环境恢复（RestorePage）
 - **需求覆盖**: 需求 4.1-4.10
-- **实现状态**: ✅ 完成
+- **实现状态**: ✅ 完成（端口冲突检测除外，见「待完善功能」）
 - **核心功能**:
   - 备份包预览（manifest 解析、文件统计）
   - SHA256 完整性验证
-  - 端口冲突检测与自动分配
+  - 路径遍历防护（zip-slip，恶意备份包整体拒绝）
   - 配置文件、项目文件、SQL 文件还原（SQL 导入执行待完善）
   - 进度通知与错误汇总
 
 ### 5. 基础设施模块
 - **env_parser.rs**: .env 文件可靠读写，保留注释和空行（Property 9, 10）
 - **backup_manifest.rs**: Manifest 序列化/反序列化（Property 11, 12）
-- **测试覆盖**: 后端单元测试 + 3 个集成测试（backup_restore、config_generation、workspace_commands）+ 前端 8 个组件测试（Vitest），含属性测试（proptest）
+- **测试覆盖**: 后端单元测试 + 4 个集成测试（backup_restore、config_generation、workspace_commands、docker_manager）+ 前端组件测试（Vitest）
 
 ## ✅ v0.2.0 / v0.3.0 新增功能
 
 ### 1. 前端国际化（i18n）
 - 中/英双语支持，运行时动态切换（vue-i18n）
-- 后端日志英文化
+- ⚠️ 后端用户可见日志（ui_log!）当前为中文，i18n 化待完善
 
 ### 2. 主题预设系统
 - 自动 / 明亮 / 暗黑三种模式，全组件适配
@@ -115,9 +115,9 @@
 3. **测试**: 
    - **单元测试**：放在源文件内的 `#[cfg(test)] mod tests { ... }` 模块中
    - **集成测试**：放在 `src-tauri/tests/integration/` 目录下
-   - 纯函数模块（env_parser、backup_manifest、config_generator）使用 `proptest` 进行属性测试
-   - 标签格式：`// Feature: env-config-and-backup, Property N: {property_text}`
-   - 运行测试：`cargo test`
+   - 解析/生成类纯函数应抽为可直接测试的函数，测试必须包含真断言（禁止 `assert!(true)` 占位）
+   - 安全或回归类测试建议标注：`// Feature: {feature}, Property: {描述}`
+   - 运行测试：`cargo test`；CI 同时执行 `cargo fmt --check` 与 `cargo clippy --all-targets -- -D warnings`
 4. **模块注册**: 
    - 新增引擎模块需在 `engine/mod.rs` 中声明 `pub mod xxx;`
    - 新增命令子模块需在 `commands/mod.rs` 中声明并 re-export
@@ -183,8 +183,8 @@
 - 特性：
   - 备份预览（manifest 解析）
   - SHA256 完整性验证
-  - 端口冲突检测与自动分配
-  - 配置文件、项目文件还原（数据库 SQL 导入待完善）
+  - 路径遍历防护（zip-slip）
+  - 配置文件、项目文件还原（端口冲突检测、数据库 SQL 导入待完善）
 
 ### 7. 备份清单（v0.1.0 新增）
 - 位置：`src-tauri/src/engine/backup_manifest.rs`
@@ -302,7 +302,7 @@
 3. **权限校验**: 若新增了 Tauri 插件调用，请务必更新 `src-tauri/capabilities/default.json`。
 4. **TDD 流程**: 
    - 优先编写单元测试
-   - 纯函数模块使用 proptest 进行属性测试
+   - 解析/生成类逻辑先抽纯函数再测
    - 运行 `cargo test` 确保所有测试通过
 5. **类型同步**: 修改 Rust 数据结构后，同步更新 `src/types/` 中的 TypeScript 类型定义。
 
@@ -339,6 +339,10 @@
 
 ### 待完善功能
 
+#### 恢复端口冲突检测（中优先级）
+- **当前状态**：恢复直接使用备份包中的端口，不检测宿主机端口冲突（早期文档宣称已实现，实际从未落地）
+- **待完善**：恢复预览时读取 manifest.services 的端口映射，与当前运行容器/本机占用比对，冲突时提示改端口
+
 #### 数据库备份/恢复（低优先级）
 - **目标**：完善备份/恢复引擎中的数据库导出与导入
 - **当前状态**：备份不导出数据库（`BackupOptions` 无 `include_database`），恢复仅提取 SQL 文件到本地、不执行导入
@@ -348,6 +352,10 @@
   - 事务性恢复（失败时回滚）
 - **优先级**: 低（当前版本可使用手动方式备份/恢复数据库）
 
+#### 后端日志 i18n（低优先级）
+- **当前状态**：`ui_log!` 输出的用户可见日志为中文 + emoji，英文界面下日志面板仍显示中文
+- **建议策略**：结构化字段（模块、级别）保持英文，面向用户的固定短语如需双语，由前端按 key 翻译；不做完整后端 i18n
+
 ### 开发建议
 1. **稳定优先**: v0.3.1 重点是稳定性和用户体验优化
 2. **Bug 修复**: 优先处理用户反馈的问题和边界情况
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0156438..4404d78 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,8 +10,46 @@
 ### 待发布功能
 - 虚拟主机管理（Nginx 站点配置）
 
+### 🐛 修复
+- 一键停止改用 `docker compose stop`，保留容器并展示已停用状态
+- 统一服务模板解析路径，释放后不覆盖用户修改
+- 容器状态 running 文案中文化
+- 恢复引擎拒绝含路径遍历条目的备份包，堵住 zip-slip 漏洞
+- 修复 Nginx 多版本配置回读时非默认端口被错误重置为 80 的问题
+- 修复环境配置页多 PHP 服务时自定义扩展输入互相串扰的问题
+- 修复 `scripts/` 下两个同步脚本的单元测试因 shebang 被 vitest 报 SyntaxError、整个 suite 无法加载的问题
+- 修复日志文件每次启动被清空、现场日志一重启即丢失的问题（改为轮转保留最近 3 份）
+- 修复日志锁被毒化后每次写日志连锁 panic 的问题
+- 修复备份打包大文件时整体读入内存的问题（改为 64KB 分块流式写入）
+- 修复 `path.file_name().unwrap()` 对无名路径 panic 的问题
+- 修复 Docker 不可用时仍每 5 秒全量轮询、且每轮都刷一条失败日志的问题
+- 修复日志面板「复制」按钮复制的是后端文件日志全文、与界面显示内容对不上的问题
+- 修复配置的工作区目录不存在时数据被静默写到默认目录的问题（改为先创建目录；创建失败才回退并在界面告警）
+- 修复镜像拉取命令为同步执行、下载大镜像时整个窗口「未响应」的问题（改为 async + spawn_blocking）
+- 修复 `envConfig` 语言节点下存在两个同名 `toast`、JSON 解析时后者静默覆盖前者，导致应用配置后的成功提示直接显示为裸 key（`envConfig.toast.applySuccess` / `backedUp`）的问题（合并节点，恢复被覆盖的 8 条文案）
+- 修复 Nginx 容器启动即崩溃、无限重启的问题：Dockerfile 末尾 `USER nginx` 使 master 进程无权限创建 `/var/cache/nginx/client_temp`、也无法 bind 80 端口（改为 root 运行 master，worker 仍为 `nginx`，PUID/PGID 映射不变）
+- 修复 PUID/PGID 用户映射在默认配置下从不生效的问题：判断条件写成「PUID/PGID 不等于 1000 才调整」，而默认值本身就是 1000，等于永远跳过（改为「与镜像内当前 UID/GID 不一致才调整」）
+- 修复 Nginx 镜像模板只支持 alpine 基础镜像的问题：原实现用 `deluser/adduser`，若把 `NGINX*_VERSION` 换成 debian 版（如 `nginx:1.28`）则构建直接失败；现在按基础镜像分发命令（alpine 用 `deluser/adduser`，debian 用 `groupmod/usermod`）。PHP 模板同样补齐 alpine 版兼容性
+
+### 🔧 改进
+- 环境配置页 .env 解析主体抽为纯函数并以真断言测试覆盖
+- 配置生成集成测试替换为端到端断言（validate / .env / compose / 自定义变量保留）
+- 清理死代码：未注册使用的占位命令、无效占位测试、未使用的 proptest 依赖
+- 新增 CI 测试流水线（fmt / clippy / cargo test / 前端测试 / 构建）
+- 补充 MIT LICENSE 文件，声明 Cargo `license` 字段
+- 恢复前自动生成回滚包（`.restore_rollback_<时间戳>.zip`），恢复出错可据此回退
+- 恢复结果由「成功/失败一句话」改为返回完整明细，前端展示已恢复文件列表、逐条错误与回滚包路径
+- 环境启动流程的 Docker 同步调用（`compose down`、`up` 等待、日志轮询）统一走 `spawn_blocking`，不再阻塞 async 执行线程
+- **容器状态改为前后端共享的枚举契约**（`running`/`exited`/...），替换此前 `format!("{:?}")` 产出 `"Some(RUNNING)"` 再由前端 `includes('running')` 猜测的脆弱做法
+- **路径解析收口为 `commands/paths.rs` 单一模块**；用户级配置 `workspace.json` 与日志迁至 Tauri 官方 `app_data_dir`，解决装进 `Program Files` 后无写权限的问题，首次启动自动从旧位置迁移
+- 日志面板新增「清空」与「导出」动作（导出走后端文件日志，落盘到用户指定位置）
+- 轮询间隔随 Docker 连续失败次数退避（5s → 15s → 30s），恢复后立即回到 5s
+- 容器状态灯改为仅运行中时脉冲，停止状态不再一直闪烁
+- 新增 `pnpm check:i18n` 检查脚本（`scripts/check-i18n-keys.mjs`）：扫描语言包同层级重复 key、中英 key 集合一致性、源码 `t()` 引用的 key 是否存在，并配 10 条单元测试防回归
+
 ### 📁 文档
 - 合并 `doc/` 与 `docs/` 为统一的 `docs/` 目录，更新 README、AGENTS、文档索引中的路径引用
+- 修订 AGENTS.md 与实际实现不符的描述（proptest 属性测试、恢复端口冲突检测、后端日志英文化），未实现项移入「待完善功能」
 
 ---
 
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..093a9b9
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jeeinn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/docs/IMPROVEMENT_REPORT.md b/docs/IMPROVEMENT_REPORT.md
index 51d1eab..58cdd23 100644
--- a/docs/IMPROVEMENT_REPORT.md
+++ b/docs/IMPROVEMENT_REPORT.md
@@ -3,6 +3,8 @@
 > **评审版本**: v0.3.1（2026-09-18）
 > **评审方式**: 全量阅读前端（src/，约 5600 行）与后端（src-tauri/src/，约 6600 行）核心代码，结合 CI、文档、测试的量化检查
 > **评审原则**: 一切建议服从四个指标——**简单、简洁、实用、可靠**。凡与"轻量级配置管理工具"定位冲突的"高级架构"，一律不推荐。
+>
+> **进度标记说明**（2026-09-21 更新）：每条建议标题后以 `[已完成]` / `[部分完成]` / `[未开始]` 标注当前状态；有实现偏差的条目在正文末尾附"实现偏差"说明。第二批 8 项已全部完成，详见第 6 节路线图。
 
 ---
 
@@ -34,19 +36,19 @@
 
 > 「可靠」是四个指标中当前欠账最多的一项。以下按严重程度排序。
 
-### R1.【P0·安全】恢复引擎存在 Zip-Slip 路径遍历风险
+### R1.【P0·安全】恢复引擎存在 Zip-Slip 路径遍历风险 `[已完成]`
 
 `src-tauri/src/engine/restore_engine.rs:268-287`：`extract_prefix` 将 ZIP 条目名直接 `target_dir.join(relative)` 写盘，**未校验路径是否逃逸目标目录**。恶意构造的备份包（条目名如 `../../../x` 或 Windows 绝对路径 `C:\...`）可把文件写到工作区之外的任意位置。`projects/` 前缀恢复（restore_engine.rs:174）直接解到 `project_root`，同样暴露。
 
 **修复**（约 20 行）：解压前对每个条目做 canonicalize 前缀校验——拼接后确认 `target_path` 仍在 `target_dir` 之内，并拒绝含 `..`、绝对路径、盘符的条目名。同时为 `extract_file_to_path` 补同样的防护。**配套测试**：构造恶意 ZIP 的回归测试（`test_restore_rejects_path_traversal`）。
 
-### R2.【P0·可靠】恢复会直接覆盖现有文件，且无恢复前自动备份
+### R2.【P0·可靠】恢复会直接覆盖现有文件，且无恢复前自动备份 `[已完成]`
 
 恢复流程（.env、docker-compose.yml、services/）逐文件 `fs::write` 覆盖（restore_engine.rs:111-189），中途失败则留下**半恢复状态**，用户当前可用环境被破坏且无法一键回退。对一个"迁移工具"而言这是最伤信任的故障模式。
 
 **修复**（低成本方案，不需要事务框架）：`execute_restore` 开始前，把即将被覆盖的文件打包成一份自动备份 zip（复用 BackupEngine），放在工作区 `.restore_rollback_<ts>.zip`；恢复报错时在结果中提示回滚包路径。约 30-50 行。
 
-### R3.【P1·可靠】Docker 启动流程在 async 命令中执行阻塞 IO
+### R3.【P1·可靠】Docker 启动流程在 async 命令中执行阻塞 IO `[已完成]`
 
 `src-tauri/src/commands/env_config.rs` 的 `start_environment`：
 - `down_cmd.output()`（:406）、`child.wait()`（:587）为同步阻塞调用；
@@ -56,25 +58,25 @@
 
 **修复**：把这 3 类同步 `Command` 调用包进 `tokio::task::spawn_blocking`（项目在 `commands/backup.rs:23` 已有此模式的先例，保持一致即可）。`create_backup` 里的 `spawn_blocking` + `block_on` 双层嵌套（backup.rs:23-34）可顺手简化为单层。
 
-### R4.【P1·可靠】容器状态用 `format!("{:?}")` 字符串作为前后端契约
+### R4.【P1·可靠】容器状态用 `format!("{:?}")` 字符串作为前后端契约 `[已完成]`
 
 `src-tauri/src/docker/manager.rs:57` 把 bollard 的枚举序列化成 `"Some(RUNNING)"` 这类 Debug 字符串，前端再用 `includes('running')` 猜测解析（`src/App.vue:79-83`），后端自己也写注释承认这个格式问题（manager.rs:122）。契约脆弱，Docker 升级或 bollard 版本变化即碎。
 
 **修复**：`PsContainer.state` 改为 `#[serde(rename_all="lowercase")]` 的枚举（`running/exited/paused/...`），前后端类型同步更新（`src/types/` 新增对应类型）。约 40 行，一劳永逸。
 
-### R5.【P1·可靠】备份将整个文件读入内存
+### R5.【P1·可靠】备份将整个文件读入内存 `[已完成]`
 
 `src-tauri/src/engine/backup_engine.rs:123,256`：所有文件（含可选的项目文件）先 `fs::read` 全量进内存再写 ZIP。用户勾选"包含项目文件"后，单个大文件（如数据库 dump、视频素材）即可导致内存飙升。
 
 **修复**：`add_file_to_zip` 改为 `io::copy` 流式写入（zip crate 支持 `std::io::Read` 源），SHA256 用分块读取计算。API 签名从 `&[u8]` 改为 `&Path`，约 40 行。
 
-### R6.【P2·可靠】日志文件每次启动清空，无轮转
+### R6.【P2·可靠】日志文件每次启动清空，无轮转 `[已完成]`
 
 `src-tauri/src/logging.rs:19-24` 使用 `truncate(true)`，每次启动覆盖 `php-stack.log`。用户遇到问题后重启应用，现场日志即丢失，"导出日志"命令（`commands/workspace.rs:195`）也随之失去排查价值。
 
 **修复**：保留最近 3 份按启动时间命名的日志（`php-stack.1.log` 轮转），或至少改为 append + 启动时写入分隔线。约 20 行。
 
-### R7.【P2·可靠】零散 panic 风险点
+### R7.【P2·可靠】零散 panic 风险点 `[部分完成]`
 
 - `backup_engine.rs:250`：`path.file_name().unwrap()` 对无名路径（如盘符根）会 panic；
 - `logging.rs:27,62`：`Mutex::lock().unwrap()`，另一处持锁 panic 会毒化全局日志锁；
@@ -82,13 +84,15 @@
 
 **修复**：均改为 `map_err` 降级处理，合计 15 行。
 
+**实现偏差（2026-09-21）**：三处里已修两处（`backup_engine.rs` 的 `file_name().unwrap()`、`logging.rs` 的两处 `Mutex::lock().unwrap()`），都是在 R5 / R6 的改动中顺带完成的。`version_manifest.rs` 的 `include_str!` + `expect` 未动——它是编译期嵌入的固定资源，解析失败等于打包损坏，属于"启动即崩"的正确行为，改降级反而会掩盖问题；报告本身也标注"可接受，但建议错误信息带上实际解析错误"。
+
 ---
 
 ## 2. 架构设计
 
 > 总体分层（commands → engine → docker）是清晰的，不需要推倒重来。以下是"简洁"维度的具体欠账。
 
-### A1.【P0】路径解析逻辑重复三份，且生产模式写到 exe 同级目录
+### A1.【P0】路径解析逻辑重复三份，且生产模式写到 exe 同级目录 `[已完成]`
 
 同一段"开发模式向上爬 4 层 / 生产模式取 exe 父目录"的逻辑出现在：
 - `src-tauri/src/commands/mod.rs:17-45`（`get_project_root`）
@@ -102,78 +106,86 @@
 2. 用户级配置（workspace.json、.user_*.json、日志）迁移到 Tauri 官方 `app.path().app_data_dir()`（通过 `AppHandle` 传入，不再自己爬目录）；工作区内的文件（.env、services/、备份）保持原地不动——它们本来就是"工作区"的一部分。
 3. 首次启动时检测旧位置文件并自动迁移 + 提示。
 
-### A2.【P1】.env 键名解析依赖字符串前缀切片
+**实现偏差（2026-09-21）**：本轮只迁移了 `workspace.json` 与日志文件，`.user_mirror_config.json` / `.user_version_overrides.json` **保留在项目根**。原因：这两个文件被 `backup_engine` 按项目根打包、`restore_engine` 按项目根还原，且语义上随工作区走（换工作区就该换一套覆盖）——迁到 app_data_dir 会直接打断备份/恢复闭环，收益不抵风险。若后续要做，需连同备份/恢复管道一起改，届时应作为一个独立改动统一处理。
+
+**实现方式**：`app_data_dir` 由 setup 注入一次后存入 `OnceLock`，而不是把 `AppHandle` 透传进 20 余处命令——后者会让所有命令签名膨胀，与"简单"原则冲突。未注入时回退旧逻辑，保证单元测试可用。
+
+### A2.【P1】.env 键名解析依赖字符串前缀切片 `[未开始]`
 
 `commands/env_config.rs:139-263` 的 `load_existing_config` 用 `&key[3..key.len()-8]`、`&key[6..key.len()-8]` 这类魔数切片反解 `PHP82_VERSION` / `NGINX127_HTTP_HOST_PORT`，且四个服务的解析代码高度雷同。新增服务类型或前缀规则变化时极易出错（NGINX 的"5 个字母 + 1 = 6"注释就是危险信号）。
 
 **修复**：已有 `VersionManifest::find_entry_by_env_prefix`（version_manifest.rs:76）能做前缀反查，应反向利用——遍历 manifest 中所有 `service_dir` 生成前缀去匹配 env 键，替代手写切片；四个服务的重复循环抽成一个泛型函数。约 60 行替换 120 行。
 
-### A3.【P1】前端缺少统一的 API 层
+### A3.【P1】前端缺少统一的 API 层 `[未开始]`
 
 `invoke` 直接散落在 8 个组件里，错误处理模式各不相同：EnvConfigPage 有 `formatErrorMessage`（EnvConfigPage.vue:208-236），其他页面直接 `showToast(e as string)`，Dashboard 只写日志不弹提示（App.vue:121）。`e as string` 假设后端总是返回字符串，遇到非字符串错误时会显示 `[object Object]`。
 
 **修复**：新建 `src/api/` 目录，按域封装（`docker.ts` / `envConfig.ts` / `mirror.ts` / `backup.ts`），统一做三件事：错误规范化（`String(e)` + 剥离 `PORT_CONFLICT:` 等协议前缀）、loading 注入、类型标注。组件只调用 api 函数。这是后续所有前端改进的地基，约 1 天。
 
-### A4.【P2】镜像源三个模块职责重叠
+### A4.【P2】镜像源三个模块职责重叠 `[未开始]`
 
 `mirror_manager.rs`（379 行，预设+测试）、`mirror_config.rs`（342 行，标注"向后兼容"）、`mirror_config_manager.rs`（325 行，用户配置）三者共存，"向后兼容"模块中仍有活跃逻辑。建议做一次收束：明确一个对外门面（`mirror_config_manager`），把 `mirror_config.rs` 的兼容层真正冻结或删除。非紧急，但拖越久越难拆。
 
-### A5.【P2】应用数据文件清单没有单一事实来源
+### A5.【P2】应用数据文件清单没有单一事实来源 `[未开始]`
 
 当前磁盘写入物散布：项目根（.env、docker-compose.yml、services/、data/、logs/、.user_mirror_config.json、.user_version_overrides.json）、exe 目录（workspace.json、php-stack.log）。建议在 `doc/architecture/ARCHITECTURE.md` 增加一张"应用写入了什么、在哪、谁负责"的表，并作为 A1 重构的验收依据。
 
-### A6.【P2】死代码与占位实现
+### A6.【P2】死代码与占位实现 `[已完成]`
 
 - `commands/backup.rs:79-83`：`select_project_folder` 是空占位（返回 `Ok(None)`），却注册在 invoke_handler（lib.rs:73），前端从未调用 → 删除；
 - `App.vue:53-61`：两个 `@ts-ignore` 的 computed（hasAnyContainers/hasStoppedContainers）→ 删除；
 - `App.vue:152-181`：`openServiceConfig` 四个分支执行完全相同的 `replace('ps-','')` → 合并为一行；
 - `App.vue:21-28`：`Container` 接口字段用了包装对象类型 `String` 而非 `string` → 修正。
 
+**实现偏差（2026-09-21）**：容器相关部分已在 R4 提交中一并完成——`Container` 接口改为 `src/types/docker.ts` 的强类型定义（state 为 `ContainerState` 枚举），`@ts-ignore` 的两个 computed 已删除。`openServiceConfig` 四个分支合并、`App.vue` 的 `String` 残留未动，属纯样式清理。
+
 ---
 
 ## 3. 用户体验
 
 > 界面风格统一、步骤式恢复向导、启动确认弹窗等都做得不错。以下是实际使用中会碰到的摩擦点。
 
-### U1.【P0·功能缺陷】多个 PHP 服务时自定义扩展输入互相污染
+### U1.【P0·功能缺陷】多个 PHP 服务时自定义扩展输入互相污染 `[已完成]`
 
 `src/components/EnvConfigPage.vue:32` 只有一个 `customExtInput`，而 `syncCustomExtensions(phpIndex)`（:503-521）把这个共享输入合并进任意一个 PHP 服务。用户给 php82 填了 `xdebug`，切到 php85 的面板时同一个输入框内容还在，保存时会错误地合并进去。
 
 **修复**：`customExtInput` 改为 `Record<number, string>`（项目里 `phpExtensionsPanelState` 已是同款模式，照抄即可）。约 10 行。**这是真实功能 bug，建议单独出一个 fix 提交。**
 
-### U2.【P1】恢复结果只有"成功/失败"一句话，错误明细不可读
+### U2.【P1】恢复结果只有"成功/失败"一句话，错误明细不可读 `[已完成]`
 
 后端 `execute_restore` 把多行 errors 用 `\n` 拼进 Err（commands/backup.rs:70-74），前端 `showToast(e as string)` 弹一个 3 秒的 toast（RestorePage.vue:157）——用户既看不全也来不及看。而 `RestoreResult.restored_files` 明细后端算好了却完全没展示。
 
 **修复**：`execute_restore` 改为始终返回 `RestoreResult`，前端在恢复步骤（RestorePage 第 4 步）渲染结果卡片：恢复文件列表 + 错误列表 + （配合 R2 的）回滚包路径提示。
 
-### U3.【P1】Docker 不可用时仍每 5 秒全量轮询
+### U3.【P1】Docker 不可用时仍每 5 秒全量轮询 `[已完成]`
 
 `App.vue:339` 的 `setInterval` 永不清除（且组件卸载语义上也不需要，但 Docker 不可用时依旧每 5 秒 ping + 拉列表 + 写日志），Docker Desktop 未启动时日志面板会被 `dockerCheckFailed` 每隔 5 秒刷一条。
 
 **修复**：连续失败 N 次后退避到 15-30 秒；Docker 恢复后恢复 5 秒。同时顺手把轮询间隔与"运行中"状态灯的 animate-pulse 区分开。
 
-### U4.【P1】UI 日志与文件日志是两套东西，复制按钮语义混乱
+### U4.【P1】UI 日志与文件日志是两套东西，复制按钮语义混乱 `[已完成]`
 
 日志面板显示的是内存中最近 50 条（`useToast.ts:20`，超过即丢），"复制"按钮复制的却是后端文件日志全文（`App.vue:391-398` → `export_logs`）。用户在界面上看到的错误未必复制得出来（50 条以前），复制出来的内容又和看到的对不上。另外面板没有"清空"按钮，长会话下满屏历史。
 
 **修复**：复制按钮复制 UI 日志原文；面板加"清空"与"导出文件"两个动作（导出走后端文件日志）；文件日志本身配合 R6 做轮转。
 
-### U5.【P2】i18n 收尾
+### U5.【P2】i18n 收尾 `[部分完成]`
 
 - 残留硬编码中文运行时文案：`useConfirmDialog.ts:25-27`（默认"确认操作/确认/取消"，英文界面下弹中文按钮）、`App.vue:465`（侧边栏折叠按钮 title）、`App.vue:639`（复制日志 title）；
 - 后端用户可见日志（ui_log!）全部是中文 + emoji（如 env_config.rs 全文），英文界面下日志面板是中文。AGENTS.md 宣称"后端日志英文化"并未达成。
 - **建议**：前端三处立即修；后端日志选择一个现实策略——要么承认"UI 日志面向中文用户、仅结构化字段英文"，写进文档；要么把 ui_log 的固定短语做成 key 传给前端翻译。不建议做完整后端 i18n（违背"简单"原则）。
 
-### U6.【P2】WorkspaceInitDialog 不适配亮色主题
+**实现偏差（2026-09-21）**：只完成了 `App.vue` 复制日志按钮的硬编码 title（U4 提交中顺带改掉，新增 `dashboard.log.copyTip`）。`useConfirmDialog.ts` 的默认按钮文案与侧边栏折叠 title 未动，后端日志 i18n 按报告建议**明确不做**（违背"简单"原则）——这一策略尚未写进 AGENTS.md，建议后续补。
+
+### U6.【P2】WorkspaceInitDialog 不适配亮色主题 `[未开始]`
 
 对话框写死暗色（`bg-slate-900 border-slate-700`，无 `dark:` 前缀），亮色模式下是全应用唯一的突兀深色弹窗；确认后 `window.location.reload()` 整页刷新（WorkspaceInitDialog.vue:44），丢失所有未保存状态。建议：补 `dark:` 适配；reload 改为事件通知各页面重新加载工作区信息。
 
-### U7.【P2】EnvConfigPage 内置的前端版本 fallback 列表会烂掉
+### U7.【P2】EnvConfigPage 内置的前端版本 fallback 列表会烂掉 `[未开始]`
 
 `EnvConfigPage.vue:179-203` 在后端加载失败时使用一份硬编码版本清单，与 `services/version_manifest.json` 双源维护。建议失败时显示明确错误 + 重试按钮，而不是降级到一份必然过期的静态数据（备份一段"应急可用"的体验，代价是永久的双维护）。
 
-### U8.【P2】清理调试输出与提高键盘可达性
+### U8.【P2】清理调试输出与提高键盘可达性 `[未开始]`
 
 - 22 处 `console.log`（主要集中在 EnvConfigPage 的加载流程）清理或降级为统一 debug 开关；
 - 侧边栏导航与日志按钮是 `div @click`（App.vue:417-453），无 Tab 焦点、无 Enter 触发。桌面应用要求不高，但改成 `<button>` 零成本，建议顺手做。
@@ -184,25 +196,25 @@
 
 > 原则：只做"到时候能扩展"的准备，不做"提前建好的抽象"。
 
-### E1.【P1】版本清单嵌入二进制，新增版本必须重新发版
+### E1.【P1】版本清单嵌入二进制，新增版本必须重新发版 `[未开始]`
 
 `version_manifest.rs:44` 用 `include_str!` 把 `services/version_manifest.json` 编译进二进制。PHP 8.5 / MySQL 9.x 发布时，用户必须升级整个应用才能选新版本。而项目已有的 `.user_version_overrides.json` 机制只覆盖"改镜像 tag"，覆盖不了"新增条目"。
 
 **建议**：启动时按 `app_data_dir/services/version_manifest.json`（若存在）→ 内置 fallback 的顺序加载，用户可下载新清单文件覆盖。**不**要做远程自动拉取（保持简单，避免新增网络依赖面）。约 30 行 + 文档。
 
-### E2.【P2】新增服务类型（如 PostgreSQL）的改动点清单
+### E2.【P2】新增服务类型（如 PostgreSQL）的改动点清单 `[未开始]`
 
 当前需要同步修改：Rust 侧 `config_generator::ServiceType`、`version_manifest` 的 key 匹配、`load_existing_config` 解析分支、compose 模板；前端 `ServiceType` 联合类型、EnvConfigPage 四组几乎相同的服务数组与增删函数。建议：① 把 EnvConfigPage 中 PHP/MySQL/Redis/Nginx 四组 `ref` + `add/remove` 函数收敛为一份配置驱动的通用实现（当前就是复制粘贴的，约省 200 行）；② 在 `docs/architecture/EXTENSION_GUIDE.md` 补一份"新增服务类型 checklist"。
 
-### E3.【P2】数据库备份/恢复（已知待完善项）
+### E3.【P2】数据库备份/恢复（已知待完善项） `[未开始]`
 
 AGENTS.md 已列为低优先级，建议维持，但给出实现边界以防过度设计：mysqldump 通过 bollard exec 在容器内执行、dump 到挂载目录（复用现有 volume 映射），**不要**在宿主机找 mysql client；恢复阶段只把 SQL 放入 `database/` 并提示用户确认后执行导入（与现有"恢复预览→确认"两段式一致）。进度事件复用 `backup-progress` 通道。
 
-### E4.【P2】备份包版本兼容性检查缺失
+### E4.【P2】备份包版本兼容性检查缺失 `[未开始]`
 
 manifest 有 `version: "1.0.0"` 字段（backup_manifest.rs），但 `RestoreEngine` 不校验它。未来格式升级后，旧版 app 打开新备份包会静默丢字段。**建议**：restore 预览时检查 `manifest.version` 是否在支持区间，不在则明确报"备份包版本过新/过旧，请升级应用"。约 10 行，现在做成本最低。
 
-### E5.【P1】自动更新是面向用户的最大缺口
+### E5.【P1】自动更新是面向用户的最大缺口 `[未开始]`
 
 `tauri.conf.json` 无 updater 配置，release.yml 永远 `prerelease: true`，用户发现新版本的唯一方式是手动查看仓库。对一个分发给开发者的桌面工具，建议引入 `tauri-plugin-updater` + 签名密钥（GitHub Releases 作为源）。这是本报告唯一建议新增的重型功能，因为它直接决定用户能否留在新版本上。若暂不做，至少把 release 的 prerelease 改为正式版 + 在应用"关于"里放检查更新链接（shell open 即可，一天内完成）。
 
@@ -210,11 +222,11 @@ manifest 有 `version: "1.0.0"` 字段（backup_manifest.rs），但 `RestoreEng
 
 ## 5. 工程质量与文档
 
-### Q1.【P0】没有 CI 测试流水线
+### Q1.【P0】没有 CI 测试流水线 `[已完成]`
 
 `.github/workflows/` 只有 release.yml（tag 触发）。当前 85 + 60 个测试全部依赖本地手动运行，"cargo test 通过"没有任何机器保证。**建议新增 `ci.yml`**：push/PR 触发，跑 `cargo fmt --check`、`cargo clippy -- -D warnings`、`cargo test`、`npm run test:run`、`npm run build`（Windows 单平台即可，成本可控）。这是所有其他质量工作的前提，约半天。
 
-### Q2.【P0】文档与事实脱节（可信度问题）
+### Q2.【P0】文档与事实脱节（可信度问题） `[已完成]`
 
 AI/新人依赖的 AGENTS.md 存在多处失实：
 - "proptest 属性测试"——实际 0 处使用（依赖还挂在 Cargo.toml dev-deps 里，要么删依赖要么删描述）；
@@ -224,23 +236,23 @@ AI/新人依赖的 AGENTS.md 存在多处失实：
 
 **建议**：以本次评审为准修订 AGENTS.md（把未实现项移入"待完善"），CHANGELOG 补记 2026-09 的三笔修复（compose stop 保留容器、模板路径、i18n 文案）；`docs/README.md` 版本头已于 2026-09-20 doc/→docs/ 目录合并时更新至 v0.3.1。**规则化**：以后每个 fix 提交同时更新 CHANGELOG 的 Unreleased 段。
 
-### Q3.【P1】LICENSE 缺失
+### Q3.【P1】LICENSE 缺失 `[已完成]`
 
 README 底部链接 `[MIT](LICENSE)`，但文件不存在。要么补 MIT 全文（推荐，README 与 Cargo.toml license 字段都写了 MIT），要么改掉链接。
 
-### Q4.【P1】无效测试要删掉
+### Q4.【P1】无效测试要删掉 `[已完成]`
 
 `commands/env_config.rs:854-928` 的三个"测试"创建临时文件后又删除，**没有任何断言**（注释自己承认"无法直接测试"）。它们制造了测试通过的假象。处理：把 `load_existing_config` 的解析主体抽成 `fn parse_env_to_config(env_map, manifest) -> Vec<ServiceEntry>` 纯函数，这三个用例改为对纯函数的真断言（数据都是现成的）。
 
-### Q5.【P2】补充 lint 基建
+### Q5.【P2】补充 lint 基建 `[未开始]`
 
 无 eslint/prettier。建议加 `eslint` + `eslint-plugin-vue`（flat config）+ prettier，规则从宽（不做风格洁癖），仅拦截未用变量、明显的 hook 误用。Rust 侧 clippy 已清理过（f2c3 提交），纳入 CI 即可维持。
 
-### Q6.【P2】CSP 为 null
+### Q6.【P2】CSP 为 null `[未开始]`
 
 `tauri.conf.json:26`。桌面应用风险低于 Web，但前端只加载本地资源，配一条最小 CSP（`default-src 'self'` + style 允许 inline）成本半小时，堵住供应链类注入的口子。
 
-### Q7.【P2】两个大组件的拆分（渐进式，不强制）
+### Q7.【P2】两个大组件的拆分（渐进式，不强制） `[未开始]`
 
 `EnvConfigPage.vue`（1102 行）与 `App.vue`（812 行）已到可维护性边界。建议在下次功能迭代触碰它们时顺手拆：EnvConfigPage → 按服务类型拆 4 个子组件 + 1 个 composable；App.vue → Dashboard 视图 + 侧边栏 + 日志面板各自成组件，全局状态收敛到 `composables/useDocker.ts`（模式与 useToast 一致，不需要引 pinia）。**不建议**为此专门发起重构分支。
 
@@ -252,39 +264,43 @@ README 底部链接 `[MIT](LICENSE)`，但文件不存在。要么补 MIT 全文
 
 ### 第一批：止血（0.5~1 天，建议单独分支 `fix/reliability-basics`）
 
-| # | 事项 | 对应条目 | 预估 |
-|---|---|---|---|
-| 1 | 修复 zip-slip + 恶意包回归测试 | R1 | 2h |
-| 2 | 新增 ci.yml（fmt/clippy/test/vitest/build） | Q1 | 2h |
-| 3 | 补 LICENSE 文件 | Q3 | 5min |
-| 4 | 修订 AGENTS.md、CHANGELOG（docs/README.md 版本头已随目录合并更新） | Q2 | 1h |
-| 5 | 删除死代码（select_project_folder、@ts-ignore computed、无效测试转为真测试） | A6、Q4 | 2h |
-| 6 | 修复多 PHP 服务自定义扩展串扰 | U1 | 0.5h |
+| # | 事项 | 对应条目 | 预估 | 状态 |
+|---|---|---|---|---|
+| 1 | 修复 zip-slip + 恶意包回归测试 | R1 | 2h | ✅ 已完成 |
+| 2 | 新增 ci.yml（fmt/clippy/test/vitest/build） | Q1 | 2h | ✅ 已完成 |
+| 3 | 补 LICENSE 文件 | Q3 | 5min | ✅ 已完成 |
+| 4 | 修订 AGENTS.md、CHANGELOG（docs/README.md 版本头已随目录合并更新） | Q2 | 1h | ✅ 已完成 |
+| 5 | 删除死代码（select_project_folder、@ts-ignore computed、无效测试转为真测试） | A6、Q4 | 2h | ✅ 已完成 |
+| 6 | 修复多 PHP 服务自定义扩展串扰 | U1 | 0.5h | ✅ 已完成 |
+
+> 第一批 6 项已全部完成（2026-09-21 核对）。A6 中 `openServiceConfig` 四分支合并、App.vue 残留 `String` 未做，属纯样式清理，不影响功能。
 
 ### 第二批：可靠与体验（2~3 天）
 
-| # | 事项 | 对应条目 | 预估 |
-|---|---|---|---|
-| 1 | 恢复前自动备份（回滚包） | R2 | 2h |
-| 2 | 恢复结果页展示明细 + 错误列表 | U2 | 2h |
-| 3 | Docker 阻塞调用包 spawn_blocking | R3 | 2h |
-| 4 | 容器状态枚举化（前后端契约） | R4 | 3h |
-| 5 | 路径解析统一 + 用户配置迁至 app_data_dir | A1 | 4h |
-| 6 | 备份流式写入 | R5 | 3h |
-| 7 | 日志轮转 + UI 日志复制/清空/导出 | R6、U4 | 2h |
-| 8 | Docker 不可用轮询退避 | U3 | 1h |
+| # | 事项 | 对应条目 | 预估 | 状态 |
+|---|---|---|---|---|
+| 1 | 恢复前自动备份（回滚包） | R2 | 2h | ✅ 已完成 |
+| 2 | 恢复结果页展示明细 + 错误列表 | U2 | 2h | ✅ 已完成 |
+| 3 | Docker 阻塞调用包 spawn_blocking | R3 | 2h | ✅ 已完成 |
+| 4 | 容器状态枚举化（前后端契约） | R4 | 3h | ✅ 已完成 |
+| 5 | 路径解析统一 + 用户配置迁至 app_data_dir | A1 | 4h | ✅ 已完成（有偏差，见 A1 条目） |
+| 6 | 备份流式写入 | R5 | 3h | ✅ 已完成 |
+| 7 | 日志轮转 + UI 日志复制/清空/导出 | R6、U4 | 2h | ✅ 已完成 |
+| 8 | Docker 不可用轮询退避 | U3 | 1h | ✅ 已完成 |
+
+> 第二批 8 项已全部完成（2026-09-21）。R3 中"顺手简化 `create_backup` 的 spawn_blocking + block_on 双层嵌套"**未做**——那是为了绕开 `BackupEngine` 返回非 Send future 的约束，改成单层 `tokio::spawn` 会直接编译失败，收益不抵风险。
 
 ### 第三批：扩展与打磨（按需排期）
 
-| # | 事项 | 对应条目 |
-|---|---|---|
-| 1 | 自动更新（tauri-plugin-updater 或最低配"检查更新"） | E5 |
-| 2 | 版本清单外部覆盖 | E1 |
-| 3 | manifest 版本兼容检查 | E4 |
-| 4 | .env 解析去魔数切片 | A2 |
-| 5 | 前端 api 层 + EnvConfigPage 服务面板配置化 | A3、E2 |
-| 6 | i18n 收尾 + 主题适配收尾 + lint 基建 + CSP | U5、U6、Q5、Q6 |
-| 7 | mysqldump / SQL 导入（维持低优先级） | E3 |
+| # | 事项 | 对应条目 | 状态 |
+|---|---|---|---|
+| 1 | 自动更新（tauri-plugin-updater 或最低配"检查更新"） | E5 | ⬜ 未开始 |
+| 2 | 版本清单外部覆盖 | E1 | ⬜ 未开始 |
+| 3 | manifest 版本兼容检查 | E4 | ⬜ 未开始 |
+| 4 | .env 解析去魔数切片 | A2 | ⬜ 未开始 |
+| 5 | 前端 api 层 + EnvConfigPage 服务面板配置化 | A3、E2 | ⬜ 未开始 |
+| 6 | i18n 收尾 + 主题适配收尾 + lint 基建 + CSP | U5、U6、Q5、Q6 | ⬜ 未开始（U5 部分完成） |
+| 7 | mysqldump / SQL 导入（维持低优先级） | E3 | ⬜ 未开始 |
 
 ### 验收标准（每批公共）
 
diff --git a/package.json b/package.json
index feea367..c602e30 100644
--- a/package.json
+++ b/package.json
@@ -15,7 +15,8 @@
     "sync:dockerfile": "node scripts/sync-php-dockerfile.mjs",
     "check:dockerfile": "node scripts/sync-php-dockerfile.mjs --check",
     "sync:manifest": "node scripts/sync-version-manifest.mjs --apply",
-    "check:manifest": "node scripts/sync-version-manifest.mjs --check"
+    "check:manifest": "node scripts/sync-version-manifest.mjs --check",
+    "check:i18n": "node scripts/check-i18n-keys.mjs"
   },
   "dependencies": {
     "@tauri-apps/api": "^2.10.1",
diff --git a/scripts/__tests__/check-i18n-keys.spec.mjs b/scripts/__tests__/check-i18n-keys.spec.mjs
new file mode 100644
index 0000000..da5cb06
--- /dev/null
+++ b/scripts/__tests__/check-i18n-keys.spec.mjs
@@ -0,0 +1,128 @@
+// @vitest-environment node
+/**
+ * check-i18n-keys.mjs 的单元测试。
+ *
+ * 核心是防回归：envConfig 下曾出现两个同名 "toast" 节点，JSON.parse 静默保留
+ * 后者，导致 applySuccess / backedUp / startSuccess 等 8 条文案整体消失，
+ * 界面直接显示裸 key "envConfig.toast.applySuccess"。
+ *
+ * 三类断言：
+ *  1. 解析层：scanDuplicateKeys 能在 JSON.parse 之前抓出同层级重复 key，
+ *     且能给出祖先路径（否则报告里只有一个 "toast"，无法定位）
+ *  2. 契约层：真实语言包无重复 key、zh-CN/en key 集合一致、源码引用的
+ *     key 全部存在
+ *  3. 工具层：extractUsedKeys 只取静态字面量，动态 key 不误报
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+
+import {
+  LOCALE_FILES,
+  scanDuplicateKeys,
+  collectLeafPaths,
+  extractUsedKeys,
+  diffKeys,
+  collectSourceFiles,
+  runCheck,
+} from '../check-i18n-keys.mjs';
+
+describe('scanDuplicateKeys', () => {
+  it('抓出同父节点下的重复 key，并给出祖先路径', () => {
+    // 必须手写 JSON 文本：JSON.stringify(obj) 在构造对象阶段就已经把重复 key 合并了，
+    // 拿它当输入永远测不出问题
+    const raw = `{
+  "envConfig": {
+    "toast": { "applySuccess": "a" },
+    "pullConfirm": { "title": "t" },
+    "toast": { "pullAllSuccess": "b" }
+  }
+}`;
+
+    const dups = scanDuplicateKeys(raw);
+    expect(dups).toHaveLength(1);
+    expect(dups[0].key).toBe('toast');
+    expect(dups[0].path).toEqual(['envConfig']);
+  });
+
+  it('不同父节点下的同名 key 不算重复', () => {
+    const raw = JSON.stringify(
+      {
+        a: { toast: { x: 1 } },
+        b: { toast: { y: 2 } },
+      },
+      null,
+      2,
+    );
+    expect(scanDuplicateKeys(raw)).toEqual([]);
+  });
+
+  it('值里出现冒号不会被误判成 key', () => {
+    const raw = '{"a": "时间 12:30", "a2": {"b": "x: y"}}';
+    expect(scanDuplicateKeys(raw)).toEqual([]);
+  });
+});
+
+describe('extractUsedKeys', () => {
+  it('提取 t() / $t() 的静态字面量 key', () => {
+    const src = `
+      t('envConfig.toast.applySuccess', { location: x });
+      $t("common.cancel");
+      t('envConfig.toast.backedUp', { count: 1, files: 'a' });
+    `;
+    const keys = extractUsedKeys(src);
+    expect(keys.has('envConfig.toast.applySuccess')).toBe(true);
+    expect(keys.has('common.cancel')).toBe(true);
+    expect(keys.has('envConfig.toast.backedUp')).toBe(true);
+  });
+
+  it('动态 key（模板字符串/变量）不提取，避免误报', () => {
+    const src = "t(`envConfig.${name}`); t(key);";
+    expect([...extractUsedKeys(src)]).toEqual([]);
+  });
+});
+
+describe('diffKeys', () => {
+  it('给出双向差集', () => {
+    const r = diffKeys(new Set(['a', 'b']), new Set(['b', 'c']));
+    expect(r.onlyInA).toEqual(['a']);
+    expect(r.onlyInB).toEqual(['c']);
+  });
+});
+
+describe('真实语言包契约', () => {
+  it('zh-CN / en 均无同层级重复 key', () => {
+    for (const [name, file] of Object.entries(LOCALE_FILES)) {
+      expect(scanDuplicateKeys(readFileSync(file, 'utf8')), `${name} 存在重复 key`).toEqual([]);
+    }
+  });
+
+  it('zh-CN 与 en 的 key 集合完全一致', () => {
+    const zh = collectLeafPaths(JSON.parse(readFileSync(LOCALE_FILES['zh-CN'], 'utf8')));
+    const en = collectLeafPaths(JSON.parse(readFileSync(LOCALE_FILES.en, 'utf8')));
+    const { onlyInA, onlyInB } = diffKeys(zh, en);
+    expect(onlyInA).toEqual([]);
+    expect(onlyInB).toEqual([]);
+    expect(zh.size).toBeGreaterThan(0);
+  });
+
+  it('源码引用的每个 key 在两个语言包里都存在', () => {
+    const zh = collectLeafPaths(JSON.parse(readFileSync(LOCALE_FILES['zh-CN'], 'utf8')));
+    const en = collectLeafPaths(JSON.parse(readFileSync(LOCALE_FILES.en, 'utf8')));
+
+    const used = new Set();
+    expect(collectSourceFiles().length).toBeGreaterThan(0);
+    for (const f of collectSourceFiles()) {
+      for (const k of extractUsedKeys(readFileSync(f, 'utf8'))) used.add(k);
+    }
+
+    const missing = [...used].filter((k) => !zh.has(k) || !en.has(k));
+    expect(missing).toEqual([]);
+  });
+
+  it('runCheck 整体通过', () => {
+    const r = runCheck();
+    expect(r.errors).toEqual([]);
+    expect(r.ok).toBe(true);
+  });
+});
diff --git a/scripts/check-i18n-keys.mjs b/scripts/check-i18n-keys.mjs
new file mode 100644
index 0000000..2939d14
--- /dev/null
+++ b/scripts/check-i18n-keys.mjs
@@ -0,0 +1,282 @@
+/**
+ * i18n 语言包完整性检查。
+ *
+ * 注意：本文件不含 shebang。vitest 解析 ESM 时不会剥离 `#!` 行，
+ * 会导致 scripts/__tests__ 下的单元测试报 "Invalid or unexpected token"。
+ * 统一通过 `node scripts/check-i18n-keys.mjs` 调用（package.json 已封装为 npm scripts）。
+ *
+ * 背景：zh-CN.json / en.json 里曾出现「同一个父节点下写了两个 "toast"」的情况。
+ * JSON.parse 对重复 key 的行为是静默取最后一个，于是 envConfig.toast 下的
+ * applySuccess / backedUp / startSuccess 等 8 条文案被后写的 pull* 三条整体覆盖，
+ * 运行时 t() 找不到 key，界面上直接显示 "envConfig.toast.applySuccess"。
+ * 这类问题在 code review 时肉眼极难发现（两段都合法 JSON、缩进一致），
+ * 因此固化为脚本检查。
+ *
+ * 检查三类问题（前三类 exit 1，第 4 类只提示）：
+ *   1. 同一父节点下的重复 key —— 静默丢文案，最致命
+ *   2. zh-CN / en 的 key 集合不一致 —— 一侧必然回退到另一种语言或裸 key
+ *   3. 源码里 t('x.y') 引用的 key 在语言包里不存在 —— 界面显示裸 key
+ *   4. 语言包里存在但源码从未引用的 key —— 死文案（仅提示，不阻断）
+ *
+ * 用法：
+ *   node scripts/check-i18n-keys.mjs
+ */
+
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, join, relative, extname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..');
+const LOCALES_DIR = join(ROOT, 'src', 'i18n', 'locales');
+
+export const LOCALE_FILES = {
+  'zh-CN': join(LOCALES_DIR, 'zh-CN.json'),
+  en: join(LOCALES_DIR, 'en.json'),
+};
+
+const SOURCE_DIRS = [join(ROOT, 'src')];
+const SOURCE_EXTS = new Set(['.vue', '.ts', '.tsx', '.js', '.mjs']);
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.git', 'target']);
+
+/**
+ * 扫描 JSON 原文，找出同一父节点下重复出现的 key。
+ * 不能用 JSON.parse —— 它在解析阶段就已经把重复 key 折叠掉了。
+ *
+ * @param {string} raw JSON 原文
+ * @returns {Array<{ key: string, path: string[] }>} 重复项（含祖先路径，便于定位）
+ */
+export function scanDuplicateKeys(raw) {
+  const stack = [];
+  const dups = [];
+  let i = 0;
+  let expectKey = false;
+  // 最近一次读到的对象 key；遇到 '{' 时它就是即将入栈的这一层的名字
+  let pendingKey = '';
+
+  const pathOf = () => stack.map((f) => f.name).filter(Boolean);
+
+  while (i < raw.length) {
+    const c = raw[i];
+
+    if (c === '"') {
+      let j = i + 1;
+      let s = '';
+      while (j < raw.length) {
+        if (raw[j] === '\\') {
+          s += raw[j] + raw[j + 1];
+          j += 2;
+          continue;
+        }
+        if (raw[j] === '"') break;
+        s += raw[j];
+        j += 1;
+      }
+      i = j + 1;
+
+      // 只有后面紧跟 ':' 的字符串才是对象 key，值字符串跳过
+      if (expectKey) {
+        let k = i;
+        while (k < raw.length && /\s/.test(raw[k])) k += 1;
+        if (raw[k] === ':') {
+          const frame = stack[stack.length - 1];
+          pendingKey = s;
+          if (frame) {
+            const count = (frame.seen.get(s) || 0) + 1;
+            frame.seen.set(s, count);
+            if (count > 1) dups.push({ key: s, path: pathOf() });
+          }
+        }
+      }
+      continue;
+    }
+
+    if (c === '{') {
+      stack.push({ name: pendingKey, seen: new Map() });
+      pendingKey = '';
+      expectKey = true;
+      i += 1;
+      continue;
+    }
+    if (c === '[') {
+      stack.push({ name: '', seen: new Map() });
+      pendingKey = '';
+      expectKey = false;
+      i += 1;
+      continue;
+    }
+    if (c === '}' || c === ']') {
+      stack.pop();
+      expectKey = false;
+      i += 1;
+      continue;
+    }
+    if (c === ',') {
+      expectKey = true;
+      i += 1;
+      continue;
+    }
+    if (c === ':') {
+      // 冒号前的 key 名回填到当前 frame，用于输出祖先路径
+      expectKey = false;
+      i += 1;
+      continue;
+    }
+    i += 1;
+  }
+
+  // 路径回填：key 自身在 dups 里，path 是它的祖先链
+  return dups;
+}
+
+/**
+ * 收集嵌套对象里所有叶子节点的点分路径。
+ * @param {Record<string, unknown>} obj
+ * @param {string} prefix
+ * @returns {Set<string>}
+ */
+export function collectLeafPaths(obj, prefix = '') {
+  const out = new Set();
+  for (const [k, v] of Object.entries(obj || {})) {
+    const path = prefix ? `${prefix}.${k}` : k;
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+      for (const p of collectLeafPaths(v, path)) out.add(p);
+    } else {
+      out.add(path);
+    }
+  }
+  return out;
+}
+
+/**
+ * 从源码文本里提取静态 i18n key：`t('a.b')` / `$t("a.b")` / `t('a.b', {...})`。
+ * 模板字符串、变量拼接等动态 key 无法静态解析，直接跳过（不误报）。
+ *
+ * @param {string} source
+ * @returns {Set<string>}
+ */
+export function extractUsedKeys(source) {
+  const out = new Set();
+  const re = /\$?\bt\(\s*['"]([A-Za-z0-9_.\-]+)['"]/g;
+  let m;
+  while ((m = re.exec(source))) out.add(m[1]);
+  return out;
+}
+
+/**
+ * 两个 key 集合的双向差集。
+ * @param {Set<string>} a
+ * @param {Set<string>} b
+ * @returns {{ onlyInA: string[], onlyInB: string[] }}
+ */
+export function diffKeys(a, b) {
+  const onlyInA = [...a].filter((k) => !b.has(k)).sort();
+  const onlyInB = [...b].filter((k) => !a.has(k)).sort();
+  return { onlyInA, onlyInB };
+}
+
+function walk(dir, out = []) {
+  if (!existsSync(dir)) return out;
+  for (const entry of readdirSync(dir)) {
+    if (SKIP_DIRS.has(entry)) continue;
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      walk(full, out);
+    } else if (SOURCE_EXTS.has(extname(entry))) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+export function collectSourceFiles() {
+  return SOURCE_DIRS.flatMap((d) => walk(d));
+}
+
+export function readLocale(name) {
+  return readFileSync(LOCALE_FILES[name], 'utf8');
+}
+
+/**
+ * 执行完整检查，返回结构化结果（不抛异常、不 exit，便于测试）。
+ */
+export function runCheck() {
+  const messages = [];
+  const errors = [];
+
+  const parsed = {};
+  const dupReport = [];
+
+  for (const name of Object.keys(LOCALE_FILES)) {
+    const raw = readLocale(name);
+    const dups = scanDuplicateKeys(raw);
+    if (dups.length > 0) {
+      dupReport.push({ locale: name, dups });
+      errors.push(`[${name}] 存在 ${dups.length} 处同层级重复 key（后者会静默覆盖前者）`);
+    }
+    parsed[name] = JSON.parse(raw);
+  }
+
+  const keys = {
+    'zh-CN': collectLeafPaths(parsed['zh-CN']),
+    en: collectLeafPaths(parsed.en),
+  };
+
+  const { onlyInA, onlyInB } = diffKeys(keys['zh-CN'], keys.en);
+  if (onlyInA.length > 0) errors.push(`zh-CN 有 ${onlyInA.length} 个 key 在 en 中缺失`);
+  if (onlyInB.length > 0) errors.push(`en 有 ${onlyInB.length} 个 key 在 zh-CN 中缺失`);
+
+  const used = new Set();
+  for (const file of collectSourceFiles()) {
+    try {
+      for (const k of extractUsedKeys(readFileSync(file, 'utf8'))) used.add(k);
+    } catch {
+      // 读失败的文件跳过，不阻断检查
+    }
+  }
+
+  const missing = [...used].filter((k) => !keys['zh-CN'].has(k) || !keys.en.has(k)).sort();
+  if (missing.length > 0) errors.push(`源码引用了 ${missing.length} 个语言包中不存在的 key`);
+
+  const unused = [...keys['zh-CN']].filter((k) => !used.has(k)).sort();
+
+  messages.push(`zh-CN: ${keys['zh-CN'].size} key / en: ${keys.en.size} key / 源码引用: ${used.size} key`);
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    dupReport,
+    missingInZh: [...used].filter((k) => !keys['zh-CN'].has(k)).sort(),
+    missingInEn: [...used].filter((k) => !keys.en.has(k)).sort(),
+    onlyInZh: onlyInA,
+    onlyInEn: onlyInB,
+    unused,
+    messages,
+  };
+}
+
+function main() {
+  const r = runCheck();
+  const lines = [...r.messages];
+
+  for (const { locale, dups } of r.dupReport) {
+    lines.push(`\n❌ [${locale}] 同层级重复 key：`);
+    for (const d of dups) lines.push(`   - ${[...d.path, d.key].join('.')}`);
+  }
+  if (r.onlyInZh.length) lines.push(`\n❌ 仅 zh-CN 有（en 缺失）：\n${r.onlyInZh.map((k) => `   - ${k}`).join('\n')}`);
+  if (r.onlyInEn.length) lines.push(`\n❌ 仅 en 有（zh-CN 缺失）：\n${r.onlyInEn.map((k) => `   - ${k}`).join('\n')}`);
+  if (r.missingInZh.length) lines.push(`\n❌ 源码引用但 zh-CN 缺失：\n${r.missingInZh.map((k) => `   - ${k}`).join('\n')}`);
+  if (r.missingInEn.length) lines.push(`\n❌ 源码引用但 en 缺失：\n${r.missingInEn.map((k) => `   - ${k}`).join('\n')}`);
+  if (r.unused.length) lines.push(`\nℹ️  未被源码引用（死文案，可选清理，共 ${r.unused.length} 条）`);
+
+  lines.push(r.ok ? '\n✅ i18n 检查通过' : `\n❌ i18n 检查失败：${r.errors.length} 类问题`);
+  console.log(lines.join('\n'));
+  process.exit(r.ok ? 0 : 1);
+}
+
+// 仅当作为 CLI 直接执行时跑 main（被 vitest import 时不执行）。
+// 用 pathToFileURL 比对而非字符串拼接：Windows 下盘符与反斜杠会让手工拼接失配。
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}
diff --git a/scripts/sync-php-dockerfile.mjs b/scripts/sync-php-dockerfile.mjs
index c5598c0..e713dec 100644
--- a/scripts/sync-php-dockerfile.mjs
+++ b/scripts/sync-php-dockerfile.mjs
@@ -1,7 +1,10 @@
-#!/usr/bin/env node
 /**
  * 同步各 PHP 版本目录下的 Dockerfile。
  *
+ * 注意：本文件不含 shebang。vitest 解析 ESM 时不会剥离 `#!` 行，
+ * 会导致 scripts/__tests__ 下的单元测试报 "Invalid or unexpected token"。
+ * 统一通过 `node scripts/sync-php-dockerfile.mjs` 调用（package.json 已封装为 npm scripts）。
+ *
  * 背景：services/phpXX/Dockerfile 共 8 份，内容仅两行不同（版本注释与
  * ARG PHP_BASE_IMAGE 的默认值），其余完全一致。由于 config_generator.rs
  * 的 resolve_template_dir() 要求每个 service_dir 都真实存在 Dockerfile
diff --git a/scripts/sync-version-manifest.mjs b/scripts/sync-version-manifest.mjs
index ba637fa..642b36a 100644
--- a/scripts/sync-version-manifest.mjs
+++ b/scripts/sync-version-manifest.mjs
@@ -1,8 +1,11 @@
-#!/usr/bin/env node
 /**
  * 从上游（docker-library/official-images + endoflife.date）拉取版本元数据，
  * 与 src-tauri/services/version_manifest.json 对比，生成可审计的差异报告。
  *
+ * 注意：本文件不含 shebang。vitest 解析 ESM 时不会剥离 `#!` 行，
+ * 会导致 scripts/__tests__ 下的单元测试报 "Invalid or unexpected token"。
+ * 统一通过 `node scripts/sync-version-manifest.mjs` 调用（package.json 已封装为 npm scripts）。
+ *
  * 背景：version_manifest.json 之前是手工维护的，结果严重滞后（项目 PHP 还在
  * 8.5，但上游已有 8.6-RC；MySQL 跳过了整条 9.x）。本脚本在仓库侧 / CI 跑，
  * 把"哪些版本算 stable"的决策外包给 endoflife.date（权威 EOL 数据源），
diff --git a/src-tauri/Cargo.lock b/src-tauri/Cargo.lock
index a5e4743..bf7b004 100644
--- a/src-tauri/Cargo.lock
+++ b/src-tauri/Cargo.lock
@@ -97,7 +97,6 @@ dependencies = [
  "handlebars",
  "log",
  "pathdiff",
- "proptest",
  "reqwest 0.12.28",
  "serde",
  "serde_json",
@@ -3409,25 +3408,6 @@ dependencies = [
  "unicode-ident",
 ]
 
-[[package]]
-name = "proptest"
-version = "1.11.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4b45fcc2344c680f5025fe57779faef368840d0bd1f42f216291f0dc4ace4744"
-dependencies = [
- "bit-set",
- "bit-vec",
- "bitflags 2.11.1",
- "num-traits",
- "rand 0.9.4",
- "rand_chacha 0.9.0",
- "rand_xorshift",
- "regex-syntax",
- "rusty-fork",
- "tempfile",
- "unarray",
-]
-
 [[package]]
 name = "ptr_meta"
 version = "0.1.4"
@@ -3454,12 +3434,6 @@ version = "0.1.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e0c5ccf5294c6ccd63a74f1565028353830a9c2f5eb0c682c355c471726a6e3f"
 
-[[package]]
-name = "quick-error"
-version = "1.2.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a1d01941d82fa2ab50be1e79e6714289dd7cde78eba4c074bc5a4374f650dfe0"
-
 [[package]]
 name = "quick-error"
 version = "2.0.1"
@@ -3536,16 +3510,6 @@ dependencies = [
  "rand_core 0.6.4",
 ]
 
-[[package]]
-name = "rand"
-version = "0.9.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "44c5af06bb1b7d3216d91932aed5265164bf384dc89cd6ba05cf59a35f5f76ea"
-dependencies = [
- "rand_chacha 0.9.0",
- "rand_core 0.9.5",
-]
-
 [[package]]
 name = "rand_chacha"
 version = "0.2.2"
@@ -3566,16 +3530,6 @@ dependencies = [
  "rand_core 0.6.4",
 ]
 
-[[package]]
-name = "rand_chacha"
-version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
-dependencies = [
- "ppv-lite86",
- "rand_core 0.9.5",
-]
-
 [[package]]
 name = "rand_core"
 version = "0.5.1"
@@ -3594,15 +3548,6 @@ dependencies = [
  "getrandom 0.2.17",
 ]
 
-[[package]]
-name = "rand_core"
-version = "0.9.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
-dependencies = [
- "getrandom 0.3.4",
-]
-
 [[package]]
 name = "rand_hc"
 version = "0.2.0"
@@ -3621,15 +3566,6 @@ dependencies = [
  "rand_core 0.5.1",
 ]
 
-[[package]]
-name = "rand_xorshift"
-version = "0.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "513962919efc330f829edb2535844d1b912b0fbe2ca165d613e4e8788bb05a5a"
-dependencies = [
- "rand_core 0.9.5",
-]
-
 [[package]]
 name = "raw-window-handle"
 version = "0.6.2"
@@ -3939,18 +3875,6 @@ version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
 
-[[package]]
-name = "rusty-fork"
-version = "0.3.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cc6bf79ff24e648f6da1f8d1f011e9cac26491b619e6b9280f2b47f1774e6ee2"
-dependencies = [
- "fnv",
- "quick-error 1.2.3",
- "tempfile",
- "wait-timeout",
-]
-
 [[package]]
 name = "ryu"
 version = "1.0.23"
@@ -5111,7 +5035,7 @@ dependencies = [
  "fax",
  "flate2",
  "half",
- "quick-error 2.0.1",
+ "quick-error",
  "weezl",
  "zune-jpeg",
 ]
@@ -5503,12 +5427,6 @@ version = "0.1.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2896d95c02a80c6d6a5d6e953d479f5ddf2dfdb6a244441010e373ac0fb88971"
 
-[[package]]
-name = "unarray"
-version = "0.1.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "eaea85b334db583fe3274d12b4cd1880032beab409c0d774be044d4480ab9a94"
-
 [[package]]
 name = "unic-char-property"
 version = "0.9.0"
@@ -5685,15 +5603,6 @@ dependencies = [
  "libc",
 ]
 
-[[package]]
-name = "wait-timeout"
-version = "0.2.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "09ac3b126d3914f9849036f826e054cbabdc8519970b8998ddaf3b5bd3c65f11"
-dependencies = [
- "libc",
-]
-
 [[package]]
 name = "walkdir"
 version = "2.5.0"
diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml
index 6f91335..ea92711 100644
--- a/src-tauri/Cargo.toml
+++ b/src-tauri/Cargo.toml
@@ -3,7 +3,7 @@ name = "app"
 version = "0.3.1"
 description = "PHP-Stack - PHP Development Environment Manager"
 authors = ["jeeinn"]
-license = ""
+license = "MIT"
 repository = ""
 edition = "2021"
 rust-version = "1.77.2"
@@ -41,7 +41,6 @@ sha2 = "0.10"
 pathdiff = "0.2"
 
 [dev-dependencies]
-proptest = "1"
 tempfile = "3"
 
 [[test]]
diff --git a/src-tauri/build.rs b/src-tauri/build.rs
index 311900d..261851f 100644
--- a/src-tauri/build.rs
+++ b/src-tauri/build.rs
@@ -1,3 +1,3 @@
 fn main() {
-  tauri_build::build();
+    tauri_build::build();
 }
diff --git a/src-tauri/services/nginx124/Dockerfile b/src-tauri/services/nginx124/Dockerfile
index 48bd16e..4e084f6 100644
--- a/src-tauri/services/nginx124/Dockerfile
+++ b/src-tauri/services/nginx124/Dockerfile
@@ -6,18 +6,38 @@ FROM ${NGINX_BASE_IMAGE}
 ARG PUID=1000
 ARG PGID=1000
 
-# Dynamically adjust nginx user ID to match host (Alpine Linux)
-# Default nginx UID=100, GID=101 in Alpine
-RUN if [ "${PUID}" != "1000" ] || [ "${PGID}" != "1000" ]; then \
-      # Delete existing nginx group and user
-      deluser nginx && \
-      delgroup nginx && \
-      # Create new group and user with specified IDs
-      addgroup -g ${PGID} nginx && \
-      adduser -u ${PUID} -G nginx -s /bin/sh -D nginx && \
-      echo "Adjusted nginx to UID=${PUID}, GID=${PGID}"; \
-    fi
+# 把容器内 nginx 用户的 UID/GID 对齐宿主机，避免挂载目录里写出的文件属主不匹配。
+#
+# 这里修掉了原实现的两个坑：
+#   1. 原条件是 `PUID != 1000 || PGID != 1000`，而默认值本身就是 1000 ——
+#      等于默认配置下永远不执行，映射形同虚设。现在改为「与目标不一致才调整」。
+#   2. 原实现只用了 alpine 的 deluser/adduser。用户若在 .env 里把基础镜像换成
+#      debian 版（如 nginx:1.28），构建会直接 `deluser: not found` 失败。
+#      现在按基础镜像分发：alpine 用 deluser/adduser，debian 用 groupmod/usermod。
+#
+# 只在与目标不一致时才改动，保证默认构建层可缓存、不产生无谓的镜像层差异。
+RUN set -eux; \
+    if [ -f /etc/alpine-release ]; then \
+      if [ "$(id -u nginx)" != "${PUID}" ] || [ "$(id -g nginx)" != "${PGID}" ]; then \
+        deluser nginx; \
+        # alpine 的 deluser 会连带删掉同名组，delgroup 再删会报 unknown group
+        delgroup nginx 2>/dev/null || true; \
+        addgroup -g "${PGID}" nginx; \
+        adduser -u "${PUID}" -G nginx -s /bin/sh -D nginx; \
+      fi; \
+    elif command -v usermod >/dev/null 2>&1; then \
+      if [ "$(id -g nginx)" != "${PGID}" ]; then groupmod -o -g "${PGID}" nginx; fi; \
+      if [ "$(id -u nginx)" != "${PUID}" ]; then usermod -o -u "${PUID}" -g "${PGID}" nginx; fi; \
+    else \
+      echo "skip: 未识别的基础镜像，沿用镜像默认的 nginx 用户"; \
+    fi; \
+    echo "nginx uid=$(id -u nginx) gid=$(id -g nginx)"
 
 WORKDIR /www
 
-USER nginx
+# 不能切换为 USER nginx：官方 nginx 镜像的 entrypoint 需要 root 权限
+# （创建 /var/cache/nginx/*_temp 目录、改写 conf.d/default.conf），
+# 且 80 端口只有 root 能 bind。以 nginx 身份启动会直接报
+# [emerg] mkdir() "/var/cache/nginx/client_temp" failed (13: Permission denied)。
+# worker 进程身份由 nginx.conf 的 `user nginx;` 决定，PUID/PGID 映射仍然生效：
+# root 只跑 master，写文件（日志、缓存）的是 nginx(PUID:PGID)。
diff --git a/src-tauri/services/nginx125/Dockerfile b/src-tauri/services/nginx125/Dockerfile
index b081eb8..d4d5883 100644
--- a/src-tauri/services/nginx125/Dockerfile
+++ b/src-tauri/services/nginx125/Dockerfile
@@ -6,18 +6,38 @@ FROM ${NGINX_BASE_IMAGE}
 ARG PUID=1000
 ARG PGID=1000
 
-# Dynamically adjust nginx user ID to match host (Alpine Linux)
-# Default nginx UID=100, GID=101 in Alpine
-RUN if [ "${PUID}" != "1000" ] || [ "${PGID}" != "1000" ]; then \
-      # Delete existing nginx group and user
-      deluser nginx && \
-      delgroup nginx && \
-      # Create new group and user with specified IDs
-      addgroup -g ${PGID} nginx && \
-      adduser -u ${PUID} -G nginx -s /bin/sh -D nginx && \
-      echo "Adjusted nginx to UID=${PUID}, GID=${PGID}"; \
-    fi
+# 把容器内 nginx 用户的 UID/GID 对齐宿主机，避免挂载目录里写出的文件属主不匹配。
+#
+# 这里修掉了原实现的两个坑：
+#   1. 原条件是 `PUID != 1000 || PGID != 1000`，而默认值本身就是 1000 ——
+#      等于默认配置下永远不执行，映射形同虚设。现在改为「与目标不一致才调整」。
+#   2. 原实现只用了 alpine 的 deluser/adduser。用户若在 .env 里把基础镜像换成
+#      debian 版（如 nginx:1.28），构建会直接 `deluser: not found` 失败。
+#      现在按基础镜像分发：alpine 用 deluser/adduser，debian 用 groupmod/usermod。
+#
+# 只在与目标不一致时才改动，保证默认构建层可缓存、不产生无谓的镜像层差异。
+RUN set -eux; \
+    if [ -f /etc/alpine-release ]; then \
+      if [ "$(id -u nginx)" != "${PUID}" ] || [ "$(id -g nginx)" != "${PGID}" ]; then \
+        deluser nginx; \
+        # alpine 的 deluser 会连带删掉同名组，delgroup 再删会报 unknown group
+        delgroup nginx 2>/dev/null || true; \
+        addgroup -g "${PGID}" nginx; \
+        adduser -u "${PUID}" -G nginx -s /bin/sh -D nginx; \
+      fi; \
+    elif command -v usermod >/dev/null 2>&1; then \
+      if [ "$(id -g nginx)" != "${PGID}" ]; then groupmod -o -g "${PGID}" nginx; fi; \
+      if [ "$(id -u nginx)" != "${PUID}" ]; then usermod -o -u "${PUID}" -g "${PGID}" nginx; fi; \
+    else \
+      echo "skip: 未识别的基础镜像，沿用镜像默认的 nginx 用户"; \
+    fi; \
+    echo "nginx uid=$(id -u nginx) gid=$(id -g nginx)"
 
 WORKDIR /www
 
-USER nginx
+# 不能切换为 USER nginx：官方 nginx 镜像的 entrypoint 需要 root 权限
+# （创建 /var/cache/nginx/*_temp 目录、改写 conf.d/default.conf），
+# 且 80 端口只有 root 能 bind。以 nginx 身份启动会直接报
+# [emerg] mkdir() "/var/cache/nginx/client_temp" failed (13: Permission denied)。
+# worker 进程身份由 nginx.conf 的 `user nginx;` 决定，PUID/PGID 映射仍然生效：
+# root 只跑 master，写文件（日志、缓存）的是 nginx(PUID:PGID)。
diff --git a/src-tauri/services/nginx126/Dockerfile b/src-tauri/services/nginx126/Dockerfile
index d9af35c..093082b 100644
--- a/src-tauri/services/nginx126/Dockerfile
+++ b/src-tauri/services/nginx126/Dockerfile
@@ -6,18 +6,38 @@ FROM ${NGINX_BASE_IMAGE}
 ARG PUID=1000
 ARG PGID=1000
 
-# Dynamically adjust nginx user ID to match host (Alpine Linux)
-# Default nginx UID=100, GID=101 in Alpine
-RUN if [ "${PUID}" != "1000" ] || [ "${PGID}" != "1000" ]; then \
-      # Delete existing nginx group and user
-      deluser nginx && \
-      delgroup nginx && \
-      # Create new group and user with specified IDs
-      addgroup -g ${PGID} nginx && \
-      adduser -u ${PUID} -G nginx -s /bin/sh -D nginx && \
-      echo "Adjusted nginx to UID=${PUID}, GID=${PGID}"; \
-    fi
+# 把容器内 nginx 用户的 UID/GID 对齐宿主机，避免挂载目录里写出的文件属主不匹配。
+#
+# 这里修掉了原实现的两个坑：
+#   1. 原条件是 `PUID != 1000 || PGID != 1000`，而默认值本身就是 1000 ——
+#      等于默认配置下永远不执行，映射形同虚设。现在改为「与目标不一致才调整」。
+#   2. 原实现只用了 alpine 的 deluser/adduser。用户若在 .env 里把基础镜像换成
+#      debian 版（如 nginx:1.28），构建会直接 `deluser: not found` 失败。
+#      现在按基础镜像分发：alpine 用 deluser/adduser，debian 用 groupmod/usermod。
+#
+# 只在与目标不一致时才改动，保证默认构建层可缓存、不产生无谓的镜像层差异。
+RUN set -eux; \
+    if [ -f /etc/alpine-release ]; then \
+      if [ "$(id -u nginx)" != "${PUID}" ] || [ "$(id -g nginx)" != "${PGID}" ]; then \
+        deluser nginx; \
+        # alpine 的 deluser 会连带删掉同名组，delgroup 再删会报 unknown group
+        delgroup nginx 2>/dev/null || true; \
+        addgroup -g "${PGID}" nginx; \
+        adduser -u "${PUID}" -G nginx -s /bin/sh -D nginx; \
+      fi; \
+    elif command -v usermod >/dev/null 2>&1; then \
+      if [ "$(id -g nginx)" != "${PGID}" ]; then groupmod -o -g "${PGID}" nginx; fi; \
+      if [ "$(id -u nginx)" != "${PUID}" ]; then usermod -o -u "${PUID}" -g "${PGID}" nginx; fi; \
+    else \
+      echo "skip: 未识别的基础镜像，沿用镜像默认的 nginx 用户"; \
+    fi; \
+    echo "nginx uid=$(id -u nginx) gid=$(id -g nginx)"
 
 WORKDIR /www
 
-USER nginx
+# 不能切换为 USER nginx：官方 nginx 镜像的 entrypoint 需要 root 权限
+# （创建 /var/cache/nginx/*_temp 目录、改写 conf.d/default.conf），
+# 且 80 端口只有 root 能 bind。以 nginx 身份启动会直接报
+# [emerg] mkdir() "/var/cache/nginx/client_temp" failed (13: Permission denied)。
+# worker 进程身份由 nginx.conf 的 `user nginx;` 决定，PUID/PGID 映射仍然生效：
+# root 只跑 master，写文件（日志、缓存）的是 nginx(PUID:PGID)。
diff --git a/src-tauri/services/nginx127/Dockerfile b/src-tauri/services/nginx127/Dockerfile
index ccc23f7..9a3c745 100644
--- a/src-tauri/services/nginx127/Dockerfile
+++ b/src-tauri/services/nginx127/Dockerfile
@@ -6,18 +6,38 @@ FROM ${NGINX_BASE_IMAGE}
 ARG PUID=1000
 ARG PGID=1000
 
-# Dynamically adjust nginx user ID to match host (Alpine Linux)
-# Default nginx UID=100, GID=101 in Alpine
-RUN if [ "${PUID}" != "1000" ] || [ "${PGID}" != "1000" ]; then \
-      # Delete existing nginx group and user
-      deluser nginx && \
-      delgroup nginx && \
-      # Create new group and user with specified IDs
-      addgroup -g ${PGID} nginx && \
-      adduser -u ${PUID} -G nginx -s /bin/sh -D nginx && \
-      echo "Adjusted nginx to UID=${PUID}, GID=${PGID}"; \
-    fi
+# 把容器内 nginx 用户的 UID/GID 对齐宿主机，避免挂载目录里写出的文件属主不匹配。
+#
+# 这里修掉了原实现的两个坑：
+#   1. 原条件是 `PUID != 1000 || PGID != 1000`，而默认值本身就是 1000 ——
+#      等于默认配置下永远不执行，映射形同虚设。现在改为「与目标不一致才调整」。
+#   2. 原实现只用了 alpine 的 deluser/adduser。用户若在 .env 里把基础镜像换成
+#      debian 版（如 nginx:1.28），构建会直接 `deluser: not found` 失败。
+#      现在按基础镜像分发：alpine 用 deluser/adduser，debian 用 groupmod/usermod。
+#
+# 只在与目标不一致时才改动，保证默认构建层可缓存、不产生无谓的镜像层差异。
+RUN set -eux; \
+    if [ -f /etc/alpine-release ]; then \
+      if [ "$(id -u nginx)" != "${PUID}" ] || [ "$(id -g nginx)" != "${PGID}" ]; then \
+        deluser nginx; \
+        # alpine 的 deluser 会连带删掉同名组，delgroup 再删会报 unknown group
+        delgroup nginx 2>/dev/null || true; \
+        addgroup -g "${PGID}" nginx; \
+        adduser -u "${PUID}" -G nginx -s /bin/sh -D nginx; \
+      fi; \
+    elif command -v usermod >/dev/null 2>&1; then \
+      if [ "$(id -g nginx)" != "${PGID}" ]; then groupmod -o -g "${PGID}" nginx; fi; \
+      if [ "$(id -u nginx)" != "${PUID}" ]; then usermod -o -u "${PUID}" -g "${PGID}" nginx; fi; \
+    else \
+      echo "skip: 未识别的基础镜像，沿用镜像默认的 nginx 用户"; \
+    fi; \
+    echo "nginx uid=$(id -u nginx) gid=$(id -g nginx)"
 
 WORKDIR /www
 
-USER nginx
+# 不能切换为 USER nginx：官方 nginx 镜像的 entrypoint 需要 root 权限
+# （创建 /var/cache/nginx/*_temp 目录、改写 conf.d/default.conf），
+# 且 80 端口只有 root 能 bind。以 nginx 身份启动会直接报
+# [emerg] mkdir() "/var/cache/nginx/client_temp" failed (13: Permission denied)。
+# worker 进程身份由 nginx.conf 的 `user nginx;` 决定，PUID/PGID 映射仍然生效：
+# root 只跑 master，写文件（日志、缓存）的是 nginx(PUID:PGID)。
diff --git a/src-tauri/services/nginx128/Dockerfile b/src-tauri/services/nginx128/Dockerfile
index 43aec89..e8d1e98 100644
--- a/src-tauri/services/nginx128/Dockerfile
+++ b/src-tauri/services/nginx128/Dockerfile
@@ -6,18 +6,38 @@ FROM ${NGINX_BASE_IMAGE}
 ARG PUID=1000
 ARG PGID=1000
 
-# Dynamically adjust nginx user ID to match host (Alpine Linux)
-# Default nginx UID=100, GID=101 in Alpine
-RUN if [ "${PUID}" != "1000" ] || [ "${PGID}" != "1000" ]; then \
-      # Delete existing nginx group and user
-      deluser nginx && \
-      delgroup nginx && \
-      # Create new group and user with specified IDs
-      addgroup -g ${PGID} nginx && \
-      adduser -u ${PUID} -G nginx -s /bin/sh -D nginx && \
-      echo "Adjusted nginx to UID=${PUID}, GID=${PGID}"; \
-    fi
+# 把容器内 nginx 用户的 UID/GID 对齐宿主机，避免挂载目录里写出的文件属主不匹配。
+#
+# 这里修掉了原实现的两个坑：
+#   1. 原条件是 `PUID != 1000 || PGID != 1000`，而默认值本身就是 1000 ——
+#      等于默认配置下永远不执行，映射形同虚设。现在改为「与目标不一致才调整」。
+#   2. 原实现只用了 alpine 的 deluser/adduser。用户若在 .env 里把基础镜像换成
+#      debian 版（如 nginx:1.28），构建会直接 `deluser: not found` 失败。
+#      现在按基础镜像分发：alpine 用 deluser/adduser，debian 用 groupmod/usermod。
+#
+# 只在与目标不一致时才改动，保证默认构建层可缓存、不产生无谓的镜像层差异。
+RUN set -eux; \
+    if [ -f /etc/alpine-release ]; then \
+      if [ "$(id -u nginx)" != "${PUID}" ] || [ "$(id -g nginx)" != "${PGID}" ]; then \
+        deluser nginx; \
+        # alpine 的 deluser 会连带删掉同名组，delgroup 再删会报 unknown group
+        delgroup nginx 2>/dev/null || true; \
+        addgroup -g "${PGID}" nginx; \
+        adduser -u "${PUID}" -G nginx -s /bin/sh -D nginx; \
+      fi; \
+    elif command -v usermod >/dev/null 2>&1; then \
+      if [ "$(id -g nginx)" != "${PGID}" ]; then groupmod -o -g "${PGID}" nginx; fi; \
+      if [ "$(id -u nginx)" != "${PUID}" ]; then usermod -o -u "${PUID}" -g "${PGID}" nginx; fi; \
+    else \
+      echo "skip: 未识别的基础镜像，沿用镜像默认的 nginx 用户"; \
+    fi; \
+    echo "nginx uid=$(id -u nginx) gid=$(id -g nginx)"
 
 WORKDIR /www
 
-USER nginx
+# 不能切换为 USER nginx：官方 nginx 镜像的 entrypoint 需要 root 权限
+# （创建 /var/cache/nginx/*_temp 目录、改写 conf.d/default.conf），
+# 且 80 端口只有 root 能 bind。以 nginx 身份启动会直接报
+# [emerg] mkdir() "/var/cache/nginx/client_temp" failed (13: Permission denied)。
+# worker 进程身份由 nginx.conf 的 `user nginx;` 决定，PUID/PGID 映射仍然生效：
+# root 只跑 master，写文件（日志、缓存）的是 nginx(PUID:PGID)。
diff --git a/src-tauri/services/php56/Dockerfile b/src-tauri/services/php56/Dockerfile
index 1bb28b7..5a02cb8 100644
--- a/src-tauri/services/php56/Dockerfile
+++ b/src-tauri/services/php56/Dockerfile
@@ -57,11 +57,31 @@ RUN if [ -n "$COMPOSER_MIRROR" ] && [ "$COMPOSER_MIRROR" != "https://packagist.o
 ARG PUID=1000
 ARG PGID=1000
 
-# Dynamically adjust www-data user ID to match host
-RUN if [ "${PUID}" != "1000" ] || [ "${PGID}" != "1000" ]; then \
-      groupmod -o -g ${PGID} www-data && \
-      usermod -o -u ${PUID} -g ${PGID} www-data && \
-      echo "Adjusted www-data to UID=${PUID}, GID=${PGID}"; \
-    fi
+# 把容器内 www-data 用户的 UID/GID 对齐宿主机，避免挂载目录里写出的文件属主不匹配。
+#
+# 这里修掉了原实现的两个坑：
+#   1. 原条件是 `PUID != 1000 || PGID != 1000`，而默认值本身就是 1000 ——
+#      等于默认配置下永远不执行，映射形同虚设。现在改为「与目标不一致才调整」。
+#   2. 原实现只用 debian 的 groupmod/usermod。用户若把基础镜像换成 alpine 版
+#      （如 php:8.2-fpm-alpine），构建会直接 `groupmod: not found` 失败。
+#      现在按可用命令分发两种改法。
+#
+# 只在与目标不一致时才改动，保证默认构建层可缓存。
+RUN set -eux; \
+    if [ "$(id -u www-data)" != "${PUID}" ] || [ "$(id -g www-data)" != "${PGID}" ]; then \
+      if command -v usermod >/dev/null 2>&1; then \
+        groupmod -o -g "${PGID}" www-data; \
+        usermod -o -u "${PUID}" -g "${PGID}" www-data; \
+      elif command -v adduser >/dev/null 2>&1; then \
+        deluser www-data; \
+        # alpine 的 deluser 会连带删掉同名组，delgroup 再删会报 unknown group
+        delgroup www-data 2>/dev/null || true; \
+        addgroup -g "${PGID}" www-data; \
+        adduser -u "${PUID}" -G www-data -s /bin/sh -D www-data; \
+      else \
+        echo "skip: 未识别的基础镜像，沿用镜像默认的 www-data 用户"; \
+      fi; \
+    fi; \
+    echo "www-data uid=$(id -u www-data) gid=$(id -g www-data)"
 
 WORKDIR /www
diff --git a/src-tauri/services/php74/Dockerfile b/src-tauri/services/php74/Dockerfile
index f3ff3df..876cd94 100644
--- a/src-tauri/services/php74/Dockerfile
+++ b/src-tauri/services/php74/Dockerfile
@@ -57,11 +57,31 @@ RUN if [ -n "$COMPOSER_MIRROR" ] && [ "$COMPOSER_MIRROR" != "https://packagist.o
 ARG PUID=1000
 ARG PGID=1000
 
-# Dynamically adjust www-data user ID to match host
-RUN if [ "${PUID}" != "1000" ] || [ "${PGID}" != "1000" ]; then \
-      groupmod -o -g ${PGID} www-data && \
-      usermod -o -u ${PUID} -g ${PGID} www-data && \
-      echo "Adjusted www-data to UID=${PUID}, GID=${PGID}"; \
-    fi
+# 把容器内 www-data 用户的 UID/GID 对齐宿主机，避免挂载目录里写出的文件属主不匹配。
+#
+# 这里修掉了原实现的两个坑：
+#   1. 原条件是 `PUID != 1000 || PGID != 1000`，而默认值本身就是 1000 ——
+#      等于默认配置下永远不执行，映射形同虚设。现在改为「与目标不一致才调整」。
+#   2. 原实现只用 debian 的 groupmod/usermod。用户若把基础镜像换成 alpine 版
+#      （如 php:8.2-fpm-alpine），构建会直接 `groupmod: not found` 失败。
+#      现在按可用命令分发两种改法。
+#
+# 只在与目标不一致时才改动，保证默认构建层可缓存。
+RUN set -eux; \
+    if [ "$(id -u www-data)" != "${PUID}" ] || [ "$(id -g www-data)" != "${PGID}" ]; then \
+      if command -v usermod >/dev/null 2>&1; then \
+        groupmod -o -g "${PGID}" www-data; \
+        usermod -o -u "${PUID}" -g "${PGID}" www-data; \
+      elif command -v adduser >/dev/null 2>&1; then \
+        deluser www-data; \
+        # alpine 的 deluser 会连带删掉同名组，delgroup 再删会报 unknown group
+        delgroup www-data 2>/dev/null || true; \
+        addgroup -g "${PGID}" www-data; \
+        adduser -u "${PUID}" -G www-data -s /bin/sh -D www-data; \
+      else \
+        echo "skip: 未识别的基础镜像，沿用镜像默认的 www-data 用户"; \
+      fi; \
+    fi; \
+    echo "www-data uid=$(id -u www-data) gid=$(id -g www-data)"
 
 WORKDIR /www
diff --git a/src-tauri/services/php80/Dockerfile b/src-tauri/services/php80/Dockerfile
index 3778697..3a8c33f 100644
--- a/src-tauri/services/php80/Dockerfile
+++ b/src-tauri/services/php80/Dockerfile
@@ -57,11 +57,31 @@ RUN if [ -n "$COMPOSER_MIRROR" ] && [ "$COMPOSER_MIRROR" != "https://packagist.o
 ARG PUID=1000
 ARG PGID=1000
 
-# Dynamically adjust www-data user ID to match host
-RUN if [ "${PUID}" != "1000" ] || [ "${PGID}" != "1000" ]; then \
-      groupmod -o -g ${PGID} www-data && \
-      usermod -o -u ${PUID} -g ${PGID} www-data && \
-      echo "Adjusted www-data to UID=${PUID}, GID=${PGID}"; \
-    fi
+# 把容器内 www-data 用户的 UID/GID 对齐宿主机，避免挂载目录里写出的文件属主不匹配。
+#
+# 这里修掉了原实现的两个坑：
+#   1. 原条件是 `PUID != 1000 || PGID != 1000`，而默认值本身就是 1000 ——
+#      等于默认配置下永远不执行，映射形同虚设。现在改为「与目标不一致才调整」。
+#   2. 原实现只用 debian 的 groupmod/usermod。用户若把基础镜像换成 alpine 版
+#      （如 php:8.2-fpm-alpine），构建会直接 `groupmod: not found` 失败。
+#      现在按可用命令分发两种改法。
+#
+# 只在与目标不一致时才改动，保证默认构建层可缓存。
+RUN set -eux; \
+    if [ "$(id -u www-data)" != "${PUID}" ] || [ "$(id -g www-data)" != "${PGID}" ]; then \
+      if command -v usermod >/dev/null 2>&1; then \
+        groupmod -o -g "${PGID}" www-data; \
+        usermod -o -u "${PUID}" -g "${PGID}" www-data; \
+      elif command -v adduser >/dev/null 2>&1; then \
+        deluser www-data; \
+        # alpine 的 deluser 会连带删掉同名组，delgroup 再删会报 unknown group
+        delgroup www-data 2>/dev/null || true; \
+        addgroup -g "${PGID}" www-data; \
+        adduser -u "${PUID}" -G www-data -s /bin/sh -D www-data; \
+      else \
+        echo "skip: 未识别的基础镜像，沿用镜像默认的 www-data 用户"; \
+      fi; \
+    fi; \
+    echo "www-data uid=$(id -u www-data) gid=$(id -g www-data)"
 
 WORKDIR /www
diff --git a/src-tauri/services/php81/Dockerfile b/src-tauri/services/php81/Dockerfile
index 22298ed..e5d77d5 100644
--- a/src-tauri/services/php81/Dockerfile
+++ b/src-tauri/services/php81/Dockerfile
@@ -57,11 +57,31 @@ RUN if [ -n "$COMPOSER_MIRROR" ] && [ "$COMPOSER_MIRROR" != "https://packagist.o
 ARG PUID=1000
 ARG PGID=1000
 
-# Dynamically adjust www-data user ID to match host
-RUN if [ "${PUID}" != "1000" ] || [ "${PGID}" != "1000" ]; then \
-      groupmod -o -g ${PGID} www-data && \
-      usermod -o -u ${PUID} -g ${PGID} www-data && \
-      echo "Adjusted www-data to UID=${PUID}, GID=${PGID}"; \
-    fi
+# 把容器内 www-data 用户的 UID/GID 对齐宿主机，避免挂载目录里写出的文件属主不匹配。
+#
+# 这里修掉了原实现的两个坑：
+#   1. 原条件是 `PUID != 1000 || PGID != 1000`，而默认值本身就是 1000 ——
+#      等于默认配置下永远不执行，映射形同虚设。现在改为「与目标不一致才调整」。
+#   2. 原实现只用 debian 的 groupmod/usermod。用户若把基础镜像换成 alpine 版
+#      （如 php:8.2-fpm-alpine），构建会直接 `groupmod: not found` 失败。
+#      现在按可用命令分发两种改法。
+#
+# 只在与目标不一致时才改动，保证默认构建层可缓存。
+RUN set -eux; \
+    if [ "$(id -u www-data)" != "${PUID}" ] || [ "$(id -g www-data)" != "${PGID}" ]; then \
+      if command -v usermod >/dev/null 2>&1; then \
+        groupmod -o -g "${PGID}" www-data; \
+        usermod -o -u "${PUID}" -g "${PGID}" www-data; \
+      elif command -v adduser >/dev/null 2>&1; then \
+        deluser www-data; \
+        # alpine 的 deluser 会连带删掉同名组，delgroup 再删会报 unknown group
+        delgroup www-data 2>/dev/null || true; \
+        addgroup -g "${PGID}" www-data; \
+        adduser -u "${PUID}" -G www-data -s /bin/sh -D www-data; \
+      else \
+        echo "skip: 未识别的基础镜像，沿用镜像默认的 www-data 用户"; \
+      fi; \
+    fi; \
+    echo "www-data uid=$(id -u www-data) gid=$(id -g www-data)"
 
 WORKDIR /www
diff --git a/src-tauri/services/php82/Dockerfile b/src-tauri/services/php82/Dockerfile
index e385cdf..3d42811 100644
--- a/src-tauri/services/php82/Dockerfile
+++ b/src-tauri/services/php82/Dockerfile
@@ -57,11 +57,31 @@ RUN if [ -n "$COMPOSER_MIRROR" ] && [ "$COMPOSER_MIRROR" != "https://packagist.o
 ARG PUID=1000
 ARG PGID=1000
 
-# Dynamically adjust www-data user ID to match host
-RUN if [ "${PUID}" != "1000" ] || [ "${PGID}" != "1000" ]; then \
-      groupmod -o -g ${PGID} www-data && \
-      usermod -o -u ${PUID} -g ${PGID} www-data && \
-      echo "Adjusted www-data to UID=${PUID}, GID=${PGID}"; \
-    fi
+# 把容器内 www-data 用户的 UID/GID 对齐宿主机，避免挂载目录里写出的文件属主不匹配。
+#
+# 这里修掉了原实现的两个坑：
+#   1. 原条件是 `PUID != 1000 || PGID != 1000`，而默认值本身就是 1000 ——
+#      等于默认配置下永远不执行，映射形同虚设。现在改为「与目标不一致才调整」。
+#   2. 原实现只用 debian 的 groupmod/usermod。用户若把基础镜像换成 alpine 版
+#      （如 php:8.2-fpm-alpine），构建会直接 `groupmod: not found` 失败。
+#      现在按可用命令分发两种改法。
+#
+# 只在与目标不一致时才改动，保证默认构建层可缓存。
+RUN set -eux; \
+    if [ "$(id -u www-data)" != "${PUID}" ] || [ "$(id -g www-data)" != "${PGID}" ]; then \
+      if command -v usermod >/dev/null 2>&1; then \
+        groupmod -o -g "${PGID}" www-data; \
+        usermod -o -u "${PUID}" -g "${PGID}" www-data; \
+      elif command -v adduser >/dev/null 2>&1; then \
+        deluser www-data; \
+        # alpine 的 deluser 会连带删掉同名组，delgroup 再删会报 unknown group
+        delgroup www-data 2>/dev/null || true; \
+        addgroup -g "${PGID}" www-data; \
+        adduser -u "${PUID}" -G www-data -s /bin/sh -D www-data; \
+      else \
+        echo "skip: 未识别的基础镜像，沿用镜像默认的 www-data 用户"; \
+      fi; \
+    fi; \
+    echo "www-data uid=$(id -u www-data) gid=$(id -g www-data)"
 
 WORKDIR /www
diff --git a/src-tauri/services/php83/Dockerfile b/src-tauri/services/php83/Dockerfile
index 81eafc2..9a1f6da 100644
--- a/src-tauri/services/php83/Dockerfile
+++ b/src-tauri/services/php83/Dockerfile
@@ -57,11 +57,31 @@ RUN if [ -n "$COMPOSER_MIRROR" ] && [ "$COMPOSER_MIRROR" != "https://packagist.o
 ARG PUID=1000
 ARG PGID=1000
 
-# Dynamically adjust www-data user ID to match host
-RUN if [ "${PUID}" != "1000" ] || [ "${PGID}" != "1000" ]; then \
-      groupmod -o -g ${PGID} www-data && \
-      usermod -o -u ${PUID} -g ${PGID} www-data && \
-      echo "Adjusted www-data to UID=${PUID}, GID=${PGID}"; \
-    fi
+# 把容器内 www-data 用户的 UID/GID 对齐宿主机，避免挂载目录里写出的文件属主不匹配。
+#
+# 这里修掉了原实现的两个坑：
+#   1. 原条件是 `PUID != 1000 || PGID != 1000`，而默认值本身就是 1000 ——
+#      等于默认配置下永远不执行，映射形同虚设。现在改为「与目标不一致才调整」。
+#   2. 原实现只用 debian 的 groupmod/usermod。用户若把基础镜像换成 alpine 版
+#      （如 php:8.2-fpm-alpine），构建会直接 `groupmod: not found` 失败。
+#      现在按可用命令分发两种改法。
+#
+# 只在与目标不一致时才改动，保证默认构建层可缓存。
+RUN set -eux; \
+    if [ "$(id -u www-data)" != "${PUID}" ] || [ "$(id -g www-data)" != "${PGID}" ]; then \
+      if command -v usermod >/dev/null 2>&1; then \
+        groupmod -o -g "${PGID}" www-data; \
+        usermod -o -u "${PUID}" -g "${PGID}" www-data; \
+      elif command -v adduser >/dev/null 2>&1; then \
+        deluser www-data; \
+        # alpine 的 deluser 会连带删掉同名组，delgroup 再删会报 unknown group
+        delgroup www-data 2>/dev/null || true; \
+        addgroup -g "${PGID}" www-data; \
+        adduser -u "${PUID}" -G www-data -s /bin/sh -D www-data; \
+      else \
+        echo "skip: 未识别的基础镜像，沿用镜像默认的 www-data 用户"; \
+      fi; \
+    fi; \
+    echo "www-data uid=$(id -u www-data) gid=$(id -g www-data)"
 
 WORKDIR /www
diff --git a/src-tauri/services/php84/Dockerfile b/src-tauri/services/php84/Dockerfile
index b61df1b..6317103 100644
--- a/src-tauri/services/php84/Dockerfile
+++ b/src-tauri/services/php84/Dockerfile
@@ -57,11 +57,31 @@ RUN if [ -n "$COMPOSER_MIRROR" ] && [ "$COMPOSER_MIRROR" != "https://packagist.o
 ARG PUID=1000
 ARG PGID=1000
 
-# Dynamically adjust www-data user ID to match host
-RUN if [ "${PUID}" != "1000" ] || [ "${PGID}" != "1000" ]; then \
-      groupmod -o -g ${PGID} www-data && \
-      usermod -o -u ${PUID} -g ${PGID} www-data && \
-      echo "Adjusted www-data to UID=${PUID}, GID=${PGID}"; \
-    fi
+# 把容器内 www-data 用户的 UID/GID 对齐宿主机，避免挂载目录里写出的文件属主不匹配。
+#
+# 这里修掉了原实现的两个坑：
+#   1. 原条件是 `PUID != 1000 || PGID != 1000`，而默认值本身就是 1000 ——
+#      等于默认配置下永远不执行，映射形同虚设。现在改为「与目标不一致才调整」。
+#   2. 原实现只用 debian 的 groupmod/usermod。用户若把基础镜像换成 alpine 版
+#      （如 php:8.2-fpm-alpine），构建会直接 `groupmod: not found` 失败。
+#      现在按可用命令分发两种改法。
+#
+# 只在与目标不一致时才改动，保证默认构建层可缓存。
+RUN set -eux; \
+    if [ "$(id -u www-data)" != "${PUID}" ] || [ "$(id -g www-data)" != "${PGID}" ]; then \
+      if command -v usermod >/dev/null 2>&1; then \
+        groupmod -o -g "${PGID}" www-data; \
+        usermod -o -u "${PUID}" -g "${PGID}" www-data; \
+      elif command -v adduser >/dev/null 2>&1; then \
+        deluser www-data; \
+        # alpine 的 deluser 会连带删掉同名组，delgroup 再删会报 unknown group
+        delgroup www-data 2>/dev/null || true; \
+        addgroup -g "${PGID}" www-data; \
+        adduser -u "${PUID}" -G www-data -s /bin/sh -D www-data; \
+      else \
+        echo "skip: 未识别的基础镜像，沿用镜像默认的 www-data 用户"; \
+      fi; \
+    fi; \
+    echo "www-data uid=$(id -u www-data) gid=$(id -g www-data)"
 
 WORKDIR /www
diff --git a/src-tauri/services/php85/Dockerfile b/src-tauri/services/php85/Dockerfile
index be3375f..f8496b3 100644
--- a/src-tauri/services/php85/Dockerfile
+++ b/src-tauri/services/php85/Dockerfile
@@ -57,11 +57,31 @@ RUN if [ -n "$COMPOSER_MIRROR" ] && [ "$COMPOSER_MIRROR" != "https://packagist.o
 ARG PUID=1000
 ARG PGID=1000
 
-# Dynamically adjust www-data user ID to match host
-RUN if [ "${PUID}" != "1000" ] || [ "${PGID}" != "1000" ]; then \
-      groupmod -o -g ${PGID} www-data && \
-      usermod -o -u ${PUID} -g ${PGID} www-data && \
-      echo "Adjusted www-data to UID=${PUID}, GID=${PGID}"; \
-    fi
+# 把容器内 www-data 用户的 UID/GID 对齐宿主机，避免挂载目录里写出的文件属主不匹配。
+#
+# 这里修掉了原实现的两个坑：
+#   1. 原条件是 `PUID != 1000 || PGID != 1000`，而默认值本身就是 1000 ——
+#      等于默认配置下永远不执行，映射形同虚设。现在改为「与目标不一致才调整」。
+#   2. 原实现只用 debian 的 groupmod/usermod。用户若把基础镜像换成 alpine 版
+#      （如 php:8.2-fpm-alpine），构建会直接 `groupmod: not found` 失败。
+#      现在按可用命令分发两种改法。
+#
+# 只在与目标不一致时才改动，保证默认构建层可缓存。
+RUN set -eux; \
+    if [ "$(id -u www-data)" != "${PUID}" ] || [ "$(id -g www-data)" != "${PGID}" ]; then \
+      if command -v usermod >/dev/null 2>&1; then \
+        groupmod -o -g "${PGID}" www-data; \
+        usermod -o -u "${PUID}" -g "${PGID}" www-data; \
+      elif command -v adduser >/dev/null 2>&1; then \
+        deluser www-data; \
+        # alpine 的 deluser 会连带删掉同名组，delgroup 再删会报 unknown group
+        delgroup www-data 2>/dev/null || true; \
+        addgroup -g "${PGID}" www-data; \
+        adduser -u "${PUID}" -G www-data -s /bin/sh -D www-data; \
+      else \
+        echo "skip: 未识别的基础镜像，沿用镜像默认的 www-data 用户"; \
+      fi; \
+    fi; \
+    echo "www-data uid=$(id -u www-data) gid=$(id -g www-data)"
 
 WORKDIR /www
diff --git a/src-tauri/src/commands/backup.rs b/src-tauri/src/commands/backup.rs
index ea1be90..b7cf31a 100644
--- a/src-tauri/src/commands/backup.rs
+++ b/src-tauri/src/commands/backup.rs
@@ -1,6 +1,7 @@
+use crate::app_log;
 use crate::engine::backup_engine::BackupEngine;
 use crate::engine::backup_manifest::BackupOptions;
-use crate::engine::restore_engine::{RestoreEngine, RestorePreview};
+use crate::engine::restore_engine::{RestoreEngine, RestorePreview, RestoreResult};
 
 use super::get_project_root;
 
@@ -51,46 +52,94 @@ pub fn verify_backup(zip_path: String) -> Result<bool, String> {
 }
 
 /// 执行环境恢复
+///
+/// 始终返回 `RestoreResult`（U2）：成功、部分失败、致命失败（包打不开 / zip-slip 等）
+/// 都走 `Ok`，把错误明细与回滚包路径交给前端结果面板。
+/// 仅工作区路径等命令前置失败才走 `Err`。
 #[tauri::command]
 pub async fn execute_restore(
     zip_path: String,
     app_handle: tauri::AppHandle,
-) -> Result<(), String> {
+) -> Result<RestoreResult, String> {
     let project_root = get_project_root()?;
-    let result = RestoreEngine::restore(
-        &zip_path,
-        &project_root,
-        Some(&app_handle),
-    )
-    .await?;
-
-    if result.success {
-        Ok(())
-    } else {
-        Err(format!(
-            "恢复完成但存在错误:\n{}",
-            result.errors.join("\n")
-        ))
-    }
+
+    // R2: 恢复是逐文件覆盖的破坏性操作，开始前先打一份回滚包
+    let rollback_path = create_rollback_bundle(&project_root).await;
+
+    let mut result = match RestoreEngine::restore(&zip_path, &project_root, Some(&app_handle)).await
+    {
+        Ok(r) => r,
+        // 致命错误也结构化返回：前端可渲染错误面板 + 回滚快捷入口，
+        // 不再把多行文案塞进 toast。
+        Err(e) => RestoreResult {
+            success: false,
+            restored_files: Vec::new(),
+            errors: vec![e],
+            rollback_path: None,
+        },
+    };
+
+    result.rollback_path = rollback_path;
+    Ok(result)
 }
 
-/// 选择项目文件夹并转换为相对路径
-#[tauri::command]
-pub fn select_project_folder() -> Result<Option<String>, String> {
-    // 实际的文件选择逻辑应该在前端通过 @tauri-apps/plugin-dialog 实现
-    // 这里仅作为占位符
-    Ok(None)
+/// 恢复前把即将被覆盖的配置文件打包成回滚包（R2）
+///
+/// 写入项目根目录 `.restore_rollback_<时间戳>.zip`，只打包配置文件
+/// （不含项目文件与日志），保证体积小、回滚快。
+/// 失败不阻断恢复——回滚包是兜底手段，没有它也允许用户继续。
+async fn create_rollback_bundle(project_root: &std::path::Path) -> Option<String> {
+    // 首次恢复场景：没有任何现有配置，不存在覆盖风险，跳过
+    let has_existing = project_root.join(".env").exists()
+        || project_root.join("docker-compose.yml").exists()
+        || project_root.join("services").exists();
+    if !has_existing {
+        return None;
+    }
+
+    let timestamp = chrono::Local::now().format("%Y%m%d_%H%M%S");
+    let save_path = project_root.join(format!(".restore_rollback_{timestamp}.zip"));
+    let options = BackupOptions {
+        include_projects: false,
+        project_patterns: Vec::new(),
+        include_logs: false,
+    };
+
+    match BackupEngine::create_backup(&save_path.to_string_lossy(), options, project_root, None)
+        .await
+    {
+        Ok(()) => {
+            app_log!(
+                info,
+                "commands::execute_restore",
+                "已生成恢复前回滚包: {}",
+                save_path.display()
+            );
+            Some(save_path.to_string_lossy().to_string())
+        }
+        Err(e) => {
+            app_log!(
+                warn,
+                "commands::execute_restore",
+                "生成回滚包失败（不阻断恢复）: {e}"
+            );
+            None
+        }
+    }
 }
 
 /// 将绝对路径转换为相对于项目根目录的路径
 #[tauri::command]
-pub fn convert_to_relative_path(absolute_path: String, is_directory: bool) -> Result<String, String> {
+pub fn convert_to_relative_path(
+    absolute_path: String,
+    is_directory: bool,
+) -> Result<String, String> {
     let project_root = get_project_root()?;
     let abs_path = std::path::PathBuf::from(&absolute_path);
-    
+
     // 使用 pathdiff 计算相对路径，它会自动处理跨平台差异（如 Windows 盘符）
     match pathdiff::diff_paths(&abs_path, &project_root) {
-        Some(relative) if relative.as_os_str().is_empty() || relative == std::path::PathBuf::from(".") => {
+        Some(relative) if relative.as_os_str().is_empty() || relative.as_os_str() == "." => {
             Err("不能选择项目根目录本身，请选择其子文件或子文件夹".to_string())
         }
         Some(relative) => {
@@ -102,7 +151,7 @@ pub fn convert_to_relative_path(absolute_path: String, is_directory: bool) -> Re
                     project_root.display()
                 ));
             }
-            
+
             // 统一转换为正斜杠
             let normalized = rel_str.replace('\\', "/");
             if is_directory {
@@ -114,3 +163,46 @@ pub fn convert_to_relative_path(absolute_path: String, is_directory: bool) -> Re
         None => Err("无法计算相对路径，请确保文件位于项目目录内".to_string()),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+
+    /// `create_rollback_bundle` 是 async，但内部只做文件 IO，
+    /// 用当前线程 runtime block 住即可。
+    fn block_on<F: std::future::Future>(fut: F) -> F::Output {
+        tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("创建 tokio runtime")
+            .block_on(fut)
+    }
+
+    #[test]
+    fn test_create_rollback_bundle_skips_empty_workspace() {
+        let dir = tempfile::tempdir().unwrap();
+        let result = block_on(create_rollback_bundle(dir.path()));
+        assert!(result.is_none(), "没有任何现有配置时不应生成回滚包");
+    }
+
+    #[test]
+    fn test_create_rollback_bundle_creates_valid_zip() {
+        let dir = tempfile::tempdir().unwrap();
+        fs::write(dir.path().join(".env"), "PHP82_VERSION=8.2\n").unwrap();
+
+        let result = block_on(create_rollback_bundle(dir.path()));
+        let path = result.expect("存在 .env 时应生成回滚包");
+
+        assert!(std::path::Path::new(&path).exists(), "回滚包文件应存在");
+        assert!(
+            path.contains(".restore_rollback_"),
+            "回滚包应带可识别的前缀，实际: {path}"
+        );
+
+        // 回滚包必须是合法 ZIP——否则用户真要回滚时才发现打不开
+        let file = fs::File::open(&path).expect("回滚包应可读");
+        let archive = zip::ZipArchive::new(file).expect("回滚包应是合法 ZIP");
+        assert!(!archive.is_empty(), "回滚包不应为空");
+    }
+}
diff --git a/src-tauri/src/commands/docker.rs b/src-tauri/src/commands/docker.rs
index f331598..3cc127e 100644
--- a/src-tauri/src/commands/docker.rs
+++ b/src-tauri/src/commands/docker.rs
@@ -10,7 +10,10 @@ pub async fn check_docker() -> Result<(), String> {
 pub async fn list_containers() -> Result<Vec<PsContainer>, String> {
     check_docker().await?;
     let manager = DockerManager::new().map_err(|e| e.to_string())?;
-    manager.list_ps_containers().await.map_err(|e| e.to_string())
+    manager
+        .list_ps_containers()
+        .await
+        .map_err(|e| e.to_string())
 }
 
 /// 获取所有运行中的容器（用于端口冲突检测）
@@ -18,26 +21,38 @@ pub async fn list_containers() -> Result<Vec<PsContainer>, String> {
 pub async fn list_all_running_containers() -> Result<Vec<PsContainer>, String> {
     check_docker().await?;
     let manager = DockerManager::new().map_err(|e| e.to_string())?;
-    manager.list_all_running_containers().await.map_err(|e| e.to_string())
+    manager
+        .list_all_running_containers()
+        .await
+        .map_err(|e| e.to_string())
 }
 
 #[tauri::command]
 pub async fn start_container(name: String) -> Result<(), String> {
     check_docker().await?;
     let manager = DockerManager::new().map_err(|e| e.to_string())?;
-    manager.start_container(&name).await.map_err(|e| e.to_string())
+    manager
+        .start_container(&name)
+        .await
+        .map_err(|e| e.to_string())
 }
 
 #[tauri::command]
 pub async fn stop_container(name: String) -> Result<(), String> {
     check_docker().await?;
     let manager = DockerManager::new().map_err(|e| e.to_string())?;
-    manager.stop_container(&name).await.map_err(|e| e.to_string())
+    manager
+        .stop_container(&name)
+        .await
+        .map_err(|e| e.to_string())
 }
 
 #[tauri::command]
 pub async fn restart_container(name: String) -> Result<(), String> {
     check_docker().await?;
     let manager = DockerManager::new().map_err(|e| e.to_string())?;
-    manager.restart_container(&name).await.map_err(|e| e.to_string())
+    manager
+        .restart_container(&name)
+        .await
+        .map_err(|e| e.to_string())
 }
diff --git a/src-tauri/src/commands/env_config.rs b/src-tauri/src/commands/env_config.rs
index 1ec9222..99fb3bc 100644
--- a/src-tauri/src/commands/env_config.rs
+++ b/src-tauri/src/commands/env_config.rs
@@ -1,11 +1,8 @@
+use super::get_project_root;
 use crate::docker::manager::DockerManager;
+use crate::engine::config_extractor::{ConfigExtractor, ExtractOutcome, ImageStatus};
 use crate::engine::config_generator::{ConfigGenerator, EnvConfig};
-use crate::engine::version_manifest::{VersionManifest, ServiceType as VmServiceType};
-use crate::engine::config_extractor::{
-    ConfigExtractor, ExtractOutcome, ImageStatus,
-};
-
-use super::get_project_root;
+use crate::engine::version_manifest::{ServiceType as VmServiceType, VersionManifest};
 
 /// 单个镜像拉取结果（前端"待拉取"确认弹窗使用）
 #[derive(Debug, Clone, serde::Serialize)]
@@ -16,39 +13,72 @@ pub struct PullImageResult {
     pub error: Option<String>,
 }
 
-/// 获取 Docker Compose 容器的最新日志（非阻塞）
+/// 把同步子进程调用挪到阻塞线程池执行（R3）
+///
+/// Tauri 命令跑在 async 执行线程上，同步的 `Command::output()` / `Child::wait()`
+/// 会把整条线程占住，同线程上的其它命令（容器列表轮询、镜像探测等）
+/// 会被一起拖慢。这里收敛成统一助手，与 `commands/backup.rs` 的既有做法对齐。
+async fn run_blocking_command<F, T>(f: F) -> Result<T, String>
+where
+    F: FnOnce() -> Result<T, String> + Send + 'static,
+    T: Send + 'static,
+{
+    tokio::task::spawn_blocking(f)
+        .await
+        .map_err(|e| format!("阻塞任务执行失败: {e}"))?
+}
+
+/// 获取 Docker Compose 容器的最新日志
 ///
 /// 使用 `docker compose logs --tail 100` 获取最近日志，
 /// 通过 skip_lines 跳过已处理的行，只返回新增内容。
-fn get_compose_logs(project_root: &std::path::Path, skip_lines: usize) -> Result<(Vec<String>, usize), String> {
-    use std::process::Command;
-    
-    let mut logs_cmd = Command::new("docker");
-    logs_cmd.args(["compose", "logs", "--tail", "100"])
-        .current_dir(project_root);
-    
-    #[cfg(windows)]
-    {
-        use std::os::windows::process::CommandExt;
-        logs_cmd.creation_flags(0x08000200);
-    }
-    
-    let output = logs_cmd.output().map_err(|e| format!("执行 docker compose logs 失败: {e}"))?;
-    
-    if !output.status.success() {
-        return Err(format!("docker compose logs 退出码: {:?}", output.status.code()));
-    }
-    
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    let all_lines: Vec<&str> = stdout.lines().collect();
-    let total_count = all_lines.len();
-    
-    let new_lines: Vec<String> = all_lines.iter()
-        .skip(skip_lines)
-        .map(|s| s.to_string())
-        .collect();
-    
-    Ok((new_lines, total_count))
+///
+/// 内部是同步子进程调用，已包进 `run_blocking_command`——本函数在启动流程中
+/// 最长 5 分钟内每 2 秒被调用一次，直接在 async 线程上跑会持续占用该线程。
+async fn get_compose_logs(
+    project_root: &std::path::Path,
+    skip_lines: usize,
+) -> Result<(Vec<String>, usize), String> {
+    let project_root = project_root.to_path_buf();
+
+    run_blocking_command(move || {
+        use std::process::Command;
+
+        let mut logs_cmd = Command::new("docker");
+        logs_cmd
+            .args(["compose", "logs", "--tail", "100"])
+            .current_dir(&project_root);
+
+        #[cfg(windows)]
+        {
+            use std::os::windows::process::CommandExt;
+            logs_cmd.creation_flags(0x08000200);
+        }
+
+        let output = logs_cmd
+            .output()
+            .map_err(|e| format!("执行 docker compose logs 失败: {e}"))?;
+
+        if !output.status.success() {
+            return Err(format!(
+                "docker compose logs 退出码: {:?}",
+                output.status.code()
+            ));
+        }
+
+        let stdout = String::from_utf8_lossy(&output.stdout);
+        let all_lines: Vec<&str> = stdout.lines().collect();
+        let total_count = all_lines.len();
+
+        let new_lines: Vec<String> = all_lines
+            .iter()
+            .skip(skip_lines)
+            .map(|s| s.to_string())
+            .collect();
+
+        Ok((new_lines, total_count))
+    })
+    .await
 }
 
 /// 解析 Docker Compose 输出，提取关键进度信息
@@ -60,40 +90,40 @@ fn parse_docker_progress(line: &str) -> Option<String> {
             return Some(format!("正在拉取镜像: {}", service));
         }
     }
-    
+
     // 下载进度: php Pulled
     if line.contains("Pulled") {
         if let Some(service) = extract_service_name(line, "Pulled") {
             return Some(format!("✅ 镜像拉取完成: {}", service));
         }
     }
-    
+
     // 构建镜像: Building php
     if line.contains("Building") {
         if let Some(service) = extract_service_name(line, "Building") {
             return Some(format!("🔨 正在构建镜像: {}", service));
         }
     }
-    
+
     // 创建容器: Creating ps-php-1 ... done
     if line.contains("Creating") {
         if let Some(service) = extract_service_name(line, "Creating") {
             return Some(format!("📦 正在创建容器: {}", service));
         }
     }
-    
+
     // 启动容器: Starting ps-php-1 ... done
     if line.contains("Starting") {
         if let Some(service) = extract_service_name(line, "Starting") {
             return Some(format!("🚀 正在启动服务: {}", service));
         }
     }
-    
+
     // 容器已存在: Container ps-php-1 is running
     if line.contains("is running") || line.contains("Up to date") {
         return Some("⚡ 服务已在运行".to_string());
     }
-    
+
     None
 }
 
@@ -121,31 +151,18 @@ pub fn validate_env_config(config: EnvConfig) -> Result<(), String> {
     ConfigGenerator::validate(&config)
 }
 
-/// 读取现有配置文件并解析为 EnvConfig
-#[tauri::command]
-pub fn load_existing_config() -> Result<Option<EnvConfig>, String> {
-    let project_root = get_project_root()?;
-    let env_path = project_root.join(".env");
-    let compose_path = project_root.join("docker-compose.yml");
-    
-    // 如果两个文件都不存在，返回 None
-    if !env_path.exists() || !compose_path.exists() {
-        return Ok(None);
-    }
-    
-    // 读取 .env 文件
-    let env_content = std::fs::read_to_string(&env_path)
-        .map_err(|e| format!("读取 .env 文件失败: {e}"))?;
-    let env_file = crate::engine::env_parser::EnvFile::parse(&env_content)
-        .map_err(|e| format!("解析 .env 文件失败: {e}"))?;
-    let env_map = env_file.to_map();
-    
-    // 解析服务配置
-    let mut services: Vec<crate::engine::config_generator::ServiceEntry> = Vec::new();
-    
-    // 创建 VersionManifest 用于 env prefix 反查
-    let manifest = VersionManifest::new();
-    
+/// 从 .env 变量映射解析出服务配置列表（纯函数，便于单元测试）
+///
+/// 按键名前缀（PHP82_VERSION / MYSQL80_VERSION / ...）识别多版本服务，
+/// 并通过 VersionManifest 反查版本 ID；未收录的前缀回退为小写 ID。
+fn parse_env_to_services(
+    env_map: &std::collections::HashMap<String, String>,
+    manifest: &VersionManifest,
+) -> Vec<crate::engine::config_generator::ServiceEntry> {
+    use crate::engine::config_generator::{ServiceEntry, ServiceType};
+
+    let mut services: Vec<ServiceEntry> = Vec::new();
+
     // 解析 PHP 服务（支持多版本）
     // 查找所有 PHPxx_VERSION 格式的键
     for key in env_map.keys() {
@@ -153,140 +170,183 @@ pub fn load_existing_config() -> Result<Option<EnvConfig>, String> {
             // 提取前缀，如 PHP82_VERSION → PHP82
             let prefix = &key[..key.len() - 8]; // 去掉 "_VERSION"
             let ver_part = &key[3..key.len() - 8]; // 去掉 "PHP" 和 "_VERSION"
-            
+
             if ver_part.is_empty() {
                 continue;
             }
-            
+
             // 使用 manifest 反查 ID，如 "PHP82" → "php82"
-            let version = manifest.find_entry_by_env_prefix(&VmServiceType::Php, prefix)
+            let version = manifest
+                .find_entry_by_env_prefix(&VmServiceType::Php, prefix)
                 .map(|(id, _)| id.clone())
                 .unwrap_or_else(|| prefix.to_lowercase());
-            
+
             let port_key = format!("PHP{ver_part}_HOST_PORT");
             let ext_key = format!("PHP{ver_part}_EXTENSIONS");
-            
-            let host_port = env_map.get(&port_key)
+
+            let host_port = env_map
+                .get(&port_key)
                 .and_then(|p| p.parse::<u16>().ok())
                 .unwrap_or(9000);
-            
-            let extensions = env_map.get(&ext_key)
+
+            let extensions = env_map
+                .get(&ext_key)
                 .map(|exts| exts.split(',').map(|s| s.trim().to_string()).collect());
-            
-            services.push(crate::engine::config_generator::ServiceEntry {
-                service_type: crate::engine::config_generator::ServiceType::PHP,
+
+            services.push(ServiceEntry {
+                service_type: ServiceType::PHP,
                 version,
                 host_port,
                 extensions,
             });
         }
     }
-    
+
     // 解析 MySQL 服务（支持多版本）
     let mut mysql_index = 0;
     for key in env_map.keys() {
-        if key.ends_with("_VERSION") && key.starts_with("MYSQL") && !key.contains("ROOT") && !key.contains("USER") && !key.contains("PASSWORD") {
+        if key.ends_with("_VERSION")
+            && key.starts_with("MYSQL")
+            && !key.contains("ROOT")
+            && !key.contains("USER")
+            && !key.contains("PASSWORD")
+        {
             let prefix = &key[..key.len() - 8];
             let index_part = &key[5..key.len() - 8];
-            
+
             if index_part.is_empty() {
                 continue;
             }
-            
+
             let idx = index_part.parse::<usize>().unwrap_or(mysql_index);
-            
-            let version = manifest.find_entry_by_env_prefix(&VmServiceType::Mysql, prefix)
+
+            let version = manifest
+                .find_entry_by_env_prefix(&VmServiceType::Mysql, prefix)
                 .map(|(id, _)| id.clone())
                 .unwrap_or_else(|| prefix.to_lowercase());
-            
+
             let port_key = format!("MYSQL{index_part}_HOST_PORT");
-            
-            let host_port = env_map.get(&port_key)
+
+            let host_port = env_map
+                .get(&port_key)
                 .and_then(|p| p.parse::<u16>().ok())
                 .unwrap_or(3306 + idx as u16);
-            
-            services.push(crate::engine::config_generator::ServiceEntry {
-                service_type: crate::engine::config_generator::ServiceType::MySQL,
+
+            services.push(ServiceEntry {
+                service_type: ServiceType::MySQL,
                 version,
                 host_port,
                 extensions: None,
             });
-            
+
             mysql_index += 1;
         }
     }
-    
+
     // 解析 Redis 服务（支持多版本）
     for key in env_map.keys() {
         if key.ends_with("_VERSION") && key.starts_with("REDIS") {
             let prefix = &key[..key.len() - 8];
             let index_part = &key[5..key.len() - 8];
-            
+
             if index_part.is_empty() {
                 continue;
             }
-            
-            let version = manifest.find_entry_by_env_prefix(&VmServiceType::Redis, prefix)
+
+            let version = manifest
+                .find_entry_by_env_prefix(&VmServiceType::Redis, prefix)
                 .map(|(id, _)| id.clone())
                 .unwrap_or_else(|| prefix.to_lowercase());
-            
+
             let port_key = format!("REDIS{index_part}_HOST_PORT");
-            
-            let host_port = env_map.get(&port_key)
+
+            let host_port = env_map
+                .get(&port_key)
                 .and_then(|p| p.parse::<u16>().ok())
                 .unwrap_or(6379);
-            
-            services.push(crate::engine::config_generator::ServiceEntry {
-                service_type: crate::engine::config_generator::ServiceType::Redis,
+
+            services.push(ServiceEntry {
+                service_type: ServiceType::Redis,
                 version,
                 host_port,
                 extensions: None,
             });
         }
     }
-    
+
     // 解析 Nginx 服务（支持多版本）
     for key in env_map.keys() {
         if key.ends_with("_VERSION") && key.starts_with("NGINX") {
             let prefix = &key[..key.len() - 8];
-            let index_part = &key[6..key.len() - 8]; // NGINX 是 5 个字母 + 1 = 6
-            
+            // NGINX 为 5 个字母（与 MYSQL/REDIS 一致），版本号从第 5 位开始
+            let index_part = &key[5..key.len() - 8];
+
             if index_part.is_empty() {
                 continue;
             }
-            
-            let version = manifest.find_entry_by_env_prefix(&VmServiceType::Nginx, prefix)
+
+            let version = manifest
+                .find_entry_by_env_prefix(&VmServiceType::Nginx, prefix)
                 .map(|(id, _)| id.clone())
                 .unwrap_or_else(|| prefix.to_lowercase());
-            
+
             let port_key = format!("NGINX{index_part}_HTTP_HOST_PORT");
-            
-            let host_port = env_map.get(&port_key)
+
+            let host_port = env_map
+                .get(&port_key)
                 .and_then(|p| p.parse::<u16>().ok())
                 .unwrap_or(80);
-            
-            services.push(crate::engine::config_generator::ServiceEntry {
-                service_type: crate::engine::config_generator::ServiceType::Nginx,
+
+            services.push(ServiceEntry {
+                service_type: ServiceType::Nginx,
                 version,
                 host_port,
                 extensions: None,
             });
         }
     }
-    
+
+    services
+}
+
+/// 读取现有配置文件并解析为 EnvConfig
+#[tauri::command]
+pub fn load_existing_config() -> Result<Option<EnvConfig>, String> {
+    let project_root = get_project_root()?;
+    let env_path = project_root.join(".env");
+    let compose_path = project_root.join("docker-compose.yml");
+
+    // 如果两个文件都不存在，返回 None
+    if !env_path.exists() || !compose_path.exists() {
+        return Ok(None);
+    }
+
+    // 读取 .env 文件
+    let env_content =
+        std::fs::read_to_string(&env_path).map_err(|e| format!("读取 .env 文件失败: {e}"))?;
+    let env_file = crate::engine::env_parser::EnvFile::parse(&env_content)
+        .map_err(|e| format!("解析 .env 文件失败: {e}"))?;
+    let env_map = env_file.to_map();
+
+    // 创建 VersionManifest 用于 env prefix 反查
+    let manifest = VersionManifest::new();
+    let services = parse_env_to_services(&env_map, &manifest);
+
     // 如果没有解析到任何服务，返回 None
     if services.is_empty() {
         return Ok(None);
     }
-    
-    let source_dir = env_map.get("SOURCE_DIR")
+
+    let source_dir = env_map
+        .get("SOURCE_DIR")
         .cloned()
         .unwrap_or_else(|| "./www".to_string());
-    let timezone = env_map.get("TZ")
+    let timezone = env_map
+        .get("TZ")
         .cloned()
         .unwrap_or_else(|| "Asia/Shanghai".to_string());
     let mysql_root_password = env_map.get("MYSQL_ROOT_PASSWORD").cloned();
-    
+
     Ok(Some(EnvConfig {
         services,
         source_dir,
@@ -315,67 +375,140 @@ pub fn preview_compose(config: EnvConfig) -> Result<String, String> {
 pub fn check_config_files_exist() -> Result<Vec<String>, String> {
     let project_root = get_project_root()?;
     let mut existing_files = Vec::new();
-    
+
     // 检查关键文件
     let files_to_check = [
         (".env", "环境配置文件"),
         ("docker-compose.yml", "Docker Compose 配置"),
     ];
-    
+
     for (filename, description) in &files_to_check {
         let file_path = project_root.join(filename);
         if file_path.exists() {
             existing_files.push(format!("{filename} ({description})"));
         }
     }
-    
+
     // 检查 services 目录
     let services_dir = project_root.join("services");
     if services_dir.exists() {
         existing_files.push("services/ (服务配置目录)".to_string());
     }
-    
+
     Ok(existing_files)
 }
 
 /// 应用配置（写入 .env、docker-compose.yml、创建目录）
 #[tauri::command]
-pub async fn apply_env_config(config: EnvConfig, enable_backup: bool, app_handle: tauri::AppHandle) -> Result<Vec<String>, String> {
-    use tauri::Emitter;
+pub async fn apply_env_config(
+    config: EnvConfig,
+    enable_backup: bool,
+    app_handle: tauri::AppHandle,
+) -> Result<Vec<String>, String> {
     use crate::ui_log;
-    
-    ui_log!(app_handle, info, "commands::apply_env_config", "📝 开始应用配置...");
-    
+    use tauri::Emitter;
+
+    ui_log!(
+        app_handle,
+        info,
+        "commands::apply_env_config",
+        "📝 开始应用配置..."
+    );
+
     let project_root = get_project_root()?;
-    ui_log!(app_handle, info, "commands::apply_env_config", "📁 项目根目录: {:?}", project_root);
-    
+    ui_log!(
+        app_handle,
+        info,
+        "commands::apply_env_config",
+        "📁 项目根目录: {:?}",
+        project_root
+    );
+
     // 检查用户覆盖配置
     let overrides_path = project_root.join(".user_version_overrides.json");
     if overrides_path.exists() {
-        ui_log!(app_handle, info, "commands::apply_env_config", "✅ 检测到用户版本覆盖配置");
+        ui_log!(
+            app_handle,
+            info,
+            "commands::apply_env_config",
+            "✅ 检测到用户版本覆盖配置"
+        );
     } else {
-        ui_log!(app_handle, info, "commands::apply_env_config", "ℹ️  未找到用户覆盖配置，使用默认配置");
+        ui_log!(
+            app_handle,
+            info,
+            "commands::apply_env_config",
+            "ℹ️  未找到用户覆盖配置，使用默认配置"
+        );
     }
-    
-    ui_log!(app_handle, info, "commands::apply_env_config", "🔧 验证配置...");
-    ui_log!(app_handle, info, "commands::apply_env_config", "📄 生成 .env 文件...");
-    ui_log!(app_handle, info, "commands::apply_env_config", "🐳 生成 docker-compose.yml...");
-    ui_log!(app_handle, info, "commands::apply_env_config", "📂 创建服务目录结构...");
-    
+
+    ui_log!(
+        app_handle,
+        info,
+        "commands::apply_env_config",
+        "🔧 验证配置..."
+    );
+    ui_log!(
+        app_handle,
+        info,
+        "commands::apply_env_config",
+        "📄 生成 .env 文件..."
+    );
+    ui_log!(
+        app_handle,
+        info,
+        "commands::apply_env_config",
+        "🐳 生成 docker-compose.yml..."
+    );
+    ui_log!(
+        app_handle,
+        info,
+        "commands::apply_env_config",
+        "📂 创建服务目录结构..."
+    );
+
     match ConfigGenerator::apply(&config, &project_root, enable_backup).await {
         Ok(backed_up_files) => {
             if !backed_up_files.is_empty() {
-                ui_log!(app_handle, info, "commands::apply_env_config", "💾 已备份 {} 个文件/目录", backed_up_files.len());
+                ui_log!(
+                    app_handle,
+                    info,
+                    "commands::apply_env_config",
+                    "💾 已备份 {} 个文件/目录",
+                    backed_up_files.len()
+                );
                 for file in &backed_up_files {
-                    ui_log!(app_handle, info, "commands::apply_env_config", "   - {}", file);
+                    ui_log!(
+                        app_handle,
+                        info,
+                        "commands::apply_env_config",
+                        "   - {}",
+                        file
+                    );
                 }
             }
-            ui_log!(app_handle, info, "commands::apply_env_config", "✅ 配置应用成功！");
-            ui_log!(app_handle, info, "commands::apply_env_config", "💡 提示：请重启容器使新配置生效");
+            ui_log!(
+                app_handle,
+                info,
+                "commands::apply_env_config",
+                "✅ 配置应用成功！"
+            );
+            ui_log!(
+                app_handle,
+                info,
+                "commands::apply_env_config",
+                "💡 提示：请重启容器使新配置生效"
+            );
             Ok(backed_up_files)
         }
         Err(e) => {
-            ui_log!(app_handle, error, "commands::apply_env_config", "❌ 配置应用失败: {}", e);
+            ui_log!(
+                app_handle,
+                error,
+                "commands::apply_env_config",
+                "❌ 配置应用失败: {}",
+                e
+            );
             Err(e)
         }
     }
@@ -427,12 +560,16 @@ pub fn check_service_images_presence(config: EnvConfig) -> Result<Vec<ImageStatu
 /// **一条失败不影响其他镜像**——返回每条的 success/error，前端可选择继续或回滚。
 /// `pull_service_images` 是 idempotent：本机已有镜像时 `docker pull` 本身是 no-op + 极快。
 #[tauri::command]
-pub fn pull_service_images(image_tags: Vec<String>) -> Result<Vec<PullImageResult>, String> {
+pub async fn pull_service_images(image_tags: Vec<String>) -> Result<Vec<PullImageResult>, String> {
     use crate::app_log;
 
     let mut results: Vec<PullImageResult> = Vec::with_capacity(image_tags.len());
-    for tag in &image_tags {
-        match ConfigExtractor::pull_image(tag) {
+    for tag in image_tags {
+        let tag_for_task = tag.clone();
+        // docker pull 会长时间阻塞（大镜像下载），必须走阻塞线程池，
+        // 否则 Tauri async runtime 的执行线程被占满，前端弹窗无响应。
+        let result = run_blocking_command(move || ConfigExtractor::pull_image(&tag_for_task)).await;
+        match result {
             Ok(()) => {
                 app_log!(
                     info,
@@ -441,7 +578,7 @@ pub fn pull_service_images(image_tags: Vec<String>) -> Result<Vec<PullImageResul
                     tag
                 );
                 results.push(PullImageResult {
-                    tag: tag.clone(),
+                    tag,
                     success: true,
                     error: None,
                 });
@@ -455,7 +592,7 @@ pub fn pull_service_images(image_tags: Vec<String>) -> Result<Vec<PullImageResul
                     e
                 );
                 results.push(PullImageResult {
-                    tag: tag.clone(),
+                    tag,
                     success: false,
                     error: Some(e),
                 });
@@ -501,211 +638,378 @@ pub fn extract_service_config(
         service_dir
     );
 
-    let outcome = ConfigExtractor::extract_config(
-        &vm_service_type,
-        &service_dir,
-        &image_tag,
-        &project_root,
-    );
+    let outcome =
+        ConfigExtractor::extract_config(&vm_service_type, &service_dir, &image_tag, &project_root);
     Ok(outcome)
 }
 
 /// 一键启动环境（docker compose up -d）
 #[tauri::command]
 pub async fn start_environment(app_handle: tauri::AppHandle) -> Result<String, String> {
+    use crate::ui_log;
     use std::process::Command;
     use tauri::Emitter;
-    use crate::ui_log;
-    
-    ui_log!(app_handle, info, "commands::start_environment", "🚀 开始启动环境...");
-    
+
+    ui_log!(
+        app_handle,
+        info,
+        "commands::start_environment",
+        "🚀 开始启动环境..."
+    );
+
     let project_root = get_project_root()?;
-    ui_log!(app_handle, info, "commands::start_environment", "📁 项目根目录: {:?}", project_root);
-    
+    ui_log!(
+        app_handle,
+        info,
+        "commands::start_environment",
+        "📁 项目根目录: {:?}",
+        project_root
+    );
+
     let compose_file = project_root.join("docker-compose.yml");
-    
+
     if !compose_file.exists() {
-        ui_log!(app_handle, info, "commands::start_environment", "❌ docker-compose.yml 文件不存在");
+        ui_log!(
+            app_handle,
+            info,
+            "commands::start_environment",
+            "❌ docker-compose.yml 文件不存在"
+        );
         return Err("docker-compose.yml 文件不存在，请先应用配置".to_string());
     }
-    
-    ui_log!(app_handle, info, "commands::start_environment", "✅ docker-compose.yml 存在");
-    
+
+    ui_log!(
+        app_handle,
+        info,
+        "commands::start_environment",
+        "✅ docker-compose.yml 存在"
+    );
+
     // 第一步：清理旧容器（避免名称冲突）
-    ui_log!(app_handle, info, "commands::start_environment", "🧹 清理旧容器...");
+    ui_log!(
+        app_handle,
+        info,
+        "commands::start_environment",
+        "🧹 清理旧容器..."
+    );
     let mut down_cmd = Command::new("docker");
-    down_cmd.args(["compose", "down", "--remove-orphans"])
+    down_cmd
+        .args(["compose", "down", "--remove-orphans"])
         .current_dir(&project_root);
-    
+
     #[cfg(windows)]
     {
         use std::os::windows::process::CommandExt;
         // CREATE_NEW_PROCESS_GROUP (0x00000200) | CREATE_NO_WINDOW (0x08000000)
         down_cmd.creation_flags(0x08000200);
     }
-    
-    let down_output = down_cmd.output().map_err(|e| {
-            let err_msg = format!("清理旧容器失败: {e}");
-            ui_log!(app_handle, info, "commands::start_environment", "⚠️ {}", err_msg);
-            err_msg
-        })?;
-    
+
+    // R3: docker compose down 是同步阻塞调用，挪到阻塞线程池
+    let down_output = run_blocking_command(move || {
+        down_cmd
+            .output()
+            .map_err(|e| format!("清理旧容器失败: {e}"))
+    })
+    .await
+    .map_err(|e| {
+        ui_log!(app_handle, info, "commands::start_environment", "⚠️ {}", e);
+        e
+    })?;
+
     if !down_output.status.success() {
         let stderr = String::from_utf8_lossy(&down_output.stderr);
-        ui_log!(app_handle, warn, "commands::start_environment", "清理警告: {}", stderr.lines().next().unwrap_or(""));
+        ui_log!(
+            app_handle,
+            warn,
+            "commands::start_environment",
+            "清理警告: {}",
+            stderr.lines().next().unwrap_or("")
+        );
     } else {
-        ui_log!(app_handle, info, "commands::start_environment", "✅ 旧容器已清理");
+        ui_log!(
+            app_handle,
+            info,
+            "commands::start_environment",
+            "✅ 旧容器已清理"
+        );
     }
-    
+
     // 等待 ps- 前缀的容器完全停止（最多等待 10 秒）
-    ui_log!(app_handle, info, "commands::start_environment", "⏳ 等待容器完全停止...");
+    ui_log!(
+        app_handle,
+        info,
+        "commands::start_environment",
+        "⏳ 等待容器完全停止..."
+    );
     let manager = DockerManager::new().map_err(|e| {
         let err_msg = format!("创建 Docker 管理器失败: {e}");
-        ui_log!(app_handle, info, "commands::start_environment", "❌ {}", err_msg);
+        ui_log!(
+            app_handle,
+            info,
+            "commands::start_environment",
+            "❌ {}",
+            err_msg
+        );
         err_msg
     })?;
-    
+
     for attempt in 1..=10 {
         let ps_containers = manager.list_ps_containers().await.map_err(|e| {
             let err_msg = format!("检查容器状态失败: {e}");
-            ui_log!(app_handle, info, "commands::start_environment", "❌ {}", err_msg);
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "❌ {}",
+                err_msg
+            );
             err_msg
         })?;
-        
+
         // 过滤出仍在运行的 ps- 容器
-        let running_ps_containers: Vec<_> = ps_containers.iter()
-            .filter(|c| c.state.to_lowercase().contains("running") || 
-                        c.state.to_lowercase().contains("up"))
+        let running_ps_containers: Vec<_> = ps_containers
+            .iter()
+            .filter(|c| c.state.is_running())
             .collect();
-        
+
         if running_ps_containers.is_empty() {
-            ui_log!(app_handle, info, "commands::start_environment", "✅ 所有 ps- 容器已完全停止");
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "✅ 所有 ps- 容器已完全停止"
+            );
             break;
         }
-        
+
         if attempt == 10 {
-            ui_log!(app_handle, warn, "commands::start_environment", "等待超时，仍有 {} 个容器未停止", running_ps_containers.len());
+            ui_log!(
+                app_handle,
+                warn,
+                "commands::start_environment",
+                "等待超时，仍有 {} 个容器未停止",
+                running_ps_containers.len()
+            );
             for container in &running_ps_containers {
-                ui_log!(app_handle, info, "commands::start_environment", "   - {} ({})", container.name, container.state);
+                ui_log!(
+                    app_handle,
+                    info,
+                    "commands::start_environment",
+                    "   - {} ({})",
+                    container.name,
+                    container.state
+                );
             }
         } else {
             tokio::time::sleep(std::time::Duration::from_secs(1)).await;
         }
     }
     ui_log!(app_handle, info, "commands::start_environment", "");
-    
+
     // 第二步：端口冲突检测
-    ui_log!(app_handle, info, "commands::start_environment", "🔍 检查端口冲突...");
-    
+    ui_log!(
+        app_handle,
+        info,
+        "commands::start_environment",
+        "🔍 检查端口冲突..."
+    );
+
     // 获取所有运行中的容器
     let manager = DockerManager::new().map_err(|e| {
         let err_msg = format!("创建 Docker 管理器失败: {e}");
-        ui_log!(app_handle, info, "commands::start_environment", "❌ {}", err_msg);
+        ui_log!(
+            app_handle,
+            info,
+            "commands::start_environment",
+            "❌ {}",
+            err_msg
+        );
         err_msg
     })?;
-    
+
     let all_containers = manager.list_all_running_containers().await.map_err(|e| {
         let err_msg = format!("获取容器列表失败: {e}");
-        ui_log!(app_handle, info, "commands::start_environment", "❌ {}", err_msg);
+        ui_log!(
+            app_handle,
+            info,
+            "commands::start_environment",
+            "❌ {}",
+            err_msg
+        );
         err_msg
     })?;
-    
+
     // 加载配置并检查端口
     let config_result = load_existing_config()?;
     if let Some(config) = config_result {
         let mut conflicts: Vec<(String, u16, String)> = Vec::new();
-        
+
         for service in &config.services {
             let port = service.host_port;
-            let service_name = format!("{:?}{}", service.service_type, service.version.replace('.', ""));
-            
+            let service_name = format!(
+                "{:?}{}",
+                service.service_type,
+                service.version.replace('.', "")
+            );
+
             // 检查是否有容器占用了这个端口
             for container in &all_containers {
                 if container.ports.contains(&(port as i32)) {
-                    conflicts.push((
-                        container.name.clone(),
-                        port,
-                        service_name.clone(),
-                    ));
+                    conflicts.push((container.name.clone(), port, service_name.clone()));
                     break;
                 }
             }
         }
-        
+
         if !conflicts.is_empty() {
-            ui_log!(app_handle, info, "commands::start_environment", "❌ 检测到端口冲突！");
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "❌ 检测到端口冲突！"
+            );
             ui_log!(app_handle, info, "commands::start_environment", "");
-            
+
             for (container_name, port, service_name) in &conflicts {
-                ui_log!(app_handle, info, "commands::start_environment", "   ❌ 端口 {} ({}) 被容器 {} 占用", port, service_name, container_name);
+                ui_log!(
+                    app_handle,
+                    info,
+                    "commands::start_environment",
+                    "   ❌ 端口 {} ({}) 被容器 {} 占用",
+                    port,
+                    service_name,
+                    container_name
+                );
             }
-            
+
             ui_log!(app_handle, info, "commands::start_environment", "");
-            ui_log!(app_handle, info, "commands::start_environment", "💡 解决方案：");
-            ui_log!(app_handle, info, "commands::start_environment", "   • 停止冲突容器: docker stop <容器名>");
-            ui_log!(app_handle, info, "commands::start_environment", "   • 或删除冲突容器: docker rm <容器名>");
-            ui_log!(app_handle, info, "commands::start_environment", "   • 或在环境配置中修改为其他端口");
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "💡 解决方案："
+            );
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "   • 停止冲突容器: docker stop <容器名>"
+            );
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "   • 或删除冲突容器: docker rm <容器名>"
+            );
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "   • 或在环境配置中修改为其他端口"
+            );
             ui_log!(app_handle, info, "commands::start_environment", "");
-            ui_log!(app_handle, info, "commands::start_environment", "⚠️ 请在前端解决冲突后重新启动");
-            
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "⚠️ 请在前端解决冲突后重新启动"
+            );
+
             // 返回错误，终止后续流程
-            let conflict_details: Vec<String> = conflicts.iter()
+            let conflict_details: Vec<String> = conflicts
+                .iter()
                 .map(|(name, port, service)| format!("端口 {port} ({service}) 被容器 {name} 占用"))
                 .collect();
-            
+
             return Err(format!("PORT_CONFLICT:{}", conflict_details.join("; ")));
         } else {
-            ui_log!(app_handle, info, "commands::start_environment", "✅ 没有检测到端口冲突");
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "✅ 没有检测到端口冲突"
+            );
         }
     } else {
-        ui_log!(app_handle, info, "commands::start_environment", "⚠️ 未找到配置文件，跳过端口检查");
+        ui_log!(
+            app_handle,
+            info,
+            "commands::start_environment",
+            "⚠️ 未找到配置文件，跳过端口检查"
+        );
     }
     ui_log!(app_handle, info, "commands::start_environment", "");
-    
+
     // 第二步：后台启动容器（spawn 模式，实时读取 build/pull 进度）
-    ui_log!(app_handle, info, "commands::start_environment", "🔧 执行: docker compose up -d");
-    ui_log!(app_handle, info, "commands::start_environment", "⏳ 首次启动可能需要几分钟(下载镜像、安装扩展)...");
+    ui_log!(
+        app_handle,
+        info,
+        "commands::start_environment",
+        "🔧 执行: docker compose up -d"
+    );
+    ui_log!(
+        app_handle,
+        info,
+        "commands::start_environment",
+        "⏳ 首次启动可能需要几分钟(下载镜像、安装扩展)..."
+    );
     ui_log!(app_handle, info, "commands::start_environment", "");
-    
+
     let mut compose_cmd = Command::new("docker");
-    compose_cmd.args(["compose", "up", "-d"])
+    compose_cmd
+        .args(["compose", "up", "-d"])
         .current_dir(&project_root)
         .stdout(std::process::Stdio::piped())
         .stderr(std::process::Stdio::piped());
-    
+
     #[cfg(windows)]
     {
         use std::os::windows::process::CommandExt;
         compose_cmd.creation_flags(0x08000200);
     }
-    
+
     // 使用 spawn 而非 output，这样 build/pull 过程中可以实时读取 stderr 进度
     let mut child = compose_cmd.spawn().map_err(|e| {
         let err_msg = format!("执行 docker compose 失败: {e}");
-        ui_log!(app_handle, info, "commands::start_environment", "❌ {}", err_msg);
+        ui_log!(
+            app_handle,
+            info,
+            "commands::start_environment",
+            "❌ {}",
+            err_msg
+        );
         err_msg
     })?;
-    
+
     let stdout_opt = child.stdout.take();
     let stderr_opt = child.stderr.take();
     let stderr_lines_shared = std::sync::Arc::new(std::sync::Mutex::new(Vec::<String>::new()));
-    
+
     // stdout 线程：读取容器创建信息
     let app_stdout = app_handle.clone();
-    let stdout_thread = stdout_opt.map(|stdout| std::thread::spawn(move || {
+    let stdout_thread = stdout_opt.map(|stdout| {
+        std::thread::spawn(move || {
             use std::io::{BufRead, BufReader};
             let reader = BufReader::new(stdout);
             for line in reader.lines().map_while(Result::ok) {
                 if !line.is_empty() {
-                    ui_log!(&app_stdout, info, "commands::start_environment", "   {}", line);
+                    ui_log!(
+                        &app_stdout,
+                        info,
+                        "commands::start_environment",
+                        "   {}",
+                        line
+                    );
                 }
             }
-        }));
-    
+        })
+    });
+
     // stderr 线程：读取 build/pull 进度（Docker Compose 的进度信息输出到 stderr）
     let app_stderr = app_handle.clone();
     let stderr_lines_clone = stderr_lines_shared.clone();
-    let stderr_thread = stderr_opt.map(|stderr| std::thread::spawn(move || {
+    let stderr_thread = stderr_opt.map(|stderr| {
+        std::thread::spawn(move || {
             use std::io::{BufRead, BufReader};
             let reader = BufReader::new(stderr);
             for line in reader.lines().map_while(Result::ok) {
@@ -713,112 +1017,277 @@ pub async fn start_environment(app_handle: tauri::AppHandle) -> Result<String, S
                     // 解析关键进度信息，添加 emoji
                     let progress_msg = parse_docker_progress(&line);
                     if let Some(msg) = progress_msg {
-                        ui_log!(&app_stderr, info, "commands::start_environment", "📦 {}", msg);
+                        ui_log!(
+                            &app_stderr,
+                            info,
+                            "commands::start_environment",
+                            "📦 {}",
+                            msg
+                        );
                     } else {
-                        ui_log!(&app_stderr, info, "commands::start_environment", "   {}", line);
+                        ui_log!(
+                            &app_stderr,
+                            info,
+                            "commands::start_environment",
+                            "   {}",
+                            line
+                        );
                     }
                     if let Ok(mut lines) = stderr_lines_clone.lock() {
                         lines.push(line);
                     }
                 }
             }
-        }));
-    
+        })
+    });
+
     // 等待 up -d 进程完成
-    let status = child.wait().map_err(|e| {
-        let err_msg = format!("等待 docker compose 完成失败: {e}");
-        ui_log!(app_handle, info, "commands::start_environment", "❌ {}", err_msg);
-        err_msg
+    // R3: child.wait() 会阻塞 async 线程直到 up -d 结束，同样挪走
+    let status = run_blocking_command(move || {
+        child
+            .wait()
+            .map_err(|e| format!("等待 docker compose 完成失败: {e}"))
+    })
+    .await
+    .map_err(|e| {
+        ui_log!(app_handle, info, "commands::start_environment", "❌ {}", e);
+        e
     })?;
-    
-    if let Some(t) = stdout_thread { let _ = t.join(); }
-    if let Some(t) = stderr_thread { let _ = t.join(); }
-    
+
+    if let Some(t) = stdout_thread {
+        let _ = t.join();
+    }
+    if let Some(t) = stderr_thread {
+        let _ = t.join();
+    }
+
     // 启动失败：详细分析错误类型
     if !status.success() {
-        let collected_stderr = stderr_lines_shared.lock()
+        let collected_stderr = stderr_lines_shared
+            .lock()
             .map(|l| l.join("\n"))
             .unwrap_or_default();
         let exit_code = status.code();
-        
-        let is_port_conflict = collected_stderr.contains("port is already allocated") 
-            || collected_stderr.contains("Bind for") 
+
+        let is_port_conflict = collected_stderr.contains("port is already allocated")
+            || collected_stderr.contains("Bind for")
             || collected_stderr.contains("address already in use");
-        
+
         if is_port_conflict {
-            ui_log!(app_handle, info, "commands::start_environment", "❌ 端口冲突 detected！");
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "❌ 端口冲突 detected！"
+            );
             ui_log!(app_handle, info, "commands::start_environment", "");
-            ui_log!(app_handle, info, "commands::start_environment", "💡 可能的原因：");
-            ui_log!(app_handle, info, "commands::start_environment", "   1. 其他 Docker 容器占用了相同端口");
-            ui_log!(app_handle, info, "commands::start_environment", "   2. 本地服务（如 MySQL、Nginx）正在运行");
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "💡 可能的原因："
+            );
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "   1. 其他 Docker 容器占用了相同端口"
+            );
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "   2. 本地服务（如 MySQL、Nginx）正在运行"
+            );
             ui_log!(app_handle, info, "commands::start_environment", "");
-            ui_log!(app_handle, info, "commands::start_environment", "🔧 解决方案：");
-            ui_log!(app_handle, info, "commands::start_environment", "   方案 1: 停止占用端口的容器");
-            ui_log!(app_handle, info, "commands::start_environment", "           docker ps  # 查看运行中的容器");
-            ui_log!(app_handle, info, "commands::start_environment", "           docker stop <容器名>");
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "🔧 解决方案："
+            );
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "   方案 1: 停止占用端口的容器"
+            );
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "           docker ps  # 查看运行中的容器"
+            );
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "           docker stop <容器名>"
+            );
             ui_log!(app_handle, info, "commands::start_environment", "");
-            ui_log!(app_handle, info, "commands::start_environment", "   方案 2: 修改 .env 文件中的端口配置");
-            ui_log!(app_handle, info, "commands::start_environment", "           例如：MYSQL_PORT=3307 (改为其他端口)");
-            ui_log!(app_handle, info, "commands::start_environment", "           然后重新应用配置");
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "   方案 2: 修改 .env 文件中的端口配置"
+            );
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "           例如：MYSQL_PORT=3307 (改为其他端口)"
+            );
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "           然后重新应用配置"
+            );
             ui_log!(app_handle, info, "commands::start_environment", "");
-            ui_log!(app_handle, info, "commands::start_environment", "   方案 3: 停止本地服务");
-            ui_log!(app_handle, info, "commands::start_environment", "           检查是否有本地 MySQL/Nginx/Redis 在运行");
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "   方案 3: 停止本地服务"
+            );
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "           检查是否有本地 MySQL/Nginx/Redis 在运行"
+            );
             ui_log!(app_handle, info, "commands::start_environment", "");
-            
+
             if let Some(line) = collected_stderr.lines().find(|l| l.contains("Bind for")) {
-                ui_log!(app_handle, info, "commands::start_environment", "📍 详细信息: {}", line.trim());
+                ui_log!(
+                    app_handle,
+                    info,
+                    "commands::start_environment",
+                    "📍 详细信息: {}",
+                    line.trim()
+                );
             }
         } else {
-            ui_log!(app_handle, info, "commands::start_environment", "❌ Docker Compose 启动失败，退出码: {:?}", exit_code);
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "❌ Docker Compose 启动失败，退出码: {:?}",
+                exit_code
+            );
             ui_log!(app_handle, info, "commands::start_environment", "");
-            ui_log!(app_handle, info, "commands::start_environment", "💡 建议检查：");
-            ui_log!(app_handle, info, "commands::start_environment", "   1. Docker Desktop 是否正常运行");
-            ui_log!(app_handle, info, "commands::start_environment", "   2. docker-compose.yml 文件格式是否正确");
-            ui_log!(app_handle, info, "commands::start_environment", "   3. 镜像是否存在或网络是否正常");
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "💡 建议检查："
+            );
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "   1. Docker Desktop 是否正常运行"
+            );
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "   2. docker-compose.yml 文件格式是否正确"
+            );
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "   3. 镜像是否存在或网络是否正常"
+            );
         }
-        
-        let err_msg = format!("Docker Compose 启动失败: {}", 
-            if is_port_conflict { "端口冲突" } else { "未知错误" });
+
+        let err_msg = format!(
+            "Docker Compose 启动失败: {}",
+            if is_port_conflict {
+                "端口冲突"
+            } else {
+                "未知错误"
+            }
+        );
         return Err(err_msg);
     }
-    
-    ui_log!(app_handle, info, "commands::start_environment", "✅ 容器已在后台启动");
+
+    ui_log!(
+        app_handle,
+        info,
+        "commands::start_environment",
+        "✅ 容器已在后台启动"
+    );
     ui_log!(app_handle, info, "commands::start_environment", "");
-    
+
     // 第三步：轮询容器运行日志 + 检查就绪状态
-    ui_log!(app_handle, info, "commands::start_environment", "📜 开始监控容器启动日志...");
-    
+    ui_log!(
+        app_handle,
+        info,
+        "commands::start_environment",
+        "📜 开始监控容器启动日志..."
+    );
+
     let docker_manager = match DockerManager::new() {
         Ok(manager) => manager,
         Err(e) => {
-            ui_log!(app_handle, warn, "commands::start_environment", "⚠️ 无法创建 DockerManager: {}", e);
-            ui_log!(app_handle, info, "commands::start_environment", "⚠️ 跳过日志监控，直接返回");
+            ui_log!(
+                app_handle,
+                warn,
+                "commands::start_environment",
+                "⚠️ 无法创建 DockerManager: {}",
+                e
+            );
+            ui_log!(
+                app_handle,
+                info,
+                "commands::start_environment",
+                "⚠️ 跳过日志监控，直接返回"
+            );
             return Ok("环境启动成功（未检查容器状态）".to_string());
         }
     };
-    
+
     let mut last_line_count: usize = 0;
     let mut consecutive_failures: u32 = 0;
     let max_consecutive_failures = 10;
     let start_time = std::time::Instant::now();
     let max_wait = std::time::Duration::from_secs(300);
-    
+
     loop {
         if start_time.elapsed() > max_wait {
-            ui_log!(app_handle, warn, "commands::start_environment", "⚠️ 等待容器就绪超时（5 分钟），跳过日志监控");
+            ui_log!(
+                app_handle,
+                warn,
+                "commands::start_environment",
+                "⚠️ 等待容器就绪超时（5 分钟），跳过日志监控"
+            );
             break;
         }
-        
+
         // 1. 获取最新的容器日志
-        match get_compose_logs(&project_root, last_line_count) {
+        match get_compose_logs(&project_root, last_line_count).await {
             Ok((new_lines, total_count)) => {
                 if !new_lines.is_empty() {
                     for line in &new_lines {
                         let progress_msg = parse_docker_progress(line);
                         if let Some(msg) = progress_msg {
-                            ui_log!(app_handle, info, "commands::start_environment", "📦 {}", msg);
+                            ui_log!(
+                                app_handle,
+                                info,
+                                "commands::start_environment",
+                                "📦 {}",
+                                msg
+                            );
                         } else {
-                            ui_log!(app_handle, info, "commands::start_environment", "   {}", line);
+                            ui_log!(
+                                app_handle,
+                                info,
+                                "commands::start_environment",
+                                "   {}",
+                                line
+                            );
                         }
                     }
                     last_line_count = total_count;
@@ -828,25 +1297,48 @@ pub async fn start_environment(app_handle: tauri::AppHandle) -> Result<String, S
             Err(e) => {
                 consecutive_failures += 1;
                 if consecutive_failures >= max_consecutive_failures {
-                    ui_log!(app_handle, warn, "commands::start_environment", 
-                        "⚠️ 连续 {} 次获取日志失败，跳过日志监控: {}", 
-                        consecutive_failures, e);
+                    ui_log!(
+                        app_handle,
+                        warn,
+                        "commands::start_environment",
+                        "⚠️ 连续 {} 次获取日志失败，跳过日志监控: {}",
+                        consecutive_failures,
+                        e
+                    );
                     break;
                 }
             }
         }
-        
+
         // 2. 检查所有容器是否就绪
         match docker_manager.check_all_ps_containers_running().await {
             Ok(true) => {
-                ui_log!(app_handle, info, "commands::start_environment", "✅ 所有容器已就绪");
-                if let Ok((final_lines, _)) = get_compose_logs(&project_root, last_line_count) {
+                ui_log!(
+                    app_handle,
+                    info,
+                    "commands::start_environment",
+                    "✅ 所有容器已就绪"
+                );
+                if let Ok((final_lines, _)) = get_compose_logs(&project_root, last_line_count).await
+                {
                     for line in &final_lines {
                         let progress_msg = parse_docker_progress(line);
                         if let Some(msg) = progress_msg {
-                            ui_log!(app_handle, info, "commands::start_environment", "📦 {}", msg);
+                            ui_log!(
+                                app_handle,
+                                info,
+                                "commands::start_environment",
+                                "📦 {}",
+                                msg
+                            );
                         } else {
-                            ui_log!(app_handle, info, "commands::start_environment", "   {}", line);
+                            ui_log!(
+                                app_handle,
+                                info,
+                                "commands::start_environment",
+                                "   {}",
+                                line
+                            );
                         }
                     }
                 }
@@ -854,219 +1346,390 @@ pub async fn start_environment(app_handle: tauri::AppHandle) -> Result<String, S
             }
             Ok(false) => {}
             Err(e) => {
-                ui_log!(app_handle, warn, "commands::start_environment", "⚠️ 检查容器状态失败: {}", e);
+                ui_log!(
+                    app_handle,
+                    warn,
+                    "commands::start_environment",
+                    "⚠️ 检查容器状态失败: {}",
+                    e
+                );
             }
         }
-        
+
         // 3. 每 2 秒检查一次
         tokio::time::sleep(std::time::Duration::from_secs(2)).await;
     }
-    
-    ui_log!(app_handle, info, "commands::start_environment", "✅ 环境启动成功！");
+
+    ui_log!(
+        app_handle,
+        info,
+        "commands::start_environment",
+        "✅ 环境启动成功！"
+    );
     Ok("环境启动成功".to_string())
 }
 
 /// 一键重启环境（docker compose restart）
 #[tauri::command]
 pub async fn restart_environment(app_handle: tauri::AppHandle) -> Result<String, String> {
+    use crate::ui_log;
     use std::process::Command;
     use tauri::Emitter;
-    use crate::ui_log;
-    
-    ui_log!(app_handle, info, "commands::restart_environment", "🔄 开始重启环境...");
-    
+
+    ui_log!(
+        app_handle,
+        info,
+        "commands::restart_environment",
+        "🔄 开始重启环境..."
+    );
+
     let project_root = get_project_root()?;
-    ui_log!(app_handle, info, "commands::restart_environment", "📁 项目根目录: {:?}", project_root);
-    
+    ui_log!(
+        app_handle,
+        info,
+        "commands::restart_environment",
+        "📁 项目根目录: {:?}",
+        project_root
+    );
+
     let compose_file = project_root.join("docker-compose.yml");
-    
+
     if !compose_file.exists() {
-        ui_log!(app_handle, info, "commands::restart_environment", "❌ docker-compose.yml 文件不存在");
+        ui_log!(
+            app_handle,
+            info,
+            "commands::restart_environment",
+            "❌ docker-compose.yml 文件不存在"
+        );
         return Err("docker-compose.yml 文件不存在，请先应用配置".to_string());
     }
-    
-    ui_log!(app_handle, info, "commands::restart_environment", "✅ docker-compose.yml 存在");
-    
+
+    ui_log!(
+        app_handle,
+        info,
+        "commands::restart_environment",
+        "✅ docker-compose.yml 存在"
+    );
+
     // 使用 docker compose restart 重启所有容器
-    ui_log!(app_handle, info, "commands::restart_environment", "🔧 执行: docker compose restart");
-    
+    ui_log!(
+        app_handle,
+        info,
+        "commands::restart_environment",
+        "🔧 执行: docker compose restart"
+    );
+
     let mut restart_cmd = Command::new("docker");
-    restart_cmd.args(["compose", "restart"])
+    restart_cmd
+        .args(["compose", "restart"])
         .current_dir(&project_root);
-    
+
     #[cfg(windows)]
     {
         use std::os::windows::process::CommandExt;
         // CREATE_NEW_PROCESS_GROUP (0x00000200) | CREATE_NO_WINDOW (0x08000000)
         restart_cmd.creation_flags(0x08000200);
     }
-    
+
     let output = restart_cmd.output().map_err(|e| {
-            let err_msg = format!("执行 docker compose restart 失败: {e}");
-            ui_log!(app_handle, info, "commands::restart_environment", "❌ {}", err_msg);
+        let err_msg = format!("执行 docker compose restart 失败: {e}");
+        ui_log!(
+            app_handle,
+            info,
+            "commands::restart_environment",
+            "❌ {}",
             err_msg
-        })?;
-    
+        );
+        err_msg
+    })?;
+
     let stdout = String::from_utf8_lossy(&output.stdout);
     let stderr = String::from_utf8_lossy(&output.stderr);
-    
+
     if !output.status.success() {
-        ui_log!(app_handle, info, "commands::restart_environment", "❌ 重启失败");
-        ui_log!(app_handle, info, "commands::restart_environment", "错误输出: {}", stderr);
+        ui_log!(
+            app_handle,
+            info,
+            "commands::restart_environment",
+            "❌ 重启失败"
+        );
+        ui_log!(
+            app_handle,
+            info,
+            "commands::restart_environment",
+            "错误输出: {}",
+            stderr
+        );
         return Err(format!("Docker Compose 重启失败: {stderr}"));
     }
-    
+
     // 记录重启结果
     if !stdout.is_empty() {
         for line in stdout.lines() {
             if !line.is_empty() {
-                ui_log!(app_handle, info, "commands::restart_environment", "   {}", line);
+                ui_log!(
+                    app_handle,
+                    info,
+                    "commands::restart_environment",
+                    "   {}",
+                    line
+                );
             }
         }
     }
-    
-    ui_log!(app_handle, info, "commands::restart_environment", "✅ 环境重启成功！");
+
+    ui_log!(
+        app_handle,
+        info,
+        "commands::restart_environment",
+        "✅ 环境重启成功！"
+    );
     Ok("环境重启成功".to_string())
 }
 
 /// 一键停止环境（docker compose stop）
 #[tauri::command]
 pub async fn stop_environment(app_handle: tauri::AppHandle) -> Result<String, String> {
+    use crate::ui_log;
     use std::process::Command;
     use tauri::Emitter;
-    use crate::ui_log;
-    
-    ui_log!(app_handle, info, "commands::stop_environment", "🛑 开始停止环境...");
-    
+
+    ui_log!(
+        app_handle,
+        info,
+        "commands::stop_environment",
+        "🛑 开始停止环境..."
+    );
+
     let project_root = get_project_root()?;
-    ui_log!(app_handle, info, "commands::stop_environment", "📁 项目根目录: {:?}", project_root);
-    
+    ui_log!(
+        app_handle,
+        info,
+        "commands::stop_environment",
+        "📁 项目根目录: {:?}",
+        project_root
+    );
+
     let compose_file = project_root.join("docker-compose.yml");
-    
+
     if !compose_file.exists() {
-        ui_log!(app_handle, info, "commands::stop_environment", "❌ docker-compose.yml 文件不存在");
+        ui_log!(
+            app_handle,
+            info,
+            "commands::stop_environment",
+            "❌ docker-compose.yml 文件不存在"
+        );
         return Err("docker-compose.yml 文件不存在，请先应用配置".to_string());
     }
-    
-    ui_log!(app_handle, info, "commands::stop_environment", "✅ docker-compose.yml 存在");
-    
+
+    ui_log!(
+        app_handle,
+        info,
+        "commands::stop_environment",
+        "✅ docker-compose.yml 存在"
+    );
+
     // 使用 docker compose stop 停止容器（保留容器，前端可显示"已停用"状态）
-    ui_log!(app_handle, info, "commands::stop_environment", "🔧 执行: docker compose stop");
-    
+    ui_log!(
+        app_handle,
+        info,
+        "commands::stop_environment",
+        "🔧 执行: docker compose stop"
+    );
+
     let mut stop_cmd = Command::new("docker");
-    stop_cmd.args(["compose", "stop"])
+    stop_cmd
+        .args(["compose", "stop"])
         .current_dir(&project_root);
-    
+
     #[cfg(windows)]
     {
         use std::os::windows::process::CommandExt;
         // CREATE_NEW_PROCESS_GROUP (0x00000200) | CREATE_NO_WINDOW (0x08000000)
         stop_cmd.creation_flags(0x08000200);
     }
-    
+
     let output = stop_cmd.output().map_err(|e| {
-            let err_msg = format!("执行 docker compose stop 失败: {e}");
-            ui_log!(app_handle, info, "commands::stop_environment", "❌ {}", err_msg);
+        let err_msg = format!("执行 docker compose stop 失败: {e}");
+        ui_log!(
+            app_handle,
+            info,
+            "commands::stop_environment",
+            "❌ {}",
             err_msg
-        })?;
-    
+        );
+        err_msg
+    })?;
+
     let stdout = String::from_utf8_lossy(&output.stdout);
     let stderr = String::from_utf8_lossy(&output.stderr);
-    
+
     if !output.status.success() {
-        ui_log!(app_handle, info, "commands::stop_environment", "❌ 停止失败");
-        ui_log!(app_handle, info, "commands::stop_environment", "错误输出: {}", stderr);
+        ui_log!(
+            app_handle,
+            info,
+            "commands::stop_environment",
+            "❌ 停止失败"
+        );
+        ui_log!(
+            app_handle,
+            info,
+            "commands::stop_environment",
+            "错误输出: {}",
+            stderr
+        );
         return Err(format!("Docker Compose 停止失败: {stderr}"));
     }
-    
+
     // 记录停止结果
     if !stdout.is_empty() {
         for line in stdout.lines() {
             if !line.is_empty() {
-                ui_log!(app_handle, info, "commands::stop_environment", "   {}", line);
+                ui_log!(
+                    app_handle,
+                    info,
+                    "commands::stop_environment",
+                    "   {}",
+                    line
+                );
             }
         }
     }
-    
-    ui_log!(app_handle, info, "commands::stop_environment", "✅ 环境停止成功！");
+
+    ui_log!(
+        app_handle,
+        info,
+        "commands::stop_environment",
+        "✅ 环境停止成功！"
+    );
     Ok("环境停止成功".to_string())
 }
 
 #[cfg(test)]
 mod tests {
+    use super::parse_env_to_services;
+    use super::run_blocking_command;
     use super::PullImageResult;
-    use std::fs;
+    use crate::engine::config_generator::ServiceType;
+    use crate::engine::env_parser::EnvFile;
+    use crate::engine::version_manifest::VersionManifest;
 
-    /// 测试 load_existing_config 解析多版本 Redis
+    /// R3: 同步阻塞调用统一走 `run_blocking_command`。
+    /// 「在阻塞线程池执行」由 tokio 保证，这里锁住的是对外契约：
+    /// 闭包的成功/失败结果必须原样透传给调用方，不能被包装或吞掉。
     #[test]
-    fn test_load_existing_config_multi_redis() {
-        // 创建临时目录
-        let temp_dir = std::env::temp_dir().join("php_stack_test_multi_redis");
-        fs::create_dir_all(&temp_dir).unwrap();
-        
-        // 创建测试 .env 文件
-        let env_content = r#"SOURCE_DIR=./www
-TZ=Asia/Shanghai
-REDIS62_VERSION=6.2-alpine-01
-REDIS62_HOST_PORT=6379
-REDIS72_VERSION=7.2-alpine
-REDIS72_HOST_PORT=6380
-"#;
-        fs::write(temp_dir.join(".env"), env_content).unwrap();
-        
-        // 创建空的 docker-compose.yml
-        fs::write(temp_dir.join("docker-compose.yml"), "version: '3'\nservices: {}\n").unwrap();
-        
-        // 临时修改 project_root（这里无法直接测试，因为 get_project_root 是硬编码的）
-        // 所以这个测试主要用于验证解析逻辑
-        
-        // 清理
-        fs::remove_dir_all(&temp_dir).ok();
+    fn test_run_blocking_command_passes_through_result() {
+        let rt = tokio::runtime::Builder::new_multi_thread()
+            .enable_all()
+            .build()
+            .expect("创建多线程 runtime");
+
+        let ok: Result<i32, String> = rt.block_on(run_blocking_command(|| Ok(42)));
+        assert_eq!(ok.expect("成功分支应返回值"), 42);
+
+        let err: Result<i32, String> =
+            rt.block_on(run_blocking_command(|| Err("boom".to_string())));
+        assert_eq!(err.expect_err("失败分支应返回错误"), "boom");
     }
 
-    /// 测试 load_existing_config 解析多版本 Nginx
+    fn parse_env(content: &str) -> std::collections::HashMap<String, String> {
+        EnvFile::parse(content)
+            .expect("解析 .env 内容失败")
+            .to_map()
+    }
+
+    /// 测试解析多版本 Redis
     #[test]
-    fn test_load_existing_config_multi_nginx() {
-        let temp_dir = std::env::temp_dir().join("php_stack_test_multi_nginx");
-        fs::create_dir_all(&temp_dir).unwrap();
-        
-        let env_content = r#"SOURCE_DIR=./www
-TZ=Asia/Shanghai
-NGINX127_VERSION=1.27-alpine
-NGINX127_HTTP_HOST_PORT=80
-NGINX125_VERSION=1.25-alpine
-NGINX125_HTTP_HOST_PORT=8080
-"#;
-        fs::write(temp_dir.join(".env"), env_content).unwrap();
-        fs::write(temp_dir.join("docker-compose.yml"), "version: '3'\nservices: {}\n").unwrap();
-        
-        fs::remove_dir_all(&temp_dir).ok();
+    fn test_parse_env_to_services_multi_redis() {
+        let env_map = parse_env(
+            "SOURCE_DIR=./www\nTZ=Asia/Shanghai\nREDIS62_VERSION=6.2-alpine-01\nREDIS62_HOST_PORT=6379\nREDIS72_VERSION=7.2-alpine\nREDIS72_HOST_PORT=6380\n",
+        );
+        let manifest = VersionManifest::new();
+        let services = parse_env_to_services(&env_map, &manifest);
+
+        let redis: Vec<_> = services
+            .iter()
+            .filter(|s| matches!(s.service_type, ServiceType::Redis))
+            .collect();
+        assert_eq!(
+            redis.len(),
+            2,
+            "应解析出 2 个 Redis 服务，实际: {services:?}"
+        );
+
+        let ports: Vec<u16> = redis.iter().map(|s| s.host_port).collect();
+        assert!(ports.contains(&6379), "REDIS62 端口应为 6379");
+        assert!(ports.contains(&6380), "REDIS72 端口应为 6380");
     }
 
-    /// 测试 load_existing_config 解析混合服务
+    /// 测试解析多版本 Nginx
     #[test]
-    fn test_load_existing_config_mixed_services() {
-        let temp_dir = std::env::temp_dir().join("php_stack_test_mixed");
-        fs::create_dir_all(&temp_dir).unwrap();
-        
-        let env_content = r#"SOURCE_DIR=./www
-TZ=Asia/Shanghai
-PHP85_VERSION=8.5
-PHP85_HOST_PORT=9000
-PHP85_EXTENSIONS=mysqli,mbstring
-MYSQL84_VERSION=8.4
-MYSQL84_HOST_PORT=3306
-REDIS62_VERSION=6.2-alpine-01
-REDIS62_HOST_PORT=6379
-NGINX127_VERSION=1.27-alpine
-NGINX127_HTTP_HOST_PORT=80
-"#;
-        fs::write(temp_dir.join(".env"), env_content).unwrap();
-        fs::write(temp_dir.join("docker-compose.yml"), "version: '3'\nservices: {}\n").unwrap();
-        
-        fs::remove_dir_all(&temp_dir).ok();
+    fn test_parse_env_to_services_multi_nginx() {
+        let env_map = parse_env(
+            "SOURCE_DIR=./www\nTZ=Asia/Shanghai\nNGINX127_VERSION=1.27-alpine\nNGINX127_HTTP_HOST_PORT=80\nNGINX125_VERSION=1.25-alpine\nNGINX125_HTTP_HOST_PORT=8080\n",
+        );
+        let manifest = VersionManifest::new();
+        let services = parse_env_to_services(&env_map, &manifest);
+
+        let nginx: Vec<_> = services
+            .iter()
+            .filter(|s| matches!(s.service_type, ServiceType::Nginx))
+            .collect();
+        assert_eq!(
+            nginx.len(),
+            2,
+            "应解析出 2 个 Nginx 服务，实际: {services:?}"
+        );
+
+        let ports: Vec<u16> = nginx.iter().map(|s| s.host_port).collect();
+        assert!(ports.contains(&80), "NGINX127 端口应为 80");
+        assert!(ports.contains(&8080), "NGINX125 端口应为 8080");
+
+        // manifest 收录的版本应反查出 ID，未收录的回退为小写前缀
+        let ids: Vec<&str> = nginx.iter().map(|s| s.version.as_str()).collect();
+        assert!(ids.contains(&"nginx127"), "NGINX127 应反查为 ID nginx127");
+        assert!(ids.contains(&"nginx125"), "NGINX125 应反查为 ID nginx125");
     }
 
+    /// 测试解析混合服务（含 manifest 未收录的 PHP85 回退路径）
+    #[test]
+    fn test_parse_env_to_services_mixed_services() {
+        let env_map = parse_env(
+            "SOURCE_DIR=./www\nTZ=Asia/Shanghai\nPHP85_VERSION=8.5\nPHP85_HOST_PORT=9000\nPHP85_EXTENSIONS=mysqli,mbstring\nMYSQL84_VERSION=8.4\nMYSQL84_HOST_PORT=3306\nREDIS62_VERSION=6.2-alpine-01\nREDIS62_HOST_PORT=6379\nNGINX127_VERSION=1.27-alpine\nNGINX127_HTTP_HOST_PORT=80\n",
+        );
+        let manifest = VersionManifest::new();
+        let services = parse_env_to_services(&env_map, &manifest);
+
+        assert_eq!(services.len(), 4, "应解析出 4 个服务，实际: {services:?}");
+
+        let php = services
+            .iter()
+            .find(|s| matches!(s.service_type, ServiceType::PHP))
+            .expect("应包含 PHP 服务");
+        assert_eq!(php.version, "php85", "未收录的 PHP85 应回退为小写前缀");
+        assert_eq!(php.host_port, 9000);
+        let php_exts = php.extensions.as_ref().expect("PHP 服务应有扩展列表");
+        assert_eq!(
+            php_exts,
+            &["mysqli".to_string(), "mbstring".to_string()],
+            "扩展列表应按逗号拆分"
+        );
+
+        let mysql = services
+            .iter()
+            .find(|s| matches!(s.service_type, ServiceType::MySQL))
+            .expect("应包含 MySQL 服务");
+        assert_eq!(mysql.version, "mysql84");
+        assert_eq!(mysql.host_port, 3306);
+
+        // MYSQL_ROOT_PASSWORD 不应被误识别为 MySQL 服务
+        let with_root = parse_env("MYSQL_ROOT_PASSWORD=secret\n");
+        let no_services = parse_env_to_services(&with_root, &VersionManifest::new());
+        assert!(
+            no_services.is_empty(),
+            "仅 ROOT_PASSWORD 时不应解析出服务，实际: {no_services:?}"
+        );
+    }
     // ─── 前后端 serde 契约 ──────────────────────────────────────
     // 前端 `PullImageResultItem` 按 `success` 判定成功/失败、按 `error` 展示原因。
     // pull_service_images 的失败是「部分失败也继续」语义，因此 error 字段的
diff --git a/src-tauri/src/commands/mirror.rs b/src-tauri/src/commands/mirror.rs
index 3ffd551..7825562 100644
--- a/src-tauri/src/commands/mirror.rs
+++ b/src-tauri/src/commands/mirror.rs
@@ -1,5 +1,5 @@
+use crate::engine::mirror_config_manager::{MergedMirrorCategory, MirrorConfigManager};
 use crate::engine::mirror_manager::{MirrorManager as UnifiedMirrorManager, MirrorPreset};
-use crate::engine::mirror_config_manager::{MirrorConfigManager, MergedMirrorCategory};
 
 use super::get_project_root;
 
@@ -32,10 +32,10 @@ pub async fn apply_mirror_preset(preset_name: String) -> Result<(), String> {
 pub fn update_single_mirror(category: String, source: String) -> Result<(), String> {
     let project_root = get_project_root()?;
     let env_path = project_root.join(".env");
-    
+
     // 标准化镜像源地址（去除尾部斜杠）
     let normalized_source = normalize_mirror_url(&source);
-    
+
     UnifiedMirrorManager::update_single(&category, &normalized_source, &env_path)
 }
 
@@ -51,8 +51,7 @@ pub fn get_mirror_status() -> Result<serde_json::Value, String> {
     let project_root = get_project_root()?;
     let env_path = project_root.join(".env");
     let status = UnifiedMirrorManager::get_current_status(&env_path)?;
-    serde_json::to_value(&status)
-        .map_err(|e| format!("序列化镜像源状态失败: {e}"))
+    serde_json::to_value(&status).map_err(|e| format!("序列化镜像源状态失败: {e}"))
 }
 
 /// 获取当前匹配的预设名称
@@ -74,10 +73,7 @@ pub fn get_merged_mirror_list() -> Result<Vec<MergedMirrorCategory>, String> {
 
 /// 保存用户选择的镜像源选项
 #[tauri::command]
-pub fn save_selected_mirror_option(
-    category_id: String,
-    option_id: String,
-) -> Result<(), String> {
+pub fn save_selected_mirror_option(category_id: String, option_id: String) -> Result<(), String> {
     let project_root = get_project_root()?;
     MirrorConfigManager::save_selected_option(&project_root, &category_id, &option_id)
 }
@@ -90,21 +86,26 @@ pub fn save_user_mirror_category(
     description: Option<String>,
 ) -> Result<(), String> {
     let project_root = get_project_root()?;
-    
+
     // 标准化镜像源地址（去除尾部斜杠）
     let normalized_source = normalize_mirror_url(&source);
-    
-    MirrorConfigManager::save_user_category(&project_root, &category_id, &normalized_source, description)
+
+    MirrorConfigManager::save_user_category(
+        &project_root,
+        &category_id,
+        &normalized_source,
+        description,
+    )
 }
 
 /// 删除用户自定义的类别配置
 #[tauri::command]
 pub fn remove_user_mirror_category(category_id: String) -> Result<(), String> {
     let project_root = get_project_root()?;
-    
+
     // 1. 从用户配置中删除
     MirrorConfigManager::remove_user_category(&project_root, &category_id)?;
-    
+
     // 2. 同步更新 .env 文件，恢复为默认值
     let env_path = project_root.join(".env");
     let default_value = match category_id.as_str() {
@@ -115,7 +116,7 @@ pub fn remove_user_mirror_category(category_id: String) -> Result<(), String> {
         "github_proxy" => "",
         _ => return Err(format!("未知的镜像源类别: {category_id}")),
     };
-    
+
     UnifiedMirrorManager::update_single(&category_id, default_value, &env_path)
 }
 
diff --git a/src-tauri/src/commands/mod.rs b/src-tauri/src/commands/mod.rs
index fd6d41b..92ecb57 100644
--- a/src-tauri/src/commands/mod.rs
+++ b/src-tauri/src/commands/mod.rs
@@ -1,45 +1,28 @@
+mod backup;
 mod docker;
 mod env_config;
 mod mirror;
-mod backup;
+pub mod paths;
 mod workspace;
 
 // Re-export all commands for lib.rs invoke_handler registration
+pub use backup::*;
 pub use docker::*;
 pub use env_config::*;
 pub use mirror::*;
-pub use backup::*;
 pub use workspace::*;
 
-use crate::engine::workspace_manager::WorkspaceManager;
+use paths::project_root;
 
 /// 获取项目根目录（优先读取 workspace.json）
+///
+/// 逻辑已迁至 `paths::project_root()`，此处保留同名薄封装，
+/// 避免 20 余处调用点一起改动。
 pub(crate) fn get_project_root() -> Result<std::path::PathBuf, String> {
-    // 1. 尝试从 workspace.json 读取配置
-    if let Some(workspace) = WorkspaceManager::load_workspace()? {
-        let path = std::path::PathBuf::from(&workspace.workspace_path);
-        if path.exists() {
-            return Ok(path);
-        }
-    }
+    project_root()
+}
 
-    // 2. 如果未配置或路径无效，返回 exe 同级目录作为默认值
-    if cfg!(debug_assertions) {
-        // 开发模式：使用项目根目录（src-tauri 的父目录）
-        Ok(std::env::current_exe()
-            .map_err(|e| format!("获取程序路径失败: {e}"))?
-            .parent() // target/debug/
-            .and_then(|p| p.parent()) // target/
-            .and_then(|p| p.parent()) // src-tauri/
-            .and_then(|p| p.parent()) // 项目根目录
-            .ok_or("无法获取项目根目录")?
-            .to_path_buf())
-    } else {
-        // 生产模式：使用可执行文件所在目录
-        Ok(std::env::current_exe()
-            .map_err(|e| format!("获取程序路径失败: {e}"))?
-            .parent()
-            .ok_or("无法获取程序所在目录")?
-            .to_path_buf())
-    }
+/// 获取日志文件路径（位于应用数据目录）
+pub(crate) fn get_log_file() -> Result<std::path::PathBuf, String> {
+    paths::log_file()
 }
diff --git a/src-tauri/src/commands/paths.rs b/src-tauri/src/commands/paths.rs
new file mode 100644
index 0000000..352ad29
--- /dev/null
+++ b/src-tauri/src/commands/paths.rs
@@ -0,0 +1,255 @@
+//! 应用路径的唯一事实来源。
+//!
+//! 此前"开发模式向上爬 4 层 / 生产模式取 exe 父目录"这段逻辑被抄了三份：
+//! `commands/mod.rs`（get_project_root）、`commands/workspace.rs`（export_logs）、
+//! `lib.rs`（日志目录）。更关键的是产品问题——生产模式下 workspace.json 与
+//! php-stack.log 写在 exe 同级目录，装进 `Program Files` 后无写权限，功能直接失效。
+//!
+//! 本模块收口三件事：
+//! - `app_data_dir()`：用户级配置的唯一落点，由 setup 用 Tauri 官方
+//!   `app.path().app_data_dir()` 注入，不再自己爬目录；
+//! - `project_root()`：工作区目录（.env / services / 备份所在），语义不同，保持独立；
+//! - `log_file()`：日志文件路径，随 app_data_dir 走。
+//!
+//! 约定：**工作区内的文件（.env、docker-compose.yml、services/、备份包、.user_*.json）
+//! 一律原地不动**——它们本来就是"工作区"的一部分，且备份/恢复管道按项目根读写。
+//! 只有用户级配置与日志迁入 app_data_dir。
+
+use std::path::PathBuf;
+use std::sync::OnceLock;
+
+use crate::engine::workspace_manager::WorkspaceManager;
+
+/// setup 阶段注入一次；未注入时回退到旧的 exe 同级逻辑（测试与早期调用）。
+static APP_DATA_DIR: OnceLock<PathBuf> = OnceLock::new();
+
+/// 由 `lib.rs` 的 setup 调用，传入 Tauri 官方应用数据目录。
+///
+/// 重复调用只保留首次值——路径在进程生命周期内必须稳定。
+pub fn init_app_data_dir(dir: PathBuf) {
+    let _ = APP_DATA_DIR.set(dir);
+}
+
+/// 回退路径：exe 同级（生产）或项目根（开发）。
+///
+/// 仅用于 `init_app_data_dir` 尚未执行的场景（单元测试、setup 之前的日志）。
+fn legacy_app_dir() -> Result<PathBuf, String> {
+    let exe = std::env::current_exe().map_err(|e| format!("获取程序路径失败: {e}"))?;
+
+    if cfg!(debug_assertions) {
+        // 开发模式：src-tauri 的父目录 = 项目根
+        exe.parent() // target/debug/
+            .and_then(|p| p.parent()) // target/
+            .and_then(|p| p.parent()) // src-tauri/
+            .and_then(|p| p.parent()) // 项目根
+            .map(|p| p.to_path_buf())
+            .ok_or_else(|| "无法获取项目根目录".to_string())
+    } else {
+        exe.parent()
+            .map(|p| p.to_path_buf())
+            .ok_or_else(|| "无法获取程序所在目录".to_string())
+    }
+}
+
+/// 用户级配置目录（workspace.json 等）。
+pub fn app_data_dir() -> Result<PathBuf, String> {
+    match APP_DATA_DIR.get() {
+        Some(dir) => Ok(dir.clone()),
+        None => legacy_app_dir(),
+    }
+}
+
+/// 日志文件路径。
+pub fn log_file() -> Result<PathBuf, String> {
+    Ok(app_data_dir()?.join("php-stack.log"))
+}
+
+/// 工作区解析结果。
+///
+/// `path` 是**实际生效**的落点；`fell_back` 为真表示配置的工作区用不了、
+/// 数据正写到默认位置——这必须让上层和用户知道，不能静默发生。
+#[derive(Debug, Clone)]
+pub struct WorkspaceResolution {
+    pub path: PathBuf,
+    /// 配置的工作区不可用、已回退到默认目录
+    pub fell_back: bool,
+    /// 回退原因（`fell_back` 为真时必有值）
+    pub reason: Option<String>,
+}
+
+/// 解析工作区根目录（.env / docker-compose.yml / services/ 所在）。
+///
+/// 优先级：
+/// 1. workspace.json 已配置的路径：存在则直接用；**不存在则先尝试创建**——
+///    用户明确设定过工作区，写回默认位置会让他的配置看起来"没生效"；
+/// 2. 创建失败才回退到默认目录，并把原因记进 `reason`；
+/// 3. 从未配置过：用默认位置，这不算回退。
+pub fn resolve_workspace() -> Result<WorkspaceResolution, String> {
+    let Some(config) = WorkspaceManager::load_workspace()? else {
+        return Ok(WorkspaceResolution {
+            path: legacy_app_dir()?,
+            fell_back: false,
+            reason: None,
+        });
+    };
+
+    let path = PathBuf::from(&config.workspace_path);
+
+    if path.exists() {
+        return Ok(WorkspaceResolution {
+            path,
+            fell_back: false,
+            reason: None,
+        });
+    }
+
+    // 目录不见了（盘符卸载 / 目录被删 / 路径写错）：先试着建回来
+    match std::fs::create_dir_all(&path) {
+        Ok(()) => Ok(WorkspaceResolution {
+            path,
+            fell_back: false,
+            reason: None,
+        }),
+        Err(e) => {
+            let reason = format!("配置的工作区 {} 不可用（{}）", config.workspace_path, e);
+            eprintln!("{reason}，已回退到默认目录");
+            Ok(WorkspaceResolution {
+                path: legacy_app_dir()?,
+                fell_back: true,
+                reason: Some(reason),
+            })
+        }
+    }
+}
+
+/// 工作区根目录（.env / docker-compose.yml / services/ 所在）。
+///
+/// 只取路径；需要知道是否发生回退时用 [`resolve_workspace`]。
+pub fn project_root() -> Result<PathBuf, String> {
+    Ok(resolve_workspace()?.path)
+}
+
+/// 需要随 app_data_dir 迁移的用户级配置文件名。
+const MIGRATABLE_FILES: [&str; 1] = ["workspace.json"];
+
+/// 把 `from_dir` 中缺失于 `to_dir` 的用户级配置复制过去。
+///
+/// 纯函数、可单测：只在目标不存在时复制，绝不覆盖已有配置。
+/// 返回被迁移的文件名列表。
+fn migrate_files(from_dir: &std::path::Path, to_dir: &std::path::Path) -> Vec<String> {
+    if from_dir == to_dir {
+        return Vec::new();
+    }
+
+    if let Err(e) = std::fs::create_dir_all(to_dir) {
+        eprintln!("无法创建应用数据目录 {}: {e}", to_dir.display());
+        return Vec::new();
+    }
+
+    let mut migrated = Vec::new();
+    for name in MIGRATABLE_FILES {
+        let from = from_dir.join(name);
+        let to = to_dir.join(name);
+
+        if !from.exists() || to.exists() {
+            continue;
+        }
+
+        match std::fs::copy(&from, &to) {
+            Ok(_) => migrated.push(name.to_string()),
+            Err(e) => eprintln!("迁移 {} 失败: {e}", from.display()),
+        }
+    }
+
+    migrated
+}
+
+/// 首次启动时把旧位置的用户级配置迁移到 app_data_dir。
+///
+/// 复制失败仅记录，不阻断启动——迁移是便利手段，不是前置条件。
+/// 返回被迁移的文件名列表，供启动日志提示用户。
+pub fn migrate_legacy_config() -> Vec<String> {
+    let (Ok(target_dir), Ok(legacy_dir)) = (app_data_dir(), legacy_app_dir()) else {
+        return Vec::new();
+    };
+
+    migrate_files(&legacy_dir, &target_dir)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::Path;
+
+    /// 建一个干净的临时目录（已存在则先清空）
+    fn fresh_dir(name: &str) -> std::path::PathBuf {
+        let dir = std::env::temp_dir().join(format!("php-stack-paths-{name}"));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).unwrap();
+        dir
+    }
+
+    #[test]
+    fn test_log_file_lives_in_app_data_dir() {
+        let dir = app_data_dir().expect("app_data_dir 不应失败");
+        let log = log_file().expect("log_file 不应失败");
+        assert_eq!(log.parent(), Some(dir.as_path()));
+        assert_eq!(log.file_name().unwrap(), "php-stack.log");
+    }
+
+    #[test]
+    fn test_project_root_is_absolute() {
+        let root = project_root().expect("project_root 不应失败");
+        assert!(root.is_absolute(), "project_root 应为绝对路径: {root:?}");
+    }
+
+    #[test]
+    fn test_migrate_files_copies_when_missing() {
+        let legacy = fresh_dir("legacy");
+        let target = fresh_dir("target");
+        std::fs::write(legacy.join("workspace.json"), r#"{"workspace_path":"/x"}"#).unwrap();
+
+        let migrated = migrate_files(&legacy, &target);
+
+        assert_eq!(migrated, vec!["workspace.json".to_string()]);
+        let copied = std::fs::read_to_string(target.join("workspace.json")).unwrap();
+        assert_eq!(copied, r#"{"workspace_path":"/x"}"#);
+    }
+
+    #[test]
+    fn test_migrate_files_does_not_overwrite_existing() {
+        let legacy = fresh_dir("legacy2");
+        let target = fresh_dir("target2");
+        std::fs::write(legacy.join("workspace.json"), "OLD").unwrap();
+        std::fs::write(target.join("workspace.json"), "NEW").unwrap();
+
+        assert!(migrate_files(&legacy, &target).is_empty());
+        // 新位置的配置必须原封不动
+        assert_eq!(
+            std::fs::read_to_string(target.join("workspace.json")).unwrap(),
+            "NEW"
+        );
+    }
+
+    #[test]
+    fn test_migrate_files_noop_for_same_dir() {
+        let dir = fresh_dir("same");
+        std::fs::write(dir.join("workspace.json"), "X").unwrap();
+        assert!(migrate_files(&dir, &dir).is_empty());
+    }
+
+    #[test]
+    fn test_migrate_files_noop_when_nothing_to_migrate() {
+        let legacy = fresh_dir("legacy3");
+        let target = fresh_dir("target3");
+        assert!(migrate_files(&legacy, &target).is_empty());
+        assert!(!Path::new(&target.join("workspace.json")).exists());
+    }
+
+    #[test]
+    fn test_project_root_never_falls_back_silently_when_unconfigured() {
+        // 未配置工作区时用默认目录，属于预期行为，不算回退
+        let root = project_root().expect("project_root 不应失败");
+        assert!(root.is_absolute(), "默认目录应为绝对路径: {root:?}");
+    }
+}
diff --git a/src-tauri/src/commands/workspace.rs b/src-tauri/src/commands/workspace.rs
index 43fc76f..707df5d 100644
--- a/src-tauri/src/commands/workspace.rs
+++ b/src-tauri/src/commands/workspace.rs
@@ -1,19 +1,19 @@
-use crate::engine::version_manifest::{VersionManifest, ServiceType as VmServiceType};
 use crate::engine::user_override_manager::{UserOverrideManager, UserVersionOverride};
+use crate::engine::version_manifest::{ServiceType as VmServiceType, VersionManifest};
 use crate::engine::workspace_manager::WorkspaceManager;
 
-use super::get_project_root;
+use super::{get_log_file, get_project_root, paths};
 
 /// 打开指定服务的配置文件目录
 #[tauri::command]
 pub fn open_service_config(service_name: String) -> Result<(), String> {
     let project_root = get_project_root()?;
     let service_dir = project_root.join("services").join(&service_name);
-    
+
     if !service_dir.exists() {
         return Err(format!("服务配置目录不存在: {}", service_dir.display()));
     }
-    
+
     // 在 Windows 上使用 explorer 打开目录
     #[cfg(target_os = "windows")]
     {
@@ -22,7 +22,7 @@ pub fn open_service_config(service_name: String) -> Result<(), String> {
             .spawn()
             .map_err(|e| format!("无法打开目录: {e}"))?;
     }
-    
+
     // 在 macOS 上使用 open 命令
     #[cfg(target_os = "macos")]
     {
@@ -31,7 +31,7 @@ pub fn open_service_config(service_name: String) -> Result<(), String> {
             .spawn()
             .map_err(|e| format!("无法打开目录: {}", e))?;
     }
-    
+
     // 在 Linux 上使用 xdg-open 命令
     #[cfg(target_os = "linux")]
     {
@@ -40,14 +40,45 @@ pub fn open_service_config(service_name: String) -> Result<(), String> {
             .spawn()
             .map_err(|e| format!("无法打开目录: {}", e))?;
     }
-    
+
     Ok(())
 }
 
+/// 工作区信息。
+///
+/// `workspace_path` 是用户配置的值，`effective_path` 是**数据真正落到的地方**。
+/// 两者不一致（`using_fallback`）时必须让用户看到，否则配置看起来"没生效"。
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct WorkspaceInfo {
+    /// 用户配置的工作区路径
+    pub workspace_path: String,
+    /// 实际生效的数据落点
+    pub effective_path: String,
+    /// 配置路径不可用时为 true，数据正写到 effective_path
+    pub using_fallback: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub fallback_reason: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub last_updated: Option<String>,
+}
+
 /// 获取当前工作目录信息
+///
+/// 未配置过工作区时返回 `None`，前端据此弹出初始化对话框。
 #[tauri::command]
-pub fn get_workspace_info() -> Result<Option<crate::engine::workspace_manager::WorkspaceConfig>, String> {
-    WorkspaceManager::load_workspace()
+pub fn get_workspace_info() -> Result<Option<WorkspaceInfo>, String> {
+    let Some(config) = WorkspaceManager::load_workspace()? else {
+        return Ok(None);
+    };
+
+    let resolved = paths::resolve_workspace()?;
+    Ok(Some(WorkspaceInfo {
+        workspace_path: config.workspace_path,
+        effective_path: resolved.path.to_string_lossy().to_string(),
+        using_fallback: resolved.fell_back,
+        fallback_reason: resolved.reason,
+        last_updated: config.last_updated,
+    }))
 }
 
 /// 设置工作目录路径
@@ -64,12 +95,12 @@ pub fn set_workspace_path(path: String) -> Result<(), String> {
 #[tauri::command]
 pub fn get_version_mappings() -> Result<serde_json::Value, String> {
     use std::collections::HashMap;
-    
+
     let manifest = VersionManifest::new();
     let project_root = get_project_root()?;
     let override_manager = UserOverrideManager::new(&project_root);
     let mut result = HashMap::new();
-    
+
     // 使用辅助函数处理每种服务类型
     let service_types = [
         ("php", VmServiceType::Php),
@@ -77,18 +108,19 @@ pub fn get_version_mappings() -> Result<serde_json::Value, String> {
         ("redis", VmServiceType::Redis),
         ("nginx", VmServiceType::Nginx),
     ];
-    
+
     for (key, service_type) in &service_types {
         let mut versions = Vec::new();
         let entries = manifest.get_available_entries(service_type);
-        
+
         for (id, entry) in entries {
             // 使用合并后的配置（用户覆盖优先）
-            let merged_entry = override_manager.get_merged_entry(service_type, id)
+            let merged_entry = override_manager
+                .get_merged_entry(service_type, id)
                 .unwrap_or_else(|| entry.clone());
-            
+
             let has_user_override = override_manager.has_user_override(service_type, id);
-            
+
             versions.push(serde_json::json!({
                 "id": id,
                 "display_name": merged_entry.display_name,
@@ -103,7 +135,7 @@ pub fn get_version_mappings() -> Result<serde_json::Value, String> {
         }
         result.insert(key.to_string(), serde_json::Value::Array(versions));
     }
-    
+
     serde_json::to_value(result).map_err(|e| format!("序列化失败: {e}"))
 }
 
@@ -118,7 +150,7 @@ pub fn validate_version(service_type: String, version: String) -> Result<bool, S
         "nginx" => VmServiceType::Nginx,
         _ => return Err(format!("不支持的服务类型: {service_type}")),
     };
-    
+
     Ok(manifest.is_id_valid(&vm_service_type, &version))
 }
 
@@ -133,8 +165,10 @@ pub fn get_recommended_version(service_type: String) -> Result<Option<String>, S
         "nginx" => VmServiceType::Nginx,
         _ => return Err(format!("不支持的服务类型: {service_type}")),
     };
-    
-    Ok(manifest.get_recommended_entry(&vm_service_type).map(|(id, _)| id.to_string()))
+
+    Ok(manifest
+        .get_recommended_entry(&vm_service_type)
+        .map(|(id, _)| id.to_string()))
 }
 
 /// 保存用户自定义版本覆盖
@@ -147,7 +181,7 @@ pub fn save_user_override(
 ) -> Result<(), String> {
     let project_root = get_project_root()?;
     let mut manager = UserOverrideManager::new(&project_root);
-    
+
     let vm_service_type = match service_type.as_str() {
         "php" => VmServiceType::Php,
         "mysql" => VmServiceType::Mysql,
@@ -155,12 +189,12 @@ pub fn save_user_override(
         "nginx" => VmServiceType::Nginx,
         _ => return Err(format!("不支持的服务类型: {service_type}")),
     };
-    
+
     let override_config = UserVersionOverride {
         image_tag,
         description,
     };
-    
+
     manager.save_user_override(&project_root, vm_service_type, id, override_config)
 }
 
@@ -169,7 +203,7 @@ pub fn save_user_override(
 pub fn remove_user_override(service_type: String, id: String) -> Result<(), String> {
     let project_root = get_project_root()?;
     let mut manager = UserOverrideManager::new(&project_root);
-    
+
     let vm_service_type = match service_type.as_str() {
         "php" => VmServiceType::Php,
         "mysql" => VmServiceType::Mysql,
@@ -177,7 +211,7 @@ pub fn remove_user_override(service_type: String, id: String) -> Result<(), Stri
         "nginx" => VmServiceType::Nginx,
         _ => return Err(format!("不支持的服务类型: {service_type}")),
     };
-    
+
     manager.remove_user_override(&project_root, &vm_service_type, &id)
 }
 
@@ -186,39 +220,37 @@ pub fn remove_user_override(service_type: String, id: String) -> Result<(), Stri
 pub fn reset_all_overrides() -> Result<(), String> {
     let project_root = get_project_root()?;
     let mut manager = UserOverrideManager::new(&project_root);
-    
+
     manager.reset_all_overrides(&project_root)
 }
 
+/// 把完整文件日志导出到用户指定位置
+///
+/// 与 `export_logs`（返回文本内容，供复制）不同，这里直接落盘，
+/// 对应日志面板的"导出"动作。
+#[tauri::command]
+pub fn export_logs_to(dest: String) -> Result<(), String> {
+    let log_path = get_log_file()?;
+
+    if !log_path.exists() {
+        return Err("日志文件不存在，请先执行一些操作".to_string());
+    }
+
+    std::fs::copy(&log_path, &dest).map_err(|e| format!("导出日志失败: {e}"))?;
+
+    Ok(())
+}
+
 /// 导出当前会话日志
+///
+/// 日志文件位于应用数据目录（路径由 `paths::log_file()` 统一给出）。
 #[tauri::command]
 pub fn export_logs() -> Result<String, String> {
-    // 获取项目根目录（与 get_project_root 逻辑一致）
-    let log_dir = if cfg!(debug_assertions) {
-        // 开发模式：使用项目根目录
-        std::env::current_exe()
-            .map_err(|e| format!("获取程序路径失败: {e}"))?
-            .parent()
-            .and_then(|p| p.parent())
-            .and_then(|p| p.parent())
-            .and_then(|p| p.parent())
-            .ok_or("无法获取项目根目录")?
-            .to_path_buf()
-    } else {
-        // 生产模式：使用可执行文件所在目录
-        std::env::current_exe()
-            .map_err(|e| format!("获取程序路径失败: {e}"))?
-            .parent()
-            .ok_or("无法获取程序所在目录")?
-            .to_path_buf()
-    };
-    
-    let log_path = log_dir.join("php-stack.log");
-    
+    let log_path = get_log_file()?;
+
     if !log_path.exists() {
         return Err("日志文件不存在，请先执行一些操作".to_string());
     }
-    
-    std::fs::read_to_string(&log_path)
-        .map_err(|e| format!("读取日志失败: {e}"))
+
+    std::fs::read_to_string(&log_path).map_err(|e| format!("读取日志失败: {e}"))
 }
diff --git a/src-tauri/src/docker/manager.rs b/src-tauri/src/docker/manager.rs
index a0609ec..5d09af2 100644
--- a/src-tauri/src/docker/manager.rs
+++ b/src-tauri/src/docker/manager.rs
@@ -1,9 +1,70 @@
-use bollard::Docker;
+use bollard::models::ContainerSummaryStateEnum;
 use bollard::query_parameters::{
-    ListContainersOptions, StartContainerOptions, StopContainerOptions, RestartContainerOptions,
+    ListContainersOptions, RestartContainerOptions, StartContainerOptions, StopContainerOptions,
 };
-use serde::{Serialize, Deserialize};
+use bollard::Docker;
+use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
+use std::fmt;
+
+/// 容器运行状态。
+///
+/// 前后端契约：序列化为小写字符串（`running` / `exited` / ...）。
+/// 此前后端用 `format!("{:?}", c.state)` 产出 `"Some(RUNNING)"`，前端靠
+/// `includes('running')` 猜测解析——Docker 或 bollard 升级即碎。枚举化后
+/// 契约由 serde 保证，两端都不再做字符串猜测。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum ContainerState {
+    Created,
+    Running,
+    Paused,
+    Restarting,
+    Exited,
+    Removing,
+    Dead,
+    /// Docker 未返回状态（字段缺失或为空）。保留兜底变体，避免反序列化失败。
+    Unknown,
+}
+
+impl ContainerState {
+    /// 仅 `running` 视为运行中；`restarting` 尚未真正提供服务，不算。
+    pub fn is_running(&self) -> bool {
+        matches!(self, ContainerState::Running)
+    }
+}
+
+impl From<Option<ContainerSummaryStateEnum>> for ContainerState {
+    fn from(state: Option<ContainerSummaryStateEnum>) -> Self {
+        match state {
+            Some(ContainerSummaryStateEnum::CREATED) => ContainerState::Created,
+            Some(ContainerSummaryStateEnum::RUNNING) => ContainerState::Running,
+            Some(ContainerSummaryStateEnum::PAUSED) => ContainerState::Paused,
+            Some(ContainerSummaryStateEnum::RESTARTING) => ContainerState::Restarting,
+            Some(ContainerSummaryStateEnum::EXITED) => ContainerState::Exited,
+            Some(ContainerSummaryStateEnum::REMOVING) => ContainerState::Removing,
+            Some(ContainerSummaryStateEnum::DEAD) => ContainerState::Dead,
+            // 空字符串变体与字段缺失都归为 Unknown
+            Some(ContainerSummaryStateEnum::EMPTY) | None => ContainerState::Unknown,
+        }
+    }
+}
+
+impl fmt::Display for ContainerState {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let s = match self {
+            ContainerState::Created => "created",
+            ContainerState::Running => "running",
+            ContainerState::Paused => "paused",
+            ContainerState::Restarting => "restarting",
+            ContainerState::Exited => "exited",
+            ContainerState::Removing => "removing",
+            ContainerState::Dead => "dead",
+            ContainerState::Unknown => "unknown",
+        };
+        f.write_str(s)
+    }
+}
 
 #[derive(Debug, Serialize, Deserialize)]
 pub struct PsContainer {
@@ -11,10 +72,38 @@ pub struct PsContainer {
     pub name: String,
     pub image: String,
     pub status: String,
-    pub state: String,
+    pub state: ContainerState,
     pub ports: Vec<i32>,
 }
 
+/// 把 bollard 的容器摘要映射为前端契约结构。
+///
+/// `list_ps_containers` 与 `list_all_running_containers` 此前各抄了一遍，
+/// 两处必须同步修改才能保持一致——收敛为单一实现。
+fn to_ps_container(c: bollard::models::ContainerSummary) -> PsContainer {
+    let name = c
+        .names
+        .clone()
+        .unwrap_or_default()
+        .first()
+        .map(|n| n.trim_start_matches('/').to_string())
+        .unwrap_or_else(|| "unknown".to_string());
+
+    PsContainer {
+        id: c.id.unwrap_or_default(),
+        name,
+        image: c.image.unwrap_or_default(),
+        status: c.status.unwrap_or_default(),
+        state: ContainerState::from(c.state),
+        ports: c
+            .ports
+            .unwrap_or_default()
+            .into_iter()
+            .filter_map(|p| p.public_port.map(|port| port as i32))
+            .collect(),
+    }
+}
+
 pub struct DockerManager {
     docker: Docker,
 }
@@ -35,7 +124,7 @@ impl DockerManager {
     pub async fn list_ps_containers(&self) -> Result<Vec<PsContainer>, Box<dyn std::error::Error>> {
         let mut filters = HashMap::new();
         filters.insert("name".to_string(), vec!["ps-".to_string()]);
-        
+
         let options = Some(ListContainersOptions {
             all: true,
             filters: Some(filters),
@@ -43,88 +132,135 @@ impl DockerManager {
         });
 
         let containers = self.docker.list_containers(options).await?;
-        
-        let ps_containers = containers.into_iter().map(|c| {
-            let name = c.names.clone().unwrap_or_default().first()
-                .map(|n| n.trim_start_matches('/').to_string())
-                .unwrap_or_else(|| "unknown".to_string());
-
-            PsContainer {
-                id: c.id.unwrap_or_default(),
-                name,
-                image: c.image.unwrap_or_default(),
-                status: c.status.unwrap_or_default(),
-                state: format!("{:?}", c.state),
-                ports: c.ports.unwrap_or_default().into_iter()
-                    .filter_map(|p| p.public_port.map(|port| port as i32))
-                    .collect(),
-            }
-        }).collect();
 
-        Ok(ps_containers)
+        Ok(containers.into_iter().map(to_ps_container).collect())
     }
 
     /// 获取所有运行中的容器（用于端口冲突检测）
-    pub async fn list_all_running_containers(&self) -> Result<Vec<PsContainer>, Box<dyn std::error::Error>> {
+    pub async fn list_all_running_containers(
+        &self,
+    ) -> Result<Vec<PsContainer>, Box<dyn std::error::Error>> {
         let options = Some(ListContainersOptions {
             all: false, // 只返回运行中的容器
             ..Default::default()
         });
 
         let containers = self.docker.list_containers(options).await?;
-        
-        let all_containers = containers.into_iter().map(|c| {
-            let name = c.names.clone().unwrap_or_default().first()
-                .map(|n| n.trim_start_matches('/').to_string())
-                .unwrap_or_else(|| "unknown".to_string());
-
-            PsContainer {
-                id: c.id.unwrap_or_default(),
-                name,
-                image: c.image.unwrap_or_default(),
-                status: c.status.unwrap_or_default(),
-                state: format!("{:?}", c.state),
-                ports: c.ports.unwrap_or_default().into_iter()
-                    .filter_map(|p| p.public_port.map(|port| port as i32))
-                    .collect(),
-            }
-        }).collect();
 
-        Ok(all_containers)
+        Ok(containers.into_iter().map(to_ps_container).collect())
     }
 
     pub async fn start_container(&self, name: &str) -> Result<(), Box<dyn std::error::Error>> {
-        self.docker.start_container(name, None::<StartContainerOptions>).await?;
+        self.docker
+            .start_container(name, None::<StartContainerOptions>)
+            .await?;
         Ok(())
     }
 
     pub async fn stop_container(&self, name: &str) -> Result<(), Box<dyn std::error::Error>> {
-        self.docker.stop_container(name, None::<StopContainerOptions>).await?;
+        self.docker
+            .stop_container(name, None::<StopContainerOptions>)
+            .await?;
         Ok(())
     }
 
     pub async fn restart_container(&self, name: &str) -> Result<(), Box<dyn std::error::Error>> {
-        self.docker.restart_container(name, None::<RestartContainerOptions>).await?;
+        self.docker
+            .restart_container(name, None::<RestartContainerOptions>)
+            .await?;
         Ok(())
     }
 
     /// 检查所有 ps- 前缀的容器是否都处于 running 状态
     pub async fn check_all_ps_containers_running(&self) -> Result<bool, String> {
-        let containers = self.list_ps_containers().await
+        let containers = self
+            .list_ps_containers()
+            .await
             .map_err(|e| format!("获取容器列表失败: {e}"))?;
-        
+
         if containers.is_empty() {
             return Ok(false);
         }
-        
+
         // 检查所有容器是否都是 running 状态
         for container in &containers {
-            // state 字段是 "Some(RUNNING)" 或 "Some(EXITED)" 等格式
-            if !container.state.contains("RUNNING") {
+            if !container.state.is_running() {
                 return Ok(false);
             }
         }
-        
+
         Ok(true)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_container_state_serializes_lowercase() {
+        assert_eq!(
+            serde_json::to_string(&ContainerState::Running).unwrap(),
+            "\"running\""
+        );
+        assert_eq!(
+            serde_json::to_string(&ContainerState::Exited).unwrap(),
+            "\"exited\""
+        );
+        assert_eq!(
+            serde_json::to_string(&ContainerState::Unknown).unwrap(),
+            "\"unknown\""
+        );
+    }
+
+    #[test]
+    fn test_container_state_roundtrip() {
+        for state in [
+            ContainerState::Created,
+            ContainerState::Running,
+            ContainerState::Paused,
+            ContainerState::Restarting,
+            ContainerState::Exited,
+            ContainerState::Removing,
+            ContainerState::Dead,
+            ContainerState::Unknown,
+        ] {
+            let json = serde_json::to_string(&state).unwrap();
+            let back: ContainerState = serde_json::from_str(&json).unwrap();
+            assert_eq!(back, state, "往返失败: {json}");
+        }
+    }
+
+    #[test]
+    fn test_container_state_from_bollard_enum() {
+        assert_eq!(
+            ContainerState::from(Some(ContainerSummaryStateEnum::RUNNING)),
+            ContainerState::Running
+        );
+        assert_eq!(
+            ContainerState::from(Some(ContainerSummaryStateEnum::EXITED)),
+            ContainerState::Exited
+        );
+        // 空字符串变体与字段缺失都不能让反序列化崩掉
+        assert_eq!(
+            ContainerState::from(Some(ContainerSummaryStateEnum::EMPTY)),
+            ContainerState::Unknown
+        );
+        assert_eq!(ContainerState::from(None), ContainerState::Unknown);
+    }
+
+    #[test]
+    fn test_is_running_only_for_running() {
+        assert!(ContainerState::Running.is_running());
+        // restarting 尚未真正提供服务，不当作运行中
+        assert!(!ContainerState::Restarting.is_running());
+        assert!(!ContainerState::Exited.is_running());
+        assert!(!ContainerState::Unknown.is_running());
+    }
+
+    #[test]
+    fn test_container_state_display() {
+        assert_eq!(ContainerState::Running.to_string(), "running");
+        assert_eq!(ContainerState::Dead.to_string(), "dead");
+    }
+}
diff --git a/src-tauri/src/docker/mod.rs b/src-tauri/src/docker/mod.rs
index 07301bd..1418046 100644
--- a/src-tauri/src/docker/mod.rs
+++ b/src-tauri/src/docker/mod.rs
@@ -1,2 +1,3 @@
 pub mod manager;
-pub mod tests;
+#[cfg(test)]
+mod tests;
diff --git a/src-tauri/src/docker/tests.rs b/src-tauri/src/docker/tests.rs
index d538d79..7a97194 100644
--- a/src-tauri/src/docker/tests.rs
+++ b/src-tauri/src/docker/tests.rs
@@ -1,10 +1,10 @@
-#[cfg(test)]
-mod tests {
-    use crate::docker::manager::DockerManager;
+use crate::docker::manager::DockerManager;
 
-    #[tokio::test]
-    async fn test_docker_manager_init() {
-        let manager = DockerManager::new();
-        assert!(manager.is_ok(), "DockerManager 应该能够初始化，即使 Docker 未运行（懒连接）");
-    }
+#[tokio::test]
+async fn test_docker_manager_init() {
+    let manager = DockerManager::new();
+    assert!(
+        manager.is_ok(),
+        "DockerManager 应该能够初始化，即使 Docker 未运行（懒连接）"
+    );
 }
diff --git a/src-tauri/src/engine/backup_engine.rs b/src-tauri/src/engine/backup_engine.rs
index 5acdc77..918c544 100644
--- a/src-tauri/src/engine/backup_engine.rs
+++ b/src-tauri/src/engine/backup_engine.rs
@@ -1,9 +1,9 @@
+use glob::glob;
+use sha2::{Digest, Sha256};
 use std::fs;
-use std::io::{Write, Seek};
+use std::io::{Read, Seek, Write};
 use std::path::Path;
 use zip::write::FileOptions;
-use sha2::{Sha256, Digest};
-use glob::glob;
 
 use super::backup_manifest::{BackupManifest, BackupOptions};
 use crate::app_log;
@@ -26,8 +26,7 @@ impl BackupEngine {
         project_root: &Path,
         app_handle: Option<&tauri::AppHandle>,
     ) -> Result<(), String> {
-        let file = fs::File::create(save_path)
-            .map_err(|e| format!("创建备份文件失败: {e}"))?;
+        let file = fs::File::create(save_path).map_err(|e| format!("创建备份文件失败: {e}"))?;
         let mut zip = zip::ZipWriter::new(file);
         let mut manifest = BackupManifest::new();
         manifest.options = options.clone();
@@ -36,23 +35,14 @@ impl BackupEngine {
         Self::emit_progress(app_handle, "打包环境配置...", 10);
         let env_path = project_root.join(".env");
         if env_path.exists() {
-            let content = fs::read(&env_path)
-                .map_err(|e| format!("读取 .env 失败: {e}"))?;
-            Self::add_file_to_zip(&mut zip, ".env", &content, &mut manifest)?;
+            Self::add_file_to_zip(&mut zip, ".env", &env_path, &mut manifest)?;
         }
 
         // Step 2: Pack docker-compose.yml (20%)
         Self::emit_progress(app_handle, "打包 Docker 配置...", 20);
         let compose_path = project_root.join("docker-compose.yml");
         if compose_path.exists() {
-            let content = fs::read(&compose_path)
-                .map_err(|e| format!("读取 docker-compose.yml 失败: {e}"))?;
-            Self::add_file_to_zip(
-                &mut zip,
-                "docker-compose.yml",
-                &content,
-                &mut manifest,
-            )?;
+            Self::add_file_to_zip(&mut zip, "docker-compose.yml", &compose_path, &mut manifest)?;
         }
 
         // Step 3: Pack services/ configs (30%)
@@ -64,29 +54,25 @@ impl BackupEngine {
 
         // Step 3.5: Pack user custom configuration files (35%)
         Self::emit_progress(app_handle, "打包用户自定义配置...", 35);
-        
+
         // .user_mirror_config.json - User mirror source configuration
         let user_mirror_config_path = project_root.join(".user_mirror_config.json");
         if user_mirror_config_path.exists() {
-            let content = fs::read(&user_mirror_config_path)
-                .map_err(|e| format!("读取 .user_mirror_config.json 失败: {e}"))?;
             Self::add_file_to_zip(
                 &mut zip,
                 ".user_mirror_config.json",
-                &content,
+                &user_mirror_config_path,
                 &mut manifest,
             )?;
         }
-        
+
         // .user_version_overrides.json - User version override configuration
         let user_version_overrides_path = project_root.join(".user_version_overrides.json");
         if user_version_overrides_path.exists() {
-            let content = fs::read(&user_version_overrides_path)
-                .map_err(|e| format!("读取 .user_version_overrides.json 失败: {e}"))?;
             Self::add_file_to_zip(
                 &mut zip,
                 ".user_version_overrides.json",
-                &content,
+                &user_version_overrides_path,
                 &mut manifest,
             )?;
         }
@@ -97,22 +83,31 @@ impl BackupEngine {
             for pattern in &options.project_patterns {
                 // 将相对路径模式转换为绝对路径模式
                 let mut normalized_pattern = pattern.clone();
-                
+
                 // 如果模式以 /** 结尾，添加 /* 以匹配文件
                 // 例如："www/AAA/**" -> "www/AAA/**/*"
                 if normalized_pattern.ends_with("/**") {
                     normalized_pattern.push_str("/*");
                 }
-                
+
                 let abs_pattern = if std::path::Path::new(&normalized_pattern).is_absolute() {
                     normalized_pattern
                 } else {
-                    project_root.join(&normalized_pattern).to_string_lossy().replace('\\', "/")
+                    project_root
+                        .join(&normalized_pattern)
+                        .to_string_lossy()
+                        .replace('\\', "/")
                 };
-                
+
                 // 记录尝试的模式（用于调试）
-                app_log!(debug, "engine::backup", "尝试匹配模式: {} -> {}", pattern, abs_pattern);
-                
+                app_log!(
+                    debug,
+                    "engine::backup",
+                    "尝试匹配模式: {} -> {}",
+                    pattern,
+                    abs_pattern
+                );
+
                 match glob(&abs_pattern) {
                     Ok(entries) => {
                         let mut matched_count = 0;
@@ -120,28 +115,24 @@ impl BackupEngine {
                             match entry {
                                 Ok(path) if path.is_file() => {
                                     matched_count += 1;
-                                    match fs::read(&path) {
-                                        Ok(content) => {
-                                            // 计算相对于项目根目录的路径
-                                            let relative_path = pathdiff::diff_paths(&path, project_root)
-                                                .map(|p| p.to_string_lossy().replace('\\', "/"))
-                                                .unwrap_or_else(|| path.display().to_string());
-                                            let zip_path = format!("projects/{relative_path}");
-                                            app_log!(debug, "engine::backup", "添加文件: {}", zip_path);
-                                            Self::add_file_to_zip(
-                                                &mut zip,
-                                                &zip_path,
-                                                &content,
-                                                &mut manifest,
-                                            )?;
-                                        }
-                                        Err(e) => {
-                                            manifest.errors.push(format!(
-                                                "读取项目文件失败 {}: {}",
-                                                path.display(),
-                                                e
-                                            ));
-                                        }
+                                    // 计算相对于项目根目录的路径
+                                    let relative_path = pathdiff::diff_paths(&path, project_root)
+                                        .map(|p| p.to_string_lossy().replace('\\', "/"))
+                                        .unwrap_or_else(|| path.display().to_string());
+                                    let zip_path = format!("projects/{relative_path}");
+                                    app_log!(debug, "engine::backup", "添加文件: {}", zip_path);
+                                    // 流式写入：单个大文件不再整体进内存
+                                    if let Err(e) = Self::add_file_to_zip(
+                                        &mut zip,
+                                        &zip_path,
+                                        &path,
+                                        &mut manifest,
+                                    ) {
+                                        manifest.errors.push(format!(
+                                            "打包项目文件失败 {}: {}",
+                                            path.display(),
+                                            e
+                                        ));
                                     }
                                 }
                                 Ok(path) => {
@@ -154,7 +145,13 @@ impl BackupEngine {
                                 }
                             }
                         }
-                        app_log!(info, "engine::backup", "模式 '{}' 匹配到 {} 个文件", pattern, matched_count);
+                        app_log!(
+                            info,
+                            "engine::backup",
+                            "模式 '{}' 匹配到 {} 个文件",
+                            pattern,
+                            matched_count
+                        );
                     }
                     Err(e) => {
                         let error_msg = format!("Glob 模式错误 '{pattern}': {e}");
@@ -178,15 +175,16 @@ impl BackupEngine {
         // Step 8: Write manifest.json (95%)
         Self::emit_progress(app_handle, "生成备份清单...", 95);
         let manifest_json = manifest.serialize()?;
-        let zip_options = FileOptions::<()>::default()
-            .compression_method(zip::CompressionMethod::Deflated);
+        let zip_options =
+            FileOptions::<()>::default().compression_method(zip::CompressionMethod::Deflated);
         zip.start_file("manifest.json", zip_options)
             .map_err(|e| format!("创建 manifest 条目失败: {e}"))?;
         zip.write_all(manifest_json.as_bytes())
             .map_err(|e| format!("写入 manifest 失败: {e}"))?;
 
         // Finish ZIP
-        zip.finish().map_err(|e| format!("完成 ZIP 文件失败: {e}"))?;
+        zip.finish()
+            .map_err(|e| format!("完成 ZIP 文件失败: {e}"))?;
 
         Self::emit_progress(app_handle, "备份完成", 100);
         Ok(())
@@ -213,21 +211,40 @@ impl BackupEngine {
         }
     }
 
-    /// Helper: add a file to ZIP and record in manifest with SHA256.
+    /// Helper: add a file to ZIP and record its SHA256 in the manifest.
+    ///
+    /// 以 64KB 分块流式读取：同一趟既喂给 SHA256 也写进 ZIP，文件不再整体进内存。
+    /// 勾选"包含项目文件"时可能命中数据库 dump、视频素材等大文件，
+    /// 旧实现 `fs::read` 全量读入会让内存随文件大小线性飙升。
     fn add_file_to_zip<W: Write + Seek>(
         zip: &mut zip::ZipWriter<W>,
         zip_path: &str,
-        content: &[u8],
+        source: &Path,
         manifest: &mut BackupManifest,
     ) -> Result<(), String> {
-        let zip_options = FileOptions::<()>::default()
-            .compression_method(zip::CompressionMethod::Deflated);
+        let zip_options =
+            FileOptions::<()>::default().compression_method(zip::CompressionMethod::Deflated);
         zip.start_file(zip_path, zip_options)
             .map_err(|e| format!("创建 ZIP 条目失败: {e}"))?;
-        zip.write_all(content)
-            .map_err(|e| format!("写入 ZIP 内容失败: {e}"))?;
 
-        let sha256 = Self::compute_sha256(content);
+        let mut file = fs::File::open(source)
+            .map_err(|e| format!("打开文件失败 {}: {}", source.display(), e))?;
+
+        let mut hasher = Sha256::new();
+        let mut buffer = [0u8; 64 * 1024];
+        loop {
+            let read = file
+                .read(&mut buffer)
+                .map_err(|e| format!("读取文件失败 {}: {}", source.display(), e))?;
+            if read == 0 {
+                break;
+            }
+            hasher.update(&buffer[..read]);
+            zip.write_all(&buffer[..read])
+                .map_err(|e| format!("写入 ZIP 内容失败: {e}"))?;
+        }
+
+        let sha256 = format!("{:x}", hasher.finalize());
         manifest.files.insert(zip_path.to_string(), sha256);
         Ok(())
     }
@@ -242,20 +259,20 @@ impl BackupEngine {
         if !src_dir.exists() {
             return Ok(());
         }
-        for entry in
-            fs::read_dir(src_dir).map_err(|e| format!("读取目录失败: {e}"))?
-        {
+        for entry in fs::read_dir(src_dir).map_err(|e| format!("读取目录失败: {e}"))? {
             let entry = entry.map_err(|e| format!("读取目录条目失败: {e}"))?;
             let path = entry.path();
-            let name = path.file_name().unwrap().to_string_lossy();
-            let zip_path = format!("{zip_prefix}/{name}");
+            // 无文件名（盘符根等）时跳过而非 panic
+            let Some(name) = path.file_name() else {
+                app_log!(warn, "engine::backup", "跳过无文件名的路径: {:?}", path);
+                continue;
+            };
+            let zip_path = format!("{zip_prefix}/{}", name.to_string_lossy());
 
             if path.is_dir() {
                 Self::add_dir_to_zip(zip, &path, &zip_path, manifest)?;
             } else {
-                let content = fs::read(&path)
-                    .map_err(|e| format!("读取文件失败 {}: {}", path.display(), e))?;
-                Self::add_file_to_zip(zip, &zip_path, &content, manifest)?;
+                Self::add_file_to_zip(zip, &zip_path, &path, manifest)?;
             }
         }
         Ok(())
@@ -266,6 +283,84 @@ impl BackupEngine {
 mod tests {
     use super::*;
 
+    /// 流式写入必须跨分块边界算出与全量读取一致的 SHA256。
+    ///
+    /// 缓冲区是 64KB，这里构造远超一块的内容（含 5 个跨块点），
+    /// 一旦分块拼接或 hasher 更新有错，哈希立刻对不上。
+    #[test]
+    fn test_streamed_sha256_matches_full_read() {
+        let tmp_dir = tempfile::tempdir().expect("创建临时目录失败");
+        let project_root = tmp_dir.path();
+
+        // 约 300KB，跨越 5 个 64KB 分块
+        let content: Vec<u8> = (0..300 * 1024).map(|i| (i % 251) as u8).collect();
+        let big_file = project_root.join("big.bin");
+        fs::write(&big_file, &content).expect("写入大文件失败");
+
+        let services_dir = project_root.join("services");
+        fs::create_dir_all(&services_dir).expect("创建 services 失败");
+        fs::write(services_dir.join("big.bin"), &content).expect("写入失败");
+
+        let backup_path = project_root.join("backup.zip");
+        let rt = tokio::runtime::Runtime::new().unwrap();
+        rt.block_on(BackupEngine::create_backup(
+            backup_path.to_str().unwrap(),
+            BackupOptions {
+                include_projects: true,
+                project_patterns: vec!["big.bin".to_string()],
+                include_logs: false,
+            },
+            project_root,
+            None,
+        ))
+        .expect("备份失败");
+
+        let file = fs::File::open(&backup_path).expect("打开备份文件失败");
+        let mut archive = zip::ZipArchive::new(file).expect("解析 ZIP 失败");
+
+        // manifest 里的哈希必须等于全量读取算出的哈希
+        use std::io::Read;
+        let manifest: BackupManifest = {
+            let mut manifest_file = archive.by_name("manifest.json").unwrap();
+            let mut manifest_json = String::new();
+            manifest_file.read_to_string(&mut manifest_json).unwrap();
+            serde_json::from_str(&manifest_json).expect("解析 manifest 失败")
+        };
+
+        let expected = BackupEngine::compute_sha256(&content);
+        assert_eq!(
+            manifest.files.get("projects/big.bin"),
+            Some(&expected),
+            "流式写入的哈希与全量读取不一致"
+        );
+        assert_eq!(
+            manifest.files.get("services/big.bin"),
+            Some(&expected),
+            "目录递归同样应走流式写入"
+        );
+
+        // 内容本身也必须完整（哈希对但内容丢字节的情况要排除）
+        let mut zipped = Vec::new();
+        {
+            let mut entry = archive.by_name("projects/big.bin").unwrap();
+            entry.read_to_end(&mut zipped).unwrap();
+        }
+        assert_eq!(zipped.len(), content.len(), "ZIP 内文件大小不符");
+    }
+
+    #[test]
+    fn test_add_file_to_zip_missing_file_reports_error() {
+        let tmp_dir = tempfile::tempdir().expect("创建临时目录失败");
+        let backup_path = tmp_dir.path().join("out.zip");
+        let file = fs::File::create(&backup_path).expect("创建备份文件失败");
+        let mut zip = zip::ZipWriter::new(file);
+        let mut manifest = BackupManifest::new();
+
+        let missing = tmp_dir.path().join("nope.txt");
+        let result = BackupEngine::add_file_to_zip(&mut zip, "nope.txt", &missing, &mut manifest);
+        assert!(result.is_err(), "缺失文件应返回错误而不是 panic");
+    }
+
     #[test]
     fn test_compute_sha256() {
         // Known SHA256 for "hello world"
@@ -293,8 +388,7 @@ mod tests {
         let project_root = tmp_dir.path();
 
         // Create .env and docker-compose.yml in the temp project root
-        fs::write(project_root.join(".env"), "PHP82_VERSION=8.2.27\n")
-            .expect("写入 .env 失败");
+        fs::write(project_root.join(".env"), "PHP82_VERSION=8.2.27\n").expect("写入 .env 失败");
         fs::write(
             project_root.join("docker-compose.yml"),
             "version: '3'\nservices:\n  php:\n    image: php:8.2\n",
@@ -304,8 +398,7 @@ mod tests {
         // Create a services/ directory with a config file
         let services_dir = project_root.join("services/php82");
         fs::create_dir_all(&services_dir).expect("创建 services 目录失败");
-        fs::write(services_dir.join("php.ini"), "memory_limit=256M\n")
-            .expect("写入 php.ini 失败");
+        fs::write(services_dir.join("php.ini"), "memory_limit=256M\n").expect("写入 php.ini 失败");
 
         // Create user custom configuration files
         fs::write(
diff --git a/src-tauri/src/engine/backup_manifest.rs b/src-tauri/src/engine/backup_manifest.rs
index dd77d9f..8b8ba52 100644
--- a/src-tauri/src/engine/backup_manifest.rs
+++ b/src-tauri/src/engine/backup_manifest.rs
@@ -48,8 +48,7 @@ impl Default for BackupManifest {
 impl BackupManifest {
     /// 序列化为格式化的 JSON 字符串（缩进 2 空格）
     pub fn serialize(&self) -> Result<String, String> {
-        serde_json::to_string_pretty(self)
-            .map_err(|e| format!("序列化 manifest 失败: {e}"))
+        serde_json::to_string_pretty(self).map_err(|e| format!("序列化 manifest 失败: {e}"))
     }
 
     /// 从 JSON 字符串反序列化，缺少必需字段时返回描述性错误
@@ -94,7 +93,6 @@ impl BackupManifest {
     }
 }
 
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -105,14 +103,8 @@ mod tests {
         ports.insert(8080, 80);
 
         let mut files = HashMap::new();
-        files.insert(
-            ".env".to_string(),
-            "abc123def456".to_string(),
-        );
-        files.insert(
-            "docker-compose.yml".to_string(),
-            "789xyz000111".to_string(),
-        );
+        files.insert(".env".to_string(), "abc123def456".to_string());
+        files.insert("docker-compose.yml".to_string(), "789xyz000111".to_string());
 
         BackupManifest {
             version: "1.0.0".to_string(),
@@ -147,8 +139,7 @@ mod tests {
     fn test_serialize_deserialize_roundtrip() {
         let manifest = sample_manifest();
         let json = manifest.serialize().expect("serialize should succeed");
-        let deserialized =
-            BackupManifest::deserialize(&json).expect("deserialize should succeed");
+        let deserialized = BackupManifest::deserialize(&json).expect("deserialize should succeed");
         assert_eq!(manifest, deserialized);
     }
 
diff --git a/src-tauri/src/engine/config_extractor.rs b/src-tauri/src/engine/config_extractor.rs
index 4d7f00a..e04458d 100644
--- a/src-tauri/src/engine/config_extractor.rs
+++ b/src-tauri/src/engine/config_extractor.rs
@@ -131,7 +131,10 @@ impl ConfigExtractor {
             .status()
             .map_err(|e| format!("docker pull 启动失败: {e}"))?;
         if !status.success() {
-            return Err(format!("docker pull {image_tag} 失败（exit code: {:?}）", status.code()));
+            return Err(format!(
+                "docker pull {image_tag} 失败（exit code: {:?}）",
+                status.code()
+            ));
         }
         app_log!(
             info,
@@ -317,12 +320,10 @@ impl ConfigExtractor {
                     "redis.conf".to_string(),
                 ))
             }
-            VmServiceType::Nginx => {
-                Ok((
-                    vec!["/etc/nginx/nginx.conf".to_string()],
-                    "nginx.conf".to_string(),
-                ))
-            }
+            VmServiceType::Nginx => Ok((
+                vec!["/etc/nginx/nginx.conf".to_string()],
+                "nginx.conf".to_string(),
+            )),
         }
     }
 
@@ -358,11 +359,20 @@ mod tests {
         assert_eq!(ConfigExtractor::major_version_from_tag("php:5.6-fpm"), 5);
         assert_eq!(ConfigExtractor::major_version_from_tag("mysql:8.4"), 8);
         assert_eq!(ConfigExtractor::major_version_from_tag("mysql:5.7"), 5);
-        assert_eq!(ConfigExtractor::major_version_from_tag("redis:7.2-alpine"), 7);
+        assert_eq!(
+            ConfigExtractor::major_version_from_tag("redis:7.2-alpine"),
+            7
+        );
         assert_eq!(ConfigExtractor::major_version_from_tag("redis:8.0"), 8);
-        assert_eq!(ConfigExtractor::major_version_from_tag("nginx:1.27-alpine"), 1);
+        assert_eq!(
+            ConfigExtractor::major_version_from_tag("nginx:1.27-alpine"),
+            1
+        );
         // 边缘情况
-        assert_eq!(ConfigExtractor::major_version_from_tag("library/php:8.5-fpm"), 8);
+        assert_eq!(
+            ConfigExtractor::major_version_from_tag("library/php:8.5-fpm"),
+            8
+        );
         assert_eq!(ConfigExtractor::major_version_from_tag("invalid"), 0);
         assert_eq!(ConfigExtractor::major_version_from_tag(""), 0);
     }
@@ -370,16 +380,19 @@ mod tests {
     #[test]
     fn test_extract_paths_php() {
         // 5.6 走老路径
-        let (srcs, dest) = ConfigExtractor::extract_paths(&VmServiceType::Php, "php:5.6-fpm").unwrap();
+        let (srcs, dest) =
+            ConfigExtractor::extract_paths(&VmServiceType::Php, "php:5.6-fpm").unwrap();
         assert_eq!(srcs, vec!["/usr/local/etc/php/php.ini"]);
         assert_eq!(dest, "php.ini");
 
         // 7.x+ 走 -production
-        let (srcs, dest) = ConfigExtractor::extract_paths(&VmServiceType::Php, "php:7.4-fpm").unwrap();
+        let (srcs, dest) =
+            ConfigExtractor::extract_paths(&VmServiceType::Php, "php:7.4-fpm").unwrap();
         assert_eq!(srcs, vec!["/usr/local/etc/php/php.ini-production"]);
         assert_eq!(dest, "php.ini");
 
-        let (srcs, dest) = ConfigExtractor::extract_paths(&VmServiceType::Php, "php:8.5-fpm").unwrap();
+        let (srcs, dest) =
+            ConfigExtractor::extract_paths(&VmServiceType::Php, "php:8.5-fpm").unwrap();
         assert_eq!(srcs, vec!["/usr/local/etc/php/php.ini-production"]);
         assert_eq!(dest, "php.ini");
     }
@@ -387,12 +400,14 @@ mod tests {
     #[test]
     fn test_extract_paths_mysql() {
         // 5.x 走 /etc/mysql/my.cnf
-        let (srcs, dest) = ConfigExtractor::extract_paths(&VmServiceType::Mysql, "mysql:5.7").unwrap();
+        let (srcs, dest) =
+            ConfigExtractor::extract_paths(&VmServiceType::Mysql, "mysql:5.7").unwrap();
         assert_eq!(srcs, vec!["/etc/mysql/my.cnf"]);
         assert_eq!(dest, "mysql.cnf");
 
         // 8.x 走 /etc/my.cnf
-        let (srcs, dest) = ConfigExtractor::extract_paths(&VmServiceType::Mysql, "mysql:8.4").unwrap();
+        let (srcs, dest) =
+            ConfigExtractor::extract_paths(&VmServiceType::Mysql, "mysql:8.4").unwrap();
         assert_eq!(srcs, vec!["/etc/my.cnf"]);
         assert_eq!(dest, "mysql.cnf");
     }
@@ -400,18 +415,21 @@ mod tests {
     #[test]
     fn test_extract_paths_redis() {
         // 全部版本统一
-        let (srcs, dest) = ConfigExtractor::extract_paths(&VmServiceType::Redis, "redis:7.2-alpine").unwrap();
+        let (srcs, dest) =
+            ConfigExtractor::extract_paths(&VmServiceType::Redis, "redis:7.2-alpine").unwrap();
         assert_eq!(srcs, vec!["/usr/local/etc/redis/redis.conf"]);
         assert_eq!(dest, "redis.conf");
 
-        let (srcs, dest) = ConfigExtractor::extract_paths(&VmServiceType::Redis, "redis:8.2-alpine").unwrap();
+        let (srcs, dest) =
+            ConfigExtractor::extract_paths(&VmServiceType::Redis, "redis:8.2-alpine").unwrap();
         assert_eq!(srcs, vec!["/usr/local/etc/redis/redis.conf"]);
         assert_eq!(dest, "redis.conf");
     }
 
     #[test]
     fn test_extract_paths_nginx() {
-        let (srcs, dest) = ConfigExtractor::extract_paths(&VmServiceType::Nginx, "nginx:1.27-alpine").unwrap();
+        let (srcs, dest) =
+            ConfigExtractor::extract_paths(&VmServiceType::Nginx, "nginx:1.27-alpine").unwrap();
         assert_eq!(srcs, vec!["/etc/nginx/nginx.conf"]);
         assert_eq!(dest, "nginx.conf");
     }
@@ -435,12 +453,8 @@ mod tests {
         let dest_file = dest_dir.join("mysql.cnf");
         fs::write(&dest_file, "user customized content").unwrap();
 
-        let result = ConfigExtractor::extract_config(
-            &VmServiceType::Mysql,
-            svc_dir,
-            "mysql:5.6",
-            &tmp,
-        );
+        let result =
+            ConfigExtractor::extract_config(&VmServiceType::Mysql, svc_dir, "mysql:5.6", &tmp);
         match result {
             ExtractOutcome::SkippedExists => {
                 // 验证文件未被覆盖
diff --git a/src-tauri/src/engine/config_generator.rs b/src-tauri/src/engine/config_generator.rs
index 17cd43e..315283b 100644
--- a/src-tauri/src/engine/config_generator.rs
+++ b/src-tauri/src/engine/config_generator.rs
@@ -1,14 +1,14 @@
+use chrono::Local;
 use serde::{Deserialize, Serialize};
-use std::path::{Path, PathBuf};
 use std::io::Write;
-use chrono::Local;
+use std::path::{Path, PathBuf};
 use zip::write::FileOptions;
 
+use super::config_extractor::{ConfigExtractor, ExtractOutcome};
 use super::env_parser::EnvFile;
-use super::version_manifest::{VersionManifest, ServiceType as VmServiceType};
-use super::user_override_manager::UserOverrideManager;
 use super::mirror_config_manager::UserMirrorConfig;
-use super::config_extractor::{ConfigExtractor, ExtractOutcome};
+use super::user_override_manager::UserOverrideManager;
+use super::version_manifest::{ServiceType as VmServiceType, VersionManifest};
 use crate::app_log;
 
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
@@ -32,7 +32,7 @@ pub struct EnvConfig {
     pub services: Vec<ServiceEntry>,
     pub source_dir: String,
     pub timezone: String,
-    pub mysql_root_password: Option<String>,  // MySQL root密码（可选）
+    pub mysql_root_password: Option<String>, // MySQL root密码（可选）
 }
 
 pub struct ConfigGenerator;
@@ -49,14 +49,14 @@ pub enum ConfigSource {
 }
 
 /// 检测宿主机当前用户的 UID/GID
-/// 
+///
 /// - Linux: 精确检测当前用户 ID（唯一需要精确映射的平台）
 /// - Windows/macOS: 返回默认值 1000，依赖 Docker Desktop 的权限转换层
 fn detect_host_uid_gid() -> Result<(u32, u32), String> {
     #[cfg(target_os = "linux")]
     {
         use std::process::Command;
-        
+
         let uid_output = Command::new("id")
             .arg("-u")
             .output()
@@ -65,7 +65,7 @@ fn detect_host_uid_gid() -> Result<(u32, u32), String> {
             .trim()
             .parse::<u32>()
             .map_err(|e| format!("Invalid UID: {}", e))?;
-        
+
         let gid_output = Command::new("id")
             .arg("-g")
             .output()
@@ -74,10 +74,10 @@ fn detect_host_uid_gid() -> Result<(u32, u32), String> {
             .trim()
             .parse::<u32>()
             .map_err(|e| format!("Invalid GID: {}", e))?;
-        
+
         Ok((uid, gid))
     }
-    
+
     #[cfg(not(target_os = "linux"))]
     {
         // Windows/macOS 下 Docker Desktop 自动处理权限转换
@@ -142,7 +142,11 @@ impl ConfigGenerator {
     ///
     /// Note: `ServiceEntry.version` is now a manifest ID (e.g., "php82", "mysql84").
     /// `project_root` is the user's workspace directory where `.user_version_overrides.json` resides.
-    pub fn generate_env(config: &EnvConfig, existing_env: Option<&EnvFile>, project_root: &Path) -> EnvFile {
+    pub fn generate_env(
+        config: &EnvConfig,
+        existing_env: Option<&EnvFile>,
+        project_root: &Path,
+    ) -> EnvFile {
         let mut env = if let Some(existing) = existing_env {
             existing.clone()
         } else {
@@ -204,19 +208,13 @@ impl ConfigGenerator {
             match &service.service_type {
                 ServiceType::PHP => {
                     // Use entry.image_tag directly (e.g., "php:8.2-fpm")
-                    env.set(
-                        &format!("{env_prefix}_VERSION"),
-                        &entry.image_tag,
-                    );
+                    env.set(&format!("{env_prefix}_VERSION"), &entry.image_tag);
                     env.set(
                         &format!("{env_prefix}_HOST_PORT"),
                         &service.host_port.to_string(),
                     );
                     if let Some(exts) = &service.extensions {
-                        env.set(
-                            &format!("{env_prefix}_EXTENSIONS"),
-                            &exts.join(","),
-                        );
+                        env.set(&format!("{env_prefix}_EXTENSIONS"), &exts.join(","));
                     }
                     env.set(
                         &format!("{env_prefix}_PHP_CONF_FILE"),
@@ -233,28 +231,61 @@ impl ConfigGenerator {
                 }
                 ServiceType::MySQL => {
                     env.set(&format!("{env_prefix}_VERSION"), &entry.image_tag);
-                    env.set(&format!("{env_prefix}_HOST_PORT"), &service.host_port.to_string());
-                    
+                    env.set(
+                        &format!("{env_prefix}_HOST_PORT"),
+                        &service.host_port.to_string(),
+                    );
+
                     // 设置MySQL root密码（优先使用用户配置的密码）
                     let root_password = config.mysql_root_password.as_deref().unwrap_or("root");
                     env.set("MYSQL_ROOT_PASSWORD", root_password);
-                    
-                    env.set(&format!("{env_prefix}_CONF_FILE"), &format!("./services/{service_dir}/mysql.cnf"));
-                    env.set(&format!("{env_prefix}_DATA_DIR"), &format!("./data/{service_dir}"));
-                    env.set(&format!("{env_prefix}_LOG_DIR"), &format!("./logs/{service_dir}"));
+
+                    env.set(
+                        &format!("{env_prefix}_CONF_FILE"),
+                        &format!("./services/{service_dir}/mysql.cnf"),
+                    );
+                    env.set(
+                        &format!("{env_prefix}_DATA_DIR"),
+                        &format!("./data/{service_dir}"),
+                    );
+                    env.set(
+                        &format!("{env_prefix}_LOG_DIR"),
+                        &format!("./logs/{service_dir}"),
+                    );
                 }
                 ServiceType::Redis => {
                     env.set(&format!("{env_prefix}_VERSION"), &entry.image_tag);
-                    env.set(&format!("{env_prefix}_HOST_PORT"), &service.host_port.to_string());
-                    env.set(&format!("{env_prefix}_CONF_FILE"), &format!("./services/{service_dir}/redis.conf"));
-                    env.set(&format!("{env_prefix}_DATA_DIR"), &format!("./data/{service_dir}"));
+                    env.set(
+                        &format!("{env_prefix}_HOST_PORT"),
+                        &service.host_port.to_string(),
+                    );
+                    env.set(
+                        &format!("{env_prefix}_CONF_FILE"),
+                        &format!("./services/{service_dir}/redis.conf"),
+                    );
+                    env.set(
+                        &format!("{env_prefix}_DATA_DIR"),
+                        &format!("./data/{service_dir}"),
+                    );
                 }
                 ServiceType::Nginx => {
                     env.set(&format!("{env_prefix}_VERSION"), &entry.image_tag);
-                    env.set(&format!("{env_prefix}_HTTP_HOST_PORT"), &service.host_port.to_string());
-                    env.set(&format!("{env_prefix}_BUILD_CONTEXT"), &format!("./services/{service_dir}"));
-                    env.set(&format!("{env_prefix}_CONF_FILE"), &format!("./services/{service_dir}/nginx.conf"));
-                    env.set(&format!("{env_prefix}_CONFD_DIR"), &format!("./services/{service_dir}/conf.d"));
+                    env.set(
+                        &format!("{env_prefix}_HTTP_HOST_PORT"),
+                        &service.host_port.to_string(),
+                    );
+                    env.set(
+                        &format!("{env_prefix}_BUILD_CONTEXT"),
+                        &format!("./services/{service_dir}"),
+                    );
+                    env.set(
+                        &format!("{env_prefix}_CONF_FILE"),
+                        &format!("./services/{service_dir}/nginx.conf"),
+                    );
+                    env.set(
+                        &format!("{env_prefix}_CONFD_DIR"),
+                        &format!("./services/{service_dir}/conf.d"),
+                    );
                     env.set("NGINX_LOG_DIR", "./logs/nginx");
                 }
             }
@@ -268,21 +299,21 @@ impl ConfigGenerator {
                     env.set("APT_MIRROR", &apt_cat.source);
                 }
             }
-            
+
             // Composer Mirror
             if let Some(composer_cat) = user_mirror_config.get_category("composer") {
                 if composer_cat.enabled && !composer_cat.source.is_empty() {
                     env.set("COMPOSER_MIRROR", &composer_cat.source);
                 }
             }
-            
+
             // NPM Mirror
             if let Some(npm_cat) = user_mirror_config.get_category("npm") {
                 if npm_cat.enabled && !npm_cat.source.is_empty() {
                     env.set("NPM_MIRROR", &npm_cat.source);
                 }
             }
-            
+
             // GitHub Proxy
             if let Some(github_cat) = user_mirror_config.get_category("github_proxy") {
                 if github_cat.enabled && !github_cat.source.is_empty() {
@@ -335,13 +366,23 @@ impl ConfigGenerator {
                     lines.push(format!("      context: ./services/{service_dir}"));
                     lines.push("      args:".to_string());
                     // Pass the full image tag to Dockerfile's PHP_BASE_IMAGE ARG
-                    lines.push(format!("        PHP_BASE_IMAGE: \"${{{env_prefix}_VERSION}}\""));
-                    lines.push(format!("        PHP_EXTENSIONS: \"${{{env_prefix}_EXTENSIONS}}\""));
+                    lines.push(format!(
+                        "        PHP_BASE_IMAGE: \"${{{env_prefix}_VERSION}}\""
+                    ));
+                    lines.push(format!(
+                        "        PHP_EXTENSIONS: \"${{{env_prefix}_EXTENSIONS}}\""
+                    ));
                     lines.push("        TZ: \"${TZ}\"".to_string());
                     // 镜像源配置（Debian APT 加速，适用于所有 PHP 版本）
                     // 注意：所有 PHP Dockerfile 现已统一使用 Debian 基础镜像（与 version_manifest.json 一致）
-                    lines.push("        DEBIAN_MIRROR_DOMAIN: \"${APT_MIRROR:-deb.debian.org}\"".to_string());
-                    lines.push("        COMPOSER_MIRROR: \"${COMPOSER_MIRROR:-https://packagist.org}\"".to_string());
+                    lines.push(
+                        "        DEBIAN_MIRROR_DOMAIN: \"${APT_MIRROR:-deb.debian.org}\""
+                            .to_string(),
+                    );
+                    lines.push(
+                        "        COMPOSER_MIRROR: \"${COMPOSER_MIRROR:-https://packagist.org}\""
+                            .to_string(),
+                    );
                     lines.push("        GITHUB_PROXY: \"${GITHUB_PROXY:-}\"".to_string());
                     // File permissions configuration
                     lines.push("        PUID: \"${PUID:-1000}\"".to_string());
@@ -357,9 +398,7 @@ impl ConfigGenerator {
                     lines.push(format!(
                         "      - ${{{env_prefix}_FPM_CONF_FILE}}:/usr/local/etc/php-fpm.d/www.conf"
                     ));
-                    lines.push(format!(
-                        "      - ${{{env_prefix}_LOG_DIR}}:/var/log/php"
-                    ));
+                    lines.push(format!("      - ${{{env_prefix}_LOG_DIR}}:/var/log/php"));
                     lines.push("    restart: always".to_string());
                     lines.push("    networks:".to_string());
                     lines.push("      - php-stack-network".to_string());
@@ -401,11 +440,11 @@ impl ConfigGenerator {
                     lines.push(format!(
                         "      - ${{{env_prefix}_CONF_FILE}}:/etc/redis.conf:ro"
                     ));
-                    lines.push(format!(
-                        "      - ${{{env_prefix}_DATA_DIR}}:/data/:rw"
-                    ));
+                    lines.push(format!("      - ${{{env_prefix}_DATA_DIR}}:/data/:rw"));
                     lines.push("    restart: always".to_string());
-                    lines.push("    entrypoint: [\"redis-server\", \"/etc/redis.conf\"]".to_string());
+                    lines.push(
+                        "    entrypoint: [\"redis-server\", \"/etc/redis.conf\"]".to_string(),
+                    );
                     lines.push("    networks:".to_string());
                     lines.push("      - php-stack-network".to_string());
                     lines.push(String::new());
@@ -416,7 +455,9 @@ impl ConfigGenerator {
                     lines.push(format!("      context: ${{{env_prefix}_BUILD_CONTEXT}}"));
                     lines.push("      args:".to_string());
                     // Pass the full image tag to Dockerfile's NGINX_BASE_IMAGE ARG
-                    lines.push(format!("        NGINX_BASE_IMAGE: \"${{{env_prefix}_VERSION}}\""));
+                    lines.push(format!(
+                        "        NGINX_BASE_IMAGE: \"${{{env_prefix}_VERSION}}\""
+                    ));
                     // File permissions configuration
                     lines.push("        PUID: \"${PUID:-1000}\"".to_string());
                     lines.push("        PGID: \"${PGID:-1000}\"".to_string());
@@ -468,7 +509,11 @@ impl ConfigGenerator {
                     candidates.push(src_tauri.join("services"));
                 }
                 // 3. 测试二进制布局：exe_dir 为 src-tauri/target/<profile>/deps/
-                if let Some(src_tauri) = exe_dir.parent().and_then(|p| p.parent()).and_then(|p| p.parent()) {
+                if let Some(src_tauri) = exe_dir
+                    .parent()
+                    .and_then(|p| p.parent())
+                    .and_then(|p| p.parent())
+                {
                     candidates.push(src_tauri.join("services"));
                 }
             }
@@ -521,8 +566,7 @@ impl ConfigGenerator {
 
         // Create destination directory if needed
         if let Some(parent) = dest_path.parent() {
-            std::fs::create_dir_all(parent)
-                .map_err(|e| format!("创建目录失败: {e}"))?;
+            std::fs::create_dir_all(parent).map_err(|e| format!("创建目录失败: {e}"))?;
         }
 
         // Copy file (destination is guaranteed not to exist at this point)
@@ -584,12 +628,8 @@ impl ConfigGenerator {
         }
 
         // 3. 调用 ConfigExtractor 从官方镜像提取
-        let extract_outcome = ConfigExtractor::extract_config(
-            service_type,
-            service_dir,
-            image_tag,
-            dest_root,
-        );
+        let extract_outcome =
+            ConfigExtractor::extract_config(service_type, service_dir, image_tag, dest_root);
         match extract_outcome {
             ExtractOutcome::Extracted { dest, bytes } => {
                 app_log!(
@@ -646,9 +686,9 @@ impl ConfigGenerator {
         };
 
         // Check if the exact service_dir template exists in any candidate base dir
-        let exact_found = Self::template_base_candidates().iter().any(|base| {
-            base.join(service_dir).join(key_file).exists()
-        });
+        let exact_found = Self::template_base_candidates()
+            .iter()
+            .any(|base| base.join(service_dir).join(key_file).exists());
         if exact_found {
             return (service_dir.to_string(), false);
         }
@@ -716,11 +756,15 @@ impl ConfigGenerator {
                 });
 
             // Resolve template directory: check if exact service_dir template exists, else fallback
-            let (template_dir, is_fallback) = Self::resolve_template_dir(&service.service_type, &service_dir_name);
+            let (template_dir, is_fallback) =
+                Self::resolve_template_dir(&service.service_type, &service_dir_name);
             if is_fallback {
-                app_log!(info, "engine::config_generator",
+                app_log!(
+                    info,
+                    "engine::config_generator",
                     "模板目录 services/{} 不存在，使用 {} 作为模板源",
-                    service_dir_name, template_dir
+                    service_dir_name,
+                    template_dir
                 );
             }
 
@@ -815,8 +859,12 @@ impl ConfigGenerator {
                     let service_dir = root.join(format!("services/{service_dir_name}"));
                     std::fs::create_dir_all(&service_dir)
                         .map_err(|e| format!("创建 services/{service_dir_name}/ 目录失败: {e}"))?;
-                    std::fs::create_dir_all(root.join(format!("services/{service_dir_name}/conf.d")))
-                        .map_err(|e| format!("创建 services/{service_dir_name}/conf.d/ 目录失败: {e}"))?;
+                    std::fs::create_dir_all(
+                        root.join(format!("services/{service_dir_name}/conf.d")),
+                    )
+                    .map_err(|e| {
+                        format!("创建 services/{service_dir_name}/conf.d/ 目录失败: {e}")
+                    })?;
 
                     // Copy Dockerfile from template (项目自研，不从镜像提取)
                     Self::copy_template_file(
@@ -856,11 +904,11 @@ impl ConfigGenerator {
     /// Returns BackupState or error if pre-check fails
     fn precheck_backup(project_root: &Path) -> Result<BackupState, String> {
         let timestamp = Local::now().format("%Y%m%d_%H%M%S").to_string();
-        
+
         // List of files/directories to backup
         let items_to_backup = vec![".env", "docker-compose.yml", "services"];
         let mut existing_items = Vec::new();
-        
+
         // Check which items exist
         for item in &items_to_backup {
             let path = project_root.join(item);
@@ -868,22 +916,22 @@ impl ConfigGenerator {
                 existing_items.push((*item).to_string());
             }
         }
-        
+
         if existing_items.is_empty() {
             return Ok(BackupState::NothingToBackup);
         }
-        
+
         // Pre-check: verify backup zip file doesn't exist (avoid overwriting old backups)
         let backup_zip_name = format!("config_backup_{timestamp}.zip");
         let backup_zip_path = project_root.join(&backup_zip_name);
-        
+
         if backup_zip_path.exists() {
             return Err(format!("备份文件已存在，请删除后重试: {backup_zip_name}"));
         }
-        
-        Ok(BackupState::Ready { 
-            timestamp, 
-            items: existing_items 
+
+        Ok(BackupState::Ready {
+            timestamp,
+            items: existing_items,
         })
     }
 
@@ -895,22 +943,27 @@ impl ConfigGenerator {
             BackupState::Ready { timestamp, items } => {
                 let backup_zip_name = format!("config_backup_{timestamp}.zip");
                 let backup_zip_path = project_root.join(&backup_zip_name);
-                
-                app_log!(info, "engine::config_generator", "开始创建配置备份: {}", backup_zip_name);
-                
+
+                app_log!(
+                    info,
+                    "engine::config_generator",
+                    "开始创建配置备份: {}",
+                    backup_zip_name
+                );
+
                 // Create ZIP file
                 let file = std::fs::File::create(&backup_zip_path)
                     .map_err(|e| format!("创建备份文件失败: {e}"))?;
                 let mut zip = zip::ZipWriter::new(file);
                 let zip_options = FileOptions::<()>::default()
                     .compression_method(zip::CompressionMethod::Deflated);
-                
+
                 let mut backed_up_count = 0;
-                
+
                 // Add each item to the ZIP
                 for item in &items {
                     let item_path = project_root.join(item);
-                    
+
                     if item_path.is_file() {
                         // Add single file
                         match std::fs::read(&item_path) {
@@ -919,35 +972,61 @@ impl ConfigGenerator {
                                     .map_err(|e| format!("添加文件到ZIP失败: {e}"))?;
                                 zip.write_all(&content)
                                     .map_err(|e| format!("写入文件内容失败: {e}"))?;
-                                app_log!(info, "engine::config_generator", "已添加到备份: {}", item);
+                                app_log!(
+                                    info,
+                                    "engine::config_generator",
+                                    "已添加到备份: {}",
+                                    item
+                                );
                                 backed_up_count += 1;
                             }
                             Err(e) => {
-                                app_log!(error, "engine::config_generator", "读取文件 {} 失败: {}", item, e);
+                                app_log!(
+                                    error,
+                                    "engine::config_generator",
+                                    "读取文件 {} 失败: {}",
+                                    item,
+                                    e
+                                );
                                 // Continue with other files, don't fail entire backup
                             }
                         }
                     } else if item_path.is_dir() {
                         // Add directory recursively
-                        match Self::add_dir_to_zip_recursive(&mut zip, &item_path, item, zip_options) {
+                        match Self::add_dir_to_zip_recursive(
+                            &mut zip,
+                            &item_path,
+                            item,
+                            zip_options,
+                        ) {
                             Ok(count) => {
-                                app_log!(info, "engine::config_generator", "已添加目录 {} ({} 个文件)", item, count);
+                                app_log!(
+                                    info,
+                                    "engine::config_generator",
+                                    "已添加目录 {} ({} 个文件)",
+                                    item,
+                                    count
+                                );
                                 backed_up_count += count;
                             }
                             Err(e) => {
-                                app_log!(error, "engine::config_generator", "添加目录 {} 失败: {}", item, e);
+                                app_log!(
+                                    error,
+                                    "engine::config_generator",
+                                    "添加目录 {} 失败: {}",
+                                    item,
+                                    e
+                                );
                                 // Continue with other items
                             }
                         }
                     }
                 }
-                
+
                 // Add user custom configuration files (same as backup_engine.rs)
-                let user_config_files = vec![
-                    ".user_mirror_config.json",
-                    ".user_version_overrides.json",
-                ];
-                
+                let user_config_files =
+                    vec![".user_mirror_config.json", ".user_version_overrides.json"];
+
                 for config_file in &user_config_files {
                     let config_path = project_root.join(config_file);
                     if config_path.exists() {
@@ -957,33 +1036,54 @@ impl ConfigGenerator {
                                     .map_err(|e| format!("添加用户配置文件到ZIP失败: {e}"))?;
                                 zip.write_all(&content)
                                     .map_err(|e| format!("写入用户配置文件失败: {e}"))?;
-                                app_log!(info, "engine::config_generator", "已添加用户配置: {}", config_file);
+                                app_log!(
+                                    info,
+                                    "engine::config_generator",
+                                    "已添加用户配置: {}",
+                                    config_file
+                                );
                                 backed_up_count += 1;
                             }
                             Err(e) => {
-                                app_log!(warn, "engine::config_generator", "读取用户配置文件 {} 失败: {}", config_file, e);
+                                app_log!(
+                                    warn,
+                                    "engine::config_generator",
+                                    "读取用户配置文件 {} 失败: {}",
+                                    config_file,
+                                    e
+                                );
                                 // Continue with other config files
                             }
                         }
                     }
                 }
-                
+
                 // Finish ZIP file
                 zip.finish().map_err(|e| format!("完成ZIP文件失败: {e}"))?;
-                
+
                 if backed_up_count == 0 {
                     // No files were successfully added, delete the empty ZIP
                     let _ = std::fs::remove_file(&backup_zip_path);
-                    app_log!(warn, "engine::config_generator", "没有文件被成功备份，已删除空ZIP文件");
+                    app_log!(
+                        warn,
+                        "engine::config_generator",
+                        "没有文件被成功备份，已删除空ZIP文件"
+                    );
                     return Ok(vec![]);
                 }
-                
-                app_log!(info, "engine::config_generator", "备份完成: {} (共 {} 个文件/目录项)", backup_zip_name, items.len());
+
+                app_log!(
+                    info,
+                    "engine::config_generator",
+                    "备份完成: {} (共 {} 个文件/目录项)",
+                    backup_zip_name,
+                    items.len()
+                );
                 Ok(vec![backup_zip_name])
             }
         }
     }
-    
+
     /// Recursively add directory contents to ZIP
     fn add_dir_to_zip_recursive(
         zip: &mut zip::ZipWriter<std::fs::File>,
@@ -992,13 +1092,11 @@ impl ConfigGenerator {
         options: FileOptions<()>,
     ) -> Result<usize, String> {
         let mut file_count = 0;
-        
-        for entry in std::fs::read_dir(dir_path)
-            .map_err(|e| format!("读取目录失败: {e}"))?
-        {
+
+        for entry in std::fs::read_dir(dir_path).map_err(|e| format!("读取目录失败: {e}"))? {
             let entry = entry.map_err(|e| format!("读取目录项失败: {e}"))?;
             let path = entry.path();
-            
+
             if path.is_file() {
                 if let Some(file_name) = path.file_name() {
                     let zip_path = format!("{}/{}", zip_base_path, file_name.to_string_lossy());
@@ -1011,19 +1109,26 @@ impl ConfigGenerator {
                             file_count += 1;
                         }
                         Err(e) => {
-                            app_log!(warn, "engine::config_generator", "跳过文件 {:?}: {}", path, e);
+                            app_log!(
+                                warn,
+                                "engine::config_generator",
+                                "跳过文件 {:?}: {}",
+                                path,
+                                e
+                            );
                         }
                     }
                 }
             } else if path.is_dir() {
                 if let Some(dir_name) = path.file_name() {
                     let sub_zip_path = format!("{}/{}", zip_base_path, dir_name.to_string_lossy());
-                    let sub_count = Self::add_dir_to_zip_recursive(zip, &path, &sub_zip_path, options)?;
+                    let sub_count =
+                        Self::add_dir_to_zip_recursive(zip, &path, &sub_zip_path, options)?;
                     file_count += sub_count;
                 }
             }
         }
-        
+
         Ok(file_count)
     }
 
@@ -1032,10 +1137,10 @@ impl ConfigGenerator {
     /// Contains: .env, docker-compose.yml, services/, .user_mirror_config.json, .user_version_overrides.json
     pub fn backup_existing_config(project_root: &Path) -> Result<Vec<String>, String> {
         app_log!(info, "engine::config_generator", "开始预检查备份...");
-        
+
         // Phase 1: Pre-check
         let backup_state = Self::precheck_backup(project_root)?;
-        
+
         // Phase 2: Execute with rollback
         app_log!(info, "engine::config_generator", "执行备份...");
         Self::execute_backup(backup_state, project_root)
@@ -1043,7 +1148,11 @@ impl ConfigGenerator {
 
     /// Apply config: write .env, docker-compose.yml, create directories.
     /// If enable_backup is true, backup existing config files before overwriting.
-    pub async fn apply(config: &EnvConfig, project_root: &Path, enable_backup: bool) -> Result<Vec<String>, String> {
+    pub async fn apply(
+        config: &EnvConfig,
+        project_root: &Path,
+        enable_backup: bool,
+    ) -> Result<Vec<String>, String> {
         // Validate first
         Self::validate(config)?;
 
@@ -1066,18 +1175,20 @@ impl ConfigGenerator {
 
         // Create directory structure
         Self::generate_service_dirs(config, project_root)?;
-        
+
         // Generate .npmrc file in workspace path if NPM mirror is configured
         let npm_mirror = env_file.get("NPM_MIRROR").unwrap_or("");
         if !npm_mirror.is_empty() && npm_mirror != "https://registry.npmjs.org" {
             // 从 workspace.json 获取工作区路径
-            let workspace_path = if let Some(workspace_config) = crate::engine::workspace_manager::WorkspaceManager::load_workspace()? {
+            let workspace_path = if let Some(workspace_config) =
+                crate::engine::workspace_manager::WorkspaceManager::load_workspace()?
+            {
                 PathBuf::from(workspace_config.workspace_path)
             } else {
                 // 如果没有配置 workspace，使用项目根目录作为后备
                 project_root.to_path_buf()
             };
-            
+
             let npmrc_content = format!("registry={npm_mirror}\n");
             let npmrc_path = workspace_path.join(".npmrc");
             std::fs::write(&npmrc_path, npmrc_content)
@@ -1086,7 +1197,6 @@ impl ConfigGenerator {
 
         Ok(backed_up_files)
     }
-
 }
 
 #[cfg(test)]
@@ -1159,8 +1269,7 @@ mod tests {
         let dir = tempfile::tempdir().expect("创建临时目录失败");
         let dest = dir.path().join("Dockerfile");
 
-        ConfigGenerator::copy_template_file("php85/Dockerfile", &dest)
-            .expect("模板释放应成功");
+        ConfigGenerator::copy_template_file("php85/Dockerfile", &dest).expect("模板释放应成功");
 
         assert!(dest.exists(), "目标文件应被释放创建");
         assert!(!std::fs::read_to_string(&dest).unwrap().is_empty());
@@ -1255,7 +1364,8 @@ mod tests {
             mysql_root_password: None,
         };
 
-        let env = ConfigGenerator::generate_env(&config, Some(&existing_env), &std::env::temp_dir());
+        let env =
+            ConfigGenerator::generate_env(&config, Some(&existing_env), &std::env::temp_dir());
         let map = env.to_map();
 
         // Custom variable preserved
diff --git a/src-tauri/src/engine/env_parser.rs b/src-tauri/src/engine/env_parser.rs
index a19c9f0..f1cc959 100644
--- a/src-tauri/src/engine/env_parser.rs
+++ b/src-tauri/src/engine/env_parser.rs
@@ -339,10 +339,7 @@ mod tests {
             } => {
                 assert_eq!(key, "KEY");
                 assert_eq!(value, "value");
-                assert_eq!(
-                    inline_comment,
-                    &Some("# this is a comment".to_string())
-                );
+                assert_eq!(inline_comment, &Some("# this is a comment".to_string()));
             }
             _ => panic!("Expected KeyValue"),
         }
@@ -407,9 +404,7 @@ mod tests {
         assert_eq!(env.get("KEY"), Some("new"));
         // Inline comment should be preserved
         match &env.lines[0] {
-            EnvLine::KeyValue {
-                inline_comment, ..
-            } => {
+            EnvLine::KeyValue { inline_comment, .. } => {
                 assert_eq!(inline_comment, &Some("# comment".to_string()));
             }
             _ => panic!("Expected KeyValue"),
@@ -479,13 +474,12 @@ QUOTED_VALUE='hello world'"#;
         assert_eq!(map.get("QUOTED_VALUE"), Some(&"hello world".to_string()));
 
         // Verify inline comment on APT_MIRROR
-        let apt_line = env.lines.iter().find(|l| {
-            matches!(l, EnvLine::KeyValue { key, .. } if key == "APT_MIRROR")
-        });
+        let apt_line = env
+            .lines
+            .iter()
+            .find(|l| matches!(l, EnvLine::KeyValue { key, .. } if key == "APT_MIRROR"));
         match apt_line {
-            Some(EnvLine::KeyValue {
-                inline_comment, ..
-            }) => {
+            Some(EnvLine::KeyValue { inline_comment, .. }) => {
                 assert_eq!(inline_comment, &Some("# Aliyun mirror".to_string()));
             }
             _ => panic!("Expected APT_MIRROR KeyValue with inline comment"),
diff --git a/src-tauri/src/engine/mirror_config.rs b/src-tauri/src/engine/mirror_config.rs
index ecced7b..9166f27 100644
--- a/src-tauri/src/engine/mirror_config.rs
+++ b/src-tauri/src/engine/mirror_config.rs
@@ -9,7 +9,7 @@ use std::fs;
 use std::path::Path;
 
 /// 镜像源配置
-/// 
+///
 /// 统一管理容器内依赖镜像源（APT/Composer/PyPI/NPM）
 /// 注意：Docker Daemon 的 registry-mirrors 由 docker/mirror.rs 管理
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -19,7 +19,7 @@ pub struct MirrorConfig {
     pub composer_mirror: MirrorSource,
     pub pypi_mirror: MirrorSource,
     pub npm_mirror: MirrorSource,
-    
+
     // Docker 构建代理（可选）
     pub http_proxy: Option<String>,
     pub https_proxy: Option<String>,
@@ -43,24 +43,16 @@ impl MirrorSource {
     pub fn get_url(&self, service: &str) -> String {
         match (self, service) {
             // Docker Registry
-            (MirrorSource::Ustc, "docker") => {
-                "https://docker.mirrors.ustc.edu.cn".to_string()
-            }
-            (MirrorSource::Tencent, "docker") => {
-                "https://mirror.ccs.tencentyun.com".to_string()
-            }
-            
+            (MirrorSource::Ustc, "docker") => "https://docker.mirrors.ustc.edu.cn".to_string(),
+            (MirrorSource::Tencent, "docker") => "https://mirror.ccs.tencentyun.com".to_string(),
+
             // APT
-            (MirrorSource::Aliyun, "apt") => {
-                "http://mirrors.aliyun.com/debian/".to_string()
-            }
+            (MirrorSource::Aliyun, "apt") => "http://mirrors.aliyun.com/debian/".to_string(),
             (MirrorSource::Tsinghua, "apt") => {
                 "https://mirrors.tuna.tsinghua.edu.cn/debian/".to_string()
             }
-            (MirrorSource::Ustc, "apt") => {
-                "https://mirrors.ustc.edu.cn/debian/".to_string()
-            }
-            
+            (MirrorSource::Ustc, "apt") => "https://mirrors.ustc.edu.cn/debian/".to_string(),
+
             // Composer
             (MirrorSource::Aliyun, "composer") => {
                 "https://mirrors.aliyun.com/composer/".to_string()
@@ -68,27 +60,21 @@ impl MirrorSource {
             (MirrorSource::HuaweiCloud, "composer") => {
                 "https://repo.huaweicloud.com/repository/php/".to_string()
             }
-            
+
             // PyPI
-            (MirrorSource::Aliyun, "pypi") => {
-                "https://mirrors.aliyun.com/pypi/simple/".to_string()
-            }
+            (MirrorSource::Aliyun, "pypi") => "https://mirrors.aliyun.com/pypi/simple/".to_string(),
             (MirrorSource::Tsinghua, "pypi") => {
                 "https://pypi.tuna.tsinghua.edu.cn/simple".to_string()
             }
-            
+
             // NPM
-            (MirrorSource::Taobao, "npm") => {
-                "https://registry.npmmirror.com".to_string()
-            }
-            (MirrorSource::Tencent, "npm") => {
-                "https://mirrors.cloud.tencent.com/npm/".to_string()
-            }
-            
+            (MirrorSource::Taobao, "npm") => "https://registry.npmmirror.com".to_string(),
+            (MirrorSource::Tencent, "npm") => "https://mirrors.cloud.tencent.com/npm/".to_string(),
+
             _ => String::new(), // Default or unsupported
         }
     }
-    
+
     /// 转换为字符串标识
     pub fn as_str(&self) -> &str {
         match self {
@@ -101,7 +87,7 @@ impl MirrorSource {
             MirrorSource::Taobao => "taobao",
         }
     }
-    
+
     /// 从字符串解析
     pub fn from_key(s: &str) -> Self {
         match s {
@@ -120,94 +106,113 @@ impl MirrorConfig {
     /// 从 .env 文件加载配置
     pub fn load_from_env() -> Result<Self, String> {
         let env_path = Path::new(".env");
-        
+
         if !env_path.exists() {
             log::warn!("⚠️ .env 文件不存在，使用默认配置");
             return Ok(Self::default());
         }
-        
-        let env_content = fs::read_to_string(env_path)
-            .map_err(|e| format!("读取 .env 文件失败: {e}"))?;
-        
+
+        let env_content =
+            fs::read_to_string(env_path).map_err(|e| format!("读取 .env 文件失败: {e}"))?;
+
         let env_map = Self::parse_env_file(&env_content);
-        
+
         Ok(Self {
             apt_mirror: MirrorSource::from_key(
-                env_map.get("APT_MIRROR").map(|s| s.as_str()).unwrap_or("default")
+                env_map
+                    .get("APT_MIRROR")
+                    .map(|s| s.as_str())
+                    .unwrap_or("default"),
             ),
             composer_mirror: MirrorSource::from_key(
-                env_map.get("COMPOSER_MIRROR").map(|s| s.as_str()).unwrap_or("default")
+                env_map
+                    .get("COMPOSER_MIRROR")
+                    .map(|s| s.as_str())
+                    .unwrap_or("default"),
             ),
             pypi_mirror: MirrorSource::from_key(
-                env_map.get("PYPI_MIRROR").map(|s| s.as_str()).unwrap_or("default")
+                env_map
+                    .get("PYPI_MIRROR")
+                    .map(|s| s.as_str())
+                    .unwrap_or("default"),
             ),
             npm_mirror: MirrorSource::from_key(
-                env_map.get("NPM_MIRROR").map(|s| s.as_str()).unwrap_or("default")
+                env_map
+                    .get("NPM_MIRROR")
+                    .map(|s| s.as_str())
+                    .unwrap_or("default"),
             ),
             http_proxy: env_map.get("HTTP_PROXY").cloned(),
             https_proxy: env_map.get("HTTPS_PROXY").cloned(),
             no_proxy: env_map.get("NO_PROXY").cloned(),
         })
     }
-    
+
     /// 解析 .env 文件内容
     fn parse_env_file(content: &str) -> HashMap<String, String> {
         let mut map = HashMap::new();
-        
+
         for line in content.lines() {
             let line = line.trim();
-            
+
             // 跳过注释和空行
             if line.is_empty() || line.starts_with('#') {
                 continue;
             }
-            
+
             // 解析 KEY=VALUE
             if let Some((key, value)) = line.split_once('=') {
                 let key = key.trim().to_string();
-                let value = value.trim().trim_matches('"').trim_matches('\'').to_string();
+                let value = value
+                    .trim()
+                    .trim_matches('"')
+                    .trim_matches('\'')
+                    .to_string();
                 map.insert(key, value);
             }
         }
-        
+
         map
     }
-    
+
     /// 保存到 .env 文件
     pub fn save_to_env(&self) -> Result<(), String> {
         let env_path = Path::new(".env");
         let mut env_content = if env_path.exists() {
-            fs::read_to_string(env_path)
-                .map_err(|e| format!("读取 .env 文件失败: {e}"))?
+            fs::read_to_string(env_path).map_err(|e| format!("读取 .env 文件失败: {e}"))?
         } else {
             String::new()
         };
-        
+
         // 更新或添加配置项（仅容器内依赖镜像源）
         env_content = Self::update_env_value(&env_content, "APT_MIRROR", self.apt_mirror.as_str());
-        env_content = Self::update_env_value(&env_content, "COMPOSER_MIRROR", self.composer_mirror.as_str());
-        env_content = Self::update_env_value(&env_content, "PYPI_MIRROR", self.pypi_mirror.as_str());
+        env_content = Self::update_env_value(
+            &env_content,
+            "COMPOSER_MIRROR",
+            self.composer_mirror.as_str(),
+        );
+        env_content =
+            Self::update_env_value(&env_content, "PYPI_MIRROR", self.pypi_mirror.as_str());
         env_content = Self::update_env_value(&env_content, "NPM_MIRROR", self.npm_mirror.as_str());
-        
+
         if let Some(proxy) = &self.http_proxy {
             env_content = Self::update_env_value(&env_content, "HTTP_PROXY", proxy);
         }
         if let Some(proxy) = &self.https_proxy {
             env_content = Self::update_env_value(&env_content, "HTTPS_PROXY", proxy);
         }
-        
-        fs::write(env_path, env_content)
-            .map_err(|e| format!("写入 .env 文件失败: {e}"))?;
+
+        fs::write(env_path, env_content).map_err(|e| format!("写入 .env 文件失败: {e}"))?;
         log::info!("✅ 容器内镜像源配置已保存到 .env");
         Ok(())
     }
-    
+
     /// 更新 .env 文件中的值
     fn update_env_value(content: &str, key: &str, value: &str) -> String {
         let lines: Vec<&str> = content.lines().collect();
         let mut new_lines: Vec<String> = Vec::new();
         let mut found = false;
-        
+
         for line in lines {
             if line.trim().starts_with(&format!("{key}=")) {
                 new_lines.push(format!("{key}={value}"));
@@ -216,18 +221,18 @@ impl MirrorConfig {
                 new_lines.push(line.to_string());
             }
         }
-        
+
         if !found {
             new_lines.push(format!("{key}={value}"));
         }
-        
+
         new_lines.join("\n")
     }
-    
+
     /// 生成 Docker 构建参数
     pub fn to_build_args(&self) -> Vec<String> {
         let mut args = Vec::new();
-        
+
         // 添加代理配置
         if let Some(proxy) = &self.http_proxy {
             args.push(format!("HTTP_PROXY={proxy}"));
@@ -238,14 +243,14 @@ impl MirrorConfig {
         if let Some(no_proxy) = &self.no_proxy {
             args.push(format!("NO_PROXY={no_proxy}"));
         }
-        
+
         args
     }
-    
+
     /// 生成 Dockerfile 中的镜像源配置片段
     pub fn to_dockerfile_snippet(&self) -> String {
         let mut snippet = String::new();
-        
+
         // APT 镜像源
         if self.apt_mirror != MirrorSource::Default {
             let apt_url = self.apt_mirror.get_url("apt");
@@ -256,10 +261,12 @@ RUN sed -i 's|deb.debian.org/debian|{}|g' /etc/apt/sources.list && \
 
 ",
                 apt_url.trim_end_matches('/'),
-                apt_url.replace("debian", "debian-security").trim_end_matches('/')
+                apt_url
+                    .replace("debian", "debian-security")
+                    .trim_end_matches('/')
             ));
         }
-        
+
         // Composer 镜像源（先安装 Composer）
         if self.composer_mirror != MirrorSource::Default {
             let composer_url = self.composer_mirror.get_url("composer");
@@ -272,22 +279,22 @@ RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local
                 composer_url.trim_end_matches('/')
             ));
         }
-        
+
         // PyPI 镜像源（暂时禁用，PHP-FPM 镜像不包含 pip）
         // 如果未来需要，可以先安装 Python
         /*
-        if self.pypi_mirror != MirrorSource::Default {
-            let pypi_url = self.pypi_mirror.get_url("pypi");
-            snippet.push_str(&format!(
-                r#"# 配置 PyPI 镜像源
-RUN pip config set global.index-url {}
+                if self.pypi_mirror != MirrorSource::Default {
+                    let pypi_url = self.pypi_mirror.get_url("pypi");
+                    snippet.push_str(&format!(
+                        r#"# 配置 PyPI 镜像源
+        RUN pip config set global.index-url {}
+
+        "#,
+                        pypi_url.trim_end_matches('/')
+                    ));
+                }
+                */
 
-"#,
-                pypi_url.trim_end_matches('/')
-            ));
-        }
-        */
-        
         snippet
     }
 }
@@ -309,23 +316,23 @@ impl Default for MirrorConfig {
 #[cfg(test)]
 mod tests {
     use super::*;
-    
+
     #[test]
     fn test_mirror_source_from_key() {
         assert_eq!(MirrorSource::from_key("aliyun"), MirrorSource::Aliyun);
         assert_eq!(MirrorSource::from_key("tsinghua"), MirrorSource::Tsinghua);
         assert_eq!(MirrorSource::from_key("invalid"), MirrorSource::Default);
     }
-    
+
     #[test]
     fn test_mirror_source_get_url() {
         let url = MirrorSource::Aliyun.get_url("apt");
         assert!(url.contains("aliyun.com"));
-        
+
         let url = MirrorSource::Tsinghua.get_url("pypi");
         assert!(url.contains("tsinghua.edu.cn"));
     }
-    
+
     #[test]
     fn test_parse_env_file() {
         let content = r#"
diff --git a/src-tauri/src/engine/mirror_config_manager.rs b/src-tauri/src/engine/mirror_config_manager.rs
index db08295..2229231 100644
--- a/src-tauri/src/engine/mirror_config_manager.rs
+++ b/src-tauri/src/engine/mirror_config_manager.rs
@@ -36,51 +36,50 @@ impl UserMirrorConfig {
     /// 从文件加载用户配置
     pub fn load(project_root: &Path) -> Result<Self, String> {
         let config_path = project_root.join(".user_mirror_config.json");
-        
+
         if !config_path.exists() {
             return Ok(Self::default());
         }
-        
+
         let content = std::fs::read_to_string(&config_path)
             .map_err(|e| format!("读取用户镜像配置文件失败: {e}"))?;
-        
-        serde_json::from_str(&content)
-            .map_err(|e| format!("解析用户镜像配置文件失败: {e}"))
+
+        serde_json::from_str(&content).map_err(|e| format!("解析用户镜像配置文件失败: {e}"))
     }
-    
+
     /// 保存用户配置到文件
     pub fn save(&self, project_root: &Path) -> Result<(), String> {
         let config_path = project_root.join(".user_mirror_config.json");
-        
+
         let content = serde_json::to_string_pretty(self)
             .map_err(|e| format!("序列化用户镜像配置失败: {e}"))?;
-        
-        std::fs::write(&config_path, content)
-            .map_err(|e| format!("写入用户镜像配置文件失败: {e}"))
+
+        std::fs::write(&config_path, content).map_err(|e| format!("写入用户镜像配置文件失败: {e}"))
     }
-    
+
     /// 检查某个类别是否有用户自定义配置
     pub fn has_user_override(&self, category_id: &str) -> bool {
-        self.categories.get(category_id)
+        self.categories
+            .get(category_id)
             .map(|c| c.enabled)
             .unwrap_or(false)
     }
-    
+
     /// 获取某个类别的自定义配置
     pub fn get_category(&self, category_id: &str) -> Option<&UserMirrorCategory> {
         self.categories.get(category_id)
     }
-    
+
     /// 设置某个类别的自定义配置
     pub fn set_category(&mut self, category_id: String, category: UserMirrorCategory) {
         self.categories.insert(category_id, category);
     }
-    
+
     /// 删除某个类别的自定义配置
     pub fn remove_category(&mut self, category_id: &str) -> Option<UserMirrorCategory> {
         self.categories.remove(category_id)
     }
-    
+
     /// 清空所有自定义配置
     pub fn clear_all(&mut self) {
         self.categories.clear();
@@ -101,9 +100,9 @@ pub struct MirrorSourceOption {
 pub struct MergedMirrorCategory {
     pub category_id: String,
     pub options: Vec<MirrorSourceOption>,
-    pub selected_id: String,        // 当前选中的选项 ID
-    pub current_value: String,      // 当前值
-    pub has_user_override: bool,    // 是否有用户自定义
+    pub selected_id: String,     // 当前选中的选项 ID
+    pub current_value: String,   // 当前值
+    pub has_user_override: bool, // 是否有用户自定义
 }
 
 pub struct MirrorConfigManager;
@@ -112,10 +111,9 @@ impl MirrorConfigManager {
     /// 从嵌入的 JSON 数据加载默认镜像配置
     pub fn load_default_config() -> Result<serde_json::Value, String> {
         let json_data = include_str!("../../services/mirror_config.json");
-        serde_json::from_str(json_data)
-            .map_err(|e| format!("解析 mirror_config.json 失败: {e}"))
+        serde_json::from_str(json_data).map_err(|e| format!("解析 mirror_config.json 失败: {e}"))
     }
-    
+
     /// 获取所有类别 ID 列表
     pub fn get_category_ids() -> Vec<String> {
         vec![
@@ -126,43 +124,42 @@ impl MirrorConfigManager {
             "github_proxy".to_string(),
         ]
     }
-    
+
     /// 获取合并后的镜像源列表（默认配置 + 用户自定义）
-    pub fn get_merged_mirror_list(project_root: &Path) -> Result<Vec<MergedMirrorCategory>, String> {
+    pub fn get_merged_mirror_list(
+        project_root: &Path,
+    ) -> Result<Vec<MergedMirrorCategory>, String> {
         let default_config = Self::load_default_config()?;
         let user_config = UserMirrorConfig::load(project_root)?;
-        
+
         let category_ids = Self::get_category_ids();
         let mut merged_list = Vec::new();
-        
+
         for category_id in category_ids {
             // 从默认配置中获取该类别的选项列表
             let options_value = &default_config[&category_id];
             let options_array = options_value
                 .as_array()
                 .ok_or(format!("mirror_config.json 中缺少类别: {category_id}"))?;
-            
+
             // 解析选项列表
             let options: Vec<MirrorSourceOption> = options_array
                 .iter()
-                .filter_map(|opt| {
-                    serde_json::from_value(opt.clone()).ok()
-                })
+                .filter_map(|opt| serde_json::from_value(opt.clone()).ok())
                 .collect();
-            
+
             if options.is_empty() {
                 continue;
             }
-            
+
             // 确定当前选中的选项
             let has_user_override = user_config.has_user_override(&category_id);
             let (selected_id, current_value, final_options) = if has_user_override {
                 // 用户有自定义配置
                 if let Some(user_cat) = user_config.get_category(&category_id) {
                     // 查找匹配的选项 ID
-                    let matched_option = options.iter()
-                        .find(|opt| opt.value == user_cat.source);
-                    
+                    let matched_option = options.iter().find(|opt| opt.value == user_cat.source);
+
                     if let Some(opt) = matched_option {
                         // 匹配到预设选项
                         (opt.id.clone(), user_cat.source.clone(), options.clone())
@@ -175,19 +172,27 @@ impl MirrorConfigManager {
                             value: user_cat.source.clone(),
                             description: user_cat.description.clone().unwrap_or_default(),
                         });
-                        
-                        ("custom".to_string(), user_cat.source.clone(), opts_with_custom)
+
+                        (
+                            "custom".to_string(),
+                            user_cat.source.clone(),
+                            opts_with_custom,
+                        )
                     }
                 } else {
                     // 回退到第一个选项
-                    (options[0].id.clone(), options[0].value.clone(), options.clone())
+                    (
+                        options[0].id.clone(),
+                        options[0].value.clone(),
+                        options.clone(),
+                    )
                 }
             } else {
                 // 首次设置：没有用户自定义配置
                 // selected_id 返回空字符串，让前端显示所有选项为可点选状态
                 ("".to_string(), String::new(), options.clone())
             };
-            
+
             merged_list.push(MergedMirrorCategory {
                 category_id,
                 options: final_options,
@@ -196,10 +201,10 @@ impl MirrorConfigManager {
                 has_user_override,
             });
         }
-        
+
         Ok(merged_list)
     }
-    
+
     /// 保存用户选择的镜像源选项
     pub fn save_selected_option(
         project_root: &Path,
@@ -211,17 +216,18 @@ impl MirrorConfigManager {
         let options_array = options_value
             .as_array()
             .ok_or(format!("类别 {category_id} 不存在"))?;
-        
+
         // 查找对应的选项值
-        let selected_value = options_array.iter()
+        let selected_value = options_array
+            .iter()
             .find(|opt| opt.get("id").and_then(|v| v.as_str()) == Some(option_id))
             .and_then(|opt| opt.get("value").and_then(|v| v.as_str()))
             .ok_or(format!("选项 {option_id} 不存在于类别 {category_id} 中"))?;
-        
+
         // 保存为用户自定义配置
         Self::save_user_category(project_root, category_id, selected_value, None)
     }
-    
+
     /// 保存用户自定义的单个类别配置
     pub fn save_user_category(
         project_root: &Path,
@@ -230,24 +236,24 @@ impl MirrorConfigManager {
         description: Option<String>,
     ) -> Result<(), String> {
         let mut user_config = UserMirrorConfig::load(project_root)?;
-        
+
         let category = UserMirrorCategory {
             source: source.to_string(),
             enabled: true,
             description,
         };
-        
+
         user_config.set_category(category_id.to_string(), category);
         user_config.save(project_root)
     }
-    
+
     /// 删除用户自定义的类别配置
     pub fn remove_user_category(project_root: &Path, category_id: &str) -> Result<(), String> {
         let mut user_config = UserMirrorConfig::load(project_root)?;
         user_config.remove_category(category_id);
         user_config.save(project_root)
     }
-    
+
     /// 重置所有用户自定义配置
     pub fn reset_all_overrides(project_root: &Path) -> Result<(), String> {
         let mut user_config = UserMirrorConfig::load(project_root)?;
@@ -261,18 +267,18 @@ mod tests {
     use super::*;
     use std::path::PathBuf;
     use tempfile::TempDir;
-    
+
     fn create_test_project() -> (TempDir, PathBuf) {
         let dir = TempDir::new().expect("创建临时目录失败");
         let path = dir.path().to_path_buf();
         (dir, path)
     }
-    
+
     #[test]
     fn test_load_default_config() {
         let config = MirrorConfigManager::load_default_config();
         assert!(config.is_ok());
-        
+
         let config = config.unwrap();
         assert!(config.get("docker_registry").is_some());
         assert!(config.get("apt").is_some());
@@ -280,22 +286,22 @@ mod tests {
         assert!(config.get("npm").is_some());
         assert!(config.get("github_proxy").is_some());
     }
-    
+
     #[test]
     fn test_user_config_save_and_load() {
         let (_dir, path) = create_test_project();
-        
+
         let mut user_config = UserMirrorConfig::default();
-        
+
         let category = UserMirrorCategory {
             source: "https://custom.mirror.com".to_string(),
             enabled: true,
             description: Some("Custom mirror".to_string()),
         };
         user_config.set_category("npm".to_string(), category);
-        
+
         user_config.save(&path).expect("保存配置失败");
-        
+
         let loaded = UserMirrorConfig::load(&path).expect("加载配置失败");
         assert!(loaded.has_user_override("npm"));
         assert_eq!(
@@ -303,17 +309,17 @@ mod tests {
             "https://custom.mirror.com"
         );
     }
-    
+
     #[test]
     fn test_get_merged_mirror_list() {
         let (_dir, path) = create_test_project();
-        
+
         let merged = MirrorConfigManager::get_merged_mirror_list(&path);
         assert!(merged.is_ok());
-        
+
         let merged = merged.unwrap();
         assert!(!merged.is_empty());
-        
+
         // 检查是否包含所有类别
         let category_ids: Vec<&String> = merged.iter().map(|m| &m.category_id).collect();
         assert!(category_ids.contains(&&"docker_registry".to_string()));
diff --git a/src-tauri/src/engine/mirror_manager.rs b/src-tauri/src/engine/mirror_manager.rs
index 5e79dc9..c394d07 100644
--- a/src-tauri/src/engine/mirror_manager.rs
+++ b/src-tauri/src/engine/mirror_manager.rs
@@ -86,14 +86,13 @@ impl MirrorManager {
             .ok_or_else(|| format!("未找到预设方案: {preset_name}"))?;
 
         let content = if env_path.exists() {
-            std::fs::read_to_string(env_path)
-                .map_err(|e| format!("读取 .env 文件失败: {e}"))?
+            std::fs::read_to_string(env_path).map_err(|e| format!("读取 .env 文件失败: {e}"))?
         } else {
             String::new()
         };
 
-        let mut env_file = EnvFile::parse(&content)
-            .map_err(|e| format!("解析 .env 文件失败: {e}"))?;
+        let mut env_file =
+            EnvFile::parse(&content).map_err(|e| format!("解析 .env 文件失败: {e}"))?;
 
         env_file.set("DOCKER_REGISTRY_MIRROR", &preset.docker_registry);
         env_file.set("APT_MIRROR", preset.apt.as_str());
@@ -101,8 +100,7 @@ impl MirrorManager {
         env_file.set("NPM_MIRROR", &preset.npm);
 
         let output = env_file.format();
-        std::fs::write(env_path, output)
-            .map_err(|e| format!("写入 .env 文件失败: {e}"))?;
+        std::fs::write(env_path, output).map_err(|e| format!("写入 .env 文件失败: {e}"))?;
 
         Ok(())
     }
@@ -111,11 +109,7 @@ impl MirrorManager {
     ///
     /// category: "docker", "apt", "composer", "npm", "github"
     /// 只更新指定类别的键，其他类别保持不变。
-    pub fn update_single(
-        category: &str,
-        value: &str,
-        env_path: &Path,
-    ) -> Result<(), String> {
+    pub fn update_single(category: &str, value: &str, env_path: &Path) -> Result<(), String> {
         let key = match category {
             "docker_registry" => "DOCKER_REGISTRY_MIRROR",
             "apt" => "APT_MIRROR",
@@ -126,20 +120,18 @@ impl MirrorManager {
         };
 
         let content = if env_path.exists() {
-            std::fs::read_to_string(env_path)
-                .map_err(|e| format!("读取 .env 文件失败: {e}"))?
+            std::fs::read_to_string(env_path).map_err(|e| format!("读取 .env 文件失败: {e}"))?
         } else {
             String::new()
         };
 
-        let mut env_file = EnvFile::parse(&content)
-            .map_err(|e| format!("解析 .env 文件失败: {e}"))?;
+        let mut env_file =
+            EnvFile::parse(&content).map_err(|e| format!("解析 .env 文件失败: {e}"))?;
 
         env_file.set(key, value);
 
         let output = env_file.format();
-        std::fs::write(env_path, output)
-            .map_err(|e| format!("写入 .env 文件失败: {e}"))?;
+        std::fs::write(env_path, output).map_err(|e| format!("写入 .env 文件失败: {e}"))?;
 
         Ok(())
     }
@@ -159,7 +151,9 @@ impl MirrorManager {
             .map_err(|e| format!("创建 HTTP 客户端失败: {e}"))?;
 
         match client.head(url).send().await {
-            Ok(response) => Ok(response.status().is_success() || response.status().is_redirection()),
+            Ok(response) => {
+                Ok(response.status().is_success() || response.status().is_redirection())
+            }
             Err(e) => {
                 if e.is_timeout() || e.is_connect() {
                     Ok(false)
@@ -175,14 +169,12 @@ impl MirrorManager {
     /// 从 .env 文件中读取 4 个镜像源键的值。
     pub fn get_current_status(env_path: &Path) -> Result<MirrorStatus, String> {
         let content = if env_path.exists() {
-            std::fs::read_to_string(env_path)
-                .map_err(|e| format!("读取 .env 文件失败: {e}"))?
+            std::fs::read_to_string(env_path).map_err(|e| format!("读取 .env 文件失败: {e}"))?
         } else {
             String::new()
         };
 
-        let env_file = EnvFile::parse(&content)
-            .map_err(|e| format!("解析 .env 文件失败: {e}"))?;
+        let env_file = EnvFile::parse(&content).map_err(|e| format!("解析 .env 文件失败: {e}"))?;
 
         Ok(MirrorStatus {
             docker_registry: env_file
@@ -222,7 +214,9 @@ impl MirrorManager {
         if status.docker_registry.is_empty()
             && (status.apt == "default" || status.apt.is_empty())
             && (status.composer == "default" || status.composer.is_empty())
-            && (status.npm == "default" || status.npm.is_empty() || status.npm == "https://registry.npmjs.org")
+            && (status.npm == "default"
+                || status.npm.is_empty()
+                || status.npm == "https://registry.npmjs.org")
         {
             return Ok("官方默认".to_string());
         }
@@ -282,7 +276,9 @@ mod tests {
         MirrorManager::apply_preset("阿里云全套", &env_path).expect("应用预设失败");
 
         let content = fs::read_to_string(&env_path).expect("读取文件失败");
-        assert!(content.contains("DOCKER_REGISTRY_MIRROR=https://registry.cn-hangzhou.aliyuncs.com"));
+        assert!(
+            content.contains("DOCKER_REGISTRY_MIRROR=https://registry.cn-hangzhou.aliyuncs.com")
+        );
         assert!(content.contains("APT_MIRROR=aliyun"));
         assert!(content.contains("COMPOSER_MIRROR=aliyun"));
         assert!(content.contains("NPM_MIRROR=https://registry.npmmirror.com"));
diff --git a/src-tauri/src/engine/mod.rs b/src-tauri/src/engine/mod.rs
index c1ac650..e10bd20 100644
--- a/src-tauri/src/engine/mod.rs
+++ b/src-tauri/src/engine/mod.rs
@@ -1,12 +1,12 @@
-pub mod mirror_config;      // 镜像源配置（向后兼容）
-pub mod env_parser;          // Env 解析器/格式化器
-pub mod backup_manifest;     // 备份清单数据模型与序列化
-pub mod config_generator;   // 可视化配置生成器
-pub mod config_extractor;    // 运行时配置基线提取器（Phase 3）
-pub mod mirror_manager;     // 统一镜像源管理器
-pub mod backup_engine;      // 增强备份引擎
-pub mod restore_engine;     // 恢复引擎
-pub mod version_manifest;   // 版本清单管理器
-pub mod user_override_manager; // 用户版本覆盖管理器
+pub mod backup_engine; // 增强备份引擎
+pub mod backup_manifest; // 备份清单数据模型与序列化
+pub mod config_extractor; // 运行时配置基线提取器（Phase 3）
+pub mod config_generator; // 可视化配置生成器
+pub mod env_parser; // Env 解析器/格式化器
+pub mod mirror_config; // 镜像源配置（向后兼容）
 pub mod mirror_config_manager; // 用户镜像源配置管理器
-pub mod workspace_manager;     // 工作目录管理器
+pub mod mirror_manager; // 统一镜像源管理器
+pub mod restore_engine; // 恢复引擎
+pub mod user_override_manager; // 用户版本覆盖管理器
+pub mod version_manifest; // 版本清单管理器
+pub mod workspace_manager; // 工作目录管理器
diff --git a/src-tauri/src/engine/restore_engine.rs b/src-tauri/src/engine/restore_engine.rs
index 804c144..adc9aa7 100644
--- a/src-tauri/src/engine/restore_engine.rs
+++ b/src-tauri/src/engine/restore_engine.rs
@@ -25,18 +25,46 @@ pub struct RestoreResult {
     pub success: bool,
     pub restored_files: Vec<String>,
     pub errors: Vec<String>,
+    /// 恢复开始前自动生成的回滚包路径（R2）。
+    ///
+    /// 恢复是逐文件覆盖现有配置的破坏性操作，中途失败会留下半恢复状态。
+    /// 该字段指向恢复前的自动备份，用户可用它一键回退。
+    /// 由调用方 `commands::execute_restore` 在创建回滚包后填入。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub rollback_path: Option<String>,
 }
 
 pub struct RestoreEngine;
 
+/// 校验 ZIP 条目名是否安全（zip-slip 路径遍历防护）
+///
+/// 拒绝三类条目：
+/// - 绝对路径（`/etc/passwd`、Windows 盘符 `C:\...` 或 UNC `\\...`）
+/// - 包含父目录引用（`../`）
+/// - 根目录组件
+fn is_safe_entry_name(name: &str) -> bool {
+    let path = std::path::Path::new(name);
+    if path.is_absolute() {
+        return false;
+    }
+    for comp in path.components() {
+        match comp {
+            std::path::Component::ParentDir
+            | std::path::Component::RootDir
+            | std::path::Component::Prefix(_) => return false,
+            _ => {}
+        }
+    }
+    true
+}
+
 impl RestoreEngine {
     /// Parse backup ZIP and return preview info.
     /// Reads manifest.json from ZIP, detects port conflicts, counts files.
     pub fn preview(zip_path: &str) -> Result<RestorePreview, String> {
-        let file = std::fs::File::open(zip_path)
-            .map_err(|e| format!("打开备份文件失败: {e}"))?;
-        let mut archive = zip::ZipArchive::new(file)
-            .map_err(|e| format!("解析 ZIP 文件失败: {e}"))?;
+        let file = std::fs::File::open(zip_path).map_err(|e| format!("打开备份文件失败: {e}"))?;
+        let mut archive =
+            zip::ZipArchive::new(file).map_err(|e| format!("解析 ZIP 文件失败: {e}"))?;
 
         // Read manifest.json
         let manifest = Self::read_manifest_from_archive(&mut archive)?;
@@ -61,10 +89,9 @@ impl RestoreEngine {
     /// For each file in manifest.files, read from ZIP and compute SHA256,
     /// compare with recorded hash.
     pub fn verify_integrity(zip_path: &str) -> Result<bool, String> {
-        let file = std::fs::File::open(zip_path)
-            .map_err(|e| format!("打开备份文件失败: {e}"))?;
-        let mut archive = zip::ZipArchive::new(file)
-            .map_err(|e| format!("解析 ZIP 文件失败: {e}"))?;
+        let file = std::fs::File::open(zip_path).map_err(|e| format!("打开备份文件失败: {e}"))?;
+        let mut archive =
+            zip::ZipArchive::new(file).map_err(|e| format!("解析 ZIP 文件失败: {e}"))?;
 
         let manifest = Self::read_manifest_from_archive(&mut archive)?;
 
@@ -97,10 +124,21 @@ impl RestoreEngine {
         let mut restored_files: Vec<String> = Vec::new();
         let mut errors: Vec<String> = Vec::new();
 
-        let file = std::fs::File::open(zip_path)
-            .map_err(|e| format!("打开备份文件失败: {e}"))?;
-        let mut archive = zip::ZipArchive::new(file)
-            .map_err(|e| format!("解析 ZIP 文件失败: {e}"))?;
+        let file = std::fs::File::open(zip_path).map_err(|e| format!("打开备份文件失败: {e}"))?;
+        let mut archive =
+            zip::ZipArchive::new(file).map_err(|e| format!("解析 ZIP 文件失败: {e}"))?;
+
+        // Step 0: 安全校验——拒绝包含路径遍历条目的备份包，在任何写盘操作之前拦截
+        for i in 0..archive.len() {
+            let name = archive
+                .by_index(i)
+                .map_err(|e| format!("读取 ZIP 条目失败: {e}"))?
+                .name()
+                .to_string();
+            if !is_safe_entry_name(&name) {
+                return Err(format!("备份包包含非法路径条目，已拒绝恢复: {name}"));
+            }
+        }
 
         // Step 1: Read manifest
         Self::emit_progress(app_handle, "解析备份包...", 5);
@@ -115,7 +153,11 @@ impl RestoreEngine {
 
         // Step 3: Extract docker-compose.yml
         Self::emit_progress(app_handle, "恢复 Docker 配置...", 25);
-        match Self::extract_file_to_path(&mut archive, "docker-compose.yml", &project_root.join("docker-compose.yml")) {
+        match Self::extract_file_to_path(
+            &mut archive,
+            "docker-compose.yml",
+            &project_root.join("docker-compose.yml"),
+        ) {
             Ok(()) => restored_files.push("docker-compose.yml".to_string()),
             Err(e) => errors.push(format!("恢复 docker-compose.yml 失败: {e}")),
         }
@@ -129,7 +171,7 @@ impl RestoreEngine {
 
         // Step 4.5: Restore user custom configuration files
         Self::emit_progress(app_handle, "恢复用户自定义配置...", 45);
-        
+
         // .user_mirror_config.json - User mirror source configuration
         match Self::extract_file_to_path(
             &mut archive,
@@ -141,7 +183,7 @@ impl RestoreEngine {
                 // Not a critical error, file may not exist in backup
             }
         }
-        
+
         // .user_version_overrides.json - User version override configuration
         match Self::extract_file_to_path(
             &mut archive,
@@ -179,11 +221,7 @@ impl RestoreEngine {
 
         // Step 7: Extract database/ SQL files
         Self::emit_progress(app_handle, "恢复数据库文件...", 85);
-        match Self::extract_prefix(
-            &mut archive,
-            "database/",
-            &project_root.join("database"),
-        ) {
+        match Self::extract_prefix(&mut archive, "database/", &project_root.join("database")) {
             Ok(files) => restored_files.extend(files),
             Err(e) => errors.push(format!("恢复数据库文件失败: {e}")),
         }
@@ -197,10 +235,11 @@ impl RestoreEngine {
             success: errors.is_empty(),
             restored_files,
             errors,
+            // 由调用方（commands::execute_restore）在创建回滚包后填入
+            rollback_path: None,
         })
     }
 
-
     /// Read manifest.json from a ZIP archive.
     fn read_manifest_from_archive<R: Read + std::io::Seek>(
         archive: &mut zip::ZipArchive<R>,
@@ -233,8 +272,7 @@ impl RestoreEngine {
             .map_err(|e| format!("读取文件内容 '{zip_entry}' 失败: {e}"))?;
 
         if let Some(parent) = target_path.parent() {
-            std::fs::create_dir_all(parent)
-                .map_err(|e| format!("创建目录失败: {e}"))?;
+            std::fs::create_dir_all(parent).map_err(|e| format!("创建目录失败: {e}"))?;
         }
 
         std::fs::write(target_path, &content)
@@ -307,8 +345,7 @@ impl RestoreEngine {
             .map_err(|e| format!("读取 .env 内容失败: {e}"))?;
 
         let env_path = project_root.join(".env");
-        std::fs::write(&env_path, content)
-            .map_err(|e| format!("写入 .env 失败: {e}"))?;
+        std::fs::write(&env_path, content).map_err(|e| format!("写入 .env 失败: {e}"))?;
 
         Ok(())
     }
@@ -328,7 +365,6 @@ impl RestoreEngine {
     }
 }
 
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -339,6 +375,63 @@ mod tests {
     use std::io::Write;
     use zip::write::FileOptions;
 
+    /// Feature: restore-security, Property: 恶意条目名必须被拒绝
+    #[test]
+    fn test_is_safe_entry_name_rejects_traversal() {
+        assert!(!is_safe_entry_name("../evil.txt"));
+        assert!(!is_safe_entry_name("a/../../evil.txt"));
+        assert!(!is_safe_entry_name("/etc/passwd"));
+        assert!(!is_safe_entry_name("C:\\Windows\\evil.txt"));
+        assert!(!is_safe_entry_name("\\\\server\\share\\evil.txt"));
+    }
+
+    #[test]
+    fn test_is_safe_entry_name_accepts_normal_paths() {
+        assert!(is_safe_entry_name(".env"));
+        assert!(is_safe_entry_name("docker-compose.yml"));
+        assert!(is_safe_entry_name("services/php82/php.ini"));
+        assert!(is_safe_entry_name("projects/www/test/index.php"));
+        assert!(is_safe_entry_name(
+            "services/php82/sub/dir/conf.d/default.conf"
+        ));
+    }
+
+    /// Feature: restore-security, Property: 含路径遍历条目的 ZIP 必须整体拒绝且不写盘
+    #[test]
+    fn test_restore_rejects_zip_slip() {
+        let tmp_dir = tempfile::tempdir().expect("创建临时目录失败");
+        let restore_dir = tmp_dir.path().join("restored");
+        fs::create_dir_all(&restore_dir).expect("创建恢复目录失败");
+
+        // 构造含 ../ 逃逸条目的恶意 ZIP
+        let malicious_zip = tmp_dir.path().join("malicious.zip");
+        let file = fs::File::create(&malicious_zip).expect("创建恶意 ZIP 失败");
+        let mut zip = zip::ZipWriter::new(file);
+        let zip_options =
+            FileOptions::<()>::default().compression_method(zip::CompressionMethod::Deflated);
+        zip.start_file("../../escaped.txt", zip_options).unwrap();
+        zip.write_all(b"pwned").unwrap();
+        zip.finish().unwrap();
+
+        let rt = tokio::runtime::Runtime::new().unwrap();
+        let result = rt.block_on(RestoreEngine::restore(
+            malicious_zip.to_str().unwrap(),
+            &restore_dir,
+            None,
+        ));
+
+        assert!(result.is_err(), "含路径遍历条目的备份包必须被拒绝");
+        let err_msg = result.unwrap_err();
+        assert!(
+            err_msg.contains("../../escaped.txt"),
+            "错误信息应指出非法条目，实际: {err_msg}"
+        );
+
+        // 逃逸目标（restore_dir 的上级）不应出现被写入的文件
+        let escaped = tmp_dir.path().join("escaped.txt");
+        assert!(!escaped.exists(), "逃逸文件不应被写入磁盘");
+    }
+
     /// Helper: create a test backup ZIP with manifest and some files.
     fn create_test_backup(dir: &Path) -> String {
         let backup_path = dir.join("test_backup.zip");
@@ -367,7 +460,8 @@ mod tests {
         let php_ini_hash = BackupEngine::compute_sha256(php_ini_content);
 
         // Add user custom configuration files
-        let user_mirror_config_content = b"{\"apt\":{\"source\":\"http://mirrors.aliyun.com/debian/\",\"enabled\":true}}";
+        let user_mirror_config_content =
+            b"{\"apt\":{\"source\":\"http://mirrors.aliyun.com/debian/\",\"enabled\":true}}";
         zip.start_file(".user_mirror_config.json", zip_options)
             .unwrap();
         zip.write_all(user_mirror_config_content).unwrap();
@@ -385,7 +479,10 @@ mod tests {
         files.insert("docker-compose.yml".to_string(), compose_hash);
         files.insert("services/php82/php.ini".to_string(), php_ini_hash);
         files.insert(".user_mirror_config.json".to_string(), user_mirror_hash);
-        files.insert(".user_version_overrides.json".to_string(), user_version_hash);
+        files.insert(
+            ".user_version_overrides.json".to_string(),
+            user_version_hash,
+        );
 
         let mut ports = HashMap::new();
         ports.insert(3306, 3306);
@@ -466,10 +563,7 @@ mod tests {
             services: Vec::new(),
             options: BackupOptions {
                 include_projects: true,
-                project_patterns: vec![
-                    "www/test/**".to_string(),
-                    "www/readme.md".to_string(),
-                ],
+                project_patterns: vec!["www/test/**".to_string(), "www/readme.md".to_string()],
                 include_logs: false,
             },
             files,
@@ -509,8 +603,7 @@ mod tests {
         let tmp_dir = tempfile::tempdir().expect("创建临时目录失败");
         let zip_path = create_test_backup(tmp_dir.path());
 
-        let result =
-            RestoreEngine::verify_integrity(&zip_path).expect("验证完整性失败");
+        let result = RestoreEngine::verify_integrity(&zip_path).expect("验证完整性失败");
         assert!(result, "Valid backup should pass integrity check");
     }
 
@@ -557,10 +650,7 @@ mod tests {
 
         let result = RestoreEngine::verify_integrity(backup_path.to_str().unwrap())
             .expect("验证完整性调用失败");
-        assert!(
-            !result,
-            "Tampered backup should fail integrity check"
-        );
+        assert!(!result, "Tampered backup should fail integrity check");
     }
 
     #[test]
@@ -573,11 +663,7 @@ mod tests {
         fs::create_dir_all(&restore_dir).expect("创建恢复目录失败");
 
         let rt = tokio::runtime::Runtime::new().unwrap();
-        let result = rt.block_on(RestoreEngine::restore(
-            &zip_path,
-            &restore_dir,
-            None,
-        ));
+        let result = rt.block_on(RestoreEngine::restore(&zip_path, &restore_dir, None));
 
         let restore_result = result.expect("恢复操作失败");
         assert!(
@@ -608,8 +694,7 @@ mod tests {
             php_ini_path.exists(),
             "services/php82/php.ini should be restored"
         );
-        let php_ini_content =
-            fs::read_to_string(&php_ini_path).expect("读取 php.ini 失败");
+        let php_ini_content = fs::read_to_string(&php_ini_path).expect("读取 php.ini 失败");
         assert!(
             php_ini_content.contains("memory_limit=256M"),
             "php.ini should contain memory_limit"
@@ -664,11 +749,7 @@ mod tests {
         fs::create_dir_all(&restore_dir).expect("创建恢复目录失败");
 
         let rt = tokio::runtime::Runtime::new().unwrap();
-        let result = rt.block_on(RestoreEngine::restore(
-            &zip_path,
-            &restore_dir,
-            None,
-        ));
+        let result = rt.block_on(RestoreEngine::restore(&zip_path, &restore_dir, None));
 
         let restore_result = result.expect("恢复操作失败");
         assert!(
diff --git a/src-tauri/src/engine/user_override_manager.rs b/src-tauri/src/engine/user_override_manager.rs
index dabdc0c..3800077 100644
--- a/src-tauri/src/engine/user_override_manager.rs
+++ b/src-tauri/src/engine/user_override_manager.rs
@@ -2,7 +2,7 @@ use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use std::path::Path;
 
-use super::version_manifest::{VersionEntry, ServiceType, VersionManifest};
+use super::version_manifest::{ServiceType, VersionEntry, VersionManifest};
 use crate::app_log;
 
 /// 用户自定义的版本覆盖配置
@@ -28,7 +28,7 @@ impl UserOverrideManager {
     pub fn new(project_root: &Path) -> Self {
         let default_manifest = VersionManifest::new();
         let user_overrides = Self::load_user_overrides(project_root);
-        
+
         Self {
             default_manifest,
             user_overrides,
@@ -41,21 +41,32 @@ impl UserOverrideManager {
     ) -> HashMap<ServiceType, HashMap<String, UserVersionOverride>> {
         // 使用 project_root 作为配置文件存放位置（与 .env 同级）
         let overrides_path = project_root.join(".user_version_overrides.json");
-        
+
         if !overrides_path.exists() {
-            app_log!(info, "engine::user_override", "未找到用户覆盖配置文件，使用默认配置");
+            app_log!(
+                info,
+                "engine::user_override",
+                "未找到用户覆盖配置文件，使用默认配置"
+            );
             return HashMap::new();
         }
 
-        app_log!(info, "engine::user_override", "加载用户覆盖配置: {:?}", overrides_path);
+        app_log!(
+            info,
+            "engine::user_override",
+            "加载用户覆盖配置: {:?}",
+            overrides_path
+        );
 
         match std::fs::read_to_string(&overrides_path) {
             Ok(content) => {
-                match serde_json::from_str::<HashMap<String, HashMap<String, UserVersionOverride>>>(&content) {
+                match serde_json::from_str::<HashMap<String, HashMap<String, UserVersionOverride>>>(
+                    &content,
+                ) {
                     Ok(raw) => {
                         let mut result = HashMap::new();
                         let mut override_count = 0;
-                        
+
                         for (service_key, versions) in raw {
                             let service_type = match service_key.as_str() {
                                 "php" => ServiceType::Php,
@@ -65,11 +76,21 @@ impl UserOverrideManager {
                                 _ => continue,
                             };
                             override_count += versions.len();
-                            app_log!(info, "engine::user_override", "{service_key}: {} 个版本覆盖", versions.len());
+                            app_log!(
+                                info,
+                                "engine::user_override",
+                                "{service_key}: {} 个版本覆盖",
+                                versions.len()
+                            );
                             result.insert(service_type, versions);
                         }
-                        
-                        app_log!(info, "engine::user_override", "加载成功，共 {} 个服务类型，{override_count} 个版本覆盖", result.len());
+
+                        app_log!(
+                            info,
+                            "engine::user_override",
+                            "加载成功，共 {} 个服务类型，{override_count} 个版本覆盖",
+                            result.len()
+                        );
                         result
                     }
                     Err(e) => {
@@ -87,22 +108,22 @@ impl UserOverrideManager {
 
     /// 获取合并后的版本条目（用户覆盖 > 默认配置）
     /// 用户覆盖仅替换 image_tag（和可选的 description），其他字段保持 manifest 默认值
-    pub fn get_merged_entry(
-        &self,
-        service_type: &ServiceType,
-        id: &str,
-    ) -> Option<VersionEntry> {
+    pub fn get_merged_entry(&self, service_type: &ServiceType, id: &str) -> Option<VersionEntry> {
         // 1. 检查用户是否有覆盖配置
         if let Some(user_override) = self
             .user_overrides
             .get(service_type)
             .and_then(|entries| entries.get(id))
         {
-            app_log!(info, "engine::user_override", "{} {} 使用自定义标签: {}",
+            app_log!(
+                info,
+                "engine::user_override",
+                "{} {} 使用自定义标签: {}",
                 format!("{service_type:?}").to_lowercase(),
-                id, 
-                user_override.image_tag);
-            
+                id,
+                user_override.image_tag
+            );
+
             // 2. 获取默认配置作为基础
             if let Some(default_info) = self.default_manifest.get_entry(service_type, id) {
                 // 3. 返回合并后的配置（用户覆盖的 image_tag 优先）
@@ -113,7 +134,10 @@ impl UserOverrideManager {
                     default_port: default_info.default_port,
                     show_port: default_info.show_port,
                     eol: default_info.eol,
-                    description: user_override.description.clone().or_else(|| default_info.description.clone()),
+                    description: user_override
+                        .description
+                        .clone()
+                        .or_else(|| default_info.description.clone()),
                 });
             }
         }
@@ -141,8 +165,7 @@ impl UserOverrideManager {
         let json = serde_json::to_string_pretty(&self.user_overrides)
             .map_err(|e| format!("序列化失败: {e}"))?;
 
-        std::fs::write(&overrides_path, json)
-            .map_err(|e| format!("写入文件失败: {e}"))?;
+        std::fs::write(&overrides_path, json).map_err(|e| format!("写入文件失败: {e}"))?;
 
         Ok(())
     }
@@ -163,8 +186,7 @@ impl UserOverrideManager {
         let json = serde_json::to_string_pretty(&self.user_overrides)
             .map_err(|e| format!("序列化失败: {e}"))?;
 
-        std::fs::write(&overrides_path, json)
-            .map_err(|e| format!("写入文件失败: {e}"))?;
+        std::fs::write(&overrides_path, json).map_err(|e| format!("写入文件失败: {e}"))?;
 
         Ok(())
     }
@@ -172,12 +194,11 @@ impl UserOverrideManager {
     /// 重置所有用户覆盖（恢复到默认配置）
     pub fn reset_all_overrides(&mut self, project_root: &Path) -> Result<(), String> {
         self.user_overrides.clear();
-        
+
         // 删除配置文件（与 .env 同级目录）
         let overrides_path = project_root.join(".user_version_overrides.json");
         if overrides_path.exists() {
-            std::fs::remove_file(&overrides_path)
-                .map_err(|e| format!("删除文件失败: {e}"))?;
+            std::fs::remove_file(&overrides_path).map_err(|e| format!("删除文件失败: {e}"))?;
         }
 
         Ok(())
@@ -208,7 +229,7 @@ mod tests {
     fn test_get_default_when_no_override() {
         let temp_dir = env::temp_dir();
         let manager = UserOverrideManager::new(&temp_dir);
-        
+
         let info = manager.get_merged_entry(&ServiceType::Mysql, "mysql80");
         assert!(info.is_some());
         let info = info.unwrap();
diff --git a/src-tauri/src/engine/version_manifest.rs b/src-tauri/src/engine/version_manifest.rs
index 46e9145..ff67c5b 100644
--- a/src-tauri/src/engine/version_manifest.rs
+++ b/src-tauri/src/engine/version_manifest.rs
@@ -120,13 +120,11 @@ impl VersionManifest {
         prefix: &str,
     ) -> Option<(&String, &VersionEntry)> {
         let prefix_lower = prefix.to_lowercase();
-        self.versions
-            .get(service_type)
-            .and_then(|entries| {
-                entries
-                    .iter()
-                    .find(|(_, entry)| entry.service_dir == prefix_lower)
-            })
+        self.versions.get(service_type).and_then(|entries| {
+            entries
+                .iter()
+                .find(|(_, entry)| entry.service_dir == prefix_lower)
+        })
     }
 
     /// 获取指定服务的所有可用版本条目，按版本号降序排列
@@ -171,12 +169,12 @@ impl VersionManifest {
         self.get_entry(service_type, id)
             .filter(|entry| entry.eol)
             .and_then(|entry| {
-                entry.description.as_ref().map(|desc| {
-                    format!("⚠️ {desc} - 建议使用更新版本")
-                })
+                entry
+                    .description
+                    .as_ref()
+                    .map(|desc| format!("⚠️ {desc} - 建议使用更新版本"))
             })
     }
-
 }
 
 /// 从 ID 中提取版本数字用于排序（如 "php82" → (8, 2), "nginx128" → (1, 28)）
@@ -396,8 +394,7 @@ mod tests {
             "_provenance": { "updated_at": "2026-01-01" },
             "mysql": {}
         }"#;
-        let file: ManifestFile =
-            serde_json::from_str(json).expect("字段部分缺失时仍应解析成功");
+        let file: ManifestFile = serde_json::from_str(json).expect("字段部分缺失时仍应解析成功");
         let provenance = file._provenance.expect("_provenance 应被解析");
 
         assert_eq!(provenance.updated_at.as_deref(), Some("2026-01-01"));
@@ -426,6 +423,9 @@ mod tests {
 
         assert_eq!(provenance.updated_at.as_deref(), Some("2026-02-02"));
         let sources = provenance.sources.expect("sources 应被解析");
-        assert_eq!(sources.get("future_key").map(String::as_str), Some("some://url"));
+        assert_eq!(
+            sources.get("future_key").map(String::as_str),
+            Some("some://url")
+        );
     }
 }
diff --git a/src-tauri/src/engine/workspace_manager.rs b/src-tauri/src/engine/workspace_manager.rs
index 2827abc..50d42ff 100644
--- a/src-tauri/src/engine/workspace_manager.rs
+++ b/src-tauri/src/engine/workspace_manager.rs
@@ -2,6 +2,8 @@ use serde::{Deserialize, Serialize};
 use std::fs;
 use std::path::PathBuf;
 
+use crate::commands::paths;
+
 /// 工作目录配置结构
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct WorkspaceConfig {
@@ -12,27 +14,12 @@ pub struct WorkspaceConfig {
 pub struct WorkspaceManager;
 
 impl WorkspaceManager {
-    /// 获取 workspace.json 的路径（位于可执行文件同级）
+    /// 获取 workspace.json 的路径。
+    ///
+    /// 位于应用数据目录（`%APPDATA%\<identifier>` / `~/Library/Application Support/<identifier>`）。
+    /// 此前放在 exe 同级目录，用户装进 `Program Files` 后无写权限。
     fn get_config_path() -> Result<PathBuf, String> {
-        let exe_path = std::env::current_exe()
-            .map_err(|e| format!("获取程序路径失败: {e}"))?;
-        
-        let config_dir = if cfg!(debug_assertions) {
-            // 开发模式：workspace.json 放在项目根目录 (src-tauri 的父目录)
-            exe_path.parent()
-                .and_then(|p| p.parent())
-                .and_then(|p| p.parent())
-                .and_then(|p| p.parent())
-                .ok_or("无法获取项目根目录")?
-                .to_path_buf()
-        } else {
-            // 生产模式：放在 exe 同级目录
-            exe_path.parent()
-                .ok_or("无法获取程序所在目录")?
-                .to_path_buf()
-        };
-
-        Ok(config_dir.join("workspace.json"))
+        Ok(paths::app_data_dir()?.join("workspace.json"))
     }
 
     /// 读取工作目录配置
@@ -44,9 +31,9 @@ impl WorkspaceManager {
 
         let content = fs::read_to_string(&config_path)
             .map_err(|e| format!("读取 workspace.json 失败: {e}"))?;
-        
-        let config: WorkspaceConfig = serde_json::from_str(&content)
-            .map_err(|e| format!("解析 workspace.json 失败: {e}"))?;
+
+        let config: WorkspaceConfig =
+            serde_json::from_str(&content).map_err(|e| format!("解析 workspace.json 失败: {e}"))?;
 
         Ok(Some(config))
     }
@@ -59,11 +46,10 @@ impl WorkspaceManager {
             last_updated: Some(chrono::Local::now().to_rfc3339()),
         };
 
-        let json = serde_json::to_string_pretty(&config)
-            .map_err(|e| format!("序列化配置失败: {e}"))?;
+        let json =
+            serde_json::to_string_pretty(&config).map_err(|e| format!("序列化配置失败: {e}"))?;
 
-        fs::write(&config_path, json)
-            .map_err(|e| format!("写入 workspace.json 失败: {e}"))?;
+        fs::write(&config_path, json).map_err(|e| format!("写入 workspace.json 失败: {e}"))?;
 
         Ok(())
     }
diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs
index c657f2b..7a8362d 100644
--- a/src-tauri/src/lib.rs
+++ b/src-tauri/src/lib.rs
@@ -1,5 +1,5 @@
-pub mod docker;
 pub mod commands;
+pub mod docker;
 pub mod engine;
 pub mod logging;
 #[macro_use]
@@ -9,91 +9,109 @@ pub mod macros;
 pub fn run() {
     tauri::Builder::default()
         .setup(|app| {
-            // 获取项目根目录（优先 workspace.json，否则 exe 同级目录）
-            let log_dir = if cfg!(debug_assertions) {
-                // 开发模式：使用项目根目录
-                std::env::current_exe()
-                    .ok()
-                    .and_then(|p| p.parent().and_then(|p| p.parent()).and_then(|p| p.parent()).and_then(|p| p.parent()).map(|p| p.to_path_buf()))
-                    .unwrap_or_else(|| std::path::PathBuf::from("."))
-            } else {
-                // 生产模式：使用可执行文件所在目录
-                std::env::current_exe()
-                    .ok()
-                    .and_then(|p| p.parent().map(|p| p.to_path_buf()))
-                    .unwrap_or_else(|| std::path::PathBuf::from("."))
-            };
-            
+            use tauri::Manager;
+
+            // 用户级配置与日志统一落在 Tauri 官方应用数据目录：
+            // Windows %APPDATA%\<identifier>、macOS ~/Library/Application Support/<identifier>。
+            // 此前写在 exe 同级目录，装进 Program Files 后无写权限。
+            let app_data = app
+                .path()
+                .app_data_dir()
+                .map_err(|e| format!("无法获取应用数据目录: {e}"))?;
+            commands::paths::init_app_data_dir(app_data.clone());
+
+            // 旧版本把 workspace.json 放在 exe 同级目录，首次启动自动搬迁
+            let migrated = commands::paths::migrate_legacy_config();
+
             // 初始化日志系统
-            if let Err(e) = logging::init_logging(&log_dir) {
+            if let Err(e) = logging::init_logging(&app_data) {
                 eprintln!("Failed to initialize logging: {e}");
             }
-            
-            app_log!(info, "app", "PHP-Stack started, log file at: {:?}", log_dir.join("php-stack.log"));
-            
+
+            let log_path =
+                commands::paths::log_file().unwrap_or_else(|_| app_data.join("php-stack.log"));
+
+            app_log!(
+                info,
+                "app",
+                "PHP-Stack started, log file at: {:?}",
+                log_path
+            );
+
+            if !migrated.is_empty() {
+                app_log!(
+                    info,
+                    "app",
+                    "已从旧位置迁移用户配置到 {:?}: {}",
+                    app_data,
+                    migrated.join(", ")
+                );
+            }
+
             app.handle().plugin(tauri_plugin_dialog::init())?;
-            app.handle().plugin(tauri_plugin_clipboard_manager::init())?;
+            app.handle()
+                .plugin(tauri_plugin_clipboard_manager::init())?;
             app.handle().plugin(tauri_plugin_shell::init())?;
             Ok(())
         })
-    .invoke_handler(tauri::generate_handler![
-      // Dashboard
-      commands::check_docker,
-      commands::list_containers,
-      commands::list_all_running_containers,
-      commands::start_container,
-      commands::stop_container,
-      commands::restart_container,
-      commands::open_service_config,
-      // 可视化配置生成
-      commands::load_existing_config,
-      commands::validate_env_config,
-      commands::generate_env_config,
-      commands::preview_compose,
-      commands::check_config_files_exist,
-      commands::apply_env_config,
-      commands::start_environment,
-      commands::restart_environment,
-      commands::stop_environment,
-      // Phase 3: 镜像探测 / 拉取 / 配置提取
-      commands::check_service_images_presence,
-      commands::pull_service_images,
-      commands::extract_service_config,
-      // 统一镜像源管理
-      commands::get_mirror_presets,
-      commands::apply_mirror_preset,
-      commands::update_single_mirror,
-      commands::test_mirror,
-      commands::get_mirror_status,
-      commands::get_current_mirror_preset,
-      // 增强镜像源管理
-      commands::get_merged_mirror_list,
-      commands::save_selected_mirror_option,
-      commands::save_user_mirror_category,
-      commands::remove_user_mirror_category,
-      commands::reset_all_mirror_overrides,
-      // 备份
-      commands::create_backup,
-      commands::select_project_folder,
-      commands::convert_to_relative_path,
-      // 恢复
-      commands::preview_restore,
-      commands::verify_backup,
-      commands::execute_restore,
-      // 工作目录管理
-      commands::get_workspace_info,
-      commands::set_workspace_path,
-      // 版本管理
-      commands::get_version_mappings,
-      commands::validate_version,
-      commands::get_recommended_version,
-      // 用户版本覆盖
-      commands::save_user_override,
-      commands::remove_user_override,
-      commands::reset_all_overrides,
-      // 日志导出
-      commands::export_logs,
-    ])
-    .run(tauri::generate_context!())
-    .expect("error while running tauri application");
+        .invoke_handler(tauri::generate_handler![
+            // Dashboard
+            commands::check_docker,
+            commands::list_containers,
+            commands::list_all_running_containers,
+            commands::start_container,
+            commands::stop_container,
+            commands::restart_container,
+            commands::open_service_config,
+            // 可视化配置生成
+            commands::load_existing_config,
+            commands::validate_env_config,
+            commands::generate_env_config,
+            commands::preview_compose,
+            commands::check_config_files_exist,
+            commands::apply_env_config,
+            commands::start_environment,
+            commands::restart_environment,
+            commands::stop_environment,
+            // Phase 3: 镜像探测 / 拉取 / 配置提取
+            commands::check_service_images_presence,
+            commands::pull_service_images,
+            commands::extract_service_config,
+            // 统一镜像源管理
+            commands::get_mirror_presets,
+            commands::apply_mirror_preset,
+            commands::update_single_mirror,
+            commands::test_mirror,
+            commands::get_mirror_status,
+            commands::get_current_mirror_preset,
+            // 增强镜像源管理
+            commands::get_merged_mirror_list,
+            commands::save_selected_mirror_option,
+            commands::save_user_mirror_category,
+            commands::remove_user_mirror_category,
+            commands::reset_all_mirror_overrides,
+            // 备份
+            commands::create_backup,
+            commands::convert_to_relative_path,
+            // 恢复
+            commands::preview_restore,
+            commands::verify_backup,
+            commands::execute_restore,
+            // 工作目录管理
+            commands::get_workspace_info,
+            commands::set_workspace_path,
+            // 版本管理
+            commands::get_version_mappings,
+            commands::validate_version,
+            commands::get_recommended_version,
+            // 用户版本覆盖
+            commands::save_user_override,
+            commands::remove_user_override,
+            commands::reset_all_overrides,
+            // 日志导出
+            commands::export_logs,
+            commands::export_logs_to,
+        ])
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
 }
diff --git a/src-tauri/src/logging.rs b/src-tauri/src/logging.rs
index 6142bf8..2ae849a 100644
--- a/src-tauri/src/logging.rs
+++ b/src-tauri/src/logging.rs
@@ -1,49 +1,105 @@
 use std::fs::{File, OpenOptions};
 use std::io::Write;
-use std::path::PathBuf;
+use std::path::Path;
 use std::sync::Mutex;
 use tracing_subscriber::{fmt, EnvFilter};
 
 /// 全局日志文件句柄（线程安全）
 static LOG_FILE: Mutex<Option<File>> = Mutex::new(None);
 
+/// 保留的历史日志份数（不含当前日志）
+const RETAINED_LOG_GENERATIONS: usize = 2;
+
+/// 当前日志名与历史日志名（`.1` 最近，`.2` 更早）
+const CURRENT_LOG_NAME: &str = "php-stack.log";
+
+/// 日志轮转：当前 → `.1` → `.2`，超出保留份数的删除。
+///
+/// 此前每次启动 `truncate(true)` 直接覆盖，用户遇到问题后一重启，现场日志
+/// 就没了——"导出日志"命令也随之失去排查价值。
+fn rotate_logs(dir: &Path) -> Result<(), String> {
+    // 从最老的一份开始处理，避免覆盖尚未移走的日志
+    for generation in (1..=RETAINED_LOG_GENERATIONS).rev() {
+        let from = if generation == 1 {
+            dir.join(CURRENT_LOG_NAME)
+        } else {
+            dir.join(format!("php-stack.{}.log", generation - 1))
+        };
+        let to = dir.join(format!("php-stack.{generation}.log"));
+
+        if !from.exists() {
+            continue;
+        }
+
+        // 最老的一份已被挤出保留范围，直接丢弃
+        if generation == RETAINED_LOG_GENERATIONS && to.exists() {
+            std::fs::remove_file(&to)
+                .map_err(|e| format!("删除旧日志失败 {}: {}", to.display(), e))?;
+        }
+
+        std::fs::rename(&from, &to)
+            .map_err(|e| format!("轮转日志失败 {}: {}", from.display(), e))?;
+    }
+
+    Ok(())
+}
+
+/// 取锁并在锁被毒化时恢复。
+///
+/// 直接用 `unwrap()` 的话，任何一次持锁期间 panic 都会毒化全局日志锁，
+/// 之后每一次写日志都连锁 panic——把一个小故障放大成整个应用不可用。
+fn lock_log_file() -> std::sync::MutexGuard<'static, Option<File>> {
+    LOG_FILE.lock().unwrap_or_else(|e| e.into_inner())
+}
+
 /// 初始化日志系统
-pub fn init_logging(app_data_dir: &PathBuf) -> Result<(), String> {
+pub fn init_logging(app_data_dir: &std::path::PathBuf) -> Result<(), String> {
     // 确保目录存在
     std::fs::create_dir_all(app_data_dir)
         .map_err(|e| format!("无法创建应用数据目录 {}: {}", app_data_dir.display(), e))?;
-    
-    let log_path = app_data_dir.join("php-stack.log");
-    
-    // 每次启动时覆盖写入（truncate）
-    let file = OpenOptions::new()
+
+    rotate_logs(app_data_dir)?;
+
+    let log_path = app_data_dir.join(CURRENT_LOG_NAME);
+
+    // 轮转后当前日志一定是新文件；truncate 仅作兜底
+    let mut file = OpenOptions::new()
         .create(true)
         .write(true)
-        .truncate(true)  // 关键：覆盖旧日志
+        .truncate(true)
         .open(&log_path)
         .map_err(|e| format!("无法创建日志文件 {}: {}", log_path.display(), e))?;
-    
+
+    // 写入启动分隔线，便于区分多次启动的日志段
+    let now = chrono::Local::now();
+    let _ = writeln!(
+        file,
+        "=========== PHP-Stack 启动 {} ===========",
+        now.format("%Y-%m-%d %H:%M:%S")
+    );
+    let _ = file.flush();
+
     // 保存文件句柄到全局变量
-    *LOG_FILE.lock().unwrap() = Some(file);
-    
+    *lock_log_file() = Some(file);
+
     // 配置 tracing subscriber
-    let filter = EnvFilter::try_from_default_env()
-        .unwrap_or_else(|_| EnvFilter::new("info,app=debug"));
-    
+    let filter =
+        EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("info,app=debug"));
+
     // 自定义格式化器：添加时间前缀
     let formatter = fmt::format()
         .with_target(false)
         .with_level(true)
         .with_timer(CustomTimer)
         .compact();
-    
+
     // 输出到控制台
     tracing_subscriber::fmt()
         .with_env_filter(filter)
         .event_format(formatter)
         .with_writer(std::io::stdout)
         .init();
-    
+
     Ok(())
 }
 
@@ -59,7 +115,7 @@ impl tracing_subscriber::fmt::time::FormatTime for CustomTimer {
 
 /// 向日志文件写入消息（供宏调用）
 pub fn write_to_log_file(level: &str, module: &str, message: &str) {
-    if let Some(file) = LOG_FILE.lock().unwrap().as_mut() {
+    if let Some(file) = lock_log_file().as_mut() {
         let now = chrono::Local::now();
         let timestamp = now.format("[%H:%M:%S%.3f]").to_string();
         let log_line = format!("{timestamp} {level} [{module}] {message}\n");
@@ -67,3 +123,81 @@ pub fn write_to_log_file(level: &str, module: &str, message: &str) {
         let _ = file.flush();
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::PathBuf;
+
+    fn fresh_dir(name: &str) -> PathBuf {
+        let dir = std::env::temp_dir().join(format!("php-stack-logging-{name}"));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).unwrap();
+        dir
+    }
+
+    #[test]
+    fn test_rotate_shifts_generations() {
+        let dir = fresh_dir("shift");
+        std::fs::write(dir.join("php-stack.log"), "current").unwrap();
+        std::fs::write(dir.join("php-stack.1.log"), "previous").unwrap();
+
+        rotate_logs(&dir).unwrap();
+
+        assert!(!dir.join("php-stack.log").exists(), "当前日志应被移走");
+        assert_eq!(
+            std::fs::read_to_string(dir.join("php-stack.1.log")).unwrap(),
+            "current",
+            "本次日志应成为 .1"
+        );
+        assert_eq!(
+            std::fs::read_to_string(dir.join("php-stack.2.log")).unwrap(),
+            "previous",
+            "上一份 .1 应顺延为 .2"
+        );
+    }
+
+    #[test]
+    fn test_rotate_drops_oldest_beyond_retention() {
+        let dir = fresh_dir("retention");
+        std::fs::write(dir.join("php-stack.log"), "t0").unwrap();
+        std::fs::write(dir.join("php-stack.1.log"), "t1").unwrap();
+        std::fs::write(dir.join("php-stack.2.log"), "t2").unwrap();
+
+        rotate_logs(&dir).unwrap();
+
+        assert_eq!(
+            std::fs::read_to_string(dir.join("php-stack.1.log")).unwrap(),
+            "t0"
+        );
+        assert_eq!(
+            std::fs::read_to_string(dir.join("php-stack.2.log")).unwrap(),
+            "t1"
+        );
+        // t2 已超出保留份数，应被丢弃而不是留下第三份
+        assert!(!dir.join("php-stack.3.log").exists());
+    }
+
+    #[test]
+    fn test_rotate_noop_on_empty_dir() {
+        let dir = fresh_dir("empty");
+        rotate_logs(&dir).unwrap();
+        assert!(!dir.join("php-stack.1.log").exists());
+    }
+
+    #[test]
+    fn test_rotate_preserves_content() {
+        let dir = fresh_dir("content");
+        let body: String = (0..2000)
+            .map(|i| char::from(b'a' + (i % 26) as u8))
+            .collect();
+        std::fs::write(dir.join("php-stack.log"), &body).unwrap();
+
+        rotate_logs(&dir).unwrap();
+
+        assert_eq!(
+            std::fs::read_to_string(dir.join("php-stack.1.log")).unwrap(),
+            body
+        );
+    }
+}
diff --git a/src-tauri/src/main.rs b/src-tauri/src/main.rs
index ad5fe83..69c3a72 100644
--- a/src-tauri/src/main.rs
+++ b/src-tauri/src/main.rs
@@ -2,5 +2,5 @@
 #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
 
 fn main() {
-  app_lib::run();
+    app_lib::run();
 }
diff --git a/src-tauri/tests/integration/backup_restore_integration.rs b/src-tauri/tests/integration/backup_restore_integration.rs
index 3e286db..c98f479 100644
--- a/src-tauri/tests/integration/backup_restore_integration.rs
+++ b/src-tauri/tests/integration/backup_restore_integration.rs
@@ -2,8 +2,8 @@
 // These tests verify the end-to-end backup and restore workflow
 
 use app_lib::engine::backup_engine::BackupEngine;
-use app_lib::engine::restore_engine::RestoreEngine;
 use app_lib::engine::backup_manifest::BackupOptions;
+use app_lib::engine::restore_engine::RestoreEngine;
 use std::fs;
 use tempfile::TempDir;
 
@@ -12,17 +12,17 @@ async fn test_backup_and_restore_workflow() {
     // Create a temporary directory for testing
     let temp_dir = TempDir::new().expect("Failed to create temp dir");
     let workspace_path = temp_dir.path().to_path_buf();
-    
+
     // Create a sample .env file
     let env_content = "PHP_VERSION=8.2\nMYSQL_PORT=3306\n";
     let env_path = workspace_path.join(".env");
     fs::write(&env_path, env_content).expect("Failed to write .env file");
-    
+
     // Create a sample docker-compose.yml file
     let compose_content = "version: '3'\nservices:\n  php:\n    image: php:8.2\n";
     let compose_path = workspace_path.join("docker-compose.yml");
     fs::write(&compose_path, compose_content).expect("Failed to write docker-compose.yml");
-    
+
     // Test backup creation
     let backup_path = workspace_path.join("backup.zip");
     let options = BackupOptions {
@@ -30,37 +30,42 @@ async fn test_backup_and_restore_workflow() {
         project_patterns: vec![],
         include_logs: false,
     };
-    
+
     let backup_result = BackupEngine::create_backup(
         backup_path.to_str().unwrap(),
         options,
         &workspace_path,
         None, // No app handle in tests
-    ).await;
-    
+    )
+    .await;
+
     assert!(backup_result.is_ok(), "Backup should succeed");
-    
+
     // Verify backup file exists
     assert!(backup_path.exists(), "Backup file should exist");
-    
+
     // Test restore from backup
     let restore_workspace = temp_dir.path().join("restored");
     fs::create_dir(&restore_workspace).expect("Failed to create restore dir");
-    
+
     let restore_result = RestoreEngine::restore(
         backup_path.to_str().unwrap(),
         &restore_workspace,
         None, // No app handle in tests
-    ).await;
-    
+    )
+    .await;
+
     assert!(restore_result.is_ok(), "Restore should succeed");
-    
+
     // Verify restored files exist
     let restored_env = restore_workspace.join(".env");
     assert!(restored_env.exists(), "Restored .env should exist");
-    
+
     let restored_compose = restore_workspace.join("docker-compose.yml");
-    assert!(restored_compose.exists(), "Restored docker-compose.yml should exist");
+    assert!(
+        restored_compose.exists(),
+        "Restored docker-compose.yml should exist"
+    );
 }
 
 #[tokio::test]
@@ -69,26 +74,30 @@ async fn test_backup_with_database_export() {
     // For now, we'll just test the structure without actual DB export
     let temp_dir = TempDir::new().expect("Failed to create temp dir");
     let workspace_path = temp_dir.path().to_path_buf();
-    
+
     // Create minimal environment for backup
     let env_content = "MYSQL_HOST_PORT=3306\n";
     let env_path = workspace_path.join(".env");
     fs::write(&env_path, env_content).expect("Failed to write .env file");
-    
+
     let backup_path = workspace_path.join("backup_with_db.zip");
     let options = BackupOptions {
         include_projects: false,
         project_patterns: vec![],
         include_logs: false,
     };
-    
+
     let backup_result = BackupEngine::create_backup(
         backup_path.to_str().unwrap(),
         options,
         &workspace_path,
         None,
-    ).await;
-    
+    )
+    .await;
+
     // Even without a real database, the backup should succeed
-    assert!(backup_result.is_ok(), "Backup should succeed even without DB");
+    assert!(
+        backup_result.is_ok(),
+        "Backup should succeed even without DB"
+    );
 }
diff --git a/src-tauri/tests/integration/config_generation_integration.rs b/src-tauri/tests/integration/config_generation_integration.rs
index 288a330..315a8df 100644
--- a/src-tauri/tests/integration/config_generation_integration.rs
+++ b/src-tauri/tests/integration/config_generation_integration.rs
@@ -1,15 +1,98 @@
-// Integration tests for configuration generation
-// These tests verify the end-to-end config generation workflow
-// Note: Most config generation logic is covered by unit tests in config_generator.rs
-// Integration tests would require full Tauri app context
-
-#[cfg(test)]
-mod integration_tests_placeholder {
-    #[test]
-    fn test_integration_tests_setup() {
-        // Placeholder test to verify integration test setup works
-        // Actual config generation is tested in unit tests
-        // This test ensures the integration test module compiles and runs correctly
-        assert!(true, "Integration test setup is working");
+//! 配置生成端到端集成测试：EnvConfig → validate → .env 内容 → compose 内容
+//!
+//! 解析细节由 config_generator.rs 的单元测试覆盖，本文件验证完整链路。
+
+use app_lib::engine::config_generator::{ConfigGenerator, EnvConfig, ServiceEntry, ServiceType};
+
+fn sample_config() -> EnvConfig {
+    EnvConfig {
+        services: vec![
+            ServiceEntry {
+                service_type: ServiceType::PHP,
+                version: "php82".to_string(),
+                host_port: 9000,
+                extensions: Some(vec!["pdo_mysql".to_string(), "mysqli".to_string()]),
+            },
+            ServiceEntry {
+                service_type: ServiceType::MySQL,
+                version: "mysql80".to_string(),
+                host_port: 3306,
+                extensions: None,
+            },
+        ],
+        source_dir: "./www".to_string(),
+        timezone: "Asia/Shanghai".to_string(),
+        mysql_root_password: None,
     }
 }
+
+#[test]
+fn test_validate_accepts_conflict_free_config() {
+    ConfigGenerator::validate(&sample_config()).expect("无冲突配置应通过验证");
+}
+
+#[test]
+fn test_validate_rejects_port_conflict() {
+    let mut config = sample_config();
+    config.services[1].host_port = 9000; // 与 PHP 服务同端口
+    let result = ConfigGenerator::validate(&config);
+    assert!(result.is_err(), "同端口配置应验证失败");
+    assert!(
+        result.unwrap_err().contains("9000"),
+        "错误信息应包含冲突端口"
+    );
+}
+
+#[test]
+fn test_generate_env_contains_expected_keys() {
+    let tmp = tempfile::tempdir().expect("创建临时目录失败");
+    let env = ConfigGenerator::generate_env(&sample_config(), None, tmp.path());
+    let formatted = env.format();
+
+    assert!(formatted.contains("SOURCE_DIR=./www"), "应包含 SOURCE_DIR");
+    assert!(formatted.contains("TZ=Asia/Shanghai"), "应包含 TZ");
+    assert!(
+        formatted.contains("PHP82_VERSION=php:8.2-fpm"),
+        "PHP82_VERSION 应来自 manifest 的 image_tag，实际:\n{formatted}"
+    );
+    assert!(
+        formatted.contains("PHP82_EXTENSIONS=pdo_mysql,mysqli"),
+        "PHP82_EXTENSIONS 应包含所选扩展"
+    );
+    assert!(
+        formatted.contains("MYSQL80_HOST_PORT=3306"),
+        "MYSQL80_HOST_PORT 应为 3306"
+    );
+    assert!(
+        formatted.contains("MYSQL_ROOT_PASSWORD=root"),
+        "未指定密码时应使用默认 root"
+    );
+}
+
+#[test]
+fn test_generate_compose_contains_services() {
+    let compose = ConfigGenerator::generate_compose(&sample_config());
+
+    assert!(
+        compose.contains("php82"),
+        "compose 应包含 php82 服务配置，实际:\n{compose}"
+    );
+    assert!(
+        compose.contains("mysql80"),
+        "compose 应包含 mysql80 服务配置"
+    );
+}
+
+#[test]
+fn test_generate_env_preserves_user_variables() {
+    let tmp = tempfile::tempdir().expect("创建临时目录失败");
+    let existing = app_lib::engine::env_parser::EnvFile::parse("MY_CUSTOM_VAR=hello\n").unwrap();
+
+    let env = ConfigGenerator::generate_env(&sample_config(), Some(&existing), tmp.path());
+    let formatted = env.format();
+
+    assert!(
+        formatted.contains("MY_CUSTOM_VAR=hello"),
+        "用户自定义变量应被保留，实际:\n{formatted}"
+    );
+}
diff --git a/src-tauri/tests/integration/docker_manager_integration.rs b/src-tauri/tests/integration/docker_manager_integration.rs
index ae549ef..c02d168 100644
--- a/src-tauri/tests/integration/docker_manager_integration.rs
+++ b/src-tauri/tests/integration/docker_manager_integration.rs
@@ -38,10 +38,7 @@ async fn test_list_all_running_containers() {
         );
     }
 
-    assert!(
-        !containers.is_empty(),
-        "宿主机应至少有一个运行中的容器"
-    );
+    assert!(!containers.is_empty(), "宿主机应至少有一个运行中的容器");
 }
 
 #[tokio::test]
diff --git a/src-tauri/tests/integration/workspace_commands_integration.rs b/src-tauri/tests/integration/workspace_commands_integration.rs
index 91b797b..e8fc99c 100644
--- a/src-tauri/tests/integration/workspace_commands_integration.rs
+++ b/src-tauri/tests/integration/workspace_commands_integration.rs
@@ -1,9 +1,9 @@
 // Integration tests for workspace and version management commands
 // These tests verify the end-to-end workspace and version workflow
 
-use app_lib::engine::workspace_manager::WorkspaceManager;
-use app_lib::engine::version_manifest::VersionManifest;
 use app_lib::engine::user_override_manager::UserOverrideManager;
+use app_lib::engine::version_manifest::VersionManifest;
+use app_lib::engine::workspace_manager::WorkspaceManager;
 use std::fs;
 use tempfile::TempDir;
 
@@ -31,7 +31,10 @@ fn test_workspace_manager_save_and_load() {
 fn test_workspace_manager_load_nonexistent() {
     // When no workspace.json exists, load should return None
     let load_result = WorkspaceManager::load_workspace();
-    assert!(load_result.is_ok(), "Load workspace should succeed even if file doesn't exist");
+    assert!(
+        load_result.is_ok(),
+        "Load workspace should succeed even if file doesn't exist"
+    );
 }
 
 #[test]
@@ -39,16 +42,20 @@ fn test_version_manifest_load() {
     let manifest = VersionManifest::new();
 
     // Test that we can get entries for each service type
-    let php_entries = manifest.get_available_entries(&app_lib::engine::version_manifest::ServiceType::Php);
+    let php_entries =
+        manifest.get_available_entries(&app_lib::engine::version_manifest::ServiceType::Php);
     assert!(!php_entries.is_empty(), "Should have PHP versions");
 
-    let mysql_entries = manifest.get_available_entries(&app_lib::engine::version_manifest::ServiceType::Mysql);
+    let mysql_entries =
+        manifest.get_available_entries(&app_lib::engine::version_manifest::ServiceType::Mysql);
     assert!(!mysql_entries.is_empty(), "Should have MySQL versions");
 
-    let redis_entries = manifest.get_available_entries(&app_lib::engine::version_manifest::ServiceType::Redis);
+    let redis_entries =
+        manifest.get_available_entries(&app_lib::engine::version_manifest::ServiceType::Redis);
     assert!(!redis_entries.is_empty(), "Should have Redis versions");
 
-    let nginx_entries = manifest.get_available_entries(&app_lib::engine::version_manifest::ServiceType::Nginx);
+    let nginx_entries =
+        manifest.get_available_entries(&app_lib::engine::version_manifest::ServiceType::Nginx);
     assert!(!nginx_entries.is_empty(), "Should have Nginx versions");
 }
 
@@ -57,13 +64,17 @@ fn test_version_manifest_validate_id() {
     let manifest = VersionManifest::new();
 
     // Test valid IDs
-    let php_entries = manifest.get_available_entries(&app_lib::engine::version_manifest::ServiceType::Php);
+    let php_entries =
+        manifest.get_available_entries(&app_lib::engine::version_manifest::ServiceType::Php);
     if let Some((id, _)) = php_entries.first() {
         assert!(manifest.is_id_valid(&app_lib::engine::version_manifest::ServiceType::Php, id));
     }
 
     // Test invalid ID
-    assert!(!manifest.is_id_valid(&app_lib::engine::version_manifest::ServiceType::Php, "nonexistent_version"));
+    assert!(!manifest.is_id_valid(
+        &app_lib::engine::version_manifest::ServiceType::Php,
+        "nonexistent_version"
+    ));
 }
 
 #[test]
@@ -71,17 +82,33 @@ fn test_version_manifest_recommended() {
     let manifest = VersionManifest::new();
 
     // Each service type should have a recommended version
-    let php_recommended = manifest.get_recommended_entry(&app_lib::engine::version_manifest::ServiceType::Php);
-    assert!(php_recommended.is_some(), "Should have recommended PHP version");
+    let php_recommended =
+        manifest.get_recommended_entry(&app_lib::engine::version_manifest::ServiceType::Php);
+    assert!(
+        php_recommended.is_some(),
+        "Should have recommended PHP version"
+    );
 
-    let mysql_recommended = manifest.get_recommended_entry(&app_lib::engine::version_manifest::ServiceType::Mysql);
-    assert!(mysql_recommended.is_some(), "Should have recommended MySQL version");
+    let mysql_recommended =
+        manifest.get_recommended_entry(&app_lib::engine::version_manifest::ServiceType::Mysql);
+    assert!(
+        mysql_recommended.is_some(),
+        "Should have recommended MySQL version"
+    );
 
-    let redis_recommended = manifest.get_recommended_entry(&app_lib::engine::version_manifest::ServiceType::Redis);
-    assert!(redis_recommended.is_some(), "Should have recommended Redis version");
+    let redis_recommended =
+        manifest.get_recommended_entry(&app_lib::engine::version_manifest::ServiceType::Redis);
+    assert!(
+        redis_recommended.is_some(),
+        "Should have recommended Redis version"
+    );
 
-    let nginx_recommended = manifest.get_recommended_entry(&app_lib::engine::version_manifest::ServiceType::Nginx);
-    assert!(nginx_recommended.is_some(), "Should have recommended Nginx version");
+    let nginx_recommended =
+        manifest.get_recommended_entry(&app_lib::engine::version_manifest::ServiceType::Nginx);
+    assert!(
+        nginx_recommended.is_some(),
+        "Should have recommended Nginx version"
+    );
 }
 
 #[test]
@@ -94,7 +121,7 @@ fn test_user_override_manager_save_and_load() {
     // Initially, no overrides should exist
     let has_override = manager.has_user_override(
         &app_lib::engine::version_manifest::ServiceType::Php,
-        "php82"
+        "php82",
     );
     assert!(!has_override, "Should not have override initially");
 
@@ -115,14 +142,14 @@ fn test_user_override_manager_save_and_load() {
     // Now should have override
     let has_override = manager.has_user_override(
         &app_lib::engine::version_manifest::ServiceType::Php,
-        "php82"
+        "php82",
     );
     assert!(has_override, "Should have override after save");
 
     // Get merged entry should return custom values
     let merged = manager.get_merged_entry(
         &app_lib::engine::version_manifest::ServiceType::Php,
-        "php82"
+        "php82",
     );
     assert!(merged.is_some(), "Should get merged entry");
     let merged = merged.unwrap();
@@ -143,12 +170,14 @@ fn test_user_override_manager_remove() {
         description: None,
     };
 
-    manager.save_user_override(
-        &project_root,
-        app_lib::engine::version_manifest::ServiceType::Php,
-        "php82".to_string(),
-        override_config,
-    ).unwrap();
+    manager
+        .save_user_override(
+            &project_root,
+            app_lib::engine::version_manifest::ServiceType::Php,
+            "php82".to_string(),
+            override_config,
+        )
+        .unwrap();
 
     // Remove the override
     let remove_result = manager.remove_user_override(
@@ -161,7 +190,7 @@ fn test_user_override_manager_remove() {
     // Should not have override anymore
     let has_override = manager.has_user_override(
         &app_lib::engine::version_manifest::ServiceType::Php,
-        "php82"
+        "php82",
     );
     assert!(!has_override, "Should not have override after remove");
 }
@@ -184,19 +213,23 @@ fn test_user_override_manager_reset_all() {
         description: None,
     };
 
-    manager.save_user_override(
-        &project_root,
-        app_lib::engine::version_manifest::ServiceType::Php,
-        "php82".to_string(),
-        override1,
-    ).unwrap();
-
-    manager.save_user_override(
-        &project_root,
-        app_lib::engine::version_manifest::ServiceType::Mysql,
-        "mysql80".to_string(),
-        override2,
-    ).unwrap();
+    manager
+        .save_user_override(
+            &project_root,
+            app_lib::engine::version_manifest::ServiceType::Php,
+            "php82".to_string(),
+            override1,
+        )
+        .unwrap();
+
+    manager
+        .save_user_override(
+            &project_root,
+            app_lib::engine::version_manifest::ServiceType::Mysql,
+            "mysql80".to_string(),
+            override2,
+        )
+        .unwrap();
 
     // Reset all overrides
     let reset_result = manager.reset_all_overrides(&project_root);
@@ -205,15 +238,21 @@ fn test_user_override_manager_reset_all() {
     // Should not have any overrides
     let has_php_override = manager.has_user_override(
         &app_lib::engine::version_manifest::ServiceType::Php,
-        "php82"
+        "php82",
     );
     let has_mysql_override = manager.has_user_override(
         &app_lib::engine::version_manifest::ServiceType::Mysql,
-        "mysql80"
+        "mysql80",
     );
 
-    assert!(!has_php_override, "Should not have PHP override after reset");
-    assert!(!has_mysql_override, "Should not have MySQL override after reset");
+    assert!(
+        !has_php_override,
+        "Should not have PHP override after reset"
+    );
+    assert!(
+        !has_mysql_override,
+        "Should not have MySQL override after reset"
+    );
 }
 
 #[test]
@@ -267,4 +306,4 @@ MYSQL_ROOT_PASSWORD=secret123
     let content2 = fs::read_to_string(&env_path).expect("Failed to read updated .env file");
     let env3 = EnvFile::parse(&content2).expect("Failed to parse updated .env file");
     assert_eq!(env3.get("MYSQL_ROOT_PASSWORD"), Some("new_secret"));
-}
\ No newline at end of file
+}
diff --git a/src/App.vue b/src/App.vue
index ca82080..fa0a473 100644
--- a/src/App.vue
+++ b/src/App.vue
@@ -1,9 +1,10 @@
 <script setup lang="ts">
-import { ref, onMounted, nextTick, watch, computed } from 'vue';
+import { ref, onMounted, onUnmounted, nextTick, watch, computed } from 'vue';
 import { useI18n } from 'vue-i18n';
 import { invoke } from '@tauri-apps/api/core';
 import { listen } from '@tauri-apps/api/event';
 import { writeText } from '@tauri-apps/plugin-clipboard-manager';
+import { save } from '@tauri-apps/plugin-dialog';
 import { getVersion } from '@tauri-apps/api/app';
 import EnvConfigPage from './components/EnvConfigPage.vue';
 import SettingsPage from './components/SettingsPage.vue';
@@ -11,22 +12,16 @@ import MigrationPage from './components/MigrationPage.vue';
 import Toast from './components/Toast.vue';
 import ConfirmDialog from './components/ConfirmDialog.vue';
 import WorkspaceInitDialog from './components/WorkspaceInitDialog.vue';
-import { getLogs, addLog, showToast } from './composables/useToast';
+import { getLogs, addLog, clearLogs, showToast } from './composables/useToast';
 import { showConfirm } from './composables/useConfirmDialog';
+import type { Container } from './types/docker';
+import { isContainerRunning } from './types/docker';
+import { nextPollDelay, POLL_INTERVAL_MS } from './utils/pollBackoff';
 
 const { t } = useI18n();
 
 const appVersion = ref('v0.0.0'); // 应用版本号
 
-interface Container {
-  id: String;
-  name: String;
-  image: String;
-  status: String;
-  state: String;
-  ports: number[];
-}
-
 const containers = ref<Container[]>([]);
 const loading = ref(false);
 const starting = ref(false); // 启动环境时的加载状态
@@ -41,23 +36,22 @@ const showRestartConfirm = ref(false); // 控制重启确认弹窗
 const logPanelRef = ref<HTMLElement | null>(null); // 日志面板引用
 const isUserScrolling = ref(false); // 用户是否正在手动滚动
 let scrollTimeout: ReturnType<typeof setTimeout> | null = null; // 滚动超时定时器
+let consecutiveFailures = 0; // Docker 连续失败次数（用于轮询退避）
+let pollTimer: ReturnType<typeof setTimeout> | null = null; // 轮询定时器
 const hasEnvFile = ref(false); // .env 文件是否存在
+/// 工作区回退告警（配置路径不可用、数据写到别处）。全局横幅展示，不限环境配置页。
+const workspaceFallbackMsg = ref('');
+
+interface WorkspaceInfo {
+  workspace_path: string;
+  effective_path: string;
+  using_fallback: boolean;
+  fallback_reason?: string | null;
+}
 
 // 判断是否有运行中的 ps- 容器
 const hasRunningContainers = computed(() => {
-  return containers.value.some(c => isRunning(String(c.state)));
-});
-
-// 判断是否有任何 ps- 容器（不管状态）
-// @ts-ignore - 用于后续功能扩展，暂时未使用
-const hasAnyContainers = computed(() => {
-  return containers.value.length > 0;
-});
-
-// 判断是否有任何停止的 ps- 容器
-// @ts-ignore - 用于后续功能扩展，暂时未使用
-const hasStoppedContainers = computed(() => {
-  return containers.value.some(c => !isRunning(String(c.state)));
+  return containers.value.some(c => isContainerRunning(c.state));
 });
 
 // 判断是否可以启动（没有任何容器或所有容器都已停止，且存在 .env 文件）
@@ -75,21 +69,22 @@ const canStop = computed(() => {
   return hasRunningContainers.value;
 });
 
-// 判断容器是否运行中（兼容多种格式）
-const isRunning = (state: string): boolean => {
-  // 后端返回的格式："Some(RUNNING)" 或 "Some(Exceeded)" 等
-  const normalized = state.toLowerCase();
-  return normalized.includes('running');
-};
-
 const checkDocker = async () => {
   try {
     await invoke('check_docker');
+    // Docker 刚恢复可用时才提示——持续不可用时每次轮询都刷一条毫无意义
+    if (dockerError.value !== null) {
+      addLog(t('dashboard.toast.dockerRestored'));
+    }
     dockerError.value = null;
     return true;
   } catch (e) {
+    // 只在状态由可用翻转为不可用时记一条，之后静默退避
+    const wasAvailable = dockerError.value === null;
     dockerError.value = e as string;
-    addLog(t('dashboard.toast.dockerCheckFailed', { error: e }));
+    if (wasAvailable) {
+      addLog(t('dashboard.toast.dockerCheckFailed', { error: e }));
+    }
     return false;
   }
 };
@@ -100,6 +95,7 @@ const refreshContainers = async (silent = false) => {
     addLog(t('dashboard.toast.refreshing'));
   }
   if (!(await checkDocker())) {
+    consecutiveFailures += 1;
     containers.value = [];
     if (!silent) {
       loading.value = false;
@@ -109,6 +105,7 @@ const refreshContainers = async (silent = false) => {
   }
   try {
     const result = await invoke('list_containers') as Container[];
+    consecutiveFailures = 0;
     
     // 只有当内容真正改变时才更新，减少 DOM 抖动
     if (JSON.stringify(containers.value) !== JSON.stringify(result)) {
@@ -118,6 +115,7 @@ const refreshContainers = async (silent = false) => {
       addLog(t('dashboard.toast.containerNoChange'));
     }
   } catch (e) {
+    consecutiveFailures += 1;
     if (!silent) addLog(t('dashboard.toast.refreshFailed', { error: e }));
   } finally {
     if (!silent) {
@@ -317,6 +315,23 @@ const checkEnvFileExists = async () => {
   }
 };
 
+/// 加载工作区状态：配置路径不可用时必须全局可见，否则备份/恢复也会写到错误位置。
+async function loadWorkspaceFallbackBanner() {
+  try {
+    const info = await invoke<WorkspaceInfo | null>('get_workspace_info');
+    if (info?.using_fallback) {
+      workspaceFallbackMsg.value = t('workspace.status.fallback', {
+        effective: info.effective_path,
+        reason: info.fallback_reason || '',
+      });
+    } else {
+      workspaceFallbackMsg.value = '';
+    }
+  } catch {
+    workspaceFallbackMsg.value = '';
+  }
+}
+
 // 监听 tab 切换，回到 dashboard 时刷新 .env 检测状态
 watch(activeTab, async (newTab) => {
   if (newTab === 'dashboard') {
@@ -324,6 +339,27 @@ watch(activeTab, async (newTab) => {
   }
 });
 
+function stopPolling() {
+  if (pollTimer !== null) {
+    clearTimeout(pollTimer);
+    pollTimer = null;
+  }
+}
+
+// 自适应轮询：正常 5 秒；Docker 连续失败后逐级退避到 15s / 30s，恢复后回到 5 秒。
+// 用自调度的 setTimeout 而非 setInterval，间隔才能随失败次数变化。
+async function pollOnce() {
+  await refreshContainers(true);
+  // stopPolling() 可能在 await 期间被调用（组件卸载），此时不再续期
+  if (pollTimer === null) return;
+  pollTimer = setTimeout(pollOnce, nextPollDelay(consecutiveFailures));
+}
+
+function startPolling() {
+  stopPolling();
+  pollTimer = setTimeout(pollOnce, POLL_INTERVAL_MS);
+}
+
 onMounted(async () => {
   // 获取应用版本号
   try {
@@ -335,8 +371,8 @@ onMounted(async () => {
   
   refreshContainers();
   checkEnvFileExists(); // 检查 .env 文件是否存在
-  // 每 5 秒自动静默刷新一次
-  setInterval(() => refreshContainers(true), 5000);
+  loadWorkspaceFallbackBanner();
+  startPolling();
   
   // 监听后端发送的日志事件
   listen('env-log', (event) => {
@@ -345,6 +381,11 @@ onMounted(async () => {
   });
 });
 
+onUnmounted(() => {
+  stopPolling();
+  if (scrollTimeout) clearTimeout(scrollTimeout);
+});
+
 // 监听日志变化，自动滚动到底部（用户未手动滚动时）
 watch(logs, async () => {
   await nextTick();
@@ -387,16 +428,41 @@ const scrollToBottom = async () => {
   }
 };
 
-// 复制日志到剪贴板
+// 复制面板里当前可见的日志（此前复制的是后端文件日志全文，
+// 与界面看到的内容对不上——面板只保留最近 50 条）
 async function copyLogs() {
+  if (logs.value.length === 0) {
+    showToast(t('dashboard.log.empty'), 'warning');
+    return;
+  }
   try {
-    const logs = await invoke('export_logs');
-    await writeText(logs as string);
+    await writeText(logs.value.join('\n'));
     showToast(t('dashboard.log.copied'), 'success');
   } catch (e) {
     showToast(t('dashboard.log.copyFailed', { error: e }), 'error');
   }
 }
+
+// 清空面板（长会话下满屏历史，此前没有出口）
+function clearLogPanel() {
+  clearLogs();
+  showToast(t('dashboard.log.cleared'), 'success');
+}
+
+// 导出完整文件日志到用户指定位置（走后端，与面板显示范围无关）
+async function exportLogs() {
+  try {
+    const dest = await save({
+      defaultPath: 'php-stack.log',
+      filters: [{ name: 'Log', extensions: ['log', 'txt'] }],
+    });
+    if (!dest) return; // 用户取消
+    await invoke('export_logs_to', { dest });
+    showToast(t('dashboard.log.exported', { path: dest }), 'success');
+  } catch (e) {
+    showToast(t('dashboard.log.exportFailed', { error: e }), 'error');
+  }
+}
 </script>
 
 <template>
@@ -481,6 +547,25 @@ async function copyLogs() {
 
     <!-- Main Content -->
     <div class="flex-1 flex flex-col overflow-hidden p-3 sm:p-4 md:p-5 lg:p-6">
+      <!-- 工作区回退全局告警：备份/恢复/启动都走 effective_path，必须跨页可见 -->
+      <div
+        v-if="workspaceFallbackMsg"
+        data-testid="workspace-fallback-banner"
+        class="flex-shrink-0 mb-3 sm:mb-4 p-3 sm:p-4 bg-amber-500/10 border border-amber-500/30 rounded-xl flex flex-col sm:flex-row items-start sm:items-center gap-3 text-amber-700 dark:text-amber-400"
+      >
+        <div class="flex-1 min-w-0">
+          <h3 class="font-bold text-sm sm:text-base mb-0.5">{{ $t('workspace.banner.title') }}</h3>
+          <p class="text-xs sm:text-sm opacity-90 break-words">{{ workspaceFallbackMsg }}</p>
+        </div>
+        <button
+          type="button"
+          @click="activeTab = 'env-config'"
+          class="flex-shrink-0 px-3 py-1.5 bg-amber-500 hover:bg-amber-600 text-white rounded-lg text-xs sm:text-sm font-bold transition whitespace-nowrap"
+        >
+          {{ $t('workspace.banner.action') }}
+        </button>
+      </div>
+
       <!-- 1. 环境管理 (Dashboard) -->
       <div v-if="activeTab === 'dashboard'" class="flex-1 flex flex-col overflow-hidden">
         <header class="flex flex-col sm:flex-row justify-between items-start sm:items-center gap-4 mb-6 sm:mb-8">
@@ -565,11 +650,11 @@ async function copyLogs() {
             <div class="flex justify-between items-start mb-4">
               <span class="text-slate-500 dark:text-slate-400 text-xs font-mono uppercase tracking-wider">{{ String(c.image).split(':')[0] }}</span>
               <span 
-                :class="isRunning(String(c.state)) ? 'text-emerald-400' : 'text-rose-400'"
+                :class="isContainerRunning(c.state) ? 'text-emerald-400' : 'text-rose-400'"
                 class="flex items-center gap-1.5 text-xs font-bold uppercase tracking-tighter"
               >
-                <span :class="isRunning(String(c.state)) ? 'bg-emerald-500' : 'bg-rose-500'" class="w-2 h-2 rounded-full animate-pulse"></span>
-                {{ isRunning(String(c.state)) ? $t('dashboard.container.running') : $t('dashboard.container.stopped') }}
+                <span :class="[isContainerRunning(c.state) ? 'bg-emerald-500' : 'bg-rose-500', { 'animate-pulse': isContainerRunning(c.state) }]" class="w-2 h-2 rounded-full"></span>
+                {{ isContainerRunning(c.state) ? $t('dashboard.container.running') : $t('dashboard.container.stopped') }}
               </span>
             </div>
             <div class="text-xl font-bold mb-1 truncate text-slate-900 dark:text-slate-200" :title="String(c.name)">{{ String(c.name) }}</div>
@@ -580,7 +665,7 @@ async function copyLogs() {
             
             <div class="flex gap-2">
               <button 
-                v-if="!isRunning(String(c.state))"
+                v-if="!isContainerRunning(c.state)"
                 @click="startService(String(c.name))"
                 class="flex-1 py-2 bg-emerald-600/20 hover:bg-emerald-600 text-emerald-400 hover:text-white border border-emerald-600/30 rounded text-sm font-medium transition-all"
               >
@@ -636,9 +721,23 @@ async function copyLogs() {
             <button 
               @click="copyLogs"
               class="text-xs px-2 py-1 bg-slate-200 dark:bg-slate-800 hover:bg-slate-300 dark:hover:bg-slate-700 rounded text-slate-600 dark:text-slate-400 transition-colors flex items-center gap-1"
-              title="复制日志到剪贴板"
+              :title="$t('dashboard.log.copyTip')"
+            >
+              📋 {{ $t('dashboard.log.copy') }}
+            </button>
+            <button 
+              @click="clearLogPanel"
+              class="text-xs px-2 py-1 bg-slate-200 dark:bg-slate-800 hover:bg-slate-300 dark:hover:bg-slate-700 rounded text-slate-600 dark:text-slate-400 transition-colors flex items-center gap-1"
+              :title="$t('dashboard.log.clearTip')"
+            >
+              🗑️ {{ $t('dashboard.log.clear') }}
+            </button>
+            <button 
+              @click="exportLogs"
+              class="text-xs px-2 py-1 bg-slate-200 dark:bg-slate-800 hover:bg-slate-300 dark:hover:bg-slate-700 rounded text-slate-600 dark:text-slate-400 transition-colors flex items-center gap-1"
+              :title="$t('dashboard.log.exportTip')"
             >
-              📋 {{ $t('common.copy') }}
+              💾 {{ $t('dashboard.log.export') }}
             </button>
             <button 
               @click="scrollToBottom"
diff --git a/src/components/EnvConfigPage.vue b/src/components/EnvConfigPage.vue
index 68b444a..9891660 100644
--- a/src/components/EnvConfigPage.vue
+++ b/src/components/EnvConfigPage.vue
@@ -36,7 +36,7 @@ const commonExtensions = [
   'imagick', 'exif', 'pcntl', 'sockets'
 ];
 
-const customExtInput = ref('');
+const customExtInput = ref<Record<number, string>>({}); // 为每个 PHP 服务维护独立的自定义扩展输入
 // 为每个 PHP 服务维护独立的扩展面板展开状态
 const phpExtensionsPanelState = ref<Record<number, boolean>>({});
 
@@ -153,6 +153,7 @@ onMounted(async () => {
   await loadExistingConfig();
 });
 
+/// 工作区路径展示（回退告警已提升为 App 全局横幅，此处只显示配置值）
 async function loadWorkspaceInfo() {
   try {
     const info = await invoke<any>('get_workspace_info');
@@ -428,8 +429,9 @@ function addPhpVersion() {
     host_port: 9000 + phpServices.value.length,
     extensions: ['pdo_mysql', 'mysqli', 'mbstring', 'curl'],
   });
-  // 初始化新添加的 PHP 服务的扩展面板状态为关闭
+  // 初始化新添加的 PHP 服务的扩展面板状态与自定义扩展输入
   phpExtensionsPanelState.value[newIndex] = false;
+  customExtInput.value[newIndex] = '';
 }
 
 function removePhpVersion(index: number) {
@@ -437,6 +439,7 @@ function removePhpVersion(index: number) {
   phpServices.value.splice(index, 1);
   // 清理已删除服务的状态
   delete phpExtensionsPanelState.value[index];
+  delete customExtInput.value[index];
   // 重新索引后续服务的状态
   const newState: Record<number, boolean> = {};
   Object.keys(phpExtensionsPanelState.value).forEach(key => {
@@ -448,6 +451,16 @@ function removePhpVersion(index: number) {
     }
   });
   phpExtensionsPanelState.value = newState;
+  const newInputs: Record<number, string> = {};
+  Object.keys(customExtInput.value).forEach(key => {
+    const numKey = Number(key);
+    if (numKey > index) {
+      newInputs[numKey - 1] = customExtInput.value[numKey];
+    } else {
+      newInputs[numKey] = customExtInput.value[numKey];
+    }
+  });
+  customExtInput.value = newInputs;
 }
 
 // Add MySQL version
@@ -513,16 +526,16 @@ function toggleExtension(phpIndex: number, ext: string) {
 function syncCustomExtensions(phpIndex: number) {
   const service = phpServices.value[phpIndex];
   if (!service.extensions) service.extensions = [];
-  
+
   // 获取当前已选的预设扩展
   const presetExts = service.extensions.filter(e => commonExtensions.includes(e));
-  
-  // 解析用户输入的自定义扩展
-  const customExts = customExtInput.value
+
+  // 解析该服务自己的自定义扩展输入
+  const customExts = (customExtInput.value[phpIndex] || '')
     .split(/[,\s]+/)
     .map(s => s.trim())
     .filter(s => s.length > 0 && !commonExtensions.includes(s));
-  
+
   // 合并并去重
   service.extensions = [...new Set([...presetExts, ...customExts])];
 }
@@ -970,8 +983,8 @@ const goToMirrorSettings = () => {
                 <!-- 自定义扩展输入区 -->
                 <div class="pt-3 border-t border-slate-200 dark:border-slate-700/50">
                   <label class="block text-[10px] font-medium text-emerald-600 dark:text-emerald-400 mb-1.5">{{ $t('envConfig.php.customExtensions') }}</label>
-                  <input 
-                    v-model="customExtInput" 
+                  <input
+                    v-model="customExtInput[idx]"
                     @blur="syncCustomExtensions(idx)"
                     :placeholder="$t('envConfig.php.customExtPlaceholder')"  
                     class="w-full bg-slate-50 dark:bg-slate-800 border border-slate-300 dark:border-slate-700 rounded-lg px-3 py-1.5 text-xs text-emerald-600 dark:text-emerald-400 font-mono outline-none focus:ring-2 focus:ring-emerald-500/50"
diff --git a/src/components/RestorePage.vue b/src/components/RestorePage.vue
index fe52f30..4e429aa 100644
--- a/src/components/RestorePage.vue
+++ b/src/components/RestorePage.vue
@@ -4,7 +4,7 @@ import { useI18n } from 'vue-i18n';
 import { invoke } from '@tauri-apps/api/core';
 import { open } from '@tauri-apps/plugin-dialog';
 import { listen } from '@tauri-apps/api/event';
-import type { RestorePreview, RestoreProgress } from '../types/env-config';
+import type { RestorePreview, RestoreProgress, RestoreResult } from '../types/env-config';
 import { showToast } from '../composables/useToast';
 import { showConfirm } from '../composables/useConfirmDialog';
 
@@ -18,6 +18,14 @@ const verified = ref<boolean | null>(null);
 const restoring = ref(false);
 const loading = ref(false);
 const progress = ref<RestoreProgress | null>(null);
+// U2: 恢复结果明细（已恢复文件 / 错误列表 / 回滚包路径）
+const restoreResult = ref<RestoreResult | null>(null);
+
+/// 无任何文件恢复成功的失败视为「致命失败」（含引擎直接 Err 的结构化包装）
+const isFatalRestoreFailure = computed(() => {
+  const r = restoreResult.value;
+  return !!r && !r.success && r.restored_files.length === 0;
+});
 
 const currentStep = ref<RestoreStep>('select');
 const completedSteps = ref<Set<RestoreStep>>(new Set());
@@ -146,20 +154,67 @@ async function handleRestore() {
   restoring.value = true;
   progress.value = { step: t('common.loading'), percentage: 0 };
 
+  restoreResult.value = null;
+
   try {
-    await invoke('execute_restore', {
+    // 成功 / 部分失败 / 致命失败均返回 RestoreResult，明细进结果面板
+    const result = await invoke<RestoreResult>('execute_restore', {
       zipPath: zipPath.value,
     });
-    showToast(t('restore.toast.success'), 'success');
-    progress.value = { step: '✅', percentage: 100 };
-    markStepCompleted('restore');
+    restoreResult.value = result;
+
+    if (result.success) {
+      showToast(t('restore.toast.success'), 'success');
+      progress.value = { step: '✅', percentage: 100 };
+      markStepCompleted('restore');
+    } else if (result.restored_files.length === 0) {
+      showToast(t('restore.toast.fatalFailed'), 'error');
+      progress.value = null;
+    } else {
+      // 部分失败：不静默吞掉，明细留在页面上供用户逐条查看
+      showToast(t('restore.toast.partialSuccess'), 'warning');
+      progress.value = null;
+    }
   } catch (e) {
-    showToast(e as string, 'error');
+    // 仅命令前置失败（如工作区路径）仍可能抛 Err
+    restoreResult.value = {
+      success: false,
+      restored_files: [],
+      errors: [String(e)],
+      rollback_path: null,
+    };
+    showToast(t('restore.toast.fatalFailed'), 'error');
+    progress.value = null;
   } finally {
     restoring.value = false;
   }
 }
 
+/// 用回滚包重新走预览→校验→恢复向导（快捷入口，避免用户手动找 zip）
+async function useRollbackBundle() {
+  const path = restoreResult.value?.rollback_path;
+  if (!path) return;
+
+  const confirmed = await showConfirm({
+    title: t('restore.rollbackConfirm.title'),
+    message: t('restore.rollbackConfirm.message'),
+    confirmText: t('restore.rollbackConfirm.confirm'),
+    cancelText: t('common.cancel'),
+    type: 'warning',
+  });
+  if (!confirmed) return;
+
+  zipPath.value = path;
+  preview.value = null;
+  verified.value = null;
+  restoreResult.value = null;
+  progress.value = null;
+  resetSteps();
+  markStepCompleted('select');
+  goToStep('preview');
+  await handlePreview();
+}
+
 function formatTimestamp(ts: string): string {
   try {
     return new Date(ts).toLocaleString();
@@ -345,6 +400,56 @@ function formatTimestamp(ts: string): string {
               <h3 class="text-xl font-bold text-emerald-600 dark:text-emerald-400 mb-2">{{ $t('restore.success.title') }}</h3>
               <p class="text-sm text-slate-600 dark:text-slate-400">{{ $t('restore.success.description') }}</p>
             </div>
+
+            <!-- U2: 恢复结果明细（成功 / 部分失败 / 致命失败都展示） -->
+            <div v-if="restoreResult" class="mt-6 text-left space-y-4" data-testid="restore-result">
+              <div
+                v-if="isFatalRestoreFailure"
+                class="p-3 bg-rose-50 dark:bg-rose-900/20 border border-rose-200 dark:border-rose-800 rounded-lg"
+                data-testid="restore-fatal"
+              >
+                <h3 class="font-bold text-rose-700 dark:text-rose-400">{{ $t('restore.fatal.title') }}</h3>
+                <p class="text-sm text-rose-700 dark:text-rose-400 mt-1">{{ $t('restore.fatal.description') }}</p>
+              </div>
+              <div
+                v-else-if="!restoreResult.success"
+                class="p-3 bg-amber-50 dark:bg-amber-900/20 border border-amber-200 dark:border-amber-800 rounded-lg"
+              >
+                <h3 class="font-bold text-amber-700 dark:text-amber-400">{{ $t('restore.partialSuccess.title') }}</h3>
+                <p class="text-sm text-amber-700 dark:text-amber-400 mt-1">{{ $t('restore.partialSuccess.description') }}</p>
+              </div>
+
+              <div v-if="restoreResult.restored_files.length">
+                <h4 class="font-semibold text-sm text-slate-700 dark:text-slate-300 mb-2">
+                  {{ $t('restore.result.restoredFiles') }}
+                  <span class="text-slate-500 dark:text-slate-500">({{ $t('restore.result.filesCount', { count: restoreResult.restored_files.length }) }})</span>
+                </h4>
+                <ul class="max-h-48 overflow-y-auto text-xs space-y-1 bg-slate-50 dark:bg-slate-800 rounded-lg p-3" data-testid="restored-files">
+                  <li v-for="file in restoreResult.restored_files" :key="file" class="font-mono text-slate-600 dark:text-slate-400">{{ file }}</li>
+                </ul>
+              </div>
+
+              <div v-if="restoreResult.errors.length">
+                <h4 class="font-semibold text-sm text-red-700 dark:text-red-400 mb-2">{{ $t('restore.result.errors') }}</h4>
+                <ul class="max-h-48 overflow-y-auto text-xs space-y-1 bg-red-50 dark:bg-red-900/20 rounded-lg p-3" data-testid="restore-errors">
+                  <li v-for="(err, idx) in restoreResult.errors" :key="idx" class="font-mono text-red-600 dark:text-red-400 whitespace-pre-wrap">{{ err }}</li>
+                </ul>
+              </div>
+
+              <div v-if="restoreResult.rollback_path" class="p-3 bg-slate-50 dark:bg-slate-800 border border-slate-200 dark:border-slate-700 rounded-lg">
+                <h4 class="font-semibold text-sm text-slate-700 dark:text-slate-300 mb-1">{{ $t('restore.result.rollbackTitle') }}</h4>
+                <p class="text-xs text-slate-600 dark:text-slate-400 mb-2">{{ $t('restore.result.rollbackHint') }}</p>
+                <code class="block break-all text-xs font-mono text-slate-700 dark:text-slate-300 mb-3" data-testid="rollback-path">{{ restoreResult.rollback_path }}</code>
+                <button
+                  type="button"
+                  data-testid="rollback-action"
+                  @click="useRollbackBundle"
+                  class="w-full sm:w-auto px-4 py-2 bg-blue-600 hover:bg-blue-700 text-white text-sm font-medium rounded-lg transition"
+                >
+                  {{ $t('restore.result.rollbackAction') }}
+                </button>
+              </div>
+            </div>
           </section>
         </Transition>
 
diff --git a/src/components/__tests__/EnvConfigPage.spec.ts b/src/components/__tests__/EnvConfigPage.spec.ts
index 6975ad0..b08669f 100644
--- a/src/components/__tests__/EnvConfigPage.spec.ts
+++ b/src/components/__tests__/EnvConfigPage.spec.ts
@@ -147,4 +147,47 @@ describe('EnvConfigPage', () => {
     expect(text).toContain('MySQL 8.0')
     expect(text).toContain('mysql:8.0')
   })
+
+  it('custom extension inputs are independent across multiple PHP services', async () => {
+    const wrapper = mount(EnvConfigPage)
+    await flushPromises()
+
+    // 在 PHP 分区内点击"添加版本"，得到两个 PHP 服务卡片
+    const sections = wrapper.findAll('section')
+    const phpSection = sections.find(s => s.text().includes('PHP 服务'))!
+    const addBtn = phpSection.findAll('button').find(b => b.text().includes('添加版本'))!
+    await addBtn.trigger('click')
+
+    // 展开两个服务的扩展面板（默认收起）
+    const panelToggles = phpSection
+      .findAll('button')
+      .filter(b => b.text().includes('预设扩展库'))
+    expect(panelToggles.length).toBe(2)
+    for (const toggle of panelToggles) {
+      await toggle.trigger('click')
+    }
+
+    // 找到两个"自定义扩展"输入框（placeholder 定位）
+    const customInputs = phpSection.findAll('input[placeholder="例如: grpc protobuf"]')
+    expect(customInputs.length).toBe(2)
+
+    // 给第一个服务的输入框填写内容
+    await customInputs[0].setValue('xdebug')
+    expect((customInputs[0].element as HTMLInputElement).value).toBe('xdebug')
+
+    // 给第二个服务的输入框填写不同内容（修复前共享同一个 ref，会覆盖第一个输入框）
+    await customInputs[1].setValue('swoole')
+
+    const v1 = (customInputs[0].element as HTMLInputElement).value
+    const v2 = (customInputs[1].element as HTMLInputElement).value
+    expect(v1).toBe('xdebug')
+    expect(v2).toBe('swoole')
+    expect(v1).not.toBe(v2)
+
+    // blur 触发各自的合并逻辑，输入框内容保持独立
+    await customInputs[0].trigger('blur')
+    await customInputs[1].trigger('blur')
+    expect((customInputs[0].element as HTMLInputElement).value).toBe('xdebug')
+    expect((customInputs[1].element as HTMLInputElement).value).toBe('swoole')
+  })
 })
diff --git a/src/components/__tests__/RestorePage.spec.ts b/src/components/__tests__/RestorePage.spec.ts
index 16e1319..71d8a04 100644
--- a/src/components/__tests__/RestorePage.spec.ts
+++ b/src/components/__tests__/RestorePage.spec.ts
@@ -1,6 +1,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest'
-import { mount } from '@vue/test-utils'
+import { mount, flushPromises } from '@vue/test-utils'
 import RestorePage from '../RestorePage.vue'
+import { invoke } from '@tauri-apps/api/core'
 
 // Mock @tauri-apps/api/core
 vi.mock('@tauri-apps/api/core', () => ({
@@ -91,4 +92,144 @@ describe('RestorePage', () => {
     const stepIndicators = wrapper.findAll('.rounded-full')
     expect(stepIndicators.length).toBeGreaterThanOrEqual(4)
   })
+})
+
+// ─── U2 / R2：恢复结果明细展示 ──────────────────────────────────────
+// 以前 execute_restore 只回 Ok/Err，前端弹一句 toast 就结束，
+// 用户既看不全 restored_files 也来不及看 errors。现在改为始终返回结果，
+// 这两条测试把「明细真的渲染出来了」锁住。
+
+const PREVIEW_PAYLOAD = {
+  manifest: {
+    timestamp: '2026-04-30T10:00:00Z',
+    app_version: '0.3.1',
+    os_info: 'Windows 11',
+    services: [{ name: 'ps-nginx', image: 'nginx', version: '1.27' }],
+    files: { '.env': {}, 'docker-compose.yml': {} },
+    errors: [],
+  },
+}
+
+/** 走完 select → preview → verify，停在第 4 步，可执行恢复 */
+async function prepareRestoreStep(wrapper: ReturnType<typeof mount>) {
+  const vm = wrapper.vm as any
+  await vm.selectFile()
+  await vm.handlePreview()
+  await vm.handleVerify()
+  vm.goToStep('restore')
+  await flushPromises()
+}
+
+function mockInvoke(executeRestoreResult: unknown) {
+  vi.mocked(invoke).mockImplementation(async (command: string) => {
+    if (command === 'preview_restore') return PREVIEW_PAYLOAD
+    if (command === 'verify_backup') return true
+    if (command === 'execute_restore') return executeRestoreResult
+    return null
+  })
+}
+
+describe('RestorePage — 恢复结果明细', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('成功时展示已恢复文件列表与回滚包路径', async () => {
+    mockInvoke({
+      success: true,
+      restored_files: ['.env', 'docker-compose.yml', 'services/php82/php.ini'],
+      errors: [],
+      rollback_path: '/ws/.restore_rollback_20260921_120000.zip',
+    })
+
+    const wrapper = mount(RestorePage)
+    await prepareRestoreStep(wrapper)
+    await (wrapper.vm as any).handleRestore()
+    await flushPromises()
+
+    const files = wrapper.find('[data-testid="restored-files"]')
+    expect(files.exists()).toBe(true)
+    expect(files.text()).toContain('.env')
+    expect(files.text()).toContain('services/php82/php.ini')
+
+    // R2：回滚包路径必须可见，否则用户不知道去哪撤销
+    const rollback = wrapper.find('[data-testid="rollback-path"]')
+    expect(rollback.exists()).toBe(true)
+    expect(rollback.text()).toContain('.restore_rollback_')
+
+    // 成功时不应出现错误区块
+    expect(wrapper.find('[data-testid="restore-errors"]').exists()).toBe(false)
+  })
+
+  it('部分失败时逐条展示错误明细，不折叠成一句话 toast', async () => {
+    mockInvoke({
+      success: false,
+      restored_files: ['.env'],
+      errors: ['恢复 services/ 失败: 权限不足', '恢复 database/ 失败: 条目损坏'],
+      rollback_path: '/ws/.restore_rollback_20260921_120001.zip',
+    })
+
+    const wrapper = mount(RestorePage)
+    await prepareRestoreStep(wrapper)
+    await (wrapper.vm as any).handleRestore()
+    await flushPromises()
+
+    const errors = wrapper.find('[data-testid="restore-errors"]')
+    expect(errors.exists()).toBe(true)
+    expect(errors.text()).toContain('恢复 services/ 失败: 权限不足')
+    expect(errors.text()).toContain('恢复 database/ 失败: 条目损坏')
+
+    // 部分失败同样要给出回滚包，这是用户唯一的退路
+    expect(wrapper.find('[data-testid="rollback-path"]').text()).toContain(
+      '.restore_rollback_',
+    )
+    expect(wrapper.find('[data-testid="rollback-action"]').exists()).toBe(true)
+    // 有已恢复文件 → 不算致命失败
+    expect(wrapper.find('[data-testid="restore-fatal"]').exists()).toBe(false)
+  })
+
+  it('致命失败时展示错误面板与回滚快捷入口，而非仅 toast', async () => {
+    mockInvoke({
+      success: false,
+      restored_files: [],
+      errors: ['备份包包含非法路径条目，已拒绝恢复: ../../escaped.txt'],
+      rollback_path: '/ws/.restore_rollback_20260921_120002.zip',
+    })
+
+    const wrapper = mount(RestorePage)
+    await prepareRestoreStep(wrapper)
+    await (wrapper.vm as any).handleRestore()
+    await flushPromises()
+
+    expect(wrapper.find('[data-testid="restore-fatal"]').exists()).toBe(true)
+    expect(wrapper.find('[data-testid="restore-errors"]').text()).toContain(
+      '非法路径条目',
+    )
+    expect(wrapper.find('[data-testid="rollback-action"]').exists()).toBe(true)
+  })
+
+  it('点击回滚快捷入口后载入回滚包并进入预览步骤', async () => {
+    const rollbackPath = '/ws/.restore_rollback_20260921_120003.zip'
+    mockInvoke({
+      success: false,
+      restored_files: [],
+      errors: ['打开备份文件失败'],
+      rollback_path: rollbackPath,
+    })
+
+    const wrapper = mount(RestorePage)
+    await prepareRestoreStep(wrapper)
+    await (wrapper.vm as any).handleRestore()
+    await flushPromises()
+
+    await (wrapper.vm as any).useRollbackBundle()
+    await flushPromises()
+
+    const vm = wrapper.vm as any
+    expect(vm.zipPath).toBe(rollbackPath)
+    expect(vm.currentStep).toBe('preview')
+    expect(vm.restoreResult).toBeNull()
+    // 载入后自动触发预览
+    expect(vm.preview).not.toBeNull()
+  })
 })
\ No newline at end of file
diff --git a/src/composables/__tests__/useToast.spec.ts b/src/composables/__tests__/useToast.spec.ts
index b13aac3..fd3529d 100644
--- a/src/composables/__tests__/useToast.spec.ts
+++ b/src/composables/__tests__/useToast.spec.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { showToast, getToasts, removeToast, addLog, getLogs } from '../useToast'
+import { showToast, getToasts, removeToast, addLog, getLogs, clearLogs } from '../useToast'
 
 describe('useToast', () => {
   it('shows a toast message', () => {
@@ -25,4 +25,11 @@ describe('useToast', () => {
     expect(logs.value.length).toBeGreaterThan(0)
     expect(logs.value[logs.value.length - 1]).toContain('Test log message')
   })
+
+  it('clears all log messages', () => {
+    addLog('to be cleared')
+    expect(getLogs().value.length).toBeGreaterThan(0)
+    clearLogs()
+    expect(getLogs().value.length).toBe(0)
+  })
 })
diff --git a/src/composables/useToast.ts b/src/composables/useToast.ts
index cc0a81a..9150a23 100644
--- a/src/composables/useToast.ts
+++ b/src/composables/useToast.ts
@@ -25,6 +25,11 @@ export function getLogs() {
   return logs;
 }
 
+// 清空日志面板
+export function clearLogs() {
+  logs.value = [];
+}
+
 // 显示 Toast
 export function showToast(message: string, type: ToastType = 'info', duration = 3000) {
   const id = nextId++;
diff --git a/src/i18n/locales/en.json b/src/i18n/locales/en.json
index ac99b90..48ee4b2 100644
--- a/src/i18n/locales/en.json
+++ b/src/i18n/locales/en.json
@@ -73,9 +73,17 @@
       "action": "Confirm Restart"
     },
     "log": {
-      "title": "Live Logs",
-      "copy": "📋 Copy",
-      "bottom": "⬇️ Bottom",
+  "title": "Live Logs",
+  "copy": "Copy",
+  "copyTip": "Copy the logs shown in this panel (keeps the latest 50 entries)",
+  "clear": "Clear",
+  "clearTip": "Clear the log panel",
+  "export": "Export",
+  "exportTip": "Export the full file log to a location of your choice",
+  "cleared": "Log panel cleared",
+  "exported": "Log exported to {path}",
+  "exportFailed": "Export failed: {error}",
+  "bottom": "⬇️ Bottom",
       "show": "Show",
       "hide": "Hide",
       "empty": "Waiting for operations...",
@@ -88,8 +96,9 @@
       "refreshFailed": "Refresh failed: {error}",
       "containerUpdated": "Container list updated ({count} containers)",
       "containerNoChange": "Container status unchanged",
-      "dockerUnavailable": "Docker unavailable, container list cleared",
-      "dockerCheckFailed": "Docker check failed: {error}",
+  "dockerUnavailable": "Docker unavailable, container list cleared",
+  "dockerCheckFailed": "Docker check failed: {error}",
+  "dockerRestored": "Docker is available again, polling interval back to 5s",
       "serviceStarting": "Starting service: {name}...",
       "serviceStarted": "Service {name} started",
       "serviceStopping": "Stopping service: {name}...",
@@ -235,7 +244,10 @@
       "backupPartialFail": "\n\n⚠️  Note: Some files failed to backup (may be in use). Please close related programs and retry.",
       "startSuccess": "Environment started!\n{result}",
       "nginxConfigOpened": "Opened {dir} config directory",
-      "nginxConfigFailed": "Failed to open directory, please manually open services/{dir}/conf.d/"
+      "nginxConfigFailed": "Failed to open directory, please manually open services/{dir}/conf.d/",
+      "pullPartialSuccess": "⚠️ Some images failed to pull: {details}. Fallback templates will be used for those.",
+      "pullAllFailed": "❌ All images failed to pull. Falling back to built-in templates.",
+      "pullAllSuccess": "✅ {count} images pulled successfully"
     },
     "error": {
       "dockerNotRunning": "❌ Docker Not Running\n\nPlease start Docker Desktop and try again.",
@@ -296,11 +308,6 @@
       "tip": "Once pulled, \"One-click start\" reuses the local cache — it won't re-download on subsequent runs.",
       "confirmPull": "Pull {count}",
       "pulling": "Pulling…"
-    },
-    "toast": {
-      "pullPartialSuccess": "⚠️ Some images failed to pull: {details}. Fallback templates will be used for those.",
-      "pullAllFailed": "❌ All images failed to pull. Falling back to built-in templates.",
-      "pullAllSuccess": "✅ {count} images pulled successfully"
     }
   },
   "settings": {
@@ -548,6 +555,22 @@
       "title": "Environment Restored!",
       "description": "You can restart Docker containers to apply the new configuration"
     },
+    "partialSuccess": {
+      "title": "Restore finished with errors",
+      "description": "Files that could not be restored are listed below. Use the rollback bundle to undo this restore if needed."
+    },
+    "fatal": {
+      "title": "Restore failed",
+      "description": "No files were written. See the error below. If a rollback bundle was created, you can use it to restore the previous configuration."
+    },
+    "result": {
+      "restoredFiles": "Restored files",
+      "filesCount": "{count} files",
+      "errors": "Errors",
+      "rollbackTitle": "Pre-restore rollback bundle",
+      "rollbackHint": "Your previous configuration was backed up automatically. To undo, load this bundle into the restore wizard:",
+      "rollbackAction": "Restore from this bundle"
+    },
     "progress": {
       "title": "📊 Restore Progress"
     },
@@ -556,11 +579,18 @@
       "message": "⚠️ Warning: Existing config files will be overwritten. Consider backing up first.\n\n💡 After restore, click \"Start All\" to run the environment.",
       "start": "Start Restore"
     },
+    "rollbackConfirm": {
+      "title": "Restore from rollback bundle?",
+      "message": "This loads the rollback bundle into the restore wizard (preview → verify → confirm). Current workspace config will be overwritten again.",
+      "confirm": "Load rollback bundle"
+    },
     "toast": {
       "previewDone": "Preview complete, check backup contents",
       "verifyPassed": "Verification passed, ready to restore",
       "verifyFailed": "Verification failed, backup may be corrupted",
-      "success": "Environment restored successfully!"
+      "success": "Environment restored successfully!",
+      "partialSuccess": "⚠️ Restore finished with errors, see details below",
+      "fatalFailed": "Restore failed, see error details below"
     }
   },
   "workspace": {
@@ -573,10 +603,15 @@
     "error": {
       "invalidPath": "Please select a valid directory as workspace"
     },
+    "banner": {
+      "title": "Workspace path unavailable",
+      "action": "Open Env Config"
+    },
     "status": {
       "loading": "Loading...",
       "notConfigured": "Not configured",
-      "loadFailed": "Load failed"
+      "loadFailed": "Load failed",
+      "fallback": "Configured workspace is unavailable; data is written to {effective}. {reason}"
     }
   }
 }
\ No newline at end of file
diff --git a/src/i18n/locales/zh-CN.json b/src/i18n/locales/zh-CN.json
index 3a049e2..8856ab8 100644
--- a/src/i18n/locales/zh-CN.json
+++ b/src/i18n/locales/zh-CN.json
@@ -73,9 +73,17 @@
       "action": "确认重启"
     },
     "log": {
-      "title": "实时日志",
-      "copy": "📋 复制",
-      "bottom": "⬇️ 底部",
+  "title": "实时日志",
+  "copy": "复制",
+  "copyTip": "复制面板中显示的日志（保留最近 50 条）",
+  "clear": "清空",
+  "clearTip": "清空面板中的日志显示",
+  "export": "导出",
+  "exportTip": "导出完整文件日志到指定位置",
+  "cleared": "日志面板已清空",
+  "exported": "日志已导出到 {path}",
+  "exportFailed": "导出失败: {error}",
+  "bottom": "⬇️ 底部",
       "show": "显示",
       "hide": "隐藏",
       "empty": "等待操作中...",
@@ -88,8 +96,9 @@
       "refreshFailed": "刷新失败: {error}",
       "containerUpdated": "容器列表已更新 ({count} 个容器)",
       "containerNoChange": "容器状态未变化",
-      "dockerUnavailable": "Docker 不可用，已清空容器列表",
-      "dockerCheckFailed": "Docker 检查失败: {error}",
+  "dockerUnavailable": "Docker 不可用，已清空容器列表",
+  "dockerCheckFailed": "Docker 检查失败: {error}",
+  "dockerRestored": "Docker 已恢复可用，轮询间隔已回到 5 秒",
       "serviceStarting": "正在启动服务: {name}...",
       "serviceStarted": "服务 {name} 已启动",
       "serviceStopping": "正在停止服务: {name}...",
@@ -235,7 +244,10 @@
       "backupPartialFail": "\n\n⚠️  注意：部分文件备份失败（可能文件被占用），请关闭相关程序后重试。",
       "startSuccess": "环境启动成功！\n{result}",
       "nginxConfigOpened": "已打开 {dir} 配置目录",
-      "nginxConfigFailed": "打开目录失败，请手动打开 services/{dir}/conf.d/"
+      "nginxConfigFailed": "打开目录失败，请手动打开 services/{dir}/conf.d/",
+      "pullPartialSuccess": "⚠️ 部分镜像拉取失败：{details}。失败的将回退到 fallback 模板。",
+      "pullAllFailed": "❌ 所有镜像拉取失败，已使用 fallback 模板应用配置",
+      "pullAllSuccess": "✅ {count} 个镜像全部拉取成功"
     },
     "error": {
       "dockerNotRunning": "❌ Docker 未运行\n\n请启动 Docker Desktop 后重试。",
@@ -296,11 +308,6 @@
       "tip": "镜像一旦拉取到本地，\"一键启动\"会直接复用本地缓存，不会重复下载。后续启动更快速。",
       "confirmPull": "确认拉取 {count} 个",
       "pulling": "拉取中…"
-    },
-    "toast": {
-      "pullPartialSuccess": "⚠️ 部分镜像拉取失败：{details}。失败的将回退到 fallback 模板。",
-      "pullAllFailed": "❌ 所有镜像拉取失败，已使用 fallback 模板应用配置",
-      "pullAllSuccess": "✅ {count} 个镜像全部拉取成功"
     }
   },
   "settings": {
@@ -548,6 +555,22 @@
       "title": "环境恢复成功！",
       "description": "您可以重新启动 Docker 容器以应用新的配置"
     },
+    "partialSuccess": {
+      "title": "恢复完成，但有部分失败",
+      "description": "下方列出了未能恢复的文件。如需撤销本次恢复，可使用回滚包还原。"
+    },
+    "fatal": {
+      "title": "恢复失败",
+      "description": "未能写入任何文件。下方是错误原因；若已生成回滚包，可用它还原恢复前的配置。"
+    },
+    "result": {
+      "restoredFiles": "已恢复文件",
+      "filesCount": "共 {count} 个文件",
+      "errors": "错误明细",
+      "rollbackTitle": "恢复前回滚包",
+      "rollbackHint": "恢复开始前已自动备份当前配置，如需撤销可一键用此包重新走恢复向导：",
+      "rollbackAction": "用此包重新恢复"
+    },
     "progress": {
       "title": "📊 恢复进度"
     },
@@ -556,11 +579,18 @@
       "message": "⚠️ 注意: 现有配置文件将被覆盖，建议先备份当前环境\n\n💡 恢复完成后，点击\"一键启动\"即可运行环境",
       "start": "开始恢复"
     },
+    "rollbackConfirm": {
+      "title": "用回滚包重新恢复？",
+      "message": "将把该回滚包载入恢复向导（预览 → 校验 → 确认）。这会再次覆盖当前工作区配置。",
+      "confirm": "载入回滚包"
+    },
     "toast": {
       "previewDone": "预览完成，请查看备份内容",
       "verifyPassed": "校验通过，可以开始恢复",
       "verifyFailed": "校验失败，备份文件可能已损坏",
-      "success": "环境恢复成功！"
+      "success": "环境恢复成功！",
+      "partialSuccess": "⚠️ 恢复完成但存在错误，请查看下方明细",
+      "fatalFailed": "恢复失败，请查看下方错误明细"
     }
   },
   "workspace": {
@@ -573,10 +603,15 @@
     "error": {
       "invalidPath": "请选择一个有效的目录作为工作区"
     },
+    "banner": {
+      "title": "工作区路径不可用",
+      "action": "查看环境配置"
+    },
     "status": {
       "loading": "加载中...",
       "notConfigured": "未配置",
-      "loadFailed": "获取失败"
+      "loadFailed": "获取失败",
+      "fallback": "配置的工作区不可用，数据实际写入 {effective}。{reason}"
     }
   }
 }
\ No newline at end of file
diff --git a/src/types/__tests__/docker.spec.ts b/src/types/__tests__/docker.spec.ts
new file mode 100644
index 0000000..14659e6
--- /dev/null
+++ b/src/types/__tests__/docker.spec.ts
@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest'
+import { isContainerRunning, parseContainerState } from '../docker'
+import type { ContainerState } from '../docker'
+
+describe('docker 容器状态契约', () => {
+  it('仅 running 判定为运行中', () => {
+    const running: ContainerState[] = ['running']
+    const notRunning: ContainerState[] = [
+      'created',
+      'paused',
+      'restarting',
+      'exited',
+      'removing',
+      'dead',
+      'unknown',
+    ]
+
+    for (const s of running) {
+      expect(isContainerRunning(s)).toBe(true)
+    }
+    for (const s of notRunning) {
+      expect(isContainerRunning(s)).toBe(false)
+    }
+  })
+
+  it('后端枚举值全部能被识别，不落入 unknown', () => {
+    const backendValues = [
+      'created',
+      'running',
+      'paused',
+      'restarting',
+      'exited',
+      'removing',
+      'dead',
+    ]
+    for (const v of backendValues) {
+      expect(parseContainerState(v)).toBe(v)
+    }
+  })
+
+  it('未知或缺失状态降级为 unknown，而不是抛错', () => {
+    expect(parseContainerState('SOMETHING_NEW')).toBe('unknown')
+    expect(parseContainerState(undefined)).toBe('unknown')
+    expect(parseContainerState(null)).toBe('unknown')
+  })
+
+  it('兼容历史遗留的 "Some(RUNNING)" 写法', () => {
+    // 旧契约是 Rust Debug 输出；若仍有老版本后端在跑，不应把面板打崩
+    expect(parseContainerState('Some(RUNNING)')).toBe('unknown')
+    expect(isContainerRunning(parseContainerState('Some(RUNNING)'))).toBe(false)
+  })
+})
diff --git a/src/types/docker.ts b/src/types/docker.ts
new file mode 100644
index 0000000..0f75eb5
--- /dev/null
+++ b/src/types/docker.ts
@@ -0,0 +1,44 @@
+// 容器状态契约：与 Rust `docker::manager::ContainerState` 一一对应。
+// 后端用 `#[serde(rename_all = "lowercase")]` 序列化，前端按同样的字面量解析。
+// 此前两端靠 `format!("{:?}")` → `includes('running')` 猜测，Docker/bollard 升级即碎。
+export type ContainerState =
+  | 'created'
+  | 'running'
+  | 'paused'
+  | 'restarting'
+  | 'exited'
+  | 'removing'
+  | 'dead'
+  | 'unknown';
+
+export interface Container {
+  id: string;
+  name: string;
+  image: string;
+  status: string;
+  state: ContainerState;
+  ports: number[];
+}
+
+/** 仅 running 视为运行中；restarting 尚未真正提供服务，不算。 */
+export function isContainerRunning(state: ContainerState): boolean {
+  return state === 'running';
+}
+
+/**
+ * 兜底解析：后端枚举升级、新增变体或字段异常时，未知值一律归为 'unknown'，
+ * 不让反序列化把整个容器列表打崩。
+ */
+export function parseContainerState(raw: unknown): ContainerState {
+  const known: ContainerState[] = [
+    'created',
+    'running',
+    'paused',
+    'restarting',
+    'exited',
+    'removing',
+    'dead',
+  ];
+  const value = String(raw ?? '').toLowerCase();
+  return (known as string[]).includes(value) ? (value as ContainerState) : 'unknown';
+}
diff --git a/src/types/env-config.ts b/src/types/env-config.ts
index d184bd8..909ab26 100644
--- a/src/types/env-config.ts
+++ b/src/types/env-config.ts
@@ -111,6 +111,21 @@ export interface RestoreProgress {
   percentage: number;
 }
 
+/// 后端 `RestoreResult` 序列化形态
+///
+/// 恢复命令始终返回该结构（U2）：
+/// - success=true：全部成功
+/// - success=false 且 restored_files 非空：部分失败
+/// - success=false 且 restored_files 为空：致命失败（包打不开 / zip-slip 等）
+/// 前端用结果面板展示明细与回滚包快捷入口，不只弹 toast。
+export interface RestoreResult {
+  success: boolean;
+  restored_files: string[];
+  errors: string[];
+  /// 恢复前自动生成的回滚包绝对路径（R2）。无回滚包时后端省略该字段。
+  rollback_path?: string | null;
+}
+
 // Docker 容器端口冲突信息
 export interface ContainerPortConflict {
   port: number;
diff --git a/src/utils/__tests__/pollBackoff.spec.ts b/src/utils/__tests__/pollBackoff.spec.ts
new file mode 100644
index 0000000..58f5ea4
--- /dev/null
+++ b/src/utils/__tests__/pollBackoff.spec.ts
@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest'
+import { nextPollDelay, POLL_INTERVAL_MS } from '../pollBackoff'
+
+describe('轮询退避', () => {
+  it('正常情况与短暂抖动都保持 5 秒', () => {
+    expect(nextPollDelay(0)).toBe(POLL_INTERVAL_MS)
+    expect(nextPollDelay(1)).toBe(POLL_INTERVAL_MS)
+    expect(nextPollDelay(2)).toBe(POLL_INTERVAL_MS)
+  })
+
+  it('连续失败 3 次起退避到 15 秒', () => {
+    expect(nextPollDelay(3)).toBe(15000)
+    expect(nextPollDelay(5)).toBe(15000)
+  })
+
+  it('连续失败 6 次起退避到 30 秒', () => {
+    expect(nextPollDelay(6)).toBe(30000)
+    expect(nextPollDelay(100)).toBe(30000)
+  })
+
+  it('间隔随失败次数单调不减', () => {
+    let previous = 0
+    for (let failures = 0; failures <= 20; failures++) {
+      const delay = nextPollDelay(failures)
+      expect(delay).toBeGreaterThanOrEqual(previous)
+      previous = delay
+    }
+  })
+})
diff --git a/src/utils/pollBackoff.ts b/src/utils/pollBackoff.ts
new file mode 100644
index 0000000..734e403
--- /dev/null
+++ b/src/utils/pollBackoff.ts
@@ -0,0 +1,32 @@
+/**
+ * 容器轮询间隔与退避策略。
+ *
+ * Docker Desktop 未启动时，固定 5 秒一次的全量轮询（ping + 拉列表 + 写日志）
+ * 会持续刷屏且毫无产出。连续失败后拉长间隔，恢复可用后立即回到 5 秒。
+ */
+
+/** Docker 可用时的正常轮询间隔 */
+export const POLL_INTERVAL_MS = 5000;
+
+/** 连续失败达到阈值后逐级退避的间隔 */
+const POLL_BACKOFF_MS = [15000, 30000];
+
+/** 触发各档退避所需的连续失败次数（与 POLL_BACKOFF_MS 一一对应） */
+const BACKOFF_THRESHOLDS = [3, 6];
+
+/**
+ * 根据连续失败次数得出下一次轮询的等待时间。
+ *
+ * 0~2 次失败：5s（短暂抖动不惩罚）
+ * 3~5 次失败：15s
+ * 6 次及以上：30s
+ */
+export function nextPollDelay(consecutiveFailures: number): number {
+  // 从最严档位往下找第一个满足的阈值
+  for (let i = BACKOFF_THRESHOLDS.length - 1; i >= 0; i--) {
+    if (consecutiveFailures >= BACKOFF_THRESHOLDS[i]) {
+      return POLL_BACKOFF_MS[i];
+    }
+  }
+  return POLL_INTERVAL_MS;
+}
diff --git a/src/utils/portChecker.ts b/src/utils/portChecker.ts
index 55716bc..fb21256 100644
--- a/src/utils/portChecker.ts
+++ b/src/utils/portChecker.ts
@@ -1,15 +1,8 @@
 import { invoke } from '@tauri-apps/api/core';
 import type { ContainerPortConflict } from '../types/env-config';
 import type { EnvConfig } from '../types/env-config';
-
-interface Container {
-  id: string;
-  name: string;
-  image: string;
-  status: string;
-  state: string;
-  ports: number[];
-}
+import type { Container } from '../types/docker';
+import { isContainerRunning } from '../types/docker';
 
 /**
  * 从 EnvConfig 中提取所有需要检查的端口
@@ -48,7 +41,7 @@ export async function checkContainerPortConflicts(
     for (const [port, service] of requiredPorts.entries()) {
       // 查找是否有容器占用了这个端口
       const occupyingContainer = containers.find(c => 
-        c.ports.includes(port) && isRunning(c.state)
+        c.ports.includes(port) && isContainerRunning(c.state)
       );
       
       if (occupyingContainer) {
@@ -72,14 +65,6 @@ export async function checkContainerPortConflicts(
   }
 }
 
-/**
- * 判断容器是否运行中
- */
-function isRunning(state: string): boolean {
-  const normalized = state.toLowerCase();
-  return normalized.includes('running');
-}
-
 /**
  * 格式化容器端口冲突提示信息
  */