# 업그레이드

> 설치를 새 릴리스로 업데이트하고, 2.1.0에서 2.2.0으로 이동할 때 변경해야 할 사항을 안내합니다.

업데이트는 PentAGI 이미지를 교체하며, 릴리스에서 변경된 경우 compose 파일도 함께 교체합니다. 사용자의 `.env`와 데이터 볼륨은 유지되며, PentAGI 시작 시 데이터베이스 마이그레이션이 실행됩니다.

## [시작하기 전에](https://pentagi.com/ko/docs/deployment/upgrade/#before-you-start)

* 현재 실행 중인 버전 이후의 모든 버전에 대한 [릴리스 노트](https://pentagi.com/changelog/)를 읽으세요. 2.1.0부터는 업그레이드 안내 사항이 포함되어 있습니다.
* 데이터베이스를 백업하세요. 인스톨러와 PentAGI 모두 이를 수행하지 않으며, 마이그레이션은 데이터를 손실하지 않고 롤백할 수 없습니다. 기본 `PENTAGI_POSTGRES_USER` 및 `PENTAGI_POSTGRES_DB`을 사용하는 경우:

  ```bash
  docker exec pgvector pg_dump -U postgres -Fc pentagidb > pentagi-backup.dump
  ```

  `.env`과 compose 파일의 복사본도 보관하세요. 인스톨러는 백업 없이 compose 파일을 교체합니다.
* 더 이상 필요하지 않은 [flow](https://pentagi.com/ko/docs/glossary/#flow)를 완료하세요. 여전히 실행 중인 [sandbox](https://pentagi.com/ko/docs/glossary/#sandbox)는 생성된 당시의 설정(해당 sandbox를 생성한 릴리스의 설정)으로 재사용됩니다.
* 2.1.0에서 업그레이드하는 경우, 새 릴리스가 시작되기 전에 `.env` 및 그 옆의 파일들에 [2.1.0에서 2.2.0으로](#from-210-to-220)의 변경 사항을 적용하세요. Google 또는 GitHub 로그인이 활성화되어 있다면 지금 `OAUTH_GOOGLE_CLIENT_ID`와 `OAUTH_GITHUB_CLIENT_ID`을 비우세요. 해당 섹션에서 이유를 설명합니다.

## [Docker Compose](https://pentagi.com/ko/docs/deployment/upgrade/#docker-compose)

1. 새 릴리스의 compose 파일을 `.env` 옆에 다운로드하세요: `docker-compose.yml` 및 실행 중인 각 선택적 스택의 파일입니다. PentAGI 컨테이너는 해당 compose 파일에 나열된 변수만 받으므로, 이전 버전의 파일 뒤에서는 `.env`의 새 설정이 적용되지 않습니다.

   ```bash
   cd ~/pentagi
   curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/main/docker-compose.yml
   # and the file of each optional stack you run, for example:
   curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/main/docker-compose-langfuse.yml
   ```

2. 스택을 시작할 때 사용하는 것과 동일한 `-f` 파일로 이미지를 pull하고 다시 시작하세요. `pull`가 없으면 `up -d`는 호스트에 이미 있는 이미지만 유지합니다.

   ```bash
   docker compose pull && docker compose up -d
   ```

3. flow를 실행하는 Docker 호스트에서 sandbox 이미지를 새로 고치세요. `docker compose pull`는 이를 수행하지 않습니다. 이후에 생성된 flow는 이 이미지를 사용합니다.

   ```bash
   docker pull vxcontrol/kali-linux
   ```

`latest` 이미지 태그는 main 브랜치를 따릅니다. 하나의 릴리스에 고정하려면 `.env`에서 `PENTAGI_IMAGE=vxcontrol/pentagi:<version>`을 설정하세요.

## [인스톨러](https://pentagi.com/ko/docs/deployment/upgrade/#installer)

1. [Quick start](https://pentagi.com/ko/docs/getting-started/quickstart/)에서 새 릴리스의 인스톨러를 다운로드하고 `.env`로 실행하세요. 2.1.0 인스톨러는 자체적으로 업데이트할 수 없습니다.
2. compose 파일을 교체하려면, 메뉴에 **Apply Changes**가 나타나도록 설정을 변경하고 이를 선택한 후, 인스톨러가 구버전 파일을 목록에 표시할 때 `y`이라고 답하세요.
3. 유지보수 메뉴에서 **Update PentAGI**를 실행하여 새 이미지를 pull하고, 제안될 때 **Update Worker Image**를 실행하세요. **Update PentAGI**만 실행하면 기존 compose 파일은 유지됩니다.

## [2.1.0에서 2.2.0으로](https://pentagi.com/ko/docs/deployment/upgrade/#from-210-to-220)

### [파일](https://pentagi.com/ko/docs/deployment/upgrade/#files)

* compose 파일은 그 옆에 `example.bedrock.provider.yml`을 마운트합니다. 인스톨러가 이를 생성하며, 수동 설치 시에는 직접 생성해야 합니다(빈 파일이면 충분합니다): `touch example.bedrock.provider.yml`.
* Langfuse를 실행하는 경우 `docker-compose-langfuse.yml`을 교체하세요. 2.1.0 파일은 더 이상 배포되지 않는 `minio/minio` 이미지를 지정하므로, `docker compose pull`이 이에 대해 실패합니다. `.env`에서 `MINIO_IMAGE=minio/minio:…`을 설정했다면 해당 줄을 제거하세요.
* [knowledge graph](https://pentagi.com/ko/docs/glossary/#knowledge-graph)를 위해 저장소의 `examples/neo4j`을 `./neo4j`에 배치하세요(Graphiti는 APOC 플러그인이 필요합니다). 모델 프리셋은 [Memory and knowledge](https://pentagi.com/ko/docs/concepts/memory/#knowledge-graph-optional)를 참조하세요. `GRAPHITI_MODEL_NAME`은 더 이상 읽히지 않습니다.
* 첫 시작 시 8개의 데이터베이스 마이그레이션이 실행됩니다. 완료되면 `docker compose logs pentagi`에 "Database schema updated successfully"가 표시됩니다.

### [로그인 및 접근](https://pentagi.com/ko/docs/deployment/upgrade/#sign-in-and-access)

* 모든 사용자가 다시 로그인해야 합니다. 2.1.0의 세션은 거부됩니다. API 토큰은 계속 작동하며, 스크립트는 `POST /api/v1/auth/logout`으로 로그아웃합니다.
* API 토큰은 REST `/users`, `/roles` 및 `/tokens` 라우트에서 403 오류를 반환합니다. 계정, 역할 및 토큰은 로그인된 브라우저 세션에서 관리하세요.
* Google 및 GitHub 로그인은 이제 해당 주소의 기존 계정(로컬 계정 포함)으로 [provider](https://pentagi.com/ko/docs/glossary/#provider)가 검증한 이메일을 해당 계정의 역할로 로그인시킵니다. 2.1.0은 계정 이메일을 변경할 수 없으므로, 로그인이 활성화되어 있다면 `OAUTH_GOOGLE_CLIENT_ID` 및 `OAUTH_GITHUB_CLIENT_ID`을 빈 값으로 두고 업그레이드한 후, **Settings → Account**에서 `admin@pentagi.com`을 사용자가 제어하는 주소로 이동시킨 다음 로그인을 다시 활성화하세요. 인스톨러의 **Reset Admin Password**는 `admin@pentagi.com`만으로 관리자를 찾습니다.
* 리버스 프록시 뒤에 있는 경우 `TRUSTED_PROXIES`을 설정하세요. 그렇지 않으면 모든 사용자가 프록시의 주소를 공유하게 되어, 한 번의 로그인 실패 폭주로 인해 모든 사용자가 15분 동안 잠금됩니다. 자세한 내용은 [Network exposure](https://pentagi.com/ko/docs/configuration/security/#network-exposure)를 참조하세요.

### [Sandboxes](https://pentagi.com/ko/docs/deployment/upgrade/#sandboxes)

* `DOCKER_INSIDE=true`(2.1.0 `.env` 템플릿 및 인스톨러 기본값)을 사용하면 2.1.0은 모든 sandbox에 호스트 Docker 소켓을 마운트했습니다. 2.2.0은 [agent](https://pentagi.com/ko/docs/glossary/#agent)에게 `DOCKER_INSIDE_HOST`에 설정된 별도의 데몬 세트에서만 Docker를 제공합니다. 이것이 없으면 Docker를 전혀 사용할 수 없으며, 로그에 `sandbox DISABLED`라고 표시됩니다. `DOCKER_INSIDE_HOST`을 사용하는 경우 `DOCKER_SOCKET=`을 빈 값으로 설정하세요. 그렇지 않으면 템플릿의 `/var/run/docker.sock`이 여전히 마운트됩니다. 자세한 내용은 [Worker node](https://pentagi.com/ko/docs/deployment/worker-node/)를 참조하세요.
* 2.1.0에서 시작된 flow를 완료하세요. 해당 flow의 sandbox는 flow가 완료될 때까지 이전 소켓 마운트와 기능을 유지합니다.
* `TENANT_ID`을 빈 값으로 두세요. 기존 설치 환경에서는 이것이 PentAGI를 새로운 빈 스키마로 지정합니다.

### [모델 및 프롬프트](https://pentagi.com/ko/docs/deployment/upgrade/#models-and-prompts)

* custom provider에는 `LLM_SERVER_KEY`이 필요합니다. 키가 비어 있으면 비활성화되므로, 인증이 없는 서버의 경우 비어 있지 않은 임의의 값을 설정하세요.
* `LLM_SERVER_LEGACY_REASONING`이 제거되었습니다. custom provider는 `reasoning_effort`을 보내며 `reasoning.max_tokens` 예산을 노력 수준(effort level)으로 변환합니다. Kimi K2, 5.2 이전 버전의 GLM 및 MiniMax M 모델에서는 예산 설정이 호출을 실패시키므로, 해당 agent에서 이를 제거하세요.
* provider 구성 파일에서 `max_tokens`, `temperature`, `top_p` 또는 `n`을 비워둔 agent 항목은 이제 아무것도 전송하지 않는 대신 provider 유형의 기본값을 받습니다.
* Bedrock을 제외한 모든 provider의 내장 기본 모델이 변경되었습니다. **Settings → Providers**에 저장된 provider는 모델을 유지합니다. 이미지에 번들된 5개 구성(`openrouter`, `deepinfra`, `ollama-cloud`, `moonshot` 및 `deepseek`)의 모델이 변경되었습니다. `LLM_SERVER_CONFIG_PATH` 또는 `OLLAMA_SERVER_CONFIG_PATH`이 `/opt/pentagi/conf/` 아래에서 이들 중 하나를 가리키고 있다면, 호스트에 2.1.0 파일을 유지하고 이를 custom 또는 Ollama 구성으로 마운트하세요.
* OpenAI 이외의 서버에서 `EMBEDDING_URL`을 사용하는 경우 `EMBEDDING_KEY`을 설정하세요. `OPEN_AI_KEY`은 더 이상 해당 서버로 전송되지 않습니다.
* agent는 하나의 `web_search` 도구를 통해 검색합니다. `{{.GoogleToolName}}` 및 기타 엔진별 변수를 사용한 custom 프롬프트는 `{{.WebSearchToolName}}`을 사용할 때까지 경고와 함께 무시됩니다. custom searcher 및 pentester 프롬프트를 새로운 기본값을 기반으로 재작성(rebase)하세요.

### [기타 변경 사항](https://pentagi.com/ko/docs/deployment/upgrade/#other-changes)

* 시작 후 2분 이내와 그 후 3시간마다 PentAGI는 버전과 설치 요약 정보를 `update.pentagi.com`에 보고합니다. [Update check](https://pentagi.com/ko/docs/configuration/security/#update-check)에는 전송되는 내용이 나열되어 있으며, `UPDATE_CHECK_INTERVAL=0`으로 이를 비활성화할 수 있습니다.
* profiler는 `PPROF_ADDR`이 설정되지 않은 한 포트 7777에서 수신 대기하지 않습니다.
* 새로운 선택적 설정에는 `LLM_FALLBACK_PROVIDER`을 사용한 [provider failover](https://pentagi.com/ko/docs/configuration/llm-providers/#failover), [여러 인스턴스](https://pentagi.com/ko/docs/deployment/production/#several-instances-tenant_id)용 `DOCKER_PORTS_BASE`, `DOCKER_IMAGE_SELECTION_MODE` 및 `DOCKER_ALLOWED_IMAGES`, 내부 [search engine](https://pentagi.com/ko/docs/glossary/#search-engine) `WEB_SEARCH_INTERNAL_ENABLED`, 그리고 Mistral, xAI, MiniMax 및 Firecrawl 키가 포함됩니다.

## [백업 및 롤백](https://pentagi.com/ko/docs/deployment/upgrade/#back-up-and-roll-back)

PentAGI는 마이그레이션을 역방향으로 실행하지 않으며, 수동으로 실행하면 데이터가 삭제되므로 2.1.0으로 돌아가는 방법은 백업입니다. 데이터베이스를 사용하는 서비스를 중지하고, 데이터베이스를 다시 생성한 후 덤프를 복원하세요:

```bash
docker compose stop pentagi pgexporter
docker exec pgvector dropdb -U postgres pentagidb
docker exec pgvector createdb -U postgres pentagidb
docker exec -i pgvector pg_restore -U postgres -d pentagidb < pentagi-backup.dump
```

그런 다음 저장해 둔 `.env`과 compose 파일을 다시 넣고, `PENTAGI_IMAGE=vxcontrol/pentagi:2.1.0`을 설정한 후 스택을 시작하세요. 새로운 `docker-compose-langfuse.yml`은 그대로 유지하세요. 2.1.0 파일의 MinIO 이미지는 더 이상 pull할 수 없습니다.