Hyperf单机Docker多阶段部署需确保根目录含composer.json、config/、runtime/、.env、Dockerfile五要素，runtime/不可被.dockerignore删除，.env须存在；采用两阶段Dockerfile（构建阶段装Swoole并生成代理类，运行阶段精简COPY+www-data用户），配合docker-compose.yml挂载配置、暴露9501端口、设restart: unless-stopped及APP_ENV=prod，最终镜像约150MB，curl http://localhost:9501/health返回{"status":"ok"}即验证成功。
Hyperf 单机部署用 Docker 多阶段构建，核心目标是把镜像体积压到最小、启动快、运行稳。不依赖外部构建机，本地就能完成；也不需要 Kubernetes，一台服务器跑一个容器就够用。
必须检查的项目结构
开始前确认项目根目录有这 5 个东西：composer.json、config/、runtime/、.env、Dockerfile。缺任何一个都可能让容器起不来。
- runtime/ 目录不能被 .dockerignore 删除——它存协程上下文和日志，删了服务卡在 “Loading config”
- .env 文件要真实存在（哪怕只是空文件），否则 Hyperf 启动时读不到环境变量会报错
- config/autoload/server.php 中的端口需与 Dockerfile EXPOSE 和 docker run -p 保持一致（默认 9501）
推荐的多阶段 Dockerfile 写法
分两阶段：第一阶段装依赖并生成代理类，第二阶段只留运行所需文件，镜像体积可从 1.2GB 降到 150MB 左右。
- 构建阶段用 php:8.1-cli-alpine + pecl install swoole-5.1.0，确保 Swoole 扩展启用
- 先 COPY composer.json 和 composer.lock，再 run composer install --no-dev --optimize-autoloader
- 接着 COPY . .，再执行 php bin/hyperf.php gen:proxy 等命令生成必要代码
- 运行阶段 FROM 同样用 alpine 镜像，COPY --from=builder /app /app，USER www-data 提权
- 最后 CMD ["php", "bin/hyperf.php", "start"]，别加 --watch，生产环境必须关掉
单机部署用 docker-compose.yml
不用写复杂网络或服务发现，就配 Hyperf 本身 + 挂载配置 + 暴露端口 + 自启保障。
- 用 volumes 把 ./config:/app/config:ro 挂载，方便改配置不用重打镜像
- 映射 -p 9501:9501，如果用了 WebSocket 或 HTTP2，再加 -p 9502:9502
- 加 restart: unless-stopped，机器重启后自动拉起容器
- 通过 environment 设置 APP_ENV=prod，触发 OPcache 和调试关闭
- runtime/ 目录建议也挂载出来（如 ./runtime:/app/runtime），避免容器销毁后日志丢失
验证是否跑通三件事
镜像构建完，别急着上线，本地快速验一遍：
- docker-compose build 成功，没 warning 或 error
- docker-compose up -d 后，docker-compose ps 显示状态是 Up
- curl http://localhost:9501/health 返回 {"status":"ok"} 或访问首页能出响应
