Diviner Phabricator 用户文档 Diffusion 用户指南: 仓库托管

Diffusion 用户指南: 仓库托管
Phabricator 用户文档 (应用程序用户指南)

配置 Phabricator 仓库托管指南。

概览

Phabricator 可以托管仓库,并通过 HTTP 和 SSH 提供经过身份验证的读写访问。 本文档介绍如何配置仓库托管。

了解支持的协议

Phabricator 支持通过这些协议托管:

VCSSSHHTTP
Git支持支持
Mercurial支持支持
Subversion支持不支持

所有支持的协议均可处理读取(pull/checkout/clone)和写入(push/commit)。 在这两种协议中,SSH 通常更加健壮,安全和高效,但 HTTP 更易于设置并支持匿名访问。

SSHHTTP
授权访问
推送日志
Commit 钩子
匿名访问
安全性更好 (非对称密钥)还好 (密码)
性能更好还好
设置困难简单

每个仓库可以单独配置,您可以使用任意一个协议,或两者都用。

建议使用 SSH,除非您需要匿名访问,或者由于技术原因而无法对其进行配置。

创建系统用户帐户

Phabricator 使用两个系统用户帐户,如果您配置 SSH 访问还需要第三个帐户,。 本节将指导您完成创建和配置它们。这些是 Phabricator 运行的系统上的用户帐户, 而不是 Phabricator 系统中的帐户。

Phabricator 使用的系统用户有:

  • web 服务器运行用的用户,我们叫 www-user
  • 守护进程运行用的用户。 我们叫 daemon-user。 该用户是将直接与仓库交互的唯一用户。 其他帐户将 sudo 到此帐户以执行仓库操作。
  • SSH 连接的用户。 我们称之为 vcs-user。 如果您不打算通过 SSH 提供仓库,则无需创建或配置此用户。

创建这些用户:

  • 创建一个 www-user,如果它不存在。 在大多数情况下,此用户已经存在,您只需要确定它是哪个用户。 以此用户身份运行 Web 服务器。
  • 创建一个 daemon-user, 如果还不存在的话。(用户名可以随便定义,或者使用现有的帐户)。 下面,您将配置守护程序以此用户身份启动。
  • 创建 vcs-user(如果尚不存在并且计划设置 SSH)。 当用户克隆仓库时,他们将使用像 vcs-user@phabricator.yourcompany.com 这样的 URI, 因此该用户的常用名称是 githg

请在下面继续配置这些帐户。

配置 Phabricator

现在您已创建或识别这些帐户,更新 Phabricator 配置以指定它们。

首先, 设置 phd.userdaemon-user:

phabricator/ $ ./bin/config set phd.user daemon-user

重新启动守护程序以确保此配置正常工作。他们应该作为正确的用户自动启动。

如果 SSH 使用 vcs-user 用户,需要这样配置:

phabricator/ $ ./bin/config set diffusion.ssh-user vcs-user

接下来,您将设置 sudo 权限,以便这些用户可以相互交互。

配置 Sudo

www-uservcs-user 需要能够通过 sudo 切换为 `daemon-user' 用户, 这样他们就可以与仓库进行交互了。

要授予它们访问权限,请编辑 sudo 系统配置。在许多系统上, 您将使用 visudosudoedit 修改 /etc/sudoers 文件。 在某些情况下,您可以添加一个新文件到 /etc/sudoers.d 目录。

为了给用户帐户 sudo 配置可运行二进制文件列表, 在配置文件中添加一行(这个例子将授予 vcs-user 权限以 daemon-user 用户身份运行 ls):

vcs-user ALL=(daemon-user) SETENV: NOPASSWD: /path/to/bin/ls

www-user 需要能够像 daemon-user 那样运行这些二进制文件:

  • git (如果使用 Git)
  • git-http-backend (如果使用 Git)
  • hg (如果使用 Mercurial)
  • ssh (如果配置了集群)

如果打算使用 SSH, vcs-user 需要能够以 daemon-user 用户身份运行这些命令:

  • git (如果使用 Git)
  • git-upload-pack (如果使用 Git)
  • git-receive-pack (如果使用 Git)
  • hg (如果使用 Mercurial)
  • svnserve (如果使用 Subversion)
  • ssh (如果配置了集群)

标识系统上所有这些二进制文件的完整路径,并向 sudo 配置中添加适当的权限。

通常,你会添加类似如下的两行配置:

www-user ALL=(daemon-user) SETENV: NOPASSWD: /path/to/x, /path/to/y, ...
vcs-user ALL=(daemon-user) SETENV: NOPASSWD: /path/to/x, /path/to/y, ...

这只是一个模板。 在真实的配置文件中,您需要:

  • 替换 www-user, dameon-uservcs-user 为你系统上正确的用户名。
  • 列出这些用户需要访问的每个二进制文件,如上所述。
  • 确保每个二进制路径是系统上正确的完整路径。

在继续之前,在你的 sudo 配置中寻找这行:

Defaults    requiretty

如果它存在,通过在行的开头放一个 来注释掉。 启用此选项后,VCS SSH 会话将无法使用 sudo

其他 SSH 用户配置

如果你计划使用 SSH,你还应该编辑 /etc/passwd/etc/shadow, 以确保 vcs-user 帐户设置正确。

/etc/shadow: 打开 /etc/shadow 找到 vcs-user 用户所在行。

第二个字段(即密码字段)不能设置为 !!。 此值将阻止登录。 如果设置为 !!,则编辑它并将其设置为 NP(“无密码”)。

/etc/passwd: 打开 /etc/passwd 找到 vcs-user 用户所在行。

最后一个字段(即登录 shell)必须设置为一个真实的 shell。 如果它被设置为像 /bin/false,那么 sshd 将不能执行命令。 相反,你应该将它设置为一个真正的 shell,如 /bin/sh

配置 HTTP

如果计划通过经过身份验证的 HTTP 提供仓库,则需要在 Config 中设置 diffusion.allow-http-auth。 如果您不打算通过 HTTP 提供仓库(或计划仅使用匿名 HTTP),则可以禁用此设置。

如果计划使用经过身份验证的 HTTP,您(和所有其他用户)还需要在 设置VCS 密码中为您的帐户配置 VCS 密码。

您的 VCS 密码必须是与 Phabricator 密码不同的密码,因为 VCS 密码很容易被意外泄露。 它们通常以纯文本存储在可读的文件中,在 ps 输出中可观察到,并存在于命令输出和日志中。 我们强烈建议您使用 SSH 而不是 HTTP 来验证对仓库的访问。

否则,如果您已在上面配置系统帐户,则全部设置已经完成。 不需要其他服务器配置来使 HTTP 工作。您现在应该能够通过 HTTP 提取和推送仓库。 有关详细信息,请参阅下面的“克隆仓库”。

如果遇到问题,请参阅下面的“排查HTTP”。

配置 SSH

SSH 访问需要一些额外的设置。您将在机器上用不同于标准 sshd 端口的配置和 运行 sshd 的第二个限制副本。 sshd 的这个特殊副本将提供仓库请求并提供其他 Phabricator SSH 服务。

NOTE: Phabricator 的 sshd 服务 必须 是 6.2 或更新版本, 因为 Phabricator 依赖于 AuthorizedKeysCommand 选项.

在继续之前,您必须选择一个策略,指定 sshd 的不同副本将运行在哪个端口。 下一节阐述了各种方法。

SSHD 端口分配

正常情况下,不允许管理主机和提供仓库的 sshd 在同一个端口上运行。 特别是,其中只有一个可以运行在端口 22,这将使它有点不方便访问另一个。

这些指令将引导您配置 sshd 在端口 “2222” 运行。 这个配置很容易,但如果你在这个端口上运行服务, 用户将克隆并推送到像 ssh://git@host.com:2222/ 这样有点丑的 URI。

有几种不同的方法可以用来减轻或消除这个问题。

在 2222 端口运行:你可以什么也不做,只是在端口 2222 运行 sshd , 并在 URI 中指明端口。这是最简单的方法,你可以先这样使用。 如果以后厌倦了,再处理端口号。

使用负载平衡器:您可以在主机前配置负载平衡器,并将端口 22 上的 TCP 流量转发到端口 2222。 然后用户可以从 ssh://git@host.com/ 克隆而不用显式指明端口号。

这可能非常容易设置,特别是如果您托管在 AWS 中,通常也是最简单和最干净的方法。

交换端口:您可以将管理 sshd 移动到一个新的端口,然后在端口 22 上运行 Phabricator`sshd`。 这有点复杂,如果你犯了错误可能有点冒险。有关帮助,请参阅下面的“移动sshd端口”。

更改客户端配置:您可以在非标准端口上运行,但在客户端配置 SSH, 以便 ssh 在连接到主机时自动默认为正确的端口。 要做到这一点,添加一个这样的部分到你的 〜/.ssh/config 文件中:

Host phabricator.corporation.com
  Port 2222

(如果你愿意的话,你也可以添加一个默认的 User。)

在连接到此主机时,像 sshgithg 命令行工具现在将默认使用端口 2222

这种方法的一个缺点是,你的用户每个需要单独设置他们的 ~/.ssh/config 文件。

此文件还允许您使用 HostHostName 选项为主机定义短名称。 如果你选择这样做,请注意,Phabricator 使用 remote/clone URI来确定它运行在哪个仓库, 但不能解决在你的 ssh 配置中定义的主机别名。如果创建主机别名, 它们可能会破坏与仓库标识相关的一些功能。

如果使用此方法,则还需要在连接以管理主机时明确指定端口。 任何单元测试或其他构建自动化也将需要配置或使用显式端口号。

端口复用:如果您可以访问硬件,您可以关闭主机,找到主板上的网络 I/O 引脚(用于板载网络)或网卡。

在外部接口 22 和内部 2222 的引脚之间小心剥离和焊接一小段铜线, 因此外部接口可以接收这两种服务的流量。

(确保不要拆除外部 22 和内部 22 之间的现有连接,否则将无法正常连接来管理主机。)

这种方法的明显缺点是,它需要物理访问机器,所以如果你托管在云提供商,就不好办了。

SSHD 设置

现在你已经决定如何处理端口分配,你准备继续设置 sshd

如果你打算连接到一个不是 22 的端口, 你应该在你的 Phabricator 配置里把 diffusion.ssh-port 设置为这个端口:

$ ./bin/config set diffusion.ssh-port 2222

此端口不是特殊的,您可以自由选择不同的端口,只要您进行相应的配置调整如下。

配置和启动 Phabricator SSHD:现在,您将配置和启动 sshd 的副本, 它将通过 SSH 为 Phabricator(包括仓库)提供服务。

此实例将使用一个特殊的锁定配置,使用 Phabricator 处理身份验证和命令执行。

有三个主要步骤:

  • 创建 phabricator-ssh-hook.sh 文件
  • 创建 sshd_phabricator 配置文件
  • 使用新配置启动一个新 sshd 副本

创建 phabricator-ssh-hook.sh: 复制模版文件 phabricator/resources/sshd/phabricator-ssh-hook.sh 到像 /usr/libexec/phabricator-ssh-hook.sh 这样的位置,然后修改为正确的设置。

脚本本身和脚本所在的父目录必须由 root 用户所有,脚本文件权限必须为 755

$ sudo chown root /path/to/somewhere/
$ sudo chown root /path/to/somewhere/phabricator-ssh-hook.sh
$ sudo chmod 755 /path/to/somewhere/phabricator-ssh-hook.sh

不这样设置的话,sshd 将拒绝执行钩子。

为 Phabricator 创建 sshd_config: 复制模版文件 phabricator/resources/sshd/sshd_config.phabricator.example/etc/ssh/sshd_config.phabricator

打开文件修改 AuthorizedKeysCommand, AuthorizedKeysCommandUser, 和 AllowUsers 设置为系统的正确值。

此配置文件还指定服务应该运行的端口。 如果您打算在非默认端口上运行,请立即进行调整。

启动 SSHD: 现在,启动 Phabricator sshd:

sudo /path/to/sshd -f /path/to/sshd_config.phabricator

如果一切设置正确,你应该能够运行这个命令:

$ echo {} | ssh vcs-user@phabricator.yourcompany.com conduit conduit.ping

...响应如下:

{"result":"phabricator.yourcompany.com","error_code":null,"error_info":null}

如果您遇到身份验证错误,请务必在设置SSH 公钥中添加您的公开密钥。 如果您遇到问题,请查看下面的问题排查部分。

通过 SSH 进行身份验证

要通过 SSH 进行身份验证,用户应该在 设置SSH 公钥 下添加其公钥。

克隆仓库

如果您已经设置了托管仓库,则可以尝试立即克隆它。 为此,请浏览到 Diffusion 中的仓库的主页面。 您应该在页面顶部看到克隆命令。

要克隆仓库,只需运行相应的命令。

如果没有看到命令或运行它们不起作用,请参阅下面的故障排除提示。

HTTP 故障排除

有关解决 HTTP 问题的一些常见提示:

  • 确保在您的 Phabricator 配置中启用了 diffusion.allow-http-auth
  • 确保您要尝试克隆的仓库启用了 HTTP 。您可以在 编辑仓库托管中找到它。
  • 确保您已配置 VCS 密码。这与您的主要帐户密码是分开的。 您可以在设置VCS 密码中进行配置。
  • 确保 Diffusion 中的主仓库页面显示 HTTP的 克隆/检出 命令。 如果没有,表明以上的东西设置不正确:仔细检查你的配置。 你应该看到一个 svn checkout http://...git clone http://...hg clone http://...命令。 逐字运行该命令以克隆仓库。

如果您使用 Git,则使用 `GIT_CURL_VERBOSE' 可能有助于评估登录失败。 为此,请在命令行上 git clone命令之前指定它,如下所示:

$ GIT_CURL_VERBOSE=1 git clone ...

这将使 git 打印出更多的信息。 特别地,具有 HTTP 响应的行可能是有用的:

< HTTP/1.1 403 Invalid credentials.

在许多情况下,这可以为您提供有关错误的更多信息。

SSH 故障排除

有关解决 SSH 问题的一些常见提示:

  • 检查您是否配置了 diffusion.ssh-user
  • 检查您是否配置了 phd.user
  • 确保您要尝试克隆的仓库启用了 SSH 服务。 您可以在 Diffusion 中的主仓库页面中通过{nav 编辑仓库>编辑主机> 托管在 Phabricator 上的仓库>保存并继续> SSH 只读或读/写>保存更改)更改此设置。
  • 请确保您已在帐户中添加 SSH 公钥。 您可以在设置SSH 公钥中执行此操作。
  • 确保 Diffusion 中的主仓库页面显示 SSH 的克隆/检出命令。 如果不是,则表明以上的东西设置不正确。 你应该看到一个 svn checkout http://...git clone http://...hg clone http://...命令。 逐字运行该命令以克隆仓库。
  • 检查你的 phabricator-ssh-hook.sh 文件是否有正确的设置。
  • 检查你的 sshd_config.phabricator 文件是否有正确的设置。

要解决 SSH 设置问题:使用 ssh 连接到服务器,而不运行命令。 您可能需要使用 -T 标志,如果您在非标准端口上运行,则需要使用 -p 指定端口。 您应该会看到类似这样的消息:

$ ssh -T -p 2222 vcs-user@phabricator.yourcompany.com
phabricator-ssh-exec: Welcome to Phabricator.

You are logged in as alincoln.

You haven't specified a command to run. This means you're requesting an
interactive shell, but Phabricator does not provide an interactive shell over
SSH.

Usually, you should run a command like `git clone` or `hg push` rather than
connecting directly with SSH.

Supported commands are: conduit, git-receive-pack, git-upload-pack, hg,
svnserve.

如果您看到此消息,则说明您的所有 SSH 都已正确配置。 如果你得到一个登录shell,你可能错过了一些主要的设置步骤: 查看上面的文档,如果你得到一些其他类型的错误,请仔细检查这些设置:

  • 你正在用 vcs-user 连接
  • 用户 vcs-user/etc/shadow 设置为 NP
  • 用户 vcs-user/etc/passwd 文件有 /bin/sh 或其他有效的 shell
  • 您的 SSH 私钥是正确的,您已在“设置”面板中将相应的公钥添加到 Phabricator

如果你能走到这儿,但不能执行像 git clone 这样的 VCS 命令, 你的 sudoers 配置可能有一个问题。 请检查:

  • 你的 sudoers 文件是按照上面介绍设置的
  • 已在 sudoers 文件中注释掉 Defaults requiretty
  • 您的系统上没有 VCS 二进制文件的多个副本(如 `git-upload-pack') 您可能已授予 sudo 访问权限,而 VCS 用户尝试运行其他访问权限
  • 已经配置了 phd.user
  • phd.user 有仓库的读写权限

在调试模式下运行 sshd 也是有帮助的:

$ /path/to/sshd -d -d -d -f /path/to/sshd_config.phabricator

这将在前台运行它,并在连接到它时发出大量的调试信息。

最后,你通常可以通过这样做来测试 'sudoers' 是否配置正确:

$ su vcs-user
$ sudo -E -n -u daemon-user -- /path/to/some/vcs-binary --help

这将尝试以类似于 Phabricator 运行它的方式通过 sudo 运行二进制文件。 这可以给你关于 sudoers 配置问题的更好错误消息。

其他故障排除

  • 如果你得到一个关于 svnlook 没有找到的错误,添加 svnlook 所在的路径到 Phabricator 配置environment.append-paths(即使它已经出现在 PATH 中)。 此问题是由 SVN 在调用提交钩子时擦除环境(包括 PATH)引起的。

交换 sshd 端口

如果你想将标准(管理)sshd 移动到不同的端口 使 Phabricator 仓库的 URI 更简洁,本节有一些提示。

这是可选的,通常通过在 Phabricator 前面放置负载均衡器并使其在端口 22 上接受 TCP 流量 并将其转发到某个其他端口来执行此操作通常更容易。

当移动 sshd 时,在编辑配置时要小心。 如果你错了,你可能会把自己锁在机器之外。 重新启动 sshd 一般不会中断现有的连接,但是你应该小心。 您可以使用两种策略来减轻这种风险:通过启动第二个 sshd 来进行烟雾测试配置; 并使用 screen 会话,它会自动修复配置,除非停止。

要对配置进行烟雾测试,只需使用 -f 标志启动另一个sshd

sudo /path/to/sshd -f /path/to/config_file.edited

然后,可以在替换主配置文件之前连接并确保编辑的配置文件有效。

要自动修复配置,使用这样的命令启动一个 screen 会话:

sleep 60 ; mv sshd_config.good sshd_config ; /etc/init.d/sshd restart

具体命令可能会因系统而异,但一般的想法是让机器在一段时间后自动恢复配置(如果不停止)。 如果你不小心锁定了自己,这可以自动修复。

现在你已经准备好编辑你的配置了,打开你的 sshd 配置(通常是/etc/ssh/sshd_config), 把 Port 设置改成其他端口,比如 222 (可以选择除 22 端口以外的任何端口)。

Port 222

一定要非常小心,重新启动 sshd。 验证您是否可以在新端口上连接:

ssh -p 222 ...

现在,您可以将 Phabricator sshd 移动到端口 22, 然后在 Phabricator 配置中调整 diffusion.ssh-port 的值。

不能直接推送

在尝试推送时,您可能会收到关于“不能直接推送”的错误。 这意味着您直接推送到仓库,而不是通过 Phabricator 推送。 这是不支持的:对托管仓库的写入必须通过 Phabricator, 以便它可以执行身份验证,强制执行权限,写入日志,代理请求,应用重写等。

在同一台机器上不小心使用 file:/// 这样的 URI 与仓库进行直接推送。 这不受支持。而应使用 Web 界面中提供的仓库 URI 之一,即使您在同一台计算机上工作。

直接推送的另一种方法是错误配置 SSH(或根本不配置它),以使上述逻辑都不运行, 并且只是作为系统用户正常连接。在这种情况下,上面描述的 ssh 测试将失败 (当你连接时,你会得到一个命令提示符,而不会得道上面所说的提示信息)。

如果您遇到此错误:请确保您正在使用 Diffusion 在 Web 界面中为您提供的远程 URI, 然后仔细执行上述故障排除步骤。

有时用户会遇到这个问题,因为他们完全跳过了整个文档,假设他们不需要配置任何东西。 这将不工作,你必须按照上面说明进行配置,才能使托管仓库正确工作。

这个错误发生的技术原因是当提交钩子运行 PHABRICATOR_USER 环境变量没有定义。 当请求通过身份验证层时,此变量由 Phabricator 设置,本文档提供了配置说明。 找不到此变量表示请求没有通过 Phabricator。

下一步

设置托管仓库后: