BunkerWeb项目本地开发环境配置指南

BunkerWeb作为一款基于Nginx的安全增强型Web服务器，在本地开发环境中的配置与生产环境有所不同。本文将详细介绍如何正确配置BunkerWeb用于本地开发环境，特别是针对localhost域名和自定义端口的使用场景。

核心组件架构

BunkerWeb采用模块化设计，主要包含三个核心组件：

1. BunkerWeb主容器：负责处理HTTP请求和安全防护
2. 调度器容器(Scheduler)：负责生成和推送Nginx配置
3. Docker Socket代理：提供安全的Docker API访问

这三个组件必须协同工作才能确保BunkerWeb正常运行。

常见配置误区

许多开发者在本地配置BunkerWeb时容易犯以下错误：

1. 遗漏调度器容器：误以为BunkerWeb可以独立运行，实际上必须配合调度器使用
2. 网络配置不当：未正确设置容器间通信的网络规则
3. API白名单缺失：未配置API_WHITELIST_IP导致调度器无法推送配置

完整配置方案

以下是一个经过验证的本地开发环境配置示例，支持多站点反向代理：

volumes:
  nginx-configs:

networks:
  dev-net:
    ipam:
      driver: default
      config:
        - subnet: 10.20.30.0/24

services:
  bunkerweb:
    image: "ghcr.io/bunkerity/bunkerweb:latest"
    volumes:
      - nginx-configs:/etc/nginx
    environment:
      API_WHITELIST_IP: 127.0.0.0/8 10.20.30.0/24
      MULTISITE: yes
      USE_REVERSE_PROXY: yes
      SERVER_NAME: app.localhost api.localhost storage.localhost
      app.localhost_REVERSE_PROXY_HOST: http://frontend:3000
      api.localhost_REVERSE_PROXY_HOST: http://backend:8000
      storage.localhost_REVERSE_PROXY_HOST: http://minio:9000
    ports:
      - 7050:8080
    networks:
      - dev-net

  scheduler:
    image: "ghcr.io/bunkerity/bunkerweb-scheduler:latest"
    environment:
      - DOCKER_HOST=tcp://docker-proxy:2375
    networks:
      - dev-net

  docker-proxy:
    image: "docker.io/tecnativa/docker-socket-proxy:latest"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - CONTAINERS=1
    networks:
      - dev-net

  frontend:
    image: "your-frontend-image"
    networks:
      - dev-net

  backend:
    image: "your-backend-image"
    networks:
      - dev-net

  minio:
    image: "minio/minio"
    networks:
      - dev-net

关键配置说明

1. API_WHITELIST_IP：必须包含调度器所在网络的IP段(10.20.30.0/24)和本地回环地址(127.0.0.0/8)

2. MULTISITE：启用多站点支持，允许通过不同子域名访问不同后端服务

3. 网络配置：所有容器必须加入同一网络，确保容器间可通过服务名互相访问

4. 端口映射：将容器内8080端口映射到宿主机7050端口，避免与本地80端口冲突

资源优化方案

对于资源受限的开发环境，可以考虑以下优化措施：

1. 限制调度器运行时间：配置调度器在完成初始配置后自动退出
2. 共享配置卷：将生成的Nginx配置持久化，避免重复生成
3. 精简容器数量：在开发环境可以合并部分服务

常见问题排查

1. 持续显示"Generating Bunkerweb Config"：

   • 检查调度器容器是否正常运行
   • 验证API_WHITELIST_IP配置是否正确
   • 查看调度器日志确认配置推送是否成功

2. 容器间通信失败：

   • 确保所有容器加入同一Docker网络
   • 检查网络IPAM配置是否正确
   • 验证服务名称解析是否正常

通过以上配置和优化，开发者可以在本地环境中充分利用BunkerWeb的安全特性，同时保持开发效率。这种配置既适合本地开发调试，也可以作为生产环境配置的基础模板。