Hyperf单机Docker部署应按需挂载：/app/config只读挂载支持热更新，/app/runtime用命名卷或宿主机路径确保可写，禁用整目录挂载以防覆盖vendor；开发环境可挂载代码目录并排除vendor，生产环境仅挂载config、runtime、logs，并通过APP_ENV统一控制行为。
单机 Docker 部署 Hyperf 时，用数据卷（Volume）挂载实现配置、日志和代码的持久化，是保障服务稳定、便于调试和升级的关键操作。重点不是“全盘映射”，而是按需挂载、权限可控、开发与生产分离。
明确哪些目录需要挂载
Hyperf 运行时关键路径需区分对待：
-
/app/config：配置文件目录 —— 建议只读挂载（
:ro），避免容器内误改，同时支持热更新（如修改database.php后 reload 生效） -
/app/runtime：运行时生成目录（日志、缓存、协程文件）—— 必须可写，推荐用命名卷（
hyperf_runtime）或宿主机绝对路径（如./runtime:/app/runtime） - /app/public（如有静态资源）：可选挂载，便于前端文件热替换
-
代码根目录（/app）本身不建议整目录挂载：尤其生产环境，会覆盖容器内已优化的
vendor和autoload，导致性能下降或启动失败
docker-compose.yml 中的挂载写法示例
以生产环境为例，使用命名卷 + 配置只读 + 日志独立存储：
services:
app:
build: .
volumes:
- ./config:/app/config:ro
- hyperf_runtime:/app/runtime
- ./logs:/app/storage/logs
environment:
- APP_ENV=prod
- HYPERF_LOG_LEVEL=info
volumes:
hyperf_runtime:说明：
-
./config是宿主机当前目录下的 config 文件夹，保持与容器内结构一致 -
hyperf_runtime是 Docker 自动创建的命名卷，生命周期独立于容器，重启/重建不丢失 -
./logs映射到宿主机，方便用tail -f或日志收集工具接入
开发环境 vs 生产环境挂载策略
两者目标不同，挂载方式应有明显区分：
-
开发环境：可挂载整个项目目录（
./:/app），配合--watch实现代码热重载；但需确保vendor不被宿主机覆盖（可在docker-compose.yml中加volumes排除：- /app/vendor） -
生产环境：禁用代码挂载，只挂载
config、runtime、logs；镜像内已构建好优化后的依赖，保证启动快、内存稳 - 统一通过
APP_ENV环境变量控制行为，避免手动改 CMD 或配置文件
权限与 SELinux 注意事项（Linux/macOS）
挂载后常见报错如 Permission denied 或 mkdir(): Permission denied，多因用户 UID 不匹配：
- Hyperf 官方镜像默认以
www-data（UID 82）或root用户运行，而宿主机目录常属当前用户（如 UID 1000） - 解决方法一：在
Dockerfile中指定用户，例如USER 1000 - 解决方法二：启动时加
--user $(id -u):$(id -g)参数（docker run场景） - SELinux 环境（如 CentOS/RHEL）需加
:z或:Z标签，例如./config:/app/config:ro,z
