포탈에 설치하기

업무패키지(Business Package, 이하 BP)는 서명된 패키지 아카이브(.tgz)로 포탈에 설치한다. 포탈은 아카이브를 반입해 검증하고, 패키지 관리 권한을 가진 사람이 승인한 뒤에 마이그레이션을 적용하고 코드를 적재한다. 포탈 이미지를 다시 빌드하지 않는다.

아카이브를 만드는 방법은 build-and-package.md §7에 있다.

이 문서의 starj 명령은 실행하는 곳에 따라 쓰는 방법이 다르다. BP 저장소에서는 devDependencies로 받은 CLI를 pnpm exec starj …로 실행한다. 포탈 운영자는 포탈이 배포한 starj CLI를 쓴다. 운영자 쪽 예시(신뢰 키 등록, 상태 조회)는 starj …로 적는다.

1. 인계하는 것

항목	내용
패키지 아카이브	pnpm run package가 만든 dist-package/<id>-<version>.tgz. 무결성 정보(파일별 해시)와 서명이 아카이브 안에 들어 있으므로 체크섬을 따로 인계하지 않아도 된다
신뢰 키(처음 한 번)	starj package keygen이 만든 starj-signing.trusted-key.json(또는 공개 키 .pub.pem). 공개 키만 전달한다. 개인 키는 전달하지 않는다. 운영자가 이 키를 포탈의 신뢰 키로 등록해야 운영 모드 포탈이 그 서명을 받는다(§2-3)

매니페스트에 이미 포함되어 있는 것은 별도 문서로 다시 작성할 필요가 없다. 운영자는 승인 화면이나 starj package inspect <tgz>로 확인한다.

항목	매니페스트 필드
BP id와 버전	id, version
요구하는 호스트 계약 범위	runtime.hostContract
지원 DB 방언	backend.database.providers
의존하는 다른 BP	dependsOn[](아카이브 매니페스트의 dependencies[]로 옮겨진다)
자체 테이블	아카이브 매니페스트의 database.tables(마이그레이션에서 계산한다)

매니페스트에 없어 반드시 별도로 인계해야 하는 것은 산출물만으로는 알 수 없다.

항목	내용
필요한 외부 연결 (Destination)	이 BP가 호출하는 외부 시스템마다 운영자가 포탈에 등록해야 하는 Destination(외부 연결처)의 이름·대상 주소·인증 방식·허용 경로·허용 요청 헤더. BP는 주소와 자격증명을 자기 산출물에 포함하지 않고 등록된 이름으로 host.destinations를 호출한다(backend-guide.md §16). BP가 사용하는 Destination 이름을 그대로 인계하고, 등록이 누락되면 그 호출만 실패한다는 점을 함께 전달한다
BP가 발행하는 알림	매니페스트 notificationCategories[]가 설치 시 포탈 카테고리로 자동 등록되므로 별도 요청이 필요하지 않다. 다만 특정 역할 전원에게 발행하는 알림이 있다면 그 역할(기본 권한)이 사용자에게 부여되어야 실제 수신자가 있다
초기 데이터와 운영 전제	onInstall이 자동 생성하지 않는 마스터 데이터, 필요한 관리자 조작
주기 실행이 필요한 작업	포탈은 스케줄러를 제공하지 않는다(backend-guide.md §9). 외부 스케줄러가 호출해야 하는 엔드포인트와 주기를 명시한다
필요한 기계 자격증명 (API 클라이언트)	위의 주기 실행처럼 사람의 세션 없이 BP를 호출해야 하는 경로가 있으면, 운영자가 포탈에 API 클라이언트를 등록하고 client_id·client_secret을 발급해야 한다(backend-guide.md §9-1). 그 자격증명으로 호출할 엔드포인트와 대상 도메인을 함께 인계한다. 자격증명 값 자체는 산출물이나 문서에 포함하지 않는다

2. 설치

2-1. 반입 경로 세 가지

어느 경로든 같은 검증·승인·적용 절차를 거친다. 다른 것은 행위자와 감사로그의 경로 값뿐이다.

경로	방법	승인
CLI	pnpm exec starj package add <tgz> [--approve] [--wait](BP 저장소에서)	--approve를 주고 토큰에 패키지 관리 권한이 있으면 반입과 승인을 함께 한다
폴더 투입	아카이브를 포탈 작업 영역의 inbox/ 폴더에 복사한다(개발 환경 기본값은 .data/packages/inbox/)	항상 승인 대기로만 등록된다. 폴더에 쓸 수 있다는 사실은 설치 권한이 아니다
관리 화면	패키지 관리 화면에서 파일을 첨부한다	화면에서 승인한다

CLI의 포탈 연결:

export STARJ_PORTAL_URL=https://<포탈 주소>
# 토큰은 둘 중 하나. 값은 명령줄 인자로 주지 않는다.
export STARJ_TOKEN=<패키지 관리 권한이 있는 API 클라이언트의 토큰>
#   또는
export STARJ_CLIENT_ID=<client_id>
export STARJ_CLIENT_SECRET=<client_secret>     # CLI가 client_credentials로 토큰을 받는다

pnpm exec starj package add dist-package/task-bp-1.0.0.tgz --approve --wait

• 승인은 패키지 관리 권한(MANAGE_PACKAGES)을 가진 계정만 할 수 있다. 이 권한은 기본으로 Basis 역할에만 있다. BP 개발자에게 권한이 없으면 --approve 없이 반입하고 운영자에게 승인을 요청한다.
• CLI의 승인은 발급된 지 10분(기본값) 안의 토큰이어야 한다. STARJ_CLIENT_ID/STARJ_CLIENT_SECRET이 있으면 CLI가 승인 직전에 토큰을 다시 받는다.
• 토큰이 없거나 권한이 없으면 승인 대기 등록까지만 하고 종료 코드 8로 끝난다. 반입 자체가 인증·권한 문제로 실패하면 종료 코드 5다.
• --wait는 적용이 확정될 때까지 기다린다(기본 제한 300초, --timeout <초>로 바꾼다). 제한 시간 안에 확정되지 않으면 종료 코드 6, 자동으로 되돌려지면 7, 수동 재시작이 필요한 상태에서 멈추면 9다.
• 루프백이 아닌 http: 주소는 거부한다.

2-2. 개발 포탈에 설치하기

로컬 개발 포탈은 개발 모드(PORTAL_PACKAGE_MODE=development)로 구동한다. 포탈 저장소의 pnpm dev가 이 값을 지정한다. 개발 모드의 차이는 다음과 같다.

• 서명하지 않은 아카이브도 경고와 함께 반입된다. 서명이 있는데 틀리면 개발 모드에서도 거부된다.
• 승인은 개발 모드에서도 필요하다. --approve로 함께 승인하거나 관리 화면에서 승인한다.
• 개발 서버에는 재시작 정책이 없으므로, 서버 코드가 바뀌는 적용은 수동 재시작 필요 상태에서 멈춘다. 포탈을 직접 재시작하면 절차가 이어진다(pnpm exec starj package status로 상태를 본다).
• 소스 폴더(PORTAL_BP_DIR)의 BP도 이전처럼 부팅 때 적재된다. 이 경로는 승인·서명을 거치지 않는 "개발 소스"로 표시되며, 운영 모드 포탈은 적재하지 않는다.

# BP 저장소에서
pnpm run verify                                         # 빌드부터 아카이브 검증까지
STARJ_PORTAL_URL=http://localhost:<포트> STARJ_TOKEN=<토큰> \
  pnpm exec starj package add dist-package/task-bp-1.0.0.tgz --approve --wait

같은 이름·버전을 내용만 바꿔 다시 반입하면 V11로 거부된다. 고쳐서 다시 설치할 때는 version을 올린다.

2-3. 운영 포탈에 설치하기

운영 모드는 신뢰 키로 서명한 아카이브만 받는다. 처음 한 번, 운영자가 BP 제작자의 공개 키를 신뢰 키로 등록한다.

starj package keys add starj-signing.pub.pem --label "<제작자> 업무패키지 키"

고객이 등록한 키의 기본 허용 종류는 업무패키지다. 키는 지문(공개 키의 SHA-256)으로 식별하며, 운영자는 승인 화면에서 서명자 라벨과 지문을 확인한다. 키를 폐기하면 그 키로 서명한 새 아카이브는 반입되지 않는다. 이미 설치된 BP는 계속 동작하고 목록에 경고가 표시된다.

2-4. 포탈이 반입할 때 확인하는 것

반입하면 포탈이 아래 항목을 전부 확인한다. 하나라도 실패이면 승인할 수 없다. 이 단계에서는 코드를 적재하지 않는다.

항목	실패하는 경우
V1 아카이브 구조	경로 이탈·링크·장치 파일, 크기·파일 수 상한 초과, POSIX ustar/pax가 아닌 tar 형식(build-and-package.md §7-5)
V2 매니페스트	starj-package.json이 bp-manifest.yaml과 어긋남. contractDir이 있는데 backwardCompatible: true가 없음(호스트 계약 2.1.0)
V3 무결성	파일 목록·해시 불일치
V4 서명	서명 없음(운영 모드), 서명 오류, 알 수 없는 키·폐기된 키·만료된 키
V5 호환	포탈의 호스트 계약(연계 규약) 버전이 runtime.hostContract 범위 밖
V7 방언	실행 중인 방언을 지원하지 않거나 그 방언의 마이그레이션이 없음. 정리 마이그레이션(contractDir)의 방언 폴더가 없거나 폴더 이름이 방언끼리 다름, 확장 마이그레이션과 같은 폴더 이름(호스트 계약 2.1.0)
V8 데이터베이스	접두어 위반·충돌, 허용 목록 밖의 마이그레이션 SQL, 선언 테이블 불일치(build-and-package.md §7-6). backwardCompatible: true인데 확장 마이그레이션이 이전 코드를 깨뜨리는 문장을 포함함(BACKWARD_INCOMPATIBLE_SQL, 호스트 계약 2.1.0, backend-guide.md §7-5)
V11 버전	같은 이름·버전이 이미 설치되었는데 내용이 다름. 정리 마이그레이션이 이미 실행된 버전보다 낮은 버전(DOWNGRADE_AFTER_CONTRACT, 호스트 계약 2.1.0)
V13 저장 위치(호스트 계약 2.0.0)	운영자가 고른 데이터 저장 위치에 접속할 수 없거나, 포탈이 그곳에 BP 전용 이름공간·전용 계정을 만들 권한이 없음

V9(의존성)에서 BP가 다른 BP에 거는 의존의 부재는 경고이며 설치를 막지 않는다. 의존 대상의 판정은 도메인 활성화 때 한다.

호스트 계약 2.0.0 포탈에서는 운영자가 최초 승인 때 BP 데이터의 저장 위치를 고른다. 포탈 기본 DB가 기본값이고, 운영자가 다른 DB 서버를 등록해 두었으면 그중에서 고를 수 있다. 저장 위치는 설치 뒤 바꿀 수 없으며 업그레이드도 같은 위치를 쓴다. BP 개발자가 인계할 것은 없다. BP는 받은 접속 정보만 쓴다(backend-guide.md §6-3).

3. 포탈이 승인 뒤와 부팅 시 하는 일

승인된 아카이브는 다음 순서로 적용된다.

1. 의존성을 다시 확인한다.
2. 이미 사용 중인 BP를 서버 코드가 바뀌는 새 버전으로 바꾸면 그 BP의 요청을 거부하기 시작한다(호스트 계약 2.1.0, 아래 §5-1). 몇 초 기다려 진행 중인 요청이 끝나게 한 뒤 다음 단계로 간다. backwardCompatible: true이면 확장 마이그레이션을 이 시점에 한 번 더 검사한다.
3. 마이그레이션을 적용한다. 아직 적용하지 않은 migration.sql을 이름 순으로, BP 하나당 한 트랜잭션으로 실행한다. 하나라도 실패하면 전부 취소되고 적용이 실패로 끝난다(코드는 바뀌지 않는다). 적용 이력은 포탈의 패키지 전용 표에 남는다.
4. 새 구성(세대)을 기록하고, 서버 코드가 바뀌면 포탈을 재시작한다. 화면 번들만 바뀌면 재시작하지 않는다. 정리 마이그레이션이 있으면 정리 작업을 대기 상태로 만든다.
5. 재시작한 포탈이 정해진 시간 동안 정상이고 BP가 적재되면 설치가 확정된다. 정상이 되지 못하면 포탈이 이전 구성으로 자동으로 되돌린다. 마이그레이션은 되돌리지 않는다.
6. 모든 포탈 인스턴스가 새 버전을 적재하면 요청 거부를 풀고, 정리 마이그레이션을 실행한다(호스트 계약 2.1.0, backend-guide.md §7-5).

부팅 시 BP를 적재하는 순서는 다음과 같다. 어느 단계에서 걸리든 그 BP만 건너뛰고 포탈은 정상 기동한다. 다만 패키지로 설치한 BP가 적재되지 못하면 위 5번의 확인에 실패해 이전 구성으로 되돌려진다.

1. 확정된 구성의 패키지 설치 트리(개발 모드이면 소스 폴더도)를 열거한다
2. 각 bp-manifest.yaml을 읽는다. apiVersion을 인식하지 못하면 건너뜀
3. runtime.hostContract를 포탈의 계약 버전과 대조한다. 범위가 맞지 않으면 건너뜀
4. backend.database.providers에 실행 중인 방언이 있는지 확인한다. 없으면 건너뜀
5. backend.entry를 동적 import하고 register(host)를 호출한다. 없거나 예외가 발생하면 건너뜀
6. 반환된 능력 표면으로 화면·메뉴·카드·기본 권한·알림 카테고리를 등록(upsert)한다
7. version 문자열이 처음 등장하는 값이면 onInstall 훅을 호출한다

6단계의 알림 카테고리 등록은 계약 1.1.0에서 추가된 것이다. 매니페스트 notificationCategories[]에 선언한 키가 포탈의 알림 카테고리 카탈로그에 upsert되어 관리 화면과 사용자 수신 설정 화면에 나타난다. 선언에서 제거된 카테고리는 삭제되지 않고 비활성 상태로 전환된다. 자세한 내용은 bp-manifest.md §notificationCategories에 있다.

"설치했는데 아무 변화가 없다"는 이 중 어딘가에서 오류 메시지 없이 걸린 것이다. 건너뛴 사유는 포탈 부팅 로그에 남고, GET /bp/runtime-info의 skipped[]로도 조회할 수 있다. 그 API는 업무패키지 관리 권한을 요구하므로, 권한이 없는 개발자는 운영자에게 조회를 요청한다(host-contract.md §5, troubleshooting.md 참고).

마이그레이션은 적재 순서와 별개다

마이그레이션 적용은 onInstall이나 버전 판정과 별개 경로다. 경로에 따라 방식이 다르다.

설치 경로	적용 시점	이력
패키지 아카이브(운영과 starj package add)	승인 뒤 적용 단계. 새 코드가 기동하기 전	포탈의 패키지 전용 이력 표(호스트 계약 2.0.0에서는 BP 이름공간 안의 이력 표). 이미 적용된 것은 건너뛰고, 이미 적용된 migration.sql의 내용이 바뀌었으면 적용을 거부한다
개발 모드의 소스 폴더(PORTAL_BP_DIR)	두 방언 모두 포탈 부팅 중 그 BP를 적재하기 직전에	패키지 아카이브와 같은 러너와 같은 이력 표(BP id 기준)를 쓴다. 이미 적용한 것은 건너뛰고, 내용이 바뀐 파일은 거부한다. 실패하면 그 BP만 SQLITE_MIGRATION_FAILED·POSTGRESQL_MIGRATION_FAILED로 건너뛴다

onInstall이 실행되지 않아도 마이그레이션은 적용되고, 그 반대도 성립한다. 마이그레이션 SQL 작성 시 지켜야 하는 것은 backend-guide.md §7-4에 있다.

두 경로의 이력은 두 방언 모두에서 이어진다. 소스 폴더로 적용한 DB에 같은 BP를 아카이브로 설치하면, 이름과 체크섬이 같은 마이그레이션은 건너뛰고 나머지만 적용한다. 예전 개발 도구(prisma migrate deploy)가 _prisma_migrations에 남긴 BP 이력은 이어받지 않는다. 그 도구로 테이블을 만든 개발 DB나 이력 없이 테이블만 남은 개발 DB라면, 포탈 저장소의 pnpm bp:dev-reset <BP id>로 그 BP의 테이블과 이력을 지운다(데이터도 지워진다).

4. 설치 이후 — 관리자가 하는 일

설치와 사용 가능 상태는 별개다.

단계	누가	내용
설치	패키지 관리자	반입·승인·적용. 포탈 전체 단위
활성화	관리자	도메인별로 활성화해야 화면·API가 열린다
권한 부여	관리자	자동 생성된 권한 템플릿을 사용자에게 부여

defaultAuthorities가 만드는 것은 권한의 정의까지다. 사용자에게 부여하는 것은 언제나 관리자의 판단이다. 설치했는데 화면이 표시되지 않는다면 대개 이 두 단계가 남은 것이다.

관리자가 활성화·비활성화를 조작할 때 onActivate / onDeactivate 훅이 호출된다. 부팅 시에는 호출되지 않으며, 다중 인스턴스 배포에서는 그 요청을 처리한 인스턴스 1대에서만 실행된다(backend-guide.md §8-2). 훅이 실패해도 전이는 유지되고 관리자가 관리 화면에서 재시도하므로, 두 훅은 여러 번 실행해도 결과가 같게 작성한다(backend-guide.md §8-2 "훅 반복 안전 규약").

5. 업그레이드

새 버전의 아카이브를 같은 절차로 설치한다. 포탈이 이전 버전의 설치 트리를 새 트리로 바꾸므로 잔존 파일 문제가 없다.

• version을 반드시 올린다. 같은 이름·버전으로 내용이 다른 아카이브는 V11로 거부된다.
• 이미 배포한 migration.sql은 고치지 않는다. 이미 적용된 마이그레이션의 내용이 바뀌면 포탈이 적용을 거부한다. 변경은 새 마이그레이션으로 추가한다.
• 마이그레이션은 새 코드가 기동하기 전에 적용되므로, 다중 인스턴스에서는 이전 버전 코드가 잠시 새 스키마에서 동작할 수 있다. 추가한 뒤 나중에 정리하는 방식으로 마이그레이션을 나눈다. 호스트 계약 2.1.0 포탈은 정리 마이그레이션(contractDir)을 받아 적절한 때에 직접 실행한다(backend-guide.md §7-5).
• bp-manifest.yaml의 version 문자열이 처음 등장하는 값일 때 onInstall이 실행된다. semver 비교가 아니라 문자열 일치 판정이므로, 이전에 설치했던 버전으로 되돌리면 onInstall이 실행되지 않는다.
• id는 변경하지 않는다. upsert 기준이라 변경하면 기존 레코드와 이어지지 않고 새 BP로 등록된다.
• apps[].id / menu[].id / cards[].id도 마찬가지다. 이전 버전에서 쓰던 id를 유지해야 화면·권한·홈 배치가 이어진다.
• 관리자가 이동시킨 메뉴 배치는 덮어쓰지 않는다. 다만 카드 카탈로그는 매 부팅마다 매니페스트 기준으로 덮어쓴다.
• 매니페스트에서 제거된 App·카드는 삭제되지 않고 숨김 처리된다. 선언을 복원하면 다시 표시된다.
• 알림 카테고리는 예외다. 제거되어 비활성으로 전환된 카테고리는 선언을 복원해도 자동으로 다시 활성화되지 않는다. 관리자가 알림 카테고리 관리 화면에서 활성화해야 한다(bp-manifest.md §notificationCategories).
• 설치된 버전보다 낮은 버전을 반입하면 경고(DOWNGRADE)가 표시된다.

5-1. 업데이트하는 동안 BP를 사용할 수 없다 (호스트 계약 2.1.0)

이미 사용 중인 BP를 서버 코드가 바뀌는 새 버전으로 바꾸는 동안, 포탈은 그 BP의 요청만 거부한다. 마이그레이션을 적용하기 전에 시작해 모든 포탈 인스턴스가 새 버전을 적재하면 끝난다. 첫 설치, 다시 활성화, 화면 번들만 바뀐 업그레이드는 거부하지 않는다. 다른 BP와 포탈 화면, 패키지 관리 화면도 그대로 동작한다.

• 사용자에게는 그 BP의 화면 위치에 "업데이트 중입니다. 잠시 후 다시 접속하세요."가 표시된다. 오류 화면이 아니며 재시도 버튼도 없다. 업데이트가 끝나면 Portal Shell(포탈 셸)이 새 화면으로 자동으로 바꾼다.
• 그 BP의 REST를 호출하는 외부 시스템은 503 BP_UPDATING을 받는다. Retry-After가 지난 뒤 다시 호출하게 한다.
• 거부가 풀리는 때는 다음과 같다.

상황	거부가 풀리는 때
마이그레이션이 실패해 변경이 취소됨	즉시
새 버전이 확정되고 모든 인스턴스가 적재함	그때
새 버전이 자동으로 되돌려짐	backwardCompatible: true이면 모든 인스턴스가 이전 버전으로 돌아간 때. 아니면 운영자가 풀 때까지 유지된다
포탈 재시작을 운영자가 직접 해야 하는 환경	backwardCompatible: true이면 즉시. 아니면 운영자가 풀 때까지 유지된다
안전 상한 시간(기본 30분)이 지남	backwardCompatible: true이면 풀고 경고를 남긴다. 아니면 유지된다
운영자가 직접 풂	즉시(재인증과 감사로그)

backwardCompatible: true가 아닌 BP는 업데이트가 실패하면 운영자가 풀 때까지 사용할 수 없다. 이전 버전 코드가 새 스키마에서 동작한다는 보장이 없기 때문이다. 운영자는 상태를 확인한 뒤 관리 화면의 차단 해제 버튼이나 starj package unblock <이름>으로 푼다.

운영자가 확인하는 화면. 승인 대화상자에 "적용하는 동안 이 업무패키지는 사용할 수 없습니다" 안내, 이번 버전의 정리 마이그레이션 목록과 실행 뒤 되돌림이 제한된다는 안내, 하위 호환 검사 결과가 표시된다. 설치된 패키지 목록과 상세에는 "업데이트 중", "업데이트 차단 유지" 표시와 차단 해제 버튼이 있다. 상세의 정리 영역에는 정리 작업의 상태, 대기 중인 마이그레이션 이름, 실행되지 않는 사유, 실패 사유와 시도 횟수, 정리 실행·재시도 버튼이 있다.

CLI(호스트 계약 2.1.0을 제공하는 포탈과 starj CLI 0.3.0 이상):

명령	하는 일
starj package contract list	정리 작업 목록과 상태, 실행되지 않는 사유
starj package contract run <이름> [--wait]	정리 실행을 지시한다. 실행 조건(모든 인스턴스가 새 버전을 적재함 등)이 맞지 않으면 거부된다. --wait이면 끝날 때까지 기다린다
starj package contract retry <이름> [--wait]	실패한 정리를 다시 실행한다
starj package unblock <이름>	업데이트 중 요청 거부를 운영자가 푼다
starj package verify <대상> --previous <이전 아카이브나 폴더>	이전 버전에 이미 적용된 마이그레이션을 기준으로 하위 호환 검사를 한다. --previous가 없으면 이 검사를 건너뛰고 경고한다
starj package pack … --previous <이전 아카이브나 폴더>	묶기 전에 같은 검사를 한다. 위반이면 종료 코드 3으로 끝난다

BP 개발자는 새 버전을 인계하기 전에 starj package verify dist-package/<새 아카이브> --previous dist-package/<직전에 인계한 아카이브>로 검사를 미리 받는다. 운영 포탈의 판정과 같은 검사기다.

되돌림

자동 되돌림(§3의 5번)과 운영자의 수동 되돌림(starj package rollback)은 코드(설치된 패키지 구성)만 되돌린다. 마이그레이션은 되돌아가지 않는다.

• 새 버전에서 추가된 컬럼·테이블은 남는다. 스키마를 되돌려야 한다면 역방향 마이그레이션을 새 버전으로 배포한다.
• 정리 마이그레이션이 한 번이라도 실행된 버전보다 낮은 버전으로는 되돌릴 수 없다(호스트 계약 2.1.0). 포탈이 되돌림 요청과 그런 버전의 반입을 거부한다. 되돌릴 수 있는 기간이 필요하면 운영자가 정리 자동 실행 정책을 비활성화하고 확인한 뒤 starj package contract run으로 실행한다.
• onInstall이 이미 생성한 데이터도 제거되지 않는다.

따라서 되돌림을 전제로 마이그레이션을 설계한다. 파괴적 변경(컬럼 삭제·타입 변경)은 확장과 정리 두 단계로 나눈다(backend-guide.md §7-5).

6. 비활성화·제거·데이터 삭제

• 도메인별 비활성화는 이전과 같다. 권한 부여 기록은 보존된다(재활성화 시 복원). 나를 required로 의존하는 활성 BP가 있으면 비활성화가 차단된다.
• 패키지 단위의 비활성화는 모든 도메인에서 비활성처럼 동작하게 한다. 도메인 활성화 레코드는 그대로 남는다.
• 제거는 코드와 포탈의 등록 정보(App, 메뉴 배치, 권한 매핑, 카드, 활성화 레코드)를 정리하고 BP 자체 테이블과 데이터, 사용자가 첨부한 파일은 남긴다. 같은 BP를 다시 설치하면 데이터가 이어진다. 적재되어 있으면 onUninstall 훅이 호출되며, 훅이 실패하면 제거가 중단된다. 어느 도메인에서든 활성 상태이면 제거가 차단된다.
• 데이터 삭제는 제거된 BP만 대상이며 되돌릴 수 없다. bp_<id>_ 접두어 테이블과 마이그레이션 이력을 한 트랜잭션으로 삭제한다. 호스트 계약 2.0.0 포탈은 BP 이름공간 전체와 BP 전용 DB 계정을 삭제한다. 저장 위치를 잘못 골랐을 때 다시 고르는 방법도 데이터 삭제 뒤 재설치다. 감사로그는 남는다. 데이터 삭제 뒤 같은 BP를 설치하면 마이그레이션이 처음부터 적용되어 빈 상태로 시작한다.

함께 볼 것

• build-and-package.md §7 — 아카이브를 만들고 서명·검증하는 방법
• troubleshooting.md — 설치했는데 동작하지 않을 때
• backend-guide.md §7~§8 — 마이그레이션과 라이프사이클 훅의 실제 동작