面向：Pi Node 界面一片空白、转圈不动、或者区块高度卡死在那儿的人。
这篇不讲原理，只给排查顺序 —— 按顺序走，绝大多数情况能自己定位到。
先说一个重要的事实
「区块高度卡住不动」是全网普遍现象，不是你一个人的问题。
Pi 官方的 GitHub issues 里，#345、#184 等大量记录都是这个问题，社区共识的解法是： 重启 docker 容器，不是重装系统、不是重装软件。
很多人第一反应是卸载重装，结果节点数据全丢、要重新同步几小时到几天。 先别动，按下面的顺序查。
排查顺序（从最轻的动作开始）
第一层：先确认是不是"假死"
有时候界面不动，但节点其实在工作。先看容器状态：
docker ps -a --filter name=testnet2 --format '{{.Names}}\t{{.Status}}'看 Status 那一列：
| 你看到 | 含义 | 下一步 | |---|---|---| | Up 3 days | 容器活着 | 看第二层 | | Restarting (1) 5 seconds ago | 反复崩溃重启 | 看第四层（日志） | | Exited (137) | 进程被强制杀掉（Docker 里 137 = 128+9，通常是内存不足） | 看第五层 | | Exited (1) | 启动即失败 | 看第四层（日志） | | 什么都没有 | 容器根本没建 | 看第六层 |
容器名是testnet2，不是旧教程里的pi-consensus。
如果你的命令查不到东西，先 docker ps -a 全看一眼实际叫什么。第二层：容器活着但界面不动
直接问 stellar-core 它自己觉得怎么样：
docker exec testnet2 curl -s localhost:11626/info | head -c 400重点看两个字段：
"state": "Synced!"→ 同步好了，问题在客户端显示层，不是节点"state": "Catching up"→ 还在追块，看下面的判断
如果 `state` 是 `Synced!` 但界面还转圈 —— 那是客户端 UI 的问题， 节点本身没事，你的奖励不受影响。这种情况重启客户端（不是容器）就行。
如果是 `Catching up` 且 `ledger.num` 长时间不动 —— 是追块卡住了， 这是我写过的另一个问题（历史归档源下载不通），不是"白屏"范畴。
第三层：端口通不通（这层最容易被忽略）
节点能连出去 ≠ 别人能连进来。从另一台公网机器测：
IP=你的公网IP
for p in $(seq 31400 31409); do
timeout 3 nc -zv "$IP" "$p" >/dev/null 2>&1 && echo "$p 通" || echo "$p 不通 ★"
done要十个全通。打不通的时候，三层都要查：
- 路由器端口转发 —— 家里宽带最常见的问题
- 主机防火墙 —— Windows 防火墙 / ufw / firewalld
- 云厂商安全组 —— 云服务器默认只放 22/80/443
任何一层拦了都表现为"不通"，所以要三层都过一遍。
第四层：看日志，别猜
# 容器内的 stellar-core 日志
docker exec testnet2 tail -100 /tmp/stellar-core.log
# supervisor 日志（看进程有没有反复重启）
docker exec testnet2 ls /var/log/supervisor/
docker exec testnet2 tail -50 /var/log/supervisor/*.log日志里出现这些词，对应不同问题：
| 日志关键词 | 含义 | |---|---| | FATAL | 致命错误，通常是配置或数据库问题 | | Catchup material failed verification | 版本不匹配（比如全网升级了协议，你的还是旧版） | | unsupported ledger version | 同上，必须升级容器镜像 | | Connection refused 大量重复 | 依赖服务（postgres）没起来 | | No space left on device | 磁盘满了 |
`unsupported ledger version` 这个特别要注意：这不是你的错，是 Pi 网络升级了协议， 你的节点还是旧版本，追不上新块。解法是拉新镜像重启容器。
第五层：内存不足（Windows 用户尤其常见）
Exited (137) 就是被 OOM killer 干掉了。查一下：
docker inspect testnet2 --format '{{.State.OOMKilled}}'返回 true 就是内存不足。Pi 节点跑起来吃内存不少，Windows 上 如果同时开着浏览器一堆标签页，很容易触发。
解法：给 Docker Desktop 分配更多内存，或者关掉别的程序。不是重装能解决的。
第六层：容器根本没建起来
说明客户端启动时就没成功创建容器。看客户端的日志：
- Windows：
%APPDATA%\Pi Network\下面找日志 - Linux：
~/.config/Pi Network/或对应路径
常见原因：
- Docker 服务没启动（
docker ps报连不上 daemon） - 磁盘空间不足，创建容器失败
- 客户端没有权限访问 Docker（Linux 下用户不在 docker 组）
一个高频误区：重装能解决一切
不能，而且会让情况更糟。
节点数据在 <USER_DATA>/docker_volumes/testnet_2/stellar，重装软件如果清了这个目录， 节点身份和已同步的数据全没，要从零同步（几小时到几天，看网络）。
社区里大量"重装后更糟"的案例。正确的动作顺序是： 先看状态 → 再看端口 → 再看日志 → 最后才考虑重建容器。
重建容器（docker rm -f testnet2 让客户端重建）比"重装整个软件"轻得多， 但在做之前一定先备份 docker_volumes 目录。
几个别踩的坑
别把 5432 端口开到公网。 有人为了"方便排查"把数据库端口暴露出去，这是安全事故级别的操作。 数据库只该监听容器内网。
别用最新版 Docker 就一定好。 Pi 节点的镜像和 Docker 版本之间有兼容性要求，盲目升级 Docker 可能让原本能跑的容器起不来。 升级前先记下当前版本。
别同时改多个东西。 改配置、升镜像、开端口一起做，出问题就不知道是哪个导致的。 一次改一个，改完验证，再改下一个。
小结（按这个顺序）
docker ps看容器状态 —— 分清是崩了还是假死docker exec ... 11626/info看state—— 分清是同步问题还是 UI 问题- 十个端口从公网测一遍 —— 路由器 / 防火墙 / 安全组三层
- 看日志关键词 ——
unsupported ledger version要升级镜像 OOMKilled查内存 —— Windows 用户高发- 最后才考虑重建容器，重装软件是下下策
---