首页 › 博客 › 文章

REST API 安全:鉴权、限流与暴露面收敛

REST API 安全:鉴权、限流与暴露面收敛

结论先行: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,而不是映射到一个万能 api scope。网关签发 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 上下文,修完灰度放量。

实施步骤:上线排查流程

  1. 冻结基线:导出 /wp-json/ 路由表、Nginx 配置、WAF 规则、对象缓存状态与当前应用密码清单,提交到 docs/rest-baseline-2026。
  2. 匿名复测:用无 Cookie 的 curl 跑 GET/POST/context=edit/_fields/分页上限,记录状态码、字段、响应头,标出所有超出产品需求的暴露。
  3. 凭证灰度:先给专用账号发应用密码或 OAuth 短期 token,只切 10% 内部流量,核对 401/403/201 比例与审计日志字段完整性。
  4. 限流压测:按本文 seq + xargs 命令验证 429、Retry-After、白名单独立阈值,同时观察 DB 慢查询与缓存命中率,确认拦截发生在查询前。
  5. 自定义端点回归:执行 PHPUnit 四种身份用例,补一次跨 blog、跨 post_type、非法参数测试;失败即回滚到上一版 MU 插件文件,不放松 permission_callback。
  6. 值守与回滚:上线 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 与 schemavendor/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 插件重命名、凭证吊销三步输出。

需要把鉴权、限流和端点收敛做成可交付插件?查看 插件开发服务 或 服务总览,我们按验收表交付。

参考资料与延伸阅读

WPDaiwei

WPDaiwei-专业Wordpress网站定制开发提供商

需要 WordPress 开发服务?

24 小时内免费出方案与报价,国内国外都接单。

QQ