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 中的挂载写法示例

以生产环境为例，使用命名卷 + 配置只读 + 日志独立存储：

Docker Image Puller

使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。

下载

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