Directus: AI 콘텐츠 워크플로우를 구동하는 오픈소스 Headless CMS — 2026 설치 및 API 가이드

mkdir ~/directus && cd ~/directus

# compose 파일 생성
cat > docker-compose.yml << 'EOF'
version: "3"
services:
  directus:
    image: directus/directus:11.3.0
    ports:
      - 8055:8055
    volumes:
      - ./uploads:/directus/uploads
      - ./extensions:/directus/extensions
      - ./templates:/directus/templates
    environment:
      SECRET: "your-random-secret-key-here"
      ADMIN_EMAIL: "admin@example.com"
      ADMIN_PASSWORD: "SecureAdminPass123!"
      DB_CLIENT: "pg"
      DB_HOST: "database"
      DB_PORT: "5432"
      DB_DATABASE: "directus"
      DB_USER: "directus"
      DB_PASSWORD: "directus-pass"
      WEBSOCKETS_ENABLED: "true"
      CORS_ENABLED: "true"
      CORS_ORIGIN: "true"
    depends_on:
      - database
      - redis

  database:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: "directus"
      POSTGRES_USER: "directus"
      POSTGRES_PASSWORD: "directus-pass"
    volumes:
      - pg-data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data

volumes:
  pg-data:
  redis-data:
EOF

docker compose up -d

# 초기화를 기다린 후 상태 확인
curl -s http://localhost:8055/server/health | jq .
# 예상 출력: {"status":"ok","release":"11.3.0"}

# 프로덕션용 .env 파일
cat > .env << 'EOF'
# 보안
SECRET=super-random-64-char-secret-for-jwt-signing
KEY=your-instance-unique-key

# 데이터베이스
DB_CLIENT=pg
DB_HOST=database
DB_PORT=5432
DB_DATABASE=directus
DB_USER=directus
DB_PASSWORD=$(openssl rand -base64 32)

# 캐시 & 세션
CACHE_ENABLED=true
CACHE_STORE=redis
CACHE_REDIS=redis://redis:6379
RATE_LIMITER_ENABLED=true
RATE_LIMITER_STORE=redis

# 파일 스토리지 (프로덕션용 S3)
STORAGE_LOCATIONS=s3
STORAGE_S3_DRIVER=s3
STORAGE_S3_KEY=your-access-key
STORAGE_S3_SECRET=your-secret-key
STORAGE_S3_BUCKET=your-bucket
STORAGE_S3_REGION=us-east-1
STORAGE_S3_ENDPOINT=s3.amazonaws.com

# 이메일
EMAIL_TRANSPORT=smtp
EMAIL_SMTP_HOST=smtp.sendgrid.net
EMAIL_SMTP_PORT=587
EMAIL_SMTP_USER=apikey
EMAIL_SMTP_PASSWORD=your-sendgrid-key

# AI / 확장
EXTENSIONS_PATH=./extensions
EXTENSIONS_AUTO_RELOAD=true
EOF

# REST API로 컬렉션 생성
curl -X POST http://localhost:8055/collections \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{
    "collection": "articles",
    "schema": { "name": "articles" },
    "meta": { "icon": "article", "singleton": false },
    "fields": [
      { "field": "id", "type": "uuid", "meta": { "special": ["uuid"] }, "schema": { "is_primary_key": true } },
      { "field": "title", "type": "string", "meta": {}, "schema": {} },
      { "field": "content", "type": "text", "meta": {}, "schema": {} },
      { "field": "status", "type": "string", "meta": { "interface": "select-dropdown", "options": { "choices": [{ "text": "초안", "value": "draft" }, { "text": "게시됨", "value": "published" }] } }, "schema": { "default_value": "draft" } },
      { "field": "ai_generated", "type": "boolean", "meta": {}, "schema": { "default_value": false } },
      { "field": "seo_score", "type": "integer", "meta": {}, "schema": {} },
      { "field": "published_at", "type": "timestamp", "meta": {}, "schema": {} },
      { "field": "hero_image", "type": "uuid", "meta": { "special": ["file"] }, "schema": {} }
    ]
  }'

# 필터링과 필드 선택으로 모든 게시된 아티클 읽기
curl -s "http://localhost:8055/items/articles?filter[status][_eq]=published&fields=id,title,seo_score,published_at&sort=-published_at&limit=10" \
  -H "Authorization: Bearer <token>" | jq .

# 아티클 생성
curl -X POST http://localhost:8055/items/articles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"title":"Directus 시작하기","content":"Directus는 Headless CMS입니다...","status":"draft","seo_score":85}'

# 부분 업데이트
curl -X PATCH http://localhost:8055/items/articles/<id> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"status":"published","published_at":"2026-05-19T10:00:00Z"}'

# 집계 쿼리: 상태별 평균 SEO 점수
curl -s "http://localhost:8055/items/articles?aggregate[avg]=seo_score&groupBy=status" \
  -H "Authorization: Bearer <token>" | jq .

# 깊은 관계 쿼리: 작성자 정보와 이미지 변환이 있는 아티클
curl -s "http://localhost:8055/items/articles?fields=id,title,author.name,author.email,hero_image.id,hero_image.filename_disk&filter[status][_eq]=published" \
  -H "Authorization: Bearer <token>" | jq .

# 스키마 내성
curl -X POST http://localhost:8055/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __schema { types { name } } }"}' | jq .

# 필터링이 있는 쿼리
curl -X POST http://localhost:8055/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "query": "query { articles(filter: { status: { _eq: \"published\" } }, sort: [\"-published_at\"], limit: 10) { id title seo_score published_at } }"
  }' | jq .

# 뮤테이션: 아티클 생성
curl -X POST http://localhost:8055/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "query": "mutation { create_articles_item(data: { title: \"GraphQL 가이드\", content: \"내용은 여기...\", status: \"draft\", seo_score: 90 }) { id title } }"
  }' | jq .

npm install @directus/sdk@18.0.0

import { createDirectus, rest, readItems, createItem, staticToken } from '@directus/sdk';

const client = createDirectus('http://localhost:8055')
  .with(rest())
  .with(staticToken('your-static-token'));

// 필터가 있는 아티클 가져오기
const articles = await client.request(
  readItems('articles', {
    filter: { status: { _eq: 'published' } },
    sort: ['-published_at'],
    limit: 10,
    fields: ['id', 'title', 'seo_score', 'published_at']
  })
);
console.log(`${articles.length}개의 아티클을 찾았습니다`);

// 아티클 생성
const newArticle = await client.request(
  createItem('articles', {
    title: 'AI 기반 콘텐츠 전략',
    content: 'GPT-4로 생성...',
    status: 'draft',
    ai_generated: true,
    seo_score: 92
  })
);
console.log('생성됨:', newArticle.id);

# ai_flag=true로 아티클이 생성될 때 트리거되는 Flow를 API로 생성
curl -X POST http://localhost:8055/flows \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{
    "name": "AI 콘텐츠 생성기",
    "status": "active",
    "trigger": "event",
    "accountability": "all",
    "options": { "type": "filter", "scope": ["items.create.articles"] }
  }'

// extensions/hooks/ai-content/index.js
import { defineHook } from '@directus/extensions-sdk';

export default defineHook(({ filter, action }) => {
  filter('articles.items.create', async (payload, meta, context) => {
    if (payload.ai_generate === true && !payload.content) {
      const { OpenAI } = await import('openai');
      const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

      const response = await openai.chat.completions.create({
        model: 'gpt-4o',
        messages: [
          { role: 'system', content: 'You are a technical content writer.' },
          { role: 'user', content: `Write a blog post titled: "${payload.title}". Output JSON with fields: content, excerpt, seo_keywords (array).` }
        ],
        response_format: { type: 'json_object' },
        max_tokens: 2000
      });

      const result = JSON.parse(response.choices[0].message.content);
      payload.content = result.content;
      payload.excerpt = result.excerpt;
      payload.seo_keywords = result.seo_keywords;
      payload.ai_generated = true;
      payload.status = 'review'; // 강제 리뷰 상태
    }
    return payload;
  });

  // AI 생성 이벤트 기록
  action('articles.items.create', async (meta, context) => {
    if (meta.payload.ai_generated) {
      await context.database('activity').insert({
        action: 'ai_generate',
        user: meta.user,
        collection: 'articles',
        item: meta.key,
        timestamp: new Date()
      });
    }
  });
});

# 확장 빌드 및 배포
cd extensions/hooks/ai-content
npm install
npm run build

# Directus가 핫 리로드한다
cp -r dist/* /directus/extensions/hooks/ai-content/

// 리뷰 대기 중인 아티클 가져오기
const pendingReview = await client.request(
  readItems('articles', {
    filter: {
      _and: [
        { status: { _eq: 'review' } },
        { ai_generated: { _eq: true } }
      ]
    },
    fields: ['id', 'title', 'excerpt', 'seo_score', 'seo_keywords', 'date_created']
  })
);

// 콘텐츠 편집자 승인
await client.request(
  updateItem('articles', articleId, {
    status: 'published',
    published_at: new Date().toISOString()
  })
);

# 읽기 레플리카로 API 수평 확장
version: "3"
services:
  directus-api-1:
    image: directus/directus:11.3.0
    environment:
      DB_CLIENT: "pg"
      DB_HOST: "postgres-primary"
      # ... 기타 환경 변수

  directus-api-2:
    image: directus/directus:11.3.0
    environment:
      DB_CLIENT: "pg"
      DB_HOST: "postgres-replica"
      # ... 기타 환경 변수

  nginx:
    image: nginx:alpine
    ports:
      - "8055:8055"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf

#!/bin/bash
# backup.sh — cron을 통해 매일 실행
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR=/backups/directus
mkdir -p $BACKUP_DIR

# 데이터베이스 백업
docker exec directus-database pg_dump -U directus directus \
  | gzip > $BACKUP_DIR/db_$TIMESTAMP.sql.gz

# 업로드 백업
tar czf $BACKUP_DIR/uploads_$TIMESTAMP.tar.gz ./uploads/

# S3로 동기화
aws s3 sync $BACKUP_DIR s3://backup-bucket/directus/ --delete

# 14일 보관
find $BACKUP_DIR -mtime +14 -delete

// extensions/endpoints/stats/index.js
import { defineEndpoint } from '@directus/extensions-sdk';

export default defineEndpoint((router, { services, database }) => {
  const { ItemsService } = services;

  router.get('/content-stats', async (req, res) => {
    const articles = new ItemsService('articles', { schema: req.schema, accountability: req.accountability });

    const [total, published, draft, aiGenerated] = await Promise.all([
      articles.count(),
      articles.count({ status: { _eq: 'published' } }),
      articles.count({ status: { _eq: 'draft' } }),
      articles.count({ ai_generated: { _eq: true } })
    ]);

    res.json({ total, published, draft, aiGenerated, ratio: Math.round((aiGenerated / total) * 100) });
  });

  router.get('/seo-report', async (req, res) => {
    const result = await database.raw(`
      SELECT status, AVG(seo_score) as avg_score, COUNT(*) as count
      FROM articles
      GROUP BY status
    `);
    res.json(result.rows);
  });
});

// 편집자 역할에 SEO 필드는 읽기 전용, 콘텐츠는 전체 접근 권한 부여
const rolePermissions = {
  collection: 'articles',
  role: 'editor-role-id',
  action: 'read',
  permissions: { status: { _eq: 'published' } },
  fields: ['id', 'title', 'content', 'published_at'], // seo_score, ai_generated 제외
  validation: null
};

// 관리자 역할은 모든 것을 볼 수 있음
const adminPermissions = {
  collection: 'articles',
  role: 'admin-role-id',
  action: 'read',
  permissions: {},
  fields: ['*'], // 모든 필드
  validation: null
};

// extensions/endpoints/metrics/index.js
import { defineEndpoint } from '@directus/extensions-sdk';

export default defineEndpoint((router, { database }) => {
  router.get('/metrics', async (_req, res) => {
    const metrics = await database.raw(`
      SELECT schemaname, tablename, n_tup_ins, n_tup_upd, n_tup_del
      FROM pg_stat_user_tables
      WHERE schemaname = 'public'
    `);

    let output = '';
    metrics.rows.forEach(row => {
      output += `directus_table_inserts{table="${row.tablename}"} ${row.n_tup_ins}\n`;
      output += `directus_table_updates{table="${row.tablename}"} ${row.n_tup_upd}\n`;
    });

    res.setHeader('Content-Type', 'text/plain');
    res.send(output);
  });
});