SpeedVideo 配置参数详解

目标：逐项讲清 SpeedVideo 视频测试源服务器（Apache HTTP Server 2.4.69 承载）的全部关键配置——监听端口、虚拟主机、MIME 映射、缓存策略、CORS、限速、鉴权、TLS、日志与状态页。每个参数均给出配置块、改法与修改后的验证命令 + 实测回显，已在 Ubuntu 24.04 服务器上逐项实测通过。环境搭建见本专栏《SpeedVideo Docker Compose 部署指南》，本篇不重复安装过程。

一、环境信息

操作系统：Ubuntu 24.04.5 LTS（x86_64）
服务进程：Apache HTTP Server 2.4.69（Unix），MPM 为 event，OpenSSL 3.5.7
安装前缀：/usr/local/apache2/；站点根 /usr/local/apache2/htdocs；站点配置 conf/extra/speedvideo.conf
监听端口：HTTP 8080、HTTPS 8443
验证客户端：curl 8.5.0、FFmpeg/ffprobe 7.0.2、OpenSSL 3.x

二、前置条件

测试源服务已启动，curl -s http://127.0.0.1:8080/healthz.txt 返回 ok；
对配置文件有编辑权限，且能执行 apachectl -t（语法检查）与 apachectl graceful（平滑重载）；
本文所有验证命令均在本机回环地址执行；远程执行时把 127.0.0.1 换成服务器 IP 即可。

三、参数查看与修改方式

修改任何参数遵循同一条闭环：改配置 → 语法检查 → 平滑重载 → 验证回显。

$ apachectl -t
Syntax OK
$ apachectl graceful        # 平滑重载，不断开已有连接
（无输出即成功）

查看当前生效的虚拟主机与关键模块：

$ apachectl -S
VirtualHost configuration:
*:8080                 speedvideo.local (/usr/local/apache2/conf/extra/speedvideo.conf:1)
ServerRoot: "/usr/local/apache2"
Main DocumentRoot: "/usr/local/apache2/htdocs"
User: name="www-data" id=33
Group: name="www-data" id=33

$ httpd -M | grep -E "headers|status|ssl|ratelimit|mime"
 auth_basic_module (shared)
 mime_module (shared)
 headers_module (shared)
 status_module (shared)

⚠️ 注意：apachectl -S 输出若伴随 AH00558: httpd: Could not reliably determine the server's fully qualified domain name 警告，说明全局 ServerName 未生效；在主配置写入 ServerName speedvideo.local 并重载即可消除。

四、参数总览

分类	参数	当前值	所在文件
监听	`Listen`	`8080` / `8443`	httpd.conf
全局	`ServerName`	`speedvideo.local`	httpd.conf
虚拟主机	`<VirtualHost>`	`:8080`（HTTP）、`:8443`（HTTPS）	speedvideo.conf
目录	`Options` / `AllowOverride` / `Require`	`-Indexes +FollowSymLinks` / `None` / `all granted`	speedvideo.conf
MIME	`AddType`	m3u8→`application/vnd.apple.mpegurl`、ts→`video/mp2t`、mp4→`video/mp4`	speedvideo.conf
跨域	`Header set Access-Control-Allow-Origin`	`*`	speedvideo.conf
缓存	`Cache-Control`	m3u8 `max-age=1, must-revalidate`；ts `max-age=10`；mp4 `max-age=60`	speedvideo.conf
缓存校验	`FileETag`	默认（INode+MTime+Size）	httpd.conf
连接	`KeepAlive` / `KeepAliveTimeout` / `MaxKeepAliveRequests`	`On` / `5` / `100`	httpd.conf
限速	`SetOutputFilter RATE_LIMIT` + `SetEnv rate-limit`	2160p 档限速 2000 KB/s	speedvideo.conf
鉴权	`AuthType Basic` + `AuthUserFile`	`/secure/` 目录，账号 root	speedvideo.conf
TLS	`SSLProtocol` / `SSLCipherSuite` / HSTS	仅 TLS1.2/1.3 / `HIGH:!aNULL:!MD5` / `max-age=31536000`	speedvideo.conf
日志	`ErrorLog` / `CustomLog` / `LogLevel`	`logs/sv_error.log`、`logs/sv_access.log`、默认 `warn`	speedvideo.conf / httpd.conf
状态页	`SetHandler server-status`	`/status`，仅 127.0.0.1	speedvideo.conf

五、核心参数分类详解

5.1 监听端口与 ServerName

主配置中的监听与全局名：

ServerName speedvideo.local
Listen 8080
Listen 8443

Listen 决定服务进程绑定端口；改成其他端口后需同步调整访问 URL；
全局 ServerName 消除 AH00558 警告，并作为自引用跳转的规范主机名。

验证（实测回显）：

$ ss -ltn | grep -E '8080|8443'
LISTEN 0 4096 0.0.0.0:8080 0.0.0.0:*
LISTEN 0 4096 0.0.0.0:8443 0.0.0.0:*
$ curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/healthz.txt
200

5.2 DocumentRoot 与目录权限

DocumentRoot "/usr/local/apache2/htdocs"
<Directory "/usr/local/apache2/htdocs">
    Options -Indexes +FollowSymLinks
    AllowOverride None
    Require all granted
</Directory>

-Indexes：禁止目录列表。实测对目录发起请求返回 403：

$ curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/clips/
403
$ curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/nope
404

调试期若需浏览片源列表，把 -Indexes 改成 +Indexes 并重载，实测目录页返回 200，页面中可列出全部片源文件名（sv-1080p-3000k.mp4、sv-2160p-12000k.mp4 等）；调完改回 -Indexes；
AllowOverride None：禁止 .htaccess 覆盖，配置集中可控，也省去每请求读盘开销；
Require all granted：公开测试源；需要收紧时改成 Require ip 10.0.0.0/8 之类的网段白名单。

错误日志中对 403 的解释实录（定位目录索引被拒时很有用）：

[autoindex:error] AH01276: Cannot serve directory /usr/local/apache2/htdocs/clips/: No matching DirectoryIndex (index.html) found, and server-generated directory index forbidden by Options directive

5.3 MIME 类型映射（HLS 播放的生死线）

AddType application/vnd.apple.mpegurl .m3u8
AddType video/mp2t .ts
AddType video/mp4 .mp4

三个映射逐项实测的响应头：

$ curl -sI http://127.0.0.1:8080/hls/sv-1080p/index.m3u8 | grep -i content-type
Content-Type: application/vnd.apple.mpegurl
$ curl -sI http://127.0.0.1:8080/hls/sv-1080p/seg_000.ts | grep -i content-type
Content-Type: video/mp2t
$ curl -sI http://127.0.0.1:8080/clips/sv-1080p-5000k.mp4 | grep -i content-type
Content-Type: video/mp4

漏配 .m3u8 映射时响应会退化为 application/octet-stream，Safari 与 hls.js 都会拒绝解析——这是 HLS 测试源最常见的部署缺陷。

5.4 CORS 跨域头

Header set Access-Control-Allow-Origin "*"

Web 播放器（hls.js/video.js 页内播放器）从其他域拉流时必须。实测带 Origin 头的请求响应：

$ curl -s -D - -o /dev/null -H "Origin: http://example.com" http://127.0.0.1:8080/clips/sv-1080p-3000k.mp4
HTTP/1.1 200 OK
Server: Apache/2.4.69 (Unix)
Accept-Ranges: bytes
Content-Length: 8061820
Access-Control-Allow-Origin: *
Cache-Control: max-age=60
Content-Type: video/mp4

生产环境若测试页面来源固定，可把 * 收紧为具体源，如 Header set Access-Control-Allow-Origin "https://player.example.com"。

5.5 缓存策略（FilesMatch 分级）

<FilesMatch "\.m3u8$">
    Header set Cache-Control "max-age=1, must-revalidate"
</FilesMatch>
<FilesMatch "\.ts$">
    Header set Cache-Control "max-age=10"
</FilesMatch>
<FilesMatch "\.mp4$">
    Header set Cache-Control "max-age=60"
</FilesMatch>

设计理由：HLS 清单必须近乎实时（1 秒 + 强制再验证），分片与 MP4 允许短缓存降低重复回源。三类响应头实测已分别在 5.3 与部署篇回显中体现（Cache-Control: max-age=1, must-revalidate / max-age=10 / max-age=60）。

5.6 ETag 与条件请求

默认 FileETag（INode+MTime+Size）参与生成 ETag，客户端可用 If-None-Match 做 304 校验。实测：

$ curl -sI http://127.0.0.1:8080/clips/sv-720p-2500k.mp4 | grep -i etag
ETag: "682bda-65ea5ff1d9ac2"
$ curl -s -o /dev/null -w "%{http_code}\n" -H 'If-None-Match: "682bda-65ea5ff1d9ac2"' http://127.0.0.1:8080/clips/sv-720p-2500k.mp4
304

片源每次重新生成会改变 INode 导致 ETag 变化；若希望 ETag 只随内容大小/时间变，可在主配置加 FileETag MTime Size。实测极端写法 FileETag None 重载后响应头不再携带 ETag（curl -sI ... | grep -i etag 无输出），不建议测试源使用——失去 304 校验能力。

5.7 KeepAlive 长连接

KeepAlive On
KeepAliveTimeout 5
MaxKeepAliveRequests 100

HLS 客户端会在几十秒内顺序拉 10 个分片，长连接避免每分片一次 TCP 握手。实测 KeepAlive On 时 curl 复用连接：

* Connected to 127.0.0.1 (127.0.0.1) port 8080
* Re-using existing connection with host 127.0.0.1

对照实验：改 KeepAlive Off 重载后，同一命令每次请求都新建连接，且响应头出现 Connection: close：

$ curl -sI http://127.0.0.1:8080/healthz.txt | grep -i connection
Connection: close

测试源务必保持 KeepAlive On（测完已改回）。

5.8 限速参数（mod_ratelimit，弱网模拟核心）

<Location "/clips/sv-2160p-12000k.mp4">
    SetOutputFilter RATE_LIMIT
    SetEnv rate-limit 2000
</Location>

rate-limit 单位是 KB/s，只对该 Location 生效。用途：模拟弱网/拥塞，验证播放器缓冲策略与 SpeedVideo 类客户端的卡顿统计。实测限速效果（31MB 文件，限速 2000 KB/s ≈ 16Mbps）：

$ curl -s -o /dev/null -w "time=%{time_total}s speed=%{speed_download}B/s\n" http://127.0.0.1:8080/clips/sv-2160p-12000k.mp4
time=15.046049s speed=2068563B/s

31.1MB ÷ 2068563B/s ≈ 15.0s，与实测耗时吻合。调整建议：模拟 4G 单用户好体验用 rate-limit 30000（约 240Mbps），模拟拥塞用 2000，模拟极差网络用 512。

5.9 Basic 鉴权（受限片源）

<Location "/secure/">
    AuthType Basic
    AuthName "SpeedVideo Test Source"
    AuthUserFile "/usr/local/apache2/conf/extra/.htpasswd"
    Require valid-user
</Location>

账号文件用 bcrypt 生成（演示账号 root，密码 q1w2e3r4）：

$ htpasswd -nbB root q1w2e3r4
root:$2y$05$uoy4Lfk/UOgE3h88I5wHOu3yEAmrcS8W5bqrshZwIpthyMSuG2efm

💡 技术拓展：HTTP 鉴权方式不止 Basic。常见选项——

方式特点适用
Basic 明文 Base64，需配合 HTTPS 内网测试、简单门禁
Digest 挑战-应答摘要，不明文传密无法上 TLS 的遗留场景
Bearer Token / OAuth2 令牌化、可过期可撤销对外 API、生产系统

本文采用 Basic：测试源在内网使用、且 HTTPS 侧可用，满足「验证客户端鉴权播放能力」的目标即可。

方式	特点	适用
Basic	明文 Base64，需配合 HTTPS	内网测试、简单门禁
Digest	挑战-应答摘要，不明文传密	无法上 TLS 的遗留场景
Bearer Token / OAuth2	令牌化、可过期可撤销	对外 API、生产系统

三段式验证（实测）：

$ curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/secure/auth-check.txt
401
$ curl -s -D - -o /dev/null http://127.0.0.1:8080/secure/auth-check.txt
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="SpeedVideo Test Source"
$ curl -s -u root:q1w2e3r4 -w "\n%{http_code}\n" http://127.0.0.1:8080/secure/auth-check.txt
authenticated

200

未带凭据返回 401 且携带 WWW-Authenticate 挑战头；带正确凭据返回 200 与文件内容 authenticated。

5.10 TLS 证书与协议版本

SSLEngine on
SSLCertificateFile "/usr/local/apache2/conf/extra/tls/sv.crt"
SSLCertificateKeyFile "/usr/local/apache2/conf/extra/tls/sv.key"
SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
SSLCipherSuite HIGH:!aNULL:!MD5
Header always set Strict-Transport-Security "max-age=31536000"

证书信息实测：

$ openssl x509 -in /usr/local/apache2/conf/extra/tls/sv.crt -noout -subject -issuer -dates -ext subjectAltName
subject=C = CN, ST = Shanghai, L = Shanghai, O = SpeedVideo Lab, CN = speedvideo.local
issuer=C = CN, ST = Shanghai, L = Shanghai, O = SpeedVideo Lab, CN = speedvideo.local
notBefore=Oct 25 08:36:16 2026 GMT
notAfter=Oct 25 08:36:16 2027 GMT
X509v3 Subject Alternative Name:
    DNS:speedvideo.local, IP Address:127.0.0.1

协议版本逐项实测：

$ echo | openssl s_client -connect 127.0.0.1:8443 -tls1_3 2>/dev/null | grep -E "Cipher is"
New, TLSv1.3, Cipher is TLS_AES_256_GCM_SHA384
$ echo | openssl s_client -connect 127.0.0.1:8443 -tls1_2 2>/dev/null | grep -E "Cipher is"
New, TLSv1.2, Cipher is ECDHE-RSA-AES256-GCM-SHA384
$ echo | openssl s_client -connect 127.0.0.1:8443 -tls1_1 2>&1 | grep -E "no protocols" | head -1
error:0A0000BF:SSL routines:tls_setup_handshake:no protocols available

TLS1.3/1.2 正常握手，TLS1.1 被 SSLProtocol 禁用拒绝握手——符合预期。HTTPS 响应头中 Strict-Transport-Security: max-age=31536000 已生效（回显见部署篇 4.6 节）。

5.11 日志参数

ErrorLog "/usr/local/apache2/logs/sv_error.log"
CustomLog "/usr/local/apache2/logs/sv_access.log" "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\""

每个虚拟主机独立日志文件，避免与主站日志混杂；
CustomLog 格式含 %u（鉴权用户名）与 %{User-Agent}i（识别播放器/客户端类型），实测一条鉴权成功记录：

10.0.0.8 - root [25/Oct/2026:08:38:03 +0000] "GET /secure/auth-check.txt HTTP/1.1" 200 14 "-" "curl/8.5.0"

排障时把主配置 LogLevel 临时提到 debug，可看到授权判定过程实录：

[authz_core:debug] mod_authz_core.c(815): AH01626: authorization result of Require all granted: granted

排查完改回 warn，避免 debug 日志灌满磁盘。

5.12 状态页（server-status）

<Location "/status">
    SetHandler server-status
    Require ip 127.0.0.1
</Location>

仅本机可访问，外网无法探测服务器负载。实测：

$ curl -s "http://127.0.0.1:8080/status?auto" | head -12
127.0.0.1
ServerVersion: Apache/2.4.69 (Unix)
ServerMPM: event
Server Built: Oct 21 2026 00:17:29
ServerUptimeSeconds: 18
ServerUptime: 18 seconds
Load1: 1.47
Total Accesses: 2
Total kBytes: 0

💡 技术拓展：ServerMPM: event 是 Apache 三种 MPM（多路处理模块）之一——

MPM 模型适用
prefork 多进程、每进程一线程与非线程安全模块（如 mod_php）共存
worker 多进程多线程老版本通用场景
event worker + 独立监听线程，KeepAlive 不占工作线程高并发长连接（默认推荐）

测试源大量 KeepAlive 拉流连接，采用 event 可避免长连接耗尽工作线程。

MPM	模型	适用
prefork	多进程、每进程一线程	与非线程安全模块（如 mod_php）共存
worker	多进程多线程	老版本通用场景
event	worker + 独立监听线程，KeepAlive 不占工作线程	高并发长连接（默认推荐）

六、生产配置模板

适用场景：8GB 内存、千兆网卡、10~50 并发的内网视频体验测试（对齐官方套件 10 并发标定并留有余量）。以下为 speedvideo.conf 推荐全量配置，相对默认值的每处改动均有注释：

<VirtualHost *:8080>
    ServerName speedvideo.local          # 改成服务器实际主机名
    DocumentRoot "/usr/local/apache2/htdocs"
    <Directory "/usr/local/apache2/htdocs">
        Options -Indexes +FollowSymLinks  # 生产必须关目录索引
        AllowOverride None
        Require ip 10.0.0.0/8             # 生产建议收紧为内网网段（默认 all granted 仅适合临时调试）
    </Directory>
    AddType application/vnd.apple.mpegurl .m3u8   # 三个 MIME 映射缺一不可
    AddType video/mp2t .ts
    AddType video/mp4 .mp4
    Header set Access-Control-Allow-Origin "*"
    <FilesMatch "\.m3u8$">
        Header set Cache-Control "max-age=1, must-revalidate"
    </FilesMatch>
    <FilesMatch "\.ts$">
        Header set Cache-Control "max-age=10"
    </FilesMatch>
    <FilesMatch "\.mp4$">
        Header set Cache-Control "max-age=60"
    </FilesMatch>
    <Location "/clips/sv-2160p-12000k.mp4">
        SetOutputFilter RATE_LIMIT
        SetEnv rate-limit 2000            # 弱网模拟档位，按需调整（KB/s）
    </Location>
    <Location "/secure/">
        AuthType Basic
        AuthName "SpeedVideo Test Source"
        AuthUserFile "/usr/local/apache2/conf/extra/.htpasswd"
        Require valid-user
    </Location>
    <Location "/status">
        SetHandler server-status
        Require ip 127.0.0.1
    </Location>
    ErrorLog "/usr/local/apache2/logs/sv_error.log"
    CustomLog "/usr/local/apache2/logs/sv_access.log" "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\""
</VirtualHost>

配套主配置项：KeepAlive On / KeepAliveTimeout 5 / MaxKeepAliveRequests 100 / LogLevel warn；出口带宽按官方公式「并发用户数 × 单用户预期速率」估算（如 50 并发 × 25Mbps 高清测试 ≈ 1.25Gbps，需万兆或聚合链路）。

七、常见问题

Q1：改完配置没生效？ 先 apachectl -t 确认语法（应输出 Syntax OK），再确认执行了 apachectl graceful；Apache 不会自动感知文件变更。

Q2：m3u8 能下载但播放器不播？ 九成是 MIME 没配对，见 5.3 节验证命令；Content-Type 必须是 application/vnd.apple.mpegurl。

Q3：日志里大量 AH01276: Cannot serve directory ...？ 那是 -Indexes 拦截了目录访问（返回 403），属正常安全行为，见 5.2 节；若是有意提供目录列表再开 +Indexes。

Q4：8443 端口握手报 no protocols available？ 客户端强制用了 TLS1.1 及以下版本，已被 SSLProtocol 禁用；让客户端升级到 TLS1.2+，不要盲目放开老协议。

Q5：限速改了不生效？ rate-limit 只在匹配 <Location> 的 URL 上生效，确认请求的 URL 路径与 Location 完全一致（含大小写与文件名）。

八、参考链接

Apache 2.4 指令官方索引：https://httpd.apache.org/docs/2.4/mod/directives.html
mod_ratelimit 说明：https://httpd.apache.org/docs/2.4/mod/mod_ratelimit.html
mod_ssl 说明：https://httpd.apache.org/docs/2.4/mod/mod_ssl.html
MPM event 说明：https://httpd.apache.org/docs/2.4/mod/event.html