Skip to content

Commit 56e7be6

Browse files
yaoge123yaoge123
committed
docs: align README files with current release line
1 parent f2f8cc7 commit 56e7be6

2 files changed

Lines changed: 105 additions & 48 deletions

File tree

‎README.md‎

Lines changed: 97 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,12 @@ matches the purge request.
4545
| nginx | status |
4646
|--------|------------|
4747
| 1.20.x | ✓ tested |
48+
| 1.22.x | ✓ tested |
49+
| 1.24.x | ✓ tested |
4850
| 1.26.x | ✓ tested |
4951
| 1.28.x | ✓ tested |
50-
| 1.29.x | ✓ tested |
52+
| latest stable | ✓ tested |
53+
| latest mainline | ✓ tested |
5154

5255
Older releases back to 1.7.9 compile but are not covered by CI.
5356

@@ -388,68 +391,79 @@ The module automatically sets `$cache_purge_refresh_bypass` for refresh
388391
subrequests so validation reaches upstream instead of being satisfied by the
389392
local cache.
390393

391-
The cache key must end with the URI portion, for example
392-
`$uri$is_args$args`, so refresh can reconstruct the upstream request target
393-
from cached keys.
394-
395-
server {
396-
location / {
397-
proxy_pass http://127.0.0.1:8000;
398-
proxy_cache tmpcache;
399-
proxy_cache_key "$scheme$host$request_uri";
400-
proxy_cache_bypass $cache_purge_refresh_bypass;
401-
proxy_no_cache $cache_purge_refresh_bypass;
402-
}
403-
404-
location ~ /purge(/.*) {
405-
allow 127.0.0.1;
406-
deny all;
407-
proxy_cache_purge tmpcache $scheme$host$1$is_args$args;
408-
}
409-
410-
location ~ /refresh(/.*) {
411-
allow 127.0.0.1;
412-
deny all;
413-
proxy_pass http://127.0.0.1:8000;
414-
proxy_cache_bypass $cache_purge_refresh_bypass;
415-
proxy_no_cache $cache_purge_refresh_bypass;
416-
proxy_cache_refresh tmpcache $scheme$host$1$is_args$args;
417-
cache_purge_refresh_timeout 60s;
418-
cache_purge_refresh_concurrency 32;
419-
}
394+
Refresh only works when the evaluated cache key keeps the request-target tail
395+
unambiguous. Safe shapes include keys that are already the request path (for
396+
example `$uri$is_args$args` or `$request_uri`), keys whose tail still clearly
397+
preserves the URI / request-URI portion (for example `$host$request_uri`,
398+
`$scheme$host$request_uri`, or `$host$uri$is_args$args`), and exact literal-path
399+
keys such as `proxy_cache_key /dir01/file1.txt;`.
400+
401+
Recommended separate-endpoint layout:
402+
403+
```nginx
404+
http {
405+
proxy_cache_path /tmp/cache keys_zone=tmpcache:10m;
406+
407+
server {
408+
location / {
409+
proxy_pass http://127.0.0.1:8000;
410+
proxy_cache tmpcache;
411+
proxy_cache_key "$scheme$host$request_uri";
412+
proxy_cache_bypass $cache_purge_refresh_bypass;
413+
proxy_no_cache $cache_purge_refresh_bypass;
414+
}
415+
416+
location ~ /purge(/.*) {
417+
allow 127.0.0.1;
418+
deny all;
419+
proxy_cache_purge tmpcache $scheme$host$1$is_args$args;
420+
}
421+
422+
location ~ /refresh(/.*) {
423+
allow 127.0.0.1;
424+
deny all;
425+
proxy_pass http://127.0.0.1:8000;
426+
proxy_cache_bypass $cache_purge_refresh_bypass;
427+
proxy_no_cache $cache_purge_refresh_bypass;
428+
proxy_cache_refresh tmpcache $scheme$host$1$is_args$args;
429+
cache_purge_refresh_timeout 600s;
430+
cache_purge_refresh_concurrency 32;
420431
}
421432
}
422433
}
423434
```
424435

425-
Gradual migration layout: keep one entry directive and migrate clients by switching
426-
HTTP method first. Exact and partial requests already route by method.
436+
Gradual migration layout: keep one entry directive and migrate clients by
437+
switching HTTP method first. Exact and partial requests already route by
438+
method.
427439

428-
http {
429-
proxy_cache_path /tmp/cache keys_zone=tmpcache:10m;
440+
```nginx
441+
http {
442+
proxy_cache_path /tmp/cache keys_zone=tmpcache:10m;
430443
431-
server {
432-
location / {
433-
proxy_pass http://127.0.0.1:8000;
434-
proxy_cache tmpcache;
435-
proxy_cache_key "$host$request_uri";
436-
proxy_cache_bypass $cache_purge_refresh_bypass;
437-
proxy_no_cache $cache_purge_refresh_bypass;
438-
proxy_cache_purge PURGE from 127.0.0.1;
439-
}
444+
server {
445+
location / {
446+
proxy_pass http://127.0.0.1:8000;
447+
proxy_cache tmpcache;
448+
proxy_cache_key "$host$request_uri";
449+
proxy_cache_bypass $cache_purge_refresh_bypass;
450+
proxy_no_cache $cache_purge_refresh_bypass;
451+
proxy_cache_purge PURGE from 127.0.0.1;
440452
}
441453
}
454+
}
455+
```
442456

443457
In that layout:
444458

445459
- `PURGE /path/file` performs purge.
446460
- `REFRESH /path/file` performs refresh.
447461
- Full-zone `REFRESH` still needs a dedicated `proxy_cache_refresh ... refresh_all ...` location.
448462

449-
This migration trick does not remove refresh prerequisites. If a request is routed
450-
to refresh, the proxy path participating in that refresh flow still needs the
451-
refresh bypass rules, and the cache key still needs to end with the URI or
452-
request URI portion.
463+
This migration trick does not remove refresh prerequisites. If a request is
464+
routed to refresh, the proxy path participating in that refresh flow still
465+
needs the refresh bypass rules, and the evaluated cache key still needs to keep
466+
the request-target tail safely identifiable.
453467

454468
### Common Misconfigurations
455469

@@ -528,6 +542,7 @@ entries in a single request without hitting nginx's 64535 subrequest limit.
528542
```bash
529543
# Refresh a single file
530544
curl -X REFRESH http://localhost/refresh/path/to/file.txt
545+
```
531546

532547
Current upstream status policy during refresh is intentionally conservative:
533548

@@ -753,7 +768,41 @@ Enable `cache_purge_vary_aware on`.
753768

754769
## Testing
755770

756-
The test suite uses [Test::Nginx](https://github.com/openresty/test-nginx).
771+
The project keeps two complementary testing entry points:
772+
773+
- `t/Makefile` for Docker-based Test::Nginx runs
774+
- `scripts/run_regression.sh` from the repo root for the broader regression backstop
775+
776+
Current compatibility matrix policy is:
777+
778+
- latest stable
779+
- latest mainline
780+
- every legacy stable line from `1.20.x` up to the current stable line
781+
782+
Current concrete regression versions are:
783+
784+
- `1.20.2`
785+
- `1.22.1`
786+
- `1.24.0`
787+
- `1.26.3`
788+
- `1.28.3`
789+
- latest stable
790+
- latest mainline
791+
792+
Before running the matrix, re-check the nginx download page and refresh the
793+
concrete latest stable / latest mainline / legacy stable versions if upstream
794+
has moved.
795+
796+
Docker-based test targets from `t/`:
797+
798+
```bash
799+
make test
800+
make test-all
801+
make test-version VERSION=1.28.3
802+
make test-compat
803+
```
804+
805+
Legacy direct `prove` usage is still available when dependencies are installed:
757806

758807
```bash
759808
prove -r t/

‎README.zh-CN.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -254,6 +254,14 @@ location / {
254254
- 检查 refresh 子请求实际会经过哪些 proxy location，确保这些 location 都正确配置了 `proxy_cache_bypass` 与 `proxy_no_cache`。
255255
- 把 `X-Cache-Action` 纳入日志或审计字段，这样能快速确认一次请求最终执行的是 purge 还是 refresh。
256256

257+
## 兼容与测试
258+
259+
- 当前兼容矩阵遵循这条规则：覆盖 latest stable、latest mainline，以及从 `1.20.x` 到当前 stable 之间的所有 legacy stable lines。
260+
- 当前具体回归版本为：`1.20.2`、`1.22.1`、`1.24.0`、`1.26.3`、`1.28.3`、latest stable、latest mainline。
261+
- 每次跑矩阵前，都要先检查 nginx 官方下载页；如果 latest stable、latest mainline 或任一 legacy stable line 已更新，就先刷新具体版本号再测试。
262+
- 在 `t/` 目录下优先使用 Docker 化入口：`make test`、`make test-all`、`make test-version VERSION=<x.y.z>`、`make test-compat`。
263+
- repo 级集成回归回退命令仍然是仓库根目录下的 `./scripts/run_regression.sh`。
264+
257265
## 响应与排错提示
258266

259267
- refresh 成功时返回 `200 OK`；refresh 目前只支持 JSON 或 text 两种正文格式：当 `cache_purge_response_type=json` 时返回 JSON，例如 `{"status":"refresh",...,"total_bytes":12345,"kept_bytes":6789,"purged_bytes":5556,"status_counts":{"200":190,"301":1,"304":15375},"status_bytes":{"200":1048576,"301":512,"304":2097152}}`；其余取值都会回退到 text。默认 text 模式下，正文类似 `Refresh: total=<N> kept=<K> purged=<P> errors=<E> total_bytes=<B> kept_bytes=<KB> purged_bytes=<PB> statuses={200:<N>,304:<N>,...} status_bytes={200:<BYTES>,304:<BYTES>,...}`。

0 commit comments

Comments
 (0)