設定雲端的虛擬主機

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

使用付費帳戶的 Cloud 客戶可以在機構中建立虛擬主機。

瞭解詳情：

• 關於虛擬主機
• 設定虛擬主機
• 設定 TLS
• KeyStore 和 Truststore

誰可以在 Cloud 中建立及修改虛擬主機

建立及修改虛擬主機的功能僅適用於 Edge Cloud 中的付費帳戶。建立虛擬主機的使用者必須是機構管理員的角色，或是具備修改虛擬主機權限的自訂角色。其他角色的使用者並沒有建立虛擬主機的授權。

舉例來說，付費客戶可以：

• 啟用單向和雙向傳輸層安全標準 (TLS)
• 指定虛擬主機使用的 KeyStore/truststore

免費試用和試用帳戶無法建立或修改虛擬主機，且僅限於在 Edge 註冊時為其建立的虛擬主機。如要進一步瞭解 Edge 定價方案，請參閱 https://apigee.com/api-management/#/pricing。

為 Cloud 設定虛擬主機的需求

下表摘要說明建立虛擬主機的必要條件：

類別	規定	說明
帳戶類型	付費	免費試用和試用版帳戶無法建立或修改虛擬主機。
使用者角色	機構管理員	只有機構管理員可以建立虛擬主機，或是具備有權修改虛擬主機的自訂角色使用者。
虛擬主機數量	最多 20 個	在雲端中，每個機構/環境最多只能有 20 個虛擬主機。 注意事項：私有雲中的虛擬主機沒有數量限制。 大部分的機構/環境會使用兩個虛擬主機：一個用於 HTTP，另一個用於存取 HTTPS。如果機構/環境允許使用其他網域名稱存取，您可能需要使用額外的虛擬主機。
基準網址	包含通訊協定	透過 UI 或 API 定義虛擬主機的基準網址時，你必須在網址中指定通訊協定 (即「http://」或「https://」)。
通訊埠	443	您只能透過通訊埠 443 建立虛擬主機。 請注意，您可以在通訊埠 443 上建立多個虛擬主機，前提是這些主機均有專屬的主機別名，且全都支援 TLS。
使用 TLS 加密的郵件數	必要	您只能建立支援透過 HTTPS 使用傳輸層安全標準 (TLS) 的虛擬主機。您必須已建立 KeyStore，也可以選擇包含傳輸層安全標準 (TLS) 憑證和金鑰的信任儲存庫。 您必須擁有由可信任實體 (例如 Symantec 或 VeriSign) 簽署的憑證。 無法使用自行簽署的憑證。 如果您需要 HTTP 存取權，請與 Apigee Edge 支援團隊聯絡。
TLS 通訊協定	TLS 1.2	Cloud Edge 僅支援傳輸層安全標準 (TLS) 1.2 版。
主機別名	在機構和環境中不重複	其他機構/環境組合沒有主機別名。
網域名稱	客戶擁有	您必須擁有虛擬主機中指定的網域名稱。邊緣檢查可確保如主機別名定義的網域名稱與 TLS 憑證中的中繼資料相符。 具體來說，Edge 會檢查憑證中的下列資訊： CN - 一般名稱 SAN - 主體別名 SAN 或 CN 中可使用萬用字元，例如 *.myco.net。 Edge 也會驗證憑證尚未過期。
用戶端應用程式 SNI 支援	所有存取虛擬主機的用戶端應用程式都必須支援 SNI。	所有應用程式都必須支援 SNI。

使用瀏覽器建立虛擬主機

本節大部分的範例都使用 Edge API 建立或修改虛擬主機，但您可以在 Edge UI 中建立虛擬主機。

如何使用 Edge UI 建立虛擬主機：

1. 登入 apigee.com/edge。
2. 依序選取「Admin」>「Virtual Hosts」。
3. 選取環境，例如 prod 或 test。
4. 選取「+ Virtual Host」即可建立虛擬主機，或選取現有虛擬主機的名稱進行編輯。
5. 如要進一步瞭解如何填入虛擬主機欄位，請參閱上表。

定義單向傳輸層安全標準 (TLS) 的虛擬主機

定義虛擬主機的 XML 物件。舉例來說，下列 XML 物件定義了單向傳輸層安全標準 (TLS) 的虛擬主機：

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>api.myCompany.com</HostAlias> 
    </HostAliases> 
    <Port>443</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>false</ClientAuthEnabled> 
        <KeyStore>ref://myTestKeystoreRef</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
    </SSLInfo>
</VirtualHost>

定義如下：

• 將 name 指定為 myTLSVHost。在 API Proxy 或 API 呼叫中，請使用這個名稱來參照虛擬主機。
• 將「主機別名」指定為 api.myCompany.com。這是公開網域，可讓您依據 DNS 定義和 CNAME 記錄的定義來存取 API。
• 將「port」號碼指定為 443。如果省略，通訊埠會預設為 443。
• 視需要啟用 TLS。
  
  <Enable> 元素設為 true 以啟用單向傳輸層安全標準 (TLS)，而 <KeyStore> 元素會指定傳輸層安全標準 (TLS) 連線使用的 KeyStore 和金鑰別名。
  
  如要啟用雙向傳輸層安全標準 (TLS)，請將 <ClientAuthEnabled> 設為 true，並使用 <TrustStore> 元素指定信任存放區。信任儲存庫保存了用戶端的憑證核發者和憑證的 CA 鏈結，為必要項目。
  
  注意：由於 Edge 原本支援安全資料傳輸層 (SSL)，因此您用來設定 TLS 的標記名稱為 <SSLInfo>。

請注意，您可以在虛擬主機中設定額外屬性。如需所有屬性的參考資料，請參閱虛擬主機屬性參考資料。

決定在虛擬主機中指定 KeyStore 和信任儲存庫名稱的方式

設定支援傳輸層安全標準 (TLS) 的虛擬主機時，必須使用參照來指定 KeyStore。參照是一種包含 KeyStore 或 TrustStore 名稱的變數，而不是直接指定 KeyStore 或信任儲存庫名稱，如下所示：

    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>false</ClientAuthEnabled> 
        <KeyStore>ref://myTestKeystoreRef</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
    </SSLInfo>

使用參照的優點是，您可以變更參照的值來變更虛擬主機使用的 KeyStore，原因通常是因為目前 KeyStore 中的憑證將於近期到期。變更參照值時，不需要重新啟動邊緣路由器。如要進一步瞭解如何建立及修改參照，請參閱「使用參照」。

您只能使用 KeyStore 和 Truststore 的參照，不能使用別名的參照。當您變更 KeyStore 的參照時，請確認憑證的別名名稱與舊的 KeyStore 相同。

使用 KeyStore 和 Truststore 的參照限制

使用 KeyStore 和信任儲存庫的參照時，必須考量下列限制：

• 您必須支援 SNI，並在 Apigee 路由器上終止 SSL，才能在虛擬主機中使用 KeyStore 和 Truststore 參照。
• 如果 Apigee 路由器前方有負載平衡器，且您在負載平衡器上終止 TLS，您就無法在虛擬主機中使用 KeyStore 和 Truststore 參照。

定義雙向傳輸層安全標準 (TLS) 的虛擬主機

如要啟用雙向傳輸層安全標準 (TLS)，請將 <ClientAuthEnabled> 元素設為 true，並使用搭配 <TrustStore> 元素的參照來指定信任儲存庫。信任儲存庫保存了用戶端的憑證核發者和憑證的 CA 鏈結，為必要項目。用戶端也必須正確設定，才能使用雙向傳輸層安全標準 (TLS)。

如要建立適用於雙向傳輸層安全標準 (TLS) 的虛擬主機，請建立用於定義虛擬主機的 XML 物件：

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>api.myCompany.com</HostAlias> 
    </HostAliases> 
    <Port>443</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>true</ClientAuthEnabled> 
        <KeyStore>ref://myTestKeystoreRef</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
        <TrustStore>ref://myTestTruststoreRef</TrustStore> 
    </SSLInfo>
</VirtualHost>

定義如下：

• 將 <ClientAuthEnabled> 設為 true，即可啟用雙向傳輸層安全標準 (TLS)。
• 使用 <TrustStore> 元素指定信任儲存庫的參照。信任儲存庫保存了用戶端的憑證核發者和憑證的 CA 鏈結，為必要項目。

定義使用 Apigee 免費試用憑證和金鑰的虛擬主機

如果您有 Cloud Edge for Cloud 帳戶，但尚未取得 TLS 憑證和金鑰，您可以建立使用 Apigee 免費試用憑證和金鑰的虛擬主機。也就是說，您不必先建立 KeyStore，就能建立虛擬主機。

已為「*.apigee.net」網域定義 Apigee 免費試用憑證。因此，虛擬主機的 <HostAlias> 也必須採用 *.apigee.net 的形式。

如果您正在執行雙向傳輸層安全標準 (TLS)，仍須將 <ClientAuthEnabled> 元素設為 true，並使用帶有 <TrustStore> 元素的參照來指定信任商店，詳情請參閱上文「定義雙向傳輸層安全標準 (TLS) 的虛擬主機」一節。

使用 Apigee 免費試用憑證和金鑰定義虛擬主機的 XML 物件會省略 <KeyStore> 和 <KeyAlias> 元素，並替換成 <UseBuiltInFreeTrialCert> 元素，如下所示：

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>myapi.apigee.net</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
    </SSLInfo>
    <UseBuiltInFreeTrialCert>true</UseBuiltInFreeTrialCert>
</VirtualHost>

<UseBuiltInFreeTrialCert> 元素的預設值為 false。

針對雙向 TLS，請將虛擬主機定義為：

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>myapi.apigee.net</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <TrustStore>ref://myTestTruststoreRef</TrustStore>
    </SSLInfo>
    <UseBuiltInFreeTrialCert>true</UseBuiltInFreeTrialCert>
</VirtualHost>

在 Edge UI 中，在建立虛擬主機時選取「使用內建的免費試用憑證」選項，即可使用免費的 Apigee 憑證和金鑰：

建立虛擬主機

請按照下列程序建立虛擬主機：

1. 為公開網域api.myCompany.com建立 DNS 項目和 CNAME 記錄，並指向 [org]-[environment].apigee.net。
2. 按照以下所述的程序，建立及設定在這個例子中名為 myTestKeystore 的 KeyStore： 使用 Edge UI 建立 KeyStore 和 Truststore。在這個範例中，請確認 KeyStore 針對憑證和私密金鑰使用 myKeyAlias 的別名名稱。
3. 將憑證和金鑰上傳至 KeyStore。請確保憑證指定的網域名稱與要用於虛擬主機的主機別名相符。

4. 使用 Edge UI 或 API 建立 KeyStore 的參照。參考資料將 KeyStore 名稱和參照類型指定為 KeyStore。如要進一步瞭解如何建立及修改參照，請參閱「使用參照」。

5. 使用 Create a Virtual Host API 建立虛擬主機。請務必指定正確的 KeyStore 參照和金鑰別名。如要使用 API，請使用下列 POST API 呼叫建立名為 myTLSVHost 的 KeyStore：

   curl -X POST -H "Content-Type:application/xml" \
     https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts \
     -d '<VirtualHost name="myTLSVHost">
       <HostAliases>
         <HostAlias>api.myCompany.com</HostAlias>
       </HostAliases>
       <Port>443</Port>
       <SSLInfo>
         <Enabled>true</Enabled>
         <ClientAuthEnabled>false</ClientAuthEnabled>
         <KeyStore>ref://myTestKeystoreRef</KeyStore>
         <KeyAlias>myKeyAlias</KeyAlias>
       </SSLInfo>
     </VirtualHost>' \
     -u orgAdminEmail:password

   如要透過用戶端執行雙向傳輸層安全標準 (TLS)，請將 <ClientAuthEnabled> 設為 true，並使用 <TrustStore> 元素指定信任存放區。用戶端必須正確設定雙向傳輸層安全標準 (TLS)，也就是說，Edge 的信任儲存庫含有用戶端的憑證核發者和憑證鏈結。按照以下流程建立信任存放區： 使用 Edge UI 建立 KeyStore 和 Truststore。

6. 如果您有現有的 API Proxy，請將虛擬主機新增至 Proxy 端點的 <HTTPConnection> 元素。系統會自動將虛擬主機新增至所有新的 API Proxy。 請參閱 設定 API Proxy 以使用虛擬主機。

將 API Proxy 更新為使用虛擬主機，並為主機別名建立 DNS 項目和 CNAME 記錄後，您可以存取 API Proxy，如下所示：

https://api.myCompany.com/v1/{project-base-path}/{resource-path}

例如：

https://api.myCompany.com/v1/weather/forecastrss?w=12797282

修改虛擬主機

付費 Cloud 客戶會執行兩項主要工作來修改現有的虛擬主機：

1. 修改 KeyStore 或 Truststore 的參照值。
   
   注意：設定 <KeyStore> 或 <TrustStore> 使用參照後，您隨時可以變更參照的值。不過，如果您想變更 <KeyStore> 或 <TrustStore> 以採用其他參照，或是將 <KeyAlias> 變更為使用其他別名，請與 Apigee Edge 支援團隊聯絡。
2. 修改虛擬主機的 TLS 屬性。

修改參照的值

您可以修改參照的值，變更虛擬主機使用的 KeyStore 或 Truststore。

修改參照值之前：

1. 按照 使用 Edge UI 建立 KeyStore 和 TrustStore 的說明，建立新的 KeyStore 並上傳憑證和金鑰。在新的 KeyStore 中，確保金鑰別名的名稱與現有金鑰庫使用的名稱相同。
2. 如有必要，請依據「 使用 Edge UI 建立 KeyStore 和 Truststore」的說明，建立新的信任儲存庫並上傳憑證。
3. 按照「使用參照」一節的說明修改參照。

修改虛擬主機的 TLS 屬性

付費客戶可以使用 更新虛擬主機 API 來更新虛擬主機。這個 API 可讓您設定虛擬主機的所有屬性，相關說明請參閱虛擬主機屬性參考資料。

修改虛擬主機時，Edge 會執行與建立虛擬主機時類似的驗證。也就是說，當您修改時，Edge 會驗證以下內容：

• 主機別名指定的網域並未用於其他機構和環境。
• 您擁有這個網域名稱。具體來說，Edge 會檢查憑證中的下列資訊是否與主機別名相符：
  • CN - 一般名稱
  • SAN - 主體別名
  • Edge 會驗證憑證尚未過期。

如要使用 Edge API 修改虛擬主機，請執行下列操作：

1. 使用 更新虛擬主機 API 更新虛擬主機。使用 API 時，您必須在要求主體中指定虛擬主機的完整定義，而不只是您要變更的元素。在這個範例中，您會設定 proxy_read_timeout 屬性的值：

   curl -X PUT -H "Content-Type:application/xml" \
     https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts/{vhost_name} \
     -d '<VirtualHost name="myTLSVHost">
       <HostAliases>
         <HostAlias>api.myCompany.com</HostAlias>
       </HostAliases>
       <Port>443</Port>
       <SSLInfo>
         <Enabled>true</Enabled>
         <ClientAuthEnabled>false</ClientAuthEnabled>
         <KeyStore>ref://myTestKeystoreRef</KeyStore>
         <KeyAlias>myKeyAlias</KeyAlias>
       </SSLInfo>
       <Properties>
          <Property name="proxy_read_timeout">50</Property>
            </Properties>
     </VirtualHost>' \
     -u orgAdminEmail:password

修改虛擬主機，以使用 KeyStore 和 Truststore 的參照

Cloud 中的所有新的 Edge 虛擬主機都會使用 KeyStore 和 Truststore 的參照。 參照可讓您變更 KeyStore 和信任儲存庫，而不必與 Apigee Edge 支援團隊聯絡。

Apigee Edge 中的舊版虛擬主機可能未設為使用 KeyStore 和信任存放區的參照。在此情況下，您可以將虛擬主機更新為使用參照。

更新虛擬主機以使用參照

請按照下列程序更新虛擬主機：

1. 如有需要，請建立新的 KeyStore 並上傳憑證，如 使用 Edge UI 建立 KeyStore 和 Truststore。如果您已經有 KeyStore，可以設定指向該 KeyStore 的參照。
2. 建立 KeyStore 的新參照。
3. 如有需要，請建立新的信任儲存庫並上傳憑證。如果您已經有信任儲存庫，可以設定指向該信任儲存庫的參照。
4. 建立信任儲存庫的新參照。
5. 更新虛擬主機以設定 KeyStore、別名、Truststore 和其他任何傳輸層安全標準 (TLS) 屬性。呼叫的酬載為：

   curl -X PUT -H "Content-Type:application/xml" \
     https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts/{vhost_name} \
     -d '<VirtualHost  name="myTLSVHost">
           <HostAliases>
             <HostAlias>api.myCompany.com</HostAlias>
           </HostAliases>
           <Port>443</Port>
           <OCSPStapling>off</OCSPStapling>
           <SSLInfo>
             <Enabled>true</Enabled>
             <ClientAuthEnabled>true</ClientAuthEnabled>
             <KeyStore>ref://myKeyStore2Way</KeyStore>
             <KeyAlias>keyAlias</KeyAlias>
             <TrustStore>ref://myTrustStore2Way</TrustStore>
             <IgnoreValidationErrors>false</IgnoreValidationErrors>
           </SSLInfo>
         </VirtualHost>' \
       -u orgAdminEmail:pWord

6. 請與 Apigee 支援團隊聯絡，重新啟動 Edge Router 來完成這項程序。