diff --git a/CHANGELOG.md b/CHANGELOG.md
index c9098bc..dc44e79 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.3.4] - 2026-09-28
+
+### 修复
+
+- **一键升级找不到 Compose 文件**：fnOS 或 Docker UI 启动 Compose 时，updater 的 `.:/workspace` 可能解析到错误目录，构建时报 `open /workspace/docker-compose.hub.yml: no such file or directory`。Compose 文件现支持用 `FONU_UPDATE_HOST_DIR` 显式指定宿主机 Compose 目录，并在状态接口中提前报告缺少 Compose 文件，避免排到升级后才失败
+- **示例页验证标识更新为 v1.3.4-example-page**，用于确认升级后的前端资源确实生效
+
+### 变更
+
+- 版本号提升到 1.3.4；`web/package.json` 与 `web/package-lock.json` 同步对齐
+- `AgentVersion` 保持 0.12.8
+
+### 测试
+
+- `internal/updater`：补充 Compose 文件缺失检查
+
 ## [v1.3.3] - 2026-09-27
 
 ### 新增
diff --git a/VERSION b/VERSION
index 31e5c84..d0149fe 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-1.3.3
+1.3.4
diff --git a/docker-compose.hub.yml b/docker-compose.hub.yml
index 496885c..de8ae41 100644
--- a/docker-compose.hub.yml
+++ b/docker-compose.hub.yml
@@ -70,7 +70,7 @@ services:
     restart: unless-stopped
     volumes:
       - ${DOCKER_SOCK:-/var/run/docker.sock}:/var/run/docker.sock
-      - .:/workspace
+      - ${FONU_UPDATE_HOST_DIR:-.}:/workspace
       - fonu-updater-sock:/run/fonu-updater
     environment:
       FONU_UPDATER_SOCKET: /run/fonu-updater/updater.sock
diff --git a/docker-compose.yml b/docker-compose.yml
index 2358773..4d496b3 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -54,7 +54,7 @@ services:
     restart: unless-stopped
     volumes:
       - ${DOCKER_SOCK:-/var/run/docker.sock}:/var/run/docker.sock
-      - .:/workspace
+      - ${FONU_UPDATE_HOST_DIR:-.}:/workspace
       - fonu-updater-sock:/run/fonu-updater
     environment:
       FONU_UPDATER_SOCKET: /run/fonu-updater/updater.sock
diff --git a/docs/README.md b/docs/README.md
index eae4b1c..3760897 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,7 +1,7 @@
 # Fonu 文档索引
 
 > 维护约定：新增方案 / 审查文档时在下方登记；方案落地后在「状态」列标注实施结果，并给已被推翻的描述加时效说明。
-> 最近更新：2026-09-27（v1.3.3）
+> 最近更新：2026-09-28（v1.3.4）
 
 ## 方案与设计（本目录）
 
@@ -9,7 +9,7 @@
 | --- | --- | --- |
 | `project-analysis-2026-09-27.md` | 全项目详细分析（v1.2.19）：架构、模块、数据、API、前端、链路、风险与改进路线 | 当前版本快照 |
 | `improvement-roadmap-2026-09-27.md` | P0-P3 改进路线实施方案：逐项改法、测试、验收、依赖、发布与回滚 | P0-1、P0-3 已完成，其余待实施 |
-| `system-upgrade.md` | Docker Compose 一键升级：sidecar 架构、首次部署、安全边界、回滚、故障排查与验证页 | 已实施（v1.3.3） |
+| `system-upgrade.md` | Docker Compose 一键升级：sidecar 架构、首次部署、安全边界、回滚、故障排查与验证页 | 已实施（v1.3.4） |
 | `project-audit-2026-09-24.md` | 全项目审查：P0/P1/P2 分级，含精确行号与逐条修法 | **进行中**——P0 已随 v1.2.7 完成，P1 实施中 |
 | `frp-server-list-merge-plan.md` | FRP 服务端列表并入「公网服务端」页（方案 A，四步） | 步 1/2 已完成（v1.2.6）；步 3 文案收尾、步 4 死样式清理未做 |
 | `agent-capability-plan.md` | fonu-agent 能力扩展（P0/P1/P2/P3） | 已实施（agent 0.11.0）；P3 三项不做 |
diff --git a/docs/system-upgrade.md b/docs/system-upgrade.md
index 2521d6c..d99c203 100644
--- a/docs/system-upgrade.md
+++ b/docs/system-upgrade.md
@@ -94,6 +94,7 @@ docker compose -f docker-compose.hub.yml up -d --build
 | `FONU_UPDATE_BRANCH` | `git` 模式下的分支，默认 `main` |
 | `FONU_UPDATE_APP_URL` | 健康检查地址，默认 `http://fonu:6893` |
 | `DOCKER_SOCK` | 宿主机 Docker Socket，默认 `/var/run/docker.sock` |
+| `FONU_UPDATE_HOST_DIR` | 宿主机上 Compose 文件所在目录；Docker UI / fnOS 场景下建议显式设置 |
 
 ## 6. 前端行为
 
@@ -157,6 +158,28 @@ docker compose up -d --build updater
 docker compose up -d --build
 ```
 
+### 升级时报 `/workspace/docker-compose.hub.yml: no such file or directory`
+
+说明 updater 容器没有挂载到真实的 Compose 项目目录。先查询运行中 `fonu` 容器的 Compose 工作目录：
+
+```bash
+docker inspect fonu --format '{{ index .Config.Labels "com.docker.compose.project.working_dir" }}'
+```
+
+把输出目录写入 Compose 同层 `.env`：
+
+```dotenv
+FONU_UPDATE_HOST_DIR=/实际/的/Compose/目录
+```
+
+然后只重建 updater：
+
+```bash
+docker compose -f /实际/的/Compose/目录/docker-compose.hub.yml up -d --build updater
+```
+
+状态接口此时会明确提示 Compose 文件缺失，修复挂载后按钮才会重新显示。
+
 ### `docker-compose.hub.yml` 模式无法读取远端版本
 
 检查 sidecar 容器内是否可以访问 Git 仓库：
@@ -203,16 +226,16 @@ FONU_VERSION=<旧版本> docker compose up -d --no-deps --force-recreate fonu
 
 ## 10. 在线升级验证
 
-示例页面用于验证升级结果。v1.3.3 的验证流程：
+示例页面用于验证升级结果。v1.3.4 的验证流程：
 
 1. 确认当前线上实例为 v1.3.0，且 `fonu-updater` sidecar 已运行。
-2. 确认远端 `main` 分支的 `VERSION` 为 `1.3.3`。
+2. 确认远端 `main` 分支的 `VERSION` 为 `1.3.4`。
 3. 在侧栏看到「一键升级」后点击并确认。
 4. 等待升级弹窗显示成功，页面自动刷新。
 5. 打开侧栏「示例页面」，确认：
    - 页面路由为 `/example`；
-   - 页面显示的版本为 `1.3.3`；
-   - 页面显示验证标识 `v1.3.3-example-page`；
+   - 页面显示的版本为 `1.3.4`；
+   - 页面显示验证标识 `v1.3.4-example-page`；
    - 「升级验证」显示为「通过」。
 
 如果示例页面可见且版本正确，说明镜像构建、容器重建、后端版本注入和前端静态资源更新均已生效。
diff --git a/internal/updater/runner.go b/internal/updater/runner.go
index d2da593..fd5619c 100644
--- a/internal/updater/runner.go
+++ b/internal/updater/runner.go
@@ -22,6 +22,9 @@ func (s *Server) runUpdate(ctx context.Context) error {
 	s.state.Phase = PhaseRunning
 	s.state.Message = "正在准备升级"
 	s.mu.Unlock()
+	if err := s.ensureComposeFile(); err != nil {
+		return err
+	}
 
 	latest, err := s.latestVersion(ctx)
 	if err != nil {
diff --git a/internal/updater/server.go b/internal/updater/server.go
index 90e8ee5..ddf7193 100644
--- a/internal/updater/server.go
+++ b/internal/updater/server.go
@@ -162,6 +162,17 @@ func (s *Server) handleApply(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusAccepted, status)
 }
 
+func (s *Server) ensureComposeFile() error {
+	info, err := os.Stat(s.composePath)
+	if err != nil {
+		return fmt.Errorf("找不到 Compose 文件 %s；请确认 updater 的 /workspace 挂载，或在 .env 设置 FONU_UPDATE_HOST_DIR 指向 Compose 所在目录", s.composePath)
+	}
+	if info.IsDir() {
+		return fmt.Errorf("Compose 路径是目录而不是文件：%s", s.composePath)
+	}
+	return nil
+}
+
 // Status 返回当前版本、远端版本和任务状态。
 func (s *Server) Status(ctx context.Context) Status {
 	s.mu.Lock()
@@ -170,6 +181,16 @@ func (s *Server) Status(ctx context.Context) Status {
 		s.mu.Unlock()
 		return status
 	}
+	s.mu.Unlock()
+	if err := s.ensureComposeFile(); err != nil {
+		s.mu.Lock()
+		defer s.mu.Unlock()
+		s.state.UpdateAvailable = false
+		s.state.Message = err.Error()
+		s.state.CheckedAt = time.Now().UTC().Format(time.RFC3339)
+		return cloneStatus(s.state)
+	}
+	s.mu.Lock()
 	if !s.lastChecked.IsZero() && time.Since(s.lastChecked) < time.Minute {
 		status := cloneStatus(s.state)
 		s.mu.Unlock()
diff --git a/internal/updater/server_test.go b/internal/updater/server_test.go
index fa4cd3a..15bc0e7 100644
--- a/internal/updater/server_test.go
+++ b/internal/updater/server_test.go
@@ -1,6 +1,7 @@
 package updater
 
 import (
+	"os"
 	"path/filepath"
 	"testing"
 )
@@ -41,3 +42,21 @@ func TestNewServerDefaultsAndValidation(t *testing.T) {
 		t.Fatal("git 模式缺少 RepoURL 应被拒绝")
 	}
 }
+
+func TestEnsureComposeFile(t *testing.T) {
+	dir := t.TempDir()
+	server, err := NewServer(Config{ProjectDir: dir, ComposeFile: "docker-compose.yml"}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := server.ensureComposeFile(); err == nil {
+		t.Fatal("缺少 compose 文件时应返回错误")
+	}
+	path := filepath.Join(dir, "docker-compose.yml")
+	if err := os.WriteFile(path, []byte("services: {}\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := server.ensureComposeFile(); err != nil {
+		t.Fatalf("存在 compose 文件时不应报错: %v", err)
+	}
+}
diff --git a/web/package-lock.json b/web/package-lock.json
index 93a9e72..35562d6 100644
--- a/web/package-lock.json
+++ b/web/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "fonu-web",
-  "version": "1.3.3",
+  "version": "1.3.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "fonu-web",
-      "version": "1.3.3",
+      "version": "1.3.4",
       "dependencies": {
         "@codemirror/commands": "^6.11.1",
         "@codemirror/lang-javascript": "^6.2.5",
diff --git a/web/package.json b/web/package.json
index 208ee11..25cbde4 100644
--- a/web/package.json
+++ b/web/package.json
@@ -1,7 +1,7 @@
 {
   "name": "fonu-web",
   "private": true,
-  "version": "1.3.3",
+  "version": "1.3.4",
   "packageManager": "npm@10.9.4",
   "type": "module",
   "scripts": {
diff --git a/web/src/views/ExampleView.vue b/web/src/views/ExampleView.vue
index f7a12e7..c7a50a4 100644
--- a/web/src/views/ExampleView.vue
+++ b/web/src/views/ExampleView.vue
@@ -8,7 +8,7 @@
     </template>
   </PageHeader>
 
-  <n-alert type="success" :bordered="false" class="example-alert" title="v1.3.3 示例页面验证标识已生效">
+  <n-alert type="success" :bordered="false" class="example-alert" title="v1.3.4 示例页面验证标识已生效">
     当前页面由 v{{ version }} 提供，验证标识为 <span class="mono">{{ verificationMarker }}</span>。
     如果你是在升级后首次看到这行内容，说明前端构建、镜像重建和服务重启均已成功。
   </n-alert>
@@ -66,7 +66,7 @@ const message = useMessage()
 const version = ref(__APP_VERSION__)
 const checkedAt = ref('')
 const refreshing = ref(false)
-const verificationMarker = 'v1.3.3-example-page'
+const verificationMarker = 'v1.3.4-example-page'
 
 async function refreshVersion() {
   refreshing.value = true