設定 Dispatcher configuring-dispatcher

以下幾節將說明如何設定 Dispatcher 的各個層面。

對 IPv4 和 IPv6 的支援 support-for-ipv-and-ipv

AEM 和 Dispatcher 的所有元素都可以安裝在 IPv4 和 IPv6 網路上。請參閱 IPV4 和 IPV6。

Dispatcher 設定檔案 dispatcher-configuration-files

根據預設，Dispatcher 設定會儲存在 dispatcher.any 文字檔中，但是您在安裝期間可以變更此檔案的名稱和位置。

此設定檔案包含一系列的單一值或多值屬性，這些屬性用來控制 Dispatcher 的行為：

範例設定的結構如下所示：

# name of the dispatcher
/name "internet-server"

# each farm configures a set off (loadbalanced) renders
/farms
 {
  # first farm entry (label is not important, just for your convenience)
   /website
     {
     /clientheaders
       {
       # List of headers that are passed on
       }
     /virtualhosts
       {
       # List of URLs for this Web site
       }
     /sessionmanagement
       {
       # settings for user authentification
       }
     /renders
       {
       # List of AEM instances that render the documents
       }
     /filter
       {
       # List of filters
       }
     /vanity_urls
       {
       # List of vanity URLs
       }
     /cache
       {
       # Cache configuration
       /rules
         {
         # List of cachable documents
         }
       /invalidate
         {
         # List of auto-invalidated documents
         }
       }
     /statistics
       {
       /categories
         {
         # The document categories that are used for load balancing estimates
         }
       }
     /stickyConnectionsFor "/myFolder"
     /health_check
       {
       # Page gets contacted when an instance returns a 500
       }
     /retryDelay "1"
     /numberOfRetries "5"
     /unavailablePenalty "1"
     /failover "1"
     }
 }

您可以包含有助於設定的其他檔案：

例如，若要在 /farms 設定中包含 myFarm.any 檔案，請使用以下程式碼：

/farms
  {
  $include "myFarm.any"
  }

要指定要包含的檔案範圍，請使用星號 (*) 作為萬用字元。

例如，如果檔案 farm_1.any 到 farm_5.any 包含陣列一到五的設定，您可依照以下方式來包含這些陣列：

/farms
  {
  $include "farm_*.any"
  }

使用環境變數 using-environment-variables

您可以在 dispatcher.any 檔案中的字串-值屬性內使用環境變數，而不是以硬式編碼方式編寫這些值。若要包含環境變數的值，請使用 ${variable_name} 格式。

例如，如果 dispatcher.any 檔案位於與快取目錄相同的目錄中，則可以針對 docroot 屬性使用下列值：

/docroot "${PWD}/cache"

還有另一個範例，如果您建立名為 PUBLISH_IP 的環境變數來儲存 AEM Publish 執行個體的主機名稱，則可以使用以下的 /renders 屬性設定：

/renders {
  /0001 {
    /hostname "${PUBLISH_IP}"
    /port "8443"
  }
}

為 Dispatcher 執行個體命名 naming-the-dispatcher-instance-name

使用 /name 屬性可指定唯一名稱來識別您的 Dispatcher 執行個體。/name 屬性是設定結構中的最上層屬性。

定義陣列 defining-farms-farms

/farms 屬性可定義一組或多組 Dispatcher 行為，每一組行為會與不同網站或 URL 有關聯。/farms 屬性可以包含單一陣列或多個陣列：

/farms 屬性是設定結構中的最上層屬性。若要定義陣列，請在 /farms 屬性中新增子屬性。使用在 Dispatcher 執行個體中可唯一識別陣列的屬性名稱。

/farmname 屬性是多值屬性，而且包含可定義 Dispatcher 行為的其他屬性：

值可包含任何英數 (a-z、0-9) 字元。以下範例說明名為 /daycom 和 /docsdaycom 的兩個陣列的骨架定義：

#name of dispatcher
/name "day sites"

#farms section defines a list of farms or sites
/farms
{
   /daycom
   {
       ...
   }
   /docdaycom
   {
      ...
   }
}

每個陣列屬性都可包含以下子屬性：

指定預設頁面 (僅限 IIS) - /homepage specify-a-default-page-iis-only-homepage

指定要傳遞的 HTTP 標題 specifying-the-http-headers-to-pass-through-clientheaders

/clientheaders 屬性會定義 Dispatcher 從用戶端 HTTP 請求傳送給轉譯器 (AEM 執行個體) 的 HTTP 標題清單。

Dispatcher 預設會將標準 HTTP 標題轉送給 AEM 執行個體。在某些情況下，您可能會想要轉送其他標題或移除特定標題：

如果您自訂要傳遞的標頭組合，則必須指定詳盡的標頭清單，包括通常在預設情況下包含的該些標頭。

例如，為發佈執行個體處理頁面啟用請求的 Dispatcher 執行個體需要 /clientheaders 區段中的 PATH 標題。PATH 標頭會啟用複寫代理程式與 Dispatcher 之間的通訊。

以下程式碼為 /clientheaders 的設定範例：

/clientheaders
  {
  "CSRF-Token"
  "X-Forwarded-Proto"
  "referer"
  "user-agent"
  "authorization"
  "from"
  "content-type"
  "content-length"
  "accept-charset"
  "accept-encoding"
  "accept-language"
  "accept"
  "host"
  "max-forwards"
  "proxy-authorization"
  "proxy-connection"
  "range"
  "cookie"
  "cq-action"
  "cq-handle"
  "handle"
  "action"
  "cqstats"
  "depth"
  "translate"
  "expires"
  "date"
  "dav"
  "ms-author-via"
  "if"
  "lock-token"
  "x-expected-entity-length"
  "destination"
  "PATH"
  }

識別虛擬主機 identifying-virtual-hosts-virtualhosts

/virtualhosts 屬性會定義 Dispatcher 在此陣列中接受的所有主機名稱和 URI 組合的清單。您可以使用星號 (*) 當作萬用字元。/ virtualhosts 屬性的值會使用以下格式：

[scheme]host[uri][*]

以下範例設定會處理 myCompany 的 .com 和 .ch 網域以及 mySubDivision 的所有網域的請求：

   /virtualhosts
    {
    "www.myCompany.com"
    "www.myCompany.ch"
    "www.mySubDivison.*"
    }

以下設定會處理​ 所有 ​請求：

   /virtualhosts
    {
    "*"
    }

解析虛擬主機 resolving-the-virtual-host

當 Dispatcher 收到 HTTP 或 HTTPS 請求時，它會尋找最符合該請求的 host, uri 和 scheme 標題的虛擬主機值。Dispatcher 會依照以下順序評估 virtualhosts 屬性中的值：

Dispatcher 會依照以下順序尋找最符合的虛擬主機值：

因此，您應該將預設虛擬主機放在 virtualhosts 屬性的最上方。放在 dispatcher.any 檔案的最上層陣列中。

範例虛擬主機解析 example-virtual-host-resolution

以下範例代表 dispatcher.any 檔案中的一個片段，該片段定義兩個 Dispatcher 陣列，每個陣列各定義一個 virtualhosts 屬性。

/farms
  {
  /myProducts
    {
    /virtualhosts
      {
      "www.mycompany.com/products/*"
      }
    /renders
      {
      /hostname "server1.myCompany.com"
      /port "80"
      }
    }
  /myCompany
    {
    /virtualhosts
      {
      "www.mycompany.com"
      }
    /renders
      {
      /hostname "server2.myCompany.com"
      /port "80"
      }
    }
  }

根據此範例，下表顯示為特定 HTTP 請求解析的虛擬主機：

啟用安全工作階段 - /sessionmanagement enabling-secure-sessions-sessionmanagement

建立安全工作階段以存取轉譯器陣列，讓使用者必須登入才能存取陣列中的任何頁面。使用者在登入後，就可以存取陣列中的頁面。如需搭配 CUG 使用此功能的相關資訊，請參閱建立封閉式使用者群組。此外，也請在上線前參考 Dispatcher 安全性檢查清單。

/sessionmanagement 屬性是 /farms 的子屬性。

/sessionmanagement 有幾個子參數：

/directory (必要)

儲存工作階段資訊的目錄。如果此目錄不存在，則會建立它。

/sessionmanagement
  {
  /directory "/usr/local/apache/.sessions"
  }

/encode (選擇性)

工作階段資訊的編碼方式。使用 md5 可透過 md5 演算法進行加密，或是使用 hex 進行十六進位加密。如果您為工作階段資料加密，可存取檔案系統的使用者將無法讀取工作階段內容。預設為 md5。

/header (選擇性)

儲存授權資訊的 HTTP 標題或 Cookie 的名稱。如果您將此資訊儲存在 http 標題中，請使用 HTTP:<header-name>。若要將此資訊儲存在 Cookie 中，請使用 Cookie:<header-name>。如果您未指定值，則會使用 HTTP:authorization。

/timeout (選擇性)

工作階段在上次使用之後，進入逾時之前的秒數。如果未指定，則會使用 "800"，所以工作階段的逾時時間為使用者的最後一次請求後的 13 分鐘多一點。

範例設定如下所示：

/sessionmanagement
  {
  /directory "/usr/local/apache/.sessions"
  /encode "md5"
  /header "HTTP:authorization"
  /timeout "800"
  }

定義頁面轉譯器 defining-page-renderers-renders

/renders 屬性會定義 URL，Dispatcher 會傳送請求到該 URL 以轉譯文件。以下範例 /renders 區段會識別用於轉譯的單一 AEM 執行個體：

/renders
  {
    /myRenderer
      {
      # hostname or IP of the renderer
      /hostname "aem.myCompany.com"
      # port of the renderer
      /port "4503"
      # connection timeout in milliseconds, "0" (default) waits indefinitely
      /timeout "0"
      }
  }

以下範例 /renders 區段會識別在相同電腦上當作 Dispatcher 執行的 AEM 執行個體：

/renders
  {
    /myRenderer
     {
     /hostname "127.0.0.1"
     /port "4503"
     }
  }

以下範例 /renders 區段會將轉譯請求平均分配到兩個 AEM 執行個體：

/renders
  {
    /myFirstRenderer
      {
      /hostname "aem.myCompany.com"
      /port "4503"
      }
    /mySecondRenderer
      {
      /hostname "127.0.0.1"
      /port "4503"
      }
  }

轉譯選項 renders-options

/timeout

指定存取 AEM 執行個體的連線逾時值 (以毫秒為單位)。預設為 "0"，此值會讓 Dispatcher 無限期等待。

/receiveTimeout

指定允許接收回應的時間 (以毫秒為單位)。預設為 "600000"，此值會讓 Dispatcher 等待 10 分鐘。設定為 "0" 可免除逾時。

如果在剖析回應標頭時到達逾時時間，則會傳回 HTTP 狀態 504 (閘道錯誤)。如果在讀取回應本文時到達逾時時間，Dispatcher 會將不完整的回應傳回給用戶端。Dispatcher 也會刪除任何可能已寫入的快取檔案。

/ipv4

指定 Dispatcher 是要使用 getaddrinfo 函數 (適用於 IPv6) 還是 gethostbyname 函數 (適用於 IPv4) 來取得轉譯器的 IP 位址。0 的值會使用 getaddrinfo。1 的值會使用 gethostbyname。預設值為 0。

getaddrinfo 函數會傳回 IP 位址清單。Dispatcher 會逐一查看此位址清單，直到建立 TCP/IP 連線為止。因此，在下列清況中 ipv4 屬性非常重要：當轉譯器主機名稱與多個 IP 位址相關聯，而主機在回應 getaddrinfo 函數時傳回始終具有相同順序的 IP 位址清單時。在此情況下，您應該使用 gethostbyname 函數，好讓 Dispatcher 連線的 IP 位址是隨機的。

Amazon Elastic Load Balancing (ELB) 服務可使用可能具有相同順序的 IP 位址清單來回應 getaddrinfo。

/secure

如果 /secure 屬性的值為 "1"，則 Dispatcher 會使用 HTTPS 來與 AEM 執行個體通訊。如需更多詳細資訊，可參閱設定 Dispatcher 使用 SSL。

/always-resolve

使用 Dispatcher 版本 4.1.6 時，您可以依照以下方式設定 /always-resolve 屬性：

此外，如果您遇到動態 IP 解析問題，也可以使用此屬性，如以下範例所示：

/renders {
  /0001 {
     /hostname "host-name-here"
     /port "4502"
     /ipv4 "1"
     /always-resolve "1"
     }
  }

設定對內容的存取權 configuring-access-to-content-filter

使用 /filter 區段可指定 Dispatcher 接受的 HTTP 請求。所有其他請求都會傳回網頁伺服器，並傳回 404 錯誤碼 (找不到頁面)。如果 /filter 區段不存在，則會接受所有請求。

注意： ​對 statfile 的請求一律會遭到拒絕。

/filter 區段是由一系列規則所組成，這些規則會根據 HTTP 請求的請求行部分中的模式來拒絕或允許對內容的存取。針對 /filter 區段使用允許清單策略：

定義篩選條件 defining-a-filter

/filter 區段中的每個項目都包含與請求行的特定元素或完整請求行相符的類型和模式。每個篩選條件都可包含以下項目：

HTTP 請求的請求行部分 the-request-line-part-of-http-requests

HTTP/1.1 會依據以下方式定義請求行：

Method Request-URI HTTP-Version<CRLF>

<CRLF> 字元代表歸位字元及後面跟著的換行字元。以下範例是當用戶端請求 WKND 網站的英文版頁面時所收到的請求行：

GET /content/wknd/us/en.html HTTP.1.1<CRLF>

您的模式必須考量請求行中的空格字元和 <CRLF> 字元。

雙引號與單引號的比較 double-quotes-vs-single-quotes

在建立篩選規則時，請針對簡單模式使用雙引號 "pattern"。如果您使用 Dispatcher 4.2.0 或更新版本，而且您的模式包含規則運算式，則必須用單引號括住規則運算式模式 '(pattern1|pattern2)'。

規則運算式 regular-expressions

在 Dispatcher 4.2.0 之後的版本中，您可以在篩選模式中包含 POSIX 擴充型規則運算式。

篩選的疑難排解 troubleshooting-filters

如果篩選器並未如您預期的方式觸發，請對 Dispatcher 啟用追蹤記錄，以便可以查看哪個篩選條件正在攔截請求。

範例篩選條件：全部拒絕 example-filter-deny-all

以下範例篩選區段會讓 Dispatcher 拒絕所有檔案的請求。拒絕存取所有檔案，然後允許存取特定區域。

/0001  { /type "deny" /url "*"  }

針對被明確拒絕的區域的請求會傳回 404 錯誤碼 (找不到頁面)。

範例篩選條件：拒絕存取特定區域 example-filter-deny-access-to-specific-areas

篩選器也可讓您拒絕存取各種元素 (例如 ASP 頁面) 以及發佈執行個體中的敏感區域。以下篩選條件會拒絕存取 ASP 頁面：

/0002  { /type "deny" /url "*.asp"  }

範例篩選條件：啟用 POST 請求 example-filter-enable-post-requests

以下範例篩選條件可透過 POST 方法提交表單資料：

/filter {
    /0001  { /glob "*" /type "deny" }
    /0002 { /type "allow" /method "POST" /url "/content/[.]*.form.html" }
}

範例篩選條件：允許存取 Workflow Console example-filter-allow-access-to-the-workflow-console

以下範例顯示用來允許外部使用者存取 Workflow console 的篩選條件：

/filter {
    /0001  { /glob "*" /type "deny" }
    /0002  {  /type "allow"  /url "/libs/cq/workflow/content/console*"  }
}

如果您的發佈執行個體使用網站應用程式環境 (例如發佈)，您也可以將其新增到您的篩選定義中。

/0003   { /type "deny"  /url "/publish/libs/cq/workflow/content/console/archive*"  }

如果您必須存取受限區域中的單次頁面，您可以允許存取這些頁面。例如，若要允許存取 Workflow console 內的 Archive 索引標籤，請新增以下區段：

/0004  { /type "allow"  /url "/libs/cq/workflow/content/console/archive*"   }

範例篩選條件：使用規則運算式 example-filter-using-regular-expressions

此篩選條件使用規則運算式，在非公開內容目錄中啟用副檔名 (在這裡是定義在單引號之間)：

/005  {  /type "allow" /extension '(css|gif|ico|js|png|swf|jpe?g)' }

範例篩選條件：篩選請求 URL 的額外元素 example-filter-filter-additional-elements-of-a-request-url

底下規則範例使用路徑、選擇器和副檔名的篩選條件來封鎖擷取自 /content 路徑及其子樹狀結構的內容：

/006 {
        /type "deny"
        /path "/content/*"
        /selectors '(feed|rss|pages|languages|blueprint|infinity|tidy|sysview|docview|query|jcr:content|_jcr_content|search|childrenlist|ext|assets|assetsearch|[0-9-]+)'
        /extension '(json|xml|html|feed))'
        }

範例 /filter 區段 example-filter-section

當您設定 Dispatcher 時，要盡可能限制外部存取。以下範例為外部訪客提供最低限度的存取權：

在建立篩選條件後，請測試頁面存取權以確保您的 AEM 執行個體安全無虞。

dispatcher.any 檔案的以下 /filter 區段可當作您的 Dispatcher 設定檔案的基礎。

以下範例是根據 Dispatcher 所提供的預設設定檔案，可當作生產環境中的範例使用。前置詞為 # 的項目已停用 (標記為註解)。如果您決定啟用其中任何項目 (藉由移除該行上的 #)，則應該要謹慎。這麼做可能會影響安全性。

拒絕存取所有內容，然後允許存取特定 (受限) 元素：

  /filter
      {
      # Deny everything first and then allow specific entries
      /0001  { /type "deny" /url "*"  }

      # Open consoles
#     /0011 { /type "allow" /url "/admin/*"  }  # allow servlet engine admin
#     /0012 { /type "allow" /url "/crx/*"    }  # allow content repository
#     /0013 { /type "allow" /url "/system/*" }  # allow OSGi console

      # Allow non-public content directories
#     /0021 { /type "allow" /url "/apps/*"   }  # allow apps access
#     /0022 { /type "allow" /url "/bin/*"    }
      /0023 { /type "allow" /url "/content*" }  # disable this rule to allow mapped content only

#     /0024 { /type "allow" /url "/libs/*"   }
#     /0025 { /type "deny"  /url "/libs/shindig/proxy*" } # if you enable /libs close access to proxy

#     /0026 { /type "allow" /url "/home/*"   }
#     /0027 { /type "allow" /url "/tmp/*"    }
#     /0028 { /type "allow" /url "/var/*"    }

      # Enable extensions in non-public content directories, using a regular expression
      /0041
        {
        /type "allow"
        /extension '(css|gif|ico|js|png|swf|jpe?g)'
        }

      # Enable features
      /0062 { /type "allow" /url "/libs/cq/personalization/*"  }  # enable personalization

      # Deny content grabbing, on all accessible pages, using regular expressions
      /0081
        {
        /type "deny"
        /selectors '((sys|doc)view|query|[0-9-]+)'
        /extension '(json|xml)'
        }
      # Deny content grabbing for /content and its subtree
      /0082
        {
        /type "deny"
        /path "/content/*"
        /selectors '(feed|rss|pages|languages|blueprint|infinity|tidy)'
        /extension '(json|xml|html)'
        }

#     /0087 { /type "allow" /method "GET" /extension 'json' "*.1.json" }  # allow one-level json requests
}

如果您選擇擴充存取權，請考量以下建議事項：

根據您的安裝情況，在 /libs、/apps 底下或其他地方可能有更多必須提供的資源。您可以使用 access.log 檔案當作判斷是否有人在外部存取資源的方式之一。

限制查詢字串 restricting-query-strings

從 Dispatcher 版本 4.1.5 開始，請使用 /filter 區段來限制查詢字串。建議您明確允許查詢字串，並透過 allow 篩選元素來排除一般性允許。

單一項目可以是 glob 或是 method、url、query 和 version 的某個組合，但兩者不能同時存在。以下範例針對解析成 /etc 節點的 URL，允許 a=* 查詢字串但拒絕所有其他查詢字串：

/filter {
 /0001 { /type "deny" /method "POST" /url "/etc/*" }
 /0002 { /type "allow" /method "GET" /url "/etc/*" /query "a=*" }
}

/filter {
>/0001 { /type "deny" /method "*" /url "/path/*" }
>/0002 { /type "allow" /method "GET" /url "/path/*" }
>/0003 { /type "deny" /method "GET" /url "/path/*" /query "*" }
>/0004 { /type "allow" /method "GET" /url "/path/*" /query "a=*" }
}

測試 Dispatcher 安全性 testing-dispatcher-security

Dispatcher 篩選條件應該在 AEM 發佈執行個體上封鎖對以下頁面和指令碼的存取。使用網頁瀏覽器，嘗試以網站訪客的身分開啟以下頁面，並驗證是否傳回錯誤碼 404。如果獲得其他任何結果，請調整篩選條件。

您應該會看到 /content/add_valid_page.html?debug=layout 的正常頁面呈現。

若要確定是否已啟用匿名寫入權限，請在終端機或命令提示字元中發出以下命令。應該無法將資料寫入節點。

curl -X POST "https://anonymous:anonymous@hostname:port/content/usergenerated/mytestnode"

若要嘗試讓 Dispatcher 快取失效，並確定您收到了代碼 403 回應，請在終端機或命令提示字元中發出以下命令：

curl -H "CQ-Handle: /content" -H "CQ-Path: /content" https://yourhostname/dispatcher/invalidate.cache

啟用對虛名 URL 的存取權 enabling-access-to-vanity-urls-vanity-urls

設定 Dispatcher 以啟用對虛名 URL 的存取權，這些是為您的 AEM 頁面設定的虛名 URL。

在啟用對虛名 URL 的存取權時，Dispatcher 會定期呼叫在轉譯器執行個體上執行的服務來取得虛名 URL 清單。Dispatcher 會將此清單儲存在本機檔案中。當由於 /filter 區段中的篩選條件而拒絕頁面的請求時，Dispatcher 會查詢虛名 URL 清單。如果被拒絕的 URL 在此清單上，Dispatcher 會允許存取虛名 URL。

若要啟用對虛名 URL 的存取權，請在 /farms 區段中新增 /vanity_urls 區段，類似於以下範例：

 /vanity_urls {
      /url "/libs/granite/dispatcher/content/vanityUrls.html"
      /file "/tmp/vanity_urls"
      /delay 300
 }

/vanity_urls 區段包含以下屬性：

使用以下程序來啟用對虛名 URL 的存取權。

轉送整合請求 - /propagateSyndPost forwarding-syndication-requests-propagatesyndpost

整合請求僅適用於 Dispatcher，所以在預設情況下不會傳送給轉譯器 (例如 AEM 執行個體)。

必要時，請將 /propagateSyndPost 屬性設定為 "1" 以將整合請求轉送給 Dispatcher。如果有設定此屬性，您必須確定篩選區段中不會拒絕 POST 請求。

設定 Dispatcher 快取 - /cache configuring-the-dispatcher-cache-cache

/cache 區段會控制 Dispatcher 如何快取文件。設定幾個子屬性以實施您的快取策略：

快取區段範例可能如下所示：

/cache
  {
  /docroot "/opt/dispatcher/cache"
  /statfile  "/tmp/dispatcher-website.stat"
  /allowAuthorized "0"

  /rules
    {
    # List of files that are cached
    }

  /invalidate
    {
    # List of files that are auto-invalidated
    }
  }

指定快取目錄 specifying-the-cache-directory

/docroot 屬性可識別快取檔案儲存所在的目錄。

如果您使用多個陣列，每個陣列都必須使用不同的主目錄。

為 Statfile 命名 naming-the-statfile

/statfile 屬性可識別要當作 statfile 使用的檔案。Dispatcher 會使用這個檔案來登錄最近一次內容更新的時間。statfile 可以是網頁伺服器上的任何檔案。

statfile 沒有任何內容。當更新內容時，Dispatcher 會更新時間戳記。預設 statfile 命名為 .stat，並儲存在 docroot 中。Dispatcher 會封鎖對 statfile 的存取權。

在發生錯誤時提供過時文件 serving-stale-documents-when-errors-occur

/serveStaleOnError 屬性可控制當轉譯伺服器傳回錯誤時，Dispatcher 是否會傳回失效的文件。根據預設，在接觸了 statfile 並讓快取內容失效時，Dispatcher 在下次請求該內容時會刪除快取的內容。此動作將在下次請求時執行。

如果 /serveStaleOnError 設定為 "1"，則 Dispatcher 不會從快取中刪除失效的內容。也就是說，除非轉譯伺服器傳回成功的回應。來自 AEM 的 5xx 回應或連線逾時會導致 Dispatcher 提供過時的內容及 HTTP 狀態 111 (重新驗證失敗) 的回應。

在使用驗證時快取 caching-when-authentication-is-used

/allowAuthorized 屬性可控制是否快取包含以下任何驗證資訊的請求：

預設不會快取包含此驗證資訊的請求，因為將快取的文件傳回用戶端時並不會執行驗證。此設定可避免 Dispatcher 提供快取的文件給沒有必要權限的使用者。

不過，如果您的要求允許快取經過驗證的文件，請將 /allowAuthorized 設為一：

/allowAuthorized "1"

指定要快取的文件 specifying-the-documents-to-cache

/rules 屬性可控制根據文件路徑快取哪些文件。無論 /rules 屬性為何，Dispatcher 在以下情況下絕對不會快取文件：

/rules 屬性中的每個項目都包含 glob 模式和一個類型：

如果您沒有動態頁面 (在上述規則已排除的頁面之外)，您可以設定 Dispatcher 快取所有內容。規則區段如下所示：

/rules
  {
    /0000  {  /glob "*"   /type "allow" }
  }

如需 Glob 屬性的相關資訊，請參閱為 Glob 屬性設計模式。

如果頁面中的某些區段是動態的 (例如新聞應用程式) 或是在封閉式使用者群組內，您可以定義例外情況：

/rules
  {
   /0000  { /glob "*" /type "allow" }
   /0001  { /glob "/en/news/*" /type "deny" }
   /0002  { /glob "*/private/*" /type "deny"  }
  }

壓縮

在 Apache Web Server 上，您可以壓縮快取文件。如果用戶端要求的話，壓縮可讓 Apache 傳回壓縮格式的文件。啟用 Apache 模組 mod_deflate 即可自動進行壓縮，例如：

AddOutputFilterByType DEFLATE text/plain

Apache 2.x 預設會安裝此模組。

依照資料夾層級讓檔案失效 invalidating-files-by-folder-level

使用 /statfileslevel 屬性可根據快取檔案的路徑來讓這些檔案失效：

只有失效檔案的​ 路徑上 ​的資源會受到影響。考量以下範例：網站使用此結構：/content/myWebsite/xx/. 如果您將 statfileslevel 設為 3，則會建立 .stat 檔案，如下所示：

當 /content/myWebsite/xx 中的某個檔案失效時，會觸及每個 .stat 檔案，從 docroot 往下到 /content/myWebsite/xx。只有 /content/myWebsite/xx 才會是這種情況，而不是 /content/myWebsite/yy 或 /content/anotherWebSite 等。

自動讓快取檔案失效 automatically-invalidating-cached-files

/invalidate 屬性會定義在內容更新時自動失效的文件。

使用自動失效時，Dispatcher 並不會在內容更新後刪除快取檔案，而是在下次請求快取檔案時檢查其是否有效。快取中未自動失效的文件會留在快取中，直到內容更新明確將其刪除為止。

自動失效通常用於 HTML 頁面。HTML 頁面經常包含其他頁面的連結，所以很難判斷內容更新是否會影響頁面。為了確保在內容更新時所有相關頁面都會失效，請讓所有 HTML 頁面自動失效。以下設定會讓所有 HTML 頁面失效：

  /invalidate
  {
   /0000  { /glob "*" /type "deny" }
   /0001  { /glob "*.html" /type "allow" }
  }

如需 Glob 屬性的相關資訊，請參閱為 Glob 屬性設計模式。

在啟用 /content/wknd/us/en 時，此設定會產生以下活動：

如果您提供自動產生的 PDF 和 ZIP 檔案供人下載，您也可能必須讓這些檔案自動失效。設定範例如下所示：

/invalidate
  {
   /0000 { /glob "*" /type "deny" }
   /0001 { /glob "*.html" /type "allow" }
   /0002 { /glob "*.zip" /type "allow" }
   /0003 { /glob "*.pdf" /type "allow" }
  }

AEM 與 Adobe Analytics 的整合可在您網站的analytics.sitecatalyst.js 檔案中提供設定資料。Dispatcher 提供的範例 dispatcher.any 檔案包含此檔案適用的以下失效規則：

{
   /glob "*/analytics.sitecatalyst.js"  /type "allow"
}

使用自訂失效指令碼 using-custom-invalidation-scripts

/invalidateHandler 屬性可讓您定義指令碼，Dispatcher 收到的每個失效請求都會呼叫此指令碼。

呼叫此指令碼時會使用以下引數：

此方法可用於涵蓋多個不同的使用案例。例如，讓其他應用程式特有的快取失效，或是處理頁面的外部化 URL 及其在 docroot 中的位置與內容路徑不符的情況。

下列範例指令碼會將每個失效請求記錄到檔案中。

/invalidateHandler "/opt/dispatcher/scripts/invalidate.sh"

失效處理常式指令碼範例 sample-invalidation-handler-script

#!/bin/bash

printf "%-15s: %s %s" $1 $2 $3>> /opt/dispatcher/logs/invalidate.log

限制可以清除快取的用戶端 limiting-the-clients-that-can-flush-the-cache

/allowedClients 屬性會定義允許清除快取的特定用戶端。系統會將萬用字元模式與 IP 進行比對。

下列範例：

/allowedClients
  {
   /0001 { /glob "*.*.*.*"  /type "deny" }
   /0002 { /glob "127.0.0.1" /type "allow" }
  }

如需 Glob 屬性的相關資訊，請參閱為 Glob 屬性設計模式。

忽略 URL 參數 ignoring-url-parameters

ignoreUrlParams 區段會定義在判斷要快取頁面還是從快取中傳遞頁面時要忽略哪些 URL 參數：

忽略頁面的某個參數時，將會在第一次請求該頁面時快取該頁面。無論請求中的參數值為何，都將為該頁面的後續請求提供快取頁面。

若要指定哪些參數會被忽略，請在 ignoreUrlParams 屬性中新增 glob 規則：

下列範例會造成 Dispatcher 忽略所有參數，nocache 參數除外。如此一來，Dispatcher 永遠不會快取包含 nocache 參數的要求 URL：

/ignoreUrlParams
{
    # ignore-all-url-parameters-by-dispatcher-and-requests-are-cached
    /0001 { /glob "*" /type "allow" }
    # allow-the-url-parameter-nocache-to-bypass-dispatcher-on-every-request
    /0002 { /glob "nocache" /type "deny" }
}

在上述 ignoreUrlParams 配置範例的上下文中，以下 HTTP 要求會導致頁面被快取，因為 willbecached 參數被忽略：

GET /mypage.html?willbecached=true

在上述 ignoreUrlParams 配置範例的上下文中，以下 HTTP 要求會導致頁面​ 不會 ​被快取，因為 nocache 參數不會被忽略：

GET /mypage.html?nocache=true
GET /mypage.html?nocache=true&willbecached=true

如需 Glob 屬性的相關資訊，請參閱為 Glob 屬性設計模式。

快取 HTTP 回應標頭 caching-http-response-headers

/headers 屬性可讓您定義將由 Dispatcher 快取的 HTTP 標題類型。初次請求未快取的資源時，符合其中一個設定值 (請參閱底下的設定範例) 的所有標題都會儲存在快取檔案旁邊的另一個檔案中。後續請求快取的資源時，儲存的標題會新增到回應中。

下面是預設設定中的範例：

/cache {
  ...
  /headers {
    "Cache-Control"
    "Content-Disposition"
    "Content-Type"
    "Expires"
    "Last-Modified"
    "X-Content-Type-Options"
    "Last-Modified"
  }
}

FileETag none

Dispatcher 快取檔案權限 dispatcher-cache-file-permissions

mode 屬性會指定哪些檔案權限會套用到快取中的新目錄和檔案。呼叫程序的 umask 會限制此設定。這是一個八進位數字，由下列一個或多個值的總和所構成：

預設值為 0755，允許所有者讀取、寫入或搜尋，並允許群組成員和其他人讀取或搜尋。

限制 .stat 檔案的接觸 throttling-stat-file-touching

使用預設 /invalidate 屬性時，每次啟用都會有效地讓所有 .html 檔案失效 (當其路徑符合 /invalidate 區段時)。在流量很大的網站上，後續的多次啟用會增加後端的 CPU 負載。在這種情況下，最好「限制」.stat 檔案的接觸，以維持網站的回應能力。您可以使用 /gracePeriod 屬性來完成此動作。

/gracePeriod 屬性會定義在最後一次啟用後，仍然可以從快取中提供舊的、已自動失效的資源的秒數。此屬性適用於以下情況的設定：如果不這樣設定，有一批啟用會反覆地讓整個快取失效。建議值為 2 秒。

如需更多詳細資訊，可參閱更早版本的 /invalidate 和 /statfileslevel。

設定以時間為基礎的快取失效 - /enableTTL configuring-time-based-cache-invalidation-enablettl

以時間為基礎的快取失效取決於 /enableTTL 屬性以及來自 HTTP 標準的一般到期標頭是否存在。如果將此屬性設為 1 (/enableTTL "1")，它會評估來自後端的回應標頭。如果標頭包含 Cache-Control、max-age 或 Expires 日期，則會在快取檔案旁邊建立空的輔助檔案，且修改時間等於到期日。在修改時間過後請求快取檔案時，將會自動從後端重新請求該檔案。

在 Dispatcher 4.3.5 之前，TTL 失效邏輯僅根據設定的 TTL 值。使用 Dispatcher 4.3.5，設定的 TTL 和 Dispatcher 快取失效規則都會列入考量。因此，對於快取的檔案：

此新實作支援的使用案例是檔案有較長的 TTL (例如，在 CDN 上)。但即使 TTL 尚未過期，這些檔案仍可能失效。它有利於內容處於最新狀態，而不是 Dispatcher 上的快取命中率。

相反地，如果您​ 僅 ​需要套用到檔案的到期邏輯，則將 /enableTTL 設定為 1，並從標準快取失效機制中排除該檔案。例如，您可以：

  /invalidate
  {
   /0000  { /glob "*" /type "deny" }
   /0001  { /glob "*.html" /type "allow" }
   /0002  { /glob "*.example.html" /type "deny" }
  }

這麼做確保不會使用 .stat 檔案失效，只有 TTL 到期對指定的檔案有效。

設定負載平衡 - /statistics configuring-load-balancing-statistics

/statistics 區段會定義檔案類別，Dispatcher 針對這類檔案為每個轉譯器的回應能力評分。Dispatcher 會使用這些評分來決定哪個轉譯器要傳送請求。

您建立的每個類別都會定義 glob 模式。Dispatcher 會將請求內容的 URI 與這些模式做比較，以判斷請求內容的類別：

Dispatcher 最多可支援 8 個統計類別。如果您定義 8 個以上的類別，只會使用前 8 個類別。

轉譯器選擇

每當 Dispatcher 需要轉譯頁面時，它都會使用以下演算法來選取轉譯器：

轉譯器類別的分數是根據之前的回應時間，以及之前 Dispatcher 嘗試建立的失敗和成功的連線。對於每次嘗試，都會更新請求的 URI 的類別分數。

定義統計資料類別 defining-statistics-categories

針對您想要保留統計資料以便選擇轉譯器的每個文件類型定義一個類別。/statistics 區段包含 /categories 區段。若要定義類別，請在 /categories 區段底下新增具有以下格式的一行：

/name { /glob "pattern"}

類別 name 對該陣列而言必須是獨一無二的。為 glob 屬性設計模式一節中有說明 pattern。

為了判斷 URI 的類別，Dispatcher 會將 URI 與每個類別模式做比較，直到找到符合項目為止。Dispatcher 會從清單中的第一個類別開始，然後依順序繼續進行。所以，請將具有更具體模式的類別放在前面。

例如，Dispatcher 預設 dispatcher.any 檔案會定義 HTML 類別以及一個其他類別。HTML 類別比較具體，所以會先出現：

/statistics
  {
  /categories
    {
      /html { /glob "*.html" }
      /others  { /glob "*" }
    }
  }

以下範例也包含搜尋頁面的類別：

/statistics
  {
  /categories
    {
      /search { /glob "*search.html" }
      /html { /glob "*.html" }
      /others  { /glob "*" }
    }
  }

在 Dispatcher 統計資料中反映伺服器無法使用 reflecting-server-unavailability-in-dispatcher-statistics

/unavailablePenalty 屬性會設定當與轉譯器的連線失敗時，套用到轉譯器統計資料的時間 (以十分之一秒為單位)。Dispatcher 會將此時間新增到符合請求的 URI 的統計資料類別。

例如，當無法建立與指定的主機名稱/連接埠的 TCP/IP 連線時就會套用懲罰。這是因為 AEM 未執行 (也未偵聽) 或是網路相關問題所造成。

/unavailablePenalty 屬性是 /farm 區段的直接子項 (/statistics 區段的同層級)。

如果沒有 /unavailablePenalty 屬性存在，則會使用 "1" 的值。

/unavailablePenalty "1"

識別黏性連線資料夾 - /stickyConnectionsFor identifying-a-sticky-connection-folder-stickyconnectionsfor

/stickyConnectionsFor 屬性會定義一個包含黏性文件的資料夾。此屬性是使用 URL 存取。Dispatcher 會將來自單一使用者的所有請求 (都在此資料夾中) 傳送給相同轉譯器執行個體。黏性連線可確保工作階段資料存在，且在所有文件中都是一致的。此機制會使用 renderid Cookie。

以下範例定義與 /products 資料夾的黏性連線：

/stickyConnectionsFor "/products"

當頁面是由數個內容節點中的內容所組成時，請包含列出內容路徑的 /paths 屬性。例如，某個頁面包含 /content/image、/content/video 和 /var/files/pdfs 中的內容。以下設定會針對該頁面上的所有內容啟用黏性連線：

/stickyConnections {
  /paths {
    "/content/image"
    "/content/video"
    "/var/files/pdfs"
  }
}

httpOnly httponly

當啟用黏性連線時，Dispatcher 模組會設定 renderid Cookie。此 Cookie 沒有 httponly 標幟，應該要新增此標幟以增強安全性。您新增 httponly 標幟的方式是設定 httpOnly 屬性，位於 /stickyConnections 節點中 (dispatcher.any 設定檔案)。該屬性的值 (0 或 1) 會定義 renderid Cookie 是否已附加 HttpOnly 屬性。預設值為 0，這表示不會新增此屬性。

如需有關 httponly 標幟的其他資訊，請閱讀此頁面。

secure secure

當啟用黏性連線時，Dispatcher 模組會設定 renderid Cookie。此 Cookie 沒有 secure 標幟，應該要新增此標幟以增強安全性。您新增 secure 標幟，設定 secure 屬性，位於 /stickyConnections 節點中 (dispatcher.any 設定檔案)。該屬性的值 (0 或 1) 會定義 renderid Cookie 是否已附加 secure 屬性。預設值為 0，這表示​ 如果 ​傳入的請求是安全的，會新增此屬性。如果此值設定為 1，則無論傳入的請求是否安全，都會新增 secure 標幟。

處理轉譯器連線錯誤 handling-render-connection-errors

設定當轉譯器伺服器傳回 500 錯誤或無法使用時的 Dispatcher 行為。

指定健康情況檢查頁面 specifying-a-health-check-page

使用 /health_check 屬性可指定在出現 500 狀態代碼時檢查的 URL。如果此頁面也傳回 500 狀態代碼，則會將執行個體視為無法使用，並在重試之前將可設定的時間懲罰 ( /unavailablePenalty) 套用到轉譯器。

/health_check
  {
  # Page gets contacted when an instance returns a 500
  /url "/health_check.html"
  }

指定頁面重試延遲 specifying-the-page-retry-delay

/retryDelay 屬性會設定 Dispatcher 嘗試與陣列轉譯器建立的連線輪次之間等待的時間 (以秒為單位)。針對每一輪，Dispatcher 嘗試與轉譯器建立連線的次數上限為陣列中的轉譯器數目。

如果未明確定義 /retryDelay，Dispatcher 會使用 "1" 的值。預設值一般都適用。

/retryDelay "1"

設定重試次數 configuring-the-number-of-retries

/numberOfRetries 屬性會設定 Dispatcher 嘗試與轉譯器建立的連線輪次的數目上限。如果 Dispatcher 在超過此重試次數後還是無法成功連線到轉譯器，Dispatcher 會傳回失敗的回應。

針對每一輪，Dispatcher 嘗試與轉譯器建立連線的次數上限為陣列中的轉譯器數目。因此，Dispatcher 嘗試建立連線的次數上限為 ( /numberOfRetries) x (轉譯器數目)。

如果未明確定義此值，預設值為 5。

/numberOfRetries "5"

使用容錯移轉機制 using-the-failover-mechanism

若要在原始請求失敗時重新傳送請求給不同的轉譯器，請在您的 Dispatcher 陣列上啟用容錯移轉機制。當啟用容錯移轉時，Dispatcher 具有以下行為：

若要啟用容錯移轉，請在陣列 (或網站) 中新增下面這一行：

/failover "1"

忽略中斷錯誤 - /ignoreEINTR ignoring-interruption-errors-ignoreeintr

如果系統呼叫的物件位在透過 NFS 的方式存取的遠端系統上，則任何檔案系統導向的系統呼叫都可以被中斷 EINTR。這些系統呼叫可以逾時還是被中斷，取決於基礎檔案系統如何在本機電腦上裝載。

如果您的執行個體有這類設定，而且記錄中包含以下訊息，請使用 /ignoreEINTR 參數：

Error while reading response: Interrupted system call

在內部，Dispatcher 會使用可以表示如下的迴圈來讀取來自遠端伺服器 (亦即 AEM) 的回應：

while (response not finished) {
read more data
}

這類訊息會在下列情況中產生：當 read more data 區段中出現 EINTR，而且是因為在收到任何資料之前收到訊號所導致。

若要忽略這類中斷，可以將下面參數新增到 dispatcher.any (在 /farms 前面)：

/ignoreEINTR "1"

將 /ignoreEINTR 設為 "1" 會讓 Dispatcher 繼續嘗試讀取資料，直到讀取完整回應為止。預設值為 0，且會停用此選項。

為 Glob 屬性設計模式 designing-patterns-for-glob-properties

Dispatcher 設定檔案中有幾個區段會使用 glob 屬性當作用戶端請求的選擇標準。glob 屬性的值是 Dispatcher 與請求的某個層面進行比較的模式，例如請求的資源的路徑或是用戶端的 IP 位址。例如，/filter 區段中的項目會使用 glob 模式來識別 Dispatcher 採取行動或拒絕的頁面的路徑。

glob 值可包含萬用字元和英數字元來定義模式。

記錄 logging

在網頁伺服器設定中，您可以設定：

如需詳細資訊，請參閱您的 Dispatcher 執行個體的網頁伺服器文件和讀我檔案。

Apache 輪換記錄或管道傳輸記錄

如果您使用 Apache 網頁伺服器，可以將標準功能用於輪換記錄或管道傳輸記錄，或兩者。例如，使用管道傳輸記錄：

DispatcherLog "| /usr/apache/bin/rotatelogs logs/dispatcher.log%Y%m%d 604800"

此功能自動輪換：

請參閱 Apache 網頁伺服器文件中有關記錄輪換和管道傳輸記錄的內容。例如，Apache 2.4。

追蹤記錄 trace-logging

在 Dispatcher 的其他增強功能中，版本 4.2.0 也引進了追蹤記錄。

此功能層級高於偵錯記錄，會在記錄中顯示額外的資訊。它會新增以下項目的記錄：

若要啟用追蹤記錄，請在網頁伺服器中將記錄層級設定為 4。

底下是已啟用追蹤的記錄範例：

[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[Host] = "localhost:8443"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[User-Agent] = "curl/7.43.0"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[Accept] = "*/*"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[X-Forwarded-SSL-Client-Cert] = "(null)"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[Via] = "1.1 localhost:8443 (dispatcher)"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[X-Forwarded-For] = "::1"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[X-Forwarded-SSL] = "on"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[X-Forwarded-SSL-Cipher] = "DHE-RSA-AES256-SHA"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[X-Forwarded-SSL-Session-ID] = "ba931f5e4925c2dde572d766fdd436375e15a0fd24577b91f4a4d51232a934ae"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[X-Forwarded-Port] = "8443"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[Server-Agent] = "Communique-Dispatcher"

在請求符合封鎖規則的檔案時記錄了一個事件：

[Thu Mar 03 14:42:45 2016] [T] [11831] 'GET /content.infinity.json HTTP/1.1' was blocked because of /0082

確認基本操作 confirming-basic-operation

若要確認網頁伺服器、Dispatcher 和 AEM 執行個體的基本操作和互動，您可以使用以下步驟：

使用多個 Dispatcher using-multiple-dispatchers

您可以透過複雜的設定來使用多個 Dispatcher。例如您可以使用：

在這種情況下，請確定每個請求只通過一個 Dispatcher。Dispatcher 不會處理來自其他 Dispatcher 的請求。因此，請確定兩個 Dispatcher 都直接存取 AEM 網站。

偵錯 debugging

將標頭 X-Dispatcher-Info 新增到請求時，Dispatcher 會回應是快取了目標、從快取中返回還是完全不可快取。回應標頭 X-Cache-Info 會在可讀的表單中包含此資訊。您可以使用這些回應標頭來偵錯 Dispatcher 快取回應的相關問題。

預設不會啟用此功能，所以若要包含回應標頭 X-Cache-Info，陣列必須包含以下項目：

/info "1"

例如，

/farm
{
    /mywebsite
    {
        # Include X-Cache-Info response header if X-Dispatcher-Info is in request header
        /info "1"
    }
}

此外，X-Dispatcher-Info 標頭不需要值，但如果您使用 curl 進行測試，就必須提供值以便傳送標頭，例如：

curl -v -H "X-Dispatcher-Info: true" https://localhost/content/wknd/us/en.html

底下是包含 X-Dispatcher-Info 會傳回的回應標頭的清單：