本文旨在解决 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 用户就能被宿主机识别为文件的合法所有者或组内成员，从而获得相应的读写权限。
立即学习“PHP免费学习笔记（深入）”；
实施步骤
我们将通过 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 文件成功创建，则表明权限问题已解决。
注意事项与最佳实践
- 安全性考量: 将容器内用户的UID/GID与宿主机用户同步，在开发环境中非常方便。但在生产环境中，出于安全考虑，通常不建议直接使用宿主机开发用户的UID。生产环境应使用较低权限的专用用户，并确保挂载卷的权限配置得当。
- 多用户环境: 如果宿主机上有多个用户或团队成员，每个人的UID可能不同。这种情况下，可能需要更复杂的权限管理策略，例如使用 ACLs (Access Control Lists) 或确保所有开发人员的UID/GID在一定范围内。
- 其他服务: 这种UID/GID同步的方法不仅适用于 Apache/PHP，也适用于任何需要写入挂载卷的 Dockerized 服务（如 Nginx、Node.js 应用等）。只需找到服务运行的用户并修改其UID/GID即可。
- Dockerfile 层优化: usermod 和 groupmod 命令应该放在 Dockerfile 中尽可能靠后的位置，以避免在前面的层中进行不必要的重建。
总结
解决 Docker PHP Apache 容器中文件写入权限问题的核心在于理解宿主机与容器间用户ID（UID）和组ID（GID）不匹配的机制。通过在 docker-compose.yml 中传递宿主机UID，并在 Dockerfile 中利用 usermod 和 groupmod 命令修改容器内 www-data 用户的UID/GID，可以有效地解决这一常见的开发痛点，确保 PHP 应用在 Docker 环境中能够顺畅地进行文件操作。这种方法提供了一种灵活且相对安全的解决方案，尤其适用于开发和测试阶段。
