Apache HTTP Server 完全指南 / 配置文件结构与指令

配置文件结构与指令

Apache 的配置系统是其强大灵活性的基础。理解配置文件的结构、指令和作用域对于有效管理 Apache 至关重要。

1. 配置文件层次结构

1.1 主配置文件

发行版	主配置文件路径
Debian/Ubuntu	`/etc/apache2/apache2.conf`
CentOS/RHEL	`/etc/httpd/conf/httpd.conf`
源码编译	`/usr/local/apache2/conf/httpd.conf`
macOS (Homebrew)	`/usr/local/etc/httpd/httpd.conf`

1.2 配置文件组织

Debian/Ubuntu 风格：

/etc/apache2/
├── apache2.conf          # 主配置文件
├── ports.conf            # 端口配置
├── envvars               # 环境变量
├── magic                 # MIME 魔术规则
├── conf-available/       # 可用配置片段
├── conf-enabled/         # 启用配置片段 -> 符号链接
├── mods-available/       # 可用模块配置
├── mods-enabled/         # 启用模块配置 -> 符号链接
├── sites-available/      # 可用虚拟主机
└── sites-enabled/        # 启用虚拟主机 -> 符号链接

CentOS/RHEL 风格：

/etc/httpd/
├── conf/
│   └── httpd.conf        # 主配置文件
├── conf.d/               # 额外配置文件
├── conf.modules.d/       # 模块配置
└── modules/              # 模块链接

1.3 配置文件包含

# 包含其他配置文件
Include /etc/apache2/ports.conf
IncludeOptional /etc/apache2/conf-enabled/*.conf
IncludeOptional /etc/apache2/sites-enabled/*.conf

# 条件包含
<IfDefine !ENVVAR>
    Include /etc/apache2/custom.conf
</IfDefine>

# 相对路径包含
Include conf/extra/httpd-info.conf

2. 指令（Directives）详解

2.1 指令语法

# 基本语法
DirectiveName value

# 多值指令
AddType application/x-httpd-php .php .phtml

# 布尔指令
Options Indexes FollowSymLinks

# 注释
# 这是注释

2.2 核心指令

服务器标识指令

# 服务器版本信息
ServerTokens Prod
# Prod: Server: Apache
# Major: Server: Apache/2
# Minor: Server: Apache/2.4
# OS: Server: Apache/2.4.58 (Ubuntu)
# Full: Server: Apache/2.4.58 (Ubuntu) PHP/8.2.0

ServerAdmin admin@example.com
ServerName www.example.com:80
ServerRoot "/etc/apache2"

网络指令

# 监听端口
Listen 80
Listen 443
Listen 192.168.1.100:8080
Listen [::1]:80

# 超时设置
Timeout 300
KeepAlive On
MaxKeepAliveRequests 100
KeepAliveTimeout 5

# 运行用户/组 (Linux)
User www-data
Group www-data

文档根目录

DocumentRoot "/var/www/html"

# 目录索引
DirectoryIndex index.html index.php index.htm

2.3 指令作用域

Apache 指令可以存在于不同的作用域中：

作用域	描述	示例
服务器配置	全局有效	`ServerName`
虚拟主机	特定虚拟主机	`<VirtualHost>`
目录	特定目录	`<Directory>`
文件	特定文件	`<Files>`
位置	特定 URL	`<Location>`
.htaccess	分布式配置	`AllowOverride`

3. 作用域（Containers）

3.1 `<Directory>` 容器

# 匹配文件系统目录
<Directory "/var/www/html">
    Options Indexes FollowSymLinks
    AllowOverride All
    Require all granted
</Directory>

# 正则表达式匹配
<DirectoryMatch "^/var/www/(?!html)">
    Require all denied
</DirectoryMatch>

# 嵌套目录
<Directory "/var/www">
    # /var/www 的配置
    <Directory "/var/www/html">
        # /var/www/html 的配置（覆盖父级）
    </Directory>
</Directory>

3.2 `<Files>` 容器

# 匹配特定文件
<Files "favicon.ico">
    Require all granted
</Files>

# 正则表达式匹配
<FilesMatch "\.(gif|jpe?g|png)$">
    # 图片文件配置
</FilesMatch>

# 保护敏感文件
<FilesMatch "^\.ht">
    Require all denied
</FilesMatch>

3.3 `<Location>` 容器

# 匹配 URL 路径
<Location "/admin">
    AuthType Basic
    AuthName "Admin Area"
    AuthUserFile /etc/apache2/.htpasswd
    Require valid-user
</Location>

# 正则表达式匹配
<LocationMatch "^/api/v[0-9]+/">
    # API 版本配置
</LocationMatch>

# 反向代理
<Location "/app">
    ProxyPass "http://localhost:8080/"
    ProxyPassReverse "http://localhost:8080/"
</Location>

3.4 `<VirtualHost>` 容器

# 基于域名的虚拟主机
<VirtualHost *:80>
    ServerName www.example.com
    DocumentRoot /var/www/example
</VirtualHost>

# 基于 IP 的虚拟主机
<VirtualHost 192.168.1.100:80>
    ServerName www.example.com
    DocumentRoot /var/www/example
</VirtualHost>

3.5 容器合并规则

配置按以下顺序合并（后者覆盖前者）：

主服务器配置
<Directory> (按路径长度)
.htaccess
<Files> / <FilesMatch>
<Location> / <LocationMatch>

# 合并示例
<Directory "/var/www">
    # 1. 先应用此配置
    Options Indexes
</Directory>

<Directory "/var/www/html">
    # 2. 再应用此配置（覆盖）
    Options -Indexes +FollowSymLinks
</Directory>

<Files "secret.txt">
    # 3. 最后应用此配置
    Require all denied
</Files>

4. 条件配置

4.1 `<IfDefine>`

# 根据启动参数条件配置
# 启动时：httpd -DDEBUG

<IfDefine DEBUG>
    LogLevel debug
    ErrorLog logs/debug.log
</IfDefine>

<IfDefine !DEBUG>
    LogLevel warn
</IfDefine>

4.2 `<IfModule>`

# 检查模块是否加载
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteRule ^(.*)$ https://%{HTTP_HOST}$1 [R=301,L]
</IfModule>

<IfModule !mod_ssl.c>
    # SSL 模块未加载时的配置
    Redirect /secure http://www.example.com
</IfModule>

4.3 `<IfVersion>`

# 根据 Apache 版本条件配置
<IfVersion >= 2.4>
    # Apache 2.4+ 配置
    Require all granted
</IfVersion>

<IfVersion < 2.4>
    # Apache 2.2 配置
    Order allow,deny
    Allow from all
</IfVersion>

4.4 `<If>`

# Apache 2.4+ 动态条件
<If "req('Host') == 'www.example.com'">
    # 特定主机配置
</If>

<If "-T -d '%{REQUEST_FILENAME}'">
    # 目录请求配置
</If>

5. 环境变量

5.1 设置环境变量

# 使用 SetEnv
SetEnv APP_ENV production
SetEnv DB_HOST localhost

# 使用 PassEnv（传递系统环境变量）
PassEnv HOME
PassEnv LANG

# 使用 SetEnvIf
SetEnvIf User-Agent "Mobile" mobile_device
SetEnvIf Request_URI "\.pdf$" pdf_request

5.2 使用环境变量

# 条件配置
<If "env('APP_ENV') == 'production'">
    LogLevel warn
</If>

# 自定义日志格式
CustomLog logs/access.log "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\""

# 条件重写
RewriteCond %{ENV:mobile_device} 1
RewriteRule ^(.*)$ /mobile/$1 [L]

6. 配置测试与调试

6.1 测试配置语法

# 测试配置
apachectl configtest
# 或
apache2ctl configtest

# 输出：
# Syntax OK
# 或显示错误信息和行号

6.2 查看解析后的配置

# 显示所有虚拟主机配置
apachectl -S
# 或
httpd -S

# 显示编译时设置
apachectl -V

# 显示加载的模块
apachectl -M

# 显示编译的模块
apachectl -l

6.3 转储配置

# 转储所有配置指令
apachectl -t -D DUMP_RUN_CFG

# 转储模块列表
apachectl -t -D DUMP_MODULES

# 转储包含的文件
apachectl -t -D DUMP_INCLUDES

6.4 使用 mod_info

# 启用 mod_info
LoadModule info_module modules/mod_info.so

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

访问 http://localhost/server-info 查看详细配置信息。

7. 业务场景

7.1 多环境配置管理

# /etc/apache2/envvars
export APP_ENV="production"

# 主配置中使用
<If "%{ENV:APP_ENV} == 'development'">
    LogLevel debug
    ErrorLog logs/dev-error.log
</If>
<Else>
    LogLevel warn
    ErrorLog logs/error.log
</Else>

7.2 安全配置模板

# /etc/apache2/conf-available/security.conf
ServerTokens Prod
ServerSignature Off

<Directory />
    Options -Indexes -FollowSymLinks
    AllowOverride None
    Require all denied
</Directory>

<Directory "/var/www/html">
    Options -Indexes +FollowSymLinks
    AllowOverride None
    Require all granted
</Directory>

# 保护敏感文件
<FilesMatch "^\.">
    Require all denied
</FilesMatch>

<FilesMatch "\.(conf|log|bak|sql|sh)$">
    Require all denied
</FilesMatch>

7.3 性能配置模板

# /etc/apache2/conf-available/performance.conf
<IfModule mpm_event_module>
    StartServers             3
    MinSpareThreads         75
    MaxSpareThreads        250
    ThreadsPerChild         25
    MaxRequestWorkers      400
    MaxConnectionsPerChild 10000
</IfModule>

<IfModule mod_expires.c>
    ExpiresActive On
    ExpiresByType text/css "access plus 1 year"
    ExpiresByType application/javascript "access plus 1 year"
    ExpiresByType image/jpeg "access plus 1 year"
    ExpiresByType image/png "access plus 1 year"
</IfModule>

8. 注意事项

配置备份：修改配置前务必备份原文件
语法检查：修改后始终运行 apachectl configtest
重启服务：大部分配置修改需要重启服务生效
.htaccess 性能：生产环境建议禁用 .htaccess，使用主配置
指令冲突：注意不同作用域的指令合并规则

9. 扩展阅读

10. 总结

Apache 的配置系统提供了极大的灵活性：

模块化：配置文件可以按功能分割
层次化：不同作用域的配置可以合并
条件化：可以根据环境和模块动态配置
可测试：提供了丰富的配置调试工具

理解配置文件结构是有效管理 Apache 的基础。