UploadSleuth – Media Audit & Cleanup
| 开发者 | eboxnet |
|---|---|
| 更新时间 | 2026年9月15日 02:46 |
| PHP版本: | 7.4 及以上 |
| WordPress版本: | 7.1 |
| 版权: | GPLv3 or later |
| 版权网址: | 版权信息 |
详情介绍:
UploadSleuth reconciles files in the uploads directory against WordPress attachment metadata and database references.
Files without a detected reference are shown as likely stray candidates. They are not declared safe to delete. The plugin encourages a review, dry-run, and quarantine workflow before permanent removal.
Features
- AJAX-powered dashboard under Tools > UploadSleuth.
- Scan summaries including candidate count and potential disk space.
- Persistent storage-impact statistics for reclaimed space and completed cleanup actions.
- Search, sorting, bulk selection, and per-user saved results.
- Dry-run, timestamped quarantine, verified backup-and-remove, and guarded deletion.
- Recognition of attachment originals, generated sizes, edited originals, and backups.
- Checks for references in posts, metadata, options, and configured custom tables.
- Optional non-core database table scanning.
- WP-CLI table, CSV, JSON, and YAML output.
- CLI age and size filters, CI mode, and explicit permanent-delete confirmation.
- Complete in-dashboard WP-CLI reference with copy-ready recipes.
- Optional last-moment attachment and database revalidation, enabled by default.
- Configurable scan/action batches and pauses for slow servers.
- WordPress-native standalone-file deletion through
wp_delete_file(). - Stoppable batched scans that preserve reviewed partial findings.
- Separate Media Library integrity checks for missing originals and generated image sizes.
- WordPress-native cleanup of reviewed missing-file attachment records.
- No external service or telemetry.
安装:
- Upload the
upload-sleuthdirectory to/wp-content/plugins/. - Activate UploadSleuth through the Plugins screen.
- Open Tools > UploadSleuth.
- Configure ignore patterns or custom table checks if needed.
- Begin with a narrow subdirectory scan.
常见问题:
Does a finding mean the file is safe to delete?
No. A finding means the plugin did not detect a reference in the locations it checked. Treat it as a candidate requiring review.
What does quarantine do?
Quarantine moves selected files into a timestamped directory below the configured quarantine folder while preserving their original relative paths. The quarantine directory is excluded from future scans.
Can I restore a quarantined file?
Yes. The Quarantined files panel lists recoverable files and restores each one to its original uploads path. Restore is blocked rather than overwriting a file that already exists there. The same panel can permanently delete selected quarantined files or all recoverable quarantined files. Downloadable backup ZIPs are not included in Delete all.
What does Download ZIP & remove do?
The dashboard and WP-CLI create one ZIP, verify every archived entry using its size and SHA-256 hash, and only then remove the originals. The dashboard starts an authenticated download; WP-CLI reports the protected server-side archive path.
Can I preview an action?
Yes. Dry-run is an opt-in checkbox in the dashboard. WP-CLI supports --dry-run with quarantine or deletion.
Can I stop a long scan?
Yes. Dashboard scans process database candidates in small batches. Stop finishes the current request, saves everything classified through the latest completed batch, and marks the result as partial. Unprocessed candidates are not included in partial findings.
Does it support ACF?
ACF commonly stores values in post, term, user, and options metadata. Those locations are checked. Unusual custom tables can be configured explicitly.
What is the WP-CLI command?
Run wp upload-sleuth. Use wp help upload-sleuth for all options.
How do I inspect older, larger candidates only?
Use wp upload-sleuth --older-than=90 --min-size=100 to report candidates older than 90 days and at least 100 KB.
Can the command be used in automation?
Yes. --summary-only --fail-on-findings provides a concise result and a non-zero exit when candidates exist.
Does the plugin send data elsewhere?
No. Scanning and file operations run locally within WordPress.
Can it find Media Library records whose files are missing?
Yes. The Library integrity tab checks attachment records in batches. It reports missing local originals and, separately, generated sizes that are absent while the original exists. Missing-original records can be deleted individually or all at once after confirmation; cleanup uses WordPress wp_delete_attachment() rather than direct database queries.
Sites using S3, CDN, or another media-offload plugin require special care. A valid remote attachment may intentionally have no local file, so confirm the remote object and offload configuration before deleting a reported record.
更新日志:
1.1.0
- Added animated WP-CLI progress output for interactive scans.
- Added resumable scan checkpoints with
--state-file,--resume, and--clear-state. - Added JSON report export with
--save-reportand secure dashboard import for review. - Documented all new CLI workflows in the dashboard and project documentation.
- Added detailed
upload_sleuth_*lifecycle hooks for notification integrations. - Added configurable batch tuning, visible ignore patterns, and improved admin action feedback.
- Removed automatic legacy-option migration to prevent namespace conflicts.
- Renamed internal constants and PHP package annotations to match the UploadSleuth brand.
- Added a WordPress-native uninstall routine that removes UploadSleuth options and temporary scan data while preserving user files and backup archives.
- Renamed the Tools menu entry to Media Audit for clearer administration.
- Updated the directory description with related developer project and source links.
- Added the validated WordPress Playground Blueprint for the public Live Preview.
- Renamed the plugin to UploadSleuth – Media Audit & Cleanup and changed the public slug, text domain, package, dashboard URL, and WP-CLI command to
upload-sleuth. - Limited quarantine, restore, backup, and delete actions to file types recognised by WordPress;
--all-filesnow expands reporting only. - Replaced WP-CLI backup trees with verified ZIP archives.
- Moved runtime storage below
uploads/upload-sleuth, added direct-access protection files, and stored quarantined files with a non-executable suffix. - Blocked symbolic links from quarantine and restore operations.
- Matched the Settings tab width to the other UploadSleuth sections.
- Expanded the How it works guide with scan stages, result meanings, action guidance, and a pre-cleanup checklist.
- First stable public release of UploadSleuth.
- Added uploads auditing with attachment and database-reference checks.
- Added stoppable AJAX scans, saved partial results, filtering, sorting, and batched actions.
- Added quarantine, guarded restoration, verified ZIP backup and removal, and permanent cleanup tools.
- Added Media Library integrity checks for missing originals and generated files.
- Added slow-server controls, cleanup statistics, WP-CLI workflows, and developer documentation.
- Passed WordPress coding standards, PHP 7.4 compatibility, and Plugin Check new-submission validation.
- Applied the WordPress PHP Coding Standards throughout the plugin.
- Completed PHPDoc parameter and return documentation for every PHP function and method.
- Documented narrowly scoped database and filesystem exceptions used for safe batching, atomic moves, and streamed ZIP verification.
- Hardened AJAX array unslashing and sanitization while retaining server-owned finding validation.
- Modernized and formatted dashboard JavaScript and CSS using the official WordPress lint configurations.
- Added current WordPress compatibility and release metadata for directory submission.
- Allowed safe filenames containing consecutive dots.
- Kept traversal protection for actual current-directory and parent-directory path segments.
- Unified the corrected path rule across dashboard and WP-CLI workflows.
- Added consistent spacing above section-level notices.
- Fixed Delete all validation across batched requests.
- Preserved whole-result authorization while keeping genuine per-batch progress.
- Chunked large saved finding sets to avoid object-cache item-size failures.
- Removed repeated full-result payloads and full-result rewrites during file actions.
- Added a clear message when saved server findings have expired.
- Moved AJAX success, warning, and error notices into their related scan, quarantine, integrity, or CLI section.
- Added reliable dismiss controls for notices created after page load.
- Added a Library integrity tab for missing local attachment originals and generated sizes.
- Added batched progress, cooperative stopping, saved partial findings, and incremental rendering.
- Added selected/all attachment-record cleanup through
wp_delete_attachment()with immediate original rechecks. - Added explicit media-offload warnings and accurate statistics for generated files removed by WordPress.
- Reduced repeated AJAX payload size during large integrity checks.
- Aligned settings checkboxes with their first text line.
- Added incremental findings and action-report rendering with Load more controls.
- Added a configurable rows-per-view setting, defaulting to 250.
- Debounced result filtering and reduced DOM layout/paint work.
- Kept complete datasets available for whole-result actions without rendering every row.
- Avoided duplicating the complete findings array during ordinary renders.
- Added opt-in browser console diagnostics, disabled by default.
- Disabled heartbeat timers and diagnostic payload construction while logging is off.
- Capped enabled file-action console samples at 100 rows.
- Moved Storage Impact above the scan controls.
- Kept cleanup statistics hidden until tracked activity exists.
- Constrained large per-file reports to a keyboard-accessible fixed-height scroll area.
- Added a visible action-result count.
- Batched delete, Delete all, and quarantine actions with genuine progress.
- Added scan batch, file-action batch, and inter-batch pause settings.
- Made last-moment reference revalidation optional but enabled by default.
- Kept saved-finding and path validation active when revalidation is disabled.
- Added inline operation progress for all dashboard filesystem actions.
- Added dedicated progress feedback for quarantine loading, restore, and selected/all deletion.
- Displayed queued file counts without fabricating percentages for one-request operations.
- Added accessible busy/live states without moving the viewport.
- Added a persistent Storage Impact dashboard section.
- Counted reclaimed bytes only after successful permanent removal.
- Added cumulative permanent-removal, quarantine, and restore counters.
- Included quarantine cleanup in reclaimed-space totals.
- Fixed HTML-escaped query separators causing valid ZIP downloads to reach a missing/invalid endpoint.
- Added Delete all findings for the complete saved result set.
- Added quarantine selection plus permanent Delete selected and Delete all controls.
- Excluded ZIP and CLI backup artifacts from quarantine deletion.
- Used WordPress-native file deletion with explicit confirmations for quarantine cleanup.
- Replaced the browser-blocked hidden-frame ZIP transfer with a named attachment download.
- Made dashboard dry-run opt-in; destructive removal actions still require confirmation.
- Isolated ZIP downloads so they cannot move or navigate the admin page.
- Preserved timestamped UploadSleuth archive filenames instead of the download endpoint name.
- Added an in-dashboard quarantine inventory with guarded one-click restoration.
- Blocked restoration when the original uploads path is already occupied.
- Clarified quarantine behavior beside the file actions.
- Prevented notices, focused buttons, and progress visibility from moving the viewport during actions.
- Changed the dashboard backup action to create and automatically download one verified ZIP before removing originals.
- Added an authenticated, short-lived, current-user-only archive download endpoint.
- Prevented file-action controls and results rerendering from jumping the page to the top.
- Kept the existing WP-CLI verified backup-directory behavior.
- Refined dashboard hierarchy, spacing, responsive controls, progress treatment, and results table.
- Added clear Live, Partial, Limited, and Complete result states with accurate live metric labels.
- Replaced absolute scan paths with concise uploads-relative scope labels.
- Kept filtering, sorting, and row selection usable during batched scans.
- Fixed sticky table headers bleeding into result rows and improved progress accessibility.
- Added complete PHPDoc to the admin controller and scan-job helpers.
- Documented JavaScript batching, cancellation, race handling, and trust boundaries.
- Added a developer architecture guide covering state, safety invariants, and extension hooks.
- Converted dashboard reference checks to persistent batches of 25 candidates.
- Added live candidate counts and percentage progress.
- Added Stop scan with saved, clearly marked partial findings.
- Allowed dry-run and quarantine review against stopped results.
- Added race-safe stop markers and 30-minute per-user scan jobs.
- Revalidate attachment metadata and database references immediately before every action.
- Block files that became referenced after the scan.
- Use WordPress
wp_delete_file()for standalone-file removal. - Added lifecycle hooks for quarantine, backup-and-remove, and deletion.
- Excluded UploadSleuth's own settings and transients from reference matching.
- Added a CLI Reference dashboard tab.
- Documented every plugin command option and common global WP-CLI parameters.
- Added one-click copying for complete command recipes.
- Added verified Backup & remove actions to the dashboard and WP-CLI.
- Added live browser-console scan heartbeats and final diagnostic summaries.
- Added WP-CLI inventory, reference-index, and database-check progress messages.
- Rebuilt the admin experience with AJAX scanning and file actions.
- Added result summaries, filtering, sorting, persistent findings, and action reports.
- Added size and age CLI filters, summary-only and CI modes, guarded deletion, and richer metrics.
- Hardened path validation and excluded quarantine files from future scans.
- Added comprehensive project and WordPress.org documentation.
- Initial release.