Naik taraf Lucee 7.1 ke 8.0: senarai semak langkah demi langkah

Naik taraf Lucee 7.1 ke 8.0: senarai semak langkah demi langkah

Naik taraf dari Lucee 7.1 ke 8.0 bukan sekadar menukar fail jar. Lucee 8.0 membawa perubahan yang boleh mematahkan kod dan konfigurasi secara senyap, jadi anda perlu mengikut senarai semak yang teratur. Artikel ini menulis semula resipi rasmi Lucee ke dalam Bahasa Melayu dan menyesuaikannya dengan keadaan pelayan sebenar, lengkap dengan arahan pemeriksaan yang boleh anda jalankan sendiri.

Sebelum mula: baca perubahan yang mematahkan

Langkah pertama ialah memahami apa yang berubah. Dokumentasi rasmi Lucee menyediakan halaman Breaking Changes between Lucee 7.1 and 8.0 yang menerangkan latar belakang setiap perubahan, dan halaman senarai semak untuk ejen pengekodan AI yang menyusun perubahan mengikut kesan. Baca kedua-duanya dahulu sebelum menyentuh apa-apa.

Ringkasan perubahan paling penting untuk diingat: Java 21 menjadi minimum, tetapan konfigurasi tertentu mesti dipindahkan ke dalam seksyen, fungsi selari kini menggunakan benang maya, susunan kunci scope berubah, dan enjin PDF diganti. Gambaran penuh ada dalam artikel Lucee 8.0: apa yang baharu.

Langkah 1: sandaran dahulu

Sebelum sebarang perubahan, buat sandaran lengkap tiga perkara: kod aplikasi, pangkalan data, dan fail konfigurasi Lucee. Fail konfigurasi ialah .CFConfig.json atau config.json yang terletak dalam folder konteks Lucee, biasanya di bawah lucee-server/context/ atau WEB-INF/lucee/.

Jangan langkau langkah ini walaupun anda yakin. Sandaran ialah pelan undur yang paling asas, dan tanpa sandaran konfigurasi, anda tidak boleh kembali ke keadaan 7.1 dengan cepat jika sesuatu rosak. Rujuk panduan sandaran dan pemulihan CFML untuk butiran lengkap.

Langkah 2: semak keperluan Java 21

Lucee 8.0 tidak akan mula pada Java 11 atau 17. Sahkan versi Java pada pelayan anda dahulu:

java -version

Jika ia menunjukkan Java 11 atau 17, anda mesti menaik taraf JVM kepada Java 21 atau lebih baharu terlebih dahulu. Bagi pengguna Docker, semak imej asas dalam Dockerfile dan tukar kepada yang berasaskan Java 21:

grep -nE '^\s*FROM\s' Dockerfile*

Bekas servlet mesti kekal berasaskan Jakarta, iaitu Tomcat 10.1 atau lebih baharu, sama seperti 7.x. Jangan ubah bahagian ini.

Langkah 3: semak perubahan konfigurasi

Dalam 8.0, beberapa tetapan yang dahulunya berada di peringkat atas fail .CFConfig.json kini hanya dibaca di dalam seksyen masing-masing. Jika dibiarkan di peringkat atas, Lucee mengabaikannya tanpa amaran. Ini termasuk kunci debugging (contohnya debuggingTemplate, showDebug), cacheDefault (contohnya cacheDefaultQuery), dan updateProxy (contohnya updateProxyHost).

Gunakan jq untuk mengesan kunci yang perlu dipindahkan:

jq -r 'keys[] | select(test("^(debugging|showDebug|cacheDefault|updateProxy)"))' .CFConfig.json

Pindahkan setiap kunci yang ditemui ke lokasi baharu: kunci debugging dan showDebug ke dalam monitoring, cacheDefault ke dalam cache, dan updateProxy ke dalam proxy. Nilai kekal sama, cuma lokasinya berubah.

Langkah 4: semak perubahan kod

Tiga perkara dalam kod CFML yang paling kerap terkesan. Pertama, susunan kunci scope application, server, dan sesi tidak lagi mengikut susunan sisipan, jadi kod yang melingkar ke atas scope atau membandingkan output bersiri perlu disemak. Kedua, fungsi selari seperti arrayEach dengan parallel=true kini berjalan di atas benang maya tanpa had, jadi tutup yang menggunakan sumber terhad perlu menetapkan had secara eksplisit. Ketiga, penjanaan PDF melalui cfdocument menggunakan enjin baharu dan outputnya perlu dibandingkan.

Jika anda menggunakan skrip automasi pentadbir, banyak argumen Administrator.cfc dan cfadmin telah ditukar nama. Argumen lama diabaikan tanpa ralat, jadi skrip anda mungkin senyap menyimpan nilai lalai. Semak setiap skrip sedemikian secara manual.

Langkah 5: uji di slot ujian atau bekas

Jangan naik taraf terus pada pelayan pengeluaran. Sediakan slot ujian yang meniru pengeluaran, sama ada pelayan berasingan atau bekas Docker dengan imej 8.0 RC. Salin kod dan konfigurasi anda ke sana, kemudian jalankan boot pertama dengan pengesahan konfigurasi dihidupkan:

LUCEE_CONFIG_VALIDATE=true

Bendera ini memaksa Lucee memuatkan setiap tetapan ketika mula, jadi nilai yang tidak sah kelihatan serta-merta dan bukannya ketika tetapan itu pertama kali digunakan. Jalankan suite ujian aplikasi anda, uji laluan kritikal secara manual, dan jana semula PDF penting untuk dibandingkan. Pendekatan bekas diterangkan dalam deploy Lucee dengan Docker.

Langkah 6: naik taraf jar atau imej Docker

Selepas ujian lulus, barulah naik taraf persekitaran pengeluaran. Bagi pemasangan berasaskan jar, gantikan fail lucee.jar dengan versi 8.0 RC dan pastikan kebergantungan yang diperlukan boleh dimuat turun. Lucee 8.0 memuat turun artifak daripada repositori Maven, jadi pastikan pelayan anda boleh mencapai repositori tersebut:

curl -s -o /dev/null -w "%{http_code}\n" --max-time 10 https://repo1.maven.org/maven2/

Jika kod jawapan bukan 200, sama ada buka akses firewall atau sediakan cermin Maven dalaman melalui tetapan maven.repository. Bagi pengguna Docker, tukar tag imej kepada 8.0 RC dan bina semula bekas, ikut corak yang sama seperti deploy tanpa henti jika anda mahu mengelakkan masa henti.

Langkah 7: cetus muat semula dan sahkan versi

Selepas menggantikan jar atau imej, mulakan semula Lucee supaya ia memuatkan versi baharu. Sahkan versi yang berjalan dengan menyemak pemboleh ubah pelayan dalam templat CFML ringkas:

writeOutput( server.lucee.version );

Ia sepatutnya memaparkan versi 8.0, contohnya 8.0.0.186. Anda juga boleh menyemak versi melalui halaman gambaran keseluruhan dalam Lucee Administrator. Jika versi masih menunjukkan 7.1, proses naik taraf belum berjaya dan anda perlu semak sama ada jar lama masih digunakan.

Langkah 8: sahkan setiap laman dan semak log

Selepas versi disahkan, buka setiap laman penting aplikasi dan semak ia berfungsi. Beri perhatian khusus kepada laman yang menjana PDF, laman yang menggunakan fungsi selari, dan laman yang membaca tetapan konfigurasi. Pantau log pelayan untuk ralat konfigurasi atau sambungan yang gagal dimuat turun:

tail -n 100 /opt/lucee/server/context/logs/application.log

Lokasi log bergantung pada pemasangan anda, tetapi ia sentiasa berada di bawah folder logs dalam konteks Lucee. Ralat konfigurasi biasanya muncul di sini atau dalam output konsol seperti catalina.out. Untuk pemantauan berterusan, rujuk log dan pemantauan CFML.

Pelan undur

Pelan undur anda ialah sandaran yang dibuat dalam langkah pertama. Jika sesuatu rosak selepas naik taraf dan tidak dapat dibaiki dengan cepat, pulihkan kod, pangkalan data, dan fail konfigurasi 7.1, kemudian kembalikan jar atau imej kepada versi 7.1 dan mulakan semula. Pastikan anda menguji pelan undur ini di slot ujian sebelum ia diperlukan dalam kecemasan.

Satu peringatan penting: fail .CFConfig.json yang disimpan oleh 8.0 tidak dibaca sama oleh 7.1 kerana 8.0 menulis tetapan ke dalam seksyen baharu. Jadi selepas undur, pastikan anda memulihkan fail konfigurasi 7.1 daripada sandaran, bukan menggunakan fail yang telah diubah oleh 8.0.

Untuk rujukan pantas, berikut ialah ringkasan keseluruhan proses dalam bentuk jadual:

Soalan Lazim (FAQ)

Bolehkah saya naik taraf terus dari 7.1 ke 8.0 tanpa langkah perantaraan?

Ya, laluan naik taraf yang didokumenkan ialah terus dari 7.1 ke 8.0. Yang penting ialah mengikut senarai semak perubahan yang mematahkan, bukan melompat versi secara berperingkat.

Adakah saya perlu menaik taraf Java sebelum Lucee?

Ya, jika anda masih di Java 11 atau 17. Lucee 8.0 memerlukan Java 21 atau lebih baharu dan tidak akan mula pada versi yang lebih lama.

Apakah LUCEE_CONFIG_VALIDATE itu?

Ia pemboleh ubah persekitaran yang memaksa Lucee memuatkan setiap tetapan konfigurasi ketika mula, supaya nilai tidak sah kelihatan serta-merta. Gunakannya semasa ujian, kemudian buang jika tidak diperlukan kekal.

Apa yang berlaku jika saya tinggalkan kunci konfigurasi lama di peringkat atas?

Lucee 8.0 mengabaikannya tanpa amaran dan menggunakan nilai lalai. Tetapan seperti pilihan nyahpepijat boleh mati secara senyap tanpa sebarang ralat dalam log.

Bagaimana cara saya kembali ke 7.1 jika naik taraf gagal?

Pulihkan sandaran kod, pangkalan data, dan fail konfigurasi 7.1, kemudian kembalikan jar atau imej kepada 7.1 dan mulakan semula. Jangan guna fail konfigurasi yang telah diubah oleh 8.0.

Sumber

• Upgrade Lucee 7.1 to 8.0: Checklist for AI Coding Agents
• Breaking Changes between Lucee 7.1 and 8.0
• Lucee All Releases
• Lucee 7.1 new features
• Lucee releases di GitHub
• Lucee Changelog