Infrastructure / Self-hosted AI Platform

Dify को v1.9.2 से v1.13.3 में अपग्रेड कैसे करें और किन pitfalls से बचें #

Self-hosted Dify को अपग्रेड करना उतना ही कठिन होता जाता है, जितने अधिक कस्टम बदलाव पुराने docker-compose.yaml में किए गए हों। इस बार, हमने Docker Compose पर चल रहे Dify को v1.9.2 से v1.13.3 में अपडेट करने की प्रक्रिया को दस्तावेज़ित किया है, जिसमें सार्वजनिक रिलीज़ के लिए संवेदनशील जानकारी मास्क कर दी गई है। केवल image tag अपडेट करने के बजाय, सबसे सुरक्षित तरीका यह था कि official compose को base बनाकर replace करें, फिर environment-विशिष्ट settings को restore करें।

Dify Docker Compose Weaviate Self-hosted Upgrade Masked for Public

सार्वजनिक रिलीज़ नोट
इस लेख में domain नाम, ईमेल एड्रेस, API keys, authentication credentials, certificate paths, hostnames, और कुछ volume configurations को वास्तविक environment की पहचान रोकने के लिए मास्क या abstract किया गया है।

Before

अपडेट से पहले की configuration #

Dify v1.9.2 base
Docker Compose के साथ operate किया गया
PostgreSQL / Redis / Weaviate
NGINX reverse proxy + external certificate directory
Sandbox / Plugin Daemon enabled

After

अपडेट के बाद की configuration #

Dify v1.13.3 base
Official compose को foundation बनाकर reconfigure किया गया
नई configuration में db_postgres / worker_beat शामिल
Sandbox settings को नए paths के अनुसार अपडेट किया गया
कस्टम TLS / plugin settings दोबारा लागू किए गए

केवल “Image Tag अपडेट” जोखिम भरा क्यों है #

बड़े version gaps के साथ, Dify केवल एक सामान्य container image अपडेट को absorb नहीं कर पाता। वास्तविक differences की तुलना करने पर, इस अपडेट में निम्नलिखित प्रमुख बिंदु थे।

Service configuration में बदलाव #

नए official compose में, DB service का नाम db_postgres होना अपेक्षित है, न कि db, और इसमें worker_beat और permission initialization प्रोसेस शामिल हैं, जो संरचनात्मक अंतर दिखाते हैं।

आसपास के components के अपडेट #

Plugin Daemon, Sandbox, Weaviate, और Dify core से परे अन्य components भी अपडेट के दायरे में हैं। पुरानी configuration फ़ाइलें रखने से startup के बाद आसानी से ऐसी स्थिति बन सकती है जहाँ कुछ features टूट जाएँ।

कस्टम customizations का अस्तित्व #

लंबे समय से चल रहे environments में कस्टम settings जमा होती जाती हैं: certificate mounts, कस्टम environment variables, plugin configurations आदि। ये official compose में अपने आप शामिल नहीं होतीं, इसलिए मैनुअल restoration जरूरी है।

Configuration फ़ाइल का drift #

पुराने compose को सीधे एडिट करते रहने से समय के साथ यह अस्पष्ट हो जाता है कि कौन-सी settings official हैं और कौन-सी कंपनी-विशिष्ट। इस स्थिति में bulk अपडेट करने से ऐसी failures हो सकती हैं जिनसे recover करना मुश्किल हो।

इस बार का निर्णय
मौजूदा compose को जीवित रखने के बजाय, official v1.13.3 compose को base बनाकर replace करना और केवल आवश्यक differences को restore करना — इससे अपडेट के बाद readability और maintainability कहीं बेहतर रही।

इस अपडेट के लिए upgrade strategy #

सबसे पहले, docker/volumes सहित full backup लें
Diff baseline स्थापित करने के लिए official v1.13.3 को एक अलग directory में प्राप्त करें
docker-compose.yaml को official version से replace करें
केवल environment-विशिष्ट settings जैसे .env और TLS mounts को restore करें
Sandbox configuration फ़ाइलों को नई मान्यताओं के अनुसार अपडेट करें
Startup से पहले docker compose config से syntax validate करें
Startup के बाद, केवल UI ही नहीं बल्कि Knowledge / Plugin / Code execution भी वेरिफ़ाई करें

1. सबसे पहले backup लें #

सबसे महत्वपूर्ण बात यह सुनिश्चित करना है कि अपडेट से पहले वाले compose और volumes पर वापस लौटा जा सके। खासकर Weaviate या PostgreSQL के साथ, ऐसे परिदृश्य निश्चित रूप से होते हैं जहाँ अपडेट के बाद rollback करना चाहेंगे।

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

यहाँ दिखाए गए paths सार्वजनिक रिलीज़ के लिए उदाहरण हैं। Production में, इन्हें अपने environment की directory संरचना के अनुसार बदलें।

2. Official v1.13.3 प्राप्त करें #

मौजूदा directory को सीधे मॉडिफाई करने के बजाय, तुलना के लिए इसे एक अलग directory में fetch करें। मुख्य बिंदु यह है कि इस चरण में मौजूदा environment फ़ाइलों को overwrite न करें।

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

Fetch करने के बाद, कम-से-कम तीन फ़ाइलों की तुलना करने से यह समझना आसान हो जाता है कि इस अपडेट में क्या absorb करना है: docker-compose.yaml, .env.example, और volumes/sandbox/conf/config.yaml.example।

3. Compose को official version से replace करें #

इस बार, मौजूदा compose को मॉडिफाई करते रहने के बजाय, हमने official v1.13.3 को सीधे foundation के रूप में अपनाया। इससे भविष्य के upgrades में “official से differences” को track करना आसान हो जाता है।

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

महत्वपूर्ण
सबसे अहम बिंदु यह है कि compose replace करने के तुरंत बाद start न करें। पहले .env, certificate mounts, Sandbox settings जैसे environment-विशिष्ट values restore करें, फिर start करें।

4. Environment-विशिष्ट settings restore करें #

Official compose अपनाने के बाद, production operations के लिए जरूरी settings को ही overlay के रूप में restore करें। हमारे environment में, निम्नलिखित items विशेष रूप से महत्वपूर्ण थे।

हमेशा वेरिफ़ाई करने वाले items #

DB_HOST को db_postgres पर सेट किया गया है
Weaviate API key और gRPC endpoint
NGINX server name और certificate path
Public URL और internal files URL
Plugin Daemon संबंधित timeout settings

सार्वजनिक रिलीज़ के लिए मास्क करने वाले items #

Domain नाम
ईमेल एड्रेस
API keys / secrets
वास्तविक certificate फ़ाइल नाम
Internal volume configurations और hostnames

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

मुख्य बिंदु यह है कि सभी पुराने environment variables को carry over न करें, बल्कि नए official .env.example के आधार पर केवल जरूरी items को reconfigure करें। खासकर DB_HOST और Weaviate संबंधित settings ऐसी जगहें हैं जहाँ पुराने compose से reuse करने पर startup के बाद errors होने की आशंका रहती है।

5. NGINX certificate mounts restore करें #

Official compose से replace करने के बाद, TLS mount configuration आपके environment की मान्यताओं से अलग हो सकती है। इस बार, हम certificates को एक मौजूदा host directory में manage कर रहे थे, इसलिए हमने केवल NGINX service के लिए mounts को readjust किया।

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

यदि आपकी configuration में certificates पूरी तरह Certbot container के भीतर संभाले जाते हैं, तो official mounts जस-के-तस ठीक हो सकते हैं। हालांकि, यदि आप certificates को external paths के जरिये manage करते हैं, तो replacement के बाद समीक्षा करना अधिक सुरक्षित है।

6. Sandbox configuration अपडेट करें #

एक आम तौर पर अनदेखा किया जाने वाला पहलू है Sandbox configuration। Version बदलने पर, Python / Node.js path की मान्यताएँ बदल सकती हैं, और मौजूदा config.yaml फ़ाइलें अपने आप अपडेट नहीं होतीं।

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

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

नोट
पुरानी config.yaml carry over करने पर अक्सर ऐसी स्थिति बनती है जहाँ UI तो ठीक start होता है लेकिन केवल Code execution fail होता है। अपडेट के बाद, Sandbox को स्वतंत्र रूप से वेरिफ़ाई करने की सलाह दी जाती है।

7. Startup से पहले syntax check, startup के बाद log की समीक्षा #

Compose replace करने के बाद, सबसे पहले syntax checks चलाएँ। फिर images fetch करें और services start करें।

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

अपडेट के काम में यह महत्वपूर्ण है कि startup हो जाने भर से सफलता मान न लें। खासकर api, worker, worker_beat, plugin_daemon, और sandbox के logs functionality failures का जल्दी पता लगाने में उपयोगी हैं।

8. अपडेट के बाद की verification checklist #

Admin console में login सामान्य रूप से काम करता है
मौजूदा applications से chat responses सामान्य रूप से लौटते हैं
Knowledge search और reindexing सफल होते हैं
Code node और Sandbox execution सफल होता है
Plugin activation और execution सफल होता है
HTTPS delivery और certificate reference बिना किसी समस्या के काम करते हैं

इस जैसे अपडेट में, जहाँ आसपास के components के differences बड़े हों, UI का खुलना और production में सभी आवश्यक functions का काम करना दो अलग-अलग बातें हैं। अपने उपयोग के आधार पर प्रमुख verification items पहले से तय करने से rollback के निर्णय आसान हो जाते हैं।

आम pitfalls का सारांश #

`DB_HOST` mismatch #

यदि इसे नए official compose से align न किया जाए, तो API और Plugin Daemon database से connect नहीं हो पाते और crash हो जाते हैं। db और db_postgres के बीच का mismatch विशेष रूप से आसानी से नज़रअंदाज़ हो जाने वाला बिंदु था।

`worker_beat` की अनदेखी #

केवल मुख्य API और worker पर ध्यान केंद्रित करने से periodic tasks की समस्याएँ छूट सकती हैं। अपडेट के बाद, auxiliary services को भी वेरिफ़ाई करना अधिक सुरक्षित है।

TLS mount restoration भूल जाना #

Compose को official version से replace करते समय, certificate paths आपके environment की मान्यताओं से बाहर जा सकते हैं। इससे HTTP तो ठीक काम करता है लेकिन HTTPS fail हो जाता है।

पुरानी Sandbox configuration को carry over करना #

चूंकि admin console खुल जाता है, यह आसानी से छूट जाता है, लेकिन यह सीधे Code execution failures को प्रभावित करता है। UI और Sandbox दोनों को अलग-अलग वेरिफ़ाई करना कुंजी है।

इस अपडेट से मिले सबक #

Dify environment जितना लंबे समय तक चलता है, upgrade के समय “version numbers” की तुलना में “जमा हुए कस्टम differences” का प्रभाव उतना ही अधिक होता है। इस बार हमने फिर से यह पुष्टि की कि official compose के modifications को न्यूनतम रखना और environment-विशिष्ट settings को overlays के रूप में manage करना बाद के upgrades और incident response को नाटकीय रूप से आसान बना देता है।

यदि आपका मौजूदा environment किसी पुराने version पर स्थिर रूप से चल रहा है, तो अपडेट से पहले सिर्फ ये तीन बिंदु व्यवस्थित कर लेने से प्रक्रिया कहीं अधिक सहज हो जाती है।

Official से आई settings और कंपनी-विशिष्ट settings की inventory बनाकर उन्हें अलग करें
हमेशा rollback-सक्षम backups लें
Startup verification से पहले प्रमुख feature verification items तय करें

निष्कर्ष
Dify के बड़े version अपडेट के लिए, “पुराने compose को extend करने” के बजाय “नए official compose पर rebase करना” — यह अधिक सुरक्षित तरीका है और ऐसी configuration देता है जो बाद में देखने पर भी समझ में आती है।

Dify को v1.9.2 से v1.13.3 में अपग्रेड करने की प्रक्रिया और समस्याग्रस्त बिंदु