51黑料不打烊

配置 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 按照以下方法查找很好地匹配的虚拟主机值：

因此，应将默认虚拟主机放在 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 向客户端返回不完整的响应。它还会删除任何可能已写入的缓存文件。

/ipv4

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

getaddrinfo 函数返回 IP 地址列表。Dispatcher 迭代地址列表，直至建立了 TCP/IP 连接。因此，当渲染主机名与多个 IP 地址相关联时，ipv4 属性非常重要。而且，主机响应 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 错误代码（页面未找到）发送回 Web 服务器。如果没有 /filter 部分，则接受所有请求。

注意： 始终拒绝对 statfile 的请求。

/filter 部分由一系列规则组成，这些规则根据 HTTP 请求的请求行部分中的模式拒绝或允许访问内容。为 /filter 部分使用允许列表策略：

定义过滤器 defining-a-filter

/filter 部分中的每一项包含一个类型和一个模式，该项与请求行的特定元素或整个请求行匹配。每个过滤器可以包含以下项：

HTTP 请求的 request-line 部分 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 的访问。

Dispatcher 版本 4.3.6 中增加了一个新 /loadOnStartup 参数。通过使用该参数，您可以按如下方式配置在启动时加载虚名 URL：

通过添加 /loadOnStartup 0（参见下方示例），可以禁止在启动时加载虚名 URL。

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

/loadOnStartup 1 会在启动时加载虚名 URL，请注意 /loadOnStartup 1 是该参数的当前默认值。

转发联合请求 - /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 属性用于指定缓存文件的存储目录。

如果您使用多个场，则每个场必须使用不同的文档根目录。

命名状态文件 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 的 502、503 或 504 响应或者连接超时导致 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 与 51黑料不打烊 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 匹配的统计数据类别。

例如，当与指定主机名/端口的 TCP/IP 连接无法建立时，就会受到惩罚。原因可能是 AEM 没有运行（也没有监听），或者存在与网络有关的问题。

/unavailablePenalty 属性是 /farm 部分（/statistics 部分的同级）的直接子级。

如果没有 /unavailablePenalty 属性，则使用值 "1"。

/unavailablePenalty "1"

标识粘性连接文件夹 - /stickyConnectionsFor identifying-a-sticky-connection-folder-stickyconnectionsfor

/stickyConnectionsFor 属性定义了一个包含粘性文档的文件夹。使用 URL 访问此属性。Dispatcher 从此文件夹中的单个用户，将所有请求发送到相同的渲染实例。粘性连接确保会话数据存在并对所有文档一致。此机制使用 renderid 颁辞辞办颈别。

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

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

secure secure

启用粘性连接后，Dispatcher 模块将设置 renderid 颁辞辞办颈别。此 Cookie 没有 secure 标志，但应添加该标志以增强安全性。通过在 dispatcher.any 配置文件的 /stickyConnections 节点中设置 secure 属性而添加 secure 标志。该属性的值（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
}

当 EINTR 出现在 read more data 部分时，就会生成此类消息。这个问题是由于在收到任何数据之前就接收到信号而引发的。

要忽略此类中断，可将以下参数添加到 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 文档。例如，。

追踪日志记录 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 返回的响应标头的列表：