refactor(docker): refine container disk spec handling

cmd/revm/docker.go

@@ -49,6 +49,15 @@ func dockerLifeCycle(_ context.Context, command *cli.Command) error {
 		return err
 	}
 
+	var containerDiskSpec *librevm.ContainerDiskSpec
+	if value := command.String(define.FlagContainerDisk); value != "" {
+		spec, err := librevm.ParseContainerDiskSpec(value)
+		if err != nil {
+			return err
+		}
+		containerDiskSpec = &spec
+	}
+
 	cfg := librevm.DefaultConfig().
 		WithMode(librevm.ModeContainer).
 		WithName(command.String(define.FlagSessionID)).
@@ -59,7 +68,7 @@ func dockerLifeCycle(_ context.Context, command *cli.Command) error {
 		WithLogLevel(command.String(define.FlagLogLevel)).
 		WithLogTo(command.String(define.FlagLogTo)).
 		WithMount(command.StringSlice(define.FlagMount)...).
-		WithContainerDisk(command.String(define.FlagContainerDisk)).
+		WithContainerDiskSpec(containerDiskSpec).
 		WithPodmanProxyAPIFile(command.String(define.FlagPodmanProxyAPIFile)).
 		WithManageAPIFile(command.String(define.FlagManageAPIFile)).
 		WithSSHKeyDir(command.String(define.FlagSSHKeyDir)).

cmd/revm/flags.go

@@ -85,7 +85,7 @@ var (
 
 	containerDiskFlag = &cli.StringFlag{
 		Name:  define.FlagContainerDisk,
-		Usage: "path to a persistent ext4 raw disk image for container storage; auto-created if the file does not exist; defaults to a workspace-local disk if unset",
+		Usage: "persistent ext4 raw disk image for container storage (format: <path>[,version=<string>]); auto-created if missing; if the stored version xattr is missing or mismatched, the disk is recreated; defaults to a workspace-local disk with the built-in container disk version when unset",
 	}
 
 	podmanProxyAPIFileFlag = &cli.StringFlag{

docs/docker-mode.md

@@ -78,7 +78,7 @@ revm docker [flags]
 | `--raw-disk`       | Attach an ext4 disk image (format: `<path>[,uuid=<uuid>][,version=<string>][,mnt=<guest-path>]`); path-only works; new disks auto-create, default to a random UUID, and mount at `/mnt/<UUID>` (repeatable) | — |
 | `--network`        | Network stack: `gvisor` (full virtual NIC, supports port mapping) or `tsi` (transparent intercept)  | `gvisor`              |
 | `--system-proxy`   | Read macOS system proxy and inject into containers; rewrites `127.0.0.1` to `host.containers.internal` | `false`            |
-| `--container-disk` | Path to a persistent ext4 raw disk image for container storage; auto-created if missing; defaults to a session-local disk | session-local |
+| `--container-disk` | Container storage disk spec (format: `<path>[,version=<string>]`); path-only works; defaults to a session-local disk with the built-in container disk version; if the stored version xattr is missing or mismatched, the disk is recreated | session-local + built-in version |
 | `--podman-proxy-api-file` | Custom Unix socket path for the Podman API proxy; defaults to `<session_dir>/socks/podman-api.sock` | —                  |
 | `--manage-api-file` | Custom Unix socket path for the VM management API; defaults to `<session_dir>/socks/vmctl.sock` | —                  |
 | `--ssh-key-dir`    | Directory to symlink the generated SSH key pair (`key` and `key.pub`) into; keys are always created inside the session directory | — |

docs/docker-mode_zh.md

@@ -76,7 +76,7 @@ revm docker [flags]
 | `--raw-disk`       | 挂载 ext4 裸盘镜像（格式：`<path>[,uuid=<uuid>][,version=<string>][,mnt=<guest-path>]`）；只传路径即可；新磁盘会自动创建，默认随机 UUID，并挂载到 `/mnt/<UUID>`（可重复） | — |
 | `--network`        | 网络栈：`gvisor`（完整虚拟网卡，支持端口映射）或 `tsi`（透明转发）                         | `gvisor`              |
 | `--system-proxy`   | 读取 macOS 系统代理并注入容器内，自动将 127.0.0.1 重写为 `host.containers.internal` | `false`               |
-| `--container-disk` | 持久化容器存储磁盘路径（ext4 裸盘镜像）；不存在时自动创建；不指定则使用会话目录内的默认磁盘 | 会话目录内默认磁盘 |
+| `--container-disk` | 容器存储磁盘规格（格式：`<path>[,version=<string>]`）；只传路径即可；默认使用会话目录内的磁盘和内置 version；如果已有磁盘的 version xattr 缺失或不匹配，会直接重建 | 会话目录内默认磁盘 + 内置 version |
 | `--podman-proxy-api-file` | Podman API socket 的自定义 Unix socket 路径；默认为 `<会话目录>/socks/podman-api.sock` | —                     |
 | `--manage-api-file` | VM 管理 API socket 的自定义 Unix socket 路径；默认为 `<会话目录>/socks/vmctl.sock` | —                     |
 | `--ssh-key-dir`    | SSH 密钥对（`key` 和 `key.pub`）的符号链接目录；密钥始终在会话目录内生成                   | —                     |

pkg/define/const.go

@@ -40,7 +40,8 @@ const (
 	VMConfigFilePathInGuest = "/vmconfig.json"
 	HostDomainInGVPNet      = "host.containers.internal"
 
-	ContainerStorageMountPoint = "/var/lib/containers"
+	ContainerStorageMountPoint  = "/var/lib/containers"
+	DefaultContainerDiskVersion = "revm-container-storage-v1"
 
 	DefaultGuestUser = "root"
 

pkg/librevm/config.go

@@ -48,20 +48,19 @@ type Config struct {
 	WorkDir string   `toml:"workdir,omitempty"  json:"workdir,omitempty"`
 	Env     []string `toml:"env,omitempty"      json:"env,omitempty"`
 
-	Network                 string          `toml:"network,omitempty"         json:"network,omitempty"` // "gvisor" | "tsi"
-	Mounts                  []string        `toml:"mounts,omitempty"          json:"mounts,omitempty"`  // "/host:/guest[,ro]"
-	Disks                   []RawDiskSpec   `toml:"disks,omitempty"           json:"disks,omitempty"`
-	ContainerDisk           string          `toml:"container_disk,omitempty"         json:"containerDisk,omitempty"`
-	ContainerDiskVersion    string          `toml:"container_disk_version,omitempty" json:"containerDiskVersion,omitempty"`
-	PodmanProxyAPIFile      string          `toml:"podman_proxy_api_file,omitempty"   json:"podmanProxyAPIFile,omitempty"`
-	ManageAPIFile           string          `toml:"manage_api_file,omitempty"         json:"manageAPIFile,omitempty"`
-	SSHKeyDir               string          `toml:"ssh_key_dir,omitempty"                json:"sshKeyDir,omitempty"`
-	ExportSSHKeyPrivateFile string          `toml:"export_ssh_key_private_file,omitempty" json:"exportSSHKeyPrivateFile,omitempty"`
-	ExportSSHKeyPublicFile  string          `toml:"export_ssh_key_public_file,omitempty"  json:"exportSSHKeyPublicFile,omitempty"`
-	Proxy                   bool            `toml:"proxy,omitempty"           json:"proxy,omitempty"`
-	LogLevel                string          `toml:"log_level,omitempty"       json:"logLevel,omitempty"` // default "info"
-	LogTo                   string          `toml:"log_to,omitempty"          json:"logTo,omitempty"`
-	Reporters               []EventReporter `toml:"-" json:"-"`
+	Network                 string             `toml:"network,omitempty"         json:"network,omitempty"` // "gvisor" | "tsi"
+	Mounts                  []string           `toml:"mounts,omitempty"          json:"mounts,omitempty"`  // "/host:/guest[,ro]"
+	Disks                   []RawDiskSpec      `toml:"disks,omitempty"           json:"disks,omitempty"`
+	ContainerDisk           *ContainerDiskSpec `toml:"container_disk,omitempty" json:"containerDisk,omitempty"`
+	PodmanProxyAPIFile      string             `toml:"podman_proxy_api_file,omitempty"   json:"podmanProxyAPIFile,omitempty"`
+	ManageAPIFile           string             `toml:"manage_api_file,omitempty"         json:"manageAPIFile,omitempty"`
+	SSHKeyDir               string             `toml:"ssh_key_dir,omitempty"                json:"sshKeyDir,omitempty"`
+	ExportSSHKeyPrivateFile string             `toml:"export_ssh_key_private_file,omitempty" json:"exportSSHKeyPrivateFile,omitempty"`
+	ExportSSHKeyPublicFile  string             `toml:"export_ssh_key_public_file,omitempty"  json:"exportSSHKeyPublicFile,omitempty"`
+	Proxy                   bool               `toml:"proxy,omitempty"           json:"proxy,omitempty"`
+	LogLevel                string             `toml:"log_level,omitempty"       json:"logLevel,omitempty"` // default "info"
+	LogTo                   string             `toml:"log_to,omitempty"          json:"logTo,omitempty"`
+	Reporters               []EventReporter    `toml:"-" json:"-"`
 }
 
 // DefaultConfig returns a Config with sensible defaults pre-filled.
@@ -83,15 +82,10 @@ func (c *Config) WithMemory(mb uint64) *Config    { c.MemoryMB = mb; return c }
 func (c *Config) WithRootfs(path string) *Config  { c.Rootfs = path; return c }
 func (c *Config) WithWorkDir(dir string) *Config  { c.WorkDir = dir; return c }
 func (c *Config) WithNetwork(mode string) *Config { c.Network = mode; return c }
-func (c *Config) WithContainerDisk(path string) *Config {
-	if path != "" {
-		c.ContainerDisk = path
-	}
-	return c
-}
-func (c *Config) WithContainerDiskVersion(v string) *Config {
-	if v != "" {
-		c.ContainerDiskVersion = v
+func (c *Config) WithContainerDiskSpec(spec *ContainerDiskSpec) *Config {
+	if spec != nil {
+		specCopy := *spec
+		c.ContainerDisk = &specCopy
 	}
 	return c
 }
@@ -207,11 +201,9 @@ func (c *Config) MergeFrom(other *Config) {
 	if len(other.Mounts) > 0 {
 		c.Mounts = append(c.Mounts, other.Mounts...)
 	}
-	if other.ContainerDisk != "" {
-		c.ContainerDisk = other.ContainerDisk
-	}
-	if other.ContainerDiskVersion != "" {
-		c.ContainerDiskVersion = other.ContainerDiskVersion
+	if other.ContainerDisk != nil {
+		specCopy := *other.ContainerDisk
+		c.ContainerDisk = &specCopy
 	}
 	if other.PodmanProxyAPIFile != "" {
 		c.PodmanProxyAPIFile = other.PodmanProxyAPIFile

pkg/librevm/machine.go

@@ -504,13 +504,8 @@ func buildMachine(ctx context.Context, cfg Config, workspacePath string) (mc *de
 			return nil, nil, fmt.Errorf("configure podman: %w", err)
 		}
 
-		diskPath := mBuilder.pathMgr.GetBuiltInContainerStorageDiskFile()
-		if cfg.ContainerDisk != "" {
-			diskPath = cfg.ContainerDisk
-		}
-
 		logrus.Info("Preparing container storage disk...")
-		if err := mBuilder.configureContainerRAWDisk(ctx, diskPath, cfg.ContainerDiskVersion); err != nil {
+		if err := mBuilder.configureContainerRAWDisk(ctx, cfg.ContainerDisk, mBuilder.pathMgr.GetBuiltInContainerStorageDiskFile()); err != nil {
 			return nil, nil, fmt.Errorf("setup container disk: %w", err)
 		}
 	}