Stellar-Core 快速参考指南：核心功能与操作详解

Stellar-Core 快速参考指南：核心功能与操作详解

stellar-core stellar-core is the reference implementation for the peer to peer agent that manages the Stellar network 项目地址: https://gitcode.com/gh_mirrors/st/stellar-core

概述

Stellar-Core 是 Stellar 网络的核心组件，负责维护分布式账本、处理交易以及参与共识过程。本文将全面介绍 Stellar-Core 的安装部署、运行管理以及常用操作命令，帮助开发者和系统管理员快速掌握核心功能。

安装与运行

生产环境部署

在生产环境中运行 Stellar-Core 有两种主要角色：

1. 观察节点(Watcher)：仅同步网络数据但不参与共识
2. 验证节点(Validator)：参与共识过程并验证交易

生产部署需要特别注意安全配置和性能调优，建议参考详细的管理指南进行设置。

安装方式

Debian 包安装（Linux）

在 Linux 系统上，最简单的方式是使用预构建的 Debian 包安装：

1. 添加 Stellar 软件源
2. 通过 apt-get 安装 stellar-core 包
3. 完成基础配置后启动服务

这种方式适合需要长期稳定运行的节点。

Docker 快速启动

对于快速测试和开发环境，可以使用预构建的 Docker 镜像：

1. 拉取最新的稳定版或候选版镜像
2. 通过 docker-compose 启动容器
3. 容器已包含 Stellar-Core 和 Horizon 的集成环境

开发容器

使用 VS Code 的开发容器功能可以快速搭建开发环境：

1. 安装 VS Code 和容器插件
2. 克隆项目并打开开发容器配置
3. 容器会自动构建并运行 Stellar-Core 实例

测试构建与功能验证

生产环境的构建通常会禁用测试钩子以优化性能。要验证当前构建是否包含测试功能，可以检查帮助命令：

stellar-core help

如果输出中包含 test 子命令，则说明测试功能已启用：

  test                              execute test suite

节点管理与交互

管理接口

Stellar-Core 提供了 HTTP 管理接口，可以通过两种方式访问：

1. 直接使用 HTTP 客户端：

curl http://localhost:11626/peers

2. 使用内置命令：

stellar-core http-command peers

日志管理

日志系统支持精细化控制：

• 使用 ll 命令动态调整日志级别
• 可以针对特定模块(partition)设置不同日志级别
• perf 分区专门用于性能关键任务的监控
• logrotate 命令配合日志轮转工具使用

性能指标

Stellar-Core 内置了丰富的性能指标系统：

• metrics：获取所有指标的 JSON 格式数据
• clearmetrics：重置所有指标计数器，便于测试时获取干净数据

指标数据包括网络状态、处理性能、资源使用等关键信息。

网络管理

覆盖网络控制

节点提供了多种网络管理功能：

• peers：查看当前连接的节点
• 拓扑调查命令：获取全局网络拓扑信息

节点连接控制命令：

• ban：禁止特定节点连接
• connect：主动连接到指定节点
• droppeer：断开与特定节点的连接

维护操作

节点会维护历史数据用于发布，当需要深度清理时：

maintenance?count=100000000

此操作可能耗时较长，完成后可执行 PostgreSQL 的 VACUUM FULL 回收磁盘空间。

测试功能

手动控制

在配置 MANUAL_CLOSE=true 时：

• manualclose：手动关闭账本
• 配合 RUN_STANDALONE=true 可控制账本参数

负载生成

在私有网络中：

• generateload：创建测试账户并生成模拟流量
• 可用于压力测试和性能评估

历史数据操作

离线追赶

catchup 命令支持从历史存档中重放特定账本范围：

catchup [ledger]/[count]

注意事项：

• 不会连接实时网络
• 可能产生发布积压
• 可配置写入存档行为

可信账本验证

为防范存档数据篡改，可使用可信哈希验证：

1. 生成参考文件：

verify-checkpoints --output-filename hashes.json

2. 使用参考文件进行追赶：

catchup --trusted-checkpoint-hashes hashes.json

存档查询与验证

• report-last-history-checkpoint：查询最后发布的检查点
• catchup --extra-verification：验证存档完整性

账本状态管理

离线信息

offline-info 命令可快速获取节点状态信息：

stellar-core offline-info --ll fatal

输出为纯 JSON 格式，包含最后加载的账本、支持协议版本等信息。

快照测试

优化特定账本测试流程：

1. 先追赶至目标账本前一个：

catchup 1999/0

2. 备份数据库状态
3. 恢复后重放目标账本：

catchup 2000/1

数据库重建

当数据库损坏时，可从桶数据重建：

rebuild-ledger-from-buckets

XDR 工具

XDR 解析

• dump-xdr：解析存档中的 XDR 流
• print-xdr：解析单个 XDR 对象（支持二进制和 Base64）

示例：

stellar-core print-xdr --base64 tx-result.txt

密钥管理

密钥生成

stellar-core gen-seed

输出包含私钥和对应的公钥地址。

密钥转换

stellar-core convert-id GDJLE5FAS4RVCWX...

显示密钥的不同表示形式（字符串和十六进制）。

交易签名

stellar-core sign-transaction [参数]

低权限运行

通过分离数据库升级操作，可使用低权限账号运行：

stellar-core upgrade-db

先由高权限账号完成架构更新，再切换至低权限账号运行核心服务。

总结

本文详细介绍了 Stellar-Core 的安装部署、日常管理和高级操作技巧。掌握这些核心功能后，开发者可以更高效地运行和维护 Stellar 网络节点，进行各种测试和验证工作。对于生产环境部署，建议结合详细的配置指南和安全最佳实践进行操作。

stellar-core stellar-core is the reference implementation for the peer to peer agent that manages the Stellar network 项目地址: https://gitcode.com/gh_mirrors/st/stellar-core