Strapi 5 가이드: 설정, API, 플러그인 및 배포 (2026)

Strapi 5 가이드: 설정, API, 플러그인 및 배포 (2026)

Strapi는 Node.js 기반으로 구축된 오픈소스 헤드리스 CMS로, API, 데이터베이스 및 배포에 대한 완전한 제어권을 제공합니다. 타인의 인프라에 대한 접근 권한을 임대하는 호스팅형 CMS 플랫폼과 달리, Strapi는 사용자의 서버에서 실행되며 콘텐츠 스키마로부터 REST 및 GraphQL 엔드포인트를 생성하고, 순수 JavaScript 또는 TypeScript를 사용하여 백엔드의 모든 계층을カスタ마이즈할 수 있게 해줍니다.

이 가이드는 첫 번째 npx create-strapi 명령어부터 Railway 또는 Strapi Cloud에서의 프로덕션 배포까지, 구체적으로 Strapi 5를 다룹니다. 모든 코드 예제는 복사하여 붙여넣기만 하면 바로 사용할 수 있으며 Strapi 5.x 버전에서 테스트되었습니다.

Strapi란 무엇이며 어떻게 작동하나요?

Strapi는 콘텐츠 백엔드를 프론트엔드와 분리하는 자체 호스팅, API 우선 콘텐츠 관리 시스템입니다. 시각적 빌더나 코드를 통해 콘텐츠 스키마를 정의하면, Strapi는 모든 프론트엔드 프레임워크가 사용할 수 있는 CRUD API 엔드포인트(REST 및 GraphQL 모두)를 자동으로 생성합니다. 관리자 패널은 공식 Strapi 문서에 따르면 코드를 건드리지 않고 콘텐츠 편집자가 항목을 생성하고 관리할 수 있는 React 기반 UI입니다.

헤드리스 CMS vs 전통적인 CMS

WordPress와 같은 전통적인 CMS는 콘텐츠를 프레젠테이션 레이어와 결합합니다. 블로그 게시물, 페이지 및 미디어는 모두 방문자에게 HTML을 렌더링하는 동일한 시스템 내에 존재합니다. 이는 모바일 앱, 마케팅 마이크로사이트 및 문서 포털에서 동시에 동일한 콘텐츠가 필요해지기 전까지는 잘 작동합니다.

헤드리스 CMS는 프론트엔드를 완전히 제거합니다. Strapi는 콘텐츠를 저장하고 API 엔드포인트를 통해 JSON으로 제공합니다. Next.js 사이트, React Native 앱 및 IoT 대시보드는 모두 동일한 Strapi 백엔드에서 데이터를 가져옵니다. 하나의 진실된 소스(Source of Truth)와 여러 소비자를 갖게 되는 것입니다.

Strapi 외에도 다른 옵션을 평가 중이라면, 주요 플랫폼들을 나란히 비교한 헤드리스 CMS 비교 글을 참고하세요.

Strapi의 아키텍처

Strapi의 스택은 직관적입니다. Node.js 서버가 데이터베이스(PostgreSQL, MySQL 또는 SQLite)와 프론트엔드 애플리케이션 사이에 위치합니다. React 단일 페이지 애플리케이션(SPA)인 관리자 패널은 더 향상된 권한 설정을 제외하면 프론트엔드가 사용하는 것과 동일한 API에 연결됩니다.

흐름은 다음과 같습니다: 데이터베이스가 콘텐츠를 보유합니다. Strapi의 ORM 레이어(Knex.js 기반)가 이를 쿼리합니다. API 레이어가 REST 및 GraphQL 엔드포인트를 노출합니다. Next.js, Nuxt, Astro, Gatsby 또는 모바일 앱 등 프론트엔드는 이러한 엔드포인트에서 JSON을 가져옵니다. Strapi 자체는 최종 사용자에게 HTML을 렌더링하지 않습니다.

Strapi GitHub 저장소는 65,000개 이상의 스타를 보유하고 있어, 해당 플랫폼에서 가장 인기 있는 오픈소스 CMS 프로젝트 중 하나입니다.

Strapi 5의 새로운 기능은 무엇인가요?

Strapi 5는 Entity Service API를 새로운 Document Service API로 대체하고, 관리자 패널 빌드를 Webpack에서 Vite로 전환하며, 새 프로젝트의 기본 언어로 TypeScript를 도입한 대규모 재작성 버전입니다. 이는 단순한 점진적 업데이트가 아니라 내부 아키텍처가 크게 변경된 것으로, Strapi 5 개요 페이지에 자세히 설명되어 있습니다.

Strapi 5 개발자 변경 로그에 따르면 개발자에게 가장 중요한 변경 사항은 다음과 같습니다:

• Document Service API: Entity Service API를 대체하며, 더 깔끔한 메서드 시그니처, 개선된 TypeScript 타입, CRUD 작업을 위한 통합 인터페이스 제공
• Draft & Publish 개편: 관리자 패널에서 초안과 게시된 콘텐츠 상태를 분리하는 두 개의 탭 시스템 도입
• 콘텐츠 히스토리(Content History): 관리자 패널에서 직접 항목의 이전 버전을 보고 복원 가능
• 미리보기 기능: 게시 전에 실제 프론트엔드에서 콘텐츠를 미리볼 수 있으며, 콘텐츠 타입별로 구성 가능
• Vite로 Webpack 대체: 관리자 패널 빌드 속도가 눈에 띄게 빨라짐(빌드 시간 약 60% 개선 확인)
• TypeScript 우선 접근 방식: 새 프로젝트가 기본적으로 TypeScript로 스캐폴딩됨
• AI 콘텐츠 타입 빌더: 자연어 설명이나 Figma 디자인으로부터 콘텐츠 스키마 생성. 2026년의 신규 기능으로, 다른 헤드리스 CMS는 아직 이를 제공하지 않음
• 간소화된 API 응답: REST 및 GraphQL 모두에 대해 더 평평한(flat) JSON 구조 제공
• 새로운 플러그인 SDK: Strapi 플러그인 구축 및 배포를 위한 간소화된 API

Strapi 5 설치 및 설정 방법

Strapi 5 프로젝트 설정에는 약 2분이 소요됩니다. Node.js 18 이상과 npm, yarn 또는 pnpm 중 하나가 필요합니다. Strapi는 단일 명령어로 관리자 패널, 데이터베이스 연결 및 API 레이어를 갖춘 전체 프로젝트를 스캐폴딩하며, 이는 Strapi 빠른 시작 가이드에 문서화되어 있습니다.

사전 요구 사항

• Node.js 18+ (20 LTS 권장)
• npm 6+, yarn 또는 pnpm
• 데이터베이스: 개발용으로는 SQLite가 기본으로 작동하며, 프로덕션용으로는 PostgreSQL 권장

첫 번째 프로젝트 생성

npx create-strapi@latest my-project

# Interactive prompts:
# ? Choose your preferred language: TypeScript
# ? Choose your default database client: sqlite
# ? Start with an example structure?: Yes (recommended for first-timers)

cd my-project
npm run develop

Strapi는 http://localhost:1337에서 시작됩니다. 처음 접속하면 관리자 계정 생성을 요청받습니다. 그 후에는 관리자 패널에 진입하여 콘텐츠 타입을 구축할 준비가 됩니다.

프로젝트 구조 개요

my-project/
├── config/
│   ├── database.ts          # Database connection
│   ├── server.ts             # Host, port, app keys
│   ├── admin.ts              # Admin panel config
│   └── plugins.ts            # Plugin configuration
├── src/
│   ├── api/                  # Your content types live here
│   │   └── article/
│   │       ├── content-types/
│   │       │   └── article/schema.json
│   │       ├── controllers/article.ts
│   │       ├── routes/article.ts
│   │       └── services/article.ts
│   ├── plugins/              # Custom plugins
│   └── index.ts              # App bootstrap/lifecycle
├── public/                   # Static files
├── .env                      # Environment variables
└── package.json

각 콘텐츠 타입은 src/api/ 아래에 스키마, 컨트롤러, 라우트 및 서비스 파일과 함께 고유한 폴더를 갖습니다. Strapi는 관리자 패널을 통해 콘텐츠 타입을 생성할 때 이를 자동으로 생성하지만, 수동으로 생성할 수도 있습니다.

콘텐츠 타입 구축 및 콘텐츠 관리

콘텐츠 타입은 Strapi의 핵심으로, 데이터 스키마를 정의하고 API 엔드포인트, 관리자 패널 폼 및 데이터베이스 테이블을 자동으로 생성합니다. Strapi는 두 가지 주요 유형을 지원합니다: 컬렉션 타입(블로그 게시물이나 제품처럼 여러 항목이 있는 경우)과 싱글 타입(홈페이지나 사이트 설정처럼 단일 항목만 존재하는 경우).

콘텐츠 타입 빌더 walkthrough

Strapi 관리자 패널의 콘텐츠 타입 빌더를 사용하면 시각적으로 스키마를 정의할 수 있습니다. 텍스트, 리치 텍스트, 미디어, 숫자, 불리언, 관계, 컴포넌트, 동적 영역(Dynamic Zone), JSON 등 필드 유형을 선택하면 Strapi가 스키마 파일을 작성해 줍니다.

다음은 Article 콘텐츠 타입 스키마의 내부 모습입니다:

{
  "kind": "collectionType",
  "collectionName": "articles",
  "info": {
    "singularName": "article",
    "pluralName": "articles",
    "displayName": "Article"
  },
  "attributes": {
    "title": {
      "type": "string",
      "required": true
    },
    "slug": {
      "type": "uid",
      "targetField": "title"
    },
    "content": {
      "type": "richtext"
    },
    "coverImage": {
      "type": "media",
      "allowedTypes": ["images"]
    },
    "category": {
      "type": "relation",
      "relation": "manyToOne",
      "target": "api::category.category"
    },
    "publishedAt": {
      "type": "datetime"
    }
  }
}

또한 새로운 AI 콘텐츠 타입 빌더를 사용하여 "제목, 슬러그, 리치 텍스트 콘텐츠, 커버 이미지 및 카테고리가 있는 블로그가 필요합니다"와 같은 일반 영어 설명으로부터 스키마를 생성할 수 있습니다. Strapi는 스키마 JSON을 생성하고 데이터베이스 테이블을 만듭니다. 프로토타이핑에 매우 유용합니다.

컴포넌트 및 동적 영역(Dynamic Zones)

컴포넌트는 재사용 가능한 필드 그룹입니다. 콘텐츠 구조를 위한 React 컴포넌트라고 생각하면 됩니다. metaTitle, metaDescription 및 canonicalUrl 필드가 있는 "SEO" 컴포넌트는 모든 콘텐츠 타입에 첨부할 수 있습니다.

동적 영역은 이를 한 단계 더 발전시켜, 콘텐츠 편집자가 유연한 페이지 레이아웃을 구축하기 위해 컴포넌트 목록에서 선택할 수 있게 합니다. 랜딩 페이지에는 Hero 컴포넌트, 그 다음 Features Grid, 그리고 Testimonials Slider가 있을 수 있으며, 모두 편집자가 선택하고 순서를 정합니다. 이 패턴은 모든 페이지가 다른 구조를 갖는 마케팅 사이트에 인기가 많습니다.

Draft & Publish로 콘텐츠 관리

Strapi 5는 Draft & Publish 시스템을 대폭 개편했습니다. 단일 토글 대신, 콘텐츠 관리자에서 초안 버전용과 게시된 버전용 두 개의 별도 탭을 제공합니다. 편집자는 라이브 콘텐츠에 영향을 주지 않고 초안을 자유롭게 수정할 수 있습니다. 준비가 되면 게시하며, 초안이 새로운 게시 버전이 됩니다. Content History를 사용하면 문제가 발생했을 때 이전 상태로 롤백할 수 있습니다.

Strapi API 작업하기 (REST 및 GraphQL)

Strapi는 생성하는 모든 콘텐츠 타입에 대해 REST 및 GraphQL 엔드포인트를 자동으로 생성합니다. REST API는 별도의 구성 없이 즉시 사용 가능합니다. GraphQL은 내장 플러그인을 활성화해야 하지만 설정에는 약 30초가 소요됩니다. 두 API 모두 Strapi REST API 문서에 따라 필터링, 정렬, 페이지네이션, 필드 선택 및 관계 채우기(population)를 지원합니다.

REST API 쿼리

모든 컬렉션 타입은 /api/{복수형 이름}에 엔드포인트를 갖습니다. 다음은 필터를 적용하고 관계를 채워 기사를 가져오는 방법입니다:

// Fetch published articles, sorted by date, with category populated
const response = await fetch(
  'http://localhost:1337/api/articles?' + new URLSearchParams({
    'filters[publishedAt][$notNull]': 'true',
    'sort': 'publishedAt:desc',
    'populate': 'category,coverImage',
    'pagination[page]': '1',
    'pagination[pageSize]': '10',
    'fields[0]': 'title',
    'fields[1]': 'slug',
    'fields[2]': 'publishedAt'
  }),
  {
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`
    }
  }
);

const { data, meta } = await response.json();
// data: array of articles
// meta.pagination: { page, pageSize, pageCount, total }

Strapi 5는 응답 형식을 평평하게(flattened) 만들었습니다. v4에서는 data.attributes.title을 깊이 탐색해야 했지만, v5에서는 단순히 data.title입니다. 작은 변경이지만 생활의 질(QoL)을 크게 향상시킵니다.

GraphQL 설정 및 쿼리

플러그인을 설치하여 GraphQL을 활성화합니다:

npm run strapi install graphql

그런 다음 /graphql에서 쿼리합니다:

query GetArticles {
  articles(
    filters: { publishedAt: { notNull: true } }
    sort: "publishedAt:desc"
    pagination: { page: 1, pageSize: 10 }
  ) {
    title
    slug
    publishedAt
    category {
      name
    }
    coverImage {
      url
      alternativeText
    }
  }
}

GraphQL은 프론트엔드가 깊게 중첩된 관계를 필요로 할 때 특히 유용합니다. 서로 다른 populate 매개변수를 사용한 여러 REST 호출 대신, 하나의 GraphQL 쿼리로 필요한 것만 정확히 가져올 수 있습니다.

Next.js에서 Strapi 콘텐츠 가져오기

다음은 Next.js App Router 페이지에서 Strapi 콘텐츠를 가져오는 실용적인 예제로, 이는 가장 일반적인 Strapi + 프론트엔드 프레임워크 조합 중 하나입니다:

// app/blog/page.tsx
async function getArticles() {
  const res = await fetch(
    `${process.env.STRAPI_URL}/api/articles?populate=category,coverImage&sort=publishedAt:desc`,
    {
      headers: {
        Authorization: `Bearer ${process.env.STRAPI_TOKEN}`,
      },
      next: { revalidate: 60 }, // ISR: revalidate every 60 seconds
    }
  );

  if (!res.ok) throw new Error('Failed to fetch articles');
  const { data } = await res.json();
  return data;
}

export default async function BlogPage() {
  const articles = await getArticles();

  return (
    <main>
      {articles.map((article) => (
        <article key={article.documentId}>
          <h2>{article.title}</h2>
          <span>{article.category?.name}</span>
        </article>
      ))}
    </main>
  );
}

v5의 documentId에 주목하세요. 이는 v4의 숫자 id를 대체합니다. 이는 놓치면 어려움을 겪게 될 마이그레이션 세부 사항 중 하나입니다.

Strapi의 커스텀 컨트롤러, 서비스 및 라우트

커스텀 컨트롤러는 Strapi가 Contentful이나 Sanity와 같은 SaaS 헤드리스 CMS 플랫폼과 차별화되는 지점입니다. Strapi는 Node.js 애플리케이션으로서 사용자의 서버에서 실행되므로, 자동 생성된 엔드포인트를 자체 비즈니스 로직, 입력 유효성 검사, 데이터 변환, 외부 API 호출, 알림 트리거 등 Express.js 앱에서 수행할 수 있는 모든 작업으로 덮어쓸 수 있습니다. 팀이 호스팅 대안보다 Strapi를 선택하게 만드는 기능이 바로 이것이라고 생각합니다.

Strapi 컨트롤러 문서는 전체 API를 다룹니다. 다음은 공식 서비스 및 컨트롤러 예제를 기반으로 제가 가장 많이 사용하는 패턴입니다.

핵심 컨트롤러 확장

Strapi는 createCoreController 팩토리를 제공합니다. 나머지 자동 생성된 동작을 유지하면서 특정 액션(find, findOne, create, update, delete)을 덮어써서 확장할 수 있습니다:

// src/api/article/controllers/article.ts
import { factories } from '@strapi/strapi';

export default factories.createCoreController(
  'api::article.article',
  ({ strapi }) => ({
    // Override the default find to add custom filtering
    async find(ctx) {
      // Validate and sanitize the incoming query
      const sanitizedQuery = await this.sanitizeQuery(ctx);

      // Add your custom logic -- e.g., only return articles
      // that belong to the authenticated user's organization
      const user = ctx.state.user;
      if (user?.organization) {
        sanitizedQuery.filters = {
          ...sanitizedQuery.filters,
          organization: user.organization.id,
        };
      }

      const { results, pagination } = await strapi
        .service('api::article.article')
        .find(sanitizedQuery);

      const sanitizedResults = await this.sanitizeOutput(results, ctx);
      return this.transformResponse(sanitizedResults, { pagination });
    },
  })
);

커스텀 서비스 작성

서비스는 컨트롤러(및 다른 서비스)가 호출할 수 있는 재사용 가능한 비즈니스 로직을 포함합니다. 컨트롤러는 얇게(thin), 서비스는 두껍게(fat) 유지하세요:

// src/api/article/services/article.ts
import { factories } from '@strapi/strapi';

export default factories.createCoreService(
  'api::article.article',
  ({ strapi }) => ({
    // Custom method: publish article and notify subscribers
    async publishAndNotify(documentId: string) {
      const article = await strapi.documents('api::article.article').update({
        documentId,
        data: { publishedAt: new Date() },
        status: 'published',
      });

      // Call an external notification service
      const subscribers = await strapi
        .service('api::subscriber.subscriber')
        .find({ filters: { active: true } });

      await Promise.allSettled(
        subscribers.results.map((sub) =>
          fetch(process.env.NOTIFICATION_WEBHOOK, {
            method: 'POST',
            body: JSON.stringify({
              email: sub.email,
              article: article.title,
            }),
          })
        )
      );

      return article;
    },
  })
);

커스텀 라우트 추가

자동 생성된 CRUD 라우트와 함께 커스텀 라우트를 등록합니다:

// src/api/article/routes/custom-article.ts
export default {
  routes: [
    {
      method: 'POST',
      path: '/articles/:id/publish-notify',
      handler: 'article.publishAndNotify',
      config: {
        policies: ['admin::isAuthenticatedAdmin'],
      },
    },
  ],
};

그런 다음 핸들러를 컨트롤러에 추가합니다:

async publishAndNotify(ctx) {
  const { id } = ctx.params;
  const article = await strapi
    .service('api::article.article')
    .publishAndNotify(id);
  return this.transformResponse(article);
}

이러한 종류의 백엔드 커스터마이징은 Contentful이나 Sanity에서는 단순히 불가능하며, 별도의 서버리스 함수 또는 미들웨어 레이어가 필요합니다. Strapi에서는 모든 것이 하나의 코드베이스 내에 있습니다.

플러그인 생태계 및 자체 구축

Strapi의 플러그인 마켓플레이스에는 SEO 메타데이터부터 Stripe 결제까지 모든 것을 다루는 500개 이상의 플러그인이 있습니다. 일부는 공식(Strapi 팀이 유지 관리)이고, 다른 일부는 커뮤니티에서 제작했습니다. npm 패키지와 마찬가지로 품질이 다양하므로 설치 전에 GitHub 스타, 최근 커밋 및 Strapi 5 호환성을 확인하세요.

필수 플러그인

이들은 Strapi에 포함되어 있거나 한 번의 설치 명령어로 사용할 수 있습니다:

• GraphQL: /graphql 엔드포인트 및 GraphQL Playground 추가
• i18n: 로케일 기반 콘텐츠 변형을 지원하는 국제화
• Users & Permissions: 인증, 역할, 공개/인증된 API 접근
• Upload: 로컬 스토리지, AWS S3 또는 Cloudinary 제공자를 사용하는 미디어 라이브러리
• Email: SendGrid, Mailgun, Amazon SES 또는 SMTP를 통한 트랜잭셔널 이메일

확인해 볼 만한 커뮤니티 플러그인: @strapi/plugin-seo(메타 태그 및 소셜 카드), strapi-plugin-sitemap(자동 생성 XML 사이트맵) 및 strapi-plugin-content-versioning(내장 Content History beyond 세분화된 버전 제어).

커스텀 플러그인 구축 (Strapi 5 SDK)

Strapi 5는 플러그인 개발을 간소화하는 새로운 플러그인 SDK를 도입했습니다. 공식 플러그인 튜토리얼은 전체 과정을 안내하지만, 요점은 다음과 같습니다:

1. npx @strapi/sdk-plugin init my-plugin을 실행하여 스캐폴딩
2. 플러그인의 콘텐츠 타입, 컨트롤러 및 관리자 패널 UI 정의
3. npm run build로 빌드하고 npm에 게시

플러그인을 구축할지 커스텀 컨트롤러를 작성할지의 결정은 재사용성에 달려 있습니다. 로직이 프로젝트 특정한 경우 컨트롤러를 사용하세요. 프로젝트 간 또는 커뮤니티와 공유하려면 플러그인으로 패키징하세요.

데이터베이스 구성: PostgreSQL, MySQL 또는 SQLite?

Strapi는 PostgreSQL, MySQL, MariaDB 및 SQLite를 기본적으로 지원합니다. SQLite는 설정이 필요 없으므로 새 프로젝트의 기본값으로 제공되며, 개발 및 프로토타이핑에 적합합니다. 프로덕션에서는 PostgreSQL이 권장되며 Strapi 팀이 가장 집중적으로 테스트하는 데이터베이스입니다.

프로덕션 준비가 된 PostgreSQL 구성은 다음과 같습니다:

// config/database.ts
export default ({ env }) => ({
  connection: {
    client: 'postgres',
    connection: {
      host: env('DATABASE_HOST', 'localhost'),
      port: env.int('DATABASE_PORT', 5432),
      database: env('DATABASE_NAME', 'strapi'),
      user: env('DATABASE_USERNAME', 'strapi'),
      password: env('DATABASE_PASSWORD', ''),
      ssl: env.bool('DATABASE_SSL', false) && {
        rejectUnauthorized: env.bool('DATABASE_SSL_REJECT', true),
      },
    },
    pool: {
      min: env.int('DATABASE_POOL_MIN', 2),
      max: env.int('DATABASE_POOL_MAX', 10),
    },
  },
});

데이터베이스 옵션을 고려 중이라면, 차이점을 심도 있게 다루는 PostgreSQL vs MySQL 비교를 참고하세요.

10,000개 이상의 항목이 있는 콘텐츠 중심 애플리케이션의 경우, 연결 풀링(PgBouncer)이 있는 PostgreSQL이 부하를 잘 처리합니다. SQLite는 몇 hundred 개의 동시 요청에서 쓰기 경합 문제를 보이기 시작하며, 블로그 관리자용으로는 괜찮지만 고트래픽 API에는 문제가 될 수 있습니다.

Strapi를 프로덕션에 배포하기

프로덕션 배포는 대부분의 Strapi 가이드가 중단되고 개발자들이 막히는 지점입니다. Strapi는 영구적인 Node.js 서버(정적 사이트가 아님), 데이터베이스, 미디어 스토리지 및 적절한 환경 구성이 필요합니다. 두 가지 경로가 있습니다: Strapi Cloud(관리형) 또는 Railway, Render, DigitalOcean과 같은 플랫폼에서의 자체 호스팅이며, 이는 Strapi 배포 문서에 개요가 나와 있습니다.

Strapi Cloud (관리형)

Strapi Cloud는 공식 호스팅 옵션입니다. 서버 프로비저닝, 데이터베이스 관리, CDN 및 백업을 처리합니다. 티어는 다음과 같습니다:

Strapi Cloud는 프로덕션으로 가는 가장 빠른 길입니다. 하지만 Contentful과 Sanity의 호스팅과 비교하면 아직 성숙 단계에 있으며, 리전이 적고 접근 제어가 덜 세분화되며 무료 티어가 상당히 제한적입니다. 사이드 프로젝트나 MVP에는 무료 티어가 작동합니다. 실제 트래픽을 처리하는 프로덕션 앱에는 Essential 또는 Pro가 필요할 것입니다.

Railway 또는 Render에서 자체 호스팅

경험상 Railway는 자체 호스팅 프로덕션 Strapi 인스턴스로 가는 가장 빠른 길입니다. GitHub 저장소를 연결하고 환경 변수를 설정하면 Railway가 나머지를 처리합니다. 자세한 플랫폼 비교는 Railway vs Render 비교를 참조하세요.

프로덕션 환경 구성은 다음과 같습니다:

# .env.production
NODE_ENV=production
HOST=0.0.0.0
PORT=1337

# App keys (generate unique values!)
APP_KEYS=key1,key2,key3,key4
API_TOKEN_SALT=your-api-token-salt
ADMIN_JWT_SECRET=your-admin-jwt-secret
JWT_SECRET=your-jwt-secret
TRANSFER_TOKEN_SALT=your-transfer-token-salt

# Database (Railway provides DATABASE_URL automatically)
DATABASE_CLIENT=postgres
DATABASE_HOST=${PGHOST}
DATABASE_PORT=${PGPORT}
DATABASE_NAME=${PGDATABASE}
DATABASE_USERNAME=${PGUSER}
DATABASE_PASSWORD=${PGPASSWORD}
DATABASE_SSL=true

# Media storage (S3-compatible)
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret
AWS_REGION=us-east-1
AWS_BUCKET=your-strapi-uploads

컨테이너를 선호한다면 Strapi를 Docker화하여 어디에나 배포할 수 있으며, 컨테이너화 옵션에 대한 가이드를 참조하세요. Railway는 Dockerfile 없이 자동 빌드를 위한 Nixpacks도 지원합니다.

프로덕션 체크리스트

-live 전에 다음 사항을 확인하세요:

• 관리자 패널 빌드: npm run build를 실행하여 프로덕션용 React 관리자를 컴파일합니다.
• 프로세스 관리자: PM2를 사용하여 Strapi를 실행 상태로 유지하고 충돌 시 자동 재시작합니다.
• 헬스 체크: Strapi는 /_health를 노출하며(HTTP 204 반환), 로드 밸런서를 이에 지정합니다.
• 미디어 스토리지: 로컬 업로드에서 S3 또는 Cloudinary로 전환합니다. 로컬 스토리지는 대부분의 PaaS 플랫폼에서 지속되지 않습니다.
• 리버스 프록시: SSL 종료 및 정적 파일 캐싱을 위해 Strapi 앞에 Nginx 또는 Caddy를 배치합니다.
• 환경 변수: 비밀 정보를 커밋하지 마세요. 플랫폼 네이티브 env var 관리를 사용하세요.

Strapi vs Sanity vs Contentful: 무엇을 선택해야 할까요?

Strapi, Sanity 및 Contentful 사이의 선택은 세 가지 사항에 달려 있습니다: 자체 호스팅 필요 여부, 콘텐츠 협업 방식 및 예산 제약. 세 가지 모두 프로덕션 등급의 헤드리스 CMS 플랫폼이지만 근본적으로 다른 trade-off를 만듭니다. 더 깊은 내용은 Sanity CMS 가이드와 Contentful 가이드를 확인하세요.

결정 프레임워크, 실제 제약 조건에 따라 선택:

Techsy에서는 Strapi, Sanity 및 Contentful을 사용하여 헤드리스 CMS 아키텍처를 구축합니다. 프로젝트에 적합한 CMS 선택이나 프로덕션 준비가 된 Strapi 설정에 도움이 필요하면 무료 상담을 받으세요.

솔직한 장단점 및 Strapi를 사용하지 않아야 할 때

세 개의 클라이언트 프로젝트에서 Strapi 5를 테스트한 후, 솔직한 분석을 제시합니다. Strapi는 완전한 백엔드 제어를 원하는 팀에게 훌륭하지만, 모든 사람에게 적합한 도구는 아닙니다.

장점:

• 완전한 코드 소유권: 당신의 데이터, 당신의 서버, 당신의 규칙
• 벤더 락인 없는 MIT 라이선스
• v5의 TypeScript 우선 및 강력한 타입 추론
• 콘텐츠 스키마로부터 자동 생성된 REST 및 GraphQL 엔드포인트
• 활발한 커뮤니티: 65,000+ GitHub 스타, 20,000+ 회원 Discord
• 마켓플레이스의 500+ 플러그인
• 커스텀 컨트롤러를 통한 Express.js 수준의 백엔드 유연성
• 자체 호스팅을 원하지 않는 경우 관리형 옵션인 Strapi Cloud 제공

단점:

• 자체 호스팅에는 운영 작업 필요: 업데이트, 모니터링 및 백업에 월 10-20시간 예상
• 실시간 협업 부재 (두 편집자가 서로의 변경 사항을 덮어쓸 수 있음)
• Strapi 4에서 5로의 마이그레이션 마찰: Entity Service에서 Document Service로, 새로운 응답 형식, 플러그인 호환성 격차
• Strapi Cloud는 Contentful이나 Sanity의 호스팅 플랫폼과 비교하면 아직 성숙 단계
• Contentful보다 적은 엔터프라이즈 채택, 더 적은 준수 인증
• 관리자 패널 커스터마이징은 가능하지만 Strapi의 내부 API에 대한 깊은 지식 필요

Strapi를 사용하지 않아야 할 때:

• 실시간 협업 필요, 편집 팀이 콘텐츠에서 동시에 작업하나요? Sanity를 사용하세요. Strapi에는 멀티플레이어 편집이 없습니다.
• 엔터프라이즈 거버넌스 및 SOC2 필요, 준수가 중요한 조직인가요? Contentful은 거버넌스 툴링에서 10년의 선두 주자입니다.
• 비기술적 팀, 개발자 지원 없음, Strapi는 설정, 배포 및 유지 관리를 위해 개발자가 필요합니다. 팀이 모두 마케터라면 SaaS CMS 또는 WordPress를 고려하세요.
• 서버리스 우선 아키텍처, Strapi는 영구적인 서버가 필요합니다. 엣지 함수와 서버리스로 entirely 구축하는 경우 Sanity 또는 Contentful이 더 적합합니다.

FAQ

Strapi란 무엇이며 어떻게 작동하나요?

Strapi는 Node.js 기반으로 구축된 오픈소스 헤드리스 CMS입니다. 시각적 빌더나 코드를 통해 콘텐츠 타입을 정의하면, Strapi는 REST 및 GraphQL API 엔드포인트를 자동 생성합니다. 프론트엔드 애플리케이션은 이러한 엔드포인트에서 JSON으로 콘텐츠를 가져옵니다. 관리자 패널은 콘텐츠 편집자가 코드를 작성하지 않고 항목을 관리할 수 있는 React 기반 인터페이스를 제공합니다.

Strapi는 무료로 사용할 수 있나요?

예. Strapi 커뮤니티 에디션은 MIT 라이선스 하에 무료이며 오픈소스입니다. 사용 제한, 좌석 제한 또는 API 호출 캡 없이 자체 서버에 호스팅할 수 있습니다. Strapi Cloud(관리형 호스팅 옵션)는 월 10,000 API 호출이 포함된 무료 티어가 있으며, 유료 계획은 더 높은 제한을 위해 월 $18부터 시작합니다.

Strapi와 Contentful의 차이점은 무엇인가요?

Strapi는 오픈소스이며 자체 호스팅되어 완전한 코드 접근 및 데이터 소유권을 제공합니다. Contentful은 더 강력한 엔터프라이즈 거버넌스, 준수 인증 및 더 큰 편집 도구 세트를 갖춘 독점 SaaS 플랫폼입니다. 코드 제어 및 예산 유연성을 위해 Strapi를 선택하세요. 엔터프라이즈 준수 요구 사항 및 관리형 인프라가 필요한 더 큰 편집 팀을 위해 Contentful을 선택하세요.

Strapi는 초보자에게 좋은가요?

기본적인 Node.js 및 JavaScript 지식이 있다면 Strapi는 초보자 친화적입니다. 관리자 패널과 콘텐츠 타입 빌더는 시각적이고 직관적이며, 콘텐츠 모델링에는 코드가 필요하지 않습니다. 배포 및 커스텀 백엔드 로직에는 개발자 경험이 필요합니다. 코딩 배경이 없는 절대 초보자의 경우 WordPress 또는 완전히 관리되는 SaaS CMS가 더 쉬운 시작점이 될 것입니다.

Strapi는 어떤 데이터베이스를 사용하나요?

Strapi는 PostgreSQL, MySQL, MariaDB 및 SQLite를 지원합니다. 새 프로젝트는 제로 설정 개발을 위해 기본적으로 SQLite를 사용합니다. PostgreSQL은 프로덕션 워크로드에 권장되며, Strapi와 함께 가장 많이 테스트된 데이터베이스로 동시 접근, 복잡한 쿼리 및 JSON 필드 유형을 잘 처리합니다. 데이터베이스 연결은 config/database.ts에서 구성합니다.

Strapi를 프로덕션에 어떻게 배포하나요?

Strapi를 Strapi Cloud(월 $18부터 시작하는 관리형 호스팅)에 배포하거나, Railway, Render, DigitalOcean 또는 AWS와 같은 플랫폼에서 자체 호스팅할 수 있습니다. 자체 호스팅에는 Node.js 서버, PostgreSQL 데이터베이스, 환경 변수, 미디어 스토리지(S3 또는 Cloudinary) 및 PM2와 같은 프로세스 관리자 구성이 필요합니다. 관리자 패널을 컴파일하기 위해 배포 전에 npm run build를 실행하세요.

Strapi가 WordPress보다 나은가요?

Strapi와 WordPress는 다른 문제를 해결합니다. Strapi는 모든 프론트엔드에 JSON API를 제공하는 헤드리스 CMS로, 커스텀 앱, 멀티 플랫폼 콘텐츠 전달 또는 JavaScript 중심 사이트를 구축하는 개발자에게 이상적입니다. WordPress는 HTML 페이지를 렌더링하는 전통적인 CMS로, 코드를 작성하지 않고 테마, 드래그 앤 드롭 빌더 및 방대한 플러그인 생태계를 원하는 비기술적 사용자에게 더 적합합니다.

Strapi의 단점은 무엇인가요?

주요 단점은 자체 호스팅으로 인한 운영 오버헤드(업데이트, 모니터링, 백업), 편집 팀을 위한 실시간 협업 부재, 주요 버전 간 마이그레이션 마찰(v4에서 v5로 코드 변경 필요) 및 Contentful과 비교하여 덜 성숙한 엔터프라이즈 제공 사항입니다. Strapi Cloud는 호스팅 부담을 해결하지만 기능과 글로벌 가용성 측면에서 아직 뒤따르고 있습니다.

Strapi는 대규모 애플리케이션을 처리할 수 있나요?

예. Strapi는 적절한 인프라(PostgreSQL 연결 풀링, 로드 밸런서 뒤의 수평 확장, 미디어 자산용 CDN 및 캐싱용 Redis)를 사용하여 대규모 애플리케이션을 처리할 수 있습니다. IBM, NASA 및 Toyota와 같은 회사들이 프로덕션에서 Strapi를 사용합니다. 병목 현상은 일반적으로 Strapi 자체가 아닌 데이터베이스 성능과 호스팅 구성입니다.

Strapi Cloud란 무엇이며 비용은 얼마인가요?

Strapi Cloud는 Strapi 프로젝트용 공식 관리형 호스팅 플랫폼입니다. 서버 프로비저닝, 데이터베이스 관리, CDN 및 자동 백업을 처리합니다. 가격은 무료 티어(1 프로젝트, 월 10K API 호출)로 시작하며, 이후 Essential은 월 $18, Pro는 월 $90, Scale은 월 $450입니다. 각 티어는 API 호출 제한, 팀 좌석 및 스토리지 용량을 증가시킵니다.