왜 “image tag만 업데이트”는 위험한가 #

버전 차이가 클 경우, Dify는 단순한 컨테이너 이미지 업데이트만으로는 대응할 수 없는 경우가 있습니다. 실제로 차이를 비교해보면, 이번 업데이트에서는 다음과 같은 포인트가 있었습니다.

이번 업그레이드 방침 #

1. 먼저 docker/volumes를 포함해 전체 백업을 수행한다
2. 공식 v1.13.3을 별도 디렉터리에 가져와서 차이의 기준을 만든다
3. docker-compose.yaml은 공식 버전으로 교체한다
4. .env와 TLS 마운트 등 환경 의존 설정만 복원한다
5. Sandbox 설정 파일을 새로운 전제에 맞춘다
6. 시작 전에 docker compose config로 구문 검증한다
7. 시작 후에는 UI뿐만 아니라 Knowledge / Plugin / Code 실행까지 확인한다

1. 먼저 백업을 수행한다 #

가장 중요한 것은 업데이트 전 compose와 volumes를 복원할 수 있는 상태로 만들어두는 것입니다. 특히 Weaviate나 PostgreSQL을 사용하고 있는 경우, 업데이트 후 롤백하고 싶은 상황은 충분히 발생할 수 있습니다.

cd /srv/dify/docker
TS=$(date +%Y%m%d%H%M%S)

cp -a docker-compose.yaml "docker-compose.yaml.${TS}.bak"
cp -a .env ".env.${TS}.bak"
[ -f volumes/sandbox/conf/config.yaml ] && \
  cp -a volumes/sandbox/conf/config.yaml "volumes/sandbox/conf/config.yaml.${TS}.bak"

tar -czf "/root/dify-volumes-${TS}.tgz" volumes

경로는 어디까지나 공개용 예시입니다. 실제 운영 시에는 자사 환경의 배치에 맞춰 읽어주시기 바랍니다.

2. 공식 v1.13.3 가져오기 #

기존 디렉터리를 직접 수정하지 않고, 비교용으로 별도 디렉터리에 가져옵니다. 이 시점에서 기존 환경의 파일을 덮어쓰지 않는 것이 포인트입니다.

cd /tmp
rm -rf dify-1.13.3
git clone --branch 1.13.3 https://github.com/langgenius/dify.git dify-1.13.3

가져온 후에는 최소한 docker-compose.yaml, .env.example, volumes/sandbox/conf/config.yaml.example 이 3개를 비교하면, 이번 업데이트에서 무엇을 반영해야 하는지 파악하기 쉬워집니다.

3. compose는 공식 버전으로 교체 #

이번에는 기존 compose를 계속 수정하기보다는, 공식 v1.13.3을 그대로 기반으로 삼는 구성을 택했습니다. 이를 통해 향후 업그레이드 시에도 “공식과의 차이점”을 추적하기 쉬워집니다.

cp /tmp/dify-1.13.3/docker/docker-compose.yaml /srv/dify/docker/docker-compose.yaml
cp /tmp/dify-1.13.3/docker/.env.example /srv/dify/docker/.env.example.1.13.3
cp /tmp/dify-1.13.3/docker/volumes/sandbox/conf/config.yaml.example \
   /srv/dify/docker/volumes/sandbox/conf/config.yaml.example.1.13.3

4. 환경 의존 설정 복원 #

공식 compose를 채택한 후, 실제 운영에 필요한 설정만을 overlay하는 이미지로 복원합니다. 이번 환경에서는 주로 다음과 같은 항목이 중요했습니다.

DB_TYPE=postgresql
DB_HOST=db_postgres
DB_PORT=5432

VECTOR_STORE=weaviate
WEAVIATE_ENDPOINT=http://weaviate:8080
WEAVIATE_GRPC_ENDPOINT=grpc://weaviate:50051
WEAVIATE_API_KEY=<YOUR_WEAVIATE_API_KEY>

NGINX_SERVER_NAME=<YOUR_DOMAIN>
NGINX_HTTPS_ENABLED=true
NGINX_SSL_CERT_FILENAME=live/<YOUR_DOMAIN>/fullchain.pem
NGINX_SSL_CERT_KEY_FILENAME=live/<YOUR_DOMAIN>/privkey.pem

FILES_URL=https://<YOUR_DOMAIN>
INTERNAL_FILES_URL=http://api:5001
PLUGIN_MAX_EXECUTION_TIMEOUT=1800

포인트는, 기존 환경 변수를 모두 이어받는 것이 아니라, 새로운 공식 .env.example을 기준으로 필요한 항목만 재설정하는 것입니다. 특히 DB_HOST와 Weaviate 관련 설정은 기존 compose를 그대로 유용하면 시작 후 오류를 일으키기 쉬운 부분이었습니다.

5. NGINX의 인증서 마운트 복원 #

공식 compose로 교체한 후, 그대로 두면 TLS 관련 마운트 구성이 자사 환경과 어긋날 수 있습니다. 이번에는 인증서를 호스트 측의 기존 디렉터리에서 관리하고 있었기 때문에, NGINX 서비스만 마운트 정의를 재조정했습니다.

services:
  nginx:
    volumes:
      - ./nginx/ssl:/etc/ssl
      - /path/to/external/letsencrypt:/etc/letsencrypt

인증서를 Certbot 컨테이너에서 완결시키는 구성이라면, 그대로 공식 마운트로 문제없는 경우도 있습니다. 단, 외부 경로 관리를 하고 있는 경우는 교체 후 반드시 재검토하는 것이 안전합니다.

6. Sandbox 설정 업데이트 #

놓치기 쉬운 것이 Sandbox 측의 설정입니다. 버전이 올라가면 Python / Node.js의 경로 전제가 바뀔 수 있으며, 기존의 config.yaml은 자동 업데이트되지 않습니다.

app:
  port: 8194
  debug: true
  key: dify-sandbox

python_path: /opt/python/bin/python3
nodejs_path: /usr/local/bin/node

7. 기동 전 구문 체크, 기동 후 로그 확인 #

compose를 교체한 후에는 먼저 구문 체크를 통과시킵니다. 그 다음 이미지를 가져오고, 서비스를 기동합니다.

docker compose --profile weaviate --profile postgresql config > /tmp/dify.check.yaml

docker compose --profile weaviate --profile postgresql pull
docker compose --profile weaviate --profile postgresql up -d --remove-orphans

docker compose ps
docker compose logs --tail=120 api worker worker_beat plugin_daemon sandbox weaviate nginx

업데이트 작업에서는 기동 가능 여부만 보고 안심하지 않는 것이 중요합니다. 특히 api, worker, worker_beat, plugin_daemon, sandbox의 로그는 기능 불량의 조기 발견에 도움이 됩니다.

8. 업데이트 후 확인 체크리스트 #

• 관리 화면에 정상 로그인할 수 있다
• 기존 앱의 채팅 응답이 정상적으로 반환된다
• Knowledge의 검색·재인덱싱이 통과된다
• Code 노드와 Sandbox 실행이 성공한다
• Plugin의 활성화·실행이 성공한다
• HTTPS 배포와 인증서 참조에 문제가 없다

이번과 같이 주변 컴포넌트의 차이가 큰 업데이트에서는, UI가 열리는 것과 실제 운용에 필요한 기능이 모두 작동하는 것은 별개의 문제입니다. 사용 중인 주요 기능에 따른 확인 항목을 처음부터 정해두면 롤백 판단도 하기 쉬워집니다.

주의사항 정리 #

이번에 배운 점 #

오랫동안 운영한 Dify 환경일수록, 업그레이드 시 영향을 미치는 것은 “버전 번호”보다 “축적된 독자적 차이”입니다. 이번에 다시 느낀 것은, 공식 compose를 가능한 건드리지 않고, 환경 종속 설정은 overlay로 관리하는 편이 그 후의 업그레이드와 장애 대응도 압도적으로 편하다는 것이었습니다.

현재 환경이 구버전 그대로 안정적으로 가동되고 있다면, 업데이트 전에 다음 3가지만이라도 정리해두면 훨씬 진행하기 쉬워집니다.

• 공식 유래의 설정과 자사 고유 설정을 구분하여 정리한다
• 롤백 가능한 백업을 반드시 취득한다
• 기동 확인이 아닌, 주요 기능의 확인 항목을 미리 정해둔다