Lucee di belakang IIS: isu dan penyelesaian

Lucee di belakang IIS: isu dan penyelesaian

Apabila anda perlu menjalankan Lucee pada pelayan Windows yang sudah ada IIS, anda ada dua pilihan: sambungkan Lucee melalui ISAPI redirector, atau letakkan Lucee di belakang IIS sebagai reverse proxy menggunakan Application Request Routing (ARR). Kedua-dua cara berfungsi, tetapi kebanyakan pemasangan baharu lebih senang diselenggara dengan reverse proxy. Artikel ini menerangkan kedua-dua cara, contoh web.config yang sah, masalah biasa, dan cara membaca log kedua-dua pelayan bersama. Jika anda belum memasang Lucee, rujuk dahulu panduan pemasangan Lucee.

Dua cara: ISAPI redirector lawan reverse proxy ARR

ISAPI redirector ialah penyambung daripada projek Tomcat Connectors. Ia satu fail DLL asli bernama isapi_redirect.dll yang dimuatkan terus ke dalam proses IIS, dan ia bercakap dengan pelayan servlet di belakang menggunakan protokol AJP. Pendekatan ini memerlukan tiga perkara: fail DLL itu sendiri, fail workers.properties yang menerangkan hos dan port pekerja, dan fail uriworkermap.properties yang memetakan corak URL kepada pekerja. Anda juga perlu mendaftarkan DLL itu sebagai penapis ISAPI, membenarkannya dalam senarai ISAPI and CGI Restrictions, dan menyediakan satu direktori maya dengan kebenaran execute. Pendekatan ini sesuai apabila Lucee berjalan sebagai servlet di dalam Tomcat.

Reverse proxy ARR mengambil jalan berbeza. Anda memasang dua modul IIS, iaitu URL Rewrite dan Application Request Routing, kemudian menulis satu peraturan rewrite yang menghantar setiap permintaan ke Lucee melalui HTTP biasa, contohnya http://127.0.0.1:8888. Tiada DLL asli, dan anda boleh menguji laluan itu dengan curl terus ke port Lucee sebelum menyambungkannya ke IIS. Inilah pendekatan yang saya syorkan untuk pemasangan baharu, dan ia sama konsepnya dengan meletakkan Lucee di belakang nginx.

Kenapa reverse proxy lebih mudah diselenggara

Reverse proxy ARR menang dalam beberapa perkara yang sering memeningkan pemasangan ISAPI. Pertama, tiada isu bitness: DLL yang salah menghasilkan ralat 404 atau 500 yang mengelirukan, manakala reverse proxy tidak memuatkan apa-apa ke dalam proses IIS selain modul yang disokong Microsoft.

Kedua, ia bercakap HTTP, jadi anda boleh melihat setiap permintaan dengan alat biasa seperti curl tanpa mentafsir log AJP. Ketiga, anda mengawal header sepenuhnya, kunci kepada isu skema asal dan sesi yang dibincangkan nanti. Keempat, ARR memberi caching dan pengimbangan beban secara percuma, dan Lucee boleh berada pada mesin lain sepenuhnya.

Konfigurasi web.config untuk laluan dan header

Ini web.config minimum untuk reverse proxy, dengan peraturan rewrite, pemeliharaan hos, dan had muat naik dinaikkan kepada 100 MB:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="LuceeReverseProxy" stopProcessing="true">
          <match url="(.*)" />
          <serverVariables>
            <set name="HTTP_X_FORWARDED_PROTO" value="https" />
            <set name="HTTP_X_FORWARDED_HOST" value="{HTTP_HOST}" />
          </serverVariables>
          <action type="Rewrite" url="http://127.0.0.1:8888/{R:1}" />
        </rule>
      </rules>
    </rewrite>
    <proxy preserveHostHeader="true" reverseRewriteHostInResponseHeaders="true" />
    <security>
      <requestFiltering>
        <requestLimits maxAllowedContentLength="104857600" />
      </requestFiltering>
    </security>
  </system.webServer>
</configuration>

Tiga perkara di sini patut diberi perhatian. preserveHostHeader memastikan Lucee menerima header Host asal pelawat, bukan 127.0.0.1:8888; tanpanya Lucee membina pautan mutlak dan kuki sesi dengan hos yang salah. Elemen serverVariables menambah X-Forwarded-Proto supaya Lucee tahu permintaan asal tiba melalui https. Dan requestLimits menaikkan had muat naik daripada lalai 30 MB.

Sebelum peraturan ini berjalan, dua persediaan perlu dibuat dengan appcmd. Pertama, pemboleh ubah pelayan yang ditetapkan dalam peraturan rewrite mesti didaftarkan dalam senarai yang dibenarkan, dan kedua, proksi ARR mesti dihidupkan di peringkat pelayan:

# Benarkan pemboleh ubah pelayan yang ditetapkan oleh peraturan rewrite
%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/rewrite/allowedServerVariables /+"[name='HTTP_X_FORWARDED_PROTO']" /commit:apphost
%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/rewrite/allowedServerVariables /+"[name='HTTP_X_FORWARDED_HOST']" /commit:apphost

# Hidupkan proksi ARR di peringkat pelayan
%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/proxy /enabled:"True" /commit:apphost

Untuk pendekatan ISAPI redirector pula, fail konfigurasi asasnya kelihatan seperti ini:

# workers.properties
worker.list=lucee
worker.lucee.type=ajp13
worker.lucee.host=127.0.0.1
worker.lucee.port=8009

# uriworkermap.properties
/*.cfm=lucee
/*.cfc=lucee
/=lucee

Dan DLL itu didaftarkan sebagai penapis dengan satu arahan:

%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/isapiFilters /+"[name='jakarta',path='C:\isapi\isapi_redirect.dll',enabled='True']" /commit:apphost

Masalah biasa dan pembetulannya

Ralat 500.19 ialah aduan paling kerap selepas menambah web.config. Ia bermaksud IIS enggan memuatkan satu seksyen konfigurasi. Varian paling biasa membawa kod 0x80070021, yang bermaksud seksyen itu dikunci di peringkat induk. Penyelesaiannya ialah membuka kunci seksyen itu di peringkat pelayan:

%windir%\system32\inetsrv\appcmd.exe unlock config -section:system.webServer/handlers
%windir%\system32\inetsrv\appcmd.exe unlock config -section:system.webServer/security/requestFiltering

Handler hilang menunjukkan diri sebagai 404.2 atau 404.3 dalam mod ISAPI: 404.2 bermaksud DLL belum dibenarkan dalam ISAPI and CGI Restrictions, manakala 404.3 bermaksud IIS tidak tahu cara menghidangkan .cfm. Dalam mod reverse proxy, IIS memulangkan 404 kerana tiada handler untuk .cfm, yang biasanya bermaksud peraturan rewrite tidak sepadan atau modul URL Rewrite belum dipasang.

Laluan maya ialah perangkap khusus ISAPI redirector. Fail isapi_redirect.properties menetapkan extension_uri yang menunjuk ke direktori maya, contohnya /jakarta/isapi_redirect.dll, dan direktori itu mesti wujud serta membenarkan execute. Jika extension_uri tidak sepadan, permintaan .cfm gagal sebelum sampai ke Lucee.

HTTPS di hadapan menimbulkan isu skema asal. Apabila TLS ditamatkan di IIS dan Lucee menerima http biasa, Lucee melihat cgi.https sebagai kosong, jadi pautan mutlak dan ubah hala dibina dengan http. Penyelesaiannya ialah menghantar header X-Forwarded-Proto seperti dalam web.config di atas, dan memastikan Lucee mempercayai header itu.

Sesi hilang ada dua punca yang sering bertindih. Pertama, jika preserveHostHeader tidak dihidupkan, kuki sesi JSESSIONID dijana dengan hos 127.0.0.1, jadi pelayar tidak menghantarnya kembali kepada domain sebenar, dan setiap permintaan kelihatan seperti pengguna baharu. Kedua, jika aplikasi menetapkan this.sessioncookie.secure = true tetapi skema asal tidak dihantar, Lucee tidak tahu permintaan itu https dan kuki Secure tidak berfungsi seperti sepatutnya. Rujuk panduan pengurusan sesi untuk perincian kuki sesi.

Had muat naik ialah perangkap terakhir yang menyakitkan. IIS menghadkan badan permintaan kepada 30 MB secara lalai melalui requestFiltering, dan lebihan dipulangkan dengan 404.13 sebelum sampai ke Lucee. Ramai pembangun menyalahkan Lucee sedangkan IIS yang menolaknya. Naikkan maxAllowedContentLength dalam web.config, dan semak panduan muat naik fail selamat untuk had di pihak Lucee.

Jadual gejala, punca dan pembetulan

Membaca log IIS dan log Lucee bersama

Apabila permintaan gagal, baca kedua-dua log mengikut urutan. Log IIS berada dalam folder C:\inetpub\logs\LogFiles\W3SVC1 dengan format W3C, dan medan paling penting ialah sc-status, cs-uri-stem dan time-taken. Status dalam log IIS memberitahu anda sejauh mana permintaan itu sampai: 502 bermaksud Lucee tidak menjawab, 404.x bermaksud masalah handler atau peraturan rewrite di pihak IIS, manakala 500 bermaksud permintaan sudah sampai ke Lucee dan Lucee yang gagal.

Log Lucee pula berada dalam folder logs dalam direktori pemasangan Lucee, dengan fail utama exception.log, application.log dan requesttimeout.log. Padankan satu permintaan antara kedua-dua log menggunakan cap masa dan laluan URL, bukan alamat IP, kerana di belakang proksi Lucee selalu melihat 127.0.0.1 sebagai pelanggan. Alamat IP sebenar muncul hanya jika X-Forwarded-For dihantar dan Lucee dikonfigurasi untuk membacanya.

Aliran kerja yang berkesan: semak sc-status dalam log IIS dahulu. Jika 500, buka exception.log dan cari cap masa yang sama untuk tindanan ralat CFML. Jika 404.x, permintaan itu tidak pernah sampai ke Lucee, jadi semak peraturan rewrite dan sekatan ISAPI. Rujuk panduan ralat HTTP 500 untuk diagnosis penuh.

Soalan Lazim (FAQ)

Apakah perbezaan ISAPI redirector dan reverse proxy ARR?

ISAPI redirector ialah DLL asli yang memuatkan ke dalam IIS dan bercakap AJP dengan Tomcat, manakala ARR menggunakan peraturan rewrite untuk menghantar permintaan melalui HTTP biasa. Reverse proxy lebih mudah didebug dan tidak bergantung pada bitness.

Kenapa saya dapat ralat 500.19 selepas menambah web.config?

500.19 dengan kod 0x80070021 bermaksud satu seksyen konfigurasi dikunci di peringkat induk. Jalankan appcmd unlock config untuk seksyen yang dinamakan dalam mesej ralat.

Kenapa sesi Lucee hilang selepas diletakkan di belakang HTTPS?

Biasanya kerana header Host asal tidak dipelihara, jadi kuki sesi dijana dengan hos yang salah, atau kerana skema asal tidak dihantar, jadi Lucee tidak tahu permintaan itu https. Hidupkan preserveHostHeader dan hantar X-Forwarded-Proto.

Berapa had muat naik lalai IIS dan bagaimana menaikkannya?

IIS menghadkan badan permintaan kepada 30 MB secara lalai melalui requestFiltering, dan melebihi had ini menghasilkan 404.13. Naikkan maxAllowedContentLength dalam elemen requestLimits web.config.

Bagaimana memadankan satu permintaan dalam log IIS dan log Lucee?

Gunakan cap masa dan laluan URL sebagai kunci, bukan alamat IP, kerana Lucee melihat 127.0.0.1 di belakang proksi. Semak sc-status dalam log IIS dahulu untuk menentukan lapisan yang gagal.

Sumber

• Configuring the ISAPI redirector for Microsoft IIS, Tomcat Connectors
• Reverse Proxy with URL Rewrite v2 and Application Request Routing, Microsoft Learn
• HTTP Error 500.19 troubleshooting, Microsoft Learn
• ISAPI Filters configuration reference, Microsoft Learn

Senarai semak

• Pasang modul URL Rewrite dan Application Request Routing di IIS.
• Hidupkan proksi ARR dengan appcmd set config -section:system.webServer/proxy.
• Daftarkan HTTP_X_FORWARDED_PROTO dan HTTP_X_FORWARDED_HOST dalam allowedServerVariables.
• Tulis peraturan rewrite yang menghantar semua laluan ke port Lucee.
• Hidupkan preserveHostHeader supaya header Host asal sampai ke Lucee.
• Naikkan maxAllowedContentLength jika aplikasi menerima muat naik besar.
• Pastikan semua trafik pelawat melalui https sebelum menandakan kuki Secure.
• Uji port Lucee terus dengan curl sebelum menyambungkannya ke IIS.
• Sahkan log IIS mencatat status yang dijangkakan, dan log Lucee mencatat pelanggan sebenar melalui X-Forwarded-For.
• Mulakan semula kumpulan aplikasi selepas setiap perubahan konfigurasi.