1.1 安装失败或卡住的常见原因

1.1 安装失败或卡住的常见原因

先给一个判断

安装卡住，90% 不是 1Panel 的问题，而是 Docker 和网络的问题。 1Panel 的安装脚本本身很短，真正耗时的一步是“装 Docker”。所以下次卡住的时候，先看它到底卡在哪一行，别上来就重装系统。

现象：卡住长什么样

现象	看到什么	卡在哪
A	卡在某一行不动，没有输出	网络请求超时（下载源不可达）
B	直接报 `ERROR: Unsupported distribution`	Docker 脚本不支持你的发行版
C	Docker 装完了，面板没起来	面板服务启动失败
D	脚本跑完了，但访问不了	端口/防火墙问题（见 1.2 节）

注意 A 和 D 的区别：A 是脚本没跑完，D 是脚本跑完了但访问不了。先分清这两类，排查方向就对了。

可能原因与排查

原因一：系统不支持，Docker 装不上（最常见）

报错原文：

ERROR: Unsupported distribution 'xxx'

这是 Docker 官方安装脚本的报错，不是 1Panel 的。官方 FAQ 给出了明确答案：先手动装好 Docker 并启动，再装 1Panel。

先确认你的系统版本：

cat /etc/os-release

手动装 Docker（官方 FAQ 推荐的脚本）：

bash <(curl -sSL https://linuxmirrors.cn/docker.sh)

装完验证：

systemctl status docker
docker version

Docker 正常后，重新执行 1Panel 安装脚本。

原因二：WSL 子系统装不了

在 Windows 的 WSL 里安装，通常报这一行：

System has not been booted with systemd as init system (PID 1).
Can't operate. Failed to connect to bus: Host is down

根因是 WSL 没开 systemd，导致 Docker 服务起不来。解决办法是按微软官方文档开启 systemd 支持，重启 WSL 后再装。

一句话边界：WSL 不是正经的服务器环境，官方 FAQ 把它单列出来，本身就说明这是“能凑合但不推荐”的场景。生产环境请用真正的 Linux 服务器。

原因三：网络不通或太慢

安装脚本要下载文件，网络不行就卡住。先测连通性：

curl -sSL -o /dev/null -w "%{http_code} %{time_total}s\n" https://resource.fit2cloud.com/1panel/package/v2/quick_start.sh

如果超时或很慢，按情况处理：

情况	处理
国内服务器	检查是否有异常代理、DNS 解析是否正常
海外服务器	一般没问题，确认没被出站防火墙拦
完全内网	别用在线安装，用离线安装包

离线安装的思路：在能上网的机器下载对应架构的安装包，上传到服务器解压，进入目录执行 install.sh。升级时则执行 upgrade.sh。

原因四：内存和磁盘不够

官方环境要求写得很清楚：可用内存建议 1GB 以上。别小看这一条：

free -h
df -h /

真实场景：512M 内存的小机器能装上，但跑两个数据库就 OOM。这种机器不是不能装，是装完也别指望跑很多应用。

原因五：特殊架构的镜像问题

官方支持 x86_64、aarch64、armv7l、ppc64le、s390x、riscv64，但有些架构上数据库镜像是缺失的：

架构	问题	官方解法
s390x	MySQL 官方无此架构镜像	手动拉 `ibmcom/mysql-s390x` 再 `docker tag` 成商店使用的版本
armv7l	MySQL 8.0 不支持	只能用 5.7；OpenResty 也要换成社区维护的镜像

以 s390x 装 MySQL 5.7 为例：

docker pull ibmcom/mysql-s390x:5.7.34
docker tag ibmcom/mysql-s390x:5.7.34 mysql:5.7.42

重命名完成后再去应用商店安装，版本选 5.7.42。详见 1Panel 官方文档：服务器架构相关 FAQ。

原因六：非交互安装参数写错

自动化部署常用非交互模式，参数不对会静默失败。关键的几个环境变量：

环境变量	作用	易错点
`PANEL_NON_INTERACTIVE=true`	开启非交互模式	不写脚本会停下来等你输入
`PANEL_PORT=18080`	指定面板端口	不写会随机生成，自动化脚本对不上
`PANEL_ENTRANCE=panelEntrance`	安全入口	3-30 位字母、数字、下划线
`PANEL_PASSWORD='ChangeMe_123456'`	面板密码	8-30 位；建议用环境变量传，别写在命令行参数里
`PANEL_INSTALL_DOCKER=y`	是否自动装 Docker	非交互模式默认 n，不开就不会装
`PANEL_CONFIGURE_ACCELERATOR=y`	是否配镜像加速	同上，默认 n

最容易踩的坑：忘了写 PANEL_INSTALL_DOCKER=y，脚本跑完了，Docker 没装，后面应用全部装不上。

原因七：旧版本残留或端口被占用

服务器上以前装过 1Panel、或者别的面板（比如宝塔），再装新版本时可能起不来。重点是两个地方：

# 端口是否被占用（把 8090 换成你的面板端口）
ss -ltnp | grep 8090

# 是否有旧的 1Panel 进程
ps aux | grep 1panel | grep -v grep

如果旧进程还在，先停掉再装。注意：卸载旧面板前一定要备份好数据，快照和数据库备份先下载到本地，别等删完了才想起来。

原因八：SELinux / 系统安全策略拦截

有些国产系统或加固版系统默认开着 SELinux 且策略严格，会导致 Docker 或面板服务异常。可以先临时关闭验证：

setenforce 0
getenforce

如果关掉之后装上了，说明是策略问题，再按需调整策略而不是长期关闭。长期关闭 SELinux 要看你公司的安全规范。

一个完整的复现与修复

现象：一台 CentOS 7 服务器，执行官方安装脚本，卡住十几分钟不动。

排查过程：

# 第一步：确认脚本到底有没有在跑
ps aux | grep -E "quick_start|yum|dnf" | grep -v grep

# 第二步：看是不是在等网络
# 直接测下载速度
curl -sSL -o /dev/null -w "%{time_total}s\n" https://resource.fit2cloud.com/

# 第三步：看系统日志
tail -f /var/log/messages

结论：下载速度只有几十 KB/s，卡在下载 Docker 的 RPM 包上。

修复：先用国内镜像源手动装好 Docker，再跑 1Panel 脚本，两分钟装完。

装完之后的第一件事

很多人装完就开始建网站，千万别急。先做三件事：

把控制台打印的信息（地址、端口、入口、账号密码）记下来，丢了就用 1pctl user-info 重看。
立刻去云控制台的安全组里确认端口已放行（下一节细讲）。
试一下 1pctl status，确认面板服务是 running。

1pctl status
1pctl user-info

这三步做完，再开始后面的操作，能省掉后面 80% 的“莫名其妙”。

本节要点

安装卡住先定位“卡在哪一行”，别重装；
Unsupported distribution 是 Docker 的报错，手动装 Docker 即可；
WSL 要先开 systemd；内网环境用离线包；
特殊架构（s390x/armv7l）数据库镜像要手动拉取并 docker tag；
非交互安装记得显式开 PANEL_INSTALL_DOCKER=y；
装完先 1pctl status + 1pctl user-info，再干别的。

下一节：脚本跑完了、面板也起来了，但浏览器就是打不开——我们来说说端口、防火墙和安全组这三道门。