csrf插件
更新时间 2026-04-21 15:48:56
最近更新时间: 2026-04-21 15:48:56
本文将详细介绍csrf插件功能、配置和使用。
功能说明
csrf 插件可保护用户的 API 免于 CSRF 攻击。
在此插件运行时，GET、HEAD 和 OPTIONS 会被定义为 safe-methods，其他的请求方法则定义为 unsafe-methods。因此 GET、HEAD 和 OPTIONS 方法的调用不会被检查拦截。
使用 GET 请求 API 时，在响应中会有一个携带了加密 Token 的 Cookie。Token 字段名称为插件配置中的 name 值，默认为 agw-csrf-token。
注意
每一个请求都会返回一个新的 Cookie。
在后续对该路由进行的 unsafe-methods 请求中，需要从 Cookie 中读取加密的 Token，并在请求头中携带该 Token。请求头字段的名称为插件属性中的 name。
配置字段
| 名称 | 类型 | 填写要求 | 默认值 | 有效值 | 描述 |
|---|---|---|---|---|---|
| key | string | 必填 | 加密 Token 的密钥。 | ||
| name | string | 可选 | agw-csrf-token | 生成的 Cookie 中的 Token 名称，需要使用此名称在请求头携带 Cookie 中的内容。 | |
| expires | number | 可选 | 7200 | CSRF Cookie 的过期时间，单位为秒。当设置为 0 时，会忽略 CSRF Cookie 过期时间检查。 |
配置示例
key: "edd1c9f034335f136f87ad84b625c8f1"启用插件后，使用 curl 命令尝试直接对该路由发起 POST 请求，会返回 Unauthorized 字样的报错提示：
curl -i http://127.0.0.1:27151/hello -X POST
HTTP/1.1 401 Unauthorized
{"error_msg":"no csrf token in headers"}当发起 GET 请求时，返回结果中会有携带 Token 的 Cookie：
curl -i http://127.0.0.1:27151/hello -i
HTTP/1.1 200 OK
Set-Cookie: agw-csrf-token=eyJyYW5kb20iOjAuNzgyMDk5MTE4NjUxNjQsInNpZ24iOiIwNTEyZDFkZDRiMmNjYTIxMTRlYWRhYWUxOTkxNmNiZGYzMWE2ZGI0MzRkNWQ5MzRjODkzZWM3M2ZmNTQxZTJlIiwiZXhwaXJlcyI6MTc0NTQ4ODkxM30=;path=/;SameSite=Lax;Expires=Thu, 24-Apr-25 12:01:53 GMT在请求之前，用户需要从 Cookie 中读取 Token，并在后续的 unsafe-methods 请求的请求头中携带。
例如，你可以在客户端使用 js-cookie 读取 Cookie，使用 axios 发送请求：
const token = Cookie.get('agw-csrf-token');
const instance = axios.create({
headers: {'agw-csrf-token': token}
});使用 curl 命令发送请求，确保请求中携带了 Cookie 信息，如果返回 200 HTTP 状态码则表示请求成功：
curl -i http://127.0.0.1:27151/hello -X POST -H 'agw-csrf-token: eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ==' -b 'agw-csrf-token=eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ=='
HTTP/1.1 200 OK配置模板
#必填，加密 Token 的密钥
key: "edd1c9f034335f136f87ad84b625c8f1"
#[可选]默认为agw-csrf-token，生成的 Cookie 中的 Token 名称，需要使用此名称在请求头携带 Cookie 中的内容
#name: "agw-csrf-token"
#[可选]CSRF Cookie 的过期时间
#expires: 7200
