From fb2ca805d95fb4616a4a67613d8fd5db6ae5411a Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Sun, 29 Mar 2026 23:18:29 +0800
Subject: [PATCH 01/28] =?UTF-8?q?docs:=20=E9=87=8D=E6=9E=84=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3=E7=BB=93=E6=9E=84=E5=B9=B6=E4=BF=AE=E6=94=B9=E5=86=85?=
 =?UTF-8?q?=E5=AE=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md                              | 11 ++++
 Readme.md                              |  4 --
 docs/00_Root_Context.md                | 67 ------------------------
 docs/01_Backend_Standards.md           | 21 --------
 docs/01_Frontend_Standards.md          | 25 ---------
 docs/02_API_Contracts.md               | 13 -----
 docs/api/contracts.md                  | 46 ++++++++++++++++
 docs/design-docs/instance_lifecycle.md | 46 ++++++++++++++++
 docs/domain_instance_lifecycle.md      | 35 -------------
 docs/exec-plans/README.md              | 67 ++++++++++++++++++++++++
 docs/ops_engineering_standards.md      | 69 ------------------------
 docs/standards/backend.md              | 72 ++++++++++++++++++++++++++
 docs/standards/directory.md            | 29 +++++++++++
 docs/standards/frontend.md             | 67 ++++++++++++++++++++++++
 docs/standards/ops.md                  | 62 ++++++++++++++++++++++
 15 files changed, 400 insertions(+), 234 deletions(-)
 create mode 100644 AGENTS.md
 delete mode 100644 docs/00_Root_Context.md
 delete mode 100644 docs/01_Backend_Standards.md
 delete mode 100644 docs/01_Frontend_Standards.md
 delete mode 100644 docs/02_API_Contracts.md
 create mode 100644 docs/api/contracts.md
 create mode 100644 docs/design-docs/instance_lifecycle.md
 delete mode 100644 docs/domain_instance_lifecycle.md
 create mode 100644 docs/exec-plans/README.md
 delete mode 100644 docs/ops_engineering_standards.md
 create mode 100644 docs/standards/backend.md
 create mode 100644 docs/standards/directory.md
 create mode 100644 docs/standards/frontend.md
 create mode 100644 docs/standards/ops.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..c36ebfc
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,11 @@
+## 文档目录
+[API](docs/api/contracts.md)
+## 规范
+[目录规范](docs/standards/directory.md)
+[后端规范](docs/standards/backend.md)
+[前端规范](docs/standards/frontend.md)
+[运维规范](docs/standards/ops.md)
+## 设计
+[容器实例设计](docs/design-docs/instance_lifecycle.md)
+## 执行计划
+[执行计划目录说明](docs/exec-plans/README.md)
diff --git a/Readme.md b/Readme.md
index ab4c7a3..66779bd 100644
--- a/Readme.md
+++ b/Readme.md
@@ -38,7 +38,3 @@ task frontend:install  # 安装前端依赖
 - [ ] 可视化 Web 文件浏览器
 - [ ] 游戏基础配置文件的在线文本编辑器
 - [ ] 大文件 (Mod/插件) 上传及在线解压缩
-
-## 注意事项
-默认 SQLite 数据库路径为 `backend/data/minedock.db`（在 `backend` 目录启动时对应 `data/minedock.db`）。
-可通过环境变量 `MINEDOCK_DB_PATH` 覆盖。
\ No newline at end of file
diff --git a/docs/00_Root_Context.md b/docs/00_Root_Context.md
deleted file mode 100644
index 8f98311..0000000
--- a/docs/00_Root_Context.md
+++ /dev/null
@@ -1,67 +0,0 @@
-# MineDock Root Context
-
-## 1. 说明
-MineDock 是一个用于管理 Docker 容器实例的系统
-
-## 2. 目标
-实现一个支持易配置,功能强的游戏服务器容器化管理平台
-
-## 3. 当前系统边界
-### 所有权边界
-#### 边界内
-- 本系统创建的容器
-- 本系统的数据库及其数据
-- 本系统的工作目录及容器挂载配置的数据卷目录
-#### 边界外
-- 非本系统创建的容器
-- 宿主机的其他进程
-- 除上述工作与挂载目录外的其他宿主机文件系统
-### 功能边界
-#### 边界内
-- 容器的生命周期管理与资源配额调度
-- 容器内游戏服务器的快速安装与运行
-- 在线终端交互与控制指令下发
-- 游戏数据的持久化与灾灾备 (快照、备份与回档)
-#### 边界外
-- 游戏服务端程序本身的更新与热修复
-### 数据边界
-#### 边界内
-- Docker SDK返回的运行时信息
-- 容器的标准输出日志流
-- 容器的端口暴露配置
-#### 边界外
-- Docker Daemon的集群状态
-- 主机底层的网络状态(如防火墙配置)
-### 用户边界
-#### 边界内
-- 单管理员环境结构下的全局容器管控
-#### 边界外
-- 复杂的多租户资源隔离与细粒度角色控制 (RBAC)
-
-## 4. 目录规范
-```text
-MineDock/
-├── backend/                # 后端 Go 服务
-│   ├── data/               # 数据存储目录（如 SQLite 数据库文件）
-│   ├── internal/           # 内部私有代码
-│   │   ├── api/            # 路由与 HTTP 处理层 (Handlers, Routers)
-│   │   ├── model/          # 领域数据模型定义实体 (如 Instance)
-│   │   ├── service/        # 核心业务逻辑服务 (如调用 Docker CLI/SDK)
-│   │   └── store/          # 数据持久化/存储交互层
-│   ├── main.go             # 后端程序入口
-│   └── go.mod              # Go 依赖配置
-├── frontend/               # 前端 Vue 项目
-│   ├── src/
-│   │   ├── api/            # 统一管理后端接口定义与请求封装
-│   │   ├── components/     # 全局复用组件（非全局使用的应当就近存放业务内）
-│   │   ├── composables/    # 复用的组合式 API (如 useInstances) 
-│   │   ├── locales/        # 多语言 i18n 配置文件
-│   │   ├── router/         # 路由配置与全局路由守卫
-│   │   ├── stores/         # 全局跨组件状态管理 (Pinia)
-│   │   └── views/          # 路由级别的业务页面组件
-│   ├── package.json        # Npm 依赖配置
-│   └── vite.config.js      # Vite 构建配置
-├── docs/                   # 相关架构规范与领域文档
-├── Taskfile.yml            # 自动化任务构建配置
-└── Readme.md               # 项目文档与入口
-```
diff --git a/docs/01_Backend_Standards.md b/docs/01_Backend_Standards.md
deleted file mode 100644
index fca6c3a..0000000
--- a/docs/01_Backend_Standards.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# 后端规范
-
-后端基于以下核心选型构建：
-- **开发语言**：Go
-- **持久化存储**：SQLite
-- **核心依赖**：Docker SDK
-
-## 架构依赖规则
-为保证代码的可测试性与可维护性，`internal` 目录下的四层架构必须遵循单向依赖规则，严禁循环引用：
-- **`api` 层**：作为程序的入口与防腐层，负责依赖注入 `service`，并处理 HTTP 相关的解析与返回。
-- **`service` 层**：作为纯粹的业务中枢，内部调用 `store` 进行持久化获取或通过外部组件交互。
-- **`store` 层**：负责底层数据落地设计（如 SQLite 语句），对外暴露 Interface 或直接的数据操作方法。
-- **`model` 层**：最为底层，被上述三层共同引用，不应依赖 `api`/`service`/`store` 的任何代码。
-
-## 编码质量与规范
-- **代码格式化与校验**：`go fmt` 与 `go vet`
-- **错误处理**：
-  - 核心逻辑层要求显式返回 `error`，并在合适的网络层封装为统一规范的 JSON HTTP 响应体（如 `{"status": "error", "message": "..."}`）。
-  - 透传错误时，应使用 `%w` （如 `fmt.Errorf("操作容器失败: %w", err)`）保留错误堆栈及上下文。
-- **Panic 处理**：业务处理流程中严禁主动触发 `panic`。仅系统引导阶段（如 SQLite 数据源加载失败、配置文件解析失败等无法提供服务的场景）被允许 `panic`
-- **无状态设计**：作为管理平台，除了 `store` 与外部环境，`api` 层与 `service` 层应保持无状态，以防发生状态数据不一致的异常
diff --git a/docs/01_Frontend_Standards.md b/docs/01_Frontend_Standards.md
deleted file mode 100644
index d963cbc..0000000
--- a/docs/01_Frontend_Standards.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# 前端规范
-
-前端基于以下核心选型构建：
-- **构建工具**：Vite
-- **核心框架**：Vue 3 (Composition API)
-- **开发语言**: TypeScript
-- **状态管理**：Pinia
-- **路由控制**：Vue Router
-
-## 代码质量
-- **代码格式化与校验**: 使用 ESLint + Prettier
-
-## 模块化与主题化
-前端 UI 必须具备高度的模块化，以支持动态主题（如浅色/暗色模式切换）和未来可能的皮肤更换
-- **禁止硬编码样式**：所有颜色、间距、字体大小必须使用 CSS 变量引入
-- **变量分层**：
-  - 基础变量：如 `--blue-500`, `--gray-900`
-  - 语义变量：如 `--bg-primary`, `--text-danger`, `--border-color`
-- **主题切换实现**：通过动态修改 `<html>` 或 `<body>` 的 `data-theme` 属性（如 `data-theme="dark"`），结合 CSS 变量覆盖实现低成本主题切换
-
-## 国际化规范
-提供多语言支持
-- **文案分离**：所有的界面静态文本禁止在 `.vue` 或 `.js` 文件中硬编码，必须通过 Vue I18n 等插件引入
-- **文件组织**：语言包统一存放于 `src/locales/`，按语言划分（如 `zh-CN.json`, `en-US.json`）
-- **动态变量插值**：涉及动态数据的文案使用插值符，例如："成功启动容器 {containerName}"
diff --git a/docs/02_API_Contracts.md b/docs/02_API_Contracts.md
deleted file mode 100644
index e9c73e9..0000000
--- a/docs/02_API_Contracts.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# MineDock API Contracts
-
-前后端接口定义,后端与Docker Daemon的交互流等
-
-## 1. 容器实例生命周期接口 (Instance Lifecycle)
-
-| 方法 | 路径 | 说明 | 请求参数 | 返回结果 |
-| --- | --- | --- | --- | --- |
-| GET | `/api/instances` | 获取当前所有容器的列表 | 无 | `[{"container_id":"xxx", "name":"xxx", "status":"xxx"}]` |
-| POST | `/api/instances` | 创建一个新容器（初始为 Stopped） | `{"name": "测试服1号"}` | `{"status": "success", "container_id": "xxx"}` |
-| POST | `/api/instances/:id/start` | 启动指定容器实例 | 无（ID 在路径中） | `{"status": "success"}` |
-| POST | `/api/instances/:id/stop` | 停止指定容器实例 | 无（ID 在路径中） | `{"status": "success"}` |
-| DELETE | `/api/instances/:id` | 彻底删除指定容器实例 | 无（ID 在路径中） | `{"status": "success"}` |
diff --git a/docs/api/contracts.md b/docs/api/contracts.md
new file mode 100644
index 0000000..e4d058a
--- /dev/null
+++ b/docs/api/contracts.md
@@ -0,0 +1,46 @@
+# MineDock API Contracts
+
+## 命名规则
+
+
+## 约定
+- Base URL: `/api`
+- CORS: 允许任意来源,允许方法 `GET,POST,DELETE,OPTIONS`
+
+## HTTP接口
+
+| 方法 | 路径 | 说明 | 请求参数 | 返回结果 |
+| --- | --- | --- | --- | --- |
+| GET | `/api/instances` | 获取当前所有容器的列表 | 无 | `[{"container_id":"xxx", "name":"xxx", "status":"xxx"}]` |
+| POST | `/api/instances` | 创建一个新容器（初始为 Stopped） | `{"name": "测试服1号"}` | `{"status": "success", "container_id": "xxx"}` |
+| POST | `/api/instances/:id/start` | 启动指定容器实例 | 无（ID 在路径中） | `{"status": "success"}` |
+| POST | `/api/instances/:id/stop` | 停止指定容器实例 | 无（ID 在路径中） | `{"status": "success"}` |
+| DELETE | `/api/instances/:id` | 彻底删除指定容器实例 | 无（ID 在路径中） | `{"status": "success"}` |
+
+## JSON格式
+
+```go
+type createRequest struct {
+	Name string `json:"name"`
+}
+
+type statusResponse struct {
+	Status string `json:"status"`
+	Error  string `json:"error,omitempty"`
+}
+
+type createResponse struct {
+	Status      string `json:"status"`
+	ContainerID string `json:"container_id"`
+}
+```
+
+## 状态码约定
+
+| 接口 | 成功 | 失败 |
+| --- | --- | --- |
+| `GET /api/instances` | `200` | `500` |
+| `POST /api/instances` | `200` | `400`(JSON非法/空名称), `409`(名称冲突), `500` |
+| `POST /api/instances/:id/start` | `200` | `400`(ID非法), `500` |
+| `POST /api/instances/:id/stop` | `200` | `400`(ID非法), `500` |
+| `DELETE /api/instances/:id` | `200` | `400`(ID非法), `409`(实例运行中), `500` |
diff --git a/docs/design-docs/instance_lifecycle.md b/docs/design-docs/instance_lifecycle.md
new file mode 100644
index 0000000..36ef476
--- /dev/null
+++ b/docs/design-docs/instance_lifecycle.md
@@ -0,0 +1,46 @@
+# 容器实例生命周期
+
+## 数据结构
+
+### 后端
+```go
+type Instance struct {
+    // 映射的 Docker 容器唯一标识
+    ContainerID string `json:"container_id"`
+    // 服务端名称
+    Name        string `json:"name"`
+    // 当前运行态
+    Status      string `json:"status"`
+}
+```
+### 数据库
+- `instances` 表字段：
+- `container_id`（主键）
+- `name`（唯一）
+- `status`
+- `created_at`
+
+## 接口
+[../api/contracts.md](../api/contracts.md)
+
+## 状态流转
+
+```mermaid
+stateDiagram-v2
+    [*] --> Stopped: Create
+    Stopped --> Running: Start
+    Running --> Stopped: Stop
+    Stopped --> [*]: Delete
+```
+
+## 一致性策略
+
+- 事实来源：Docker Daemon。
+- 缓存来源：SQLite（用于实例名、状态缓存和恢复）。
+- 收敛机制：`ListInstances` 周期性/调用时同步 Docker -> SQLite。
+
+## 失败与回滚策略
+
+- 创建流程：若数据库保存失败，立即强制删除刚创建容器。
+- 启停流程：Docker 操作成功但 DB 更新失败时，接口返回错误；后续列表刷新会将状态重新收敛。
+- 删除流程：Docker 删除成功后若 DB 删除失败，后续列表会因 Docker 不存在而清理状态。
diff --git a/docs/domain_instance_lifecycle.md b/docs/domain_instance_lifecycle.md
deleted file mode 100644
index e8de601..0000000
--- a/docs/domain_instance_lifecycle.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# 容器实例生命周期
-
-## 1. 说明
-该领域负责容器实例的完整生命周期管理：
-- 查询当前实例列表
-- 创建新实例（不自动启动）
-- 启动指定实例
-- 停止指定实例
-- 彻底删除指定实例（要求先停止）
-
-该领域是当前系统的核心业务能力。
-
-## 2. 数据结构
-
-### Instance（后端）
-```go
-type Instance struct {
-    // 映射的 Docker 容器唯一标识
-    ContainerID string `json:"container_id"`
-    // 服务端名称 (比如 "测试服1号")
-    Name        string `json:"name"`
-    // 当前运行态 (Running, Stopped)
-    Status      string `json:"status"`
-}
-```
-
-## 3. HTTP 接口
-具体的接口定义请参考 [02_API_Contracts.md](02_API_Contracts.md#1-容器实例生命周期接口-instance-lifecycle)。
-
-## 4. 状态流转（当前实现语义）
-- 创建成功后：实例进入 `Stopped`，并写入 SQLite 持久化存储。
-- 启动成功后：实例状态更新为 `Running`。
-- 停止成功后：实例状态更新为 `Stopped`。
-- 删除成功后：销毁 Docker 容器，同时从 SQLite 中删除该实例记录；若实例仍为 `Running`，删除请求会被拒绝（需先停止）。
-- 列表查询：以后端从 Docker 引擎读取的受管容器为准，并同步更新 SQLite 中的实例状态信息。
diff --git a/docs/exec-plans/README.md b/docs/exec-plans/README.md
new file mode 100644
index 0000000..ea64905
--- /dev/null
+++ b/docs/exec-plans/README.md
@@ -0,0 +1,67 @@
+# 执行计划目录说明
+
+本目录用于存放可执行的研发计划文档（Execution Plan）。
+
+## 目标
+
+- 将需求拆分为可落地的阶段与任务。
+- 明确每一步的输入、输出、风险与验收标准。
+- 作为开发、联调、测试、验收的共享依据。
+
+## 命名规范
+
+建议格式：
+
+`YYYYMMDD-主题关键字.md`
+
+示例：
+
+- `20260329-instance-restart.md`
+- `20260330-backup-snapshot.md`
+
+## 编写模板
+
+```md
+# <计划标题>
+
+## 1. 背景与目标
+- 背景：
+- 目标：
+- 不在本次范围：
+
+## 2. 需求拆解
+- 功能点 A：
+- 功能点 B：
+
+## 3. 设计与改动范围
+- 后端改动：
+- 前端改动：
+- 文档改动：
+- 数据结构/接口变更：
+
+## 4. 执行步骤
+1. 步骤一
+2. 步骤二
+3. 步骤三
+
+## 5. 风险与回滚
+- 风险 1：
+- 风险 2：
+- 回滚方案：
+
+## 6. 验收标准
+- [ ] 验收项 1
+- [ ] 验收项 2
+- [ ] 验收项 3
+
+## 7. 测试计划
+- 单元测试：
+- 集成测试：
+- 手工验证：
+```
+
+## 完成定义（DoD）
+
+- 计划中的功能点已实现并通过对应检查。
+- 涉及接口变更时，`docs/api/contracts.md` 已同步更新。
+- 涉及行为变更时，设计文档与规范文档已同步更新。
\ No newline at end of file
diff --git a/docs/ops_engineering_standards.md b/docs/ops_engineering_standards.md
deleted file mode 100644
index e513a30..0000000
--- a/docs/ops_engineering_standards.md
+++ /dev/null
@@ -1,69 +0,0 @@
-# Ops & Infrastructure
-
-本文档定义了项目的本地开发工作流、自动化构建与 CI/CD 规范
-
-## 1. 构建命令
-| 指令 | 作用 | 说明 |
-| --- | --- | --- |
-| `task --list-all` | 查看可用任务 | 输出当前支持的任务列表 |
-| `task dev` | 一键启动前后端开发服务 | 并行执行 `backend:dev` 与 `frontend:dev` |
-| `task backend:fmt` | 检查后端 Go 代码格式 | 若存在未格式化文件则失败 |
-| `task backend:vet` | 执行后端静态检查 | 在 `backend` 目录执行 `go vet ./...` |
-| `task backend:test` | 执行后端测试 | 在 `backend` 目录执行 `go test ./...` |
-| `task build` | 统一编译前后端 | 依赖 `backend:build` 与 `frontend:build` |
-| `task clean` | 清理构建产物 | 清理 `backend/bin` 与 `frontend/dist` |
-| `task frontend:install` | 安装前端依赖 | 在 `frontend` 目录执行 `npm install` |
-| `task fmt` | 执行全局格式检查 | 当前依赖 `backend:fmt` |
-| `task vet` | 执行全局静态检查 | 当前依赖 `backend:vet` |
-| `task test` | 执行全局测试 | 当前依赖 `backend:test` |
-
-## 2. 环境依赖
-| 组件 | 用途 |
-| --- | --- |
-| Go | 后端编译与运行 |
-| Node.js + npm | 前端依赖安装、开发与构建 |
-| Docker Engine | 后端容器生命周期能力依赖 |
-| task | 统一任务入口 |
-
-## 3. CI/CD 对接规范
-GitHub Actions 工作流：
-
-- `.github/workflows/ci.yml`
-- `.github/workflows/release.yml`
-
-### 3.1 CI（代码自动化检查）
-
-触发条件：`push`、`pull_request`
-
-执行顺序：
-
-1. 准备 Go 与 Node.js 环境
-2. 安装 `task`
-3. 执行 `task frontend:install`
-4. 执行 `task fmt`
-5. 执行 `task test`
-6. 执行 `task vet`
-7. 执行 `task build`
-
-### 3.2 Release（跨平台编译发布）
-
-触发条件：推送标签 `v*`（例如 `v0.1.0`）
-
-执行顺序：
-
-1. 准备 Go 与 Node.js 环境
-2. 安装 `task`
-3. 执行 `task frontend:install`
-4. 执行 `task frontend:build`（仅构建一次）
-5. 交叉编译后端二进制（`linux/amd64`、`windows/amd64`、`darwin/amd64`、`darwin/arm64`）
-6. 打包发布产物（包含后端二进制、前端 `dist`、`Readme.md`）
-7. 上传到 GitHub Release
-
-## 4. 本地开发工作流
-
-推荐执行顺序如下：
-
-1. 安装前端依赖：`task frontend:install`
-2. 启动开发环境：`task dev`
-3. 发布前构建验证：`task build`
-4. 收尾清理：`task clean`
diff --git a/docs/standards/backend.md b/docs/standards/backend.md
new file mode 100644
index 0000000..f02849a
--- /dev/null
+++ b/docs/standards/backend.md
@@ -0,0 +1,72 @@
+# 后端规范
+
+## 1. 基础规范
+
+### 技术栈
+- 开发语言：Go
+- 持久化存储：SQLite
+- 核心依赖：Docker SDK
+- HTTP 框架：标准库 `net/http` + `http.ServeMux`
+- 数据库驱动：`modernc.org/sqlite`
+
+### 格式化
+
+- 所有 Go 文件必须通过 `gofmt`。
+- 本地执行：`task backend:fmt`，仓库级执行：`task fmt`。
+
+### 注释(Go Doc)
+
+- 导出符号（大写开头）**必须**以符号名开头的完整句子注释。
+- TODO 规范：`// TODO(username): 描述内容`。
+
+## 2. 核心机制与控制流
+
+### 上下文与并发
+- Context 传递：
+  - `ctx` 必须作为函数第一个参数。
+  - Handler 层通过 `r.Context()` 获取生命周期。
+  - 禁止将 `context.Context` 存储在结构体中。
+- Goroutine 管理：
+    - 启动 Goroutine 时必须明确其**退出机制**（通过 ctx 或 channel）。
+    - 禁止在 `init()` 函数中启动后台任务。
+
+### 错误处理
+
+- 底层错误统一使用 `fmt.Errorf("...: %w", err)` 包装。
+- 对于可预见的业务逻辑错误，在包级别定义 `ErrNotFound` 等变量，便于 `errors.Is()` 判断。
+- 优先处理错误流，减少 `else` 嵌套。
+
+## 3. 架构与设计模式
+
+### 依赖注入
+
+- 接口原则：Service 层定义的依赖接口应尽量“小”。
+- 构造函数：组件通过 `New...` 函数初始化，并在此处注入依赖（如 `func NewService(s Store) *Service`）。
+- 解耦：Handler 仅负责解析请求、调用 Service、返回 Response。禁止在 Handler 直接操作 Docker SDK 或 SQL。
+
+## 4. 数据与存储
+
+### 数据库
+
+- 并发控制：SQLite 必须限制 `SetMaxOpenConns(1)` 以避免 `database is locked` 错误。
+- 事务处理：涉及多表更新的操作必须在 Store 层封装事务，并确保 `defer tx.Rollback()`。
+- Upsert 模式：优先使用 `ON CONFLICT` 处理幂等写入。
+
+### API
+
+[../api/contracts.md](../api/contracts.md)
+
+## 5. 可观测性
+
+### 日志规范
+
+- 启动与致命错误使用标准库日志输出。
+- 禁止记录无意义的 `err != nil`。日志应包含：**动作+对象+关键ID+原始错误**。
+
+## 6. 质量保障
+
+### 测试
+
+- 后端测试入口：`task backend:test`（`go test ./...`）。
+- 静态检查：`task backend:vet`（`go vet ./...`）。
+- 提交前最低门禁建议：`task fmt && task vet && task test && task build`。
diff --git a/docs/standards/directory.md b/docs/standards/directory.md
new file mode 100644
index 0000000..419d45a
--- /dev/null
+++ b/docs/standards/directory.md
@@ -0,0 +1,29 @@
+## 目录规范
+```
+MineDock/
+├── .github/                # 存放ci/cd
+├── backend/                # 后端 Go 服务
+│   ├── data/               # 数据存储目录
+│   ├── internal/           # 内部私有代码
+│   │   ├── api/            # 路由与 HTTP 处理层
+│   │   ├── model/          # 领域数据模型定义
+│   │   ├── service/        # 核心业务逻辑层
+│   │   └── store/          # 数据持久化/存储交互层
+│   ├── main.go             # 后端程序入口
+│   └── go.mod              # Go 依赖配置
+├── frontend/               # 前端 Vue 项目
+│   ├── src/
+│   │   ├── api/            # 统一管理后端接口定义与请求封装
+│   │   ├── components/     # 全局复用组件
+│   │   ├── composables/    # 复用的组合式API
+│   │   ├── locales/        # 多语言 i18n 配置文件
+│   │   ├── router/         # 路由配置与全局路由守卫
+│   │   ├── stores/         # 全局状态管理
+│   │   └── views/          # 路由级别的业务页面组件
+│   ├── package.json        # Npm 依赖配置
+│   └── vite.config.js      # Vite 构建配置
+├── docs/                   # 文档
+├── Taskfile.yml            # 构建配置
+├── AGENTS.md               # 文档导航
+└── Readme.md               # 项目介绍
+```
diff --git a/docs/standards/frontend.md b/docs/standards/frontend.md
new file mode 100644
index 0000000..04c47f7
--- /dev/null
+++ b/docs/standards/frontend.md
@@ -0,0 +1,67 @@
+# 前端规范
+
+## 1. 基础与类型安全
+
+### 技术栈
+- 构建工具：Vite
+- 核心框架：Vue 3 (Composition API)
+- 开发语言: TypeScript
+- 状态管理：Pinia
+- 路由控制：Vue Router
+
+### 格式化
+
+- 使用 ESLint + Prettier。
+- 使用 TypeScript严格模式。
+
+## 2. 架构与组件设计
+
+- `views/` 放路由级页面。
+- `components/` 放可复用 UI 组件。
+- `stores/` 放 Pinia 业务状态和副作用聚合。
+- `api/` 统一封装网络调用，禁止在页面组件里散落 `fetch`。
+- 页面组件使用 `script setup` + Composition API 组织逻辑。
+
+## 3. 状态管理
+
+- 全局状态统一使用 Pinia。
+- 业务动作在 store 中实现并返回执行结果。
+- 视图层只负责触发动作和渲染，不直接维护后端数据副本。
+
+## 4. 数据交互与网络
+
+### API
+[../api/contracts.md](../api/contracts.md)
+
+网络约定：
+
+- 基础地址读取 `VITE_API_BASE_URL`，默认回退 `/api`。
+- 通用请求函数负责：
+	- JSON 序列化与 `Content-Type` 注入
+	- 默认 `Accept: application/json`
+	- 非 2xx 响应统一抛错（优先读取后端 `error` 字段）
+- 所有业务 API 通过统一封装函数导出。
+
+## 5. 样式与 UI 框架
+
+- 禁止硬编码样式：所有颜色、间距、字体大小必须使用 CSS 变量引入
+- 变量分层：
+  - 基础变量：如 `--blue-500`, `--gray-900`
+  - 语义变量：如 `--bg-primary`, `--text-danger`, `--border-color`
+- 主题切换实现：通过动态修改 `<html>` 或 `<body>` 的 `data-theme` 属性（如 `data-theme="dark"`），结合 CSS 变量覆盖实现低成本主题切换
+
+## 6. 路由与鉴权
+
+- 当前仅包含基础路由 `/`，映射容器列表页。
+- 当前版本无登录鉴权。
+- 新增页面时要求：
+	- 在 `router/index.ts` 显式注册路由
+	- 路由名称与页面职责一致
+	- 若后续引入鉴权，统一通过全局前置守卫实现
+
+## 7. 异常处理
+
+- API 异常统一在 store 层收敛并转换为可读错误信息。
+- 视图层对关键破坏性操作进行二次确认（如删除实例）。
+- 统一将成功/失败反馈写入 `output` 区域，避免静默失败。
+- 国际化文案通过 `vue-i18n` 管理，错误提示使用 i18n key 输出。
diff --git a/docs/standards/ops.md b/docs/standards/ops.md
new file mode 100644
index 0000000..138f491
--- /dev/null
+++ b/docs/standards/ops.md
@@ -0,0 +1,62 @@
+# 运维规范
+
+## 构建
+- `task frontend:install`：安装前端依赖
+- `task dev`：并行启动前后端开发服务
+- `task build`：构建前后端产物
+- `task clean`：清理构建产物
+- `task fmt` / `task lint` / `task test` / `task vet`：质量检查
+
+构建产物约定：
+
+- 后端：`backend/bin/minedock-backend(.exe)`
+- 前端：`frontend/dist`
+
+环境变量约定：
+
+- 后端：
+	- `MINEDOCK_DB_PATH`（默认 `data/minedock.db`）
+	- `MINEDOCK_IMAGE`（默认 `alpine:latest`）
+- 前端：
+	- `VITE_API_BASE_URL`（默认 `/api`）
+
+## CI/CD
+
+CI（`.github/workflows/ci.yml`）规则：
+
+- 触发条件：`push`、`pull_request`
+- 运行环境：`ubuntu-latest`
+- 校验顺序：
+	1. 安装前端依赖
+	2. `task fmt`
+	3. `task lint`
+	4. `task test`
+	5. `task vet`
+	6. `task build`
+
+Release（`.github/workflows/release.yml`）规则：
+
+- 触发条件：tag push（`v*`）
+- 发布前检查：前端格式检查、前端 lint、前端构建
+- 打包目标：
+	- `linux/amd64` (`tar.gz`)
+	- `windows/amd64` (`zip`)
+	- `darwin/amd64` (`tar.gz`)
+	- `darwin/arm64` (`tar.gz`)
+- 归档内容：
+	- 后端可执行文件
+	- 前端 `dist`
+	- `Readme.md`
+
+### 命名规范
+
+- 正式版本标签：`vX.Y.Z`
+- 预发布标签：`vX.Y.Z-alpha.N` / `vX.Y.Z-beta.N` / `vX.Y.Z-rc.N`
+- 不符合上述规则的 tag 禁止进入发布流程
+
+### 必要检查
+
+- 合并到主线前必须通过：`fmt`、`lint`、`test`、`vet`、`build`
+- 发布前必须确保：
+	- 前端已完成一次独立构建
+	- Release 产物可在目标平台解压并运行

From cbcbc82deca30239ccb11f88b4183f5dd16a58db Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Mon, 30 Mar 2026 00:12:54 +0800
Subject: [PATCH 02/28] refactor(backend): enrich godoc and refactor notes

---
 backend/internal/api/handlers.go           | 17 +++++++++++++++++
 backend/internal/api/router.go             |  2 ++
 backend/internal/service/docker_service.go | 19 +++++++++++++++++++
 backend/internal/store/memory.go           | 14 +++++++++++++-
 4 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/backend/internal/api/handlers.go b/backend/internal/api/handlers.go
index 18f7c36..bd51cbf 100644
--- a/backend/internal/api/handlers.go
+++ b/backend/internal/api/handlers.go
@@ -14,24 +14,29 @@ type Handler struct {
 	svc *service.DockerService
 }
 
+// NewHandler creates a Handler with the provided Docker service.
 func NewHandler(svc *service.DockerService) *Handler {
 	return &Handler{svc: svc}
 }
 
+// createRequest defines the payload for creating an instance.
 type createRequest struct {
 	Name string `json:"name"`
 }
 
+// statusResponse defines the standard status response body.
 type statusResponse struct {
 	Status string `json:"status"`
 	Error  string `json:"error,omitempty"`
 }
 
+// createResponse defines the response body of a successful create operation.
 type createResponse struct {
 	Status      string `json:"status"`
 	ContainerID string `json:"container_id"`
 }
 
+// GetInstances handles GET /api/instances and returns all managed instances.
 func (h *Handler) GetInstances(w http.ResponseWriter, r *http.Request) {
 	instances, err := h.svc.ListInstances(r.Context())
 	if err != nil {
@@ -41,6 +46,7 @@ func (h *Handler) GetInstances(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, instances)
 }
 
+// CreateInstance handles POST /api/instances and creates a new managed instance.
 func (h *Handler) CreateInstance(w http.ResponseWriter, r *http.Request) {
 	var req createRequest
 	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
@@ -57,6 +63,7 @@ func (h *Handler) CreateInstance(w http.ResponseWriter, r *http.Request) {
 	id, err := h.svc.CreateInstance(r.Context(), req.Name)
 	if err != nil {
 		code := http.StatusInternalServerError
+		// NOTE: Keep domain error to HTTP status mapping consistent across handlers.
 		if err == store.ErrNameExists {
 			code = http.StatusConflict
 		}
@@ -67,6 +74,9 @@ func (h *Handler) CreateInstance(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, createResponse{Status: "success", ContainerID: id})
 }
 
+// TODO(minedock): Extract a shared handler flow for start/stop/delete.
+// The three handlers repeat: parse container id, call service, and write status JSON.
+// StartInstance handles POST /api/instances/{id}/start and starts one instance.
 func (h *Handler) StartInstance(w http.ResponseWriter, r *http.Request) {
 	id, ok := pathContainerID(r)
 	if !ok {
@@ -82,6 +92,7 @@ func (h *Handler) StartInstance(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, statusResponse{Status: "success"})
 }
 
+// StopInstance handles POST /api/instances/{id}/stop and stops one instance.
 func (h *Handler) StopInstance(w http.ResponseWriter, r *http.Request) {
 	id, ok := pathContainerID(r)
 	if !ok {
@@ -97,6 +108,7 @@ func (h *Handler) StopInstance(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, statusResponse{Status: "success"})
 }
 
+// DeleteInstance handles DELETE /api/instances/{id} and removes one instance.
 func (h *Handler) DeleteInstance(w http.ResponseWriter, r *http.Request) {
 	id, ok := pathContainerID(r)
 	if !ok {
@@ -106,6 +118,7 @@ func (h *Handler) DeleteInstance(w http.ResponseWriter, r *http.Request) {
 
 	if err := h.svc.DeleteInstance(r.Context(), id); err != nil {
 		code := http.StatusInternalServerError
+		// NOTE: Keep domain error to HTTP status mapping consistent across handlers.
 		if err == service.ErrInstanceRunning {
 			code = http.StatusConflict
 		}
@@ -116,6 +129,7 @@ func (h *Handler) DeleteInstance(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, statusResponse{Status: "success"})
 }
 
+// pathContainerID parses and validates the container id from URL path params.
 func pathContainerID(r *http.Request) (string, bool) {
 	id := strings.TrimSpace(r.PathValue("id"))
 	if id == "" || strings.Contains(id, "/") {
@@ -124,7 +138,10 @@ func pathContainerID(r *http.Request) (string, bool) {
 	return id, true
 }
 
+// writeJSON writes a JSON response with the provided status code.
 func writeJSON(w http.ResponseWriter, code int, v any) {
+	// NOTE: Encoding errors are currently ignored because status may already be written.
+	// TODO(minedock): Add centralized encoding-error logging for better observability.
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(code)
 	_ = json.NewEncoder(w).Encode(v)
diff --git a/backend/internal/api/router.go b/backend/internal/api/router.go
index e63422e..423deff 100644
--- a/backend/internal/api/router.go
+++ b/backend/internal/api/router.go
@@ -2,6 +2,7 @@ package api
 
 import "net/http"
 
+// NewRouter registers API endpoints and wraps them with HTTP middleware.
 func NewRouter(h *Handler) http.Handler {
 	mux := http.NewServeMux()
 
@@ -14,6 +15,7 @@ func NewRouter(h *Handler) http.Handler {
 	return withCORS(mux)
 }
 
+// withCORS adds permissive CORS headers and handles OPTIONS preflight requests.
 func withCORS(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Access-Control-Allow-Origin", "*")
diff --git a/backend/internal/service/docker_service.go b/backend/internal/service/docker_service.go
index 3b16939..a6f19b3 100644
--- a/backend/internal/service/docker_service.go
+++ b/backend/internal/service/docker_service.go
@@ -16,6 +16,7 @@ import (
 	"minedock/backend/internal/store"
 )
 
+// ErrInstanceRunning indicates the instance is running and must be stopped before delete.
 var ErrInstanceRunning = errors.New("instance is running, stop it before delete")
 
 const (
@@ -32,6 +33,7 @@ type DockerService struct {
 	image string
 }
 
+// NewDockerService creates a DockerService with its dependencies and runtime image.
 func NewDockerService(cli *client.Client, sqliteStore *store.SQLiteStore, imageName string) *DockerService {
 	if strings.TrimSpace(imageName) == "" {
 		imageName = defaultImage
@@ -39,6 +41,8 @@ func NewDockerService(cli *client.Client, sqliteStore *store.SQLiteStore, imageN
 	return &DockerService{cli: cli, store: sqliteStore, image: imageName}
 }
 
+// CreateInstance creates a managed container and persists its metadata.
+// TODO(minedock): Make create and save behavior atomic across Docker and SQLite.
 func (s *DockerService) CreateInstance(ctx context.Context, name string) (string, error) {
 	if err := s.ensureImage(ctx, s.image); err != nil {
 		return "", err
@@ -58,6 +62,7 @@ func (s *DockerService) CreateInstance(ctx context.Context, name string) (string
 
 	inst := model.Instance{ContainerID: resp.ID, Name: name, Status: "Stopped"}
 	if err := s.store.Save(ctx, inst); err != nil {
+		// NOTE: Best-effort cleanup uses a detached context if request context is canceled.
 		_ = s.cli.ContainerRemove(context.Background(), resp.ID, container.RemoveOptions{Force: true})
 		return "", err
 	}
@@ -65,6 +70,7 @@ func (s *DockerService) CreateInstance(ctx context.Context, name string) (string
 	return resp.ID, nil
 }
 
+// StartInstance starts a managed container and updates persisted state.
 func (s *DockerService) StartInstance(ctx context.Context, containerID string) error {
 	if err := s.cli.ContainerStart(ctx, containerID, container.StartOptions{}); err != nil {
 		return fmt.Errorf("start container: %w", err)
@@ -81,6 +87,7 @@ func (s *DockerService) StartInstance(ctx context.Context, containerID string) e
 	return nil
 }
 
+// StopInstance stops a managed container and updates persisted state.
 func (s *DockerService) StopInstance(ctx context.Context, containerID string) error {
 	timeout := 10
 	if err := s.cli.ContainerStop(ctx, containerID, container.StopOptions{Timeout: &timeout}); err != nil {
@@ -98,6 +105,9 @@ func (s *DockerService) StopInstance(ctx context.Context, containerID string) er
 	return nil
 }
 
+// ListInstances lists managed containers and synchronizes snapshot state into the store.
+// TODO(minedock): Replace per-item Save with a batched or transactional sync path.
+// TODO(minedock): Guard concurrent snapshot writes to avoid last-write-wins races.
 func (s *DockerService) ListInstances(ctx context.Context) ([]model.Instance, error) {
 	args := filters.NewArgs()
 	args.Add("label", managedLabelKey+"="+managedLabelValue)
@@ -109,6 +119,7 @@ func (s *DockerService) ListInstances(ctx context.Context) ([]model.Instance, er
 
 	instances := make([]model.Instance, 0, len(containers))
 	for _, c := range containers {
+		// NOTE: Name fallback order is label value first, then Docker container name.
 		name := c.Labels[nameLabelKey]
 		if strings.TrimSpace(name) == "" && len(c.Names) > 0 {
 			name = strings.TrimPrefix(c.Names[0], "/")
@@ -122,6 +133,8 @@ func (s *DockerService) ListInstances(ctx context.Context) ([]model.Instance, er
 			Name:        name,
 			Status:      status,
 		}
+		// NOTE: Save is currently best-effort to keep list responses available.
+		// TODO(minedock): Report sync failures without breaking the listing path.
 		_ = s.store.Save(ctx, inst)
 		instances = append(instances, inst)
 	}
@@ -129,6 +142,7 @@ func (s *DockerService) ListInstances(ctx context.Context) ([]model.Instance, er
 	return instances, nil
 }
 
+// DeleteInstance removes a stopped managed container and its persisted metadata.
 func (s *DockerService) DeleteInstance(ctx context.Context, containerID string) error {
 	inspect, err := s.cli.ContainerInspect(ctx, containerID)
 	if err != nil {
@@ -148,12 +162,15 @@ func (s *DockerService) DeleteInstance(ctx context.Context, containerID string)
 	return nil
 }
 
+// readInstance resolves instance metadata from store and reconciles runtime state.
+// TODO(minedock): Split this function into store read and Docker reconcile helpers.
 func (s *DockerService) readInstance(ctx context.Context, containerID string, fallbackStatus string) (model.Instance, error) {
 	inst, ok, err := s.store.Get(ctx, containerID)
 	if err != nil {
 		return model.Instance{}, err
 	}
 	if ok {
+		// NOTE: Store hit still applies caller-provided fallback status.
 		inst.Status = fallbackStatus
 		return inst, nil
 	}
@@ -173,6 +190,7 @@ func (s *DockerService) readInstance(ctx context.Context, containerID string, fa
 
 	status := fallbackStatus
 	if inspect.State != nil {
+		// NOTE: Docker runtime state overrides fallback when inspect data is present.
 		if inspect.State.Running {
 			status = "Running"
 		} else {
@@ -183,6 +201,7 @@ func (s *DockerService) readInstance(ctx context.Context, containerID string, fa
 	return model.Instance{ContainerID: containerID, Name: name, Status: status}, nil
 }
 
+// ensureImage ensures imageName exists locally and pulls it when missing.
 func (s *DockerService) ensureImage(ctx context.Context, imageName string) error {
 	list, err := s.cli.ImageList(ctx, image.ListOptions{})
 	if err != nil {
diff --git a/backend/internal/store/memory.go b/backend/internal/store/memory.go
index af0e566..d30b0fa 100644
--- a/backend/internal/store/memory.go
+++ b/backend/internal/store/memory.go
@@ -14,6 +14,7 @@ import (
 	_ "modernc.org/sqlite"
 )
 
+// ErrNameExists indicates that an instance name is already in use.
 var ErrNameExists = errors.New("instance name already exists")
 
 // SQLiteStore persists instance state in a local SQLite database.
@@ -21,6 +22,7 @@ type SQLiteStore struct {
 	db *sql.DB
 }
 
+// NewSQLiteStore opens SQLite at dbPath and initializes required schema.
 func NewSQLiteStore(dbPath string) (*SQLiteStore, error) {
 	cleanPath := strings.TrimSpace(dbPath)
 	if cleanPath == "" {
@@ -36,7 +38,8 @@ func NewSQLiteStore(dbPath string) (*SQLiteStore, error) {
 		return nil, fmt.Errorf("open sqlite db: %w", err)
 	}
 
-	// SQLite works best with a single writer connection in this MVP.
+	// NOTE: SQLite works best with a single writer connection in this MVP.
+	// TODO(minedock): Revisit connection strategy when write throughput requirements grow.
 	db.SetMaxOpenConns(1)
 
 	if err := db.Ping(); err != nil {
@@ -53,6 +56,7 @@ func NewSQLiteStore(dbPath string) (*SQLiteStore, error) {
 	return s, nil
 }
 
+// Close releases the underlying SQLite database connection.
 func (s *SQLiteStore) Close() error {
 	if s == nil || s.db == nil {
 		return nil
@@ -60,6 +64,7 @@ func (s *SQLiteStore) Close() error {
 	return s.db.Close()
 }
 
+// InitSchema creates storage tables when they do not exist.
 func (s *SQLiteStore) InitSchema(ctx context.Context) error {
 	const schema = `
 CREATE TABLE IF NOT EXISTS instances (
@@ -76,6 +81,7 @@ CREATE TABLE IF NOT EXISTS instances (
 	return nil
 }
 
+// Save upserts one instance row by container id.
 func (s *SQLiteStore) Save(ctx context.Context, instance model.Instance) error {
 	const upsert = `
 INSERT INTO instances(container_id, name, status)
@@ -97,6 +103,7 @@ DO UPDATE SET
 	return nil
 }
 
+// Delete removes one instance row by container id.
 func (s *SQLiteStore) Delete(ctx context.Context, containerID string) error {
 	if _, err := s.db.ExecContext(ctx, "DELETE FROM instances WHERE container_id = ?", containerID); err != nil {
 		return fmt.Errorf("delete instance: %w", err)
@@ -104,6 +111,7 @@ func (s *SQLiteStore) Delete(ctx context.Context, containerID string) error {
 	return nil
 }
 
+// Get returns one instance row by container id.
 func (s *SQLiteStore) Get(ctx context.Context, containerID string) (model.Instance, bool, error) {
 	const q = `
 SELECT container_id, name, status
@@ -122,6 +130,7 @@ WHERE container_id = ?;
 	return inst, true, nil
 }
 
+// List returns all instance rows ordered by creation time descending.
 func (s *SQLiteStore) List(ctx context.Context) ([]model.Instance, error) {
 	const q = `
 SELECT container_id, name, status
@@ -151,6 +160,9 @@ ORDER BY created_at DESC;
 	return out, nil
 }
 
+// isUniqueNameErr reports whether err is a unique constraint violation for instances.name.
+// NOTE: This currently relies on matching SQLite error text.
+// TODO(minedock): Replace text matching with SQLite error-code based detection.
 func isUniqueNameErr(err error) bool {
 	if err == nil {
 		return false

From 38e52fe1fb2258bc945e867f2e65db1899bb0320 Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Mon, 30 Mar 2026 00:13:49 +0800
Subject: [PATCH 03/28] chore(tooling): add lint and todo index generator

---
 Taskfile.yml              |  12 ++
 backend/.golangci.yml     |  17 +++
 docs/exec-plans/README.md |   7 +-
 docs/exec-plans/TODO.md   |  19 ++++
 docs/standards/backend.md |   3 +-
 scripts/todo-gen/main.go  | 229 ++++++++++++++++++++++++++++++++++++++
 6 files changed, 285 insertions(+), 2 deletions(-)
 create mode 100644 backend/.golangci.yml
 create mode 100644 docs/exec-plans/TODO.md
 create mode 100644 scripts/todo-gen/main.go

diff --git a/Taskfile.yml b/Taskfile.yml
index fdc0a24..e831b39 100644
--- a/Taskfile.yml
+++ b/Taskfile.yml
@@ -27,6 +27,12 @@ tasks:
     cmds:
       - go vet ./...
 
+  backend:lint:
+    desc: Run backend golangci-lint checks
+    dir: backend
+    cmds:
+      - go run github.com/golangci/golangci-lint/cmd/golangci-lint@latest run --config .golangci.yml ./...
+
   backend:test:
     desc: Run backend tests
     dir: backend
@@ -70,6 +76,11 @@ tasks:
     cmds:
       - npm run format:check
 
+  docs:todo:
+    desc: Generate docs/exec-plans/TODO.md from TODO comments
+    cmds:
+      - go run ./scripts/todo-gen/main.go -root .. -out ../docs/exec-plans/TODO.md
+
   dev:
     desc: Run backend and frontend dev servers in parallel
     deps:
@@ -96,6 +107,7 @@ tasks:
   lint:
     desc: Run global lint checks
     deps:
+      - backend:lint
       - frontend:lint
 
   vet:
diff --git a/backend/.golangci.yml b/backend/.golangci.yml
new file mode 100644
index 0000000..5bb27df
--- /dev/null
+++ b/backend/.golangci.yml
@@ -0,0 +1,17 @@
+run:
+  timeout: 5m
+  tests: true
+  modules-download-mode: readonly
+
+linters:
+  disable-all: true
+  enable:
+    - govet
+    - staticcheck
+    - ineffassign
+    - unused
+    - gosimple
+
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0
diff --git a/docs/exec-plans/README.md b/docs/exec-plans/README.md
index ea64905..41f6c88 100644
--- a/docs/exec-plans/README.md
+++ b/docs/exec-plans/README.md
@@ -64,4 +64,9 @@
 
 - 计划中的功能点已实现并通过对应检查。
 - 涉及接口变更时，`docs/api/contracts.md` 已同步更新。
-- 涉及行为变更时，设计文档与规范文档已同步更新。
\ No newline at end of file
+- 涉及行为变更时，设计文档与规范文档已同步更新。
+
+## TODO 索引生成
+
+- 运行 `task docs:todo` 可从仓库注释中的 `TODO(username): 描述` 自动生成 `docs/exec-plans/TODO.md`。
+- 生成文件用于集中追踪技术债与改进事项，建议在提交前执行一次。
\ No newline at end of file
diff --git a/docs/exec-plans/TODO.md b/docs/exec-plans/TODO.md
new file mode 100644
index 0000000..d5a2191
--- /dev/null
+++ b/docs/exec-plans/TODO.md
@@ -0,0 +1,19 @@
+# TODO Index
+
+Generated at: 2026-03-30T00:04:01+08:00
+Source pattern: TODO(username): description
+Repository root: C:/Users/guzem/Desktop/Core/毕设/MineDock
+
+## Summary
+- Total TODO items: 9
+
+## Items
+- [ ] minedock: Extract a shared handler flow for start/stop/delete. (backend/internal/api/handlers.go:77)
+- [ ] minedock: Add centralized encoding-error logging for better observability. (backend/internal/api/handlers.go:144)
+- [ ] minedock: Make create and save behavior atomic across Docker and SQLite. (backend/internal/service/docker_service.go:45)
+- [ ] minedock: Replace per-item Save with a batched or transactional sync path. (backend/internal/service/docker_service.go:109)
+- [ ] minedock: Guard concurrent snapshot writes to avoid last-write-wins races. (backend/internal/service/docker_service.go:110)
+- [ ] minedock: Report sync failures without breaking the listing path. (backend/internal/service/docker_service.go:137)
+- [ ] minedock: Split this function into store read and Docker reconcile helpers. (backend/internal/service/docker_service.go:166)
+- [ ] minedock: Revisit connection strategy when write throughput requirements grow. (backend/internal/store/memory.go:42)
+- [ ] minedock: Replace text matching with SQLite error-code based detection. (backend/internal/store/memory.go:165)
diff --git a/docs/standards/backend.md b/docs/standards/backend.md
index f02849a..5828865 100644
--- a/docs/standards/backend.md
+++ b/docs/standards/backend.md
@@ -68,5 +68,6 @@
 ### 测试
 
 - 后端测试入口：`task backend:test`（`go test ./...`）。
+- Lint 检查：`task backend:lint`（`golangci-lint run ./...`）。
 - 静态检查：`task backend:vet`（`go vet ./...`）。
-- 提交前最低门禁建议：`task fmt && task vet && task test && task build`。
+- 提交前最低门禁建议：`task fmt && task lint && task vet && task test && task build`。
diff --git a/scripts/todo-gen/main.go b/scripts/todo-gen/main.go
new file mode 100644
index 0000000..1100419
--- /dev/null
+++ b/scripts/todo-gen/main.go
@@ -0,0 +1,229 @@
+package main
+
+import (
+	"bufio"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+	"time"
+)
+
+var todoPattern = regexp.MustCompile(`TODO\(([^)]+)\):\s*(.+)$`)
+
+type todoItem struct {
+	Owner string
+	Text  string
+	Path  string
+	Line  int
+}
+
+func main() {
+	rootFlag := flag.String("root", "..", "repository root path")
+	outFlag := flag.String("out", "../docs/exec-plans/TODO.md", "output markdown file path")
+	flag.Parse()
+
+	root, err := filepath.Abs(*rootFlag)
+	if err != nil {
+		fatalf("resolve root path: %v", err)
+	}
+	outPath, err := filepath.Abs(*outFlag)
+	if err != nil {
+		fatalf("resolve output path: %v", err)
+	}
+
+	items, err := collectTODOItems(root)
+	if err != nil {
+		fatalf("collect TODO comments: %v", err)
+	}
+
+	if err := writeMarkdown(root, outPath, items); err != nil {
+		fatalf("write output file: %v", err)
+	}
+
+	fmt.Printf("Generated %s with %d TODO items\n", outPath, len(items))
+}
+
+func collectTODOItems(root string) ([]todoItem, error) {
+	items := make([]todoItem, 0)
+
+	err := filepath.WalkDir(root, func(path string, d os.DirEntry, walkErr error) error {
+		if walkErr != nil {
+			return walkErr
+		}
+
+		if d.IsDir() {
+			if shouldSkipDir(path, d.Name()) {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+
+		if shouldSkipFile(path) {
+			return nil
+		}
+
+		file, err := os.Open(path)
+		if err != nil {
+			return err
+		}
+		defer file.Close()
+
+		scanner := bufio.NewScanner(file)
+		buf := make([]byte, 0, 64*1024)
+		scanner.Buffer(buf, 1024*1024)
+
+		lineNo := 0
+		for scanner.Scan() {
+			lineNo++
+			line := scanner.Text()
+			idx := strings.Index(line, "TODO(")
+			if idx < 0 || !isLikelyCommentLine(line, idx) {
+				continue
+			}
+
+			matches := todoPattern.FindStringSubmatch(line[idx:])
+			if len(matches) != 3 {
+				continue
+			}
+
+			owner := strings.TrimSpace(matches[1])
+			text := strings.TrimSpace(matches[2])
+			text = strings.TrimSuffix(text, "*/")
+			text = strings.TrimSpace(text)
+			if owner == "" || text == "" {
+				continue
+			}
+
+			relPath, err := filepath.Rel(root, path)
+			if err != nil {
+				return err
+			}
+			relPath = filepath.ToSlash(relPath)
+
+			items = append(items, todoItem{
+				Owner: owner,
+				Text:  text,
+				Path:  relPath,
+				Line:  lineNo,
+			})
+		}
+
+		if err := scanner.Err(); err != nil {
+			return err
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	sort.Slice(items, func(i, j int) bool {
+		if items[i].Path == items[j].Path {
+			return items[i].Line < items[j].Line
+		}
+		return items[i].Path < items[j].Path
+	})
+
+	return items, nil
+}
+
+func shouldSkipDir(path, name string) bool {
+	switch name {
+	case ".git", "node_modules", "vendor", ".idea", ".vscode", "bin", "dist":
+		return true
+	}
+
+	normalized := filepath.ToSlash(path)
+	if strings.Contains(normalized, "/backend/bin") || strings.Contains(normalized, "/frontend/dist") {
+		return true
+	}
+
+	return false
+}
+
+func shouldSkipFile(path string) bool {
+	base := filepath.Base(path)
+	if strings.HasPrefix(base, ".") && base != ".golangci.yml" {
+		return true
+	}
+	if strings.HasSuffix(base, ".md") {
+		return true
+	}
+	if strings.HasSuffix(base, ".png") || strings.HasSuffix(base, ".jpg") || strings.HasSuffix(base, ".jpeg") || strings.HasSuffix(base, ".gif") || strings.HasSuffix(base, ".webp") || strings.HasSuffix(base, ".svg") {
+		return true
+	}
+	if strings.HasSuffix(base, ".db") || strings.HasSuffix(base, ".exe") || strings.HasSuffix(base, ".dll") || strings.HasSuffix(base, ".so") {
+		return true
+	}
+	return false
+}
+
+func isLikelyCommentLine(line string, todoIndex int) bool {
+	prefix := line[:todoIndex]
+	trimmed := strings.TrimSpace(prefix)
+	if strings.Contains(prefix, "//") || strings.Contains(prefix, "#") || strings.Contains(prefix, "/*") || strings.Contains(prefix, "<!--") {
+		return true
+	}
+	return strings.HasPrefix(trimmed, "*")
+}
+
+func writeMarkdown(root, outPath string, items []todoItem) error {
+	if err := os.MkdirAll(filepath.Dir(outPath), 0o755); err != nil {
+		return err
+	}
+
+	f, err := os.Create(outPath)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+
+	now := time.Now().Format(time.RFC3339)
+	if _, err := fmt.Fprintln(f, "# TODO Index"); err != nil {
+		return err
+	}
+	if _, err := fmt.Fprintf(f, "\nGenerated at: %s\n", now); err != nil {
+		return err
+	}
+	if _, err := fmt.Fprintln(f, "Source pattern: TODO(username): description"); err != nil {
+		return err
+	}
+	if _, err := fmt.Fprintf(f, "Repository root: %s\n", filepath.ToSlash(root)); err != nil {
+		return err
+	}
+
+	if _, err := fmt.Fprintln(f, "\n## Summary"); err != nil {
+		return err
+	}
+	if _, err := fmt.Fprintf(f, "- Total TODO items: %d\n", len(items)); err != nil {
+		return err
+	}
+
+	if _, err := fmt.Fprintln(f, "\n## Items"); err != nil {
+		return err
+	}
+
+	if len(items) == 0 {
+		if _, err := fmt.Fprintln(f, "- No TODO items found."); err != nil {
+			return err
+		}
+		return nil
+	}
+
+	for _, item := range items {
+		if _, err := fmt.Fprintf(f, "- [ ] %s: %s (%s:%d)\n", item.Owner, item.Text, item.Path, item.Line); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func fatalf(format string, args ...any) {
+	_, _ = fmt.Fprintf(os.Stderr, format+"\n", args...)
+	os.Exit(1)
+}

From 6ae21d6cae67e394be63bfd0a7ba4b1e4fcfeb24 Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Mon, 30 Mar 2026 00:14:43 +0800
Subject: [PATCH 04/28] docs(readme): simplify runtime command snippet

---
 Readme.md | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/Readme.md b/Readme.md
index 66779bd..2478707 100644
--- a/Readme.md
+++ b/Readme.md
@@ -3,16 +3,8 @@
 轻量级游戏服务器容器化管理平台。
 
 ## 运行指南
-
-### Task 命令
 ```bash
 task dev               # 一键启动前后端开发服务
-task fmt               # 执行全局格式检查（当前依赖 backend:fmt）
-task vet               # 执行全局静态检查（当前依赖 backend:vet）
-task test              # 执行全局测试（当前依赖 backend:test）
-task build             # 统一编译前后端
-task clean             # 清理构建产物
-task frontend:install  # 安装前端依赖
 ```
 
 ## 待办清单

From 6762a50b5b8c6c4f29dac999cc8b62f0903b0532 Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Mon, 30 Mar 2026 00:27:41 +0800
Subject: [PATCH 05/28] =?UTF-8?q?docs:=20=E4=BF=AE=E6=94=B9=E5=90=8E?=
 =?UTF-8?q?=E7=AB=AF=E8=A7=84=E8=8C=83=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/standards/backend.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/docs/standards/backend.md b/docs/standards/backend.md
index 5828865..1345653 100644
--- a/docs/standards/backend.md
+++ b/docs/standards/backend.md
@@ -40,9 +40,11 @@
 
 ### 依赖注入
 
-- 接口原则：Service 层定义的依赖接口应尽量“小”。
-- 构造函数：组件通过 `New...` 函数初始化，并在此处注入依赖（如 `func NewService(s Store) *Service`）。
-- 解耦：Handler 仅负责解析请求、调用 Service、返回 Response。禁止在 Handler 直接操作 Docker SDK 或 SQL。
+- 构造函数：组件通过 `New...` 函数初始化，并在此处注入依赖。
+- 接口定义：**消费方**在自己的包中定义所需接口（Go 惯例），
+  接口应尽量小，仅包含实际调用的方法。
+- 解耦底线：Handler 禁止直接操作 Docker SDK 或 SQL，
+  仅通过 Service 层暴露的接口交互。
 
 ## 4. 数据与存储
 

From 1257686c8b6f533e240f425795b3558afacf5564 Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Mon, 30 Mar 2026 00:33:07 +0800
Subject: [PATCH 06/28] =?UTF-8?q?refactor(backend):=20=E8=A7=A3=E8=80=A6?=
 =?UTF-8?q?=E6=9C=8D=E5=8A=A1=E4=B8=8E=E5=AD=98=E5=82=A8=E4=BE=9D=E8=B5=96?=
 =?UTF-8?q?=E5=B9=B6=E7=BB=9F=E4=B8=80=E9=A2=86=E5=9F=9F=E9=94=99=E8=AF=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 backend/internal/api/handlers.go              | 24 ++++++++++++-----
 backend/internal/model/errors.go              |  9 +++++++
 backend/internal/service/docker_service.go    | 26 ++++++++++---------
 .../internal/store/{memory.go => sqlite.go}   |  7 +++--
 4 files changed, 43 insertions(+), 23 deletions(-)
 create mode 100644 backend/internal/model/errors.go
 rename backend/internal/store/{memory.go => sqlite.go} (96%)

diff --git a/backend/internal/api/handlers.go b/backend/internal/api/handlers.go
index bd51cbf..4576cdf 100644
--- a/backend/internal/api/handlers.go
+++ b/backend/internal/api/handlers.go
@@ -1,21 +1,31 @@
 package api
 
 import (
+	"context"
 	"encoding/json"
+	"errors"
 	"net/http"
 	"strings"
 
-	"minedock/backend/internal/service"
-	"minedock/backend/internal/store"
+	"minedock/backend/internal/model"
 )
 
+// InstanceService defines the business operations called by API handlers.
+type InstanceService interface {
+	ListInstances(ctx context.Context) ([]model.Instance, error)
+	CreateInstance(ctx context.Context, name string) (string, error)
+	StartInstance(ctx context.Context, containerID string) error
+	StopInstance(ctx context.Context, containerID string) error
+	DeleteInstance(ctx context.Context, containerID string) error
+}
+
 // Handler exposes HTTP handlers.
 type Handler struct {
-	svc *service.DockerService
+	svc InstanceService
 }
 
-// NewHandler creates a Handler with the provided Docker service.
-func NewHandler(svc *service.DockerService) *Handler {
+// NewHandler creates a Handler with the provided instance service.
+func NewHandler(svc InstanceService) *Handler {
 	return &Handler{svc: svc}
 }
 
@@ -64,7 +74,7 @@ func (h *Handler) CreateInstance(w http.ResponseWriter, r *http.Request) {
 	if err != nil {
 		code := http.StatusInternalServerError
 		// NOTE: Keep domain error to HTTP status mapping consistent across handlers.
-		if err == store.ErrNameExists {
+		if errors.Is(err, model.ErrNameExists) {
 			code = http.StatusConflict
 		}
 		writeJSON(w, code, statusResponse{Status: "error", Error: err.Error()})
@@ -119,7 +129,7 @@ func (h *Handler) DeleteInstance(w http.ResponseWriter, r *http.Request) {
 	if err := h.svc.DeleteInstance(r.Context(), id); err != nil {
 		code := http.StatusInternalServerError
 		// NOTE: Keep domain error to HTTP status mapping consistent across handlers.
-		if err == service.ErrInstanceRunning {
+		if errors.Is(err, model.ErrInstanceRunning) {
 			code = http.StatusConflict
 		}
 		writeJSON(w, code, statusResponse{Status: "error", Error: err.Error()})
diff --git a/backend/internal/model/errors.go b/backend/internal/model/errors.go
new file mode 100644
index 0000000..f2f91b1
--- /dev/null
+++ b/backend/internal/model/errors.go
@@ -0,0 +1,9 @@
+package model
+
+import "errors"
+
+// ErrNameExists indicates that an instance name is already in use.
+var ErrNameExists = errors.New("instance name already exists")
+
+// ErrInstanceRunning indicates the instance is running and must be stopped before delete.
+var ErrInstanceRunning = errors.New("instance is running, stop it before delete")
diff --git a/backend/internal/service/docker_service.go b/backend/internal/service/docker_service.go
index a6f19b3..b91118d 100644
--- a/backend/internal/service/docker_service.go
+++ b/backend/internal/service/docker_service.go
@@ -2,7 +2,6 @@ package service
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"io"
 	"strings"
@@ -13,12 +12,8 @@ import (
 	"github.com/docker/docker/client"
 
 	"minedock/backend/internal/model"
-	"minedock/backend/internal/store"
 )
 
-// ErrInstanceRunning indicates the instance is running and must be stopped before delete.
-var ErrInstanceRunning = errors.New("instance is running, stop it before delete")
-
 const (
 	managedLabelKey   = "minedock.managed"
 	managedLabelValue = "true"
@@ -26,19 +21,26 @@ const (
 	defaultImage      = "alpine:latest"
 )
 
+// InstanceStore defines the persistence operations needed by DockerService.
+type InstanceStore interface {
+	Save(ctx context.Context, inst model.Instance) error
+	Get(ctx context.Context, containerID string) (model.Instance, bool, error)
+	Delete(ctx context.Context, containerID string) error
+}
+
 // DockerService contains business logic for container management.
 type DockerService struct {
 	cli   *client.Client
-	store *store.SQLiteStore
+	store InstanceStore
 	image string
 }
 
 // NewDockerService creates a DockerService with its dependencies and runtime image.
-func NewDockerService(cli *client.Client, sqliteStore *store.SQLiteStore, imageName string) *DockerService {
+func NewDockerService(cli *client.Client, s InstanceStore, imageName string) *DockerService {
 	if strings.TrimSpace(imageName) == "" {
 		imageName = defaultImage
 	}
-	return &DockerService{cli: cli, store: sqliteStore, image: imageName}
+	return &DockerService{cli: cli, store: s, image: imageName}
 }
 
 // CreateInstance creates a managed container and persists its metadata.
@@ -81,7 +83,7 @@ func (s *DockerService) StartInstance(ctx context.Context, containerID string) e
 		return err
 	}
 	if err := s.store.Save(ctx, inst); err != nil {
-		return err
+		return fmt.Errorf("save instance state: %w", err)
 	}
 
 	return nil
@@ -99,7 +101,7 @@ func (s *DockerService) StopInstance(ctx context.Context, containerID string) er
 		return err
 	}
 	if err := s.store.Save(ctx, inst); err != nil {
-		return err
+		return fmt.Errorf("save instance state: %w", err)
 	}
 
 	return nil
@@ -150,14 +152,14 @@ func (s *DockerService) DeleteInstance(ctx context.Context, containerID string)
 	}
 
 	if inspect.State != nil && inspect.State.Running {
-		return ErrInstanceRunning
+		return model.ErrInstanceRunning
 	}
 
 	if err := s.cli.ContainerRemove(ctx, containerID, container.RemoveOptions{Force: false}); err != nil {
 		return fmt.Errorf("remove container: %w", err)
 	}
 	if err := s.store.Delete(ctx, containerID); err != nil {
-		return err
+		return fmt.Errorf("delete instance record: %w", err)
 	}
 	return nil
 }
diff --git a/backend/internal/store/memory.go b/backend/internal/store/sqlite.go
similarity index 96%
rename from backend/internal/store/memory.go
rename to backend/internal/store/sqlite.go
index d30b0fa..9c6a129 100644
--- a/backend/internal/store/memory.go
+++ b/backend/internal/store/sqlite.go
@@ -11,11 +11,10 @@ import (
 
 	"minedock/backend/internal/model"
 
-	_ "modernc.org/sqlite"
+	_ "modernc.org/sqlite" // SQLite driver registration
 )
 
-// ErrNameExists indicates that an instance name is already in use.
-var ErrNameExists = errors.New("instance name already exists")
+
 
 // SQLiteStore persists instance state in a local SQLite database.
 type SQLiteStore struct {
@@ -95,7 +94,7 @@ DO UPDATE SET
 	_, err := s.db.ExecContext(ctx, upsert, instance.ContainerID, instance.Name, instance.Status)
 	if err != nil {
 		if isUniqueNameErr(err) {
-			return ErrNameExists
+			return model.ErrNameExists
 		}
 		return fmt.Errorf("save instance: %w", err)
 	}

From 282a5c9fbd9145adf1ac1d14923a73a819f13d4b Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Mon, 30 Mar 2026 00:37:30 +0800
Subject: [PATCH 07/28] =?UTF-8?q?test(backend):=20=E8=A1=A5=E9=BD=90=20API?=
 =?UTF-8?q?=20Handler=20=E4=B8=8E=20SQLite=20Store=20=E5=8D=95=E5=85=83?=
 =?UTF-8?q?=E6=B5=8B=E8=AF=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 backend/internal/api/handlers_test.go | 258 ++++++++++++++++++++++++++
 backend/internal/store/sqlite_test.go | 168 +++++++++++++++++
 2 files changed, 426 insertions(+)
 create mode 100644 backend/internal/api/handlers_test.go
 create mode 100644 backend/internal/store/sqlite_test.go

diff --git a/backend/internal/api/handlers_test.go b/backend/internal/api/handlers_test.go
new file mode 100644
index 0000000..b1e3a09
--- /dev/null
+++ b/backend/internal/api/handlers_test.go
@@ -0,0 +1,258 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"minedock/backend/internal/model"
+)
+
+// mockService implements InstanceService for handler tests.
+type mockService struct {
+	listFn   func(ctx context.Context) ([]model.Instance, error)
+	createFn func(ctx context.Context, name string) (string, error)
+	startFn  func(ctx context.Context, id string) error
+	stopFn   func(ctx context.Context, id string) error
+	deleteFn func(ctx context.Context, id string) error
+}
+
+func (m *mockService) ListInstances(ctx context.Context) ([]model.Instance, error) {
+	return m.listFn(ctx)
+}
+func (m *mockService) CreateInstance(ctx context.Context, name string) (string, error) {
+	return m.createFn(ctx, name)
+}
+func (m *mockService) StartInstance(ctx context.Context, id string) error {
+	return m.startFn(ctx, id)
+}
+func (m *mockService) StopInstance(ctx context.Context, id string) error {
+	return m.stopFn(ctx, id)
+}
+func (m *mockService) DeleteInstance(ctx context.Context, id string) error {
+	return m.deleteFn(ctx, id)
+}
+
+func newTestRouter(m *mockService) http.Handler {
+	h := NewHandler(m)
+	return NewRouter(h)
+}
+
+// --- GET /api/instances ---
+
+func TestGetInstances_Success(t *testing.T) {
+	router := newTestRouter(&mockService{
+		listFn: func(_ context.Context) ([]model.Instance, error) {
+			return []model.Instance{
+				{ContainerID: "c1", Name: "server-1", Status: "Running"},
+			}, nil
+		},
+	})
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodGet, "/api/instances", nil)
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d", w.Code)
+	}
+
+	var got []model.Instance
+	if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if len(got) != 1 || got[0].ContainerID != "c1" {
+		t.Fatalf("unexpected response: %+v", got)
+	}
+}
+
+func TestGetInstances_Error(t *testing.T) {
+	router := newTestRouter(&mockService{
+		listFn: func(_ context.Context) ([]model.Instance, error) {
+			return nil, errTest
+		},
+	})
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodGet, "/api/instances", nil)
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusInternalServerError {
+		t.Fatalf("expected 500, got %d", w.Code)
+	}
+}
+
+// --- POST /api/instances ---
+
+func TestCreateInstance_Success(t *testing.T) {
+	router := newTestRouter(&mockService{
+		createFn: func(_ context.Context, name string) (string, error) {
+			if name != "test-server" {
+				t.Fatalf("unexpected name: %s", name)
+			}
+			return "abc123", nil
+		},
+	})
+
+	body := `{"name":"test-server"}`
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(body))
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+	}
+
+	var resp createResponse
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if resp.Status != "success" || resp.ContainerID != "abc123" {
+		t.Fatalf("unexpected response: %+v", resp)
+	}
+}
+
+func TestCreateInstance_InvalidJSON(t *testing.T) {
+	router := newTestRouter(&mockService{})
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader("{bad"))
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", w.Code)
+	}
+}
+
+func TestCreateInstance_EmptyName(t *testing.T) {
+	router := newTestRouter(&mockService{})
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(`{"name":"  "}`))
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", w.Code)
+	}
+}
+
+func TestCreateInstance_NameConflict(t *testing.T) {
+	router := newTestRouter(&mockService{
+		createFn: func(_ context.Context, _ string) (string, error) {
+			return "", model.ErrNameExists
+		},
+	})
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(`{"name":"dup"}`))
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusConflict {
+		t.Fatalf("expected 409, got %d", w.Code)
+	}
+}
+
+// --- POST /api/instances/{id}/start ---
+
+func TestStartInstance_Success(t *testing.T) {
+	router := newTestRouter(&mockService{
+		startFn: func(_ context.Context, id string) error {
+			if id != "abc123" {
+				t.Fatalf("unexpected id: %s", id)
+			}
+			return nil
+		},
+	})
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodPost, "/api/instances/abc123/start", nil)
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+	}
+}
+
+func TestStartInstance_Error(t *testing.T) {
+	router := newTestRouter(&mockService{
+		startFn: func(_ context.Context, _ string) error {
+			return errTest
+		},
+	})
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodPost, "/api/instances/abc123/start", nil)
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusInternalServerError {
+		t.Fatalf("expected 500, got %d", w.Code)
+	}
+}
+
+// --- POST /api/instances/{id}/stop ---
+
+func TestStopInstance_Success(t *testing.T) {
+	router := newTestRouter(&mockService{
+		stopFn: func(_ context.Context, id string) error {
+			if id != "abc123" {
+				t.Fatalf("unexpected id: %s", id)
+			}
+			return nil
+		},
+	})
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodPost, "/api/instances/abc123/stop", nil)
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+	}
+}
+
+// --- DELETE /api/instances/{id} ---
+
+func TestDeleteInstance_Success(t *testing.T) {
+	router := newTestRouter(&mockService{
+		deleteFn: func(_ context.Context, id string) error {
+			if id != "abc123" {
+				t.Fatalf("unexpected id: %s", id)
+			}
+			return nil
+		},
+	})
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodDelete, "/api/instances/abc123", nil)
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+	}
+}
+
+func TestDeleteInstance_Running(t *testing.T) {
+	router := newTestRouter(&mockService{
+		deleteFn: func(_ context.Context, _ string) error {
+			return model.ErrInstanceRunning
+		},
+	})
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodDelete, "/api/instances/abc123", nil)
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusConflict {
+		t.Fatalf("expected 409, got %d", w.Code)
+	}
+}
+
+// errTest is a generic error used in test stubs.
+var errTest = errorString("test error")
+
+type errorString string
+
+func (e errorString) Error() string { return string(e) }
diff --git a/backend/internal/store/sqlite_test.go b/backend/internal/store/sqlite_test.go
new file mode 100644
index 0000000..6773da7
--- /dev/null
+++ b/backend/internal/store/sqlite_test.go
@@ -0,0 +1,168 @@
+package store
+
+import (
+	"context"
+	"errors"
+	"path/filepath"
+	"testing"
+
+	"minedock/backend/internal/model"
+)
+
+func newTestStore(t *testing.T) *SQLiteStore {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "test.db")
+	s, err := NewSQLiteStore(path)
+	if err != nil {
+		t.Fatalf("new test store: %v", err)
+	}
+	t.Cleanup(func() { s.Close() })
+	return s
+}
+
+func TestNewSQLiteStore_EmptyPath(t *testing.T) {
+	_, err := NewSQLiteStore("")
+	if err == nil {
+		t.Fatal("expected error for empty path")
+	}
+}
+
+func TestSaveAndGet(t *testing.T) {
+	s := newTestStore(t)
+	ctx := context.Background()
+
+	inst := model.Instance{ContainerID: "c1", Name: "server-1", Status: "Stopped"}
+	if err := s.Save(ctx, inst); err != nil {
+		t.Fatalf("save: %v", err)
+	}
+
+	got, ok, err := s.Get(ctx, "c1")
+	if err != nil {
+		t.Fatalf("get: %v", err)
+	}
+	if !ok {
+		t.Fatal("expected instance to exist")
+	}
+	if got.ContainerID != "c1" || got.Name != "server-1" || got.Status != "Stopped" {
+		t.Fatalf("unexpected instance: %+v", got)
+	}
+}
+
+func TestSave_Upsert(t *testing.T) {
+	s := newTestStore(t)
+	ctx := context.Background()
+
+	inst := model.Instance{ContainerID: "c1", Name: "server-1", Status: "Stopped"}
+	if err := s.Save(ctx, inst); err != nil {
+		t.Fatalf("first save: %v", err)
+	}
+
+	inst.Status = "Running"
+	if err := s.Save(ctx, inst); err != nil {
+		t.Fatalf("upsert save: %v", err)
+	}
+
+	got, _, err := s.Get(ctx, "c1")
+	if err != nil {
+		t.Fatalf("get: %v", err)
+	}
+	if got.Status != "Running" {
+		t.Fatalf("expected Running, got %s", got.Status)
+	}
+}
+
+func TestSave_DuplicateName(t *testing.T) {
+	s := newTestStore(t)
+	ctx := context.Background()
+
+	if err := s.Save(ctx, model.Instance{ContainerID: "c1", Name: "dup", Status: "Stopped"}); err != nil {
+		t.Fatalf("first save: %v", err)
+	}
+
+	err := s.Save(ctx, model.Instance{ContainerID: "c2", Name: "dup", Status: "Stopped"})
+	if !errors.Is(err, model.ErrNameExists) {
+		t.Fatalf("expected ErrNameExists, got %v", err)
+	}
+}
+
+func TestGet_NotFound(t *testing.T) {
+	s := newTestStore(t)
+	ctx := context.Background()
+
+	_, ok, err := s.Get(ctx, "nonexistent")
+	if err != nil {
+		t.Fatalf("get: %v", err)
+	}
+	if ok {
+		t.Fatal("expected not found")
+	}
+}
+
+func TestDelete(t *testing.T) {
+	s := newTestStore(t)
+	ctx := context.Background()
+
+	inst := model.Instance{ContainerID: "c1", Name: "server-1", Status: "Stopped"}
+	if err := s.Save(ctx, inst); err != nil {
+		t.Fatalf("save: %v", err)
+	}
+
+	if err := s.Delete(ctx, "c1"); err != nil {
+		t.Fatalf("delete: %v", err)
+	}
+
+	_, ok, err := s.Get(ctx, "c1")
+	if err != nil {
+		t.Fatalf("get after delete: %v", err)
+	}
+	if ok {
+		t.Fatal("expected instance to be deleted")
+	}
+}
+
+func TestDelete_NonExistent(t *testing.T) {
+	s := newTestStore(t)
+	ctx := context.Background()
+
+	// Deleting a non-existent row should not error.
+	if err := s.Delete(ctx, "nonexistent"); err != nil {
+		t.Fatalf("delete non-existent: %v", err)
+	}
+}
+
+func TestList(t *testing.T) {
+	s := newTestStore(t)
+	ctx := context.Background()
+
+	instances := []model.Instance{
+		{ContainerID: "c1", Name: "alpha", Status: "Running"},
+		{ContainerID: "c2", Name: "beta", Status: "Stopped"},
+		{ContainerID: "c3", Name: "gamma", Status: "Running"},
+	}
+	for _, inst := range instances {
+		if err := s.Save(ctx, inst); err != nil {
+			t.Fatalf("save %s: %v", inst.Name, err)
+		}
+	}
+
+	got, err := s.List(ctx)
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if len(got) != 3 {
+		t.Fatalf("expected 3 instances, got %d", len(got))
+	}
+}
+
+func TestList_Empty(t *testing.T) {
+	s := newTestStore(t)
+	ctx := context.Background()
+
+	got, err := s.List(ctx)
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if len(got) != 0 {
+		t.Fatalf("expected 0 instances, got %d", len(got))
+	}
+}

From 5ff8703198f8d9f23ee48955b5325ebb1a79af98 Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Mon, 30 Mar 2026 00:45:01 +0800
Subject: [PATCH 08/28] =?UTF-8?q?refactor(backend):=20=E6=B3=A8=E9=87=8A?=
 =?UTF-8?q?=E4=B8=AD=E6=96=87=E5=8C=96=E5=B9=B6=E7=BB=9F=E4=B8=80=20TODO?=
 =?UTF-8?q?=20=E4=B9=A6=E5=86=99?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 backend/internal/api/handlers.go           | 38 ++++++++++----------
 backend/internal/api/handlers_test.go      | 14 ++++----
 backend/internal/api/router.go             |  4 +--
 backend/internal/model/errors.go           |  4 +--
 backend/internal/service/docker_service.go | 40 +++++++++++-----------
 backend/internal/store/sqlite.go           | 30 ++++++++--------
 backend/internal/store/sqlite_test.go      |  2 +-
 7 files changed, 65 insertions(+), 67 deletions(-)

diff --git a/backend/internal/api/handlers.go b/backend/internal/api/handlers.go
index 4576cdf..8502506 100644
--- a/backend/internal/api/handlers.go
+++ b/backend/internal/api/handlers.go
@@ -10,7 +10,7 @@ import (
 	"minedock/backend/internal/model"
 )
 
-// InstanceService defines the business operations called by API handlers.
+// InstanceService 定义 API Handler 依赖的业务操作。
 type InstanceService interface {
 	ListInstances(ctx context.Context) ([]model.Instance, error)
 	CreateInstance(ctx context.Context, name string) (string, error)
@@ -19,34 +19,34 @@ type InstanceService interface {
 	DeleteInstance(ctx context.Context, containerID string) error
 }
 
-// Handler exposes HTTP handlers.
+// Handler 暴露 HTTP 处理器。
 type Handler struct {
 	svc InstanceService
 }
 
-// NewHandler creates a Handler with the provided instance service.
+// NewHandler 使用给定的实例服务创建 Handler。
 func NewHandler(svc InstanceService) *Handler {
 	return &Handler{svc: svc}
 }
 
-// createRequest defines the payload for creating an instance.
+// createRequest 定义创建实例请求体。
 type createRequest struct {
 	Name string `json:"name"`
 }
 
-// statusResponse defines the standard status response body.
+// statusResponse 定义通用状态响应体。
 type statusResponse struct {
 	Status string `json:"status"`
 	Error  string `json:"error,omitempty"`
 }
 
-// createResponse defines the response body of a successful create operation.
+// createResponse 定义创建成功时的响应体。
 type createResponse struct {
 	Status      string `json:"status"`
 	ContainerID string `json:"container_id"`
 }
 
-// GetInstances handles GET /api/instances and returns all managed instances.
+// GetInstances 处理 GET /api/instances 并返回所有托管实例。
 func (h *Handler) GetInstances(w http.ResponseWriter, r *http.Request) {
 	instances, err := h.svc.ListInstances(r.Context())
 	if err != nil {
@@ -56,7 +56,7 @@ func (h *Handler) GetInstances(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, instances)
 }
 
-// CreateInstance handles POST /api/instances and creates a new managed instance.
+// CreateInstance 处理 POST /api/instances 并创建新实例。
 func (h *Handler) CreateInstance(w http.ResponseWriter, r *http.Request) {
 	var req createRequest
 	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
@@ -73,7 +73,7 @@ func (h *Handler) CreateInstance(w http.ResponseWriter, r *http.Request) {
 	id, err := h.svc.CreateInstance(r.Context(), req.Name)
 	if err != nil {
 		code := http.StatusInternalServerError
-		// NOTE: Keep domain error to HTTP status mapping consistent across handlers.
+		// 说明：保持领域错误到 HTTP 状态码的映射在各 Handler 中一致。
 		if errors.Is(err, model.ErrNameExists) {
 			code = http.StatusConflict
 		}
@@ -84,9 +84,9 @@ func (h *Handler) CreateInstance(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, createResponse{Status: "success", ContainerID: id})
 }
 
-// TODO(minedock): Extract a shared handler flow for start/stop/delete.
-// The three handlers repeat: parse container id, call service, and write status JSON.
-// StartInstance handles POST /api/instances/{id}/start and starts one instance.
+// TODO: 抽取 start/stop/delete 的公共处理流程。
+// 这三个处理器都重复了：解析容器 ID、调用 Service、写回状态 JSON。
+// StartInstance 处理 POST /api/instances/{id}/start 并启动实例。
 func (h *Handler) StartInstance(w http.ResponseWriter, r *http.Request) {
 	id, ok := pathContainerID(r)
 	if !ok {
@@ -102,7 +102,7 @@ func (h *Handler) StartInstance(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, statusResponse{Status: "success"})
 }
 
-// StopInstance handles POST /api/instances/{id}/stop and stops one instance.
+// StopInstance 处理 POST /api/instances/{id}/stop 并停止实例。
 func (h *Handler) StopInstance(w http.ResponseWriter, r *http.Request) {
 	id, ok := pathContainerID(r)
 	if !ok {
@@ -118,7 +118,7 @@ func (h *Handler) StopInstance(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, statusResponse{Status: "success"})
 }
 
-// DeleteInstance handles DELETE /api/instances/{id} and removes one instance.
+// DeleteInstance 处理 DELETE /api/instances/{id} 并删除实例。
 func (h *Handler) DeleteInstance(w http.ResponseWriter, r *http.Request) {
 	id, ok := pathContainerID(r)
 	if !ok {
@@ -128,7 +128,7 @@ func (h *Handler) DeleteInstance(w http.ResponseWriter, r *http.Request) {
 
 	if err := h.svc.DeleteInstance(r.Context(), id); err != nil {
 		code := http.StatusInternalServerError
-		// NOTE: Keep domain error to HTTP status mapping consistent across handlers.
+		// 说明：保持领域错误到 HTTP 状态码的映射在各 Handler 中一致。
 		if errors.Is(err, model.ErrInstanceRunning) {
 			code = http.StatusConflict
 		}
@@ -139,7 +139,7 @@ func (h *Handler) DeleteInstance(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, statusResponse{Status: "success"})
 }
 
-// pathContainerID parses and validates the container id from URL path params.
+// pathContainerID 解析并校验 URL 路径中的容器 ID。
 func pathContainerID(r *http.Request) (string, bool) {
 	id := strings.TrimSpace(r.PathValue("id"))
 	if id == "" || strings.Contains(id, "/") {
@@ -148,10 +148,10 @@ func pathContainerID(r *http.Request) (string, bool) {
 	return id, true
 }
 
-// writeJSON writes a JSON response with the provided status code.
+// writeJSON 按指定状态码写入 JSON 响应。
 func writeJSON(w http.ResponseWriter, code int, v any) {
-	// NOTE: Encoding errors are currently ignored because status may already be written.
-	// TODO(minedock): Add centralized encoding-error logging for better observability.
+	// 说明：当前会忽略编码错误，因为状态码可能已写入。
+	// TODO: 增加统一的编码错误日志，提升可观测性。
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(code)
 	_ = json.NewEncoder(w).Encode(v)
diff --git a/backend/internal/api/handlers_test.go b/backend/internal/api/handlers_test.go
index b1e3a09..86799d6 100644
--- a/backend/internal/api/handlers_test.go
+++ b/backend/internal/api/handlers_test.go
@@ -11,7 +11,7 @@ import (
 	"minedock/backend/internal/model"
 )
 
-// mockService implements InstanceService for handler tests.
+// mockService 为 Handler 测试实现 InstanceService。
 type mockService struct {
 	listFn   func(ctx context.Context) ([]model.Instance, error)
 	createFn func(ctx context.Context, name string) (string, error)
@@ -41,7 +41,7 @@ func newTestRouter(m *mockService) http.Handler {
 	return NewRouter(h)
 }
 
-// --- GET /api/instances ---
+// --- GET /api/instances 场景 ---
 
 func TestGetInstances_Success(t *testing.T) {
 	router := newTestRouter(&mockService{
@@ -85,7 +85,7 @@ func TestGetInstances_Error(t *testing.T) {
 	}
 }
 
-// --- POST /api/instances ---
+// --- POST /api/instances 场景 ---
 
 func TestCreateInstance_Success(t *testing.T) {
 	router := newTestRouter(&mockService{
@@ -155,7 +155,7 @@ func TestCreateInstance_NameConflict(t *testing.T) {
 	}
 }
 
-// --- POST /api/instances/{id}/start ---
+// --- POST /api/instances/{id}/start 场景 ---
 
 func TestStartInstance_Success(t *testing.T) {
 	router := newTestRouter(&mockService{
@@ -192,7 +192,7 @@ func TestStartInstance_Error(t *testing.T) {
 	}
 }
 
-// --- POST /api/instances/{id}/stop ---
+// --- POST /api/instances/{id}/stop 场景 ---
 
 func TestStopInstance_Success(t *testing.T) {
 	router := newTestRouter(&mockService{
@@ -213,7 +213,7 @@ func TestStopInstance_Success(t *testing.T) {
 	}
 }
 
-// --- DELETE /api/instances/{id} ---
+// --- DELETE /api/instances/{id} 场景 ---
 
 func TestDeleteInstance_Success(t *testing.T) {
 	router := newTestRouter(&mockService{
@@ -250,7 +250,7 @@ func TestDeleteInstance_Running(t *testing.T) {
 	}
 }
 
-// errTest is a generic error used in test stubs.
+// errTest 是测试桩使用的通用错误。
 var errTest = errorString("test error")
 
 type errorString string
diff --git a/backend/internal/api/router.go b/backend/internal/api/router.go
index 423deff..62ae44a 100644
--- a/backend/internal/api/router.go
+++ b/backend/internal/api/router.go
@@ -2,7 +2,7 @@ package api
 
 import "net/http"
 
-// NewRouter registers API endpoints and wraps them with HTTP middleware.
+// NewRouter 注册 API 路由并包装中间件。
 func NewRouter(h *Handler) http.Handler {
 	mux := http.NewServeMux()
 
@@ -15,7 +15,7 @@ func NewRouter(h *Handler) http.Handler {
 	return withCORS(mux)
 }
 
-// withCORS adds permissive CORS headers and handles OPTIONS preflight requests.
+// withCORS 添加宽松的 CORS 响应头并处理 OPTIONS 预检请求。
 func withCORS(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Access-Control-Allow-Origin", "*")
diff --git a/backend/internal/model/errors.go b/backend/internal/model/errors.go
index f2f91b1..3385945 100644
--- a/backend/internal/model/errors.go
+++ b/backend/internal/model/errors.go
@@ -2,8 +2,8 @@ package model
 
 import "errors"
 
-// ErrNameExists indicates that an instance name is already in use.
+// ErrNameExists 表示实例名称已被占用。
 var ErrNameExists = errors.New("instance name already exists")
 
-// ErrInstanceRunning indicates the instance is running and must be stopped before delete.
+// ErrInstanceRunning 表示实例正在运行，删除前必须先停止。
 var ErrInstanceRunning = errors.New("instance is running, stop it before delete")
diff --git a/backend/internal/service/docker_service.go b/backend/internal/service/docker_service.go
index b91118d..fc2c45d 100644
--- a/backend/internal/service/docker_service.go
+++ b/backend/internal/service/docker_service.go
@@ -21,21 +21,21 @@ const (
 	defaultImage      = "alpine:latest"
 )
 
-// InstanceStore defines the persistence operations needed by DockerService.
+// InstanceStore 定义 DockerService 依赖的持久化操作。
 type InstanceStore interface {
 	Save(ctx context.Context, inst model.Instance) error
 	Get(ctx context.Context, containerID string) (model.Instance, bool, error)
 	Delete(ctx context.Context, containerID string) error
 }
 
-// DockerService contains business logic for container management.
+// DockerService 封装容器管理相关业务逻辑。
 type DockerService struct {
 	cli   *client.Client
 	store InstanceStore
 	image string
 }
 
-// NewDockerService creates a DockerService with its dependencies and runtime image.
+// NewDockerService 使用依赖项和运行镜像创建 DockerService。
 func NewDockerService(cli *client.Client, s InstanceStore, imageName string) *DockerService {
 	if strings.TrimSpace(imageName) == "" {
 		imageName = defaultImage
@@ -43,8 +43,8 @@ func NewDockerService(cli *client.Client, s InstanceStore, imageName string) *Do
 	return &DockerService{cli: cli, store: s, image: imageName}
 }
 
-// CreateInstance creates a managed container and persists its metadata.
-// TODO(minedock): Make create and save behavior atomic across Docker and SQLite.
+// CreateInstance 创建托管容器并持久化实例元数据。
+// TODO: 让 Docker 创建与 SQLite 保存具备原子性。
 func (s *DockerService) CreateInstance(ctx context.Context, name string) (string, error) {
 	if err := s.ensureImage(ctx, s.image); err != nil {
 		return "", err
@@ -64,7 +64,7 @@ func (s *DockerService) CreateInstance(ctx context.Context, name string) (string
 
 	inst := model.Instance{ContainerID: resp.ID, Name: name, Status: "Stopped"}
 	if err := s.store.Save(ctx, inst); err != nil {
-		// NOTE: Best-effort cleanup uses a detached context if request context is canceled.
+		// 说明：请求上下文取消时，清理逻辑会使用独立上下文做尽力回收。
 		_ = s.cli.ContainerRemove(context.Background(), resp.ID, container.RemoveOptions{Force: true})
 		return "", err
 	}
@@ -72,7 +72,7 @@ func (s *DockerService) CreateInstance(ctx context.Context, name string) (string
 	return resp.ID, nil
 }
 
-// StartInstance starts a managed container and updates persisted state.
+// StartInstance 启动托管容器并更新持久化状态。
 func (s *DockerService) StartInstance(ctx context.Context, containerID string) error {
 	if err := s.cli.ContainerStart(ctx, containerID, container.StartOptions{}); err != nil {
 		return fmt.Errorf("start container: %w", err)
@@ -89,7 +89,7 @@ func (s *DockerService) StartInstance(ctx context.Context, containerID string) e
 	return nil
 }
 
-// StopInstance stops a managed container and updates persisted state.
+// StopInstance 停止托管容器并更新持久化状态。
 func (s *DockerService) StopInstance(ctx context.Context, containerID string) error {
 	timeout := 10
 	if err := s.cli.ContainerStop(ctx, containerID, container.StopOptions{Timeout: &timeout}); err != nil {
@@ -107,9 +107,9 @@ func (s *DockerService) StopInstance(ctx context.Context, containerID string) er
 	return nil
 }
 
-// ListInstances lists managed containers and synchronizes snapshot state into the store.
-// TODO(minedock): Replace per-item Save with a batched or transactional sync path.
-// TODO(minedock): Guard concurrent snapshot writes to avoid last-write-wins races.
+// ListInstances 列出托管容器并将快照状态同步到存储层。
+// TODO: 将逐条 Save 改为批量或事务化同步路径。
+// TODO: 增加并发写保护，避免最后写入覆盖前写入。
 func (s *DockerService) ListInstances(ctx context.Context) ([]model.Instance, error) {
 	args := filters.NewArgs()
 	args.Add("label", managedLabelKey+"="+managedLabelValue)
@@ -121,7 +121,7 @@ func (s *DockerService) ListInstances(ctx context.Context) ([]model.Instance, er
 
 	instances := make([]model.Instance, 0, len(containers))
 	for _, c := range containers {
-		// NOTE: Name fallback order is label value first, then Docker container name.
+		// 说明：名称回退顺序是先 label，再 Docker 容器名。
 		name := c.Labels[nameLabelKey]
 		if strings.TrimSpace(name) == "" && len(c.Names) > 0 {
 			name = strings.TrimPrefix(c.Names[0], "/")
@@ -135,8 +135,8 @@ func (s *DockerService) ListInstances(ctx context.Context) ([]model.Instance, er
 			Name:        name,
 			Status:      status,
 		}
-		// NOTE: Save is currently best-effort to keep list responses available.
-		// TODO(minedock): Report sync failures without breaking the listing path.
+		// 说明：当前 Save 为尽力而为，避免影响列表返回。
+		// TODO: 在不影响列表返回的前提下上报同步失败。
 		_ = s.store.Save(ctx, inst)
 		instances = append(instances, inst)
 	}
@@ -144,7 +144,7 @@ func (s *DockerService) ListInstances(ctx context.Context) ([]model.Instance, er
 	return instances, nil
 }
 
-// DeleteInstance removes a stopped managed container and its persisted metadata.
+// DeleteInstance 删除已停止的托管容器及其持久化记录。
 func (s *DockerService) DeleteInstance(ctx context.Context, containerID string) error {
 	inspect, err := s.cli.ContainerInspect(ctx, containerID)
 	if err != nil {
@@ -164,15 +164,15 @@ func (s *DockerService) DeleteInstance(ctx context.Context, containerID string)
 	return nil
 }
 
-// readInstance resolves instance metadata from store and reconciles runtime state.
-// TODO(minedock): Split this function into store read and Docker reconcile helpers.
+// readInstance 从存储层读取实例信息并与运行态进行对账。
+// TODO: 将该函数拆分为存储读取与 Docker 对账两个辅助函数。
 func (s *DockerService) readInstance(ctx context.Context, containerID string, fallbackStatus string) (model.Instance, error) {
 	inst, ok, err := s.store.Get(ctx, containerID)
 	if err != nil {
 		return model.Instance{}, err
 	}
 	if ok {
-		// NOTE: Store hit still applies caller-provided fallback status.
+		// 说明：命中存储后仍会应用调用方传入的兜底状态。
 		inst.Status = fallbackStatus
 		return inst, nil
 	}
@@ -192,7 +192,7 @@ func (s *DockerService) readInstance(ctx context.Context, containerID string, fa
 
 	status := fallbackStatus
 	if inspect.State != nil {
-		// NOTE: Docker runtime state overrides fallback when inspect data is present.
+		// 说明：当 inspect 有运行态数据时，以 Docker 真实状态覆盖兜底状态。
 		if inspect.State.Running {
 			status = "Running"
 		} else {
@@ -203,7 +203,7 @@ func (s *DockerService) readInstance(ctx context.Context, containerID string, fa
 	return model.Instance{ContainerID: containerID, Name: name, Status: status}, nil
 }
 
-// ensureImage ensures imageName exists locally and pulls it when missing.
+// ensureImage 确保本地存在目标镜像，缺失时自动拉取。
 func (s *DockerService) ensureImage(ctx context.Context, imageName string) error {
 	list, err := s.cli.ImageList(ctx, image.ListOptions{})
 	if err != nil {
diff --git a/backend/internal/store/sqlite.go b/backend/internal/store/sqlite.go
index 9c6a129..db09f23 100644
--- a/backend/internal/store/sqlite.go
+++ b/backend/internal/store/sqlite.go
@@ -11,17 +11,15 @@ import (
 
 	"minedock/backend/internal/model"
 
-	_ "modernc.org/sqlite" // SQLite driver registration
+	_ "modernc.org/sqlite" // 注册 SQLite 驱动
 )
 
-
-
-// SQLiteStore persists instance state in a local SQLite database.
+// SQLiteStore 在本地 SQLite 数据库中持久化实例状态。
 type SQLiteStore struct {
 	db *sql.DB
 }
 
-// NewSQLiteStore opens SQLite at dbPath and initializes required schema.
+// NewSQLiteStore 打开 dbPath 指向的 SQLite 并初始化所需表结构。
 func NewSQLiteStore(dbPath string) (*SQLiteStore, error) {
 	cleanPath := strings.TrimSpace(dbPath)
 	if cleanPath == "" {
@@ -37,8 +35,8 @@ func NewSQLiteStore(dbPath string) (*SQLiteStore, error) {
 		return nil, fmt.Errorf("open sqlite db: %w", err)
 	}
 
-	// NOTE: SQLite works best with a single writer connection in this MVP.
-	// TODO(minedock): Revisit connection strategy when write throughput requirements grow.
+	// 说明：当前 MVP 阶段使用单写连接更贴合 SQLite 的并发模型。
+	// TODO: 当写入吞吐成为瓶颈时，重新评估连接池策略。
 	db.SetMaxOpenConns(1)
 
 	if err := db.Ping(); err != nil {
@@ -55,7 +53,7 @@ func NewSQLiteStore(dbPath string) (*SQLiteStore, error) {
 	return s, nil
 }
 
-// Close releases the underlying SQLite database connection.
+// Close 释放底层 SQLite 数据库连接。
 func (s *SQLiteStore) Close() error {
 	if s == nil || s.db == nil {
 		return nil
@@ -63,7 +61,7 @@ func (s *SQLiteStore) Close() error {
 	return s.db.Close()
 }
 
-// InitSchema creates storage tables when they do not exist.
+// InitSchema 在表不存在时创建存储表结构。
 func (s *SQLiteStore) InitSchema(ctx context.Context) error {
 	const schema = `
 CREATE TABLE IF NOT EXISTS instances (
@@ -80,7 +78,7 @@ CREATE TABLE IF NOT EXISTS instances (
 	return nil
 }
 
-// Save upserts one instance row by container id.
+// Save 按容器 ID 执行实例记录的 upsert。
 func (s *SQLiteStore) Save(ctx context.Context, instance model.Instance) error {
 	const upsert = `
 INSERT INTO instances(container_id, name, status)
@@ -102,7 +100,7 @@ DO UPDATE SET
 	return nil
 }
 
-// Delete removes one instance row by container id.
+// Delete 按容器 ID 删除一条实例记录。
 func (s *SQLiteStore) Delete(ctx context.Context, containerID string) error {
 	if _, err := s.db.ExecContext(ctx, "DELETE FROM instances WHERE container_id = ?", containerID); err != nil {
 		return fmt.Errorf("delete instance: %w", err)
@@ -110,7 +108,7 @@ func (s *SQLiteStore) Delete(ctx context.Context, containerID string) error {
 	return nil
 }
 
-// Get returns one instance row by container id.
+// Get 按容器 ID 获取一条实例记录。
 func (s *SQLiteStore) Get(ctx context.Context, containerID string) (model.Instance, bool, error) {
 	const q = `
 SELECT container_id, name, status
@@ -129,7 +127,7 @@ WHERE container_id = ?;
 	return inst, true, nil
 }
 
-// List returns all instance rows ordered by creation time descending.
+// List 返回所有实例记录，并按创建时间倒序排列。
 func (s *SQLiteStore) List(ctx context.Context) ([]model.Instance, error) {
 	const q = `
 SELECT container_id, name, status
@@ -159,9 +157,9 @@ ORDER BY created_at DESC;
 	return out, nil
 }
 
-// isUniqueNameErr reports whether err is a unique constraint violation for instances.name.
-// NOTE: This currently relies on matching SQLite error text.
-// TODO(minedock): Replace text matching with SQLite error-code based detection.
+// isUniqueNameErr 判断是否为 instances.name 的唯一约束冲突。
+// 说明：当前实现依赖 SQLite 错误文本匹配。
+// TODO: 用 SQLite 错误码替代文本匹配判断。
 func isUniqueNameErr(err error) bool {
 	if err == nil {
 		return false
diff --git a/backend/internal/store/sqlite_test.go b/backend/internal/store/sqlite_test.go
index 6773da7..6826bf0 100644
--- a/backend/internal/store/sqlite_test.go
+++ b/backend/internal/store/sqlite_test.go
@@ -124,7 +124,7 @@ func TestDelete_NonExistent(t *testing.T) {
 	s := newTestStore(t)
 	ctx := context.Background()
 
-	// Deleting a non-existent row should not error.
+	// 删除不存在的记录不应返回错误。
 	if err := s.Delete(ctx, "nonexistent"); err != nil {
 		t.Fatalf("delete non-existent: %v", err)
 	}

From ee73d1bd0ffe48210485c7520ac1b1ea50023b5a Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Mon, 30 Mar 2026 00:45:22 +0800
Subject: [PATCH 09/28] =?UTF-8?q?chore(docs):=20=E5=90=8C=E6=AD=A5=20TODO?=
 =?UTF-8?q?=20=E8=A7=84=E8=8C=83=E4=B8=8E=E7=B4=A2=E5=BC=95=E7=94=9F?=
 =?UTF-8?q?=E6=88=90=E8=A7=84=E5=88=99?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/exec-plans/README.md |  2 +-
 docs/exec-plans/TODO.md   | 22 +++++++++++-----------
 docs/standards/backend.md |  2 +-
 scripts/todo-gen/main.go  | 14 ++++++++++----
 4 files changed, 23 insertions(+), 17 deletions(-)

diff --git a/docs/exec-plans/README.md b/docs/exec-plans/README.md
index 41f6c88..e5bb9bb 100644
--- a/docs/exec-plans/README.md
+++ b/docs/exec-plans/README.md
@@ -68,5 +68,5 @@
 
 ## TODO 索引生成
 
-- 运行 `task docs:todo` 可从仓库注释中的 `TODO(username): 描述` 自动生成 `docs/exec-plans/TODO.md`。
+- 运行 `task docs:todo` 可从仓库注释中的 `TODO: 描述` 自动生成 `docs/exec-plans/TODO.md`。
 - 生成文件用于集中追踪技术债与改进事项，建议在提交前执行一次。
\ No newline at end of file
diff --git a/docs/exec-plans/TODO.md b/docs/exec-plans/TODO.md
index d5a2191..ae1f07b 100644
--- a/docs/exec-plans/TODO.md
+++ b/docs/exec-plans/TODO.md
@@ -1,19 +1,19 @@
 # TODO Index
 
-Generated at: 2026-03-30T00:04:01+08:00
-Source pattern: TODO(username): description
+Generated at: 2026-03-30T00:42:39+08:00
+Source pattern: TODO: description
 Repository root: C:/Users/guzem/Desktop/Core/毕设/MineDock
 
 ## Summary
 - Total TODO items: 9
 
 ## Items
-- [ ] minedock: Extract a shared handler flow for start/stop/delete. (backend/internal/api/handlers.go:77)
-- [ ] minedock: Add centralized encoding-error logging for better observability. (backend/internal/api/handlers.go:144)
-- [ ] minedock: Make create and save behavior atomic across Docker and SQLite. (backend/internal/service/docker_service.go:45)
-- [ ] minedock: Replace per-item Save with a batched or transactional sync path. (backend/internal/service/docker_service.go:109)
-- [ ] minedock: Guard concurrent snapshot writes to avoid last-write-wins races. (backend/internal/service/docker_service.go:110)
-- [ ] minedock: Report sync failures without breaking the listing path. (backend/internal/service/docker_service.go:137)
-- [ ] minedock: Split this function into store read and Docker reconcile helpers. (backend/internal/service/docker_service.go:166)
-- [ ] minedock: Revisit connection strategy when write throughput requirements grow. (backend/internal/store/memory.go:42)
-- [ ] minedock: Replace text matching with SQLite error-code based detection. (backend/internal/store/memory.go:165)
+- [ ] 抽取 start/stop/delete 的公共处理流程。 (backend/internal/api/handlers.go:87)
+- [ ] 增加统一的编码错误日志，提升可观测性。 (backend/internal/api/handlers.go:154)
+- [ ] 让 Docker 创建与 SQLite 保存具备原子性。 (backend/internal/service/docker_service.go:47)
+- [ ] 将逐条 Save 改为批量或事务化同步路径。 (backend/internal/service/docker_service.go:111)
+- [ ] 增加并发写保护，避免最后写入覆盖前写入。 (backend/internal/service/docker_service.go:112)
+- [ ] 在不影响列表返回的前提下上报同步失败。 (backend/internal/service/docker_service.go:139)
+- [ ] 将该函数拆分为存储读取与 Docker 对账两个辅助函数。 (backend/internal/service/docker_service.go:168)
+- [ ] 当写入吞吐成为瓶颈时，重新评估连接池策略。 (backend/internal/store/sqlite.go:39)
+- [ ] 用 SQLite 错误码替代文本匹配判断。 (backend/internal/store/sqlite.go:162)
diff --git a/docs/standards/backend.md b/docs/standards/backend.md
index 1345653..0066290 100644
--- a/docs/standards/backend.md
+++ b/docs/standards/backend.md
@@ -17,7 +17,7 @@
 ### 注释(Go Doc)
 
 - 导出符号（大写开头）**必须**以符号名开头的完整句子注释。
-- TODO 规范：`// TODO(username): 描述内容`。
+- TODO 规范：`// TODO: 描述内容`。
 
 ## 2. 核心机制与控制流
 
diff --git a/scripts/todo-gen/main.go b/scripts/todo-gen/main.go
index 1100419..b68b6bf 100644
--- a/scripts/todo-gen/main.go
+++ b/scripts/todo-gen/main.go
@@ -12,7 +12,7 @@ import (
 	"time"
 )
 
-var todoPattern = regexp.MustCompile(`TODO\(([^)]+)\):\s*(.+)$`)
+var todoPattern = regexp.MustCompile(`TODO(?:\(([^)]+)\))?:\s*(.+)$`)
 
 type todoItem struct {
 	Owner string
@@ -80,7 +80,7 @@ func collectTODOItems(root string) ([]todoItem, error) {
 		for scanner.Scan() {
 			lineNo++
 			line := scanner.Text()
-			idx := strings.Index(line, "TODO(")
+			idx := strings.Index(line, "TODO")
 			if idx < 0 || !isLikelyCommentLine(line, idx) {
 				continue
 			}
@@ -94,7 +94,7 @@ func collectTODOItems(root string) ([]todoItem, error) {
 			text := strings.TrimSpace(matches[2])
 			text = strings.TrimSuffix(text, "*/")
 			text = strings.TrimSpace(text)
-			if owner == "" || text == "" {
+			if text == "" {
 				continue
 			}
 
@@ -189,7 +189,7 @@ func writeMarkdown(root, outPath string, items []todoItem) error {
 	if _, err := fmt.Fprintf(f, "\nGenerated at: %s\n", now); err != nil {
 		return err
 	}
-	if _, err := fmt.Fprintln(f, "Source pattern: TODO(username): description"); err != nil {
+	if _, err := fmt.Fprintln(f, "Source pattern: TODO: description"); err != nil {
 		return err
 	}
 	if _, err := fmt.Fprintf(f, "Repository root: %s\n", filepath.ToSlash(root)); err != nil {
@@ -215,6 +215,12 @@ func writeMarkdown(root, outPath string, items []todoItem) error {
 	}
 
 	for _, item := range items {
+		if item.Owner == "" {
+			if _, err := fmt.Fprintf(f, "- [ ] %s (%s:%d)\n", item.Text, item.Path, item.Line); err != nil {
+				return err
+			}
+			continue
+		}
 		if _, err := fmt.Fprintf(f, "- [ ] %s: %s (%s:%d)\n", item.Owner, item.Text, item.Path, item.Line); err != nil {
 			return err
 		}

From 779e3faedf0b6ead72b3a2596085f7cfdc77c342 Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Mon, 30 Mar 2026 01:02:10 +0800
Subject: [PATCH 10/28] =?UTF-8?q?refactor(backend):=20=E7=BB=9F=E4=B8=80?=
 =?UTF-8?q?=E5=A4=84=E7=90=86=E5=99=A8=E7=9A=84=E9=94=99=E8=AF=AF=E6=98=A0?=
 =?UTF-8?q?=E5=B0=84=EF=BC=8C=E5=B9=B6=E5=8C=85=E8=A3=85=E6=9C=8D=E5=8A=A1?=
 =?UTF-8?q?=E5=B1=82=E9=94=99=E8=AF=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 backend/internal/api/handlers.go           | 26 ++++++++++++----------
 backend/internal/service/docker_service.go |  4 ++--
 docs/standards/backend.md                  |  1 +
 3 files changed, 17 insertions(+), 14 deletions(-)

diff --git a/backend/internal/api/handlers.go b/backend/internal/api/handlers.go
index 8502506..a479ea5 100644
--- a/backend/internal/api/handlers.go
+++ b/backend/internal/api/handlers.go
@@ -72,12 +72,7 @@ func (h *Handler) CreateInstance(w http.ResponseWriter, r *http.Request) {
 
 	id, err := h.svc.CreateInstance(r.Context(), req.Name)
 	if err != nil {
-		code := http.StatusInternalServerError
-		// 说明：保持领域错误到 HTTP 状态码的映射在各 Handler 中一致。
-		if errors.Is(err, model.ErrNameExists) {
-			code = http.StatusConflict
-		}
-		writeJSON(w, code, statusResponse{Status: "error", Error: err.Error()})
+		writeJSON(w, mapErrorCode(err), statusResponse{Status: "error", Error: err.Error()})
 		return
 	}
 
@@ -127,12 +122,7 @@ func (h *Handler) DeleteInstance(w http.ResponseWriter, r *http.Request) {
 	}
 
 	if err := h.svc.DeleteInstance(r.Context(), id); err != nil {
-		code := http.StatusInternalServerError
-		// 说明：保持领域错误到 HTTP 状态码的映射在各 Handler 中一致。
-		if errors.Is(err, model.ErrInstanceRunning) {
-			code = http.StatusConflict
-		}
-		writeJSON(w, code, statusResponse{Status: "error", Error: err.Error()})
+		writeJSON(w, mapErrorCode(err), statusResponse{Status: "error", Error: err.Error()})
 		return
 	}
 
@@ -148,6 +138,18 @@ func pathContainerID(r *http.Request) (string, bool) {
 	return id, true
 }
 
+// mapErrorCode 将领域错误统一映射为 HTTP 状态码。
+func mapErrorCode(err error) int {
+	switch {
+	case errors.Is(err, model.ErrNameExists):
+		return http.StatusConflict
+	case errors.Is(err, model.ErrInstanceRunning):
+		return http.StatusConflict
+	default:
+		return http.StatusInternalServerError
+	}
+}
+
 // writeJSON 按指定状态码写入 JSON 响应。
 func writeJSON(w http.ResponseWriter, code int, v any) {
 	// 说明：当前会忽略编码错误，因为状态码可能已写入。
diff --git a/backend/internal/service/docker_service.go b/backend/internal/service/docker_service.go
index fc2c45d..56e10d0 100644
--- a/backend/internal/service/docker_service.go
+++ b/backend/internal/service/docker_service.go
@@ -66,7 +66,7 @@ func (s *DockerService) CreateInstance(ctx context.Context, name string) (string
 	if err := s.store.Save(ctx, inst); err != nil {
 		// 说明：请求上下文取消时，清理逻辑会使用独立上下文做尽力回收。
 		_ = s.cli.ContainerRemove(context.Background(), resp.ID, container.RemoveOptions{Force: true})
-		return "", err
+		return "", fmt.Errorf("save instance record: %w", err)
 	}
 
 	return resp.ID, nil
@@ -169,7 +169,7 @@ func (s *DockerService) DeleteInstance(ctx context.Context, containerID string)
 func (s *DockerService) readInstance(ctx context.Context, containerID string, fallbackStatus string) (model.Instance, error) {
 	inst, ok, err := s.store.Get(ctx, containerID)
 	if err != nil {
-		return model.Instance{}, err
+		return model.Instance{}, fmt.Errorf("read instance: %w", err)
 	}
 	if ok {
 		// 说明：命中存储后仍会应用调用方传入的兜底状态。
diff --git a/docs/standards/backend.md b/docs/standards/backend.md
index 0066290..fe9489c 100644
--- a/docs/standards/backend.md
+++ b/docs/standards/backend.md
@@ -35,6 +35,7 @@
 - 底层错误统一使用 `fmt.Errorf("...: %w", err)` 包装。
 - 对于可预见的业务逻辑错误，在包级别定义 `ErrNotFound` 等变量，便于 `errors.Is()` 判断。
 - 优先处理错误流，减少 `else` 嵌套。
+- Handler 层错误映射：业务错误到 HTTP 状态码的映射应集中管理（如统一查表函数），避免在各 Handler 中重复硬编码。
 
 ## 3. 架构与设计模式
 

From db549c282254852c0d31ae452d63800e6a27e858 Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Mon, 30 Mar 2026 14:01:17 +0800
Subject: [PATCH 11/28] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E8=AE=A1?=
 =?UTF-8?q?=E5=88=92=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/exec-plans/README.md | 93 ++++++++++++++++++++-------------------
 1 file changed, 48 insertions(+), 45 deletions(-)

diff --git a/docs/exec-plans/README.md b/docs/exec-plans/README.md
index e5bb9bb..cd902e2 100644
--- a/docs/exec-plans/README.md
+++ b/docs/exec-plans/README.md
@@ -1,17 +1,11 @@
 # 执行计划目录说明
 
-本目录用于存放可执行的研发计划文档（Execution Plan）。
-
-## 目标
-
-- 将需求拆分为可落地的阶段与任务。
-- 明确每一步的输入、输出、风险与验收标准。
-- 作为开发、联调、测试、验收的共享依据。
+本目录用于存放计划文档
+- `completed` 存放已经完成的计划
+- `active` 存放当前正在进行的计划
 
 ## 命名规范
 
-建议格式：
-
 `YYYYMMDD-主题关键字.md`
 
 示例：
@@ -19,52 +13,61 @@
 - `20260329-instance-restart.md`
 - `20260330-backup-snapshot.md`
 
-## 编写模板
+## 内容格式
+
+执行计划内容建议遵循以下标准结构模块：
+
+````markdown
+# [目标描述 / Goal Description]
+
+提供问题的简要描述，相关背景上下文，以及此更改要实现的目标。
+
+## 需要评审的内容 (User Review Required)
+
+记录任何需要用户审查或反馈的内容，例如破坏性更改或重大且重要的设计决策。可以使用 GitHub 提示块（如 `> [!IMPORTANT]` 或 `> [!WARNING]`）高亮强调。
+
+## 拟定更改 (Proposed Changes)
+
+按组件名称（如具体的 package、功能区或依赖层）将将要修改的文件分组归类，并按逻辑顺序（例如先依赖后实现）展开描述。建议使用水平分割线来区分不同组件。
+
+### [组件名称 / Component Name]
+
+简述该组件的变化，并按具体文件拆分说明。
+对于具体的变更文件，使用 `[NEW]` 和 `[DELETE]` 标签标明文件的新旧状态，例如：
 
-```md
-# <计划标题>
+#### [MODIFY] 修改的文件名.go (及文件相对路径)
+#### [NEW] 新增的文件名.go
+#### [DELETE] 删除的文件名.go
 
-## 1. 背景与目标
-- 背景：
-- 目标：
-- 不在本次范围：
+## 执行步骤 (Execution Steps)
 
-## 2. 需求拆解
-- 功能点 A：
-- 功能点 B：
+将完整的计划拆分为可执行的、细化的步骤列表，使用复选框来追踪进度状态：
+- `[ ]` 待办 (Uncompleted)
+- `[/]` 进行中 (In Progress)
+- `[x]` 已完成 (Completed)
 
-## 3. 设计与改动范围
-- 后端改动：
-- 前端改动：
-- 文档改动：
-- 数据结构/接口变更：
+推荐使用嵌套列表来拆分复杂的步骤，例如：
+- [ ] 核心模型层设计
+  - [ ] 定义 `User` 结构体
+  - [ ] 编写对应的单元测试
+- [ ] API 路由注册
+- [/] 当前正在开发的功能
+- [x] 已经处理完毕的事项
 
-## 4. 执行步骤
-1. 步骤一
-2. 步骤二
-3. 步骤三
+## 待确认的疑问 (Open Questions)
 
-## 5. 风险与回滚
-- 风险 1：
-- 风险 2：
-- 回滚方案：
+记录任何需要澄清的业务逻辑或者架构设计疑问，这些疑问通常会直接影响执行计划的方案。可以使用 GitHub 提示块强调。
 
-## 6. 验收标准
-- [ ] 验收项 1
-- [ ] 验收项 2
-- [ ] 验收项 3
+## 验证计划 (Verification Plan)
 
-## 7. 测试计划
-- 单元测试：
-- 集成测试：
-- 手工验证：
-```
+简述你将如何验证上述更改达到了预期效果。
 
-## 完成定义（DoD）
+### 自动化测试 (Automated Tests)
+- 将要执行的确切测试命令 (如 `go test ./...`)。
 
-- 计划中的功能点已实现并通过对应检查。
-- 涉及接口变更时，`docs/api/contracts.md` 已同步更新。
-- 涉及行为变更时，设计文档与规范文档已同步更新。
+### 手动验证 (Manual Verification)
+- 如果涉及无法自动化测试的部分（如 UI 调整），提供手动的步骤和期望结果的说明。
+````
 
 ## TODO 索引生成
 

From 1585e8ab8e451ef64437d0c04cbfcbb581031507 Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Mon, 30 Mar 2026 14:46:47 +0800
Subject: [PATCH 12/28] =?UTF-8?q?docs:=20=E6=A0=BC=E5=BC=8F=E5=8C=96?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md                              |   9 ++-
 Readme.md                              |   5 ++
 docs/api/contracts.md                  | 100 +++++++++++++++++--------
 docs/design-docs/instance_lifecycle.md |   4 +
 docs/exec-plans/README.md              |  13 +++-
 docs/exec-plans/TODO.md                |   2 +
 docs/standards/backend.md              |  10 ++-
 docs/standards/directory.md            |   5 +-
 docs/standards/frontend.md             |  17 +++--
 docs/standards/ops.md                  |  41 +++++-----
 10 files changed, 136 insertions(+), 70 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index c36ebfc..03ba32c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,11 +1,18 @@
-## 文档目录
+# 文档目录
+
 [API](docs/api/contracts.md)
+
 ## 规范
+
 [目录规范](docs/standards/directory.md)
 [后端规范](docs/standards/backend.md)
 [前端规范](docs/standards/frontend.md)
 [运维规范](docs/standards/ops.md)
+
 ## 设计
+
 [容器实例设计](docs/design-docs/instance_lifecycle.md)
+
 ## 执行计划
+
 [执行计划目录说明](docs/exec-plans/README.md)
diff --git a/Readme.md b/Readme.md
index 2478707..8c5805a 100644
--- a/Readme.md
+++ b/Readme.md
@@ -3,6 +3,7 @@
 轻量级游戏服务器容器化管理平台。
 
 ## 运行指南
+
 ```bash
 task dev               # 一键启动前后端开发服务
 ```
@@ -10,23 +11,27 @@ task dev               # 一键启动前后端开发服务
 ## 待办清单
 
 ### 实例生命周期与资源调度
+
 - [x] 开服与停服
 - [x] 实例的创建与删除
 - [ ] 实例重启与强制结束进程
 - [ ] 基于 Cgroups 的 CPU 与内存资源配额可视化配置
 
 ### 实时交互与性能监控
+
 - [ ] Web 控制台标准输出日志实时推流
 - [ ] 网页端在线交互指令无缝下发
 - [ ] 容器 CPU、内存、网络 I/O 运行态数据实时图表展示
 
 ### 数据灾备与持久化
+
 - [ ] 游戏容器 Volume 持久化目录挂载映射
 - [ ] 游戏存档/数据一键手动快照备份
 - [ ] 基于 Cron 表达式的自动化定时备份任务
 - [ ] 一键回档功能
 
 ### 在线文件管理与差异化配置
+
 - [ ] 可视化 Web 文件浏览器
 - [ ] 游戏基础配置文件的在线文本编辑器
 - [ ] 大文件 (Mod/插件) 上传及在线解压缩
diff --git a/docs/api/contracts.md b/docs/api/contracts.md
index e4d058a..4231525 100644
--- a/docs/api/contracts.md
+++ b/docs/api/contracts.md
@@ -2,45 +2,79 @@
 
 ## 命名规则
 
-
 ## 约定
+
 - Base URL: `/api`
 - CORS: 允许任意来源,允许方法 `GET,POST,DELETE,OPTIONS`
 
 ## HTTP接口
 
-| 方法 | 路径 | 说明 | 请求参数 | 返回结果 |
-| --- | --- | --- | --- | --- |
-| GET | `/api/instances` | 获取当前所有容器的列表 | 无 | `[{"container_id":"xxx", "name":"xxx", "status":"xxx"}]` |
-| POST | `/api/instances` | 创建一个新容器（初始为 Stopped） | `{"name": "测试服1号"}` | `{"status": "success", "container_id": "xxx"}` |
-| POST | `/api/instances/:id/start` | 启动指定容器实例 | 无（ID 在路径中） | `{"status": "success"}` |
-| POST | `/api/instances/:id/stop` | 停止指定容器实例 | 无（ID 在路径中） | `{"status": "success"}` |
-| DELETE | `/api/instances/:id` | 彻底删除指定容器实例 | 无（ID 在路径中） | `{"status": "success"}` |
-
-## JSON格式
-
-```go
-type createRequest struct {
-	Name string `json:"name"`
-}
-
-type statusResponse struct {
-	Status string `json:"status"`
-	Error  string `json:"error,omitempty"`
-}
-
-type createResponse struct {
-	Status      string `json:"status"`
-	ContainerID string `json:"container_id"`
-}
+### GET /api/instances
+
+- 说明：获取当前所有容器的列表
+- 状态码：
+  - 成功：`200`
+  - 失败：`500`
+- 请求参数：无
+- 返回结果：
+
+```json
+[{ "container_id": "xxx", "name": "xxx", "status": "xxx" }]
+```
+
+### POST /api/instances
+
+- 说明：创建一个新容器（初始为 Stopped）
+- 状态码：
+  - 成功：`200`
+  - 失败：`400`（JSON非法/空名称）、`409`（名称冲突）、`500`
+- 请求参数：
+
+```json
+{ "name": "容器1号" }
+```
+
+- 返回结果：
+
+```json
+{ "status": "success", "container_id": "xxx" }
 ```
 
-## 状态码约定
+### POST /api/instances/:id/start
 
-| 接口 | 成功 | 失败 |
-| --- | --- | --- |
-| `GET /api/instances` | `200` | `500` |
-| `POST /api/instances` | `200` | `400`(JSON非法/空名称), `409`(名称冲突), `500` |
-| `POST /api/instances/:id/start` | `200` | `400`(ID非法), `500` |
-| `POST /api/instances/:id/stop` | `200` | `400`(ID非法), `500` |
-| `DELETE /api/instances/:id` | `200` | `400`(ID非法), `409`(实例运行中), `500` |
+- 说明：启动指定容器实例
+- 状态码：
+  - 成功：`200`
+  - 失败：`400`（ID非法）、`500`
+- 请求参数：无（ID 在路径中）
+- 返回结果：
+
+```json
+{ "status": "success" }
+```
+
+### POST /api/instances/:id/stop
+
+- 说明：停止指定容器实例
+- 状态码：
+  - 成功：`200`
+  - 失败：`400`（ID非法）、`500`
+- 请求参数：无（ID 在路径中）
+- 返回结果：
+
+```json
+{ "status": "success" }
+```
+
+### DELETE /api/instances/:id
+
+- 说明：彻底删除指定容器实例
+- 状态码：
+  - 成功：`200`
+  - 失败：`400`（ID非法）、`409`（实例运行中）、`500`
+- 请求参数：无（ID 在路径中）
+- 返回结果：
+
+```json
+{ "status": "success" }
+```
diff --git a/docs/design-docs/instance_lifecycle.md b/docs/design-docs/instance_lifecycle.md
index 36ef476..2f26bae 100644
--- a/docs/design-docs/instance_lifecycle.md
+++ b/docs/design-docs/instance_lifecycle.md
@@ -3,6 +3,7 @@
 ## 数据结构
 
 ### 后端
+
 ```go
 type Instance struct {
     // 映射的 Docker 容器唯一标识
@@ -13,7 +14,9 @@ type Instance struct {
     Status      string `json:"status"`
 }
 ```
+
 ### 数据库
+
 - `instances` 表字段：
 - `container_id`（主键）
 - `name`（唯一）
@@ -21,6 +24,7 @@ type Instance struct {
 - `created_at`
 
 ## 接口
+
 [../api/contracts.md](../api/contracts.md)
 
 ## 状态流转
diff --git a/docs/exec-plans/README.md b/docs/exec-plans/README.md
index cd902e2..761889b 100644
--- a/docs/exec-plans/README.md
+++ b/docs/exec-plans/README.md
@@ -1,6 +1,7 @@
 # 执行计划目录说明
 
 本目录用于存放计划文档
+
 - `completed` 存放已经完成的计划
 - `active` 存放当前正在进行的计划
 
@@ -17,7 +18,7 @@
 
 执行计划内容建议遵循以下标准结构模块：
 
-````markdown
+```markdown
 # [目标描述 / Goal Description]
 
 提供问题的简要描述，相关背景上下文，以及此更改要实现的目标。
@@ -36,17 +37,21 @@
 对于具体的变更文件，使用 `[NEW]` 和 `[DELETE]` 标签标明文件的新旧状态，例如：
 
 #### [MODIFY] 修改的文件名.go (及文件相对路径)
+
 #### [NEW] 新增的文件名.go
+
 #### [DELETE] 删除的文件名.go
 
 ## 执行步骤 (Execution Steps)
 
 将完整的计划拆分为可执行的、细化的步骤列表，使用复选框来追踪进度状态：
+
 - `[ ]` 待办 (Uncompleted)
 - `[/]` 进行中 (In Progress)
 - `[x]` 已完成 (Completed)
 
 推荐使用嵌套列表来拆分复杂的步骤，例如：
+
 - [ ] 核心模型层设计
   - [ ] 定义 `User` 结构体
   - [ ] 编写对应的单元测试
@@ -63,13 +68,15 @@
 简述你将如何验证上述更改达到了预期效果。
 
 ### 自动化测试 (Automated Tests)
+
 - 将要执行的确切测试命令 (如 `go test ./...`)。
 
 ### 手动验证 (Manual Verification)
+
 - 如果涉及无法自动化测试的部分（如 UI 调整），提供手动的步骤和期望结果的说明。
-````
+```
 
 ## TODO 索引生成
 
 - 运行 `task docs:todo` 可从仓库注释中的 `TODO: 描述` 自动生成 `docs/exec-plans/TODO.md`。
-- 生成文件用于集中追踪技术债与改进事项，建议在提交前执行一次。
\ No newline at end of file
+- 生成文件用于集中追踪技术债与改进事项，建议在提交前执行一次。
diff --git a/docs/exec-plans/TODO.md b/docs/exec-plans/TODO.md
index ae1f07b..d049934 100644
--- a/docs/exec-plans/TODO.md
+++ b/docs/exec-plans/TODO.md
@@ -5,9 +5,11 @@ Source pattern: TODO: description
 Repository root: C:/Users/guzem/Desktop/Core/毕设/MineDock
 
 ## Summary
+
 - Total TODO items: 9
 
 ## Items
+
 - [ ] 抽取 start/stop/delete 的公共处理流程。 (backend/internal/api/handlers.go:87)
 - [ ] 增加统一的编码错误日志，提升可观测性。 (backend/internal/api/handlers.go:154)
 - [ ] 让 Docker 创建与 SQLite 保存具备原子性。 (backend/internal/service/docker_service.go:47)
diff --git a/docs/standards/backend.md b/docs/standards/backend.md
index fe9489c..434a9a1 100644
--- a/docs/standards/backend.md
+++ b/docs/standards/backend.md
@@ -3,6 +3,7 @@
 ## 1. 基础规范
 
 ### 技术栈
+
 - 开发语言：Go
 - 持久化存储：SQLite
 - 核心依赖：Docker SDK
@@ -12,7 +13,7 @@
 ### 格式化
 
 - 所有 Go 文件必须通过 `gofmt`。
-- 本地执行：`task backend:fmt`，仓库级执行：`task fmt`。
+- 本地执行：`task backend:fmt:check`，仓库级执行：`task fmt:check`。
 
 ### 注释(Go Doc)
 
@@ -22,13 +23,14 @@
 ## 2. 核心机制与控制流
 
 ### 上下文与并发
+
 - Context 传递：
   - `ctx` 必须作为函数第一个参数。
   - Handler 层通过 `r.Context()` 获取生命周期。
   - 禁止将 `context.Context` 存储在结构体中。
 - Goroutine 管理：
-    - 启动 Goroutine 时必须明确其**退出机制**（通过 ctx 或 channel）。
-    - 禁止在 `init()` 函数中启动后台任务。
+  - 启动 Goroutine 时必须明确其**退出机制**（通过 ctx 或 channel）。
+  - 禁止在 `init()` 函数中启动后台任务。
 
 ### 错误处理
 
@@ -73,4 +75,4 @@
 - 后端测试入口：`task backend:test`（`go test ./...`）。
 - Lint 检查：`task backend:lint`（`golangci-lint run ./...`）。
 - 静态检查：`task backend:vet`（`go vet ./...`）。
-- 提交前最低门禁建议：`task fmt && task lint && task vet && task test && task build`。
+- 提交前最低门禁建议：`task fmt:check && task lint && task vet && task test && task build`。
diff --git a/docs/standards/directory.md b/docs/standards/directory.md
index 419d45a..7ca4d7f 100644
--- a/docs/standards/directory.md
+++ b/docs/standards/directory.md
@@ -1,5 +1,6 @@
-## 目录规范
-```
+# 目录规范
+
+```text
 MineDock/
 ├── .github/                # 存放ci/cd
 ├── backend/                # 后端 Go 服务
diff --git a/docs/standards/frontend.md b/docs/standards/frontend.md
index 04c47f7..3c2412a 100644
--- a/docs/standards/frontend.md
+++ b/docs/standards/frontend.md
@@ -3,6 +3,7 @@
 ## 1. 基础与类型安全
 
 ### 技术栈
+
 - 构建工具：Vite
 - 核心框架：Vue 3 (Composition API)
 - 开发语言: TypeScript
@@ -31,15 +32,16 @@
 ## 4. 数据交互与网络
 
 ### API
+
 [../api/contracts.md](../api/contracts.md)
 
 网络约定：
 
 - 基础地址读取 `VITE_API_BASE_URL`，默认回退 `/api`。
 - 通用请求函数负责：
-	- JSON 序列化与 `Content-Type` 注入
-	- 默认 `Accept: application/json`
-	- 非 2xx 响应统一抛错（优先读取后端 `error` 字段）
+  - JSON 序列化与 `Content-Type` 注入
+  - 默认 `Accept: application/json`
+  - 非 2xx 响应统一抛错（优先读取后端 `error` 字段）
 - 所有业务 API 通过统一封装函数导出。
 
 ## 5. 样式与 UI 框架
@@ -48,16 +50,17 @@
 - 变量分层：
   - 基础变量：如 `--blue-500`, `--gray-900`
   - 语义变量：如 `--bg-primary`, `--text-danger`, `--border-color`
-- 主题切换实现：通过动态修改 `<html>` 或 `<body>` 的 `data-theme` 属性（如 `data-theme="dark"`），结合 CSS 变量覆盖实现低成本主题切换
+- 主题切换实现：通过动态修改 `<html>` 或 `<body>` 的 `data-theme` 属性
+  （如 `data-theme="dark"`），结合 CSS 变量覆盖实现低成本主题切换
 
 ## 6. 路由与鉴权
 
 - 当前仅包含基础路由 `/`，映射容器列表页。
 - 当前版本无登录鉴权。
 - 新增页面时要求：
-	- 在 `router/index.ts` 显式注册路由
-	- 路由名称与页面职责一致
-	- 若后续引入鉴权，统一通过全局前置守卫实现
+  - 在 `router/index.ts` 显式注册路由
+  - 路由名称与页面职责一致
+  - 若后续引入鉴权，统一通过全局前置守卫实现
 
 ## 7. 异常处理
 
diff --git a/docs/standards/ops.md b/docs/standards/ops.md
index 138f491..5ff17d4 100644
--- a/docs/standards/ops.md
+++ b/docs/standards/ops.md
@@ -1,11 +1,12 @@
 # 运维规范
 
 ## 构建
+
 - `task frontend:install`：安装前端依赖
 - `task dev`：并行启动前后端开发服务
 - `task build`：构建前后端产物
 - `task clean`：清理构建产物
-- `task fmt` / `task lint` / `task test` / `task vet`：质量检查
+- `task fmt:check` / `task lint` / `task test` / `task vet`：质量检查
 
 构建产物约定：
 
@@ -15,10 +16,10 @@
 环境变量约定：
 
 - 后端：
-	- `MINEDOCK_DB_PATH`（默认 `data/minedock.db`）
-	- `MINEDOCK_IMAGE`（默认 `alpine:latest`）
+  - `MINEDOCK_DB_PATH`（默认 `data/minedock.db`）
+  - `MINEDOCK_IMAGE`（默认 `alpine:latest`）
 - 前端：
-	- `VITE_API_BASE_URL`（默认 `/api`）
+  - `VITE_API_BASE_URL`（默认 `/api`）
 
 ## CI/CD
 
@@ -27,26 +28,26 @@ CI（`.github/workflows/ci.yml`）规则：
 - 触发条件：`push`、`pull_request`
 - 运行环境：`ubuntu-latest`
 - 校验顺序：
-	1. 安装前端依赖
-	2. `task fmt`
-	3. `task lint`
-	4. `task test`
-	5. `task vet`
-	6. `task build`
+  1. 安装前端依赖
+  2. `task fmt:check`
+  3. `task lint`
+  4. `task test`
+  5. `task vet`
+  6. `task build`
 
 Release（`.github/workflows/release.yml`）规则：
 
 - 触发条件：tag push（`v*`）
 - 发布前检查：前端格式检查、前端 lint、前端构建
 - 打包目标：
-	- `linux/amd64` (`tar.gz`)
-	- `windows/amd64` (`zip`)
-	- `darwin/amd64` (`tar.gz`)
-	- `darwin/arm64` (`tar.gz`)
+  - `linux/amd64` (`tar.gz`)
+  - `windows/amd64` (`zip`)
+  - `darwin/amd64` (`tar.gz`)
+  - `darwin/arm64` (`tar.gz`)
 - 归档内容：
-	- 后端可执行文件
-	- 前端 `dist`
-	- `Readme.md`
+  - 后端可执行文件
+  - 前端 `dist`
+  - `Readme.md`
 
 ### 命名规范
 
@@ -56,7 +57,7 @@ Release（`.github/workflows/release.yml`）规则：
 
 ### 必要检查
 
-- 合并到主线前必须通过：`fmt`、`lint`、`test`、`vet`、`build`
+- 合并到主线前必须通过：`fmt:check`、`lint`、`test`、`vet`、`build`
 - 发布前必须确保：
-	- 前端已完成一次独立构建
-	- Release 产物可在目标平台解压并运行
+  - 前端已完成一次独立构建
+  - Release 产物可在目标平台解压并运行

From 1997df0f5eb8e2721d797164137e0027706d2091 Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Mon, 30 Mar 2026 14:47:50 +0800
Subject: [PATCH 13/28] =?UTF-8?q?chore:=20=E6=9B=B4=E6=94=B9task=E7=9A=84f?=
 =?UTF-8?q?mt=E5=91=BD=E5=90=8D=E6=A0=BC=E5=BC=8F,=20=E6=B7=BB=E5=8A=A0?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3=E7=9A=84lint=E4=B8=8Efmt?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/workflows/ci.yml      |  2 +-
 .github/workflows/release.yml |  2 +-
 Taskfile.yml                  | 67 ++++++++++++++++++++++++++++++++---
 3 files changed, 64 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 499292e..ad3ab86 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -30,7 +30,7 @@ jobs:
         run: task frontend:install
 
       - name: Run formatting checks
-        run: task fmt
+        run: task fmt:check
 
       - name: Run lint checks
         run: task lint
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 0bbee86..ad198e5 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -34,7 +34,7 @@ jobs:
         run: task frontend:install
 
       - name: Run frontend format checks
-        run: task frontend:fmt
+        run: task frontend:fmt:check
 
       - name: Run frontend lint checks
         run: task frontend:lint
diff --git a/Taskfile.yml b/Taskfile.yml
index e831b39..3e87649 100644
--- a/Taskfile.yml
+++ b/Taskfile.yml
@@ -9,7 +9,7 @@ tasks:
     cmds:
       - go run main.go
 
-  backend:fmt:
+  backend:fmt:check:
     desc: Verify backend Go formatting
     dir: backend
     cmds:
@@ -21,6 +21,12 @@ tasks:
             exit 1
           fi
 
+  backend:fmt:fix:
+    desc: Format backend Go files with gofmt
+    dir: backend
+    cmds:
+      - gofmt -w .
+
   backend:vet:
     desc: Run backend go vet checks
     dir: backend
@@ -70,17 +76,59 @@ tasks:
     cmds:
       - npm run lint
 
-  frontend:fmt:
+  frontend:fmt:check:
     desc: Run frontend Prettier format checks
     dir: frontend
     cmds:
       - npm run format:check
 
+  frontend:fmt:fix:
+    desc: Format frontend files with Prettier
+    dir: frontend
+    cmds:
+      - npm run format
+
   docs:todo:
     desc: Generate docs/exec-plans/TODO.md from TODO comments
     cmds:
       - go run ./scripts/todo-gen/main.go -root .. -out ../docs/exec-plans/TODO.md
 
+  docs:lint:rules:
+    desc: Run Markdown rule checks for the knowledge base
+    cmds:
+      - npx --yes markdownlint-cli2 "AGENTS.md" "Readme.md" "docs/**/*.md"
+
+  docs:lint:rules:fix:
+    desc: Auto-fix Markdown rule violations where possible
+    cmds:
+      - npx --yes markdownlint-cli2 --fix "AGENTS.md" "Readme.md" "docs/**/*.md"
+
+  docs:links:check:
+    desc: Check Markdown links for the knowledge base
+    cmds:
+      - npx --yes markdown-link-check -q "AGENTS.md" "Readme.md" "docs"
+
+  docs:lint:
+    desc: Run documentation lint checks
+    deps:
+      - docs:lint:rules
+      - docs:links:check
+
+  docs:lint:fix:
+    desc: Auto-fix documentation lint issues where possible
+    deps:
+      - docs:lint:rules:fix
+
+  docs:fmt:check:
+    desc: Run Markdown formatting checks
+    cmds:
+      - npx --yes prettier --check "AGENTS.md" "Readme.md" "docs/**/*.md"
+
+  docs:fmt:fix:
+    desc: Format Markdown documents with Prettier
+    cmds:
+      - npx --yes prettier --write "AGENTS.md" "Readme.md" "docs/**/*.md"
+
   dev:
     desc: Run backend and frontend dev servers in parallel
     deps:
@@ -98,17 +146,26 @@ tasks:
     cmds:
       - rm -rf backend/bin frontend/dist
 
-  fmt:
+  fmt:check:
     desc: Run global formatting checks
     deps:
-      - backend:fmt
-      - frontend:fmt
+      - backend:fmt:check
+      - frontend:fmt:check
+      - docs:fmt:check
+
+  fmt:fix:
+    desc: Run global formatting fixes
+    deps:
+      - backend:fmt:fix
+      - frontend:fmt:fix
+      - docs:fmt:fix
 
   lint:
     desc: Run global lint checks
     deps:
       - backend:lint
       - frontend:lint
+      - docs:lint
 
   vet:
     desc: Run global vet checks

From dcdf0105a7da513a3fd2dc16b1acb6fcf108544e Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Mon, 30 Mar 2026 15:08:09 +0800
Subject: [PATCH 14/28] =?UTF-8?q?refactor:=20=E4=BF=AE=E6=94=B9=E5=89=8D?=
 =?UTF-8?q?=E7=AB=AF=E4=BB=A3=E7=A0=81=E6=B3=A8=E9=87=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend/src/api/index.ts            | 17 ++++++++++++++---
 frontend/src/components/Sidebar.vue  |  1 +
 frontend/src/components/TopBar.vue   |  3 ++-
 frontend/src/stores/containers.ts    |  6 ++++++
 frontend/src/views/ContainerList.vue |  4 ++++
 5 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/frontend/src/api/index.ts b/frontend/src/api/index.ts
index 2284d1f..375a2a7 100644
--- a/frontend/src/api/index.ts
+++ b/frontend/src/api/index.ts
@@ -12,7 +12,19 @@ function isPlainObject(value: unknown): value is JsonObject {
   return Object.prototype.toString.call(value) === "[object Object]";
 }
 
+function getResponseErrorMessage(data: unknown, status: number): string {
+  // 后端契约约定优先返回 error 字段，前端统一在这里做错误信息提取。
+  if (data && typeof data === "object" && "error" in data) {
+    const error = (data as { error?: unknown }).error;
+    if (typeof error === "string" && error.trim().length > 0) {
+      return error;
+    }
+  }
+  return `request failed: ${status}`;
+}
+
 async function request<T = unknown>(path: string, options: RequestOptions = {}): Promise<T> {
+  // 统一处理请求体序列化、默认请求头和非 2xx 错误转换。
   const { headers: customHeaders, body, ...rest } = options;
   const headers = new Headers(customHeaders);
 
@@ -38,10 +50,9 @@ async function request<T = unknown>(path: string, options: RequestOptions = {}):
     body: finalBody,
   });
 
-  const data = await resp.json().catch(() => ({}));
+  const data: unknown = await resp.json().catch(() => ({}));
   if (!resp.ok) {
-    const message = data?.error || `request failed: ${resp.status}`;
-    throw new Error(message);
+    throw new Error(getResponseErrorMessage(data, resp.status));
   }
   return data as T;
 }
diff --git a/frontend/src/components/Sidebar.vue b/frontend/src/components/Sidebar.vue
index 7c9cfcc..f379614 100644
--- a/frontend/src/components/Sidebar.vue
+++ b/frontend/src/components/Sidebar.vue
@@ -2,6 +2,7 @@
 import { ref } from "vue";
 import { RouterLink } from "vue-router";
 
+// 同一开关状态同时驱动桌面折叠和移动端抽屉，保持两端导航行为一致。
 const isOpen = ref<boolean>(false);
 </script>
 
diff --git a/frontend/src/components/TopBar.vue b/frontend/src/components/TopBar.vue
index 2585e67..db625d4 100644
--- a/frontend/src/components/TopBar.vue
+++ b/frontend/src/components/TopBar.vue
@@ -15,7 +15,7 @@ const setLocale = (lang: typeof locale.value) => {
   isOpen.value = false;
 };
 
-// Close dropdown when clicking outside
+// 语言菜单只在组件内维护，点击外部区域时统一收起。
 const handleClickOutside = (event: MouseEvent) => {
   const target = event.target as HTMLElement;
   if (!target.closest(".lang-selector")) {
@@ -24,6 +24,7 @@ const handleClickOutside = (event: MouseEvent) => {
 };
 
 onMounted(() => {
+  // 使用 document 级监听做外部点击检测，卸载时必须成对移除。
   document.addEventListener("click", handleClickOutside);
 });
 
diff --git a/frontend/src/stores/containers.ts b/frontend/src/stores/containers.ts
index 657be56..88f8c99 100644
--- a/frontend/src/stores/containers.ts
+++ b/frontend/src/stores/containers.ts
@@ -11,8 +11,10 @@ import {
 
 export const useContainerStore = defineStore("containers", () => {
   const instances = ref<Instance[]>([]);
+  // 统一的输出区文本，视图层只负责渲染该结果。
   const output = ref<string>("");
 
+  // 将异常对象收敛为可展示文本，避免视图层分散处理错误结构。
   function getErrorMessage(error: unknown): string {
     if (error instanceof Error) return error.message;
     if (typeof error === "string") return error;
@@ -38,6 +40,7 @@ export const useContainerStore = defineStore("containers", () => {
     output.value = `ERROR: ${getErrorMessage(error)}`;
   }
 
+  // 同步后端实例列表到全局状态，返回值供视图层决定后续提示文案。
   async function fetchInstances(): Promise<boolean> {
     try {
       const data = await listInstances();
@@ -49,6 +52,7 @@ export const useContainerStore = defineStore("containers", () => {
     }
   }
 
+  // 创建实例后立即刷新列表，避免视图层维护后端数据副本。
   async function create(name: string): Promise<boolean> {
     try {
       const data = await apiCreate(name);
@@ -61,6 +65,7 @@ export const useContainerStore = defineStore("containers", () => {
     }
   }
 
+  // 删除结果与刷新都在 store 内完成，破坏性确认由视图层负责。
   async function remove(containerId: string): Promise<void> {
     try {
       const data = await apiDelete(containerId);
@@ -71,6 +76,7 @@ export const useContainerStore = defineStore("containers", () => {
     }
   }
 
+  // start/stop 统一走一个 action，并在 finally 刷新以消除状态漂移。
   async function toggle(instance: Instance): Promise<boolean> {
     const running = isRunning(instance.status);
     let success = true;
diff --git a/frontend/src/views/ContainerList.vue b/frontend/src/views/ContainerList.vue
index 268b959..e2a90ca 100644
--- a/frontend/src/views/ContainerList.vue
+++ b/frontend/src/views/ContainerList.vue
@@ -13,6 +13,7 @@ onMounted(() => {
   void initializeList();
 });
 
+// 页面启动时统一触发列表拉取，并输出首屏可读状态。
 async function initializeList(): Promise<void> {
   store.print(t("status.waiting"));
   const success = await store.fetchInstances();
@@ -25,6 +26,7 @@ async function initializeList(): Promise<void> {
   }
 }
 
+// 视图层仅做输入校验和 action 触发，副作用与错误收敛在 store 内完成。
 async function handleCreate(): Promise<void> {
   const trimmed = newContainerName.value.trim();
   if (!trimmed) {
@@ -40,12 +42,14 @@ async function handleCreate(): Promise<void> {
   }
 }
 
+// 删除属于破坏性操作，执行前必须二次确认。
 async function handleDelete(containerId: string): Promise<void> {
   if (!confirm(t("containers.confirmDelete"))) return;
   store.print(t("status.deleting"));
   await store.remove(containerId);
 }
 
+// 根据当前运行态切换 start/stop，并输出阶段性反馈以避免静默操作。
 async function handleToggle(instance: {
   container_id: string;
   name: string;

From eb1cf69296a82c63b7d8835cea96c82cbc003909 Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Mon, 30 Mar 2026 15:08:20 +0800
Subject: [PATCH 15/28] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E5=89=8D?=
 =?UTF-8?q?=E7=AB=AF=E6=B3=A8=E9=87=8A=E8=A7=84=E8=8C=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/standards/frontend.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/docs/standards/frontend.md b/docs/standards/frontend.md
index 3c2412a..8fe27f0 100644
--- a/docs/standards/frontend.md
+++ b/docs/standards/frontend.md
@@ -15,6 +15,18 @@
 - 使用 ESLint + Prettier。
 - 使用 TypeScript严格模式。
 
+### 注释规范
+
+- 注释整体以说明“做什么”为主，避免逐行复述代码。
+- 关键决策点允许补充“为什么”，例如性能权衡、兼容性约束、并发/时序约束、回退策略。
+- 以下场景必须补充注释：
+  - `api/` 中不直观的数据映射与错误转换。
+  - `stores/` 中包含副作用或跨模块状态同步的 action。
+  - `composables/` 导出函数的输入、输出与边界条件。
+  - 组件中不直观的交互状态机或复杂条件分支。
+- 注释必须与代码同步维护：逻辑变更后，失效注释必须同步更新或删除。
+- TODO 规范：`// TODO: 描述内容`。
+
 ## 2. 架构与组件设计
 
 - `views/` 放路由级页面。

From 5e7dc2e4b7133703e89ccce459697b68e0782961 Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Mon, 30 Mar 2026 16:50:09 +0800
Subject: [PATCH 16/28] =?UTF-8?q?chore:=20=E4=BD=BF=20TODO=20=E7=94=9F?=
 =?UTF-8?q?=E6=88=90=E7=BB=93=E6=9E=9C=E5=8F=AF=E5=A4=8D=E7=8E=B0=EF=BC=8C?=
 =?UTF-8?q?=E5=B9=B6=E5=9B=BA=E5=AE=9A=E5=90=8E=E7=AB=AF=20Lint=20?=
 =?UTF-8?q?=E5=B7=A5=E5=85=B7=E7=9A=84=E7=89=88=E6=9C=AC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Taskfile.yml                |  4 ++--
 docs/exec-plans/TODO.md     |  7 +++----
 docs/standards/directory.md |  2 +-
 docs/standards/frontend.md  |  2 +-
 scripts/todo-gen/main.go    | 11 ++++-------
 5 files changed, 11 insertions(+), 15 deletions(-)

diff --git a/Taskfile.yml b/Taskfile.yml
index 3e87649..9981ef3 100644
--- a/Taskfile.yml
+++ b/Taskfile.yml
@@ -37,7 +37,7 @@ tasks:
     desc: Run backend golangci-lint checks
     dir: backend
     cmds:
-      - go run github.com/golangci/golangci-lint/cmd/golangci-lint@latest run --config .golangci.yml ./...
+      - go run github.com/golangci/golangci-lint/cmd/golangci-lint@v1.64.8 run --config .golangci.yml ./...
 
   backend:test:
     desc: Run backend tests
@@ -91,7 +91,7 @@ tasks:
   docs:todo:
     desc: Generate docs/exec-plans/TODO.md from TODO comments
     cmds:
-      - go run ./scripts/todo-gen/main.go -root .. -out ../docs/exec-plans/TODO.md
+      - go run ./scripts/todo-gen/main.go -root . -out ./docs/exec-plans/TODO.md
 
   docs:lint:rules:
     desc: Run Markdown rule checks for the knowledge base
diff --git a/docs/exec-plans/TODO.md b/docs/exec-plans/TODO.md
index d049934..a763c60 100644
--- a/docs/exec-plans/TODO.md
+++ b/docs/exec-plans/TODO.md
@@ -1,8 +1,7 @@
 # TODO Index
 
-Generated at: 2026-03-30T00:42:39+08:00
+Generated date: 2026-03-30
 Source pattern: TODO: description
-Repository root: C:/Users/guzem/Desktop/Core/毕设/MineDock
 
 ## Summary
 
@@ -10,8 +9,8 @@ Repository root: C:/Users/guzem/Desktop/Core/毕设/MineDock
 
 ## Items
 
-- [ ] 抽取 start/stop/delete 的公共处理流程。 (backend/internal/api/handlers.go:87)
-- [ ] 增加统一的编码错误日志，提升可观测性。 (backend/internal/api/handlers.go:154)
+- [ ] 抽取 start/stop/delete 的公共处理流程。 (backend/internal/api/handlers.go:82)
+- [ ] 增加统一的编码错误日志，提升可观测性。 (backend/internal/api/handlers.go:156)
 - [ ] 让 Docker 创建与 SQLite 保存具备原子性。 (backend/internal/service/docker_service.go:47)
 - [ ] 将逐条 Save 改为批量或事务化同步路径。 (backend/internal/service/docker_service.go:111)
 - [ ] 增加并发写保护，避免最后写入覆盖前写入。 (backend/internal/service/docker_service.go:112)
diff --git a/docs/standards/directory.md b/docs/standards/directory.md
index 7ca4d7f..9c61602 100644
--- a/docs/standards/directory.md
+++ b/docs/standards/directory.md
@@ -2,7 +2,7 @@
 
 ```text
 MineDock/
-├── .github/                # 存放ci/cd
+├── .github/                # 存放 CI/CD
 ├── backend/                # 后端 Go 服务
 │   ├── data/               # 数据存储目录
 │   ├── internal/           # 内部私有代码
diff --git a/docs/standards/frontend.md b/docs/standards/frontend.md
index 8fe27f0..d2904af 100644
--- a/docs/standards/frontend.md
+++ b/docs/standards/frontend.md
@@ -13,7 +13,7 @@
 ### 格式化
 
 - 使用 ESLint + Prettier。
-- 使用 TypeScript严格模式。
+- 使用 TypeScript 严格模式。
 
 ### 注释规范
 
diff --git a/scripts/todo-gen/main.go b/scripts/todo-gen/main.go
index b68b6bf..6d6374c 100644
--- a/scripts/todo-gen/main.go
+++ b/scripts/todo-gen/main.go
@@ -40,7 +40,7 @@ func main() {
 		fatalf("collect TODO comments: %v", err)
 	}
 
-	if err := writeMarkdown(root, outPath, items); err != nil {
+	if err := writeMarkdown(outPath, items); err != nil {
 		fatalf("write output file: %v", err)
 	}
 
@@ -171,7 +171,7 @@ func isLikelyCommentLine(line string, todoIndex int) bool {
 	return strings.HasPrefix(trimmed, "*")
 }
 
-func writeMarkdown(root, outPath string, items []todoItem) error {
+func writeMarkdown(outPath string, items []todoItem) error {
 	if err := os.MkdirAll(filepath.Dir(outPath), 0o755); err != nil {
 		return err
 	}
@@ -182,19 +182,16 @@ func writeMarkdown(root, outPath string, items []todoItem) error {
 	}
 	defer f.Close()
 
-	now := time.Now().Format(time.RFC3339)
+	generatedDate := time.Now().UTC().Format("2006-01-02")
 	if _, err := fmt.Fprintln(f, "# TODO Index"); err != nil {
 		return err
 	}
-	if _, err := fmt.Fprintf(f, "\nGenerated at: %s\n", now); err != nil {
+	if _, err := fmt.Fprintf(f, "\nGenerated date: %s\n", generatedDate); err != nil {
 		return err
 	}
 	if _, err := fmt.Fprintln(f, "Source pattern: TODO: description"); err != nil {
 		return err
 	}
-	if _, err := fmt.Fprintf(f, "Repository root: %s\n", filepath.ToSlash(root)); err != nil {
-		return err
-	}
 
 	if _, err := fmt.Fprintln(f, "\n## Summary"); err != nil {
 		return err

From 8db31e25f3cc5ce56bf1fb02bd0aed03153739a1 Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Mon, 30 Mar 2026 16:52:29 +0800
Subject: [PATCH 17/28] =?UTF-8?q?fix(frontend):=20=E5=B0=86=20API=20?=
 =?UTF-8?q?=E5=92=8C=20Store=20=E7=9A=84=E9=94=99=E8=AF=AF=E4=BF=A1?=
 =?UTF-8?q?=E6=81=AF=E6=98=A0=E5=B0=84=E4=B8=BA=20i18n=20=E5=9B=BD?=
 =?UTF-8?q?=E9=99=85=E5=8C=96=E6=96=87=E6=A1=88=EF=BC=88=E5=B1=95=E7=A4=BA?=
 =?UTF-8?q?=E4=BA=8E=E8=BE=93=E5=87=BA=E9=9D=A2=E6=9D=BF=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend/src/api/index.ts            |  49 ++++++++++---
 frontend/src/locales/en-US.json      |  13 ++++
 frontend/src/locales/zh-CN.json      |  13 ++++
 frontend/src/stores/containers.ts    | 102 ++++++++++++++++++++++-----
 frontend/src/views/ContainerList.vue |  13 +++-
 5 files changed, 159 insertions(+), 31 deletions(-)

diff --git a/frontend/src/api/index.ts b/frontend/src/api/index.ts
index 375a2a7..c75f568 100644
--- a/frontend/src/api/index.ts
+++ b/frontend/src/api/index.ts
@@ -8,19 +8,39 @@ interface RequestOptions extends Omit<RequestInit, "headers" | "body"> {
   body?: BodyInit | JsonObject | null;
 }
 
+export interface ApiRequestErrorInfo {
+  key: string;
+  status?: number;
+  backendMessage?: string;
+}
+
+export class ApiRequestError extends Error {
+  readonly key: string;
+  readonly status?: number;
+  readonly backendMessage?: string;
+
+  constructor(info: ApiRequestErrorInfo) {
+    super(info.key);
+    this.name = "ApiRequestError";
+    this.key = info.key;
+    this.status = info.status;
+    this.backendMessage = info.backendMessage;
+  }
+}
+
 function isPlainObject(value: unknown): value is JsonObject {
   return Object.prototype.toString.call(value) === "[object Object]";
 }
 
-function getResponseErrorMessage(data: unknown, status: number): string {
-  // 后端契约约定优先返回 error 字段，前端统一在这里做错误信息提取。
+function getResponseBackendError(data: unknown): string | undefined {
+  // 后端契约约定优先返回 error 字段，前端统一在这里提取后再映射到 i18n key。
   if (data && typeof data === "object" && "error" in data) {
     const error = (data as { error?: unknown }).error;
     if (typeof error === "string" && error.trim().length > 0) {
-      return error;
+      return error.trim();
     }
   }
-  return `request failed: ${status}`;
+  return undefined;
 }
 
 async function request<T = unknown>(path: string, options: RequestOptions = {}): Promise<T> {
@@ -44,15 +64,24 @@ async function request<T = unknown>(path: string, options: RequestOptions = {}):
     headers.set("Accept", "application/json");
   }
 
-  const resp = await fetch(`${BASE_URL}${path}`, {
-    ...rest,
-    headers,
-    body: finalBody,
-  });
+  let resp: Response;
+  try {
+    resp = await fetch(`${BASE_URL}${path}`, {
+      ...rest,
+      headers,
+      body: finalBody,
+    });
+  } catch {
+    throw new ApiRequestError({ key: "errors.network" });
+  }
 
   const data: unknown = await resp.json().catch(() => ({}));
   if (!resp.ok) {
-    throw new Error(getResponseErrorMessage(data, resp.status));
+    throw new ApiRequestError({
+      key: "errors.httpStatus",
+      status: resp.status,
+      backendMessage: getResponseBackendError(data),
+    });
   }
   return data as T;
 }
diff --git a/frontend/src/locales/en-US.json b/frontend/src/locales/en-US.json
index b685029..a0cd763 100644
--- a/frontend/src/locales/en-US.json
+++ b/frontend/src/locales/en-US.json
@@ -25,6 +25,19 @@
     "starting": "Starting container: {name}...",
     "startSuccess": "Container {name} start request sent"
   },
+  "errors": {
+    "network": "Network request failed. Please check your connection and try again.",
+    "badRequest": "The request is invalid. Please verify your input and retry.",
+    "notFound": "The requested resource was not found.",
+    "conflict": "The operation conflicts with the current resource state. Please refresh and retry.",
+    "internal": "The service is temporarily unavailable. Please try again later.",
+    "requestFailedWithStatus": "Request failed (status: {status}).",
+    "invalidJsonBody": "The request body format is invalid.",
+    "invalidContainerId": "The container ID is invalid.",
+    "instanceNameExists": "Container name already exists. Please choose another one.",
+    "instanceRunning": "The container is running. Stop it before deleting.",
+    "unknown": "An unknown error occurred. Please try again later."
+  },
   "sidebar": {
     "containerList": "Containers"
   },
diff --git a/frontend/src/locales/zh-CN.json b/frontend/src/locales/zh-CN.json
index f9f80cd..26bd819 100644
--- a/frontend/src/locales/zh-CN.json
+++ b/frontend/src/locales/zh-CN.json
@@ -25,6 +25,19 @@
     "starting": "正在开启容器: {name}...",
     "startSuccess": "容器 {name} 请求开启成功"
   },
+  "errors": {
+    "network": "网络请求失败，请检查连接后重试。",
+    "badRequest": "请求参数无效，请检查输入后重试。",
+    "notFound": "请求的资源不存在或已被移除。",
+    "conflict": "当前操作与资源状态冲突，请刷新后重试。",
+    "internal": "服务暂时不可用，请稍后重试。",
+    "requestFailedWithStatus": "请求失败（状态码：{status}）。",
+    "invalidJsonBody": "请求体格式不正确。",
+    "invalidContainerId": "容器 ID 无效。",
+    "instanceNameExists": "容器名称已存在，请更换后重试。",
+    "instanceRunning": "容器运行中，请先停止后再删除。",
+    "unknown": "发生未知错误，请稍后重试。"
+  },
   "sidebar": {
     "containerList": "容器列表"
   },
diff --git a/frontend/src/stores/containers.ts b/frontend/src/stores/containers.ts
index 88f8c99..28ef056 100644
--- a/frontend/src/stores/containers.ts
+++ b/frontend/src/stores/containers.ts
@@ -2,6 +2,7 @@ import { ref } from "vue";
 import { defineStore } from "pinia";
 import type { Instance } from "../api/index";
 import {
+  ApiRequestError,
   listInstances,
   createInstance as apiCreate,
   deleteInstance as apiDelete,
@@ -9,35 +10,98 @@ import {
   stopInstance as apiStop,
 } from "../api/index";
 
+type OutputI18nPayload = {
+  key: string;
+  values?: Record<string, string | number>;
+};
+
+const backendMessageKeyMap: Record<string, string> = {
+  "name is required": "status.emptyName",
+  "invalid json body": "errors.invalidJsonBody",
+  "invalid container id": "errors.invalidContainerId",
+  "instance name already exists": "errors.instanceNameExists",
+  "instance is running, stop it before delete": "errors.instanceRunning",
+};
+
+function isLikelyI18nKey(value: string): boolean {
+  return /^[a-z][a-z0-9_-]*(?:\.[a-zA-Z0-9_-]+)+$/.test(value);
+}
+
 export const useContainerStore = defineStore("containers", () => {
   const instances = ref<Instance[]>([]);
-  // 统一的输出区文本，视图层只负责渲染该结果。
+  // 统一输出区支持纯文本和 i18n key 两种模式，视图层只负责渲染。
   const output = ref<string>("");
+  const outputI18n = ref<OutputI18nPayload | null>(null);
+
+  function print(data: unknown): void {
+    outputI18n.value = null;
+    output.value = typeof data === "string" ? data : JSON.stringify(data, null, 2);
+  }
+
+  function printI18n(key: string, values?: Record<string, string | number>): void {
+    outputI18n.value = { key, values };
+    output.value = "";
+  }
+
+  function mapStatusToError(status?: number): OutputI18nPayload {
+    switch (status) {
+      case 400:
+        return { key: "errors.badRequest" };
+      case 404:
+        return { key: "errors.notFound" };
+      case 409:
+        return { key: "errors.conflict" };
+      case 500:
+        return { key: "errors.internal" };
+      default:
+        if (typeof status === "number") {
+          return { key: "errors.requestFailedWithStatus", values: { status } };
+        }
+        return { key: "errors.unknown" };
+    }
+  }
+
+  // 统一将底层异常映射为稳定的 i18n key，避免泄露网络/后端原始文案。
+  function mapErrorToI18n(error: unknown): OutputI18nPayload {
+    if (error instanceof ApiRequestError) {
+      if (error.backendMessage) {
+        const mappedKey = backendMessageKeyMap[error.backendMessage.trim().toLowerCase()];
+        if (mappedKey) {
+          return { key: mappedKey };
+        }
+      }
+
+      if (error.key === "errors.network") {
+        return { key: "errors.network" };
+      }
 
-  // 将异常对象收敛为可展示文本，避免视图层分散处理错误结构。
-  function getErrorMessage(error: unknown): string {
-    if (error instanceof Error) return error.message;
-    if (typeof error === "string") return error;
-    if (error && typeof error === "object") {
-      const maybeMessage = (error as { message?: unknown }).message;
-      if (typeof maybeMessage === "string" && maybeMessage.trim().length > 0) {
-        return maybeMessage;
+      if (error.key === "errors.httpStatus") {
+        return mapStatusToError(error.status);
       }
-      try {
-        return JSON.stringify(error);
-      } catch {
-        return String(error);
+
+      if (isLikelyI18nKey(error.key)) {
+        return { key: error.key };
       }
     }
-    return String(error);
-  }
 
-  function print(data: unknown): void {
-    output.value = typeof data === "string" ? data : JSON.stringify(data, null, 2);
+    if (typeof error === "string" && isLikelyI18nKey(error)) {
+      return { key: error };
+    }
+
+    if (error instanceof Error && isLikelyI18nKey(error.message)) {
+      return { key: error.message };
+    }
+
+    return { key: "errors.unknown" };
   }
 
   function printError(error: unknown): void {
-    output.value = `ERROR: ${getErrorMessage(error)}`;
+    const mapped = mapErrorToI18n(error);
+    printI18n(mapped.key, mapped.values);
+  }
+
+  function printErrorKey(key: string, values?: Record<string, string | number>): void {
+    printI18n(key, values);
   }
 
   // 同步后端实例列表到全局状态，返回值供视图层决定后续提示文案。
@@ -103,8 +167,10 @@ export const useContainerStore = defineStore("containers", () => {
   return {
     instances,
     output,
+    outputI18n,
     print,
     printError,
+    printErrorKey,
     fetchInstances,
     create,
     remove,
diff --git a/frontend/src/views/ContainerList.vue b/frontend/src/views/ContainerList.vue
index e2a90ca..a598a38 100644
--- a/frontend/src/views/ContainerList.vue
+++ b/frontend/src/views/ContainerList.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { ref, onMounted } from "vue";
+import { computed, ref, onMounted } from "vue";
 import { useI18n } from "vue-i18n";
 import { useContainerStore } from "../stores/containers";
 
@@ -9,6 +9,13 @@ const store = useContainerStore();
 const showCreateModal = ref(false);
 const newContainerName = ref("");
 
+const outputText = computed(() => {
+  if (store.outputI18n) {
+    return t(store.outputI18n.key, store.outputI18n.values ?? {});
+  }
+  return store.output;
+});
+
 onMounted(() => {
   void initializeList();
 });
@@ -30,7 +37,7 @@ async function initializeList(): Promise<void> {
 async function handleCreate(): Promise<void> {
   const trimmed = newContainerName.value.trim();
   if (!trimmed) {
-    store.printError(new Error(t("status.emptyName")));
+    store.printErrorKey("status.emptyName");
     return;
   }
 
@@ -131,7 +138,7 @@ async function handleToggle(instance: {
     </div>
 
     <!-- 用于显示接口返回的简易日志 -->
-    <pre class="output">{{ store.output }}</pre>
+    <pre class="output">{{ outputText }}</pre>
   </main>
 </template>
 

From ca2ccb83d724c8564ea0d424bdcc96fcef20cca4 Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Mon, 30 Mar 2026 17:11:05 +0800
Subject: [PATCH 18/28] =?UTF-8?q?docs:=20=E4=BF=AE=E5=A4=8D=E4=B8=80?=
 =?UTF-8?q?=E4=B8=AA=E9=94=99=E5=88=AB=E5=AD=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/exec-plans/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/exec-plans/README.md b/docs/exec-plans/README.md
index 761889b..4419b2f 100644
--- a/docs/exec-plans/README.md
+++ b/docs/exec-plans/README.md
@@ -29,7 +29,7 @@
 
 ## 拟定更改 (Proposed Changes)
 
-按组件名称（如具体的 package、功能区或依赖层）将将要修改的文件分组归类，并按逻辑顺序（例如先依赖后实现）展开描述。建议使用水平分割线来区分不同组件。
+按组件名称（如具体的 package、功能区或依赖层）将要修改的文件分组归类，并按逻辑顺序（例如先依赖后实现）展开描述。建议使用水平分割线来区分不同组件。
 
 ### [组件名称 / Component Name]
 

From 1666d9aef68e8a8eaa1ad91067f02bbee0dc1b4c Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Tue, 31 Mar 2026 14:41:52 +0800
Subject: [PATCH 19/28] =?UTF-8?q?docs:=20=E4=BF=AE=E6=94=B9Readme=E5=BE=85?=
 =?UTF-8?q?=E5=8A=9E=E6=B8=85=E5=8D=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Readme.md | 47 ++++++++++++++++++++++++++++++-----------------
 1 file changed, 30 insertions(+), 17 deletions(-)

diff --git a/Readme.md b/Readme.md
index 8c5805a..e2a0aa7 100644
--- a/Readme.md
+++ b/Readme.md
@@ -10,28 +10,41 @@ task dev               # 一键启动前后端开发服务
 
 ## 待办清单
 
-### 实例生命周期与资源调度
+### 镜像与模板
 
-- [x] 开服与停服
-- [x] 实例的创建与删除
-- [ ] 实例重启与强制结束进程
-- [ ] 基于 Cgroups 的 CPU 与内存资源配额可视化配置
+- [ ] 静态镜像注册表（后端 JSON 配置）
+- [ ] 镜像市场前端页面（浏览、筛选、选用镜像）
+- [ ] 基于 YAML 的游戏模板规范设计
+- [ ] 模板解析引擎（根据模板自动生成 Docker 启动参数）
 
-### 实时交互与性能监控
+### 实例生命周期
 
-- [ ] Web 控制台标准输出日志实时推流
-- [ ] 网页端在线交互指令无缝下发
-- [ ] 容器 CPU、内存、网络 I/O 运行态数据实时图表展示
+- [x] 容器基础生命周期：创建、删除、开启、停止
+- [ ] 创建容器时支持镜像选择
+- [ ] 创建容器时支持环境变量注入
+- [ ] 创建容器时支持 Volume 持久化目录挂载
+- [ ] 创建容器时支持动态端口映射与防冲突检测
+- [ ] 实例重启与强制终止
+- [ ] 实例详情页（镜像信息、端口、环境变量、运行时长等）
 
-### 数据灾备与持久化
+### 资源管控与监控
 
-- [ ] 游戏容器 Volume 持久化目录挂载映射
-- [ ] 游戏存档/数据一键手动快照备份
-- [ ] 基于 Cron 表达式的自动化定时备份任务
-- [ ] 一键回档功能
+- [ ] 基于 Cgroups 的 CPU 与内存资源配额配置
+- [ ] 容器 CPU、内存、网络 I/O 运行态数据采集
+- [ ] 前端实时折线图表展示硬件运行态数据
+
+### 实时交互
 
-### 在线文件管理与差异化配置
+- [ ] Web 控制台标准输出日志实时推流
+- [ ] 网页端在线交互指令下发
+- [ ] 前端终端高亮渲染及日志自动滚动
+
+### 运维与文件管理
 
 - [ ] 可视化 Web 文件浏览器
-- [ ] 游戏基础配置文件的在线文本编辑器
-- [ ] 大文件 (Mod/插件) 上传及在线解压缩
+- [ ] 游戏配置文件在线文本编辑器
+- [ ] 大文件上传及在线解压缩
+- [ ] 对接第三方社区 API，实现整合包一键解析与下载
+- [ ] 游戏存档一键手动快照备份
+- [ ] 基于 Cron 表达式的自动化定时备份
+- [ ] 一键回档功能

From 31073f3ce97d95b0b0797f90b741f914d261233c Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Tue, 31 Mar 2026 22:03:06 +0800
Subject: [PATCH 20/28] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E9=9D=99?=
 =?UTF-8?q?=E6=80=81=E9=95=9C=E5=83=8F=E6=B3=A8=E5=86=8C=E8=A1=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 backend/internal/api/handlers.go              |  14 +-
 backend/internal/api/handlers_test.go         |  91 ++++-
 backend/internal/api/registry_handlers.go     |  34 ++
 backend/internal/api/router.go                |   5 +-
 backend/internal/model/errors.go              |   3 +
 backend/internal/model/registry.go            |  13 +
 backend/internal/service/docker_service.go    |  36 +-
 backend/internal/service/registry_service.go  | 105 ++++++
 .../internal/service/registry_service_test.go | 119 +++++++
 backend/main.go                               |  16 +-
 backend/registry.json                         |  43 +++
 docs/api/contracts.md                         |  28 +-
 docs/design-docs/instance_lifecycle.md        |   2 +
 .../20260331-static-image-registry.md         | 326 ++++++++++++++++++
 docs/standards/ops.md                         |   2 +-
 frontend/src/api/index.ts                     |  19 +-
 frontend/src/locales/en-US.json               |   7 +
 frontend/src/locales/zh-CN.json               |   7 +
 frontend/src/stores/containers.ts             |   6 +-
 frontend/src/stores/registry.ts               |  33 ++
 frontend/src/views/ContainerList.vue          |  84 ++++-
 21 files changed, 952 insertions(+), 41 deletions(-)
 create mode 100644 backend/internal/api/registry_handlers.go
 create mode 100644 backend/internal/model/registry.go
 create mode 100644 backend/internal/service/registry_service.go
 create mode 100644 backend/internal/service/registry_service_test.go
 create mode 100644 backend/registry.json
 create mode 100644 docs/exec-plans/completed/20260331-static-image-registry.md
 create mode 100644 frontend/src/stores/registry.ts

diff --git a/backend/internal/api/handlers.go b/backend/internal/api/handlers.go
index a479ea5..751390f 100644
--- a/backend/internal/api/handlers.go
+++ b/backend/internal/api/handlers.go
@@ -13,7 +13,7 @@ import (
 // InstanceService 定义 API Handler 依赖的业务操作。
 type InstanceService interface {
 	ListInstances(ctx context.Context) ([]model.Instance, error)
-	CreateInstance(ctx context.Context, name string) (string, error)
+	CreateInstance(ctx context.Context, name, imageID string) (string, error)
 	StartInstance(ctx context.Context, containerID string) error
 	StopInstance(ctx context.Context, containerID string) error
 	DeleteInstance(ctx context.Context, containerID string) error
@@ -31,7 +31,8 @@ func NewHandler(svc InstanceService) *Handler {
 
 // createRequest 定义创建实例请求体。
 type createRequest struct {
-	Name string `json:"name"`
+	Name    string `json:"name"`
+	ImageID string `json:"image_id"`
 }
 
 // statusResponse 定义通用状态响应体。
@@ -69,8 +70,13 @@ func (h *Handler) CreateInstance(w http.ResponseWriter, r *http.Request) {
 		writeJSON(w, http.StatusBadRequest, statusResponse{Status: "error", Error: "name is required"})
 		return
 	}
+	req.ImageID = strings.TrimSpace(req.ImageID)
+	if req.ImageID == "" {
+		writeJSON(w, http.StatusBadRequest, statusResponse{Status: "error", Error: "image_id is required"})
+		return
+	}
 
-	id, err := h.svc.CreateInstance(r.Context(), req.Name)
+	id, err := h.svc.CreateInstance(r.Context(), req.Name, req.ImageID)
 	if err != nil {
 		writeJSON(w, mapErrorCode(err), statusResponse{Status: "error", Error: err.Error()})
 		return
@@ -141,6 +147,8 @@ func pathContainerID(r *http.Request) (string, bool) {
 // mapErrorCode 将领域错误统一映射为 HTTP 状态码。
 func mapErrorCode(err error) int {
 	switch {
+	case errors.Is(err, model.ErrImageNotFound):
+		return http.StatusBadRequest
 	case errors.Is(err, model.ErrNameExists):
 		return http.StatusConflict
 	case errors.Is(err, model.ErrInstanceRunning):
diff --git a/backend/internal/api/handlers_test.go b/backend/internal/api/handlers_test.go
index 86799d6..508ea2d 100644
--- a/backend/internal/api/handlers_test.go
+++ b/backend/internal/api/handlers_test.go
@@ -14,7 +14,7 @@ import (
 // mockService 为 Handler 测试实现 InstanceService。
 type mockService struct {
 	listFn   func(ctx context.Context) ([]model.Instance, error)
-	createFn func(ctx context.Context, name string) (string, error)
+	createFn func(ctx context.Context, name, imageID string) (string, error)
 	startFn  func(ctx context.Context, id string) error
 	stopFn   func(ctx context.Context, id string) error
 	deleteFn func(ctx context.Context, id string) error
@@ -23,8 +23,8 @@ type mockService struct {
 func (m *mockService) ListInstances(ctx context.Context) ([]model.Instance, error) {
 	return m.listFn(ctx)
 }
-func (m *mockService) CreateInstance(ctx context.Context, name string) (string, error) {
-	return m.createFn(ctx, name)
+func (m *mockService) CreateInstance(ctx context.Context, name, imageID string) (string, error) {
+	return m.createFn(ctx, name, imageID)
 }
 func (m *mockService) StartInstance(ctx context.Context, id string) error {
 	return m.startFn(ctx, id)
@@ -36,9 +36,25 @@ func (m *mockService) DeleteInstance(ctx context.Context, id string) error {
 	return m.deleteFn(ctx, id)
 }
 
+type mockRegistryLister struct {
+	listFn func(ctx context.Context) []model.RegistryImage
+}
+
+func (m *mockRegistryLister) ListImages(ctx context.Context) []model.RegistryImage {
+	if m == nil || m.listFn == nil {
+		return []model.RegistryImage{}
+	}
+	return m.listFn(ctx)
+}
+
 func newTestRouter(m *mockService) http.Handler {
 	h := NewHandler(m)
-	return NewRouter(h)
+	rh := NewRegistryHandler(&mockRegistryLister{
+		listFn: func(_ context.Context) []model.RegistryImage {
+			return []model.RegistryImage{}
+		},
+	})
+	return NewRouter(h, rh)
 }
 
 // --- GET /api/instances 场景 ---
@@ -85,19 +101,48 @@ func TestGetInstances_Error(t *testing.T) {
 	}
 }
 
+func TestGetRegistryImages_Success(t *testing.T) {
+	h := NewHandler(&mockService{})
+	rh := NewRegistryHandler(&mockRegistryLister{
+		listFn: func(_ context.Context) []model.RegistryImage {
+			return []model.RegistryImage{{ID: "minecraft-java", Image: "itzg/minecraft-server:latest"}}
+		},
+	})
+	router := NewRouter(h, rh)
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodGet, "/api/registry/images", nil)
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+	}
+
+	var got []model.RegistryImage
+	if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if len(got) != 1 || got[0].ID != "minecraft-java" {
+		t.Fatalf("unexpected response: %+v", got)
+	}
+}
+
 // --- POST /api/instances 场景 ---
 
 func TestCreateInstance_Success(t *testing.T) {
 	router := newTestRouter(&mockService{
-		createFn: func(_ context.Context, name string) (string, error) {
+		createFn: func(_ context.Context, name, imageID string) (string, error) {
 			if name != "test-server" {
 				t.Fatalf("unexpected name: %s", name)
 			}
+			if imageID != "minecraft-java" {
+				t.Fatalf("unexpected image_id: %s", imageID)
+			}
 			return "abc123", nil
 		},
 	})
 
-	body := `{"name":"test-server"}`
+	body := `{"name":"test-server","image_id":"minecraft-java"}`
 	w := httptest.NewRecorder()
 	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(body))
 	router.ServeHTTP(w, r)
@@ -131,7 +176,19 @@ func TestCreateInstance_EmptyName(t *testing.T) {
 	router := newTestRouter(&mockService{})
 
 	w := httptest.NewRecorder()
-	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(`{"name":"  "}`))
+	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(`{"name":"  ","image_id":"minecraft-java"}`))
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", w.Code)
+	}
+}
+
+func TestCreateInstance_EmptyImageID(t *testing.T) {
+	router := newTestRouter(&mockService{})
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(`{"name":"server","image_id":"   "}`))
 	router.ServeHTTP(w, r)
 
 	if w.Code != http.StatusBadRequest {
@@ -141,13 +198,13 @@ func TestCreateInstance_EmptyName(t *testing.T) {
 
 func TestCreateInstance_NameConflict(t *testing.T) {
 	router := newTestRouter(&mockService{
-		createFn: func(_ context.Context, _ string) (string, error) {
+		createFn: func(_ context.Context, _, _ string) (string, error) {
 			return "", model.ErrNameExists
 		},
 	})
 
 	w := httptest.NewRecorder()
-	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(`{"name":"dup"}`))
+	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(`{"name":"dup","image_id":"minecraft-java"}`))
 	router.ServeHTTP(w, r)
 
 	if w.Code != http.StatusConflict {
@@ -155,6 +212,22 @@ func TestCreateInstance_NameConflict(t *testing.T) {
 	}
 }
 
+func TestCreateInstance_ImageNotFound(t *testing.T) {
+	router := newTestRouter(&mockService{
+		createFn: func(_ context.Context, _, _ string) (string, error) {
+			return "", model.ErrImageNotFound
+		},
+	})
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(`{"name":"dup","image_id":"not-exists"}`))
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", w.Code)
+	}
+}
+
 // --- POST /api/instances/{id}/start 场景 ---
 
 func TestStartInstance_Success(t *testing.T) {
diff --git a/backend/internal/api/registry_handlers.go b/backend/internal/api/registry_handlers.go
new file mode 100644
index 0000000..30a1c0a
--- /dev/null
+++ b/backend/internal/api/registry_handlers.go
@@ -0,0 +1,34 @@
+package api
+
+import (
+	"context"
+	"net/http"
+
+	"minedock/backend/internal/model"
+)
+
+// RegistryLister 定义注册表 Handler 依赖的查询操作。
+type RegistryLister interface {
+	ListImages(ctx context.Context) []model.RegistryImage
+}
+
+// RegistryHandler 暴露镜像注册表相关 HTTP 处理器。
+type RegistryHandler struct {
+	registry RegistryLister
+}
+
+// NewRegistryHandler 创建 RegistryHandler。
+func NewRegistryHandler(r RegistryLister) *RegistryHandler {
+	return &RegistryHandler{registry: r}
+}
+
+// GetImages 处理 GET /api/registry/images，返回可用镜像列表。
+func (h *RegistryHandler) GetImages(w http.ResponseWriter, r *http.Request) {
+	if h == nil || h.registry == nil {
+		writeJSON(w, http.StatusInternalServerError, statusResponse{Status: "error", Error: "registry service unavailable"})
+		return
+	}
+
+	images := h.registry.ListImages(r.Context())
+	writeJSON(w, http.StatusOK, images)
+}
diff --git a/backend/internal/api/router.go b/backend/internal/api/router.go
index 62ae44a..d73bc2c 100644
--- a/backend/internal/api/router.go
+++ b/backend/internal/api/router.go
@@ -3,7 +3,7 @@ package api
 import "net/http"
 
 // NewRouter 注册 API 路由并包装中间件。
-func NewRouter(h *Handler) http.Handler {
+func NewRouter(h *Handler, registry *RegistryHandler) http.Handler {
 	mux := http.NewServeMux()
 
 	mux.HandleFunc("GET /api/instances", h.GetInstances)
@@ -11,6 +11,9 @@ func NewRouter(h *Handler) http.Handler {
 	mux.HandleFunc("POST /api/instances/{id}/start", h.StartInstance)
 	mux.HandleFunc("POST /api/instances/{id}/stop", h.StopInstance)
 	mux.HandleFunc("DELETE /api/instances/{id}", h.DeleteInstance)
+	if registry != nil {
+		mux.HandleFunc("GET /api/registry/images", registry.GetImages)
+	}
 
 	return withCORS(mux)
 }
diff --git a/backend/internal/model/errors.go b/backend/internal/model/errors.go
index 3385945..6e1069b 100644
--- a/backend/internal/model/errors.go
+++ b/backend/internal/model/errors.go
@@ -7,3 +7,6 @@ var ErrNameExists = errors.New("instance name already exists")
 
 // ErrInstanceRunning 表示实例正在运行，删除前必须先停止。
 var ErrInstanceRunning = errors.New("instance is running, stop it before delete")
+
+// ErrImageNotFound 表示请求的镜像 ID 不在注册表中。
+var ErrImageNotFound = errors.New("image not found in registry")
diff --git a/backend/internal/model/registry.go b/backend/internal/model/registry.go
new file mode 100644
index 0000000..23acddf
--- /dev/null
+++ b/backend/internal/model/registry.go
@@ -0,0 +1,13 @@
+package model
+
+// RegistryImage 描述注册表中的一个可用镜像条目。
+type RegistryImage struct {
+	ID           string            `json:"id"`
+	Name         string            `json:"name"`
+	Image        string            `json:"image"`
+	Description  string            `json:"description"`
+	Category     string            `json:"category"`
+	Icon         string            `json:"icon"`
+	DefaultEnv   map[string]string `json:"default_env"`
+	DefaultPorts []string          `json:"default_ports"`
+}
diff --git a/backend/internal/service/docker_service.go b/backend/internal/service/docker_service.go
index 56e10d0..254a9cb 100644
--- a/backend/internal/service/docker_service.go
+++ b/backend/internal/service/docker_service.go
@@ -18,7 +18,6 @@ const (
 	managedLabelKey   = "minedock.managed"
 	managedLabelValue = "true"
 	nameLabelKey      = "minedock.name"
-	defaultImage      = "alpine:latest"
 )
 
 // InstanceStore 定义 DockerService 依赖的持久化操作。
@@ -28,30 +27,41 @@ type InstanceStore interface {
 	Delete(ctx context.Context, containerID string) error
 }
 
+// ImageRegistry 定义 DockerService 依赖的镜像注册表查询能力。
+type ImageRegistry interface {
+	GetImage(ctx context.Context, id string) (model.RegistryImage, error)
+}
+
 // DockerService 封装容器管理相关业务逻辑。
 type DockerService struct {
-	cli   *client.Client
-	store InstanceStore
-	image string
+	cli      *client.Client
+	store    InstanceStore
+	registry ImageRegistry
 }
 
-// NewDockerService 使用依赖项和运行镜像创建 DockerService。
-func NewDockerService(cli *client.Client, s InstanceStore, imageName string) *DockerService {
-	if strings.TrimSpace(imageName) == "" {
-		imageName = defaultImage
-	}
-	return &DockerService{cli: cli, store: s, image: imageName}
+// NewDockerService 使用依赖项创建 DockerService。
+func NewDockerService(cli *client.Client, s InstanceStore, registry ImageRegistry) *DockerService {
+	return &DockerService{cli: cli, store: s, registry: registry}
 }
 
 // CreateInstance 创建托管容器并持久化实例元数据。
 // TODO: 让 Docker 创建与 SQLite 保存具备原子性。
-func (s *DockerService) CreateInstance(ctx context.Context, name string) (string, error) {
-	if err := s.ensureImage(ctx, s.image); err != nil {
+func (s *DockerService) CreateInstance(ctx context.Context, name, imageID string) (string, error) {
+	if s.registry == nil {
+		return "", fmt.Errorf("image registry is not configured")
+	}
+
+	regImage, err := s.registry.GetImage(ctx, imageID)
+	if err != nil {
+		return "", err
+	}
+
+	if err := s.ensureImage(ctx, regImage.Image); err != nil {
 		return "", err
 	}
 
 	resp, err := s.cli.ContainerCreate(ctx, &container.Config{
-		Image: s.image,
+		Image: regImage.Image,
 		Cmd:   []string{"sleep", "3600"},
 		Labels: map[string]string{
 			managedLabelKey: managedLabelValue,
diff --git a/backend/internal/service/registry_service.go b/backend/internal/service/registry_service.go
new file mode 100644
index 0000000..e7089a1
--- /dev/null
+++ b/backend/internal/service/registry_service.go
@@ -0,0 +1,105 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+
+	"minedock/backend/internal/model"
+)
+
+// RegistryService 提供可用镜像注册表的查询能力。
+type RegistryService struct {
+	images   []model.RegistryImage
+	imageMap map[string]model.RegistryImage
+}
+
+// NewRegistryService 从 JSON 文件加载镜像数据并构建查找索引。
+func NewRegistryService(filePath string) (*RegistryService, error) {
+	path := strings.TrimSpace(filePath)
+	if path == "" {
+		return nil, fmt.Errorf("registry path is required")
+	}
+
+	content, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("read registry file: %w", err)
+	}
+
+	var images []model.RegistryImage
+	if err := json.Unmarshal(content, &images); err != nil {
+		return nil, fmt.Errorf("decode registry file: %w", err)
+	}
+
+	imageMap := make(map[string]model.RegistryImage, len(images))
+	for i, img := range images {
+		id := strings.TrimSpace(img.ID)
+		if id == "" {
+			return nil, fmt.Errorf("registry image at index %d has empty id", i)
+		}
+		if strings.TrimSpace(img.Image) == "" {
+			return nil, fmt.Errorf("registry image %q has empty image", id)
+		}
+		if _, exists := imageMap[id]; exists {
+			return nil, fmt.Errorf("duplicate registry image id: %s", id)
+		}
+		img.ID = id
+		img.Image = strings.TrimSpace(img.Image)
+		imageMap[id] = img
+		images[i] = img
+	}
+
+	return &RegistryService{images: images, imageMap: imageMap}, nil
+}
+
+// ListImages 返回注册表中全部可用镜像。
+func (s *RegistryService) ListImages(_ context.Context) []model.RegistryImage {
+	if s == nil || len(s.images) == 0 {
+		return []model.RegistryImage{}
+	}
+	out := make([]model.RegistryImage, 0, len(s.images))
+	for _, img := range s.images {
+		out = append(out, cloneRegistryImage(img))
+	}
+	return out
+}
+
+// GetImage 按 ID 查找镜像，未找到时返回 model.ErrImageNotFound。
+func (s *RegistryService) GetImage(_ context.Context, id string) (model.RegistryImage, error) {
+	if s == nil {
+		return model.RegistryImage{}, model.ErrImageNotFound
+	}
+
+	key := strings.TrimSpace(id)
+	if key == "" {
+		return model.RegistryImage{}, model.ErrImageNotFound
+	}
+
+	img, ok := s.imageMap[key]
+	if !ok {
+		return model.RegistryImage{}, model.ErrImageNotFound
+	}
+	return cloneRegistryImage(img), nil
+}
+
+func cloneRegistryImage(img model.RegistryImage) model.RegistryImage {
+	clone := img
+	if len(img.DefaultEnv) > 0 {
+		clone.DefaultEnv = make(map[string]string, len(img.DefaultEnv))
+		for k, v := range img.DefaultEnv {
+			clone.DefaultEnv[k] = v
+		}
+	} else {
+		clone.DefaultEnv = map[string]string{}
+	}
+
+	if len(img.DefaultPorts) > 0 {
+		clone.DefaultPorts = append([]string(nil), img.DefaultPorts...)
+	} else {
+		clone.DefaultPorts = []string{}
+	}
+
+	return clone
+}
diff --git a/backend/internal/service/registry_service_test.go b/backend/internal/service/registry_service_test.go
new file mode 100644
index 0000000..7c04506
--- /dev/null
+++ b/backend/internal/service/registry_service_test.go
@@ -0,0 +1,119 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"minedock/backend/internal/model"
+)
+
+func writeRegistryFile(t *testing.T, content string) string {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "registry.json")
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatalf("write registry: %v", err)
+	}
+	return path
+}
+
+func TestNewRegistryService_Success(t *testing.T) {
+	path := writeRegistryFile(t, `[
+  {
+    "id": "minecraft-java",
+    "name": "Minecraft Java Edition",
+    "image": "itzg/minecraft-server:latest",
+    "description": "desc",
+    "category": "minecraft",
+    "icon": "minecraft-java",
+    "default_env": {"EULA": "TRUE"},
+    "default_ports": ["25565:25565"]
+  }
+]`)
+
+	svc, err := NewRegistryService(path)
+	if err != nil {
+		t.Fatalf("new registry service: %v", err)
+	}
+
+	images := svc.ListImages(context.Background())
+	if len(images) != 1 {
+		t.Fatalf("expected 1 image, got %d", len(images))
+	}
+	if images[0].ID != "minecraft-java" {
+		t.Fatalf("unexpected image id: %s", images[0].ID)
+	}
+
+	images[0].DefaultEnv["EULA"] = "FALSE"
+	images2 := svc.ListImages(context.Background())
+	if images2[0].DefaultEnv["EULA"] != "TRUE" {
+		t.Fatalf("expected cloned env map, got %s", images2[0].DefaultEnv["EULA"])
+	}
+}
+
+func TestNewRegistryService_InvalidJSON(t *testing.T) {
+	path := writeRegistryFile(t, `{`)
+
+	_, err := NewRegistryService(path)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+}
+
+func TestNewRegistryService_DuplicateID(t *testing.T) {
+	path := writeRegistryFile(t, `[
+  {"id": "a", "name": "A", "image": "repo/a:latest", "default_env": {}, "default_ports": []},
+  {"id": "a", "name": "B", "image": "repo/b:latest", "default_env": {}, "default_ports": []}
+]`)
+
+	_, err := NewRegistryService(path)
+	if err == nil {
+		t.Fatal("expected duplicate id error")
+	}
+}
+
+func TestNewRegistryService_EmptyRequiredField(t *testing.T) {
+	path := writeRegistryFile(t, `[
+  {"id": "", "name": "A", "image": "repo/a:latest", "default_env": {}, "default_ports": []}
+]`)
+
+	_, err := NewRegistryService(path)
+	if err == nil {
+		t.Fatal("expected empty id error")
+	}
+
+	path = writeRegistryFile(t, `[
+  {"id": "a", "name": "A", "image": "", "default_env": {}, "default_ports": []}
+]`)
+
+	_, err = NewRegistryService(path)
+	if err == nil {
+		t.Fatal("expected empty image error")
+	}
+}
+
+func TestRegistryService_GetImage(t *testing.T) {
+	path := writeRegistryFile(t, `[
+  {"id": "minecraft-java", "name": "A", "image": "repo/a:latest", "default_env": {}, "default_ports": []}
+]`)
+
+	svc, err := NewRegistryService(path)
+	if err != nil {
+		t.Fatalf("new registry service: %v", err)
+	}
+
+	img, err := svc.GetImage(context.Background(), "minecraft-java")
+	if err != nil {
+		t.Fatalf("get image: %v", err)
+	}
+	if img.Image != "repo/a:latest" {
+		t.Fatalf("unexpected image: %s", img.Image)
+	}
+
+	_, err = svc.GetImage(context.Background(), "not-exists")
+	if !errors.Is(err, model.ErrImageNotFound) {
+		t.Fatalf("expected ErrImageNotFound, got %v", err)
+	}
+}
diff --git a/backend/main.go b/backend/main.go
index 3062f86..9d2182f 100644
--- a/backend/main.go
+++ b/backend/main.go
@@ -30,10 +30,20 @@ func main() {
 	}
 	defer sqliteStore.Close()
 
-	imageName := os.Getenv("MINEDOCK_IMAGE")
-	svc := service.NewDockerService(cli, sqliteStore, imageName)
+	registryPath := os.Getenv("MINEDOCK_REGISTRY_PATH")
+	if registryPath == "" {
+		registryPath = "registry.json"
+	}
+
+	registrySvc, err := service.NewRegistryService(registryPath)
+	if err != nil {
+		log.Fatalf("init registry service: %v", err)
+	}
+
+	svc := service.NewDockerService(cli, sqliteStore, registrySvc)
 	h := api.NewHandler(svc)
-	router := api.NewRouter(h)
+	registryHandler := api.NewRegistryHandler(registrySvc)
+	router := api.NewRouter(h, registryHandler)
 
 	addr := ":8080"
 	log.Printf("MineDock backend listening on %s", addr)
diff --git a/backend/registry.json b/backend/registry.json
new file mode 100644
index 0000000..5118009
--- /dev/null
+++ b/backend/registry.json
@@ -0,0 +1,43 @@
+[
+  {
+    "id": "minecraft-java",
+    "name": "Minecraft Java Edition",
+    "image": "itzg/minecraft-server:latest",
+    "description": "最流行的 Minecraft Java 版服务器，支持原版/Forge/Fabric/Paper 等多种模组加载器。",
+    "category": "minecraft",
+    "icon": "minecraft-java",
+    "default_env": {
+      "EULA": "TRUE",
+      "TYPE": "PAPER"
+    },
+    "default_ports": [
+      "25565:25565"
+    ]
+  },
+  {
+    "id": "minecraft-bedrock",
+    "name": "Minecraft Bedrock Edition",
+    "image": "itzg/minecraft-bedrock-server:latest",
+    "description": "Minecraft 基岩版服务器，支持手机/主机/Win10 跨平台联机。",
+    "category": "minecraft",
+    "icon": "minecraft-bedrock",
+    "default_env": {
+      "EULA": "TRUE"
+    },
+    "default_ports": [
+      "19132:19132/udp"
+    ]
+  },
+  {
+    "id": "terraria",
+    "name": "Terraria",
+    "image": "ryshe/terraria:latest",
+    "description": "Terraria 专用服务器，支持 tShock 管理。",
+    "category": "sandbox",
+    "icon": "terraria",
+    "default_env": {},
+    "default_ports": [
+      "7777:7777"
+    ]
+  }
+]
diff --git a/docs/api/contracts.md b/docs/api/contracts.md
index 4231525..c777f7b 100644
--- a/docs/api/contracts.md
+++ b/docs/api/contracts.md
@@ -22,16 +22,40 @@
 [{ "container_id": "xxx", "name": "xxx", "status": "xxx" }]
 ```
 
+### GET /api/registry/images
+
+- 说明：获取注册表中所有可用的容器镜像列表
+- 状态码：
+  - 成功：`200`
+  - 失败：`500`
+- 请求参数：无
+- 返回结果：
+
+```json
+[
+  {
+    "id": "minecraft-java",
+    "name": "Minecraft Java Edition",
+    "image": "itzg/minecraft-server:latest",
+    "description": "...",
+    "category": "minecraft",
+    "icon": "minecraft-java",
+    "default_env": { "EULA": "TRUE" },
+    "default_ports": ["25565:25565"]
+  }
+]
+```
+
 ### POST /api/instances
 
 - 说明：创建一个新容器（初始为 Stopped）
 - 状态码：
   - 成功：`200`
-  - 失败：`400`（JSON非法/空名称）、`409`（名称冲突）、`500`
+  - 失败：`400`（JSON非法/空名称/缺失 image_id/image_id 不合法）、`409`（名称冲突）、`500`
 - 请求参数：
 
 ```json
-{ "name": "容器1号" }
+{ "name": "容器1号", "image_id": "minecraft-java" }
 ```
 
 - 返回结果：
diff --git a/docs/design-docs/instance_lifecycle.md b/docs/design-docs/instance_lifecycle.md
index 2f26bae..73e136a 100644
--- a/docs/design-docs/instance_lifecycle.md
+++ b/docs/design-docs/instance_lifecycle.md
@@ -10,6 +10,8 @@ type Instance struct {
     ContainerID string `json:"container_id"`
     // 服务端名称
     Name        string `json:"name"`
+    // 来源镜像的注册表 ID
+    ImageID     string `json:"image_id"`
     // 当前运行态
     Status      string `json:"status"`
 }
diff --git a/docs/exec-plans/completed/20260331-static-image-registry.md b/docs/exec-plans/completed/20260331-static-image-registry.md
new file mode 100644
index 0000000..e34b61c
--- /dev/null
+++ b/docs/exec-plans/completed/20260331-static-image-registry.md
@@ -0,0 +1,326 @@
+# 静态镜像注册表（后端 JSON 配置）
+
+## 背景
+
+当前 MineDock 创建容器时使用硬编码的 `alpine:latest` 镜像，用户无法选择容器镜像。本计划实现**静态镜像注册表**：后端通过 `registry.json` 配置文件维护一份受控的镜像列表，并暴露 API 供前端查询；同时改造创建容器接口，要求前端必须指定镜像 ID 进行创建。
+
+本计划仅覆盖**后端部分**和**必要的前端 API/Store 适配**，不包含镜像市场 UI 页面（留作后续计划）。
+
+## 需要评审的内容
+
+> [!IMPORTANT]
+> **API 变更（Breaking Change）**
+>
+> `POST /api/instances` 请求体从 `{ "name": "xxx" }` 变更为 `{ "name": "xxx", "image_id": "minecraft-java" }`。
+>
+> - `image_id` 为**必填**字段，未提供时返回 `400`。
+> - `image_id` 不合法（即不在注册表中）时返回 `400`。
+> - 同时移除 `MINEDOCK_IMAGE` 环境变量，镜像来源完全由注册表管控。
+
+> [!IMPORTANT]
+> **镜像校验逻辑**
+>
+> 创建容器时只允许使用注册表中存在的镜像，拒绝任意 Docker 镜像名称。这保证了安全可控性。
+
+## 拟定更改
+
+### 镜像注册表数据（新增）
+
+#### [NEW] registry.json (`backend/registry.json`)
+
+静态镜像目录配置文件，启动时由后端加载。初始包含以下镜像条目：
+
+```json
+[
+  {
+    "id": "minecraft-java",
+    "name": "Minecraft Java Edition",
+    "image": "itzg/minecraft-server:latest",
+    "description": "最流行的 Minecraft Java 版服务器，支持原版/Forge/Fabric/Paper 等多种模组加载器。",
+    "category": "minecraft",
+    "icon": "minecraft-java",
+    "default_env": {
+      "EULA": "TRUE",
+      "TYPE": "PAPER"
+    },
+    "default_ports": ["25565:25565"]
+  },
+  {
+    "id": "minecraft-bedrock",
+    "name": "Minecraft Bedrock Edition",
+    "image": "itzg/minecraft-bedrock-server:latest",
+    "description": "Minecraft 基岩版服务器，支持手机/主机/Win10 跨平台联机。",
+    "category": "minecraft",
+    "icon": "minecraft-bedrock",
+    "default_env": {
+      "EULA": "TRUE"
+    },
+    "default_ports": ["19132:19132/udp"]
+  },
+  {
+    "id": "terraria",
+    "name": "Terraria",
+    "image": "ryshe/terraria:latest",
+    "description": "Terraria 专用服务器，支持 tShock 管理。",
+    "category": "sandbox",
+    "icon": "terraria",
+    "default_env": {},
+    "default_ports": ["7777:7777"]
+  }
+]
+```
+
+> [!NOTE]
+> `default_env` 和 `default_ports` 本期**不会**在创建容器时生效（当前 `ContainerCreate` 尚未支持环境变量和端口映射）。它们作为元数据保留，为后续功能做准备。本期仅使用 `image` 字段来决定创建容器时使用的 Docker 镜像。
+
+---
+
+### 后端 Model 层
+
+#### [NEW] registry.go (`backend/internal/model/registry.go`)
+
+新增 `RegistryImage` 结构体，映射 `registry.json` 中的条目：
+
+```go
+// RegistryImage 描述注册表中的一个可用镜像条目。
+type RegistryImage struct {
+    ID           string            `json:"id"`
+    Name         string            `json:"name"`
+    Image        string            `json:"image"`
+    Description  string            `json:"description"`
+    Category     string            `json:"category"`
+    Icon         string            `json:"icon"`
+    DefaultEnv   map[string]string `json:"default_env"`
+    DefaultPorts []string          `json:"default_ports"`
+}
+```
+
+#### [MODIFY] errors.go (`backend/internal/model/errors.go`)
+
+新增错误变量：
+
+```go
+// ErrImageNotFound 表示请求的镜像 ID 不在注册表中。
+var ErrImageNotFound = errors.New("image not found in registry")
+```
+
+---
+
+### 后端 Service 层
+
+#### [NEW] registry_service.go (`backend/internal/service/registry_service.go`)
+
+新增 `RegistryService`，职责：
+
+- 从指定路径读取 `registry.json`，解码后在内存中缓存
+- 启动时校验：JSON 合法性、ID 非空且唯一、`image` 非空
+- 暴露以下方法：
+  - `ListImages(ctx) -> []RegistryImage` — 返回完整列表
+  - `GetImage(ctx, id) -> (RegistryImage, error)` — 按 ID 查找，不存在时返回 `model.ErrImageNotFound`
+
+```go
+// RegistryService 提供可用镜像注册表的查询能力。
+type RegistryService struct {
+    images   []model.RegistryImage
+    imageMap map[string]model.RegistryImage
+}
+
+// NewRegistryService 从 JSON 文件加载镜像数据并构建查找索引。
+func NewRegistryService(filePath string) (*RegistryService, error) { ... }
+
+// ListImages 返回注册表中全部可用镜像。
+func (s *RegistryService) ListImages(_ context.Context) []model.RegistryImage { ... }
+
+// GetImage 按 ID 查找镜像，未找到时返回 model.ErrImageNotFound。
+func (s *RegistryService) GetImage(_ context.Context, id string) (model.RegistryImage, error) { ... }
+```
+
+#### [MODIFY] docker_service.go (`backend/internal/service/docker_service.go`)
+
+- **`DockerService` 结构体变更**：移除 `image string` 字段，新增 `registry` 依赖（消费方接口）
+- **`NewDockerService` 签名变更**：用 `ImageRegistry` 接口替代 `imageName string` 参数
+- **`CreateInstance` 签名变更**：`CreateInstance(ctx, name, imageID string)` — 增加 `imageID` 参数
+  - 通过 `registry.GetImage(ctx, imageID)` 校验镜像 ID，不存在则返回 `model.ErrImageNotFound`
+  - 使用查到的 `RegistryImage.Image` 作为 Docker 镜像名调用 `ensureImage` 和 `ContainerCreate`
+- **移除 `defaultImage` 常量**和相关回退逻辑
+
+在 service 包内定义消费方接口：
+
+```go
+// ImageRegistry 定义 DockerService 依赖的镜像注册表查询能力。
+type ImageRegistry interface {
+    GetImage(ctx context.Context, id string) (model.RegistryImage, error)
+}
+```
+
+---
+
+### 后端 API 层
+
+#### [NEW] registry_handlers.go (`backend/internal/api/registry_handlers.go`)
+
+新增 `RegistryHandler`：
+
+```go
+// RegistryLister 定义注册表 Handler 依赖的查询操作。
+type RegistryLister interface {
+    ListImages(ctx context.Context) []model.RegistryImage
+}
+
+// RegistryHandler 暴露镜像注册表相关 HTTP 处理器。
+type RegistryHandler struct {
+    registry RegistryLister
+}
+
+// NewRegistryHandler 创建 RegistryHandler。
+func NewRegistryHandler(r RegistryLister) *RegistryHandler { ... }
+
+// GetImages 处理 GET /api/registry/images，返回可用镜像列表。
+func (h *RegistryHandler) GetImages(w http.ResponseWriter, r *http.Request) { ... }
+```
+
+#### [MODIFY] handlers.go (`backend/internal/api/handlers.go`)
+
+- `createRequest` 增加 `ImageID string \`json:"image_id"\`` 字段
+- `InstanceService` 接口的 `CreateInstance` 签名更新为 `CreateInstance(ctx context.Context, name string, imageID string) (string, error)`
+- `CreateInstance` Handler 增加 `image_id` 非空校验，为空时返回 `400`
+- `CreateInstance` Handler 调用 Service 时传入 `req.ImageID`
+- `mapErrorCode` 增加 `model.ErrImageNotFound -> 400` 的映射
+
+#### [MODIFY] router.go (`backend/internal/api/router.go`)
+
+- `NewRouter` 签名变更：接受 `*Handler` 和 `*RegistryHandler` 两个参数
+- 注册新路由：`GET /api/registry/images`
+
+---
+
+### 后端入口
+
+#### [MODIFY] main.go
+
+- 移除 `MINEDOCK_IMAGE` 环境变量读取逻辑
+- 新增 `RegistryService` 初始化：从 `registry.json` 加载（路径可通过 `MINEDOCK_REGISTRY_PATH` 环境变量覆盖，默认 `registry.json`）
+- 将 `RegistryService` 注入 `DockerService`（替代原有的 `imageName` 参数）
+- 创建 `RegistryHandler` 并注入 `RegistryService`
+- 更新 `NewRouter` 调用
+
+---
+
+### 前端 API 层
+
+#### [MODIFY] index.ts (`frontend/src/api/index.ts`)
+
+- 新增 `RegistryImage` 接口类型
+- 新增 `listRegistryImages()` API 函数
+- `createInstance` 函数签名变更：接受 `name` 和 `imageId` 两个必填参数
+
+---
+
+### 前端状态管理
+
+#### [NEW] registry.ts (`frontend/src/stores/registry.ts`)
+
+新增 Pinia store：
+
+- `images: RegistryImage[]` — 可用镜像列表
+- `loading: boolean` — 加载状态
+- `fetchImages()` — 从后端加载镜像列表
+- `getById(id)` — 按 ID 查找镜像
+
+#### [MODIFY] containers.ts (`frontend/src/stores/containers.ts`)
+
+- `create` action 签名变更：`create(name: string, imageId: string)`
+- 调用 `apiCreate(name, imageId)` 时传入镜像参数
+
+---
+
+### 文档更新
+
+#### [MODIFY] contracts.md (`docs/api/contracts.md`)
+
+新增 API 文档：
+
+````markdown
+### GET /api/registry/images
+
+- 说明：获取注册表中所有可用的容器镜像列表
+- 状态码：
+  - 成功：`200`
+  - 失败：`500`
+- 请求参数：无
+- 返回结果：
+
+\```json
+[{
+"id": "minecraft-java",
+"name": "Minecraft Java Edition",
+"image": "itzg/minecraft-server:latest",
+"description": "...",
+"category": "minecraft",
+"icon": "minecraft-java",
+"default_env": { "EULA": "TRUE" },
+"default_ports": ["25565:25565"]
+}]
+\```
+````
+
+更新 `POST /api/instances` 请求参数说明，增加 `image_id` 字段。
+
+#### [MODIFY] instance_lifecycle.md (`docs/design-docs/instance_lifecycle.md`)
+
+- Instance 结构体新增 `ImageID` 字段说明（用于标识容器基于的注册表镜像）
+
+---
+
+## 执行步骤
+
+- [ ] 后端 Model 层
+  - [ ] 新建 `backend/internal/model/registry.go`，定义 `RegistryImage` 结构体
+  - [ ] 修改 `backend/internal/model/errors.go`，新增 `ErrImageNotFound`
+- [ ] 后端注册表数据
+  - [ ] 新建 `backend/registry.json`，写入初始镜像条目
+- [ ] 后端 Service 层
+  - [ ] 新建 `backend/internal/service/registry_service.go`，实现 `RegistryService`
+  - [ ] 编写 `registry_service_test.go` 单元测试（加载合法/非法 JSON、按 ID 查询）
+  - [ ] 修改 `backend/internal/service/docker_service.go`：移除 `image` 字段和 `defaultImage` 常量、新增 `ImageRegistry` 接口依赖、更新 `CreateInstance` 签名
+- [ ] 后端 API 层
+  - [ ] 新建 `backend/internal/api/registry_handlers.go`，实现 `RegistryHandler`
+  - [ ] 修改 `backend/internal/api/handlers.go`：`createRequest` 增加 `ImageID`、`InstanceService` 接口同步更新
+  - [ ] 修改 `backend/internal/api/router.go`：注册 `GET /api/registry/images`
+  - [ ] 更新 `handlers_test.go`：适配新的 `CreateInstance` 签名
+- [ ] 后端入口
+  - [ ] 修改 `backend/main.go`：移除 `MINEDOCK_IMAGE`、初始化 `RegistryService`、注入 `DockerService`、创建 `RegistryHandler`
+- [ ] 前端适配
+  - [ ] 修改 `frontend/src/api/index.ts`：新增 `RegistryImage` 类型和 `listRegistryImages()` 函数、更新 `createInstance` 签名
+  - [ ] 新建 `frontend/src/stores/registry.ts`：镜像注册表 Pinia store
+  - [ ] 修改 `frontend/src/stores/containers.ts`：`create` action 增加 `imageId` 参数
+- [ ] 文档更新
+  - [ ] 修改 `docs/api/contracts.md`：新增 `GET /api/registry/images`、更新 `POST /api/instances`
+  - [ ] 修改 `docs/design-docs/instance_lifecycle.md`：补充 `ImageID` 字段
+
+## 已确认的决策
+
+- ✅ 初始镜像列表：Minecraft Java、Minecraft Bedrock、Terraria 三个条目
+- ✅ 字段命名：使用 `image_id` 引用注册表 ID
+- ✅ `image_id` 为必填字段，不提供时返回 `400`
+- ✅ 移除 `MINEDOCK_IMAGE` 环境变量
+- ✅ 移除 `recommended` 和 `tags` 字段
+
+## 验证计划
+
+### 自动化测试
+
+- `task backend:test` — 覆盖：
+  - `RegistryService`：加载合法 JSON / 格式错误 JSON / ID 重复校验
+  - `RegistryService.GetImage`：存在的 ID / 不存在的 ID
+  - `DockerService.CreateInstance`（mock）：有效 imageID、无效 imageID 返回 400
+  - `Handler` 层：更新后的请求体解析与错误映射
+- `task backend:vet && task backend:lint`
+- 前端：`npm run lint`
+
+### 手动验证
+
+- 启动后端，调用 `GET /api/registry/images`，验证返回完整镜像列表
+- 调用 `POST /api/instances` 传入合法 `image_id`，验证容器使用了正确镜像
+- 调用 `POST /api/instances` 不传 `image_id`，验证返回 `400`
+- 调用 `POST /api/instances` 传入非法 `image_id`，验证返回 `400`
diff --git a/docs/standards/ops.md b/docs/standards/ops.md
index 5ff17d4..038d52c 100644
--- a/docs/standards/ops.md
+++ b/docs/standards/ops.md
@@ -17,7 +17,7 @@
 
 - 后端：
   - `MINEDOCK_DB_PATH`（默认 `data/minedock.db`）
-  - `MINEDOCK_IMAGE`（默认 `alpine:latest`）
+  - `MINEDOCK_REGISTRY_PATH`（默认 `registry.json`）
 - 前端：
   - `VITE_API_BASE_URL`（默认 `/api`）
 
diff --git a/frontend/src/api/index.ts b/frontend/src/api/index.ts
index c75f568..b3dd974 100644
--- a/frontend/src/api/index.ts
+++ b/frontend/src/api/index.ts
@@ -92,14 +92,29 @@ export interface Instance {
   status: string;
 }
 
+export interface RegistryImage {
+  id: string;
+  name: string;
+  image: string;
+  description: string;
+  category: string;
+  icon: string;
+  default_env: Record<string, string>;
+  default_ports: string[];
+}
+
 export function listInstances(): Promise<Instance[]> {
   return request<Instance[]>("/instances", { method: "GET" });
 }
 
-export function createInstance(name: string): Promise<unknown> {
+export function listRegistryImages(): Promise<RegistryImage[]> {
+  return request<RegistryImage[]>("/registry/images", { method: "GET" });
+}
+
+export function createInstance(name: string, imageId: string): Promise<unknown> {
   return request("/instances", {
     method: "POST",
-    body: { name },
+    body: { name, image_id: imageId },
   });
 }
 
diff --git a/frontend/src/locales/en-US.json b/frontend/src/locales/en-US.json
index a0cd763..3915270 100644
--- a/frontend/src/locales/en-US.json
+++ b/frontend/src/locales/en-US.json
@@ -10,6 +10,10 @@
   "createModal": {
     "title": "New Container",
     "placeholder": "Enter container name...",
+    "imageLabel": "Select Image",
+    "imagePlaceholder": "Please select an image",
+    "loadingImages": "Loading image list...",
+    "noImages": "No images available right now. Please try again later.",
     "cancel": "Cancel",
     "confirm": "OK"
   },
@@ -18,6 +22,7 @@
     "listRefreshed": "Container list refreshed.",
     "noContainers": "No containers available.",
     "emptyName": "Container name cannot be empty",
+    "emptyImage": "Please select a container image",
     "creating": "Creating container...",
     "deleting": "Deleting container...",
     "stopping": "Stopping container: {name}...",
@@ -33,6 +38,8 @@
     "internal": "The service is temporarily unavailable. Please try again later.",
     "requestFailedWithStatus": "Request failed (status: {status}).",
     "invalidJsonBody": "The request body format is invalid.",
+    "imageIdRequired": "You must select an image before creating a container.",
+    "imageNotFound": "The selected image does not exist. Please refresh and try again.",
     "invalidContainerId": "The container ID is invalid.",
     "instanceNameExists": "Container name already exists. Please choose another one.",
     "instanceRunning": "The container is running. Stop it before deleting.",
diff --git a/frontend/src/locales/zh-CN.json b/frontend/src/locales/zh-CN.json
index 26bd819..8bb8c4c 100644
--- a/frontend/src/locales/zh-CN.json
+++ b/frontend/src/locales/zh-CN.json
@@ -10,6 +10,10 @@
   "createModal": {
     "title": "新建容器",
     "placeholder": "请输入新容器名称...",
+    "imageLabel": "选择镜像",
+    "imagePlaceholder": "请选择一个镜像",
+    "loadingImages": "镜像列表加载中...",
+    "noImages": "暂无可用镜像，请稍后重试。",
     "cancel": "取消",
     "confirm": "确定"
   },
@@ -18,6 +22,7 @@
     "listRefreshed": "已刷新容器列表。",
     "noContainers": "当前暂无容器。",
     "emptyName": "容器名称不能为空",
+    "emptyImage": "请选择一个容器镜像",
     "creating": "正在创建容器...",
     "deleting": "正在删除容器...",
     "stopping": "正在关闭容器: {name}...",
@@ -33,6 +38,8 @@
     "internal": "服务暂时不可用，请稍后重试。",
     "requestFailedWithStatus": "请求失败（状态码：{status}）。",
     "invalidJsonBody": "请求体格式不正确。",
+    "imageIdRequired": "必须选择镜像后才能创建容器。",
+    "imageNotFound": "所选镜像不存在或已下线，请刷新后重试。",
     "invalidContainerId": "容器 ID 无效。",
     "instanceNameExists": "容器名称已存在，请更换后重试。",
     "instanceRunning": "容器运行中，请先停止后再删除。",
diff --git a/frontend/src/stores/containers.ts b/frontend/src/stores/containers.ts
index 28ef056..81ae64e 100644
--- a/frontend/src/stores/containers.ts
+++ b/frontend/src/stores/containers.ts
@@ -17,6 +17,8 @@ type OutputI18nPayload = {
 
 const backendMessageKeyMap: Record<string, string> = {
   "name is required": "status.emptyName",
+  "image_id is required": "errors.imageIdRequired",
+  "image not found in registry": "errors.imageNotFound",
   "invalid json body": "errors.invalidJsonBody",
   "invalid container id": "errors.invalidContainerId",
   "instance name already exists": "errors.instanceNameExists",
@@ -117,9 +119,9 @@ export const useContainerStore = defineStore("containers", () => {
   }
 
   // 创建实例后立即刷新列表，避免视图层维护后端数据副本。
-  async function create(name: string): Promise<boolean> {
+  async function create(name: string, imageId: string): Promise<boolean> {
     try {
-      const data = await apiCreate(name);
+      const data = await apiCreate(name, imageId);
       print(data);
       await fetchInstances();
       return true;
diff --git a/frontend/src/stores/registry.ts b/frontend/src/stores/registry.ts
new file mode 100644
index 0000000..c438f38
--- /dev/null
+++ b/frontend/src/stores/registry.ts
@@ -0,0 +1,33 @@
+import { ref } from "vue";
+import { defineStore } from "pinia";
+import type { RegistryImage } from "../api/index";
+import { listRegistryImages } from "../api/index";
+
+export const useRegistryStore = defineStore("registry", () => {
+  const images = ref<RegistryImage[]>([]);
+  const loading = ref(false);
+
+  async function fetchImages(): Promise<void> {
+    loading.value = true;
+    try {
+      images.value = await listRegistryImages();
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  function getById(id: string): RegistryImage | undefined {
+    const key = id.trim();
+    if (!key) {
+      return undefined;
+    }
+    return images.value.find((item) => item.id === key);
+  }
+
+  return {
+    images,
+    loading,
+    fetchImages,
+    getById,
+  };
+});
diff --git a/frontend/src/views/ContainerList.vue b/frontend/src/views/ContainerList.vue
index a598a38..a11ac59 100644
--- a/frontend/src/views/ContainerList.vue
+++ b/frontend/src/views/ContainerList.vue
@@ -2,12 +2,15 @@
 import { computed, ref, onMounted } from "vue";
 import { useI18n } from "vue-i18n";
 import { useContainerStore } from "../stores/containers";
+import { useRegistryStore } from "../stores/registry";
 
 const { t } = useI18n();
 const store = useContainerStore();
+const registryStore = useRegistryStore();
 
 const showCreateModal = ref(false);
 const newContainerName = ref("");
+const selectedImageId = ref("");
 
 const outputText = computed(() => {
   if (store.outputI18n) {
@@ -16,13 +19,36 @@ const outputText = computed(() => {
   return store.output;
 });
 
+const selectedImageDescription = computed(() => {
+  return registryStore.getById(selectedImageId.value)?.description ?? "";
+});
+
 onMounted(() => {
   void initializeList();
 });
 
+function ensureDefaultImageSelection(): void {
+  if (!selectedImageId.value && registryStore.images.length > 0) {
+    selectedImageId.value = registryStore.images[0].id;
+  }
+}
+
+function openCreateModal(): void {
+  showCreateModal.value = true;
+  ensureDefaultImageSelection();
+}
+
 // 页面启动时统一触发列表拉取，并输出首屏可读状态。
 async function initializeList(): Promise<void> {
   store.print(t("status.waiting"));
+
+  try {
+    await registryStore.fetchImages();
+    ensureDefaultImageSelection();
+  } catch (err) {
+    store.printError(err);
+  }
+
   const success = await store.fetchInstances();
   if (!success) return;
 
@@ -41,8 +67,14 @@ async function handleCreate(): Promise<void> {
     return;
   }
 
+  const imageId = selectedImageId.value.trim();
+  if (!imageId) {
+    store.printErrorKey("status.emptyImage");
+    return;
+  }
+
   store.print(t("status.creating"));
-  const success = await store.create(trimmed);
+  const success = await store.create(trimmed, imageId);
   if (success) {
     showCreateModal.value = false;
     newContainerName.value = "";
@@ -87,7 +119,7 @@ async function handleToggle(instance: {
   <main class="main-content">
     <!-- 列表操作栏 -->
     <div class="content-actions">
-      <button class="create-btn" @click="showCreateModal = true">
+      <button class="create-btn" @click="openCreateModal">
         {{ $t("containers.createBtn") }}
       </button>
     </div>
@@ -128,11 +160,35 @@ async function handleToggle(instance: {
           :placeholder="$t('createModal.placeholder')"
           @keyup.enter="handleCreate"
         />
+        <label class="field-label" for="image-select">{{ $t("createModal.imageLabel") }}</label>
+        <select
+          id="image-select"
+          v-model="selectedImageId"
+          :disabled="registryStore.loading || registryStore.images.length === 0"
+        >
+          <option value="" disabled>{{ $t("createModal.imagePlaceholder") }}</option>
+          <option v-for="image in registryStore.images" :key="image.id" :value="image.id">
+            {{ image.name }}
+          </option>
+        </select>
+        <p v-if="registryStore.loading" class="modal-hint">{{ $t("createModal.loadingImages") }}</p>
+        <p v-else-if="registryStore.images.length === 0" class="modal-hint">
+          {{ $t("createModal.noImages") }}
+        </p>
+        <p v-else-if="selectedImageDescription" class="modal-hint">
+          {{ selectedImageDescription }}
+        </p>
         <div class="modal-actions">
           <button class="btn-cancel" @click="showCreateModal = false">
             {{ $t("createModal.cancel") }}
           </button>
-          <button class="btn-confirm" @click="handleCreate">{{ $t("createModal.confirm") }}</button>
+          <button
+            class="btn-confirm"
+            :disabled="registryStore.loading || registryStore.images.length === 0"
+            @click="handleCreate"
+          >
+            {{ $t("createModal.confirm") }}
+          </button>
         </div>
       </div>
     </div>
@@ -364,7 +420,8 @@ input:checked + .slider:before {
   font-size: 16px;
 }
 
-.modal-content input {
+.modal-content input,
+.modal-content select {
   padding: 8px 10px;
   background: var(--input-bg);
   border: 1px solid var(--input-border);
@@ -373,10 +430,22 @@ input:checked + .slider:before {
   outline: none;
 }
 
-.modal-content input:focus {
+.modal-content input:focus,
+.modal-content select:focus {
   border-color: var(--create-brass-primary);
 }
 
+.field-label {
+  font-size: 12px;
+  color: var(--text-muted);
+}
+
+.modal-hint {
+  margin: 0;
+  font-size: 12px;
+  color: var(--text-muted);
+}
+
 .modal-actions {
   display: flex;
   justify-content: flex-end;
@@ -410,6 +479,11 @@ input:checked + .slider:before {
   filter: brightness(1.1);
 }
 
+.btn-confirm:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
 /* ========== 底部输出 ========== */
 .output {
   margin-top: auto;

From daa05d484199933c8f675f40bb62304849092df0 Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Tue, 31 Mar 2026 22:07:53 +0800
Subject: [PATCH 21/28] =?UTF-8?q?chore:=20=E6=B7=BB=E5=8A=A0markdownlint?=
 =?UTF-8?q?=E9=85=8D=E7=BD=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .markdownlint.json                 | 3 +++
 docs/exec-plans/.markdownlint.json | 4 ++++
 2 files changed, 7 insertions(+)
 create mode 100644 .markdownlint.json
 create mode 100644 docs/exec-plans/.markdownlint.json

diff --git a/.markdownlint.json b/.markdownlint.json
new file mode 100644
index 0000000..900d8e0
--- /dev/null
+++ b/.markdownlint.json
@@ -0,0 +1,3 @@
+{
+  "default": true
+}
\ No newline at end of file
diff --git a/docs/exec-plans/.markdownlint.json b/docs/exec-plans/.markdownlint.json
new file mode 100644
index 0000000..66621ea
--- /dev/null
+++ b/docs/exec-plans/.markdownlint.json
@@ -0,0 +1,4 @@
+{
+  "MD013": false,
+  "MD028": false
+}
\ No newline at end of file

From 6217c96b5f30a9dd54b7f36beca1da1492ad542d Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Tue, 31 Mar 2026 22:19:14 +0800
Subject: [PATCH 22/28] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0plan=E4=B8=8ERe?=
 =?UTF-8?q?adme?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Readme.md                                     |  2 +-
 .../20260331-static-image-registry.md         | 46 +++++++++----------
 2 files changed, 24 insertions(+), 24 deletions(-)

diff --git a/Readme.md b/Readme.md
index e2a0aa7..bc0d782 100644
--- a/Readme.md
+++ b/Readme.md
@@ -12,7 +12,7 @@ task dev               # 一键启动前后端开发服务
 
 ### 镜像与模板
 
-- [ ] 静态镜像注册表（后端 JSON 配置）
+- [x] 静态镜像注册表（后端 JSON 配置）
 - [ ] 镜像市场前端页面（浏览、筛选、选用镜像）
 - [ ] 基于 YAML 的游戏模板规范设计
 - [ ] 模板解析引擎（根据模板自动生成 Docker 启动参数）
diff --git a/docs/exec-plans/completed/20260331-static-image-registry.md b/docs/exec-plans/completed/20260331-static-image-registry.md
index e34b61c..480fde2 100644
--- a/docs/exec-plans/completed/20260331-static-image-registry.md
+++ b/docs/exec-plans/completed/20260331-static-image-registry.md
@@ -274,29 +274,29 @@ func (h *RegistryHandler) GetImages(w http.ResponseWriter, r *http.Request) { ..
 
 ## 执行步骤
 
-- [ ] 后端 Model 层
-  - [ ] 新建 `backend/internal/model/registry.go`，定义 `RegistryImage` 结构体
-  - [ ] 修改 `backend/internal/model/errors.go`，新增 `ErrImageNotFound`
-- [ ] 后端注册表数据
-  - [ ] 新建 `backend/registry.json`，写入初始镜像条目
-- [ ] 后端 Service 层
-  - [ ] 新建 `backend/internal/service/registry_service.go`，实现 `RegistryService`
-  - [ ] 编写 `registry_service_test.go` 单元测试（加载合法/非法 JSON、按 ID 查询）
-  - [ ] 修改 `backend/internal/service/docker_service.go`：移除 `image` 字段和 `defaultImage` 常量、新增 `ImageRegistry` 接口依赖、更新 `CreateInstance` 签名
-- [ ] 后端 API 层
-  - [ ] 新建 `backend/internal/api/registry_handlers.go`，实现 `RegistryHandler`
-  - [ ] 修改 `backend/internal/api/handlers.go`：`createRequest` 增加 `ImageID`、`InstanceService` 接口同步更新
-  - [ ] 修改 `backend/internal/api/router.go`：注册 `GET /api/registry/images`
-  - [ ] 更新 `handlers_test.go`：适配新的 `CreateInstance` 签名
-- [ ] 后端入口
-  - [ ] 修改 `backend/main.go`：移除 `MINEDOCK_IMAGE`、初始化 `RegistryService`、注入 `DockerService`、创建 `RegistryHandler`
-- [ ] 前端适配
-  - [ ] 修改 `frontend/src/api/index.ts`：新增 `RegistryImage` 类型和 `listRegistryImages()` 函数、更新 `createInstance` 签名
-  - [ ] 新建 `frontend/src/stores/registry.ts`：镜像注册表 Pinia store
-  - [ ] 修改 `frontend/src/stores/containers.ts`：`create` action 增加 `imageId` 参数
-- [ ] 文档更新
-  - [ ] 修改 `docs/api/contracts.md`：新增 `GET /api/registry/images`、更新 `POST /api/instances`
-  - [ ] 修改 `docs/design-docs/instance_lifecycle.md`：补充 `ImageID` 字段
+- [x] 后端 Model 层
+  - [x] 新建 `backend/internal/model/registry.go`，定义 `RegistryImage` 结构体
+  - [x] 修改 `backend/internal/model/errors.go`，新增 `ErrImageNotFound`
+- [x] 后端注册表数据
+  - [x] 新建 `backend/registry.json`，写入初始镜像条目
+- [x] 后端 Service 层
+  - [x] 新建 `backend/internal/service/registry_service.go`，实现 `RegistryService`
+  - [x] 编写 `registry_service_test.go` 单元测试（加载合法/非法 JSON、按 ID 查询）
+  - [x] 修改 `backend/internal/service/docker_service.go`：移除 `image` 字段和 `defaultImage` 常量、新增 `ImageRegistry` 接口依赖、更新 `CreateInstance` 签名
+- [x] 后端 API 层
+  - [x] 新建 `backend/internal/api/registry_handlers.go`，实现 `RegistryHandler`
+  - [x] 修改 `backend/internal/api/handlers.go`：`createRequest` 增加 `ImageID`、`InstanceService` 接口同步更新
+  - [x] 修改 `backend/internal/api/router.go`：注册 `GET /api/registry/images`
+  - [x] 更新 `handlers_test.go`：适配新的 `CreateInstance` 签名
+- [x] 后端入口
+  - [x] 修改 `backend/main.go`：移除 `MINEDOCK_IMAGE`、初始化 `RegistryService`、注入 `DockerService`、创建 `RegistryHandler`
+- [x] 前端适配
+  - [x] 修改 `frontend/src/api/index.ts`：新增 `RegistryImage` 类型和 `listRegistryImages()` 函数、更新 `createInstance` 签名
+  - [x] 新建 `frontend/src/stores/registry.ts`：镜像注册表 Pinia store
+  - [x] 修改 `frontend/src/stores/containers.ts`：`create` action 增加 `imageId` 参数
+- [x] 文档更新
+  - [x] 修改 `docs/api/contracts.md`：新增 `GET /api/registry/images`、更新 `POST /api/instances`
+  - [x] 修改 `docs/design-docs/instance_lifecycle.md`：补充 `ImageID` 字段
 
 ## 已确认的决策
 

From 5ea7fb5b2466a7548f34ef395976e2a52c742b10 Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Wed, 1 Apr 2026 14:45:46 +0800
Subject: [PATCH 23/28] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E9=95=9C?=
 =?UTF-8?q?=E5=83=8F=E5=B8=82=E5=9C=BA=E5=89=8D=E7=AB=AF=E9=A1=B5=E9=9D=A2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Readme.md                                     |   3 +-
 .../20260331-image-marketplace-page.md        | 193 ++++++++++++
 docs/standards/frontend.md                    |   4 +-
 frontend/src/components/Sidebar.vue           |  16 +
 frontend/src/locales/en-US.json               |  10 +-
 frontend/src/locales/zh-CN.json               |  10 +-
 frontend/src/router/index.ts                  |   5 +
 frontend/src/stores/registry.ts               |  63 +++-
 frontend/src/views/ContainerList.vue          |  50 ++-
 frontend/src/views/ImageRegistry.vue          | 287 ++++++++++++++++++
 10 files changed, 627 insertions(+), 14 deletions(-)
 create mode 100644 docs/exec-plans/completed/20260331-image-marketplace-page.md
 create mode 100644 frontend/src/views/ImageRegistry.vue

diff --git a/Readme.md b/Readme.md
index bc0d782..0397bc2 100644
--- a/Readme.md
+++ b/Readme.md
@@ -13,13 +13,14 @@ task dev               # 一键启动前后端开发服务
 ### 镜像与模板
 
 - [x] 静态镜像注册表（后端 JSON 配置）
-- [ ] 镜像市场前端页面（浏览、筛选、选用镜像）
+- [x] 镜像市场前端页面（浏览、筛选、选用镜像）
 - [ ] 基于 YAML 的游戏模板规范设计
 - [ ] 模板解析引擎（根据模板自动生成 Docker 启动参数）
 
 ### 实例生命周期
 
 - [x] 容器基础生命周期：创建、删除、开启、停止
+- [ ] 容器运行状态实时同步
 - [ ] 创建容器时支持镜像选择
 - [ ] 创建容器时支持环境变量注入
 - [ ] 创建容器时支持 Volume 持久化目录挂载
diff --git a/docs/exec-plans/completed/20260331-image-marketplace-page.md b/docs/exec-plans/completed/20260331-image-marketplace-page.md
new file mode 100644
index 0000000..11514a6
--- /dev/null
+++ b/docs/exec-plans/completed/20260331-image-marketplace-page.md
@@ -0,0 +1,193 @@
+# 镜像市场前端页面
+
+## 背景
+
+静态镜像注册表后端已实现（`GET /api/registry/images`、`POST /api/instances` 需要 `image_id`）。前端 API 层（`listRegistryImages()`）和 Pinia store（`useRegistryStore`）也已就绪。当前创建容器时通过 `ContainerList.vue` 弹窗内的下拉框选择镜像，但缺少一个独立的**镜像市场页面**让用户直观浏览、筛选、选用镜像。
+
+本计划实现 `/registry` 路由下的镜像市场页面，作为发现和选用镜像的主入口。
+
+## 需要评审的内容
+
+> [!IMPORTANT]
+> **镜像市场 → 创建容器的交互流程**
+>
+> 用户在镜像市场**直接点击整张游戏卡片**，使用 Vue Router 跳转到容器列表页 `/`，并通过 query 参数 `?imageId=minecraft-java` 传递预选镜像。`ContainerList.vue` 检测到该参数后自动弹出创建弹窗并预填镜像。
+>
+> 卡片上不设独立的「选用」按钮，卡片本身即为点击入口，交互更简洁直接。
+
+> [!IMPORTANT]
+> **按 category 筛选**
+>
+> 镜像卡片支持按 `category` 筛选。筛选栏提供「全部」及各 `category`（从后端数据动态提取）选项卡。当前 registry.json 中有 `minecraft` 和 `sandbox` 两个分类。
+
+## 拟定更改
+
+### 路由
+
+#### [MODIFY] index.ts (`frontend/src/router/index.ts`)
+
+- 新增路由 `/registry`，路由名 `ImageRegistry`，懒加载 `views/ImageRegistry.vue`
+
+---
+
+### 视图层
+
+#### [NEW] ImageRegistry.vue (`frontend/src/views/ImageRegistry.vue`)
+
+**镜像市场页面**，页面结构：
+
+```text
+┌─────────────────────────────────────────┐
+│ page-header: "镜像市场" 标题            │
+├─────────────────────────────────────────┤
+│ 筛选栏: [全部] [minecraft] [sandbox]    │
+├─────────────────────────────────────────┤
+│ ┌─────────┐ ┌─────────┐ ┌─────────┐   │
+│ │  ⛏️     │ │  ⛏️     │ │  🌳    │   │
+│ │ MC Java │ │ MC 基岩 │ │ 泰拉瑞亚│   │
+│ │ 描述... │ │ 描述... │ │ 描述... │   │
+│ │ minecraft│ │ minecraft│ │ sandbox │   │
+│ └─────────┘ └─────────┘ └─────────┘   │
+│   (整张卡片可点击 → 跳转创建容器)       │
+│                                         │
+│ 空状态 / 加载中 提示                    │
+└─────────────────────────────────────────┘
+```
+
+关键技术细节：
+
+- **数据来源**：使用 `useRegistryStore`，`onMounted` 时调用 `fetchImages()`
+- **分类筛选**：`computed` 动态提取所有 category，`selectedCategory` ref 控制当前筛选项，`filteredImages` computed 过滤结果
+- **图标方案**：前端维护 `icon → emoji` 映射表（如 `minecraft-java → ⛏️`，`minecraft-bedrock → ⛏️`，`terraria → 🌳`），未匹配时回退到名称首字母
+- **卡片展示**：每张卡片作为一个完整的游戏入口，展示 emoji 图标、`name`（游戏名称）、`description`（简介，可截断为 2~3 行）、`category` 分类徽标。**不显示**端口列表、环境变量、选用按钮
+- **卡片点击**：整张卡片可点击，`cursor: pointer` + hover 反馈，点击执行 `router.push({ name: 'ContainerList', query: { imageId: image.id } })`
+- **空状态**：无镜像时显示空状态提示
+- **加载态**：`registryStore.loading` 为 `true` 时展示加载占位
+- **样式**：遵循 Create 主题 CSS 变量体系，卡片复用 `--card-*` 系列变量，响应式网格布局（桌面 3 列，平板 2 列，手机 1 列）
+
+#### [MODIFY] ContainerList.vue (`frontend/src/views/ContainerList.vue`)
+
+- `onMounted` 中检测 `route.query.imageId`，若存在：
+  - 等待 `registryStore.fetchImages()` 完成
+  - 校验 imageId 在注册表中存在
+  - 设置 `selectedImageId` 为该值
+  - 自动打开创建弹窗
+  - 清除 URL query 参数（`router.replace({ query: {} })`）防止刷新重触发
+
+---
+
+### 侧边栏
+
+#### [MODIFY] Sidebar.vue (`frontend/src/components/Sidebar.vue`)
+
+- 在「容器列表」菜单项下方新增「镜像市场」菜单项
+- 路由指向 `/registry`
+- 图标使用网格/市场风格 SVG（4 格方块或拼图图标）
+- 移动端和桌面端菜单同步新增
+
+---
+
+### 国际化
+
+#### [MODIFY] zh-CN.json (`frontend/src/locales/zh-CN.json`)
+
+新增翻译 key：
+
+```json
+{
+  "registry": {
+    "title": "镜像市场",
+    "filterAll": "全部",
+    "emptyState": "暂无可用镜像。",
+    "loading": "正在加载镜像列表...",
+    "loadError": "镜像列表加载失败，请稍后重试。"
+  },
+  "sidebar": {
+    "imageRegistry": "镜像市场"
+  }
+}
+```
+
+#### [MODIFY] en-US.json (`frontend/src/locales/en-US.json`)
+
+```json
+{
+  "registry": {
+    "title": "Image Marketplace",
+    "filterAll": "All",
+    "emptyState": "No images available.",
+    "loading": "Loading image list...",
+    "loadError": "Failed to load image list. Please try again later."
+  },
+  "sidebar": {
+    "imageRegistry": "Images"
+  }
+}
+```
+
+---
+
+### Store 层（可选增强）
+
+#### [MODIFY] registry.ts (`frontend/src/stores/registry.ts`)
+
+- 新增 `categories` computed getter：从 `images` 中提取去重的 category 列表
+- 新增 `error` ref：`fetchImages` 失败时记录错误状态，视图层据此渲染错误提示
+
+---
+
+### 文档
+
+#### [MODIFY] frontend.md (`docs/standards/frontend.md`)
+
+- 更新路由表：新增 `/registry` → `ImageRegistry.vue` 说明
+
+---
+
+## 执行步骤
+
+- [x] Store 层增强
+  - [x] 修改 `frontend/src/stores/registry.ts`：新增 `categories` computed 和 `error` ref
+- [x] 路由注册
+  - [x] 修改 `frontend/src/router/index.ts`：新增 `/registry` 路由（懒加载）
+- [x] 镜像市场页面
+  - [x] 新建 `frontend/src/views/ImageRegistry.vue`
+  - [x] 实现页面标题区（复用 `.page-header` / `.page-title` 样式模式）
+  - [x] 实现分类筛选栏（category tabs）
+  - [x] 实现镜像卡片网格（响应式 grid）
+  - [x] 实现卡片内容：emoji 图标、名称、描述、分类徽标
+  - [x] 实现加载态和空状态
+  - [x] 实现整张卡片点击 → 跳转到容器列表页并传入 `imageId` query
+- [x] 容器列表页适配
+  - [x] 修改 `frontend/src/views/ContainerList.vue`：检测 `route.query.imageId`，自动预填镜像并弹出创建弹窗
+- [x] 侧边栏更新
+  - [x] 修改 `frontend/src/components/Sidebar.vue`：添加「镜像市场」导航项（桌面端 + 移动端）
+- [x] 国际化
+  - [x] 修改 `frontend/src/locales/zh-CN.json`：新增 `registry.*` 和 `sidebar.imageRegistry`
+  - [x] 修改 `frontend/src/locales/en-US.json`：同步英文翻译
+- [x] 文档
+  - [x] 修改 `docs/standards/frontend.md`：更新路由说明
+
+## 已确认的决策
+
+- ✅ 镜像图标方案：Emoji / Unicode 映射（`minecraft-java → ⛏️`，`minecraft-bedrock → ⛏️`，`terraria → 🌳`），未匹配时回退首字母
+- ✅ 卡片只展示：emoji 图标 + 游戏名称 + 描述 + 分类徽标
+- ✅ 不显示：端口列表、环境变量、独立选用按钮
+- ✅ 整张卡片可点击，直接跳转到创建容器流程
+
+## 验证计划
+
+### 自动化测试
+
+- 前端：`npm run lint`（ESLint + Prettier + TypeScript 检查）
+
+### 手动验证
+
+- 启动前后端，在侧边栏点击「镜像市场」，验证页面正常渲染
+- 验证分类筛选栏：点击各分类 tab，卡片正确过滤
+- 验证卡片点击：点击整张卡片后跳转到容器列表页，创建弹窗自动弹出且镜像已预填
+- 创建弹窗内完成创建，验证容器使用了预选的镜像
+- 手动刷新 `/registry` 页面，验证数据正常重新加载
+- 验证响应式布局：桌面端 3 列 → 平板 2 列 → 手机 1 列
+- 验证 i18n：切换中英文，所有新增文案正确显示
+- 验证空状态：后端返回空数组时，页面展示友好提示
diff --git a/docs/standards/frontend.md b/docs/standards/frontend.md
index d2904af..3702197 100644
--- a/docs/standards/frontend.md
+++ b/docs/standards/frontend.md
@@ -67,7 +67,9 @@
 
 ## 6. 路由与鉴权
 
-- 当前仅包含基础路由 `/`，映射容器列表页。
+- 当前路由：
+  - `/` 映射容器列表页（`ContainerList.vue`）
+  - `/registry` 映射镜像市场页（`ImageRegistry.vue`）
 - 当前版本无登录鉴权。
 - 新增页面时要求：
   - 在 `router/index.ts` 显式注册路由
diff --git a/frontend/src/components/Sidebar.vue b/frontend/src/components/Sidebar.vue
index f379614..57e0537 100644
--- a/frontend/src/components/Sidebar.vue
+++ b/frontend/src/components/Sidebar.vue
@@ -30,6 +30,14 @@ const isOpen = ref<boolean>(false);
           </div>
           <div class="menu-text">{{ $t("sidebar.containerList") }}</div>
         </RouterLink>
+        <RouterLink to="/registry" class="menu-item">
+          <div class="menu-icon">
+            <svg viewBox="0 0 24 24" fill="currentColor">
+              <path d="M4 4h7v7H4zM13 4h7v7h-7zM4 13h7v7H4zM13 13h7v7h-7z" />
+            </svg>
+          </div>
+          <div class="menu-text">{{ $t("sidebar.imageRegistry") }}</div>
+        </RouterLink>
       </div>
     </aside>
   </Transition>
@@ -54,6 +62,14 @@ const isOpen = ref<boolean>(false);
         </div>
         <div class="menu-text">{{ $t("sidebar.containerList") }}</div>
       </RouterLink>
+      <RouterLink to="/registry" class="menu-item">
+        <div class="menu-icon">
+          <svg viewBox="0 0 24 24" fill="currentColor">
+            <path d="M4 4h7v7H4zM13 4h7v7h-7zM4 13h7v7H4zM13 13h7v7h-7z" />
+          </svg>
+        </div>
+        <div class="menu-text">{{ $t("sidebar.imageRegistry") }}</div>
+      </RouterLink>
     </div>
   </aside>
 </template>
diff --git a/frontend/src/locales/en-US.json b/frontend/src/locales/en-US.json
index 3915270..2c9d085 100644
--- a/frontend/src/locales/en-US.json
+++ b/frontend/src/locales/en-US.json
@@ -46,7 +46,15 @@
     "unknown": "An unknown error occurred. Please try again later."
   },
   "sidebar": {
-    "containerList": "Containers"
+    "containerList": "Containers",
+    "imageRegistry": "Images"
+  },
+  "registry": {
+    "title": "Image Marketplace",
+    "filterAll": "All",
+    "emptyState": "No images available.",
+    "loading": "Loading image list...",
+    "loadError": "Failed to load image list. Please try again later."
   },
   "topbar": {
     "switchLanguage": "Switch Language",
diff --git a/frontend/src/locales/zh-CN.json b/frontend/src/locales/zh-CN.json
index 8bb8c4c..01cb977 100644
--- a/frontend/src/locales/zh-CN.json
+++ b/frontend/src/locales/zh-CN.json
@@ -46,7 +46,15 @@
     "unknown": "发生未知错误，请稍后重试。"
   },
   "sidebar": {
-    "containerList": "容器列表"
+    "containerList": "容器列表",
+    "imageRegistry": "镜像市场"
+  },
+  "registry": {
+    "title": "镜像市场",
+    "filterAll": "全部",
+    "emptyState": "暂无可用镜像。",
+    "loading": "正在加载镜像列表...",
+    "loadError": "镜像列表加载失败，请稍后重试。"
   },
   "topbar": {
     "switchLanguage": "切换语言",
diff --git a/frontend/src/router/index.ts b/frontend/src/router/index.ts
index e276063..78059f3 100644
--- a/frontend/src/router/index.ts
+++ b/frontend/src/router/index.ts
@@ -9,6 +9,11 @@ const router = createRouter({
       name: "ContainerList",
       component: ContainerList,
     },
+    {
+      path: "/registry",
+      name: "ImageRegistry",
+      component: () => import("../views/ImageRegistry.vue"),
+    },
   ],
 });
 
diff --git a/frontend/src/stores/registry.ts b/frontend/src/stores/registry.ts
index c438f38..184b00e 100644
--- a/frontend/src/stores/registry.ts
+++ b/frontend/src/stores/registry.ts
@@ -1,19 +1,65 @@
-import { ref } from "vue";
+import { computed, ref } from "vue";
 import { defineStore } from "pinia";
 import type { RegistryImage } from "../api/index";
 import { listRegistryImages } from "../api/index";
 
+const DEFAULT_CACHE_WINDOW_MS = 60_000;
+
+type FetchImagesOptions = {
+  force?: boolean;
+  cacheWindowMs?: number;
+};
+
 export const useRegistryStore = defineStore("registry", () => {
   const images = ref<RegistryImage[]>([]);
   const loading = ref(false);
+  const error = ref<unknown>(null);
+  const hasFetched = ref(false);
+  const fetchedAt = ref<number>(0);
+  let inflightRequest: Promise<void> | null = null;
 
-  async function fetchImages(): Promise<void> {
-    loading.value = true;
-    try {
-      images.value = await listRegistryImages();
-    } finally {
-      loading.value = false;
+  const categories = computed<string[]>(() => {
+    const values = new Set<string>();
+    for (const image of images.value) {
+      const category = image.category?.trim();
+      if (category) {
+        values.add(category);
+      }
+    }
+    return Array.from(values);
+  });
+
+  async function fetchImages(options: FetchImagesOptions = {}): Promise<void> {
+    const { force = false, cacheWindowMs = DEFAULT_CACHE_WINDOW_MS } = options;
+    const cacheAge = Date.now() - fetchedAt.value;
+    const canUseCache = hasFetched.value && cacheAge < cacheWindowMs;
+
+    if (!force && canUseCache) {
+      return;
     }
+
+    if (inflightRequest) {
+      return inflightRequest;
+    }
+
+    loading.value = true;
+    error.value = null;
+
+    inflightRequest = (async () => {
+      try {
+        images.value = await listRegistryImages();
+        hasFetched.value = true;
+        fetchedAt.value = Date.now();
+      } catch (err) {
+        error.value = err;
+        throw err;
+      } finally {
+        loading.value = false;
+        inflightRequest = null;
+      }
+    })();
+
+    return inflightRequest;
   }
 
   function getById(id: string): RegistryImage | undefined {
@@ -27,6 +73,9 @@ export const useRegistryStore = defineStore("registry", () => {
   return {
     images,
     loading,
+    error,
+    hasFetched,
+    categories,
     fetchImages,
     getById,
   };
diff --git a/frontend/src/views/ContainerList.vue b/frontend/src/views/ContainerList.vue
index a11ac59..adec7e0 100644
--- a/frontend/src/views/ContainerList.vue
+++ b/frontend/src/views/ContainerList.vue
@@ -1,10 +1,13 @@
 <script setup lang="ts">
 import { computed, ref, onMounted } from "vue";
+import { useRoute, useRouter } from "vue-router";
 import { useI18n } from "vue-i18n";
 import { useContainerStore } from "../stores/containers";
 import { useRegistryStore } from "../stores/registry";
 
 const { t } = useI18n();
+const route = useRoute();
+const router = useRouter();
 const store = useContainerStore();
 const registryStore = useRegistryStore();
 
@@ -38,15 +41,54 @@ function openCreateModal(): void {
   ensureDefaultImageSelection();
 }
 
+function getImageIdFromQuery(): string {
+  const raw = route.query.imageId;
+  if (Array.isArray(raw)) {
+    return typeof raw[0] === "string" ? raw[0].trim() : "";
+  }
+  return typeof raw === "string" ? raw.trim() : "";
+}
+
+function preselectImageFromQuery(imageId: string): void {
+  const image = registryStore.getById(imageId);
+  if (!image) {
+    store.printErrorKey("errors.imageNotFound");
+    return;
+  }
+
+  selectedImageId.value = image.id;
+  openCreateModal();
+}
+
+async function clearImageIdQuery(): Promise<void> {
+  const nextQuery = { ...route.query };
+  delete nextQuery.imageId;
+  await router.replace({ path: route.path, query: nextQuery });
+}
+
 // 页面启动时统一触发列表拉取，并输出首屏可读状态。
 async function initializeList(): Promise<void> {
   store.print(t("status.waiting"));
+  const imageIdFromQuery = getImageIdFromQuery();
+
+  // 已有缓存时优先弹窗，避免从市场页回跳后再次等待网络。
+  if (imageIdFromQuery && registryStore.getById(imageIdFromQuery)) {
+    preselectImageFromQuery(imageIdFromQuery);
+  }
 
   try {
     await registryStore.fetchImages();
     ensureDefaultImageSelection();
+
+    if (imageIdFromQuery && !showCreateModal.value) {
+      preselectImageFromQuery(imageIdFromQuery);
+    }
   } catch (err) {
     store.printError(err);
+  } finally {
+    if (imageIdFromQuery) {
+      await clearImageIdQuery();
+    }
   }
 
   const success = await store.fetchInstances();
@@ -164,14 +206,16 @@ async function handleToggle(instance: {
         <select
           id="image-select"
           v-model="selectedImageId"
-          :disabled="registryStore.loading || registryStore.images.length === 0"
+          :disabled="registryStore.images.length === 0"
         >
           <option value="" disabled>{{ $t("createModal.imagePlaceholder") }}</option>
           <option v-for="image in registryStore.images" :key="image.id" :value="image.id">
             {{ image.name }}
           </option>
         </select>
-        <p v-if="registryStore.loading" class="modal-hint">{{ $t("createModal.loadingImages") }}</p>
+        <p v-if="registryStore.loading && registryStore.images.length === 0" class="modal-hint">
+          {{ $t("createModal.loadingImages") }}
+        </p>
         <p v-else-if="registryStore.images.length === 0" class="modal-hint">
           {{ $t("createModal.noImages") }}
         </p>
@@ -184,7 +228,7 @@ async function handleToggle(instance: {
           </button>
           <button
             class="btn-confirm"
-            :disabled="registryStore.loading || registryStore.images.length === 0"
+            :disabled="registryStore.images.length === 0"
             @click="handleCreate"
           >
             {{ $t("createModal.confirm") }}
diff --git a/frontend/src/views/ImageRegistry.vue b/frontend/src/views/ImageRegistry.vue
new file mode 100644
index 0000000..82b846c
--- /dev/null
+++ b/frontend/src/views/ImageRegistry.vue
@@ -0,0 +1,287 @@
+<script setup lang="ts">
+import { computed, onMounted, ref, watch } from "vue";
+import { useRouter } from "vue-router";
+import { useI18n } from "vue-i18n";
+import type { RegistryImage } from "../api/index";
+import { useRegistryStore } from "../stores/registry";
+
+const router = useRouter();
+const { t } = useI18n();
+const registryStore = useRegistryStore();
+
+const ALL_CATEGORY = "__all__";
+
+const iconEmojiMap: Record<string, string> = {
+  "minecraft-java": "\u26CF\uFE0F",
+  "minecraft-bedrock": "\u26CF\uFE0F",
+  terraria: "\uD83C\uDF33",
+};
+
+const selectedCategory = ref(ALL_CATEGORY);
+
+const categoryTabs = computed(() => {
+  return [
+    { key: ALL_CATEGORY, label: t("registry.filterAll") },
+    ...registryStore.categories.map((category) => ({ key: category, label: category })),
+  ];
+});
+
+const filteredImages = computed(() => {
+  if (selectedCategory.value === ALL_CATEGORY) {
+    return registryStore.images;
+  }
+  return registryStore.images.filter((image) => image.category === selectedCategory.value);
+});
+
+watch(categoryTabs, (tabs) => {
+  if (!tabs.some((tab) => tab.key === selectedCategory.value)) {
+    selectedCategory.value = ALL_CATEGORY;
+  }
+});
+
+onMounted(() => {
+  void loadImages();
+});
+
+async function loadImages(): Promise<void> {
+  try {
+    await registryStore.fetchImages();
+  } catch {
+    // error state is captured by registry store and rendered by the view.
+  }
+}
+
+function getImageEmoji(image: RegistryImage): string {
+  const mapped = iconEmojiMap[image.icon];
+  if (mapped) {
+    return mapped;
+  }
+  const fallback = image.name.trim().charAt(0);
+  return fallback ? fallback.toUpperCase() : "?";
+}
+
+function selectImage(imageId: string): void {
+  void router.push({
+    name: "ContainerList",
+    query: { imageId },
+  });
+}
+</script>
+
+<template>
+  <header class="page-header">
+    <h1 class="page-title">{{ $t("registry.title") }}</h1>
+  </header>
+
+  <main class="main-content">
+    <div class="filter-tabs" role="tablist" aria-label="Category filter">
+      <button
+        v-for="tab in categoryTabs"
+        :key="tab.key"
+        class="filter-tab"
+        :class="{ 'is-active': selectedCategory === tab.key }"
+        type="button"
+        role="tab"
+        :aria-selected="selectedCategory === tab.key"
+        @click="selectedCategory = tab.key"
+      >
+        {{ tab.label }}
+      </button>
+    </div>
+
+    <div v-if="registryStore.loading && registryStore.images.length === 0" class="state-message">
+      {{ $t("registry.loading") }}
+    </div>
+    <div
+      v-else-if="registryStore.error && registryStore.images.length === 0"
+      class="state-message state-error"
+    >
+      {{ $t("registry.loadError") }}
+    </div>
+    <div v-else-if="filteredImages.length === 0" class="state-message">
+      {{ $t("registry.emptyState") }}
+    </div>
+    <section v-else class="image-grid">
+      <button
+        v-for="image in filteredImages"
+        :key="image.id"
+        class="image-card"
+        type="button"
+        @click="selectImage(image.id)"
+      >
+        <div class="image-icon">{{ getImageEmoji(image) }}</div>
+        <div class="image-name">{{ image.name }}</div>
+        <p class="image-description">{{ image.description }}</p>
+        <span class="category-badge">{{ image.category }}</span>
+      </button>
+    </section>
+  </main>
+</template>
+
+<style scoped>
+.page-header {
+  height: var(--header-height);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+
+.page-title {
+  margin: 0;
+  color: var(--create-brass-primary);
+  font-size: 16px;
+  font-weight: bold;
+  letter-spacing: 2px;
+  font-family: "Segoe UI", "PingFang SC", sans-serif;
+}
+
+.main-content {
+  padding: 8px 24px 24px 24px;
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  max-width: 1200px;
+  margin: 0 auto;
+  width: 100%;
+  gap: 16px;
+}
+
+.filter-tabs {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+}
+
+.filter-tab {
+  border: 1px solid var(--create-border-outer);
+  background: rgba(0, 0, 0, 0.15);
+  color: var(--create-brass-primary);
+  padding: 6px 14px;
+  border-radius: 999px;
+  cursor: pointer;
+  font-size: 13px;
+  transition: all 0.2s ease;
+}
+
+.filter-tab:hover {
+  background: rgba(0, 0, 0, 0.3);
+}
+
+.filter-tab.is-active {
+  background: var(--create-brass-dark);
+  color: var(--card-text);
+  border-color: var(--create-brass-secondary);
+}
+
+.state-message {
+  text-align: center;
+  color: var(--text-muted);
+  border: 1px dashed var(--border-muted);
+  border-radius: 8px;
+  padding: 40px 16px;
+}
+
+.state-error {
+  color: var(--danger);
+  border-color: rgba(255, 77, 79, 0.5);
+  background: var(--danger-light);
+}
+
+.image-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 16px;
+}
+
+.image-card {
+  text-align: left;
+  border: 3px solid var(--card-border);
+  background: var(--card-bg);
+  color: var(--card-text);
+  border-radius: 0;
+  padding: 16px;
+  min-height: 220px;
+  cursor: pointer;
+  box-shadow:
+    inset 0 3px 0 0 var(--card-bg),
+    inset 0 -3px 0 0 var(--card-bg),
+    inset 0 6px 0 0 var(--card-border-inner),
+    inset 0 -6px 0 0 var(--card-border-inner);
+  clip-path: polygon(
+    0 3px,
+    3px 3px,
+    3px 0,
+    calc(100% - 3px) 0,
+    calc(100% - 3px) 3px,
+    100% 3px,
+    100% calc(100% - 3px),
+    calc(100% - 3px) calc(100% - 3px),
+    calc(100% - 3px) 100%,
+    3px 100%,
+    3px calc(100% - 3px),
+    0 calc(100% - 3px)
+  );
+  transition:
+    transform 0.2s ease,
+    filter 0.2s ease;
+}
+
+.image-card:hover {
+  transform: translateY(-2px);
+  filter: brightness(0.97);
+}
+
+.image-icon {
+  font-size: 32px;
+  margin-bottom: 12px;
+}
+
+.image-name {
+  font-size: 17px;
+  font-weight: 700;
+  margin-bottom: 8px;
+}
+
+.image-description {
+  margin: 0 0 16px;
+  color: #3b3b3b;
+  font-size: 13px;
+  line-height: 1.5;
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+.category-badge {
+  display: inline-block;
+  margin-top: auto;
+  font-size: 12px;
+  color: var(--create-brass-primary);
+  background: var(--create-border-dark);
+  border: 1px solid var(--create-border-outer);
+  border-radius: 999px;
+  padding: 3px 10px;
+}
+
+@media (max-width: 1023px) {
+  .page-title {
+    display: none;
+  }
+
+  .image-grid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+@media (max-width: 767px) {
+  .main-content {
+    padding: 8px 16px 20px 16px;
+  }
+
+  .image-grid {
+    grid-template-columns: 1fr;
+  }
+}
+</style>

From 2d12a42b77d6e3145f14575ab2db3d80508a7987 Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Wed, 1 Apr 2026 17:57:06 +0800
Subject: [PATCH 24/28] =?UTF-8?q?feat:=20=E5=AE=9E=E7=8E=B0=E5=AE=B9?=
 =?UTF-8?q?=E5=99=A8=E8=BF=90=E8=A1=8C=E7=8A=B6=E6=80=81=E5=AE=9E=E6=97=B6?=
 =?UTF-8?q?=E5=90=8C=E6=AD=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Readme.md                                     |   2 +-
 backend/go.mod                                |   1 +
 backend/go.sum                                |   2 +
 backend/internal/api/handlers_test.go         |   4 +-
 backend/internal/api/router.go                |  15 +-
 backend/internal/api/ws_handler.go            |  46 +++
 backend/internal/api/ws_handler_test.go       |  85 +++++
 backend/internal/service/event_hub.go         | 317 +++++++++++++++++
 backend/internal/service/event_hub_test.go    | 175 ++++++++++
 backend/main.go                               |  10 +-
 docs/api/contracts.md                         |  17 +
 docs/design-docs/instance_lifecycle.md        |   3 +-
 .../active/20260401-realtime-status-sync.md   | 330 ++++++++++++++++++
 frontend/src/api/index.ts                     |  18 +
 frontend/src/components/TopBar.vue            | 101 ++++--
 frontend/src/composables/useInstanceSync.ts   | 178 ++++++++++
 frontend/src/locales/en-US.json               |   2 +
 frontend/src/locales/zh-CN.json               |   2 +
 frontend/src/stores/containers.ts             |  38 +-
 frontend/src/views/ContainerList.vue          |   9 +-
 frontend/vite.config.js                       |  10 +-
 21 files changed, 1324 insertions(+), 41 deletions(-)
 create mode 100644 backend/internal/api/ws_handler.go
 create mode 100644 backend/internal/api/ws_handler_test.go
 create mode 100644 backend/internal/service/event_hub.go
 create mode 100644 backend/internal/service/event_hub_test.go
 create mode 100644 docs/exec-plans/active/20260401-realtime-status-sync.md
 create mode 100644 frontend/src/composables/useInstanceSync.ts

diff --git a/Readme.md b/Readme.md
index 0397bc2..b684028 100644
--- a/Readme.md
+++ b/Readme.md
@@ -20,7 +20,7 @@ task dev               # 一键启动前后端开发服务
 ### 实例生命周期
 
 - [x] 容器基础生命周期：创建、删除、开启、停止
-- [ ] 容器运行状态实时同步
+- [x] 容器运行状态实时同步
 - [ ] 创建容器时支持镜像选择
 - [ ] 创建容器时支持环境变量注入
 - [ ] 创建容器时支持 Volume 持久化目录挂载
diff --git a/backend/go.mod b/backend/go.mod
index 880d95e..1a2c65b 100644
--- a/backend/go.mod
+++ b/backend/go.mod
@@ -3,6 +3,7 @@ module minedock/backend
 go 1.25.0
 
 require (
+	github.com/coder/websocket v1.8.14
 	github.com/docker/docker v28.0.1+incompatible
 	modernc.org/sqlite v1.47.0
 )
diff --git a/backend/go.sum b/backend/go.sum
index 3064815..9361e19 100644
--- a/backend/go.sum
+++ b/backend/go.sum
@@ -6,6 +6,8 @@ github.com/cenkalti/backoff/v5 v5.0.3 h1:ZN+IMa753KfX5hd8vVaMixjnqRZ3y8CuJKRKj1x
 github.com/cenkalti/backoff/v5 v5.0.3/go.mod h1:rkhZdG3JZukswDf7f0cwqPNk4K0sa+F97BxZthm/crw=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/coder/websocket v1.8.14 h1:9L0p0iKiNOibykf283eHkKUHHrpG7f65OE3BhhO7v9g=
+github.com/coder/websocket v1.8.14/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg=
 github.com/containerd/log v0.1.0 h1:TCJt7ioM2cr/tfR8GPbGf9/VRAX8D2B4PjzCpfX540I=
 github.com/containerd/log v0.1.0/go.mod h1:VRRf09a7mHDIRezVKTRCrOq78v577GXq3bSa3EhrzVo=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
diff --git a/backend/internal/api/handlers_test.go b/backend/internal/api/handlers_test.go
index 508ea2d..68f5783 100644
--- a/backend/internal/api/handlers_test.go
+++ b/backend/internal/api/handlers_test.go
@@ -54,7 +54,7 @@ func newTestRouter(m *mockService) http.Handler {
 			return []model.RegistryImage{}
 		},
 	})
-	return NewRouter(h, rh)
+	return NewRouter(h, rh, nil)
 }
 
 // --- GET /api/instances 场景 ---
@@ -108,7 +108,7 @@ func TestGetRegistryImages_Success(t *testing.T) {
 			return []model.RegistryImage{{ID: "minecraft-java", Image: "itzg/minecraft-server:latest"}}
 		},
 	})
-	router := NewRouter(h, rh)
+	router := NewRouter(h, rh, nil)
 
 	w := httptest.NewRecorder()
 	r := httptest.NewRequest(http.MethodGet, "/api/registry/images", nil)
diff --git a/backend/internal/api/router.go b/backend/internal/api/router.go
index d73bc2c..b69b3bb 100644
--- a/backend/internal/api/router.go
+++ b/backend/internal/api/router.go
@@ -1,9 +1,12 @@
 package api
 
-import "net/http"
+import (
+	"net/http"
+	"strings"
+)
 
 // NewRouter 注册 API 路由并包装中间件。
-func NewRouter(h *Handler, registry *RegistryHandler) http.Handler {
+func NewRouter(h *Handler, registry *RegistryHandler, ws *WsHandler) http.Handler {
 	mux := http.NewServeMux()
 
 	mux.HandleFunc("GET /api/instances", h.GetInstances)
@@ -11,6 +14,9 @@ func NewRouter(h *Handler, registry *RegistryHandler) http.Handler {
 	mux.HandleFunc("POST /api/instances/{id}/start", h.StartInstance)
 	mux.HandleFunc("POST /api/instances/{id}/stop", h.StopInstance)
 	mux.HandleFunc("DELETE /api/instances/{id}", h.DeleteInstance)
+	if ws != nil {
+		mux.HandleFunc("GET /api/ws/events", ws.HandleEvents)
+	}
 	if registry != nil {
 		mux.HandleFunc("GET /api/registry/images", registry.GetImages)
 	}
@@ -21,6 +27,11 @@ func NewRouter(h *Handler, registry *RegistryHandler) http.Handler {
 // withCORS 添加宽松的 CORS 响应头并处理 OPTIONS 预检请求。
 func withCORS(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if strings.HasPrefix(r.URL.Path, "/api/ws/") {
+			next.ServeHTTP(w, r)
+			return
+		}
+
 		w.Header().Set("Access-Control-Allow-Origin", "*")
 		w.Header().Set("Access-Control-Allow-Methods", "GET,POST,DELETE,OPTIONS")
 		w.Header().Set("Access-Control-Allow-Headers", "Content-Type")
diff --git a/backend/internal/api/ws_handler.go b/backend/internal/api/ws_handler.go
new file mode 100644
index 0000000..7c53a9d
--- /dev/null
+++ b/backend/internal/api/ws_handler.go
@@ -0,0 +1,46 @@
+package api
+
+import (
+	"net/http"
+
+	"github.com/coder/websocket"
+)
+
+// EventBroadcaster 定义 WebSocket Handler 依赖的事件广播操作。
+type EventBroadcaster interface {
+	AddClient(conn *websocket.Conn)
+	RemoveClient(conn *websocket.Conn)
+}
+
+// WsHandler 暴露 WebSocket 相关 HTTP 处理器。
+type WsHandler struct {
+	hub EventBroadcaster
+}
+
+// NewWsHandler 创建 WsHandler。
+func NewWsHandler(hub EventBroadcaster) *WsHandler {
+	return &WsHandler{hub: hub}
+}
+
+// HandleEvents 处理 GET /api/ws/events，将 HTTP 连接升级为 WebSocket。
+func (h *WsHandler) HandleEvents(w http.ResponseWriter, r *http.Request) {
+	if h == nil || h.hub == nil {
+		writeJSON(w, http.StatusServiceUnavailable, statusResponse{Status: "error", Error: "event hub unavailable"})
+		return
+	}
+
+	// 仅支持同源 WebSocket，保持默认 Origin 校验行为。
+	conn, err := websocket.Accept(w, r, &websocket.AcceptOptions{})
+	if err != nil {
+		return
+	}
+
+	h.hub.AddClient(conn)
+	defer h.hub.RemoveClient(conn)
+
+	for {
+		if _, _, err := conn.Read(r.Context()); err != nil {
+			return
+		}
+	}
+}
diff --git a/backend/internal/api/ws_handler_test.go b/backend/internal/api/ws_handler_test.go
new file mode 100644
index 0000000..504f44d
--- /dev/null
+++ b/backend/internal/api/ws_handler_test.go
@@ -0,0 +1,85 @@
+package api
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/coder/websocket"
+)
+
+type mockEventBroadcaster struct {
+	mu          sync.Mutex
+	addCount    int
+	removeCount int
+	addCh       chan struct{}
+	removeCh    chan struct{}
+}
+
+func (m *mockEventBroadcaster) AddClient(_ *websocket.Conn) {
+	m.mu.Lock()
+	m.addCount++
+	m.mu.Unlock()
+	select {
+	case m.addCh <- struct{}{}:
+	default:
+	}
+}
+
+func (m *mockEventBroadcaster) RemoveClient(_ *websocket.Conn) {
+	m.mu.Lock()
+	m.removeCount++
+	m.mu.Unlock()
+	select {
+	case m.removeCh <- struct{}{}:
+	default:
+	}
+}
+
+func TestWsHandler_HubUnavailable(t *testing.T) {
+	h := NewWsHandler(nil)
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodGet, "/api/ws/events", nil)
+
+	h.HandleEvents(w, r)
+
+	if w.Code != http.StatusServiceUnavailable {
+		t.Fatalf("expected 503, got %d", w.Code)
+	}
+}
+
+func TestWsHandler_HandleEvents_AddAndRemoveClient(t *testing.T) {
+	mockHub := &mockEventBroadcaster{
+		addCh:    make(chan struct{}, 1),
+		removeCh: make(chan struct{}, 1),
+	}
+
+	server := httptest.NewServer(http.HandlerFunc(NewWsHandler(mockHub).HandleEvents))
+	defer server.Close()
+
+	wsURL := "ws" + strings.TrimPrefix(server.URL, "http")
+	conn, _, err := websocket.Dial(context.Background(), wsURL, nil)
+	if err != nil {
+		t.Fatalf("dial websocket: %v", err)
+	}
+
+	select {
+	case <-mockHub.addCh:
+	case <-time.After(time.Second):
+		t.Fatal("timeout waiting AddClient")
+	}
+
+	if err := conn.Close(websocket.StatusNormalClosure, "test done"); err != nil {
+		t.Fatalf("close websocket: %v", err)
+	}
+
+	select {
+	case <-mockHub.removeCh:
+	case <-time.After(time.Second):
+		t.Fatal("timeout waiting RemoveClient")
+	}
+}
diff --git a/backend/internal/service/event_hub.go b/backend/internal/service/event_hub.go
new file mode 100644
index 0000000..24dc292
--- /dev/null
+++ b/backend/internal/service/event_hub.go
@@ -0,0 +1,317 @@
+package service
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"log"
+	"sort"
+	"sync"
+	"time"
+
+	"github.com/coder/websocket"
+	"github.com/docker/docker/api/types/events"
+	"github.com/docker/docker/api/types/filters"
+	"github.com/docker/docker/client"
+
+	"minedock/backend/internal/model"
+)
+
+const (
+	eventHubDebounceWindow = 150 * time.Millisecond
+	eventHubWriteTimeout   = 3 * time.Second
+	eventHubMaxBackoff     = 30 * time.Second
+)
+
+// dockerEventClient 定义 EventHub 依赖的 Docker Events 能力。
+type dockerEventClient interface {
+	Events(ctx context.Context, options events.ListOptions) (<-chan events.Message, <-chan error)
+}
+
+type instancesUpdatedMessage struct {
+	Type string           `json:"type"`
+	Data []model.Instance `json:"data"`
+}
+
+// EventHub 管理 WebSocket 连接并将 Docker 事件广播给所有客户端。
+type EventHub struct {
+	cli    dockerEventClient
+	listFn func(ctx context.Context) ([]model.Instance, error)
+
+	mu           sync.RWMutex
+	clients      map[*websocket.Conn]struct{}
+	lastSnapshot []byte
+	lastPayload  []byte
+
+	debounceWindow time.Duration
+	writeTimeout   time.Duration
+}
+
+// NewEventHub 创建 EventHub。
+// listFn 是获取完整实例列表的回调（注入 DockerService.ListInstances）。
+func NewEventHub(cli *client.Client, listFn func(ctx context.Context) ([]model.Instance, error)) *EventHub {
+	return newEventHub(cli, listFn)
+}
+
+func newEventHub(cli dockerEventClient, listFn func(ctx context.Context) ([]model.Instance, error)) *EventHub {
+	return &EventHub{
+		cli:            cli,
+		listFn:         listFn,
+		clients:        make(map[*websocket.Conn]struct{}),
+		debounceWindow: eventHubDebounceWindow,
+		writeTimeout:   eventHubWriteTimeout,
+	}
+}
+
+// Run 启动 Docker Events 监听循环，ctx 取消时退出。
+func (h *EventHub) Run(ctx context.Context) {
+	if h == nil {
+		return
+	}
+	defer h.closeAllClients(websocket.StatusGoingAway, "server shutdown")
+
+	backoff := time.Second
+	for {
+		healthy, err := h.runOnce(ctx)
+		if ctx.Err() != nil {
+			return
+		}
+		if healthy {
+			backoff = time.Second
+		}
+		if err != nil {
+			log.Printf("event hub run once: %v", err)
+		}
+
+		timer := time.NewTimer(backoff)
+		select {
+		case <-ctx.Done():
+			timer.Stop()
+			return
+		case <-timer.C:
+		}
+
+		if backoff < eventHubMaxBackoff {
+			backoff *= 2
+			if backoff > eventHubMaxBackoff {
+				backoff = eventHubMaxBackoff
+			}
+		}
+	}
+}
+
+func (h *EventHub) runOnce(ctx context.Context) (bool, error) {
+	if h.cli == nil {
+		return false, fmt.Errorf("docker client is nil")
+	}
+	if h.listFn == nil {
+		return false, fmt.Errorf("list function is nil")
+	}
+
+	healthy := false
+
+	args := filters.NewArgs()
+	args.Add("type", "container")
+	args.Add("label", managedLabelKey+"="+managedLabelValue)
+	for _, action := range []string{"start", "stop", "die", "destroy", "kill"} {
+		args.Add("event", action)
+	}
+
+	msgCh, errCh := h.cli.Events(ctx, events.ListOptions{Filters: args})
+
+	// 每次连接（含重连）成功后立即推送一次全量快照。
+	if err := h.refreshAndBroadcast(ctx); err != nil && ctx.Err() == nil {
+		log.Printf("event hub initial snapshot: %v", err)
+	} else if err == nil {
+		healthy = true
+	}
+
+	timer := time.NewTimer(time.Hour)
+	if !timer.Stop() {
+		<-timer.C
+	}
+	timerCh := (<-chan time.Time)(nil)
+	pending := false
+
+	for {
+		select {
+		case <-ctx.Done():
+			if timerCh != nil {
+				if !timer.Stop() {
+					select {
+					case <-timer.C:
+					default:
+					}
+				}
+			}
+			return healthy, nil
+		case _, ok := <-msgCh:
+			if !ok {
+				return healthy, fmt.Errorf("docker events channel closed")
+			}
+			pending = true
+			healthy = true
+			if !timer.Stop() {
+				select {
+				case <-timer.C:
+				default:
+				}
+			}
+			timer.Reset(h.debounceWindow)
+			timerCh = timer.C
+		case err, ok := <-errCh:
+			if !ok {
+				return healthy, fmt.Errorf("docker events error channel closed")
+			}
+			if err != nil {
+				return healthy, fmt.Errorf("docker events stream error: %w", err)
+			}
+		case <-timerCh:
+			timerCh = nil
+			if !pending {
+				continue
+			}
+			pending = false
+			if err := h.refreshAndBroadcast(ctx); err != nil && ctx.Err() == nil {
+				log.Printf("event hub broadcast snapshot: %v", err)
+			} else if err == nil {
+				healthy = true
+			}
+		}
+	}
+}
+
+func (h *EventHub) refreshAndBroadcast(ctx context.Context) error {
+	instances, err := h.listFn(ctx)
+	if err != nil {
+		return fmt.Errorf("list instances: %w", err)
+	}
+
+	snapshot, payload, err := buildEventPayload(instances)
+	if err != nil {
+		return fmt.Errorf("marshal snapshot: %w", err)
+	}
+
+	if h.shouldSkipSnapshot(snapshot) {
+		return nil
+	}
+
+	h.updateSnapshot(snapshot, payload)
+	h.broadcastPayload(payload)
+	return nil
+}
+
+func buildEventPayload(instances []model.Instance) ([]byte, []byte, error) {
+	ordered := append([]model.Instance(nil), instances...)
+	sort.Slice(ordered, func(i, j int) bool {
+		if ordered[i].ContainerID != ordered[j].ContainerID {
+			return ordered[i].ContainerID < ordered[j].ContainerID
+		}
+		return ordered[i].Name < ordered[j].Name
+	})
+
+	snapshot, err := json.Marshal(ordered)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	payload, err := json.Marshal(instancesUpdatedMessage{Type: "instances_updated", Data: ordered})
+	if err != nil {
+		return nil, nil, err
+	}
+
+	return snapshot, payload, nil
+}
+
+func (h *EventHub) shouldSkipSnapshot(snapshot []byte) bool {
+	h.mu.RLock()
+	defer h.mu.RUnlock()
+	return bytes.Equal(h.lastSnapshot, snapshot)
+}
+
+func (h *EventHub) updateSnapshot(snapshot []byte, payload []byte) {
+	h.mu.Lock()
+	h.lastSnapshot = append([]byte(nil), snapshot...)
+	h.lastPayload = append([]byte(nil), payload...)
+	h.mu.Unlock()
+}
+
+// AddClient 注册一个 WebSocket 客户端连接。
+func (h *EventHub) AddClient(conn *websocket.Conn) {
+	if h == nil || conn == nil {
+		return
+	}
+
+	h.mu.Lock()
+	h.clients[conn] = struct{}{}
+	payload := append([]byte(nil), h.lastPayload...)
+	h.mu.Unlock()
+
+	if len(payload) == 0 {
+		return
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), h.writeTimeout)
+	defer cancel()
+	if err := conn.Write(ctx, websocket.MessageText, payload); err != nil {
+		h.removeClient(conn, websocket.StatusInternalError, "send initial snapshot failed")
+	}
+}
+
+// RemoveClient 移除一个 WebSocket 客户端连接。
+func (h *EventHub) RemoveClient(conn *websocket.Conn) {
+	if h == nil || conn == nil {
+		return
+	}
+	h.removeClient(conn, websocket.StatusNormalClosure, "client disconnected")
+}
+
+func (h *EventHub) removeClient(conn *websocket.Conn, code websocket.StatusCode, reason string) {
+	h.mu.Lock()
+	_, exists := h.clients[conn]
+	if exists {
+		delete(h.clients, conn)
+	}
+	h.mu.Unlock()
+
+	if exists {
+		_ = conn.Close(code, reason)
+	}
+}
+
+func (h *EventHub) broadcastPayload(payload []byte) {
+	clients := h.snapshotClients()
+	for _, conn := range clients {
+		ctx, cancel := context.WithTimeout(context.Background(), h.writeTimeout)
+		err := conn.Write(ctx, websocket.MessageText, payload)
+		cancel()
+		if err != nil {
+			h.removeClient(conn, websocket.StatusInternalError, "write failed")
+		}
+	}
+}
+
+func (h *EventHub) snapshotClients() []*websocket.Conn {
+	h.mu.RLock()
+	defer h.mu.RUnlock()
+	clients := make([]*websocket.Conn, 0, len(h.clients))
+	for conn := range h.clients {
+		clients = append(clients, conn)
+	}
+	return clients
+}
+
+func (h *EventHub) closeAllClients(code websocket.StatusCode, reason string) {
+	h.mu.Lock()
+	clients := make([]*websocket.Conn, 0, len(h.clients))
+	for conn := range h.clients {
+		clients = append(clients, conn)
+	}
+	h.clients = make(map[*websocket.Conn]struct{})
+	h.mu.Unlock()
+
+	for _, conn := range clients {
+		_ = conn.Close(code, reason)
+	}
+}
diff --git a/backend/internal/service/event_hub_test.go b/backend/internal/service/event_hub_test.go
new file mode 100644
index 0000000..58e1c60
--- /dev/null
+++ b/backend/internal/service/event_hub_test.go
@@ -0,0 +1,175 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/coder/websocket"
+
+	"minedock/backend/internal/model"
+)
+
+func TestEventHub_AddRemoveClient(t *testing.T) {
+	hub := newEventHub(nil, nil)
+	serverConn, clientConn, cleanup := newWebSocketPair(t)
+	defer cleanup()
+
+	hub.AddClient(serverConn)
+	if got := len(hub.snapshotClients()); got != 1 {
+		t.Fatalf("expected 1 client, got %d", got)
+	}
+
+	hub.RemoveClient(serverConn)
+	if got := len(hub.snapshotClients()); got != 0 {
+		t.Fatalf("expected 0 clients, got %d", got)
+	}
+
+	readCtx, cancel := context.WithTimeout(context.Background(), 300*time.Millisecond)
+	defer cancel()
+	_, _, err := clientConn.Read(readCtx)
+	if websocket.CloseStatus(err) != websocket.StatusNormalClosure {
+		t.Fatalf("expected normal closure, got %v", err)
+	}
+}
+
+func TestEventHub_RefreshAndBroadcast_DeduplicateSnapshot(t *testing.T) {
+	instances := []model.Instance{{ContainerID: "c1", Name: "alpha", Status: "Running"}}
+	hub := newEventHub(nil, func(context.Context) ([]model.Instance, error) {
+		return append([]model.Instance(nil), instances...), nil
+	})
+
+	serverConn, clientConn, cleanup := newWebSocketPair(t)
+	defer cleanup()
+	hub.AddClient(serverConn)
+
+	if err := hub.refreshAndBroadcast(context.Background()); err != nil {
+		t.Fatalf("first refresh: %v", err)
+	}
+
+	first := readWSMessage(t, clientConn)
+	assertInstancesUpdatedPayload(t, first, "Running")
+
+	nextMessageCh := readWSMessageAsync(clientConn)
+
+	if err := hub.refreshAndBroadcast(context.Background()); err != nil {
+		t.Fatalf("duplicate refresh: %v", err)
+	}
+
+	select {
+	case result := <-nextMessageCh:
+		if result.err != nil {
+			t.Fatalf("unexpected websocket error: %v", result.err)
+		}
+		t.Fatalf("expected no message for duplicate snapshot, got %s", string(result.payload))
+	case <-time.After(120 * time.Millisecond):
+	}
+
+	instances[0].Status = "Stopped"
+	if err := hub.refreshAndBroadcast(context.Background()); err != nil {
+		t.Fatalf("third refresh: %v", err)
+	}
+
+	select {
+	case result := <-nextMessageCh:
+		if result.err != nil {
+			t.Fatalf("read websocket payload: %v", result.err)
+		}
+		assertInstancesUpdatedPayload(t, result.payload, "Stopped")
+	case <-time.After(time.Second):
+		t.Fatal("timeout waiting message after snapshot change")
+	}
+}
+
+func newWebSocketPair(t *testing.T) (*websocket.Conn, *websocket.Conn, func()) {
+	t.Helper()
+
+	serverConnCh := make(chan *websocket.Conn, 1)
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		conn, err := websocket.Accept(w, r, &websocket.AcceptOptions{InsecureSkipVerify: true})
+		if err != nil {
+			t.Errorf("accept websocket: %v", err)
+			return
+		}
+		serverConnCh <- conn
+		for {
+			if _, _, err := conn.Read(r.Context()); err != nil {
+				return
+			}
+		}
+	}))
+
+	clientURL := "ws" + strings.TrimPrefix(server.URL, "http")
+	clientConn, _, err := websocket.Dial(context.Background(), clientURL, nil)
+	if err != nil {
+		server.Close()
+		t.Fatalf("dial websocket: %v", err)
+	}
+
+	var serverConn *websocket.Conn
+	select {
+	case serverConn = <-serverConnCh:
+	case <-time.After(time.Second):
+		_ = clientConn.Close(websocket.StatusAbnormalClosure, "timeout")
+		server.Close()
+		t.Fatal("timeout waiting for server websocket connection")
+	}
+
+	cleanup := func() {
+		_ = clientConn.Close(websocket.StatusNormalClosure, "test cleanup")
+		_ = serverConn.Close(websocket.StatusNormalClosure, "test cleanup")
+		server.Close()
+	}
+
+	return serverConn, clientConn, cleanup
+}
+
+func readWSMessage(t *testing.T, conn *websocket.Conn) []byte {
+	t.Helper()
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	_, payload, err := conn.Read(ctx)
+	if err != nil {
+		t.Fatalf("read websocket payload: %v", err)
+	}
+	return payload
+}
+
+type wsReadResult struct {
+	payload []byte
+	err     error
+}
+
+func readWSMessageAsync(conn *websocket.Conn) <-chan wsReadResult {
+	ch := make(chan wsReadResult, 1)
+	go func() {
+		_, payload, err := conn.Read(context.Background())
+		ch <- wsReadResult{payload: payload, err: err}
+	}()
+	return ch
+}
+
+func assertInstancesUpdatedPayload(t *testing.T, payload []byte, wantStatus string) {
+	t.Helper()
+
+	var msg struct {
+		Type string           `json:"type"`
+		Data []model.Instance `json:"data"`
+	}
+	if err := json.Unmarshal(payload, &msg); err != nil {
+		t.Fatalf("decode websocket payload: %v", err)
+	}
+	if msg.Type != "instances_updated" {
+		t.Fatalf("unexpected message type: %s", msg.Type)
+	}
+	if len(msg.Data) != 1 {
+		t.Fatalf("unexpected data size: %d", len(msg.Data))
+	}
+	if msg.Data[0].Status != wantStatus {
+		t.Fatalf("unexpected status: %s", msg.Data[0].Status)
+	}
+}
diff --git a/backend/main.go b/backend/main.go
index 9d2182f..76a2694 100644
--- a/backend/main.go
+++ b/backend/main.go
@@ -1,6 +1,7 @@
 package main
 
 import (
+	"context"
 	"log"
 	"net/http"
 	"os"
@@ -40,10 +41,17 @@ func main() {
 		log.Fatalf("init registry service: %v", err)
 	}
 
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
 	svc := service.NewDockerService(cli, sqliteStore, registrySvc)
+	hub := service.NewEventHub(cli, svc.ListInstances)
+	go hub.Run(ctx)
+
 	h := api.NewHandler(svc)
 	registryHandler := api.NewRegistryHandler(registrySvc)
-	router := api.NewRouter(h, registryHandler)
+	wsHandler := api.NewWsHandler(hub)
+	router := api.NewRouter(h, registryHandler, wsHandler)
 
 	addr := ":8080"
 	log.Printf("MineDock backend listening on %s", addr)
diff --git a/docs/api/contracts.md b/docs/api/contracts.md
index c777f7b..cff9459 100644
--- a/docs/api/contracts.md
+++ b/docs/api/contracts.md
@@ -102,3 +102,20 @@
 ```json
 { "status": "success" }
 ```
+
+### GET /api/ws/events (WebSocket)
+
+- 说明：建立 WebSocket 连接，实时接收容器状态变更推送
+- 协议：WebSocket（HTTP Upgrade）
+- 同源限制：仅支持同源连接（`Origin` 必须与请求 `Host` 一致），当前版本不支持跨域 WebSocket
+- 消息格式（服务端 -> 客户端）：
+
+```json
+{
+  "type": "instances_updated",
+  "data": [{ "container_id": "xxx", "name": "xxx", "status": "Running" }]
+}
+```
+
+- 触发时机：任一托管容器状态发生变化（`start` / `stop` / `die` / `destroy` / `kill`）
+- 降级方案：客户端连接失败时应回退到轮询 `GET /api/instances`
diff --git a/docs/design-docs/instance_lifecycle.md b/docs/design-docs/instance_lifecycle.md
index 73e136a..20235b0 100644
--- a/docs/design-docs/instance_lifecycle.md
+++ b/docs/design-docs/instance_lifecycle.md
@@ -43,7 +43,8 @@ stateDiagram-v2
 
 - 事实来源：Docker Daemon。
 - 缓存来源：SQLite（用于实例名、状态缓存和恢复）。
-- 收敛机制：`ListInstances` 周期性/调用时同步 Docker -> SQLite。
+- 收敛机制（主路径）：监听 Docker Events，在容器状态变化后通过 WebSocket 推送最新实例快照。
+- 收敛机制（降级路径）：`ListInstances` 按需对账 Docker -> SQLite；当前端 WebSocket 不可用时回退到轮询接口。
 
 ## 失败与回滚策略
 
diff --git a/docs/exec-plans/active/20260401-realtime-status-sync.md b/docs/exec-plans/active/20260401-realtime-status-sync.md
new file mode 100644
index 0000000..b9e4908
--- /dev/null
+++ b/docs/exec-plans/active/20260401-realtime-status-sync.md
@@ -0,0 +1,330 @@
+# 容器运行状态实时同步（WebSocket + Docker Events）
+
+## 背景
+
+当前 MineDock 的容器状态同步依赖请求驱动的拉取模式：前端每次执行操作（create / start / stop / delete）后主动调用 `fetchInstances()` 刷新列表，后端 `ListInstances` 遍历 Docker API 并逐条同步到 SQLite。这意味着：
+
+- **外部状态变更不可见**：若容器被 Docker CLI / Portainer 等外部工具操作（或容器自行崩溃退出），前端无法感知，直到用户手动触发刷新
+- **状态延迟**：start / stop 操作返回 HTTP 200 时，Docker 可能尚未完成状态切换，前端显示的状态可能短暂不一致
+- **轮询浪费**：若改为定时轮询弥补，会产生大量无意义的 HTTP 请求
+
+本计划引入 **WebSocket + Docker Events** 方案：后端启动一个常驻 Goroutine 监听 Docker Events（`container start`、`stop`、`die` 等），当托管容器状态变化时，通过 WebSocket 将增量事件推送给所有已连接的前端客户端，实现实时状态同步。
+
+## 需要评审的内容
+
+> [!IMPORTANT]
+> **WebSocket 库选型**
+>
+> Go 标准库不内置 WebSocket 支持。推荐使用 `github.com/coder/websocket`（`nhooyr.io/websocket` 的社区延续版本，API 兼容、`net/http` 原生兼容、支持 context 取消）。也可选择 `github.com/gorilla/websocket`（社区更成熟但已归档维护模式）。
+>
+> 本计划默认使用 `github.com/coder/websocket`。
+
+> [!IMPORTANT]
+> **推送消息格式**
+>
+> WebSocket 推送的消息为 JSON，采用最简的「全量快照」模式：当任一托管容器状态变化时，后端重新查询完整实例列表并推送给所有客户端。这与当前 `GET /api/instances` 返回格式一致。
+>
+> ```json
+> {
+>   "type": "instances_updated",
+>   "data": [
+>     { "container_id": "xxx", "name": "xxx", "status": "Running" },
+>     { "container_id": "yyy", "name": "yyy", "status": "Stopped" }
+>   ]
+> }
+> ```
+>
+> 选择全量快照而非增量事件的原因：
+>
+> - 前端无需维护复杂的增量合并逻辑，直接替换 `instances` 数组
+> - 容器数量有限（游戏服务器场景通常 < 50），全量传输开销可忽略
+> - 避免增量事件丢失或乱序导致的状态不一致
+
+> [!IMPORTANT]
+> **前端降级策略**
+>
+> WebSocket 连接失败或断线时，前端自动降级为定时轮询（如每 5 秒一次 `GET /api/instances`），恢复连接后停止轮询。这保证即使 WebSocket 不可用，功能依然正常。
+
+## 拟定更改
+
+### 后端 Service 层
+
+#### [NEW] event_hub.go (`backend/internal/service/event_hub.go`)
+
+新增 `EventHub`，职责：管理 WebSocket 客户端连接、监听 Docker Events、广播状态变更。
+
+```go
+// EventHub 管理 WebSocket 连接并将 Docker 事件广播给所有客户端。
+type EventHub struct {
+    cli           *client.Client
+    listFn        func(ctx context.Context) ([]model.Instance, error)
+    mu            sync.RWMutex
+    clients       map[*websocket.Conn]struct{}
+    lastSnapshot  []byte // 上一次广播的 JSON 快照，用于去重比对
+}
+
+// NewEventHub 创建 EventHub。
+// listFn 是获取完整实例列表的回调（注入 DockerService.ListInstances）。
+func NewEventHub(cli *client.Client, listFn func(ctx context.Context) ([]model.Instance, error)) *EventHub { ... }
+
+// Run 启动 Docker Events 监听循环，ctx 取消时退出。
+func (h *EventHub) Run(ctx context.Context) { ... }
+
+// AddClient 注册一个 WebSocket 客户端连接。
+func (h *EventHub) AddClient(conn *websocket.Conn) { ... }
+
+// RemoveClient 移除一个 WebSocket 客户端连接。
+func (h *EventHub) RemoveClient(conn *websocket.Conn) { ... }
+```
+
+核心逻辑：
+
+- **`Run` 方法**：
+  - 调用 `cli.Events(ctx, events.ListOptions{...})` 获取 Docker Events 流
+  - 通过 `filters` 仅监听 `container` 类型、`start / stop / die / destroy / kill` 动作、带有 `minedock.managed=true` 标签的容器
+  - 收到事件后，调用 `listFn(ctx)` 获取最新实例列表
+  - **快照去重**：将列表序列化为 JSON 后与上一次广播的 `lastSnapshot []byte` 对比，内容完全一致则跳过本次推送，避免无意义的全量传输
+  - 内容变化时，将列表封装为 `{ "type": "instances_updated", "data": [...] }` JSON
+  - 遍历所有 `clients`，写入 WebSocket 消息；写入失败则移除该连接
+  - **防抖**：短时间内收到多个事件时（如 stop 后紧接 die），合并为一次推送（100~200ms 窗口）
+
+- **退出机制**：`ctx` 取消时，Events 流自动关闭，`Run` 退出。关闭所有客户端连接。
+
+- **重连**：Docker Events 流断开时（网络闪断、Docker 重启），自动重连（指数退避，最大间隔 30s），并在重连后立即推送一次全量快照。
+
+---
+
+### 后端 API 层
+
+#### [NEW] ws_handler.go (`backend/internal/api/ws_handler.go`)
+
+新增 WebSocket Handler：
+
+```go
+// EventBroadcaster 定义 WebSocket Handler 依赖的事件广播操作。
+type EventBroadcaster interface {
+    AddClient(conn *websocket.Conn)
+    RemoveClient(conn *websocket.Conn)
+}
+
+// WsHandler 暴露 WebSocket 相关 HTTP 处理器。
+type WsHandler struct {
+    hub EventBroadcaster
+}
+
+// NewWsHandler 创建 WsHandler。
+func NewWsHandler(hub EventBroadcaster) *WsHandler { ... }
+
+// HandleEvents 处理 GET /api/ws/events，将 HTTP 连接升级为 WebSocket。
+func (h *WsHandler) HandleEvents(w http.ResponseWriter, r *http.Request) { ... }
+```
+
+`HandleEvents` 逻辑：
+
+1. 使用 `websocket.Accept(w, r, &websocket.AcceptOptions{...})` 升级连接
+2. 调用 `hub.AddClient(conn)` 注册连接
+3. 阻塞读循环（等待客户端关闭或 ctx 取消）
+4. `defer hub.RemoveClient(conn)` 清理
+
+#### [MODIFY] router.go (`backend/internal/api/router.go`)
+
+- `NewRouter` 签名变更：增加 `*WsHandler` 参数
+- 注册新路由：`GET /api/ws/events`（不受 `withCORS` 中间件影响，WebSocket 有自身的 Origin 校验）
+
+---
+
+### 后端入口
+
+#### [MODIFY] main.go
+
+- 创建 `EventHub`，注入 Docker client 和 `DockerService.ListInstances`
+- 启动 `EventHub.Run` Goroutine（使用 `context.WithCancel` 控制生命周期）
+- 创建 `WsHandler` 并注入 `EventHub`
+- 更新 `NewRouter` 调用
+
+```go
+// main.go 新增部分（伪代码）
+ctx, cancel := context.WithCancel(context.Background())
+defer cancel()
+
+hub := service.NewEventHub(cli, svc.ListInstances)
+go hub.Run(ctx)
+
+wsHandler := api.NewWsHandler(hub)
+router := api.NewRouter(h, registryHandler, wsHandler)
+```
+
+---
+
+### 后端依赖
+
+#### [MODIFY] go.mod
+
+- 新增依赖：`github.com/coder/websocket`
+
+---
+
+### 前端 Composable 层
+
+#### [NEW] useInstanceSync.ts (`frontend/src/composables/useInstanceSync.ts`)
+
+新增 Composable，封装原生 WebSocket 连接管理和降级轮询逻辑。
+
+> [!NOTE]
+> 本计划使用原生 `new WebSocket()` API 自实现，**不引入 VueUse 的 `useWebSocket`**。原因：
+>
+> - 当前项目未依赖 VueUse，仅为一个 Composable 引入整个库不合算
+> - 自实现可以精确控制降级轮询、重连退避、store 集成等业务逻辑
+> - 原生 WebSocket API 本身已足够简洁，封装量很小
+
+```typescript
+// useInstanceSync 管理与后端的 WebSocket 实时连接，
+// 收到 instances_updated 消息时自动更新 container store。
+// 连接失败或断开时降级为定时轮询。
+export function useInstanceSync(): {
+  /** WebSocket 连接状态 */
+  connected: Ref<boolean>;
+  /** 启动同步（在 onMounted 中调用） */
+  start: () => void;
+  /** 停止同步（在 onUnmounted 中调用） */
+  stop: () => void;
+};
+```
+
+核心逻辑：
+
+- **WebSocket URL 构建**：根据当前页面协议自动选择 `ws://` 或 `wss://`，路径为 `/api/ws/events`
+- **连接成功**：设置 `connected = true`，停止轮询定时器
+- **收到消息**：解析 JSON，若 `type === "instances_updated"`，直接将 `data` 写入 `useContainerStore().instances`
+- **连接断开 / 失败**：设置 `connected = false`，启动降级轮询（每 5 秒调用 `fetchInstances()`），并启动重连定时器（指数退避 1s → 2s → 4s → ... → 最大 30s）
+- **重连成功**：停止轮询，重新进入 WebSocket 模式
+- **`stop`**：关闭 WebSocket 连接，清除所有定时器
+
+#### [MODIFY] containers.ts (`frontend/src/stores/containers.ts`)
+
+- 新增 `applySnapshot(instances: Instance[])` 方法：直接替换 `instances` 数组（供 WebSocket 消息使用，绕过 `fetchInstances` 的 HTTP 调用）
+- 现有 `create` / `remove` / `toggle` action 中的 `await fetchInstances()` 保留不变（WebSocket 推送会自然覆盖，但 HTTP 回调提供了及时的首次状态更新）
+
+---
+
+### 前端视图层
+
+#### [MODIFY] ContainerList.vue (`frontend/src/views/ContainerList.vue`)
+
+- 引入 `useInstanceSync` composable
+- `onMounted` 中调用 `start()`
+- `onUnmounted` 中调用 `stop()`
+
+#### [MODIFY] TopBar.vue (`frontend/src/components/TopBar.vue`)
+
+- 在语言切换按钮左侧新增 WebSocket 连接状态指示器：
+  - 绿色圆点（`connected === true`）+ tooltip「实时同步已连接」
+  - 灰色圆点（`connected === false`）+ tooltip「实时同步已断开，轮询模式」
+  - 圆点使用 CSS 变量 `--success` / `--text-muted`
+- `useInstanceSync` 的 `connected` ref 需要在 store 或 composable 中暴露为全局可访问（因为 TopBar 和 ContainerList 是不同组件）
+  - 方案：在 `useContainerStore` 中新增 `wsConnected` ref，由 `useInstanceSync` 写入，TopBar 读取
+
+---
+
+### 前端 API 层
+
+#### [MODIFY] index.ts (`frontend/src/api/index.ts`)
+
+- 新增 `WS_BASE_URL` 常量：根据 `VITE_API_BASE_URL` 和当前协议构建 WebSocket URL
+- 新增 `WsMessage` 类型定义：
+
+```typescript
+export interface WsInstancesUpdated {
+  type: "instances_updated";
+  data: Instance[];
+}
+
+export type WsMessage = WsInstancesUpdated;
+```
+
+---
+
+### 文档
+
+#### [MODIFY] contracts.md (`docs/api/contracts.md`)
+
+新增 WebSocket 接口文档：
+
+````markdown
+### GET /api/ws/events (WebSocket)
+
+- 说明：建立 WebSocket 连接，实时接收容器状态变更推送
+- 协议：WebSocket（HTTP Upgrade）
+- 消息格式（服务端 → 客户端）：
+
+\```json
+{
+"type": "instances_updated",
+"data": [{ "container_id": "xxx", "name": "xxx", "status": "Running" }]
+}
+\```
+
+- 触发时机：任一托管容器状态发生变化（start / stop / die / destroy）
+- 降级方案：客户端连接失败时应回退到轮询 GET /api/instances
+````
+
+#### [MODIFY] instance_lifecycle.md (`docs/design-docs/instance_lifecycle.md`)
+
+- 更新一致性策略：新增 Docker Events 实时推送机制说明
+- 收敛机制更新为：Docker Events 实时推送（主路径）+ `ListInstances` 按需对账（降级路径）
+
+---
+
+## 执行步骤
+
+- [ ] 后端依赖
+  - [ ] 执行 `go get github.com/coder/websocket`，更新 `go.mod` 和 `go.sum`
+- [ ] 后端 Service 层
+  - [ ] 新建 `backend/internal/service/event_hub.go`，实现 `EventHub`
+  - [ ] 实现 Docker Events 监听循环（过滤托管容器、防抖合并、重连退避）
+  - [ ] 实现快照去重（`lastSnapshot` 对比，内容一致时跳过推送）
+  - [ ] 实现客户端连接管理（AddClient / RemoveClient / 广播）
+  - [ ] 编写 `event_hub_test.go` 单元测试（广播逻辑、客户端增删）
+- [ ] 后端 API 层
+  - [ ] 新建 `backend/internal/api/ws_handler.go`，实现 `WsHandler`
+  - [ ] 修改 `backend/internal/api/router.go`：注册 `GET /api/ws/events` 路由
+- [ ] 后端入口
+  - [ ] 修改 `backend/main.go`：创建 `EventHub`、启动 Run Goroutine、创建 `WsHandler`、更新 Router
+- [ ] 前端 API 层
+  - [ ] 修改 `frontend/src/api/index.ts`：新增 `WS_BASE_URL` 和 `WsMessage` 类型
+- [ ] 前端 Composable 层
+  - [ ] 新建 `frontend/src/composables/useInstanceSync.ts`，实现 WebSocket 连接管理和降级轮询
+- [ ] 前端 Store 层
+  - [ ] 修改 `frontend/src/stores/containers.ts`：新增 `applySnapshot` 方法和 `wsConnected` ref
+- [ ] 前端视图层
+  - [ ] 修改 `frontend/src/views/ContainerList.vue`：接入 `useInstanceSync`
+  - [ ] 修改 `frontend/src/components/TopBar.vue`：新增 WebSocket 连接状态圆点指示器
+- [ ] 文档更新
+  - [ ] 修改 `docs/api/contracts.md`：新增 WebSocket 接口文档
+  - [ ] 修改 `docs/design-docs/instance_lifecycle.md`：更新一致性策略
+
+## 已确认的决策
+
+- ✅ WebSocket 库：使用 `github.com/coder/websocket`
+- ✅ 连接状态 UI：在 TopBar 语言按钮左侧添加绿色/灰色圆点指示器
+- ✅ 快照去重：EventHub 缓存上一次广播的 JSON，内容一致时跳过推送
+- ✅ 前端 WebSocket：使用原生 `new WebSocket()` 自实现 composable，不引入 VueUse
+
+## 验证计划
+
+### 自动化测试
+
+- `task backend:test` — 覆盖：
+  - `EventHub`：客户端注册/移除、广播消息格式、并发安全
+  - `WsHandler`：HTTP → WebSocket 升级
+- `task backend:vet && task backend:lint`
+- 前端：`npm run lint`
+
+### 手动验证
+
+- 启动前后端，打开容器列表页，验证 WebSocket 连接建立（DevTools → Network → WS）
+- 通过 Docker CLI 执行 `docker stop <container>`，验证前端状态**自动**更新为 Stopped（无需手动刷新）
+- 通过 Docker CLI 执行 `docker start <container>`，验证前端状态自动更新为 Running
+- 断开 WebSocket（如关闭后端），验证前端降级为轮询模式
+- 重启后端，验证前端自动重连 WebSocket 并恢复实时推送
+- 同时打开两个浏览器标签页，验证状态变更在两个页面同步更新
diff --git a/frontend/src/api/index.ts b/frontend/src/api/index.ts
index b3dd974..866452b 100644
--- a/frontend/src/api/index.ts
+++ b/frontend/src/api/index.ts
@@ -1,6 +1,17 @@
 const BASE_URL: string =
   (typeof import.meta !== "undefined" && import.meta.env?.VITE_API_BASE_URL) || "/api";
 
+const runtimeOrigin = typeof window === "undefined" ? "http://localhost" : window.location.origin;
+const resolvedBaseURL: URL = new URL(BASE_URL, runtimeOrigin);
+
+// WebSocket 仅支持同源连接：固定使用当前页面 origin，只复用 API 基础路径。
+const pageProtocol =
+  typeof window === "undefined" ? resolvedBaseURL.protocol : window.location.protocol;
+const wsProtocol = pageProtocol === "https:" ? "wss:" : "ws:";
+const wsHost = typeof window === "undefined" ? resolvedBaseURL.host : window.location.host;
+const wsPath = resolvedBaseURL.pathname.replace(/\/+$/, "");
+export const WS_BASE_URL = `${wsProtocol}//${wsHost}${wsPath}`;
+
 type JsonObject = Record<string, unknown>;
 
 interface RequestOptions extends Omit<RequestInit, "headers" | "body"> {
@@ -92,6 +103,13 @@ export interface Instance {
   status: string;
 }
 
+export interface WsInstancesUpdated {
+  type: "instances_updated";
+  data: Instance[];
+}
+
+export type WsMessage = WsInstancesUpdated;
+
 export interface RegistryImage {
   id: string;
   name: string;
diff --git a/frontend/src/components/TopBar.vue b/frontend/src/components/TopBar.vue
index db625d4..b46db1b 100644
--- a/frontend/src/components/TopBar.vue
+++ b/frontend/src/components/TopBar.vue
@@ -1,10 +1,15 @@
 <script setup lang="ts">
-import { ref, onMounted, onUnmounted } from "vue";
+import { computed, ref, onMounted, onUnmounted } from "vue";
 import { useI18n } from "vue-i18n";
+import { useContainerStore } from "../stores/containers";
 
 const { t, locale } = useI18n();
+const store = useContainerStore();
 
 const isOpen = ref(false);
+const syncStatusTitle = computed(() => {
+  return store.wsConnected ? t("topbar.realtimeConnected") : t("topbar.realtimeDisconnected");
+});
 
 const toggleMenu = () => {
   isOpen.value = !isOpen.value;
@@ -35,37 +40,43 @@ onUnmounted(() => {
 
 <template>
   <div class="top-bar-overlay">
-    <div class="lang-selector">
-      <button class="lang-btn" :title="t('topbar.switchLanguage')" @click.stop="toggleMenu">
-        <!-- "文A" or Translate Icon -->
-        <svg
-          xmlns="http://www.w3.org/2000/svg"
-          viewBox="0 0 24 24"
-          width="20"
-          height="20"
-          fill="currentColor"
-        >
-          <path
-            d="M12.87 15.07l-2.54-2.51.03-.03A17.52 17.52 0 0014.07 6H17V4h-7V2H8v2H1v2h11.17C11.5 7.92 10.44 9.75 9 11.35 8.07 10.32 7.3 9.19 6.69 8h-2c.73 1.63 1.73 3.17 2.98 4.56l-5.09 5.02L4 19l5-5 3.11 3.11.76-2.04zM18.5 10h-2L12 22h2l1.12-3h4.75L21 22h2l-4.5-12zm-2.62 7l1.62-4.33L19.12 17h-3.24z"
-          />
-        </svg>
-      </button>
-
-      <div v-show="isOpen" class="dropdown-menu">
-        <button
-          class="dropdown-item"
-          :class="{ active: locale === 'zh-CN' }"
-          @click="setLocale('zh-CN')"
-        >
-          {{ t("topbar.zhCN") }}
-        </button>
-        <button
-          class="dropdown-item"
-          :class="{ active: locale === 'en-US' }"
-          @click="setLocale('en-US')"
-        >
-          {{ t("topbar.enUS") }}
+    <div class="top-actions">
+      <div class="sync-indicator" :title="syncStatusTitle" :aria-label="syncStatusTitle">
+        <span class="sync-dot" :class="{ connected: store.wsConnected }"></span>
+      </div>
+
+      <div class="lang-selector">
+        <button class="lang-btn" :title="t('topbar.switchLanguage')" @click.stop="toggleMenu">
+          <!-- "文A" or Translate Icon -->
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            viewBox="0 0 24 24"
+            width="20"
+            height="20"
+            fill="currentColor"
+          >
+            <path
+              d="M12.87 15.07l-2.54-2.51.03-.03A17.52 17.52 0 0014.07 6H17V4h-7V2H8v2H1v2h11.17C11.5 7.92 10.44 9.75 9 11.35 8.07 10.32 7.3 9.19 6.69 8h-2c.73 1.63 1.73 3.17 2.98 4.56l-5.09 5.02L4 19l5-5 3.11 3.11.76-2.04zM18.5 10h-2L12 22h2l1.12-3h4.75L21 22h2l-4.5-12zm-2.62 7l1.62-4.33L19.12 17h-3.24z"
+            />
+          </svg>
         </button>
+
+        <div v-show="isOpen" class="dropdown-menu">
+          <button
+            class="dropdown-item"
+            :class="{ active: locale === 'zh-CN' }"
+            @click="setLocale('zh-CN')"
+          >
+            {{ t("topbar.zhCN") }}
+          </button>
+          <button
+            class="dropdown-item"
+            :class="{ active: locale === 'en-US' }"
+            @click="setLocale('en-US')"
+          >
+            {{ t("topbar.enUS") }}
+          </button>
+        </div>
       </div>
     </div>
   </div>
@@ -78,6 +89,9 @@ onUnmounted(() => {
   left: 0;
   right: 0;
   height: var(--header-height);
+  --top-actions-gap: 10px;
+  --topbar-sync-dot-size: 10px;
+  --topbar-sync-dot-radius: 999px;
   pointer-events: none; /* Let clicks pass through */
   display: flex;
   justify-content: flex-end;
@@ -86,6 +100,31 @@ onUnmounted(() => {
   z-index: 100;
 }
 
+.top-actions {
+  display: flex;
+  align-items: center;
+  gap: var(--top-actions-gap);
+}
+
+.sync-indicator {
+  pointer-events: auto;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.sync-dot {
+  width: var(--topbar-sync-dot-size);
+  height: var(--topbar-sync-dot-size);
+  border-radius: var(--topbar-sync-dot-radius);
+  background-color: var(--text-muted);
+  box-shadow: 0 0 0 2px var(--hover-darken);
+}
+
+.sync-dot.connected {
+  background-color: var(--success);
+}
+
 .lang-selector {
   position: relative;
   pointer-events: auto; /* Enable clicks for this component */
diff --git a/frontend/src/composables/useInstanceSync.ts b/frontend/src/composables/useInstanceSync.ts
new file mode 100644
index 0000000..e4e24e5
--- /dev/null
+++ b/frontend/src/composables/useInstanceSync.ts
@@ -0,0 +1,178 @@
+import { ref, type Ref } from "vue";
+import { WS_BASE_URL, type WsMessage } from "../api/index";
+import { useContainerStore } from "../stores/containers";
+
+const POLL_INTERVAL_MS = 5000;
+const INITIAL_RECONNECT_DELAY_MS = 1000;
+const MAX_RECONNECT_DELAY_MS = 30000;
+
+function isInstancesUpdatedMessage(payload: unknown): payload is WsMessage {
+  if (!payload || typeof payload !== "object") {
+    return false;
+  }
+  const message = payload as { type?: unknown; data?: unknown };
+  return message.type === "instances_updated" && Array.isArray(message.data);
+}
+
+// useInstanceSync 管理与后端的 WebSocket 实时连接，
+// 收到 instances_updated 消息时自动更新 container store。
+// 连接失败或断开时降级为定时轮询。
+export function useInstanceSync(): {
+  connected: Ref<boolean>;
+  start: () => void;
+  stop: () => void;
+} {
+  const store = useContainerStore();
+  const connected = ref(false);
+
+  const wsURL = `${WS_BASE_URL}/ws/events`;
+  let socket: WebSocket | null = null;
+  let started = false;
+  let reconnectDelay = INITIAL_RECONNECT_DELAY_MS;
+  let reconnectTimer: ReturnType<typeof window.setTimeout> | null = null;
+  let pollingTimer: ReturnType<typeof window.setInterval> | null = null;
+
+  const setConnected = (value: boolean): void => {
+    connected.value = value;
+    store.setWsConnected(value);
+  };
+
+  const stopPolling = (): void => {
+    if (pollingTimer !== null) {
+      window.clearInterval(pollingTimer);
+      pollingTimer = null;
+    }
+  };
+
+  const startPolling = (): void => {
+    if (pollingTimer !== null) {
+      return;
+    }
+    pollingTimer = window.setInterval(() => {
+      void store.fetchInstances();
+    }, POLL_INTERVAL_MS);
+  };
+
+  const clearReconnectTimer = (): void => {
+    if (reconnectTimer !== null) {
+      window.clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+  };
+
+  const closeSocket = (): void => {
+    if (!socket) {
+      return;
+    }
+    socket.onopen = null;
+    socket.onclose = null;
+    socket.onerror = null;
+    socket.onmessage = null;
+    if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) {
+      socket.close();
+    }
+    socket = null;
+  };
+
+  const scheduleReconnect = (): void => {
+    if (!started || reconnectTimer !== null) {
+      return;
+    }
+    reconnectTimer = window.setTimeout(() => {
+      reconnectTimer = null;
+      connect();
+    }, reconnectDelay);
+    reconnectDelay = Math.min(reconnectDelay * 2, MAX_RECONNECT_DELAY_MS);
+  };
+
+  const handleDisconnected = (): void => {
+    setConnected(false);
+    startPolling();
+    scheduleReconnect();
+  };
+
+  const connect = (): void => {
+    if (!started) {
+      return;
+    }
+
+    if (
+      socket &&
+      (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING)
+    ) {
+      return;
+    }
+
+    let nextSocket: WebSocket;
+    try {
+      nextSocket = new WebSocket(wsURL);
+    } catch {
+      handleDisconnected();
+      return;
+    }
+
+    socket = nextSocket;
+
+    nextSocket.onopen = () => {
+      reconnectDelay = INITIAL_RECONNECT_DELAY_MS;
+      clearReconnectTimer();
+      stopPolling();
+      setConnected(true);
+      void store.fetchInstances();
+    };
+
+    nextSocket.onmessage = (event: MessageEvent): void => {
+      if (typeof event.data !== "string") {
+        return;
+      }
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+      if (!isInstancesUpdatedMessage(parsed)) {
+        return;
+      }
+      store.applySnapshot(parsed.data);
+    };
+
+    nextSocket.onerror = () => {
+      nextSocket.close();
+    };
+
+    nextSocket.onclose = () => {
+      if (socket === nextSocket) {
+        socket = null;
+      }
+      if (!started) {
+        return;
+      }
+      handleDisconnected();
+    };
+  };
+
+  const start = (): void => {
+    if (started) {
+      return;
+    }
+    started = true;
+    reconnectDelay = INITIAL_RECONNECT_DELAY_MS;
+    clearReconnectTimer();
+    setConnected(false);
+    connect();
+  };
+
+  const stop = (): void => {
+    if (!started) {
+      return;
+    }
+    started = false;
+    clearReconnectTimer();
+    stopPolling();
+    setConnected(false);
+    closeSocket();
+  };
+
+  return { connected, start, stop };
+}
diff --git a/frontend/src/locales/en-US.json b/frontend/src/locales/en-US.json
index 2c9d085..9b8f005 100644
--- a/frontend/src/locales/en-US.json
+++ b/frontend/src/locales/en-US.json
@@ -58,6 +58,8 @@
   },
   "topbar": {
     "switchLanguage": "Switch Language",
+    "realtimeConnected": "Realtime sync connected",
+    "realtimeDisconnected": "Realtime sync disconnected, polling mode",
     "zhCN": "简体中文",
     "enUS": "English"
   }
diff --git a/frontend/src/locales/zh-CN.json b/frontend/src/locales/zh-CN.json
index 01cb977..89e5875 100644
--- a/frontend/src/locales/zh-CN.json
+++ b/frontend/src/locales/zh-CN.json
@@ -58,6 +58,8 @@
   },
   "topbar": {
     "switchLanguage": "切换语言",
+    "realtimeConnected": "实时同步已连接",
+    "realtimeDisconnected": "实时同步已断开，轮询模式",
     "zhCN": "简体中文",
     "enUS": "English"
   }
diff --git a/frontend/src/stores/containers.ts b/frontend/src/stores/containers.ts
index 81ae64e..55979ae 100644
--- a/frontend/src/stores/containers.ts
+++ b/frontend/src/stores/containers.ts
@@ -31,6 +31,7 @@ function isLikelyI18nKey(value: string): boolean {
 
 export const useContainerStore = defineStore("containers", () => {
   const instances = ref<Instance[]>([]);
+  const wsConnected = ref(false);
   // 统一输出区支持纯文本和 i18n key 两种模式，视图层只负责渲染。
   const output = ref<string>("");
   const outputI18n = ref<OutputI18nPayload | null>(null);
@@ -106,11 +107,34 @@ export const useContainerStore = defineStore("containers", () => {
     printI18n(key, values);
   }
 
+  // 保持列表顺序稳定：优先沿用当前显示顺序，新增项再按名称/ID 排序追加。
+  function normalizeInstances(nextInstances: Instance[]): Instance[] {
+    const currentOrder = new Map(instances.value.map((item, index) => [item.container_id, index]));
+    return [...nextInstances].sort((a, b) => {
+      const aIndex = currentOrder.get(a.container_id);
+      const bIndex = currentOrder.get(b.container_id);
+      if (typeof aIndex === "number" && typeof bIndex === "number") {
+        return aIndex - bIndex;
+      }
+      if (typeof aIndex === "number") {
+        return -1;
+      }
+      if (typeof bIndex === "number") {
+        return 1;
+      }
+      const nameOrder = a.name.localeCompare(b.name);
+      if (nameOrder !== 0) {
+        return nameOrder;
+      }
+      return a.container_id.localeCompare(b.container_id);
+    });
+  }
+
   // 同步后端实例列表到全局状态，返回值供视图层决定后续提示文案。
   async function fetchInstances(): Promise<boolean> {
     try {
       const data = await listInstances();
-      instances.value = data;
+      instances.value = normalizeInstances(data);
       return true;
     } catch (err) {
       printError(err);
@@ -118,6 +142,15 @@ export const useContainerStore = defineStore("containers", () => {
     }
   }
 
+  // WebSocket 推送的全量快照直接覆盖本地列表，避免再次触发 HTTP 拉取。
+  function applySnapshot(nextInstances: Instance[]): void {
+    instances.value = normalizeInstances(nextInstances);
+  }
+
+  function setWsConnected(connected: boolean): void {
+    wsConnected.value = connected;
+  }
+
   // 创建实例后立即刷新列表，避免视图层维护后端数据副本。
   async function create(name: string, imageId: string): Promise<boolean> {
     try {
@@ -168,11 +201,14 @@ export const useContainerStore = defineStore("containers", () => {
 
   return {
     instances,
+    wsConnected,
     output,
     outputI18n,
     print,
     printError,
     printErrorKey,
+    applySnapshot,
+    setWsConnected,
     fetchInstances,
     create,
     remove,
diff --git a/frontend/src/views/ContainerList.vue b/frontend/src/views/ContainerList.vue
index adec7e0..adec5e3 100644
--- a/frontend/src/views/ContainerList.vue
+++ b/frontend/src/views/ContainerList.vue
@@ -1,15 +1,17 @@
 <script setup lang="ts">
-import { computed, ref, onMounted } from "vue";
+import { computed, ref, onMounted, onUnmounted } from "vue";
 import { useRoute, useRouter } from "vue-router";
 import { useI18n } from "vue-i18n";
 import { useContainerStore } from "../stores/containers";
 import { useRegistryStore } from "../stores/registry";
+import { useInstanceSync } from "../composables/useInstanceSync";
 
 const { t } = useI18n();
 const route = useRoute();
 const router = useRouter();
 const store = useContainerStore();
 const registryStore = useRegistryStore();
+const instanceSync = useInstanceSync();
 
 const showCreateModal = ref(false);
 const newContainerName = ref("");
@@ -27,9 +29,14 @@ const selectedImageDescription = computed(() => {
 });
 
 onMounted(() => {
+  instanceSync.start();
   void initializeList();
 });
 
+onUnmounted(() => {
+  instanceSync.stop();
+});
+
 function ensureDefaultImageSelection(): void {
   if (!selectedImageId.value && registryStore.images.length > 0) {
     selectedImageId.value = registryStore.images[0].id;
diff --git a/frontend/vite.config.js b/frontend/vite.config.js
index 4c688ff..a011b5e 100644
--- a/frontend/vite.config.js
+++ b/frontend/vite.config.js
@@ -4,11 +4,19 @@ import vue from "@vitejs/plugin-vue";
 export default defineConfig({
   plugins: [vue()],
   server: {
+    host: "127.0.0.1",
     port: 5173,
+    strictPort: true,
+    hmr: {
+      host: "127.0.0.1",
+      protocol: "ws",
+      clientPort: 5173,
+    },
     proxy: {
       "/api": {
         target: "http://localhost:8080",
-        changeOrigin: true,
+        changeOrigin: false,
+        ws: true,
       },
     },
   },

From 434dbf43d390878825a19ce5cece5c7082efd6d3 Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Thu, 2 Apr 2026 18:43:37 +0800
Subject: [PATCH 25/28] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E5=9F=BA?=
 =?UTF-8?q?=E4=BA=8E=20YAML=20=E7=9A=84=E6=B8=B8=E6=88=8F=E6=A8=A1?=
 =?UTF-8?q?=E6=9D=BF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Readme.md                                     |   4 +-
 backend/{registry.json => games.json}         |  26 +-
 backend/go.mod                                |   1 +
 backend/go.sum                                |   1 +
 backend/internal/api/game_handlers.go         |  68 ++
 backend/internal/api/handlers.go              |  26 +-
 backend/internal/api/handlers_test.go         | 171 +++-
 backend/internal/api/registry_handlers.go     |  34 -
 backend/internal/api/router.go                |   7 +-
 backend/internal/model/errors.go              |  13 +-
 backend/internal/model/game.go                |  10 +
 backend/internal/model/registry.go            |  13 -
 backend/internal/model/template.go            |  87 ++
 backend/internal/service/docker_service.go    | 162 +++-
 backend/internal/service/game_service.go      | 294 +++++++
 backend/internal/service/game_service_test.go | 222 +++++
 backend/internal/service/registry_service.go  | 105 ---
 .../internal/service/registry_service_test.go | 119 ---
 backend/main.go                               |  21 +-
 backend/templates/minecraft-bedrock.yaml      |  47 ++
 backend/templates/minecraft-java.yaml         |  59 ++
 backend/templates/terraria.yaml               |  34 +
 docs/api/contracts.md                         |  68 +-
 docs/design-docs/instance_lifecycle.md        |   4 +-
 .../20260401-realtime-status-sync.md          |   0
 .../20260401-yaml-game-template-design.md     | 761 ++++++++++++++++++
 docs/standards/directory.md                   |   2 +
 docs/standards/frontend.md                    |   2 +-
 docs/standards/ops.md                         |   3 +-
 frontend/src/api/index.ts                     |  85 +-
 frontend/src/locales/en-US.json               |  55 +-
 frontend/src/locales/zh-CN.json               |  55 +-
 frontend/src/router/index.ts                  |   5 +
 frontend/src/stores/containers.ts             |  38 +-
 frontend/src/stores/games.ts                  | 126 +++
 frontend/src/stores/registry.ts               |  82 --
 frontend/src/views/ContainerList.vue          | 242 +-----
 frontend/src/views/CreateInstance.vue         | 479 +++++++++++
 frontend/src/views/ImageRegistry.vue          |  76 +-
 39 files changed, 2847 insertions(+), 760 deletions(-)
 rename backend/{registry.json => games.json} (53%)
 create mode 100644 backend/internal/api/game_handlers.go
 delete mode 100644 backend/internal/api/registry_handlers.go
 create mode 100644 backend/internal/model/game.go
 delete mode 100644 backend/internal/model/registry.go
 create mode 100644 backend/internal/model/template.go
 create mode 100644 backend/internal/service/game_service.go
 create mode 100644 backend/internal/service/game_service_test.go
 delete mode 100644 backend/internal/service/registry_service.go
 delete mode 100644 backend/internal/service/registry_service_test.go
 create mode 100644 backend/templates/minecraft-bedrock.yaml
 create mode 100644 backend/templates/minecraft-java.yaml
 create mode 100644 backend/templates/terraria.yaml
 rename docs/exec-plans/{active => completed}/20260401-realtime-status-sync.md (100%)
 create mode 100644 docs/exec-plans/completed/20260401-yaml-game-template-design.md
 create mode 100644 frontend/src/stores/games.ts
 delete mode 100644 frontend/src/stores/registry.ts
 create mode 100644 frontend/src/views/CreateInstance.vue

diff --git a/Readme.md b/Readme.md
index b684028..acb124d 100644
--- a/Readme.md
+++ b/Readme.md
@@ -14,14 +14,14 @@ task dev               # 一键启动前后端开发服务
 
 - [x] 静态镜像注册表（后端 JSON 配置）
 - [x] 镜像市场前端页面（浏览、筛选、选用镜像）
-- [ ] 基于 YAML 的游戏模板规范设计
+- [x] 基于 YAML 的游戏模板规范设计
 - [ ] 模板解析引擎（根据模板自动生成 Docker 启动参数）
 
 ### 实例生命周期
 
 - [x] 容器基础生命周期：创建、删除、开启、停止
 - [x] 容器运行状态实时同步
-- [ ] 创建容器时支持镜像选择
+- [x] 创建容器时支持镜像选择
 - [ ] 创建容器时支持环境变量注入
 - [ ] 创建容器时支持 Volume 持久化目录挂载
 - [ ] 创建容器时支持动态端口映射与防冲突检测
diff --git a/backend/registry.json b/backend/games.json
similarity index 53%
rename from backend/registry.json
rename to backend/games.json
index 5118009..7755f42 100644
--- a/backend/registry.json
+++ b/backend/games.json
@@ -2,42 +2,22 @@
   {
     "id": "minecraft-java",
     "name": "Minecraft Java Edition",
-    "image": "itzg/minecraft-server:latest",
     "description": "最流行的 Minecraft Java 版服务器，支持原版/Forge/Fabric/Paper 等多种模组加载器。",
     "category": "minecraft",
-    "icon": "minecraft-java",
-    "default_env": {
-      "EULA": "TRUE",
-      "TYPE": "PAPER"
-    },
-    "default_ports": [
-      "25565:25565"
-    ]
+    "icon": "minecraft-java"
   },
   {
     "id": "minecraft-bedrock",
     "name": "Minecraft Bedrock Edition",
-    "image": "itzg/minecraft-bedrock-server:latest",
     "description": "Minecraft 基岩版服务器，支持手机/主机/Win10 跨平台联机。",
     "category": "minecraft",
-    "icon": "minecraft-bedrock",
-    "default_env": {
-      "EULA": "TRUE"
-    },
-    "default_ports": [
-      "19132:19132/udp"
-    ]
+    "icon": "minecraft-bedrock"
   },
   {
     "id": "terraria",
     "name": "Terraria",
-    "image": "ryshe/terraria:latest",
     "description": "Terraria 专用服务器，支持 tShock 管理。",
     "category": "sandbox",
-    "icon": "terraria",
-    "default_env": {},
-    "default_ports": [
-      "7777:7777"
-    ]
+    "icon": "terraria"
   }
 ]
diff --git a/backend/go.mod b/backend/go.mod
index 1a2c65b..df74b5f 100644
--- a/backend/go.mod
+++ b/backend/go.mod
@@ -38,6 +38,7 @@ require (
 	go.opentelemetry.io/otel/trace v1.42.0 // indirect
 	golang.org/x/sys v0.42.0 // indirect
 	golang.org/x/time v0.15.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
 	gotest.tools/v3 v3.5.2 // indirect
 	modernc.org/libc v1.70.0 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
diff --git a/backend/go.sum b/backend/go.sum
index 9361e19..0e31d0f 100644
--- a/backend/go.sum
+++ b/backend/go.sum
@@ -141,6 +141,7 @@ google.golang.org/grpc v1.79.2 h1:fRMD94s2tITpyJGtBBn7MkMseNpOZU8ZxgC3MMBaXRU=
 google.golang.org/grpc v1.79.2/go.mod h1:KmT0Kjez+0dde/v2j9vzwoAScgEPx/Bw1CYChhHLrHQ=
 google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
 google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q=
diff --git a/backend/internal/api/game_handlers.go b/backend/internal/api/game_handlers.go
new file mode 100644
index 0000000..14a061c
--- /dev/null
+++ b/backend/internal/api/game_handlers.go
@@ -0,0 +1,68 @@
+package api
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"strings"
+
+	"minedock/backend/internal/model"
+)
+
+// GameLister 定义游戏目录 Handler 依赖的查询操作。
+type GameLister interface {
+	ListGames(ctx context.Context) []model.Game
+	GetTemplate(ctx context.Context, id string) (model.GameTemplate, error)
+}
+
+// GameHandler 暴露游戏目录与模板相关 HTTP 处理器。
+type GameHandler struct {
+	games GameLister
+}
+
+// NewGameHandler 创建 GameHandler。
+func NewGameHandler(g GameLister) *GameHandler {
+	return &GameHandler{games: g}
+}
+
+// GetGames 处理 GET /api/games，返回游戏目录列表。
+func (h *GameHandler) GetGames(w http.ResponseWriter, r *http.Request) {
+	if h == nil || h.games == nil {
+		writeJSON(w, http.StatusInternalServerError, statusResponse{Status: "error", Error: "game service unavailable"})
+		return
+	}
+
+	games := h.games.ListGames(r.Context())
+	writeJSON(w, http.StatusOK, games)
+}
+
+// GetGameTemplate 处理 GET /api/games/{id}/template，按需返回模板详情。
+func (h *GameHandler) GetGameTemplate(w http.ResponseWriter, r *http.Request) {
+	if h == nil || h.games == nil {
+		writeJSON(w, http.StatusInternalServerError, statusResponse{Status: "error", Error: "game service unavailable"})
+		return
+	}
+
+	id := strings.TrimSpace(r.PathValue("id"))
+	if id == "" || strings.Contains(id, "/") {
+		writeJSON(w, http.StatusBadRequest, statusResponse{Status: "error", Error: "invalid game id"})
+		return
+	}
+
+	tpl, err := h.games.GetTemplate(r.Context(), id)
+	if err != nil {
+		switch {
+		case errors.Is(err, model.ErrGameNotFound):
+			writeJSON(w, http.StatusNotFound, statusResponse{Status: "error", Error: err.Error()})
+		case errors.Is(err, model.ErrTemplateNotFound):
+			writeJSON(w, http.StatusInternalServerError, statusResponse{Status: "error", Error: err.Error()})
+		case errors.Is(err, model.ErrTemplateInvalid):
+			writeJSON(w, http.StatusInternalServerError, statusResponse{Status: "error", Error: err.Error()})
+		default:
+			writeJSON(w, http.StatusInternalServerError, statusResponse{Status: "error", Error: err.Error()})
+		}
+		return
+	}
+
+	writeJSON(w, http.StatusOK, tpl)
+}
diff --git a/backend/internal/api/handlers.go b/backend/internal/api/handlers.go
index 751390f..dc8b418 100644
--- a/backend/internal/api/handlers.go
+++ b/backend/internal/api/handlers.go
@@ -13,7 +13,7 @@ import (
 // InstanceService 定义 API Handler 依赖的业务操作。
 type InstanceService interface {
 	ListInstances(ctx context.Context) ([]model.Instance, error)
-	CreateInstance(ctx context.Context, name, imageID string) (string, error)
+	CreateInstance(ctx context.Context, name, gameID string, params map[string]string) (string, error)
 	StartInstance(ctx context.Context, containerID string) error
 	StopInstance(ctx context.Context, containerID string) error
 	DeleteInstance(ctx context.Context, containerID string) error
@@ -31,8 +31,9 @@ func NewHandler(svc InstanceService) *Handler {
 
 // createRequest 定义创建实例请求体。
 type createRequest struct {
-	Name    string `json:"name"`
-	ImageID string `json:"image_id"`
+	Name   string            `json:"name"`
+	GameID string            `json:"game_id"`
+	Params map[string]string `json:"params"`
 }
 
 // statusResponse 定义通用状态响应体。
@@ -70,13 +71,16 @@ func (h *Handler) CreateInstance(w http.ResponseWriter, r *http.Request) {
 		writeJSON(w, http.StatusBadRequest, statusResponse{Status: "error", Error: "name is required"})
 		return
 	}
-	req.ImageID = strings.TrimSpace(req.ImageID)
-	if req.ImageID == "" {
-		writeJSON(w, http.StatusBadRequest, statusResponse{Status: "error", Error: "image_id is required"})
+	req.GameID = strings.TrimSpace(req.GameID)
+	if req.GameID == "" {
+		writeJSON(w, http.StatusBadRequest, statusResponse{Status: "error", Error: "game_id is required"})
 		return
 	}
+	if req.Params == nil {
+		req.Params = map[string]string{}
+	}
 
-	id, err := h.svc.CreateInstance(r.Context(), req.Name, req.ImageID)
+	id, err := h.svc.CreateInstance(r.Context(), req.Name, req.GameID, req.Params)
 	if err != nil {
 		writeJSON(w, mapErrorCode(err), statusResponse{Status: "error", Error: err.Error()})
 		return
@@ -147,12 +151,18 @@ func pathContainerID(r *http.Request) (string, bool) {
 // mapErrorCode 将领域错误统一映射为 HTTP 状态码。
 func mapErrorCode(err error) int {
 	switch {
-	case errors.Is(err, model.ErrImageNotFound):
+	case errors.Is(err, model.ErrGameNotFound):
+		return http.StatusBadRequest
+	case errors.Is(err, model.ErrInvalidParams):
 		return http.StatusBadRequest
 	case errors.Is(err, model.ErrNameExists):
 		return http.StatusConflict
 	case errors.Is(err, model.ErrInstanceRunning):
 		return http.StatusConflict
+	case errors.Is(err, model.ErrTemplateNotFound):
+		return http.StatusInternalServerError
+	case errors.Is(err, model.ErrTemplateInvalid):
+		return http.StatusInternalServerError
 	default:
 		return http.StatusInternalServerError
 	}
diff --git a/backend/internal/api/handlers_test.go b/backend/internal/api/handlers_test.go
index 68f5783..2a8977f 100644
--- a/backend/internal/api/handlers_test.go
+++ b/backend/internal/api/handlers_test.go
@@ -3,6 +3,7 @@ package api
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@@ -14,7 +15,7 @@ import (
 // mockService 为 Handler 测试实现 InstanceService。
 type mockService struct {
 	listFn   func(ctx context.Context) ([]model.Instance, error)
-	createFn func(ctx context.Context, name, imageID string) (string, error)
+	createFn func(ctx context.Context, name, gameID string, params map[string]string) (string, error)
 	startFn  func(ctx context.Context, id string) error
 	stopFn   func(ctx context.Context, id string) error
 	deleteFn func(ctx context.Context, id string) error
@@ -23,8 +24,8 @@ type mockService struct {
 func (m *mockService) ListInstances(ctx context.Context) ([]model.Instance, error) {
 	return m.listFn(ctx)
 }
-func (m *mockService) CreateInstance(ctx context.Context, name, imageID string) (string, error) {
-	return m.createFn(ctx, name, imageID)
+func (m *mockService) CreateInstance(ctx context.Context, name, gameID string, params map[string]string) (string, error) {
+	return m.createFn(ctx, name, gameID, params)
 }
 func (m *mockService) StartInstance(ctx context.Context, id string) error {
 	return m.startFn(ctx, id)
@@ -37,24 +38,35 @@ func (m *mockService) DeleteInstance(ctx context.Context, id string) error {
 }
 
 type mockRegistryLister struct {
-	listFn func(ctx context.Context) []model.RegistryImage
+	listFn     func(ctx context.Context) []model.Game
+	getTplByID func(ctx context.Context, id string) (model.GameTemplate, error)
 }
 
-func (m *mockRegistryLister) ListImages(ctx context.Context) []model.RegistryImage {
+func (m *mockRegistryLister) ListGames(ctx context.Context) []model.Game {
 	if m == nil || m.listFn == nil {
-		return []model.RegistryImage{}
+		return []model.Game{}
 	}
 	return m.listFn(ctx)
 }
 
+func (m *mockRegistryLister) GetTemplate(ctx context.Context, id string) (model.GameTemplate, error) {
+	if m == nil || m.getTplByID == nil {
+		return model.GameTemplate{}, model.ErrGameNotFound
+	}
+	return m.getTplByID(ctx, id)
+}
+
 func newTestRouter(m *mockService) http.Handler {
 	h := NewHandler(m)
-	rh := NewRegistryHandler(&mockRegistryLister{
-		listFn: func(_ context.Context) []model.RegistryImage {
-			return []model.RegistryImage{}
+	gh := NewGameHandler(&mockRegistryLister{
+		listFn: func(_ context.Context) []model.Game {
+			return []model.Game{}
+		},
+		getTplByID: func(_ context.Context, _ string) (model.GameTemplate, error) {
+			return model.GameTemplate{}, model.ErrGameNotFound
 		},
 	})
-	return NewRouter(h, rh, nil)
+	return NewRouter(h, gh, nil)
 }
 
 // --- GET /api/instances 场景 ---
@@ -101,24 +113,27 @@ func TestGetInstances_Error(t *testing.T) {
 	}
 }
 
-func TestGetRegistryImages_Success(t *testing.T) {
+func TestGetGames_Success(t *testing.T) {
 	h := NewHandler(&mockService{})
-	rh := NewRegistryHandler(&mockRegistryLister{
-		listFn: func(_ context.Context) []model.RegistryImage {
-			return []model.RegistryImage{{ID: "minecraft-java", Image: "itzg/minecraft-server:latest"}}
+	gh := NewGameHandler(&mockRegistryLister{
+		listFn: func(_ context.Context) []model.Game {
+			return []model.Game{{ID: "minecraft-java", Name: "Minecraft Java"}}
+		},
+		getTplByID: func(_ context.Context, _ string) (model.GameTemplate, error) {
+			return model.GameTemplate{}, model.ErrGameNotFound
 		},
 	})
-	router := NewRouter(h, rh, nil)
+	router := NewRouter(h, gh, nil)
 
 	w := httptest.NewRecorder()
-	r := httptest.NewRequest(http.MethodGet, "/api/registry/images", nil)
+	r := httptest.NewRequest(http.MethodGet, "/api/games", nil)
 	router.ServeHTTP(w, r)
 
 	if w.Code != http.StatusOK {
 		t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
 	}
 
-	var got []model.RegistryImage
+	var got []model.Game
 	if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
 		t.Fatalf("decode: %v", err)
 	}
@@ -127,22 +142,78 @@ func TestGetRegistryImages_Success(t *testing.T) {
 	}
 }
 
+func TestGetGameTemplate_Success(t *testing.T) {
+	h := NewHandler(&mockService{})
+	gh := NewGameHandler(&mockRegistryLister{
+		listFn: func(_ context.Context) []model.Game {
+			return []model.Game{{ID: "minecraft-java", Name: "Minecraft Java"}}
+		},
+		getTplByID: func(_ context.Context, id string) (model.GameTemplate, error) {
+			if id != "minecraft-java" {
+				return model.GameTemplate{}, model.ErrGameNotFound
+			}
+			return model.GameTemplate{Image: model.TemplateImage{Name: "itzg/minecraft-server", Tag: "latest"}}, nil
+		},
+	})
+	router := NewRouter(h, gh, nil)
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodGet, "/api/games/minecraft-java/template", nil)
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+	}
+
+	var got model.GameTemplate
+	if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if got.Image.FullImageRef() != "itzg/minecraft-server:latest" {
+		t.Fatalf("unexpected template response: %+v", got)
+	}
+}
+
+func TestGetGameTemplate_NotFound(t *testing.T) {
+	h := NewHandler(&mockService{})
+	gh := NewGameHandler(&mockRegistryLister{
+		listFn: func(_ context.Context) []model.Game {
+			return []model.Game{}
+		},
+		getTplByID: func(_ context.Context, _ string) (model.GameTemplate, error) {
+			return model.GameTemplate{}, model.ErrGameNotFound
+		},
+	})
+	router := NewRouter(h, gh, nil)
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodGet, "/api/games/not-exists/template", nil)
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d: %s", w.Code, w.Body.String())
+	}
+}
+
 // --- POST /api/instances 场景 ---
 
 func TestCreateInstance_Success(t *testing.T) {
 	router := newTestRouter(&mockService{
-		createFn: func(_ context.Context, name, imageID string) (string, error) {
+		createFn: func(_ context.Context, name, gameID string, params map[string]string) (string, error) {
 			if name != "test-server" {
 				t.Fatalf("unexpected name: %s", name)
 			}
-			if imageID != "minecraft-java" {
-				t.Fatalf("unexpected image_id: %s", imageID)
+			if gameID != "minecraft-java" {
+				t.Fatalf("unexpected game_id: %s", gameID)
+			}
+			if params["SERVER_TYPE"] != "PAPER" {
+				t.Fatalf("unexpected params: %+v", params)
 			}
 			return "abc123", nil
 		},
 	})
 
-	body := `{"name":"test-server","image_id":"minecraft-java"}`
+	body := `{"name":"test-server","game_id":"minecraft-java","params":{"SERVER_TYPE":"PAPER"}}`
 	w := httptest.NewRecorder()
 	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(body))
 	router.ServeHTTP(w, r)
@@ -176,7 +247,7 @@ func TestCreateInstance_EmptyName(t *testing.T) {
 	router := newTestRouter(&mockService{})
 
 	w := httptest.NewRecorder()
-	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(`{"name":"  ","image_id":"minecraft-java"}`))
+	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(`{"name":"  ","game_id":"minecraft-java"}`))
 	router.ServeHTTP(w, r)
 
 	if w.Code != http.StatusBadRequest {
@@ -184,11 +255,11 @@ func TestCreateInstance_EmptyName(t *testing.T) {
 	}
 }
 
-func TestCreateInstance_EmptyImageID(t *testing.T) {
+func TestCreateInstance_EmptyGameID(t *testing.T) {
 	router := newTestRouter(&mockService{})
 
 	w := httptest.NewRecorder()
-	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(`{"name":"server","image_id":"   "}`))
+	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(`{"name":"server","game_id":"   "}`))
 	router.ServeHTTP(w, r)
 
 	if w.Code != http.StatusBadRequest {
@@ -198,13 +269,13 @@ func TestCreateInstance_EmptyImageID(t *testing.T) {
 
 func TestCreateInstance_NameConflict(t *testing.T) {
 	router := newTestRouter(&mockService{
-		createFn: func(_ context.Context, _, _ string) (string, error) {
+		createFn: func(_ context.Context, _, _ string, _ map[string]string) (string, error) {
 			return "", model.ErrNameExists
 		},
 	})
 
 	w := httptest.NewRecorder()
-	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(`{"name":"dup","image_id":"minecraft-java"}`))
+	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(`{"name":"dup","game_id":"minecraft-java"}`))
 	router.ServeHTTP(w, r)
 
 	if w.Code != http.StatusConflict {
@@ -212,15 +283,31 @@ func TestCreateInstance_NameConflict(t *testing.T) {
 	}
 }
 
-func TestCreateInstance_ImageNotFound(t *testing.T) {
+func TestCreateInstance_GameNotFound(t *testing.T) {
 	router := newTestRouter(&mockService{
-		createFn: func(_ context.Context, _, _ string) (string, error) {
-			return "", model.ErrImageNotFound
+		createFn: func(_ context.Context, _, _ string, _ map[string]string) (string, error) {
+			return "", model.ErrGameNotFound
 		},
 	})
 
 	w := httptest.NewRecorder()
-	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(`{"name":"dup","image_id":"not-exists"}`))
+	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(`{"name":"dup","game_id":"not-exists"}`))
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", w.Code)
+	}
+}
+
+func TestCreateInstance_InvalidParams(t *testing.T) {
+	router := newTestRouter(&mockService{
+		createFn: func(_ context.Context, _, _ string, _ map[string]string) (string, error) {
+			return "", fmtWrap(model.ErrInvalidParams)
+		},
+	})
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(`{"name":"dup","game_id":"minecraft-java","params":{"bad":"1"}}`))
 	router.ServeHTTP(w, r)
 
 	if w.Code != http.StatusBadRequest {
@@ -329,3 +416,27 @@ var errTest = errorString("test error")
 type errorString string
 
 func (e errorString) Error() string { return string(e) }
+
+func fmtWrap(err error) error {
+	if err == nil {
+		return nil
+	}
+	return wrappedError{err: err}
+}
+
+type wrappedError struct {
+	err error
+}
+
+func (e wrappedError) Error() string { return "wrapped: " + e.err.Error() }
+
+func (e wrappedError) Unwrap() error { return e.err }
+
+func TestMapErrorCode_InvalidParamsWrapped(t *testing.T) {
+	if got := mapErrorCode(fmtWrap(model.ErrInvalidParams)); got != http.StatusBadRequest {
+		t.Fatalf("expected 400 for wrapped invalid params, got %d", got)
+	}
+	if !errors.Is(fmtWrap(model.ErrInvalidParams), model.ErrInvalidParams) {
+		t.Fatal("expected wrapped error to match ErrInvalidParams")
+	}
+}
diff --git a/backend/internal/api/registry_handlers.go b/backend/internal/api/registry_handlers.go
deleted file mode 100644
index 30a1c0a..0000000
--- a/backend/internal/api/registry_handlers.go
+++ /dev/null
@@ -1,34 +0,0 @@
-package api
-
-import (
-	"context"
-	"net/http"
-
-	"minedock/backend/internal/model"
-)
-
-// RegistryLister 定义注册表 Handler 依赖的查询操作。
-type RegistryLister interface {
-	ListImages(ctx context.Context) []model.RegistryImage
-}
-
-// RegistryHandler 暴露镜像注册表相关 HTTP 处理器。
-type RegistryHandler struct {
-	registry RegistryLister
-}
-
-// NewRegistryHandler 创建 RegistryHandler。
-func NewRegistryHandler(r RegistryLister) *RegistryHandler {
-	return &RegistryHandler{registry: r}
-}
-
-// GetImages 处理 GET /api/registry/images，返回可用镜像列表。
-func (h *RegistryHandler) GetImages(w http.ResponseWriter, r *http.Request) {
-	if h == nil || h.registry == nil {
-		writeJSON(w, http.StatusInternalServerError, statusResponse{Status: "error", Error: "registry service unavailable"})
-		return
-	}
-
-	images := h.registry.ListImages(r.Context())
-	writeJSON(w, http.StatusOK, images)
-}
diff --git a/backend/internal/api/router.go b/backend/internal/api/router.go
index b69b3bb..8f50343 100644
--- a/backend/internal/api/router.go
+++ b/backend/internal/api/router.go
@@ -6,7 +6,7 @@ import (
 )
 
 // NewRouter 注册 API 路由并包装中间件。
-func NewRouter(h *Handler, registry *RegistryHandler, ws *WsHandler) http.Handler {
+func NewRouter(h *Handler, games *GameHandler, ws *WsHandler) http.Handler {
 	mux := http.NewServeMux()
 
 	mux.HandleFunc("GET /api/instances", h.GetInstances)
@@ -17,8 +17,9 @@ func NewRouter(h *Handler, registry *RegistryHandler, ws *WsHandler) http.Handle
 	if ws != nil {
 		mux.HandleFunc("GET /api/ws/events", ws.HandleEvents)
 	}
-	if registry != nil {
-		mux.HandleFunc("GET /api/registry/images", registry.GetImages)
+	if games != nil {
+		mux.HandleFunc("GET /api/games", games.GetGames)
+		mux.HandleFunc("GET /api/games/{id}/template", games.GetGameTemplate)
 	}
 
 	return withCORS(mux)
diff --git a/backend/internal/model/errors.go b/backend/internal/model/errors.go
index 6e1069b..24c2d79 100644
--- a/backend/internal/model/errors.go
+++ b/backend/internal/model/errors.go
@@ -8,5 +8,14 @@ var ErrNameExists = errors.New("instance name already exists")
 // ErrInstanceRunning 表示实例正在运行，删除前必须先停止。
 var ErrInstanceRunning = errors.New("instance is running, stop it before delete")
 
-// ErrImageNotFound 表示请求的镜像 ID 不在注册表中。
-var ErrImageNotFound = errors.New("image not found in registry")
+// ErrGameNotFound 表示请求的游戏 ID 不在目录中。
+var ErrGameNotFound = errors.New("game not found")
+
+// ErrTemplateNotFound 表示请求的模板文件不存在。
+var ErrTemplateNotFound = errors.New("template not found")
+
+// ErrTemplateInvalid 表示模板内容不合法。
+var ErrTemplateInvalid = errors.New("invalid template")
+
+// ErrInvalidParams 表示传入了不受模板定义约束的参数。
+var ErrInvalidParams = errors.New("invalid params")
diff --git a/backend/internal/model/game.go b/backend/internal/model/game.go
new file mode 100644
index 0000000..01d141e
--- /dev/null
+++ b/backend/internal/model/game.go
@@ -0,0 +1,10 @@
+package model
+
+// Game 描述游戏目录中的一个条目（轻量展示信息）。
+type Game struct {
+	ID          string `json:"id"`
+	Name        string `json:"name"`
+	Description string `json:"description"`
+	Category    string `json:"category"`
+	Icon        string `json:"icon"`
+}
diff --git a/backend/internal/model/registry.go b/backend/internal/model/registry.go
deleted file mode 100644
index 23acddf..0000000
--- a/backend/internal/model/registry.go
+++ /dev/null
@@ -1,13 +0,0 @@
-package model
-
-// RegistryImage 描述注册表中的一个可用镜像条目。
-type RegistryImage struct {
-	ID           string            `json:"id"`
-	Name         string            `json:"name"`
-	Image        string            `json:"image"`
-	Description  string            `json:"description"`
-	Category     string            `json:"category"`
-	Icon         string            `json:"icon"`
-	DefaultEnv   map[string]string `json:"default_env"`
-	DefaultPorts []string          `json:"default_ports"`
-}
diff --git a/backend/internal/model/template.go b/backend/internal/model/template.go
new file mode 100644
index 0000000..3ddf764
--- /dev/null
+++ b/backend/internal/model/template.go
@@ -0,0 +1,87 @@
+package model
+
+import "strings"
+
+// GameTemplate 描述一个游戏服务器的完整技术配置模板。
+type GameTemplate struct {
+	Image     TemplateImage   `json:"image" yaml:"image"`
+	Container ContainerConfig `json:"container" yaml:"container"`
+	Params    []TemplateParam `json:"params" yaml:"params"`
+}
+
+// TemplateImage Docker 镜像配置。
+type TemplateImage struct {
+	Name string `json:"name" yaml:"name"`
+	Tag  string `json:"tag" yaml:"tag"`
+}
+
+// FullImageRef 返回完整的镜像引用（name:tag）。
+func (i TemplateImage) FullImageRef() string {
+	name := strings.TrimSpace(i.Name)
+	if name == "" {
+		return ""
+	}
+
+	tag := strings.TrimSpace(i.Tag)
+	if tag == "" {
+		tag = "latest"
+	}
+
+	return name + ":" + tag
+}
+
+// ContainerConfig 容器运行配置。
+type ContainerConfig struct {
+	Ports       []PortMapping      `json:"ports" yaml:"ports"`
+	Env         map[string]string  `json:"env" yaml:"env"`
+	Volumes     []VolumeMount      `json:"volumes" yaml:"volumes"`
+	Resources   *ResourceLimits    `json:"resources,omitempty" yaml:"resources"`
+	Command     []string           `json:"command,omitempty" yaml:"command"`
+	HealthCheck *HealthCheckConfig `json:"health_check,omitempty" yaml:"health_check"`
+}
+
+// PortMapping 端口映射配置。
+type PortMapping struct {
+	Host      int    `json:"host" yaml:"host"`
+	Container int    `json:"container" yaml:"container"`
+	Protocol  string `json:"protocol" yaml:"protocol"`
+}
+
+// VolumeMount 卷挂载配置。
+type VolumeMount struct {
+	Name          string `json:"name" yaml:"name"`
+	ContainerPath string `json:"container_path" yaml:"container_path"`
+	ReadOnly      bool   `json:"readonly" yaml:"readonly"`
+}
+
+// ResourceLimits 资源限制配置。
+type ResourceLimits struct {
+	Memory string  `json:"memory" yaml:"memory"`
+	CPU    float64 `json:"cpu" yaml:"cpu"`
+}
+
+// HealthCheckConfig 健康检查配置。
+type HealthCheckConfig struct {
+	Test        []string `json:"test" yaml:"test"`
+	Interval    string   `json:"interval" yaml:"interval"`
+	Timeout     string   `json:"timeout" yaml:"timeout"`
+	Retries     int      `json:"retries" yaml:"retries"`
+	StartPeriod string   `json:"start_period" yaml:"start_period"`
+}
+
+// TemplateParam 用户可定制参数定义。
+type TemplateParam struct {
+	Key         string        `json:"key" yaml:"key"`
+	Label       string        `json:"label" yaml:"label"`
+	Description string        `json:"description" yaml:"description"`
+	Type        string        `json:"type" yaml:"type"`
+	Default     any           `json:"default" yaml:"default"`
+	Options     []ParamOption `json:"options,omitempty" yaml:"options"`
+	EnvVar      string        `json:"env_var,omitempty" yaml:"env_var"`
+}
+
+// ParamOption select 类型参数的可选项。
+type ParamOption struct {
+	Value string `json:"value" yaml:"value"`
+	Label string `json:"label" yaml:"label"`
+}
diff --git a/backend/internal/service/docker_service.go b/backend/internal/service/docker_service.go
index 254a9cb..89e8c39 100644
--- a/backend/internal/service/docker_service.go
+++ b/backend/internal/service/docker_service.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"strconv"
 	"strings"
 
 	"github.com/docker/docker/api/types/container"
@@ -18,6 +19,7 @@ const (
 	managedLabelKey   = "minedock.managed"
 	managedLabelValue = "true"
 	nameLabelKey      = "minedock.name"
+	gameIDLabelKey    = "minedock.game_id"
 )
 
 // InstanceStore 定义 DockerService 依赖的持久化操作。
@@ -27,45 +29,63 @@ type InstanceStore interface {
 	Delete(ctx context.Context, containerID string) error
 }
 
-// ImageRegistry 定义 DockerService 依赖的镜像注册表查询能力。
-type ImageRegistry interface {
-	GetImage(ctx context.Context, id string) (model.RegistryImage, error)
+// GameRegistry 定义 DockerService 依赖的游戏与模板查询能力。
+type GameRegistry interface {
+	GetGame(ctx context.Context, id string) (model.Game, error)
+	GetTemplate(ctx context.Context, id string) (model.GameTemplate, error)
 }
 
 // DockerService 封装容器管理相关业务逻辑。
 type DockerService struct {
 	cli      *client.Client
 	store    InstanceStore
-	registry ImageRegistry
+	registry GameRegistry
 }
 
 // NewDockerService 使用依赖项创建 DockerService。
-func NewDockerService(cli *client.Client, s InstanceStore, registry ImageRegistry) *DockerService {
+func NewDockerService(cli *client.Client, s InstanceStore, registry GameRegistry) *DockerService {
 	return &DockerService{cli: cli, store: s, registry: registry}
 }
 
 // CreateInstance 创建托管容器并持久化实例元数据。
 // TODO: 让 Docker 创建与 SQLite 保存具备原子性。
-func (s *DockerService) CreateInstance(ctx context.Context, name, imageID string) (string, error) {
+func (s *DockerService) CreateInstance(ctx context.Context, name, gameID string, params map[string]string) (string, error) {
 	if s.registry == nil {
-		return "", fmt.Errorf("image registry is not configured")
+		return "", fmt.Errorf("game registry is not configured")
 	}
 
-	regImage, err := s.registry.GetImage(ctx, imageID)
+	game, err := s.registry.GetGame(ctx, gameID)
 	if err != nil {
 		return "", err
 	}
 
-	if err := s.ensureImage(ctx, regImage.Image); err != nil {
+	tpl, err := s.registry.GetTemplate(ctx, game.ID)
+	if err != nil {
+		return "", err
+	}
+
+	env, err := mergeTemplateEnv(tpl, params)
+	if err != nil {
+		return "", err
+	}
+
+	imageRef := tpl.Image.FullImageRef()
+	if strings.TrimSpace(imageRef) == "" {
+		return "", model.ErrTemplateInvalid
+	}
+
+	if err := s.ensureImage(ctx, imageRef); err != nil {
 		return "", err
 	}
 
 	resp, err := s.cli.ContainerCreate(ctx, &container.Config{
-		Image: regImage.Image,
+		Image: imageRef,
 		Cmd:   []string{"sleep", "3600"},
+		Env:   mapToDockerEnv(env),
 		Labels: map[string]string{
 			managedLabelKey: managedLabelValue,
 			nameLabelKey:    name,
+			gameIDLabelKey:  game.ID,
 		},
 	}, nil, nil, nil, "")
 	if err != nil {
@@ -82,6 +102,128 @@ func (s *DockerService) CreateInstance(ctx context.Context, name, imageID string
 	return resp.ID, nil
 }
 
+func mergeTemplateEnv(tpl model.GameTemplate, params map[string]string) (map[string]string, error) {
+	merged := make(map[string]string, len(tpl.Container.Env)+len(tpl.Params))
+	for key, value := range tpl.Container.Env {
+		merged[key] = value
+	}
+
+	paramDefs := make(map[string]model.TemplateParam, len(tpl.Params))
+	for _, param := range tpl.Params {
+		paramDefs[param.Key] = param
+
+		defaultValue, ok := stringifyTemplateDefault(param)
+		if !ok {
+			continue
+		}
+		envKey := strings.TrimSpace(param.EnvVar)
+		if envKey == "" {
+			envKey = param.Key
+		}
+		merged[envKey] = defaultValue
+	}
+
+	for key, rawValue := range params {
+		paramKey := strings.TrimSpace(key)
+		paramDef, exists := paramDefs[paramKey]
+		if !exists {
+			return nil, fmt.Errorf("unknown param key %q: %w", paramKey, model.ErrInvalidParams)
+		}
+
+		normalized, err := normalizeParamValue(paramDef, rawValue)
+		if err != nil {
+			return nil, err
+		}
+
+		envKey := strings.TrimSpace(paramDef.EnvVar)
+		if envKey == "" {
+			envKey = paramDef.Key
+		}
+		merged[envKey] = normalized
+	}
+
+	return merged, nil
+}
+
+func normalizeParamValue(param model.TemplateParam, raw string) (string, error) {
+	switch param.Type {
+	case "string":
+		return raw, nil
+	case "number":
+		trimmed := strings.TrimSpace(raw)
+		if trimmed == "" {
+			return "", fmt.Errorf("param %q requires number value: %w", param.Key, model.ErrInvalidParams)
+		}
+		if _, err := strconv.ParseFloat(trimmed, 64); err != nil {
+			return "", fmt.Errorf("param %q has invalid number %q: %w", param.Key, raw, model.ErrInvalidParams)
+		}
+		return trimmed, nil
+	case "boolean":
+		trimmed := strings.TrimSpace(strings.ToLower(raw))
+		if trimmed == "" {
+			return "", fmt.Errorf("param %q requires boolean value: %w", param.Key, model.ErrInvalidParams)
+		}
+		v, err := strconv.ParseBool(trimmed)
+		if err != nil {
+			return "", fmt.Errorf("param %q has invalid boolean %q: %w", param.Key, raw, model.ErrInvalidParams)
+		}
+		if v {
+			return "true", nil
+		}
+		return "false", nil
+	case "select":
+		trimmed := strings.TrimSpace(raw)
+		if trimmed == "" {
+			return "", fmt.Errorf("param %q requires selected value: %w", param.Key, model.ErrInvalidParams)
+		}
+		for _, option := range param.Options {
+			if option.Value == trimmed {
+				return trimmed, nil
+			}
+		}
+		return "", fmt.Errorf("param %q has unsupported value %q: %w", param.Key, raw, model.ErrInvalidParams)
+	default:
+		return "", fmt.Errorf("param %q has unsupported type %q: %w", param.Key, param.Type, model.ErrTemplateInvalid)
+	}
+}
+
+func stringifyTemplateDefault(param model.TemplateParam) (string, bool) {
+	if param.Default == nil {
+		return "", false
+	}
+
+	switch param.Type {
+	case "string", "select", "number":
+		value := strings.TrimSpace(fmt.Sprint(param.Default))
+		if value == "" {
+			return "", false
+		}
+		return value, true
+	case "boolean":
+		v, err := strconv.ParseBool(strings.TrimSpace(strings.ToLower(fmt.Sprint(param.Default))))
+		if err != nil {
+			return "", false
+		}
+		if v {
+			return "true", true
+		}
+		return "false", true
+	default:
+		return "", false
+	}
+}
+
+func mapToDockerEnv(m map[string]string) []string {
+	if len(m) == 0 {
+		return nil
+	}
+	env := make([]string, 0, len(m))
+	for key, value := range m {
+		env = append(env, fmt.Sprintf("%s=%s", key, value))
+	}
+	return env
+}
+
 // StartInstance 启动托管容器并更新持久化状态。
 func (s *DockerService) StartInstance(ctx context.Context, containerID string) error {
 	if err := s.cli.ContainerStart(ctx, containerID, container.StartOptions{}); err != nil {
diff --git a/backend/internal/service/game_service.go b/backend/internal/service/game_service.go
new file mode 100644
index 0000000..21c0051
--- /dev/null
+++ b/backend/internal/service/game_service.go
@@ -0,0 +1,294 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+
+	"minedock/backend/internal/model"
+)
+
+var allowedParamTypes = map[string]struct{}{
+	"string":  {},
+	"number":  {},
+	"boolean": {},
+	"select":  {},
+}
+
+// GameService 提供游戏目录查询和模板按需加载能力。
+type GameService struct {
+	games       []model.Game
+	gameMap     map[string]model.Game
+	templateDir string
+}
+
+// NewGameService 从 games.json 加载游戏目录，并记录模板目录路径。
+func NewGameService(gamesFilePath string, templateDirPath string) (*GameService, error) {
+	gamesPath := strings.TrimSpace(gamesFilePath)
+	if gamesPath == "" {
+		return nil, fmt.Errorf("games path is required")
+	}
+
+	templateDir := strings.TrimSpace(templateDirPath)
+	if templateDir == "" {
+		return nil, fmt.Errorf("template dir path is required")
+	}
+
+	content, err := os.ReadFile(gamesPath)
+	if err != nil {
+		return nil, fmt.Errorf("read games file: %w", err)
+	}
+
+	var games []model.Game
+	if err := json.Unmarshal(content, &games); err != nil {
+		return nil, fmt.Errorf("decode games file: %w", err)
+	}
+
+	gameMap := make(map[string]model.Game, len(games))
+	for i, game := range games {
+		normalized, err := normalizeGame(game)
+		if err != nil {
+			return nil, fmt.Errorf("invalid game at index %d: %w", i, err)
+		}
+
+		if _, exists := gameMap[normalized.ID]; exists {
+			return nil, fmt.Errorf("duplicate game id: %s", normalized.ID)
+		}
+
+		templatePath := filepath.Join(templateDir, normalized.ID+".yaml")
+		if _, err := os.Stat(templatePath); err != nil {
+			if os.IsNotExist(err) {
+				return nil, fmt.Errorf("template for game %q: %w", normalized.ID, model.ErrTemplateNotFound)
+			}
+			return nil, fmt.Errorf("stat template for game %q: %w", normalized.ID, err)
+		}
+
+		games[i] = normalized
+		gameMap[normalized.ID] = normalized
+	}
+
+	return &GameService{games: games, gameMap: gameMap, templateDir: templateDir}, nil
+}
+
+// ListGames 返回游戏目录（轻量列表）。
+func (s *GameService) ListGames(_ context.Context) []model.Game {
+	if s == nil || len(s.games) == 0 {
+		return []model.Game{}
+	}
+	out := make([]model.Game, len(s.games))
+	copy(out, s.games)
+	return out
+}
+
+// GetGame 按 ID 查找游戏条目。
+func (s *GameService) GetGame(_ context.Context, id string) (model.Game, error) {
+	if s == nil {
+		return model.Game{}, model.ErrGameNotFound
+	}
+
+	key := strings.TrimSpace(id)
+	if key == "" {
+		return model.Game{}, model.ErrGameNotFound
+	}
+
+	game, ok := s.gameMap[key]
+	if !ok {
+		return model.Game{}, model.ErrGameNotFound
+	}
+	return game, nil
+}
+
+// GetTemplate 按游戏 ID 加载并返回对应的 YAML 模板。
+func (s *GameService) GetTemplate(ctx context.Context, id string) (model.GameTemplate, error) {
+	if s == nil {
+		return model.GameTemplate{}, model.ErrGameNotFound
+	}
+
+	game, err := s.GetGame(ctx, id)
+	if err != nil {
+		return model.GameTemplate{}, err
+	}
+
+	templatePath := filepath.Join(s.templateDir, game.ID+".yaml")
+	content, err := os.ReadFile(templatePath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return model.GameTemplate{}, model.ErrTemplateNotFound
+		}
+		return model.GameTemplate{}, fmt.Errorf("read template %q: %w", game.ID, err)
+	}
+
+	var tpl model.GameTemplate
+	if err := yaml.Unmarshal(content, &tpl); err != nil {
+		return model.GameTemplate{}, fmt.Errorf("parse template %q: %w: %v", game.ID, model.ErrTemplateInvalid, err)
+	}
+
+	if err := normalizeTemplate(game.ID, &tpl); err != nil {
+		return model.GameTemplate{}, err
+	}
+
+	return tpl, nil
+}
+
+func normalizeGame(game model.Game) (model.Game, error) {
+	game.ID = strings.TrimSpace(game.ID)
+	game.Name = strings.TrimSpace(game.Name)
+	game.Description = strings.TrimSpace(game.Description)
+	game.Category = strings.TrimSpace(game.Category)
+	game.Icon = strings.TrimSpace(game.Icon)
+
+	if game.ID == "" {
+		return model.Game{}, fmt.Errorf("id is required")
+	}
+	if game.Name == "" {
+		return model.Game{}, fmt.Errorf("name is required")
+	}
+	if game.Description == "" {
+		return model.Game{}, fmt.Errorf("description is required")
+	}
+	if game.Category == "" {
+		return model.Game{}, fmt.Errorf("category is required")
+	}
+	if game.Icon == "" {
+		return model.Game{}, fmt.Errorf("icon is required")
+	}
+
+	return game, nil
+}
+
+func normalizeTemplate(gameID string, tpl *model.GameTemplate) error {
+	tpl.Image.Name = strings.TrimSpace(tpl.Image.Name)
+	tpl.Image.Tag = strings.TrimSpace(tpl.Image.Tag)
+	if tpl.Image.Name == "" {
+		return fmt.Errorf("template %q image.name is required: %w", gameID, model.ErrTemplateInvalid)
+	}
+	if tpl.Image.Tag == "" {
+		tpl.Image.Tag = "latest"
+	}
+
+	normalizedEnv := make(map[string]string, len(tpl.Container.Env))
+	for key, value := range tpl.Container.Env {
+		envKey := strings.TrimSpace(key)
+		if envKey == "" {
+			return fmt.Errorf("template %q contains empty env key: %w", gameID, model.ErrTemplateInvalid)
+		}
+		normalizedEnv[envKey] = value
+	}
+	tpl.Container.Env = normalizedEnv
+
+	for i := range tpl.Container.Ports {
+		if tpl.Container.Ports[i].Host <= 0 || tpl.Container.Ports[i].Container <= 0 {
+			return fmt.Errorf("template %q port index %d is invalid: %w", gameID, i, model.ErrTemplateInvalid)
+		}
+
+		protocol := strings.ToLower(strings.TrimSpace(tpl.Container.Ports[i].Protocol))
+		if protocol == "" {
+			protocol = "tcp"
+		}
+		if protocol != "tcp" && protocol != "udp" {
+			return fmt.Errorf("template %q port index %d has unsupported protocol: %w", gameID, i, model.ErrTemplateInvalid)
+		}
+		tpl.Container.Ports[i].Protocol = protocol
+	}
+
+	for i := range tpl.Container.Volumes {
+		tpl.Container.Volumes[i].Name = strings.TrimSpace(tpl.Container.Volumes[i].Name)
+		tpl.Container.Volumes[i].ContainerPath = strings.TrimSpace(tpl.Container.Volumes[i].ContainerPath)
+		if tpl.Container.Volumes[i].ContainerPath == "" {
+			return fmt.Errorf("template %q volume index %d container_path is required: %w", gameID, i, model.ErrTemplateInvalid)
+		}
+	}
+
+	params := make([]model.TemplateParam, 0, len(tpl.Params))
+	seenKeys := make(map[string]struct{}, len(tpl.Params))
+	for i := range tpl.Params {
+		param := tpl.Params[i]
+		param.Key = strings.TrimSpace(param.Key)
+		param.Label = strings.TrimSpace(param.Label)
+		param.Description = strings.TrimSpace(param.Description)
+		param.Type = strings.ToLower(strings.TrimSpace(param.Type))
+		param.EnvVar = strings.TrimSpace(param.EnvVar)
+
+		if param.Key == "" {
+			return fmt.Errorf("template %q param index %d key is required: %w", gameID, i, model.ErrTemplateInvalid)
+		}
+		if _, exists := seenKeys[param.Key]; exists {
+			return fmt.Errorf("template %q has duplicate param key %q: %w", gameID, param.Key, model.ErrTemplateInvalid)
+		}
+		seenKeys[param.Key] = struct{}{}
+
+		if _, ok := allowedParamTypes[param.Type]; !ok {
+			return fmt.Errorf("template %q param %q has unsupported type %q: %w", gameID, param.Key, param.Type, model.ErrTemplateInvalid)
+		}
+
+		if param.Label == "" {
+			param.Label = param.Key
+		}
+		if param.EnvVar == "" {
+			param.EnvVar = param.Key
+		}
+
+		if param.Type == "select" {
+			if len(param.Options) == 0 {
+				return fmt.Errorf("template %q param %q options are required for select type: %w", gameID, param.Key, model.ErrTemplateInvalid)
+			}
+			if err := validateSelectParam(gameID, param); err != nil {
+				return err
+			}
+		}
+
+		params = append(params, param)
+	}
+	if params == nil {
+		params = []model.TemplateParam{}
+	}
+	tpl.Params = params
+
+	if tpl.Container.Ports == nil {
+		tpl.Container.Ports = []model.PortMapping{}
+	}
+	if tpl.Container.Volumes == nil {
+		tpl.Container.Volumes = []model.VolumeMount{}
+	}
+
+	return nil
+}
+
+func validateSelectParam(gameID string, param model.TemplateParam) error {
+	options := make(map[string]struct{}, len(param.Options))
+	for i := range param.Options {
+		value := strings.TrimSpace(param.Options[i].Value)
+		label := strings.TrimSpace(param.Options[i].Label)
+		if value == "" {
+			return fmt.Errorf("template %q param %q option index %d value is required: %w", gameID, param.Key, i, model.ErrTemplateInvalid)
+		}
+		if label == "" {
+			label = value
+		}
+		if _, exists := options[value]; exists {
+			return fmt.Errorf("template %q param %q has duplicate option %q: %w", gameID, param.Key, value, model.ErrTemplateInvalid)
+		}
+		param.Options[i].Value = value
+		param.Options[i].Label = label
+		options[value] = struct{}{}
+	}
+
+	if param.Default == nil {
+		return nil
+	}
+
+	defaultValue := strings.TrimSpace(fmt.Sprint(param.Default))
+	if defaultValue == "" {
+		return nil
+	}
+	if _, ok := options[defaultValue]; !ok {
+		return fmt.Errorf("template %q param %q default value %q not in options: %w", gameID, param.Key, defaultValue, model.ErrTemplateInvalid)
+	}
+
+	return nil
+}
diff --git a/backend/internal/service/game_service_test.go b/backend/internal/service/game_service_test.go
new file mode 100644
index 0000000..3b7672f
--- /dev/null
+++ b/backend/internal/service/game_service_test.go
@@ -0,0 +1,222 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"minedock/backend/internal/model"
+)
+
+func writeFile(t *testing.T, path, content string) {
+	t.Helper()
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatalf("write file %s: %v", path, err)
+	}
+}
+
+func TestNewGameService_ListGamesSuccess(t *testing.T) {
+	tempDir := t.TempDir()
+	templatesDir := filepath.Join(tempDir, "templates")
+	if err := os.Mkdir(templatesDir, 0o755); err != nil {
+		t.Fatalf("mkdir templates: %v", err)
+	}
+
+	writeFile(t, filepath.Join(tempDir, "games.json"), `[
+  {
+    "id": "minecraft-java",
+    "name": "Minecraft Java",
+    "description": "desc",
+    "category": "minecraft",
+    "icon": "minecraft-java"
+  }
+]`)
+	writeFile(t, filepath.Join(templatesDir, "minecraft-java.yaml"), `image:
+  name: "itzg/minecraft-server"
+`)
+
+	svc, err := NewGameService(filepath.Join(tempDir, "games.json"), templatesDir)
+	if err != nil {
+		t.Fatalf("new game service: %v", err)
+	}
+
+	games := svc.ListGames(context.Background())
+	if len(games) != 1 {
+		t.Fatalf("expected 1 game, got %d", len(games))
+	}
+	if games[0].ID != "minecraft-java" {
+		t.Fatalf("unexpected game id: %s", games[0].ID)
+	}
+
+	games[0].Name = "changed"
+	games2 := svc.ListGames(context.Background())
+	if games2[0].Name != "Minecraft Java" {
+		t.Fatalf("expected cloned result, got %s", games2[0].Name)
+	}
+}
+
+func TestNewGameService_EmptyAndInvalidGamesFile(t *testing.T) {
+	t.Run("empty list", func(t *testing.T) {
+		tempDir := t.TempDir()
+		templatesDir := filepath.Join(tempDir, "templates")
+		if err := os.Mkdir(templatesDir, 0o755); err != nil {
+			t.Fatalf("mkdir templates: %v", err)
+		}
+		writeFile(t, filepath.Join(tempDir, "games.json"), `[]`)
+
+		svc, err := NewGameService(filepath.Join(tempDir, "games.json"), templatesDir)
+		if err != nil {
+			t.Fatalf("new game service: %v", err)
+		}
+		if got := svc.ListGames(context.Background()); len(got) != 0 {
+			t.Fatalf("expected empty list, got %d", len(got))
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		tempDir := t.TempDir()
+		templatesDir := filepath.Join(tempDir, "templates")
+		if err := os.Mkdir(templatesDir, 0o755); err != nil {
+			t.Fatalf("mkdir templates: %v", err)
+		}
+		writeFile(t, filepath.Join(tempDir, "games.json"), `{`)
+
+		if _, err := NewGameService(filepath.Join(tempDir, "games.json"), templatesDir); err == nil {
+			t.Fatal("expected error")
+		}
+	})
+}
+
+func TestNewGameService_MissingTemplateOnStartup(t *testing.T) {
+	tempDir := t.TempDir()
+	templatesDir := filepath.Join(tempDir, "templates")
+	if err := os.Mkdir(templatesDir, 0o755); err != nil {
+		t.Fatalf("mkdir templates: %v", err)
+	}
+
+	writeFile(t, filepath.Join(tempDir, "games.json"), `[
+  {
+    "id": "minecraft-java",
+    "name": "Minecraft Java",
+    "description": "desc",
+    "category": "minecraft",
+    "icon": "minecraft-java"
+  }
+]`)
+
+	_, err := NewGameService(filepath.Join(tempDir, "games.json"), templatesDir)
+	if !errors.Is(err, model.ErrTemplateNotFound) {
+		t.Fatalf("expected ErrTemplateNotFound, got %v", err)
+	}
+}
+
+func TestGameService_GetTemplateSuccess(t *testing.T) {
+	tempDir := t.TempDir()
+	templatesDir := filepath.Join(tempDir, "templates")
+	if err := os.Mkdir(templatesDir, 0o755); err != nil {
+		t.Fatalf("mkdir templates: %v", err)
+	}
+
+	writeFile(t, filepath.Join(tempDir, "games.json"), `[
+  {
+    "id": "minecraft-java",
+    "name": "Minecraft Java",
+    "description": "desc",
+    "category": "minecraft",
+    "icon": "minecraft-java"
+  }
+]`)
+	writeFile(t, filepath.Join(templatesDir, "minecraft-java.yaml"), `image:
+  name: "itzg/minecraft-server"
+container:
+  ports:
+    - host: 25565
+      container: 25565
+  env:
+    EULA: "TRUE"
+params:
+  - key: "SERVER_TYPE"
+    type: "select"
+    default: "PAPER"
+    options:
+      - value: "PAPER"
+`)
+
+	svc, err := NewGameService(filepath.Join(tempDir, "games.json"), templatesDir)
+	if err != nil {
+		t.Fatalf("new game service: %v", err)
+	}
+
+	tpl, err := svc.GetTemplate(context.Background(), "minecraft-java")
+	if err != nil {
+		t.Fatalf("get template: %v", err)
+	}
+	if tpl.Image.FullImageRef() != "itzg/minecraft-server:latest" {
+		t.Fatalf("unexpected image ref: %s", tpl.Image.FullImageRef())
+	}
+	if len(tpl.Container.Ports) != 1 || tpl.Container.Ports[0].Protocol != "tcp" {
+		t.Fatalf("unexpected port protocol: %+v", tpl.Container.Ports)
+	}
+	if len(tpl.Params) != 1 {
+		t.Fatalf("expected 1 param, got %d", len(tpl.Params))
+	}
+	if tpl.Params[0].EnvVar != "SERVER_TYPE" {
+		t.Fatalf("expected default env var, got %s", tpl.Params[0].EnvVar)
+	}
+	if tpl.Params[0].Label != "SERVER_TYPE" {
+		t.Fatalf("expected default label, got %s", tpl.Params[0].Label)
+	}
+}
+
+func TestGameService_GetTemplateErrors(t *testing.T) {
+	tempDir := t.TempDir()
+	templatesDir := filepath.Join(tempDir, "templates")
+	if err := os.Mkdir(templatesDir, 0o755); err != nil {
+		t.Fatalf("mkdir templates: %v", err)
+	}
+
+	gamesPath := filepath.Join(tempDir, "games.json")
+	templatePath := filepath.Join(templatesDir, "minecraft-java.yaml")
+	writeFile(t, gamesPath, `[
+  {
+    "id": "minecraft-java",
+    "name": "Minecraft Java",
+    "description": "desc",
+    "category": "minecraft",
+    "icon": "minecraft-java"
+  }
+]`)
+	writeFile(t, templatePath, `image:
+  name: "itzg/minecraft-server"
+`)
+
+	svc, err := NewGameService(gamesPath, templatesDir)
+	if err != nil {
+		t.Fatalf("new game service: %v", err)
+	}
+
+	if _, err := svc.GetTemplate(context.Background(), "not-exists"); !errors.Is(err, model.ErrGameNotFound) {
+		t.Fatalf("expected ErrGameNotFound, got %v", err)
+	}
+
+	if err := os.Remove(templatePath); err != nil {
+		t.Fatalf("remove template: %v", err)
+	}
+	if _, err := svc.GetTemplate(context.Background(), "minecraft-java"); !errors.Is(err, model.ErrTemplateNotFound) {
+		t.Fatalf("expected ErrTemplateNotFound, got %v", err)
+	}
+
+	writeFile(t, templatePath, `[`) // invalid yaml
+	if _, err := svc.GetTemplate(context.Background(), "minecraft-java"); !errors.Is(err, model.ErrTemplateInvalid) {
+		t.Fatalf("expected ErrTemplateInvalid for yaml parse error, got %v", err)
+	}
+
+	writeFile(t, templatePath, `image:
+  tag: "latest"
+`)
+	if _, err := svc.GetTemplate(context.Background(), "minecraft-java"); !errors.Is(err, model.ErrTemplateInvalid) {
+		t.Fatalf("expected ErrTemplateInvalid for missing image name, got %v", err)
+	}
+}
diff --git a/backend/internal/service/registry_service.go b/backend/internal/service/registry_service.go
deleted file mode 100644
index e7089a1..0000000
--- a/backend/internal/service/registry_service.go
+++ /dev/null
@@ -1,105 +0,0 @@
-package service
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"os"
-	"strings"
-
-	"minedock/backend/internal/model"
-)
-
-// RegistryService 提供可用镜像注册表的查询能力。
-type RegistryService struct {
-	images   []model.RegistryImage
-	imageMap map[string]model.RegistryImage
-}
-
-// NewRegistryService 从 JSON 文件加载镜像数据并构建查找索引。
-func NewRegistryService(filePath string) (*RegistryService, error) {
-	path := strings.TrimSpace(filePath)
-	if path == "" {
-		return nil, fmt.Errorf("registry path is required")
-	}
-
-	content, err := os.ReadFile(path)
-	if err != nil {
-		return nil, fmt.Errorf("read registry file: %w", err)
-	}
-
-	var images []model.RegistryImage
-	if err := json.Unmarshal(content, &images); err != nil {
-		return nil, fmt.Errorf("decode registry file: %w", err)
-	}
-
-	imageMap := make(map[string]model.RegistryImage, len(images))
-	for i, img := range images {
-		id := strings.TrimSpace(img.ID)
-		if id == "" {
-			return nil, fmt.Errorf("registry image at index %d has empty id", i)
-		}
-		if strings.TrimSpace(img.Image) == "" {
-			return nil, fmt.Errorf("registry image %q has empty image", id)
-		}
-		if _, exists := imageMap[id]; exists {
-			return nil, fmt.Errorf("duplicate registry image id: %s", id)
-		}
-		img.ID = id
-		img.Image = strings.TrimSpace(img.Image)
-		imageMap[id] = img
-		images[i] = img
-	}
-
-	return &RegistryService{images: images, imageMap: imageMap}, nil
-}
-
-// ListImages 返回注册表中全部可用镜像。
-func (s *RegistryService) ListImages(_ context.Context) []model.RegistryImage {
-	if s == nil || len(s.images) == 0 {
-		return []model.RegistryImage{}
-	}
-	out := make([]model.RegistryImage, 0, len(s.images))
-	for _, img := range s.images {
-		out = append(out, cloneRegistryImage(img))
-	}
-	return out
-}
-
-// GetImage 按 ID 查找镜像，未找到时返回 model.ErrImageNotFound。
-func (s *RegistryService) GetImage(_ context.Context, id string) (model.RegistryImage, error) {
-	if s == nil {
-		return model.RegistryImage{}, model.ErrImageNotFound
-	}
-
-	key := strings.TrimSpace(id)
-	if key == "" {
-		return model.RegistryImage{}, model.ErrImageNotFound
-	}
-
-	img, ok := s.imageMap[key]
-	if !ok {
-		return model.RegistryImage{}, model.ErrImageNotFound
-	}
-	return cloneRegistryImage(img), nil
-}
-
-func cloneRegistryImage(img model.RegistryImage) model.RegistryImage {
-	clone := img
-	if len(img.DefaultEnv) > 0 {
-		clone.DefaultEnv = make(map[string]string, len(img.DefaultEnv))
-		for k, v := range img.DefaultEnv {
-			clone.DefaultEnv[k] = v
-		}
-	} else {
-		clone.DefaultEnv = map[string]string{}
-	}
-
-	if len(img.DefaultPorts) > 0 {
-		clone.DefaultPorts = append([]string(nil), img.DefaultPorts...)
-	} else {
-		clone.DefaultPorts = []string{}
-	}
-
-	return clone
-}
diff --git a/backend/internal/service/registry_service_test.go b/backend/internal/service/registry_service_test.go
deleted file mode 100644
index 7c04506..0000000
--- a/backend/internal/service/registry_service_test.go
+++ /dev/null
@@ -1,119 +0,0 @@
-package service
-
-import (
-	"context"
-	"errors"
-	"os"
-	"path/filepath"
-	"testing"
-
-	"minedock/backend/internal/model"
-)
-
-func writeRegistryFile(t *testing.T, content string) string {
-	t.Helper()
-	path := filepath.Join(t.TempDir(), "registry.json")
-	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
-		t.Fatalf("write registry: %v", err)
-	}
-	return path
-}
-
-func TestNewRegistryService_Success(t *testing.T) {
-	path := writeRegistryFile(t, `[
-  {
-    "id": "minecraft-java",
-    "name": "Minecraft Java Edition",
-    "image": "itzg/minecraft-server:latest",
-    "description": "desc",
-    "category": "minecraft",
-    "icon": "minecraft-java",
-    "default_env": {"EULA": "TRUE"},
-    "default_ports": ["25565:25565"]
-  }
-]`)
-
-	svc, err := NewRegistryService(path)
-	if err != nil {
-		t.Fatalf("new registry service: %v", err)
-	}
-
-	images := svc.ListImages(context.Background())
-	if len(images) != 1 {
-		t.Fatalf("expected 1 image, got %d", len(images))
-	}
-	if images[0].ID != "minecraft-java" {
-		t.Fatalf("unexpected image id: %s", images[0].ID)
-	}
-
-	images[0].DefaultEnv["EULA"] = "FALSE"
-	images2 := svc.ListImages(context.Background())
-	if images2[0].DefaultEnv["EULA"] != "TRUE" {
-		t.Fatalf("expected cloned env map, got %s", images2[0].DefaultEnv["EULA"])
-	}
-}
-
-func TestNewRegistryService_InvalidJSON(t *testing.T) {
-	path := writeRegistryFile(t, `{`)
-
-	_, err := NewRegistryService(path)
-	if err == nil {
-		t.Fatal("expected error")
-	}
-}
-
-func TestNewRegistryService_DuplicateID(t *testing.T) {
-	path := writeRegistryFile(t, `[
-  {"id": "a", "name": "A", "image": "repo/a:latest", "default_env": {}, "default_ports": []},
-  {"id": "a", "name": "B", "image": "repo/b:latest", "default_env": {}, "default_ports": []}
-]`)
-
-	_, err := NewRegistryService(path)
-	if err == nil {
-		t.Fatal("expected duplicate id error")
-	}
-}
-
-func TestNewRegistryService_EmptyRequiredField(t *testing.T) {
-	path := writeRegistryFile(t, `[
-  {"id": "", "name": "A", "image": "repo/a:latest", "default_env": {}, "default_ports": []}
-]`)
-
-	_, err := NewRegistryService(path)
-	if err == nil {
-		t.Fatal("expected empty id error")
-	}
-
-	path = writeRegistryFile(t, `[
-  {"id": "a", "name": "A", "image": "", "default_env": {}, "default_ports": []}
-]`)
-
-	_, err = NewRegistryService(path)
-	if err == nil {
-		t.Fatal("expected empty image error")
-	}
-}
-
-func TestRegistryService_GetImage(t *testing.T) {
-	path := writeRegistryFile(t, `[
-  {"id": "minecraft-java", "name": "A", "image": "repo/a:latest", "default_env": {}, "default_ports": []}
-]`)
-
-	svc, err := NewRegistryService(path)
-	if err != nil {
-		t.Fatalf("new registry service: %v", err)
-	}
-
-	img, err := svc.GetImage(context.Background(), "minecraft-java")
-	if err != nil {
-		t.Fatalf("get image: %v", err)
-	}
-	if img.Image != "repo/a:latest" {
-		t.Fatalf("unexpected image: %s", img.Image)
-	}
-
-	_, err = svc.GetImage(context.Background(), "not-exists")
-	if !errors.Is(err, model.ErrImageNotFound) {
-		t.Fatalf("expected ErrImageNotFound, got %v", err)
-	}
-}
diff --git a/backend/main.go b/backend/main.go
index 76a2694..c6f9432 100644
--- a/backend/main.go
+++ b/backend/main.go
@@ -31,27 +31,32 @@ func main() {
 	}
 	defer sqliteStore.Close()
 
-	registryPath := os.Getenv("MINEDOCK_REGISTRY_PATH")
-	if registryPath == "" {
-		registryPath = "registry.json"
+	gamesPath := os.Getenv("MINEDOCK_GAMES_PATH")
+	if gamesPath == "" {
+		gamesPath = "games.json"
 	}
 
-	registrySvc, err := service.NewRegistryService(registryPath)
+	templatesDir := os.Getenv("MINEDOCK_TEMPLATES_DIR")
+	if templatesDir == "" {
+		templatesDir = "templates"
+	}
+
+	gameSvc, err := service.NewGameService(gamesPath, templatesDir)
 	if err != nil {
-		log.Fatalf("init registry service: %v", err)
+		log.Fatalf("init game service: %v", err)
 	}
 
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
 
-	svc := service.NewDockerService(cli, sqliteStore, registrySvc)
+	svc := service.NewDockerService(cli, sqliteStore, gameSvc)
 	hub := service.NewEventHub(cli, svc.ListInstances)
 	go hub.Run(ctx)
 
 	h := api.NewHandler(svc)
-	registryHandler := api.NewRegistryHandler(registrySvc)
+	gameHandler := api.NewGameHandler(gameSvc)
 	wsHandler := api.NewWsHandler(hub)
-	router := api.NewRouter(h, registryHandler, wsHandler)
+	router := api.NewRouter(h, gameHandler, wsHandler)
 
 	addr := ":8080"
 	log.Printf("MineDock backend listening on %s", addr)
diff --git a/backend/templates/minecraft-bedrock.yaml b/backend/templates/minecraft-bedrock.yaml
new file mode 100644
index 0000000..ff5e303
--- /dev/null
+++ b/backend/templates/minecraft-bedrock.yaml
@@ -0,0 +1,47 @@
+image:
+  name: "itzg/minecraft-bedrock-server"
+  tag: "latest"
+
+container:
+  ports:
+    - host: 19132
+      container: 19132
+      protocol: "udp"
+  env:
+    EULA: "TRUE"
+  volumes:
+    - name: "server-data"
+      container_path: "/data"
+  resources:
+    memory: "1g"
+    cpu: 1.0
+
+params:
+  - key: "GAMEMODE"
+    label: "游戏模式"
+    description: "服务器默认游戏模式"
+    type: "select"
+    default: "survival"
+    options:
+      - value: "survival"
+        label: "生存"
+      - value: "creative"
+        label: "创造"
+      - value: "adventure"
+        label: "冒险"
+    env_var: "GAMEMODE"
+  - key: "DIFFICULTY"
+    label: "难度"
+    description: "服务器难度"
+    type: "select"
+    default: "normal"
+    options:
+      - value: "peaceful"
+        label: "和平"
+      - value: "easy"
+        label: "简单"
+      - value: "normal"
+        label: "普通"
+      - value: "hard"
+        label: "困难"
+    env_var: "DIFFICULTY"
diff --git a/backend/templates/minecraft-java.yaml b/backend/templates/minecraft-java.yaml
new file mode 100644
index 0000000..7c890a0
--- /dev/null
+++ b/backend/templates/minecraft-java.yaml
@@ -0,0 +1,59 @@
+image:
+  name: "itzg/minecraft-server"
+  tag: "latest"
+
+container:
+  ports:
+    - host: 25565
+      container: 25565
+      protocol: "tcp"
+  env:
+    EULA: "TRUE"
+    TYPE: "PAPER"
+  volumes:
+    - name: "server-data"
+      container_path: "/data"
+  resources:
+    memory: "2g"
+    cpu: 2.0
+  health_check:
+    test: ["CMD-SHELL", "mc-health"]
+    interval: "30s"
+    timeout: "10s"
+    retries: 3
+    start_period: "120s"
+
+params:
+  - key: "SERVER_TYPE"
+    label: "服务器类型"
+    description: "选择 Minecraft 服务器内核"
+    type: "select"
+    default: "PAPER"
+    options:
+      - value: "PAPER"
+        label: "Paper"
+      - value: "FABRIC"
+        label: "Fabric"
+      - value: "FORGE"
+        label: "Forge"
+      - value: "VANILLA"
+        label: "Vanilla"
+    env_var: "TYPE"
+  - key: "MC_VERSION"
+    label: "游戏版本"
+    description: "指定 Minecraft 版本号"
+    type: "string"
+    default: "LATEST"
+    env_var: "VERSION"
+  - key: "MAX_PLAYERS"
+    label: "最大玩家数"
+    description: "服务器最大在线人数"
+    type: "number"
+    default: 20
+    env_var: "MAX_PLAYERS"
+  - key: "ONLINE_MODE"
+    label: "正版验证"
+    description: "是否启用 Mojang 正版验证"
+    type: "boolean"
+    default: true
+    env_var: "ONLINE_MODE"
diff --git a/backend/templates/terraria.yaml b/backend/templates/terraria.yaml
new file mode 100644
index 0000000..a96034e
--- /dev/null
+++ b/backend/templates/terraria.yaml
@@ -0,0 +1,34 @@
+image:
+  name: "ryshe/terraria"
+  tag: "latest"
+
+container:
+  ports:
+    - host: 7777
+      container: 7777
+      protocol: "tcp"
+  volumes:
+    - name: "world-data"
+      container_path: "/root/.local/share/Terraria/Worlds"
+  resources:
+    memory: "1g"
+    cpu: 1.0
+
+params:
+  - key: "WORLD_SIZE"
+    label: "世界大小"
+    description: "新建世界的尺寸"
+    type: "select"
+    default: "2"
+    options:
+      - value: "1"
+        label: "小"
+      - value: "2"
+        label: "中"
+      - value: "3"
+        label: "大"
+  - key: "MAX_PLAYERS"
+    label: "最大玩家数"
+    description: "服务器最大在线人数"
+    type: "number"
+    default: 8
diff --git a/docs/api/contracts.md b/docs/api/contracts.md
index cff9459..5106a32 100644
--- a/docs/api/contracts.md
+++ b/docs/api/contracts.md
@@ -22,9 +22,9 @@
 [{ "container_id": "xxx", "name": "xxx", "status": "xxx" }]
 ```
 
-### GET /api/registry/images
+### GET /api/games
 
-- 说明：获取注册表中所有可用的容器镜像列表
+- 说明：获取游戏目录轻量列表（用于市场页快速加载）
 - 状态码：
   - 成功：`200`
   - 失败：`500`
@@ -36,26 +36,78 @@
   {
     "id": "minecraft-java",
     "name": "Minecraft Java Edition",
-    "image": "itzg/minecraft-server:latest",
     "description": "...",
     "category": "minecraft",
-    "icon": "minecraft-java",
-    "default_env": { "EULA": "TRUE" },
-    "default_ports": ["25565:25565"]
+    "icon": "minecraft-java"
   }
 ]
 ```
 
+### GET /api/games/:id/template
+
+- 说明：按游戏 ID 加载完整模板详情（YAML 解析结果）
+- 状态码：
+  - 成功：`200`
+  - 失败：`400`（ID 非法）、`404`（game 不存在）、`500`（模板不存在/模板非法）
+- 请求参数：
+  - 路径参数：`id`（game ID）
+- 返回结果：
+
+```json
+{
+  "image": {
+    "name": "itzg/minecraft-server",
+    "tag": "latest"
+  },
+  "container": {
+    "ports": [{ "host": 25565, "container": 25565, "protocol": "tcp" }],
+    "env": { "EULA": "TRUE", "TYPE": "PAPER" },
+    "volumes": [
+      { "name": "server-data", "container_path": "/data", "readonly": false }
+    ],
+    "resources": { "memory": "2g", "cpu": 2 },
+    "health_check": {
+      "test": ["CMD-SHELL", "mc-health"],
+      "interval": "30s",
+      "timeout": "10s",
+      "retries": 3,
+      "start_period": "120s"
+    }
+  },
+  "params": [
+    {
+      "key": "SERVER_TYPE",
+      "label": "服务器类型",
+      "description": "选择 Minecraft 服务器内核",
+      "type": "select",
+      "default": "PAPER",
+      "options": [
+        { "value": "PAPER", "label": "Paper" },
+        { "value": "FABRIC", "label": "Fabric" }
+      ],
+      "env_var": "TYPE"
+    }
+  ]
+}
+```
+
 ### POST /api/instances
 
 - 说明：创建一个新容器（初始为 Stopped）
 - 状态码：
   - 成功：`200`
-  - 失败：`400`（JSON非法/空名称/缺失 image_id/image_id 不合法）、`409`（名称冲突）、`500`
+  - 失败：`400`（JSON非法/空名称/缺失 game_id/game_id 不合法/params 非法）、`409`（名称冲突）、`500`（模板不存在或模板非法）
 - 请求参数：
 
 ```json
-{ "name": "容器1号", "image_id": "minecraft-java" }
+{
+  "name": "容器1号",
+  "game_id": "minecraft-java",
+  "params": {
+    "SERVER_TYPE": "PAPER",
+    "ONLINE_MODE": "true"
+  }
+}
 ```
 
 - 返回结果：
diff --git a/docs/design-docs/instance_lifecycle.md b/docs/design-docs/instance_lifecycle.md
index 20235b0..74ac716 100644
--- a/docs/design-docs/instance_lifecycle.md
+++ b/docs/design-docs/instance_lifecycle.md
@@ -10,8 +10,8 @@ type Instance struct {
     ContainerID string `json:"container_id"`
     // 服务端名称
     Name        string `json:"name"`
-    // 来源镜像的注册表 ID
-    ImageID     string `json:"image_id"`
+    // 来源游戏模板 ID（创建请求字段，当前版本未持久化到 instances 表）
+    GameID      string `json:"game_id"`
     // 当前运行态
     Status      string `json:"status"`
 }
diff --git a/docs/exec-plans/active/20260401-realtime-status-sync.md b/docs/exec-plans/completed/20260401-realtime-status-sync.md
similarity index 100%
rename from docs/exec-plans/active/20260401-realtime-status-sync.md
rename to docs/exec-plans/completed/20260401-realtime-status-sync.md
diff --git a/docs/exec-plans/completed/20260401-yaml-game-template-design.md b/docs/exec-plans/completed/20260401-yaml-game-template-design.md
new file mode 100644
index 0000000..8cc78e4
--- /dev/null
+++ b/docs/exec-plans/completed/20260401-yaml-game-template-design.md
@@ -0,0 +1,761 @@
+# 基于 YAML 的游戏模板规范设计
+
+## 背景
+
+当前 MineDock 使用 `registry.json` 作为静态镜像注册表，以 JSON 平铺方式定义游戏服务器的基础信息（镜像名、默认环境变量、默认端口）。随着项目演进，该方案暴露出以下局限性：
+
+- **表达力不足**：无法描述卷挂载、资源限制（CPU/内存）、健康检查、启动命令覆盖等容器高级配置
+- **用户可定制性差**：`default_env` 和 `default_ports` 虽然预留了字段，但创建流程中没有暴露用户定制入口；用户创建实例时无法调整任何参数
+- **可读性与可维护性**：JSON 不支持注释，游戏模板作为面向运维/高级用户的配置文件，缺少自文档化能力
+- **扩展性受限**：新增字段需要改动 Go 结构体、JSON 文件和前端类型定义三处，耦合度高
+
+本计划采用 **两层架构** 替代现有方案：
+
+1. **游戏目录层（`games.json`）**：轻量级游戏索引，包含 ID、名称、分类、图标等展示信息，供列表页快速加载
+2. **模板详情层（`templates/*.yaml`）**：每个游戏对应一份 YAML 模板文件，包含完整的容器配置和用户可定制参数，按需加载
+
+这种分离实现了：列表页秒开（只读小 JSON）、详情页按需获取（仅在用户点入具体游戏时加载 YAML）、模板可独立迭代。
+
+## 需要评审的内容
+
+> [!IMPORTANT]
+> **API Breaking Change**
+>
+> 本计划引入两个新 API 并替代原有端点：
+>
+> - `GET /api/registry/images` → 替换为 `GET /api/games`（返回轻量目录）
+> - 新增 `GET /api/games/:id/template`（按需返回单个模板详情）
+> - `POST /api/instances` 请求体从 `{ "name": "xxx", "image_id": "xxx" }` 扩展为 `{ "name": "xxx", "game_id": "xxx", "params": { ... } }`
+> - 旧的 `image_id` 字段将被 `game_id` 替代
+
+> [!IMPORTANT]
+> **两层数据存储**
+>
+> 从单个 `registry.json` 迁移为：
+>
+> - `games.json` — 游戏目录索引（JSON，保留快速读取和简单编辑的优势）
+> - `templates/` 目录 — 每个游戏一个 YAML 文件（支持注释、结构化复杂配置）
+>
+> `games.json` 中每条记录的 `id` 与 `templates/{id}.yaml` 文件名一一对应。
+
+> [!WARNING]
+> **向后兼容性**
+>
+> 本次变更不做向后兼容。已有的通过 `image_id` 创建的容器实例不受影响（它们已存在于 Docker 和 SQLite 中），但新创建流程将使用 `game_id`。建议在合并前同步完成前端适配。
+
+## 数据架构设计
+
+### 文件组织
+
+```text
+backend/
+├── games.json                     # 游戏目录索引（替代 registry.json）
+├── templates/                     # YAML 模板目录
+│   ├── minecraft-java.yaml
+│   ├── minecraft-bedrock.yaml
+│   └── terraria.yaml
+```
+
+### 第一层：games.json（游戏目录）
+
+轻量级 JSON 文件，前端列表页一次性加载，仅包含展示所需的最小信息集：
+
+```json
+[
+  {
+    "id": "minecraft-java",
+    "name": "Minecraft Java Edition",
+    "description": "最流行的 Minecraft Java 版服务器，支持原版/Forge/Fabric/Paper 等多种模组加载器。",
+    "category": "minecraft",
+    "icon": "minecraft-java"
+  },
+  {
+    "id": "minecraft-bedrock",
+    "name": "Minecraft Bedrock Edition",
+    "description": "Minecraft 基岩版服务器，支持手机/主机/Win10 跨平台联机。",
+    "category": "minecraft",
+    "icon": "minecraft-bedrock"
+  },
+  {
+    "id": "terraria",
+    "name": "Terraria",
+    "description": "Terraria 专用服务器，支持 tShock 管理。",
+    "category": "sandbox",
+    "icon": "terraria"
+  }
+]
+```
+
+**字段说明：**
+
+| 字段          | 类型   | 必填 | 说明                                            |
+| ------------- | ------ | ---- | ----------------------------------------------- |
+| `id`          | string | ✅   | 唯一标识，同时对应 `templates/{id}.yaml` 文件名 |
+| `name`        | string | ✅   | 前端展示名称                                    |
+| `description` | string | ✅   | 简要说明                                        |
+| `category`    | string | ✅   | 游戏分类（如 `minecraft`、`sandbox`）           |
+| `icon`        | string | ✅   | 图标标识（前端用于匹配图标资源）                |
+
+### 第二层：YAML 模板（按需加载）
+
+用户在列表页点入某个游戏后，前端请求 `GET /api/games/:id/template` 获取该游戏的完整模板配置。
+
+#### 模板 Schema 定义
+
+```yaml
+# Docker 镜像配置
+image:
+  name: "itzg/minecraft-server" # 镜像名称（必填，不含 tag）
+  tag: "latest" # 镜像标签（选填，默认 latest）
+
+# 容器运行配置
+container:
+  # 端口映射（选填）
+  ports:
+    - host: 25565
+      container: 25565
+      protocol: "tcp" # tcp | udp，默认 tcp
+
+  # 环境变量（选填）
+  env:
+    EULA: "TRUE"
+    TYPE: "PAPER"
+
+  # 卷挂载（选填）
+  volumes:
+    - name: "server-data" # 卷标识（用于生成唯一卷名）
+      container_path: "/data" # 容器内挂载路径（必填）
+      readonly: false # 是否只读（选填，默认 false）
+
+  # 资源限制（选填）
+  resources:
+    memory: "2g" # 内存上限（Docker 格式：512m, 1g, 2g）
+    cpu: 2.0 # CPU 核数上限
+
+  # 启动命令覆盖（选填）
+  # command: ["java", "-jar", "server.jar"]
+
+  # 健康检查（选填）
+  health_check:
+    test: ["CMD-SHELL", "mc-health"] # 检查命令
+    interval: "30s" # 检查间隔
+    timeout: "10s" # 超时
+    retries: 3 # 重试次数
+    start_period: "60s" # 启动等待
+
+# 用户可定制参数（选填）
+# 用户创建实例时可以覆盖的配置项
+params:
+  - key: "SERVER_TYPE" # 参数键
+    label: "服务器类型" # 前端显示名称
+    description: "选择 Minecraft 服务器内核"
+    type: "select" # 参数类型：string | number | boolean | select
+    default: "PAPER" # 默认值
+    options: # type 为 select 时的可选项
+      - value: "PAPER"
+        label: "Paper"
+      - value: "FABRIC"
+        label: "Fabric"
+      - value: "FORGE"
+        label: "Forge"
+      - value: "VANILLA"
+        label: "Vanilla"
+    env_var: "TYPE" # 映射到的环境变量名（选填，默认等于 key）
+```
+
+> [!NOTE]
+> 注意 YAML 模板中**不再包含** `meta`（name / description / category / icon）信息——这些展示字段已在 `games.json` 中定义，避免重复维护。模板仅关注技术配置（镜像、容器、参数）。
+
+### 完整示例
+
+#### minecraft-java.yaml
+
+```yaml
+image:
+  name: "itzg/minecraft-server"
+  tag: "latest"
+
+container:
+  ports:
+    - host: 25565
+      container: 25565
+      protocol: "tcp"
+  env:
+    EULA: "TRUE"
+    TYPE: "PAPER"
+  volumes:
+    - name: "server-data"
+      container_path: "/data"
+  resources:
+    memory: "2g"
+    cpu: 2.0
+  health_check:
+    test: ["CMD-SHELL", "mc-health"]
+    interval: "30s"
+    timeout: "10s"
+    retries: 3
+    start_period: "120s"
+
+params:
+  - key: "SERVER_TYPE"
+    label: "服务器类型"
+    description: "选择 Minecraft 服务器内核"
+    type: "select"
+    default: "PAPER"
+    options:
+      - value: "PAPER"
+        label: "Paper"
+      - value: "FABRIC"
+        label: "Fabric"
+      - value: "FORGE"
+        label: "Forge"
+      - value: "VANILLA"
+        label: "Vanilla"
+    env_var: "TYPE"
+  - key: "MC_VERSION"
+    label: "游戏版本"
+    description: "指定 Minecraft 版本号"
+    type: "string"
+    default: "LATEST"
+    env_var: "VERSION"
+  - key: "MAX_PLAYERS"
+    label: "最大玩家数"
+    description: "服务器最大在线人数"
+    type: "number"
+    default: 20
+    env_var: "MAX_PLAYERS"
+  - key: "ONLINE_MODE"
+    label: "正版验证"
+    description: "是否启用 Mojang 正版验证"
+    type: "boolean"
+    default: true
+    env_var: "ONLINE_MODE"
+```
+
+#### minecraft-bedrock.yaml
+
+```yaml
+image:
+  name: "itzg/minecraft-bedrock-server"
+  tag: "latest"
+
+container:
+  ports:
+    - host: 19132
+      container: 19132
+      protocol: "udp"
+  env:
+    EULA: "TRUE"
+  volumes:
+    - name: "server-data"
+      container_path: "/data"
+  resources:
+    memory: "1g"
+    cpu: 1.0
+
+params:
+  - key: "GAMEMODE"
+    label: "游戏模式"
+    description: "服务器默认游戏模式"
+    type: "select"
+    default: "survival"
+    options:
+      - value: "survival"
+        label: "生存"
+      - value: "creative"
+        label: "创造"
+      - value: "adventure"
+        label: "冒险"
+    env_var: "GAMEMODE"
+  - key: "DIFFICULTY"
+    label: "难度"
+    description: "服务器难度"
+    type: "select"
+    default: "normal"
+    options:
+      - value: "peaceful"
+        label: "和平"
+      - value: "easy"
+        label: "简单"
+      - value: "normal"
+        label: "普通"
+      - value: "hard"
+        label: "困难"
+    env_var: "DIFFICULTY"
+```
+
+#### terraria.yaml
+
+```yaml
+image:
+  name: "ryshe/terraria"
+  tag: "latest"
+
+container:
+  ports:
+    - host: 7777
+      container: 7777
+      protocol: "tcp"
+  volumes:
+    - name: "world-data"
+      container_path: "/root/.local/share/Terraria/Worlds"
+  resources:
+    memory: "1g"
+    cpu: 1.0
+
+params:
+  - key: "WORLD_SIZE"
+    label: "世界大小"
+    description: "新建世界的尺寸"
+    type: "select"
+    default: "2"
+    options:
+      - value: "1"
+        label: "小"
+      - value: "2"
+        label: "中"
+      - value: "3"
+        label: "大"
+  - key: "MAX_PLAYERS"
+    label: "最大玩家数"
+    description: "服务器最大在线人数"
+    type: "number"
+    default: 8
+```
+
+### 前端交互流程
+
+```mermaid
+sequenceDiagram
+    participant U as 用户
+    participant FE as 前端
+    participant BE as 后端
+
+    Note over FE: 镜像市场页加载
+    FE->>BE: GET /api/games
+    BE-->>FE: games.json 内容（轻量列表）
+    FE->>U: 展示游戏卡片列表
+
+    Note over U: 点击某个游戏卡片
+    U->>FE: 点击 "Minecraft Java Edition"
+    FE->>BE: GET /api/games/minecraft-java/template
+    BE-->>FE: minecraft-java.yaml 解析后的 JSON
+    FE->>U: 展示模板详情 + 参数表单
+
+    Note over U: 填写参数 & 创建
+    U->>FE: 填写实例名、调整参数、点击创建
+    FE->>BE: POST /api/instances { "name": "...", "game_id": "minecraft-java", "params": {...} }
+    BE-->>FE: { "status": "success", "container_id": "xxx" }
+```
+
+## 拟定更改
+
+### 数据文件
+
+#### [NEW] games.json (`backend/games.json`)
+
+游戏目录索引文件（替代 `registry.json`），包含三个初始游戏条目。
+
+#### [NEW] templates/ 目录 (`backend/templates/`)
+
+创建模板目录，包含三个初始 YAML 模板文件：
+
+- `minecraft-java.yaml`
+- `minecraft-bedrock.yaml`
+- `terraria.yaml`
+
+#### [DELETE] registry.json (`backend/registry.json`)
+
+迁移完成后删除旧的注册表文件。
+
+---
+
+### 后端 Model 层
+
+#### [NEW] game.go (`backend/internal/model/game.go`)
+
+新增游戏目录模型（轻量索引）：
+
+```go
+// Game 描述游戏目录中的一个条目（轻量展示信息）。
+type Game struct {
+    ID          string `json:"id"`
+    Name        string `json:"name"`
+    Description string `json:"description"`
+    Category    string `json:"category"`
+    Icon        string `json:"icon"`
+}
+```
+
+#### [MODIFY] registry.go → template.go (`backend/internal/model/template.go`)
+
+重命名文件，定义 YAML 模板数据模型（不含 meta 展示信息）：
+
+```go
+// GameTemplate 描述一个游戏服务器的完整技术配置模板。
+type GameTemplate struct {
+    Image     TemplateImage   `json:"image"     yaml:"image"`
+    Container ContainerConfig `json:"container" yaml:"container"`
+    Params    []TemplateParam `json:"params"    yaml:"params"`
+}
+
+// TemplateImage Docker 镜像配置。
+type TemplateImage struct {
+    Name string `json:"name" yaml:"name"`
+    Tag  string `json:"tag"  yaml:"tag"`
+}
+
+// FullImageRef 返回完整的镜像引用（name:tag）。
+func (i TemplateImage) FullImageRef() string { ... }
+
+// ContainerConfig 容器运行配置。
+type ContainerConfig struct {
+    Ports       []PortMapping      `json:"ports"                  yaml:"ports"`
+    Env         map[string]string  `json:"env"                    yaml:"env"`
+    Volumes     []VolumeMount      `json:"volumes"                yaml:"volumes"`
+    Resources   *ResourceLimits    `json:"resources,omitempty"    yaml:"resources"`
+    Command     []string           `json:"command,omitempty"      yaml:"command"`
+    HealthCheck *HealthCheckConfig `json:"health_check,omitempty" yaml:"health_check"`
+}
+
+// PortMapping 端口映射配置。
+type PortMapping struct {
+    Host      int    `json:"host"      yaml:"host"`
+    Container int    `json:"container" yaml:"container"`
+    Protocol  string `json:"protocol"  yaml:"protocol"`
+}
+
+// VolumeMount 卷挂载配置。
+type VolumeMount struct {
+    Name          string `json:"name"           yaml:"name"`
+    ContainerPath string `json:"container_path" yaml:"container_path"`
+    ReadOnly      bool   `json:"readonly"       yaml:"readonly"`
+}
+
+// ResourceLimits 资源限制配置。
+type ResourceLimits struct {
+    Memory string  `json:"memory" yaml:"memory"`
+    CPU    float64 `json:"cpu"    yaml:"cpu"`
+}
+
+// HealthCheckConfig 健康检查配置。
+type HealthCheckConfig struct {
+    Test        []string `json:"test"         yaml:"test"`
+    Interval    string   `json:"interval"     yaml:"interval"`
+    Timeout     string   `json:"timeout"      yaml:"timeout"`
+    Retries     int      `json:"retries"      yaml:"retries"`
+    StartPeriod string   `json:"start_period" yaml:"start_period"`
+}
+
+// TemplateParam 用户可定制参数定义。
+type TemplateParam struct {
+    Key         string        `json:"key"                   yaml:"key"`
+    Label       string        `json:"label"                 yaml:"label"`
+    Description string        `json:"description"           yaml:"description"`
+    Type        string        `json:"type"                  yaml:"type"`
+    Default     any           `json:"default"               yaml:"default"`
+    Options     []ParamOption `json:"options,omitempty"      yaml:"options"`
+    EnvVar      string        `json:"env_var,omitempty"     yaml:"env_var"`
+}
+
+// ParamOption select 类型参数的可选项。
+type ParamOption struct {
+    Value string `json:"value" yaml:"value"`
+    Label string `json:"label" yaml:"label"`
+}
+```
+
+#### [MODIFY] errors.go (`backend/internal/model/errors.go`)
+
+```go
+// ErrImageNotFound → 重命名
+var ErrGameNotFound = errors.New("game not found")
+
+// ErrTemplateNotFound 对应的模板文件不存在。
+var ErrTemplateNotFound = errors.New("template not found")
+
+// ErrTemplateInvalid 模板校验失败。
+var ErrTemplateInvalid = errors.New("invalid template")
+```
+
+---
+
+### 后端 Service 层
+
+#### [MODIFY] registry_service.go → game_service.go (`backend/internal/service/game_service.go`)
+
+重命名并重构为两层加载逻辑：
+
+```go
+// GameService 提供游戏目录查询和模板按需加载能力。
+type GameService struct {
+    games       []model.Game
+    gameMap     map[string]model.Game
+    templateDir string  // YAML 模板目录路径
+}
+
+// NewGameService 从 games.json 加载游戏目录，并记录模板目录路径。
+// 启动时仅校验 games.json 的合法性和每个 game ID 对应的 YAML 文件是否存在。
+func NewGameService(gamesFilePath string, templateDirPath string) (*GameService, error) { ... }
+
+// ListGames 返回游戏目录（轻量列表）。
+func (s *GameService) ListGames(_ context.Context) []model.Game { ... }
+
+// GetGame 按 ID 查找游戏条目。
+func (s *GameService) GetGame(_ context.Context, id string) (model.Game, error) { ... }
+
+// GetTemplate 按游戏 ID 加载并返回对应的 YAML 模板。
+// 每次调用都从文件系统读取并解析（保证看到最新文件内容）。
+func (s *GameService) GetTemplate(_ context.Context, id string) (model.GameTemplate, error) { ... }
+```
+
+> [!NOTE]
+> `GetTemplate` 计为每次调用都读取文件（而非启动时缓存全部模板）。原因：
+>
+> - 模板文件数量有限（通常 < 20），单文件解析开销极小
+> - 允许运维人员热更模板文件无需重启后端
+> - 如果后续性能分析发现瓶颈，可以轻松加一层 `sync.Map` 缓存
+
+#### [MODIFY] docker_service.go (`backend/internal/service/docker_service.go`)
+
+- `ImageRegistry` 接口替换为 `GameRegistry` 接口：
+
+```go
+// GameRegistry 定义 DockerService 依赖的游戏与模板查询能力。
+type GameRegistry interface {
+    GetGame(ctx context.Context, id string) (model.Game, error)
+    GetTemplate(ctx context.Context, id string) (model.GameTemplate, error)
+}
+```
+
+- `CreateInstance` 签名变更：`CreateInstance(ctx, name, gameID string, params map[string]string)`
+  - 先调用 `GetGame` 确认 game 存在
+  - 再调用 `GetTemplate` 获取完整模板
+  - **严格校验 params**：遍历用户传入的 params，若 key 不在模板 `params` 定义中，返回 `400` 拒绝（防止拼写错误导致参数静默失效）
+  - 合并合法 params 到模板默认环境变量
+  - **本期仅传入** `Image`、`Env`、`Labels` 到 `ContainerCreate`；端口映射、卷挂载、资源限制、健康检查等高级容器配置留作下一期实现（YAML 中定义但暂不生效）
+
+---
+
+### 后端 API 层
+
+#### [MODIFY] registry_handlers.go → game_handlers.go (`backend/internal/api/game_handlers.go`)
+
+```go
+// GameLister 定义游戏目录 Handler 依赖的查询操作。
+type GameLister interface {
+    ListGames(ctx context.Context) []model.Game
+    GetTemplate(ctx context.Context, id string) (model.GameTemplate, error)
+}
+
+// GameHandler 暴露游戏目录与模板相关 HTTP 处理器。
+type GameHandler struct {
+    games GameLister
+}
+
+// NewGameHandler 创建 GameHandler。
+func NewGameHandler(g GameLister) *GameHandler { ... }
+
+// GetGames 处理 GET /api/games，返回游戏目录列表。
+func (h *GameHandler) GetGames(w http.ResponseWriter, r *http.Request) { ... }
+
+// GetGameTemplate 处理 GET /api/games/{id}/template，按需返回模板详情。
+func (h *GameHandler) GetGameTemplate(w http.ResponseWriter, r *http.Request) { ... }
+```
+
+#### [MODIFY] handlers.go (`backend/internal/api/handlers.go`)
+
+- `createRequest` 字段变更：
+
+```go
+type createRequest struct {
+    Name   string            `json:"name"`
+    GameID string            `json:"game_id"`
+    Params map[string]string `json:"params"`
+}
+```
+
+- `InstanceService` 接口的 `CreateInstance` 签名同步更新：`CreateInstance(ctx, name, gameID string, params map[string]string)`
+- `mapErrorCode` 更新：`ErrImageNotFound` → `ErrGameNotFound`、新增 `ErrTemplateNotFound` → `500`、`ErrTemplateInvalid` → `500`
+
+#### [MODIFY] router.go (`backend/internal/api/router.go`)
+
+- 删除 `GET /api/registry/images`
+- 新增 `GET /api/games`
+- 新增 `GET /api/games/{id}/template`
+- 更新 `NewRouter` 签名和参数
+
+---
+
+### 后端入口
+
+#### [MODIFY] main.go
+
+- `MINEDOCK_REGISTRY_PATH` → `MINEDOCK_GAMES_PATH`（游戏目录文件路径，默认 `games.json`）
+- 新增 `MINEDOCK_TEMPLATES_DIR`（模板文件目录，默认 `templates`）
+- `NewRegistryService(path)` → `NewGameService(gamesPath, templatesDir)`
+- 注入链路同步更新
+
+---
+
+### 后端依赖
+
+#### [MODIFY] go.mod
+
+- 新增依赖：`gopkg.in/yaml.v3`
+
+---
+
+### 前端 API 层
+
+#### [MODIFY] index.ts (`frontend/src/api/index.ts`)
+
+- `RegistryImage` 类型重命名为 `Game`（轻量目录条目）
+- 新增 `GameTemplate`、`TemplateParam`、`ParamOption` 等类型定义
+- `listRegistryImages()` → `listGames()`
+- 新增 `getGameTemplate(id: string)` API 函数
+- `createInstance(name, imageId)` → `createInstance(name, gameId, params?)`
+
+---
+
+### 前端状态管理
+
+#### [MODIFY] registry.ts → games.ts (`frontend/src/stores/games.ts`)
+
+重命名并重构 store：
+
+```typescript
+// games store 管理游戏目录和当前选中模板
+export const useGameStore = defineStore('games', () => {
+  const games = ref<Game[]>([])                      // 游戏目录列表
+  const currentTemplate = ref<GameTemplate | null>(null)  // 当前查看的模板
+  const loading = ref(false)
+
+  // 加载游戏目录（列表页用）
+  async function fetchGames() { ... }
+
+  // 按需加载指定游戏的模板详情（点入详情时调用）
+  async function fetchTemplate(gameId: string) { ... }
+
+  // 按 ID 查找游戏条目
+  function getGameById(id: string) { ... }
+
+  return { games, currentTemplate, loading, fetchGames, fetchTemplate, getGameById }
+})
+```
+
+#### [MODIFY] containers.ts (`frontend/src/stores/containers.ts`)
+
+- `create(name, imageId)` → `create(name, gameId, params?)`
+
+---
+
+### 前端路由
+
+#### [MODIFY] router/index.ts (`frontend/src/router/index.ts`)
+
+- `/registry` 路由保持不变（游戏列表页）
+
+---
+
+### 文档
+
+#### [MODIFY] contracts.md (`docs/api/contracts.md`)
+
+- 删除 `GET /api/registry/images`
+- 新增 `GET /api/games` 文档（返回游戏目录列表）
+- 新增 `GET /api/games/:id/template` 文档（返回模板详情）
+- 更新 `POST /api/instances` 请求体：`image_id` → `game_id`，新增 `params`
+
+#### [MODIFY] instance_lifecycle.md (`docs/design-docs/instance_lifecycle.md`)
+
+- Instance 结构体中 `ImageID` 更新为 `GameID` 说明
+
+#### [MODIFY] directory.md (`docs/standards/directory.md`)
+
+- 新增 `templates/` 目录说明
+- 注释 `games.json` 用途
+
+---
+
+## 执行步骤
+
+- [ ] 后端依赖
+  - [ ] 执行 `go get gopkg.in/yaml.v3`，更新 `go.mod` 和 `go.sum`
+- [ ] 数据文件
+  - [ ] 编写 `backend/games.json`（三个游戏条目）
+  - [ ] 创建 `backend/templates/` 目录
+  - [ ] 编写 `templates/minecraft-java.yaml`
+  - [ ] 编写 `templates/minecraft-bedrock.yaml`
+  - [ ] 编写 `templates/terraria.yaml`
+- [ ] 后端 Model 层
+  - [ ] 新建 `backend/internal/model/game.go`，定义 `Game` 结构体
+  - [ ] 新建 `backend/internal/model/template.go`（替代 `registry.go`），定义 `GameTemplate` 及相关结构体
+  - [ ] 修改 `backend/internal/model/errors.go`：新增 `ErrGameNotFound`、`ErrTemplateNotFound`、`ErrTemplateInvalid`，删除 `ErrImageNotFound`
+  - [ ] 删除 `backend/internal/model/registry.go`
+- [ ] 后端 Service 层
+  - [ ] 新建 `backend/internal/service/game_service.go`（替代 `registry_service.go`），实现 JSON 目录加载 + YAML 按需解析
+  - [ ] 编写 `game_service_test.go` 单元测试
+    - [ ] `ListGames`：正常加载 / 空文件 / 格式错误
+    - [ ] `GetTemplate`：正常解析 / 文件不存在 / YAML 格式错误 / 必填字段缺失
+    - [ ] 启动校验：game ID 与 YAML 文件名的一致性检查
+  - [ ] 修改 `docker_service.go`：`ImageRegistry` → `GameRegistry`、`CreateInstance` 支持 `gameID` + `params`
+  - [ ] 删除 `registry_service.go` 和 `registry_service_test.go`
+- [ ] 后端 API 层
+  - [ ] 新建 `backend/internal/api/game_handlers.go`（替代 `registry_handlers.go`），实现 `GameHandler`
+  - [ ] 修改 `handlers.go`：`createRequest` 适配 `game_id` + `params`，`InstanceService` 接口更新
+  - [ ] 修改 `router.go`：删除 `/api/registry/images`，新增 `/api/games` 和 `/api/games/{id}/template`
+  - [ ] 更新 `handlers_test.go`
+  - [ ] 删除 `registry_handlers.go`
+- [ ] 后端入口
+  - [ ] 修改 `main.go`：环境变量、初始化链路、注入更新
+- [ ] 前端适配
+  - [ ] 修改 `frontend/src/api/index.ts`：类型定义和 API 函数更新
+  - [ ] 重命名 `frontend/src/stores/registry.ts` → `games.ts`，实现两层加载逻辑
+  - [ ] 修改 `frontend/src/stores/containers.ts`：`create` action 适配新签名
+- [ ] 前端参数表单 UI
+  - [ ] 实现动态参数表单组件（根据模板 `params` 定义渲染）
+    - [ ] `string` 类型 → 文本输入框
+    - [ ] `number` 类型 → 数字输入框
+    - [ ] `boolean` 类型 → 开关/复选框
+    - [ ] `select` 类型 → 下拉选择框（渲染 `options`）
+  - [ ] 在创建实例流程中集成参数表单（用户点入游戏详情后展示）
+  - [ ] 表单默认值从模板 `params[].default` 填充
+  - [ ] 提交时将表单值收集为 `params` 对象传入 `POST /api/instances`
+- [ ] 文档更新
+  - [ ] 修改 `docs/api/contracts.md`：更新/新增 API 端点文档
+  - [ ] 修改 `docs/design-docs/instance_lifecycle.md`：更新 `GameID` 字段
+  - [ ] 修改 `docs/standards/directory.md`：新增 `templates/` 和 `games.json` 说明
+- [ ] 清理
+  - [ ] 删除 `backend/registry.json`
+  - [ ] 全局搜索 `registry` / `image_id` / `RegistryImage` 残留引用，确保全部迁移
+
+## 已确认的决策
+
+- ✅ **params 参数合并策略**：采用严格模式——用户传入的 `params` 中若存在模板未定义的 key，返回 `400` 拒绝，防止拼写错误导致参数静默失效
+- ✅ **卷/资源/端口映射**：本期不生效。YAML 模板中可以定义 `volumes`、`resources`、`ports`、`health_check` 等字段（数据结构已就绪），但 `CreateInstance` 本期仅传入 `Image`、`Env`、`Labels`，高级容器配置留作下一期实现
+- ✅ **前端参数表单 UI**：本期包含。前端需根据模板 `params` 动态渲染参数表单（`string` → 输入框、`number` → 数字框、`boolean` → 开关、`select` → 下拉框），集成到创建实例流程中
+
+## 验证计划
+
+### 自动化测试
+
+- `task backend:test` — 覆盖：
+  - `GameService.ListGames`：正常 / 空 / 错误 JSON
+  - `GameService.GetTemplate`：正常 YAML / 文件不存在 / 格式错误 / 必填字段缺失
+  - `GameService` 启动校验：game ID 对应 YAML 不存在时报错
+  - `DockerService.CreateInstance`（mock）：有效 gameID、无效 gameID、参数合并
+  - `Handler` 层：请求体解析与错误映射
+- `task backend:vet && task backend:lint`
+- 前端：`npm run lint`
+
+### 手动验证
+
+- 启动后端，调用 `GET /api/games`，验证返回轻量游戏列表（无模板配置信息）
+- 调用 `GET /api/games/minecraft-java/template`，验证返回完整的模板详情（含 params、resources 等）
+- 调用 `GET /api/games/not-exist/template`，验证返回 `404`
+- 调用 `POST /api/instances` 传入 `game_id` + 合法 `params`，验证容器环境变量正确合并
+- 调用 `POST /api/instances` 传入未知 param key，验证返回 `400`（严格校验）
+- 修改 `templates/minecraft-java.yaml` 中某个默认值，不重启后端，调用 `GET /api/games/minecraft-java/template`，验证返回更新后的值（热更验证）
+- 前端：点入游戏详情页，验证参数表单正确渲染（输入框 / 下拉框 / 开关），默认值正确填充
+- 前端：调整参数后点击创建，验证请求体中 `params` 正确携带用户填写的值
diff --git a/docs/standards/directory.md b/docs/standards/directory.md
index 9c61602..102ff78 100644
--- a/docs/standards/directory.md
+++ b/docs/standards/directory.md
@@ -5,6 +5,8 @@ MineDock/
 ├── .github/                # 存放 CI/CD
 ├── backend/                # 后端 Go 服务
 │   ├── data/               # 数据存储目录
+│   ├── games.json          # 游戏目录索引（轻量展示信息）
+│   ├── templates/          # 游戏模板目录（YAML，按游戏 ID 命名）
 │   ├── internal/           # 内部私有代码
 │   │   ├── api/            # 路由与 HTTP 处理层
 │   │   ├── model/          # 领域数据模型定义
diff --git a/docs/standards/frontend.md b/docs/standards/frontend.md
index 3702197..1342922 100644
--- a/docs/standards/frontend.md
+++ b/docs/standards/frontend.md
@@ -69,7 +69,7 @@
 
 - 当前路由：
   - `/` 映射容器列表页（`ContainerList.vue`）
-  - `/registry` 映射镜像市场页（`ImageRegistry.vue`）
+  - `/registry` 映射游戏模板市场页（`ImageRegistry.vue`）
 - 当前版本无登录鉴权。
 - 新增页面时要求：
   - 在 `router/index.ts` 显式注册路由
diff --git a/docs/standards/ops.md b/docs/standards/ops.md
index 038d52c..5fc4bae 100644
--- a/docs/standards/ops.md
+++ b/docs/standards/ops.md
@@ -17,7 +17,8 @@
 
 - 后端：
   - `MINEDOCK_DB_PATH`（默认 `data/minedock.db`）
-  - `MINEDOCK_REGISTRY_PATH`（默认 `registry.json`）
+  - `MINEDOCK_GAMES_PATH`（默认 `games.json`）
+  - `MINEDOCK_TEMPLATES_DIR`（默认 `templates`）
 - 前端：
   - `VITE_API_BASE_URL`（默认 `/api`）
 
diff --git a/frontend/src/api/index.ts b/frontend/src/api/index.ts
index 866452b..3985fb8 100644
--- a/frontend/src/api/index.ts
+++ b/frontend/src/api/index.ts
@@ -110,29 +110,98 @@ export interface WsInstancesUpdated {
 
 export type WsMessage = WsInstancesUpdated;
 
-export interface RegistryImage {
+export interface Game {
   id: string;
   name: string;
-  image: string;
   description: string;
   category: string;
   icon: string;
-  default_env: Record<string, string>;
-  default_ports: string[];
+}
+
+export interface TemplateImage {
+  name: string;
+  tag: string;
+}
+
+export interface PortMapping {
+  host: number;
+  container: number;
+  protocol: string;
+}
+
+export interface VolumeMount {
+  name: string;
+  container_path: string;
+  readonly: boolean;
+}
+
+export interface ResourceLimits {
+  memory: string;
+  cpu: number;
+}
+
+export interface HealthCheckConfig {
+  test: string[];
+  interval: string;
+  timeout: string;
+  retries: number;
+  start_period: string;
+}
+
+export interface ContainerConfig {
+  ports: PortMapping[];
+  env: Record<string, string>;
+  volumes: VolumeMount[];
+  resources?: ResourceLimits;
+  command?: string[];
+  health_check?: HealthCheckConfig;
+}
+
+export interface ParamOption {
+  value: string;
+  label: string;
+}
+
+export type TemplateParamType = "string" | "number" | "boolean" | "select";
+
+export type TemplateParamDefault = string | number | boolean;
+
+export interface TemplateParam {
+  key: string;
+  label: string;
+  description: string;
+  type: TemplateParamType;
+  default: TemplateParamDefault;
+  options?: ParamOption[];
+  env_var?: string;
+}
+
+export interface GameTemplate {
+  image: TemplateImage;
+  container: ContainerConfig;
+  params: TemplateParam[];
 }
 
 export function listInstances(): Promise<Instance[]> {
   return request<Instance[]>("/instances", { method: "GET" });
 }
 
-export function listRegistryImages(): Promise<RegistryImage[]> {
-  return request<RegistryImage[]>("/registry/images", { method: "GET" });
+export function listGames(): Promise<Game[]> {
+  return request<Game[]>("/games", { method: "GET" });
+}
+
+export function getGameTemplate(id: string): Promise<GameTemplate> {
+  return request<GameTemplate>(`/games/${encodeURIComponent(id)}/template`, { method: "GET" });
 }
 
-export function createInstance(name: string, imageId: string): Promise<unknown> {
+export function createInstance(
+  name: string,
+  gameId: string,
+  params: Record<string, string> = {},
+): Promise<unknown> {
   return request("/instances", {
     method: "POST",
-    body: { name, image_id: imageId },
+    body: { name, game_id: gameId, params },
   });
 }
 
diff --git a/frontend/src/locales/en-US.json b/frontend/src/locales/en-US.json
index 9b8f005..20b70dd 100644
--- a/frontend/src/locales/en-US.json
+++ b/frontend/src/locales/en-US.json
@@ -10,19 +10,37 @@
   "createModal": {
     "title": "New Container",
     "placeholder": "Enter container name...",
-    "imageLabel": "Select Image",
-    "imagePlaceholder": "Please select an image",
-    "loadingImages": "Loading image list...",
-    "noImages": "No images available right now. Please try again later.",
+    "gameLabel": "Select Game",
+    "gamePlaceholder": "Please select a game template",
+    "loadingGames": "Loading game list...",
+    "noGames": "No game templates available right now. Please try again later.",
+    "loadingTemplate": "Loading template details...",
+    "paramsTitle": "Template Parameters",
+    "booleanEnabled": "Enabled",
+    "booleanDisabled": "Disabled",
     "cancel": "Cancel",
     "confirm": "OK"
   },
+  "createPage": {
+    "title": "Create Instance",
+    "loading": "Loading create page...",
+    "nameLabel": "Container Name",
+    "namePlaceholder": "Enter container name",
+    "loadingTemplate": "Loading template details...",
+    "paramsTitle": "Parameters",
+    "noParams": "This template has no configurable parameters.",
+    "booleanEnabled": "Enabled",
+    "booleanDisabled": "Disabled",
+    "cancel": "Cancel",
+    "confirm": "Create",
+    "creating": "Creating..."
+  },
   "status": {
     "waiting": "Waiting for action...",
     "listRefreshed": "Container list refreshed.",
     "noContainers": "No containers available.",
     "emptyName": "Container name cannot be empty",
-    "emptyImage": "Please select a container image",
+    "emptyGame": "Please select a game template",
     "creating": "Creating container...",
     "deleting": "Deleting container...",
     "stopping": "Stopping container: {name}...",
@@ -38,8 +56,11 @@
     "internal": "The service is temporarily unavailable. Please try again later.",
     "requestFailedWithStatus": "Request failed (status: {status}).",
     "invalidJsonBody": "The request body format is invalid.",
-    "imageIdRequired": "You must select an image before creating a container.",
-    "imageNotFound": "The selected image does not exist. Please refresh and try again.",
+    "gameIdRequired": "You must select a game template before creating a container.",
+    "gameNotFound": "The selected game template does not exist. Please refresh and try again.",
+    "invalidParams": "The submitted parameters are invalid. Please verify and retry.",
+    "templateNotFound": "Template file is missing on the server.",
+    "templateInvalid": "Template content is invalid on the server.",
     "invalidContainerId": "The container ID is invalid.",
     "instanceNameExists": "Container name already exists. Please choose another one.",
     "instanceRunning": "The container is running. Stop it before deleting.",
@@ -47,14 +68,24 @@
   },
   "sidebar": {
     "containerList": "Containers",
-    "imageRegistry": "Images"
+    "imageRegistry": "Game Templates"
   },
   "registry": {
-    "title": "Image Marketplace",
+    "title": "Game Template Marketplace",
     "filterAll": "All",
-    "emptyState": "No images available.",
-    "loading": "Loading image list...",
-    "loadError": "Failed to load image list. Please try again later."
+    "emptyState": "No game templates available.",
+    "loading": "Loading game list...",
+    "loadError": "Failed to load game list. Please try again later.",
+    "selectHint": "Select a game template from the left panel.",
+    "useTemplate": "Use This Template",
+    "templateLoading": "Loading template details...",
+    "templateLoadError": "Failed to load template details.",
+    "summaryImage": "Image",
+    "summaryPorts": "Default Ports",
+    "summaryParams": "Configurable Params",
+    "noParams": "This template has no configurable parameters.",
+    "defaultValue": "Default",
+    "options": "Options"
   },
   "topbar": {
     "switchLanguage": "Switch Language",
diff --git a/frontend/src/locales/zh-CN.json b/frontend/src/locales/zh-CN.json
index 89e5875..8dab688 100644
--- a/frontend/src/locales/zh-CN.json
+++ b/frontend/src/locales/zh-CN.json
@@ -10,19 +10,37 @@
   "createModal": {
     "title": "新建容器",
     "placeholder": "请输入新容器名称...",
-    "imageLabel": "选择镜像",
-    "imagePlaceholder": "请选择一个镜像",
-    "loadingImages": "镜像列表加载中...",
-    "noImages": "暂无可用镜像，请稍后重试。",
+    "gameLabel": "选择游戏",
+    "gamePlaceholder": "请选择一个游戏模板",
+    "loadingGames": "游戏列表加载中...",
+    "noGames": "暂无可用游戏模板，请稍后重试。",
+    "loadingTemplate": "模板详情加载中...",
+    "paramsTitle": "参数配置",
+    "booleanEnabled": "启用",
+    "booleanDisabled": "禁用",
     "cancel": "取消",
     "confirm": "确定"
   },
+  "createPage": {
+    "title": "创建容器",
+    "loading": "正在加载创建页面...",
+    "nameLabel": "容器名称",
+    "namePlaceholder": "请输入容器名称",
+    "loadingTemplate": "模板详情加载中...",
+    "paramsTitle": "参数配置",
+    "noParams": "该模板没有可调整参数。",
+    "booleanEnabled": "启用",
+    "booleanDisabled": "禁用",
+    "cancel": "取消",
+    "confirm": "创建",
+    "creating": "创建中..."
+  },
   "status": {
     "waiting": "等待操作...",
     "listRefreshed": "已刷新容器列表。",
     "noContainers": "当前暂无容器。",
     "emptyName": "容器名称不能为空",
-    "emptyImage": "请选择一个容器镜像",
+    "emptyGame": "请选择一个游戏模板",
     "creating": "正在创建容器...",
     "deleting": "正在删除容器...",
     "stopping": "正在关闭容器: {name}...",
@@ -38,8 +56,11 @@
     "internal": "服务暂时不可用，请稍后重试。",
     "requestFailedWithStatus": "请求失败（状态码：{status}）。",
     "invalidJsonBody": "请求体格式不正确。",
-    "imageIdRequired": "必须选择镜像后才能创建容器。",
-    "imageNotFound": "所选镜像不存在或已下线，请刷新后重试。",
+    "gameIdRequired": "必须选择游戏模板后才能创建容器。",
+    "gameNotFound": "所选游戏模板不存在或已下线，请刷新后重试。",
+    "invalidParams": "提交的参数不合法，请检查后重试。",
+    "templateNotFound": "服务器模板文件缺失，请联系管理员。",
+    "templateInvalid": "服务器模板配置不合法，请联系管理员。",
     "invalidContainerId": "容器 ID 无效。",
     "instanceNameExists": "容器名称已存在，请更换后重试。",
     "instanceRunning": "容器运行中，请先停止后再删除。",
@@ -47,14 +68,24 @@
   },
   "sidebar": {
     "containerList": "容器列表",
-    "imageRegistry": "镜像市场"
+    "imageRegistry": "游戏模板"
   },
   "registry": {
-    "title": "镜像市场",
+    "title": "游戏模板市场",
     "filterAll": "全部",
-    "emptyState": "暂无可用镜像。",
-    "loading": "正在加载镜像列表...",
-    "loadError": "镜像列表加载失败，请稍后重试。"
+    "emptyState": "暂无可用游戏模板。",
+    "loading": "正在加载游戏列表...",
+    "loadError": "游戏列表加载失败，请稍后重试。",
+    "selectHint": "请先从左侧选择一个游戏模板。",
+    "useTemplate": "使用该模板创建",
+    "templateLoading": "正在加载模板详情...",
+    "templateLoadError": "模板详情加载失败，请稍后重试。",
+    "summaryImage": "镜像",
+    "summaryPorts": "默认端口数",
+    "summaryParams": "可配置参数",
+    "noParams": "该模板未定义可配置参数。",
+    "defaultValue": "默认值",
+    "options": "可选项"
   },
   "topbar": {
     "switchLanguage": "切换语言",
diff --git a/frontend/src/router/index.ts b/frontend/src/router/index.ts
index 78059f3..391b2e3 100644
--- a/frontend/src/router/index.ts
+++ b/frontend/src/router/index.ts
@@ -14,6 +14,11 @@ const router = createRouter({
       name: "ImageRegistry",
       component: () => import("../views/ImageRegistry.vue"),
     },
+    {
+      path: "/registry/:gameId/create",
+      name: "CreateInstance",
+      component: () => import("../views/CreateInstance.vue"),
+    },
   ],
 });
 
diff --git a/frontend/src/stores/containers.ts b/frontend/src/stores/containers.ts
index 55979ae..9f928b5 100644
--- a/frontend/src/stores/containers.ts
+++ b/frontend/src/stores/containers.ts
@@ -17,14 +17,38 @@ type OutputI18nPayload = {
 
 const backendMessageKeyMap: Record<string, string> = {
   "name is required": "status.emptyName",
-  "image_id is required": "errors.imageIdRequired",
-  "image not found in registry": "errors.imageNotFound",
+  "game_id is required": "errors.gameIdRequired",
+  "game not found": "errors.gameNotFound",
+  "invalid params": "errors.invalidParams",
   "invalid json body": "errors.invalidJsonBody",
   "invalid container id": "errors.invalidContainerId",
   "instance name already exists": "errors.instanceNameExists",
   "instance is running, stop it before delete": "errors.instanceRunning",
 };
 
+function mapBackendMessageToKey(message: string): string | undefined {
+  const normalized = message.trim().toLowerCase();
+  const exact = backendMessageKeyMap[normalized];
+  if (exact) {
+    return exact;
+  }
+
+  if (normalized.includes("invalid params")) {
+    return "errors.invalidParams";
+  }
+  if (normalized.includes("game not found")) {
+    return "errors.gameNotFound";
+  }
+  if (normalized.includes("template not found")) {
+    return "errors.templateNotFound";
+  }
+  if (normalized.includes("invalid template")) {
+    return "errors.templateInvalid";
+  }
+
+  return undefined;
+}
+
 function isLikelyI18nKey(value: string): boolean {
   return /^[a-z][a-z0-9_-]*(?:\.[a-zA-Z0-9_-]+)+$/.test(value);
 }
@@ -68,7 +92,7 @@ export const useContainerStore = defineStore("containers", () => {
   function mapErrorToI18n(error: unknown): OutputI18nPayload {
     if (error instanceof ApiRequestError) {
       if (error.backendMessage) {
-        const mappedKey = backendMessageKeyMap[error.backendMessage.trim().toLowerCase()];
+        const mappedKey = mapBackendMessageToKey(error.backendMessage);
         if (mappedKey) {
           return { key: mappedKey };
         }
@@ -152,9 +176,13 @@ export const useContainerStore = defineStore("containers", () => {
   }
 
   // 创建实例后立即刷新列表，避免视图层维护后端数据副本。
-  async function create(name: string, imageId: string): Promise<boolean> {
+  async function create(
+    name: string,
+    gameId: string,
+    params: Record<string, string> = {},
+  ): Promise<boolean> {
     try {
-      const data = await apiCreate(name, imageId);
+      const data = await apiCreate(name, gameId, params);
       print(data);
       await fetchInstances();
       return true;
diff --git a/frontend/src/stores/games.ts b/frontend/src/stores/games.ts
new file mode 100644
index 0000000..ca9b37d
--- /dev/null
+++ b/frontend/src/stores/games.ts
@@ -0,0 +1,126 @@
+import { computed, ref } from "vue";
+import { defineStore } from "pinia";
+import type { Game, GameTemplate } from "../api/index";
+import { getGameTemplate, listGames } from "../api/index";
+
+const DEFAULT_CACHE_WINDOW_MS = 60_000;
+
+type FetchGamesOptions = {
+  force?: boolean;
+  cacheWindowMs?: number;
+};
+
+export const useGameStore = defineStore("games", () => {
+  const games = ref<Game[]>([]);
+  const currentTemplate = ref<GameTemplate | null>(null);
+  const currentTemplateGameID = ref<string>("");
+  const loading = ref(false);
+  const templateLoading = ref(false);
+  const error = ref<unknown>(null);
+  const hasFetched = ref(false);
+  const fetchedAt = ref<number>(0);
+  let inflightGamesRequest: Promise<void> | null = null;
+  let inflightTemplateRequest: Promise<void> | null = null;
+
+  const categories = computed<string[]>(() => {
+    const values = new Set<string>();
+    for (const game of games.value) {
+      const category = game.category?.trim();
+      if (category) {
+        values.add(category);
+      }
+    }
+    return Array.from(values);
+  });
+
+  async function fetchGames(options: FetchGamesOptions = {}): Promise<void> {
+    const { force = false, cacheWindowMs = DEFAULT_CACHE_WINDOW_MS } = options;
+    const cacheAge = Date.now() - fetchedAt.value;
+    const canUseCache = hasFetched.value && cacheAge < cacheWindowMs;
+
+    if (!force && canUseCache) {
+      return;
+    }
+
+    if (inflightGamesRequest) {
+      return inflightGamesRequest;
+    }
+
+    loading.value = true;
+    error.value = null;
+
+    inflightGamesRequest = (async () => {
+      try {
+        games.value = await listGames();
+        hasFetched.value = true;
+        fetchedAt.value = Date.now();
+      } catch (err) {
+        error.value = err;
+        throw err;
+      } finally {
+        loading.value = false;
+        inflightGamesRequest = null;
+      }
+    })();
+
+    return inflightGamesRequest;
+  }
+
+  async function fetchTemplate(gameID: string, force = false): Promise<void> {
+    const key = gameID.trim();
+    if (!key) {
+      currentTemplate.value = null;
+      currentTemplateGameID.value = "";
+      return;
+    }
+
+    if (!force && currentTemplate.value && currentTemplateGameID.value === key) {
+      return;
+    }
+
+    if (inflightTemplateRequest && currentTemplateGameID.value === key) {
+      return inflightTemplateRequest;
+    }
+
+    templateLoading.value = true;
+    error.value = null;
+    currentTemplateGameID.value = key;
+
+    inflightTemplateRequest = (async () => {
+      try {
+        currentTemplate.value = await getGameTemplate(key);
+      } catch (err) {
+        currentTemplate.value = null;
+        error.value = err;
+        throw err;
+      } finally {
+        templateLoading.value = false;
+        inflightTemplateRequest = null;
+      }
+    })();
+
+    return inflightTemplateRequest;
+  }
+
+  function getGameById(id: string): Game | undefined {
+    const key = id.trim();
+    if (!key) {
+      return undefined;
+    }
+    return games.value.find((item) => item.id === key);
+  }
+
+  return {
+    games,
+    currentTemplate,
+    currentTemplateGameID,
+    loading,
+    templateLoading,
+    error,
+    hasFetched,
+    categories,
+    fetchGames,
+    fetchTemplate,
+    getGameById,
+  };
+});
diff --git a/frontend/src/stores/registry.ts b/frontend/src/stores/registry.ts
deleted file mode 100644
index 184b00e..0000000
--- a/frontend/src/stores/registry.ts
+++ /dev/null
@@ -1,82 +0,0 @@
-import { computed, ref } from "vue";
-import { defineStore } from "pinia";
-import type { RegistryImage } from "../api/index";
-import { listRegistryImages } from "../api/index";
-
-const DEFAULT_CACHE_WINDOW_MS = 60_000;
-
-type FetchImagesOptions = {
-  force?: boolean;
-  cacheWindowMs?: number;
-};
-
-export const useRegistryStore = defineStore("registry", () => {
-  const images = ref<RegistryImage[]>([]);
-  const loading = ref(false);
-  const error = ref<unknown>(null);
-  const hasFetched = ref(false);
-  const fetchedAt = ref<number>(0);
-  let inflightRequest: Promise<void> | null = null;
-
-  const categories = computed<string[]>(() => {
-    const values = new Set<string>();
-    for (const image of images.value) {
-      const category = image.category?.trim();
-      if (category) {
-        values.add(category);
-      }
-    }
-    return Array.from(values);
-  });
-
-  async function fetchImages(options: FetchImagesOptions = {}): Promise<void> {
-    const { force = false, cacheWindowMs = DEFAULT_CACHE_WINDOW_MS } = options;
-    const cacheAge = Date.now() - fetchedAt.value;
-    const canUseCache = hasFetched.value && cacheAge < cacheWindowMs;
-
-    if (!force && canUseCache) {
-      return;
-    }
-
-    if (inflightRequest) {
-      return inflightRequest;
-    }
-
-    loading.value = true;
-    error.value = null;
-
-    inflightRequest = (async () => {
-      try {
-        images.value = await listRegistryImages();
-        hasFetched.value = true;
-        fetchedAt.value = Date.now();
-      } catch (err) {
-        error.value = err;
-        throw err;
-      } finally {
-        loading.value = false;
-        inflightRequest = null;
-      }
-    })();
-
-    return inflightRequest;
-  }
-
-  function getById(id: string): RegistryImage | undefined {
-    const key = id.trim();
-    if (!key) {
-      return undefined;
-    }
-    return images.value.find((item) => item.id === key);
-  }
-
-  return {
-    images,
-    loading,
-    error,
-    hasFetched,
-    categories,
-    fetchImages,
-    getById,
-  };
-});
diff --git a/frontend/src/views/ContainerList.vue b/frontend/src/views/ContainerList.vue
index adec5e3..3973c9d 100644
--- a/frontend/src/views/ContainerList.vue
+++ b/frontend/src/views/ContainerList.vue
@@ -1,22 +1,15 @@
 <script setup lang="ts">
-import { computed, ref, onMounted, onUnmounted } from "vue";
-import { useRoute, useRouter } from "vue-router";
+import { computed, onMounted, onUnmounted } from "vue";
+import { useRouter } from "vue-router";
 import { useI18n } from "vue-i18n";
 import { useContainerStore } from "../stores/containers";
-import { useRegistryStore } from "../stores/registry";
 import { useInstanceSync } from "../composables/useInstanceSync";
 
 const { t } = useI18n();
-const route = useRoute();
 const router = useRouter();
 const store = useContainerStore();
-const registryStore = useRegistryStore();
 const instanceSync = useInstanceSync();
 
-const showCreateModal = ref(false);
-const newContainerName = ref("");
-const selectedImageId = ref("");
-
 const outputText = computed(() => {
   if (store.outputI18n) {
     return t(store.outputI18n.key, store.outputI18n.values ?? {});
@@ -24,10 +17,6 @@ const outputText = computed(() => {
   return store.output;
 });
 
-const selectedImageDescription = computed(() => {
-  return registryStore.getById(selectedImageId.value)?.description ?? "";
-});
-
 onMounted(() => {
   instanceSync.start();
   void initializeList();
@@ -37,69 +26,12 @@ onUnmounted(() => {
   instanceSync.stop();
 });
 
-function ensureDefaultImageSelection(): void {
-  if (!selectedImageId.value && registryStore.images.length > 0) {
-    selectedImageId.value = registryStore.images[0].id;
-  }
-}
-
-function openCreateModal(): void {
-  showCreateModal.value = true;
-  ensureDefaultImageSelection();
-}
-
-function getImageIdFromQuery(): string {
-  const raw = route.query.imageId;
-  if (Array.isArray(raw)) {
-    return typeof raw[0] === "string" ? raw[0].trim() : "";
-  }
-  return typeof raw === "string" ? raw.trim() : "";
-}
-
-function preselectImageFromQuery(imageId: string): void {
-  const image = registryStore.getById(imageId);
-  if (!image) {
-    store.printErrorKey("errors.imageNotFound");
-    return;
-  }
-
-  selectedImageId.value = image.id;
-  openCreateModal();
-}
-
-async function clearImageIdQuery(): Promise<void> {
-  const nextQuery = { ...route.query };
-  delete nextQuery.imageId;
-  await router.replace({ path: route.path, query: nextQuery });
-}
-
-// 页面启动时统一触发列表拉取，并输出首屏可读状态。
 async function initializeList(): Promise<void> {
   store.print(t("status.waiting"));
-  const imageIdFromQuery = getImageIdFromQuery();
-
-  // 已有缓存时优先弹窗，避免从市场页回跳后再次等待网络。
-  if (imageIdFromQuery && registryStore.getById(imageIdFromQuery)) {
-    preselectImageFromQuery(imageIdFromQuery);
-  }
-
-  try {
-    await registryStore.fetchImages();
-    ensureDefaultImageSelection();
-
-    if (imageIdFromQuery && !showCreateModal.value) {
-      preselectImageFromQuery(imageIdFromQuery);
-    }
-  } catch (err) {
-    store.printError(err);
-  } finally {
-    if (imageIdFromQuery) {
-      await clearImageIdQuery();
-    }
-  }
-
   const success = await store.fetchInstances();
-  if (!success) return;
+  if (!success) {
+    return;
+  }
 
   if (store.instances.length > 0) {
     store.print(t("status.listRefreshed"));
@@ -108,26 +40,8 @@ async function initializeList(): Promise<void> {
   }
 }
 
-// 视图层仅做输入校验和 action 触发，副作用与错误收敛在 store 内完成。
-async function handleCreate(): Promise<void> {
-  const trimmed = newContainerName.value.trim();
-  if (!trimmed) {
-    store.printErrorKey("status.emptyName");
-    return;
-  }
-
-  const imageId = selectedImageId.value.trim();
-  if (!imageId) {
-    store.printErrorKey("status.emptyImage");
-    return;
-  }
-
-  store.print(t("status.creating"));
-  const success = await store.create(trimmed, imageId);
-  if (success) {
-    showCreateModal.value = false;
-    newContainerName.value = "";
-  }
+function goToTemplateMarket(): void {
+  void router.push({ name: "ImageRegistry" });
 }
 
 // 删除属于破坏性操作，执行前必须二次确认。
@@ -168,7 +82,7 @@ async function handleToggle(instance: {
   <main class="main-content">
     <!-- 列表操作栏 -->
     <div class="content-actions">
-      <button class="create-btn" @click="openCreateModal">
+      <button class="create-btn" @click="goToTemplateMarket">
         {{ $t("containers.createBtn") }}
       </button>
     </div>
@@ -200,50 +114,6 @@ async function handleToggle(instance: {
       </div>
     </div>
 
-    <!-- 新建容器的弹窗 (Modal) -->
-    <div v-if="showCreateModal" class="modal">
-      <div class="modal-content">
-        <h3>{{ $t("createModal.title") }}</h3>
-        <input
-          v-model="newContainerName"
-          :placeholder="$t('createModal.placeholder')"
-          @keyup.enter="handleCreate"
-        />
-        <label class="field-label" for="image-select">{{ $t("createModal.imageLabel") }}</label>
-        <select
-          id="image-select"
-          v-model="selectedImageId"
-          :disabled="registryStore.images.length === 0"
-        >
-          <option value="" disabled>{{ $t("createModal.imagePlaceholder") }}</option>
-          <option v-for="image in registryStore.images" :key="image.id" :value="image.id">
-            {{ image.name }}
-          </option>
-        </select>
-        <p v-if="registryStore.loading && registryStore.images.length === 0" class="modal-hint">
-          {{ $t("createModal.loadingImages") }}
-        </p>
-        <p v-else-if="registryStore.images.length === 0" class="modal-hint">
-          {{ $t("createModal.noImages") }}
-        </p>
-        <p v-else-if="selectedImageDescription" class="modal-hint">
-          {{ selectedImageDescription }}
-        </p>
-        <div class="modal-actions">
-          <button class="btn-cancel" @click="showCreateModal = false">
-            {{ $t("createModal.cancel") }}
-          </button>
-          <button
-            class="btn-confirm"
-            :disabled="registryStore.images.length === 0"
-            @click="handleCreate"
-          >
-            {{ $t("createModal.confirm") }}
-          </button>
-        </div>
-      </div>
-    </div>
-
     <!-- 用于显示接口返回的简易日志 -->
     <pre class="output">{{ outputText }}</pre>
   </main>
@@ -439,102 +309,6 @@ input:checked + .slider:before {
   border-radius: 50%;
 }
 
-/* ========== 弹窗样式 ========== */
-.modal {
-  position: fixed;
-  top: 0;
-  left: 0;
-  width: 100vw;
-  height: 100vh;
-  background: var(--modal-overlay);
-  display: flex;
-  justify-content: center;
-  align-items: center;
-  z-index: 1000;
-}
-
-.modal-content {
-  background-color: var(--modal-bg);
-  padding: 20px;
-  border-radius: 8px;
-  width: 360px;
-  border: 1px solid var(--create-brass-primary);
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-  box-shadow: 0 8px 24px var(--shadow-medium);
-}
-
-.modal-content h3 {
-  margin: 0;
-  color: var(--create-brass-primary);
-  font-size: 16px;
-}
-
-.modal-content input,
-.modal-content select {
-  padding: 8px 10px;
-  background: var(--input-bg);
-  border: 1px solid var(--input-border);
-  color: var(--text-on-dark);
-  border-radius: 4px;
-  outline: none;
-}
-
-.modal-content input:focus,
-.modal-content select:focus {
-  border-color: var(--create-brass-primary);
-}
-
-.field-label {
-  font-size: 12px;
-  color: var(--text-muted);
-}
-
-.modal-hint {
-  margin: 0;
-  font-size: 12px;
-  color: var(--text-muted);
-}
-
-.modal-actions {
-  display: flex;
-  justify-content: flex-end;
-  gap: 12px;
-  margin-top: 8px;
-}
-
-.btn-cancel {
-  padding: 6px 12px;
-  font-size: 13px;
-  background: transparent;
-  border: 1px solid var(--btn-secondary-border);
-  color: var(--btn-secondary-text);
-  border-radius: 4px;
-  cursor: pointer;
-}
-.btn-cancel:hover {
-  background: var(--hover-lighten);
-}
-
-.btn-confirm {
-  padding: 6px 12px;
-  font-size: 13px;
-  background: var(--create-brass-dark);
-  color: var(--text-on-dark);
-  border: none;
-  border-radius: 4px;
-  cursor: pointer;
-}
-.btn-confirm:hover {
-  filter: brightness(1.1);
-}
-
-.btn-confirm:disabled {
-  opacity: 0.55;
-  cursor: not-allowed;
-}
-
 /* ========== 底部输出 ========== */
 .output {
   margin-top: auto;
diff --git a/frontend/src/views/CreateInstance.vue b/frontend/src/views/CreateInstance.vue
new file mode 100644
index 0000000..79ed92b
--- /dev/null
+++ b/frontend/src/views/CreateInstance.vue
@@ -0,0 +1,479 @@
+<script setup lang="ts">
+import { computed, onMounted, ref, watch } from "vue";
+import { useRoute, useRouter } from "vue-router";
+import { useI18n } from "vue-i18n";
+import type { GameTemplate, TemplateParam } from "../api/index";
+import { useGameStore } from "../stores/games";
+import { useContainerStore } from "../stores/containers";
+
+const route = useRoute();
+const router = useRouter();
+const { t } = useI18n();
+const gameStore = useGameStore();
+const containerStore = useContainerStore();
+
+const loading = ref(true);
+const creating = ref(false);
+const currentGameID = ref("");
+const containerName = ref("");
+const pageErrorKey = ref("");
+const paramValues = ref<Record<string, string>>({});
+
+const currentGame = computed(() => {
+  return gameStore.getGameById(currentGameID.value) ?? null;
+});
+
+const currentTemplate = computed<GameTemplate | null>(() => {
+  if (!currentGameID.value || gameStore.currentTemplateGameID !== currentGameID.value) {
+    return null;
+  }
+  return gameStore.currentTemplate;
+});
+
+watch(
+  () => route.params.gameId,
+  () => {
+    void initializeForRoute();
+  },
+);
+
+onMounted(() => {
+  void initializeForRoute();
+});
+
+function parseRouteGameID(value: unknown): string {
+  if (Array.isArray(value)) {
+    return typeof value[0] === "string" ? value[0].trim() : "";
+  }
+  return typeof value === "string" ? value.trim() : "";
+}
+
+async function initializeForRoute(): Promise<void> {
+  loading.value = true;
+  pageErrorKey.value = "";
+  containerName.value = "";
+  paramValues.value = {};
+
+  const gameID = parseRouteGameID(route.params.gameId);
+  currentGameID.value = gameID;
+
+  if (!gameID) {
+    pageErrorKey.value = "errors.gameNotFound";
+    loading.value = false;
+    return;
+  }
+
+  try {
+    await gameStore.fetchGames();
+  } catch {
+    pageErrorKey.value = "registry.loadError";
+    loading.value = false;
+    return;
+  }
+
+  if (!gameStore.getGameById(gameID)) {
+    pageErrorKey.value = "errors.gameNotFound";
+    loading.value = false;
+    return;
+  }
+
+  try {
+    await gameStore.fetchTemplate(gameID, true);
+    initParamValuesFromTemplate(currentTemplate.value);
+  } catch {
+    pageErrorKey.value = "registry.templateLoadError";
+  }
+
+  loading.value = false;
+}
+
+function initParamValuesFromTemplate(template: GameTemplate | null): void {
+  const next: Record<string, string> = {};
+  if (template) {
+    for (const param of template.params) {
+      next[param.key] = getDefaultParamValue(param);
+    }
+  }
+  paramValues.value = next;
+}
+
+function getDefaultParamValue(param: TemplateParam): string {
+  if (typeof param.default === "boolean") {
+    return param.default ? "true" : "false";
+  }
+  if (param.default == null) {
+    return "";
+  }
+  return String(param.default);
+}
+
+function isBooleanParamEnabled(key: string): boolean {
+  return paramValues.value[key] === "true";
+}
+
+function onBooleanParamChange(key: string, event: Event): void {
+  const target = event.target as HTMLInputElement;
+  paramValues.value = {
+    ...paramValues.value,
+    [key]: target.checked ? "true" : "false",
+  };
+}
+
+function getCreateParamsPayload(): Record<string, string> {
+  const template = currentTemplate.value;
+  if (!template) {
+    return {};
+  }
+
+  const payload: Record<string, string> = {};
+  for (const param of template.params) {
+    const value = paramValues.value[param.key];
+    if (typeof value === "string") {
+      payload[param.key] = value;
+    }
+  }
+  return payload;
+}
+
+function cancelCreate(): void {
+  void router.push({ name: "ImageRegistry" });
+}
+
+async function handleCreate(): Promise<void> {
+  const name = containerName.value.trim();
+  if (!name) {
+    pageErrorKey.value = "status.emptyName";
+    return;
+  }
+
+  const gameID = currentGameID.value.trim();
+  if (!gameID) {
+    pageErrorKey.value = "errors.gameNotFound";
+    return;
+  }
+
+  pageErrorKey.value = "";
+  creating.value = true;
+  containerStore.print(t("status.creating"));
+
+  const success = await containerStore.create(name, gameID, getCreateParamsPayload());
+  creating.value = false;
+  if (!success) {
+    pageErrorKey.value = containerStore.outputI18n?.key ?? "errors.unknown";
+    return;
+  }
+
+  void router.push({ name: "ContainerList" });
+}
+</script>
+
+<template>
+  <header class="page-header">
+    <h1 class="page-title">{{ $t("createPage.title") }}</h1>
+  </header>
+
+  <main class="main-content">
+    <div v-if="loading" class="state-message">
+      {{ $t("createPage.loading") }}
+    </div>
+
+    <div v-else-if="pageErrorKey" class="state-message state-error">
+      {{ $t(pageErrorKey) }}
+    </div>
+
+    <section v-else-if="currentGame" class="form-panel">
+      <header class="form-header">
+        <h2 class="game-title">{{ currentGame.name }}</h2>
+        <p class="game-description">{{ currentGame.description }}</p>
+      </header>
+
+      <div class="field-block">
+        <label class="field-label" for="instance-name">{{ $t("createPage.nameLabel") }}</label>
+        <input
+          id="instance-name"
+          v-model="containerName"
+          class="text-input"
+          :placeholder="$t('createPage.namePlaceholder')"
+          @keyup.enter="handleCreate"
+        />
+      </div>
+
+      <div v-if="gameStore.templateLoading" class="state-message compact">
+        {{ $t("createPage.loadingTemplate") }}
+      </div>
+
+      <div v-else-if="currentTemplate" class="field-block">
+        <h3 class="section-title">{{ $t("createPage.paramsTitle") }}</h3>
+
+        <div v-if="currentTemplate.params.length === 0" class="state-message compact">
+          {{ $t("createPage.noParams") }}
+        </div>
+
+        <div v-else class="param-list">
+          <article v-for="param in currentTemplate.params" :key="param.key" class="param-item">
+            <label class="field-label" :for="`param-${param.key}`">{{ param.label }}</label>
+            <p v-if="param.description" class="field-hint">{{ param.description }}</p>
+
+            <input
+              v-if="param.type === 'string'"
+              :id="`param-${param.key}`"
+              v-model="paramValues[param.key]"
+              class="text-input"
+              type="text"
+            />
+
+            <input
+              v-else-if="param.type === 'number'"
+              :id="`param-${param.key}`"
+              v-model="paramValues[param.key]"
+              class="text-input"
+              type="number"
+            />
+
+            <label
+              v-else-if="param.type === 'boolean'"
+              class="boolean-field"
+              :for="`param-${param.key}`"
+            >
+              <input
+                :id="`param-${param.key}`"
+                type="checkbox"
+                :checked="isBooleanParamEnabled(param.key)"
+                @change="onBooleanParamChange(param.key, $event)"
+              />
+              <span>
+                {{
+                  isBooleanParamEnabled(param.key)
+                    ? $t("createPage.booleanEnabled")
+                    : $t("createPage.booleanDisabled")
+                }}
+              </span>
+            </label>
+
+            <select
+              v-else-if="param.type === 'select'"
+              :id="`param-${param.key}`"
+              v-model="paramValues[param.key]"
+              class="text-input"
+            >
+              <option
+                v-for="option in param.options || []"
+                :key="option.value"
+                :value="option.value"
+              >
+                {{ option.label }}
+              </option>
+            </select>
+          </article>
+        </div>
+      </div>
+
+      <div class="actions">
+        <button class="btn-cancel" type="button" @click="cancelCreate">
+          {{ $t("createPage.cancel") }}
+        </button>
+        <button class="btn-confirm" type="button" :disabled="creating" @click="handleCreate">
+          {{ creating ? $t("createPage.creating") : $t("createPage.confirm") }}
+        </button>
+      </div>
+    </section>
+  </main>
+</template>
+
+<style scoped>
+.page-header {
+  height: var(--header-height);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+
+.page-title {
+  margin: 0;
+  color: var(--create-brass-primary);
+  font-size: 16px;
+  font-weight: bold;
+  letter-spacing: 2px;
+  font-family: "Segoe UI", "PingFang SC", sans-serif;
+}
+
+.main-content {
+  padding: 8px 24px 24px 24px;
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  max-width: 920px;
+  margin: 0 auto;
+  width: 100%;
+  gap: 14px;
+}
+
+.form-panel {
+  border: 1px solid var(--create-border-outer);
+  background: rgba(0, 0, 0, 0.18);
+  border-radius: 8px;
+  padding: 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.form-header {
+  border-bottom: 1px solid var(--create-border-outer);
+  padding-bottom: 10px;
+}
+
+.game-title {
+  margin: 0;
+  color: var(--create-brass-primary);
+  font-size: 20px;
+}
+
+.game-description {
+  margin: 8px 0 0;
+  color: var(--text-muted);
+  line-height: 1.5;
+  font-size: 13px;
+}
+
+.field-block {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.field-label {
+  font-size: 13px;
+  color: var(--text-on-dark);
+}
+
+.field-hint {
+  margin: 0;
+  font-size: 12px;
+  color: var(--text-muted);
+}
+
+.section-title {
+  margin: 0;
+  font-size: 15px;
+  color: var(--create-brass-primary);
+}
+
+.param-list {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 12px;
+}
+
+.param-item {
+  border: 1px solid var(--create-border-outer);
+  border-radius: 6px;
+  padding: 10px;
+  background: rgba(0, 0, 0, 0.14);
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.text-input {
+  padding: 8px 10px;
+  background: var(--input-bg);
+  border: 1px solid var(--input-border);
+  color: var(--text-on-dark);
+  border-radius: 4px;
+  outline: none;
+  width: 100%;
+}
+
+.text-input:focus {
+  border-color: var(--create-brass-primary);
+}
+
+.boolean-field {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 13px;
+  color: var(--text-on-dark);
+}
+
+.actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 12px;
+  margin-top: 8px;
+}
+
+.btn-cancel {
+  padding: 8px 14px;
+  font-size: 13px;
+  background: transparent;
+  border: 1px solid var(--btn-secondary-border);
+  color: var(--btn-secondary-text);
+  border-radius: 4px;
+  cursor: pointer;
+}
+
+.btn-cancel:hover {
+  background: var(--hover-lighten);
+}
+
+.btn-confirm {
+  padding: 8px 14px;
+  font-size: 13px;
+  background: var(--create-brass-dark);
+  color: var(--text-on-dark);
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+}
+
+.btn-confirm:hover {
+  filter: brightness(1.1);
+}
+
+.btn-confirm:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
+.state-message {
+  text-align: center;
+  color: var(--text-muted);
+  border: 1px dashed var(--border-muted);
+  border-radius: 8px;
+  padding: 40px 16px;
+}
+
+.state-message.compact {
+  padding: 16px;
+}
+
+.state-error {
+  color: var(--danger);
+  border-color: rgba(255, 77, 79, 0.5);
+  background: var(--danger-light);
+}
+
+@media (max-width: 1023px) {
+  .page-title {
+    display: none;
+  }
+}
+
+@media (max-width: 767px) {
+  .main-content {
+    padding: 8px 16px 20px 16px;
+  }
+
+  .actions {
+    flex-direction: column-reverse;
+  }
+
+  .btn-cancel,
+  .btn-confirm {
+    width: 100%;
+  }
+}
+</style>
diff --git a/frontend/src/views/ImageRegistry.vue b/frontend/src/views/ImageRegistry.vue
index 82b846c..b3161e4 100644
--- a/frontend/src/views/ImageRegistry.vue
+++ b/frontend/src/views/ImageRegistry.vue
@@ -2,12 +2,12 @@
 import { computed, onMounted, ref, watch } from "vue";
 import { useRouter } from "vue-router";
 import { useI18n } from "vue-i18n";
-import type { RegistryImage } from "../api/index";
-import { useRegistryStore } from "../stores/registry";
+import type { Game } from "../api/index";
+import { useGameStore } from "../stores/games";
 
 const router = useRouter();
 const { t } = useI18n();
-const registryStore = useRegistryStore();
+const gameStore = useGameStore();
 
 const ALL_CATEGORY = "__all__";
 
@@ -22,15 +22,15 @@ const selectedCategory = ref(ALL_CATEGORY);
 const categoryTabs = computed(() => {
   return [
     { key: ALL_CATEGORY, label: t("registry.filterAll") },
-    ...registryStore.categories.map((category) => ({ key: category, label: category })),
+    ...gameStore.categories.map((category) => ({ key: category, label: category })),
   ];
 });
 
-const filteredImages = computed(() => {
+const filteredGames = computed(() => {
   if (selectedCategory.value === ALL_CATEGORY) {
-    return registryStore.images;
+    return gameStore.games;
   }
-  return registryStore.images.filter((image) => image.category === selectedCategory.value);
+  return gameStore.games.filter((game) => game.category === selectedCategory.value);
 });
 
 watch(categoryTabs, (tabs) => {
@@ -40,30 +40,30 @@ watch(categoryTabs, (tabs) => {
 });
 
 onMounted(() => {
-  void loadImages();
+  void loadGames();
 });
 
-async function loadImages(): Promise<void> {
+async function loadGames(): Promise<void> {
   try {
-    await registryStore.fetchImages();
+    await gameStore.fetchGames();
   } catch {
-    // error state is captured by registry store and rendered by the view.
+    // error state is captured by game store and rendered by the view.
   }
 }
 
-function getImageEmoji(image: RegistryImage): string {
-  const mapped = iconEmojiMap[image.icon];
+function getGameEmoji(game: Game): string {
+  const mapped = iconEmojiMap[game.icon];
   if (mapped) {
     return mapped;
   }
-  const fallback = image.name.trim().charAt(0);
+  const fallback = game.name.trim().charAt(0);
   return fallback ? fallback.toUpperCase() : "?";
 }
 
-function selectImage(imageId: string): void {
+function goToCreatePage(gameID: string): void {
   void router.push({
-    name: "ContainerList",
-    query: { imageId },
+    name: "CreateInstance",
+    params: { gameId: gameID },
   });
 }
 </script>
@@ -89,30 +89,30 @@ function selectImage(imageId: string): void {
       </button>
     </div>
 
-    <div v-if="registryStore.loading && registryStore.images.length === 0" class="state-message">
+    <div v-if="gameStore.loading && gameStore.games.length === 0" class="state-message">
       {{ $t("registry.loading") }}
     </div>
     <div
-      v-else-if="registryStore.error && registryStore.images.length === 0"
+      v-else-if="gameStore.error && gameStore.games.length === 0"
       class="state-message state-error"
     >
       {{ $t("registry.loadError") }}
     </div>
-    <div v-else-if="filteredImages.length === 0" class="state-message">
+    <div v-else-if="filteredGames.length === 0" class="state-message">
       {{ $t("registry.emptyState") }}
     </div>
-    <section v-else class="image-grid">
+    <section v-else class="game-grid">
       <button
-        v-for="image in filteredImages"
-        :key="image.id"
-        class="image-card"
+        v-for="game in filteredGames"
+        :key="game.id"
+        class="game-card"
         type="button"
-        @click="selectImage(image.id)"
+        @click="goToCreatePage(game.id)"
       >
-        <div class="image-icon">{{ getImageEmoji(image) }}</div>
-        <div class="image-name">{{ image.name }}</div>
-        <p class="image-description">{{ image.description }}</p>
-        <span class="category-badge">{{ image.category }}</span>
+        <div class="game-icon">{{ getGameEmoji(game) }}</div>
+        <div class="game-name">{{ game.name }}</div>
+        <p class="game-description">{{ game.description }}</p>
+        <span class="category-badge">{{ game.category }}</span>
       </button>
     </section>
   </main>
@@ -188,13 +188,13 @@ function selectImage(imageId: string): void {
   background: var(--danger-light);
 }
 
-.image-grid {
+.game-grid {
   display: grid;
-  grid-template-columns: repeat(3, minmax(0, 1fr));
+  grid-template-columns: repeat(2, minmax(0, 1fr));
   gap: 16px;
 }
 
-.image-card {
+.game-card {
   text-align: left;
   border: 3px solid var(--card-border);
   background: var(--card-bg);
@@ -227,23 +227,23 @@ function selectImage(imageId: string): void {
     filter 0.2s ease;
 }
 
-.image-card:hover {
+.game-card:hover {
   transform: translateY(-2px);
   filter: brightness(0.97);
 }
 
-.image-icon {
+.game-icon {
   font-size: 32px;
   margin-bottom: 12px;
 }
 
-.image-name {
+.game-name {
   font-size: 17px;
   font-weight: 700;
   margin-bottom: 8px;
 }
 
-.image-description {
+.game-description {
   margin: 0 0 16px;
   color: #3b3b3b;
   font-size: 13px;
@@ -270,7 +270,7 @@ function selectImage(imageId: string): void {
     display: none;
   }
 
-  .image-grid {
+  .game-grid {
     grid-template-columns: repeat(2, minmax(0, 1fr));
   }
 }
@@ -280,7 +280,7 @@ function selectImage(imageId: string): void {
     padding: 8px 16px 20px 16px;
   }
 
-  .image-grid {
+  .game-grid {
     grid-template-columns: 1fr;
   }
 }

From 006067c02363f2394099afb871af95fb5c5778bb Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Thu, 2 Apr 2026 23:29:29 +0800
Subject: [PATCH 26/28] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0Volume=E7=9B=AE?=
 =?UTF-8?q?=E5=BD=95=E6=8C=82=E8=BD=BD=E4=B8=8E=E7=AB=AF=E5=8F=A3=E6=98=A0?=
 =?UTF-8?q?=E5=B0=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Readme.md                                     |   4 +-
 backend/internal/service/docker_service.go    | 117 ++++++++-
 .../internal/service/docker_service_test.go   | 147 +++++++++++
 docs/api/contracts.md                         |   8 +-
 docs/design-docs/instance_lifecycle.md        |   7 +
 .../20260402-container-ports-volumes.md       | 229 ++++++++++++++++++
 6 files changed, 504 insertions(+), 8 deletions(-)
 create mode 100644 backend/internal/service/docker_service_test.go
 create mode 100644 docs/exec-plans/active/20260402-container-ports-volumes.md

diff --git a/Readme.md b/Readme.md
index acb124d..c4187c5 100644
--- a/Readme.md
+++ b/Readme.md
@@ -22,8 +22,8 @@ task dev               # 一键启动前后端开发服务
 - [x] 容器基础生命周期：创建、删除、开启、停止
 - [x] 容器运行状态实时同步
 - [x] 创建容器时支持镜像选择
-- [ ] 创建容器时支持环境变量注入
-- [ ] 创建容器时支持 Volume 持久化目录挂载
+- [x] 创建容器时支持环境变量注入
+- [x] 创建容器时支持 Volume 持久化目录挂载
 - [ ] 创建容器时支持动态端口映射与防冲突检测
 - [ ] 实例重启与强制终止
 - [ ] 实例详情页（镜像信息、端口、环境变量、运行时长等）
diff --git a/backend/internal/service/docker_service.go b/backend/internal/service/docker_service.go
index 89e8c39..e0030b2 100644
--- a/backend/internal/service/docker_service.go
+++ b/backend/internal/service/docker_service.go
@@ -11,6 +11,7 @@ import (
 	"github.com/docker/docker/api/types/filters"
 	"github.com/docker/docker/api/types/image"
 	"github.com/docker/docker/client"
+	"github.com/docker/go-connections/nat"
 
 	"minedock/backend/internal/model"
 )
@@ -78,16 +79,27 @@ func (s *DockerService) CreateInstance(ctx context.Context, name, gameID string,
 		return "", err
 	}
 
+	exposedPorts, portBindings := buildPortBindings(tpl.Container.Ports)
+	cmd := []string(nil)
+	if len(tpl.Container.Command) > 0 {
+		cmd = append(cmd, tpl.Container.Command...)
+	}
+	hostConfig := &container.HostConfig{
+		PortBindings: portBindings,
+		Binds:        buildVolumeBinds(name, tpl.Container.Volumes),
+	}
+
 	resp, err := s.cli.ContainerCreate(ctx, &container.Config{
-		Image: imageRef,
-		Cmd:   []string{"sleep", "3600"},
-		Env:   mapToDockerEnv(env),
+		Image:        imageRef,
+		Cmd:          cmd,
+		Env:          mapToDockerEnv(env),
+		ExposedPorts: exposedPorts,
 		Labels: map[string]string{
 			managedLabelKey: managedLabelValue,
 			nameLabelKey:    name,
 			gameIDLabelKey:  game.ID,
 		},
-	}, nil, nil, nil, "")
+	}, hostConfig, nil, nil, "")
 	if err != nil {
 		return "", fmt.Errorf("create container: %w", err)
 	}
@@ -224,6 +236,103 @@ func mapToDockerEnv(m map[string]string) []string {
 	return env
 }
 
+func buildPortBindings(ports []model.PortMapping) (nat.PortSet, nat.PortMap) {
+	if len(ports) == 0 {
+		return nil, nil
+	}
+
+	exposedPorts := make(nat.PortSet, len(ports))
+	portBindings := make(nat.PortMap, len(ports))
+
+	for _, p := range ports {
+		protocol := strings.ToLower(strings.TrimSpace(p.Protocol))
+		if protocol == "" {
+			protocol = "tcp"
+		}
+
+		containerPort, err := nat.NewPort(protocol, strconv.Itoa(p.Container))
+		if err != nil {
+			continue
+		}
+
+		exposedPorts[containerPort] = struct{}{}
+		portBindings[containerPort] = append(portBindings[containerPort], nat.PortBinding{
+			HostPort: strconv.Itoa(p.Host),
+		})
+	}
+
+	if len(exposedPorts) == 0 {
+		return nil, nil
+	}
+
+	return exposedPorts, portBindings
+}
+
+func buildVolumeBinds(instanceName string, volumes []model.VolumeMount) []string {
+	if len(volumes) == 0 {
+		return nil
+	}
+
+	instanceToken := sanitizeVolumeNameToken(instanceName)
+	binds := make([]string, 0, len(volumes))
+	for _, v := range volumes {
+		volumeToken := sanitizeVolumeNameToken(v.Name)
+		dockerVolName := fmt.Sprintf("minedock-%s-%s", instanceToken, volumeToken)
+		bind := fmt.Sprintf("%s:%s", dockerVolName, strings.TrimSpace(v.ContainerPath))
+		if v.ReadOnly {
+			bind += ":ro"
+		}
+		binds = append(binds, bind)
+	}
+
+	return binds
+}
+
+func sanitizeVolumeNameToken(raw string) string {
+	s := strings.ToLower(strings.TrimSpace(raw))
+	if s == "" {
+		return "default"
+	}
+
+	var b strings.Builder
+	b.Grow(len(s))
+	lastSeparator := false
+
+	for _, r := range s {
+		isAlnum := (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9')
+		if isAlnum {
+			b.WriteRune(r)
+			lastSeparator = false
+			continue
+		}
+
+		if r == '-' || r == '_' || r == '.' {
+			if !lastSeparator {
+				b.WriteRune(r)
+				lastSeparator = true
+			}
+			continue
+		}
+
+		if !lastSeparator {
+			b.WriteByte('-')
+			lastSeparator = true
+		}
+	}
+
+	token := strings.Trim(b.String(), "-_.")
+	if token == "" {
+		return "default"
+	}
+
+	first := token[0]
+	if !((first >= 'a' && first <= 'z') || (first >= '0' && first <= '9')) {
+		token = "v-" + token
+	}
+
+	return token
+}
+
 // StartInstance 启动托管容器并更新持久化状态。
 func (s *DockerService) StartInstance(ctx context.Context, containerID string) error {
 	if err := s.cli.ContainerStart(ctx, containerID, container.StartOptions{}); err != nil {
diff --git a/backend/internal/service/docker_service_test.go b/backend/internal/service/docker_service_test.go
new file mode 100644
index 0000000..81dd97d
--- /dev/null
+++ b/backend/internal/service/docker_service_test.go
@@ -0,0 +1,147 @@
+package service
+
+import (
+	"testing"
+
+	"github.com/docker/go-connections/nat"
+
+	"minedock/backend/internal/model"
+)
+
+func TestBuildPortBindings(t *testing.T) {
+	t.Run("empty ports", func(t *testing.T) {
+		exposed, bindings := buildPortBindings(nil)
+		if len(exposed) != 0 {
+			t.Fatalf("expected empty exposed ports, got %d", len(exposed))
+		}
+		if len(bindings) != 0 {
+			t.Fatalf("expected empty port bindings, got %d", len(bindings))
+		}
+	})
+
+	t.Run("tcp mapping", func(t *testing.T) {
+		exposed, bindings := buildPortBindings([]model.PortMapping{{
+			Host:      25565,
+			Container: 25565,
+			Protocol:  "tcp",
+		}})
+
+		port, err := nat.NewPort("tcp", "25565")
+		if err != nil {
+			t.Fatalf("new port: %v", err)
+		}
+
+		if _, ok := exposed[port]; !ok {
+			t.Fatalf("expected exposed port %q", port)
+		}
+		bound, ok := bindings[port]
+		if !ok {
+			t.Fatalf("expected binding for port %q", port)
+		}
+		if len(bound) != 1 {
+			t.Fatalf("expected 1 binding, got %d", len(bound))
+		}
+		if bound[0].HostPort != "25565" {
+			t.Fatalf("expected host port 25565, got %s", bound[0].HostPort)
+		}
+	})
+
+	t.Run("udp mapping", func(t *testing.T) {
+		exposed, bindings := buildPortBindings([]model.PortMapping{{
+			Host:      19132,
+			Container: 19132,
+			Protocol:  "udp",
+		}})
+
+		port, err := nat.NewPort("udp", "19132")
+		if err != nil {
+			t.Fatalf("new port: %v", err)
+		}
+
+		if _, ok := exposed[port]; !ok {
+			t.Fatalf("expected exposed port %q", port)
+		}
+		bound, ok := bindings[port]
+		if !ok {
+			t.Fatalf("expected binding for port %q", port)
+		}
+		if len(bound) != 1 {
+			t.Fatalf("expected 1 binding, got %d", len(bound))
+		}
+		if bound[0].HostPort != "19132" {
+			t.Fatalf("expected host port 19132, got %s", bound[0].HostPort)
+		}
+	})
+
+	t.Run("default protocol is tcp", func(t *testing.T) {
+		exposed, bindings := buildPortBindings([]model.PortMapping{{
+			Host:      8080,
+			Container: 8080,
+			Protocol:  "   ",
+		}})
+
+		port, err := nat.NewPort("tcp", "8080")
+		if err != nil {
+			t.Fatalf("new port: %v", err)
+		}
+
+		if _, ok := exposed[port]; !ok {
+			t.Fatalf("expected exposed port %q", port)
+		}
+		if _, ok := bindings[port]; !ok {
+			t.Fatalf("expected binding for port %q", port)
+		}
+	})
+}
+
+func TestBuildVolumeBinds(t *testing.T) {
+	t.Run("empty volumes", func(t *testing.T) {
+		binds := buildVolumeBinds("my-server", nil)
+		if binds != nil {
+			t.Fatalf("expected nil binds, got %v", binds)
+		}
+	})
+
+	t.Run("normal volume", func(t *testing.T) {
+		binds := buildVolumeBinds("my-server", []model.VolumeMount{{
+			Name:          "server-data",
+			ContainerPath: "/data",
+		}})
+
+		if len(binds) != 1 {
+			t.Fatalf("expected 1 bind, got %d", len(binds))
+		}
+		if binds[0] != "minedock-my-server-server-data:/data" {
+			t.Fatalf("unexpected bind: %s", binds[0])
+		}
+	})
+
+	t.Run("readonly volume", func(t *testing.T) {
+		binds := buildVolumeBinds("my-server", []model.VolumeMount{{
+			Name:          "server-data",
+			ContainerPath: "/data",
+			ReadOnly:      true,
+		}})
+
+		if len(binds) != 1 {
+			t.Fatalf("expected 1 bind, got %d", len(binds))
+		}
+		if binds[0] != "minedock-my-server-server-data:/data:ro" {
+			t.Fatalf("unexpected bind: %s", binds[0])
+		}
+	})
+
+	t.Run("instance name with special chars", func(t *testing.T) {
+		binds := buildVolumeBinds("My Server (US)#1", []model.VolumeMount{{
+			Name:          "World Data@Prod",
+			ContainerPath: "/data",
+		}})
+
+		if len(binds) != 1 {
+			t.Fatalf("expected 1 bind, got %d", len(binds))
+		}
+		if binds[0] != "minedock-my-server-us-1-world-data-prod:/data" {
+			t.Fatalf("unexpected bind: %s", binds[0])
+		}
+	})
+}
diff --git a/docs/api/contracts.md b/docs/api/contracts.md
index 5106a32..b2e695b 100644
--- a/docs/api/contracts.md
+++ b/docs/api/contracts.md
@@ -93,10 +93,14 @@
 
 ### POST /api/instances
 
-- 说明：创建一个新容器（初始为 Stopped）
+- 说明：创建一个新容器（初始为 Stopped），并应用模板中的端口映射与卷挂载配置
 - 状态码：
   - 成功：`200`
-  - 失败：`400`（JSON非法/空名称/缺失 game_id/game_id 不合法/params 非法）、`409`（名称冲突）、`500`（模板不存在或模板非法）
+  - 失败：`400`（JSON非法/空名称/缺失 game_id/game_id 不合法/params 非法）、`409`（名称冲突）、`500`（模板不存在或模板非法/容器创建失败）
+- 行为说明：
+  - 端口映射来源：模板 `container.ports`
+  - 卷挂载来源：模板 `container.volumes`，卷名规则为 `minedock-{instanceName}-{volumeName}`
+  - 若宿主机端口冲突，返回 Docker 原生错误并映射为 `500`
 - 请求参数：
 
 ```json
diff --git a/docs/design-docs/instance_lifecycle.md b/docs/design-docs/instance_lifecycle.md
index 74ac716..4168ea6 100644
--- a/docs/design-docs/instance_lifecycle.md
+++ b/docs/design-docs/instance_lifecycle.md
@@ -39,6 +39,12 @@ stateDiagram-v2
     Stopped --> [*]: Delete
 ```
 
+## 创建配置注入
+
+- 端口映射来源：模板 `container.ports`，创建容器时写入 Docker `ExposedPorts` 与 `PortBindings`。
+- 卷挂载来源：模板 `container.volumes`，卷名规则为 `minedock-{instanceName}-{volumeName}`。
+- 启动命令来源：若模板配置了 `container.command` 则覆盖镜像命令；否则使用镜像默认 `ENTRYPOINT/CMD`。
+
 ## 一致性策略
 
 - 事实来源：Docker Daemon。
@@ -51,3 +57,4 @@ stateDiagram-v2
 - 创建流程：若数据库保存失败，立即强制删除刚创建容器。
 - 启停流程：Docker 操作成功但 DB 更新失败时，接口返回错误；后续列表刷新会将状态重新收敛。
 - 删除流程：Docker 删除成功后若 DB 删除失败，后续列表会因 Docker 不存在而清理状态。
+- 数据卷策略：删除实例不会自动清理 Docker 卷，卷数据默认保留，需手动回收或后续能力支持。
diff --git a/docs/exec-plans/active/20260402-container-ports-volumes.md b/docs/exec-plans/active/20260402-container-ports-volumes.md
new file mode 100644
index 0000000..799a72a
--- /dev/null
+++ b/docs/exec-plans/active/20260402-container-ports-volumes.md
@@ -0,0 +1,229 @@
+# 创建容器时支持端口映射与卷挂载
+
+## 背景
+
+当前 MineDock 的 `CreateInstance` 虽然已经从 YAML 模板中加载了 `ports` 和 `volumes` 配置数据（数据结构 `PortMapping` / `VolumeMount` 已就绪），但在实际调用 Docker SDK `ContainerCreate` 时仅传入了 `Image`、`Env`、`Labels`（参见 `docker_service.go:81-90`），**端口映射和卷挂载均未生效**。
+
+这意味着：
+
+- 创建的容器没有暴露端口，宿主机无法访问游戏服务器
+- 容器数据保存在匿名层，删除容器后世界存档等数据丢失
+- 同时 `Cmd` 字段硬编码为 `["sleep", "3600"]`（开发阶段占位），真正的游戏服务器镜像有自己的 `ENTRYPOINT`，不需要覆盖 `Cmd`
+
+本计划将模板中已定义的 `ports` 和 `volumes` 配置实际传入 Docker SDK，使创建的容器真正具备网络可达和数据持久化能力。
+
+## 需要评审的内容
+
+> [!IMPORTANT]
+> **卷命名策略**
+>
+> 模板 YAML 中 `volumes[].name` 定义的是语义标识（如 `server-data`），需要转换为 Docker 卷名。
+> 采用的命名规则为：`minedock-{instanceName}-{volumeName}`。
+>
+> 例如：实例名 `my-server`，模板卷名 `server-data` → Docker 卷名 `minedock-my-server-server-data`。
+>
+> 这确保每个实例拥有独立卷，卷名可读且可追溯到实例。
+
+> [!IMPORTANT]
+> **移除硬编码 Cmd**
+>
+> 当前 `ContainerCreate` 传入 `Cmd: []string{"sleep", "3600"}`，这会覆盖镜像自身的 `ENTRYPOINT` / `CMD`，导致游戏服务器无法正常启动。本计划将移除该硬编码，让容器使用镜像默认的启动命令。
+>
+> 如果模板中定义了 `container.command`，则使用模板的命令覆盖；否则不传 `Cmd`。
+
+> [!WARNING]
+> **端口冲突**
+>
+> 当宿主机端口已被占用时，Docker 会返回创建/启动错误。当前版本不做端口冲突的预检查，依赖 Docker 的原生错误返回。后续可考虑增加端口可用性预检和用户自定义端口覆盖。
+
+## 拟定更改
+
+### 后端 Service 层
+
+#### [MODIFY] docker_service.go (`backend/internal/service/docker_service.go`)
+
+这是本次变更的核心文件。需要修改 `CreateInstance` 方法，将模板中的 `ports` 和 `volumes` 转换为 Docker SDK 的数据结构并传入 `ContainerCreate`。
+
+##### 1. 端口映射
+
+将模板 `[]PortMapping` 转换为 Docker SDK 所需的两个结构：
+
+- `container.Config.ExposedPorts`（`nat.PortSet`）— 声明容器暴露的端口
+- `container.HostConfig.PortBindings`（`nat.PortMap`）— 映射宿主机端口
+
+```go
+// buildPortBindings 将模板端口映射转换为 Docker 端口配置。
+func buildPortBindings(ports []model.PortMapping) (nat.PortSet, nat.PortMap) {
+    exposedPorts := nat.PortSet{}
+    portBindings := nat.PortMap{}
+
+    for _, p := range ports {
+        protocol := strings.ToLower(strings.TrimSpace(p.Protocol))
+        if protocol == "" {
+            protocol = "tcp"
+        }
+        containerPort, _ := nat.NewPort(protocol, strconv.Itoa(p.Container))
+        exposedPorts[containerPort] = struct{}{}
+        portBindings[containerPort] = []nat.PortBinding{
+            {HostPort: strconv.Itoa(p.Host)},
+        }
+    }
+
+    return exposedPorts, portBindings
+}
+```
+
+##### 2. 卷挂载
+
+将模板 `[]VolumeMount` 转换为 Docker SDK 所需的结构：
+
+- `container.HostConfig.Binds`（`[]string`）— 格式为 `volumeName:containerPath[:ro]`
+
+卷名使用 `minedock-{instanceName}-{volumeName}` 格式，确保每个实例的卷相互隔离。
+
+```go
+// buildVolumeBinds 将模板卷配置转换为 Docker Binds 列表。
+// 卷名格式：minedock-{instanceName}-{volumeName}
+func buildVolumeBinds(instanceName string, volumes []model.VolumeMount) []string {
+    if len(volumes) == 0 {
+        return nil
+    }
+
+    binds := make([]string, 0, len(volumes))
+    for _, v := range volumes {
+        dockerVolName := fmt.Sprintf("minedock-%s-%s", instanceName, v.Name)
+        bind := fmt.Sprintf("%s:%s", dockerVolName, v.ContainerPath)
+        if v.ReadOnly {
+            bind += ":ro"
+        }
+        binds = append(binds, bind)
+    }
+    return binds
+}
+```
+
+##### 3. 修改 `CreateInstance` 方法
+
+```go
+// 变更前
+resp, err := s.cli.ContainerCreate(ctx, &container.Config{
+    Image: imageRef,
+    Cmd:   []string{"sleep", "3600"},
+    Env:   mapToDockerEnv(env),
+    Labels: map[string]string{...},
+}, nil, nil, nil, "")
+
+// 变更后
+exposedPorts, portBindings := buildPortBindings(tpl.Container.Ports)
+
+var cmd []string
+if len(tpl.Container.Command) > 0 {
+    cmd = tpl.Container.Command
+}
+
+resp, err := s.cli.ContainerCreate(ctx, &container.Config{
+    Image:        imageRef,
+    Cmd:          cmd,
+    Env:          mapToDockerEnv(env),
+    ExposedPorts: exposedPorts,
+    Labels: map[string]string{...},
+}, &container.HostConfig{
+    PortBindings: portBindings,
+    Binds:        buildVolumeBinds(name, tpl.Container.Volumes),
+}, nil, nil, "")
+```
+
+##### 4. 新增 import
+
+```go
+import (
+    "github.com/docker/go-connections/nat"
+)
+```
+
+> [!NOTE]
+> `github.com/docker/go-connections/nat` 是 Docker SDK 的已有传递依赖，无需额外 `go get`。可通过 `go list -m all | grep go-connections` 确认。
+
+---
+
+### 后端 Service 层测试
+
+#### [MODIFY] docker_service_test.go（如存在）或新增端口/卷相关测试
+
+新增以下单元测试覆盖新增的辅助函数：
+
+- `TestBuildPortBindings`：
+  - 空端口列表 → 返回空 PortSet/PortMap
+  - TCP 端口映射 → 验证 ExposedPorts 键和 PortBindings 映射正确
+  - UDP 端口映射 → 验证 protocol 正确拼接
+  - 协议为空时默认 tcp
+- `TestBuildVolumeBinds`：
+  - 空卷列表 → 返回 nil
+  - 正常卷 → 验证格式 `minedock-{name}-{volName}:/path`
+  - 只读卷 → 验证 `:ro` 后缀
+  - 实例名含特殊字符时的卷名安全性
+
+---
+
+### 文档
+
+#### [MODIFY] contracts.md (`docs/api/contracts.md`)
+
+无 API 签名变更。但 `POST /api/instances` 的行为语义增强：创建的容器现在会应用模板中定义的端口映射和卷挂载。可在说明中补充端口冲突时的 `500` 错误行为。
+
+#### [MODIFY] instance_lifecycle.md (`docs/design-docs/instance_lifecycle.md`)
+
+在创建流程部分补充：
+
+- 端口映射来源：模板 `container.ports`
+- 卷命名规则：`minedock-{instanceName}-{volumeName}`
+- 删除实例时 Docker 卷**不会自动清理**（需用户手动或后续计划实现卷清理功能）
+
+---
+
+## 执行步骤
+
+- [ ] 确认依赖
+  - [ ] 运行 `go list -m all | grep go-connections` 确认 `nat` 包已在依赖树中
+- [ ] 后端 Service 层
+  - [ ] 新增 `buildPortBindings` 辅助函数，将 `[]PortMapping` → `nat.PortSet` + `nat.PortMap`
+  - [ ] 新增 `buildVolumeBinds` 辅助函数，将 `[]VolumeMount` → `[]string`（Docker Binds 格式）
+  - [ ] 修改 `CreateInstance`：
+    - [ ] 移除 `Cmd: []string{"sleep", "3600"}` 硬编码
+    - [ ] 传入 `ExposedPorts` 到 `container.Config`
+    - [ ] 构建 `container.HostConfig`，传入 `PortBindings` 和 `Binds`
+    - [ ] 支持模板 `container.command` 覆盖（有值时传入 `Cmd`）
+  - [ ] 添加 `nat` 包的 import
+- [ ] 后端测试
+  - [ ] 编写 `TestBuildPortBindings`（空/TCP/UDP/默认协议）
+  - [ ] 编写 `TestBuildVolumeBinds`（空/正常/只读）
+  - [ ] 运行 `task backend:test` 确认全部通过
+  - [ ] 运行 `task backend:vet && task backend:lint`
+- [ ] 文档更新
+  - [ ] 更新 `docs/design-docs/instance_lifecycle.md`：补充端口映射和卷挂载说明
+  - [ ] 更新 `docs/api/contracts.md`：补充端口冲突错误说明（可选）
+
+## 已确认的决策
+
+- ✅ **删除实例时不清理卷**：本期 `DeleteInstance` 不处理关联 Docker Volume 的清理，卷数据在删除实例后保留。用户可通过 `docker volume rm` 手动回收。后续计划提供"删除实例及数据"选项。
+- ✅ **端口冲突直接透传 Docker 错误**：当宿主机端口被占用时，Docker 返回的错误直接传递给前端。端口可用性预检查和用户自定义端口覆盖留作后续增强。
+
+## 验证计划
+
+### 自动化测试
+
+- `task backend:test` — 覆盖：
+  - `buildPortBindings`：空列表、TCP 映射、UDP 映射、默认协议
+  - `buildVolumeBinds`：空列表、正常挂载、只读挂载
+  - 现有 `CreateInstance` 相关测试（确保不被破坏）
+- `task backend:vet && task backend:lint`
+
+### 手动验证
+
+- 启动后端，创建一个 Minecraft Java 实例
+- 验证容器端口映射：`docker inspect <container_id>` 查看 `PortBindings` 包含 `25565/tcp -> 25565`
+- 验证卷挂载：`docker inspect <container_id>` 查看 `Binds` 包含 `minedock-<name>-server-data:/data`
+- 验证 `docker volume ls` 中出现 `minedock-<name>-server-data` 卷
+- 启动容器后，验证 `docker port <container_id>` 输出正确端口映射
+- 停止并删除实例后，验证 Docker 卷仍然存在（本期不清理卷）
+- 创建另一个实例使用相同端口，验证 Docker 返回端口冲突错误并正确传递给前端

From f7d2264eb6699d2d08af1e237bf879ab60d5c67b Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Fri, 3 Apr 2026 17:20:46 +0800
Subject: [PATCH 27/28] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E7=BD=91?=
 =?UTF-8?q?=E9=A1=B5=E6=8E=A7=E5=88=B6=E5=8F=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 backend/internal/api/console_handler.go       | 137 ++++++
 backend/internal/api/handlers_test.go         |   8 +-
 backend/internal/api/router.go                |   5 +-
 backend/internal/service/console_service.go   |  55 +++
 .../internal/service/console_service_test.go  | 101 ++++
 backend/internal/service/docker_service.go    |   6 +
 backend/main.go                               |   4 +-
 docs/api/contracts.md                         |  15 +
 docs/design-docs/instance_lifecycle.md        |   8 +
 .../active/20260402-container-console.md      | 444 ++++++++++++++++++
 docs/standards/frontend.md                    |   1 +
 frontend/package-lock.json                    |  27 ++
 frontend/package.json                         |   3 +
 frontend/src/api/index.ts                     |   5 +
 frontend/src/components/Sidebar.vue           |  10 +-
 frontend/src/composables/useConsole.ts        | 184 ++++++++
 frontend/src/locales/en-US.json               |  11 +
 frontend/src/locales/zh-CN.json               |  11 +
 frontend/src/router/index.ts                  |   5 +
 frontend/src/views/ContainerList.vue          |  28 +-
 frontend/src/views/InstanceDetail.vue         | 255 ++++++++++
 21 files changed, 1307 insertions(+), 16 deletions(-)
 create mode 100644 backend/internal/api/console_handler.go
 create mode 100644 backend/internal/service/console_service.go
 create mode 100644 backend/internal/service/console_service_test.go
 create mode 100644 docs/exec-plans/active/20260402-container-console.md
 create mode 100644 frontend/src/composables/useConsole.ts
 create mode 100644 frontend/src/views/InstanceDetail.vue

diff --git a/backend/internal/api/console_handler.go b/backend/internal/api/console_handler.go
new file mode 100644
index 0000000..b643650
--- /dev/null
+++ b/backend/internal/api/console_handler.go
@@ -0,0 +1,137 @@
+package api
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+
+	"github.com/coder/websocket"
+	"github.com/docker/docker/api/types"
+)
+
+const consoleWriteTimeout = 3 * time.Second
+
+// ContainerConsole 定义控制台处理器依赖的 Attach 能力。
+type ContainerConsole interface {
+	Attach(ctx context.Context, containerID string) (types.HijackedResponse, error)
+}
+
+// ConsoleHandler 暴露容器控制台 WebSocket 处理器。
+type ConsoleHandler struct {
+	console ContainerConsole
+}
+
+// NewConsoleHandler 创建 ConsoleHandler。
+func NewConsoleHandler(console ContainerConsole) *ConsoleHandler {
+	return &ConsoleHandler{console: console}
+}
+
+// HandleConsole 处理 GET /api/ws/console/{id}。
+func (h *ConsoleHandler) HandleConsole(w http.ResponseWriter, r *http.Request) {
+	if h == nil || h.console == nil {
+		writeJSON(w, http.StatusServiceUnavailable, statusResponse{Status: "error", Error: "console service unavailable"})
+		return
+	}
+
+	id, ok := pathContainerID(r)
+	if !ok {
+		writeJSON(w, http.StatusBadRequest, statusResponse{Status: "error", Error: "invalid container id"})
+		return
+	}
+
+	conn, err := websocket.Accept(w, r, &websocket.AcceptOptions{})
+	if err != nil {
+		return
+	}
+
+	hijacked, err := h.console.Attach(r.Context(), id)
+	if err != nil {
+		_ = conn.Close(websocket.StatusPolicyViolation, err.Error())
+		return
+	}
+
+	ctx, cancel := context.WithCancel(r.Context())
+	defer cancel()
+	defer hijacked.Close()
+
+	errCh := make(chan error, 2)
+
+	go func() {
+		errCh <- pipeDockerToWebSocket(ctx, conn, hijacked)
+	}()
+
+	go func() {
+		errCh <- pipeWebSocketToDocker(ctx, conn, hijacked)
+	}()
+
+	if err := <-errCh; err != nil {
+		if code := websocket.CloseStatus(err); code == websocket.StatusNormalClosure || code == websocket.StatusGoingAway {
+			_ = conn.Close(websocket.StatusNormalClosure, "closed")
+			return
+		}
+		_ = conn.Close(websocket.StatusInternalError, "console bridge failed")
+		return
+	}
+
+	_ = conn.Close(websocket.StatusNormalClosure, "closed")
+}
+
+func pipeDockerToWebSocket(
+	ctx context.Context,
+	conn *websocket.Conn,
+	hijacked types.HijackedResponse,
+) error {
+	writer := &wsBinaryWriter{ctx: ctx, conn: conn}
+	_, err := io.Copy(writer, hijacked.Reader)
+	if errors.Is(err, io.EOF) {
+		return nil
+	}
+	return err
+}
+
+func pipeWebSocketToDocker(ctx context.Context, conn *websocket.Conn, hijacked types.HijackedResponse) error {
+	for {
+		typ, data, err := conn.Read(ctx)
+		if err != nil {
+			return err
+		}
+
+		if typ != websocket.MessageText && typ != websocket.MessageBinary {
+			continue
+		}
+
+		if len(data) == 0 {
+			continue
+		}
+
+		if _, err := hijacked.Conn.Write(data); err != nil {
+			return fmt.Errorf("write stdin: %w", err)
+		}
+	}
+}
+
+type wsBinaryWriter struct {
+	ctx  context.Context
+	conn *websocket.Conn
+}
+
+func (w *wsBinaryWriter) Write(p []byte) (int, error) {
+	if len(p) == 0 {
+		return 0, nil
+	}
+
+	buf := make([]byte, len(p))
+	copy(buf, p)
+
+	writeCtx, cancel := context.WithTimeout(w.ctx, consoleWriteTimeout)
+	defer cancel()
+
+	if err := w.conn.Write(writeCtx, websocket.MessageBinary, buf); err != nil {
+		return 0, err
+	}
+
+	return len(p), nil
+}
diff --git a/backend/internal/api/handlers_test.go b/backend/internal/api/handlers_test.go
index 2a8977f..55ef8e8 100644
--- a/backend/internal/api/handlers_test.go
+++ b/backend/internal/api/handlers_test.go
@@ -66,7 +66,7 @@ func newTestRouter(m *mockService) http.Handler {
 			return model.GameTemplate{}, model.ErrGameNotFound
 		},
 	})
-	return NewRouter(h, gh, nil)
+	return NewRouter(h, gh, nil, nil)
 }
 
 // --- GET /api/instances 场景 ---
@@ -123,7 +123,7 @@ func TestGetGames_Success(t *testing.T) {
 			return model.GameTemplate{}, model.ErrGameNotFound
 		},
 	})
-	router := NewRouter(h, gh, nil)
+	router := NewRouter(h, gh, nil, nil)
 
 	w := httptest.NewRecorder()
 	r := httptest.NewRequest(http.MethodGet, "/api/games", nil)
@@ -155,7 +155,7 @@ func TestGetGameTemplate_Success(t *testing.T) {
 			return model.GameTemplate{Image: model.TemplateImage{Name: "itzg/minecraft-server", Tag: "latest"}}, nil
 		},
 	})
-	router := NewRouter(h, gh, nil)
+	router := NewRouter(h, gh, nil, nil)
 
 	w := httptest.NewRecorder()
 	r := httptest.NewRequest(http.MethodGet, "/api/games/minecraft-java/template", nil)
@@ -184,7 +184,7 @@ func TestGetGameTemplate_NotFound(t *testing.T) {
 			return model.GameTemplate{}, model.ErrGameNotFound
 		},
 	})
-	router := NewRouter(h, gh, nil)
+	router := NewRouter(h, gh, nil, nil)
 
 	w := httptest.NewRecorder()
 	r := httptest.NewRequest(http.MethodGet, "/api/games/not-exists/template", nil)
diff --git a/backend/internal/api/router.go b/backend/internal/api/router.go
index 8f50343..4c45b3b 100644
--- a/backend/internal/api/router.go
+++ b/backend/internal/api/router.go
@@ -6,7 +6,7 @@ import (
 )
 
 // NewRouter 注册 API 路由并包装中间件。
-func NewRouter(h *Handler, games *GameHandler, ws *WsHandler) http.Handler {
+func NewRouter(h *Handler, games *GameHandler, ws *WsHandler, console *ConsoleHandler) http.Handler {
 	mux := http.NewServeMux()
 
 	mux.HandleFunc("GET /api/instances", h.GetInstances)
@@ -17,6 +17,9 @@ func NewRouter(h *Handler, games *GameHandler, ws *WsHandler) http.Handler {
 	if ws != nil {
 		mux.HandleFunc("GET /api/ws/events", ws.HandleEvents)
 	}
+	if console != nil {
+		mux.HandleFunc("GET /api/ws/console/{id}", console.HandleConsole)
+	}
 	if games != nil {
 		mux.HandleFunc("GET /api/games", games.GetGames)
 		mux.HandleFunc("GET /api/games/{id}/template", games.GetGameTemplate)
diff --git a/backend/internal/service/console_service.go b/backend/internal/service/console_service.go
new file mode 100644
index 0000000..43c5e73
--- /dev/null
+++ b/backend/internal/service/console_service.go
@@ -0,0 +1,55 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/docker/docker/api/types"
+	"github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/client"
+)
+
+// ErrContainerNotRunning 表示容器当前不处于运行状态，无法建立控制台 Attach。
+var ErrContainerNotRunning = errors.New("container is not running")
+
+// consoleDockerClient 定义 ConsoleService 依赖的最小 Docker 能力集合。
+type consoleDockerClient interface {
+	ContainerInspect(ctx context.Context, containerID string) (container.InspectResponse, error)
+	ContainerAttach(ctx context.Context, containerID string, options container.AttachOptions) (types.HijackedResponse, error)
+}
+
+// ConsoleService 封装容器控制台 Attach 的业务逻辑。
+type ConsoleService struct {
+	cli consoleDockerClient
+}
+
+// NewConsoleService 创建 ConsoleService。
+func NewConsoleService(cli *client.Client) *ConsoleService {
+	return &ConsoleService{cli: cli}
+}
+
+// Attach 连接到运行中容器的 stdin/stdout/stderr。
+func (s *ConsoleService) Attach(ctx context.Context, containerID string) (types.HijackedResponse, error) {
+	inspect, err := s.cli.ContainerInspect(ctx, containerID)
+	if err != nil {
+		return types.HijackedResponse{}, fmt.Errorf("inspect container: %w", err)
+	}
+
+	if inspect.State == nil || !inspect.State.Running {
+		return types.HijackedResponse{}, ErrContainerNotRunning
+	}
+
+	hijacked, err := s.cli.ContainerAttach(ctx, containerID, container.AttachOptions{
+		Logs:   true,
+		Stream: true,
+		Stdin:  true,
+		Stdout: true,
+		Stderr: true,
+	})
+	if err != nil {
+		return types.HijackedResponse{}, fmt.Errorf("attach container: %w", err)
+	}
+
+	return hijacked, nil
+}
diff --git a/backend/internal/service/console_service_test.go b/backend/internal/service/console_service_test.go
new file mode 100644
index 0000000..73b4bdc
--- /dev/null
+++ b/backend/internal/service/console_service_test.go
@@ -0,0 +1,101 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/docker/docker/api/types"
+	"github.com/docker/docker/api/types/container"
+)
+
+type fakeConsoleDockerClient struct {
+	inspectResp container.InspectResponse
+	inspectErr  error
+
+	attachResp   types.HijackedResponse
+	attachErr    error
+	attachCalled bool
+	attachID     string
+	attachOpts   container.AttachOptions
+}
+
+func (f *fakeConsoleDockerClient) ContainerInspect(_ context.Context, _ string) (container.InspectResponse, error) {
+	if f.inspectErr != nil {
+		return container.InspectResponse{}, f.inspectErr
+	}
+	return f.inspectResp, nil
+}
+
+func (f *fakeConsoleDockerClient) ContainerAttach(
+	_ context.Context,
+	containerID string,
+	options container.AttachOptions,
+) (types.HijackedResponse, error) {
+	f.attachCalled = true
+	f.attachID = containerID
+	f.attachOpts = options
+
+	if f.attachErr != nil {
+		return types.HijackedResponse{}, f.attachErr
+	}
+	return f.attachResp, nil
+}
+
+func TestConsoleServiceAttach_RunningContainer(t *testing.T) {
+	fake := &fakeConsoleDockerClient{
+		inspectResp: container.InspectResponse{
+			ContainerJSONBase: &container.ContainerJSONBase{State: &container.State{Running: true}},
+			Config:            &container.Config{Tty: true},
+		},
+		attachResp: types.HijackedResponse{},
+	}
+
+	svc := &ConsoleService{cli: fake}
+
+	_, err := svc.Attach(context.Background(), "c1")
+	if err != nil {
+		t.Fatalf("attach: %v", err)
+	}
+	if !fake.attachCalled {
+		t.Fatal("expected attach to be called")
+	}
+	if fake.attachID != "c1" {
+		t.Fatalf("unexpected attach id: %s", fake.attachID)
+	}
+	if !fake.attachOpts.Stream || !fake.attachOpts.Stdin || !fake.attachOpts.Stdout || !fake.attachOpts.Stderr {
+		t.Fatalf("unexpected attach options: %+v", fake.attachOpts)
+	}
+}
+
+func TestConsoleServiceAttach_StoppedContainer(t *testing.T) {
+	fake := &fakeConsoleDockerClient{
+		inspectResp: container.InspectResponse{
+			ContainerJSONBase: &container.ContainerJSONBase{State: &container.State{Running: false}},
+			Config:            &container.Config{Tty: false},
+		},
+	}
+
+	svc := &ConsoleService{cli: fake}
+
+	_, err := svc.Attach(context.Background(), "c1")
+	if !errors.Is(err, ErrContainerNotRunning) {
+		t.Fatalf("expected ErrContainerNotRunning, got %v", err)
+	}
+	if fake.attachCalled {
+		t.Fatal("attach should not be called for stopped container")
+	}
+}
+
+func TestConsoleServiceAttach_ContainerNotFound(t *testing.T) {
+	fake := &fakeConsoleDockerClient{inspectErr: errors.New("no such container")}
+	svc := &ConsoleService{cli: fake}
+
+	_, err := svc.Attach(context.Background(), "missing")
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if errors.Is(err, ErrContainerNotRunning) {
+		t.Fatalf("unexpected not running error: %v", err)
+	}
+}
diff --git a/backend/internal/service/docker_service.go b/backend/internal/service/docker_service.go
index e0030b2..154c895 100644
--- a/backend/internal/service/docker_service.go
+++ b/backend/internal/service/docker_service.go
@@ -94,6 +94,12 @@ func (s *DockerService) CreateInstance(ctx context.Context, name, gameID string,
 		Cmd:          cmd,
 		Env:          mapToDockerEnv(env),
 		ExposedPorts: exposedPorts,
+		Tty:          true,
+		AttachStdin:  true,
+		AttachStdout: true,
+		AttachStderr: true,
+		OpenStdin:    true,
+		StdinOnce:    false,
 		Labels: map[string]string{
 			managedLabelKey: managedLabelValue,
 			nameLabelKey:    name,
diff --git a/backend/main.go b/backend/main.go
index c6f9432..123a59d 100644
--- a/backend/main.go
+++ b/backend/main.go
@@ -56,7 +56,9 @@ func main() {
 	h := api.NewHandler(svc)
 	gameHandler := api.NewGameHandler(gameSvc)
 	wsHandler := api.NewWsHandler(hub)
-	router := api.NewRouter(h, gameHandler, wsHandler)
+	consoleSvc := service.NewConsoleService(cli)
+	consoleHandler := api.NewConsoleHandler(consoleSvc)
+	router := api.NewRouter(h, gameHandler, wsHandler, consoleHandler)
 
 	addr := ":8080"
 	log.Printf("MineDock backend listening on %s", addr)
diff --git a/docs/api/contracts.md b/docs/api/contracts.md
index b2e695b..b5d7193 100644
--- a/docs/api/contracts.md
+++ b/docs/api/contracts.md
@@ -175,3 +175,18 @@
 
 - 触发时机：任一托管容器状态发生变化（`start` / `stop` / `die` / `destroy` / `kill`）
 - 降级方案：客户端连接失败时应回退到轮询 `GET /api/instances`
+
+### GET /api/ws/console/:id (WebSocket)
+
+- 说明：建立 WebSocket 连接，双向桥接容器主进程的 stdin/stdout/stderr
+- 协议：WebSocket（HTTP Upgrade）
+- 前置条件：容器必须处于 Running 状态
+- 路径参数：`id`（容器 ID）
+- 数据流向：
+  - 服务端 -> 客户端：容器 stdout/stderr 输出（Binary 帧）
+  - 客户端 -> 服务端：用户输入命令（Text/Binary 帧，原样写入容器 stdin）
+- TTY 自适应：
+  - TTY 容器：直接转发输出流
+  - 非 TTY 容器：服务端使用 Docker 多路复用解复用后再转发
+- 连接关闭时机：客户端断开、容器退出、服务端关闭连接
+- 失败行为：容器不存在或未运行时，服务端在升级后主动关闭连接并返回原因
diff --git a/docs/design-docs/instance_lifecycle.md b/docs/design-docs/instance_lifecycle.md
index 4168ea6..285ff2b 100644
--- a/docs/design-docs/instance_lifecycle.md
+++ b/docs/design-docs/instance_lifecycle.md
@@ -52,6 +52,14 @@ stateDiagram-v2
 - 收敛机制（主路径）：监听 Docker Events，在容器状态变化后通过 WebSocket 推送最新实例快照。
 - 收敛机制（降级路径）：`ListInstances` 按需对账 Docker -> SQLite；当前端 WebSocket 不可用时回退到轮询接口。
 
+## 控制台交互
+
+- 路由：前端通过 `/instances/:id` 进入容器详情页，页面建立 `GET /api/ws/console/:id` WebSocket。
+- 输入链路：浏览器 WebSocket 输入 -> 后端 ConsoleHandler -> Docker Attach stdin。
+- 输出链路：Docker Attach stdout/stderr -> 后端 ConsoleHandler -> 浏览器 WebSocket -> xterm.js。
+- 运行态约束：仅 Running 容器允许 Attach；容器停止后连接会断开，页面提示用户重新启动后再连接。
+- TTY 差异：TTY 容器输出直接透传；非 TTY 容器需先做 stdout/stderr 解复用再推送。
+
 ## 失败与回滚策略
 
 - 创建流程：若数据库保存失败，立即强制删除刚创建容器。
diff --git a/docs/exec-plans/active/20260402-container-console.md b/docs/exec-plans/active/20260402-container-console.md
new file mode 100644
index 0000000..7bcdea0
--- /dev/null
+++ b/docs/exec-plans/active/20260402-container-console.md
@@ -0,0 +1,444 @@
+# 容器详情页 Web 控制台（实时日志 + 交互式命令）
+
+## 背景
+
+当前 MineDock 的容器列表页仅展示容器卡片（名称、状态、启停按钮），用户无法查看容器的实时输出日志，也无法向运行中的容器发送命令（如 Minecraft 的 `/op`、`/whitelist` 等服务器指令）。对于游戏服务器管理场景，控制台是核心运维入口。
+
+本计划实现：
+
+1. 点击容器卡片后进入 **容器详情页**（新路由 `/instances/:id`）
+2. 详情页包含一个 **Web 终端**（基于 xterm.js），实时展示容器主进程的 stdout/stderr 输出
+3. 终端下方支持 **交互式命令输入**，用户输入的内容通过 WebSocket 写入容器的 stdin
+4. 后端通过 Docker SDK `ContainerAttach` 将容器的 stdin/stdout 双向桥接到 WebSocket
+
+## 需要评审的内容
+
+> [!IMPORTANT]
+> **Attach vs Exec 方案选型**
+>
+> Docker 提供两种方式与容器交互：
+>
+> | 方案                                 | 说明                               | 适用场景                                           |
+> | ------------------------------------ | ---------------------------------- | -------------------------------------------------- |
+> | **ContainerAttach**                  | 连接到容器主进程的 stdin/stdout    | 游戏服务器控制台（如 Minecraft 的 server console） |
+> | **ContainerExecCreate + ExecAttach** | 在容器中创建新进程（如 `/bin/sh`） | 调试、执行一次性命令                               |
+>
+> 本计划采用 **ContainerAttach** 方式。原因：
+>
+> - 游戏服务器（如 itzg/minecraft-server）的主进程本身就是服务端控制台，接受 stdin 命令
+> - Attach 可以看到服务器启动以来的完整日志流，不需要二次查询历史日志
+> - 无需容器内安装 shell，兼容精简镜像
+
+> [!IMPORTANT]
+> **前端终端库选型**
+>
+> 采用 **xterm.js**（`@xterm/xterm`），这是 VS Code 内置终端使用的库：
+>
+> - 支持 ANSI 转义序列（颜色、光标控制）
+> - 内置 WebSocket attach addon（`@xterm/addon-attach`）
+> - `@xterm/addon-fit` 自适应容器尺寸
+> - NPM 生态成熟，与 Vue 3 集成简单
+
+> [!WARNING]
+> **仅运行中的容器可以 Attach**
+>
+> Docker `ContainerAttach` 要求容器处于 Running 状态。如果容器已停止，后端返回错误，前端展示"容器未运行"提示。用户需先启动容器再查看控制台。
+
+> [!IMPORTANT]
+> **WebSocket 路径设计**
+>
+> 新增 WebSocket 端点 `GET /api/ws/console/{id}`，其中 `{id}` 为容器 ID。每个 WebSocket 连接对应一个 Docker Attach 会话。连接关闭时自动释放 Docker Attach 资源。
+>
+> 该端点与现有的 `GET /api/ws/events`（事件广播）相互独立。
+
+## 前端交互流程
+
+```mermaid
+sequenceDiagram
+    participant U as 用户
+    participant FE as 前端
+    participant BE as 后端
+    participant D as Docker Daemon
+
+    Note over U: 在容器列表点击卡片
+    U->>FE: 点击容器卡片
+    FE->>FE: 路由跳转 /instances/:id
+
+    Note over FE: 详情页挂载
+    FE->>BE: WebSocket /api/ws/console/{id}
+    BE->>D: ContainerAttach(stdin + stdout + stream)
+    D-->>BE: HijackedResponse (双向流)
+    BE-->>FE: WebSocket 连接建立
+
+    Note over D,FE: 实时日志推流
+    D-->>BE: 容器 stdout 输出
+    BE-->>FE: WebSocket 转发
+    FE->>FE: xterm.js 渲染日志
+
+    Note over U: 输入命令
+    U->>FE: 在终端输入 "/op player1"
+    FE->>BE: WebSocket 发送命令文本
+    BE->>D: 写入容器 stdin
+    D-->>BE: 命令执行结果 stdout
+    BE-->>FE: WebSocket 转发
+    FE->>FE: xterm.js 渲染输出
+
+    Note over U: 离开页面
+    FE->>BE: WebSocket 关闭
+    BE->>D: 关闭 Attach 流
+```
+
+## 拟定更改
+
+### 后端 Service 层
+
+#### [NEW] console_service.go (`backend/internal/service/console_service.go`)
+
+新增 `ConsoleService`，封装 Docker Attach 的双向流桥接逻辑：
+
+```go
+// ConsoleService 封装容器控制台的 Attach 逻辑。
+type ConsoleService struct {
+    cli *client.Client
+}
+
+// NewConsoleService 创建 ConsoleService。
+func NewConsoleService(cli *client.Client) *ConsoleService { ... }
+
+// Attach 连接到运行中容器的主进程 stdin/stdout/stderr。
+// 返回的 HijackedResponse 包含双向流，调用方负责关闭。
+// 容器未运行时返回错误。
+func (s *ConsoleService) Attach(ctx context.Context, containerID string) (types.HijackedResponse, error) {
+    // 1. ContainerInspect 检查容器是否 Running
+    // 2. ContainerAttach(ctx, containerID, container.AttachOptions{
+    //        Stream: true,
+    //        Stdin:  true,
+    //        Stdout: true,
+    //        Stderr: true,
+    //    })
+}
+```
+
+> [!NOTE]
+> `ConsoleService` 故意不依赖 `InstanceStore`。Attach 操作只需要 Docker client 和容器 ID，不涉及业务状态变更。保持职责单一。
+
+---
+
+### 后端 API 层
+
+#### [NEW] console_handler.go (`backend/internal/api/console_handler.go`)
+
+新增 WebSocket Handler，负责 HTTP → WebSocket 升级，然后在 WebSocket 和 Docker Attach 流之间做双向 pipe：
+
+```go
+// ContainerConsole 定义控制台 Handler 依赖的 Attach 能力。
+type ContainerConsole interface {
+    Attach(ctx context.Context, containerID string) (types.HijackedResponse, error)
+}
+
+// ConsoleHandler 暴露容器控制台 WebSocket 处理器。
+type ConsoleHandler struct {
+    console ContainerConsole
+}
+
+// NewConsoleHandler 创建 ConsoleHandler。
+func NewConsoleHandler(c ContainerConsole) *ConsoleHandler { ... }
+
+// HandleConsole 处理 GET /api/ws/console/{id}。
+// 将 HTTP 升级为 WebSocket，然后在 WebSocket ↔ Docker Attach 之间双向转发数据。
+func (h *ConsoleHandler) HandleConsole(w http.ResponseWriter, r *http.Request) {
+    // 1. 解析路径中的容器 ID
+    // 2. websocket.Accept() 升级连接
+    // 3. 调用 console.Attach() 获取 Docker 双向流
+    // 4. 启动两个 goroutine：
+    //    - Docker stdout → WebSocket write（容器输出推送给前端）
+    //    - WebSocket read → Docker stdin（用户输入写入容器）
+    // 5. 任一方向断开时关闭另一方，清理资源
+}
+```
+
+**双向桥接核心逻辑：**
+
+```go
+func (h *ConsoleHandler) bridgeLoop(ctx context.Context, conn *websocket.Conn, hijacked types.HijackedResponse) {
+    defer hijacked.Close()
+
+    done := make(chan struct{})
+
+    // Docker stdout → WebSocket
+    go func() {
+        defer close(done)
+        buf := make([]byte, 4096)
+        for {
+            n, err := hijacked.Reader.Read(buf)
+            if n > 0 {
+                writeCtx, cancel := context.WithTimeout(ctx, 3*time.Second)
+                _ = conn.Write(writeCtx, websocket.MessageBinary, buf[:n])
+                cancel()
+            }
+            if err != nil {
+                return
+            }
+        }
+    }()
+
+    // WebSocket → Docker stdin
+    go func() {
+        for {
+            _, data, err := conn.Read(ctx)
+            if err != nil {
+                return
+            }
+            _, _ = hijacked.Conn.Write(data)
+        }
+    }()
+
+    <-done
+}
+```
+
+#### [MODIFY] router.go (`backend/internal/api/router.go`)
+
+- `NewRouter` 签名新增 `*ConsoleHandler` 参数
+- 注册新路由：`GET /api/ws/console/{id}`（与 `/api/ws/events` 同级，跳过 CORS 中间件）
+
+---
+
+### 后端入口
+
+#### [MODIFY] main.go
+
+- 创建 `ConsoleService`，注入 Docker client
+- 创建 `ConsoleHandler`，注入 `ConsoleService`
+- 更新 `NewRouter` 调用
+
+```go
+consoleSvc := service.NewConsoleService(cli)
+consoleHandler := api.NewConsoleHandler(consoleSvc)
+router := api.NewRouter(h, gameHandler, wsHandler, consoleHandler)
+```
+
+---
+
+### 前端依赖
+
+#### [MODIFY] package.json
+
+新增依赖：
+
+```json
+{
+  "dependencies": {
+    "@xterm/xterm": "^5.x",
+    "@xterm/addon-fit": "^0.x",
+    "@xterm/addon-attach": "^0.x"
+  }
+}
+```
+
+---
+
+### 前端 API 层
+
+#### [MODIFY] index.ts (`frontend/src/api/index.ts`)
+
+新增 WebSocket URL 构造函数：
+
+```typescript
+// 构造容器控制台 WebSocket URL
+export function consoleWsUrl(containerId: string): string {
+  return `${WS_BASE_URL}/ws/console/${encodeURIComponent(containerId)}`;
+}
+```
+
+---
+
+### 前端 Composable 层
+
+#### [NEW] useConsole.ts (`frontend/src/composables/useConsole.ts`)
+
+新增 Composable，封装 xterm.js + WebSocket 的生命周期管理：
+
+```typescript
+// useConsole 管理容器控制台的 xterm.js 实例和 WebSocket 连接。
+export function useConsole(containerId: Ref<string>): {
+  /** xterm.js 挂载目标元素 */
+  terminalRef: Ref<HTMLElement | null>;
+  /** WebSocket 连接状态 */
+  connected: Ref<boolean>;
+  /** 错误信息 */
+  error: Ref<string | null>;
+  /** 初始化终端和 WebSocket（在 onMounted 中调用） */
+  init: () => void;
+  /** 销毁终端和 WebSocket（在 onUnmounted 中调用） */
+  dispose: () => void;
+};
+```
+
+核心逻辑：
+
+- **init**：创建 `Terminal` 实例 → 调用 `term.open(el)` → `FitAddon.fit()` → 建立 WebSocket → 使用 `AttachAddon` 桥接
+- **dispose**：关闭 WebSocket → 销毁 Terminal
+- **自适应尺寸**：监听 `ResizeObserver`，调用 `FitAddon.fit()`
+- **连接断开**：设置 `connected = false`，显示断线提示（不自动重连——用户刷新或重新进入详情页即可）
+
+---
+
+### 前端视图层
+
+#### [NEW] InstanceDetail.vue (`frontend/src/views/InstanceDetail.vue`)
+
+新增容器详情页，主体结构：
+
+```text
+┌─────────────────────────────────────────┐
+│ ← 返回        容器名称        状态指示器 │  ← 顶部导航栏
+├─────────────────────────────────────────┤
+│                                         │
+│                                         │
+│           xterm.js 终端区域              │  ← 实时日志 + 命令输出
+│         （黑底绿字/Create 主题风格）      │
+│                                         │
+│                                         │
+├─────────────────────────────────────────┤
+│ 连接状态指示 (绿点/灰点)                  │  ← 底部状态栏
+└─────────────────────────────────────────┘
+```
+
+组件职责：
+
+- 从路由参数获取 `containerId`
+- 调用 `useConsole(containerId)` 管理终端
+- 展示容器名称和状态（从 `useContainerStore` 获取）
+- 返回按钮跳回容器列表页
+- 容器未运行时展示提示信息，不初始化终端
+
+---
+
+### 前端路由
+
+#### [MODIFY] router/index.ts
+
+新增路由：
+
+```typescript
+{
+  path: "/instances/:id",
+  name: "InstanceDetail",
+  component: () => import("../views/InstanceDetail.vue"),
+  props: true,
+}
+```
+
+---
+
+### 前端容器列表页
+
+#### [MODIFY] ContainerList.vue (`frontend/src/views/ContainerList.vue`)
+
+- 容器卡片增加点击事件，点击后跳转 `/instances/:id`
+- 使用 `router.push({ name: 'InstanceDetail', params: { id: container.container_id } })`
+
+---
+
+### 文档
+
+#### [MODIFY] contracts.md (`docs/api/contracts.md`)
+
+新增 WebSocket 接口文档：
+
+```markdown
+### GET /api/ws/console/:id (WebSocket)
+
+- 说明：建立 WebSocket 连接，双向桥接容器主进程的 stdin/stdout
+- 协议：WebSocket（HTTP Upgrade）
+- 前置条件：容器必须处于 Running 状态
+- 数据流向：
+  - 服务端 → 客户端：容器 stdout/stderr 输出（二进制帧）
+  - 客户端 → 服务端：用户输入指令（文本帧，自动写入容器 stdin）
+- 连接关闭时机：客户端断开 / 容器停止 / 服务端关闭
+- 错误情况：容器不存在或未运行时，WebSocket 升级后立即关闭并附带错误原因
+```
+
+#### [MODIFY] instance_lifecycle.md (`docs/design-docs/instance_lifecycle.md`)
+
+补充控制台交互说明。
+
+#### [MODIFY] frontend.md (`docs/standards/frontend.md`)
+
+在路由部分新增：
+
+```markdown
+- `/instances/:id` 映射容器详情页（`InstanceDetail.vue`）
+```
+
+---
+
+## 执行步骤
+
+- [ ] 前端依赖
+  - [ ] 安装 `@xterm/xterm`、`@xterm/addon-fit`、`@xterm/addon-attach`
+- [ ] 后端 Service 层
+  - [ ] 新建 `backend/internal/service/console_service.go`，实现 `ConsoleService`
+    - [ ] Attach 方法：检查容器运行状态 → 调用 Docker `ContainerAttach`
+- [ ] 后端 API 层
+  - [ ] 新建 `backend/internal/api/console_handler.go`，实现 `ConsoleHandler`
+    - [ ] WebSocket 升级 → Docker Attach → 双向 pipe
+    - [ ] 容器 stdout → WebSocket write goroutine
+    - [ ] WebSocket read → Docker stdin goroutine
+    - [ ] 连接断开清理逻辑
+  - [ ] 修改 `router.go`：注册 `GET /api/ws/console/{id}`，更新 `NewRouter` 签名
+- [ ] 后端入口
+  - [ ] 修改 `main.go`：创建 ConsoleService/ConsoleHandler、注入路由
+- [ ] 前端 API 层
+  - [ ] 修改 `api/index.ts`：新增 `consoleWsUrl()` 函数
+- [ ] 前端 Composable 层
+  - [ ] 新建 `composables/useConsole.ts`：xterm.js + WebSocket 生命周期管理
+- [ ] 前端视图层
+  - [ ] 新建 `views/InstanceDetail.vue`：容器详情页 + xterm.js 终端
+  - [ ] 修改 `views/ContainerList.vue`：容器卡片增加点击跳转
+- [ ] 前端路由
+  - [ ] 修改 `router/index.ts`：注册 `/instances/:id` 路由
+- [ ] 后端测试
+  - [ ] 编写 `ConsoleService.Attach` 单元测试（容器运行/容器停止/容器不存在）
+  - [ ] 运行 `task backend:test && task backend:vet && task backend:lint`
+- [ ] 前端检查
+  - [ ] 运行 `npm run lint`
+- [ ] 文档更新
+  - [ ] 修改 `docs/api/contracts.md`：新增控制台 WebSocket 文档
+  - [ ] 修改 `docs/standards/frontend.md`：新增路由说明
+  - [ ] 修改 `docs/design-docs/instance_lifecycle.md`：补充控制台说明
+
+## 已确认的决策
+
+- ✅ **历史日志回看**：本期不实现。用户进入详情页后只能看到实时输出流（attach 之后的内容）。历史日志回看（进入页面时先拉取最近 N 行）留作后续增强。
+
+> [!NOTE]
+> **TTY 模式自适应（设计说明）**
+>
+> 游戏服务器镜像（如 itzg/minecraft-server）通常以 TTY 模式运行。Attach 时需要匹配容器的 TTY 设置：
+>
+> - 如果容器有 TTY（`Config.Tty == true`）：输出流不需要 `stdcopy` 解复用，直接转发
+> - 如果容器无 TTY：stdout/stderr 是 Docker 多路复用格式，需要用 `stdcopy.StdCopy` 解复用
+>
+> 本计划在 Attach 前通过 `ContainerInspect` 检测 TTY 设置，自适应处理。
+
+## 验证计划
+
+### 自动化测试
+
+- `task backend:test` — 覆盖：
+  - `ConsoleService.Attach`：容器运行时成功、容器停止时报错、容器不存在时报错
+- `task backend:vet && task backend:lint`
+- 前端：`npm run lint`
+
+### 手动验证
+
+- 创建并启动一个 Minecraft Java 实例
+- 在容器列表页点击容器卡片，验证路由跳转到 `/instances/:id`
+- 验证 xterm.js 终端渲染，WebSocket 连接指示器显示绿色
+- 验证容器启动日志实时滚动输出到终端
+- 在终端输入 Minecraft 服务器命令（如 `list`），验证命令被发送且返回结果显示在终端
+- 停止容器，验证 WebSocket 自动断开，终端显示断线提示
+- 对已停止的容器进入详情页，验证展示"容器未运行"提示而非空白终端
+- 浏览器调整窗口大小，验证 xterm.js 终端自适应 resize
diff --git a/docs/standards/frontend.md b/docs/standards/frontend.md
index 1342922..f4289f4 100644
--- a/docs/standards/frontend.md
+++ b/docs/standards/frontend.md
@@ -70,6 +70,7 @@
 - 当前路由：
   - `/` 映射容器列表页（`ContainerList.vue`）
   - `/registry` 映射游戏模板市场页（`ImageRegistry.vue`）
+  - `/instances/:id` 映射容器详情页（`InstanceDetail.vue`）
 - 当前版本无登录鉴权。
 - 新增页面时要求：
   - 在 `router/index.ts` 显式注册路由
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index 806fc35..3efac34 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -8,6 +8,9 @@
       "name": "minedock-frontend",
       "version": "0.1.0",
       "dependencies": {
+        "@xterm/addon-attach": "^0.11.0",
+        "@xterm/addon-fit": "^0.10.0",
+        "@xterm/xterm": "^5.5.0",
         "pinia": "^3.0.4",
         "vue": "^3.5.31",
         "vue-i18n": "^11.3.0",
@@ -1140,6 +1143,30 @@
       "integrity": "sha512-nBxuiuS9Lj5bPkPbWogPUnjxxWpkRniX7e5UBQDWl6Fsf4roq9wwV+cR7ezQ4zXswNvPIlsdj1slcLB7XCsRAw==",
       "license": "MIT"
     },
+    "node_modules/@xterm/addon-attach": {
+      "version": "0.11.0",
+      "resolved": "https://registry.npmjs.org/@xterm/addon-attach/-/addon-attach-0.11.0.tgz",
+      "integrity": "sha512-JboCN0QAY6ZLY/SSB/Zl2cQ5zW1Eh4X3fH7BnuR1NB7xGRhzbqU2Npmpiw/3zFlxDaU88vtKzok44JKi2L2V2Q==",
+      "license": "MIT",
+      "peerDependencies": {
+        "@xterm/xterm": "^5.0.0"
+      }
+    },
+    "node_modules/@xterm/addon-fit": {
+      "version": "0.10.0",
+      "resolved": "https://registry.npmjs.org/@xterm/addon-fit/-/addon-fit-0.10.0.tgz",
+      "integrity": "sha512-UFYkDm4HUahf2lnEyHvio51TNGiLK66mqP2JoATy7hRZeXaGMRDr00JiSF7m63vR5WKATF605yEggJKsw0JpMQ==",
+      "license": "MIT",
+      "peerDependencies": {
+        "@xterm/xterm": "^5.0.0"
+      }
+    },
+    "node_modules/@xterm/xterm": {
+      "version": "5.5.0",
+      "resolved": "https://registry.npmjs.org/@xterm/xterm/-/xterm-5.5.0.tgz",
+      "integrity": "sha512-hqJHYaQb5OptNunnyAnkHyM8aCjZ1MEIDTQu1iIbbTD/xops91NB5yq1ZK/dC2JDbVWtF23zUtl9JE2NqwT87A==",
+      "license": "MIT"
+    },
     "node_modules/acorn": {
       "version": "8.16.0",
       "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz",
diff --git a/frontend/package.json b/frontend/package.json
index f3810b1..b7c1068 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -13,6 +13,9 @@
     "format:check": "prettier . --check"
   },
   "dependencies": {
+    "@xterm/addon-attach": "^0.11.0",
+    "@xterm/addon-fit": "^0.10.0",
+    "@xterm/xterm": "^5.5.0",
     "pinia": "^3.0.4",
     "vue": "^3.5.31",
     "vue-i18n": "^11.3.0",
diff --git a/frontend/src/api/index.ts b/frontend/src/api/index.ts
index 3985fb8..7e268fe 100644
--- a/frontend/src/api/index.ts
+++ b/frontend/src/api/index.ts
@@ -12,6 +12,11 @@ const wsHost = typeof window === "undefined" ? resolvedBaseURL.host : window.loc
 const wsPath = resolvedBaseURL.pathname.replace(/\/+$/, "");
 export const WS_BASE_URL = `${wsProtocol}//${wsHost}${wsPath}`;
 
+// consoleWsUrl 构造容器控制台 WebSocket 地址。
+export function consoleWsUrl(containerId: string): string {
+  return `${WS_BASE_URL}/ws/console/${encodeURIComponent(containerId)}`;
+}
+
 type JsonObject = Record<string, unknown>;
 
 interface RequestOptions extends Omit<RequestInit, "headers" | "body"> {
diff --git a/frontend/src/components/Sidebar.vue b/frontend/src/components/Sidebar.vue
index 57e0537..c21bbc3 100644
--- a/frontend/src/components/Sidebar.vue
+++ b/frontend/src/components/Sidebar.vue
@@ -78,13 +78,13 @@ const isOpen = ref<boolean>(false);
 /* =========== 移动端悬浮按钮与遮罩 =========== */
 .hamburger-btn {
   position: fixed;
-  top: 14px; /* 精确对应桌面端通过 padding-top 计算出来的垂直偏移像素 */
-  left: 12px; /* 精确对应桌面端侧边宽和内居中共计 12px 的水平偏移 */
+  top: 8px; /* header-height(48) / 2 - btn-height(32) / 2 = 8px */
+  left: 12px;
   z-index: 40;
   background: transparent;
   border: none;
   color: var(--create-brass-primary);
-  padding: 8px;
+  padding: 4px;
   cursor: pointer;
   display: flex;
   align-items: center;
@@ -186,7 +186,7 @@ const isOpen = ref<boolean>(false);
 .desktop-icon-container {
   width: 56px;
   height: var(--header-height);
-  padding-top: 12px; /* 把汉堡挪到底侧，为顶部让出刚好 4px 的纯净视觉间隙 */
+  padding-top: 12px; /* 把汉堡挪到底侧，为顶部让出刚好空隙 */
   display: flex;
   align-items: center;
   justify-content: center;
@@ -215,7 +215,7 @@ const isOpen = ref<boolean>(false);
   flex: 1;
   display: flex;
   flex-direction: column;
-  padding: 4px 0 10px 0; /* 严格配合上方给底侧留出对等的 4px 间隙，实现完美对称 */
+  padding: 4px 0 10px 0;
   overflow-y: auto;
   overflow-x: hidden;
   z-index: 10;
diff --git a/frontend/src/composables/useConsole.ts b/frontend/src/composables/useConsole.ts
new file mode 100644
index 0000000..18fb2ec
--- /dev/null
+++ b/frontend/src/composables/useConsole.ts
@@ -0,0 +1,184 @@
+import { FitAddon } from "@xterm/addon-fit";
+import { Terminal } from "@xterm/xterm";
+import "@xterm/xterm/css/xterm.css";
+import { ref, type Ref } from "vue";
+import { consoleWsUrl } from "../api/index";
+
+type Disposable = { dispose: () => void };
+
+export function useConsole(containerId: Ref<string>): {
+  terminalRef: Ref<HTMLElement | null>;
+  connected: Ref<boolean>;
+  error: Ref<string | null>;
+  init: () => void;
+  dispose: () => void;
+} {
+  const terminalRef = ref<HTMLElement | null>(null);
+  const connected = ref(false);
+  const error = ref<string | null>(null);
+
+  let terminal: Terminal | null = null;
+  let fitAddon: FitAddon | null = null;
+  let inputRelay: Disposable | null = null;
+  let socket: WebSocket | null = null;
+  let resizeObserver: ResizeObserver | null = null;
+  let disposed = true;
+  const encoder = new TextEncoder();
+
+  const closeSocket = (): void => {
+    if (!socket) {
+      return;
+    }
+
+    socket.onopen = null;
+    socket.onclose = null;
+    socket.onerror = null;
+
+    if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) {
+      socket.close(1000, "dispose");
+    }
+
+    socket = null;
+  };
+
+  const dispose = (): void => {
+    disposed = true;
+    connected.value = false;
+
+    if (resizeObserver !== null) {
+      resizeObserver.disconnect();
+      resizeObserver = null;
+    }
+
+    closeSocket();
+
+    inputRelay?.dispose();
+    inputRelay = null;
+
+    fitAddon?.dispose();
+    fitAddon = null;
+
+    terminal?.dispose();
+    terminal = null;
+  };
+
+  const init = (): void => {
+    const host = terminalRef.value;
+    if (!host || !containerId.value) {
+      connected.value = false;
+      error.value = "console.mountMissing";
+      return;
+    }
+
+    dispose();
+    disposed = false;
+    connected.value = false;
+    error.value = null;
+
+    terminal = new Terminal({
+      cursorBlink: true,
+      convertEol: true,
+      fontFamily: '"JetBrains Mono", "Cascadia Code", monospace',
+      fontSize: 14,
+      theme: {
+        background: "#0f1411",
+        foreground: "#9ee38f",
+        cursor: "#f5cb6e",
+      },
+    });
+
+    fitAddon = new FitAddon();
+    terminal.loadAddon(fitAddon);
+    terminal.open(host);
+    fitAddon.fit();
+
+    resizeObserver = new ResizeObserver(() => {
+      fitAddon?.fit();
+    });
+    resizeObserver.observe(host);
+
+    socket = new WebSocket(consoleWsUrl(containerId.value));
+    socket.binaryType = "arraybuffer";
+
+    socket.onmessage = (event: MessageEvent<string | ArrayBuffer | Blob>) => {
+      if (disposed) {
+        return;
+      }
+
+      if (typeof event.data === "string") {
+        terminal?.write(event.data);
+        return;
+      }
+
+      if (event.data instanceof ArrayBuffer) {
+        terminal?.write(new Uint8Array(event.data));
+        return;
+      }
+
+      void event.data
+        .arrayBuffer()
+        .then((buffer) => {
+          if (disposed) {
+            return;
+          }
+          terminal?.write(new Uint8Array(buffer));
+        })
+        .catch(() => {
+          // ignore blob decode errors from unexpected payloads
+        });
+    };
+
+    inputRelay = terminal.onData((data: string) => {
+      if (!socket || socket.readyState !== WebSocket.OPEN) {
+        return;
+      }
+
+      const bytes = encoder.encode(data);
+      if (bytes.length > 0) {
+        socket.send(bytes);
+      }
+    });
+
+    socket.onopen = () => {
+      if (disposed) {
+        return;
+      }
+      connected.value = true;
+      error.value = null;
+      fitAddon?.fit();
+      terminal?.focus();
+    };
+
+    socket.onerror = () => {
+      if (disposed) {
+        return;
+      }
+      connected.value = false;
+      if (!error.value) {
+        error.value = "console.connectionError";
+      }
+    };
+
+    socket.onclose = (event: CloseEvent) => {
+      if (disposed) {
+        return;
+      }
+      connected.value = false;
+      if (event.reason) {
+        error.value = event.reason;
+        return;
+      }
+      if (event.code !== 1000) {
+        error.value = "console.disconnected";
+      }
+    };
+  };
+
+  return {
+    terminalRef,
+    connected,
+    error,
+    init,
+    dispose,
+  };
+}
diff --git a/frontend/src/locales/en-US.json b/frontend/src/locales/en-US.json
index 20b70dd..29876e7 100644
--- a/frontend/src/locales/en-US.json
+++ b/frontend/src/locales/en-US.json
@@ -7,6 +7,17 @@
     "toggleTitle": "Start/Stop",
     "confirmDelete": "Are you sure you want to permanently delete this container?"
   },
+  "console": {
+    "back": "Back to List",
+    "loading": "Loading container state...",
+    "instanceNotFound": "Container not found or already removed.",
+    "instanceNotRunning": "Container is not running. Start it before opening the console.",
+    "connected": "Console connected",
+    "disconnectedLabel": "Console disconnected",
+    "connectionError": "Failed to connect to console. Refresh and try again.",
+    "statusUnknown": "Unknown",
+    "mountMissing": "Terminal is not ready yet. Please try again."
+  },
   "createModal": {
     "title": "New Container",
     "placeholder": "Enter container name...",
diff --git a/frontend/src/locales/zh-CN.json b/frontend/src/locales/zh-CN.json
index 8dab688..3af6926 100644
--- a/frontend/src/locales/zh-CN.json
+++ b/frontend/src/locales/zh-CN.json
@@ -7,6 +7,17 @@
     "toggleTitle": "开启/关闭",
     "confirmDelete": "确认彻底删除该容器吗？"
   },
+  "console": {
+    "back": "返回列表",
+    "loading": "正在加载容器状态...",
+    "instanceNotFound": "容器不存在或已被删除。",
+    "instanceNotRunning": "容器未运行，请先启动后再连接控制台。",
+    "connected": "控制台已连接",
+    "disconnectedLabel": "控制台未连接",
+    "connectionError": "控制台连接失败，请刷新页面重试。",
+    "statusUnknown": "状态未知",
+    "mountMissing": "终端尚未准备好，请稍后重试。"
+  },
   "createModal": {
     "title": "新建容器",
     "placeholder": "请输入新容器名称...",
diff --git a/frontend/src/router/index.ts b/frontend/src/router/index.ts
index 391b2e3..328f1ca 100644
--- a/frontend/src/router/index.ts
+++ b/frontend/src/router/index.ts
@@ -19,6 +19,11 @@ const router = createRouter({
       name: "CreateInstance",
       component: () => import("../views/CreateInstance.vue"),
     },
+    {
+      path: "/instances/:id",
+      name: "InstanceDetail",
+      component: () => import("../views/InstanceDetail.vue"),
+    },
   ],
 });
 
diff --git a/frontend/src/views/ContainerList.vue b/frontend/src/views/ContainerList.vue
index 3973c9d..d2bfdd8 100644
--- a/frontend/src/views/ContainerList.vue
+++ b/frontend/src/views/ContainerList.vue
@@ -44,6 +44,10 @@ function goToTemplateMarket(): void {
   void router.push({ name: "ImageRegistry" });
 }
 
+function openInstanceDetail(containerId: string): void {
+  void router.push({ name: "InstanceDetail", params: { id: containerId } });
+}
+
 // 删除属于破坏性操作，执行前必须二次确认。
 async function handleDelete(containerId: string): Promise<void> {
   if (!confirm(t("containers.confirmDelete"))) return;
@@ -74,7 +78,6 @@ async function handleToggle(instance: {
 </script>
 
 <template>
-  <!-- 顶部栏 -->
   <header class="page-header">
     <h1 class="page-title">{{ $t("containers.title") }}</h1>
   </header>
@@ -92,13 +95,18 @@ async function handleToggle(instance: {
         {{ $t("containers.emptyState") }}
       </div>
 
-      <div v-for="item in store.instances" :key="item.container_id" class="card">
+      <div
+        v-for="item in store.instances"
+        :key="item.container_id"
+        class="card"
+        @click="openInstanceDetail(item.container_id)"
+      >
         <!-- 左侧：容器名称 -->
         <div class="card-left">
           <span class="card-name">{{ item.name }}</span>
         </div>
         <!-- 右侧：控制按钮（拉杆与删除） -->
-        <div class="card-right">
+        <div class="card-right" @click.stop>
           <label class="switch" :title="$t('containers.toggleTitle')">
             <input
               type="checkbox"
@@ -127,6 +135,13 @@ async function handleToggle(instance: {
   justify-content: center;
   flex-shrink: 0;
   position: relative;
+  padding: 0 80px 0 24px; /* 为右侧透明的全局 TopBar 预留 80px 的事件不遮挡空间，左层 24px */
+}
+
+@media (max-width: 767px) {
+  .page-header {
+    padding: 0 80px 0 52px; /* 移动端左侧多让出 52px 的空间给绝对定位的 Hamburger，防止标题偏移碰撞 */
+  }
 }
 
 .page-title {
@@ -138,7 +153,6 @@ async function handleToggle(instance: {
   font-family: "Segoe UI", "PingFang SC", sans-serif;
 }
 
-/* 内容区操作栏与新建按钮 */
 .content-actions {
   display: flex;
   justify-content: flex-end;
@@ -161,7 +175,7 @@ async function handleToggle(instance: {
 }
 
 .main-content {
-  padding: 8px 24px 24px 24px;
+  padding: 0 24px 24px 24px;
   flex: 1;
   display: flex;
   flex-direction: column;
@@ -220,6 +234,10 @@ async function handleToggle(instance: {
   filter: brightness(0.96);
 }
 
+.card {
+  cursor: pointer;
+}
+
 .card-left {
   display: flex;
   flex-direction: column;
diff --git a/frontend/src/views/InstanceDetail.vue b/frontend/src/views/InstanceDetail.vue
new file mode 100644
index 0000000..00f9c20
--- /dev/null
+++ b/frontend/src/views/InstanceDetail.vue
@@ -0,0 +1,255 @@
+<script setup lang="ts">
+import { computed, nextTick, onUnmounted, ref, watch } from "vue";
+import { useRoute, useRouter } from "vue-router";
+import { useI18n } from "vue-i18n";
+import { useConsole } from "../composables/useConsole";
+import { useContainerStore } from "../stores/containers";
+
+const route = useRoute();
+const router = useRouter();
+const { t } = useI18n();
+const store = useContainerStore();
+
+const loading = ref(true);
+const containerId = ref("");
+
+const { terminalRef, error, init, dispose } = useConsole(containerId);
+
+const currentInstance = computed(() => {
+  return store.instances.find((item) => item.container_id === containerId.value) ?? null;
+});
+
+const containerName = computed(() => {
+  return currentInstance.value?.name || containerId.value;
+});
+
+const canAttach = computed(() => {
+  return currentInstance.value ? store.isRunning(currentInstance.value.status) : false;
+});
+
+const infoKey = computed<string | null>(() => {
+  if (!containerId.value) {
+    return "errors.invalidContainerId";
+  }
+  if (loading.value) {
+    return "console.loading";
+  }
+  if (!currentInstance.value) {
+    return "console.instanceNotFound";
+  }
+  if (!canAttach.value) {
+    return "console.instanceNotRunning";
+  }
+  return null;
+});
+
+const displayError = computed(() => {
+  if (!error.value) {
+    return "";
+  }
+  if (error.value.includes("container is not running")) {
+    return t("console.instanceNotRunning");
+  }
+  if (error.value.includes("no such container")) {
+    return t("console.instanceNotFound");
+  }
+  if (error.value.startsWith("console.")) {
+    return t(error.value);
+  }
+  return error.value;
+});
+
+function parseContainerID(value: unknown): string {
+  if (Array.isArray(value)) {
+    return typeof value[0] === "string" ? value[0].trim() : "";
+  }
+  return typeof value === "string" ? value.trim() : "";
+}
+
+async function loadInstance(): Promise<void> {
+  loading.value = true;
+  dispose();
+
+  containerId.value = parseContainerID(route.params.id);
+  if (!containerId.value) {
+    loading.value = false;
+    return;
+  }
+
+  await store.fetchInstances();
+  loading.value = false;
+}
+
+function backToList(): void {
+  void router.push({ name: "ContainerList" });
+}
+
+watch(
+  () => route.params.id,
+  () => {
+    void loadInstance();
+  },
+  { immediate: true },
+);
+
+watch(
+  [loading, canAttach],
+  ([isLoading, running]) => {
+    if (isLoading || !running) {
+      dispose();
+      return;
+    }
+    void nextTick(() => {
+      init();
+    });
+  },
+  { immediate: true },
+);
+
+onUnmounted(() => {
+  dispose();
+});
+</script>
+
+<template>
+  <header class="page-header">
+    <div class="header-left">
+      <button class="back-btn" @click="backToList">&lt;</button>
+    </div>
+    <h1 class="page-title">{{ containerName }}</h1>
+    <div class="header-right"></div>
+  </header>
+
+  <main class="main-content">
+    <section class="terminal-panel">
+      <div v-if="infoKey" class="panel-overlay">
+        {{ $t(infoKey) }}
+      </div>
+      <div v-else ref="terminalRef" class="terminal-host"></div>
+    </section>
+
+    <footer v-if="displayError" class="status-bar">
+      <div class="error-text">{{ displayError }}</div>
+    </footer>
+  </main>
+</template>
+
+<style scoped>
+.page-header {
+  height: var(--header-height);
+  display: grid;
+  grid-template-columns: 1fr auto 1fr;
+  align-items: center;
+  gap: 12px;
+  padding: 0 80px 0 24px; /* 右侧留给 Top actions，左侧常规 24px (桌面汉堡在自身 sidebar 中，不挤占 header) */
+  flex-shrink: 0;
+}
+
+.header-left {
+  justify-self: start;
+}
+
+.header-right {
+  justify-self: end;
+}
+
+.back-btn {
+  border: 1px solid var(--create-border-outer);
+  background: rgba(0, 0, 0, 0.25);
+  color: var(--create-brass-primary);
+  padding: 6px 12px;
+  border-radius: 4px;
+  cursor: pointer;
+  font-weight: bold;
+}
+
+.back-btn:hover {
+  background: rgba(0, 0, 0, 0.4);
+}
+
+.page-title {
+  margin: 0;
+  color: var(--create-brass-primary);
+  font-size: 16px;
+  letter-spacing: 1px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  text-align: center;
+}
+
+.main-content {
+  flex: 1;
+  min-height: 0;
+  max-width: 1200px;
+  width: 100%;
+  margin: 0 auto;
+  padding: 8px 24px 24px;
+  display: grid;
+  grid-template-rows: 1fr auto;
+  gap: 12px;
+}
+
+.terminal-panel {
+  min-height: 0;
+  position: relative;
+  border: 1px solid var(--create-border-outer);
+  background: radial-gradient(circle at top, rgba(33, 55, 40, 0.9), rgba(9, 12, 11, 0.95));
+  border-radius: 6px;
+  overflow: hidden;
+}
+
+.terminal-host {
+  width: 100%;
+  height: 100%;
+  padding: 0;
+}
+
+.panel-overlay {
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--create-brass-primary);
+  background: rgba(0, 0, 0, 0.35);
+  font-size: 15px;
+}
+
+.status-bar {
+  border: 1px solid var(--create-border-outer);
+  background: rgba(0, 0, 0, 0.28);
+  border-radius: 6px;
+  padding: 10px 12px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.error-text {
+  color: var(--danger);
+  font-size: 13px;
+  text-align: right;
+}
+
+@media (max-width: 767px) {
+  .page-header {
+    padding: 0 80px 0 52px; /* 避开左边栏悬浮按钮和右边栏操作区 */
+    grid-template-columns: 1fr auto 1fr;
+    height: var(--header-height);
+  }
+
+  .main-content {
+    padding: 8px 12px 12px;
+  }
+
+  .status-bar {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+
+  .error-text {
+    text-align: left;
+  }
+}
+</style>

From 403b12cc7cb6a6ded65ad7987f5f16386c17da80 Mon Sep 17 00:00:00 2001
From: mf1bzz-desktop <guzemin@hotmail.com>
Date: Sat, 4 Apr 2026 17:13:51 +0800
Subject: [PATCH 28/28] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E5=AE=B9?=
 =?UTF-8?q?=E5=99=A8=E9=85=8D=E7=BD=AE=E9=A1=B5=E9=9D=A2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 backend/internal/api/config_handler.go        |  94 +++
 backend/internal/api/config_handler_test.go   | 163 ++++++
 backend/internal/api/handlers.go              |  13 +-
 backend/internal/api/handlers_test.go         |  38 +-
 backend/internal/api/router.go                |   8 +-
 backend/internal/model/errors.go              |   3 +
 backend/internal/model/instance.go            |   1 +
 backend/internal/service/docker_service.go    | 343 ++++++++++-
 .../internal/service/docker_service_test.go   | 414 ++++++++++++++
 backend/internal/store/sqlite.go              |  43 +-
 backend/internal/store/sqlite_test.go         |  22 +-
 backend/main.go                               |   3 +-
 docs/api/contracts.md                         |  50 +-
 docs/design-docs/instance_lifecycle.md        |  12 +-
 .../active/20260403-detail-tabs-config.md     | 533 ++++++++++++++++++
 frontend/src/api/index.ts                     |  33 +-
 frontend/src/locales/en-US.json               |  21 +
 frontend/src/locales/zh-CN.json               |  21 +
 frontend/src/stores/containers.ts             |   5 +-
 frontend/src/views/CreateInstance.vue         |  56 +-
 frontend/src/views/InstanceConfig.vue         | 496 ++++++++++++++++
 frontend/src/views/InstanceDetail.vue         | 103 +++-
 22 files changed, 2414 insertions(+), 61 deletions(-)
 create mode 100644 backend/internal/api/config_handler.go
 create mode 100644 backend/internal/api/config_handler_test.go
 create mode 100644 docs/exec-plans/active/20260403-detail-tabs-config.md
 create mode 100644 frontend/src/views/InstanceConfig.vue

diff --git a/backend/internal/api/config_handler.go b/backend/internal/api/config_handler.go
new file mode 100644
index 0000000..f44c6a2
--- /dev/null
+++ b/backend/internal/api/config_handler.go
@@ -0,0 +1,94 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+
+	"minedock/backend/internal/model"
+	"minedock/backend/internal/service"
+)
+
+// InstanceConfigurator 定义配置 Handler 依赖的业务能力。
+type InstanceConfigurator interface {
+	GetInstanceConfig(ctx context.Context, containerID string) (*service.InstanceConfig, error)
+	UpdateInstanceConfig(
+		ctx context.Context,
+		containerID string,
+		params map[string]string,
+		ports []model.PortMapping,
+	) (string, error)
+}
+
+// ConfigHandler 暴露容器配置相关 HTTP 处理器。
+type ConfigHandler struct {
+	cfg InstanceConfigurator
+}
+
+// NewConfigHandler 创建 ConfigHandler。
+func NewConfigHandler(cfg InstanceConfigurator) *ConfigHandler {
+	return &ConfigHandler{cfg: cfg}
+}
+
+type updateConfigRequest struct {
+	Params map[string]string   `json:"params"`
+	Ports  []model.PortMapping `json:"ports"`
+}
+
+type updateConfigResponse struct {
+	Status      string `json:"status"`
+	ContainerID string `json:"container_id"`
+}
+
+// HandleGetConfig 处理 GET /api/instances/{id}/config。
+func (h *ConfigHandler) HandleGetConfig(w http.ResponseWriter, r *http.Request) {
+	if h == nil || h.cfg == nil {
+		writeJSON(w, http.StatusServiceUnavailable, statusResponse{Status: "error", Error: "config service unavailable"})
+		return
+	}
+
+	id, ok := pathContainerID(r)
+	if !ok {
+		writeJSON(w, http.StatusBadRequest, statusResponse{Status: "error", Error: "invalid container id"})
+		return
+	}
+
+	cfg, err := h.cfg.GetInstanceConfig(r.Context(), id)
+	if err != nil {
+		writeJSON(w, mapErrorCode(err), statusResponse{Status: "error", Error: err.Error()})
+		return
+	}
+
+	writeJSON(w, http.StatusOK, cfg)
+}
+
+// HandleUpdateConfig 处理 PUT /api/instances/{id}/config。
+func (h *ConfigHandler) HandleUpdateConfig(w http.ResponseWriter, r *http.Request) {
+	if h == nil || h.cfg == nil {
+		writeJSON(w, http.StatusServiceUnavailable, statusResponse{Status: "error", Error: "config service unavailable"})
+		return
+	}
+
+	id, ok := pathContainerID(r)
+	if !ok {
+		writeJSON(w, http.StatusBadRequest, statusResponse{Status: "error", Error: "invalid container id"})
+		return
+	}
+
+	var req updateConfigRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeJSON(w, http.StatusBadRequest, statusResponse{Status: "error", Error: "invalid json body"})
+		return
+	}
+	if req.Params == nil {
+		req.Params = map[string]string{}
+	}
+
+	newID, err := h.cfg.UpdateInstanceConfig(r.Context(), id, req.Params, req.Ports)
+	if err != nil {
+		writeJSON(w, mapErrorCode(err), statusResponse{Status: "error", Error: err.Error()})
+		return
+	}
+
+	writeJSON(w, http.StatusOK, updateConfigResponse{Status: "success", ContainerID: newID})
+}
diff --git a/backend/internal/api/config_handler_test.go b/backend/internal/api/config_handler_test.go
new file mode 100644
index 0000000..e2964d9
--- /dev/null
+++ b/backend/internal/api/config_handler_test.go
@@ -0,0 +1,163 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"minedock/backend/internal/model"
+	"minedock/backend/internal/service"
+)
+
+type mockConfigurator struct {
+	getFn    func(ctx context.Context, containerID string) (*service.InstanceConfig, error)
+	updateFn func(ctx context.Context, containerID string, params map[string]string, ports []model.PortMapping) (string, error)
+}
+
+func (m *mockConfigurator) GetInstanceConfig(ctx context.Context, containerID string) (*service.InstanceConfig, error) {
+	if m == nil || m.getFn == nil {
+		return nil, errTest
+	}
+	return m.getFn(ctx, containerID)
+}
+
+func (m *mockConfigurator) UpdateInstanceConfig(
+	ctx context.Context,
+	containerID string,
+	params map[string]string,
+	ports []model.PortMapping,
+) (string, error) {
+	if m == nil || m.updateFn == nil {
+		return "", errTest
+	}
+	return m.updateFn(ctx, containerID, params, ports)
+}
+
+func newConfigTestRouter(cfg *mockConfigurator) http.Handler {
+	h := NewHandler(&mockService{
+		listFn: func(_ context.Context) ([]model.Instance, error) {
+			return []model.Instance{}, nil
+		},
+		createFn: func(_ context.Context, _, _ string, _ map[string]string, _ []model.PortMapping) (string, error) {
+			return "", nil
+		},
+		startFn: func(_ context.Context, _ string) error { return nil },
+		stopFn:  func(_ context.Context, _ string) error { return nil },
+		deleteFn: func(_ context.Context, _ string) error {
+			return nil
+		},
+	})
+
+	return NewRouter(h, nil, nil, nil, NewConfigHandler(cfg))
+}
+
+func TestGetConfig_Success(t *testing.T) {
+	router := newConfigTestRouter(&mockConfigurator{
+		getFn: func(_ context.Context, containerID string) (*service.InstanceConfig, error) {
+			if containerID != "c1" {
+				t.Fatalf("unexpected container id: %s", containerID)
+			}
+			return &service.InstanceConfig{
+				GameID: "minecraft-java",
+				Status: "Stopped",
+				Ports:  []model.PortMapping{{Host: 25565, Container: 25565, Protocol: "tcp"}},
+				Params: map[string]string{"MAX_PLAYERS": "20"},
+			}, nil
+		},
+	})
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodGet, "/api/instances/c1/config", nil)
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d", w.Code)
+	}
+
+	var got service.InstanceConfig
+	if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if got.GameID != "minecraft-java" || got.Params["MAX_PLAYERS"] != "20" {
+		t.Fatalf("unexpected response: %+v", got)
+	}
+	if len(got.Ports) != 1 || got.Ports[0].Host != 25565 {
+		t.Fatalf("unexpected ports: %+v", got.Ports)
+	}
+}
+
+func TestGetConfig_InvalidContainerID(t *testing.T) {
+	router := newConfigTestRouter(&mockConfigurator{})
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodGet, "/api/instances/%20/config", nil)
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", w.Code)
+	}
+}
+
+func TestUpdateConfig_Success(t *testing.T) {
+	router := newConfigTestRouter(&mockConfigurator{
+		updateFn: func(_ context.Context, containerID string, params map[string]string, ports []model.PortMapping) (string, error) {
+			if containerID != "c1" {
+				t.Fatalf("unexpected container id: %s", containerID)
+			}
+			if params["MAX_PLAYERS"] != "50" {
+				t.Fatalf("unexpected params: %+v", params)
+			}
+			if len(ports) != 1 || ports[0].Host != 25575 || ports[0].Container != 25565 {
+				t.Fatalf("unexpected ports: %+v", ports)
+			}
+			return "c2", nil
+		},
+	})
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodPut, "/api/instances/c1/config", strings.NewReader(`{"params":{"MAX_PLAYERS":"50"},"ports":[{"host":25575,"container":25565,"protocol":"tcp"}]}`))
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d", w.Code)
+	}
+
+	var got updateConfigResponse
+	if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if got.Status != "success" || got.ContainerID != "c2" {
+		t.Fatalf("unexpected response: %+v", got)
+	}
+}
+
+func TestUpdateConfig_InvalidJSON(t *testing.T) {
+	router := newConfigTestRouter(&mockConfigurator{})
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodPut, "/api/instances/c1/config", strings.NewReader("{bad"))
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", w.Code)
+	}
+}
+
+func TestUpdateConfig_ContainerNotStopped(t *testing.T) {
+	router := newConfigTestRouter(&mockConfigurator{
+		updateFn: func(_ context.Context, _ string, _ map[string]string, _ []model.PortMapping) (string, error) {
+			return "", model.ErrContainerNotStopped
+		},
+	})
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodPut, "/api/instances/c1/config", strings.NewReader(`{"params":{}}`))
+	router.ServeHTTP(w, r)
+
+	if w.Code != http.StatusConflict {
+		t.Fatalf("expected 409, got %d", w.Code)
+	}
+}
diff --git a/backend/internal/api/handlers.go b/backend/internal/api/handlers.go
index dc8b418..7490e16 100644
--- a/backend/internal/api/handlers.go
+++ b/backend/internal/api/handlers.go
@@ -13,7 +13,7 @@ import (
 // InstanceService 定义 API Handler 依赖的业务操作。
 type InstanceService interface {
 	ListInstances(ctx context.Context) ([]model.Instance, error)
-	CreateInstance(ctx context.Context, name, gameID string, params map[string]string) (string, error)
+	CreateInstance(ctx context.Context, name, gameID string, params map[string]string, ports []model.PortMapping) (string, error)
 	StartInstance(ctx context.Context, containerID string) error
 	StopInstance(ctx context.Context, containerID string) error
 	DeleteInstance(ctx context.Context, containerID string) error
@@ -31,9 +31,10 @@ func NewHandler(svc InstanceService) *Handler {
 
 // createRequest 定义创建实例请求体。
 type createRequest struct {
-	Name   string            `json:"name"`
-	GameID string            `json:"game_id"`
-	Params map[string]string `json:"params"`
+	Name   string              `json:"name"`
+	GameID string              `json:"game_id"`
+	Params map[string]string   `json:"params"`
+	Ports  []model.PortMapping `json:"ports"`
 }
 
 // statusResponse 定义通用状态响应体。
@@ -80,7 +81,7 @@ func (h *Handler) CreateInstance(w http.ResponseWriter, r *http.Request) {
 		req.Params = map[string]string{}
 	}
 
-	id, err := h.svc.CreateInstance(r.Context(), req.Name, req.GameID, req.Params)
+	id, err := h.svc.CreateInstance(r.Context(), req.Name, req.GameID, req.Params, req.Ports)
 	if err != nil {
 		writeJSON(w, mapErrorCode(err), statusResponse{Status: "error", Error: err.Error()})
 		return
@@ -159,6 +160,8 @@ func mapErrorCode(err error) int {
 		return http.StatusConflict
 	case errors.Is(err, model.ErrInstanceRunning):
 		return http.StatusConflict
+	case errors.Is(err, model.ErrContainerNotStopped):
+		return http.StatusConflict
 	case errors.Is(err, model.ErrTemplateNotFound):
 		return http.StatusInternalServerError
 	case errors.Is(err, model.ErrTemplateInvalid):
diff --git a/backend/internal/api/handlers_test.go b/backend/internal/api/handlers_test.go
index 55ef8e8..46b5b42 100644
--- a/backend/internal/api/handlers_test.go
+++ b/backend/internal/api/handlers_test.go
@@ -15,7 +15,7 @@ import (
 // mockService 为 Handler 测试实现 InstanceService。
 type mockService struct {
 	listFn   func(ctx context.Context) ([]model.Instance, error)
-	createFn func(ctx context.Context, name, gameID string, params map[string]string) (string, error)
+	createFn func(ctx context.Context, name, gameID string, params map[string]string, ports []model.PortMapping) (string, error)
 	startFn  func(ctx context.Context, id string) error
 	stopFn   func(ctx context.Context, id string) error
 	deleteFn func(ctx context.Context, id string) error
@@ -24,8 +24,13 @@ type mockService struct {
 func (m *mockService) ListInstances(ctx context.Context) ([]model.Instance, error) {
 	return m.listFn(ctx)
 }
-func (m *mockService) CreateInstance(ctx context.Context, name, gameID string, params map[string]string) (string, error) {
-	return m.createFn(ctx, name, gameID, params)
+func (m *mockService) CreateInstance(
+	ctx context.Context,
+	name, gameID string,
+	params map[string]string,
+	ports []model.PortMapping,
+) (string, error) {
+	return m.createFn(ctx, name, gameID, params, ports)
 }
 func (m *mockService) StartInstance(ctx context.Context, id string) error {
 	return m.startFn(ctx, id)
@@ -66,7 +71,7 @@ func newTestRouter(m *mockService) http.Handler {
 			return model.GameTemplate{}, model.ErrGameNotFound
 		},
 	})
-	return NewRouter(h, gh, nil, nil)
+	return NewRouter(h, gh, nil, nil, nil)
 }
 
 // --- GET /api/instances 场景 ---
@@ -123,7 +128,7 @@ func TestGetGames_Success(t *testing.T) {
 			return model.GameTemplate{}, model.ErrGameNotFound
 		},
 	})
-	router := NewRouter(h, gh, nil, nil)
+	router := NewRouter(h, gh, nil, nil, nil)
 
 	w := httptest.NewRecorder()
 	r := httptest.NewRequest(http.MethodGet, "/api/games", nil)
@@ -155,7 +160,7 @@ func TestGetGameTemplate_Success(t *testing.T) {
 			return model.GameTemplate{Image: model.TemplateImage{Name: "itzg/minecraft-server", Tag: "latest"}}, nil
 		},
 	})
-	router := NewRouter(h, gh, nil, nil)
+	router := NewRouter(h, gh, nil, nil, nil)
 
 	w := httptest.NewRecorder()
 	r := httptest.NewRequest(http.MethodGet, "/api/games/minecraft-java/template", nil)
@@ -184,7 +189,7 @@ func TestGetGameTemplate_NotFound(t *testing.T) {
 			return model.GameTemplate{}, model.ErrGameNotFound
 		},
 	})
-	router := NewRouter(h, gh, nil, nil)
+	router := NewRouter(h, gh, nil, nil, nil)
 
 	w := httptest.NewRecorder()
 	r := httptest.NewRequest(http.MethodGet, "/api/games/not-exists/template", nil)
@@ -199,7 +204,7 @@ func TestGetGameTemplate_NotFound(t *testing.T) {
 
 func TestCreateInstance_Success(t *testing.T) {
 	router := newTestRouter(&mockService{
-		createFn: func(_ context.Context, name, gameID string, params map[string]string) (string, error) {
+		createFn: func(_ context.Context, name, gameID string, params map[string]string, ports []model.PortMapping) (string, error) {
 			if name != "test-server" {
 				t.Fatalf("unexpected name: %s", name)
 			}
@@ -209,11 +214,14 @@ func TestCreateInstance_Success(t *testing.T) {
 			if params["SERVER_TYPE"] != "PAPER" {
 				t.Fatalf("unexpected params: %+v", params)
 			}
+			if len(ports) != 1 || ports[0].Host != 25575 || ports[0].Container != 25565 || ports[0].Protocol != "tcp" {
+				t.Fatalf("unexpected ports: %+v", ports)
+			}
 			return "abc123", nil
 		},
 	})
 
-	body := `{"name":"test-server","game_id":"minecraft-java","params":{"SERVER_TYPE":"PAPER"}}`
+	body := `{"name":"test-server","game_id":"minecraft-java","params":{"SERVER_TYPE":"PAPER"},"ports":[{"host":25575,"container":25565,"protocol":"tcp"}]}`
 	w := httptest.NewRecorder()
 	r := httptest.NewRequest(http.MethodPost, "/api/instances", strings.NewReader(body))
 	router.ServeHTTP(w, r)
@@ -269,7 +277,7 @@ func TestCreateInstance_EmptyGameID(t *testing.T) {
 
 func TestCreateInstance_NameConflict(t *testing.T) {
 	router := newTestRouter(&mockService{
-		createFn: func(_ context.Context, _, _ string, _ map[string]string) (string, error) {
+		createFn: func(_ context.Context, _, _ string, _ map[string]string, _ []model.PortMapping) (string, error) {
 			return "", model.ErrNameExists
 		},
 	})
@@ -285,7 +293,7 @@ func TestCreateInstance_NameConflict(t *testing.T) {
 
 func TestCreateInstance_GameNotFound(t *testing.T) {
 	router := newTestRouter(&mockService{
-		createFn: func(_ context.Context, _, _ string, _ map[string]string) (string, error) {
+		createFn: func(_ context.Context, _, _ string, _ map[string]string, _ []model.PortMapping) (string, error) {
 			return "", model.ErrGameNotFound
 		},
 	})
@@ -301,7 +309,7 @@ func TestCreateInstance_GameNotFound(t *testing.T) {
 
 func TestCreateInstance_InvalidParams(t *testing.T) {
 	router := newTestRouter(&mockService{
-		createFn: func(_ context.Context, _, _ string, _ map[string]string) (string, error) {
+		createFn: func(_ context.Context, _, _ string, _ map[string]string, _ []model.PortMapping) (string, error) {
 			return "", fmtWrap(model.ErrInvalidParams)
 		},
 	})
@@ -440,3 +448,9 @@ func TestMapErrorCode_InvalidParamsWrapped(t *testing.T) {
 		t.Fatal("expected wrapped error to match ErrInvalidParams")
 	}
 }
+
+func TestMapErrorCode_ContainerNotStopped(t *testing.T) {
+	if got := mapErrorCode(model.ErrContainerNotStopped); got != http.StatusConflict {
+		t.Fatalf("expected 409 for container-not-stopped, got %d", got)
+	}
+}
diff --git a/backend/internal/api/router.go b/backend/internal/api/router.go
index 4c45b3b..2795008 100644
--- a/backend/internal/api/router.go
+++ b/backend/internal/api/router.go
@@ -6,7 +6,7 @@ import (
 )
 
 // NewRouter 注册 API 路由并包装中间件。
-func NewRouter(h *Handler, games *GameHandler, ws *WsHandler, console *ConsoleHandler) http.Handler {
+func NewRouter(h *Handler, games *GameHandler, ws *WsHandler, console *ConsoleHandler, config *ConfigHandler) http.Handler {
 	mux := http.NewServeMux()
 
 	mux.HandleFunc("GET /api/instances", h.GetInstances)
@@ -14,6 +14,10 @@ func NewRouter(h *Handler, games *GameHandler, ws *WsHandler, console *ConsoleHa
 	mux.HandleFunc("POST /api/instances/{id}/start", h.StartInstance)
 	mux.HandleFunc("POST /api/instances/{id}/stop", h.StopInstance)
 	mux.HandleFunc("DELETE /api/instances/{id}", h.DeleteInstance)
+	if config != nil {
+		mux.HandleFunc("GET /api/instances/{id}/config", config.HandleGetConfig)
+		mux.HandleFunc("PUT /api/instances/{id}/config", config.HandleUpdateConfig)
+	}
 	if ws != nil {
 		mux.HandleFunc("GET /api/ws/events", ws.HandleEvents)
 	}
@@ -37,7 +41,7 @@ func withCORS(next http.Handler) http.Handler {
 		}
 
 		w.Header().Set("Access-Control-Allow-Origin", "*")
-		w.Header().Set("Access-Control-Allow-Methods", "GET,POST,DELETE,OPTIONS")
+		w.Header().Set("Access-Control-Allow-Methods", "GET,POST,PUT,DELETE,OPTIONS")
 		w.Header().Set("Access-Control-Allow-Headers", "Content-Type")
 
 		if r.Method == http.MethodOptions {
diff --git a/backend/internal/model/errors.go b/backend/internal/model/errors.go
index 24c2d79..1c05920 100644
--- a/backend/internal/model/errors.go
+++ b/backend/internal/model/errors.go
@@ -19,3 +19,6 @@ var ErrTemplateInvalid = errors.New("invalid template")
 
 // ErrInvalidParams 表示传入了不受模板定义约束的参数。
 var ErrInvalidParams = errors.New("invalid params")
+
+// ErrContainerNotStopped 表示容器必须先停止，才能执行配置更新。
+var ErrContainerNotStopped = errors.New("container must be stopped to update config")
diff --git a/backend/internal/model/instance.go b/backend/internal/model/instance.go
index 6adb1cc..77689db 100644
--- a/backend/internal/model/instance.go
+++ b/backend/internal/model/instance.go
@@ -4,5 +4,6 @@ package model
 type Instance struct {
 	ContainerID string `json:"container_id"`
 	Name        string `json:"name"`
+	GameID      string `json:"game_id"`
 	Status      string `json:"status"`
 }
diff --git a/backend/internal/service/docker_service.go b/backend/internal/service/docker_service.go
index 154c895..5769bb2 100644
--- a/backend/internal/service/docker_service.go
+++ b/backend/internal/service/docker_service.go
@@ -10,8 +10,9 @@ import (
 	"github.com/docker/docker/api/types/container"
 	"github.com/docker/docker/api/types/filters"
 	"github.com/docker/docker/api/types/image"
-	"github.com/docker/docker/client"
+	"github.com/docker/docker/api/types/network"
 	"github.com/docker/go-connections/nat"
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 
 	"minedock/backend/internal/model"
 )
@@ -23,6 +24,25 @@ const (
 	gameIDLabelKey    = "minedock.game_id"
 )
 
+// dockerClient 定义 DockerService 依赖的 Docker API。
+type dockerClient interface {
+	ContainerCreate(
+		ctx context.Context,
+		config *container.Config,
+		hostConfig *container.HostConfig,
+		networkingConfig *network.NetworkingConfig,
+		platform *ocispec.Platform,
+		containerName string,
+	) (container.CreateResponse, error)
+	ContainerInspect(ctx context.Context, containerID string) (container.InspectResponse, error)
+	ContainerRemove(ctx context.Context, containerID string, options container.RemoveOptions) error
+	ContainerStart(ctx context.Context, containerID string, options container.StartOptions) error
+	ContainerStop(ctx context.Context, containerID string, options container.StopOptions) error
+	ContainerList(ctx context.Context, options container.ListOptions) ([]container.Summary, error)
+	ImageList(ctx context.Context, options image.ListOptions) ([]image.Summary, error)
+	ImagePull(ctx context.Context, ref string, options image.PullOptions) (io.ReadCloser, error)
+}
+
 // InstanceStore 定义 DockerService 依赖的持久化操作。
 type InstanceStore interface {
 	Save(ctx context.Context, inst model.Instance) error
@@ -36,21 +56,34 @@ type GameRegistry interface {
 	GetTemplate(ctx context.Context, id string) (model.GameTemplate, error)
 }
 
+// InstanceConfig 描述容器当前生效的可编辑配置。
+type InstanceConfig struct {
+	GameID string              `json:"game_id"`
+	Status string              `json:"status"`
+	Ports  []model.PortMapping `json:"ports"`
+	Params map[string]string   `json:"params"`
+}
+
 // DockerService 封装容器管理相关业务逻辑。
 type DockerService struct {
-	cli      *client.Client
+	cli      dockerClient
 	store    InstanceStore
 	registry GameRegistry
 }
 
 // NewDockerService 使用依赖项创建 DockerService。
-func NewDockerService(cli *client.Client, s InstanceStore, registry GameRegistry) *DockerService {
+func NewDockerService(cli dockerClient, s InstanceStore, registry GameRegistry) *DockerService {
 	return &DockerService{cli: cli, store: s, registry: registry}
 }
 
 // CreateInstance 创建托管容器并持久化实例元数据。
 // TODO: 让 Docker 创建与 SQLite 保存具备原子性。
-func (s *DockerService) CreateInstance(ctx context.Context, name, gameID string, params map[string]string) (string, error) {
+func (s *DockerService) CreateInstance(
+	ctx context.Context,
+	name, gameID string,
+	params map[string]string,
+	ports []model.PortMapping,
+) (string, error) {
 	if s.registry == nil {
 		return "", fmt.Errorf("game registry is not configured")
 	}
@@ -79,7 +112,12 @@ func (s *DockerService) CreateInstance(ctx context.Context, name, gameID string,
 		return "", err
 	}
 
-	exposedPorts, portBindings := buildPortBindings(tpl.Container.Ports)
+	resolvedPorts, err := resolveConfigPorts(tpl.Container.Ports, nil, ports)
+	if err != nil {
+		return "", err
+	}
+
+	exposedPorts, portBindings := buildPortBindings(resolvedPorts)
 	cmd := []string(nil)
 	if len(tpl.Container.Command) > 0 {
 		cmd = append(cmd, tpl.Container.Command...)
@@ -110,7 +148,7 @@ func (s *DockerService) CreateInstance(ctx context.Context, name, gameID string,
 		return "", fmt.Errorf("create container: %w", err)
 	}
 
-	inst := model.Instance{ContainerID: resp.ID, Name: name, Status: "Stopped"}
+	inst := model.Instance{ContainerID: resp.ID, Name: name, GameID: game.ID, Status: "Stopped"}
 	if err := s.store.Save(ctx, inst); err != nil {
 		// 说明：请求上下文取消时，清理逻辑会使用独立上下文做尽力回收。
 		_ = s.cli.ContainerRemove(context.Background(), resp.ID, container.RemoveOptions{Force: true})
@@ -120,6 +158,163 @@ func (s *DockerService) CreateInstance(ctx context.Context, name, gameID string,
 	return resp.ID, nil
 }
 
+// GetInstanceConfig 读取容器当前生效的用户可调参数。
+func (s *DockerService) GetInstanceConfig(ctx context.Context, containerID string) (*InstanceConfig, error) {
+	if s.registry == nil {
+		return nil, fmt.Errorf("game registry is not configured")
+	}
+
+	inspect, err := s.cli.ContainerInspect(ctx, containerID)
+	if err != nil {
+		return nil, fmt.Errorf("inspect container: %w", err)
+	}
+	if inspect.Config == nil {
+		return nil, fmt.Errorf("inspect container config is empty")
+	}
+
+	gameID := strings.TrimSpace(inspect.Config.Labels[gameIDLabelKey])
+	if gameID == "" {
+		return nil, fmt.Errorf("container %q is missing %s label", containerID, gameIDLabelKey)
+	}
+
+	tpl, err := s.registry.GetTemplate(ctx, gameID)
+	if err != nil {
+		return nil, err
+	}
+
+	ports, err := resolveConfigPorts(tpl.Container.Ports, inspect.HostConfig, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	containerEnv := dockerEnvToMap(inspect.Config.Env)
+	params := make(map[string]string, len(tpl.Params))
+	for _, param := range tpl.Params {
+		envKey := strings.TrimSpace(param.EnvVar)
+		if envKey == "" {
+			envKey = param.Key
+		}
+
+		value, ok := containerEnv[envKey]
+		if !ok {
+			if defaultValue, hasDefault := stringifyTemplateDefault(param); hasDefault {
+				value = defaultValue
+			}
+		}
+
+		params[param.Key] = value
+	}
+
+	return &InstanceConfig{
+		GameID: gameID,
+		Status: instanceStatusFromState(inspect.State),
+		Ports:  ports,
+		Params: params,
+	}, nil
+}
+
+// UpdateInstanceConfig 通过重建容器应用新的用户参数。
+func (s *DockerService) UpdateInstanceConfig(
+	ctx context.Context,
+	containerID string,
+	newParams map[string]string,
+	newPorts []model.PortMapping,
+) (string, error) {
+	if s.registry == nil {
+		return "", fmt.Errorf("game registry is not configured")
+	}
+
+	inspect, err := s.cli.ContainerInspect(ctx, containerID)
+	if err != nil {
+		return "", fmt.Errorf("inspect container: %w", err)
+	}
+	if inspect.Config == nil {
+		return "", fmt.Errorf("inspect container config is empty")
+	}
+	if inspect.State != nil && inspect.State.Running {
+		return "", model.ErrContainerNotStopped
+	}
+
+	gameID := strings.TrimSpace(inspect.Config.Labels[gameIDLabelKey])
+	if gameID == "" {
+		return "", fmt.Errorf("container %q is missing %s label", containerID, gameIDLabelKey)
+	}
+
+	tpl, err := s.registry.GetTemplate(ctx, gameID)
+	if err != nil {
+		return "", err
+	}
+
+	env, err := mergeTemplateEnv(tpl, newParams)
+	if err != nil {
+		return "", err
+	}
+
+	ports, err := resolveConfigPorts(tpl.Container.Ports, inspect.HostConfig, newPorts)
+	if err != nil {
+		return "", err
+	}
+
+	exposedPorts, portBindings := buildPortBindings(ports)
+
+	containerName := strings.TrimPrefix(inspect.Name, "/")
+	instanceName := strings.TrimSpace(inspect.Config.Labels[nameLabelKey])
+	if instanceName == "" {
+		instanceName = containerName
+	}
+	if instanceName == "" {
+		instanceName = containerID
+	}
+
+	hostConfig := &container.HostConfig{}
+	if inspect.HostConfig != nil {
+		hostConfig.Binds = append([]string(nil), inspect.HostConfig.Binds...)
+	}
+	hostConfig.PortBindings = portBindings
+
+	labels := copyStringMap(inspect.Config.Labels)
+	labels[managedLabelKey] = managedLabelValue
+	labels[nameLabelKey] = instanceName
+	labels[gameIDLabelKey] = gameID
+
+	if err := s.cli.ContainerRemove(ctx, containerID, container.RemoveOptions{Force: false}); err != nil {
+		return "", fmt.Errorf("remove old container: %w", err)
+	}
+
+	resp, err := s.cli.ContainerCreate(ctx, &container.Config{
+		Image:        inspect.Config.Image,
+		Cmd:          append([]string(nil), inspect.Config.Cmd...),
+		Env:          mapToDockerEnv(env),
+		ExposedPorts: exposedPorts,
+		Tty:          inspect.Config.Tty,
+		AttachStdin:  inspect.Config.AttachStdin,
+		AttachStdout: inspect.Config.AttachStdout,
+		AttachStderr: inspect.Config.AttachStderr,
+		OpenStdin:    inspect.Config.OpenStdin,
+		StdinOnce:    inspect.Config.StdinOnce,
+		Labels:       labels,
+	}, hostConfig, nil, nil, containerName)
+	if err != nil {
+		return "", fmt.Errorf("create replacement container: %w", err)
+	}
+
+	newInst := model.Instance{
+		ContainerID: resp.ID,
+		Name:        instanceName,
+		GameID:      gameID,
+		Status:      "Stopped",
+	}
+
+	if err := s.store.Delete(ctx, containerID); err != nil {
+		return "", fmt.Errorf("delete old instance record: %w", err)
+	}
+	if err := s.store.Save(ctx, newInst); err != nil {
+		return "", fmt.Errorf("save new instance record: %w", err)
+	}
+
+	return resp.ID, nil
+}
+
 func mergeTemplateEnv(tpl model.GameTemplate, params map[string]string) (map[string]string, error) {
 	merged := make(map[string]string, len(tpl.Container.Env)+len(tpl.Params))
 	for key, value := range tpl.Container.Env {
@@ -393,6 +588,7 @@ func (s *DockerService) ListInstances(ctx context.Context) ([]model.Instance, er
 		if strings.TrimSpace(name) == "" && len(c.Names) > 0 {
 			name = strings.TrimPrefix(c.Names[0], "/")
 		}
+		gameID := strings.TrimSpace(c.Labels[gameIDLabelKey])
 		status := "Stopped"
 		if strings.EqualFold(c.State, "running") {
 			status = "Running"
@@ -400,6 +596,7 @@ func (s *DockerService) ListInstances(ctx context.Context) ([]model.Instance, er
 		inst := model.Instance{
 			ContainerID: c.ID,
 			Name:        name,
+			GameID:      gameID,
 			Status:      status,
 		}
 		// 说明：当前 Save 为尽力而为，避免影响列表返回。
@@ -438,7 +635,7 @@ func (s *DockerService) readInstance(ctx context.Context, containerID string, fa
 	if err != nil {
 		return model.Instance{}, fmt.Errorf("read instance: %w", err)
 	}
-	if ok {
+	if ok && strings.TrimSpace(inst.GameID) != "" {
 		// 说明：命中存储后仍会应用调用方传入的兜底状态。
 		inst.Status = fallbackStatus
 		return inst, nil
@@ -450,12 +647,17 @@ func (s *DockerService) readInstance(ctx context.Context, containerID string, fa
 	}
 
 	name := ""
+	gameID := ""
 	if inspect.Config != nil && inspect.Config.Labels != nil {
 		name = strings.TrimSpace(inspect.Config.Labels[nameLabelKey])
+		gameID = strings.TrimSpace(inspect.Config.Labels[gameIDLabelKey])
 	}
 	if name == "" {
 		name = strings.TrimPrefix(inspect.Name, "/")
 	}
+	if gameID == "" && ok {
+		gameID = strings.TrimSpace(inst.GameID)
+	}
 
 	status := fallbackStatus
 	if inspect.State != nil {
@@ -467,7 +669,7 @@ func (s *DockerService) readInstance(ctx context.Context, containerID string, fa
 		}
 	}
 
-	return model.Instance{ContainerID: containerID, Name: name, Status: status}, nil
+	return model.Instance{ContainerID: containerID, Name: name, GameID: gameID, Status: status}, nil
 }
 
 // ensureImage 确保本地存在目标镜像，缺失时自动拉取。
@@ -493,3 +695,128 @@ func (s *DockerService) ensureImage(ctx context.Context, imageName string) error
 	_, _ = io.Copy(io.Discard, rc)
 	return nil
 }
+
+func dockerEnvToMap(env []string) map[string]string {
+	out := make(map[string]string, len(env))
+	for _, item := range env {
+		key, value, ok := strings.Cut(item, "=")
+		if !ok {
+			continue
+		}
+		key = strings.TrimSpace(key)
+		if key == "" {
+			continue
+		}
+		out[key] = value
+	}
+	return out
+}
+
+func instanceStatusFromState(state *container.State) string {
+	if state != nil && state.Running {
+		return "Running"
+	}
+	return "Stopped"
+}
+
+func copyStringMap(in map[string]string) map[string]string {
+	out := make(map[string]string, len(in))
+	for key, value := range in {
+		out[key] = value
+	}
+	return out
+}
+
+func resolveConfigPorts(
+	templatePorts []model.PortMapping,
+	hostConfig *container.HostConfig,
+	requestedPorts []model.PortMapping,
+) ([]model.PortMapping, error) {
+	if len(templatePorts) == 0 {
+		return []model.PortMapping{}, nil
+	}
+
+	currentHosts := mapCurrentHostPorts(nil)
+	if hostConfig != nil {
+		currentHosts = mapCurrentHostPorts(hostConfig.PortBindings)
+	}
+
+	requestedHosts := make(map[string]int, len(requestedPorts))
+	for _, p := range requestedPorts {
+		if p.Container <= 0 || p.Host <= 0 {
+			return nil, fmt.Errorf("invalid port mapping: %w", model.ErrInvalidParams)
+		}
+		protocol := normalizePortProtocol(p.Protocol)
+		key := portConfigKey(p.Container, protocol)
+		if _, exists := requestedHosts[key]; exists {
+			return nil, fmt.Errorf("duplicate port mapping %q: %w", key, model.ErrInvalidParams)
+		}
+		requestedHosts[key] = p.Host
+	}
+
+	resolved := make([]model.PortMapping, 0, len(templatePorts))
+	for _, p := range templatePorts {
+		if p.Container <= 0 || p.Host <= 0 {
+			return nil, fmt.Errorf("template port is invalid: %w", model.ErrTemplateInvalid)
+		}
+
+		protocol := normalizePortProtocol(p.Protocol)
+		key := portConfigKey(p.Container, protocol)
+
+		host := p.Host
+		if currentHost, ok := currentHosts[key]; ok {
+			host = currentHost
+		}
+		if requestedHost, ok := requestedHosts[key]; ok {
+			host = requestedHost
+			delete(requestedHosts, key)
+		}
+
+		resolved = append(resolved, model.PortMapping{
+			Host:      host,
+			Container: p.Container,
+			Protocol:  protocol,
+		})
+	}
+
+	if len(requestedHosts) > 0 {
+		return nil, fmt.Errorf("unknown port mapping: %w", model.ErrInvalidParams)
+	}
+
+	return resolved, nil
+}
+
+func mapCurrentHostPorts(portBindings nat.PortMap) map[string]int {
+	out := make(map[string]int, len(portBindings))
+	for containerPort, bindings := range portBindings {
+		if len(bindings) == 0 {
+			continue
+		}
+
+		hostPort, err := strconv.Atoi(strings.TrimSpace(bindings[0].HostPort))
+		if err != nil || hostPort <= 0 {
+			continue
+		}
+
+		containerValue, err := strconv.Atoi(containerPort.Port())
+		if err != nil || containerValue <= 0 {
+			continue
+		}
+
+		key := portConfigKey(containerValue, normalizePortProtocol(containerPort.Proto()))
+		out[key] = hostPort
+	}
+	return out
+}
+
+func normalizePortProtocol(protocol string) string {
+	normalized := strings.ToLower(strings.TrimSpace(protocol))
+	if normalized == "" {
+		return "tcp"
+	}
+	return normalized
+}
+
+func portConfigKey(containerPort int, protocol string) string {
+	return fmt.Sprintf("%d/%s", containerPort, normalizePortProtocol(protocol))
+}
diff --git a/backend/internal/service/docker_service_test.go b/backend/internal/service/docker_service_test.go
index 81dd97d..3817896 100644
--- a/backend/internal/service/docker_service_test.go
+++ b/backend/internal/service/docker_service_test.go
@@ -1,9 +1,19 @@
 package service
 
 import (
+	"context"
+	"errors"
+	"io"
+	"slices"
+	"strings"
 	"testing"
 
 	"github.com/docker/go-connections/nat"
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+
+	"github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/api/types/image"
+	"github.com/docker/docker/api/types/network"
 
 	"minedock/backend/internal/model"
 )
@@ -145,3 +155,407 @@ func TestBuildVolumeBinds(t *testing.T) {
 		}
 	})
 }
+
+type fakeDockerClient struct {
+	inspectResp container.InspectResponse
+	inspectErr  error
+
+	createResp   container.CreateResponse
+	createErr    error
+	createCfg    *container.Config
+	createHost   *container.HostConfig
+	createName   string
+	removeErr    error
+	removedIDs   []string
+	listResp     []container.Summary
+	listErr      error
+	startErr     error
+	stopErr      error
+	imageList    []image.Summary
+	imageListErr error
+	imagePullErr error
+}
+
+func (f *fakeDockerClient) ContainerCreate(
+	_ context.Context,
+	config *container.Config,
+	hostConfig *container.HostConfig,
+	_ *network.NetworkingConfig,
+	_ *ocispec.Platform,
+	containerName string,
+) (container.CreateResponse, error) {
+	f.createCfg = config
+	f.createHost = hostConfig
+	f.createName = containerName
+	if f.createErr != nil {
+		return container.CreateResponse{}, f.createErr
+	}
+	if f.createResp.ID == "" {
+		f.createResp.ID = "new-container-id"
+	}
+	return f.createResp, nil
+}
+
+func (f *fakeDockerClient) ContainerInspect(_ context.Context, _ string) (container.InspectResponse, error) {
+	if f.inspectErr != nil {
+		return container.InspectResponse{}, f.inspectErr
+	}
+	return f.inspectResp, nil
+}
+
+func (f *fakeDockerClient) ContainerRemove(_ context.Context, containerID string, _ container.RemoveOptions) error {
+	f.removedIDs = append(f.removedIDs, containerID)
+	if f.removeErr != nil {
+		return f.removeErr
+	}
+	return nil
+}
+
+func (f *fakeDockerClient) ContainerStart(_ context.Context, _ string, _ container.StartOptions) error {
+	return f.startErr
+}
+
+func (f *fakeDockerClient) ContainerStop(_ context.Context, _ string, _ container.StopOptions) error {
+	return f.stopErr
+}
+
+func (f *fakeDockerClient) ContainerList(_ context.Context, _ container.ListOptions) ([]container.Summary, error) {
+	if f.listErr != nil {
+		return nil, f.listErr
+	}
+	return f.listResp, nil
+}
+
+func (f *fakeDockerClient) ImageList(_ context.Context, _ image.ListOptions) ([]image.Summary, error) {
+	if f.imageListErr != nil {
+		return nil, f.imageListErr
+	}
+	return f.imageList, nil
+}
+
+func (f *fakeDockerClient) ImagePull(_ context.Context, _ string, _ image.PullOptions) (io.ReadCloser, error) {
+	if f.imagePullErr != nil {
+		return nil, f.imagePullErr
+	}
+	return io.NopCloser(strings.NewReader("")), nil
+}
+
+type fakeInstanceStore struct {
+	instances map[string]model.Instance
+
+	saveErr   error
+	getErr    error
+	deleteErr error
+}
+
+func newFakeInstanceStore(initial ...model.Instance) *fakeInstanceStore {
+	instances := make(map[string]model.Instance, len(initial))
+	for _, inst := range initial {
+		instances[inst.ContainerID] = inst
+	}
+	return &fakeInstanceStore{instances: instances}
+}
+
+func (f *fakeInstanceStore) Save(_ context.Context, inst model.Instance) error {
+	if f.saveErr != nil {
+		return f.saveErr
+	}
+	if f.instances == nil {
+		f.instances = map[string]model.Instance{}
+	}
+	f.instances[inst.ContainerID] = inst
+	return nil
+}
+
+func (f *fakeInstanceStore) Get(_ context.Context, containerID string) (model.Instance, bool, error) {
+	if f.getErr != nil {
+		return model.Instance{}, false, f.getErr
+	}
+	inst, ok := f.instances[containerID]
+	return inst, ok, nil
+}
+
+func (f *fakeInstanceStore) Delete(_ context.Context, containerID string) error {
+	if f.deleteErr != nil {
+		return f.deleteErr
+	}
+	delete(f.instances, containerID)
+	return nil
+}
+
+type fakeRegistry struct {
+	game     model.Game
+	gameErr  error
+	template model.GameTemplate
+	tplErr   error
+}
+
+func (f *fakeRegistry) GetGame(_ context.Context, _ string) (model.Game, error) {
+	if f.gameErr != nil {
+		return model.Game{}, f.gameErr
+	}
+	return f.game, nil
+}
+
+func (f *fakeRegistry) GetTemplate(_ context.Context, _ string) (model.GameTemplate, error) {
+	if f.tplErr != nil {
+		return model.GameTemplate{}, f.tplErr
+	}
+	return f.template, nil
+}
+
+func TestGetInstanceConfig_Success(t *testing.T) {
+	port, err := nat.NewPort("tcp", "25565")
+	if err != nil {
+		t.Fatalf("new port: %v", err)
+	}
+
+	cli := &fakeDockerClient{
+		inspectResp: container.InspectResponse{
+			ContainerJSONBase: &container.ContainerJSONBase{
+				State:      &container.State{Running: true},
+				HostConfig: &container.HostConfig{PortBindings: nat.PortMap{port: []nat.PortBinding{{HostPort: "25575"}}}},
+			},
+			Config: &container.Config{
+				Labels: map[string]string{
+					gameIDLabelKey: "minecraft-java",
+				},
+				Env: []string{
+					"EULA=TRUE",
+					"TYPE=FABRIC",
+					"MAX_PLAYERS=50",
+				},
+			},
+		},
+	}
+	registry := &fakeRegistry{
+		template: model.GameTemplate{
+			Container: model.ContainerConfig{
+				Ports: []model.PortMapping{{Host: 25565, Container: 25565, Protocol: "tcp"}},
+				Env:   map[string]string{"EULA": "TRUE"},
+			},
+			Params: []model.TemplateParam{
+				{Key: "SERVER_TYPE", Type: "select", Default: "PAPER", EnvVar: "TYPE", Options: []model.ParamOption{{Value: "PAPER", Label: "Paper"}, {Value: "FABRIC", Label: "Fabric"}}},
+				{Key: "MAX_PLAYERS", Type: "number", Default: 20},
+			},
+		},
+	}
+
+	svc := NewDockerService(cli, newFakeInstanceStore(), registry)
+
+	cfg, err := svc.GetInstanceConfig(context.Background(), "c1")
+	if err != nil {
+		t.Fatalf("GetInstanceConfig: %v", err)
+	}
+	if cfg.GameID != "minecraft-java" {
+		t.Fatalf("unexpected game id: %s", cfg.GameID)
+	}
+	if cfg.Status != "Running" {
+		t.Fatalf("unexpected status: %s", cfg.Status)
+	}
+	if cfg.Params["SERVER_TYPE"] != "FABRIC" {
+		t.Fatalf("unexpected SERVER_TYPE: %s", cfg.Params["SERVER_TYPE"])
+	}
+	if cfg.Params["MAX_PLAYERS"] != "50" {
+		t.Fatalf("unexpected MAX_PLAYERS: %s", cfg.Params["MAX_PLAYERS"])
+	}
+	if len(cfg.Ports) != 1 {
+		t.Fatalf("expected 1 port mapping, got %+v", cfg.Ports)
+	}
+	if cfg.Ports[0].Host != 25575 || cfg.Ports[0].Container != 25565 || cfg.Ports[0].Protocol != "tcp" {
+		t.Fatalf("unexpected config ports: %+v", cfg.Ports)
+	}
+}
+
+func TestUpdateInstanceConfig_RejectRunning(t *testing.T) {
+	cli := &fakeDockerClient{
+		inspectResp: container.InspectResponse{
+			ContainerJSONBase: &container.ContainerJSONBase{State: &container.State{Running: true}},
+			Config: &container.Config{Labels: map[string]string{
+				gameIDLabelKey: "minecraft-java",
+			}},
+		},
+	}
+
+	svc := NewDockerService(cli, newFakeInstanceStore(), &fakeRegistry{})
+
+	_, err := svc.UpdateInstanceConfig(context.Background(), "c1", map[string]string{"MAX_PLAYERS": "50"}, nil)
+	if !errors.Is(err, model.ErrContainerNotStopped) {
+		t.Fatalf("expected ErrContainerNotStopped, got %v", err)
+	}
+}
+
+func TestUpdateInstanceConfig_Success(t *testing.T) {
+	port, err := nat.NewPort("tcp", "25565")
+	if err != nil {
+		t.Fatalf("new port: %v", err)
+	}
+
+	cli := &fakeDockerClient{
+		inspectResp: container.InspectResponse{
+			ContainerJSONBase: &container.ContainerJSONBase{
+				Name:       "/docker-name",
+				HostConfig: &container.HostConfig{Binds: []string{"minedock-server-data:/data"}, PortBindings: nat.PortMap{port: []nat.PortBinding{{HostPort: "25565"}}}},
+				State:      &container.State{Running: false},
+			},
+			Config: &container.Config{
+				Image:        "itzg/minecraft-server:latest",
+				Cmd:          []string{"/start"},
+				Env:          []string{"EULA=TRUE", "TYPE=PAPER", "MAX_PLAYERS=20"},
+				ExposedPorts: nat.PortSet{port: struct{}{}},
+				Labels: map[string]string{
+					managedLabelKey: "true",
+					nameLabelKey:    "server-1",
+					gameIDLabelKey:  "minecraft-java",
+				},
+			},
+		},
+		createResp: container.CreateResponse{ID: "new-id"},
+	}
+	registry := &fakeRegistry{
+		template: model.GameTemplate{
+			Container: model.ContainerConfig{
+				Ports: []model.PortMapping{{Host: 25565, Container: 25565, Protocol: "tcp"}},
+				Env:   map[string]string{"EULA": "TRUE"},
+			},
+			Params: []model.TemplateParam{
+				{Key: "SERVER_TYPE", Type: "select", Default: "PAPER", EnvVar: "TYPE", Options: []model.ParamOption{{Value: "PAPER", Label: "Paper"}, {Value: "FABRIC", Label: "Fabric"}}},
+				{Key: "MAX_PLAYERS", Type: "number", Default: 20},
+			},
+		},
+	}
+	store := newFakeInstanceStore(model.Instance{ContainerID: "old-id", Name: "server-1", GameID: "minecraft-java", Status: "Stopped"})
+
+	svc := NewDockerService(cli, store, registry)
+
+	newID, err := svc.UpdateInstanceConfig(context.Background(), "old-id", map[string]string{
+		"SERVER_TYPE": "FABRIC",
+		"MAX_PLAYERS": "50",
+	}, []model.PortMapping{{
+		Host:      25575,
+		Container: 25565,
+		Protocol:  "tcp",
+	}})
+	if err != nil {
+		t.Fatalf("UpdateInstanceConfig: %v", err)
+	}
+	if newID != "new-id" {
+		t.Fatalf("unexpected new container id: %s", newID)
+	}
+	if !slices.Contains(cli.removedIDs, "old-id") {
+		t.Fatalf("expected old container removed, got %+v", cli.removedIDs)
+	}
+	if cli.createName != "docker-name" {
+		t.Fatalf("unexpected recreated docker name: %s", cli.createName)
+	}
+
+	env := dockerEnvToMap(cli.createCfg.Env)
+	if env["TYPE"] != "FABRIC" {
+		t.Fatalf("unexpected TYPE env: %s", env["TYPE"])
+	}
+	if env["MAX_PLAYERS"] != "50" {
+		t.Fatalf("unexpected MAX_PLAYERS env: %s", env["MAX_PLAYERS"])
+	}
+	if env["EULA"] != "TRUE" {
+		t.Fatalf("unexpected EULA env: %s", env["EULA"])
+	}
+
+	bindings := cli.createHost.PortBindings[port]
+	if len(bindings) != 1 || bindings[0].HostPort != "25575" {
+		t.Fatalf("unexpected recreated host bindings: %+v", cli.createHost.PortBindings)
+	}
+	if _, ok := cli.createCfg.ExposedPorts[port]; !ok {
+		t.Fatalf("expected exposed port %q, got %+v", port, cli.createCfg.ExposedPorts)
+	}
+
+	if _, ok := store.instances["old-id"]; ok {
+		t.Fatal("expected old instance to be deleted from store")
+	}
+	newInst, ok := store.instances["new-id"]
+	if !ok {
+		t.Fatal("expected new instance in store")
+	}
+	if newInst.GameID != "minecraft-java" || newInst.Name != "server-1" {
+		t.Fatalf("unexpected stored instance: %+v", newInst)
+	}
+}
+
+func TestUpdateInstanceConfig_InvalidParams(t *testing.T) {
+	cli := &fakeDockerClient{
+		inspectResp: container.InspectResponse{
+			ContainerJSONBase: &container.ContainerJSONBase{State: &container.State{Running: false}},
+			Config: &container.Config{
+				Labels: map[string]string{gameIDLabelKey: "minecraft-java", nameLabelKey: "server-1"},
+			},
+		},
+	}
+	registry := &fakeRegistry{
+		template: model.GameTemplate{
+			Params: []model.TemplateParam{{Key: "MAX_PLAYERS", Type: "number", Default: 20}},
+		},
+	}
+
+	svc := NewDockerService(cli, newFakeInstanceStore(), registry)
+
+	_, err := svc.UpdateInstanceConfig(context.Background(), "c1", map[string]string{"MAX_PLAYERS": "NaN??"}, nil)
+	if !errors.Is(err, model.ErrInvalidParams) {
+		t.Fatalf("expected ErrInvalidParams, got %v", err)
+	}
+}
+
+func TestUpdateInstanceConfig_InvalidPorts(t *testing.T) {
+	cli := &fakeDockerClient{
+		inspectResp: container.InspectResponse{
+			ContainerJSONBase: &container.ContainerJSONBase{State: &container.State{Running: false}},
+			Config: &container.Config{
+				Labels: map[string]string{gameIDLabelKey: "minecraft-java", nameLabelKey: "server-1"},
+			},
+		},
+	}
+	registry := &fakeRegistry{
+		template: model.GameTemplate{
+			Container: model.ContainerConfig{Ports: []model.PortMapping{{Host: 25565, Container: 25565, Protocol: "tcp"}}, Env: map[string]string{}},
+		},
+	}
+
+	svc := NewDockerService(cli, newFakeInstanceStore(), registry)
+
+	_, err := svc.UpdateInstanceConfig(context.Background(), "c1", map[string]string{}, []model.PortMapping{{
+		Host:      19132,
+		Container: 19132,
+		Protocol:  "udp",
+	}})
+	if !errors.Is(err, model.ErrInvalidParams) {
+		t.Fatalf("expected ErrInvalidParams for unknown ports, got %v", err)
+	}
+}
+
+func TestListInstances_IncludesGameID(t *testing.T) {
+	cli := &fakeDockerClient{
+		listResp: []container.Summary{{
+			ID:    "c1",
+			State: "running",
+			Names: []string{"/server-1"},
+			Labels: map[string]string{
+				nameLabelKey:   "server-1",
+				gameIDLabelKey: "minecraft-java",
+			},
+		}},
+	}
+	store := newFakeInstanceStore()
+	svc := NewDockerService(cli, store, &fakeRegistry{})
+
+	instances, err := svc.ListInstances(context.Background())
+	if err != nil {
+		t.Fatalf("ListInstances: %v", err)
+	}
+	if len(instances) != 1 {
+		t.Fatalf("expected 1 instance, got %d", len(instances))
+	}
+	if instances[0].GameID != "minecraft-java" {
+		t.Fatalf("expected game id minecraft-java, got %s", instances[0].GameID)
+	}
+	if saved := store.instances["c1"]; saved.GameID != "minecraft-java" {
+		t.Fatalf("expected saved game id minecraft-java, got %s", saved.GameID)
+	}
+}
diff --git a/backend/internal/store/sqlite.go b/backend/internal/store/sqlite.go
index db09f23..fb62670 100644
--- a/backend/internal/store/sqlite.go
+++ b/backend/internal/store/sqlite.go
@@ -67,6 +67,7 @@ func (s *SQLiteStore) InitSchema(ctx context.Context) error {
 CREATE TABLE IF NOT EXISTS instances (
 	container_id TEXT PRIMARY KEY,
 	name TEXT NOT NULL UNIQUE,
+	game_id TEXT NOT NULL DEFAULT '',
 	status TEXT NOT NULL,
 	created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
 );
@@ -75,21 +76,41 @@ CREATE TABLE IF NOT EXISTS instances (
 	if _, err := s.db.ExecContext(ctx, schema); err != nil {
 		return fmt.Errorf("init instances table: %w", err)
 	}
+	if err := s.ensureGameIDColumn(ctx); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (s *SQLiteStore) ensureGameIDColumn(ctx context.Context) error {
+	const addGameIDColumn = `
+ALTER TABLE instances
+ADD COLUMN game_id TEXT NOT NULL DEFAULT '';
+`
+
+	if _, err := s.db.ExecContext(ctx, addGameIDColumn); err != nil {
+		if isDuplicateColumnErr(err) {
+			return nil
+		}
+		return fmt.Errorf("ensure instances.game_id column: %w", err)
+	}
+
 	return nil
 }
 
 // Save 按容器 ID 执行实例记录的 upsert。
 func (s *SQLiteStore) Save(ctx context.Context, instance model.Instance) error {
 	const upsert = `
-INSERT INTO instances(container_id, name, status)
-VALUES(?, ?, ?)
+INSERT INTO instances(container_id, name, game_id, status)
+VALUES(?, ?, ?, ?)
 ON CONFLICT(container_id)
 DO UPDATE SET
 	name = excluded.name,
+	game_id = excluded.game_id,
 	status = excluded.status;
 `
 
-	_, err := s.db.ExecContext(ctx, upsert, instance.ContainerID, instance.Name, instance.Status)
+	_, err := s.db.ExecContext(ctx, upsert, instance.ContainerID, instance.Name, instance.GameID, instance.Status)
 	if err != nil {
 		if isUniqueNameErr(err) {
 			return model.ErrNameExists
@@ -111,13 +132,13 @@ func (s *SQLiteStore) Delete(ctx context.Context, containerID string) error {
 // Get 按容器 ID 获取一条实例记录。
 func (s *SQLiteStore) Get(ctx context.Context, containerID string) (model.Instance, bool, error) {
 	const q = `
-SELECT container_id, name, status
+SELECT container_id, name, game_id, status
 FROM instances
 WHERE container_id = ?;
 `
 
 	var inst model.Instance
-	err := s.db.QueryRowContext(ctx, q, containerID).Scan(&inst.ContainerID, &inst.Name, &inst.Status)
+	err := s.db.QueryRowContext(ctx, q, containerID).Scan(&inst.ContainerID, &inst.Name, &inst.GameID, &inst.Status)
 	if errors.Is(err, sql.ErrNoRows) {
 		return model.Instance{}, false, nil
 	}
@@ -130,7 +151,7 @@ WHERE container_id = ?;
 // List 返回所有实例记录，并按创建时间倒序排列。
 func (s *SQLiteStore) List(ctx context.Context) ([]model.Instance, error) {
 	const q = `
-SELECT container_id, name, status
+SELECT container_id, name, game_id, status
 FROM instances
 ORDER BY created_at DESC;
 `
@@ -144,7 +165,7 @@ ORDER BY created_at DESC;
 	out := make([]model.Instance, 0)
 	for rows.Next() {
 		var inst model.Instance
-		if err := rows.Scan(&inst.ContainerID, &inst.Name, &inst.Status); err != nil {
+		if err := rows.Scan(&inst.ContainerID, &inst.Name, &inst.GameID, &inst.Status); err != nil {
 			return nil, fmt.Errorf("scan instance: %w", err)
 		}
 		out = append(out, inst)
@@ -167,3 +188,11 @@ func isUniqueNameErr(err error) bool {
 	errStr := err.Error()
 	return strings.Contains(errStr, "UNIQUE constraint failed: instances.name")
 }
+
+func isDuplicateColumnErr(err error) bool {
+	if err == nil {
+		return false
+	}
+	errStr := strings.ToLower(err.Error())
+	return strings.Contains(errStr, "duplicate column name") && strings.Contains(errStr, "game_id")
+}
diff --git a/backend/internal/store/sqlite_test.go b/backend/internal/store/sqlite_test.go
index 6826bf0..3b89ba9 100644
--- a/backend/internal/store/sqlite_test.go
+++ b/backend/internal/store/sqlite_test.go
@@ -31,7 +31,7 @@ func TestSaveAndGet(t *testing.T) {
 	s := newTestStore(t)
 	ctx := context.Background()
 
-	inst := model.Instance{ContainerID: "c1", Name: "server-1", Status: "Stopped"}
+	inst := model.Instance{ContainerID: "c1", Name: "server-1", GameID: "minecraft-java", Status: "Stopped"}
 	if err := s.Save(ctx, inst); err != nil {
 		t.Fatalf("save: %v", err)
 	}
@@ -43,7 +43,7 @@ func TestSaveAndGet(t *testing.T) {
 	if !ok {
 		t.Fatal("expected instance to exist")
 	}
-	if got.ContainerID != "c1" || got.Name != "server-1" || got.Status != "Stopped" {
+	if got.ContainerID != "c1" || got.Name != "server-1" || got.GameID != "minecraft-java" || got.Status != "Stopped" {
 		t.Fatalf("unexpected instance: %+v", got)
 	}
 }
@@ -52,11 +52,12 @@ func TestSave_Upsert(t *testing.T) {
 	s := newTestStore(t)
 	ctx := context.Background()
 
-	inst := model.Instance{ContainerID: "c1", Name: "server-1", Status: "Stopped"}
+	inst := model.Instance{ContainerID: "c1", Name: "server-1", GameID: "minecraft-java", Status: "Stopped"}
 	if err := s.Save(ctx, inst); err != nil {
 		t.Fatalf("first save: %v", err)
 	}
 
+	inst.GameID = "minecraft-bedrock"
 	inst.Status = "Running"
 	if err := s.Save(ctx, inst); err != nil {
 		t.Fatalf("upsert save: %v", err)
@@ -69,17 +70,20 @@ func TestSave_Upsert(t *testing.T) {
 	if got.Status != "Running" {
 		t.Fatalf("expected Running, got %s", got.Status)
 	}
+	if got.GameID != "minecraft-bedrock" {
+		t.Fatalf("expected minecraft-bedrock, got %s", got.GameID)
+	}
 }
 
 func TestSave_DuplicateName(t *testing.T) {
 	s := newTestStore(t)
 	ctx := context.Background()
 
-	if err := s.Save(ctx, model.Instance{ContainerID: "c1", Name: "dup", Status: "Stopped"}); err != nil {
+	if err := s.Save(ctx, model.Instance{ContainerID: "c1", Name: "dup", GameID: "minecraft-java", Status: "Stopped"}); err != nil {
 		t.Fatalf("first save: %v", err)
 	}
 
-	err := s.Save(ctx, model.Instance{ContainerID: "c2", Name: "dup", Status: "Stopped"})
+	err := s.Save(ctx, model.Instance{ContainerID: "c2", Name: "dup", GameID: "minecraft-java", Status: "Stopped"})
 	if !errors.Is(err, model.ErrNameExists) {
 		t.Fatalf("expected ErrNameExists, got %v", err)
 	}
@@ -102,7 +106,7 @@ func TestDelete(t *testing.T) {
 	s := newTestStore(t)
 	ctx := context.Background()
 
-	inst := model.Instance{ContainerID: "c1", Name: "server-1", Status: "Stopped"}
+	inst := model.Instance{ContainerID: "c1", Name: "server-1", GameID: "minecraft-java", Status: "Stopped"}
 	if err := s.Save(ctx, inst); err != nil {
 		t.Fatalf("save: %v", err)
 	}
@@ -135,9 +139,9 @@ func TestList(t *testing.T) {
 	ctx := context.Background()
 
 	instances := []model.Instance{
-		{ContainerID: "c1", Name: "alpha", Status: "Running"},
-		{ContainerID: "c2", Name: "beta", Status: "Stopped"},
-		{ContainerID: "c3", Name: "gamma", Status: "Running"},
+		{ContainerID: "c1", Name: "alpha", GameID: "minecraft-java", Status: "Running"},
+		{ContainerID: "c2", Name: "beta", GameID: "minecraft-bedrock", Status: "Stopped"},
+		{ContainerID: "c3", Name: "gamma", GameID: "terraria", Status: "Running"},
 	}
 	for _, inst := range instances {
 		if err := s.Save(ctx, inst); err != nil {
diff --git a/backend/main.go b/backend/main.go
index 123a59d..0f4884c 100644
--- a/backend/main.go
+++ b/backend/main.go
@@ -58,7 +58,8 @@ func main() {
 	wsHandler := api.NewWsHandler(hub)
 	consoleSvc := service.NewConsoleService(cli)
 	consoleHandler := api.NewConsoleHandler(consoleSvc)
-	router := api.NewRouter(h, gameHandler, wsHandler, consoleHandler)
+	configHandler := api.NewConfigHandler(svc)
+	router := api.NewRouter(h, gameHandler, wsHandler, consoleHandler, configHandler)
 
 	addr := ":8080"
 	log.Printf("MineDock backend listening on %s", addr)
diff --git a/docs/api/contracts.md b/docs/api/contracts.md
index b5d7193..7033eda 100644
--- a/docs/api/contracts.md
+++ b/docs/api/contracts.md
@@ -5,7 +5,7 @@
 ## 约定
 
 - Base URL: `/api`
-- CORS: 允许任意来源,允许方法 `GET,POST,DELETE,OPTIONS`
+- CORS: 允许任意来源,允许方法 `GET,POST,PUT,DELETE,OPTIONS`
 
 ## HTTP接口
 
@@ -98,7 +98,7 @@
   - 成功：`200`
   - 失败：`400`（JSON非法/空名称/缺失 game_id/game_id 不合法/params 非法）、`409`（名称冲突）、`500`（模板不存在或模板非法/容器创建失败）
 - 行为说明：
-  - 端口映射来源：模板 `container.ports`
+  - 端口映射来源：模板 `container.ports`，可在请求体 `ports` 中覆盖 host 端口
   - 卷挂载来源：模板 `container.volumes`，卷名规则为 `minedock-{instanceName}-{volumeName}`
   - 若宿主机端口冲突，返回 Docker 原生错误并映射为 `500`
 - 请求参数：
@@ -107,6 +107,7 @@
 {
   "name": "容器1号",
   "game_id": "minecraft-java",
+  "ports": [{ "host": 25575, "container": 25565, "protocol": "tcp" }],
   "params": {
     "SERVER_TYPE": "PAPER",
     "ONLINE_MODE": "true"
@@ -159,6 +160,51 @@
 { "status": "success" }
 ```
 
+### GET /api/instances/:id/config
+
+- 说明：获取容器当前生效的可编辑配置（包含模板 `params` 定义参数与可编辑端口映射）
+- 状态码：
+  - 成功：`200`
+  - 失败：`400`（ID非法）、`500`
+- 请求参数：无（ID 在路径中）
+- 返回结果：
+
+```json
+{
+  "game_id": "minecraft-java",
+  "status": "Stopped",
+  "ports": [{ "host": 25565, "container": 25565, "protocol": "tcp" }],
+  "params": {
+    "SERVER_TYPE": "PAPER",
+    "MAX_PLAYERS": "20"
+  }
+}
+```
+
+### PUT /api/instances/:id/config
+
+- 说明：更新容器配置（参数 + 端口映射，通过重建容器实现，容器必须处于 Stopped）
+- 状态码：
+  - 成功：`200`
+  - 失败：`400`（ID非法/参数非法）、`409`（容器未停止）、`500`
+- 请求参数：
+
+```json
+{
+  "ports": [{ "host": 25575, "container": 25565, "protocol": "tcp" }],
+  "params": {
+    "SERVER_TYPE": "FABRIC",
+    "MAX_PLAYERS": "50"
+  }
+}
+```
+
+- 返回结果：
+
+```json
+{ "status": "success", "container_id": "new_container_id" }
+```
+
 ### GET /api/ws/events (WebSocket)
 
 - 说明：建立 WebSocket 连接，实时接收容器状态变更推送
diff --git a/docs/design-docs/instance_lifecycle.md b/docs/design-docs/instance_lifecycle.md
index 285ff2b..8d85f7a 100644
--- a/docs/design-docs/instance_lifecycle.md
+++ b/docs/design-docs/instance_lifecycle.md
@@ -10,7 +10,7 @@ type Instance struct {
     ContainerID string `json:"container_id"`
     // 服务端名称
     Name        string `json:"name"`
-    // 来源游戏模板 ID（创建请求字段，当前版本未持久化到 instances 表）
+    // 来源游戏模板 ID（持久化在 instances 表，用于配置编辑时回查模板）
     GameID      string `json:"game_id"`
     // 当前运行态
     Status      string `json:"status"`
@@ -23,6 +23,7 @@ type Instance struct {
 - `container_id`（主键）
 - `name`（唯一）
 - `status`
+- `game_id`
 - `created_at`
 
 ## 接口
@@ -45,6 +46,15 @@ stateDiagram-v2
 - 卷挂载来源：模板 `container.volumes`，卷名规则为 `minedock-{instanceName}-{volumeName}`。
 - 启动命令来源：若模板配置了 `container.command` 则覆盖镜像命令；否则使用镜像默认 `ENTRYPOINT/CMD`。
 
+## 在线配置修改
+
+- 修改范围：允许编辑模板 `params` 定义的用户参数，以及模板端口映射对应的宿主机端口；模板固定环境变量 `container.env` 不可直接修改。
+- 变更方式：通过重建容器应用新配置，流程为 `Inspect -> Remove(old) -> Create(new env + port bindings)`。
+- 状态约束：仅允许在 Stopped 状态下执行配置更新，运行中返回冲突错误。
+- 生效方式：更新完成后容器保持 Stopped，需用户手动启动使配置生效。
+- 保留策略：复用原有卷挂载与端口映射，避免卷数据丢失。
+- 标识变化：重建后 `container_id` 会变化，前端需跳转到新的详情路由。
+
 ## 一致性策略
 
 - 事实来源：Docker Daemon。
diff --git a/docs/exec-plans/active/20260403-detail-tabs-config.md b/docs/exec-plans/active/20260403-detail-tabs-config.md
new file mode 100644
index 0000000..e0aee95
--- /dev/null
+++ b/docs/exec-plans/active/20260403-detail-tabs-config.md
@@ -0,0 +1,533 @@
+# 容器详情页 Tab 导航 + 在线配置修改
+
+## 背景
+
+当前容器详情页 (`/instances/:id`) 只有控制台终端视图。用户需要停止容器、通过命令行或外部工具才能修改运行参数（环境变量），操作门槛较高。
+
+本计划实现：
+
+1. 在容器详情页顶部添加 **Tab 导航栏**，包含"控制台"和"配置"两个标签页
+2. 控制台标签页保持现有 xterm.js 终端功能不变
+3. 新增**配置页**，展示容器当前生效的用户参数与端口映射，支持在线编辑并保存
+4. 保存配置后，更新容器环境变量（需要容器处于 **Stopped** 状态，用户手动重启后生效，不提供一键重启）
+
+## 需要评审的内容
+
+> [!IMPORTANT]
+> **配置修改的实现方式选型**
+>
+> Docker 不支持在运行中修改容器的环境变量。修改配置的标准做法是 **重建容器**：
+>
+> | 方案                           | 说明                                                         | 优缺点                                             |
+> | ------------------------------ | ------------------------------------------------------------ | -------------------------------------------------- |
+> | **Commit + Recreate**          | 将当前容器 commit 为临时镜像，用新环境变量重建容器           | 保留容器内文件改动，但 commit 成本高且污染镜像列表 |
+> | **Remove + Create (保留卷)**   | 删除旧容器，用新环境变量创建新容器，挂载相同的 Volume        | 轻量、符合 Docker 最佳实践；卷数据完整保留         |
+> | **仅允许 Stopped 修改 + 重建** | 只有容器停止后才能修改配置，修改后删除旧容器并用相同参数重建 | 最安全，无需担心运行态中断                         |
+>
+> 本计划采用 **方案 3 (仅允许 Stopped 修改 + 重建)**。原因：
+>
+> - 当前容器创建时已经将卷以 `minedock-{instanceName}-{volumeName}` 命名挂载，重建后可继续使用
+> - Stopped 状态下修改避免用户在不知情的情况下丢失运行态数据
+> - 实现最简洁，不引入 commit 等额外 Docker 操作
+
+> [!WARNING]
+> **重建容器会导致 container_id 变化**
+>
+> 由于是删除旧容器再创建新容器，container_id 会改变。需要：
+>
+> - 后端完成重建后返回新的 container_id
+> - 前端路由跳转到新的 `/instances/:newId`
+> - SQLite 中旧记录删除、新记录插入
+
+> [!IMPORTANT]
+> **配置项的数据来源**
+>
+> 容器环境变量有两个来源：
+>
+> 1. **模板固定环境变量** (`container.env`)：如 `EULA=TRUE`，这些是系统级必须值，**不允许用户修改**
+> 2. **用户可调参数** (`params`)：如 `SERVER_TYPE`、`MAX_PLAYERS`，这些**允许用户修改**
+>
+> 配置页只展示和编辑 `params` 定义的参数，使用模板的 `params` 定义来渲染合适的输入控件（文本框、数字框、下拉框、开关等）。
+>
+> 为了实现这一点，需要：
+>
+> - 后端提供一个接口，返回容器当前生效的用户参数值
+> - 后端提供一个接口，接收新参数值与端口映射并重建容器
+
+> [!IMPORTANT]
+> **端口映射编辑范围**
+>
+> 配置页允许编辑模板 `container.ports` 中定义端口对应的宿主机端口（host）。
+>
+> - 容器端口（container）和协议（protocol）来自模板定义，不允许在页面中新增或删除
+> - 保存时后端将使用新端口映射重建容器
+
+## 前端交互流程
+
+```mermaid
+sequenceDiagram
+    participant U as 用户
+    participant FE as 前端
+    participant BE as 后端
+    participant D as Docker Daemon
+
+    Note over U: 在详情页切换到"配置"标签
+
+    FE->>BE: GET /api/instances/:id/config
+    BE->>D: ContainerInspect (读取环境变量)
+    D-->>BE: 容器配置
+    BE-->>FE: { game_id, params: {...}, status }
+
+    Note over U: 修改参数并点击保存
+    U->>FE: 修改 MAX_PLAYERS = 50
+    FE->>BE: PUT /api/instances/:id/config { params: { MAX_PLAYERS: "50", ... } }
+
+    Note over BE: 容器必须为 Stopped
+    BE->>D: ContainerInspect (获取旧配置)
+    BE->>D: ContainerRemove (删除旧容器)
+    BE->>D: ContainerCreate (新环境变量)
+    D-->>BE: 新 container_id
+    BE-->>FE: { status: "success", container_id: "new_id" }
+    FE->>FE: 路由跳转 /instances/new_id
+```
+
+## 拟定更改
+
+### 后端 Model / 错误定义
+
+#### [MODIFY] errors.go (`backend/internal/model/errors.go`)
+
+新增领域错误：
+
+```go
+// ErrContainerNotStopped 表示容器必须处于停止状态才能执行此操作。
+var ErrContainerNotStopped = errors.New("container must be stopped to update config")
+```
+
+#### [MODIFY] instance.go (`backend/internal/model/instance.go`)
+
+扩展 Instance 结构体，增加 `GameID` 字段（用于查找原始模板）：
+
+```go
+type Instance struct {
+    ContainerID string `json:"container_id"`
+    Name        string `json:"name"`
+    GameID      string `json:"game_id"`
+    Status      string `json:"status"`
+}
+```
+
+> [!NOTE]
+> `GameID` 当前已在创建时通过 Docker Label (`minedock.game_id`) 存储，但未持久化到 SQLite 的 `instances` 表。本计划需要在读取实例时从 Docker Label 中回填此字段。
+
+---
+
+### 后端 Store 层
+
+#### [MODIFY] sqlite.go (`backend/internal/store/sqlite.go`)
+
+- `instances` 表新增 `game_id` 列（可选，允许空字符串兜底）
+- `Save` 方法写入 `game_id`
+- `Get` 方法读出 `game_id`
+
+---
+
+### 后端 Service 层
+
+#### [MODIFY] docker_service.go (`backend/internal/service/docker_service.go`)
+
+新增两个方法：
+
+```go
+// GetInstanceConfig 读取容器当前生效的用户可调参数。
+// 通过 ContainerInspect 读取环境变量，结合模板 params 定义进行反向映射。
+func (s *DockerService) GetInstanceConfig(ctx context.Context, containerID string) (*InstanceConfig, error) {
+    // 1. ContainerInspect 获取容器 labels 和环境变量
+    // 2. 从 labels 中取 game_id
+    // 3. 加载对应模板，获取 params 定义
+    // 4. 遍历 params 定义，从容器环境变量中提取当前值
+    // 5. 返回 InstanceConfig
+}
+
+// UpdateInstanceConfig 通过重建容器来应用新的用户参数。
+// 要求容器处于 Stopped 状态。
+func (s *DockerService) UpdateInstanceConfig(ctx context.Context, containerID string, newParams map[string]string) (string, error) {
+    // 1. ContainerInspect 确认容器为 Stopped
+    // 2. 从 labels 取 game_id、name
+    // 3. 加载模板并 mergeTemplateEnv(tpl, newParams) 生成新环境变量
+    // 4. 记录旧容器的 HostConfig (端口映射、卷挂载) ← 直接从 inspect 拿
+    // 5. ContainerRemove 删除旧容器
+    // 6. ContainerCreate 创建新容器（相同镜像、名称 label、卷、端口，新环境变量）
+    // 7. Store.Delete(oldID) + Store.Save(newInst)
+    // 8. 返回新的 container_id
+}
+```
+
+新增返回结构体：
+
+```go
+// InstanceConfig 描述容器当前生效的可编辑配置。
+type InstanceConfig struct {
+    GameID string            `json:"game_id"`
+    Status string            `json:"status"`
+    Params map[string]string `json:"params"`
+}
+```
+
+> [!NOTE]
+> `InstanceConfig.Params` 的 key 是模板 `params[].key`（如 `SERVER_TYPE`），value 是当前容器中该参数的实际值。这样前端拿到模板定义 + 当前值即可渲染编辑表单。
+
+---
+
+### 后端 API 层
+
+#### [NEW] config_handler.go (`backend/internal/api/config_handler.go`)
+
+新增 ConfigHandler：
+
+```go
+// InstanceConfigurator 定义配置 Handler 依赖的业务能力。
+type InstanceConfigurator interface {
+    GetInstanceConfig(ctx context.Context, containerID string) (*service.InstanceConfig, error)
+    UpdateInstanceConfig(ctx context.Context, containerID string, params map[string]string) (string, error)
+}
+
+// ConfigHandler 暴露容器配置的 HTTP 处理器。
+type ConfigHandler struct {
+    cfg InstanceConfigurator
+}
+
+// NewConfigHandler 创建 ConfigHandler。
+func NewConfigHandler(cfg InstanceConfigurator) *ConfigHandler { ... }
+
+// HandleGetConfig 处理 GET /api/instances/{id}/config。
+func (h *ConfigHandler) HandleGetConfig(w http.ResponseWriter, r *http.Request) {
+    // 1. 解析容器 ID
+    // 2. 调用 cfg.GetInstanceConfig()
+    // 3. JSON 返回 InstanceConfig
+}
+
+// HandleUpdateConfig 处理 PUT /api/instances/{id}/config。
+func (h *ConfigHandler) HandleUpdateConfig(w http.ResponseWriter, r *http.Request) {
+    // 1. 解析容器 ID + JSON body { params: {...} }
+    // 2. 调用 cfg.UpdateInstanceConfig()
+    // 3. 返回 { status: "success", container_id: "new_id" }
+}
+```
+
+#### [MODIFY] router.go (`backend/internal/api/router.go`)
+
+- `NewRouter` 签名新增 `*ConfigHandler` 参数
+- 注册路由：
+  - `GET /api/instances/{id}/config`
+  - `PUT /api/instances/{id}/config`
+
+---
+
+### 后端入口
+
+#### [MODIFY] main.go
+
+- 创建 `ConfigHandler`，注入 `DockerService`（它已实现 `InstanceConfigurator`）
+- 更新 `NewRouter` 调用
+
+```go
+configHandler := api.NewConfigHandler(svc)
+router := api.NewRouter(h, gameHandler, wsHandler, consoleHandler, configHandler)
+```
+
+---
+
+### 前端 API 层
+
+#### [MODIFY] index.ts (`frontend/src/api/index.ts`)
+
+新增接口：
+
+```typescript
+export interface InstanceConfig {
+  game_id: string;
+  status: string;
+  params: Record<string, string>;
+}
+
+export interface UpdateConfigResponse {
+  status: string;
+  container_id: string;
+}
+
+// 获取容器当前生效配置
+export function getInstanceConfig(
+  containerId: string,
+): Promise<InstanceConfig> {
+  return request<InstanceConfig>(
+    `/instances/${encodeURIComponent(containerId)}/config`,
+    { method: "GET" },
+  );
+}
+
+// 更新容器配置（重建容器）
+export function updateInstanceConfig(
+  containerId: string,
+  params: Record<string, string>,
+): Promise<UpdateConfigResponse> {
+  return request<UpdateConfigResponse>(
+    `/instances/${encodeURIComponent(containerId)}/config`,
+    {
+      method: "PUT",
+      body: { params },
+    },
+  );
+}
+```
+
+---
+
+### 前端视图层
+
+#### [MODIFY] InstanceDetail.vue (`frontend/src/views/InstanceDetail.vue`)
+
+这是本次改动最大的文件。主要变更：
+
+1. 新增 Tab 导航栏，包含"控制台"和"配置"两个标签
+2. 根据当前 Tab 显示对应的内容区域
+3. Tab 切换时控制台的 xterm.js 连接保持/销毁逻辑
+
+改造后的页面布局：
+
+```text
+┌─────────────────────────────────────────────┐
+│ ← 返回        容器名称         状态指示器     │ ← 顶部导航栏
+├──────────┬──────────┬───────────────────────┤
+│  控制台   │   配置   │                       │ ← Tab 导航栏
+├──────────┴──────────┴───────────────────────┤
+│                                             │
+│           Tab 内容区域                        │
+│    (控制台: xterm.js / 配置: 参数编辑表单)     │
+│                                             │
+└─────────────────────────────────────────────┘
+```
+
+Tab 导航使用 `<nav>` + `<button>` 实现，不引入子路由。通过 `ref<'console' | 'config'>` 控制当前 Tab。
+
+**样式规范**：
+
+- Tab 按钮使用 CSS 变量 `--create-brass-primary` 保持 Create 主题一致性
+- 激活 Tab 底部有高亮指示器（brass 色下划线）
+- Tab 切换有 CSS transition 过渡
+
+---
+
+#### [NEW] InstanceConfig.vue (`frontend/src/views/InstanceConfig.vue`)
+
+新增配置编辑组件（作为 InstanceDetail.vue 的子组件引入）:
+
+**职责**：
+
+- 接收 `containerId` prop
+- 调用 `getInstanceConfig()` 获取当前配置
+- 调用 `getGameTemplate(gameId)` 获取参数定义（label、type、options 等）
+- 渲染参数编辑表单：
+  - `string` → 文本输入框
+  - `number` → 数字输入框
+  - `boolean` → 开关/切换按钮
+  - `select` → 下拉选择框
+- 保存按钮调用 `updateInstanceConfig()`
+- 容器运行中时显示提示"需要先停止容器才能修改配置"，表单禁用
+- 保存成功后通过 `emit('reconfigured', newContainerId)` 通知父组件刷新路由
+
+**视觉设计**：
+
+```text
+┌─────────────────────────────────────────┐
+│ ⚙ 服务器配置                             │
+│                                         │
+│ ┌─ 服务器类型 ─────────────────────────┐ │
+│ │ [Paper           ▾]                 │ │
+│ │ 选择 Minecraft 服务器内核            │ │
+│ └─────────────────────────────────────┘ │
+│                                         │
+│ ┌─ 游戏版本 ──────────────────────────┐ │
+│ │ [LATEST                           ] │ │
+│ │ 指定 Minecraft 版本号              │ │
+│ └─────────────────────────────────────┘ │
+│                                         │
+│ ┌─ 最大玩家数 ────────────────────────┐ │
+│ │ [20                               ] │ │
+│ │ 服务器最大在线人数                  │ │
+│ └─────────────────────────────────────┘ │
+│                                         │
+│ ┌─ 正版验证 ──────────────────────────┐ │
+│ │ [●───────○]  开启                   │ │
+│ │ 是否启用 Mojang 正版验证            │ │
+│ └─────────────────────────────────────┘ │
+│                                         │
+│              [ 保存配置 ]                │
+│                                         │
+│ ⚠ 保存后需要重新启动容器才能生效        │
+└─────────────────────────────────────────┘
+```
+
+---
+
+### 前端 i18n
+
+#### [MODIFY] zh-CN.json / en-US.json (`frontend/src/locales/`)
+
+新增 key：
+
+```json
+{
+  "tabs": {
+    "console": "控制台 / Console",
+    "config": "配置 / Config"
+  },
+  "config": {
+    "title": "服务器配置 / Server Config",
+    "save": "保存配置 / Save Config",
+    "saving": "保存中... / Saving...",
+    "saveSuccess": "配置已更新，容器已重建 / Config updated, container recreated",
+    "mustStopFirst": "需要先停止容器才能修改配置 / Stop the container before editing config",
+    "noTemplate": "无法加载模板信息 / Unable to load template",
+    "restartNote": "保存后需要重新启动容器才能生效 / Restart the container after saving to apply changes"
+  },
+  "errors": {
+    "containerNotStopped": "容器必须处于停止状态 / Container must be stopped"
+  }
+}
+```
+
+---
+
+### 文档
+
+#### [MODIFY] contracts.md (`docs/api/contracts.md`)
+
+新增两个 HTTP 接口文档：
+
+```markdown
+### GET /api/instances/:id/config
+
+- 说明：获取容器当前生效的用户可调参数
+- 状态码：
+  - 成功：`200`
+  - 失败：`400`（ID 非法）、`500`
+- 返回结果：
+
+{ "game_id": "minecraft-java", "status": "Stopped", "params": { "SERVER_TYPE": "PAPER", "MAX_PLAYERS": "20" } }
+
+### PUT /api/instances/:id/config
+
+- 说明：更新容器配置参数（通过重建容器实现，容器必须为 Stopped）
+- 状态码：
+  - 成功：`200`
+  - 失败：`400`（ID/参数非法）、`409`（容器运行中）、`500`
+- 请求参数：
+
+{ "params": { "SERVER_TYPE": "FABRIC", "MAX_PLAYERS": "50" } }
+
+- 返回结果：
+
+{ "status": "success", "container_id": "new_container_id" }
+```
+
+#### [MODIFY] instance_lifecycle.md (`docs/design-docs/instance_lifecycle.md`)
+
+补充配置修改的策略说明：
+
+- 配置修改通过重建容器实现
+- 仅允许 Stopped 状态下修改
+- 卷挂载保留，端口映射保留
+- container_id 变更
+
+#### [MODIFY] frontend.md (`docs/standards/frontend.md`)
+
+路由部分无需修改（配置页不新增路由，作为 Tab 子视图）。
+
+---
+
+## 执行步骤
+
+- [x] 后端 Model 层
+  - [x] `model/errors.go`：新增 `ErrContainerNotStopped`
+  - [x] `model/instance.go`：`Instance` 结构体增加 `GameID` 字段
+- [x] 后端 Store 层
+  - [x] `store/sqlite.go`：`instances` 表增加 `game_id` 列、更新 Save/Get
+- [x] 后端 Service 层
+  - [x] `service/docker_service.go`：新增 `GetInstanceConfig` 方法
+  - [x] `service/docker_service.go`：新增 `UpdateInstanceConfig` 方法（重建容器逻辑）
+  - [x] 确保 `ListInstances` 和 `readInstance` 回填 `GameID`
+- [x] 后端 API 层
+  - [x] 新建 `api/config_handler.go`：实现 `HandleGetConfig` 和 `HandleUpdateConfig`
+  - [x] 修改 `api/router.go`：注册新路由、更新 `NewRouter` 签名
+- [x] 后端入口
+  - [x] 修改 `main.go`：创建 ConfigHandler 并注入
+- [x] 前端 API 层
+  - [x] 修改 `api/index.ts`：新增 `InstanceConfig` 类型与请求函数
+- [x] 前端视图层
+  - [x] 修改 `views/InstanceDetail.vue`：添加 Tab 导航栏，控制台/配置 Tab 切换
+  - [x] 新建 `views/InstanceConfig.vue`：配置编辑表单组件（参数 + 端口映射）
+- [x] 前端 i18n
+  - [x] 修改 `locales/zh-CN.json`：新增 tabs / config 相关文案
+  - [x] 修改 `locales/en-US.json`：新增 tabs / config 相关文案
+- [x] 后端测试
+  - [x] 编写 `GetInstanceConfig` 单元测试
+  - [x] 编写 `UpdateInstanceConfig` 单元测试（Stopped 成功 / Running 失败 / 参数非法）
+  - [x] 运行 `task backend:test && task backend:vet && task backend:lint`
+- [x] 前端检查
+  - [x] 运行 `npm run lint`
+- [x] 文档更新
+  - [x] 修改 `docs/api/contracts.md`：新增 GET/PUT config 接口文档
+  - [x] 修改 `docs/design-docs/instance_lifecycle.md`：补充配置修改策略
+- [ ] 集成验证
+  - [ ] 创建 Minecraft Java 实例，进入详情页验证 Tab 切换
+  - [ ] 停止容器后修改参数并保存，验证容器重建成功
+  - [ ] 验证重建后 container_id 变更、路由跳转正确
+  - [ ] 验证卷挂载保留，数据不丢失
+  - [ ] 验证运行中容器的配置页表单为禁用状态
+
+## 已确认结论
+
+> [!IMPORTANT]
+> **不支持"应用并重启"一键操作（本期）**
+>
+> 本期范围仅支持"保存配置（重建容器）"，保存后由用户手动启动容器使配置生效。
+>
+> "保存并重启"属于后续可选增强项，不纳入本计划实现。
+
+> [!IMPORTANT]
+> **Container ID 变更后的竞态确认**
+>
+> 结论：当前方案下不存在影响正确性的竞态。
+>
+> 依据：
+>
+> - `useInstanceSync` 当前仅在 `ContainerList` 页面挂载，详情页不依赖该 WebSocket 推送驱动刷新
+> - 配置更新成功后由接口返回新 `container_id`，前端再路由跳转到 `/instances/:newId`
+> - 详情页在路由参数变化时会主动执行 `fetchInstances`，以最新列表重新匹配实例
+>
+> 说明：网络较慢时可能出现短暂 loading/未找到提示，但会被后续拉取结果覆盖，不会造成最终状态错误。
+
+## 验证计划
+
+### 自动化测试
+
+- `task backend:test` — 覆盖：
+  - `GetInstanceConfig`：正常读取 / 容器不存在 / 模板不存在
+  - `UpdateInstanceConfig`：Stopped 时成功重建 / Running 时拒绝 / 参数非法
+  - `ConfigHandler`：HTTP 状态码映射
+- `task backend:vet && task backend:lint`
+- 前端：`npm run lint`
+
+### 手动验证
+
+- 创建 Minecraft Java 实例
+- 进入详情页，验证 Tab 导航栏正确展示"控制台"和"配置"两个标签
+- 切换到"配置"标签，验证当前参数值正确显示
+- 容器运行中时，验证配置表单为禁用状态，显示提示信息
+- 停止容器，验证配置表单变为可编辑
+- 修改 MAX_PLAYERS 为 50，点击保存
+- 验证保存成功提示、路由跳转到新 container_id
+- 验证保存后容器保持 Stopped（不会自动启动）
+- 启动容器，进入控制台验证新参数已生效
+- 浏览器刷新后，验证配置页数据持久化正确
diff --git a/frontend/src/api/index.ts b/frontend/src/api/index.ts
index 7e268fe..8d021c8 100644
--- a/frontend/src/api/index.ts
+++ b/frontend/src/api/index.ts
@@ -105,9 +105,22 @@ async function request<T = unknown>(path: string, options: RequestOptions = {}):
 export interface Instance {
   container_id: string;
   name: string;
+  game_id?: string;
   status: string;
 }
 
+export interface InstanceConfig {
+  game_id: string;
+  status: string;
+  ports: PortMapping[];
+  params: Record<string, string>;
+}
+
+export interface UpdateConfigResponse {
+  status: string;
+  container_id: string;
+}
+
 export interface WsInstancesUpdated {
   type: "instances_updated";
   data: Instance[];
@@ -203,10 +216,11 @@ export function createInstance(
   name: string,
   gameId: string,
   params: Record<string, string> = {},
+  ports: PortMapping[] = [],
 ): Promise<unknown> {
   return request("/instances", {
     method: "POST",
-    body: { name, game_id: gameId, params },
+    body: { name, game_id: gameId, params, ports },
   });
 }
 
@@ -227,3 +241,20 @@ export function deleteInstance(containerId: string): Promise<unknown> {
     method: "DELETE",
   });
 }
+
+export function getInstanceConfig(containerId: string): Promise<InstanceConfig> {
+  return request<InstanceConfig>(`/instances/${encodeURIComponent(containerId)}/config`, {
+    method: "GET",
+  });
+}
+
+export function updateInstanceConfig(
+  containerId: string,
+  params: Record<string, string>,
+  ports: PortMapping[],
+): Promise<UpdateConfigResponse> {
+  return request<UpdateConfigResponse>(`/instances/${encodeURIComponent(containerId)}/config`, {
+    method: "PUT",
+    body: { params, ports },
+  });
+}
diff --git a/frontend/src/locales/en-US.json b/frontend/src/locales/en-US.json
index 29876e7..e741d2d 100644
--- a/frontend/src/locales/en-US.json
+++ b/frontend/src/locales/en-US.json
@@ -18,6 +18,23 @@
     "statusUnknown": "Unknown",
     "mountMissing": "Terminal is not ready yet. Please try again."
   },
+  "tabs": {
+    "console": "Console",
+    "config": "Config"
+  },
+  "config": {
+    "title": "Server Config",
+    "loading": "Loading current configuration...",
+    "portsTitle": "Port Bindings",
+    "hostPortLabel": "Host Port",
+    "containerPortHint": "Container port: {container}/{protocol}",
+    "save": "Save Config",
+    "saving": "Saving...",
+    "saveSuccess": "Config updated and container recreated.",
+    "mustStopFirst": "Stop the container before editing config.",
+    "noTemplate": "Unable to load template details.",
+    "restartNote": "Start the container manually after saving to apply changes."
+  },
   "createModal": {
     "title": "New Container",
     "placeholder": "Enter container name...",
@@ -38,6 +55,9 @@
     "nameLabel": "Container Name",
     "namePlaceholder": "Enter container name",
     "loadingTemplate": "Loading template details...",
+    "portsTitle": "Port Bindings",
+    "hostPortLabel": "Host Port",
+    "containerPortHint": "Container port: {container}/{protocol}",
     "paramsTitle": "Parameters",
     "noParams": "This template has no configurable parameters.",
     "booleanEnabled": "Enabled",
@@ -75,6 +95,7 @@
     "invalidContainerId": "The container ID is invalid.",
     "instanceNameExists": "Container name already exists. Please choose another one.",
     "instanceRunning": "The container is running. Stop it before deleting.",
+    "containerNotStopped": "Container must be stopped before updating config.",
     "unknown": "An unknown error occurred. Please try again later."
   },
   "sidebar": {
diff --git a/frontend/src/locales/zh-CN.json b/frontend/src/locales/zh-CN.json
index 3af6926..8566e0f 100644
--- a/frontend/src/locales/zh-CN.json
+++ b/frontend/src/locales/zh-CN.json
@@ -18,6 +18,23 @@
     "statusUnknown": "状态未知",
     "mountMissing": "终端尚未准备好，请稍后重试。"
   },
+  "tabs": {
+    "console": "控制台",
+    "config": "配置"
+  },
+  "config": {
+    "title": "服务器配置",
+    "loading": "正在加载当前配置...",
+    "portsTitle": "端口映射",
+    "hostPortLabel": "宿主机端口",
+    "containerPortHint": "容器端口：{container}/{protocol}",
+    "save": "保存配置",
+    "saving": "保存中...",
+    "saveSuccess": "配置已更新，容器已重建。",
+    "mustStopFirst": "需要先停止容器才能修改配置。",
+    "noTemplate": "无法加载模板信息。",
+    "restartNote": "保存后请手动启动容器使配置生效。"
+  },
   "createModal": {
     "title": "新建容器",
     "placeholder": "请输入新容器名称...",
@@ -38,6 +55,9 @@
     "nameLabel": "容器名称",
     "namePlaceholder": "请输入容器名称",
     "loadingTemplate": "模板详情加载中...",
+    "portsTitle": "端口映射",
+    "hostPortLabel": "宿主机端口",
+    "containerPortHint": "容器端口：{container}/{protocol}",
     "paramsTitle": "参数配置",
     "noParams": "该模板没有可调整参数。",
     "booleanEnabled": "启用",
@@ -75,6 +95,7 @@
     "invalidContainerId": "容器 ID 无效。",
     "instanceNameExists": "容器名称已存在，请更换后重试。",
     "instanceRunning": "容器运行中，请先停止后再删除。",
+    "containerNotStopped": "容器必须处于停止状态后才能更新配置。",
     "unknown": "发生未知错误，请稍后重试。"
   },
   "sidebar": {
diff --git a/frontend/src/stores/containers.ts b/frontend/src/stores/containers.ts
index 9f928b5..28af89b 100644
--- a/frontend/src/stores/containers.ts
+++ b/frontend/src/stores/containers.ts
@@ -5,6 +5,7 @@ import {
   ApiRequestError,
   listInstances,
   createInstance as apiCreate,
+  type PortMapping,
   deleteInstance as apiDelete,
   startInstance as apiStart,
   stopInstance as apiStop,
@@ -24,6 +25,7 @@ const backendMessageKeyMap: Record<string, string> = {
   "invalid container id": "errors.invalidContainerId",
   "instance name already exists": "errors.instanceNameExists",
   "instance is running, stop it before delete": "errors.instanceRunning",
+  "container must be stopped to update config": "errors.containerNotStopped",
 };
 
 function mapBackendMessageToKey(message: string): string | undefined {
@@ -180,9 +182,10 @@ export const useContainerStore = defineStore("containers", () => {
     name: string,
     gameId: string,
     params: Record<string, string> = {},
+    ports: PortMapping[] = [],
   ): Promise<boolean> {
     try {
-      const data = await apiCreate(name, gameId, params);
+      const data = await apiCreate(name, gameId, params, ports);
       print(data);
       await fetchInstances();
       return true;
diff --git a/frontend/src/views/CreateInstance.vue b/frontend/src/views/CreateInstance.vue
index 79ed92b..ef6ded1 100644
--- a/frontend/src/views/CreateInstance.vue
+++ b/frontend/src/views/CreateInstance.vue
@@ -2,7 +2,7 @@
 import { computed, onMounted, ref, watch } from "vue";
 import { useRoute, useRouter } from "vue-router";
 import { useI18n } from "vue-i18n";
-import type { GameTemplate, TemplateParam } from "../api/index";
+import type { GameTemplate, PortMapping, TemplateParam } from "../api/index";
 import { useGameStore } from "../stores/games";
 import { useContainerStore } from "../stores/containers";
 
@@ -17,6 +17,7 @@ const creating = ref(false);
 const currentGameID = ref("");
 const containerName = ref("");
 const pageErrorKey = ref("");
+const ports = ref<PortMapping[]>([]);
 const paramValues = ref<Record<string, string>>({});
 
 const currentGame = computed(() => {
@@ -52,6 +53,7 @@ async function initializeForRoute(): Promise<void> {
   loading.value = true;
   pageErrorKey.value = "";
   containerName.value = "";
+  ports.value = [];
   paramValues.value = {};
 
   const gameID = parseRouteGameID(route.params.gameId);
@@ -90,9 +92,17 @@ async function initializeForRoute(): Promise<void> {
 function initParamValuesFromTemplate(template: GameTemplate | null): void {
   const next: Record<string, string> = {};
   if (template) {
+    ports.value = template.container.ports.map((port) => ({
+      host: port.host,
+      container: port.container,
+      protocol: port.protocol,
+    }));
+
     for (const param of template.params) {
       next[param.key] = getDefaultParamValue(param);
     }
+  } else {
+    ports.value = [];
   }
   paramValues.value = next;
 }
@@ -135,6 +145,14 @@ function getCreateParamsPayload(): Record<string, string> {
   return payload;
 }
 
+function getCreatePortsPayload(): PortMapping[] {
+  return ports.value.map((port) => ({
+    host: Number(port.host),
+    container: Number(port.container),
+    protocol: port.protocol,
+  }));
+}
+
 function cancelCreate(): void {
   void router.push({ name: "ImageRegistry" });
 }
@@ -156,7 +174,12 @@ async function handleCreate(): Promise<void> {
   creating.value = true;
   containerStore.print(t("status.creating"));
 
-  const success = await containerStore.create(name, gameID, getCreateParamsPayload());
+  const success = await containerStore.create(
+    name,
+    gameID,
+    getCreateParamsPayload(),
+    getCreatePortsPayload(),
+  );
   creating.value = false;
   if (!success) {
     pageErrorKey.value = containerStore.outputI18n?.key ?? "errors.unknown";
@@ -203,6 +226,35 @@ async function handleCreate(): Promise<void> {
       </div>
 
       <div v-else-if="currentTemplate" class="field-block">
+        <h3 class="section-title">{{ $t("createPage.portsTitle") }}</h3>
+
+        <div v-if="ports.length > 0" class="param-list">
+          <article
+            v-for="(port, index) in ports"
+            :key="`${port.container}-${port.protocol}-${index}`"
+            class="param-item"
+          >
+            <label class="field-label" :for="`port-${index}`">{{
+              $t("createPage.hostPortLabel")
+            }}</label>
+            <input
+              :id="`port-${index}`"
+              v-model.number="ports[index].host"
+              class="text-input"
+              type="number"
+              min="1"
+            />
+            <p class="field-hint">
+              {{
+                $t("createPage.containerPortHint", {
+                  container: port.container,
+                  protocol: port.protocol,
+                })
+              }}
+            </p>
+          </article>
+        </div>
+
         <h3 class="section-title">{{ $t("createPage.paramsTitle") }}</h3>
 
         <div v-if="currentTemplate.params.length === 0" class="state-message compact">
diff --git a/frontend/src/views/InstanceConfig.vue b/frontend/src/views/InstanceConfig.vue
new file mode 100644
index 0000000..069f83a
--- /dev/null
+++ b/frontend/src/views/InstanceConfig.vue
@@ -0,0 +1,496 @@
+<script setup lang="ts">
+import { computed, ref, watch } from "vue";
+import {
+  ApiRequestError,
+  getGameTemplate,
+  getInstanceConfig,
+  type GameTemplate,
+  type InstanceConfig as InstanceConfigPayload,
+  type PortMapping,
+  type TemplateParam,
+  updateInstanceConfig,
+} from "../api/index";
+
+const props = defineProps<{ containerId: string }>();
+
+const emit = defineEmits<{
+  reconfigured: [newContainerId: string];
+}>();
+
+const loading = ref(false);
+const saving = ref(false);
+const loadErrorKey = ref("");
+const saveErrorKey = ref("");
+const saveSuccess = ref(false);
+
+const config = ref<InstanceConfigPayload | null>(null);
+const template = ref<GameTemplate | null>(null);
+const ports = ref<PortMapping[]>([]);
+const values = ref<Record<string, string>>({});
+
+const isRunning = computed(() => {
+  const status = config.value?.status ?? "";
+  const normalized = status.trim().toLowerCase();
+  return normalized === "running" || normalized.startsWith("up");
+});
+
+const editable = computed(() => !loading.value && !saving.value && !isRunning.value);
+
+watch(
+  () => props.containerId,
+  () => {
+    void loadConfig();
+  },
+  { immediate: true },
+);
+
+function mapRequestErrorToKey(error: unknown): string {
+  if (error instanceof ApiRequestError) {
+    const backendMessage = error.backendMessage?.trim().toLowerCase() ?? "";
+    if (backendMessage.includes("container must be stopped")) {
+      return "errors.containerNotStopped";
+    }
+    if (backendMessage.includes("invalid container id")) {
+      return "errors.invalidContainerId";
+    }
+
+    if (error.key === "errors.network") {
+      return "errors.network";
+    }
+
+    if (error.key === "errors.httpStatus") {
+      switch (error.status) {
+        case 400:
+          return "errors.badRequest";
+        case 404:
+          return "errors.notFound";
+        case 409:
+          return "errors.conflict";
+        case 500:
+          return "errors.internal";
+        default:
+          return "errors.unknown";
+      }
+    }
+
+    if (error.key) {
+      return error.key;
+    }
+  }
+
+  return "errors.unknown";
+}
+
+function getDefaultParamValue(param: TemplateParam): string {
+  if (typeof param.default === "boolean") {
+    return param.default ? "true" : "false";
+  }
+  if (param.default == null) {
+    return "";
+  }
+  return String(param.default);
+}
+
+function initializeValues(
+  currentTemplate: GameTemplate,
+  currentConfig: InstanceConfigPayload,
+): void {
+  const next: Record<string, string> = {};
+  for (const param of currentTemplate.params) {
+    const fromConfig = currentConfig.params[param.key];
+    if (typeof fromConfig === "string") {
+      next[param.key] = fromConfig;
+      continue;
+    }
+    next[param.key] = getDefaultParamValue(param);
+  }
+  values.value = next;
+}
+
+function isBooleanParamEnabled(key: string): boolean {
+  return values.value[key] === "true";
+}
+
+function onBooleanParamChange(key: string, event: Event): void {
+  const target = event.target as HTMLInputElement;
+  values.value = {
+    ...values.value,
+    [key]: target.checked ? "true" : "false",
+  };
+}
+
+function buildParamsPayload(): Record<string, string> {
+  const currentTemplate = template.value;
+  if (!currentTemplate) {
+    return {};
+  }
+
+  const payload: Record<string, string> = {};
+  for (const param of currentTemplate.params) {
+    const value = values.value[param.key];
+    payload[param.key] = typeof value === "string" ? value : "";
+  }
+  return payload;
+}
+
+function buildPortsPayload(): PortMapping[] {
+  return ports.value.map((port) => ({
+    host: Number(port.host),
+    container: Number(port.container),
+    protocol: port.protocol,
+  }));
+}
+
+async function loadConfig(): Promise<void> {
+  loading.value = true;
+  saving.value = false;
+  loadErrorKey.value = "";
+  saveErrorKey.value = "";
+  saveSuccess.value = false;
+  config.value = null;
+  template.value = null;
+  ports.value = [];
+  values.value = {};
+
+  const id = props.containerId.trim();
+  if (!id) {
+    loadErrorKey.value = "errors.invalidContainerId";
+    loading.value = false;
+    return;
+  }
+
+  let currentConfig: InstanceConfigPayload;
+  try {
+    currentConfig = await getInstanceConfig(id);
+    config.value = currentConfig;
+    ports.value = Array.isArray(currentConfig.ports)
+      ? currentConfig.ports.map((item) => ({
+          host: item.host,
+          container: item.container,
+          protocol: item.protocol,
+        }))
+      : [];
+  } catch (error) {
+    loadErrorKey.value = mapRequestErrorToKey(error);
+    loading.value = false;
+    return;
+  }
+
+  try {
+    const currentTemplate = await getGameTemplate(currentConfig.game_id);
+    template.value = currentTemplate;
+    initializeValues(currentTemplate, currentConfig);
+  } catch {
+    loadErrorKey.value = "config.noTemplate";
+  }
+
+  loading.value = false;
+}
+
+async function handleSave(): Promise<void> {
+  if (!editable.value) {
+    return;
+  }
+  if (!template.value || !config.value) {
+    return;
+  }
+
+  saving.value = true;
+  saveErrorKey.value = "";
+  saveSuccess.value = false;
+
+  try {
+    const resp = await updateInstanceConfig(
+      props.containerId,
+      buildParamsPayload(),
+      buildPortsPayload(),
+    );
+    saveSuccess.value = true;
+    emit("reconfigured", resp.container_id);
+  } catch (error) {
+    saveErrorKey.value = mapRequestErrorToKey(error);
+  } finally {
+    saving.value = false;
+  }
+}
+</script>
+
+<template>
+  <section class="config-panel">
+    <header class="config-header">
+      <h2 class="config-title">{{ $t("config.title") }}</h2>
+      <p class="config-note">{{ $t("config.restartNote") }}</p>
+    </header>
+
+    <div v-if="loading" class="state-message">{{ $t("config.loading") }}</div>
+
+    <div v-else-if="loadErrorKey" class="state-message state-error">{{ $t(loadErrorKey) }}</div>
+
+    <template v-else-if="template && config">
+      <div v-if="isRunning" class="state-message state-warning">
+        {{ $t("config.mustStopFirst") }}
+      </div>
+
+      <div v-if="ports.length > 0" class="port-list">
+        <h3 class="section-title">{{ $t("config.portsTitle") }}</h3>
+        <article
+          v-for="(port, index) in ports"
+          :key="`${port.container}-${port.protocol}-${index}`"
+          class="port-item"
+        >
+          <label class="field-label" :for="`cfg-port-${index}`">{{
+            $t("config.hostPortLabel")
+          }}</label>
+          <input
+            :id="`cfg-port-${index}`"
+            v-model.number="ports[index].host"
+            class="text-input"
+            type="number"
+            min="1"
+            :disabled="!editable"
+          />
+          <p class="field-hint">
+            {{
+              $t("config.containerPortHint", {
+                container: port.container,
+                protocol: port.protocol,
+              })
+            }}
+          </p>
+        </article>
+      </div>
+
+      <div v-if="template.params.length === 0" class="state-message">
+        {{ $t("registry.noParams") }}
+      </div>
+
+      <div v-else class="param-list">
+        <article v-for="param in template.params" :key="param.key" class="param-item">
+          <label class="field-label" :for="`cfg-${param.key}`">{{ param.label }}</label>
+          <p v-if="param.description" class="field-hint">{{ param.description }}</p>
+
+          <input
+            v-if="param.type === 'string'"
+            :id="`cfg-${param.key}`"
+            v-model="values[param.key]"
+            class="text-input"
+            type="text"
+            :disabled="!editable"
+          />
+
+          <input
+            v-else-if="param.type === 'number'"
+            :id="`cfg-${param.key}`"
+            v-model="values[param.key]"
+            class="text-input"
+            type="number"
+            :disabled="!editable"
+          />
+
+          <label
+            v-else-if="param.type === 'boolean'"
+            class="boolean-field"
+            :for="`cfg-${param.key}`"
+          >
+            <input
+              :id="`cfg-${param.key}`"
+              type="checkbox"
+              :checked="isBooleanParamEnabled(param.key)"
+              :disabled="!editable"
+              @change="onBooleanParamChange(param.key, $event)"
+            />
+            <span>
+              {{
+                isBooleanParamEnabled(param.key)
+                  ? $t("createPage.booleanEnabled")
+                  : $t("createPage.booleanDisabled")
+              }}
+            </span>
+          </label>
+
+          <select
+            v-else-if="param.type === 'select'"
+            :id="`cfg-${param.key}`"
+            v-model="values[param.key]"
+            class="text-input"
+            :disabled="!editable"
+          >
+            <option v-for="option in param.options || []" :key="option.value" :value="option.value">
+              {{ option.label }}
+            </option>
+          </select>
+        </article>
+      </div>
+
+      <footer class="actions">
+        <button
+          class="save-btn"
+          type="button"
+          :disabled="!editable || template.params.length === 0"
+          @click="handleSave"
+        >
+          {{ saving ? $t("config.saving") : $t("config.save") }}
+        </button>
+      </footer>
+
+      <p v-if="saveSuccess" class="save-success">{{ $t("config.saveSuccess") }}</p>
+      <p v-if="saveErrorKey" class="save-error">{{ $t(saveErrorKey) }}</p>
+    </template>
+  </section>
+</template>
+
+<style scoped>
+.config-panel {
+  border: 1px solid var(--create-border-outer);
+  background: rgba(0, 0, 0, 0.18);
+  border-radius: 8px;
+  padding: 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  min-height: 0;
+}
+
+.config-header {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  border-bottom: 1px solid var(--create-border-outer);
+  padding-bottom: 10px;
+}
+
+.config-title {
+  margin: 0;
+  color: var(--create-brass-primary);
+  font-size: 18px;
+}
+
+.config-note {
+  margin: 0;
+  color: var(--text-muted);
+  font-size: 12px;
+}
+
+.state-message {
+  text-align: center;
+  color: var(--text-muted);
+  border: 1px dashed var(--border-muted);
+  border-radius: 8px;
+  padding: 16px;
+}
+
+.state-error {
+  color: var(--danger);
+  border-color: rgba(255, 77, 79, 0.5);
+  background: var(--danger-light);
+}
+
+.state-warning {
+  color: var(--create-brass-primary);
+  border-color: var(--create-border-outer);
+  background: rgba(0, 0, 0, 0.24);
+}
+
+.param-list {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 12px;
+}
+
+.port-list {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 12px;
+}
+
+.section-title {
+  margin: 0;
+  font-size: 15px;
+  color: var(--create-brass-primary);
+}
+
+.port-item {
+  border: 1px solid var(--create-border-outer);
+  border-radius: 6px;
+  padding: 10px;
+  background: rgba(0, 0, 0, 0.14);
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.param-item {
+  border: 1px solid var(--create-border-outer);
+  border-radius: 6px;
+  padding: 10px;
+  background: rgba(0, 0, 0, 0.14);
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.field-label {
+  font-size: 13px;
+  color: var(--text-on-dark);
+}
+
+.field-hint {
+  margin: 0;
+  font-size: 12px;
+  color: var(--text-muted);
+}
+
+.text-input {
+  padding: 8px 10px;
+  background: var(--input-bg);
+  border: 1px solid var(--input-border);
+  color: var(--text-on-dark);
+  border-radius: 4px;
+  outline: none;
+  width: 100%;
+}
+
+.text-input:focus {
+  border-color: var(--create-brass-primary);
+}
+
+.boolean-field {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 13px;
+  color: var(--text-on-dark);
+}
+
+.actions {
+  display: flex;
+  justify-content: flex-end;
+}
+
+.save-btn {
+  padding: 8px 16px;
+  border: 1px solid var(--create-border-outer);
+  background: var(--create-brass-dark);
+  color: var(--card-text);
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 13px;
+}
+
+.save-btn:disabled {
+  cursor: not-allowed;
+  opacity: 0.6;
+}
+
+.save-success {
+  margin: 0;
+  color: var(--success);
+  font-size: 13px;
+}
+
+.save-error {
+  margin: 0;
+  color: var(--danger);
+  font-size: 13px;
+}
+</style>
diff --git a/frontend/src/views/InstanceDetail.vue b/frontend/src/views/InstanceDetail.vue
index 00f9c20..24d767c 100644
--- a/frontend/src/views/InstanceDetail.vue
+++ b/frontend/src/views/InstanceDetail.vue
@@ -4,6 +4,9 @@ import { useRoute, useRouter } from "vue-router";
 import { useI18n } from "vue-i18n";
 import { useConsole } from "../composables/useConsole";
 import { useContainerStore } from "../stores/containers";
+import InstanceConfig from "./InstanceConfig.vue";
+
+type DetailTab = "console" | "config";
 
 const route = useRoute();
 const router = useRouter();
@@ -12,6 +15,7 @@ const store = useContainerStore();
 
 const loading = ref(true);
 const containerId = ref("");
+const activeTab = ref<DetailTab>("console");
 
 const { terminalRef, error, init, dispose } = useConsole(containerId);
 
@@ -80,6 +84,18 @@ async function loadInstance(): Promise<void> {
   loading.value = false;
 }
 
+function switchTab(tab: DetailTab): void {
+  activeTab.value = tab;
+}
+
+function handleReconfigured(newContainerID: string): void {
+  const normalized = parseContainerID(newContainerID);
+  if (!normalized || normalized === containerId.value) {
+    return;
+  }
+  void router.push({ name: "InstanceDetail", params: { id: normalized } });
+}
+
 function backToList(): void {
   void router.push({ name: "ContainerList" });
 }
@@ -93,9 +109,9 @@ watch(
 );
 
 watch(
-  [loading, canAttach],
-  ([isLoading, running]) => {
-    if (isLoading || !running) {
+  [loading, canAttach, activeTab],
+  ([isLoading, running, tab]) => {
+    if (isLoading || tab !== "console" || !running) {
       dispose();
       return;
     }
@@ -121,14 +137,41 @@ onUnmounted(() => {
   </header>
 
   <main class="main-content">
-    <section class="terminal-panel">
-      <div v-if="infoKey" class="panel-overlay">
-        {{ $t(infoKey) }}
-      </div>
-      <div v-else ref="terminalRef" class="terminal-host"></div>
+    <nav class="tab-nav" role="tablist" aria-label="Instance detail tabs">
+      <button
+        class="tab-btn"
+        :class="{ 'is-active': activeTab === 'console' }"
+        role="tab"
+        type="button"
+        :aria-selected="activeTab === 'console'"
+        @click="switchTab('console')"
+      >
+        {{ $t("tabs.console") }}
+      </button>
+      <button
+        class="tab-btn"
+        :class="{ 'is-active': activeTab === 'config' }"
+        role="tab"
+        type="button"
+        :aria-selected="activeTab === 'config'"
+        @click="switchTab('config')"
+      >
+        {{ $t("tabs.config") }}
+      </button>
+    </nav>
+
+    <section class="tab-content">
+      <section v-if="activeTab === 'console'" class="terminal-panel">
+        <div v-if="infoKey" class="panel-overlay">
+          {{ $t(infoKey) }}
+        </div>
+        <div v-else ref="terminalRef" class="terminal-host"></div>
+      </section>
+
+      <InstanceConfig v-else :container-id="containerId" @reconfigured="handleReconfigured" />
     </section>
 
-    <footer v-if="displayError" class="status-bar">
+    <footer v-if="activeTab === 'console' && displayError" class="status-bar">
       <div class="error-text">{{ displayError }}</div>
     </footer>
   </main>
@@ -186,12 +229,48 @@ onUnmounted(() => {
   margin: 0 auto;
   padding: 8px 24px 24px;
   display: grid;
-  grid-template-rows: 1fr auto;
+  grid-template-rows: auto 1fr auto;
   gap: 12px;
 }
 
+.tab-nav {
+  display: flex;
+  gap: 8px;
+  border-bottom: 1px solid var(--create-border-outer);
+  padding-bottom: 2px;
+}
+
+.tab-btn {
+  border: 1px solid transparent;
+  border-radius: 6px 6px 0 0;
+  background: transparent;
+  color: var(--text-muted);
+  padding: 8px 14px;
+  cursor: pointer;
+  font-size: 13px;
+  transition: all 0.2s ease;
+}
+
+.tab-btn:hover {
+  color: var(--create-brass-primary);
+  background: rgba(0, 0, 0, 0.2);
+}
+
+.tab-btn.is-active {
+  color: var(--create-brass-primary);
+  border-color: var(--create-border-outer);
+  border-bottom-color: transparent;
+  background: rgba(0, 0, 0, 0.3);
+  box-shadow: inset 0 -2px 0 var(--create-brass-primary);
+}
+
+.tab-content {
+  min-height: 0;
+}
+
 .terminal-panel {
   min-height: 0;
+  height: 100%;
   position: relative;
   border: 1px solid var(--create-border-outer);
   background: radial-gradient(circle at top, rgba(33, 55, 40, 0.9), rgba(9, 12, 11, 0.95));
@@ -243,6 +322,10 @@ onUnmounted(() => {
     padding: 8px 12px 12px;
   }
 
+  .tab-btn {
+    padding: 8px 12px;
+  }
+
   .status-bar {
     flex-direction: column;
     align-items: flex-start;