Lucee Admin API: automasi tetapan melalui API

Lucee Admin API: automasi tetapan melalui API

Lucee Admin API ialah permukaan programatik untuk mengubah tetapan pelayan dan web context tanpa membuka halaman Administrator. Ia bukan satu API tunggal, tetapi tiga laluan yang berkongsi nama tindakan yang sama: tag <cfadmin>, komponen Administrator.cfc, dan titik HTTP di bawah /lucee/admin/. Artikel ini menerangkan apa yang boleh dan tidak boleh dilakukan, cara pengesahan, dan contoh sebenar untuk datasource, caching, dan extension.

Apa yang boleh dan tidak boleh dilakukan

Boleh dilakukan hampir semua yang boleh dibuat melalui antara muka admin: mencipta, mengemas kini dan memadam datasource, mapping, mail server, scheduled task dan extension; membaca senarai setiap satu; mengurus sambungan cache; menukar kata laluan admin; dan memulakan semula enjin. Setiap operasi ini ialah satu tindakan dengan nama seperti updateDatasource, getDatasources, getExtensions dan updateCacheConnection.

Yang tidak boleh dilakukan perlu jelas supaya anda tidak membina jangkaan salah. Pertama, API ini mengurus konfigurasi Lucee, bukan data aplikasi anda. Ia tidak membaca jadual pangkalan data anda. Kedua, tiada kawalan capaian berbutir: sesiapa yang memegang kata laluan admin atau kunci API mendapat kuasa penuh. Ketiga, ini bukan API REST yang didokumenkan lengkap. Sebahagian tindakan didokumenkan rasmi, sebahagian lagi hanya kelihatan dalam kod sumber admin, dan nama tindakan serta parameter berubah antara versi. Semak pada versi yang dipasang sebelum menulis skrip.

Tiga laluan untuk memanggil API

Laluan pertama ialah tag <cfadmin>, yang berjalan di dalam enjin dan mengambil tiga atribut asas: action, type (sama ada web atau server), dan password. Laluan kedua ialah Administrator.cfc, juga di dalam enjin tetapi berorientasikan objek: cipta contoh dengan new Administrator("server", "kata_laluan") kemudian panggil kaedah seperti getDatasources(). Laluan ketiga ialah titik HTTP. Admin Lucee ditulis dalam CFML dan dihidangkan pada /lucee/admin/web.cfm untuk web context dan /lucee/admin/server.cfm untuk server context, boleh dipanggil dari luar melalui curl atau dari dalam aplikasi melalui <cfhttp>.

Jika skrip berjalan di dalam aplikasi Lucee yang sama, gunakan <cfadmin> atau Administrator.cfc, kerana ia tidak memerlukan panggilan rangkaian dan memulangkan nilai terus ke pemboleh ubah CFML. Gunakan titik HTTP apabila skrip berjalan di luar enjin, contohnya dalam pekerjaan CI, skrip shell, atau aplikasi lain yang mengurus pelayan.

Pengesahan: kata laluan dan kunci API

Terdapat dua cara pengesahan. Cara pertama ialah kata laluan admin, yang boleh ditetapkan melalui fail password.txt dalam direktori konteks, pemboleh ubah persekitaran LUCEE_ADMIN_PASSWORD, atau .CFConfig.json dalam bentuk pra-hash dengan kunci hspw dan salt. Tag <cfadmin> dan Administrator.cfc menerima kata laluan ini secara terus.

Cara kedua ialah kunci API. Lucee menyediakan kaedah getAPIKey(), updateAPIKey() dan removeAPIKey() dalam Administrator.cfc, dan medan kunci API boleh ditetapkan dalam admin di bawah bahagian akses. Kunci API membolehkan alat luar memanggil titik HTTP tanpa menghantar kata laluan admin, jadi ia lebih selamat untuk skrip automasi. Tetapan akses umum juga boleh ditetapkan kepada open, protected atau closed: open tidak memerlukan kata laluan, manakala closed melarang akses terus. Satu peringatan yang didokumenkan komuniti: pada Lucee 7, tag <cfadmin> sentiasa melalui semakan kata laluan server admin, jadi access_read dan access_write kepada open tidak semestinya membenarkan kata laluan kosong. Uji gelagat ini pada versi anda.

Mengemas kini datasource

Datasource ialah kes penggunaan paling lazim untuk automasi. Contoh berikut mencipta atau mengemas kini datasource MySQL bernama kedai:

<!--- Panggilan ini memerlukan kata laluan admin yang sudah ditetapkan dalam Lucee Admin. Tanpanya Lucee membalas 'no password is defined for the server context'. --->
<cfadmin
    action="updateDatasource"
    type="server"
    password="KATA_LALUAN_ADMIN"
    classname="com.mysql.cj.jdbc.Driver"
    dsn="jdbc:mysql://localhost:3306/kedai"
    name="kedai"
    newName="kedai"
    host="localhost"
    database="kedai"
    port="3306"
    dbusername="pengguna"
    dbpassword="rahsia"
    blob="false"
    clob="false"
    allowed_select="true"
    allowed_insert="true"
    allowed_update="true"
    allowed_delete="true"
    allowed_alter="false"
    allowed_drop="false"
    allowed_revoke="false"
    allowed_create="false"
    allowed_grant="false"
    verify="false">

Tindakan yang sama wujud dalam Administrator.cfc sebagai updateDatasource(), dengan argumen wajib name, type, newName, host, database, port, username dan password. Nama argumen berbeza sedikit antara tag dan komponen: tag menggunakan dbusername dan dbpassword, komponen menggunakan username dan password. Untuk menyemak sambungan sebelum menyimpan, gunakan verify="true" pada tag atau verifyDatasource() pada komponen. Jika anda mahu menggabungkan tetapan dengan pengurusan konfigurasi versi, lihat CFConfig untuk Lucee, yang boleh mengeksport dan mengimport keseluruhan tetapan sebagai JSON.

Menetapkan tetapan caching

Tetapan caching tidak dikendalikan oleh tag <cfadmin>, tetapi oleh Administrator.cfc, melalui getCacheConnections() untuk menyenaraikan, verifyCacheConnection() untuk menguji, dan updateCacheConnection() untuk mencipta atau mengemas kini sambungan. Contoh berikut menyenaraikan datasource, extension dan sambungan cache, kemudian menguji cache lalai:

admin = new Administrator("server", "KATA_LALUAN_ADMIN");

dsn = admin.getDatasources();
writeDump(dsn);

extensions = admin.getExtensions();
writeDump(extensions);

caches = admin.getCacheConnections();
writeDump(caches);
admin.verifyCacheConnection(name = "default");

updateCacheConnection() memerlukan argumen class dan name, bersama struct custom untuk tetapan khusus penyedia cache. class ialah nama kelas Java pelaksanaan cache, dan nilainya berbeza mengikut penyedia, jadi sahkan nilai ini pada pemasangan anda. Menyenaraikan dan menguji dahulu adalah amalan baik, kerana ia mengesahkan nama dan kelas yang wujud sebelum anda mengubahnya.

Menyenaraikan extension

Untuk melihat extension yang dipasang, gunakan tindakan getExtensions pada tag <cfadmin> dengan atribut returnVariable, atau kaedah getExtensions() pada Administrator.cfc. Komponen ini juga menyediakan getLocalExtensions() dan getServerExtensions() untuk membezakan extension setempat daripada extension peringkat pelayan. Hasilnya ialah query atau struct yang boleh anda gelungkan untuk inventori, audit atau pemeriksaan versi sebelum deploy, satu corak yang sepadan dengan deploy Lucee menggunakan Docker.

Memanggil melalui cfhttp dan curl

Titik HTTP /lucee/admin/web.cfm dan /lucee/admin/server.cfm menerima nama tindakan dan parameter tetapan sebagai pemboleh ubah pertanyaan atau borang. Dari dalam aplikasi, panggil dengan <cfhttp>, dan dari luar dengan curl:

curl -s "http://localhost:8888/lucee/admin/web.cfm?action=getDatasources&api-key=KUNCI_API_ANDA"

Dari dalam aplikasi CFML, panggilan yang sama kelihatan seperti ini:

<cfhttp method="get" url="http://localhost:8888/lucee/admin/web.cfm" result="resp">
    <cfhttpparam type="url" name="action" value="getDatasources">
    <cfhttpparam type="url" name="api-key" value="KUNCI_API_ANDA">
</cfhttp>

Dua perkara perlu diingat. Pertama, respons HTTP ialah output HTML admin itu sendiri, bukan JSON bersih, jadi jangan anggap ia boleh dihuraikan seperti API REST biasa. Untuk pulangan nilai berstruktur, laluan dalam enjin <cfadmin> dengan returnVariable atau Administrator.cfc lebih bersih. Kedua, nama tindakan, parameter dan parameter kunci API berbeza antara versi Lucee. Admin Lucee adalah sumber terbuka, jadi cara paling boleh dipercayai ialah melihat fail CFML admin pada versi yang anda pasang.

Mengendalikan ralat dan kod status

Ralat datang dalam dua bentuk. Dalam enjin, <cfadmin> dan Administrator.cfc melemparkan pengecualian CFML apabila tindakan gagal, contohnya kata laluan salah atau nama tindakan tidak wujud, jadi balut panggilan dalam try dan catch. Melalui HTTP, kod status memberi isyarat jenis kegagalan: akses tidak dibenarkan biasanya 403 atau 401, laluan admin yang disekat 404, dan ralat pelayan 500. Selepas panggilan HTTP, semak cfhttp.statusCode dalam resp sebelum mempercayai kandungannya. Untuk operasi yang mengubah sambungan seperti datasource atau cache, gunakan tindakan verify dahulu supaya anda mengesahkan sambungan berfungsi sebelum menyimpan perubahan kekal.

Jadual tindakan utama

Jadual berikut meringkaskan tindakan yang paling kerap digunakan:

Amaran keselamatan

API ini memberi kuasa penuh, dan pendedahan adalah bencana. Sesiapa yang boleh memanggilnya boleh menukar kata laluan admin, memadam datasource, atau memuat turun konfigurasi sensitif. Hadkan akses kepada localhost atau rangkaian dalaman sahaja. Jangan dedahkan laluan /lucee/admin melalui Traefik, nginx atau mana-mana proksi songsang kepada internet, kerana satu kesilapan konfigurasi proksi sudah cukup untuk membuka keseluruhan pemasangan. Sekat /lucee/admin dan /WEB-INF pada lapisan pelayan web, dan jika pentadbiran tidak diperlukan dalam pengeluaran, matikannya dengan LUCEE_ADMIN_ENABLED=false. Kata laluan admin dan kunci API ialah rahsia: simpan dalam pemboleh ubah persekitaran atau pengurus rahsia seperti dalam panduan mengurus rahsia dalam CFML, dan jangan komit ke repositori. Untuk konteks penuh, baca juga panduan tetapan admin Lucee dan panduan keselamatan web XSS dan CSRF.

Soalan Lazim (FAQ)

Apakah Admin API Lucee itu?

Ia ialah set cara programatik untuk mengubah tetapan Lucee: tag <cfadmin>, komponen Administrator.cfc, dan titik HTTP /lucee/admin/web.cfm serta /lucee/admin/server.cfm. Ketiga-tiganya berkongsi nama tindakan yang sama seperti updateDatasource dan getExtensions.

Apakah perbezaan antara cfadmin dan Administrator.cfc?

Kedua-duanya berjalan di dalam enjin. <cfadmin> ialah tag dengan atribut action, type dan password, manakala Administrator.cfc ialah komponen berorientasikan objek yang anda panggil sebagai kaedah. Administrator.cfc merangkumi tindakan yang tiada dalam tag, contohnya pengurusan cache.

Bagaimana saya mengesahkan panggilan tanpa menghantar kata laluan admin?

Gunakan kunci API. Tetapkan kunci API melalui admin atau updateAPIKey(), kemudian gunakannya pada panggilan HTTP supaya skrip automasi tidak perlu menyimpan kata laluan admin penuh.

Bolehkah saya mendedahkan Admin API ke internet?

Tidak. API ini memberi kuasa penuh ke atas pemasangan anda. Hadkan kepada localhost atau rangkaian dalaman, sekat laluan /lucee/admin dan /WEB-INF pada pelayan web, dan jangan dedahkan melalui Traefik atau nginx.

Bagaimana saya tahu nama tindakan untuk versi Lucee saya?

Nama tindakan dan parameter berubah antara versi, jadi semak fail CFML admin pada versi yang dipasang. Admin Lucee adalah sumber terbuka, jadi kod sumbernya ialah rujukan paling tepat.

Sumber

• CFAdmin documentation - Lucee Documentation
• Configure Lucee within your Application - Lucee Documentation
• Setting the Lucee Admin Password - Lucee Documentation
• Lockdown Guide - Lucee Documentation
• Lucee 7: Admin API with access=open fails - Lucee Dev Forum

Senarai semak keselamatan

1. Akses kepada /lucee/admin dan /WEB-INF disekat pada lapisan pelayan web.
2. Admin API tidak didedahkan melalui Traefik, nginx atau proksi songsang kepada internet.
3. Kata laluan admin kuat dan disimpan dalam pemboleh ubah persekitaran, bukan dalam kod atau repo.
4. Kunci API digunakan untuk skrip automasi dan bukannya kata laluan admin penuh.
5. Admin dimatikan dengan LUCEE_ADMIN_ENABLED=false dalam pengeluaran apabila tidak diperlukan.
6. Nama tindakan dan parameter disemak pada versi Lucee yang dipasang sebelum skrip ditulis.
7. Panggilan HTTP disemak kod statusnya, dan sambungan baharu diuji dengan tindakan verify sebelum disimpan.