upstream-twenty/packages/twenty-docs/l/ko/developers/self-host/capabilities/upgrade-guide.mdx

---
title: 업그레이드 가이드
icon: arrow-up-right-dots
---

## 일반 가이드라인

**업그레이드 프로세스를 시작하기 전에 항상 데이터베이스를 백업하십시오** 다음 명령을 실행하세요:

```bash
docker exec -it {db_container_name_or_id} pg_dumpall -U {postgres_user} > databases_backup.sql
```

백업에서 복원하려면:

```bash
cat databases_backup.sql | docker exec -i {db_container_name_or_id} psql -U {postgres_user}
```

Docker Compose를 사용하는 경우 다음 단계를 따르십시오:

1. Twenty 중지: `docker compose down`
2. `docker-compose.yml` 옆에 있는 `.env` 파일에서 `TAG` 값을 변경하십시오
3. Twenty 시작: `docker compose up -d`

서버는 시작 시 필요한 모든 업그레이드 마이그레이션을 자동으로 실행합니다. 수동 명령은 필요하지 않습니다.

## v2.34+로 업그레이드 — PostgreSQL 15 이상 필요

Twenty v2.34에는 PostgreSQL 15 이상이 필요합니다. 공식 Docker Compose 구성은 PostgreSQL 16을 사용합니다. 인스턴스가 외부에서 관리되는 데이터베이스에 연결되는 경우 v2.34 서버를 시작하기 전에 해당 데이터베이스를 업그레이드하세요.

## 교차 버전 업그레이드(v1.23+)

**v1.23**부터 Twenty는 교차 버전 업그레이드를 지원합니다. 지원되는 어떤 버전에서든 각 중간 버전을 거치지 않고 최신 릴리스로 바로 이동할 수 있습니다.

예를 들어, v1.23에서 v2.0으로 바로 업그레이드하는 것이 완전히 지원됩니다.

## v2.5+로 업그레이드 — 저장 상태 암호화 엔벨로프

**v2.5**부터 Twenty는 저장 상태의 시크릿(OAuth 토큰, 애플리케이션 변수, 서명 키의 개인 키, 민감한 설정값, TOTP 시크릿)을 버전이 지정된 `enc:v2:` 엔벨로프에 담아, `ENCRYPTION_KEY`(또는 `ENCRYPTION_KEY`가 설정되지 않은 경우 `APP_SECRET`)로 암호화해 저장합니다.

v2.5에서 첫 부팅 시, 기존 행을 새로운 엔벨로프에 백필하는 속도가 느린 업그레이드 명령이 실행됩니다. 이는 멱등적이어서 — 서버를 중단했다가 다시 시작해도 중단된 지점부터 재개되지만 — 대규모 데이터베이스에서는 시간이 오래 걸릴 수 있습니다. `upgrade:status`로 진행 상황을 모니터링할 수 있습니다.

백필이 처음부터 해당 키로 행을 기록할 수 있도록, v2.5 업그레이드 **이전에** 전용 `ENCRYPTION_KEY`를 설정해야 합니다. 백필 이후에 키를 변경하려면 [키 회전](/l/ko/developers/self-host/capabilities/key-rotation)이 필요합니다.

## 시크릿 및 서명 키 회전

`ENCRYPTION_KEY` 회전, JWT 서명 키 회전, 유출된 서명 키 폐기와 같은 일상 운영 작업에 대해서는 전용 [키 회전 가이드](/l/ko/developers/self-host/capabilities/key-rotation)를 참조하세요.

## 업그레이드 상태 확인

`upgrade:status` 명령을 사용하면 인스턴스 및 워크스페이스 마이그레이션의 현재 상태를 확인할 수 있습니다. 업그레이드 문제를 디버깅하거나 지원 요청을 제출할 때 유용합니다.

서버 컨테이너에서 실행하십시오:

```bash
docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status
```

출력 예:

```sh
APP_VERSION: v1.23.0

Instance
    Inferred version: 1.23.0
    Latest command:   1.23.0_DropWorkspaceVersionColumnFastInstanceCommand_1785000000000
    Status:           Up to date
    Executed by:      v1.23.0
    At:               2026-04-16T11:43:58.823Z

Workspace
  Apple (20202020-1c25-4d02-bf25-6aeccf7ea419)
      Inferred version: 1.23.0
      Latest command:   1.23.0_UpdateGlobalObjectContextCommandMenuItemsCommand_1780000005000
      Status:           Up to date
      Executed by:      v1.23.0
      At:               2026-04-16T11:44:09.361Z

Summary
    Instance: Up to date
    Workspaces: 1 up to date, 0 behind, 0 failed (1 total)
```

### 옵션

| 플래그                       | 설명                                       |
| ------------------------- | ---------------------------------------- |
| `-w, --workspace-id <id>` | 특정 워크스페이스로 필터링합니다. 여러 번 지정할 수 있습니다.      |
| `-f, --failed-only`       | 최신 상태의 워크스페이스는 숨기고, 뒤처졌거나 실패한 항목만 표시합니다. |

## 문제 해결

일부 워크스페이스에서 업그레이드가 실패하면 서버는 실패한 단계 이후로 진행하지 않습니다. 서버를 다시 시작하면(`docker compose up -d`) 중단된 지점부터 업그레이드를 다시 시도합니다.

문제를 빠르게 식별하려면 다음을 실행하십시오:

```bash
docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status --failed-only
```

이는 뒤처졌거나 실패한 워크스페이스만 표시하고 각 실패에 대한 오류 메시지도 함께 표시합니다.

## v1.23 이전

인스턴스가 v1.23보다 오래된 경우, v1.23에 도달할 때까지 각 주요 태그 버전(v1.6에서 v1.7, 이어서 v1.7에서 v1.8 등)을 순차적으로 업그레이드해야 합니다. 그 이후에는 최신 버전으로 바로 업그레이드할 수 있습니다.