docker-local

Docker Compose 本地开发

你正在使用自定义的 Docker Compose 本地开发环境（非 DDEV）。

环境检测

在使用 Docker 的项目中工作时，首先检测环境配置：

# Check for compose files
ls -la docker-compose*.yml compose*.yml 2>/dev/null

# Check for environment files
ls -la .env* 2>/dev/null

# Check for Makefile or scripts
ls -la Makefile docker/ scripts/ 2>/dev/null

常用命令

项目生命周期

docker compose up -d              # Start in background
docker compose up -d --build      # Start with rebuild
docker compose down               # Stop and remove containers
docker compose down -v            # Also remove volumes (DATA LOSS!)
docker compose restart            # Restart all services

运行命令

# In running container
docker compose exec <service> <command>

# Examples
docker compose exec php composer install
docker compose exec php ./vendor/bin/drush cr
docker compose exec php bash

# In new container (if service not running)
docker compose run --rm php composer install

调试

docker compose ps                 # Show container status
docker compose logs -f            # Follow all logs
docker compose logs -f php        # Follow specific service
docker compose top                # Show processes
docker compose exec php env       # Show environment

Drupal Docker 模式

常见服务名称

不同项目各不相同，但常见模式如下：

服务类型	常见名称
PHP/Web	php、web、app、drupal、php-fpm
数据库	db、mysql、mariadb、postgres
缓存	redis、memcached
搜索	solr、elasticsearch

运行 Drush

# Find the PHP container
docker compose ps

# Run Drush (path may vary)
docker compose exec php drush cr
docker compose exec php ./vendor/bin/drush cr
docker compose exec web vendor/bin/drush cr

数据库操作

# MySQL/MariaDB
docker compose exec db mysql -u root -p<password> <database>

# Import
docker compose exec -T db mysql -u root -p<password> <database> < dump.sql

# Export
docker compose exec db mysqldump -u root -p<password> <database> > dump.sql

# PostgreSQL
docker compose exec db psql -U <user> <database>

标准 Docker Compose 模板

适用于不使用 DDEV 的 Drupal 项目：

# docker-compose.yml
services:
  php:
    build:
      context: .
      dockerfile: docker/php/Dockerfile
    volumes:
      - .:/var/www/html:cached
    depends_on:
      - db
    environment:
      - PHP_MEMORY_LIMIT=512M

  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - .:/var/www/html:ro
      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - php

  db:
    image: mariadb:10.11
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: drupal
      MYSQL_USER: drupal
      MYSQL_PASSWORD: drupal
    volumes:
      - db-data:/var/lib/mysql
    ports:
      - "3306:3306"

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  db-data:

PHP Dockerfile

# docker/php/Dockerfile
FROM php:8.2-fpm

RUN apt-get update && apt-get install -y \
    git unzip libpng-dev libjpeg-dev libfreetype6-dev \
    libzip-dev libicu-dev mariadb-client \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install gd pdo_mysql zip intl opcache bcmath

COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

WORKDIR /var/www/html

Nginx 配置

# docker/nginx/default.conf
server {
    listen 80;
    server_name localhost;
    root /var/www/html/web;
    index index.php;

    location / {
        try_files $uri /index.php$is_args$args;
    }

    location ~ \.php$ {
        fastcgi_pass php:9000;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }
}

Makefile 封装

使用 Makefile 简化命令：

# Makefile
.PHONY: up down restart shell drush composer logs

up:
	docker compose up -d

down:
	docker compose down

restart:
	docker compose restart

shell:
	docker compose exec php bash

drush:
	docker compose exec php ./vendor/bin/drush $(filter-out $@,$(MAKECMDGOALS))

composer:
	docker compose exec php composer $(filter-out $@,$(MAKECMDGOALS))

logs:
	docker compose logs -f

db-import:
	docker compose exec -T db mysql -u root -proot drupal < $(file)

db-export:
	docker compose exec db mysqldump -u root -proot drupal > dump.sql

%:
	@:

用法：

make up
make drush cr
make composer require drupal/module
make db-import file=backup.sql

故障排查

端口冲突

# Find what's using a port
sudo lsof -i :80
sudo lsof -i :3306

# Check all Docker ports
docker ps --format "table {{.Names}}\t{{.Ports}}"

容器无法启动

docker compose logs <service>           # Check logs
docker compose down && docker compose up -d --build  # Rebuild
docker compose down -v && docker compose up -d       # Fresh start (loses data!)

权限问题

# Check container user
docker compose exec php id

# Fix web directory permissions
docker compose exec php chown -R www-data:www-data /var/www/html/web/sites/default/files

网络问题

# Containers reach each other by service name
# From PHP container: mysql -h db -u root -proot

# Inspect network
docker network ls
docker network inspect <project>_default

性能（macOS/Windows）

macOS/Windows 上的文件同步速度较慢：

• 使用 :cached 卷标记
• 将 vendor/ 和 node_modules/ 排除在同步范围之外
• 考虑使用 Docker Desktop 的 VirtioFS（macOS）

volumes:
  - .:/var/www/html:cached
  - vendor:/var/www/html/vendor  # Named volume for vendor

环境变量

.env 文件

Docker Compose 会自动加载 .env：

COMPOSE_PROJECT_NAME=myproject
PHP_VERSION=8.2
MYSQL_ROOT_PASSWORD=root
MYSQL_DATABASE=drupal

Drupal settings.php

// settings.php for Docker
$databases['default']['default'] = [
  'driver' => 'mysql',
  'database' => getenv('MYSQL_DATABASE') ?: 'drupal',
  'username' => getenv('MYSQL_USER') ?: 'drupal',
  'password' => getenv('MYSQL_PASSWORD') ?: 'drupal',
  'host' => getenv('DB_HOST') ?: 'db',
  'port' => getenv('DB_PORT') ?: 3306,
];

// Redis (if using)
if (getenv('REDIS_HOST')) {
  $settings['redis.connection']['host'] = getenv('REDIS_HOST') ?: 'redis';
  $settings['cache']['default'] = 'cache.backend.redis';
}

最佳实践

1. 为 docker-compose.yml 进行版本控制 - 确保环境一致
2. 使用 .env 保存密钥 - 切勿提交密码
3. 创建 Makefile - 简化团队的命令
4. 在 README 中编写文档 - 说明如何启动、停止和访问服务
5. 使用命名卷 - 持久化数据库数据
6. 健康检查 - 确保服务就绪后再启动依赖它们的服务