企业官网建设流程全解析

• 后端
• Web框架
• 微服务
• RPC框架
• 异步编程

本篇指南以 Hyperf 官方教程中「DaoCloud DevOps 构建」方案为主体，讲解个人开发者如何借助 DaoCloud 这一免费 DevOps 平台，完成 Hyperf 项目的镜像自动构建、集群托管与应用部署。读完本文，你将掌握「项目 / 集群 / 应用」三个核心页面的完整操作链路、Dockerfile 的关键调整细节，以及通过宿主机端口验证 Hyperf 服务是否正常运行的实战方法。原文参见 docs/en/tutorial/daocloud.md。

为什么选择 DaoCloud：个人开发者的 DevOps 现实诉求

对于个人开发者而言，自建Gitlab与Docker Swarm 集群的维护成本明显不可接受：你需要额外维护代码托管服务器、CI 构建机、镜像仓库以及集群调度节点。DaoCloud 提供了一种更轻量的DevOps服务，将代码仓库接入、镜像构建、集群管理与应用部署整合在同一个控制台内。官方教程推荐它的理由很简单——免费且好用。

整条链路的核心价值在于：你只需要提交代码，DaoCloud 会自动完成「拉取代码 → 构建镜像 → 部署到集群 → 暴露端口」的全流程，与自建 GitLab CI + Docker Swarm 的体验基本对齐，却无需承担基础设施成本。

前置准备：Hyperf 的运行环境与 Docker 基础

在接入 DaoCloud 之前，有必要先了解 Hyperf 的运行环境约束，因为它们直接决定了镜像选择与 Dockerfile 的形态：

• 系统环境：Hyperf 只能在 Linux 和 MacOS 上运行；Windows 用户可通过 Docker for Windows 间接使用（见 安装指南）。
• PHP 版本：要求 PHP >= 8.2。
• 网络引擎：二选一即可——Swoole PHP 扩展 >= 5.0（需在php.ini中将swoole.use_shortname设置为Off），或 Swow PHP 扩展 >= 1.4。
• 按需扩展：JSON（必装）、Pcntl（仅 Swoole 引擎）、OpenSSL（使用 HTTPS 时）、PDO（使用 MySQL 客户端时）、Redis（使用 Redis 客户端时）、Protobuf（使用 gRPC 服务端或客户端时）。
• 项目创建：使用composer create-project hyperf/hyperf-skeleton生成骨架项目；官方同时提供了基于 Alpine 的预构建镜像（如hyperf/hyperf:8.1-alpine-v3.18-swoole），这也解释了 DaoCloud 教程中为何会出现apk包管理器命令——Alpine 系镜像默认使用apk安装软件包。
• 启动方式：进入项目根目录执行php bin/hyperf.php start，默认监听9501端口，可用CTRL + C终止进程后重新启动以加载新代码。

上述要点详见 Hyperf 安装与环境要求 与 快速开始。

三个核心页面：项目、应用、集群管理

DaoCloud 控制台功能较多，但官方教程明确建议：只需关注project（项目）、application（应用）和cluster management（集群管理）三个页面。

• 项目（Project）：负责管理代码仓库接入与镜像构建规则，是整个流水线的源头；
• 集群管理（Cluster Management）：负责登记你的宿主机节点，形成可调度的主机资源池；
• 应用（Application）：负责把构建好的镜像真正运行起来，并完成端口、卷（Volume）等运行时配置。

后续所有操作都在这三个页面之间往返完成，理解这条主脉络就不会在控制台里迷失。

第一步：创建项目，打通镜像仓库与自动构建

进入projects页面创建新项目。DaoCloud 支持多种镜像仓库接入方式，可根据自己代码托管平台的实际情况选择。官方教程以hyperf-demo演示项目为例进行配置：

1. 在projects中创建项目，选择对应的仓库类型完成授权接入；
2. 项目创建成功后，Github 仓库对应的WebHooks位置会出现一个回调 URL——这个 URL 是「代码提交触发自动构建」的桥梁：当代码被提交（push）时，DaoCloud 会通过该 WebHook 收到通知，并自动执行对应的打包（镜像构建）操作，无需手动触发。

关键细节：Dockerfile 需要补充wget

项目接入后，还需要对仓库中的Dockerfile做一处必要修改：在原有的apk add命令下方，追加&& apk add wget \。以典型的 Alpine 基础镜像 Dockerfile 为例，修改后的形态如下：

RUN apk add --no-cache \ bash \ ... \ && apk add wget \ ...

官方文档的原话是：具体原因并不十分清楚，但如果不更新wget，在使用时会出现问题；而使用自建 Gitlab CI 时则没有这个问题。可以这样理解：Hyperf 官方镜像及 DaoCloud 构建环境多以 Alpine 为基础，其自带的wget（BusyBox 版本）功能较弱，部分构建或运行阶段（如下载依赖、健康检查）需要依赖功能更完整的 GNUwget，因此显式通过apk add安装一份可用的wget是必要的保险措施。如果你的构建环境不依赖wget，或使用自建 Gitlab CI，则无需此改动。

完成以上配置后，后续每次提交代码，DaoCloud 都会自动执行打包操作，无需人工干预。

第二步：创建集群并添加主机

接下来进入cluster management（集群管理）：

1. 创建一个新的cluster（集群）；
2. 在集群下add hosts（添加主机），即登记你要部署应用的目标服务器节点。

该步骤按控制台指引逐步操作即可（通常在主机上安装对应的 Agent 或完成 SSH 信任即可完成注册），核心目的是让 DaoCloud 具备把容器调度到你指定宿主机上的能力。注册完成后，主机即出现在集群的主机列表中，后续应用部署时即可选择该集群作为运行目标。

第三步：创建应用，映射端口并挂载.env

集群就绪后，进入应用部署环节：

1. 点击Apply -> Create Application（创建应用）；
2. 选择刚刚创建好的project（项目），也就是选定要部署的镜像来源；
3. 点击Deploy（部署）。

部署配置中有两个关键点需要特别注意：

主机端口：选择一个未被占用的端口

按照官方教程说明，主机端口（host port）需要用户自行选择一个未被占用的端口。Hyperf 服务默认在容器内监听9501端口，因此通常的做法是把宿主机某个空闲端口（例如9501）映射到容器的9501端口，映射关系可写为宿主机端口:容器端口。

挂载.env：用 Volume 实现配置注入

DaoCloud 没有提供Swarm那样的Config配置管理功能，因此需要主动将项目的.env文件映射进容器，以实现配置注入：

• 容器目录：/opt/www/.env
• 主机目录：你存放.env文件的位置（本地服务器上的文件路径）
• 可写与否：该挂载选项（可写 / 只读）均可，按需选择即可

挂载完成后点击Deploy Now（立即部署）。之所以必须挂载.env，是因为 Hyperf 项目的配置体系依赖环境变量文件：项目根目录下config/中的配置文件（如config/autoload/下的各组件配置与config/config.php）在服务启动时会被扫描并注入配置对象，而.env中存放的数据库、Redis 等连接信息正是这些配置的取值来源（Hyperf 配置结构的详细说明见 配置章节）。如果没有 Swarm Config 这类原生配置注入手段，把.env以 Volume 形式挂载进容器的固定路径/opt/www/.env，是最直接可靠的替代方案。

第四步：验证部署：访问 Hyperf 欢迎接口

部署完成后，进入宿主机（host），访问刚才映射的端口即可验证服务是否正常运行：

$ curl http://127.0.0.1:9501

如果部署成功，你将看到 Hyperf 的欢迎接口返回如下 JSON 数据：

{"code":0,"data":{"user":"Hyperf","method":"GET","message":"Hello Hyperf."}}

该响应正是 Hyperf 骨架项目默认首页控制器的输出——code表示业务状态码，data中携带了用户名、请求方法与欢迎语（Hello Hyperf.）。这与 Hyperf 官方文档中控制器返回字符串的示例（如 控制器章节 中curl http://127.0.0.1:9501/?target=Hyperf返回Hello Hyperf.）一脉相承，可用于确认容器内代码已正常加载、路由已生效、端口映射正确。

若 curl 无响应，可依次排查：集群主机是否在线、端口是否被占用、容器是否处于运行状态、/opt/www/.env挂载是否成功。

原理回顾与排障思路

• WebHooks 驱动 CI/CD：项目创建成功后生成的 WebHooks URL 是自动化的触发器，代码 push 后 DaoCloud 自动完成打包；若提交代码后未触发构建，优先检查 WebHook 是否配置正确、仓库授权是否有效。
• 为什么改 Dockerfile：Alpine 基础镜像中wget能力受限，构建或使用阶段可能异常，需在apk add下追加&& apk add wget \；自建 Gitlab CI 环境无此问题。
• 为什么挂载.env：DaoCloud 无 Swarm Config 功能，无法原生注入配置，只能通过 Volume 将宿主机上的.env挂载到容器/opt/www/.env，保证 Hyperf 启动时能读取环境配置。
• 为什么手动指定端口：容器端口由镜像内的 Hyperf 配置决定（默认 9501），宿主机端口由部署时指定，须确保未被占用。

延伸阅读

• DaoCloud 部署教程原文
• Hyperf 安装与环境要求：镜像、扩展与本地环境基线
• Hyperf 快速开始：路由、控制器与启动命令
• 控制器与响应示例：欢迎接口Hello Hyperf.的代码来源
• Hyperf 配置说明：config/autoload与config/config.php的配置加载机制

• 后端
• Web框架
• 微服务
• RPC框架
• 异步编程