Homestead
Homestead
Laravel Homestead
简介
Laravel 致力于让整个 PHP 开发体验变的更愉快，包括你的本地开发环境。 Vagrant 提供了一种简单、优雅的方式来管理和配置虚拟主机。
Laravel Homestead 是一个官方预封装的 Vagrant box ，它为你提供了一个完美的开发环境，你不需要在本地机器安装 PHP、 web 服务器和其他的服务器软件。你再也不用担心会弄乱你的操作系统了！ Vagrant boxes 是一次性的。 如果出现问题， 你可以在几分钟内销毁并重新创建 box !
Homestead 可以运行在任何 Windows、 Mac、 或 Linux 系统， 它包括了 Nginx web 服务器， PHP 7.3、 PHP 7.2、 PHP 7.1、 MySQL、PostgreSQL、Redis、 Memcached、 Node 以及你开发 Laravel 所需要的东西。
{note} 如果你使用的是 Windows, 你可能需要通过 BIOS 来启用硬件虚拟化 (VT-x)。如果你在 Hyper-V 系统上使用 UEFI 你可能还需要禁用 Hyper-V 以便访问 VT-x.
内置软件
- Ubuntu 18.04
- Git
- PHP 7.3
- PHP 7.2
- PHP 7.1
- Nginx
- Apache (Optional)
- MySQL
- MariaDB (Optional)
- Sqlite3
- PostgreSQL
- Composer
- Node (With Yarn, Bower, Grunt, and Gulp)
- Redis
- Memcached
- Beanstalkd
- Mailhog
- Neo4j (Optional)
- MongoDB (Optional)
- Elasticsearch (Optional)
- ngrok
- wp-cli
- Zend Z-Ray
- Go
- Minio
安装 & 设置
第一步
在你启动 Homestead 环境之前，你必须安装 VirtualBox, VMWare, Parallels 或 Hyper-V 以及 Vagrant. 以上所有软件均针对不同的操作系统提供了易于使用的可视化安装包。
若要使用 VMware 提供器， 你需要购买 VMware Fusion / Workstation 和 VMware Vagrant plug-in. 虽然它不是免费的，但是 VMware 可以提供更快的共享文件夹性能。
若要使用 Parallels 提供器， 你需要安装 Parallels Vagrant plug-in。它是免费的哦。
由于受到 Vagrant 限制 , Hyper-V 提供程序会忽略所有的网络设置。
安装 Homestead Vagrant Box
一旦将 VirtualBox / VMware 和 Vagrant 都安装好之后，你可以在终端执行下面的命令将laravel/homesteadbox 添加到 Vagrant 中安装。你可能需要几分钟的时间来下载 box ， 因为它取决于你的网络连接速度:
vagrant box add laravel/homestead
如果这个命令失败了，请确保你安装的是最新版的 Vagrant。
安装 Homestead
你可以通过克隆代码来安装 Homestead。 建议将代码克隆到你的 "home" 目录下的Homestead文件夹中， 这样 Homestead box 就可以作为你的所有 Laravel 项目的主机：
git clone https://github.com/laravel/homestead.git ~/Homestead
因为 Homestead 的 master 分支并不是稳定的，你应该使用打过标签的稳定版本。你可以在GitHub 发行页: 上找到最新的稳定版本:
cd ~/Homestead// 克隆期望的发行版本...git checkout v8.0.1
一旦克隆 Homestead 代码完成以后，在 Homestead 目录中使用bash init.sh命令来创建Homestead.yaml配置文件。Homestead.yaml文件将被放在 Homestead 目录中:
// Mac / Linux...bash init.sh// Windows...init.bat
配置 Homestead
设置提供器
Homestead.yaml文件中的provider参数决定了你用的是哪一个 Vagrant 提供器 :virtualbox,vmware_fusion,vmware_workstation,parallels以及hyperv。 你可以根据你的喜好来设置他们:
provider: virtualbox
配置共享文件夹
Homestead.yaml 文件的 folders 属性里列出了所有与 Homestead 环境共享的文件夹。 这些文件夹中的文件如果发生变更，它们会保持本地机器与 Homestead 环境之间同步。 你可以根据需要配置多个共享文件夹:
folders: - map: ~/code to: /home/vagrant/code
如果你只创建几个网站，这种通用的映射将运行的很好。但是，随着网站数量的不断增加，你可能会开始遇到性能问题。在包含大量文件的低性能机器或项目中，这个问题会非常明显。如果遇到此问题，请尝试将每个项目映射到自己的 Vagrant 文件夹:
folders: - map: ~/code/project1 to: /home/vagrant/code/project1 - map: ~/code/project2 to: /home/vagrant/code/project2
若要开启NFS, 你只需要在共享的文件夹配置中添加一个简单的标志:
folders: - map: ~/code to: /home/vagrant/code type: "nfs"
{note} 当使用 NFS 时，你最好使用vagrant-winnfsd扩展插件。 这个插件会替你处理 Homestead box 中的文件或目录权限的问题。
你也可以通过在options中列出 Vagrant's 的共享文件夹支持的任何选项:
folders: - map: ~/code to: /home/vagrant/code type: "rsync" options: rsync__args: ["--verbose", "--archive", "--delete", "-zz"] rsync__exclude: ["node_modules"]
配置 Nginx 站点
对 Nginx 不熟悉？没关系。sites功能可以让你在 Homestead 上轻松的映射一个 "域名" 到一个文件夹。在Homestead.yaml文件中包含了一个简单的站点配置示例。同样，您可以根据需要为您的 Homestead 环境添加很多的站点。Homestead 可以为你正在开发的每个 Laravel 项目提供一个方便的虚拟化环境：
sites: - map: homestead.test to: /home/vagrant/code/my-project/public
如果你在配置 Homestead 虚拟机后更改了sites选项，你需要再次运行vagrant reload --provision命令去更新虚拟机上的 Nginx 配置.
Hosts 文件
你必须将 Nginx 站点中所添加的域名添加到你本机的hosts文件中。hosts文件会将把访问你 Homestead 站点的请求重定向到你的 Homestead 虚拟机上。在 Mac 和 Linux 中，该文件的地址在/etc/hosts，在 Windows 中位于C:\Windows\System32\drivers\etc\hosts。添加新站点的格式如下所示：
192.168.10.10 homestead.test
确保监听的 IP 地址是你在Homestead.yaml文件中所设置的。一旦你将将域名添加到hosts文件中并启动 Vagrant Box 后，你就可以通过浏览器访问该站点了:
http://homestead.test
启动 Vagrant Box
根据你的需求编辑完成Homestead.yaml，在你的 Homestead 文件夹中运行vagrant up命令。Vagrant 将启动虚拟机并自动配置你的共享文件夹和 Nginx 站点。
若要删除虚拟机，只需要运行vagrant destroy --force命令。
根据项目安装
除了全局安装 Homestead 并且在所有项目共享相同的 Homestead box 之外， 你可以为每个项目配置 Homestead 实例。 通过在项目下创建Vagrantfile，其他的项目成员只需运行vagrant up就能拥有相同的开发环境。
要将 Homestead 直接安装到项目中，需要使用 Composer 命令:
composer require laravel/homestead --dev
Homestead 安装之后， 使用make命令在项目根目录中生成Vagrantfile和Homestead.yaml文件。make命令会自动配置Homestead.yaml文件中sites和folders指令。
Mac / Linux:
php vendor/bin/homestead make
Windows:
vendor\\bin\\homestead make
接下来，在命令行中运行vagrant up命令，然后在浏览器中访问http://homestead.test。 记住，在访问之前你仍然需要在/etc/hosts文件中添加你的homestead.test记录或者其他的域名。
安装 MariaDB
如果你喜欢使用 MariaDB 而不是 MySQL， 你可以在Homestead.yaml文件中增加一个mariadb的选项。这个选项会删除 MySQL 并安装 MariaDB。 MariaDB 只是作为 MySQL 的旁支替代品，因此你还是可以在应用的数据库配置中使用mysql数据库驱动：
box: laravel/homestead ip: "192.168.10.10"memory: 2048cpus: 4provider: virtualbox mariadb: true
安装 MongoDB
如果你需要安装 MongoDB 社区版， 你可以在Homestead.yaml文件中将配置修改为：
mongodb: true
MongoDB 默认的安装方式会把数据库的用户名设置为homestead，默认密码为secret。
安装 Elasticsearch
如果你要安装 Elasticsearch，你可以在Homestead.yaml文件中添加elasticsearch选项并指定支持的版本号。可以仅包含主版本，也可以是某个具体的版本号（major.minor.patch）。默认安装会创建一个名为 'homestead' 的集群。 注意永远不要赋予 Elasticsearch 超过操作系统一半的内存，因此请保证你的 Homestead 至少分配了两倍于 Elasticsearch 的内存：
box: laravel/homestead ip: "192.168.10.10"memory: 4096cpus: 4provider: virtualbox elasticsearch: 6
{tip} 你可以查看 Elasticsearch documentation 文档学习如何自定义你的配置。
安装 Neo4j
Neo4j 是一个图形数据库管理系统。要安装 Neo4j 社区版，需要更新Homestead.yaml配置项如下：
neo4j: true
默认安装的 Neo4j 会将数据库用户名设置为homestead，对应的密码设置为secret。 要查看 Neo4j 可以在浏览器中访问http://homestead.test:7474。 Neo4j 对外提供了三个端口：7687（Bolt）、7474（HTTP）、7473（HTTPS） 用于从客户端访问。
别名
你可以通过编辑 Homestead 目录下的aliases文件为 Homestead 虚拟机添加 Bash 别名：
alias c='clear'alias ..='cd ..'
更新完aliases文件后， 你应该使用vagrant reload --provision命令重启 Homestead 虚拟机， 以确保新的别名在机器上可用。
日常使用
全局可用的 Homestead
有时你可能想在文件系统的任意路径都能运行vagrant up命令启动 Homestead 虚拟机。在 Mac / Linux 系统上可以在 Bash 配置文件（~/.bash_profile）中添加 Bash 函数 。在 Windows 上， 你可以添加「批处理」文件到PATH。这些脚本允许你在系统的任何位置运行 Vagrant 命令并自动将该命令指向 Homestead 的安装路径：
Mac / Linux
function homestead() { ( cd ~/Homestead && vagrant $* ) }
确保将该函数中的~/Homestead路径调整为实际的 Homestead 安装路径。这样你就可以在系统的任意位置运行homestead up或homestead ssh等命令。
Windows
在系统的任意位置创建一个批处理文件homestead.bat，内容如下：
@echo off set cwd=%cd% set homesteadVagrant=C:\Homestead cd /d %homesteadVagrant% && vagrant %* cd /d %cwd% set cwd= set homesteadVagrant=
一定要将脚本中C:\Homestead路径调整为 Homestead 的实际安装路径。创建文件后，将文件路径添加到PATH。然后你就可以在系统任意位置运行homestead up或homestead ssh等命令。
通过 SSH 连接
你可以通过在 Homestead 目录下运行vagrant ssh终端命令以 SSH 的方式连接到虚拟机。
但是，你可能需要频繁连接 Homestead 虚拟机，因此请考虑将上面的「函数」添加到主机以便快速地以 SSH 方式连接到 Homestead 虚拟机。
连接数据库
homestead默认已经在虚拟机中为 MySQL 和 PostgreSQL 数据库做好了配置。为了方便起见， Laravel 中的.env文件将框架配置成默认使用此数据库。
要从主机的数据库客户端连接到 MySQL 或 PostgreSQL ，应该连接到127.0.0.1，端口33060（MySQL） 或54320（PostgreSQL）。用户名和密码分别是homestead/secret。
{note} 只有从本地连接 Hoemstead 的数据库时才能使用这些非标准的端口。而 Laravel在虚拟机中运行时还是应该使用默认的 3306 和 5432 端口进行数据库连接。
数据库备份
当你的 Vagrant 盒子销毁时，Homestead 能自动备份你的数据库。为了利用这个功能，你必须使用 Vagrant 2.1.0 或者更高的版本。或者，如果你使用一个旧版本的 Vagrant，你必须安装vagrant-triggers插件。为了开启自动数据库备份，添加如下的行到你的Homestead.yaml文件：
backup: true
一旦配置了，当vagrant destroy命令被执行时，Homestead 将导出你的数据库到mysql_backup和postgres_backup目录。如果你使用 每个项目安装 方法，则可以在克隆的 Homestead 或者在你的项目根目录中找到这些目录。
添加额外的站点
一旦你的 Homestead 环境已配置并运行，你可以为你的 Laravel 应用添加额外的 Nginx 站点。你可能希望在单个 Homestead 环境运行多个 Laravel 安装。要添加额外的站点，到Homestead.yaml文件中添加站点：
sites: - map: homestead.test to: /home/vagrant/code/my-project/public - map: another.test to: /home/vagrant/code/another/public
如果 Vagrant 不能自动管理你的『hosts』文件，你可能还需要添加新的站点到该文件中：
192.168.10.10 homestead.test 192.168.10.10 another.test
一旦这个站点被添加，从你的 Homestead 目录运行vagrant reload --provision命令。
站点类型
Homestead 支持多种类型的站点，允许你轻松运行不是基于 Laravel 的项目。例如，我们可以使用symfony2站点类型轻松地添加一个 Symfony 应用到 Homestead：
sites: - map: symfony2.test to: /home/vagrant/code/my-symfony-project/web type: "symfony2"
可用的站点类型是：apache，apigility，expressive，laravel（默认），proxy，silverstripe，statamic，symfony2，symfony4，和zf。
站点参数
你可以通过params站点指令添加额外的 Nginxfastcgi_param值到你的站点。例如，我们添加一个值为BAR的Foo参数：
sites: - map: homestead.test to: /home/vagrant/code/my-project/public params: - key: FOO value: BAR
环境变量
你能通过添加如下的值到Homestead.yaml文件来设置全局环境变量：
variables: - key: APP_ENV value: local - key: FOO value: bar
更新Homestead.yaml文件之后，确保通过运行vagrant reload --provision命令重新配置机器。这个将更新所有安装 的 PHP 版本的 PHP-FPM 配置并为vagrant用户更新环境。
配置定时计划
Laravel 提供了一种 计划定时作业 的方式，通过安排单个schedule:runArtisan 命令去每分钟运行。schedule:run命令将检查在你在App\Console\Kernel类中定义的计划来决定运行哪个作业。
如果你想为一个 Homestead 站点的schedule:run命令运行起来，在定义站点时，你可以设置schedule选项为true：
sites: - map: homestead.test to: /home/vagrant/code/my-project/public schedule: true
站点的 Cron 作业将被定义在虚拟机的/etc/cron.d目录中。
Configuring Mailhog
Mailhog 允许你轻松地捕获外发的电子邮件并进行检查它，而实际上没有将发送邮件给收件人。开始使用时，使用以下的邮件设置更新你的.env文件：
MAIL_DRIVER=smtp MAIL_HOST=localhost MAIL_PORT=1025 MAIL_USERNAME=null MAIL_PASSWORD=null MAIL_ENCRYPTION=null
一旦 Mailhog 被配置，你可以在http://localhost:8025上访问 Mailhog 控制面板。
配置 Minio
Minio 是一个开源的对象存储服务器，具有与 Amazon S3 兼容的 API。要安装 Minio，用以下的配置选项更新你的Homestead.yaml文件：
minio: true
默认情况下，Minio 在端口9600上是可用的。你可以访问 Minio 控制面板通过访问http://homestead:9600。默认访问的键名是homestead，同时默认的密钥是secretkey。当访问 Minio 时，你应当总是使用us-east-1。
为了使用 Minio，你将需要在你的config/filesystems.php配置文件中调整 S3 磁盘配置。你将需要添加use_path_style_endpoint选项到磁盘配置，并将url键更改为endpoint：
's3' => [ 'driver' => 's3', 'key' => env('AWS_ACCESS_KEY_ID'), 'secret' => env('AWS_SECRET_ACCESS_KEY'), 'region' => env('AWS_DEFAULT_REGION'), 'bucket' => env('AWS_BUCKET'), 'endpoint' => env('AWS_URL'), 'use_path_style_endpoint' => true ]
最后，确保你的.env文件有如下的选项：
AWS_ACCESS_KEY_ID=homestead AWS_SECRET_ACCESS_KEY=secretkey AWS_DEFAULT_REGION=us-east-1 AWS_URL=http://homestead:9600
为了配置存储桶，在 Homestead 配置文件中添加一个buckets指令：
buckets: - name: your-bucket policy: public - name: your-private-bucket policy: none
支持的policy值包括：none，download，upload和public。
端口
默认情况下，如下的端口将转发到你的 Homestead 环境：
- SSH：2222 -> 转发到 22
- ngrok UI：4040 -> 转发到 4040
- HTTP：8000 -> 转发到 80
- HTTPS：44300 -> 转发到 443
- MySQL：33060 -> 转发到 3306
- PostgreSQL：54320 -> 转发到 5432
- MongoDB：27017 -> 转发到 27017
- Mailhog：8025 -> 转发到 8025
- Minio：9600 -> 转发到 9600
转发额外的端口
如果你愿意，你可以转发额外的端口到 Vagrant 盒子，同时也指定他们的协议：
ports: - send: 50000 to: 5000 - send: 7777 to: 777 protocol: udp
共享你的环境
有时你希望共享你当前工作的内容跟同事或客户。Vagrant 有内置的方法通过vagrant share去支持这个；然而，如果在Homestead.yaml文件中有多个站点配置，这个将不会工作。
为了解决这个问题，Homestead 包含它自己的share命令。开始时，SSH 通过vagrant ssh进入你的 Homestead 机器并运行share homestead.test。这个将从你的Homestead.yaml配置文件中分享homestead.test站点。当然，你可以将任何其它配置的站点替换为homestead.test：
share homestead.test
运行此命令之后，你将看到一个 Ngrok 屏幕出现，其中包含了活动日志和共享站点的可访问的 URLs。如果你想指定一个自定义的区域，子域，或者其它 Ngrok 运行时选项，你可以添加他们到你的share命令：
share homestead.test -region=eu -subdomain=laravel
{note} 记住，Vagrant 本质上是不安全的，并且在运行
share命令时将虚拟机显露到互联网。
多版本 PHP
Homestead 6 在同一个虚拟机上引入了对多个 PHP 版本的支持。你可以在你的Homestead.yaml文件中指定要用于给定站点的 PHP 版本。可用的 PHP 版本是：『7.1』，『7.2』和『7.3』（默认）：
sites: - map: homestead.test to: /home/vagrant/code/my-project/public php: "7.1"
另外，你可以通过 CLI 使用任何支持的 PHP 版本：
php7.1 artisan list php7.2 artisan list php7.3 artisan list
Web 服务器
默认情况下，Homestead 使用 Nginx web 服务器。然而，如果apache是指定的一个站点类型，它能安装 Apache。同时两个 web 服务器在同时被安装，他们不能同时运行。flip脚本命令可用来轻松处理 web 服务器之间的切换。flip命令自动确定正在运行的 web 服务器，将其关闭。然后启动其它服务器。要使用这个命令，SSH 进入到你的 Homestead 机器并在终端运行命令：
flip
邮件
Homestead 包括 Postfix 邮件传输代理，默认监听1025端口。因此，你可以指示你的应用程序在localhost端口1025上使用smtp邮件驱动。所有发送的邮件将由 Postfix 处理并由 Mailhog 捕获。要查看已发送的邮件，在 web 浏览器中打开http://localhost:8025。
网络接口
Homestead.yaml中的networks属性为 Homestead 环境配置网络接口。你可以根据需要配置多个接口：
networks: - type: "private_network" ip: "192.168.10.20"
要开启一个桥接接口，配置bridge设置并改变public_network网络类型：
networks: - type: "public_network" ip: "192.168.10.20" bridge: "en1: Wi-Fi (AirPort)"
要开启DHCP，仅从你的配置中移除ip选项：
networks: - type: "public_network" bridge: "en1: Wi-Fi (AirPort)"
扩展 Homestead
你能在 Homestead 根目录下使用after.sh脚本扩展 Homestead。在这个文件中，你可以添加正确配置和自定义虚拟机所需的任何 shell 命令。
当自定义 Homestead 时，Ubuntu 可能会询问你是否要保留程序包的原始配置或者用一个新的配置文件覆盖它。为了避免这种情况，你应该在安装软件包时使用以下的命令，以避免覆盖之前由 Homestead 编写的任何配置：
sudo apt-get -y \ -o Dpkg::Options::="--force-confdef" \ -o Dpkg::Options::="--force-confold" \ install your-package
更新 Homestead
你能通过一些简单的步骤更新 Homestead。首先，你应当使用vagrant box update命令更新 Vagrant 盒子：
vagrant box update
接下来，你需要去更新 Homestead 源代码。如果你克隆过仓库，你能在最初克隆仓库的位置运行如下的命令：
git fetchgit checkout v8.0.1
这些命令从 GitHub 仓库拉取最新的 Homestead 代码，获取最新的标记，然后检出最新的标记版本。你能在GitHub 版本页面找到最新稳定的版本。
如果你通过你的项目的composer.json安装 Homestead，你应当确保你的composer.json包含"laravel/homestead": "^8"并更新你的依赖项：
composer update
最后，你将需要销毁和重新生成你的 Homestead 盒子去利用最新的 Vagrant 安装。为了实现这个，在你的 Homestead 目录运行如下的命令：
vagrant destroy vagrant up
提供特殊设置
VirtualBox
natdnshostresolver
默认情况下，Homestead 将natdnshostresolver配置设置为on。这允许 Homestead 去使用你的主机操作系统的 DNS 设置。如果你不想覆盖这个行为，添加如下的行到你的Homestead.yaml文件：
provider: virtualbox natdnshostresolver: off
Windows 上的符号链接
如果符号链接在你的 Windows 机器上无法正常工作，你可能需要添加以下的块到Vagrantfile文件：
config.vm.provider "virtualbox" do |v| v.customize ["setextradata", :id, "VBoxInternal2/SharedFoldersEnableSymlinksCreate/v-root", "1"] end