> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baeum.ai.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# n8n

**워크플로우 자동화 플랫폼**입니다. 다양한 서비스와 API를 연결하여 반복 작업을 자동화할 수 있습니다. Zapier, Make(Integromat)의 오픈소스 대안입니다.

## 어디에 쓰이나요?

* **업무 자동화**: 이메일 수신 → Slack 알림 → 스프레드시트 기록 같은 반복 작업을 자동 처리
* **데이터 파이프라인**: 여러 API에서 데이터를 수집하고 가공하여 데이터베이스에 저장
* **AI 워크플로우**: LLM 호출, 임베딩 생성, 벡터 검색 등을 워크플로우로 구성
* **웹훅 처리**: 외부 서비스의 이벤트를 수신하여 자동으로 후속 작업 실행
* **스케줄링**: 매일/매주 정해진 시간에 특정 작업을 반복 실행

400개 이상의 서비스 연동을 지원하며 (Google Sheets, Slack, GitHub, OpenAI 등), 노드를 드래그 앤 드롭으로 연결하여 워크플로우를 구성합니다. 코드가 필요한 경우 JavaScript/Python 노드를 추가할 수도 있습니다.

## Docker Compose

```yaml docker-compose.yml theme={null}
services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=changeme
      - GENERIC_TIMEZONE=Asia/Seoul
      - TZ=Asia/Seoul
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:
```

### PostgreSQL 연동 구성

기본 SQLite 대신 PostgreSQL을 사용하려면 다음과 같이 구성합니다.

```yaml docker-compose.yml theme={null}
services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=n8n-db
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=postgres
      - DB_POSTGRESDB_PASSWORD=changeme
      - GENERIC_TIMEZONE=Asia/Seoul
      - TZ=Asia/Seoul
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      n8n-db:
        condition: service_healthy

  n8n-db:
    image: postgres:17-alpine
    container_name: n8n-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=changeme
      - POSTGRES_DB=n8n
    volumes:
      - n8n_db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 3s
      timeout: 3s
      retries: 10

volumes:
  n8n_data:
  n8n_db_data:
```

## 실행

```bash theme={null}
docker compose up -d
```

## 접속 확인

브라우저에서 `http://localhost:5678`로 접속합니다. 초기 접속 시 관리자 계정을 생성합니다.

## 기본 정보

| 항목        | 값           |
| --------- | ----------- |
| 웹 UI 포트   | 5678        |
| 기본 데이터베이스 | SQLite (내장) |
| 타임존       | Asia/Seoul  |

## 환경 변수

| 변수                        | 설명                             |
| ------------------------- | ------------------------------ |
| `N8N_BASIC_AUTH_ACTIVE`   | 기본 인증 활성화                      |
| `N8N_BASIC_AUTH_USER`     | 기본 인증 사용자명                     |
| `N8N_BASIC_AUTH_PASSWORD` | 기본 인증 비밀번호                     |
| `DB_TYPE`                 | 데이터베이스 종류 (sqlite, postgresdb) |
| `GENERIC_TIMEZONE`        | 워크플로우 타임존                      |
| `N8N_ENCRYPTION_KEY`      | 자격 증명 암호화 키                    |
| `WEBHOOK_URL`             | 외부 웹훅 URL                      |

## 라이선스

| 구분     | 내용                                                                      |
| ------ | ----------------------------------------------------------------------- |
| 라이선스   | Sustainable Use License (Community), Enterprise License (Enterprise)    |
| 개인 사용  | 자유롭게 사용 가능                                                              |
| 상업적 사용 | 연 매출 4만 달러 미만 기업은 무료. 초과 시 Enterprise 라이선스 필요. n8n을 경쟁 제품으로 재판매하는 것은 불가 |

## 참고

* [n8n Docker 설치 가이드](https://docs.n8n.io/hosting/installation/docker/)
* [n8n 공식 문서](https://docs.n8n.io/)

## 설치 점검 목록

* `docker compose up -d` 후 `docker compose ps`로 컨테이너 상태를 확인했습니다.
* 기본 포트/계정/비밀번호를 문서대로 점검했습니다.
* 운영용으로 사용할 때 기본 비밀번호/시크릿 값을 변경했습니다.
* 장애 분석을 위해 `docker compose logs -f` 확인 방법을 숙지했습니다.

## 문제 해결 가이드

* 컨테이너가 실행되지 않으면 `docker compose logs -f`로 오류 원인을 먼저 확인합니다.
* 포트 충돌이 나면 기존 프로세스를 종료하거나 포트 매핑 값을 변경합니다.
* 이미지 pull 실패 시 네트워크 연결 및 레지스트리 접근 권한을 확인합니다.
* 설정 변경 후 문제가 지속되면 `docker compose down` 후 다시 `up -d`로 재기동합니다.

## 관련 문서

<CardGroup cols={2}>
  <Card title="Setup 홈" icon="house" href="/setup/index">
    운영체제별 설치 흐름을 다시 확인합니다.
  </Card>

  <Card title="다음: Langfuse" icon="arrow-right" href="/stacks/langfuse">
    다음 설치 단계를 이어서 진행합니다.
  </Card>
</CardGroup>