Skip to main content

​
일반 가이드라인

업그레이드 프로세스를 시작하기 전에 항상 데이터베이스를 백업하십시오 다음 명령을 실행하세요:
백업에서 복원하려면:
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를 설정해야 합니다. 백필 이후에 키를 변경하려면 키 회전이 필요합니다.

​
시크릿 및 서명 키 회전

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

​
업그레이드 상태 확인

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

​
옵션

​
문제 해결

일부 워크스페이스에서 업그레이드가 실패하면 서버는 실패한 단계 이후로 진행하지 않습니다. 서버를 다시 시작하면(docker compose up -d) 중단된 지점부터 업그레이드를 다시 시도합니다. 문제를 빠르게 식별하려면 다음을 실행하십시오:
이는 뒤처졌거나 실패한 워크스페이스만 표시하고 각 실패에 대한 오류 메시지도 함께 표시합니다.

​
v1.23 이전

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