符合 RFC 且支持 ESI 的 Nginx , OpenResty HTTP 缓存，由 Redis 支持.zip

# Ledge [](https://travis-ci.org/ledgetech/ledge) An RFC compliant and [ESI](https://www.w3.org/TR/esi-lang) capable HTTP cache for [Nginx](http://nginx.org) / [OpenResty](https://openresty.org), backed by [Redis](http://redis.io). Ledge can be utilised as a fast, robust and scalable alternative to Squid / Varnish etc, either installed standalone or integrated into an existing Nginx server or load balancer. Moreover, it is particularly suited to applications where the origin is expensive or distant, making it desirable to serve from cache as optimistically as possible. ## Table of Contents * [Installation](#installation) * [Philosophy and Nomenclature](#philosophy-and-nomenclature) * [Cache keys](#cache-keys) * [Streaming design](#streaming-design) * [Collapsed forwarding](#collapsed-forwarding) * [Advanced cache patterns](#advanced-cache-patterns) * [Minimal configuration](#minimal-configuration) * [Config systems](#config-systems) * [Events system](#events-system) * [Caching basics](#caching-basics) * [Purging](#purging) * [Serving stale](#serving-stale) * [Edge Side Includes](#edge-side-includes) * [API](#api) * [ledge.configure](#ledgeconfigure) * [ledge.set_handler_defaults](#ledgeset_handler_defaults) * [ledge.create\_handler](#ledgecreate_handler) * [ledge.create\_worker](#ledgecreate_worker) * [ledge.bind](#ledgebind) * [handler.bind](#handlerbind) * [handler.run](#handlerrun) * [worker.run](#workerrun) * [Handler configuration options](#handler-configuration-options) * [Events](#events) * [Administration](#administration) * [Managing Qless](#managing-qless) * [Licence](#licence) ## Installation [OpenResty](http://openresty.org/) is a superset of [Nginx](http://nginx.org), bundling [LuaJIT](http://luajit.org/) and the [lua-nginx-module](https://github.com/openresty/lua-nginx-module) as well as many other things. Whilst it is possible to build all of these things into Nginx yourself, we recommend using the latest OpenResty. ### 1. Download and install: * [OpenResty](http://openresty.org/) >= 1.11.x * [Redis](http://redis.io/download) >= 2.8.x * [LuaRocks](https://luarocks.org/) ### 2. Install Ledge using LuaRocks: ``` luarocks install ledge ``` This will install the latest stable release, and all other Lua module dependencies, which if installing manually without LuaRocks are: * [lua-resty-http](https://github.com/pintsized/lua-resty-http) * [lua-resty-redis-connector](https://github.com/pintsized/lua-resty-redis-connector) * [lua-resty-qless](https://github.com/pintsized/lua-resty-qless) * [lua-resty-cookie](https://github.com/cloudflare/lua-resty-cookie) * [lua-ffi-zlib](https://github.com/hamishforbes/lua-ffi-zlib) * [lua-resty-upstream](https://github.com/hamishforbes/lua-resty-upstream) *(optional, for load balancing / healthchecking upstreams)* ### 3. Review OpenResty documentation If you are new to OpenResty, it's quite important to review the [lua-nginx-module](https://github.com/openresty/lua-nginx-module) documentation on how to run Lua code in Nginx, as the environment is unusual. Specifcally, it's useful to understand the meaning of the different Nginx phase hooks such as `init_by_lua` and `content_by_lua`, as well as how the `lua-nginx-module` locates Lua modules with the [lua_package_path](https://github.com/openresty/lua-nginx-module#lua_package_path) directive. [Back to TOC](#table-of-contents) ## Philosophy and Nomenclature The central module is called `ledge`, and provides factory methods for creating `handler` instances (for handling a request) and `worker` instances (for running background tasks). The `ledge` module is also where global configuration is managed. A `handler` is short lived. It is typically created at the beginning of the Nginx `content` phase for a request, and when its [run()](#handlerrun) method is called, takes responsibility for processing the current request and delivering a response. When [run()](#handlerrun) has completed, HTTP status, headers and body will have been delivered to the client. A `worker` is long lived, and there is one per Nginx worker process. It is created when Nginx starts a worker process, and dies when the Nginx worker dies. The `worker` pops queued background jobs and processes them. An `upstream` is the only thing which must be manually configured, and points to another HTTP host where actual content lives. Typically one would use DNS to resolve client connections to the Nginx server running Ledge, and tell Ledge where to fetch from with the `upstream` configuration. As such, Ledge isn't designed to work as a forwarding proxy. [Redis](http://redis.io) is used for much more than cache storage. We rely heavily on its data structures to maintain cache `metadata`, as well as embedded Lua scripts for atomic task management and so on. By default, all cache body data and `metadata` will be stored in the same Redis instance. The location of cache `metadata` is global, set when Nginx starts up. Cache body data is handled by the `storage` system, and as mentioned, by default shares the same Redis instance as the `metadata`. However, `storage` is abstracted via a [driver system](#storage_driver) making it possible to store cache body data in a separate Redis instance, or a group of horizontally scalable Redis instances via a [proxy](https://github.com/twitter/twemproxy), or to roll your own `storage` driver, for example targeting PostreSQL or even simply a filesystem. It's perhaps important to consider that by default all cache storage uses Redis, and as such is bound by system memory. [Back to TOC](#table-of-contents) ### Cache keys A goal of any caching system is to safely maximise the HIT potential. That is, normalise factors which would split the cache wherever possible, in order to share as much cache as possible. This is tricky to generalise, and so by default Ledge puts sane defaults from the request URI into the cache key, and provides a means for this to be customised by altering the [cache\_key\_spec](#cache_key_spec). URI arguments are sorted alphabetically by default, so `http://example.com?a=1&b=2` would hit the same cache entry as `http://example.com?b=2&a=1`. [Back to TOC](#table-of-contents) ### Streaming design HTTP response sizes can be wildly different, sometimes tiny and sometimes huge, and it's not always possible to know the total size up front. To guarantee predictable memory usage regardless of response sizes Ledge operates a streaming design, meaning it only ever operates on a single `buffer` per request at a time. This is equally true when fetching upstream to when reading from cache or serving to the client request. It's also true (mostly) when processing [ESI](#edge-size-includes) instructions, except for in the case where an instruction is found to span multiple buffers. In this case, we continue buffering until a complete instruction can be understood, up to a [configurable limit](#esi_max_size). This streaming design also improves latency, since we start serving the first `buffer` to the client request as soon as we're done with it, rather than fetching and saving an entire resource prior to serving. The `buffer` size can be [tuned](#buffer_size) even on a per `location` basis. [Back to TOC](#table-of-contents) ### Collapsed forwarding Ledge can attempt to collapse concurrent origin requests for known (previously) cacheable resources into a single upstream request. That is, if an upstream request for a resource is in progress, subsequent concurrent requests for the same resource will not bother the upstream, and instead wait for the first request to finish. This is particularly useful to reduce upstream load if a spike of traffic occurs for expired and expensive content (since the chances of concurrent requests is higher on slower content). [Back to TOC](#table-of-contents) ### Advanced cach