Pi节点更新：揭秘Horizon API迁移、Docker镜像切换与主网准备

2025年4月30日，Pi节点软件推出了一次重要升级，自动触发对Horizon区块链API的数据库迁移，并同时切换Docker镜像版本。从未升级的节点上会出现容器无法正常运行的问题，升级完成后节点恢复正常，用户无需手动干预。派节点网将带您了解此次升级提示、流程，以及两种关键镜像（社区测试网Community与主网Mainnet预发布版）的Layers架构与常见指令。

一、升级提示与影响

弹窗提示

当节点软件检测到当前环境需支持新版Horizon API时，会弹出如下英文提示：

Migration is required to run the Horizon blockchain API. This process cannot be interrupted and may take time. Do you want to start now? You will be redirected to the Troubleshooting page.

升级前故障

升级前，部分节点的Docker容器因不兼容新版Horizon而无法启动，导致区块同步中断或运行异常。

升级触发与结果

用户点击“确认”后，系统自动跳转到故障排查页面，并继续执行数据库迁移与镜像切换。升级完成后，区块同步恢复正常，容器重新启动并保持稳定运行。

二、升级流程详解

1.确认迁移

弹窗确认后，进入“故障排查（Troubleshooting）”页面，提示：

Upgrade Horizon Database (required). This process is required to start Horizon. Please proceed with caution, as it may take some time to complete. Interrupting the upgrade could result in data loss or corruption.

2.数据库升级

系统后台执行对Horizon数据库的结构与数据迁移，确保新版本服务能正常启动。期间请勿手动终止进程，以免数据损坏。

3.Docker镜像切换

完成数据库升级后，节点软件会自动将Docker镜像从

pinetwork/pi-node-docker:protocol19

切换为

pinetwork/pi-node-docker:community-v1.0-p19.6

切换过程无需用户手动拉取或重命名镜像，软件内部已完成所有操作。

三、两款Pi Node镜像Layers对比

以下分别展示了社区测试网新镜像与主网预发布版镜像的主要Layers（已省略重复条目，仅列关键部分），并附上常见指令说明。

1. 社区测试网镜像pinetwork/pi-node-docker:community-v1.0-p19.6

# 基础镜像与元信息
ARG RELEASE
ARG LAUNCHPAD_BUILD_ARCH
LABEL org.opencontainers.image.ref.name=ubuntu
LABEL org.opencontainers.image.version=20.04

# 将根文件系统添加到镜像
ADD file:7486…909f9e in /

# 默认启动 shell
CMD ["/bin/bash"]

# 环境变量：指定 Stellar Core 与 Horizon 版本
ENV STELLAR_CORE_VERSION=19.6.0-1138.b3a6bc281.focal
ENV HORIZON_VERSION=2.23.1-320

# 暴露端口：PostgreSQL、Horizon、节点对等通信
EXPOSE 5432/tcp
EXPOSE 8000/tcp
EXPOSE 31402/tcp

# 安装依赖并赋予执行权限
ADD dependencies /
RUN chmod +x dependencies
RUN /bin/sh -c ./dependencies

# 安装主程序
ADD install /
RUN chmod +x install
RUN /bin/sh -c ./install

# 创建工作目录并打标
RUN mkdir -p /opt/stellar
RUN touch /opt/stellar/.docker-ephemeral

# 建立关键配置的软链接
RUN ln -s /opt/stellar /stellar
RUN ln -s /opt/stellar/core/etc/stellar-core.cfg /stellar-core.cfg
RUN ln -s /opt/stellar/horizon/etc/horizon.env /horizon.env

# 添加各网络环境默认配置
ADD common      /opt/stellar-default/common
ADD pubnet      /opt/stellar-default/pubnet
ADD testnet     /opt/stellar-default/testnet
ADD testnet2    /opt/stellar-default/testnet2
ADD standalone  /opt/stellar-default/standalone

# 启动脚本及入口
ADD start /
RUN chmod +x start
ENTRYPOINT ["/start"]

2. 主网预发布镜像：pinetwork/pi-node-docker:mainnet_relay-v1.0-p19.6

# 基础镜像与元信息
ARG RELEASE
ARG LAUNCHPAD_BUILD_ARCH
LABEL org.opencontainers.image.ref.name=ubuntu
LABEL org.opencontainers.image.version=20.04

# 根文件系统与默认命令
ADD file:f9ee…43b9894 in /
CMD ["/bin/bash"]

# Stellar Core 与 Horizon 版本
ENV STELLAR_CORE_VERSION=19.6.0-1138.b3a6bc281.focal
ENV HORIZON_VERSION=2.23.1-320

# 端口配置
EXPOSE 5432/tcp
EXPOSE 8000/tcp
EXPOSE 31402/tcp

# 依赖与安装流程
ADD dependencies /
RUN chmod +x dependencies
RUN /bin/sh -c ./dependencies
ADD install /
RUN chmod +x install
RUN /bin/sh -c ./install

# 目录创建与软链接
RUN mkdir -p /opt/stellar
RUN touch /opt/stellar/.docker-ephemeral
RUN ln -s /opt/stellar /stellar
RUN ln -s /opt/stellar/core/etc/stellar-core.cfg /stellar-core.cfg
RUN ln -s /opt/stellar/horizon/etc/horizon.env /horizon.env

# 主网及测试网配置
ADD common      /opt/stellar-default/common
ADD mainnet     /opt/stellar-default/mainnet
ADD testnet     /opt/stellar-default/testnet
ADD testnet2    /opt/stellar-default/testnet2
ADD standalone  /opt/stellar-default/standalone

# 启动脚本与入口设置
ADD start /
RUN chmod +x start
ENTRYPOINT ["/start"]

Docker指令介绍：

• ADD / COPY：将本地文件或目录导入镜像，形成新层。
• RUN：在镜像中执行命令（如安装依赖、创建目录、生成软链接），每条指令都产生一层。
• ENV：设置环境变量，用于版本管理或运行时参数。
• EXPOSE：声明容器监听端口，便于用户或编排系统映射使用。
• CMD / ENTRYPOINT：指定容器启动时执行的默认命令或脚本。

节点Docker容器差异：

四、技术架构进化启示

通过镜像层分析可见三大技术动向：

多网络架构优化

• 符号链接设计 /opt/stellar → /stellar 实现路径统一
• 核心配置文件标准化 /stellar-core.cfg 集中管理

服务韧性增强

• 新增 .docker-ephemeral 标记文件保障临时数据安全
• 启动脚本权限加固 chmod +x 提升执行可靠性

主网就绪信号

• mainnet配置目录预置表明底层架构已完成主网适配
• Stellar Core 19.6版本集成最新共识算法优化

五、用户须知与建议

自动化升级

本次升级由Pi Node节点软件自动推送，无需您手动拉取或切换镜像标签。只需在提示框中点击“确认”，并保证节点在整个过程不中断网络与运行。

无需手动切换主网镜像

虽然Docker Hub仓库已上线mainnet_relay-v1.0-p19.6镜像，但当前Pi节点仍运行在社区测试网环境。请继续使用官方提示的社区版镜像，等待后续官方正式切换主网的通知。

保持耐心并监控日志

升级与数据迁移可能需要数分钟至十几分钟不等，具体取决于本地硬件与网络环境。升级完成后，可通过查看节点日志确认服务已正常启动，区块同步恢复。