Horizon负责为POCChain网络中的数据提供HTTP API。 它以比POCChain使用的面向性能的数据表示更容易消费的形式摄取和重新提供由POCChain网络生成的数据。

为什么跑Horizon?

POCChain开发基础运行两个服务器,一个用于公共网络,一个用于测试网络,任何人都可以免费使用https://horizon.stellar.orghttps://horizon-testnet.stellar.org。 这些服务器应该适用于开发和小规模项目,但不建议您将它们用于需要强大可靠性的生产服务。 通过在您自己的基础架构中运行视野可以带来许多好处:

  • 可以运行多个实例以实现冗余和可伸缩性。
  • 可以禁用请求速率限制。
  • 完全的操作控制,不依赖于Stellar Development Foundations操作。

先决条件

Horizon依赖于一颗POCChain服务器。 Horizon需要访问由POCChain发布的SQL数据库和HTTP API。 请参阅管理指南以了解如何设置和管理POCChain服务器。 其次,视界取决于postgres服务器,它用于存储已处理的核心数据以便于使用。 Horizon需要postgres版本>=9.3。

除了上述两个先决条件之外,您还可以选择安装redis服务器以用于速率限制请求。

安装

要安装Horizon,您可以选择:为目标架构和操作系统下载预构建的版本,或者自己构建Horizon。 当任一方法完成时,您将发现自己的目录包含名为horizon的文件。 此文件是本机二进制文件。

构建或解压缩Horizon后,您只需将本机二进制文件复制到PATH的一部分目录中。 大多数类似unix的系统默认情况下在PATH中都有/usr/local/bin,所以除非你有偏好或者知道更好,否则我们建议你在那里复制二进制文件。

要测试安装,只需从终端运行horizon --help。 如果显示“Horizon帮助”,则说明安装成功。 注意:某些shell(如zsh)会缓存PATH查找。 在尝试运行horizon --help之前,您可能需要清除缓存(例如,在zsh中使用rehash)。

建立

如果您决定不使用我们的预建版本,您可以改为从源代码构建horizon。 为此,您需要安装一些开发人员工具:

  • 类似于unix的操作系统,具有通用核心命令(cp,tar,mkdir,bash等)
  • go的兼容发行版(我们正式支持1.6及更高版本)
  • glide
  • git
  • mercurial

如果您的工作站满足上述要求,请按照以下步骤操作:

  1. 克隆horizon源代码go get github.com/stellar/go && cd $GOPATH/src/github.com/stellar/go/
  2. 在项目文件夹下,下载外部依赖项:glide install
  3. 建立二进制文件:go install github.com/stellar/go/services/horizon

运行上述命令成功后,已建立的Horizon将被写入$GOPATH的bin子目录。

注意:不支持直接在Windows上构建。

配置

使用命令行标志或环境变量配置Horizon。 要查看适用于您的Horizon版本的命令行标志列表(及其默认值),请运行:

horizon --help

正如您将看到的,如果您运行上面的命令,horizon会定义大量标志,但只需要三个:

标记 envvar 例子
--db-url DATABASE_URL postgres://localhost/horizon_testnet
--stellar-core-db-url STELLAR_CORE_DATABASE_URL postgres://localhost/core_testnet
--stellar-core-url STELLAR_CORE_URL http://localhost:11626

--db-url指定horizon数据库,其值应该是有效的PostgreSQL连接URI--stellar-core-db-url指定一个POCChain数据库,用于加载有关POCChain分块的数据。 最后,--stellar-core-url为POCChain实例指定HTTP控制端口。 此URL应与在--stellar-core-db-url写入数据库的POCChain相关联。

每次调用horizon时指定命令行标志都很麻烦,因此我们建议使用环境变量。 您可以使用许多工具来管理环境变量:我们建议使用direnvdotenv。 可以在horizon git repo中找到与dotenv兼容的模板配置。

准备数据库

在可以运行Horizon服务器之前,我们必须首先准备Horizon数据库。 此数据库将用于由horizon生成的所有信息,特别是有关在POCChain网络上发生的成功交易的历史信息。

要准备数据库以供使用,首先必须确保数据库为空。 最简单的方法是在postgres服务器上创建一个专门用于Horizon使用的新数据库。 接下来,您必须通过运行horizon db init来安装架构。 请记住使用适当的命令行标志或环境变量来配置Horizon,如配置中所述。 此命令将记录发生的任何错误。

运行

配置完Horizon数据库后,您就可以运行Horizon了。 要运行Horizon,您只需运行horizonhorizon服务,这两个服务都启动HTTP服务器并开始记录到标准输出。 运行时,您应该看到一些类似于的输出:

INFO[0000] Starting horizon on :8000                     pid=29013

上面的日志行宣布Horizon已准备好为客户端请求提供服务。 注意:上面显示的数字可能与您的安装不同。 接下来,我们可以通过加载根资源来确认地平线是否正确响应。 在上面的示例中,该URL将是[http://127.0.0.1:8000/],只需运行curl http://127.0.0.1:8000/即可显示可以正确加载根资源。

获得POCChain数据

Horizon通过提取的数据提供其大部分功能。 您的Horizon服务器可以配置为侦听和接收来自连接的POCChain的交易结果。 我们建议您在基础架构中运行以这种方式配置的一个(且仅一个)范围流程。 虽然运行多个获取过程不会破坏horizon数据库,但是当两个实例竞争从POCChain中获取数据时,错误日志将很快填满。 我们可能会开发一个系统来协调未来的多个Horizon过程,但我们也很乐意包含一个实现这一目标的外部贡献。

要启用提取,必须在命令行上传递--ingest=true或将INGEST环境变量设置为“true”。

管理历史数据的存储

给定空的Horizon数据库,将附加所附的POCChain实例上的任何和所有可用历史记录。 随着时间的推移,这个记录的历史将无限增长,增加数据库使用的存储空间。 为了降低成本,您可以将horizon配置为仅在历史数据库中保留一定数量的分块。 这是使用--history-retention-count标志或HISTORY_RETENTION_COUNT环境变量完成的。 将值设置为您希望保留的最近分块的数量,并且Horizon子系统每小时将获得过期数据。 或者,您可以执行命令horizon db reap来强制收集。

幸存的POCChain停机时间

Horizo​​n试图保持一个无缝隙窗口进入POCChain网络的历史。这减少了与Horizon相关的软件必须处理的边缘情况的数量,旨在使集成过程更简单。为了保持无间隙的历史,Horizon需要访问在关闭分块的过程中由POCChain生成的所有Meta数据,并且存在可能丢失此Meta数据的情况。通常,这种Meta数据丢失的发生是因为POCChain节点脱机并在重新启动时执行了捕获操作。

要确保维护horizo​​n所需的Meta数据,您有以下几种选择:您可以将CATCHUP_COMPLETE POCChain配置选项设置为true,或者配置CATCHUP_RECENT以确定您的POCChain可以脱机的时间而无需重建您的Horizon数据库。

我们不建议使用CATCHUP_COMPLETE方法,因为这将迫使POCChain应用分块开头的每个交易,这将花费越来越多的时间。相反,我们建议您设置CATCHUP_RECENT配置值。为此,请确定您希望生存的停机时间(以秒表示)并除以10。这大致相当于在您期望的宽限期内发生的分块数量(分块大约以每十秒一个的速率关闭)。使用此值集,POCChain将重放最近的分块交易,确保视图所需的Meta数据存在。

纠正历史数据的差距

在上面的部分中,我们提到Horizon试图保持一个无间隙的窗口。不幸的是,它不能直接控制POCChain的状态,因此可能由于延长的停机时间而形成间隙。当遇到间隙时,Horizon将停止摄取历史数据并在日志中大声抱怨并显示错误消息(日志行将包括“检测到分块间隙”)。要解决此问题,您必须重新建立POCChain数据库的预期状态,并从Horizon数据库中清除历史数据。我们将此过程的详细信息留给读者,因为它取决于您的操作需求和配置,但我们提供了一个可能的解决方案:

我们建议您将Horizon中的HISTORY_RETENTION_COUNT配置为小于或等于POCChain中CATCHUP_RECENT的配置值的值。鉴于这种情况,任何导致分块缺口的停机时间都需要大于Horizon保留的历史数据量的停机时间。要重新建立连续性,只需:

  1. 停止horizon。
  2. 运行horizon db reap清除历史数据库。
  3. 通过运行stellar-core -c "dropcursor?id=HORIZON"清除光标到Horizon(确保保持了资本化)。
  4. 通过运行stellar-core -c "maintenance?queue=true"清除差距之前的分块Meta数据。
  5. 重启horizon。

管理陈旧的历史数据

Horizon从连接的POCChain实例中获取分块数据。 如果POCChain停止运行(或由于Horizon由于任何其他原因停止获取数据),Horizon提供的视图将开始落后于现实。 对于更简单的应用程序,这可能没问题,但在许多情况下,这种滞后是不可接受的,并且应用程序不应继续运行,直到滞后得到解决。

为了帮助不能容忍延迟的应用程序,horizon提供了可配置的“陈旧性”阈值。 鉴于已经积累了足够的滞后超过此阈值(以分块的数量表示),Horizon将仅响应错误:stale_history。 要配置此选项,请使用--history-stale-threshold命令行标志或HISTORY_STALE_THRESHOLD环境变量。 注意:超过过期阈值时,非历史请求(例如提交交易或查找付款路径)不会出错。

监控

为确保您的Horizon实例正确执行,我们建议您对其进行监控,并提供日志和指标。

Horizon会将日志输出到标准输出。 将报告有关请求进入的信息,但更重要的是,默认情况下也会发出警告或错误。 正确运行的Horizon实例不会输出任何警告或错误日志条目。

在Horizon过程运行时收集度量标准,并在/metrics路径中公开它们。 您可以在(https://horizon-testnet.stellar.org/metrics)上看到一个示例。

我被困了! 救命!

如果上述任何步骤不起作用或者您无法正确设置范围,请访问我们的社区并告诉我们。 要么在我们的Stack Exchange上发布一个问题,要么在闲暇时与我们聊天以寻求帮助。