[TOC] # 概況 Phalcon Box使用[Vagrant Cloud](https://atlas.hashicorp.com/phalconphp/boxes/xenial64/)的默認**phalcon/xenial64** box 來兼容。如果您選擇使用64位ISO，則可能需要更新BIOS以使用`AMD-V`，`Intel VT-x`或`VIA VT`進行虛擬化。 第一次使用`vagrant up`配置新環境時，由于必須首先將box（`phalconphp/xenial64`）下載到本地計算機，因此該過程將花費更長的時間。任何后續的環境條款都會快得多。 ## 要求 * 操作系統： Windows, Linux, or macOS * [Virtualbox](https://www.virtualbox.org/wiki/Downloads) >= 5.1 (如果使用 Virtualbox box) * [VMware Fusion](http://www.vmware.com/products/fusion) (或者 Workstation - 如果使用 VMware box) * [Vagrant](https://www.vagrantup.com/downloads.html) >= 1.9.8 ## 預裝軟件 * Ansible * Beanstalkd * Blackfire * Composer * Git * goreplace * Mailhog * Memcached * MongoDB * MySQL * Nginx * Ngrok * Node.js (with Yarn, Bower, Grunt, and Gulp) * PHIVE * PHP 7.1 * PHPMD * PHP_CodeSniffer * Phalcon * Phing * PostgreSQL * Redis * Sqlite3 * Ubuntu 16.04 * Zephir ## 安裝 ### 安裝 Vagrant Box 在啟動Phalcon Box環境之前，您必須安裝VirtualBox，VMWare以及Vagrant。所有這些軟件包都為所有流行的操作系統提供易于使用的可視化安裝程序。 安裝VirtualBox/VMWare和Vagrant后，應使用終端中的以下命令將`phalconphp/xenial64` box 加到Vagrant安裝中。下載此box將需要幾分鐘，具體取決于您的網絡連接速度： ```bash vagrant box add phalconphp/xenial64 ``` 如果此命令失敗，請確保您的Vagrant安裝是最新的。 >[warning] 要使用`VMware`，您需要同時購買`VMware Fusion/Workstation`和[VMware Vagrant](https://www.vagrantup.com/vmware)插件。雖然它不是免費的，但VMware可以提供更快的共享文件夾功能。 ### 安裝 Phalcon Box 您只需clone存儲庫即可安裝`Phalcon Box`。考慮將存儲庫克隆到主目錄中的工作區文件夾中，因為Phalcon Box框將作為所有Phalcon項目的主機： ```bash cd ~ git clone https://github.com/phalcon/box.git workspace ``` `master`分支將始終包含Phalcon Box的最新穩定版本。如果您想查看當前正在開發的舊版本或更新版本，請切換到相關的branch/tag。 (https://github.com/phalcon/box/releases): 您可以在[Github發布頁面](https://github.com/phalcon/box/releases)上找到最新的穩定版本： ```bash # Clone the desired release... git checkout v2.4.0 ``` 克隆Phalcon Box存儲庫后，從Phalcon Box根目錄運行install命令以創建`settings.yml`配置文件。`settings.yml`文件將放在Phalcon Box目錄中： ```bash # macOS || Linux ./install ``` ```cmd rem Windows install.bat ``` 現在您已準備好配置虛擬機，運行： ```bash vagrant up ``` <a name='installation-configuration'></a> ## 配置 ### 設置您的提供平臺 `settings.yml`文件中的提供程序密鑰指示應使用哪個Vagrant提供程序：`virtualbox`，`vmware_fusion`或`vmware_workstation`。您可以將其設置為您喜歡的提供平臺： ```yaml provider: virtualbox ``` ### 內存和 CPU 默認情況下，此設置使用2GB RAM。您可以在`settings.yml`中更改此設置，只需運行`vagrant reload`： ```yaml memory: 4096 ``` 如果您愿意，也可以使用多個cup，只需在同一文件中更改此行： ```yaml cpus: 4 ``` ### 共享文件夾 `settings.yml`文件的`folders`屬性列出了您希望與Phalcon Box環境共享的所有文件夾。當這些文件夾中的文件發生更改時，它們將在本地計算機和Phalcon Box環境之間保持同步。您可以根據需要配置任意數量的共享文件夾： ```yaml folders: - map: ~/workspace to: /home/vagrant/workspace ``` 要啟用[NFS](https://www.vagrantup.com/docs/synced-folders/nfs.html)，只需在同步文件夾配置中添加一個簡單標志： ```yaml folders: - map: ~/workspace to: /home/vagrant/workspace type: "nfs" ``` You may also pass any options supported by Vagrant's [Synced Folders](https://www.vagrantup.com/docs/synced-folders/basic_usage.html) by listing them under the `options` key: 您也可以通過在選項鍵下列出Vagrant[同步文件夾](https://www.vagrantup.com/docs/synced-folders/basic_usage.html)支持的任何`options`： ```yaml folders: - map: ~/workspace to: /home/vagrant/workspace type: "nfs" options: rsync__args: ["--verbose", "--archive", "--delete", "-zz"] rsync__exclude: ["node_modules"] ``` >[danger] macOS用戶可能需要安裝`vagrant-bindfs`插件來修復共享文件夾（NFS）權限問題： ```bash vagrant plugin install vagrant-bindfs ``` ### Nginx站點 `sites`屬性允許您輕松地將“域”映射到Phalcon Box環境中的文件夾。`settings.yml`文件中包含示例站點配置。您可以根據需要向Phalcon Box環境添加任意數量的站點。Phalcon Box可作為您正在處理的每個Phalcon項目的便捷虛擬化環境： ```yaml sites: - map: phalcon.local to: /home/vagrant/workspace/phalcon/public ``` 您可以使用`type`參數指定站點的Nginx配置類型。例如： ```yaml sites: - map: landing.local to: /home/vagrant/workspace/landing/public type: spa ``` 默認類型是`phalcon`。如果不允許或不提供所需類型，`phalcon`將用作后備。 可用類型： * `phalcon` * `slayer` * `phanbook` * `proxy` * `spa` * `silverstripe` * `symfony2` * `statamic` * `laravel` * `zend` 通過打開[新功能請求](https://github.com/phalcon/box/issues/new)，隨意建新類型的Nginx配置。 >[warning] 如果在配置Phalcon Box后更改`sites`屬性，則必須重新運行`vagrant reload --provision`以更新虛擬機上的Nginx配置。 #### 自定義Nginx配置 您也可以創建自己的類型。為此，請將`provisioning/templates/nginx`文件夾中的任何模板作為基礎并進行必要的更改。您需要將此文件放在同一文件夾中。之后，您將能夠使用自己的自定義類型： ```yaml sites: - map: my-site.local to: /home/vagrant/workspace/my-site/public # provisioning/templates/nginx/phalcon-advanced.conf.j2 type: phalcon-advanced ``` 您需要自定義*全局*Nginx配置嗎？是的，這是可能的。Fox示例，讓我們創建autoindex配置。 文件 `/home/user/nginx.d/00-autoindex.conf`： ```nginx # Processes requests ending with the slash character (‘/’) and produces a directory listing autoindex on; ``` 將所需的設置添加到您的文件，然后將其添加到 `copy`部分： ```yaml copy: - from: /home/user/nginx.d/00-autoindex.conf to: /etc/nginx/conf.d/ ``` #### 配置`hosts`文件 您必須將Nginx站點的“域”添加到計算機上的hosts文件中。hosts文件會將Phalcon站點的請求重定向到Phalcon Box計算機。在Mac和Linux上，此文件位于`/etc/hosts`。在Windows上，它位于`C:\Windows\System32\drivers\etc\hosts`。您添加到此文件的行將如下所示： 192.168.50.4 phalcon.local 確保列出的IP地址是`settings.yml`文件中設置的IP地址。將域添加到`hosts`文件并啟動Vagrant框后，您將可以通過Web瀏覽器訪問該站點： http://phalcon.local >[danger] 要啟用將新站點添加到`hosts`文件，請自動使用`vagrant-hostsupdater`插件： ```bash vagrant plugin install vagrant-hostsupdater ``` ### 安裝其他軟件包 我們盡最大努力為Phalcon Box提供所有必要的程序和庫。然而，應該理解，典型的用戶不需要可以安裝的所有可能的包。Phalcon Box必須具有合理的尺寸，以便即使是那些在互聯網頻道帶寬方面遇到困難的人也可以使用它。 出于這些考慮，我們允許用戶指定每個配置所需的自定義包。要安裝必要的軟件包，請在`apt`部分添加其名稱： ```yaml # Provisioning features provision: # do full system update for each full provisoning update: true # Install wkhtmltopdf and libffi-dev packages apt: - wkhtmltopdf - libffi-dev ``` ### 運行Phalcon Box 根據自己的喜好編輯`settings.yml`后，從Phalcon Box目錄運行`vagrant up`命令（例如`$HOME/workspace`）。Vagrant將啟動虛擬機并自動配置您的共享文件夾和Nginx站點。 要銷毀機器，可以使用`vagrant destroy --force`命令。 ## 日常使用 ### 全局訪問Phalcon Box Phalcon Box installation: 有時你可能想要從文件系統的任何地方`vagrant up`你的Phalcon Box機器。您可以在Mac或Linux系統上通過向Bash配置文件添加[Bash function](http://tldp.org/HOWTO/Bash-Prog-Intro-HOWTO-8.html)來執行此操作。在Windows上，您可以通過向`PATH`添加“批處理”文件來完成此操作。這些腳本允許您從系統的任何位置運行任何Vagrant命令，并自動將該命令指向Phalcon Box安裝： #### Mac || Linux ```bash function box() { ( cd $HOME/workspace && vagrant $* ) } ``` >[warning] 確保將函數中的`$HOME/workspace`路徑調整到實際Phalcon Box安裝的位置。安裝該功能后，您可以從系統的任何位置運行`box up`或`box ssh`等命令。 #### Windows 使用以下內容在計算機的任何位置創建`box.bat`批處理文件： ```cmd @echo off set cwd=%cd% set box=C:\workspace cd /d %box% && vagrant %* cd /d %cwd% set cwd= set box= ``` >[warning] 確保將腳本中的示例`C:\workspace`路徑調整為Phalcon Box安裝的實際位置。創建文件后，將文件位置添加到`PATH`。然后，您可以從系統的任何位置運行諸如`box up`或`box ssh`之類的命令。 ### 通過SSH連接 您可以通過從Phalcon Box目錄發出`vagrant ssh` 終端命令來SSH命令進入到您的虛擬機。 但是，由于您可能需要經常SSH到Phalcon Box機器，請考慮將上述“功能”添加到主機以快速SSH到Phalcon Box。 ### 連接數據庫 要從主機的數據庫客戶端連接到MySQL，Postgres或MongoDB數據庫，您應該連接到`127.0.0.1`和端口`33060`（MySQL），`54320`（Postgres）或`27017`（MongoDB）。數據庫的用戶名和密碼是`phalcon` / `secret`。 >[danger] 從主機連接到數據庫時，只應使用這些非標準端口。由于Phalcon在虛擬機中運行，因此您將使用Phalcon數據庫配置文件中的默認330和``端口。 要從Phalcon Box類型訪問交互式數據庫控制臺，請執行以下操作： * **Postgres:** `psql -U phalcon -h localhost` (密碼 `secret`) * **MySQL:** `mysql` (CLI工具不需密碼) * **MongoDB:** `mongo` (CLI工具不需密碼) ### 添加其他站點 配置并運行Phalcon Box環境后，您可能需要為應用程序添加其他Nginx站點。您可以在單個Phalcon Box環境中運行任意數量的Phalcon項目。要添加其他站點，只需將站點添加到`settings.yml`文件： ```yaml sites: - map: phalcon.local to: /home/vagrant/workspace/phalcon/public - map: pdffiller.local to: /home/vagrant/workspace/pdffiller/public - map: blog.local to: /home/vagrant/workspace/blog/public ``` 如果Vagrant沒有自動管理您的“hosts”文件，您可能還需要將新站點添加到該文件： 192.168.50.4 phalcon.local 192.168.50.4 pdffiller.local 192.168.50.4 blog.local >[danger] 要啟用將新站點添加到`hosts`文件，請自動使用`vagrant-hostsupdater`插件： ```bash vagrant plugin install vagrant-hostsupdater ``` 添加站點后，從Phalcon Box目錄運行`vagrant reload --provision`命令。 ### 環境變量 #### 全局變量 您可以輕松注冊全局環境變量。只需將變量及其值添加到`variables`部分： ```yaml variables: - key: TEST_DB_MYSQL_USER value: phalcon - key: TEST_DB_MYSQL_PASSWD value: secret - key: TEST_DB_MYSQL_DSN value: "mysql:host=127.0.0.1;dbname=phalcon_test" ``` 這樣，您就可以在應用程序或腳本中使用這些變量。例如，以這種方式配置[Codeception](http://codeception.com)： ```yaml # File codeception.yml params: # Get params from environment - env ``` 您可以按如下方式配置Unit套件： ```yaml # File tests/unit.suite.yml class_name: UnitTester modules: enabled: - Db config Db: dsn: %TEST_DB_MYSQL_DSN% user: %TEST_DB_MYSQL_USER% password: %TEST_DB_MYSQL_PASSWD% populate: true cleanup: false dump: tests/_data/schemas/mysql/mysql.dump.sql ``` #### Site變量 Site 變量是指如何在Phalcon Box中輕松將`fastcgi_param`值添加到站點主機配置中。例如，我們可以添加`development`這個值給`APP_ENV`變量： ```yaml sites: - map: phalconbox.local to: /var/www/phalconbox/public variables: - key: APP_ENV value: development # Yet another example - key: AMQP_DEBUG value: true ``` ### 端口 默認情況下，以下端口將轉發到Phalcon Box環境： | 轉發港口 | Phalcon Box | 主機系統 | | -------------- |:-----------:|:-----------:| | **SSH** | `22` | `2222` | | **HTTP** | `80` | `8000` | | **HTTPS** | `443` | `44300` | | **MySQL** | `3306` | `33060` | | **Postgres** | `5432` | `54320` | | **MailHog** | `8025` | `8025` | #### 轉發其他端口 如果您愿意，您可以將其他端口轉發到Phalcon Box，并指定其協議： ```yaml ports: - send: 63790 to: 6379 - send: 50000 to: 5000 - send: 7777 to: 777 protocol: udp ``` ### 分享您的環境 有時您可能希望與同事或客戶分享您目前正在處理的內容。Vagrant有一種內置的方式`vagrant share`來支持;但是，如果您在`settings.yml`文件中配置了多個站點，則無法使用此功能。 為解決此問題，Phalcon Box包含自己的`share`命令。首先，通過`vagrant ssh` SSH到Phalcon Box機器并運行`share <your-site-here>`，例如：`share blog.local`。這將從`settings.yml`配置文件共享您的站點。當然，您可以將任何其他配置的站點替換為`blog.local`： ```bash share blog.local ``` 運行該命令后，您將看到一個[Ngrok](https://ngrok.com)屏幕，其中包含活動日志和共享站點的可公開訪問的URL。如果要指定自定義區域，子域或其他Ngrok運行時選項，可以將它們添加到`share`命令： ```bash share blog.local -region=eu -subdomain=phalcongelist ``` >[danger] Vagrant本質上是不安全的，您在運行`share`命令時將虛擬機暴露給互聯網。 ### 網絡接口 `settings.yml`的`networks`屬性為Phalcon Box環境配置網絡接口。您可以根據需要配置任意數量的接口： ```yaml networks: - type: "private_network" ip: "192.168.50.99" ``` 要啟用[橋接](https://www.vagrantup.com/docs/networking/public_network.html)接口，請配置`網橋`設置并將網絡類型更改為`public_network`： ```yaml networks: - type: "private_network" ip: "192.168.50.99" bridge: "en1: Wi-Fi (AirPort)" ``` 要啟用[DHCP](https://www.vagrantup.com/docs/networking/public_network.html)，只需從此配置中刪除`ip`選項： ```yaml networks: - type: "private_network" bridge: "en1: Wi-Fi (AirPort)" ``` ### 更新Phalcon Box 您可以通過兩個簡單的步驟更新Phalcon Box。 1. 首先，您需要使用`vagrant box update`命令更新Vagrant框： ```bash vagrant box update ``` 2. 接下來，您需要更新Phalcon Box源代碼。如果你克隆了存儲庫，你可以簡單地 ```bash git pull origin master ``` 在您最初克隆存儲庫的位置。 新版Phalcon Box將包含更新或修改的配置文件： * `settings.yml` * `.bash_aliases` * `after_provision.sh` 運行命令`./install`（或`install.bat`）時，Phalcon Box會在根目錄中創建這些文件。但是，如果文件已存在，則不會覆蓋它們。 我們建議您始終對這些文件進行備份，并將其從項目中刪除，以便可以復制新更新的文件。然后，您可以將自己的文件與phalcon框進行比較，以應用您的個性化更改并利用更新提供的新功能。 ### 提供平臺特定設置 #### VirtualBox 默認情況下，Phalcon Box將`natdnshostresolver`設置配置為`on`。這允許Phalcon Box使用您的主機操作系統的DNS設置。如果要覆蓋此行為，請將以下行添加到`settings.ym`l文件中： ```yaml natdnshostresolver: off ``` ### Mail捕捉器 默認情況下，Phalcon Box會將所有PHP電子郵件重定向到[MailHog](https://github.com/mailhog/MailHog) （而不是將它們發送到外部世界）。您可以在`http://localhost:8025/`（或您在`settings.yml`中配置的任何域）訪問MailHog UI。 ## 故障排除 **問題：** > An error occurred in the underlying SSH library that Vagrant uses. The error message is shown below. In many cases, errors from this library are caused by ssh-agent issues. Try disabling your SSH agent or removing some keys and try again. If the problem persists, please report a bug to the net-ssh project. timeout during server version negotiating **解決：** ```bash vagrant plugin install vagrant-vbguest ``` **問題：** > Vagrant was unable to mount VirtualBox shared folders. This is usually because the filesystem "vboxsf" is not available. This filesystem is made available via the VirtualBox Guest Additions and kernel module. Please verify that these guest additions are properly installed in the guest. This is not a bug in Vagrant and is usually caused by a faulty Vagrant box. For context, the command attempted was: > > mount -t vboxsf -o uid=900,gid=900 vagrant /vagrant **解決：** ```bash vagrant plugin install vagrant-vbguest ``` **問題：** > There was an error while executing `VBoxManage`, a CLI used by Vagrant for controlling VirtualBox. The command and stderr is shown below. > > Command: `["startvm", "9d2b95e1-0fdd-40f4-ad65-4b56eb4315f8", "--type", "headless"]` > > Stderr: VBoxManage.exe: error: VT-x is not available (VERR_VMX_NO_VMX) VBoxManage.exe: error: Details: code E_FAIL (0x80004005), component ConsoleWrap, interface IConsole **解決：** 您需要更新BIOS以使用`Intel VT-x`啟用[虛擬化](https://en.wikipedia.org/wiki/X86_virtualization)。