# Backstage v1.56.0

> CI/CD & App Delivery · 2026-10-20

백엔드, 명령줄 도구, 문서, 카탈로그, 검색, 플러그인 기능을 넓히면서 API와 데이터베이스, 인증, 설정, 기본 동작에도 호환성 변경이 포함된 릴리스입니다. 관련 기능을 사용하는 환경은 마이그레이션과 동작 검증이 필요하며, 신뢰성, 성능, 정확성, 의존성 개선과 보안 취약점 대응도 함께 반영되었습니다.

## 조치 필요
- **[security]** `nodemailer` 버전 10 업데이트
  - 이전 버전의 보안 취약점에 대응하기 위해 `nodemailer`를 버전 10으로 업데이트했습니다.

## 영향 확인
- **[breaking]** `FilterPredicate` 루트 객체 제한
  - `FilterPredicate`를 사용하는 경우에 적용됩니다.
  - `FilterPredicate`의 predicate 루트에는 이제 객체만 허용됩니다.
- **[breaking]** `usernameMatchingUserEntityName` 로그인 확인자 제거
  - `usernameMatchingUserEntityName` 로그인 확인자를 사용하는 경우에 적용됩니다.
  - `usernameMatchingUserEntityName` 로그인 확인자가 제거되었습니다.
- **[breaking]** 서비스 구현의 `instance ID` 제공 요구
  - 서비스의 사용자 지정 구현이나 모의 객체를 사용하는 경우에 적용됩니다.
  - 서비스의 사용자 지정 구현과 모의 객체는 이제 `instance ID`를 제공해야 합니다.
- **[breaking]** 순차 무중단 업그레이드에서 마이그레이션 적용 제한
  - 순차 방식의 무중단 업그레이드를 수행하는 경우에 적용됩니다.
  - 이 마이그레이션은 순차 방식의 무중단 업그레이드에 포함해 적용할 수 없습니다.
- **[breaking]** `catalog backend` 버전 호환성 요구
  - Backstage 1.49 이상에서 제공하는 `catalog backend`를 사용하는 경우에 적용됩니다.
  - Backstage 1.49 이상에서 제공하는 `catalog backend`가 필요합니다.
- **[breaking]** 스티칭 간격 및 임대 기간 값 검증
  - 스티칭 폴링 간격이나 임대 기간을 설정하는 경우에 적용됩니다.
  - 0 이하로 설정한 스티칭 폴링 간격과 임대 기간은 시작할 때 거부됩니다.
- **[breaking]** Signals WebSocket 사용자 토큰 인증
  - Signals WebSocket 엔드포인트를 외부에 공개하는 경우에 적용됩니다.
  - Signals WebSocket 엔드포인트가 유효한 사용자 신원 토큰을 요구합니다.
- **[breaking]** 루트 인스턴스 메타데이터의 고유 ID 요구
  - 루트 인스턴스 메타데이터 서비스의 사용자 지정 구현이나 모의 객체를 사용하는 경우에 적용됩니다.
  - 루트 인스턴스 메타데이터 서비스의 사용자 지정 구현과 모의 객체는 실행 중인 백엔드 인스턴스의 수명 동안 변하지 않는 전역 고유 ID를 제공해야 합니다.
- **[breaking]** `MenuSection`의 `disabledKeys` 제거
  - `disabledKeys`와 함께 `MenuSection`을 사용하는 경우에 적용됩니다.
  - `MenuSection`이 더 이상 `disabledKeys`를 허용하지 않습니다.
- **[breaking]** 로그인 확인자 `usernameMatchingUserEntityName` 제거
  - `usernameMatchingUserEntityName` 로그인 확인자를 사용하는 경우에 적용됩니다.
  - `usernameMatchingUserEntityName` 로그인 확인자가 제거되었습니다.
- **[breaking]** 테이블 열 `ref`의 `entity_ref` 변경
  - 테이블의 `ref` 열을 사용하는 경우에 적용됩니다.
  - 테이블의 `ref` 열 이름이 `entity_ref`로 바뀌었습니다.
- **[breaking]** 데이터베이스 연결 유지 기본값 변경
  - `backend.database.keepalive`를 `true`로 설정하지 않은 경우에 적용됩니다.
  - 플러그인별 데이터베이스 연결 유지 쿼리를 기본적으로 더 이상 실행하지 않으며, PostgreSQL과 MySQL 연결 풀의 기본 최소 크기를 0으로 변경했습니다. 설정한 제한 시간이 지나면 유휴 연결을 정리하고, 명시적으로 설정한 최소 풀 크기는 유지합니다. 주기적인 쿼리를 계속 실행하려면 `backend.database.keepalive: true`를 설정해야 합니다.
- **[breaking]** 스티칭 설정의 양수 값 검증
  - 스티칭 폴링 간격이나 임대 기간을 설정하는 경우에 적용됩니다.
  - 0 이하로 설정한 스티칭 폴링 간격과 임대 기간은 시작할 때 거부됩니다.
- **[breaking]** Signals WebSocket 연결 인증 강화
  - Signals WebSocket 엔드포인트를 외부에 공개하는 경우에 적용됩니다.
  - Signals WebSocket 엔드포인트는 요청된 WebSocket 프로토콜의 어느 위치에든 포함된 유효한 사용자 신원 토큰을 요구합니다. 토큰이 없거나 유효하지 않거나 서비스 토큰이면 연결을 거부하며, 인증되지 않은 게스트 연결도 더 이상 허용하지 않습니다.

## 미리 준비
- **[deprecated]** `getCatalogFilters` 사용 중단 예정
  - `getCatalogFilters`를 사용하는 경우에 적용됩니다.
  - `getCatalogFilters`가 사용 중단 예정으로 지정되었습니다.
- **[deprecated]** `serve:mkdocs` 및 `--mkdocs-parameter-*` 사용 중단 예정
  - `serve:mkdocs` 또는 `--mkdocs-parameter-*` 플래그를 사용하는 경우에 적용됩니다.
  - `serve:mkdocs`와 `--mkdocs-parameter-*` 플래그를 사용하면 사용 중단 예정 경고가 출력됩니다.
- **[deprecated]** 원시 토큰 출력 사용 중단 예정
  - 원시 토큰 출력을 사용하면서 `variableKey`를 설정하지 않은 경우에 적용됩니다.
  - `variableKey`를 사용하지 않을 때 원시 토큰 출력이 사용 중단 예정으로 지정되었습니다.
- **[deprecated]** `totalItems` 옵션 사용 중단 예정
  - `totalItems`를 설정하는 경우에 적용됩니다.
  - `totalItems` 옵션이 사용 중단 예정으로 지정되었습니다.
- **[deprecated]** `serve:mkdocs` 및 `--mkdocs-parameter-*` 경고
  - `serve:mkdocs` 또는 `--mkdocs-parameter-*` 플래그를 사용하는 경우에 적용됩니다.
  - `serve:mkdocs`와 `--mkdocs-parameter-*` 플래그를 사용하면 사용 중단 예정 경고가 출력됩니다.
- **[deprecated]** `StreamEntitiesRequest.totalItems` 사용 중단 예정
  - `totalItems`를 사용하는 경우에 적용됩니다.
  - `StreamEntitiesRequest`의 `totalItems` 옵션이 사용 중단 예정으로 지정되었고 무시됩니다.
- **[deprecated]** 원시 토큰 출력의 `variableKey` 전환
  - 원시 토큰 출력을 사용하면서 `variableKey`를 설정하지 않은 경우에 적용됩니다.
  - `variableKey`를 사용하지 않을 때 원시 토큰 출력이 사용 중단 예정으로 지정되었습니다.

## 그 밖에 기록된 변경
- 256 (value_changed 131, defect_corrected 64, added 43, constraint_changed 11, renamed 4, default_changed 3)

[분석 자세히 보기](https://ratatosk.io/ko/releases/backstage/v1.56.0)

[원본 릴리스 노트](https://github.com/backstage/backstage/releases/tag/v1.56.0)