flowchart TB
    subgraph API["API 层"]
        VolumeRouter[Volume Router]
    end
    
    subgraph Service["卷服务层"]
        VolumesService[VolumesService]
        VolumeStore[VolumeStore]
    end
    
    subgraph Core["核心组件"]
        Volume[Volume 接口]
        MountPoint[MountPoint 管理器]
        RefCounter[引用计数器]
    end
    
    subgraph Drivers["卷驱动"]
        DriverStore[Driver Store]
        LocalDriver[Local 驱动]
        PluginDriver[插件驱动]
    end
    
    subgraph Storage["存储层"]
        Metadata[(卷元数据<br/>BoltDB)]
        FileSystem[(文件系统<br/>/var/lib/docker/volumes)]
    end
    
    VolumeRouter --> VolumesService
    VolumesService --> VolumeStore
    
    VolumeStore --> Volume
    VolumeStore --> DriverStore
    VolumeStore --> RefCounter
    
    Volume --> MountPoint
    
    DriverStore --> LocalDriver
    DriverStore --> PluginDriver
    
    LocalDriver --> FileSystem
    PluginDriver -.HTTP/gRPC.-> ExternalDriver[外部存储<br/>NFS/Ceph/EBS]
    
    VolumeStore --> Metadata
    LocalDriver --> FileSystem

- **VolumeStore**：卷存储管理

  ```go
  type VolumeStore struct {
      locks   *locker.Locker
      volumes map[string]*volumeMetadata
      names   map[string]volume.Volume
      refs    map[string][]string  // volumeName -> []containerID
      drivers *drivers.Store
      db      *bolt.DB
  }

- **MountPoint**：容器挂载点

  ```go
  type MountPoint struct {
      Type        mount.Type      // bind/volume/tmpfs
      Name        string          // 卷名称
      Source      string          // 源路径
      Destination string          // 容器内路径
      Driver      string          // 驱动名称
      RW          bool            // 读写权限
      Volume      volume.Volume   // 卷对象
      Propagation mount.Propagation
  }

**3. 卷驱动**：

- **Local 驱动**：
  - 数据存储：`/var/lib/docker/volumes/<volume-name>/_data`
  - 元数据：`/var/lib/docker/volumes/<volume-name>/_meta.json`
  - 支持配额限制（Linux quota）
  - 支持用户命名空间映射

- **插件驱动**：
  - 通过 HTTP/gRPC 与外部驱动通信
  - 支持远程存储（NFS/Ceph/EBS/Azure Disk）
  - 驱动能力查询（Scope: local/global）
  - 驱动配置传递

---

## 卷创建与挂载时序图

```mermaid
sequenceDiagram
    autonumber
    participant Client as docker CLI
    participant Router as Volume Router
    participant Service as VolumesService
    participant Store as VolumeStore
    participant Driver as Local Driver
    participant FS as 文件系统
    
    Note over Client: docker volume create mydata
    Client->>Router: POST /volumes/create
    Router->>Service: Create(name, driver, options)
    
    Note over Service: 阶段1: 验证参数
    Service->>Service: 验证卷名（字符限制）
    alt 名称为空
        Service->>Service: 生成随机 ID
        Service->>Service: 标记为匿名卷
    end
    
    Note over Service: 阶段2: 检查冲突
    Service->>Store: 加锁（卷名）
    Store->>Store: 检查卷是否已存在
    alt 卷已存在
        Store-->>Service: 返回已存在的卷
    end
    
    Note over Service: 阶段3: 创建驱动实例
    Service->>Store: GetDriver(driverName)
    Store->>Driver: 初始化驱动
    
    Note over Driver: 阶段4: 创建卷目录
    Store->>Driver: Create(name, opts)
    Driver->>Driver: 生成卷路径
    Note over Driver: /var/lib/docker/volumes/mydata
    
    Driver->>FS: MkdirAll(rootPath, 0o701)
    FS-->>Driver: 根目录创建成功
    
    Driver->>FS: MkdirAll(dataPath, 0o755)
    Note over FS: /var/lib/docker/volumes/mydata/_data
    FS-->>Driver: 数据目录创建成功
    
    alt 配置了选项（quota/size）
        Driver->>Driver: 设置配额限制
        Driver->>FS: setQuota(path, size)
    end
    
    Note over Driver: 阶段5: 保存元数据
    Driver->>Driver: 创建 Volume 对象
    Driver->>FS: 写入 _meta.json
    Driver-->>Store: Volume 对象
    
    Note over Service: 阶段6: 注册卷
    Store->>Store: volumes[name] = volume
    Store->>Store: 持久化到 BoltDB
    Store->>Service: 触发卷创建事件
    Store->>Store: 解锁（卷名）
    
    Service-->>Router: Volume 详情
    Router-->>Client: 201 Created
    
    Note over Client: docker run -v mydata:/data nginx
    Note over Client: (容器创建过程省略)
    
    Note over Client: 容器启动时挂载卷
    Client->>Service: Mount(volume, containerID)
    
    Note over Service: 阶段7: 获取卷对象
    Service->>Store: Get(volumeName)
    Store-->>Service: Volume 对象
    
    Note over Service: 阶段8: 增加引用计数
    Service->>Store: AddReference(volumeName, containerID)
    Store->>Store: refs[volumeName].Add(containerID)
    
    Note over Service: 阶段9: 挂载卷
    Service->>Driver: Mount(containerID)
    Driver->>Driver: mountCount++
    
    alt 首次挂载
        Driver->>FS: 确保数据目录可访问
        Driver->>Driver: 记录挂载引用
    end
    
    Driver-->>Service: 卷路径
    Note over Service: /var/lib/docker/volumes/mydata/_data
    
    Service-->>Client: 挂载成功，返回路径
    
    Note over Client: 容器启动，卷已挂载
    
    Note over Client: 容器停止
    Client->>Service: Unmount(volume, containerID)
    
    Note over Service: 阶段10: 卸载卷
    Service->>Driver: Unmount(containerID)
    Driver->>Driver: mountCount--
    
    alt mountCount == 0
        Driver->>Driver: 清理挂载状态
    end
    
    Driver-->>Service: 卸载成功
    
    Note over Service: 阶段11: 释放引用
    Service->>Store: RemoveReference(volumeName, containerID)
    Store->>Store: refs[volumeName].Remove(containerID)
    
    Service-->>Client: 卸载成功

// 驱动优先级
if driverName == "" {
    driverName = "local"  // 默认驱动
}

driver, err := s.drivers.CreateDriver(driverName)

# Local 驱动的目录结构
/var/lib/docker/volumes/mydata/
├── _data/           # 实际数据目录（容器挂载点）
└── _meta.json       # 元数据（驱动、选项、创建时间）

{
  "Driver": "local",
  "Labels": {},
  "Options": {},
  "CreatedAt": "2023-01-01T00:00:00Z"
}

// VolumeStore 持久化
func (s *VolumeStore) save(v volume.Volume) error {
    return s.db.Update(func(tx *bolt.Tx) error {
        b := tx.Bucket([]byte("volumes"))
        data := marshalVolume(v)
        return b.Put([]byte(v.Name()), data)
    })
}

- 挂载流程：
  1. 获取卷对象（从 Store）
  2. 增加引用计数（volumeName -> containerID）
  3. 调用驱动的 Mount 方法（返回宿主机路径）
  4. 容器启动时 bind mount 到容器内

**阶段10-11：卸载与引用释放（5-10ms）**

- 卸载条件：
  - 容器停止时自动卸载
  - 引用计数递减
  - 当引用计数为 0 时，卷可被删除

---

## 卷类型对比

| 特性 | 命名卷 | 匿名卷 | Bind Mount | Tmpfs Mount |
|---|---|---|---|---|
| **创建方式** | `docker volume create` | `-v /data` | `-v /host:/data` | `--tmpfs /data` |
| **持久化** | ✓ | ✓ | ✓ | ✗（内存中） |
| **容器删除后保留** | ✓ | ✗ | ✓ | ✗ |
| **权限管理** | Docker 管理 | Docker 管理 | 宿主机权限 | 容器内权限 |
| **跨容器共享** | ✓ | ✗ | ✓ | ✗ |
| **驱动支持** | ✓ | ✓ | ✗ | ✗ |
| **备份迁移** | 易 | 易 | 难 | 不可用 |
| **用例** | 生产环境数据 | 临时数据 | 开发环境 | 临时缓存 |

---

## 卷驱动插件机制

### 插件通信协议

```mermaid
sequenceDiagram
    autonumber
    participant Docker as dockerd
    participant Plugin as 卷插件
    
    Note over Docker: 发现插件
    Docker->>Plugin: GET /Plugin.Activate
    Plugin-->>Docker: {"Implements": ["VolumeDriver"]}
    
    Note over Docker: 创建卷
    Docker->>Plugin: POST /VolumeDriver.Create
    Note over Docker: {"Name": "myvol", "Opts": {...}}
    Plugin->>Plugin: 创建远程存储
    Plugin-->>Docker: {"Err": ""}
    
    Note over Docker: 挂载卷
    Docker->>Plugin: POST /VolumeDriver.Mount
    Note over Docker: {"Name": "myvol", "ID": "container-id"}
    Plugin->>Plugin: 挂载远程存储到本地
    Plugin-->>Docker: {"Mountpoint": "/mnt/myvol", "Err": ""}
    
    Note over Docker: 获取卷路径
    Docker->>Plugin: POST /VolumeDriver.Path
    Plugin-->>Docker: {"Mountpoint": "/mnt/myvol", "Err": ""}
    
    Note over Docker: 卸载卷
    Docker->>Plugin: POST /VolumeDriver.Unmount
    Note over Docker: {"Name": "myvol", "ID": "container-id"}
    Plugin->>Plugin: 卸载远程存储
    Plugin-->>Docker: {"Err": ""}
    
    Note over Docker: 删除卷
    Docker->>Plugin: POST /VolumeDriver.Remove
    Plugin->>Plugin: 删除远程存储
    Plugin-->>Docker: {"Err": ""}

// VolumeDriver 插件接口
type VolumeDriver interface {
    // Create 创建卷
    Create(req *CreateRequest) error
    
    // Remove 删除卷
    Remove(req *RemoveRequest) error
    
    // Mount 挂载卷，返回挂载点路径
    Mount(req *MountRequest) (*MountResponse, error)
    
    // Unmount 卸载卷
    Unmount(req *UnmountRequest) error
    
    // Get 获取卷详情
    Get(req *GetRequest) (*GetResponse, error)
    
    // List 列出所有卷
    List() (*ListResponse, error)
    
    // Path 获取卷在宿主机的路径
    Path(req *PathRequest) (*PathResponse, error)
    
    // Capabilities 查询驱动能力
    Capabilities() (*CapabilitiesResponse, error)
}

type CapabilitiesResponse struct {
    Capabilities Capability
}

type Capability struct {
    // Scope 卷的作用域
    // - local: 仅本地节点可访问
    // - global: 集群所有节点可访问
    Scope string  // "local" | "global"
}

// 使用 sync.Map 减少锁竞争
type refCounter struct {
    refs sync.Map  // volumeName -> sync.Map(refID -> struct{})
}

func (rc *refCounter) Add(volume, ref string) {
    refs, _ := rc.refs.LoadOrStore(volume, &sync.Map{})
    refs.(*sync.Map).Store(ref, struct{}{})
}

func (rc *refCounter) HasRef(volume string) bool {
    refs, ok := rc.refs.Load(volume)
    if !ok {
        return false
    }
    
    hasRef := false
    refs.(*sync.Map).Range(func(_, _ interface{}) bool {
        hasRef = true
        return false  // 找到一个引用即可停止
    })
    return hasRef
}

// 缓存卷元数据，避免频繁读取文件系统
type volumeCache struct {
    cache map[string]*cachedVolume
    mu    sync.RWMutex
    ttl   time.Duration
}

type cachedVolume struct {
    volume    volume.Volume
    expiresAt time.Time
}

func (vc *volumeCache) Get(name string) (volume.Volume, bool) {
    vc.mu.RLock()
    defer vc.mu.RUnlock()
    
    if cv, ok := vc.cache[name]; ok {
        if time.Now().Before(cv.expiresAt) {
            return cv.volume, true
        }
    }
    return nil, false
}

// 使用 singleflight 避免重复挂载
type mountManager struct {
    group singleflight.Group
}

func (mm *mountManager) Mount(ctx context.Context, vol volume.Volume, ref string) (string, error) {
    key := vol.Name() + ":" + ref
    
    result, err, _ := mm.group.Do(key, func() (interface{}, error) {
        return vol.Mount(ref)
    })
    
    if err != nil {
        return "", err
    }
    return result.(string), nil
}

# 推荐：命名卷（持久化、易管理）
docker volume create mydata
docker run -v mydata:/data nginx

# 不推荐：匿名卷（容器删除后丢失）
docker run -v /data nginx

# 备份卷数据
docker run --rm \
  -v mydata:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/mydata.tar.gz -C /data .

# 恢复卷数据
docker run --rm \
  -v mydata:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/mydata.tar.gz -C /data

# 方式1: 使用 docker volume export/import（需插件支持）
docker volume export mydata > mydata.tar
docker volume import mydata < mydata.tar

# 方式2: 使用容器复制数据
docker run --rm \
  -v old_volume:/from \
  -v new_volume:/to \
  alpine sh -c "cp -av /from/. /to"

# 删除未使用的卷
docker volume prune

# 强制删除卷（即使有容器引用）
docker volume rm -f mydata

# 查看卷占用空间
docker system df -v

# 安装 NFS 驱动插件
docker plugin install vieux/sshfs

# 创建 NFS 卷
docker volume create \
  --driver vieux/sshfs \
  --opt sshcmd=user@host:/path \
  --opt password=secret \
  nfs-volume

# 使用远程卷
docker run -v nfs-volume:/data nginx

# 使用 bind mount（避免卷层开销）
docker run -v /host/data:/data nginx

# 使用 tmpfs（内存文件系统，极高性能）
docker run --tmpfs /tmp:rw,size=1g nginx

# 使用卷的 nocopy 选项（跳过初始化复制）
docker run -v mydata:/data:nocopy nginx

# 只读卷
docker run -v mydata:/data:ro nginx

# 使用卷标签管理
docker volume create \
  --label env=production \
  --label app=web \
  mydata

# 限制卷大小（需驱动支持）
docker volume create \
  --opt size=10G \
  mydata

# 检查卷是否存在
docker volume inspect mydata

# 检查卷驱动是否可用
docker plugin ls | grep volume

# 查看卷挂载点权限
ls -la /var/lib/docker/volumes/mydata/_data

# 检查容器日志
docker logs <container-id>

# 查看卷引用（哪些容器正在使用）
docker ps -a --filter volume=mydata

# 停止并删除引用容器
docker rm -f $(docker ps -aq --filter volume=mydata)

# 强制删除卷
docker volume rm -f mydata

# 检查卷数据是否在磁盘上
ls -la /var/lib/docker/volumes/

# 检查 BoltDB 元数据
strings /var/lib/docker/volumes/metadata.db | grep mydata

# 恢复卷元数据
docker volume create --name mydata
# 手动复制数据到 /var/lib/docker/volumes/mydata/_data

type ListResponse struct {
    // Volumes 卷列表
    Volumes []*Volume `json:"Volumes"`
    
    // Warnings 警告信息（例如驱动错误）
    Warnings []string `json:"Warnings"`
}

type Volume struct {
    // Name 卷名称
    Name string `json:"Name"`
    
    // Driver 驱动名称
    Driver string `json:"Driver"`
    
    // Mountpoint 挂载点路径
    Mountpoint string `json:"Mountpoint"`
    
    // CreatedAt 创建时间
    CreatedAt string `json:"CreatedAt,omitempty"`
    
    // Status 驱动状态（驱动特定）
    Status map[string]interface{} `json:"Status,omitempty"`
    
    // Labels 标签
    Labels map[string]string `json:"Labels"`
    
    // Scope 作用域（local/global）
    Scope string `json:"Scope"`
    
    // Options 驱动选项
    Options map[string]string `json:"Options"`
    
    // UsageData 使用情况
    UsageData *UsageData `json:"UsageData,omitempty"`
    
    // ClusterVolume 集群卷信息（v1.42+）
    ClusterVolume *ClusterVolume `json:"ClusterVolume,omitempty"`
}

func (v *volumeRouter) getVolumesList(ctx context.Context, w http.ResponseWriter, r *http.Request, vars map[string]string) error {
    // 1. 解析过滤器
    f, err := filters.FromJSON(r.Form.Get("filters"))
    
    // 2. 获取本地卷列表
    volumes, warnings, err := v.backend.List(ctx, f)
    
    // 3. 如果是 Swarm Manager，追加集群卷
    version := httputils.VersionFromContext(ctx)
    if versions.GreaterThanOrEqualTo(version, "1.42") && v.cluster.IsManager() {
        clusterVolumes, swarmErr := v.cluster.GetVolumes(volumebackend.ListOptions{Filters: f})
        if swarmErr != nil {
            warnings = append(warnings, swarmErr.Error())
        }
        volumes = append(volumes, clusterVolumes...)
    }
    
    // 4. 返回响应
    return httputils.WriteJSON(w, http.StatusOK, &volume.ListResponse{
        Volumes:  volumes,
        Warnings: warnings,
    })
}

func (s *VolumesService) List(ctx context.Context, filter filters.Args) ([]*volumetypes.Volume, []string, error) {
    // 1. 转换过滤器
    by, err := filtersToBy(filter, acceptedListFilters)
    
    // 2. 从 VolumeStore 查找
    vols, warns, err := s.vs.Find(ctx, by)
    
    // 3. 转换为 API 类型
    return s.volumesToAPI(ctx, vols, useCachedPath(true)), warns, nil
}

func (s *VolumeStore) Find(ctx context.Context, by By) ([]*volumeWrapper, []string, error) {
    s.locks.Lock()
    defer s.locks.Unlock()
    
    // 1. 过滤卷列表
    var volumes []*volumeWrapper
    var warnings []string
    
    for _, v := range s.vols {
        // 应用过滤器（名称/驱动/标签/dangling）
        if by.Name != "" && !strings.Contains(v.Name(), by.Name) {
            continue
        }
        if by.Driver != "" && v.DriverName() != by.Driver {
            continue
        }
        // ... 其他过滤逻辑
        
        volumes = append(volumes, v)
    }
    
    return volumes, warnings, nil
}

sequenceDiagram
    autonumber
    participant Client as Docker Client
    participant Router as volumeRouter
    participant Backend as VolumesService
    participant Store as VolumeStore
    participant Cluster as SwarmCluster
    
    Client->>Router: GET /volumes?filters={...}
    Router->>Router: 解析过滤器
    Router->>Backend: List(ctx, filters)
    Backend->>Store: Find(ctx, by)
    Store->>Store: 遍历 s.vols 映射
    Store->>Store: 应用过滤器
    Store-->>Backend: [volumes], warnings
    Backend-->>Router: [volumes], warnings
    
    alt API >= 1.42 且 Swarm Manager
        Router->>Cluster: GetVolumes(listOptions)
        Cluster-->>Router: clusterVolumes
        Router->>Router: 合并本地与集群卷
    end
    
    Router-->>Client: 200 OK<br/>{Volumes, Warnings}

func (v *volumeRouter) getVolumeByName(ctx context.Context, w http.ResponseWriter, r *http.Request, vars map[string]string) error {
    version := httputils.VersionFromContext(ctx)
    
    // 1. 优先从本地查找
    vol, err := v.backend.Get(ctx, vars["name"], opts.WithGetResolveStatus)
    
    // 2. 本地未找到，尝试从 Swarm 集群查找（v1.42+）
    if cerrdefs.IsNotFound(err) &&
       versions.GreaterThanOrEqualTo(version, "1.42") &&
       v.cluster.IsManager() {
        swarmVol, err := v.cluster.GetVolume(vars["name"])
        vol = &swarmVol
    }
    
    // 3. 返回卷信息
    return httputils.WriteJSON(w, http.StatusOK, vol)
}

func (s *VolumesService) Get(ctx context.Context, name string, getOpts ...opts.GetOption) (*volumetypes.Volume, error) {
    // 1. 从 VolumeStore 获取
    v, err := s.vs.Get(ctx, name, getOpts...)
    
    // 2. 转换为 API 类型
    vol := volumeToAPIType(v)
    
    // 3. 如果需要状态信息，调用驱动
    var cfg opts.GetConfig
    for _, o := range getOpts {
        o(&cfg)
    }
    if cfg.ResolveStatus {
        vol.Status = v.Status()  // 调用驱动的 Status() 方法
    }
    
    return &vol, nil
}

func (s *VolumeStore) Get(ctx context.Context, name string, opts ...opts.GetOption) (volume.Volume, error) {
    s.locks.Lock(name)
    defer s.locks.Unlock(name)
    
    // 1. 从内存缓存获取
    v, exists := s.vols[name]
    if !exists {
        return nil, &OpErr{Op: "get", Name: name, Err: ErrNoSuchVolume}
    }
    
    return v, nil
}

sequenceDiagram
    autonumber
    participant Client as Docker Client
    participant Router as volumeRouter
    participant Backend as VolumesService
    participant Store as VolumeStore
    participant Driver as Volume Driver
    participant Cluster as SwarmCluster
    
    Client->>Router: GET /volumes/myvol
    Router->>Backend: Get(ctx, "myvol", WithResolveStatus)
    Backend->>Store: Get(ctx, "myvol")
    Store->>Store: 查找 s.vols["myvol"]
    
    alt 卷存在
        Store-->>Backend: volumeWrapper
        Backend->>Driver: Status()
        Driver-->>Backend: statusMap
        Backend-->>Router: Volume{Status}
        Router-->>Client: 200 OK<br/>{Volume}
    else 卷不存在（本地）
        Store-->>Backend: ErrNoSuchVolume
        alt API >= 1.42 且 Swarm Manager
            Router->>Cluster: GetVolume("myvol")
            Cluster-->>Router: swarmVolume
            Router-->>Client: 200 OK<br/>{ClusterVolume}
        else
            Router-->>Client: 404 Not Found
        end
    end

type CreateOptions struct {
    // Name 卷名称（可选，留空则生成随机名）
    Name string `json:"Name"`
    
    // Driver 驱动名称（默认 "local"）
    Driver string `json:"Driver"`
    
    // DriverOpts 驱动选项
    DriverOpts map[string]string `json:"DriverOpts"`
    
    // Labels 标签
    Labels map[string]string `json:"Labels"`
    
    // ClusterVolumeSpec 集群卷规格（v1.42+）
    ClusterVolumeSpec *ClusterVolumeSpec `json:"ClusterVolumeSpec,omitempty"`
}

{
    "type": "nfs",
    "o": "addr=192.168.1.100,rw",
    "device": ":/path/to/dir"
}

func (v *volumeRouter) postVolumesCreate(ctx context.Context, w http.ResponseWriter, r *http.Request, vars map[string]string) error {
    // 1. 解析请求
    var req volume.CreateOptions
    if err := httputils.ReadJSON(r, &req); err != nil {
        return err
    }
    
    version := httputils.VersionFromContext(ctx)
    
    // 2. 判断是否为集群卷
    var vol *volume.Volume
    var err error
    
    if req.ClusterVolumeSpec != nil && versions.GreaterThanOrEqualTo(version, "1.42") {
        // 集群卷：通过 Swarm 创建
        vol, err = v.cluster.CreateVolume(req)
    } else {
        // 本地卷：通过 VolumesService 创建
        vol, err = v.backend.Create(ctx, req.Name, req.Driver,
            opts.WithCreateOptions(req.DriverOpts),
            opts.WithCreateLabels(req.Labels))
    }
    
    // 3. 返回创建的卷
    return httputils.WriteJSON(w, http.StatusCreated, vol)
}

func (s *VolumesService) Create(ctx context.Context, name, driverName string, options ...opts.CreateOption) (*volumetypes.Volume, error) {
    // 1. 生成匿名卷名称
    if name == "" {
        name = stringid.GenerateRandomID()
        if driverName == "" {
            driverName = volume.DefaultDriverName
        }
        options = append(options, opts.WithCreateLabel(AnonymousLabel, ""))
    }
    
    // 2. 调用 VolumeStore 创建
    v, err := s.vs.Create(ctx, name, driverName, options...)
    
    // 3. 转换为 API 类型
    apiV := volumeToAPIType(v)
    return &apiV, nil
}

func (s *VolumeStore) Create(ctx context.Context, name, driverName string, opts ...opts.CreateOption) (volume.Volume, error) {
    // 1. 应用选项
    var cfg opts.CreateConfig
    for _, o := range opts {
        o(&cfg)
    }
    
    s.locks.Lock(name)
    defer s.locks.Unlock(name)
    
    // 2. 检查卷是否已存在
    if v, exists := s.vols[name]; exists {
        if v.DriverName() != driverName {
            return nil, &OpErr{Op: "create", Name: name, Err: ErrVolumeExists}
        }
        return v, nil  // 幂等返回
    }
    
    // 3. 获取驱动
    if driverName == "" {
        driverName = volume.DefaultDriverName
    }
    driver, err := volumedrivers.GetDriver(driverName)
    
    // 4. 调用驱动创建卷
    v, err := driver.Create(name, cfg.Options)
    
    // 5. 包装并缓存
    vw := &volumeWrapper{
        name:        name,
        driverName:  driverName,
        labels:      cfg.Labels,
        v:           v,
        options:     cfg.Options,
    }
    s.vols[name] = vw
    
    // 6. 持久化元数据
    s.setMeta(name, volumeMetadata{
        Name:    name,
        Driver:  driverName,
        Labels:  cfg.Labels,
        Options: cfg.Options,
    })
    
    // 7. 记录事件
    s.eventLogger.LogVolumeEvent(name, events.ActionCreate, attributes)
    
    return vw, nil
}

func (r *Root) Create(name string, opts map[string]string) (volume.Volume, error) {
    // 1. 验证卷名称
    if err := r.validateName(name); err != nil {
        return nil, err
    }
    
    r.m.Lock()
    defer r.m.Unlock()
    
    // 2. 创建卷目录
    path := r.DataPath(name)
    if err := os.MkdirAll(path, 0755); err != nil {
        return nil, err
    }
    
    // 3. 应用挂载选项（NFS/CIFS 等）
    v := &localVolume{
        name:       name,
        path:       path,
        opts:       opts,
    }
    
    // 4. 如果有挂载选项，执行挂载
    if optsConfig != nil {
        if err := v.mount(); err != nil {
            return nil, err
        }
    }
    
    return v, nil
}

sequenceDiagram
    autonumber
    participant Client as Docker Client
    participant Router as volumeRouter
    participant Backend as VolumesService
    participant Store as VolumeStore
    participant Driver as Volume Driver
    participant FS as Filesystem
    participant DB as BoltDB
    
    Client->>Router: POST /volumes/create<br/>{Name, Driver, DriverOpts}
    Router->>Router: 解析 CreateOptions
    
    alt 集群卷（ClusterVolumeSpec != nil）
        Router->>Router: cluster.CreateVolume()
        Note right of Router: Swarm 集群卷创建流程
    else 本地卷
        Router->>Backend: Create(ctx, name, driver, opts)
        Backend->>Store: Create(ctx, name, driver, opts)
        
        Store->>Store: 检查卷是否已存在
        alt 卷已存在
            Store-->>Backend: 返回已存在的卷（幂等）
        else 卷不存在
            Store->>Driver: GetDriver(driverName)
            Store->>Driver: Create(name, opts)
            
            Driver->>FS: MkdirAll(/var/lib/docker/volumes/name)
            FS-->>Driver: ok
            
            alt 有挂载选项（NFS/CIFS）
                Driver->>FS: mount -t nfs ...
                FS-->>Driver: ok
            end
            
            Driver-->>Store: volume
            
            Store->>Store: 包装为 volumeWrapper
            Store->>Store: 缓存到 s.vols[name]
            Store->>DB: setMeta(name, metadata)
            DB-->>Store: ok
            
            Store->>Store: LogVolumeEvent("create")
            Store-->>Backend: volumeWrapper
        end
        
        Backend-->>Router: Volume
        Router-->>Client: 201 Created<br/>{Volume}
    end

type UpdateOptions struct {
    // Spec 新的集群卷规格
    Spec *ClusterVolumeSpec `json:"Spec,omitempty"`
}

func (v *volumeRouter) putVolumesUpdate(ctx context.Context, w http.ResponseWriter, r *http.Request, vars map[string]string) error {
    // 1. 检查 Swarm 状态
    if !v.cluster.IsManager() {
        return errdefs.Unavailable(errors.New("volume update only valid for cluster volumes"))
    }
    
    // 2. 解析版本号
    rawVersion := r.URL.Query().Get("version")
    version, err := strconv.ParseUint(rawVersion, 10, 64)
    
    // 3. 解析更新选项
    var req volume.UpdateOptions
    if err := httputils.ReadJSON(r, &req); err != nil {
        return err
    }
    
    // 4. 调用 Swarm 更新
    return v.cluster.UpdateVolume(vars["name"], version, req)
}

sequenceDiagram
    autonumber
    participant Client as Docker Client
    participant Router as volumeRouter
    participant Cluster as SwarmCluster
    participant Raft as Raft Store
    
    Client->>Router: PUT /volumes/myvol?version=10<br/>{Spec}
    Router->>Router: 检查 IsManager()
    Router->>Router: 解析 version
    Router->>Router: 解析 UpdateOptions
    Router->>Cluster: UpdateVolume(name, version, opts)
    Cluster->>Raft: 更新集群卷对象
    Raft-->>Cluster: ok
    Cluster-->>Router: ok
    Router-->>Client: 200 OK

func (v *volumeRouter) deleteVolumes(ctx context.Context, w http.ResponseWriter, r *http.Request, vars map[string]string) error {
    force := httputils.BoolValue(r, "force")
    
    // 1. 尝试删除本地卷
    err := v.backend.Remove(ctx, vars["name"], opts.WithPurgeOnError(force))
    
    // 2. 如果本地未找到，尝试删除集群卷
    if cerrdefs.IsNotFound(err) || force {
        version := httputils.VersionFromContext(ctx)
        if versions.GreaterThanOrEqualTo(version, "1.42") && v.cluster.IsManager() {
            err = v.cluster.RemoveVolume(vars["name"], force)
        }
    }
    
    if err != nil {
        return err
    }
    w.WriteHeader(http.StatusNoContent)
    return nil
}