ServBay 與 Docker 協同運作常見問答集 (FAQ)

在使用 ServBay 進行本機 Web 開發時，您或許會搭配 Docker 使用容器化環境。本 FAQ 旨在解答 ServBay 與 Docker 協同作業時常見的疑問，支援 macOS 和 Windows 平台，包括如何從 Docker 存取 ServBay 服務，以及使用 ServBay 反向代理 Docker 容器內的應用程式。

Q1: 為什麼 ServBay 會修改我系統的 `hosts` 檔案？能否阻止？

ServBay 會在系統的 hosts 檔案中新增條目（如 mysite.servbay.demo 127.0.0.1），讓您可透過自定本機網域（如 mysite.servbay.demo）來存取本機開發中的網站。這些網站實際運作在您主機上的 127.0.0.1 地址。

但由於 Docker 的機制，會從主機系統（macOS 或 Windows）讀取 hosts 檔案，致使 mysite.servbay.demo 解析至 127.0.0.1，造成 Docker 存取到錯誤的（容器自身的）服務。

核心機制：

當您在 ServBay 新增網站並指定網域名稱（如 example.servbay.demo）時，ServBay 會自動將該網域對應到 127.0.0.1。
這是實現本機友善網域存取的標準方式。如果不修改 hosts 檔，您只能用 http://127.0.0.1:PORT 這樣的方式訪問，無法使用自定網域。

可以阻止嗎？

理論上，您可以手動移除 ServBay 新增的 hosts 條目，但這會導致無法用 ServBay 設定的網域連進您的本地網站，這與 ServBay 提供便捷開發體驗的初衷背道而馳。ServBay 其中一項重點功能就是簡化本地網站架設與存取。如果您不希望 ServBay 管理特定網域的 hosts 項目，建議不要在 ServBay 創建該網域的網站。

對多數本機開發場景而言，ServBay 自動管理 hosts 檔案能大幅簡化開發流程，為預期行為。

Q2: 我的 Docker 容器要如何正確透過網域存取 ServBay 主機上的網站（如 `mysite.servbay.demo`）？

這是很常見的需求，但需妥善設置以免發生問題。當 ServBay 在主機（macOS 或 Windows）運行一個網站（比方說 mysite.servbay.demo，解析到主機的 127.0.0.1），Docker 容器內的 127.0.0.1 只會指向容器自己，而非主機。

錯誤作法：直接用 host.docker.internal 作為 URL 主機名稱存取 ServBay 網站

儘管 Docker Desktop for Mac（與 Windows）提供了特殊 DNS 名稱 host.docker.internal，讓容器內可解析主機 IP，但強烈不建議直接在 URL 使用此名稱存取 ServBay 管理的網站（例如，訪問 http://host.docker.internal/ 並期待其解析到 mysite.servbay.demo）。

原因是這樣發出請求時，HTTP 的 Host 標頭會是 host.docker.internal。而 ServBay 的 Web 伺服器（如 Caddy 或 Nginx）是根據 Host 標頭決定網站路由。如果 Host 為 host.docker.internal 而非 mysite.servbay.demo，伺服器將無法正確指向目標網站，且在 HTTPS 情境下會發生 SNI (Server Name Indication) 錯誤，因為 SSL 憑證是為 mysite.servbay.demo 頒發，而不是 host.docker.internal。

正確解法：啟動 Docker 容器時新增 extra_hosts

為了讓 Docker 容器內的程式能用原始網域名稱（如 mysite.servbay.demo）並正確送出 Host 標頭，您需在容器的 /etc/hosts 檔案新增一條該網域指向主機 IP。這可透過 extra_hosts（在 docker-compose.yml）或 --add-host（在使用 docker run）實現，並建議設為指向 host-gateway。

docker run 用法:
bash
```
docker run --add-host=mysite.servbay.demo:host-gateway ... your_image
```
1
（host-gateway 是特殊值，Docker 會替換為主機內部 IP。Docker 20.10+ 通常會使用此值作為 host.docker.internal 的底層別名。）

docker-compose.yml 用法：

yaml

version: '3.8' # 或更新版本
services:
  myapp:
    image: your_image
    extra_hosts:
      - "mysite.servbay.demo:host-gateway" # 或 "mysite.servbay.demo:host.docker.internal"
    # ... 其他設定

設定完成後，在 Docker 容器內：

應用程式若存取 http://mysite.servbay.demo 或 https://mysite.servbay.demo，容器的 /etc/hosts 會將其解析到 macOS 的主機 IP。
請求會發送到主機上的 ServBay 網頁伺服器。
HTTP Host 標頭正確是 mysite.servbay.demo，可讓 ServBay 正確路由請求並提供正確的 SSL 憑證（如使用 HTTPS）。

Q3: Docker 容器如何連線到 ServBay 管理的資料庫（如 MySQL、PostgreSQL）或其他非 HTTP 服務？

與存取網域型網站不同，對連接資料庫或不依賴 SNI 的 TCP 服務來說，建議且有效的作法是用 host.docker.internal 當作服務主機名稱。

步驟：

確保 ServBay 的資料庫套件（或其他服務）已啟動，且設定允許主機連線（通常預設就適合本機開發）。
在 Docker 容器中，設定資料庫連線（或服務連線）時：
- 主機名稱 (Hostname/Server)： 使用 host.docker.internal
- 連接埠 (Port)： 用 ServBay 資料庫（或服務）對應的設定連接埠（如 MySQL 預設 3306，PostgreSQL 為 5432）。
- 帳號/密碼： 用您 ServBay 資料庫（或服務）設定的憑證。

範例（連到 ServBay 管理的 MySQL）： 假設 ServBay 的 MySQL 跑在預設 3306 埠，在 Docker 容器程式中，連線字串設定如下：

主機: host.docker.internal
連接埠: 3306
使用者: your_db_user
密碼: your_db_password

Q4: Docker 容器透過網域（用 `extra_hosts` 設定）存取 ServBay 上的 HTTPS 網站（使用 ServBay User CA 憑證）時，要怎麼讓容器信任該 CA？

假設您已按照 Q2 建議，用 extra_hosts 或 --add-host 方式，將 secure.servbay.demo 指向 host-gateway。若該網站用的是 ServBay User CA 簽發的 SSL 憑證，您的 Docker 容器預設不會信任此 CA，導致 SSL 握手失敗。

ServBay CA 檔案路徑：

ServBay User CA 根憑證：
- macOS： /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
- Windows： C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt
同時包含 ServBay User CA、Public CA 與 Mozilla 根憑證的 PEM 檔：
- macOS (ARM 架構)： /Applications/ServBay/package/common/openssl/3.2/cacert.pem
- macOS (Intel)： /Applications/ServBay/package/common/openssl/1.1.1u/cacert.pem
- Windows： C:\ServBay\package\common\openssl\3.3\cacert.pem

解決方案概述：

有多種方法可讓 Docker 容器信任 ServBay User CA：

方法一：建構階段系統級信任（用 Dockerfile） —— 適合需要整體系統廣泛信任 CA 且可自行設計映像的情境。
方法二：運作階段應用級信任（用掛載映像檔 & 環境變數） —— 用於指定應用信任 CA 或不想修改映像檔的情況。
方法三：運作階段系統級信任（掛載憑證並啟動時更新系統 CA） —— 適合希望在運作階段讓整個容器系統信任CA，但不想自訂映像檔。

方法一：建構階段系統級信任（用 Dockerfile）

此方法是在建構 Docker 映像時，將 CA 憑證整合進系統信任庫。

準備 CA 檔案： 把 ServBay User CA 根憑證複製至 Docker 建構目錄（與 Dockerfile 同層）：
- macOS： /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
- Windows： C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt

Dockerfile 範例（Debian/Ubuntu）：

dockerfile

# 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/*

Dockerfile 範例（Alpine）：

dockerfile

# 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

Docker Compose 建構：

yaml

# docker-compose.yml
version: '3.8'
services:
  myapp:
    build:
      context: ./app_service # 目錄要包含 Dockerfile 及 ServBay-Private-CA-ECC-Root.crt
      dockerfile: Dockerfile
    extra_hosts: ["secure.servbay.demo:host-gateway"]

方法二：運作階段應用級信任（用掛載憑證檔 & 環境變數）

此方法是直接將 CA 憑證檔案掛載到容器，並針對指定應用用環境變數設定 CA 檔路徑。

docker-compose.yml 範例：

yaml

version: '3.8'
services:
  myapp:
    image: some-base-image
    volumes:
      # macOS 路徑
      - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/etc/ssl/certs/MyCustomCA.crt:ro
      # Windows 路徑（請依實際調整路徑）
      # - C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt:/etc/ssl/certs/MyCustomCA.crt:ro
    environment:
      # Node.js 範例:
      - NODE_EXTRA_CA_CERTS=/etc/ssl/certs/MyCustomCA.crt
      # Python (requests) 範例:
      # - REQUESTS_CA_BUNDLE=/etc/ssl/certs/MyCustomCA.crt
      # 泛用:
      # - SSL_CERT_FILE=/etc/ssl/certs/MyCustomCA.crt
    extra_hosts: ["secure.servbay.demo:host-gateway"]

您需查閱您的應用文件以設定正確的環境變數。

方法三：運作階段系統級信任（掛載憑證 & 自訂啟動命令）

此方法結合掛載憑證檔及在容器啟動時執行命令更新系統 CA，無須自訂映像但啟動命令較繁瑣。

docker-compose.yml 範例（Debian/Ubuntu 基底）：

yaml

version: '3.8'
services:
  myapp:
    image: ubuntu:latest # 或其他可用 update-ca-certificates 的映像
    volumes:
      # 主機 CA 憑證直接掛載到系統指定目錄
      # macOS 路徑
      - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
      # Windows 路徑（依系統調整）
      # - C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
    # 覆寫 command，使容器啟動時自動更新憑證後再啟動應用
    # 請確保以 root 或具執行 update-ca-certificates 權限身分啟動
    command: >
      sh -c "
        echo 'Attempting to update CA certificates...' &&
        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 'CA certificates updated.'
        else
          echo 'update-ca-certificates command not found, skipping CA update.'
        fi &&
        echo 'Starting application...' &&
        exec your_original_application_command_here # 請替換為原始啟動命令
      "
    extra_hosts: ["secure.servbay.demo:host-gateway"]
    # 若需 root 權限執行憑證更新但應用預設非 root，可能需要額外 entrypoint 腳本
    # user: root # 可暫時設 root，或用 entrypoint 處理權限

注意：

複雜度：更動 command 或 entrypoint 可能較繁複，尤其官方映像啟動邏輯複雜時，須確保能正確執行原本啟動命令。
權限：update-ca-certificates 常需 root 權限，若容器預設非 root 權限，可能需額外調整。
套件依賴：容器須有 ca-certificates 與 update-ca-certificates 指令，腳本會自動嘗試安裝（適用 apt 系統）。
啟動時間：每次啟動都執行憑證檢查及更新，會延長啟動時間。
Alpine Linux：Alpine 下指令為 apk add --no-cache ca-certificates && update-ca-certificates。

該選哪種方法？

若能自建映像且希望 CA 被系統全面信任，建議用方法一。
若不想修改映像、只需針對特定應用信任 CA，方法二很便利。
若不想自建映像，僅需運作階段系統級信任，選方法三更合適。

公眾 CA 頒發（如 Let's Encrypt）的憑證： 如您的 ServBay 網站用 ACME 拿到公眾 CA（如 Let's Encrypt）憑證，多數 Docker 官方映像預設已信任這些 CA，通常不須額外設定。

Q5: 如何利用 ServBay 為 Docker 容器內的應用設定網域並實現反向代理？

假設您在 Docker 容器中執行了一個應用（如 Node.js 監聽 3000 埠），希望透過 ServBay 設定一個易於記憶的網域（如 myapp.servbay.demo）供主機瀏覽器連線，同時交給 ServBay 管理 SSL 憑證。

步驟：

啟動 Docker 容器，將服務連接埠映射到主機的 127.0.0.1： 確保 Docker 容器將應用埠指向主機（macOS 或 Windows）的一個埠，且綁定在 127.0.0.1，確保該埠僅本機可存取，避免外部直接進入。
bash
```
# 範例：容器服務監聽 3000 埠，映射到主機 127.0.0.1:3001
docker run -d -p 127.0.0.1:3001:3000 your-docker-app-image
```
1
2
此時可透過主機的 http://127.0.0.1:3001 連到應用。
於 ServBay 新增網站並設定反向代理：
- 開啟 ServBay 管理介面。
- 點擊「新增網站」。
- 網域名稱： 例如輸入 myapp.servbay.demo。
- 網站類型： 從下拉選項選擇 「反向代理」。
- IP 位址： 右側欄填入 127.0.0.1。
- 連接埠： 輸入 Docker 映射的主機埠，如 3001。
- 點「儲存」或「新增」。
（可選）設定 SSL： 新增網站後，可進入該網站設定啟用 SSL。ServBay 支援 ACME 協議自動申請 Let's Encrypt 等公眾 CA 憑證，也可選用 ServBay User CA 或 ServBay Public CA。由 ServBay 負責 SSL 終止，ServBay 與 Docker 間連線可採用普通 HTTP（如 http://127.0.0.1:3001）。
測試訪問： 完成 ServBay 設定後，可在瀏覽器用 http://myapp.servbay.demo 或 https://myapp.servbay.demo（如有 SSL）訪問。ServBay 會將請求代理到 Docker 容器應用。

工作流程： 使用者瀏覽器 -> https://myapp.servbay.demo -> ServBay (SSL處理、查詢反向代理規則) -> http://127.0.0.1:3001 (主機埠) -> Docker 容器應用。

小結

ServBay 大幅簡化了 macOS 與 Windows 的本機 Web 開發。結合 Docker 使用時：

Docker 容器要存取 ServBay 管理的網站，請用 extra_hosts 或 --add-host 方式將網域指向 host-gateway，確保 HTTP Host 標頭正確傳送，並避免 SNI 問題。
Docker 容器要連接 ServBay 的資料庫或非 HTTP 服務，請用 host.docker.internal 作為主機名，最單純有效。
要讓 Docker 信任 ServBay User CA 簽發的 SSL 憑證，應將 CA 憑證加入 Docker 映像並更新系統信任庫。
要用 ServBay 反向代理 Docker 容器內的應用，於 ServBay 新增「反向代理」類型網站，目標設為 Docker 映射至主機 127.0.0.1 的埠。

務必確保 ServBay 相關套件（Web 伺服器、資料庫等）與 Docker 容器皆正確設定並在運作中。

ServBay 與 Docker 協同運作常見問答集 (FAQ) ​

Q1: 為什麼 ServBay 會修改我系統的 hosts 檔案？能否阻止？ ​

Q2: 我的 Docker 容器要如何正確透過網域存取 ServBay 主機上的網站（如 mysite.servbay.demo）？ ​

Q3: Docker 容器如何連線到 ServBay 管理的資料庫（如 MySQL、PostgreSQL）或其他非 HTTP 服務？ ​

Q4: Docker 容器透過網域（用 extra_hosts 設定）存取 ServBay 上的 HTTPS 網站（使用 ServBay User CA 憑證）時，要怎麼讓容器信任該 CA？ ​

方法一：建構階段系統級信任（用 Dockerfile） ​

方法二：運作階段應用級信任（用掛載憑證檔 & 環境變數） ​

方法三：運作階段系統級信任（掛載憑證 & 自訂啟動命令） ​

Q5: 如何利用 ServBay 為 Docker 容器內的應用設定網域並實現反向代理？ ​

小結 ​

ServBay 與 Docker 協同運作常見問答集 (FAQ)

Q1: 為什麼 ServBay 會修改我系統的 `hosts` 檔案？能否阻止？

Q2: 我的 Docker 容器要如何正確透過網域存取 ServBay 主機上的網站（如 `mysite.servbay.demo`）？

Q3: Docker 容器如何連線到 ServBay 管理的資料庫（如 MySQL、PostgreSQL）或其他非 HTTP 服務？

Q4: Docker 容器透過網域（用 `extra_hosts` 設定）存取 ServBay 上的 HTTPS 網站（使用 ServBay User CA 憑證）時，要怎麼讓容器信任該 CA？

方法一：建構階段系統級信任（用 Dockerfile）

方法二：運作階段應用級信任（用掛載憑證檔 & 環境變數）

方法三：運作階段系統級信任（掛載憑證 & 自訂啟動命令）

Q5: 如何利用 ServBay 為 Docker 容器內的應用設定網域並實現反向代理？

小結