配置 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 包含场 1 到 5 的配置，您可以按如下所示包括它们：

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

使用环境变量 using-environment-variables

在 dispatcher.any 文件中，您可以在字符串值属性中使用环境变量而不是硬编码的值。要包括环境变量的值，请使用格式 ${variable_name}。

例如，如果 dispatcher.any 文件在与缓存目录相同的目录中，则可使用 docroot 属性的以下值：

/docroot "${PWD}/cache"

作为另一个示例，如果您创建名为 PUBLISH_IP 的环境变量，该变量存储 AEM 发布实例的主机名，则可以使用 /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 按照以下方法查找很好地匹配的虚拟主机值：

因此，您应该将默认虚拟主机放在 dispatcher.any 文件的最顶部场的 virtualhosts 属性的顶部。

示例虚拟主机解析 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 向客户端返回不完整的响应。它还会删除任何可能已写入的缓存文件。

/ipv4

指定 Dispatcher 使用 getaddrinfo 函数（用于 IPv6）还是 gethostbyname 函数（用于 IPv4）来获取渲染的 IP 地址。值为 0 会导致使用 getaddrinfo。值为 1 会导致使用 gethostbyname。默认值为 0。

getaddrinfo 函数返回 IP 地址列表。Dispatcher 迭代地址列表，直至建立了 TCP/IP 连接。因此，当渲染主机名与多个 IP 地址关联，而主机在响应 getaddrinfo 函数时返回始终具有相同顺序的 IP 地址列表时，ipv4 属性非常重要。在这种情况下，您应使用 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 错误代码（页面未找到）发送回 Web 服务器。如果没有 /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

在版本高于 4.2.0 的 Dispatcher 中，您可以在筛选模式中包含 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" }
}

示例筛选条件：允许访问工作流程控制台 example-filter-allow-access-to-the-workflow-console

以下示例显示用于允许从外部访问工作流控制台的筛选条件：

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

如果您的发布实例使用 Web 应用程序上下文（例如，发布），则还可将它添加到您的筛选条件定义。

/0003   { /type "deny"  /url "/publish/libs/cq/workflow/content/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 发布实例上应该阻止对以下页面和脚本的访问。使用 Web 浏览器尝试以网站访客身份打开以下页面，并验证是否返回了代码 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 以启用对为 AEM 页面配置的虚名 URL 的访问。

启用了对虚名 URL 的访问时，Dispatcher 定期调用在渲染实例上运行的服务以获取虚名 URL 的列表。Dispatcher 将此列表存储在本地文件中。由于 /filter 部分中的筛选条件而拒绝了对页面的请求时，Dispatcher 会参考虚名 URL 的列表。如果被拒绝的 URL 位于列表上，Dispatcher 将允许对虚名 URL 的访问。

要启用对虚名 URL 的访问，请将 /vanity_urls 部分添加到 /farms 部分中，类似于以下实例：

 /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 可以是 Web 服务器上的任意文件。

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 设置为 1：

/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 中的某个文件失效时，将接触从 docroot 下至 /content/myWebsite/xx 的每个 .stat 文件。此场景仅适用于 /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 参数：

忽略页面的某个参数时，在首次请求页面时缓存该页面。对该页面后续的请求提供缓存的页面，不论请求中的参数值如何。

要指定忽略哪些参数，请将 glob 规则添加到 ignoreUrlParams 属性：

以下示例导致 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 配置示例的上下文中，由于 willbecached 参数被忽略，以下 HTTP 请求会导致页面被缓存：

GET /mypage.html?willbecached=true

在上述 ignoreUrlParams 配置示例的上下文中，由于 nocache 参数不会被忽略，因此以下 HTTP 请求​ 不 ​会导致页面被缓存：

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 必须对场唯一。pattern 在为 glob 属性设计模式部分中有介绍。

为确定 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 匹配的统计数据类别。

例如，由于 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 标志，但应添加该标志以增强安全性。通过在 dispatcher.any 配置文件的 /stickyConnections 节点中设置 httpOnly 属性而添加 httponly 标志。该属性的值（0 或 1）定义 renderid Cookie 是否追加了 HttpOnly 属性。默认值为 0，这意味着不添加该属性。

有关 httponly 标记的更多信息，请阅读此页面。

secure secure

启用粘性连接后，Dispatcher 模块将设置 renderid Cookie。此 Cookie 没有 secure 标志，但应添加该标志以增强安全性。通过在 dispatcher.any 配置文件的 /stickyConnections 节点中设置 secure 属性而添加 secure 标志。该属性的值（0 或 1）定义 renderid Cookie 是否追加了 secure 属性。默认值为 0，这意味着​ 如果 ​传入请求是安全的，则添加该属性。如果将该值设置为 1，则无论传入请求是否安全，都将添加 secure 标志。

处理渲染连接错误 handling-render-connection-errors

配置 Dispatcher 在渲染服务器返回 500 错误或不可用时的行为。

指定运行状况检查页面 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

在 Web 服务器配置中，您可以设置：

有关更多信息，请参阅 Web 服务器文档和 Dispatcher 实例的自述文件。

Apache 轮换/管道传输日志

如果使用 Apache Web Server，则可使用轮换日志和/或管道传输日志的标准功能。例如，使用管道传输日志：

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

此功能自动轮换：

请参阅关于日志轮换和管道传输日志的 Apache Web Server 文档。例如，Apache 2.4。

跟踪日志记录 trace-logging

除了 Dispatcher 的其他增强之外，4.2.0 版还引入了跟踪日志记录。

此功能比在日志中显示附加信息的调试日志记录高一级。它添加以下日志记录：

您可通过在 Web 服务器上将日志级别设置为 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

要确认基本操作和与 Web 服务器、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 返回的响应标头的列表：