Docker PHP Apache 文件写入权限解决方法

本文旨在解决 Docker 环境中 PHP Apache 容器因用户ID（UID）和组ID（GID）不匹配导致的文件写入权限问题。通过同步容器内 `www-data` 用户与宿主机用户的UID/GID，确保PHP应用能够顺利读写挂载的宿主机卷，从而优化开发工作流。

在 Docker 化应用开发中，尤其是在使用 PHP 和 Apache 服务时，开发者经常会遇到一个棘手的问题：当 PHP 应用尝试向挂载到容器的宿主机卷写入文件时，会遭遇“Permission Denied”（权限拒绝）错误。这一问题通常源于容器内部运行服务的用户（例如 www-data）与宿主机上文件所有者的用户ID（UID）和组ID（GID）不匹配。

理解权限问题的根源

Docker 容器通过卷（Volume）机制将宿主机的文件系统目录映射到容器内部。当容器内的进程（如 Apache 或 PHP-FPM）尝试访问这些挂载的目录时，其权限检查是基于容器内进程的有效UID和GID，以及宿主机上对应文件的所有者和权限。

默认情况下，许多基于 Debian/Ubuntu 的 PHP Apache 镜像会配置 Apache 和 PHP-FPM 以 www-data 用户和组的身份运行。这个 www-data 用户在容器内部通常有一个固定的UID和GID（例如 33）。然而，宿主机上开发者的用户UID和GID可能与此不同（例如 1000）。当宿主机上的文件或目录由宿主机用户拥有时，容器内的 www-data 用户由于UID/GID不匹配，会被视为“其他用户”，从而受到宿主机文件权限的限制，导致写入操作失败。

解决方案：同步用户ID和组ID

解决此问题的最佳实践是修改容器内部 www-data 用户的UID和GID，使其与宿主机上拥有挂载目录的用户UID和GID保持一致。这样，容器内的 www-data 用户就能被宿主机识别为文件的合法所有者或组内成员，从而获得相应的读写权限。

实施步骤

我们将通过 docker-compose.yml 和 Dockerfile 的修改来实现这一目标。

步骤 1: 获取宿主机用户UID

首先，需要获取当前宿主机用户的UID。在 Linux 或 macOS 终端中执行以下命令：

id -u

假设输出为 1000。为了方便管理，通常会将这个UID定义在一个 .env 文件中，供 docker-compose 使用。

创建一个 .env 文件（如果尚未存在）在 docker-compose.yml 同级目录：

UID=1000

请将 1000 替换为你实际获取到的宿主机UID。

步骤 2: 修改 docker-compose.yml

在 docker-compose.yml 文件中，我们需要在 webserver 服务的 build 部分添加 args，将宿主机的UID作为构建参数传递给 Dockerfile。

version: "3"

networks:
  dirtbike:

services:
  webserver:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        uid: ${UID} # 从 .env 文件获取 UID
    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}

步骤 3: 修改 Dockerfile

在 Dockerfile 中，我们需要接收 uid 构建参数，并使用 usermod 和 groupmod 命令修改 www-data 用户的UID和GID。

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 以匹配宿主机用户
RUN usermod -u ${uid} www-data \
    && groupmod -g ${uid} www-data;

修改说明：

• ARG uid: 这行声明了一个名为 uid 的构建参数，它将接收 docker-compose.yml 中传递的值。
• RUN usermod -u ${uid} www-data && groupmod -g ${uid} www-data;: 这两条命令是关键。
  • usermod -u ${uid} www-data: 将 www-data 用户的UID更改为传递进来的 ${uid}。
  • groupmod -g ${uid} www-data: 将 www-data 组的GID更改为传递进来的 ${uid}。通常，www-data 用户的主组也是 www-data，因此需要同时修改组ID。

重建并启动容器

完成上述修改后，需要重建 Docker 镜像并重新启动服务：

docker-compose build --no-cache webserver
docker-compose up -d

--no-cache 参数确保 Dockerfile 中的所有层都会被重新执行，包括 usermod 和 groupmod 命令，从而正确应用新的UID/GID。

验证效果

现在，当 PHP 应用尝试在 /var/www/html 目录下写入文件时，由于容器内的 www-data 用户与宿主机上挂载目录的所有者UID/GID一致，权限问题应该已经解决。

可以再次运行 index.php 中的文件写入代码进行验证：

如果 test.txt 文件成功创建，则表明权限问题已解决。

注意事项与最佳实践

1. 安全性考量: 将容器内用户的UID/GID与宿主机用户同步，在开发环境中非常方便。但在生产环境中，出于安全考虑，通常不建议直接使用宿主机开发用户的UID。生产环境应使用较低权限的专用用户，并确保挂载卷的权限配置得当。
2. 多用户环境: 如果宿主机上有多个用户或团队成员，每个人的UID可能不同。这种情况下，可能需要更复杂的权限管理策略，例如使用 ACLs (Access Control Lists) 或确保所有开发人员的UID/GID在一定范围内。
3. 其他服务: 这种UID/GID同步的方法不仅适用于 Apache/PHP，也适用于任何需要写入挂载卷的 Dockerized 服务（如 Nginx、Node.js 应用等）。只需找到服务运行的用户并修改其UID/GID即可。
4. Dockerfile 层优化: usermod 和 groupmod 命令应该放在 Dockerfile 中尽可能靠后的位置，以避免在前面的层中进行不必要的重建。

总结

解决 Docker PHP Apache 容器中文件写入权限问题的核心在于理解宿主机与容器间用户ID（UID）和组ID（GID）不匹配的机制。通过在 docker-compose.yml 中传递宿主机UID，并在 Dockerfile 中利用 usermod 和 groupmod 命令修改容器内 www-data 用户的UID/GID，可以有效地解决这一常见的开发痛点，确保 PHP 应用在 Docker 环境中能够顺畅地进行文件操作。这种方法提供了一种灵活且相对安全的解决方案，尤其适用于开发和测试阶段。