Soalan Lazim (FAQ) Mengenai Kerjasama ServBay & Docker

Semasa menggunakan ServBay untuk pembangunan web tempatan, anda mungkin ingin menggabungkannya dengan Docker bagi mencipta persekitaran berasaskan kontena. FAQ ini direka untuk menjawab beberapa persoalan biasa yang mungkin timbul apabila menggunakan ServBay bersama Docker, khususnya di macOS, termasuk cara mengakses servis ServBay daripada Docker dan penggunaan proksi songsang ServBay untuk aplikasi dalam kontena.

S1: Kenapa ServBay mengubah fail hosts sistem saya? Bolehkah saya menghalangnya?

ServBay menambah entri ke dalam fail hosts sistem anda (cth. mysite.servbay.demo 127.0.0.1) supaya anda boleh mengakses laman pembangunan tempatan menggunakan nama domain tersuai seperti mysite.servbay.demo. Laman ini sebenarnya beroperasi pada alamat 127.0.0.1 mesin anda.

Namun, disebabkan ciri Docker, fail hosts daripada host macOS akan dibaca, menyebabkan mysite.servbay.demo diselesaikan kepada 127.0.0.1, sekali gus Docker akan mengakses servis dalam kontena sendiri secara salah.

Mekanisme utama:

• Apabila anda mencipta laman baru di ServBay dan tetapkan domain (seperti example.servbay.demo), ServBay secara automatik menetapkan domain itu ke 127.0.0.1.
• Ini adalah kaedah standard untuk membolehkan akses ke domain mesra tempatan. Jika tidak menambah entri ke fail hosts, anda hanya boleh akses menggunakan format seperti http://127.0.0.1:PORT dan tidak akan dapat menggunakan domain tersuai.

Bolehkah dihalang?

Secara teori, anda boleh membuang entri yang ditambah ServBay secara manual, tetapi ini menyebabkan anda tidak boleh melayari laman tempatan menggunakan domain yang ditetapkan ServBay, bertentangan dengan matlamat utama ServBay untuk memudahkan pembangunan tempatan. Salah satu ciri utama ServBay ialah mempermudah penciptaan dan akses laman web tempatan. Jika anda tidak ingin ServBay mengurus entri hosts untuk domain tertentu, sebaiknya jangan cipta laman dengan domain itu di dalam ServBay.

Untuk kebanyakan kes pembangunan tempatan, pengurusan automatik fail hosts oleh ServBay adalah ciri yang diingini untuk mengurangkan kerumitan pembangunan.

S2: Bagaimana kontena Docker saya boleh mengakses laman web diurus oleh ServBay pada macOS host menggunakan domain (cth. mysite.servbay.demo)?

Ini adalah keperluan umum, tetapi perlu dikonfigurasikan dengan betul untuk mengelakkan masalah. Bila ServBay menjalankan laman web pada host macOS anda (cth. mysite.servbay.demo yang diselesaikan ke 127.0.0.1), 127.0.0.1 dalam kontena Docker merujuk kepada kontena itu sendiri, bukan host macOS anda.

Kaedah SALAH: Mengakses laman ServBay menggunakan host.docker.internal terus di URL

Walaupun Docker Desktop for Mac (dan Windows) menyediakan nama DNS khas host.docker.internal supaya kontena dapat mengenalpasti IP host, kami TIDAK MENGGALAKKAN anda menggunakannya secara langsung dalam URL apabila mengakses laman web yang dihoskan oleh ServBay (cth. mengakses http://host.docker.internal/ dan mengharapkan ia membawa ke mysite.servbay.demo).

Ini kerana, apabila anda berbuat demikian, medan Host dalam header HTTP yang dihantar ke pelayan web ServBay (seperti Caddy atau Nginx) akan menjadi host.docker.internal. Pelayan web ServBay menggunakan header Host tersebut untuk menentukan laman mana yang hendak dihidangkan. Jika Host ialah host.docker.internal dan bukannya mysite.servbay.demo, pelayan web tidak dapat merutekan permintaan dengan betul, atau untuk HTTPS, Ralat SNI (Server Name Indication) akan berlaku kerana sijil SSL adalah untuk mysite.servbay.demo bukan untuk host.docker.internal.

Penyelesaian BETUL: Tambahkan extra_hosts semasa permulaan kontena

Supaya aplikasi dalam kontena Docker dapat mengakses domain asal laman ServBay (cth. mysite.servbay.demo) dengan header Host yang betul, anda perlu menambah entri ke fail /etc/hosts kontena yang memetakan domain tersebut ke IP host. Ia boleh dilakukan dengan extra_hosts (dalam docker-compose.yml) atau --add-host (semasa docker run), dan domain itu harus dipetakan ke host.docker.internal atau, lebih disyorkan, host-gateway.

• Menggunakan docker run:

  docker run --add-host=mysite.servbay.demo:host-gateway ... your_image

  (host-gateway ialah nilai khas, Docker akan menggantikannya dengan IP dalaman host. Pada Docker 20.10+, ini biasanya merupakan alias peringkat rendah untuk host.docker.internal.)

• Menggunakan docker-compose.yml:

  version: '3.8' # atau lebih tinggi
  services:
    myapp:
      image: your_image
      extra_hosts:
        - "mysite.servbay.demo:host-gateway" # atau "mysite.servbay.demo:host.docker.internal"
      # ... konfigurasi lain

Selepas konfigurasi, dalam kontena Docker anda:

1. Bila aplikasi cuba mengakses http://mysite.servbay.demo atau https://mysite.servbay.demo, fail /etc/hosts kontena akan menyelesaikan mysite.servbay.demo ke IP host macOS.
2. Permintaan akan dihantar ke pelayan web ServBay di host.
3. Header HTTP Host akan menjadi mysite.servbay.demo, membolehkan ServBay merutekan permintaan dengan betul dan menyediakan sijil SSL yang tepat (jika gunakan HTTPS).

S3: Bagaimana kontena Docker saya boleh bersambung ke pangkalan data (seperti MySQL, PostgreSQL) atau perkhidmatan bukan HTTP yang dikendalikan oleh ServBay?

Untuk servis TCP seperti pangkalan data yang tidak bergantung pada SNI, penggunaan host.docker.internal sebagai nama host perkhidmatan adalah cara yang disyorkan dan berkesan.

Langkah-langkah:

1. Pastikan pakej pangkalan data (atau servis lain) ServBay telah dijalankan dan diatur untuk menerima sambungan dari host (biasanya konfigurasi lalai sudah mencukupi untuk pembangunan tempatan).
2. Dalam kontena Docker anda, ketika menetapkan sambungan ke pangkalan data:
   • Hostname/Server: Gunakan host.docker.internal.
   • Port: Gunakan port yang ServBay tetapkan untuk pangkalan data tersebut (cth. MySQL lalai 3306, PostgreSQL lalai 5432).
   • Nama pengguna/Kata laluan: Gunakan maklumat log masuk yang telah anda setkan dalam ServBay.

Contoh (Sambungan ke MySQL ServBay): Jika MySQL di ServBay berjalan di port lalai 3306, konfigurasi dalam aplikasi kontena boleh seperti berikut:

• Host: host.docker.internal
• Port: 3306
• User: your_db_user
• Password: your_db_password

S4: Bagaimana membuatkan kontena Docker mempercayai sijil SSL yang dikeluarkan oleh ServBay User CA apabila mengakses laman HTTPS (menggunakan konfigurasi domain dengan extra_hosts)?

Jika, sebagaimana disyorkan dalam S2, anda telah memetakan secure.servbay.demo ke host-gateway menggunakan extra_hosts atau --add-host, dan secure.servbay.demo menggunakan sijil SSL yang dikeluarkan oleh ServBay User CA, kontena Docker anda secara lalai tidak percaya pada CA ini dan ini boleh menyebabkan kegagalan sambungan SSL.

Lokasi fail CA ServBay (di host macOS):

• Sijil akar ServBay User CA: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
• Fail PEM mengandungi ServBay User CA, Public CA dan akar Mozilla:
  • Mac ARM: /Applications/ServBay/package/common/openssl/3.2/cacert.pem
  • Mac Intel: /Applications/ServBay/package/common/openssl/1.1.1u/cacert.pem

Penyelesaian secara umum:

Terdapat beberapa kaedah untuk membuat kontena Docker mempercayai ServBay User CA:

1. Kaedah 1: Percaya sistemik pada masa binaan (melalui Dockerfile) - Disyorkan jika anda boleh ubah suai imej.
2. Kaedah 2: Percaya peringkat aplikasi pada masa jalan (melalui volume mount & env) - Untuk aplikasi tertentu tanpa perlu bina semula imej.
3. Kaedah 3: Percaya sistem pada masa jalan (volume mount & command custom) - Untuk sistem secara keseluruhan pada masa larian tanpa membina imej sendiri.

Kaedah 1: Percaya sistemik pada masa binaan (melalui Dockerfile)

Kaedah ini mengintegrasikan sijil CA ke dalam stor kepercayaan sistem semasa pembangunan imej Docker.

• Sediakan fail CA: Salin /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt ke direktori konteks binaan Docker anda (bersama Dockerfile).
• Contoh Dockerfile (Debian/Ubuntu):

  # Dockerfile
  FROM ubuntu:latest
  COPY ServBay-Private-CA-ECC-Root.crt /usr/local/share/ca-certificates/ServBay-User-CA.crt
  RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && \
      update-ca-certificates && \
      rm -rf /var/lib/apt/lists/*

• Contoh Dockerfile (Alpine):

  # Dockerfile
  FROM alpine:latest
  COPY ServBay-Private-CA-ECC-Root.crt /usr/local/share/ca-certificates/ServBay-User-CA.crt
  RUN apk add --no-cache ca-certificates && update-ca-certificates

• Kompos Docker:

  # docker-compose.yml
  version: '3.8'
  services:
    myapp:
      build:
        context: ./app_service # folder mengandungi Dockerfile & ServBay-Private-CA-ECC-Root.crt
        dockerfile: Dockerfile
      extra_hosts: ["secure.servbay.demo:host-gateway"]

Kaedah 2: Percaya peringkat aplikasi pada masa jalan (mount volume & env)

Kaedah ini mount fail CA ke dalam kontena dan menggunakan pemboleh ubah persekitaran untuk aplikasi mengikuti CA tersebut.

• Contoh docker-compose.yml:

  version: '3.8'
  services:
    myapp:
      image: some-base-image
      volumes:
        - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/etc/ssl/certs/MyCustomCA.crt:ro
      environment:
        # Contoh untuk Node.js:
        - NODE_EXTRA_CA_CERTS=/etc/ssl/certs/MyCustomCA.crt
        # Contoh untuk Python (requests):
        # - REQUESTS_CA_BUNDLE=/etc/ssl/certs/MyCustomCA.crt
        # Contoh untuk generic SSL_CERT_FILE:
        # - SSL_CERT_FILE=/etc/ssl/certs/MyCustomCA.crt
      extra_hosts: ["secure.servbay.demo:host-gateway"]

  Sila rujuk dokumentasi aplikasi untuk pemboleh ubah persekitaran yang betul.

Kaedah 3: Percaya sistem pada masa jalan (mount volume & command custom)

Kaedah ini gabungkan mount volume dengan arahan permulaan untuk mengemaskini stor CA sistem, tanpa perlu membina imej tersuai. Walaubagaimanapun, mula arahan container mungkin lebih kompleks.

• Contoh docker-compose.yml (imej berasaskan Debian/Ubuntu):

  version: '3.8'
  services:
    myapp:
      image: ubuntu:latest # atau lain-lain yang menyokong update-ca-certificates
      volumes:
        - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
      command: >
        sh -c "
          echo 'Cuba mengemaskini sijil CA...' &&
          if command -v update-ca-certificates > /dev/null; then
            if [ ! -f /usr/bin/update-ca-certificates ]; then apt-get update && apt-get install -y --no-install-recommends ca-certificates; fi &&
            update-ca-certificates &&
            echo 'Sijil CA dikemaskini.'
          else
            echo 'Perintah update-ca-certificates tiada, CA tidak dikemaskini.'
          fi &&
          echo 'Memulakan aplikasi...' &&
          exec your_original_application_command_here # Ganti dengan CMD asal
        "
      extra_hosts: ["secure.servbay.demo:host-gateway"]
      # Jika perlu jalan sebagai root untuk update CA:
      # user: root # Atau atur entrypoint untuk pengurusan hak

  Perhatian:
  • Kompleksiti: Mengubah command atau entrypoint boleh jadi rumit, terutamanya untuk imej rasmi dengan logik permulaan kompleks. Pastikan arahan aplikasi asal dijalankan.
  • Akses: update-ca-certificates biasanya perlu hak root. Jika kontena berjalan sebagai user bukan root, kaedah ini mungkin gagal atau perlu tambahan hak.
  • Dependensi pakej: Imej perlu ada pakej ca-certificates dan perintah update-ca-certificates (contoh cuba memasang automatik jika tiada).
  • Masa permulaan: Pemeriksaan dan pemasangan semula setiap permulaan kontena boleh memanjangkan masa boot.
  • Alpine: Untuk Alpine, gunakan arahan apk add --no-cache ca-certificates && update-ca-certificates.

Pilihan kaedah:

• Jika anda boleh bina imej tersuai dan mahu CA dipercayai meluas, Kaedah 1 adalah terbaik.
• Jika tidak mahu ubah imej dan hanya aplikasi tertentu perlu percaya CA, Kaedah 2 sangat mudah.
• Jika tidak mahu bina imej, perubahan sistem minimal dan mahu CA dipercayai sistemik semasa larian, Kaedah 3 sesuai.

Untuk sijil yang dikeluarkan oleh CA umum (seperti Let's Encrypt): Jika laman ServBay anda menggunakan sijil diperolehi melalui ACME dari CA awam seperti Let's Encrypt, kebanyakan imej Docker asas sudah memercayai CA ini dan tiada langkah tambahan diperlukan.

S5: Bagaimana menggunakan ServBay untuk menetapkan domain dan proksi songsang bagi aplikasi dalam kontena Docker?

Anda mungkin menjalankan aplikasi dalam Docker (mis. perkhidmatan Node.js mendengar pada port 3000 dalam kontena) dan mahu menetapkan domain mesra pengguna (cth. myapp.servbay.demo) serta mengaksesnya menerusi pelayar di mesin host sambil menggunakan pengurusan SSL oleh ServBay.

Langkah-langkah:

1. Jalankan kontena Docker dan petakan port ke 127.0.0.1 tuan rumah: Pastikan kontena Docker anda memetakan port aplikasi ke IP 127.0.0.1 pada host macOS anda supaya hanya boleh diakses secara tempatan — ini penting untuk sekuriti.

   # Contoh: Aplikasi dengar pada 3000, petakan ke host 127.0.0.1:3001
   docker run -d -p 127.0.0.1:3001:3000 your-docker-app-image

   Sekarang aplikasi dalam kontena boleh diakses di host melalui http://127.0.0.1:3001.

2. Tambah laman baharu dalam ServBay dan tetapkan proksi songsang:

   • Buka antara muka pengurusan ServBay.
   • Klik "Tambah Laman" / "Add Website".
   • Domain: Masukkan domain, cth. myapp.servbay.demo.
   • Jenis laman: Pilih "Proksi Songsang" daripada pilihan.
   • Alamat IP: Isikan 127.0.0.1.
   • Port: Masukkan port yang kontena Docker petakan ke host, cth. 3001.
   • Klik "Simpan" atau "Tambah".

3. (Pilihan) Tetapkan SSL: Setelah laman ditambah, anda boleh ke tetapan laman untuk mengaktifkan SSL. ServBay menyokong permohonan automatik sijil daripada Let's Encrypt atau anda boleh pilih guna ServBay User CA atau ServBay Public CA. ServBay akan mengurus penghentian SSL, dan sambungan antara ServBay ke kontena Docker hanya perlu HTTP (cth. http://127.0.0.1:3001).

4. Uji akses: Selepas konfigurasi ServBay siap, anda boleh akses melalui browser ke http://myapp.servbay.demo atau https://myapp.servbay.demo (jika SSL diaktifkan). ServBay akan memproksi permintaan ke aplikasi dalam kontena Docker.

Aliran Kerja: Pelayar pengguna -> https://myapp.servbay.demo -> ServBay (urus SSL, rujuk aturan proksi songsang) -> http://127.0.0.1:3001 (host) -> aplikasi dalam kontena Docker.

Ringkasan

ServBay sangat memudahkan pembangunan web tempatan di macOS. Bila digabung dengan Docker:

• Untuk akses laman web dihoskan ServBay daripada Docker, gunakan extra_hosts atau --add-host untuk memetakan domain ke host-gateway, supaya header Host betul dan mengelakkan isu SNI.
• Untuk akses pangkalan data atau servis bukan HTTP, gunakan host.docker.internal sebagai nama hos pelayan untuk kesederhanaan dan keberkesanan.
• Untuk membolehkan kontena Docker mempercayai SSL yang dikeluarkan oleh ServBay User CA, salin sijil CA ke imej Docker dan kemas kini stor kepercayaan.
• Untuk menggunakan proksi songsang ServBay bagi aplikasi dalam kontena Docker, pilih jenis laman "Proksi Songsang" di ServBay dan isi port host yang dipetakan oleh Docker ke 127.0.0.1.

Sentiasa pastikan servis berkaitan dalam ServBay (pelayan web, pangkalan data, dll.) dan kontena Docker anda dikonfigurasi dan dijalankan dengan betul.