LumenCache
| 开发者 |
nasruleam
celsiusanderson |
|---|---|
| 更新时间 | 2026年9月15日 18:14 |
| PHP版本: | 8.1 及以上 |
| WordPress版本: | 7.1 |
| 版权: | GPL-2.0-or-later |
| 版权网址: | 版权信息 |
详情介绍:
LumenCache implements a RAM-first full-page cache with a WordPress
advanced-cache.php drop-in. On a cache HIT, the drop-in serves complete HTML
before the normal WordPress bootstrap and database queries. This early-response
path reduces application-layer work and keeps repeat page requests fast across
Nginx, Apache, and LiteSpeed.
The cache is designed to fail open when its storage layer is unavailable, so a
cache connection problem does not take the WordPress site offline.
常见问题:
Getting a 502 Bad Gateway on Nginx after activating or during WooCommerce use?
Nginx has a default fastcgi_buffer_size of only 4KB–8KB. When combining rich caching headers with WooCommerce session cookies, the upstream response header exceeds this limit. Nginx immediately terminates the connection with:
upstream sent too big header while reading response header from upstream, resulting in an instant 502 Bad Gateway error.
To resolve this, add the following FastCGI and proxy buffer directives to your Nginx configuration (within the http {}, server {}, or PHP location block):
fastcgi_buffer_size 32k;
fastcgi_buffers 16 16k;
fastcgi_busy_buffers_size 32k;
proxy_buffer_size 32k;
proxy_buffers 16 16k;
proxy_busy_buffers_size 32k;
After adding these directives, test and reload Nginx:
nginx -t && systemctl reload nginx
Why are 0 pages cached?
Two common causes:
- Nginx config not applied — visit Server Setup and paste the config blocks.
- WooCommerce session cookie — fixed in v1.1.0. Previous versions bypassed
the cache for all visitors on WooCommerce sites due to the always-present
wp_woocommerce_session_*cookie.
Why can key salting affect server-level caching?
When LUMENCACHE_CACHE_SALT is set, PHP stores keys as SHA-256 hashes. A
server-level configuration must use the same key strategy or it will produce
cache misses. Disable the salt for a plain-key configuration, or use the
compatible hashed-key server template.
Does LumenCache work with LiteSpeed?
Yes. LiteSpeed supports Apache-compatible .htaccess rewrites. LumenCache uses
the Apache proxy mode on LiteSpeed. For better performance, ask your host
which in-memory cache acceleration options are available.
Can I still use wp-config.php constants?
Yes — constants always take precedence over admin settings. If you define a constant, the corresponding field in the Settings tab is shown locked (read-only).
更新日志:
1.6.34 (September 15, 2026)
- PRO COMPATIBILITY: Hardened
lumencache_is_pro_active()to verifydefined( 'LUMENCACHE_PRO_VERSION' ) && get_option( 'lumencache_pro_status' ) === 'active', preventing false positive status if the Pro add-on is deactivated or uninstalled. - CLOUDFLARE EDGE SYNC: Hooked
lumencache_purge_urlsinto single-URL purge operations (purge_url), ensuring Admin Bar "Purge This URL" and WP-CLIflush-urlactions automatically purge Cloudflare edge cache alongside local Redis. - APACHE & LITESPEED TELEMETRY: Added Pro hit-counter telemetry parity to the pre-bootstrap proxy (
server/lumen-cache-proxy.php) on cache HITs, and updatedDrop_In::write_config()to synchronize compiledpro_activestate to deployed proxy files. - ADMIN ACTIONS CONTEXT: Injected
from_tabretention to the Cloudflare purge form on the Cache Controls page, keeping administrators on their current tab after purging.
- ADMIN BAR: Added contextual "Purge This URL" sub-node when viewing frontend content, enabling instant single-URL cache invalidation directly from the toolbar without flushing the entire site.
- DASHBOARD WIDGET: Retained administrator on
wp-admin/index.phpafter flushing cache viaredirect_tohandling, complete with dismissible success notice and refined button hover styling. - WP-CLI: Enhanced
wp lumencache statuswith--formatsupport (table, json, yaml, csv) and drop-in /WP_CACHEstatus visibility; alignedflush-urloutput with semantic WP-CLI warning conventions. - REST API & HOLE-PUNCHING: Automated WooCommerce cart and session initialization (
wc_load_cart) during REST API user-state hydration requests; added LifterLMS course-progress resolution support. - REST API EXTENSIBILITY: Introduced
lumencache_user_state_keysandlumencache_resolve_user_state_{$key}filters for developer extensibility. - NONCE HARDENING: Supported both query parameter and
X-WP-Nonceheader authentication across REST user-state hydration and Admin Bar AJAX flush handlers.
- SETTINGS & CONNECTION TEST: Added native AJAX Redis connection testing (
lumencache_test_redis) supporting both phpredis and Predis drivers, Unix sockets, host/port, database indexes, connection timeouts, and authentication passwords. - UI & TAB NAVIGATION: Implemented seamless browser URL synchronization (
history.replaceState) on sidebar tab switches, preventing stale tab states across page reloads. - QUICK SETUP TRACKER: Enabled 1-click execution for Apache / LiteSpeed rewrite rule generation directly from the Quick Setup Tracker on the Overview tab, eliminating unnecessary navigation steps.
- ADMIN ACTION REDIRECTS: Added contextual
tabandfrom_tabstate retention across all admin actions (cache flushes, drop-in deployment, settings save, salt save, and rewrite operations), preserving the user's active view after every submission. - SETTINGS HARDENING: Enhanced password field handling to preserve special characters and ensured default namespace fallback (
cache:) when clearing key prefix. - SETTINGS CACHE: Added
Settings::reset_cache()method to reset in-process configuration memory.
- NGINX: Synchronized
nginx_map_block()and sample Nginx configurations withwp-postpass_andcomment_author_cookie bypass rules, preventing cached responses for unlocked password-protected posts and returning commenters. - APACHE & LITESPEED: Enhanced
.htaccessrewrite rules to directly exclude/feed/requests and XML sitemaps before proxy evaluation, avoiding unnecessary PHP execution overhead. - APACHE & LITESPEED: Added explicit
wp-postpass_andcomment_author_cookie rewrite conditions to.htaccessconfiguration. - PROXY DEPLOYMENT: Hardened
Htaccess::deploy_proxy()to verify and ensure target upload directory existence withwp_mkdir_p(). - PRE-BOOTSTRAP PROXY & DROP-IN: Aligned socket connection timeouts,
\Redis::OPT_READ_TIMEOUT, Predisread_write_timeout, andcomment_author_cookie bypass across bothserver/lumen-cache-proxy.phpandserver/advanced-cache.php.
- TIMEOUT: Added explicit connection and read timeouts for phpredis (
\Redis::OPT_READ_TIMEOUT) and Predis (read_write_timeout) to protect PHP worker processes from hanging on stalled Redis operations. - SOCKETS: Added explicit timeout to phpredis Unix socket connections and cleaned up TCP host/port parameters on Predis socket connections.
- LATENCY & QUERY OPTIMIZATION: Implemented in-memory memoization and transient caching for
key_count()to eliminate redundant full-keyspace SCAN operations across admin page views. - ARRAY SAFETY: Hardened
delete()anddelete_pattern()against PHP 8.1+ argument unpacking errors by guaranteeing integer-indexed array keys witharray_values(). - TELEMETRY: Standardized memory extraction in
memory_used()across both phpredis and Predis drivers for accurate RAM usage reporting. - RECONNECT: Added
reconnect()andget_prefix()helper methods toRedis_Connector.
- FIX: Protected logged-in sessions in Cookie Router (
clear_active_cookie()) when WooCommerce cart is emptied or subscriptions stop, ensuringsys_active_statecookie is preserved while user remains logged in. - FIX: Expanded WooCommerce bypass routes across early drop-in, proxy, and application drivers to include
/wc-api/to safeguard payment gateway callbacks and webhooks from being cached. - FIX: Hooked
woocommerce_variation_set_stockto immediately purge stale caches when variable product inventory levels are updated. - HARDENING: Dynamic cookie path and domain resolution in
send_cookie()with reverse proxy HTTPS detection viaHTTP_X_FORWARDED_PROTO.
- FIX: Added universal WordPress DONOTCACHEPAGE constant compliance in both bypass decision and shutdown write checks.
- FIX: Added contextual bypass checks in Cache_Engine for 404 pages, post draft previews, customizer previews, robots.txt, trackbacks, XML-RPC, and password-protected posts (
wp-postpass_cookie). - HARDENING: Added PHP fatal error detection (
error_get_last()) during output buffer capture to guarantee broken pages or fatal errors are never written to cache. - INVALIDATION: Added surgical invalidation for post status transitions (
transition_post_status) so unpublishing or trashing a post immediately clears its cached HTML from Redis. - INVALIDATION: Added post comment and review invalidation hooks (
comment_post,edit_comment,wp_set_comment_status,delete_comment,trashed_comment,spammed_comment) andcreated_term. - PERFORMANCE: Optimized post purging with batched multi-key Redis DEL execution and automated invalidation of all taxonomy archive URLs (categories, tags) associated with the updated post.
- REVERSE PROXY: Aligned HTTPS scheme detection across Cache_Engine, advanced-cache.php, and lumen-cache-proxy.php behind SSL-terminating reverse proxies.
- FIX: Synchronized pre-bootstrap Apache/LiteSpeed proxy (
lumen-cache-proxy.php) with complete feed bypass rules (/feed/and?feed=) to prevent XML feeds from caching as HTML. - FIX: Expanded XML sitemap bypass in both
advanced-cache.phpandlumen-cache-proxy.phpto cover core WordPress (wp-sitemap), standard sitemaps (sitemap_index), and paginated variants. - FIX: Automated compiled configuration snapshot synchronization into deployed
wp-content/uploads/lumen-cache-proxy.phpon file deployment and settings save.
- DOCS: Added Nginx 502 Bad Gateway troubleshooting FAQ and recommended 32KB FastCGI/Proxy buffer configuration directives.
- SERVER CONFIG: Updated Nginx global and per-site templates with 32k FastCGI and Proxy buffer directives to eliminate "upstream sent too big header" errors.
- UI: Added high-performance buffer configuration callout in Server Setup and Hosting Guide for Plesk and Nginx + PHP-FPM environments.
- PRO: Added Nginx FastCGI buffer size recommendation to Config Consistency Checker.
- FEATURE: Added mobile admin bar quick-action button adjacent to native new-content icon (hook priority 71) with responsive display on viewports <= 782px.
- UI: Integrated dashicons-performance tachometer icon inside a touch-friendly 46px target with live Redis connection indicator dot.
- UX: Implemented high-contrast, Apple-grade backdrop-blurred confirmation modal ("Clear All Cache?") to prevent accidental cache purges on touch devices.
- PERFORMANCE: Asynchronous non-blocking AJAX cache purge with spinning telemetry feedback, dynamic page count reset, and floating feedback toast notification.
- COMPATIBILITY: Tested and verified full compatibility with WordPress 7.1.
- PERFORMANCE: Verified pre-bootstrap drop-in execution, cache purging hooks, and REST API user-state endpoints on WordPress 7.1.
- SECURITY: Added explicit ABSPATH direct access guard to
server/lumen-cache-proxy.php. - IMPROVEMENT: Updated
Htaccess::deploy_proxy()to automatically configure localized ABSPATH definitions upon file deployment.
- COMPLIANCE: Full compliance with WordPress.org Guideline 5; streamlined UI with clean external Pro link.
- DROP-IN:
advanced-cache.phpis now completely self-contained with compiled configuration snapshot data. - SANITIZATION: Strict input and header sanitization against CRLF injection across all pre-bootstrap request paths.
- HOUSEKEEPING: Updated Plugin URI to point to the official Dev Lab page.
- FIX: Adjusted Quick Setup step flex rules in
assets/css/admin.cssto prevent connector lines from overlapping labels.
- FIX: Replaced WordPress functions in
lumen-cache-proxy.phpwith native PHP casts since the proxy runs pre-bootstrap. - FIX: Corrected root path calculation (
LUMENCACHE_PROXY_ABSPATH) for WordPressindex.phpandwp-config.phpinclusion.
- FIX: Added return value check on
$redis->auth()and$redis->select()inconnect_phpredis().
- PERF: Guarded debug string concatenation behind an explicit
LUMENCACHE_DEBUGcheck for zero production overhead.
- FIX: Replaced non-existent WordPress helper calls in
advanced-cache.phpwith native PHP casts and isset checks. - FIX: Corrected
enable_wp_cache()string replacement logic for reliableWP_CACHEinsertion intowp-config.php.
- FIX:
Lifecycle::uninstall()now flushes all Redis keys before removing plugin files. - FIX: Corrected connection source label in Settings for manually-entered host/port settings.
- SECURITY: Added direct file access protection via
ABSPATHcheck to all server drop-ins. - SANITIZATION: Sanitized all
$_SERVERinputs across pre-bootstrap request paths.
- FIX: Prevented RSS/Atom feeds from caching to avoid incorrect
Content-Type: text/htmlresponse headers. - FIX: Hardened URL sanitization in manual cache purge handler using
esc_url_raw().
- NEW: Built-in WooCommerce cart-fragments guard against crawler-triggered fragment storms.
- COMPLIANCE: Standardized update delivery on the official WordPress.org channel.
- DOCS: Added direct SSH installation instructions for Plesk in the Hosting Guide.
- NEW: Added RAM Cache Engine connectivity check to Quick Setup and introduced the Hosting Guide tab.
- IMPROVED: Quick Setup tracker review drawer for active, fully-configured sites.
- NEW: Added interactive 4-step Quick Setup progress tracker on the Overview tab.
- FIX: Aligned admin card headers and status badges across dashboard screens.
- SECURITY: Synchronized MemberPress session cookie matching across Nginx, Apache, and PHP drivers.
- FIX: Updated navigation references and doc comments for modular settings architecture.
- UX: Refined dashboard sidebar layout with dedicated feature navigation panels.
- CRITICAL: Added foreign drop-in protection to prevent overwriting existing third-party cache drop-ins.
- FIX: Aligned Redis timeout defaults and safety bypasses for dynamic/personal routes across all readers.
- FIX: Added non-HTML response rejection to prevent caching API/JSON payloads as HTML.
- IMPROVED: Refined update channel integration for WordPress.org directory hosting.
- UX: Instant click-to-show tabs across dashboard navigation.
- FIX: Fixed Admin Bar quick link URL routing.
- ARCHITECTURE: Split into clean Standard core with modular action/filter extensibility.
- UX: Single-page admin navigation shell with collapsible sidebar.
- FIX: Corrected LiteSpeed / OpenLiteSpeed server detection order.
- FIX: Added safe commented placeholders for salted Nginx configurations.
- NEW: Added Cloudflare edge cache purge integration support.
- NEW: Added cache telemetry diagnostics, bypass-reason counters, and connection test tooling.
- NEW: Automatic detection and bypass integration for XML sitemaps.
- NEW: Automatic application driver integration for educational courses and custom post types.
- COMPATIBILITY: Verified compatibility with WordPress 7.0 and PHP 8.5.
- FIX: Intelligent handling of all three
WP_CACHEstates inwp-config.phpand automated cleanup on deactivation.
- UX: Added context-aware validation for Nginx key salting configurations.
- UX: Context-aware badges in Security Hardening Matrix and direct key salt generator.
- FIX: Added tracking-parameter stripping to Apache proxy to maintain parity with PHP cache keys.
- CRITICAL: Fixed phpredis
SCANcursor handling inkey_count()anddelete_pattern().
- FIX: Automated stripping of 14 marketing tracking query parameters (Google Shopping, Meta Ads, etc.).
- FIX: Added connection return validation in
connect_phpredis()and refined Unix socket handling.
- FIX: Output buffering rebuild for PHP-FPM and Nginx FastCGI environments.
- NEW: Standalone
advanced-cache.phpdrop-in deployment with zero server configuration requirements.
- NEW: Admin settings interface, Admin Bar menu, and WP Dashboard widget.
- FIX: Resolved WooCommerce session cookie over-bypass for dramatic cache hit rate improvements.
- Initial public release.