Nginx官方文档(二十)【ngx_http_headers_module|ngx_http_hls_module】

淡淡的烟草味﹌ 2021-07-04 17:59 492阅读 0赞

# ngx\_http\_headers\_module #

*  指令
    
     *  add\_header
     *  add\_trailer
     *  expires

`ngx_http_headers_module` 模块允许将 `Expires` 和 `Cache-Control` 头字段以及任意字段添加到响应头中。

## 示例配置 ##

expires    24h;
    expires    modified +24h;
    expires    @24h;
    expires    0;
    expires    -1;
    expires    epoch;
    expires    $expires;
    add_header Cache-Control private;

## 指令 ##

### add\_header ###

<table> 
 <thead> 
  <tr> 
   <th align="right">-</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="right"><strong>语法</strong></td> 
   <td><strong>add_header</strong> <code>name value [always]</code>;</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>默认</strong></td> 
   <td>——</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>上下文</strong></td> 
   <td>http、server、location、location 中的 if</td> 
  </tr> 
 </tbody> 
</table>

如果响应代码等于 200、201（1.3.10）、204、206、301、302、303、304、307（1.1.16、1.0.13）或 308（1.13.0），则将指定的字段添加到响应报头中。该值可以包含变量。

可以存在几个 `add_header` 指令。当且仅当在当前级别上没有定义 `add_header` 指令时，这些指令才从上一级继承。

如果指定了 `always` 参数（1.7.5），则无论响应代码为何值，头字段都将被添加。

### add\_trailer ###

<table> 
 <thead> 
  <tr> 
   <th align="right">-</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="right"><strong>语法</strong></td> 
   <td><strong>add_trailer</strong> <code>number size</code>;</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>默认</strong></td> 
   <td>——</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>上下文</strong></td> 
   <td>http、server、location、location 中的 if</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>提示</strong></td> 
   <td>该指令在 1.13.2 版本中出现</td> 
  </tr> 
 </tbody> 
</table>

如果响应代码等于 200、201、206、301、302、303、307 或 308，则将指定的字段添加到响应的末尾。该值可以包含变量。

可以存在多个 `add_trailer` 指令。当且仅当在当前级别上没有定义 `add_trailer` 指令时，这些指令才从上一级继承。

如果指定 `always` 参数，则无论响应代码为何值，都会添加指定的字段。

### expires ###

<table> 
 <thead> 
  <tr> 
   <th align="right">-</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="right"><strong>语法</strong></td> 
   <td><strong>expires</strong> <code>[modified] time</code>; <br> <strong>expires</strong> <code>epoch</code> |<code>max</code> | <code>off</code>;</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>默认</strong></td> 
   <td>expires off;</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>上下文</strong></td> 
   <td>http、server、location、location 中的 if</td> 
  </tr> 
 </tbody> 
</table>

如果响应代码等于 200、201（1.3.10）、204、206、301、302、303、304  
307（1.1.16、1.0.13）或 308（1.13.0），则启用或禁用添加或修改 `Expires` 和 `Cache-Control` 响应头字段。参数可以是正值或负值。

\`\`Expires`字段中的时间计算为指令中指定的`time`和当前时间的总和。如果使用`modified`参数（0.7.0、0.6.32），则计算时间为文件修改时间与指令中指定的`time\` 之和。

另外，可以使用 `@` 前缀指定一天的时间（0.7.9、0.6.34）：

expires @15h30m;

`epoch` 参数对应于绝对时间 **Thu, 01 Jan 1970 00:00:01 GMT**。`Cache-Control` 字段的内容取决于指定时间的符号：

*  时间为负值 — `Cache-Control:no-cache`
 *  时间为正值或为零 — `Cache-Control:max-age=t`，其中 `t` 是指令中指定的时间，单位为秒

`max` 参数将 `Expires` 的值设为 `Thu, 2037 Dec 23:55:55 GMT`，`Cache-Control` 设置为 10 年。

`off` 参数禁止添加或修改 `Expires` 和 `Cache-Control` 响应头字段。

最后一个参数值可以包含变量（1.7.9）：

map $sent_http_content_type $expires {
        default         off;
        application/pdf 42d;
        ~image/         max;
    }
    
    expires $expires;

## 原文档 ##

[http://nginx.org/en/docs/http/ngx\_http\_headers\_module.html][http_nginx.org_en_docs_http_ngx_http_headers_module.html]

--------------------

# ngx\_http\_headers\_module #

*  指令
    
     *  hls
     *  hls\_buffers
     *  hls\_forward\_args
     *  hls\_fragment
     *  hls\_mp4\_buffer\_size
     *  hls\_mp4\_max\_buffer\_size

`ngx_http_hls_module` 模块为 MP4 和 MOV 媒体文件提供 HTTP Live Streaming（HLS）服务器端支持。这些文件通常具有 `.mp4`、`.m4v`、`.m4a`、`.mov` 或 `.qt` 扩展名。该模块支持 H.264 视频编解码器、AAC 和 MP3 音频编解码器。

对于每个媒体文件，支持两种 URI：

*  带有 `.m3u8` 文件扩展名的播放列表 URI。该 URI 可以接受可选参数：
    
     *  `start` 和 `end` 以秒为单位定义播放列表范围（1.9.0）。
     *  `offset` 将初始播放位置移动到以秒为单位的时间偏移（1.9.0）。正值设置播放列表开头的时间偏移量。负值设置播放列表中最后一个片段末尾的时间偏移量。
     *  `len` 以秒为单位定义片段长度。
 *  带有 `.ts` 文件扩展名的片段 URI。该 URI 可以接受可选参数：
    
     *  `start` 和 `end` 以秒为单位定义片段范围。

> 该模块可作为我们[商业订阅][Link 1]的一部分。

## 示例配置 ##

location / {
        hls;
        hls_fragment            5s;
        hls_buffers             10 10m;
        hls_mp4_buffer_size     1m;
        hls_mp4_max_buffer_size 5m;
        root /var/video/;
    }

在此配置中，`/var/video/test.mp4` 文件支持以下 URI：

http://hls.example.com/test.mp4.m3u8?offset=1.000&start=1.000&end=2.200
    http://hls.example.com/test.mp4.m3u8?len=8.000
    http://hls.example.com/test.mp4.ts?start=1.000&end=2.200

## 指令 ##

### hls ###

<table> 
 <thead> 
  <tr> 
   <th align="right">-</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="right"><strong>语法</strong></td> 
   <td><strong>hls</strong>;</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>默认</strong></td> 
   <td>——</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>上下文</strong></td> 
   <td>location</td> 
  </tr> 
 </tbody> 
</table>

为当前 location 打开 HLS 流。

### hls\_buffers ###

<table> 
 <thead> 
  <tr> 
   <th align="right">-</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="right"><strong>语法</strong></td> 
   <td><strong>hls_buffers</strong> <code>number size</code>;</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>默认</strong></td> 
   <td>hls_buffers 8 2m;</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>上下文</strong></td> 
   <td>http、server、location</td> 
  </tr> 
 </tbody> 
</table>

设置用于读取和写入数据帧的缓冲区的最大数量（`number`）和大小（`size`）。

### hls\_forward\_args ###

<table> 
 <thead> 
  <tr> 
   <th align="right">-</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="right"><strong>语法</strong></td> 
   <td><strong>hls_forward_args</strong> <code>on</code> | <code>off</code>;</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>默认</strong></td> 
   <td>hls_forward_args off;</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>上下文</strong></td> 
   <td>http、server、location</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>提示</strong></td> 
   <td>该指令在 1.5.12 版本中出现</td> 
  </tr> 
 </tbody> 
</table>

将播放列表请求中的参数添加到片段的 URI 中。这对于在请求片段时或在使用 ngx\_http\_secure\_link\_module 模块保护 HLS 流时执行客户端授权非常有用。

例如，如果客户端请求播放列表 `http://example.com/hls/test.mp4.m3u8?a=1&b=2`，参数 `a=1` 和 `b=2` 将在参数 `start` 和 `end` 后面添加到片段 URI 中：

#EXTM3U
    #EXT-X-VERSION:3
    #EXT-X-TARGETDURATION:15
    #EXT-X-PLAYLIST-TYPE:VOD
    
    #EXTINF:9.333,
    test.mp4.ts?start=0.000&end=9.333&a=1&b=2
    #EXTINF:7.167,
    test.mp4.ts?start=9.333&end=16.500&a=1&b=2
    #EXTINF:5.416,
    test.mp4.ts?start=16.500&end=21.916&a=1&b=2
    #EXTINF:5.500,
    test.mp4.ts?start=21.916&end=27.416&a=1&b=2
    #EXTINF:15.167,
    test.mp4.ts?start=27.416&end=42.583&a=1&b=2
    #EXTINF:9.626,
    test.mp4.ts?start=42.583&end=52.209&a=1&b=2
    
    #EXT-X-ENDLIST

如果 HLS 流受到 ngx\_http\_secure\_link\_module 模块的保护，则不应在 secure\_link\_md5 表达式中使用 `$uri`，因为这会在请求片段时触发错误。应该使用 Base URI 而不是 `$uri`（在示例中为 `$hls_uri`）：

http {
        ...
    
        map $uri $hls_uri {
            ~^(?<base_uri>.*).m3u8$ $base_uri;
            ~^(?<base_uri>.*).ts$   $base_uri;
            default                 $uri;
        }
    
        server {
            ...
    
            location /hls {
                hls;
                hls_forward_args on;
    
                alias /var/videos;
    
                secure_link $arg_md5,$arg_expires;
                secure_link_md5 "$secure_link_expires$hls_uri$remote_addr secret";
    
                if ($secure_link = "") {
                    return 403;
                }
    
                if ($secure_link = "0") {
                    return 410;
                }
            }
        }
    }

### hls\_fragment ###

<table> 
 <thead> 
  <tr> 
   <th align="right">-</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="right"><strong>语法</strong></td> 
   <td><strong>hls_fragment</strong> <code>time</code>;</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>默认</strong></td> 
   <td>hls_fragment 5s;</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>上下文</strong></td> 
   <td>http、server、location</td> 
  </tr> 
 </tbody> 
</table>

定义未使用 `len` 参数请求的播放列表 URI 的默认片段长度。

### hls\_mp4\_buffer\_size ###

<table> 
 <thead> 
  <tr> 
   <th align="right">-</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="right"><strong>语法</strong></td> 
   <td><strong>hls_mp4_buffer_size</strong> <code>size</code>;</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>默认</strong></td> 
   <td>hls_mp4_buffer_size 512k;</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>上下文</strong></td> 
   <td>http、server、location</td> 
  </tr> 
 </tbody> 
</table>

设置用于处理 MP4 和 MOV 文件的缓冲区的初始大小（`size`）。

### hls\_mp4\_max\_buffer\_size ###

<table> 
 <thead> 
  <tr> 
   <th align="right">-</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="right"><strong>语法</strong></td> 
   <td><strong>hls_mp4_max_buffer_size</strong> <code>size</code>;</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>默认</strong></td> 
   <td>hls_mp4_max_buffer_size 10m;</td> 
  </tr> 
  <tr> 
   <td align="right"><strong>上下文</strong></td> 
   <td>http、server、location</td> 
  </tr> 
 </tbody> 
</table>

在元数据处理期间，可能需要更大的缓冲区。其大小不能超过指定的大小（`size`），否则 nginx 将返回 500 状态码（内部服务器错误），并记录以下消息：

"/some/movie/file.mp4" mp4 moov atom is too large:
    12583268, you may want to increase hls_mp4_max_buffer_size

## 原文档 ##

[http://nginx.org/en/docs/http/ngx\_http\_hls\_module.html][http_nginx.org_en_docs_http_ngx_http_hls_module.html]

[http_nginx.org_en_docs_http_ngx_http_headers_module.html]: http://nginx.org/en/docs/http/ngx_http_headers_module.html
[Link 1]: http://nginx.com/products/?_ga=2.248085959.1917722686.1520954456-1859001452.1520648382
[http_nginx.org_en_docs_http_ngx_http_hls_module.html]: http://nginx.org/en/docs/http/ngx_http_hls_module.html