Cache 상태

Sitemap pre-warm

Render test

⬇️ 설치

# pnpm
pnpm add @spa-seo-gateway/core @spa-seo-gateway/admin-ui fastify

# npm
npm i @spa-seo-gateway/core @spa-seo-gateway/admin-ui fastify

# yarn
yarn add @spa-seo-gateway/core @spa-seo-gateway/admin-ui fastify

🛠️ 시나리오 1 — 직접 게이트웨이 구성

현재 apps/gateway 가 하는 일을 직접 구성. 가장 흔한 사용법.

// my-gateway.ts
import Fastify from 'fastify';
import compress from '@fastify/compress';
import cors from '@fastify/cors';
import {
  browserPool,
  config,
  logger,
  shutdownCache,
} from '@spa-seo-gateway/core';
import { registerAdminUI } from '@spa-seo-gateway/admin-ui';

const app = Fastify({
  loggerInstance: logger,
  trustProxy: true,
  bodyLimit: 4 * 1024 * 1024,
});

await app.register(compress, { encodings: ['br', 'gzip'] });
await app.register(cors);

// 어드민 UI 등록 — /admin/ui 에서 접근
await registerAdminUI(app, { prefix: '/admin/ui' });

// 자체 라우트는 직접 등록 (혹은 @spa-seo-gateway/cms / multi-tenant 사용)
import { detectBot, render, cacheSwr, cacheKey } from '@spa-seo-gateway/core';

app.get('/*', async (req, reply) => {
  const isBot = detectBot(req.headers['user-agent'], req.headers, req.query).isBot;
  if (!isBot) { reply.code(204).send(); return; }

  const target = new URL(req.url, config.originUrl).toString();
  const key = cacheKey(target);
  const result = await cacheSwr(key, () =>
    render({ url: target, headers: req.headers })
  );

  reply.code(result.entry.status);
  for (const [k, v] of Object.entries(result.entry.headers)) reply.header(k, v);
  reply.send(result.entry.body);
});

await browserPool.start();
await app.listen({ port: 3000 });

process.on('SIGTERM', async () => {
  await app.close();
  await browserPool.stop();
  await shutdownCache();
  process.exit(0);
});

🏢 시나리오 2 — SaaS 다중 테넌트

FileTenantStore (또는 직접 구현한 store) 와 함께 multi-tenant 플러그인 등록.

import Fastify from 'fastify';
import { browserPool } from '@spa-seo-gateway/core';
import { registerAdminUI } from '@spa-seo-gateway/admin-ui';
import {
  registerMultiTenant,
  FileTenantStore,
  type TenantStore,
} from '@spa-seo-gateway/multi-tenant';

const app = Fastify();
const store: TenantStore = new FileTenantStore('./tenants.json');

await registerMultiTenant(app, {
  store,
  adminToken: process.env.ADMIN_TOKEN,
  // 식별 전략 (기본: ['host', 'apiKey'])
  resolve: ['host', 'apiKey'],
});

await registerAdminUI(app, { prefix: '/admin/ui' });
await browserPool.start();
await app.listen({ port: 3000 });

import { type TenantStore, type Tenant } from '@spa-seo-gateway/multi-tenant';
import { sql } from './db.js';

export class PostgresTenantStore implements TenantStore {
  async list() { return sql`SELECT * FROM tenants` as unknown as Tenant[]; }
  async byId(id: string) {
    const r = await sql`SELECT * FROM tenants WHERE id = ${id}`;
    return (r[0] as Tenant) ?? null;
  }
  async byApiKey(key: string) {
    const r = await sql`SELECT * FROM tenants WHERE api_key = ${key}`;
    return (r[0] as Tenant) ?? null;
  }
  async byHost(host: string) {
    const r = await sql`SELECT * FROM tenants WHERE origin LIKE ${'%' + host + '%'}`;
    return (r[0] as Tenant) ?? null;
  }
  async upsert(t: Tenant) {
    await sql`INSERT INTO tenants ... ON CONFLICT (id) DO UPDATE ...`;
    return t;
  }
  async remove(id: string) {
    const r = await sql`DELETE FROM tenants WHERE id = ${id}`;
    return r.count > 0;
  }
}

🌐 시나리오 3 — CMS 다중 사이트

같은 조직이 여러 사이트(마케팅 / 블로그 / 도큐먼트) 를 운영할 때.

import Fastify from 'fastify';
import { browserPool } from '@spa-seo-gateway/core';
import { registerCms, FileSiteStore } from '@spa-seo-gateway/cms';
import { registerAdminUI } from '@spa-seo-gateway/admin-ui';

const app = Fastify();
const store = new FileSiteStore('./sites.json');

await registerCms(app, { store, adminToken: process.env.ADMIN_TOKEN });
await registerAdminUI(app, { prefix: '/admin/ui' });
await browserPool.start();
await app.listen({ port: 3000 });

// 사이트 추가는 admin API 로
// POST /admin/api/sites { id, name, origin, routes: [...] }

🔧 시나리오 4 — 기존 Fastify 앱에 임베드

이미 Fastify 백엔드가 있다면, 봇 트래픽만 SEO 렌더로 분기하는 미들웨어로 사용.

import {
  detectBot,
  render,
  cacheSwr,
  cacheKey,
  browserPool,
} from '@spa-seo-gateway/core';

// 앱 시작 시 한 번
await browserPool.start();

// 미들웨어처럼 사용
app.addHook('onRequest', async (req, reply) => {
  const detection = detectBot(
    req.headers['user-agent'],
    req.headers,
    req.query,
  );
  if (!detection.isBot) return; // 사람은 다음 핸들러로

  const target = new URL(req.url, 'https://your-spa.example.com').toString();
  const key = cacheKey(target);
  const result = await cacheSwr(key, () =>
    render({ url: target, headers: req.headers }),
  );

  reply.code(result.entry.status);
  for (const [k, v] of Object.entries(result.entry.headers)) reply.header(k, v);
  return reply.send(result.entry.body);
});

🖥️ 시나리오 5 — 단발 렌더 CLI / 스크립트

서버 없이 빌드 단계 / cron 으로 단발 렌더링.

import { browserPool, render } from '@spa-seo-gateway/core';
import { writeFileSync } from 'node:fs';

await browserPool.start();
try {
  const entry = await render({
    url: 'https://www.example.com/posts/123',
    headers: { 'user-agent': 'Googlebot/2.1' },
  });
  writeFileSync('out.html', entry.body, 'utf8');
  console.log(`status=${entry.status} bytes=${entry.body.length}`);
} finally {
  await browserPool.stop();
}

📚 핵심 API 레퍼런스 (@spa-seo-gateway/core)

전체 export 는 packages/core/src/index.ts 참고.

⚙️ 라이브러리 모드에서의 설정

@spa-seo-gateway/core 는 모듈 로드 시점에 환경변수와 seo-gateway.config.json 을 자동 로드합니다. 기존 환경변수 그대로 (POOL_MAX, WAIT_UNTIL, ADMIN_TOKEN 등) 동작합니다.

# .env (라이브러리로 쓰는 외부 프로젝트도 동일)
POOL_MIN=2
POOL_MAX=8
WAIT_UNTIL=networkidle2
BLOCK_RESOURCE_TYPES=image,media,font
MEMORY_CACHE_TTL_MS=86400000
SWR_WINDOW_MS=3600000
ADMIN_TOKEN=secret
REDIS_CACHE_ENABLED=true
REDIS_URL=redis://localhost:6379

자세한 설정은 CONFIGURATION.md.

💡 라이브러리 사용 시 팁

• 풀 시작 / 종료 직접 관리 — browserPool.start() 를 앱 시작 시, browserPool.stop() + shutdownCache() 를 SIGTERM 처리에 호출.
• 다른 풀 라이프사이클과 독립 — 한 프로세스에서 여러 게이트웨이를 띄우는 건 지원하지 않습니다 (모듈 싱글톤). 필요하면 별도 프로세스.
• Redis 활성 권장 — 멀티 노드 + 재시작 안전성. REDIS_CACHE_ENABLED=true
• 커스텀 store 구현 — TenantStore/SiteStore 인터페이스만 만족하면 Postgres/SQLite/DynamoDB 어떤 백엔드든 OK.
• 메트릭 노출 — app.get('/metrics', async (_req, reply) => { reply.header('content-type', registry.contentType); return registry.metrics(); })
• 품질 게이트 비활성 — 자체 검증 로직이 있다면 QUALITY_CHECK=false
• 로그 라우팅 — logger 는 pino 인스턴스. 앱 자체 로거에 통합하려면 logger.child({ ... }) 또는 transport 추가