Audit Files

Allows for comparing and correcting files and file references in the files directory, in the database, and in content.

auditfiles
4,265 sites
61
drupal.org
gui utility
file management audit maintenance cleanup database orphan files file integrity administration
Drupal 10 Drupal 11

インストール

Drupal 11, 10 v4.2.4
composer require 'drupal/auditfiles:^4.2'

概要

Audit Filesモジュールは、サーバー上のファイルとDrupalサイトで使用されているファイルの同期を維持するのに役立ちます。サーバーのファイルシステム上のファイル、file_managedデータベーステーブルのエントリ、file_usageテーブル、コンテンツエンティティ内のファイルフィールド参照を比較する7つの包括的なレポートを提供します。

このモジュールは、既存の問題を修正しようとする際に追加の問題を発生させないよう、ファイルとその参照を扱う際に意図的にDrupal File APIの使用を避けています。Drupal Batch APIを使用して操作を効率的に実行し、サーバー負荷を軽減し、大規模なファイルシステムでのタイムアウトを防ぎます。

発見された各不整合に対して、管理者はデータベースへのファイル追加、サーバーからの孤立ファイルの削除、古いデータベースエントリの削除、重複ファイル参照の単一ファイルエンティティへの統合などの修正アクションを実行できます。

Features

  • ファイルシステム、file_managedテーブル、file_usageテーブル、コンテンツ参照を横断して比較する7つの監査レポート
  • データベースに未登録レポート：file_managedデータベーステーブルで追跡されていないサーバー上のファイルを一覧表示し、データベースへの追加またはサーバーからの削除オプションを提供
  • サーバーに存在しないレポート：データベースに登録されているがファイルシステムに存在しないファイルを一覧表示し、データベースエントリの削除が可能
  • 管理対象で未使用レポート：file_usageテーブルに対応するエントリがないfile_managed内のファイルを表示
  • 使用中で管理対象外レポート：対応するファイルエンティティがfile_managedに存在しないfile_usageエントリを一覧表示
  • 使用中で未参照レポート：コンテンツフィールドから参照されなくなったfile_usage内のファイルを表示
  • 参照中で未使用レポート：対応するfile_usageエントリがないコンテンツフィールド内のファイル参照を表示し、使用レコードの追加または参照の削除オプションを提供
  • ファイル参照統合レポート：file_managed内の重複ファイル名を識別し、複数のファイルエンティティを単一の正規ファイルに統合可能
  • 大規模データセットでのタイムアウトを防ぐためのすべての操作のバッチ処理
  • ファイル、拡張子、パスの設定可能な除外フィルター
  • パフォーマンス最適化のための設定可能なレコード制限とページネーション
  • イベントサブスクライバーを通じてファイル操作のカスタマイズを可能にするイベント駆動アーキテクチャ

Use Cases

Cleaning up after content migration

After migrating content from another CMS or Drupal version, use the 'Not in database' report to identify and register files that were copied to the server but not tracked by Drupal. Add them to the database to make them available for use in content.

Removing orphaned files to free disk space

Over time, files may accumulate on the server from deleted content or failed uploads. Use the 'Not in database' report to find these orphaned files and delete them to reclaim disk space.

Fixing broken images and downloads

When content displays broken images or downloads fail, use the 'Not on server' report to identify files registered in the database but missing from the file system. Either restore the files or clean up the database entries.

Database cleanup after module uninstallation

When modules are uninstalled without proper cleanup, they may leave orphaned entries in file_usage. Use 'Used not managed' to find and remove these stale usage records.

Consolidating duplicate file uploads

When users upload the same file multiple times creating duplicates, use the 'Merge file references' report to identify files with the same name and merge them into a single entity, updating all references automatically.

Verifying file integrity after server migration

After moving a site to a new server, run all reports to verify that the file system and database are in sync. This helps identify any files that were not properly copied during migration.

Auditing file_usage table consistency

Use 'Used not referenced' and 'Referenced not used' reports to ensure the file_usage table accurately reflects actual content references. Fix discrepancies to maintain database integrity.

Tips

  • Always back up your database and files directory before performing delete or merge operations
  • Start with small batches when deleting files to verify the correct items are selected
  • Use exclusion settings to skip system-generated directories like css, js, and image style derivatives
  • For large sites, set a reasonable maximum records limit (250-500) to prevent timeouts during initial page load
  • The batch processing button appears when the maximum records limit is reached, allowing full dataset access without timeouts
  • Review the 'Managed not used' report carefully - some unused files may be intentional (e.g., placeholder images, temporary uploads)

Technical Details

Admin Pages 9
Audit Files /admin/config/system/auditfiles

Configure global settings for all Audit Files reports including file system paths, exclusion rules, domain handling, and report display options.

Audit Files /admin/reports/auditfiles

Main landing page for all Audit Files reports. Provides links to seven specialized audit reports for analyzing and correcting file discrepancies.

Not in database /admin/reports/auditfiles/notindatabase

Lists files that exist on the server's file system but are not tracked in the file_managed database table. These may be orphan files whose parent content was deleted, files from modules that did not clean up properly, or files uploaded outside of Drupal (e.g., via FTP). The report shows file pathname, MIME type, size, and last modified date.

Not on server /admin/reports/auditfiles/notonserver

Lists files that have entries in the file_managed database table but do not exist on the server's file system. These missing files may cause broken images, failed downloads, or other display issues in content.

Managed not used /admin/reports/auditfiles/managednotused

Lists files that exist in the file_managed database table but have no entries in the file_usage table. This is often normal for temporary files or files awaiting garbage collection. Review to verify expected behavior.

Used not managed /admin/reports/auditfiles/usednotmanaged

Lists entries in the file_usage table where the corresponding file entity does not exist in file_managed. These are orphaned usage records referencing non-existent files.

Used not referenced /admin/reports/auditfiles/usednotreferenced

Lists files that have entries in the file_usage table but are no longer referenced in the content that supposedly uses them. The file field in the content entity no longer contains a reference to the file.

Referenced not used /admin/reports/auditfiles/referencednotused

Lists file references found in file fields attached to content entities that do not have corresponding entries in the file_usage table. These references should normally be tracked in file_usage.

Merge file references /admin/reports/auditfiles/mergefilereferences

Lists all files in file_managed grouped by filename, showing potential duplicates. Allows merging multiple file entities that have the same filename into a single canonical file, consolidating usage records and saving disk space.

権限 2
Configure Audit Files module

Allows users to configure the Audit Files module settings such as file system paths, exclusions, and report options. This permission is marked as restricted.

Access Audit Files reports

Allows users to access the Audit Files reports and perform audit actions like adding, deleting, and merging files.

Troubleshooting 4
Warning: POST Content-Length exceeds limit / Cannot modify header information

Set a lower 'Maximum records' value in the Audit Files configuration page, then use the 'Load all records' button on the report page to batch process the data.

Fatal error: Maximum execution time exceeded

Set a lower 'Maximum records' value to limit the initial query. The batch processing feature will load remaining records without hitting PHP timeout limits.

Reports are slow or timing out

Configure appropriate exclusion paths for directories with many files that don't need auditing (e.g., css, js, styles). Reduce items per page and maximum records settings.

Files deleted but still appearing in reports

Clear Drupal's cache after making changes. The module queries the database directly, but cached data might cause stale displays.

Security Notes 4
  • The 'configure audit files reports' permission is marked as restricted access due to the potential impact of misconfiguration
  • Delete operations are permanent and cannot be undone - verify selections carefully before confirming
  • Merging files updates references across all content - ensure the canonical file choice is correct
  • Consider restricting access to these reports to trusted administrators only, as they provide detailed information about the file system