2.4 1pctl 命令行速查与常见安装失败排查

一句话回答

1pctl 是 1Panel 自带的命令行运维工具：面板打不开时它是唯一的救场手段，日常的启停、改端口、重置安全设置它都能干。记住三条命令（1pctl status、1pctl user-info、1pctl reset --help），能应付绝大多数事故。

1Panel 安装时会默认内置这个工具，通常在 /usr/local/bin/1pctl，在终端里直接敲 1pctl 就能用。它最大的价值在于：面板打不开的时候，它还在。 所有在面板里能改的安全设置（端口、安全入口、域名绑定、授权 IP、MFA），命令行里都能改回来。

什么时候用它？三类场景：

先 1pctl help 或 1pctl --help 看完整说明，下面是整理好的速查表。

参数中的 core / agent 指服务组件；单机环境直接敲 1pctl status 就行，看输出确认面板是否在正常运行。

用法都是交互式的，敲完按提示输入新值。

这条命令系列就是 2.3 节「把自己锁外面」的正式解法。 注意 reset 是取消限制，不是重置成新值——取消后回面板重新设一个。

子命令	作用
`1pctl listen-ip ipv4`	监听 IPv4
`1pctl listen-ip ipv6`	监听 IPv6

# 看面板有没有活着
1pctl status

# 忘了安全入口，重新查一下
1pctl user-info

# 改了配置后面板没生效，重启服务
1pctl restart

# 不打算用 1Panel 了（先想清楚，见下文）
1pctl uninstall

关于 1pctl uninstall，两个提醒：

卸载前做好备份。你的网站、数据库、容器数据在 /opt/1panel 下（或你自定义的安装目录），卸载面板不等于数据全没，但动卸载前先做快照、先确认数据另有备份，这是不可逆操作。
卸载后面板和容器应用可以分开处理，应用该删删、该留留（第一章 1.1 节说过「它是管理工具，不是托管绑架」）。

把官方 FAQ 里和安装、面板访问相关的典型问题整理成一张表，对号入座：

#	现象	原因	解法
1	安装时提示 `ERROR: Unsupported distribution 'xxx'`	Docker 在线脚本不支持这个发行版	先手动装 Docker：`bash <(curl -sSL https://linuxmirrors.cn/docker.sh)`，再装 1Panel
2	WSL 子系统安装失败：`System has not been booted with systemd`	WSL 没启用 systemd，Docker 服务起不来	更新 WSL 并开启 systemd 支持，再重新安装
3	Fedora 37 装完面板，防火墙里的端口规则不生效	默认区域不是 public	`firewall-cmd --set-default-zone=public` 然后 `firewall-cmd --reload`
4	装完浏览器打不开面板	云安全组或本机防火墙没放行端口	两道防火墙都放行（2.3 节）
5	端口改完面板起不来	新端口已被占用	`1pctl update port` 换一个，或先查占用
6	自建 Nginx 反代 1Panel 后，主机和容器终端都不能用	WebSocket 没透传	Nginx 配置里加 `proxy_http_version 1.1;` 和 `Upgrade` 头；或者在 1Panel 里新建反向代理网站实现

关于第 6 条，官方给出的 Nginx 配置片段是：

location / {
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

终端是长连接 WebSocket，反代不透传 Upgrade 头就断了。

如果你用的是 armv7l 或 s390x 架构（比如某些工控机、树莓派、IBM 大型机），应用商店装 MySQL / OpenResty 可能失败——因为官方镜像没有这些架构的版本。官方 FAQ 的解法是手动拉对应架构的镜像再重命名：

# 例：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 安装

armv7l 的 MySQL 8.0 官方明确暂不支持。x86_64 用户不用管这一节，云服务器基本都是 x86_64。

遇到问题别乱试，按这个顺序查：

先看状态：1pctl status，面板进程在不在。
再看日志：面板里 日志审计 → 系统日志，升级失败、快照恢复失败的原因都在这里（2.2 节提过）。
再分层排查：网络通不通（ping）、端口开没开（两道防火墙）、服务起没起（1pctl status）、配置对不对（1pctl user-info）。
最后再考虑重置：1pctl reset / 1pctl update 逐项试，一次只改一项，改完验证，别一次 reset 全套。

一个习惯建议：重置或修改前，先在面板里建个快照（2.2 节）。命令行的操作不像面板里有确认弹窗，敲下去就生效了。

1pctl 是面板自带的命令行工具，面板打不开时它是唯一救场手段；
三条必记命令：1pctl status（看状态）、1pctl user-info（查访问信息）、1pctl reset --help（看能重置什么）；
1pctl reset 系列取消安全限制（安全入口/域名/授权 IP/HTTPS/MFA），1pctl update 系列修改端口、用户名、密码；
安装失败先对号入座排查表：Docker 不支持、WSL、防火墙区域、端口占用是四大常见原因；
排错顺序：状态 → 日志（日志审计 → 系统日志）→ 分层排查 → 逐项重置；
动卸载和重置之前先做快照，这些操作不可逆。

命令行工具的完整官方说明，见《1Panel 官方文档：产品介绍与安装部署》中的「1pctl 命令行工具」一节；更多疑难杂症可查站内《1Panel 常见问题与排错实战》。

下一章：面板装好、加固完成，我们开始建站——从创建网站的第一种方式说起。