LANraragi Docker容器中插件持久化存储方案解析

问题背景

在使用LANraragi Docker容器时，许多用户会遇到一个常见问题：当容器因版本升级或环境变量更新而需要重建时，所有手动上传的插件都会丢失。这是因为插件默认存储在容器内部的/home/koyomi/lanraragi/lib/LANraragi/Plugin目录中，该目录属于镜像的一部分，容器重建后会恢复为初始状态。

技术原理分析

Docker容器的文件系统具有临时性特点，任何对容器内文件的修改都会在容器删除后消失。LANraragi的插件系统原本将所有插件（包括用户上传的）都存储在容器内部，这不符合Docker最佳实践。

解决方案演进

1. 直接挂载整个插件目录：最初尝试将本地空目录挂载到插件目录会导致原始插件被覆盖，这不是可行方案。

2. 文件级挂载方案：可以单独挂载每个插件文件到容器内指定路径，但这种方法管理起来不够灵活，特别是当插件数量较多时。

3. 子目录挂载方案：更优雅的方式是创建一个专门用于用户插件的子目录（如User或Sideloaded），然后将这个子目录挂载到宿主机。这样既能保留系统默认插件，又能持久化用户自定义插件。

官方解决方案

项目维护者最终采纳了子目录挂载的方案，在插件目录下新增了Sideloaded专用目录，并在Dockerfile中将其声明为数据卷。这种设计带来了以下优势：

• 系统默认插件和用户插件分离管理
• 用户插件可以持久化存储
• 符合Docker数据管理的最佳实践
• 配置简单，易于维护

实施建议

对于使用Docker部署LANraragi的用户，建议采用以下方式配置插件持久化：

1. 在宿主机创建用于存储插件的目录
2. 启动容器时添加卷挂载参数：

   -v /宿主机/插件目录:/home/koyomi/lanraragi/lib/LANraragi/Plugin/Sideloaded
   

3. 将自定义插件直接放入挂载目录，或通过LANraragi界面上传（上传后插件会自动存入Sideloaded目录）

技术思考

这种解决方案体现了容器化应用中数据管理的典型模式：将需要持久化的数据与临时数据分离，通过卷挂载实现数据生命周期与容器生命周期的解耦。它不仅解决了插件丢失问题，还为后续的备份、迁移等运维操作提供了便利。

对于开发者而言，这也提示我们在设计容器化应用时，应该预先考虑哪些数据需要持久化，并通过合理的目录结构设计来支持这种需求。