Dify надградба: новиот .env не смее слепо да го замени стариот

За да надградите самостојно хостиран Dify преку Docker Compose без да ги изгубите податоците и локалните поставки, зачувајте ја почетната состојба пред миграцијата и усогласете го постојниот .env со новиот образец. Упатството за Docker на Dify објаснува дека .env ги содржи локалните вредности, а dify-env-sync.sh прави негова копија и додава нови променливи од .env.example без автоматски да ги препише постојните. Затоа копирањето на новиот образец врз работниот .env не е соодветен чекор за надградба.

Пред продукцискиот прекин утврдете ја точната целна верзија, проверете ги нејзините посебни услови и обновете резервна копија во одвоена пробна околина. Во продукција повторете ја испробаната постапка со свежа копија и однапред одредете при каков неуспех ќе ги вратите заедно кодот, конфигурацијата и податоците.

Утврдете ја патеката до целната верзија

Запишете од кој Git tag или commit работи инсталацијата, кои container images се активни и кој векторски сервис го користи. Изберете конкретен целен tag и прочитајте ги белешките за изданијата меѓу почетната и целната верзија. Посебно издвојте промени во Compose составот, распоредот на env датотеките, миграциите на базата и зависните сервиси. Така пробата и продукциското пуштање ќе се однесуваат на ист состав, а не на подвижната состојба на главната гранка.

Белешките за Dify 1.17.1 бараат постепена рачна надградба пред стартување кај постојни инсталации со вградениот Weaviate и предупредуваат дека една миграција на базата нема обратен чекор. Условот за Weaviate не се однесува на надворешен Weaviate или друг векторски сервис. Ако вашата инсталација спаѓа во опфатот, следете ја посебната секвенца од белешките пред вообичаеното подигање на Dify; директното менување на Compose составот не ја извршува таа миграција.

Направете копија од целата почетна состојба

Копијата мора да ги опфати датотеките што ја одредуваат конфигурацијата и местата каде што навистина се чуваат податоците. Упатството за надградба во Dify 1.14.2 наведува копии од приспособените docker-compose.yaml и env датотеки, запирање на сервисите, архивирање на локалната папка volumes и преглед на новиот распоред под docker/envs/. Тоа е конкретен пример за издание со конфигурациска промена; за избраниот целен tag важат и неговите сопствени упатства.

1. Зачувајте ги активните docker-compose.yaml, .env, дополнителните Compose датотеки и сите локално изменети датотеки под envs/. Чувајте ја копијата одвоено од работната папка што ќе ја менувате и ограничете го пристапот, бидејќи env датотеките може да содржат тајни.
2. Запрете ги записите и сервисите според постапката за вашата верзија, па архивирајте ги локалните трајни податоци. Не додавајте опција што ги отстранува volumes при запирањето.
3. Проверете дали Compose составот користи и именувани volumes. Упатството на Docker за volumes опишува посебно архивирање и обновување на нивната содржина. Надворешна база, објектно складиште или надворешен векторски сервис исто така бараат копија според сопствената постапка.

Запишете каде е секоја копија, како се обновува и на која почетна верзија ѝ припаѓа. Проверете дека архивите се читливи, а во пробната околина потврдете дека податоците навистина може да се обноват. Архива што постои, но не може да се врати, не е употреблива основа за враќање по неуспешна миграција.

Усогласете ги поставките без препишување

Во работна копија од целниот tag споредете го стариот .env со .env.example. Додајте ги потребните нови клучеви, но за секој проверете дали предложената вредност одговара на вашата база, адреси, тајни клучеви и избраниот векторски сервис. Ако користите целосен приспособен .env, dify-env-sync.sh може да ја направи почетната синхронизација; неговата резервна копија на .env не ја заменува копијата на податоците и Compose конфигурацијата.

Променлива што исчезнала од главниот образец не мора да е укината. Проверете ги соодветните обрасци под envs/ и пренесете ги локалните вредности во датотеките што ги користи новиот состав. Исто така споредете го новиот docker-compose.yaml со стариот приспособен состав: mounts, мрежи, дополнителни сервиси и локални патеки можеби бараат рачно пренесување. Запишете ги тие одлуки за пробата да се изврши со истите поставки што планирате да ги пуштите во продукција.

Обновете пробна копија и проверете ги функциите

Подигнете одвоена пробна околина со сопствен Compose project name и без можност да запишува во продукциските складишта. Во неа обновете ги копиите, применете го целниот tag и усогласената конфигурација, па извршете ги миграциските чекори што се однесуваат на избраното издание. Оваа проба покажува дали обновените податоци, новиот состав и локалните поставки работат заедно пред вистинскиот прекин.

Пред стартување извршете docker compose config -q. Референцата за docker compose config наведува дека командата го составува ефективниот Compose модел, а опцијата -q ја проверува конфигурацијата без да ја испечати. Потоа проверете ги релевантните разрешени вредности на безбеден начин, без да изложите тајни во споделени излези или логови.

По подигањето прегледајте го статусот на сервисите и логовите, но проверете и работа со постојните податоци: најава, отворање апликација, извршување workflow и пребарување во база на знаење што веќе содржи документи. Додајте проверка за модел, додатоци, прикачени датотеки или надворешни интеграции ако од нив зависи вашата инсталација. Активен container сам по себе не покажува дека мигрираната база и поврзаните сервиси работат.

Пуштете во продукција со подготвено враќање

Во договорениот термин направете свежа копија по запирањето на записите и повторете ја секвенцата што поминала во пробната околина. Користете го истиот целен tag, проверените конфигурациски измени и соодветните миграциски чекори. По стартувањето повторете ги функционалните проверки со продукциските податоци и задржете ја почетната верзија достапна додека одлучувате дали надградбата е прифатена.

Однапред одредете кој носи одлука за враќање и кои резултати ја активираат: неуспешна миграција, недостапна база или прекин на клучна функција што работела пред надградбата. Во тој случај запрете го новиот состав и обновете ги старата верзија, нејзината конфигурација и податоците од истата почетна состојба, вклучувајќи ги поврзаните надворешни складишта кога биле опфатени. Враќањето само на Git tag не ја враќа состојбата на база или векторски индекс што веќе биле изменети.