메인 콘텐츠로 건너뛰기

​
일반 가이드라인

업그레이드 프로세스를 시작하기 전에 항상 데이터베이스를 백업하십시오 다음 명령을 실행하세요: 
docker exec -it {db_container_name_or_id} pg_dumpall -U {postgres_user} > databases_backup.sql
백업에서 복원하려면: 
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
서버는 시작 시 필요한 모든 업그레이드 마이그레이션을 자동으로 실행합니다. 수동 명령은 필요하지 않습니다.

​
교차 버전 업그레이드(v1.22+)

v1.22부터 Twenty는 교차 버전 업그레이드를 지원합니다. 지원되는 어떤 버전에서든 각 중간 버전을 거치지 않고 최신 릴리스로 바로 이동할 수 있습니다. 예를 들어, v1.22에서 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를 설정해야 합니다. 백필 이후에 키를 변경하려면 키 회전이 필요합니다.

​
시크릿 및 서명 키 회전

ENCRYPTION_KEY 회전, JWT 서명 키 회전, 유출된 서명 키 폐기와 같은 일상 운영 작업에 대해서는 전용 키 회전 가이드를 참조하세요.

​
업그레이드 상태 확인

upgrade:status 명령을 사용하면 인스턴스 및 워크스페이스 마이그레이션의 현재 상태를 확인할 수 있습니다. 업그레이드 문제를 디버깅하거나 지원 요청을 제출할 때 유용합니다. 서버 컨테이너에서 실행하십시오: 
docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status
출력 예: 
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) 중단된 지점부터 업그레이드를 다시 시도합니다. 문제를 빠르게 식별하려면 다음을 실행하십시오: 
docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status --failed-only
이는 뒤처졌거나 실패한 워크스페이스만 표시하고 각 실패에 대한 오류 메시지도 함께 표시합니다.

​
v1.22 이전

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