API 设计 / 系统课时

收紧生产端点暴露面

收紧生产端点暴露面

生产 GraphQL 端点不应把开发便利直接带到公网。本课用 Apollo Server 5 与 Express 5 把 Introspection、CORS、CSRF 和错误响应分别收紧,并通过真实请求验证每一道边界是否按预期工作。

学习目标

  • 根据环境显式控制 Introspection 与 Schema 细节暴露。
  • 为浏览器来源配置最小 CORS 白名单,并保持 CSRF 防护开启。
  • 对内部异常做错误脱敏,并用请求验证生产配置。

把暴露面拆成四层

这四项保护解决的问题不同。Introspection 控制客户端能否直接枚举 Schema;CORS 约束浏览器脚本能否读取跨源响应;CSRF 防护阻止“简单请求”绕过预检去触发 GraphQL 操作;错误脱敏则避免把堆栈、数据库信息或内部服务细节返回给客户端。

生产 GraphQL 端点的四层暴露面控制

使用显式生产配置

下面示例要求 Node.js 20+,并使用 @apollo/server 5、graphql 16.11+、Express 5、@as-integrations/express5 与 cors。生产行为由代码显式决定,而不是依赖某个部署平台恰好设置了正确的环境默认值。

js
import http from 'node:http';
import express from 'express';
import cors from 'cors';
import { ApolloServer } from '@apollo/server';
import { expressMiddleware } from '@as-integrations/express5';
import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
import { ApolloServerPluginLandingPageDisabled } from '@apollo/server/plugin/disabled';

const isProduction = process.env.NODE_ENV === 'production';
const allowedOrigin =
  process.env.ALLOWED_ORIGIN ?? 'https://app.example.com';

const typeDefs = `#graphql
  type Query {
    ping: String!
    secretError: String
  }
`;

const resolvers = {
  Query: {
    ping: () => 'pong',
    secretError: () => {
      throw new Error('db password=do-not-expose');
    },
  },
};

const app = express();
app.disable('x-powered-by');
const httpServer = http.createServer(app);

const server = new ApolloServer({
  typeDefs,
  resolvers,
  introspection: !isProduction,
  hideSchemaDetailsFromClientErrors: isProduction,
  csrfPrevention: true,
  includeStacktraceInErrorResponses: !isProduction,
  formatError(formattedError) {
    if (formattedError.extensions?.code === 'INTERNAL_SERVER_ERROR') {
      return {
        message: 'Internal server error',
        extensions: { code: 'INTERNAL_SERVER_ERROR' },
      };
    }
    return formattedError;
  },
  plugins: [
    ApolloServerPluginLandingPageDisabled(),
    ApolloServerPluginDrainHttpServer({ httpServer }),
  ],
});

await server.start();

app.use(
  '/graphql',
  cors({ origin: [allowedOrigin], credentials: true }),
  express.json({ limit: '100kb' }),
  expressMiddleware(server),
);

await new Promise((resolve) => httpServer.listen({ port: 4000 }, resolve));
console.log('GraphQL ready at http://localhost:4000/graphql');

预期结果:保存为 server.mjs 后可以直接启动;生产模式下 Introspection 与字段名建议被收紧,Apollo 落地页关闭,内部错误会经过统一脱敏。

bash
NODE_ENV=production ALLOWED_ORIGIN=https://app.example.com node server.mjs

预期输出

text
GraphQL ready at http://localhost:4000/graphql

验证每一道边界

先验证允许来源和正常查询。响应应包含允许的跨域来源,并返回 pong。

bash
curl -si -X POST http://localhost:4000/graphql \
  -H 'Origin: https://app.example.com' \
  -H 'Content-Type: application/json' \
  --data '{"query":"{ ping }"}'

预期输出

text
HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Credentials: true
<VALUE>

{"data":{"ping":"pong"}}

<VALUE> 代表日期、连接策略等与运行环境有关的响应头,实际值可能不同。再检查未授权来源是否拿不到 CORS 许可头,以及内部异常是否只暴露稳定错误信息。

bash
curl -si -X POST http://localhost:4000/graphql \
  -H 'Origin: https://evil.example' \
  -H 'Content-Type: application/json' \
  --data '{"query":"{ ping }"}' \
  | grep -i '^Access-Control-Allow-Origin:' || echo 'no ACAO header'

curl -s -X POST http://localhost:4000/graphql \
  -H 'Content-Type: application/json' \
  --data '{"query":"{ secretError }"}'

预期输出

text
no ACAO header
{"errors":[{"message":"Internal server error","extensions":{"code":"INTERNAL_SERVER_ERROR"}}],"data":{"secretError":null}}

最后用一个没有预检触发头的 GET 请求验证 CSRF 防护。此请求不应执行 GraphQL 查询。

bash
curl -si 'http://localhost:4000/graphql?query=%7Bping%7D'

预期输出

text
HTTP/1.1 400 Bad Request
<VALUE>

响应正文会说明请求未满足 CSRF 防护要求,具体错误文本可能随补丁版本变化。若业务确实允许 GET 查询,应让受信客户端发送能触发预检的非空请求头,而不是关闭 csrfPrevention。客户端错误脱敏后,原始异常仍应写入受控的服务端日志或 Trace,不能为了“安全”把排障证据一起丢掉。

生产策略不要只看一个开关

关闭 Introspection 只能降低 Schema 的直接可发现性,不能代替授权;CORS 只影响浏览器;错误脱敏也不能阻止高成本查询。真正的生产收口应把这些设置与身份认证、字段级授权、查询深度或成本限制、速率限制以及网关访问策略组合起来。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

收紧生产端点暴露面

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通