单机环境下导出导入 docker 镜像是迁移 hyperf 项目的最轻量可控方式；需用 docker save 导出镜像为 tar，docker load 导入，再同步配置、挂载卷、端口映射，并验证 swoole 进程与健康接口。
单机环境下导出和导入 Docker 镜像，是迁移 Hyperf 项目最轻量、最可控的方式，尤其适合开发测试或离线部署场景。关键不在于镜像大小，而在于保留构建上下文、运行时依赖和配置一致性。
确认并导出 Hyperf 镜像
确保目标镜像已本地存在（可通过 docker images 查看），且镜像名/标签明确（如 hyperf-app:1.2.0）。导出为 tar 文件，不依赖 registry：
- 执行
docker save -o hyperf-app-1.2.0.tar hyperf-app:1.2.0 - 若含多个镜像层或依赖基础镜像（如
php:8.2-cli），建议一并导出：docker save -o hyperf-bundle.tar hyperf-app:1.2.0 php:8.2-cli - 生成的 tar 文件可校验完整性：
sha256sum hyperf-app-1.2.0.tar
传输到目标机器后导入镜像
将 tar 文件复制到目标服务器（如用 scp 或 U 盘），再加载进 Docker daemon：
- 执行
docker load -i hyperf-app-1.2.0.tar - 导入成功后，
docker images应可见同名镜像；注意：load不会自动重命名，标签需与导出时一致 - 若提示 “no such image”，检查是否漏传基础镜像或 tar 文件损坏
启动容器前的关键校验项
Hyperf 对环境敏感，仅镜像迁移不够，还需同步配套资源：
-
配置文件：
.env、config/下的配置需单独复制，镜像内通常不含运行时配置 -
挂载卷：日志、上传目录、缓存路径（如
/data/logs）应通过-v映射宿主机目录，避免容器重启丢失 -
网络与端口：确认
docker run -p 9501:9501等端口映射匹配 Hyperf 的监听配置（默认 Swoole HTTP server 用 9501） -
启动命令：推荐使用
docker run --rm -d --name hyperf-prod -p 9501:9501 hyperf-app:1.2.0，后续可用docker logs -f hyperf-prod实时观察启动日志
验证服务是否正常响应
启动后别急着调用业务接口，先做最小闭环验证：
- 执行
docker exec -it hyperf-prod ps aux | grep swoole，确认 Swoole 主进程在运行 - 用
curl http://localhost:9501/health（或你定义的健康检查路由）查看返回状态码与 JSON 响应 - 检查容器内日志是否有
Server started或Swoole HTTP server is started类似输出 - 若 502/Connection refused，优先排查 Swoole 是否监听
0.0.0.0:9501而非127.0.0.1:9501
