Docker 上の Paperless-ngx が起動しなくなった原因と復旧方法（rclone プラグインの無効化）

自宅サーバで Docker アプリとして運用している Paperless-ngx に、ある日突然アクセスできなくなりました。
Portainer からスタックを再起動しようとするとエラーで失敗し、サービスが起動できない状態に陥りました。
本記事では、トラブル発生から復旧までの手順を記録します。

発生状況

ブラウザから Paperless-ngx にアクセスすると接続エラー。
Portainer の管理画面から stack を停止・再起動しようとしたところ、以下のエラーメッセージが表示されました。

Failed to deploy a stack: compose up operation failed: 
Error response from daemon: get paperless-ngx_media: 
error while checking if volume "paperless-ngx_media" exists in driver "rclone:latest": 
error looking up volume plugin rclone:latest: plugin rclone:latest found but disabled

環境構成

Paperless-ngx を docker-compose.yml でデプロイしており、media / export / consume ボリュームに rclone volume plugin を利用して OneDrive をマウントしています。

volumes:
  media:
    driver: rclone
    driver_opts:
      remote: "onedrive:paperless/media"
      allow_other: "true"
      vfs_cache_mode: "full"
      poll_interval: 0

原因の調査

エラーメッセージを読むと、

plugin rclone:latest found but disabled

とあり、rclone プラグイン自体は存在するが disabled 状態 であることがわかりました。
Docker プラグインの状態を確認します。

docker plugin ls

出力例：

ID                  NAME                DESCRIPTION               ENABLED
abcd1234abcd        rclone:latest       Rclone Volume Plugin      false

やはり ENABLED が false になっています。
Docker プラグインはホスト再起動や Docker デーモン再起動の際に無効化されることがあるようです。

復旧方法

プラグインを有効化すればスタックは正常に起動できました。

docker plugin enable rclone:latest

その後、Portainer からスタックを再デプロイすると成功し、Paperless-ngx にブラウザからアクセスできるようになりました。

docker plugin enable

再発防止のポイント

プラグインの有効化状態を確認する
- 障害発生時はまず docker plugin ls で ENABLED が true になっているか確認。
Docker 再起動後の挙動に注意
- プラグインは再起動を契機に無効化されることがある。
代替運用方法
- より安定させたい場合は docker plugin を使わず、rclone mount を systemd サービスで常時マウントし、コンテナには bind mount で渡す方法も検討可能。

まとめ

Paperless-ngx のスタックが起動しなくなった原因は rclone プラグインが disabled 状態になっていたこと。
docker plugin enable rclone:latest で再有効化すれば復旧できた。
Docker プラグインを利用する場合、再起動時の無効化に注意が必要。

succi0303 blog

This is my personal blog. All posts are my own.