2025年4月30日，Pi节点软件推出了一次重要升级，自动触发对Horizon区块链API的数据库迁移，并同时切换Docker镜像版本。从未升级的节点上会出现容器无法正常运行的问题，升级完成后节点恢复正常，用户无需手动干预。派节点网将带您了解此次升级提示、流程，以及两种关键镜像（社区测试网Community与主网Mainnet预发布版）的Layers架构与常见指令。
一、升级提示与影响
弹窗提示
当节点软件检测到当前环境需支持新版Horizon API时，会弹出如下英文提示：
需要进行迁移才能运行 Horizon 区块链 API。此过程无法中断，可能需要一些时间。您想立即开始吗？您将被重定向到“故障排除”页面。
升级前故障
升级前，部分节点的Docker容器因不兼容新版Horizon而无法启动，导致区块同步中断或运行异常。
升级触发与结果
用户点击“确认”后，系统自动跳转到故障排查页面，并继续执行数据库迁移与镜像切换。升级完成后，区块同步恢复正常，容器重新启动并保持稳定运行。
二、升级流程详解
1.确认迁移
弹窗确认后，进入“故障排查（Troubleshooting）”页面，提示：
升级 Horizon 数据库（必需）。此过程是启动 Horizon 所必需的。请谨慎操作，因为升级可能需要一些时间才能完成。中断升级可能会导致数据丢失或损坏。
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容器差异：
| 维度 |
Community版镜像 |
Mainnet版镜像 |
| 配置目录 |
包含pubnet配置 |
新增mainnet专属配置 |
| 运行模式 |
多网络环境兼容 |
主网优先但保留测试网支持 |
| 当前状态 |
生产环境强制启用 |
镜像预热阶段 |
四、技术架构进化启示
通过镜像层分析可见三大技术动向：
多网络架构优化
- 符号链接设计 /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节点仍运行在社区测试网环境。请继续使用官方提示的社区版镜像，等待后续官方正式切换主网的通知。
保持耐心并监控日志
升级与数据迁移可能需要数分钟至十几分钟不等，具体取决于本地硬件与网络环境。升级完成后，可通过查看节点日志确认服务已正常启动，区块同步恢复。
