本文详细阐述了在docker化php apache应用中，因主机与容器之间用户id（uid）不匹配导致的“权限拒绝”错误及其解决方案。核心方法是通过docker compose构建参数将主机用户uid传递给容器，并在dockerfile中修改容器内`www-data`用户的uid和gid以与主机同步，从而确保php进程对挂载卷拥有正确的读写权限，有效解决文件操作受阻的问题。
在开发基于Docker的PHP应用时，尤其是当使用Apache作为Web服务器，并需要PHP进程写入宿主机挂载的目录时，开发者常常会遇到“Permission denied”错误。这通常发生在PHP尝试通过file_put_contents()或其他文件操作函数向挂载卷写入数据时。
问题分析：主机与容器用户ID不匹配
该问题的根本原因在于，Docker容器内部运行的Web服务器（如Apache）通常使用一个默认用户（例如www-data），其用户ID（UID）和组ID（GID）在容器内部是固定的。然而，当宿主机上的目录被挂载到容器内部时，这些文件的所有者和所属组的UID/GID是宿主机上的。如果容器内部的www-data用户UID与宿主机上挂载目录的所有者UID不一致，容器内的www-data用户将无法获得对这些文件的写权限，从而导致“权限拒绝”错误。
例如，一个典型的PHP Apache容器可能将www-data用户的UID/GID设置为33。而宿主机上开发者的UID/GID可能是1000。当宿主机的public_html目录被挂载到容器的/var/www/html时，容器内的www-data用户（UID 33）将无法写入由宿主机用户（UID 1000）拥有的文件。
解决方案：同步主机与容器的用户ID
解决此问题的最佳实践是确保容器内用于运行Web服务的用户（例如www-data）的UID和GID与宿主机上挂载目录的所有者用户的UID和GID保持一致。这可以通过以下步骤实现：
立即学习“PHP免费学习笔记（深入）”；
在宿主机上获取当前用户的UID和GID： 在Linux/macOS终端中，可以使用id -u获取当前用户的UID，使用id -g获取当前用户的GID。
-
通过Docker Compose将UID作为构建参数传递： 在docker-compose.yml文件中，为webserver服务添加args部分，将宿主机的UID作为构建参数传递给Dockerfile。为了方便管理，通常会将UID定义在一个.env文件中。
首先，在项目根目录下创建一个.env文件，内容如下：
# .env UID=$(id -u)
然后，修改docker-compose.yml：
# docker-compose.yml version: "3" networks: dirtbike: services: webserver: build: context: . dockerfile: Dockerfile args: uid: ${UID} # 将宿主机的UID传递给Dockerfile container_name: dirtbike-webserver restart: 'always' depends_on: - database ports: - "80:80" - "443:443" networks: - dirtbike volumes: - ./public_html:/var/www/html # 宿主机目录挂载到容器 database: image: mariadb:10.3 container_name: dirtbike-database restart: 'always' networks: - dirtbike ports: - "127.0.0.1:3306:3306" environment: MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD} MYSQL_DATABASE: ${MYSQL_DATABASE} MYSQL_USER: ${MYSQL_USER} MYSQL_PASSWORD: ${MYSQL_PASSWORD} -
在Dockerfile中接收UID并修改www-data用户： 在Dockerfile中，使用ARG指令接收传入的uid参数，然后利用usermod和groupmod命令修改www-data用户的UID和GID，使其与宿主机用户的UID保持一致。
# Dockerfile FROM php:7.2-apache-stretch ARG uid # 声明接收uid参数 RUN docker-php-ext-install pdo_mysql RUN a2enmod ssl && a2enmod rewrite && a2enmod headers RUN mkdir -p /etc/apache2/ssl COPY ./Docker/ssl/*.pem /etc/apache2/ssl/ COPY ./Docker/config/apache/dirtbike.conf /etc/apache2/sites-available/000-default.conf # 修改www-data用户的UID和GID，使其与宿主机UID一致 RUN usermod -u ${uid} www-data \ && groupmod -g ${uid} www-data;注意：usermod -u修改用户UID，groupmod -g修改组GID。这里我们将www-data的组ID也修改为与UID相同的值，以确保用户和组权限的一致性。
运行与验证
完成上述修改后，需要重新构建并启动Docker容器：
docker-compose up --build -d
这将强制Docker重新构建webserver服务镜像，应用新的Dockerfile配置。容器启动后，PHP应用内部的www-data用户将拥有与宿主机用户相同的UID和GID，从而能够正确地对挂载卷中的文件进行读写操作。
例如，在public_html/index.php中执行以下代码将不再出现权限错误：
<?php file_put_contents(__DIR__.DIRECTORY_SEPARATOR.'test.txt', 'lorem ipsum'); ?>
成功执行后，你会在public_html目录下看到一个名为test.txt的文件。
总结与注意事项
通过同步宿主机与容器的用户ID，我们能够有效解决Docker化PHP应用在文件操作中遇到的权限问题。这种方法在开发环境中尤为实用，因为它允许容器内的PHP进程以与宿主机用户相同的权限操作文件，避免了复杂的权限配置或不安全的chmod 777操作。
注意事项：
- 安全性考量：在生产环境中，应避免将容器内的用户UID与宿主机root用户UID同步。生产环境通常有更严格的权限管理策略，可能需要为容器内的特定服务创建专属用户并赋予最小必要权限。
- 多用户环境：如果宿主机有多个开发者，且他们各自的UID不同，那么每个开发者在构建时都需要确保.env文件中的UID变量是正确的。
- 构建缓存：如果Dockerfile中的ARG uid或RUN usermod行在多次构建之间没有变化，Docker可能会使用构建缓存。为了确保UID更新生效，在修改.env文件后，务必使用--build参数重新构建。
- 基础镜像：本教程基于php:7.2-apache-stretch镜像，其中默认用户为www-data。如果使用其他基础镜像或Web服务器，可能需要调整usermod和groupmod命令中的用户名。
遵循此教程，开发者可以构建一个更加健壮且易于管理的Docker开发环境，有效规避因权限问题导致的开发障碍。
