How CasaOS Handles Storage Mount and Unmount Operations: A Deep Dive into the StorageService Architecture

CasaOS delegates all storage mount and unmount operations to a local rclone daemon via HTTP API calls, orchestrated through a centralized StorageService that manages mount points, configuration persistence, and automatic recovery.

CasaOS, an open-source home cloud system developed by IceWhaleTech, abstracts local folders and cloud drives behind a unified StorageService. Understanding how CasaOS handles storage mount and unmount operations reveals a clean architecture where Go-based service layers communicate with the underlying rclone filesystem daemon through a Unix socket. This design ensures that whether you are mounting a local directory or a remote cloud storage, the process follows the same HTTP-based API contract.

The StorageService Architecture

The StorageService defined in service/storage.go serves as the primary coordinator for all storage operations. It abstracts three core responsibilities: persisting remote storage configurations through methods like CreateConfig and DeleteConfigByName, querying current mount states via GetStorages, and executing the actual mount and unmount operations through MountStorage and UnmountStorage.

How Mount Operations Work

When CasaOS mounts a storage device, it follows a precise sequence that ensures the mount point exists before delegating the filesystem operation to rclone.

Preparing the Mount Point

The MountStorage method in service/storage.go (lines 27-30) first ensures the target directory exists by calling file.IsNotExistMkDir. This guarantees that the mount point is ready before any filesystem operations begin, preventing errors from rclone when attempting to mount to a non-existent path.

Communicating with the Rclone Daemon

After directory preparation, the service forwards the request to the httper layer located in pkg/utils/httper/drive.go. The httper.Mount function constructs a resty HTTP client that communicates with the local rclone daemon through the Unix socket at /var/run/rclone/rclone.sock. This client posts a form to the /mount/mount endpoint, passing the mount point, the remote filesystem string (e.g., drive:), and default mount options including AllowOther and CacheMode.

Mount Execution and Verification

When rclone successfully mounts the filesystem and returns a 200 status code, the httper.Mount function logs the response via logger.Info and returns nil to the caller. At this point, the storage is accessible at the specified mount point, and CasaOS updates its internal state to reflect the active mount.

How Unmount Operations Work

Unmounting storage follows a similar HTTP-based pattern but includes additional cleanup logic to maintain filesystem hygiene.

Sending the Unmount Command

The UnmountStorage method in service/storage.go (lines 31-38) delegates to httper.Unmount, which posts a form to the /mount/unmount endpoint on the same rclone Unix socket. The request contains only the mount point path, instructing rclone to detach the filesystem from the host.

Cleanup and Directory Removal

After receiving a successful response from rclone, CasaOS performs cleanup by checking if the mount directory is empty. If the directory contains no files, the system removes it using file.RMDir to prevent the accumulation of orphaned mount points. Any errors encountered during the rclone operation are propagated back to the caller for handling.

Automatic Mount Recovery

CasaOS provides automatic mount verification through the CheckAndMountAll and CheckAndMountByName methods in service/storage.go (lines 66-99). These helpers iterate over stored remote configurations retrieved via httper.GetAllConfigName (which calls /config/listremotes), compare them against the live mount list from httper.GetMountList (which calls /mount/listmounts), and invoke MountStorage for any missing mounts. This ensures that after system restarts or when new remotes are added, the corresponding filesystems are automatically mounted without manual intervention.

Implementation Details and Code Examples

The following Go snippets demonstrate how to interact with the storage service programmatically:

// Mount a cloud drive manually
err := MyService.Storage().MountStorage("/mnt/drive", "drive:")
if err != nil {
    // handle mount error
}

// Unmount a previously mounted storage
err = MyService.Storage().UnmountStorage("/mnt/drive")
if err != nil {
    // handle unmount error
}

// Ensure all configured storages are mounted (e.g., on startup)
if err = MyService.Storage().CheckAndMountAll(); err != nil {
    // log or retry
}

Behind these simple calls, the system persists storage metadata in the SQLite database using the Storage model defined in model/storage.go, which tracks fields such as MountPath, Driver, and Status. However, the actual filesystem operations are always performed by the rclone daemon via the HTTP API described above.

Summary

• CasaOS uses a StorageService in service/storage.go to abstract all storage operations behind a consistent Go interface.
• Actual mount and unmount operations are delegated to a local rclone daemon via HTTP requests to /mount/mount and /mount/unmount on a Unix socket at /var/run/rclone/rclone.sock.
• The system automatically creates mount point directories before mounting and removes empty directories after unmounting to maintain cleanliness.
• Automatic recovery ensures all configured storages are mounted on startup through CheckAndMountAll, which compares configured remotes against active mounts.
• Storage configurations and mount states are persisted in a SQLite database using the GORM model in model/storage.go.

Frequently Asked Questions

What daemon does CasaOS use to handle storage mounts?

CasaOS relies on the rclone daemon, which runs locally and exposes an HTTP API over a Unix socket at /var/run/rclone/rclone.sock. The CasaOS backend communicates with this daemon to perform actual filesystem mount and unmount operations.

How does CasaOS ensure mount points exist before mounting?

Before delegating to rclone, the MountStorage method in service/storage.go calls file.IsNotExistMkDir to create the directory if it does not already exist. This prevents rclone from failing when attempting to mount to a non-existent path.

What happens to the mount directory after unmounting?

After a successful unmount operation, CasaOS checks if the mount directory is empty. If it contains no files, the system automatically removes the directory using file.RMDir to prevent orphaned mount points from accumulating on the filesystem.

How does CasaOS handle storage mounts after a system restart?

The CheckAndMountAll method automatically runs on startup or can be called manually to verify all configured storage remotes. It retrieves the list of configured remotes via httper.GetAllConfigName, compares them against currently mounted filesystems using httper.GetMountList, and mounts any missing storages automatically.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}