
文章目录
结论先行:WordPress REST API 安全要先收敛可访问端点,再统一鉴权模型,最后在边缘和 PHP 两层做限流。判断做对的标准是:匿名请求只能拿到业务允许字段,写操作全部可追溯,异常流量被拦截且可回滚,自定义端点有可测试的权限回调。
默认端点暴露了什么
为什么做:很多站点把后台登录页藏得很严,却忘了 /wp-json/ 是另一套入口。2026 年 WordPress 6.9/7.0 分支仍默认启用 REST API,核心命名空间 wp/v2 会返回文章、页面、媒体、评论、分类、标签、用户、类型、状态、分类法、设置等路由。未登录用户通常能读公开内容,用户端点会暴露作者 ID、slug、名称、头像 URL、链接;?context=edit、创建、更新、删除才要求对应 capability。问题不在“公开内容可读”,而在字段、作者枚举、媒体路径、搜索参数、插件追加的路由被组合利用。
开发公司接手老项目时,经常发现 REST 被第三方编辑器、Headless 前端、移动端和定时任务同时使用,直接 rest_authentication_errors 一刀切会拖垮业务。因此第一步不是关闭 API,而是建立资产表:哪些 namespace 存在、哪些路由匿名可读、哪些字段属于业务敏感、哪些来源 IP 或客户端在调用。若站点近期做过域名或主机切换,建议把接口清单并入 2026 WordPress备份迁移选型与验收指南 里的验收项,避免迁移后丢掉 WAF 规则、Nginx limit 配置和 .htaccess 例外。
可勾选清单:盘点与收敛
- □ 拉取完整路由表。在生产域名执行
curl -sS https://example.com/wp-json/ | jq '.routes | keys',再执行curl -sS https://example.com/wp-json/wp/v2/users | jq '.[0]'。把输出存进仓库docs/rest-inventory-2026.json,不要只在本地开发环境看。 - □ 标记匿名可读路由。用
curl -I -sS 'https://example.com/wp-json/wp/v2/posts?per_page=1'与带 Cookie 的请求对比状态码、X-WP-Total、响应字段。匿名侧出现content.raw、author之外的邮箱、私单号、自定义 meta,要回到register_rest_field()或prepare_item_for_response()修。 - □ 收敛用户枚举。不需要作者归档的站点,用
rest_endpoints过滤/wp/v2/users;不要只靠 robots.txt。代码放主题inc/rest-hardening.php或自建 MU 插件wp-content/mu-plugins/rest-hardening.php,MU 插件更不容易被切换主题绕过。 - □ 清理插件 namespace。逐个核对
/wp-json/返回的 namespaces,停用废弃插件比写黑名单有效。对确实要保留但只给服务端用的 namespace,在 Nginx 层按location ~ ^/wp-json/(acme-internal|old-import)/限制内网或指定 IP。 - □ 关闭不必要的写能力。站点不开放前台投稿时,确认
wp/v2/comments的 POST 被 capability 或反垃圾层挡住;用curl -X POST -i https://example.com/wp-json/wp/v2/comments -d 'post=1&content=probe'验证应返回 401/403,而不是 201。 - □ 记录响应头。把
X-WP-Total、X-WP-TotalPages、Link、缓存头写入验收表。分页上限被放大时,攻击者能用per_page=100&page=9999低成本扫库。
怎么做验证:准备两个身份:完全匿名、最低权限订阅者。分别跑同一组 curl,差异必须能用产品需求解释。再跑一次 wp rest 不可用时的回退检查:若站点依赖 WP-CLI REST 命令,先确认 wp --info 与 wp plugin list 正常,避免把 CLI 故障误判成 API 被封。
常见踩坑:用 rest_authentication_errors 返回 true 会绕过后续鉴权,写错会让本该受保护的路由变匿名;把 /wp-json/ 整段 403 会破坏 Gutenberg、块编辑器、移动端和部分 WooCommerce 后台请求;只改 wp-config.php 加 REST_REQUEST 判断,常被 CDN 缓存命中绕过。失败回退:保留上一版 rest-hardening.php,通过 wp plugin deactivate 或重命名 MU 插件文件 30 秒内恢复,再按路由逐条放白,不要整体撤掉 WAF 规则。
应用密码与 OAuth
为什么做:REST 写操作不能复用登录 Cookie 当长期凭证。2026 年 WordPress 核心自带 Application Passwords(自 5.6 起,6.x 系列持续维护),适合服务端到服务端、CI、内部脚本;它走 HTTPS Basic Auth,能按用户生成、按名称撤销,不依赖额外插件。OAuth 2.1 / OIDC 更适合多客户端、第三方授权、需要短期 access token、refresh token、scope 和统一吊销的场景,核心不自带完整 OAuth Server,需要自建网关或成熟插件,并自行承担 token 存储、签名校验、时钟偏移和审计。
如果项目涉及多站点、多环境、外部 App 与后台服务,建议把授权模型写进 [服务页] WordPress 插件开发 的交付文档:谁发凭证、谁轮换、谁看日志、回滚时先吊销哪一批。不要把这些决定散落在运维聊天记录里。
应用密码:操作与验收
- □ 只给专用账号。执行
wp user create rest_publisher ops@example.com --role=author --user_pass="$(openssl rand -base64 24)"。不要给管理员生成应用密码;脚本只拿完成业务所需的最小角色。 - □ 强制 HTTPS。应用密码要求 SSL 或本地开发环境下
WP_ENVIRONMENT_TYPE='local'才生效。Nginx 配置if ($scheme != 'https') { return 301 https://$host$request_uri; }只作兜底,真正入口在负载均衡终止 TLS 后要透传X-Forwarded-Proto,并确认wp-config.php中$_SERVER['HTTPS']='on'的判断可靠。 - □ 生成并分空间保存。后台「用户 → 个人资料 → 应用程序密码」新增名称如
ci-2026-deploy,把xxxx xxxx xxxx xxxx xxxx xxxx存入 Vault/1Password/CI Secret;仓库里只存用户名和凭证 ID,不存明文。 - □ 调用时只带 Authorization。
curl -sS -u 'rest_publisher:APP_PASSWORD' -H 'Content-Type: application/json' -X POST https://example.com/wp-json/wp/v2/posts -d '{"title":"probe","status":"draft","content":"probe"}'。返回 201 且status=draft才算通过;返回 200 但落在 Cookie 会话上说明测错了。 - □ 轮换与撤销。用
wp user application-password list rest_publisher --format=json核对 UUID、名称、创建时间;轮换先新增、灰度切流、再wp user application-password delete rest_publisher UUID。不要先删后加。 - □ 审计失败。在
wp-content/mu-plugins/rest-auth-log.php挂rest_authentication_errors,只记录WP_Error的 code、IP、路由、User-Agent,不记 Authorization。配合grep 'rest_authentication' /var/log/nginx/access.log看 401 峰值。
OAuth:边界与校验
获取报价
邮箱 + 需求 + 预算区间,24 小时内回复报价。
- □ 明确 scope。把
posts:read、posts:write、media:write映射到 WordPress capability,而不是映射到一个万能apiscope。网关签发 token 后,插件侧仍要调用current_user_can()。 - □ 校验 token 本身。验签、
iss、aud、exp、nbf、jti缺一不可;用wp_cache_add()或 Redis 存jti重放窗口,TTL 与exp对齐。2026 年主流网关默认 RS256/EdDSA,避免alg=none和 HS256 混用。 - □ 保留吊销路径。提供
/oauth/revoke与管理端「一键停某客户端」;数据库表至少含client_id、user_id、scope、expires_at、revoked_at。验收时删 token 后旧请求必须在下一个请求即 401,不是等缓存过期。
常见踩坑:Basic Auth 头被 Nginx auth_basic 或 PHP-FPM fastcgi_pass_header 配置吃掉,表现为永远 401;CDN 把 Authorization 当缓存 key 之外字段转发,导致 A 用户 token 命中 B 用户响应;OAuth 插件只做登录、不做 per-route scope。回退方法:先切回单个应用密码专用账号维持发布链路,把 OAuth 网关流量摘到 0,保留 revoked_at 记录,再修验签与 header 透传,不要在故障中同时轮换两套凭证。官方文档可对照 REST API Authentication 核对核心行为。
限流与封禁策略
为什么做:鉴权解决“谁可以”,限流解决“可以多快”。REST 的 ?search=、?slug=、?per_page=、?_fields=、媒体上传、评论提交、密码探测都能制造 CPU、DB 慢查询和对象缓存穿透。2026 年线上常见组合是:CDN 挡体积型流量,Nginx limit_req 挡单 IP 突发,PHP 层按「用户 + 路由 + 方法」挡业务逻辑滥用,WAF/防火墙负责临时封禁与告警。只做一层不够:CDN 回源可能绕过,PHP 层太晚,数据库已经查了。
可勾选清单:三层阈值
- □ 边缘层。CDN 对
/wp-json/*单独设规则:匿名 GET 允许缓存但Authorization请求一律no-store;POST/PUT/DELETE 不缓存。把per_page上限、page上限写进 WAF 参数校验,超过直接 429。 - □ Nginx 层。在
/etc/nginx/conf.d/rest-limit.conf定义limit_req_zone $binary_remote_addr zone=rest_anon:10m rate=5r/s;,再在location ^~ /wp-json/内limit_req zone=rest_anon burst=20 nodelay;、limit_req_status 429;。改完执行nginx -t && systemctl reload nginx,不要restart打断长连接。 - □ PHP 层。对写操作和搜索按
get_current_user_id()或匿名 IP 生成 key,用wp_cache_add()/wp_cache_incr()计数;没有持久对象缓存时落到自定义表,别用set_transient()扛高并发。 - □ 封禁分级。1 分钟超阈值返回 429 +
Retry-After;连续 3 个窗口升级为 15 分钟deny;命中凭证探测、路径扫描、上传异常再升级到 24 小时并告警。封禁要带原因、命中规则、到期时间,方便误伤时精确解封。 - □ 白名单可审计。监控、CI、内网发布机用独立
client_id或固定 IP,写进rest-rate-whitelist.json并每月复核。不要写if ($remote_addr = '127.0.0.1') { allow all; }后又把全站放在反代后面,结果所有请求都像本机。 - □ 回退开关。准备
wp option patch update rest_hardening rate_limit_enabled 0或环境变量REST_RATE_LIMIT=off,只在限流组件本身故障时短时关闭,并同步开启 CDN 临时挑战页。关闭动作必须进变更记录。
下面这段可直接放进 wp-content/mu-plugins/rest-rate-guard.php。它只拦写方法和搜索,返回标准 WP_Error,不写明文凭证;<、>、& 已在示例中按 HTML 源码转义。
<?php
/**
* Plugin Name: REST Rate Guard
* Description: Per-route rate guard for write and search requests.
*/
add_filter('rest_pre_dispatch', function ($result, $server, $request) {
if (is_wp_error($result)) {
return $result;
}
$method = strtoupper($request->get_method());
$route = $request->get_route();
$is_write = in_array($method, ['POST', 'PUT', 'PATCH', 'DELETE'], true);
$is_search = $request->get_param('search') !== null;
if (!$is_write && !$is_search) {
return $result;
}
$uid = get_current_user_id();
$ip = $_SERVER['REMOTE_ADDR'] ?? 'unknown';
$bucket = $uid > 0 ? 'u:' . $uid : 'ip:' . md5($ip);
$key = 'rest_rg_' . md5($bucket . '|' . $method . '|' . $route . '|' . floor(time() / 60));
$count = wp_cache_incr($key, 1, 'rest_guard');
if ($count === false) {
wp_cache_set($key, 1, 'rest_guard', 70);
$count = 1;
}
$limit = $uid > 0 ? 60 : 12;
if ($count > $limit) {
return new WP_Error(
'rest_too_many_requests',
'Too many REST requests; retry later.',
['status' => 429, 'Retry-After' => 60]
);
}
return $result;
}, 10, 3);
怎么验证做对了:用 seq 1 40 | xargs -P8 -I{} curl -s -o /dev/null -w '%{http_code}n' 'https://example.com/wp-json/wp/v2/posts?search=probe',期望先 200、后 429,且响应含 Retry-After: 60;再带应用密码跑写请求,确认登录用户阈值独立。Nginx 侧看 awk '$9==429 {c++} END {print c}' /var/log/nginx/access.log。若全站 429,先检查反代下 $binary_remote_addr 是否变成同一个网关 IP,改用 real_ip_header X-Forwarded-For; + set_real_ip_from 可信段,回退时临时注释 limit_req 并 reload。
跨机房迁移最容易丢这层配置;把 rest-limit.conf、对象缓存组和 WAF 导出文件纳入 2026 WordPress搬迁服务商决策指南 的交付包,上线当天用同一组压测命令复验,而不是只看首页 200。
自定义端点的权限校验
为什么做:核心路由有 WP_REST_Posts_Controller 那套 capability 映射,自定义路由没有。开发者写 register_rest_route() 时漏掉 permission_callback,2026 年 WordPress 会直接报 _doing_it_wrong 并拒绝注册;但更危险的是写成 'permission_callback' => '__return_true',路由能跑、日志也干净,实际等于匿名开放内部操作。权限校验要同时回答三件事:身份是否可信、当前对象是否允许操作、输入参数是否越权。
可勾选清单:从注册到回归
- □ namespace 带版本。用
acme/v1,不要acme。路由变更时新增v2,旧版保留deprecated响应头与下线日期,避免客户端偷偷依赖未文档化字段。 - □ 每个 route 单独写 permission_callback。读、写、删除分开;不要复用一个
is_user_logged_in()。示例:'permission_callback' => function ($request) { return current_user_can('edit_post', (int) $request['id']); }。 - □ 校验对象归属。
get_post((int) $request['id'])后确认post_type、post_status、post_author、站点 ID(多站点用switch_to_blog()前后对齐)。只验 ID 存在,不验类型,常导致订单端点被拿去改文章。 - □ schema 与 sanitize 落地。
args里给每个参数type、required、sanitize_callback、validate_callback;整数用absint,slug 用sanitize_title,JSON 字段用wp_kses_post或白名单,不要直接update_post_meta($id, $key, $_POST['x'])。 - □ nonce 只用于浏览器同站会话。Gutenberg 请求带
X-WP-Nonce,用wp_verify_nonce($request->get_header('X-WP-Nonce'), 'wp_rest');应用密码/OAuth 客户端不要强制 nonce。两套混用会出现移动端 403、浏览器却正常。 - □ 响应裁剪。在
prepare_item_for_response()里按current_user_can()决定字段;错误用WP_Error('rest_forbidden', ..., ['status' => 403]),别把 SQL、绝对路径、栈信息塞进 message。 - □ 写回归测试。在
tests/phpunit/test-rest-acme.php继承WP_UnitTestCase,用rest_do_request()覆盖匿名、订阅者、作者、管理员四种身份,断言 401/403/200/201 与字段集合。CI 执行vendor/bin/phpunit --filter RestAcme。
可复制的最小注册片段,放 wp-content/mu-plugins/acme-rest.php:
<?php
add_action('rest_api_init', function () {
register_rest_route('acme/v1', '/orders/(?P<id>d+)', [
'methods' => WP_REST_Server::READABLE,
'callback' => 'acme_get_order',
'permission_callback' => function ($request) {
$post = get_post((int) $request['id']);
if (!$post || $post->post_type !== 'shop_order') {
return new WP_Error('rest_not_found', 'Not found', ['status' => 404]);
}
return current_user_can('edit_shop_order', $post->ID)
|| (int) $post->post_author === get_current_user_id();
},
'args' => [
'id' => [
'type' => 'integer',
'required' => true,
'sanitize_callback' => 'absint',
],
],
]);
});
function acme_get_order($request) {
$post = get_post((int) $request['id']);
return [
'id' => $post->ID,
'status' => $post->post_status,
'total' => get_post_meta($post->ID, '_order_total', true),
];
}
怎么验证做对了:curl -i https://example.com/wp-json/acme/v1/orders/123 匿名应 401 或 403;带订阅者应用密码访问他人订单应 403;带作者本人凭证应 200 且不含 _billing_email。再用 curl -i 'https://example.com/wp-json/acme/v1/orders/123?id=123%20OR%201=1' 确认 absint 生效。对照 Adding Custom Endpoints 检查 permission_callback 与 args 签名。
常见踩坑与回退:把权限放在 callback 第一行 return,看起来能挡,但 rest_pre_dispatch、schema 校验、日志钩子已经跑过;用 current_user_can('manage_options') 当通用门槛,会让编辑无法完成正常业务;多站点下 get_current_user_id() 有值却不属于当前 blog。上线后若客户端大面积 403,先别把回调改回 __return_true,正确回退是临时把路由指向只读 v1 快照、保留 403 审计,再用 wp rest/PHPUnit 定位是 nonce、capability 还是 blog 上下文,修完灰度放量。
实施步骤:上线排查流程
- 冻结基线:导出
/wp-json/路由表、Nginx 配置、WAF 规则、对象缓存状态与当前应用密码清单,提交到docs/rest-baseline-2026。 - 匿名复测:用无 Cookie 的 curl 跑 GET/POST/
context=edit/_fields/分页上限,记录状态码、字段、响应头,标出所有超出产品需求的暴露。 - 凭证灰度:先给专用账号发应用密码或 OAuth 短期 token,只切 10% 内部流量,核对 401/403/201 比例与审计日志字段完整性。
- 限流压测:按本文
seq + xargs命令验证 429、Retry-After、白名单独立阈值,同时观察 DB 慢查询与缓存命中率,确认拦截发生在查询前。 - 自定义端点回归:执行 PHPUnit 四种身份用例,补一次跨 blog、跨 post_type、非法参数测试;失败即回滚到上一版 MU 插件文件,不放松
permission_callback。 - 值守与回滚:上线 24 小时内保留
REST_RATE_LIMIT=off开关、旧凭证吊销清单和nginx -t && systemctl reload nginx回滚命令,告警接 429 突增与 401 突增两条,不接单一总量。
这个流程适合写进发布 Checkbox,也适合交给 技术栏目 的评审模板复用。判断完成不是“接口还能打开”,而是六步都有可复现输出:路由 diff、curl 记录、凭证 UUID、429 曲线、PHPUnit 报告、回滚演练时间戳。
验收表与失败信号

把下面表格贴进工单,每项都要有命令输出或截图编号。空一项就不算 WordPress REST API 安全收口完成。
| 检查项 | 期望结果 | 验证命令 / 位置 | 失败信号 |
|---|---|---|---|
| 默认端点暴露 | 匿名仅见业务允许字段,用户枚举已收敛 | curl -sS .../wp-json/ | jq '.routes | keys' | 出现邮箱、私单 meta、废弃 namespace |
| 应用密码 / OAuth | 专用账号、最小 scope、可即时吊销 | wp user application-password list rest_publisher --format=json | 管理员凭证进 CI、删 token 后仍 200 |
| 限流封禁 | 429 带 Retry-After,白名单独立计数 | awk '$9==429 {c++} END {print c}' access.log | 反代后全站同一 IP 被误封 |
| 自定义端点 | 每个 route 有独立 permission_callback 与 schema | vendor/bin/phpunit --filter RestAcme | __return_true、只验登录不验对象 |
| 回滚能力 | 30 秒内恢复上一版且日志不丢 | MU 插件备份 + systemctl reload nginx | 回滚靠改数据库或整站关 API |
经验规则:任何“先全开、以后再收”的 REST 改造,2026 年基本都会变成历史包袱。先写拒绝规则,再按客户端逐条放白,成本更低。
常见问题
要不要直接关闭 /wp-json/?
不建议整段关闭。Gutenberg、块编辑器、媒体库、部分后台 Ajax 替代逻辑和移动端都依赖它。正确做法是按 namespace、方法、身份放白,并对匿名 GET 做字段裁剪;只有纯静态且确认无编辑器依赖的归档站,才考虑在边缘层全拦。
应用密码和 OAuth 能同时用吗?
可以,但要分客户端:内部脚本/CI 用应用密码,第三方 App 用 OAuth,账号、日志、吊销清单分开。别让同一个 rest_authentication_errors 回调互相吞掉 WP_Error;任一链路失败时,另一条应保持可独立回退。
429 突然涨,先解封还是先改代码?
先确认是否反代 IP 归一、CDN 回源或对象缓存失联。临时用已审计的白名单和 REST_RATE_LIMIT=off 止血,保留 429 日志;不要删 permission_callback 或把阈值调到无限。定位后再 reload Nginx 并复跑压测。
结尾动作清单
- □ 今天导出生产路由表,提交
docs/rest-inventory-2026.json,标出所有非核心 namespace 与匿名可读字段。 - □ 本周撤销所有管理员应用密码,改为专用账号 + 最小角色,并把轮换 UUID 写进变更记录。
- □ 部署
rest-limit.conf与 MU 限流插件,用 40 并发命令验证 429、Retry-After与白名单隔离。 - □ 给每个自定义 route 补 PHPUnit 四身份用例,CI 加
--filter RestAcme,禁止__return_true合入主分支。 - □ 做一次 30 秒回滚演练,保存
nginx -t && systemctl reload nginx、MU 插件重命名、凭证吊销三步输出。
需要把鉴权、限流和端点收敛做成可交付插件?查看 插件开发服务 或 服务总览,我们按验收表交付。
