PHP: 入门指南

如何在 Stackhero 上快速开始使用 PHP

👋 欢迎来到 Stackhero 文档！

Stackhero 提供现成的 PHP 云解决方案，具有多种优势，包括：

通过简单的 git push 在几秒钟内 部署您的应用程序。

使用您自己的域名，并享受 HTTPS 证书的自动配置以增强安全性。

享受自动备份、一键更新以及简单、透明和可预测的定价带来的安心。

通过私有和专用的 VM获得最佳的性能和强大的安全性。

节省时间并简化您的生活：只需 5 分钟即可试用 Stackhero 的 PHP 云托管解决方案！

在 Stackhero 上部署您的 PHP 应用程序既简单又强大。只需几个步骤，您的项目就能上线并投入使用。本指南将以友好、循序渐进的方式，带您完成 PHP 服务的创建、配置和部署。

启动 PHP 服务

首先，您可以直接在 Stackhero 控制台上创建 PHP 服务。界面设计简洁直观，能够让您快速完成操作。

前置条件

在开始之前，请确保您已准备好以下工具：

Git。可从 https://git-scm.com/downloads 下载。
Windows Terminal（Windows 用户可选）。该终端可带来更佳体验，可通过 Microsoft Store 获取。

配置您的服务

主要的配置项是您的 SSH 公钥。您可以通过以下任一命令获取您的公钥：

cat ~/.ssh/id_rsa.pub

或

cat ~/.ssh/id_ed25519.pub

如果您还没有 SSH 密钥对，可以在 Linux 或 macOS 上使用 ssh-keygen，或在 Windows 上使用 ssh-keygen.exe 生成。

获得公钥后，请前往 Stackhero 控制台，选择您的 PHP 服务，进入配置页面，并将公钥粘贴到指定字段中。

Tip: 如果您希望为所有未来的服务统一设置 SSH 公钥，可以全局配置。只需点击控制台右上角的个人头像，进入“Your profile”，然后粘贴您的 SSH 公钥。

克隆示例项目

为帮助您快速上手，我们准备了一个 PHP 示例应用。您可以通过以下命令克隆仓库：

git clone https://github.com/stackhero-io/phpGettingStarted.git stackhero-php-getting-started
cd stackhero-php-getting-started

配置远程仓库服务器

Stackhero 支持通过 Git 轻松部署应用。请复制控制台 PHP 服务首页提供的 git remote 命令，格式如下：

git remote add stackhero ssh://stackhero@<XXXXXX>.stackhero-network.com:222/project.git

部署您的 PHP 代码

现在您已可以部署应用。使用以下命令推送代码：

git push stackhero main

首次推送时，系统会提示您确认密钥指纹。请按提示输入 "yes"。稍等片刻，您的应用就会上线。您可在 Stackhero 控制台提供的 URL（通常为 https://<XXXXXX>.stackhero-network.com）查看应用状态。

如需更新应用，只需修改 www/index.php 文件（或其他需要的文件），然后重新部署：

git add -A .
git commit -m "Update www/index.php"
git push stackhero main

部署已有应用

如果您已有 PHP 应用需要部署，只需将远程仓库添加到您的项目（参见配置远程仓库服务器），然后推送您的更改：

git push stackhero main

默认情况下，Stackhero 会在 www 目录下查找您的 PHP 代码和静态文件。例如，当访问 yourdomain.com/myphoto.jpg 时，文件会从 www/myphoto.jpg 提供。如果您的应用使用了不同的公开目录，可在 PHP 服务配置中进行调整。

处理 "failed to push some refs to '[...]'" 错误

如果部署时遇到如下错误：

error: failed to push some refs to '[...]'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

这表示远程 Git 仓库有您本地没有的更改。如果您确定要用本地版本覆盖远程内容，可以强制推送：

git push -f stackhero main

处理 "src refspec main does not match any" 错误

如果看到如下错误：

error: src refspec main does not match any
error: failed to push some refs to 'ssh://<XXXXXX>.stackhero-network.com:222/project.git'

通常说明本地不存在 main 分支。此时，您可以尝试推送 master 分支：

git push stackhero master

处理推送时 "Everything up-to-date" 错误

如果 Git 显示 Everything up-to-date，但您的更改未被部署，通常是因为您忘记提交更改。可通过以下命令解决：

git add -A .
git commit -m "Your commit message"
git push stackhero main

如果您没有更改代码但仍需触发部署，可以使用空提交：

git commit --allow-empty -m "Force update"
git push stackhero main

部署非 main 分支

如果您希望部署其他分支（如 production），可使用：

git push stackhero production:main

部署标签（tag）

如需部署指定标签（如 v1.0），请运行：

git push stackhero 'v1.0^{}:main'

^{} 可确保与标签关联的提交被正确推送。

回滚或部署指定提交

如需部署特定提交，先用 git log 查找其哈希值，然后强制推送该提交：

git push -f stackhero <HASH>:main

部署到多个环境

通常会为不同环境（如生产和预发布）创建独立服务。您可以通过重命名和添加远程仓库来管理。

将当前远程仓库从 stackhero 重命名为 stackhero-staging：

git remote rename stackhero stackhero-staging

然后在控制台新建生产环境 PHP 服务，并添加远程仓库：

git remote add stackhero-production ssh://stackhero@<XXXXXX>.stackhero-network.com:222/project.git

现在，您可以选择部署到不同环境：

git push stackhero-production main

或

git push stackhero-staging main

在 macOS 的钥匙串中保存 SSH 私钥密码

如果您在 macOS 上每次推送代码时都被要求输入 SSH 密钥密码，无需移除密钥密码。您可以将密码安全地存储在 macOS 钥匙串中。只需运行：

/usr/bin/ssh-add --apple-use-keychain ~/.ssh/id_rsa

此后，macOS 推送代码时将不再询问密钥密码。

管理敏感信息（secrets）

在生产和预发布环境中，建议将敏感数据（如令牌和密码）安全存储。请勿将敏感信息硬编码在仓库中，建议使用环境变量。您可以在 Stackhero 控制台添加环境变量，然后在代码中访问。例如，若创建了名为 mySecret 的环境变量，可在 PHP 中这样获取：

getenv("mySecret")

管理 PHP 依赖

每次推送代码时，Stackhero 的部署脚本会读取您的 composer.json 文件，并自动通过 Composer 安装所需依赖。

文件存储

如果您的应用需要存储文件（如用户上传的图片），建议使用对象存储方案。这有助于多服务间共享文件，并将上传文件与代码分离。您可以考虑 MinIO，它是一款高性能、可靠且兼容 S3 的解决方案。

如果您更倾向于本地存储，可使用 PHP 实例自带的持久化存储，路径为 /persistent/storage/。

例如，保存上传文件时，可使用 move_uploaded_file 函数：

move_uploaded_file($_FILES['image']['tmp_name'], '/persistent/storage/image.jpg');

关于 PHP 文件上传的更多信息，请参阅官方文档：https://www.php.net/manual/en/features.file-upload.php。

注意： 请务必将数据存储在 /persistent/storage/ 文件夹内。

如果实例重启或推送代码变更，存储在持久化存储之外的数据可能会丢失。