When migrating from local disk to S3 storage, which existing data needs to be migrated?

[kevin9121020]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
• Please do not modify this template :) and fill in all the required fields.

Content

For a Docker-deployed Dify instance that previously used local disk as storage and now switches to S3 storage: the original primary storage directory /app/api/storage contains subdirectories such as image_files, privkeys, tools, upload_files and website_files; the plugin storage directory /app/storage contains subdirectories including assets, cwd, persistence, plugin and plugin_packages. Do all these directories need to be migrated to S3 storage? If only part of them is migrated, will data be lost when the container is reconstructed?

[dosubot[bot]]

Yes, you need to migrate all data under both /app/api/storage (including image_files, privkeys, tools, upload_files, website_files, etc.) and /app/storage (assets, cwd, persistence, plugin, plugin_packages, etc.) to S3. These directories contain user uploads, keys, plugin files, and other essential runtime data. If you only migrate part of them, any files left behind on the old disk will be lost when the containers are rebuilt, which can break uploads, plugins, or other features that depend on those files being present details & migration command Docker storage config reference.

To migrate, use the flask migrate-oss command. Make sure to back up all persistent storage (including Docker volumes and your .env) before starting. For plugins, ensure they are present in the S3 bucket in the correct structure—if not, you may need to manually upload or reinstall them after migration plugin S3 details.

Partial migration will result in data loss and operational failures for any missing files or directories.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[kevin9121020]

@dosu Should the primary storage and plugin storage use the same storage bucket, or separate ones? Also, please clarify the directory structure of primary storage and plugin storage in the S3 storage buckets.

[dosubot[bot]]

You can use either the same S3 bucket or separate ones for primary storage and plugin storage in Dify. The default and most common setup is to use a single S3 bucket for both, with logical separation by directory prefixes—primary storage files are stored under paths like /app/api/storage (with subdirectories such as image_files, privkeys, tools, upload_files, website_files), and plugin storage under /app/storage (with subdirectories like assets, cwd, persistence, plugin, plugin_packages) example config & structure.

If you want to use separate buckets, set PLUGIN_STORAGE_OSS_BUCKET to a different value than S3_BUCKET_NAME in your environment variables plugin S3 config reference. There’s no technical requirement to separate them—choose based on your organization’s needs for isolation or access control. The directory structure in S3 will mirror your local paths, so after migration, you’ll see objects like /app/api/storage/upload_files/... and /app/storage/plugin_packages/... in your bucket(s) plugin storage details.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[kevin9121020]

@dosu What data is stored in the plug-in storage directories such as assets, cwd, persistence, plugin, and plugin_packages? Why do the cwd directory and plugin-related files continue to be generated locally after the data has been migrated to S3 storage?

[dosubot[bot]]

Here's what each plugin storage directory is for:

• assets: stores plugin media cache, like images or files used by plugins.
• cwd: is the working directory for plugin execution. It holds runtime files, temporary data, and virtual environments (such as .venv folders and Python packages) that plugins need to run. These files are generated and used locally during plugin startup and execution, regardless of S3 migration cite.
• persistence: keeps persistent plugin data, such as plugin-specific state or configuration that needs to survive restarts.
• plugin: contains installed plugin code.
• plugin_packages: caches plugin packages for faster startup and reuse.

Even after migrating persistent storage to S3, the cwd directory and some plugin-related files continue to be generated locally because plugin execution requires a local working directory for runtime operations, unpacking packages, and managing dependencies. The plugin daemon is designed to use these local paths for immediate execution and isolation, so not all runtime files are redirected to S3 cite cite.

If you want to minimize local file generation, you can adjust the plugin daemon's environment variables (like PLUGIN_STORAGE_TYPE and related path settings), but some runtime files—especially those in cwd—will always be created locally for plugin execution.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}