自托管指南
最后更新于
本页面将阐述如何配置并运行自托管开发服务器以及云端开发服务器。这在以下情况下很有用:
您需要测试自托管实例如何与云端通信时
您需要在不扰乱正常开发环境的情况下开发自托管功能时
在最常见的配置中,云端和自托管开发服务器的运行都使用相同的基础架构配置:
服务运行在 http://localhost:{port}
上(云端与自托管使用不同的端口号)
本地 SQL 数据库(云端与自托管使用不同的数据库名称)
本指南假定您已完成并熟悉了中的技术细节。请确保您已经拥有一个运行中的云端配置服务器开发环境,然后再将自托管实例连接到它。
将服务器存储库克隆到一个名为 server-selfhost
的新文件夹中:
接下来,我们将致力于让自托管服务器与本地云端配置服务器同时运行。
每一个自托管实例都由安装 ID 和安装 Key 定义。它们被存储在这两个地方:
作为用户机密存储在自托管实例中,以及
在您的云端配置实例的 Installations
表中,以便它可以验证来自您的自托管服务器的请求
要获取 ID 和 Key,可以选择:
生成一个 Guid (ID) 和随机字母数字字符串 (Key)
记录下记录这些信息,以便在接下来的步骤中使用。
您需要从云配置的存储库中复制两个文件(这俩个文件您应该已经设置好了)。它们将被复制到您的自托管存储库。它们都位于 dev
文件夹中。我们将它们复制过来以节省时间和精力;既然它们的值几乎都一样,就没必要重新生成了。复制到自托管存储库后,我们将在下面的后续步骤中修改它们。
secrets.json
文件将 secrets.json
文件复制到您刚刚克隆的自托管存储库的 dev
文件夹中。
.gitignore
配置将阻止将 dev
文件夹中的 secrets.json
签入源代码管理。在任何情况下都不应将 secrets.json
推送到源。
.env
文件将 .env
文件复制到您刚刚克隆的自托管存储库的 dev
文件夹中。
在您的自托管存储库中,导航到 dev
文件夹并打开您复制来的 secrets.json
文件。
我们必须配置用户机密的 Dev:SelfHostOverride:GlobalSettings
部分。本节指定的设置将覆盖本地自托管开发实例的设置。被覆盖部分中的任何内容都将被应用,而不是 GlobalSettings
中给出的值。
我们需要在此处执行此操作,因为我们需要能够定义在 Docker 容器中的环境变量中指定的真实的自托管实例的设置值。我们使用机密文件来执行此操作,而不是在我们的机器上设置环境变量以及让 .NET Core 配置中的构建为我们构建我们的设置。
安装 ID 和 Key,使用您刚刚生成的值
我们将在下面创建的新 SQL 数据库的 SQL Server 密码。它可以从您的 secrets.json
中已有的云配置设置中复制(即使用与您的云端配置服务器相同的密码),或者生成一个新的密码。
任何其他空白值
在自托管存储库中更新了 secrets.json
文件后,通过运行以下命令应用更改:
现在您已经完成更新自托管实例的用户机密的步骤。
在设置数据库之前,请确保您的 Docker 容器正在运行。
导航到自托管服务器存储库。我们将为我们的自托管配置创建第二个数据库,以便云端配置实例可以拥有用于开发的独立的数据集。
这将创建一个名为 vault_dev_self_host
的新数据库和/或对其运行未知迁移。
为了使您的自托管数据库保持最新,将来调用带有 -s
参数的脚本时将对 vault_dev_self_host
执行新的迁移。
您需要手动将安装 Key 添加到您的云端配置实例,以便它知道您的自托管实例,并在需要在两者之间进行 API 调用时允许访问。随意使用您喜欢的任何工具,如 Azure Data Studio、sqlcmd、以及下面的脚本,执行此操作。
其中 <<SA_PASSWORD>>
是云数据库的 SQL SA 密码,<<SCRIPT_FILE>>
指向包含以下内容的文件:
其中 <<YOUR_ID>>
是您的安装 ID,<<YOUR_DEV_EMAIL>>
是您的电子邮件地址,<<YOUR_KEY>>
是您的安装 Key。
如果我们没有 Web 门户来与 API 交互,则自托管服务器的用途有限。同样,克隆一个新的存储库实例是最简单的:
安装依赖并初始化 jslib:
当服务在自托管配置中运行时,它将默认使用它们在云端配置实例中运行的端口号 +1 的端口号。
上面,我们设置了一系列用户机密覆盖,使我们能够运行我们的自托管实例。我们需要确保启动服务器以使用这些设置。如果满足以下两个条件,服务器代码将使用这些设置:
环境用于开发
developSelfHosted
为 true
我们基于您运行服务器的方式以不同方式执行此操作。在您的环境中,自托管启动配置(例如「Api-SelfHost」)将为您设置环境和 developSelfHosted
标志。
我们有多种启动配置以及组合配置用以轻松启动服务。默认情况下,个人自托管启动是隐藏的。导航到 launch.json
以取消隐藏。
已运行的配置用于在自托管模式下启动一个给定服务。
要从 CLI 运行自托管,您需要:
1、在自托管存储库的根目录中打开一个新的终端窗口。
2、恢复 Identity 服务所需的 nuget 包:
3、启动 Identity 服务:
5、在另一个终端窗口中,恢复 Api 服务所需的 nuget 包:
6、启动 API 服务:
要启动其他服务,请遵循相同的格式,记得跟随合适的自托管启动配置 --launch-profile
。
从 clients-selfhost
目录中,您可以执行以下命令来启动 Bitwarden 许可服务器或 OSS Web 服务器:
npm run build:bit:selfhost:watch
npm run build:oss:selfhost:watch
默认端口是 8081
,因此您可以同时运行云端配置和自托管配置的 Web 客户端。它还被配置为指向各种服务器项目的默认 *-SelfHost
端口。
为此,您应该首先启动本地云端配置和自托管 Web 客户端,要获取和应用许可证,这两个环境都是必需的。
您现在可以选择要申请的许可证类型。每个指令的说明各不相同,但最好的资源是 Bitwarden 帮助中心文档:
请求,或者
如果您忘记了什么是用户机密,请回顾。
目前,我们只覆盖 GlobalSettings
。任何其他需要覆盖的用户机密都需要更改代码才能这样做。检查服务器存储库中的 ServiceCollectionExtension.AddGlobalSettingsServices
,看看我们现在是怎么做的()。
包含一个最小覆盖示例。您需要更新 Dev:SelfHostOverride:GlobalSettings
部分中的以下值:
如果您在创建云端配置数据库时遵循了,则您只需运行带有 -s
参数的相同 PowerShell 迁移脚本即可:
4、通过导航到 测试 Identity 服务是否处于活动状态
7、通过导航到 测试 Api 服务是否处于活动状态
如果您需要在自托管实例上重新实现,则需要使用在云端配置实例中已注册的许可证文件来解锁这些功能。