Jump to content

MediaWiki-Vagrant

本頁使用了標題或全文手工轉換
问题追踪器： #MediaWiki-Vagrant
From mediawiki.org
This page is a translated version of the page MediaWiki-Vagrant and the translation is 100% complete.
Languages:
Vagrant可视化概覽
Vagrant可视化概覽
MediaWiki Vagrant徽標
MediaWiki Vagrant徽標
Bryan Davis在维基媒体国际会议的采访中解释了MediaWiki Vagrant是什么
由Bryan Davis和Dan Duvall針對MediaWiki-Vagrant在TechTalk的發表
由Bryan Davis和Dan Duvall針對MediaWiki-Vagrant在TechTalk上发布的幻灯片

MediaWiki-Vagrant是一个可攜式的MediaWiki开发环境。它由一組Vagrant和VirtualBox的配置脚本所組成，它可將一個运行MediaWiki虚拟机的创建自动化。 由于配置應是著重在易於开发而不是安全，因此MediaWiki-Vagrant不建议用在可公开存取的维基。

用MediaWiki-Vagrant创建的虚拟机使得它易于学习、修改、並完善MediaWiki的代码：有用的调试信息是默认显示的，各种开发人员工具都是专门用来检視和与MediaWiki代码进行交互的，其包括一个强大的调试器和交互式直譯器。 最棒的是，因为配置是自动化產生的、且被封裝在虚拟环境中，所以出错的东西可以輕易還原。

系统需求

CPU
64位x86处理器
作業系統
Linux、macOS或者Windows
内存
系统至少需要4GB的RAM，最好是8GB或更多，以便同时运行host操作系统和虚拟机，不要尝试在只有2GB的RAM上运行，它最终会失败。
磁盘
对于复杂的安装，至少需要10-12 GB的主驱动器空间（Linux上的/home分区，Windows上的C:盘符）。请特别注意：默认情况下，虚拟机磁盘镜像将储存在您的主目录下。
网络
具有足够的带宽和活动的网络连接以下载Debian Linux更新和MediaWiki源代码。
时间
20分钟至2小时，视情况而定，例如您遇到任何麻烦。

快速入门

（如果要从USB发行版安装MediaWiki-Vagrant，请按照README中的步骤而不是前五个步骤进行操作。）

  1. 获取Git
  2. （仅限Linux） 安装NFS，如果它尚未安装。
    • 在Ubuntu中，使用sudo apt-get install nfs-kernel-server。
    • Fedora通常已預先安装好NFS；如果没有，請运行sudo dnf install nfs-utils。
  3. 获取VirtualBox[1]
  4. 获取Vagrant. Note that Vagrant v2.3.7 is the last version licensed under a free license.[2]
  5. 将代码克隆到您的当前資料夾 （請勿完全複製至WSL的資料夾中）[3] 
    $ git clone --recursive https://gerrit.wikimedia.org/r/mediawiki/vagrant
  6. 請進入vagrant資料夾去執行 vagrant 指令： 
    $ cd vagrant
  7. 在啟動機器前，請執行設定腳本以設定 Vagrant：
    Linux/macOS:
    $ ./setup.sh
    Windows:
    $ .\setup.bat
    出现提示时，請鍵入Gerrit的用户名（此為建議），或直接按↵ Enter。
    如果要使用某個已发布的分支而不是最新版本，可以在現在使用vagrant hiera mediawiki::branch REL1_27指定它
  8. 启动虚拟机： 
    $ vagrant up
    首次執行此操作時，系統可能會要求您輸入密碼，因為透過NFS設定資料夾共享需要系統管理員權限。 您可以透過設定適當的 sudo 權限來避開這個，如此處所述。
    請留意終端機的輸出，確保沒有發生任何錯誤。 若您遇上錯誤，請參閱#啟動疑難排解部份，其可能有所幫助。
  9. 執行指令vagrant open以開啟您的MediaWiki实例。 可以用用户Admin和密码vagrant登录。
  10. 启用额外的MediaWiki功能与扩展。
    要查看可啟用的功能清單（Vagrant角色），請執行：
    $ vagrant roles list
    要啟用某項功能（例如可視化編輯器 ），請執行：
    $ vagrant roles enable visualeditor
    要將您已啟用的角色套用至維基，請執行：
    $ vagrant provision
如果使用默认的VirtualBox提供程序且host OS上的虚拟CPU数超过32個，則vagrant up命令會失败。 請使用vagrant config vagrant_cores <核心数量>来分配32个以內的核心给虚拟机。
在第一个vagrant up命令完成之前可能需要花費一小时或更长的时间。

針對Linux的Windows子系統

如果你有在Windows上使用与WSL Linux兼容的shell：請运行vagrant.exe命令而不是vagrant。运行vagrant.exe config --required命令而不是./setup.bat，这在Linux bash shell中無法正常動作。

运行Vagrant的帐户可能需要“创建符号链接”权限（以管理员身份运行的简单方法）。

启动故障排除

如果您的问题在此未被回答，IRC是個不錯的選擇，尤其是#wikimedia-tech 在线频道。

  • 有时您可以通过运行vagrant destroy; vagrant up来修复损坏的安装（例如，"No wiki found..."，这将重建虚拟机而不会重复最耗时的安装过程部分。

適用於任何的host操作系统

  • 您可以尝试安装Linux发行版提供的VirtualBox和Vagrant版本。如果你正在运行最近的Debian或Ubuntu，请尝试sudo apt-get install virtualbox vagrant来安装VirtualBox和Vagrant的软件包。
  • 如果您有收到來自vagrant up的错误，请改以安装最新版本的VirtualBox和Vagrant。
  • 如果您遇到“无法打开文件$CLONED_REPOSITORY/trusty-cloud”這樣的错误消息，请尝试以下命令： vagrant up --provider=virtualbox
  • 如果你收到任何的Puppet错误，你可能需要初始化Puppet子模块，請在vagrant目录中运行git submodule update --init
    • Error: Puppet::Parser::AST::Resource failed with error ArgumentError: Could not find declared class
  • 請使用http://127.0.0.1:8080/info.php检查Apache/PHP是否已启动并正在运行。

您可能希望将终端中vagrant up的初始运行输出与範例进行比较。初始设置可能需要很长时间，如果它似乎挂在某处但没有错误，只需给它一段时间。

  • 如果您收到有关您的VirtualBox Guest Additions版本错误的警告，您可以尝试安装vagrant-vbguest插件，该插件会將它们自动更新。
  • Vagrant很與与您的VM失去配对。此主题讨论了解决它的一些方法（例如将旧的VM硬盘附加到新的配置文件）
  • 确保vagrant/mediawiki存储库是最新的：
$ cd vagrant/mediawiki
$ git pull
  • 确认你在BIOS启用了虚拟化技术。有时该设置在安全设置中。
  • 确保您的语言编码设置为UTF-8。如果你收到“US-ASCII中的无效字节序列”訊息，请尝试将LANG和LC_ALL环境变量(重新)设置为合适的值。 例如：
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
如果您删除了任何旧的虚拟机，您将看到一条错误消息，像是"...path contains non-directory or non-existent components..."且vagrant up将會不完整。 如果您（在非Windows的host操作系统上）使用的是NFS，您应该可以通过移除/etc/exports来解决此问题：也就是鍵入sudo rm -i /etc/exports這些指令。 Vagrant将會在您下次运行vagrant up时重新创建/etc/exports文件。
MediaWiki-Vagrant不会在不支援VT-X的host OS上运行，因为它指定了一個64位guest OS（虚拟机）。 MediaWiki-Vagrant需要在64位虚拟机上运行，部分原因是它使用维基媒体基金会生产中使用的deb软件包，这些软件包仅为amd64架构而构建。

適用於Windows相关的

  • 如果您在Windows上并且“客户机进入无效状态”-“关机”，请尝试下载4.3.15版本的VirtualBox（在Windows上有個4.3.14版的已知问题）。如果这没有帮助，请确保在BIOS中启用硬件虚拟化技术（VT-x或AMD-V）。硬件虚拟化是必需的。它不是可选的性能增强（有些笔记本电脑需要你移除电源线和电池30秒[1]）。
  • VirtualBox不兼容于微软公司的Hyper-V。 如果你启用了Hyper-V(如果您已安装Visual Studio，這可能是默认的結果)，在尝试在VirtualBox中启动虚拟机时你会遇到上述的错误。 有三种可能性：
    • 請在命令提示符下运行bcdedit / set hypervisorlaunchtype off以关闭Hyper-V然後重新启动。 若要重新启用Hyper-V，请将其设置回復到auto以取代off
    • 請通过“控制面板”中的“添加/删除Windows功能”來禁用Hyper-V，然後重新启动。 这将使VirtualBox正常工作，但会阻止您使用任何你可能已經有的Hyper-V VM，例如Windows Phone模拟器。
    • 或者，請使用Hypeer-V provider取代VirtualBox做為的Vagrant的虛擬機器。 这可能不稳定。

適用於Mac相关的

  • NFS错误为避免NFS错误，在安装时請确保防火墙可以接受连接：Apple>系统偏好设置>安全和隐私>防火墙>防火墙选项。 您需要取消勾選“阻止所有传入连接”并可能还要取消勾選“启用隱形模式”以便允許以下内容：netbiosd、nfsd、rpc.lockd、rpc.rquotad、rpcbind和VBoxHeadless。 请注意，在一对vagrant up期间，您可能需要重新启动计算机并将状态更改为“允许传入连接”。 安装后，您可以重新检查“阻止所有传入连接”和“启用隐形模式”，因为防火墙规则已更新。
    • 或者你可以用 vagrant config nfs_shares off 关闭NFS共享。

適用於Debian和Ubuntu

MediaWiki-Vagrant 使用 NFS 与host机 (你的电脑)共享某些文件夹。 您需要设置您的计算机作为一台“NFS服务器”，請參閱例如：Ubuntu 操作指南。 在Debian上，sudo apt-get install nfs-kernel-server将起作用，您可能还需要載入模組modprobe nfsv3。 请注意，如果/etc/exports中缺少条目，Debian的NFS服务器将无法启动。 如果sudo rpcinfo -p没有显示NFS服务正在运行，這很可能是發生了情況。 請在/etc/exports中将您的主目录添加到最后一行，然后/etc/init.d/nfs-kernel-server restart這道指令通常已足夠以让您解决这个「先有雞還是先有蛋」的問題。

  • MediaWiki-Vagrant所使用的NFS共享无法从加密目录运行，如果您在Ubuntu上运行并使用加密的主目录，则可能是这种情况。要运行MediaWiki-Vagrant，您可以：
    • 在运行vagrant up之前，請将MediaWiki-Vagrant目录移动到未加密的磁碟區（例如/opt）
    • 或者，您可以通过vagrant config nfs_shares off指令將NFS共享关闭
  • NFS设置有时似乎会卡住（正在初始的vagrant up在“挂载NFS共享文件夹”卡住）。 在host OS上重启NFS常駐程式会有所帮助。 （請參见#5802。）
  • 如果您收到端口转发错误，说明端口正在使用中，您可能需要开啟虚拟机、完全删除虚拟机，然后再试一次。
  • vagrant up可能會告訴您：「那個Vagrant正要嘗試執行的可執行檔'bsdtar'未能在PATH變數中找到。」 在Ubuntu上您可以用sudo apt install libarchive-tools解決此問題。
  • 在已有啟用"安全啟動(Secure Boot)"的Ubuntu系統上，安裝VirtualBox將會困難重重。 當你執行/sbin/vboxconfig時，你的機器可能會對你說一堆廢話。 若果真如此，你可以透過對相關的內核模組數位簽名來糾正此一情況。 詳細步驟說明請參閱此篇askubuntu文章。

適用於Fedora

  • 如果你在运行vagrant up之后收到了Network 10.11.12.13 is not available.訊息，請通过sudo setenforce 0禁用SELinux、不然就要修复SELinux的设置。
  • 如果你在运行vagrant roles enable mediawiki --provision之后收到了这个Vagrant管理的机器的provider报告它尚未准备好SSH。訊息，请确保有明確地设置provider，例如可通过vagrant destroy、之後緊接著vagrant up --provider=virtualbox
  • 如果你收到了mount.nfs: mount to NFS server '10.11.12.13:download-directory/vagrant' failed: RPC Error: Unable to receive訊息，請运行vagrant config nfs_shares

基本用法

截图

在host机上的命令行工具vagrant提供了多种可控制您的虚拟机的子命令。 您已经用过一个：vagrant up，其會开启虚拟机。 与大部份的vagrant子命令相同，您需要在MediaWiki-Vagrant目录中或它的其中一個子目录中运行它。 您第一次运行它时，Vagrant会获取一个系统映象并設定運行MediaWiki所需的必備軟體。 此過程在寬頻連線環境下可能耗費1至2小時的CPU運算時間與實際運行時間，但僅需執行一次。 当您未來运行vagrant up時，它会直接启動虚拟机。

vagrant ssh在虚拟机上启动一个交互的登录shell。 它会以用户vagrant为您登录；root权限可通过sudo获得，無需密码。 因为此虚拟机在您电脑中是完全沙盒化的，为了便利性而設定、並非為了安全性。 通常，任何時候您遇需要密码的提示出現，密码就是vagrant。

登入後，您應會看見色彩繽紛的MediaWiki橫幅、以及幾則實用指令的提醒。

指令 phpsh 會啟動一個互動式 PHP 直譯器，其已預先載入MediaWiki的原始碼庫。 您可以鍵入一些程式碼，按下「Enter」鍵，程式碼便會立即執行。 若你是以'='開頭新的一行，其計算結果將以美化排版的格式輸出。 鍵入?可獲取快速協助，或鍵入help start可獲取更多說明。

/vagrant資料夾是對應於您host機上的MediaWiki-Vagrant資料夾，其內容會被共享。 MediaWiki的程式碼安裝在/vagrant/mediawiki裏面。 它可讓您在host機電腦上使用常規的編輯器環境來編輯運行於虛擬機器上的MediaWiki程式碼。

更新

使用vagrant git-update可以使您的git存储库、外部库、和数据库架构保持在最新。 此命令等同于运行：

  1. core中的git pull以及所有扩展和皮肤目录
  2. composer update以確保能取得最新版本的Composer管理函式庫
  3. 最后是update.php脚本。

您还应偶尔（或在需要新功能时）更新MediaWiki-Vagrant本身，vagrant git-update不包括在内。請运行： 

git pull

...此命令是在您的MediaWiki-Vagrant根目录之中。这将會在您运行下列命令时生效： 

vagrant provision

您可以在您執行git pull後立即或稍後執行該指令。

警告 警告： 如果您手动从git更新，您可能还需要运行composer update来下载MediaWiki所需的外部库。 您可以运行checkComposerLockUpToDate.php脚本以查看composer update是否需要。
某些專案含有僅供開發使用的NPM依赖項，這些依赖項不會由Composer安裝。這些大致都可透過find -not \( -name node_modules -prune \) -name package.json命令識別出來，並在更新後依需求於所需目錄中執行npm install手動安裝。

請鍵入 logout 或按下 Ctrl+D 鍵退出虛擬機器。 現在您已回到標準命令提示字元，可執行 vagrant halt 關閉虛擬機器、然後執行 vagrant up 將它重啟。 vagrant destroy會刪除虛擬機器的檔案；若您希望你的實例回復至最原始狀態，此指令相當實用。 （您需要緊接著執行vagrant up指令來供應一個新的實例。）

使用角色

MediaWiki-Vagrant預設會建立一個基本的MediaWiki實例，但它同時也懂得如何設定一系列輔助軟體，包括一些熱門的MediaWiki擴充功能及其依赖項。 這些可選的軟體堆疊統稱為「角色」，MediaWiki-Vagrant提供簡易而強大的命令列介面來管理它們。

$ vagrant roles list # 顯示可用角色的清單。 $ vagrant roles enable 角色 # 為本機器啟用「角色」。 $ vagrant roles disable 角色 # 為本機器停用「角色」。 $ vagrant provision # 完成啟用和/或停用角色的操作後，請執行此指令使變更生效。

請觀看一段簡短的 螢幕錄影影片，了解如何使用角色功能。 角色提供關於某些角色的更多資訊。

若您新增多個角色，可能需要增加提供給 Vagrant 虛擬機器的可用記憶體。 特別是設定「browsertests」角色時，需編譯ffi ruby Gem，它是一個耗費大量記憶體的任務；若編譯失敗，請嘗試釋放虛擬機內的記憶體或增加其記憶體分配量（bug 53864）。

若您有興趣為MediaWiki-Vagrant新增角色，請參閱下方「認證角色」章節。

特定角色的疑難排解

中央认证

某些角色需要特別注意，centralauth 角色不會透過puppet自動執行資料庫遷移，必須手動執行。若在供給此角色時遇到錯誤，請嘗試在擴充功能上執行此腳本、然後檢視其輸出的錯誤訊息： 

mwscript extensions/CentralAuth/maintenance/migrateAccount.php --username 'Admin' --auto

一旦獲得更具體的錯誤訊息，您可能需要從以下遷移清單中找出需要執行的遷移： 

extensions/CentralAuth/db_patches

维基数据

只是單純的一個vagrant roles enable wikidata && vagrant provision會失敗。 以下是一組完整的指令，可讓維基數據角色立即運作起來。 

$ vagrant up
$ vagrant git-update
$ vagrant ssh
$ sudo apt-get update && sudo apt-get upgrade
$ composer selfupdate --update-keys
$ composer config --global process-timeout 9600
$ exit
$ vagrant roles enable wikidata
$ vagrant provision

請注意，第一個供給可能會報錯，因此看似失敗。然而，若執行第二次供給，您將發現一切運作正常。

接著請將瀏覽器指向 http://wikidata.wiki.local.wmftest.net:8080/ 。若要建立新的維基數據項目，請載入 http://wikidata.wiki.local.wmftest.net:8080/wiki/Special:NewItem 、若要建立新屬性，請導航至 http://wikidata.wiki.local.wmftest.net:8080/wiki/Special:NewProperty 。

如何匯入維基數據的匯出檔

Vagrant的import-dump指令，會將XML檔案匯入MediaWiki，不處理預設維基以外的維基（請參見 phab:T183274#3893785）。 您需要在Vagrant虛擬機環境之內執行 importDump.php 腳本。

以下是導入XML匯出檔的程序。 

$ mkdir wikidata_dumps
$ cd wikidata_dumps
  • 下載pages-articles的區塊。例如：
$ wget https://dumps.wikimedia.org/wikidatawiki/latest/wikidatawiki-latest-pages-articles10.xml-p5264684p6341661.bz2
  • 啟用Wikibase實體的匯入功能（參見phab:T72898#1588002）。請在您的 LocalSettings.php 檔案中追加以列這行：
$wgWBRepoSettings[ 'allowEntityImport' ] = true;
  • 以下 BASH 腳本可協助您監控該程序。您可將其貼入 import_wikidata.sh 檔案中。請注意，那個高亮的行會呼叫實際匯入的腳本：
#!/usr/bin/env bash

chunks=$(find wikidata_dumps -type f)
for chunk in $chunks
do
    now=$(date)
    echo "$now: started import of $chunk" >> wd_import.log
    echo "-------------------------------------------" >> wd_import.log
    bzcat $chunk | mwscript importDump.php --wiki=wikidatawiki --uploads --debug --report 10000 2>>wd_import.log
    now=$(date)
    echo "-------------------------------------------" >> wd_import.log
    echo "$now: completed import of $chunk" >> wd_import.log
    echo "===========================================" >> wd_import.log
done
  • 登入Vagrant虚拟机並執行腳本。除錯訊息應會在此處顯示：
$ vagrant ssh
$ cd /vagrant
$ sudo chmod +x import_wikidata.sh
$ ./import_wikidata.sh
  • 您可以在Vagrant虚拟机外部追蹤進度的log：
$ tail -f wd_import.log

高级建議

加速MediaWiki在Windows上的運作

開箱即用MediaWiki很可能會運行很緩慢（載入頁面需耗時5秒以上）。 這是因為虛擬機器使用的是一個讀取檔案速度非常慢的共享檔案系統。 透過(使用指令vagrant plugin install vagrant-winnfsd)安裝外掛程式Vagrant WinNFSd來啟用Windows上的NFS、(使用指令vagrant config nfs_shares true)啟用NFS共享，然後(使用指令vagrant reload)重新啟動機器，應能顯著加快頁面載入的時間。 您還應確保每次啟動機器時都已安裝該外掛程式。[4] 您可透過啟用nfs_cache更進一步提升速度，但請注意，由於一些檔案在使用快取時可能沒有完全更新，您的維基可能會偶爾出現怪異的錯誤。

您還可透過使用 smb_shares 來提升 Mediawiki 的運作速度。 請確保不要與 nfs_shares 同時啟用此功能。 以系統管理員身分在終端機中輸入指令vagrant config smb_shares yes、然後執行指令vagrant reload，來啟用此功能。 若未以系統管理員身分執行，當Vagrant啟動時會一個出現錯誤的警告，且當您前往維基的網址時，會看到這個Wiki not found訊息。 當系統提示時，請輸入您帳戶的使用者名稱（即是您的home user這個目錄的名稱）及密碼（若您的帳戶非採用一般密碼的本機帳戶，則需輸入您的Microsoft帳戶密碼）。

本地MediaWiki核心的副本

有時候，您可能想要藉由移除整個vagrant目錄、或清掉vagrant/mediawiki目錄，來重起爐灶。 為加快Vagrant的供應流程，您可能會考慮保留一個本地的、更新過的MediaWiki核心克隆(完全複製)版本，並將其複製至vagrant/mediawiki目錄中。

例如，假設您正在將 MediaWiki 儲存庫克隆到 ~/projects/mediawiki/： 

# 克隆並將MediaWiki核心的乾淨副本儲存至~/projects/mediawiki/core之內
cd ~/projects/mediawiki/
git clone https://gerrit.wikimedia.org/r/mediawiki/core

# 在~/projects/mediawiki/vagrant中克隆一個vagrant的乾淨副本
cd ~/projects/mediawiki
git clone https://gerrit.wikimedia.org/r/mediawiki/vagrant

# 若子目錄mediawiki不存在，則建立該子目錄
cd ~/projects/mediawiki/vagrant
mkdir ~/projects/mediawiki/vagrant/mediawiki

# 將乾淨的MediaWiki核心複製到乾淨的vagrant/mediawiki目錄之中
cp -r ~/projects/mediawiki/core/ ~/projects/mediawiki/vagrant/mediawiki

更新已複製之儲存庫

請盡可能(必要時)盡快更新已克隆的儲存庫。 

cd ~/projects/mediawiki/core
git pull

cd ~/projects/mediawiki/vagrant
git pull
git submodule update --init --recursive

或是，一招勝百招，更新所有已克隆的儲存庫： 

vagrant git-update

Vagrant的重新載入

若您改變組態（例如 vagrant_ram），導致虛擬機器/MediaWiki網站卡住、或發生問題時，執行vagrant reload指令可能有助於解決問題。 這將會讓您的guest重新啟動。 某些角色同樣需要重新載入，這會自動發生。

何時啟用各個角色

請在您首次成功運行 vagrant up 之後，方可啟用相關角色。

請注意，vagrant destroy 將「不會」重設已啟用的角色。 執行 vagrant destroy 後，請務必停用所有角色，然後再執行 vagrant up。 然後您即可重新啟用任何的角色，然後執行 vagrant provision 指令。

在代理伺服器後端的Vagrant

若您身處於代理伺服器的後端，Vagrant可能會拋出若干的錯誤。 您可以安装vagrant-proxyconf。 這是一個插件，可讓您的虛擬機器使用指定的代理伺服器。 這是快速設定指南。 如需詳細文檔說明，請參閱此處。

安装插件： 

vagrant plugin install vagrant-proxyconf

若要為所有的Vagrant虛擬機器上的所有軟體設定代理伺服器，請將以下內容新增至您的 $VAGRANT_HOME/Vagrantfile（預設為 ~/.vagrant.d/Vagrantfile）之中。 

Vagrant.configure("2") do |config|
  if Vagrant.has_plugin?("vagrant-proxyconf")
    config.proxy.http     = "http://192.168.0.2:3128/"
    config.proxy.https    = "http://192.168.0.2:3128/"
    config.proxy.no_proxy = "localhost,127.0.0.1,.example.com"
  end
  # ...其他事
end

請將上述地址替換為您的代理伺服器之IP位址與連接埠號碼。 請使用選項config.proxy.no_proxy來列出所有您可能需要繞過代理伺服器的網站或網域。例如： 

config.proxy.no_proxy = "localhost,127.0.0.1,.example.com,.someinternaldomain.com"

此時，當你執行 vagrant up 時，不應該出現任何警告訊息。

要停用此外掛程式，請將config.proxy.enabled設定為false或空字串("")。 您亦可針對特定的應用程式停用此功能。例如： 

config.proxy.enabled         # → 所有應用程式已啟用（預設）
config.proxy.enabled = true  # → 所有應用程式已啟用
config.proxy.enabled = { svn: false, docker: false }
                             # → 指定的應用程式已停用
config.proxy.enabled = ""    # → 所有應用程式已停用
config.proxy.enabled = false # → 所有應用程式已停用

MediaWiki-Vagrant prep

您可能需要考慮使用shell腳本（例如 mw-vagrant-prep）來為安裝MediaWiki-Vagrant預備一個目錄。

调试

Vagrant

您可以使用 VAGRANT_LOG 來除錯 MediaWiki-Vagrant 本身（例如在 vagrant up 過程中發生的錯誤）： 

VAGRANT_LOG=debug vagrant up

供應

您可以執行以下指令來除錯供應的過程： 

PUPPET_DEBUG=1 vagrant provision

PHP

您可以使用 Xdebug 來除錯 PHP。 PHP的除錯與其他客戶端的除錯有所不同。 您的整合開發環境會監聽傳入的連線，當您透過瀏覽器存取伺服器時，一個特殊標頭會指示PHP來連接到您的整合開發環境。 由於缺乏更完善的文檔，請參閱（過時且過於冗長的）MediaWiki-Vagrant/Advanced usage#MediaWiki debugging using Xdebug and an IDE in your host以獲取更多資訊。

Chrome

  • Chrome的用戶應安裝XDebug Helper，並可選擇性安裝清除快取、HTTP標頭、及Mod標頭。 請設定為清除快取後自動重新載入、並建立鍵盤快捷鍵（例如：Ctrl+R是執行清除然後重新載入，Ctrl+⇧ Shift+D是切換XDebugger的開或關）

Firefox

  • Firefox的使用者請查看簡易Xdebug。
  • 請在您的機器上安裝並設定一個xdebug相容的整合開發環境（如 Eclipse、PhpStorm、Emacs 等）
  • 開始在開發整合環境中偵測傳入的除錯連接
  • 在整合開發環境中，在您感興趣的地方設定中斷點
  • 在瀏覽器中啟用XDebug，並導航至您的vagrant安裝位置（http://127.0.0.1:8080/...）

命令列介面 (Command-Line Interface)

對於維護腳本及其他從命令列介面執行的程式碼，可使用 xdebug_on 和 xdebug_off shell指令來啟用/停用除錯功能。

日志文件

MediaWiki的日誌位於/vagrant/logs目錄中。 Apache 的日誌檔案位於 /var/log/apache2/ 目錄下，但似乎並未寫入任何內容。 MySQL的查詢日誌可透過在客戶端執行 SET GLOBAL general_log = 'ON'; 指令、然後檢視 /var/lib/mysql/*.log 變數來取得。

运行并调试单元测试

「執行」所有擴充功能的 PHPUnit 測試： 

$ vagrant ssh
$ sudo -u www-data env PHPUNIT_WIKI=wiki PHPUNIT_LOGS=0 composer --working-dir=/vagrant/mediawiki phpunit

為某個單一的擴充功能執行單元測試： 

$ sudo -u www-data env PHPUNIT_WIKI=wiki PHPUNIT_LOGS=0 composer --working-dir=/vagrant/mediawiki composer phpunit /vagrant/mediawiki/extensions/ExtensionName/tests/phpunit/

某些測試可能需要以正確的使用者身份執行，以便建立lock檔案之類的操作，因此此指令將以處理網頁請求的www-data「使用者」身分去執行。

欲建立覆蓋率報告，請參閱Manual:PHP unit testing/Code coverage#MediaWiki-Vagrant。

調試phpunit的測試則會稍微複雜一些。 此法雖有些手法粗糙，但在遠端直譯器的除錯功能改善前（例如在 phpStorm 8 EAP 版本中），仍可作為過渡方案使用。 此變通辦法可讓您從瀏覽器執行MediaWiki單元測試。

  • 將phpunit.phar檔案下載至您的vagrant目錄的根目錄。
  • 在mediawiki目錄的根目錄下建立一個名為unittest.php的php檔案。 請勿將此檔案提交至儲存庫。 請將以下的程式碼貼入其中：
unittest.php 
<html><body><pre>
<?php
error_reporting(E_ALL);
ini_set('display_errors', 1);
require_once 'includes/WebStart.php';
$_SERVER[ 'argv' ] = array(
	'--configuration', '/vagrant/mediawiki/tests/phpunit/suite.xml',
	'/vagrant/mediawiki/extensions/JsonConfig/tests/phpunit/JCObjContentTest.php',
);
require_once '/vagrant/mediawiki/tests/TestsAutoLoader.php';
require_once '/vagrant/phpunit.phar';
PHPUnit_TextUI_Command::main(false);
  • 請将在上面的文件中的参数argv更改为你的测试文件的名称
  • Apache會將MediaWiki目錄的根目錄映射至/w。 請導覽至 http://127.0.0.1:8080/w/unittest.php 以執行此檔案
  • 依照#除錯的指示將除錯器附加至程式

运行浏览器测试

对于 JavaScript 单元测试 (QUnit)，请参阅 Manual:JavaScript unit testing 。

有關瀏覽器端到端測試（Selenium）的說明，請參閱 品質保證/瀏覽器測試/執行測試#透過Vagrant執行視覺化編輯器瀏覽器測試 。

推送更改

若您正在使用 MediaWiki-Vagrant 進行開發，且計劃為MediaWiki核心或擴充功能提交修補程式，請參照 Gerrit/Tutorial/tl;dr。 本教學說明如何建立SSH金鑰、安裝git-review，並設定Git使Git克隆能透過SSH與Gerrit互動，而非預設的匿名https:// URL。

Gerrit

要提交變更，請使用 cd 指令導航至您的擴充功能資料夾。 接著請依照透過gerrit提交補丁程式的指示操作。

故障排除

請检查PHP版本和设置
http://127.0.0.1:8080/info.php
編輯 LocalSettings.php？
首先，確認是否已有現成角色(vagrant list-roles)能實現您所需的功能。 若沒有，請在 settings.d/ 目錄下建立檔案。 請參閱 README 及 00-debug.php-example 檔案。
更新MediaWiki程式碼？

：最簡單的方法是使用host操作系统提供的vagrant git-update。 或者，若只想更新程式碼而不處理依赖關係，您可以在 vagrant/mediawiki 和 vagrant/mediawiki/extensions/SomeExtension 目錄中使用常規的 git fetch, pull等等指令。 您可以在虛擬機器上執行這些指令，但在host機上，檔案的存取速度會更快。 MediaWiki-Vagrant 在初始設定和/或新增角色時會從git master分支之中拉取程式碼，但之後不會自動更新程式碼。

執行MediaWiki PHP直譯器
透過SSH連線至Vagrant然後執行mwscript eval.php。 您可能需要以sudo角色來執行它
執行MediaWiki SQL直譯器
透過SSH連線至Vagrant然後執行mwscript sql.php。 您可能需要以sudo角色來執行它
更新虛擬機器軟體套件？
vagrant provision不會更新虛擬機器內的系統套件。 當您透過vagrant ssh連線時，登入訊息將告知您：
有NN個套件可更新。
有NN個更新為安全性更新。
在vagrant ssh中：
  • 要更新所有套件，請輸入 sudo apt-get update && sudo apt-get upgrade
  • 若需「自動安裝安全性（及其他）的升級」，類似於雲端虛擬專用伺服器（Cloud VPS）的實例，請輸入sudo unattended-upgrade
  • 更新至與量產的WMF伺服器內相同的套件...這些是待辦事項
自訂的Vagrant
您永遠都不需直接修改Vagrantfile。 Vagrant有幾個方面可供自訂：
  • 核心的設定（Git使用者、連接埠、記憶體、IP、端口轉發）可透過 .settings.yaml 檔案進行自訂。 請參閱vagrant config --help與vagrant forward-port --help的說明。 舉例來說，您可以執行vagrant forward-port 1234 80命令以啟用從host機:1234至guest機:80的端口轉發功能。
  • 在載入Vagrantfile後執行額外步驟：建立名為 Vagrantfile-extra.rb 的檔案，並將其放置於與 Vagrantfile 同級的資料夾中——該檔案將自動載入。 若有發生衝突，'extra'檔案中的值將優先於本檔案中的值。 請參閱 support/ 目錄中的範例。
添加自定义的Puppet代码？
若您希望在本地端自行架設 MediaWiki 網站，並讓 MediaWiki-Vagrant 自動為您安裝所需依赖項，此方案將是理想選擇。 若您有自己的獨立分支，那再理想不過了。 角色與此使用案例之間存在區別。 角色應可依任意順序安裝且不致損壞。 若您的分支需要不同的呼叫並在角色方面遇到問題，請建立您自己所需的類別和呼叫功能，包括角色。
要做到這一點，請將您的自訂的puppet程式碼連同您自己的類別放到puppet/modules/local/manifests/myown.pp之中，如下：
class local::myown {
    include ::role::svg
}

要套用您的類別，請將其新增至 puppet/hieradata/local.yaml 中的「classes」鍵。 若該檔案不存在，您可以自行建立。 

classes:
  - local::myown

然後執行 vagrant provision 透過Puppet去套用變更。

更新 MediaWiki-Vagrant 本身？
（例如，要使用新角色。）在終端機中，切換至host電腦上的 vagrant 目錄，然後輸入常規的git指令，例如git pull --ff-only。 一如既往，您在更新後需要執行vagrant provision指令，以將任何新的Puppet變更套用至您的虛擬機器。
在虛擬機器上執行GUI應用程式？
若您已安裝X伺服器，請使用ssh -- -X指令透過SSH連線至虛擬機器以啟用X轉發功能。 （Mac的使用者應更新至最新版本的XQuartz。）
另一種選擇是將虛擬機器以GUI模式執行，此模式可讓您如同具備有實體顯示器般與虛擬機器互動。 要啟用GUI模式，請在根儲存庫的資料夾中建立名為Vagrantfile-extra.rb的檔案，並將以下內容寫入其中：
Vagrant.configure('2') do |config|
    config.vm.provider :virtualbox do |vb|
        vb.gui = true
    end
end
請儲存檔案，然後先執行vagrant halt、緊接著執行vagrant up。 虛擬機器的顯示器將出現在您桌面上的視窗中。
調整那些被分配給虛擬機器的資源？
若您想為虛擬機器增減CPU或RAM的資源分配，請參閱vagrant config --help內的說明。

另一種方法是透過建立Vagrantfile-extra.rb檔案來達成（請參見在support/目錄內的範例）： 

Vagrant.configure('2') do |config|
    config.vm.provider :virtualbox do |vb|
        # See http://www.virtualbox.org/manual/ch08.html for additional options.
        vb.customize ['modifyvm', :id, '--memory', '768']
        vb.customize ['modifyvm', :id, '--cpus', '2']
    end
end
變更用於Git提交訊息的編輯器？
git config --global core.editor "vim"
設定一個自訂的host名稱？
前往Horizon，選擇網頁代理伺服器、然後輸入DNS host名稱，例如<hostname>

請至"http://<hostname>/wiki/"檢視您的新維基。

讓自訂的host名稱指向我的Vagrant角色的首頁，而非維基首頁？
在/vagrant/puppet/hieradata目錄中建立一個local.yaml檔案。在其中加入：
<rolename>::vhost_name:<hostname>
role::mediawiki::hostname: localhost

运行vagrant provision。

運行一個MediaWiki主支以外的分支？
在puppet/hieradata/local.yaml中設定mediawiki::branch鍵。 若檔案不存在，您可以自行建立。
mediawiki::branch: "wmf/1.24/wmf18"
此變更必須在首次執行vagrant up「之前」完成。 若您決定你要稍後才執行此操作，請先進行變更，使用指令vagrant destroy -f銷毀當前的虛擬機器、刪除現有的 MediaWiki checkout，最後使用指令vagrant up建置新的虛擬機器。
Vagrant設計為在主分支上運行，若搭配舊版核心和/或擴充功能，可能無法完美運作，甚至完全無法運作。[5]。

高级用法

MediaWiki的设置

作為一個管理所有MediaWiki設定的替代方案，您可考慮將MediaWiki的所有組態依據元件或主題進行分組管理，然後在settings.d/目錄下為每一個群組建立一個各別的PHP檔案，以取代單一、龐大的LocalSettings.php 檔案。 這使得您能夠輕鬆地保持設定井然有序、臨時停用特定的組態、以及共享設定給他人。

MediaWiki將按語法順序自動載入settings.d/中的所有PHP檔案。 您可以透過養成在每個檔案名稱前添加兩位數字前綴的習慣，來控制設定檔的套用順序。

例如： 

    settings.d/
    ├── 10-RunFirst.php
    ├── 20-SomeExtension.php
    └── 99-RunLast.php

請注意，位於settings.d/puppet-managed中的各個設定檔會依據您的Puppet組態自動建立與刪除。 請勿將你的自訂設定存放於此處，因為Puppet會清除它或覆寫它。 請將您的自訂設定檔改存放在settings.d/目錄中。

Vagrant的旗標

vagrant config --list 會顯示出當前所有Vagrant旗標的清單。

在初始的./setup.sh執行之後，其位於您的vagrant目錄中，即可設定config清單中出現的其中一個vagrant旗標，例如vagrant config nfs_shares no

作业队列

若您正在測試需要處理大量任務的作业队列，可能需要增加工作執行器的數量。 目前此設定無法透過LocalSettings.php進行，必須在工作執行器的設定檔中進行設定。

  1. 開啟puppet/modules/mediawiki/templates/jobrunner.json.erb
  2. 將鍵runners的值從1變更為想要的值（例如 4）
  3. 使用 vagrant --provision 重新供應
  4. 請注意，這將會造成在您代碼中與git master分支之間存在差異

請參閱上述調整CPU核心數量的說明並適當調整（對於CPU密集型任務如視訊轉碼，強烈建議執行此操作）。

額外的儲存空間

預設情況下，虛擬機器內的根分割所擁有的可用空間相對較少。 若您預計是要進行上傳並處理大型圖像與影片檔案的測試，此空間可能無法滿足需求。

手動步驟：

  • 關閉虛擬機器（vagrant halt）
  • 打開 VirtualBox 管理程式
  • 選取虛擬機器並進入「設定」
    • 在儲存裝置下，選擇「控制器：SATA」，然後點擊「新增硬碟」圖示。
    • 選擇預設的磁碟映像類型。
    • 將磁碟命名為「VagrantImageSpace」或類似名稱，並預留足夠空間（例如 80GB）——預設情況下檔案會從小容量開始，隨實際使用量逐步擴充，因此請儘可能預留需要的所有空間。
    • 關閉對話框並重新啟動虛擬機器 (vagrant up)
  • 執行 vagrant ssh 命令以在終端機內取得命令列介面
    • 執行 sudo fdisk /dev/sdb 建立新分割區...
    • 輸入 n、p、1，並按兩次 (Enter) 鍵以設定預設尺寸
    • 輸入 w 以儲存分割區表
  • 執行 sudo mke2fs /dev/sdb1 建立檔案系統
  • 執行 sudo vi /etc/fstab 以編輯掛載列表
    • 在末尾添加一行：/dev/sdb1 /srv/images ext4 errors=remount-ro 0 2
    • 儲存
  • 執行 sudo mount /srv/images 來掛載檔案系統
  • 執行 sudo chown www-data:www-data /srv/images 以設定檔案權限
  • 離開 shell 環境 exit
  • 重新啟動虛擬機器（vagrant halt; vagrant up）

認證角色

MediaWiki-Vagrant所建立的虛擬機器在關鍵方面與維基媒體的量產環境相似，並採用與維基媒體技術營運團隊相同的工具——Puppet——用於管理生產伺服器及維基媒體雲端VPS實例。 Puppet是一款組態管理工具，其提供了一種領域特定的語言，用於以陳述的方式來表達軟體的組態。 包含著Puppet程式碼的檔案稱為「清單(manifests)」。 當Puppet執行時，它會解析您提供的清單檔案、然後據此對機器進行設定。 一個Vagrant的角色就是一組Puppet的清單。

MediaWiki-Vagrant的Puppet程式碼庫包含有抽象化層，能輕鬆自動化MediaWiki擴充功能及相關軟體的組態。 若您是MediaWiki相關軟體專案的開發人員，我們鼓勵您為您的專案提交一個包含有Puppet角色的修補程式。 為您的專案增加一個Vagrant角色，可讓其他開發人員輕鬆查閱您的作品。 使用一個已管理的虛擬機器作為專案的開發沙盒，可降低因地理位置分散的開發人員在不相容環境中工作而導致的「在我機器上運作正常」錯誤發生機率。

開始自訂角色的最簡單方法，是參考現有角色在 puppet/modules/role/manifests/*.pp 中如何實作的方式。 這些角色依賴於 puppet/modules 中的Puppet模組（通常，foo::bar { ... }會轉換為對puppet/modules/foo/manifests/bar.pp的呼叫），並使用來自其他puppet/modules/role/*/rolename/目錄的檔案與模板。 Puppet 程式碼通常具備完善的文件說明，並包含有展示其正確使用方式的範例。

一些較實用的Puppet模組如下：

在云VPS上设置实例

您可以在維基媒體雲端VPS實例上使用雲端VPS上的MediaWiki-Vagrant來安裝MediaWiki，並於啟用其上的MediaWiki-Vagrant角色。

隐错

若您在MediaWiki-Vagrant中發現了錯誤，有請提報。 首先，請透過搜尋GitHub上的Vagrant問題追蹤器及VirtualBox上的錯誤追蹤器確認此錯誤並非已知問題：（舊有的錯誤(正逐步淘汰中)、目前的錯誤）。 若不是已知問題，請直接前往Wikimedia Phabricator去提報錯誤。 請盡可能地清楚地描述問題、並請附上重現問題的步驟。

链接

注释

  1. ↑ 如果您使用Fedora，请「不要」遵循Oracle的指示。相反，启用RPMfusion存储库（例如通过Apper的配置），然后运行sudo dnf install VirtualBox VirtualBox-kmodsrc akmod-VirtualBox kmod-VirtualBox（注意：区分大小写，且有时区分版本！你如果找不到包，请在Discover中搜索）。 或者你也可以按照这个指导做。 您可能会收到有关内核过时的错误消息。如果这样做，请安装akmods-VirtualBox，然后运行sudo akmods以确保模块构建。
  2. ↑ 在Fedora上，您可以執行sudo dnf install vagrant。
  3. ↑ https://github.com/hashicorp/vagrant/issues/10576#issuecomment-452793401
  4. ↑ https://peshmerge.io/how-to-speed-up-vagrant-on-windows-10-using-nfs/
  5. ↑ Vagrant在MediaWiki 1.21以上版本的依赖
Retrieved from "https://www.mediawiki.org/w/index.php?title=MediaWiki-Vagrant/zh&oldid=8106624"