1Panel 常用运维指令手册

适用版本：1Panel v1.10 LTS / v2.0 ~ v2.4.x（当前 v2.4.1，2026-10-20 发布） 宿主系统：Debian 11/12/13、Ubuntu 20.04/22.04/24.04、CentOS 7/8、RHEL 8/9、Rocky/Alma、openEuler、Anolis、麒麟 V10、统信 UOS 架构：x86_64 / aarch64 / armv7l / ppc64le / s390x / riscv64 约定：# root 或 sudo，$ 普通用户，<xxx> 为占位符，安装目录默认 /opt/1panel，简写为 $PANEL_DIR。 差异标注：正文用 > **版本差异** 和 > **坑** 标注跨版本不一致与高频误操作。 更新时间：2026-11（版本事实核对至 2026-11-05）

目录

1. 版本形态与产品边界
2. 安装部署
3. 目录结构与运行机制
4. 1pctl 命令全集
5. 面板基础配置与安全入口
6. 容器管理
7. 应用商店机制
8. 网站管理
9. 数据库管理
10. 文件、终端与计划任务
11. 备份、快照与迁移
12. 防火墙与网络
13. 监控、日志与告警
14. 证书与域名
15. 升级、降级与回滚
16. 多机管理与 Core / Agent
17. 高级能力与扩展
18. 卸载与残留清理
19. 故障速查
20. 安全基线与危险操作红线
21. 附录

1. 版本形态与产品边界

1.1 它是什么、不是什么

1Panel 是飞致云（FIT2CLOUD）开源的 Linux 服务器运维面板，Go 后端 + Vue 前端，核心设计是把所有被管理的应用都跑在 Docker Compose 里。这一点决定了它和传统面板（宝塔）的根本差别：

不要同时装两套面板。1Panel 与宝塔/aaPanel 都会抢 80/443、都会写 /etc/docker/daemon.json、都会托管防火墙规则，冲突不是"端口改一下"能解决的。迁移窗口期可以并存，但必须在同一小时内完成切换。

1.2 版本线（2026-11）

版本差异：v1 → v2 不是简单改镜像 tag。v2 把面板拆成 1panel-core.service 与 1panel-agent.service，1pctl status/start/stop/restart 在 v2 支持 [core|agent|all] 参数，v1 不带参数。跨大版本升级前必须做快照，官方提供迁移路径但不支持原地回滚到 v1。

1.3 版本与授权形态

这条在信创、金融、等保场景要特别注意："开源"≠"官方安装脚本里的二进制是纯社区版代码"。审计问起时，要么走源码构建，要么明确记录授权与二进制来源。

1.4 先确认自己接手的是哪一套

1pctl version                       # 面板版本
1pctl status                        # v1 输出单服务；v2 输出 core/agent 两行
systemctl list-units --type=service | grep -i 1panel
docker ps --format '{{.Names}}\t{{.Image}}' | head -20
ls -la /opt/1panel 2>/dev/null || ls -la /opt/1panel* 2>/dev/null

2. 安装部署

2.1 前置检查（安装前必跑）

# 1) 系统血统与架构
cat /etc/os-release
uname -m

# 2) 是否已有面板 / Web 服务占 80 443
ss -tunlp | grep -E ':80 |:443 |:888 |:30083 '
systemctl is-active nginx apache2 httpd bt 2>/dev/null

# 3) 磁盘与内存
df -h / /opt
free -h

# 4) Docker 是否已装、是否健康
docker version
docker info | grep -E 'Storage Driver|Cgroup Driver|Docker Root Dir'

要求：内存 ≥ 1 GB（实际生产建议 ≥ 2 GB，装 MySQL + OpenResty + Redis 后 1 GB 会频繁 OOM）；/opt 建议独立分区或至少 20 GB 可用；必须能访问 Docker 镜像仓库，否则应用商店全线失败。

坑：1Panel 安装脚本会自行安装/接管 Docker，并可能改写 /etc/docker/daemon.json。如果这台机器上已经有跑着业务的 Docker，先备份 daemon.json，并确认脚本是否会重启 dockerd（重启会短暂中断现有容器）。已有生产容器的机器，建议先手工装好 Docker 再装面板，避免脚本覆盖配置。

2.2 在线安装

# 官方（国际 / 通用入口）
curl -sSL https://resource.fit2cloud.com/1panel/package/quick_start.sh -o quick_start.sh && bash quick_start.sh

# 国内资源入口（下载更快）
curl -sSL https://resource.1panel.pro/quick_start.sh -o quick_start.sh && bash quick_start.sh

交互项依次是：

安装完成后终端会打印完整访问信息（含安全入口）。忘记就重新取：

1pctl user-info

云服务器还要在安全组里放行面板端口。国内三大云的控制台安全组和系统内 firewalld 是两层，只改一层照样连不上。

2.3 离线 / 内网安装

内网机器没有外网时，用官方离线包（含 Docker 与面板二进制）。流程：

# 外网机：下载对应架构的离线安装包（以实际发布页文件名为准）
# 传到内网机
scp 1panel-v2.4.1-linux-amd64.tar.gz root@10.0.0.10:/opt/

# 内网机
cd /opt && tar zxf 1panel-v2.4.1-linux-amd64.tar.gz && cd 1panel-v2.4.1-linux-amd64
bash install.sh

离线环境的三个后续动作，缺一不可：

1. 把内部镜像仓库地址写进 /etc/docker/daemon.json 的 registry-mirrors / insecure-registries，systemctl restart docker。
2. 在面板「设置 → 应用商店」把应用商店源切到内网镜像/内网 Git 镜像，否则应用列表能打开但一个都装不上。
3. 关闭面板的在线检查更新与在线 License 校验，否则每次登录都会卡几秒等超时。

2.4 国产系统与信创适配

国产系统上是"面板能装 ≠ 应用能装"。先用一个最小应用（如 hello-world 或 Nginx）验证 docker pull 与 Compose 可用，再装业务应用。

2.5 安装后检查清单

1pctl status                                    # core / agent 均 active
1pctl version
systemctl is-enabled 1panel-core 1panel-agent   # v2
docker ps --format '{{.Names}} {{.Status}}'
ss -tunlp | grep -E "面板端口"
curl -k -I https://127.0.0.1:<面板端口>/<安全入口>
journalctl -u 1panel-core -n 50 --no-pager

3. 目录结构与运行机制

3.1 路径速查

版本差异：v1 的 systemd 单元叫 1panel.service，v2 拆成 1panel-core.service + 1panel-agent.service。写监控脚本、做开机自启检查时别照抄老教程。

3.2 三层数据模型

浏览器 ──HTTPS──> 1panel-core (Go, 提供 API/UI, 存 SQLite)
                      │ gRPC / HTTP
                      ▼
                 1panel-agent (v2, 在本机或受管节点执行)
                      │ Docker API / systemd / 文件系统
                      ▼
        ┌─────────────┼──────────────┐
   OpenResty容器   MySQL容器    应用商店 Compose 项目
   (网站/反代)     (业务库)     (每个应用一个目录 + 一个 project)

关键推论：

• 面板挂了，业务容器照常跑。1pctl stop 只停面板，不影响网站。
• 面板数据库（SQLite）丢了，网站还在，但面板里看到的站点、证书、计划任务、备份账号全没了，需要靠快照或手工重建元数据。所以快照比"备份网站文件"更重要。
• 应用的所有状态在 $PANEL_DIR/apps/，可以直接用 docker compose 操作，面板只是这层的一个 UI。

3.3 直接操作底层 Compose

# 找到某个应用的 compose 文件
find /opt/1panel/apps -name docker-compose.yml -maxdepth 5

# 进目录手工操作（面板会自动感知大部分变化）
cd /opt/1panel/apps/mysql/mysql
docker compose ps
docker compose logs -f --tail=100
docker compose restart
docker compose up -d

坑：手工改 docker-compose.yml 后，面板的应用升级/参数修改会覆盖回去。要么改完在面板里同步改参数，要么把修改写进面板的「编排」编辑器。生产环境建议以面板为准，命令行只用于排障。

4. 1pctl 命令全集

1pctl 是面板挂掉、Web 打不开时的唯一救生索，装在 /usr/local/bin/1pctl。

4.1 顶层命令

4.2 update 子命令

1pctl update username            # 交互式改面板用户名
1pctl update password            # 交互式改面板密码
1pctl update port                # 交互式改面板端口
1pctl update --help

改端口后要同步放行新端口（系统防火墙 + 云安全组），并关掉旧端口规则。改完先 1pctl user-info 拿新地址再断开当前会话。

4.3 reset 子命令（应急救援核心）

1pctl reset domain               # 取消域名绑定限制
1pctl reset entrance             # 取消安全入口（忘记那串随机字符）
1pctl reset https                # 取消强制 HTTPS 登录
1pctl reset ips                  # 取消授权 IP 白名单限制
1pctl reset mfa                  # 关闭两步验证（手机丢了 / MFA 码对不上）
1pctl reset --help

一点说明：官方文档里这段的 usage 写作 1panel reset [command]（少了 ctl），实际命令是 1pctl reset。文档笔误，别照抄。

安全提醒：reset entrance、reset ips、reset mfa 是把安全闸门一道道拆掉。应急用完必须立刻在面板里重新配置，并把这几个动作写进操作审计记录。

4.4 服务管理（systemd 层）

systemctl status 1panel-core 1panel-agent
systemctl restart 1panel-core
systemctl stop 1panel-agent
journalctl -u 1panel-core -f
journalctl -u 1panel-agent --since "1 hour ago" --no-pager

# v1（或单服务部署）
systemctl status 1panel.service

4.5 四个高频应急场景

# 场景 A：面板 502 / 打不开
1pctl status
1pctl restart all
journalctl -u 1panel-core -n 100 --no-pager | grep -iE 'error|panic|fatal'

# 场景 B：忘记安全入口 + 忘记密码 + 开过 MFA
1pctl reset entrance
1pctl reset mfa
1pctl update password
1pctl user-info

# 场景 C：HTTPS 证书配错导致自己进不去
1pctl reset https
1pctl restart all

# 场景 D：IP 白名单把办公网挡了
1pctl reset ips
1pctl status

5. 面板基础配置与安全入口

5.1 首次登录后必做的七件事

1. 改管理员密码（安装脚本生成的是随机串，但要换成自己的密码管理器里的高强度密码）。
2. 确认安全入口已启用，且不要写进公开文档/群聊。
3. 配置面板 SSL（自签或 ACME 证书），关闭 http 明文访问。
4. 设 IP 白名单或至少开启登录失败锁定。
5. 开启 MFA（两步验证），同时把恢复码离线保存。
6. 配置备份账号（本地 + 至少一处异地），立刻跑一次快照。
7. 在「设置 → 面板设置」里记录当前端口、用户名，写入 CMDB。

5.2 配置项与对应命令行兜底

5.3 反向代理面板的注意事项

把面板放在 Nginx / OpenResty 反代后面时，终端、日志、文件下载都依赖 WebSocket：

location / {
    proxy_pass https://127.0.0.1:<面板端口>;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 3600s;      # 在线终端长连接
    client_max_body_size 1024m;    # 文件上传/备份导入
}

坑：安全入口是路径前缀，反代时不要把 /<安全入口> 重写掉。缺 Upgrade 头会导致"面板能登录，但终端黑屏、容器日志不刷新"。

6. 容器管理

面板的「容器」页是 Docker API 的一层封装，命令行与面板等价。排障时优先用原生 docker 命令，信息更全。

6.1 状态盘点

docker ps -a --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}'
docker stats --no-stream --format 'table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}'
docker system df -v
docker info | grep -E 'Docker Root Dir|Storage Driver|Cgroup'

面板里对应的四个视图：容器 / 镜像 / 网络 / 存储卷 / Compose 编排（模板）。

6.2 容器生命周期

docker start|stop|restart <container>
docker logs -f --tail=200 <container>
docker exec -it <container> sh          # Alpine 系没有 bash
docker inspect <container> | jq '.[0].State, .[0].HostConfig.RestartPolicy'
docker update --restart=unless-stopped <container>

面板里点「重建」会按当前 Compose 定义删除并新建容器，匿名卷里的数据会丢。确认数据挂在 $PANEL_DIR/apps/... 的具名目录再点。

6.3 镜像操作与国内拉取

docker pull <image>
docker images --digests
docker image prune -a --filter "until=720h"
docker save <image> | gzip > /tmp/image.tgz
docker load -i /tmp/image.tgz

国内环境最常见的失败就是 docker pull 超时。检查与配置：

cat /etc/docker/daemon.json

{
  "registry-mirrors": ["https://<你的专属ID>.mirror.aliyuncs.com"],
  "log-driver": "json-file",
  "log-opts": { "max-size": "100m", "max-file": "3" }
}

systemctl daemon-reload && systemctl restart docker
curl -I --connect-timeout 5 https://<加速地址>/v2/    # 200 或 401 都算通

坑（2026 年现状）：绝大多数高校/公益 Docker Hub 公共加速地址已经关停或限制匿名访问，别再把一堆公开域名写进 registry-mirrors 当"多多益善"——Docker 会按顺序串行尝试，一个超时的源能把每次 pull 拖慢几十秒。正确做法是只配自己账号的云厂商专属加速器，加 1 个备用。

6.4 网络与端口

docker network ls
docker network inspect <network> | jq '.[0].IPAM.Config, .[0].Containers'
ss -tunlp | grep <宿主端口>

坑：Docker 发布的端口走 DOCKER / DOCKER-FORWARD 链，在 firewalld 的 public zone 里放行端口，对已发布容器不一定生效，反过来在面板防火墙里"关闭端口"也可能挡不住容器端口。v2.3 起 1Panel 重构了防火墙，专门补了「容器端口」这一类规则，配置时看清楚规则对象是"主机端口"还是"容器端口"。

6.5 卷与磁盘

docker volume ls
docker system df -v | grep -A20 "Local Volumes"
du -sh /opt/1panel/apps/* 2>/dev/null | sort -h
du -sh /var/lib/docker/overlay2 2>/dev/null
docker system prune            # 不删卷
docker system prune -a --volumes   # ★ 危险：删无用镜像与卷

红线：docker system prune -a --volumes 会删掉当前没有容器引用的卷。1Panel 应用停机维护时，它的卷正好处于"未引用"状态，一条命令就能把数据库目录删掉。永远不要把它写进面板的计划任务。

7. 应用商店机制

7.1 应用是怎么装上的

「应用商店」本质是飞致云维护的一个 Git 仓库，每个应用一个目录，典型结构：

apps/mysql/
├── metadata.json / app.yaml      # 名称、图标、版本、可填参数
├── docker-compose.yml.tmpl       # 参数渲染模板
├── data.yml / init.sh            # 初始化脚本、默认凭据
└── versions/                    # 各版本适配

安装流程：面板拉商店索引 → 渲染 compose（把端口、密码、版本填进模板）→ 写到 /opt/1panel/apps/<app>/<app>/ → docker compose up -d → 把参数写进面板 DB → 与「网站 / 数据库」模块联动登记。

推论：

• 应用商店源不可达 = 列表打不开或安装卡住。国内可切到官方国内镜像源；完全内网可自建商店仓库，在面板设置里改 URL。
• v2.4 起支持「镜像导入本地上传」，离线环境可先把镜像 docker save 成 tar 再从面板导入。
• 应用的"参数"不是运行时配置，而是渲染 compose 的变量。改参数往往意味着重建容器。

7.2 应用目录与手工干预

cd /opt/1panel/apps/openresty/openresty
ls -la
cat docker-compose.yml
cat .env 2>/dev/null

# 查看面板登记的应用（面板 DB，别直接改）
ls -la /opt/1panel/1panel/db/
sqlite3 /opt/1panel/1panel/db/1Panel.db '.tables' 2>/dev/null

面板 SQLite 库属于内部实现，只读可以，直接 UPDATE 会让面板状态与实际容器不一致。要改就走面板或 API。

7.3 应用升级与版本切换

v2.4 起支持"切换已安装版本"。升级前：

# 1) 面板里对该应用做一次备份（含数据卷）
# 2) 命令行再兜一层
cd /opt/1panel/apps/<app>/<app>
tar czf /root/backup-<app>-$(date +%F).tgz --exclude='*.log' .
docker compose config > /root/compose-<app>-$(date +%F).yml

# 3) 记下当前镜像 tag
docker compose images

升级失败的回退：改回原 tag → docker compose up -d → 若数据目录被新版写过且格式不兼容（MySQL / PostgreSQL 大版本尤其），用备份目录整体还原。

坑：MySQL 8.0 → 8.4、PostgreSQL 16 → 17 这类跨大版本不能靠换镜像 tag 完成，数据目录格式不兼容会直接起不来。应用商店的"切换版本"只适合同一大版本内的补丁升级，跨大版本必须走逻辑备份 → 新实例 → 导入。

7.4 自定义应用 / 本地应用

• 本地应用：上传自己的 docker-compose.yml，面板纳管启停与日志。
• 自定义商店：改商店源到自建 Git 仓库，用同样的目录规范做企业内部应用模板。
• 自定义应用的 compose 里建议显式写 container_name、restart: unless-stopped、具名卷绑定到 /opt/1panel/apps/<name>/data，否则面板的移动/备份功能找不到数据。

8. 网站管理

8.1 与宝塔最大的差异：OpenResty 是容器

站点配置在 $PANEL_DIR/www/，实际由 OpenResty 容器读取。所以：

docker exec -it 1Panel-openresty-XXX nginx -t
docker exec -it 1Panel-openresty-XXX nginx -s reload

容器名带随机后缀时用 docker ps --format '{{.Names}}' | grep -i openresty 找。面板里改配置会自动 reload，命令行只在面板不可用或调试时用；手工改容器内 /etc/nginx 是无效的，容器重建就没了，要改挂载出来的配置目录。

8.2 站点类型与端口

坑（最高频）：反代目标写 http://127.0.0.1:8080，在容器化的 OpenResty 里指向的是它自己，必然 502。正确写法是用宿主机内网 IP（10.x / 172.x），或在 compose 里给 OpenResty 加 extra_hosts: ["host.docker.internal:host-gateway"] 后写 http://host.docker.internal:8080。

8.3 常用配置核查

# 站点配置文件位置
find /opt/1panel/www -maxdepth 3 -name '*.conf' | head -20

# 站点日志
ls -lh /opt/1panel/www/sites/*/log/ 2>/dev/null
tail -f /opt/1panel/www/sites/<site>/log/access.log
tail -f /opt/1panel/www/sites/<site>/log/error.log

# 端口占用
ss -tunlp | grep -E ':80 |:443 '

8.4 SSL 与 WAF

• 证书：面板「网站 → 证书」申请 ACME（支持 DNS-01 泛域名），v2.4 起支持"删除并吊销"，别再手工 rm 证书目录。
• WAF：专业版能力，规则集更新后要确认 OpenResty reload 成功。
• 强制 HTTPS 前先确认 80 端口能通（ACME http-01 校验要用到）。

9. 数据库管理

9.1 容器化业务库

# 进入容器（面板里也有 Web 终端）
docker exec -it 1Panel-mysql-XXX mysql -uroot -p
docker exec -it 1Panel-redis-XXX redis-cli -a '<password>'

# 逻辑备份（比直接拷 data 目录可靠）
docker exec 1Panel-mysql-XXX mysqldump -uroot -p'<pwd>' --all-databases \
  --single-transaction --routines --triggers | gzip > /root/db-$(date +%F).sql.gz

# 恢复
zcat /root/db-2026-11-05.sql.gz | docker exec -i 1Panel-mysql-XXX mysql -uroot -p'<pwd>'

更细的库级运维（复制、PITR、参数调优）见对应数据库手册：MySQL / MariaDB / PostgreSQL / Redis。本手册只管"面板里这个数据库容器怎么活"。

9.2 远程访问与权限

1. 应用安装时会问「是否允许外部访问」，选否则只绑 127.0.0.1。
2. 要开远程：面板里改端口映射 + 数据库账号 host 授权 + 系统防火墙 + 云安全组，四处缺一不可。
3. 生产环境不要把 3306/6379 直接暴露公网，走 SSH 隧道或内网。

# 检查是否真的绑到了 0.0.0.0
docker ps --format '{{.Names}} {{.Ports}}' | grep -E '3306|6379|5432'
ss -tunlp | grep -E ':3306|:6379|:5432'

9.3 密码忘了怎么办

# 面板「数据库 → 连接信息」里能看/改；命令行兜底看 compose 与环境
grep -R 'MYSQL_ROOT_PASSWORD\|POSTGRES_PASSWORD\|requirepass' /opt/1panel/apps/*/*/ 2>/dev/null | head

坑：改 docker-compose.yml 里的密码环境变量不会改掉已初始化的数据卷里的密码。MySQL/PG 只在数据目录为空时读初始密码。正确做法是在面板里用「修改密码」，它会在容器里执行 ALTER USER。

10. 文件、终端与计划任务

10.1 文件管理与权限

面板文件管理器以 root 身份运行，能改任何路径，这也是它最危险的地方。常用命令行对照：

ls -la /opt/1panel/www/sites/<site>/index/
chown -R www:www /opt/1panel/www/sites/<site>/index   # uid 与容器内 nginx 用户对齐
find /opt/1panel -type d -name 'data' -exec du -sh {} \; | sort -h

网站 403 十有八九是权限：宿主机 root:root 700，容器内 www-data 读不到。看 OpenResty 容器里的 uid，再 chown 到对应数字 uid。

10.2 在线终端

依赖 WebSocket（见 5.3）。终端会话在 v2.4 起支持 SSH 会话保留与断线恢复。长时间任务不要靠面板终端，用 tmux + SSH。

10.3 计划任务类型

# 面板任务本质写进了系统 crontab 与面板 DB，排查时都看
crontab -l
ls -la /etc/cron.d/ | grep -i 1panel
journalctl -u cron --since today --no-pager | tail -50

v2.4 起计划任务支持"执行成功告警"，但默认只有失败告警，别把成功通知当成执行凭证。要验证就把任务输出重定向到固定日志并抽查。

11. 备份、快照与迁移

11.1 三种备份不是一回事

坑：快照只能选第三方备份账号（S3 / OSS / COS / WebDAV / SFTP / MinIO 等），不能存"服务器本地磁盘"。理由很直接：机器都没了，本地快照一起没。所以第一次配置就要把第三方账号建好并跑一次完整快照。

11.2 备份账号

面板「设置 → 备份账号」支持：本地磁盘、S3 兼容对象存储（阿里云 OSS、腾讯 COS、MinIO、Cloudflare R2）、WebDAV（可接 Alist）、SFTP、OneDrive 等。

S3 兼容注意项：

• 区分 Virtual Hosted Style 与 Path Style，自建 MinIO 一般要选 Path Style。
• 区域（Region）必填且要和桶所在区域一致，否则报 301/403。
• 用最小权限的 AK/SK，只给目标桶的读写，不要给账号主密钥。

# 手工验证备份账号可达（以 S3 为例，有 awscli 时）
aws --endpoint-url https://<endpoint> s3 ls s3://<bucket>/ --profile 1panel

11.3 快照恢复流程

# 面板可用时：设置 → 快照 → 恢复
# 面板不可用时
1pctl restore

恢复过程会自动对当前数据做一次备份，默认放在 $PANEL_DIR/original_<快照名>/。恢复失败时：

1. 看「面板日志 → 系统日志」定位原因。
2. 可以回滚到恢复前版本。
3. 最坏情况手工把 original_<快照名>/ 里的内容覆盖回 $PANEL_DIR/1panel/，再 1pctl restart all。

版本差异：跨机迁移时快照必须放在新机器对应备份账号的指定目录下（服务器磁盘账号为 /opt/1panel/backup/system_snapshot/），且新机安装目录要与旧机一致。装到了 /data/1panel 就恢复不回去了。

11.4 整机迁移 SOP

# 旧机 1) 冻结写入（停业务或切维护页）
# 旧机 2) 面板内做：快照 + 全站备份 + 全库备份 + 应用备份
# 旧机 3) 命令行补一层
tar czf /root/1panel-apps-$(date +%F).tgz /opt/1panel/apps
tar czf /root/1panel-www-$(date +%F).tgz /opt/1panel/www
cat /etc/docker/daemon.json > /root/daemon.json.bak

# 新机 4) 同版本安装 1Panel，安装目录保持一致
# 新机 5) 配置同一个第三方备份账号，把快照放到指定目录
scp /root/1panel-*.tgz root@<新机>:/root/

# 新机 6) 恢复快照 → 检查站点/应用/证书/计划任务是否回来
1pctl restore
1pctl status

# 新机 7) 逐站验证后再切 DNS（TTL 提前调到 300）
# 旧机 8) 保留 72 小时再下线

迁移别只搬 /opt/1panel/apps。compose 里可能有绝对路径、宿主端口、固定容器网络名，换机后要逐一核对 docker compose config。

12. 防火墙与网络

12.1 面板管的是哪一层

1Panel 的防火墙模块是对 firewalld（RHEL 系）或 ufw（Debian 系）的封装，面板里加的规则会写进系统防火墙。所以：

# RHEL 系
firewall-cmd --list-all
firewall-cmd --list-ports
firewall-cmd --permanent --add-port=8080/tcp && firewall-cmd --reload

# Debian 系
ufw status verbose
ufw allow 8080/tcp

坑：命令行手工加的规则，面板里不一定显示；面板里"关闭"的规则，可能因为 Docker 的 iptables 链仍然存在而继续放行容器端口。判断真实暴露面永远以 ss -tunlp + 外网 nmap 实测为准，别信 UI 上的开关。

12.2 v2.3 / v2.4 防火墙变化

坑：v2.4 的"规则重置"会重写防火墙规则集。在远程 SSH 会话里点之前，先确认 SSH 端口在放行列表，否则重置完成之时就是失联之时。v2.4 的"启动恢复"能救回一次，但前提是规则备份存在。

12.3 端口放行四层检查

# 1) 进程有没有监听
ss -tunlp | grep <port>
# 2) 系统防火墙
firewall-cmd --list-ports ; ufw status
# 3) Docker 发布的端口
docker ps --format '{{.Names}} {{.Ports}}'
# 4) 云安全组（控制台，命令行查不到）
# 外部实测
nmap -Pn -p <port> <公网IP>

13. 监控、日志与告警

13.1 监控能力

命令行兜底（面板挂了照样看）：

top -bn1 | head -20
free -m
df -h
iostat -x 1 3
docker stats --no-stream
nvidia-smi            # NVIDIA
npu-smi info          # 昇腾

13.2 日志位置

# 磁盘被日志撑满时定位
du -sh /var/lib/docker/containers/*/*-json.log 2>/dev/null | sort -h | tail
du -sh /opt/1panel/log /opt/1panel/www/sites/*/log 2>/dev/null | sort -h

13.3 告警

v2.3 起支持自定义 Webhook，可对接企业微信 / 钉钉 / 飞书 / 自建告警平台。配置要点：

• Webhook 用内网可达地址，面板要能出网（或走代理）。
• 告警项至少覆盖：磁盘使用率、CPU 持续高、内存、面板登录失败、计划任务失败、证书到期。
• 告警通道本身要做心跳测试，否则"没告警"可能只是通道挂了。

14. 证书与域名

# 查看面板签发的证书目录
find /opt/1panel -maxdepth 5 -type d -iname '*ssl*' -o -iname '*cert*' | head

# 校验证书链与有效期
openssl x509 -in /path/to/fullchain.pem -noout -dates -subject -issuer
curl -vI https://<domain> 2>&1 | grep -A5 'SSL connection'

ACME 要点：

v2.4 之前"删除证书"只是删本地文件，证书仍在 CA 那边有效；v2.4 起支持删除并吊销。私钥泄露时用吊销，不要只删文件。

15. 升级、降级与回滚

15.1 在线升级

面板右下角「检查更新」→ 升级。命令行等价动作（升级失败时用）：

1pctl status
# 官方升级脚本（以实际版本发布页为准）
curl -sSL https://resource.fit2cloud.com/1panel/package/quick_start.sh -o /tmp/quick_start.sh
bash /tmp/quick_start.sh

坑：重复跑 quick_start.sh 在部分版本会走"安装"逻辑而非"升级"，可能重置配置。优先用面板内升级，脚本只作为面板不可用时的备选，且必须先做快照。

15.2 升级前清单

# 1) 快照（第三方账号）
# 2) 记录版本与容器清单
1pctl version > /root/pre-upgrade.txt
docker ps -a --format '{{.Names}} {{.Image}} {{.Status}}' >> /root/pre-upgrade.txt
docker compose ls >> /root/pre-upgrade.txt
cp /etc/docker/daemon.json /root/daemon.json.pre-upgrade
# 3) 磁盘余量
df -h /opt /var/lib/docker

15.3 版本事实与安全提醒

• v2.4.1 修复 CVE-2026-111943（Go crypto/x509），属建议尽快升级的安全版本。
• 2026-10 PHP 运行环境曝出两个 CVSS 9.2 的 RCE（CVE-2026-109618 / 109619），1Panel 已升级对应运行环境版本，但已有站点需要手动切换 PHP 版本，光升面板不解决问题。这一点极容易漏。

15.4 回滚现实

16. 多机管理与 Core / Agent

v2 把面板拆成 Core（UI / API / DB）与 Agent（在被管节点执行），支持多机集中管理。

# 主控机
systemctl status 1panel-core 1panel-agent
1pctl status

# 被管节点（只跑 Agent）
systemctl status 1panel-agent
journalctl -u 1panel-agent -f
ss -tunlp | grep <agent端口>

接入检查：

1. 主控能连通被管节点的 Agent 端口（默认高位端口，安装时指定）。
2. 两侧时间同步（chronyc sources / timedatectl），证书校验对时间敏感，偏差大会握手失败。
3. Agent 与 Core 版本要一致或兼容，跨大版本混用会出现菜单能开、操作失败。
4. 内网 DNS 能解析节点主机名，或直接用 IP 接入。

坑：主控机自己也有 Agent。1pctl stop agent 会让主控在本机列表里显示离线，并导致网站、容器、计划任务等本机操作全部失败，但 UI 还能登录——看起来"面板正常但什么都点不动"，就是这个原因。

17. 高级能力与扩展

这些能力会让面板持有更多的凭据（云 AK、模型 API Key、License）。把它们写进密钥管理，不要散落在 compose 环境变量里；审计时这些文件是重点。

18. 卸载与残留清理

18.1 标准卸载

1pctl uninstall

卸载过程会询问是否保留数据。默认/建议保留，尤其网站和数据库目录。卸载只移除面板本体，不自动删除 Docker 应用容器与数据卷。

18.2 卸载前必须带走的东西

# 1) 面板凭据与快照
1pctl user-info > /root/1panel-userinfo.txt
# 面板内导出快照 / 全站备份 / 全库备份

# 2) 应用清单（重建时照着来）
docker ps -a --format '{{.Names}}\t{{.Image}}\t{{.Ports}}' > /root/1panel-containers.txt
find /opt/1panel/apps -name docker-compose.yml > /root/1panel-compose-list.txt

# 3) 全量打包
tar czf /root/1panel-final-$(date +%F).tgz /opt/1panel
cp /etc/docker/daemon.json /root/daemon.json.bak

18.3 彻底清理（确认不要任何数据时）

# ★ 下面每一步都不可逆，逐条确认后再执行
1pctl uninstall

# 停掉并删除 1Panel 纳管的 Compose 项目（会停业务！）
cd /opt/1panel/apps/<app>/<app> && docker compose down -v   # -v 删卷，★危险

# 移除面板文件
systemctl stop 1panel-core 1panel-agent 2>/dev/null
systemctl disable 1panel-core 1panel-agent 2>/dev/null
rm -f /usr/local/bin/1panel /usr/local/bin/1pctl /usr/local/bin/1panel-agent
rm -f /etc/systemd/system/1panel-core.service /etc/systemd/system/1panel-agent.service
rm -f /etc/systemd/system/1panel.service
systemctl daemon-reload

# 移除数据目录（★确认已备份）
# rm -rf /opt/1panel

# 清理计划任务与防火墙规则
crontab -l | grep -i 1panel
firewall-cmd --list-all
ufw status

18.4 卸载后残留验证

systemctl list-units --all | grep -i 1panel
ls -la /usr/local/bin/ | grep -i 1panel
ls -la /opt/ | grep -i 1panel
crontab -l | grep -i 1panel
docker ps -a --format '{{.Names}}' | grep -i 1panel
ss -tunlp | grep <原面板端口>

坑：如果还要继续用这台机器跑网站，不要删 /opt/1panel/apps 和 /www，也不要执行 docker compose down -v。很多人把"卸载面板"理解成"清空服务器"，结果把业务数据一起清了。

19. 故障速查

19.1 五分钟定位脚本

#!/usr/bin/env bash
echo "===== 版本 ====="; 1pctl version
echo "===== 服务 ====="; 1pctl status
echo "===== 磁盘 ====="; df -h / /opt /var/lib/docker 2>/dev/null
echo "===== 内存 ====="; free -h
echo "===== 容器异常 ====="; docker ps -a --filter 'status=exited' --format '{{.Names}} {{.Status}}'
echo "===== 监听 ====="; ss -tunlp | grep -E ':80 |:443 |:3306|:6379'
echo "===== Docker 空间 ====="; docker system df
echo "===== 面板错误 ====="; journalctl -u 1panel-core --since '1 hour ago' --no-pager | grep -iE 'error|panic|fatal' | tail -20
echo "===== 大日志 ====="; du -sh /var/lib/docker/containers/*/*-json.log 2>/dev/null | sort -h | tail -5

20. 安全基线与危险操作红线

20.1 基线清单

• 面板端口非默认/高位，且仅对管理网段开放（云安全组 + 系统防火墙双层）
• 安全入口启用，未写入公开文档
• HTTPS 强制，禁用弱 TLS 版本
• MFA 开启，恢复码离线保存
• 登录失败锁定 + IP 白名单
• 第三方备份账号配置完成，快照可恢复演练通过
• 数据库容器不暴露公网，root 强密码
• Docker 日志 max-size / max-file 已限制
• daemon.json 中加速器为自有账号专属地址
• 操作审计日志保留 ≥ 180 天
• 面板与业务应用定期升级（含 PHP / Node.js 运行环境）
• 不用面板的在线终端跑长期任务，用 SSH + tmux 留审计

20.2 危险命令红线

20.3 面板权限的本质

面板以 root 运行，Web 端文件管理、终端、脚本任务都是 root 权限。面板账号泄露 = 服务器 root 泄露。因此：

1. 面板不要开在公网可任意访问的地址上。
2. 生产环境优先用跳板机 / VPN / 云堡垒机访问。
3. 多用户场景只用专业版/企业版的细粒度授权，别共享 admin。

21. 附录

21.1 命令速查

21.2 端口速查

21.3 与其他手册的配合

维护建议：面板类工具的菜单路径、默认端口、专业版功能边界随版本变化最快，本文的 Web UI 描述以 v2.4.x 为准。落地时把安装目录、面板端口、Agent 端口、备份账号、快照保留策略替换成团队实际值，沉淀为内部 SOP；所有恢复类操作先在测试机演练一次。