Apache HTTP Server 网关应用 Docker 镜像文档

1. 镜像概述和主要用途

本镜像基于 Apache HTTP Server 构建，定位为轻量级网关应用，旨在提供高性能、可扩展的 HTTP/HTTPS 流量管理能力。主要用途包括反向代理、负载均衡、API 路由、SSL/TLS 终止及流量控制，适用于多服务架构下的统一入口管理场景。

2. 核心功能和特性

2.1 核心功能

• 反向代理：将客户端请求转发至后端服务，隐藏后端架构细节，提升安全性。
• 负载均衡：支持多种负载均衡策略（轮询、权重、IP 哈希等），分发流量至多个后端实例，提高系统可用性。
• SSL/TLS 终止：集中处理 HTTPS 加密解密，减轻后端服务负担，统一管理 SSL 证书。
• URL 重写：基于规则重写请求 URL，支持路径映射、参数调整等场景。
• 缓存机制：缓存静态资源或频繁访问的响应，减少后端服务压力，提升响应速度。

2.2 关键特性

• 模块化架构：支持 Apache 丰富的模块扩展（如 mod_proxy、mod_ssl、mod_rewrite 等）。
• 灵活配置：支持通过环境变量或自定义配置文件调整行为，无需重新构建镜像。
• 日志记录：内置完善的访问日志和错误日志机制，支持日志格式自定义。
• 轻量高效：基于官方 Apache 镜像优化，体积小、启动快，资源占用低。

3. 使用场景和适用范围

3.1 典型使用场景

• 微服务 API 网关：作为微服务架构的统一入口，路由不同 API 请求至对应的后端服务。
• 多服务反向代理：为前端应用、静态资源服务、后端 API 等多类服务提供统一访问域名/端口。
• 负载均衡部署：在多实例部署场景中，分发流量至后端服务集群，避免单点故障。
• SSL 终止：集中管理 HTTPS 证书，为无 SSL 能力的后端服务提供 HTTPS 访问支持。
• 静态资源缓存：缓存 CDN 回源内容或本地静态资源（如图片、JS、CSS），提升访问速度。

3.2 适用范围

• 中小规模分布式系统的流量入口管理。
• 需要快速部署、低维护成本的网关场景。
• 依赖 Apache 生态模块（如特定认证、过滤模块）的业务需求。

4. 使用方法和配置说明

4.1 基本使用（docker run）

4.1.1 快速启动（默认配置）

默认配置启用反向代理至示例后端服务，可直接运行：

docker run -d -p 80:80 --name apache-gateway apache-gateway:latest

4.1.2 自定义端口和后端服务

通过环境变量指定端口及后端服务地址：

docker run -d \
  -p 8080:80 \  # 映射容器 80 端口至主机 8080
  -e HTTP_PORT=80 \  # 容器内 HTTP 服务端口（默认 80）
  -e BACKEND_SERVICE_URL=[***] \  # 后端服务地址
  --name apache-gateway \
  apache-gateway:latest

4.2 Docker Compose 配置示例

适用于多服务协同部署场景，示例 docker-compose.yml：

version: '3.8'

services:
  apache-gateway:
    image: apache-gateway:latest
    container_name: apache-gateway
    ports:
      - "80:80"    # HTTP 端口
      - "443:443"  # HTTPS 端口（若启用）
    environment:
      - HTTP_PORT=80
      - HTTPS_PORT=443
      - BACKEND_SERVICE_URL=[***]  # 后端服务地址（需与后端服务名一致）
      - SSL_ENABLE=true  # 启用 HTTPS
      - SSL_CERT_PATH=/etc/apache2/ssl/cert.pem  # SSL 证书路径（容器内）
      - SSL_KEY_PATH=/etc/apache2/ssl/key.pem    # SSL 私钥路径（容器内）
    volumes:
      - ./conf/httpd.conf:/etc/apache2/httpd.conf  # 挂载自定义主配置文件
      - ./ssl:/etc/apache2/ssl  # 挂载 SSL 证书目录（宿主机 ./ssl 包含 cert.pem 和 key.pem）
      - ./logs:/var/log/apache2  # 挂载日志目录（持久化日志）
    depends_on:
      - backend  # 依赖后端服务启动

  backend:  # 示例后端服务
    image: nginx:alpine
    container_name: backend-service
    ports:
      - "8080:80"

4.3 环境变量说明

通过环境变量可快速调整网关核心配置，无需修改配置文件：

4.4 自定义配置

4.4.1 挂载配置文件

Apache 核心配置文件为 httpd.conf，通过挂载宿主机配置文件覆盖默认配置：

docker run -d \
  -p 80:80 \
  -v /path/on/host/httpd.conf:/etc/apache2/httpd.conf \  # 挂载主配置
  -v /path/on/host/extra:/etc/apache2/extra \  # 挂载额外配置（如 vhosts.conf）
  --name apache-gateway \
  apache-gateway:latest

4.4.2 扩展模块

如需启用额外模块（如 mod_headers、mod_deflate），可在自定义 httpd.conf 中添加：

LoadModule headers_module modules/mod_headers.so
LoadModule deflate_module modules/mod_deflate.so

4.5 持久化数据

4.5.1 日志持久化

挂载日志目录至宿主机，避免容器重启后日志丢失：

docker run -d \
  -p 80:80 \
  -v /path/on/host/logs:/var/log/apache2 \  # 挂载日志目录
  --name apache-gateway \
  apache-gateway:latest

4.5.2 SSL 证书持久化

将 SSL 证书文件存储在宿主机，并挂载至容器：

docker run -d \
  -p 443:443 \
  -e SSL_ENABLE=true \
  -v /path/on/host/ssl:/etc/apache2/ssl \  # 挂载证书目录（包含 cert.pem 和 key.pem）
  --name apache-gateway \
  apache-gateway:latest

5. 配置示例

5.1 反向代理 + SSL 终止配置（docker-compose）

以下示例实现：将 HTTPS 请求（443 端口）反向代理至后端 HTTP 服务（backend:8080），并启用日志持久化。

version: '3.8'

services:
  apache-gateway:
    image: apache-gateway:latest
    container_name: apache-gateway
    ports:
      - "443:443"
    environment:
      - HTTPS_PORT=443
      - SSL_ENABLE=true
      - BACKEND_SERVICE_URL=[***]
      - LOG_LEVEL=info
    volumes:
      - ./ssl:/etc/apache2/ssl  # 宿主机 ./ssl 目录包含 cert.pem 和 key.pem
      - ./logs:/var/log/apache2  # 日志持久化
      - ./conf/extra/vhosts.conf:/etc/apache2/extra/vhosts.conf  # 自定义虚拟主机配置
    depends_on:
      - backend

  backend:
    image: nginx:alpine
    container_name: backend-service
    ports:
      - "8080:80"
    volumes:
      - ./backend/html:/usr/share/nginx/html  # 后端静态资源

自定义虚拟主机配置（./conf/extra/vhosts.conf）：

<VirtualHost *:443>
    ServerName gateway.example.com
    ProxyPass / [***]
    ProxyPassReverse / [***]
    
    SSLEngine on
    SSLCertificateFile "/etc/apache2/ssl/cert.pem"
    SSLCertificateKeyFile "/etc/apache2/ssl/key.pem"
    
    # 启用压缩
    AddOutputFilterByType DEFLATE text/html text/css application/json
</VirtualHost>

6. 注意事项

• 权限问题：挂载宿主机文件/目录时，需确保容器内用户（通常为 www-data）对挂载资源有读权限，建议宿主机目录权限设置为 755，文件权限 644。
• 配置验证：启动前可通过 docker run --rm apache-gateway:latest httpd -t 验证配置文件语法正确性。
• 资源限制：生产环境建议通过 --memory、--cpus 限制容器资源，避免过度占用主机资源。
• 模块兼容性：自定义模块时需确保与 Apache 版本兼容（可通过 docker run --rm apache-gateway:latest httpd -v 查看 Apache 版本）。