업그레이드 — PentAGI

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

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

시작하기 전에

현재 실행 중인 버전 이후의 모든 버전에 대한 릴리스 노트를 읽으세요. 2.1.0부터는 업그레이드 안내 사항이 포함되어 있습니다.
데이터베이스를 백업하세요. 인스톨러와 PentAGI 모두 이를 수행하지 않으며, 마이그레이션은 데이터를 손실하지 않고 롤백할 수 없습니다. 기본 PENTAGI_POSTGRES_USER 및 PENTAGI_POSTGRES_DB을 사용하는 경우:
```
docker exec pgvector pg_dump -U postgres -Fc pentagidb > pentagi-backup.dump
```
.env과 compose 파일의 복사본도 보관하세요. 인스톨러는 백업 없이 compose 파일을 교체합니다.
더 이상 필요하지 않은 flow를 완료하세요. 여전히 실행 중인 sandbox는 생성된 당시의 설정(해당 sandbox를 생성한 릴리스의 설정)으로 재사용됩니다.
2.1.0에서 업그레이드하는 경우, 새 릴리스가 시작되기 전에 .env 및 그 옆의 파일들에 2.1.0에서 2.2.0으로의 변경 사항을 적용하세요. Google 또는 GitHub 로그인이 활성화되어 있다면 지금 OAUTH_GOOGLE_CLIENT_ID와 OAUTH_GITHUB_CLIENT_ID을 비우세요. 해당 섹션에서 이유를 설명합니다.

Docker Compose

새 릴리스의 compose 파일을 .env 옆에 다운로드하세요: docker-compose.yml 및 실행 중인 각 선택적 스택의 파일입니다. PentAGI 컨테이너는 해당 compose 파일에 나열된 변수만 받으므로, 이전 버전의 파일 뒤에서는 .env의 새 설정이 적용되지 않습니다.
```
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
```
스택을 시작할 때 사용하는 것과 동일한 -f 파일로 이미지를 pull하고 다시 시작하세요. pull가 없으면 up -d는 호스트에 이미 있는 이미지만 유지합니다.
```
docker compose pull && docker compose up -d
```
flow를 실행하는 Docker 호스트에서 sandbox 이미지를 새로 고치세요. docker compose pull는 이를 수행하지 않습니다. 이후에 생성된 flow는 이 이미지를 사용합니다.
```
docker pull vxcontrol/kali-linux
```

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

인스톨러

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

2.1.0에서 2.2.0으로

파일

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를 위해 저장소의 examples/neo4j을 ./neo4j에 배치하세요(Graphiti는 APOC 플러그인이 필요합니다). 모델 프리셋은 Memory and knowledge를 참조하세요. GRAPHITI_MODEL_NAME은 더 이상 읽히지 않습니다.
첫 시작 시 8개의 데이터베이스 마이그레이션이 실행됩니다. 완료되면 docker compose logs pentagi에 "Database schema updated successfully"가 표시됩니다.

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

Sandboxes

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

모델 및 프롬프트

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)하세요.

기타 변경 사항

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

백업 및 롤백

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

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할 수 없습니다.