项目介绍
1Panel 提供 Linux 主机、应用、网站和备份管理界面。下文提供一键安装命令与 Compose 配置,分别说明官方 Linux 安装和群晖容器部署。两套方案运行环境不同,选择其中一套按完整步骤操作。
一键脚本
curl -sSL https://resource.fit2cloud.com/1panel/package/quick_start.sh -o quick_start.sh && sudo bash quick_start.shcompose项目安装文件
services:
1panel:
image: koryking/1panel:latest
container_name: 1panel
ports:
- 30010:10086
volumes:
- /vol1/1000/Docker/1panel:/opt/1panel
- /vol1/1000/:/vol1/1000/
- /var/run/docker.sock:/var/run/docker.sock
environment:
- TZ=Asia/Shanghai
- PANEL_BASE_DIR=/opt/1panel
- PANEL_PORT=10086
- PANEL_ENTRANCE=123456
- PANEL_USERNAME=admin
- PANEL_PASSWORD=请设置自己的密码
network_mode: bridge
restart: always补充:部署与使用
安装前选择方案
使用环境 | 安装方式 | 本文入口 |
|---|---|---|
独立 Linux 服务器或 Linux 虚拟机 | 官方 V2 一键安装 | 方案一 |
群晖 DSM,使用 Container Manager | 第三方容器封装 | 方案二 |
官方在线安装支持基于 Debian、Red Hat 等主流 Linux 发行版,建议可用内存超过 1GB,并能访问互联网。安装脚本会按架构选择安装包。DSM 的系统与服务管理方式不同,群晖本机使用下面的容器方案;也可以在群晖虚拟机中安装受支持的 Linux,再执行官方脚本。
方案一:官方 Linux 一键安装
1. 登录主机,准备安装工具
通过 SSH 登录准备安装的 Linux 主机。Ubuntu / Debian 如果缺少 curl,先执行:
sudo apt-get update
sudo apt-get install -y curl ca-certificates
切换到 root,再执行官方当前 V2 交互式安装命令:
sudo -i
bash -c "$(curl -sSL https://resource.fit2cloud.com/1panel/package/v2/quick_start.sh)"
脚本默认选择 stable 通道,根据终端提示完成安装。这里使用的是国内版官方地址;无需另外查找旧版安装包。
如果希望先把脚本保存到本地,可以使用下面两条代替上一条一键命令,两种方式选一种即可:
curl -fSL https://resource.fit2cloud.com/1panel/package/v2/quick_start.sh -o quick_start.sh
bash quick_start.sh
2. 按提示填写安装参数
安装目录:普通 Linux 主机可使用默认
/opt,后续应用和备份目录要结合磁盘空间规划。Docker:没有 Docker 时,按交互提示安装;已安装时先核对现有容器与配置。
面板端口:选择未占用端口,并记下实际值。已有网站占用 80/443 不代表面板也必须使用这些端口。
安全入口:是访问地址末尾的路径,登录时不能省略。
管理员账号与密码:使用自己的账号信息,安装完成后保存到本机密码管理工具。
官方当前说明中,用户名和安全入口支持 3–30 位字母、数字与下划线;密码支持 8–30 位字母、数字及文档列出的特殊字符。按安装界面的校验提示填写即可。
3. 打开面板与核对状态
安装结束后终端会输出实际访问地址,格式为:
http://服务器IP:面板端口/安全入口
云服务器同时在云安全组开放面板端口;主机有防火墙时,也需要放行该端口。端口与安全入口以自己的安装输出为准。
忘记入口或想检查安装结果时,在 Linux 主机终端执行:
1pctl version
1pctl status
1pctl user-info
user-info 会显示当前面板访问信息,只在自己的终端查看。V2 可以进一步分别检查服务:
1pctl status core
1pctl status agent
方案二:群晖 Container Manager 部署
1. 镜像与目录说明
这里使用 koryking/1panel:latest。它是第三方容器封装,latest 指该维护者的标签,不等于官方当前 V2 版本。该镜像说明支持 PANEL_BASE_DIR、面板端口及初始化账号设置,适合与官方 Linux 主机安装分开使用。
这类容器会通过 Docker socket 连接 NAS 的 Docker 引擎,面板内创建的应用实际上运行在 NAS 上。应用安装目录必须在容器内外保持同一路径,否则容易出现“面板里有文件,应用却找不到目录”。
本例统一使用 /volume1/docker/1panel,面板端口为 30010,管理员名为 admin。密码和安全入口由准备命令生成,不使用个人参考文件里的登录信息。
2. 一次创建目录和初始化配置
在群晖 SSH 终端粘贴执行:
sudo sh <<'ONEPANEL_PREPARE'
set -eu
mkdir -p /volume1/docker/1panel
cd /volume1/docker/1panel
umask 077
touch .env
if ! grep -q '^PANEL_ENTRANCE=.' .env; then
generated_entrance=$(openssl rand -hex 6)
printf 'PANEL_ENTRANCE=%s\n' "$generated_entrance" >> .env
fi
if ! grep -q '^PANEL_PASSWORD=.' .env; then
generated_password=$(openssl rand -hex 12)
printf 'PANEL_PASSWORD=%s\n' "$generated_password" >> .env
fi
chmod 600 .env
ONEPANEL_PREPARE
cd /volume1/docker/1panel
重复执行会保留已有非空值。该命令只准备目录和初始化文件;接着保存下面的 Compose。
3. 完整 Compose
在 /volume1/docker/1panel/compose.yaml 保存:
services:
panel:
image: koryking/1panel:latest
container_name: 1panel
network_mode: host
restart: unless-stopped
environment:
TZ: Asia/Shanghai
PANEL_BASE_DIR: /volume1/docker/1panel
PANEL_PORT: "30010"
PANEL_ENTRANCE: "${PANEL_ENTRANCE}"
PANEL_USERNAME: admin
PANEL_PASSWORD: "${PANEL_PASSWORD}"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- /volume1/docker/1panel:/volume1/docker/1panel
这里按镜像维护者示例采用 host 网络,因此不再写 ports。PANEL_BASE_DIR 与挂载路径的左右两侧保持一致;不需要填写 UID/GID,也没有给这个方案额外添加特权模式。
4. 启动并访问
使用 SSH 时,在项目目录执行:
cd /volume1/docker/1panel
sudo docker compose config --quiet
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=100 panel
使用 Container Manager 时,新建项目,项目路径选择 /volume1/docker/1panel,导入该目录的 compose.yaml。确保 .env 也在同一项目目录,再构建启动。
在自己的 SSH 终端查看初始化信息:
sudo cat /volume1/docker/1panel/.env
访问地址为 http://群晖IP:30010/ 后接 PANEL_ENTRANCE 的值;用户名 admin,密码使用 PANEL_PASSWORD 的值。端口已占用时,修改 Compose 中的 PANEL_PORT,重建后使用新端口访问。
这两个环境变量用于首次初始化。已有面板数据时,修改 .env 不一定会重置账号或入口,应通过面板设置修改;不要删除已有数据目录来尝试恢复登录。
常用管理命令
官方 Linux 主机安装
以下命令在安装 1Panel 的 Linux 主机执行;普通账号使用时按需加 sudo:
1pctl help # 查看命令帮助
1pctl status # 检查状态
1pctl start # 启动服务
1pctl stop # 停止服务
1pctl restart # 重启服务
1pctl version # 查看版本
1pctl user-info # 查看访问与用户信息
1pctl update username # 修改面板用户名
1pctl update 请设置自己的密码 # 修改面板密码
1pctl update port # 修改面板端口
修改端口后,安全组、防火墙和反向代理也要使用新端口。更新版本从面板中的“检查更新”操作;1pctl update 是修改账号、密码等系统信息,不是升级版本的命令。
群晖 Compose 安装
在群晖项目目录操作容器:
cd /volume1/docker/1panel
sudo docker compose ps
sudo docker compose logs --tail=100 panel
sudo docker compose restart panel
sudo docker compose stop panel
sudo docker compose start panel
docker compose restart 重启现有容器;修改 Compose 环境变量后应执行 sudo docker compose up -d 重建,使新配置生效。
首次使用:完成一个应用部署
登录后检查主机和容器列表,确认面板连接的是预期设备。第三方容器中的系统监控、服务管理和文件视图可能与 NAS 本机不同。
在应用商店选择一个简单测试应用,检查它将使用的端口、数据库及数据目录。
群晖方案把应用数据放在
/volume1/docker/1panel对应的安装范围,核对生成的 Compose 中是否仍是这个绝对路径。安装后先在局域网打开应用页面,再检查容器日志,确认文件能保存、重启后仍存在。
配置一个备份任务并手动运行,核对备份文件、保存位置和保留数量,随后验证测试应用能恢复。
确定一个项目由哪个面板维护。不要让 1Panel 与 Container Manager 分别保存不同版本的同一份 Compose,否则后一次操作可能覆盖前一次设置。
常见问题与排查命令
安装脚本下载失败
先检查目标 Linux 主机的 DNS、校时、证书和外网连接。可以只测试官方脚本地址能否访问,不执行安装:
curl -I https://resource.fit2cloud.com/1panel/package/v2/quick_start.sh
如果需要代理,在本机按实际配置代理后重试;不要把别人内网的代理地址照抄进脚本。
面板打不开,或打开后是 404
先核对协议、主机地址、面板端口和安全入口。端口能连通但返回 404,常见原因是缺少入口路径;连接超时再检查端口、防火墙和网络。
官方安装使用 1pctl status 与 1pctl user-info 检查;群晖安装使用 docker compose ps、日志以及自己的 .env 检查。两种安装方式的管理入口不要混用。
群晖面板能打开,但安装应用失败
先看应用容器日志与生成的绑定目录,确认 PANEL_BASE_DIR 和容器内外路径一致。下载镜像失败时检查的是 NAS 的 Docker 引擎网络与镜像配置,单独给面板容器设置代理不一定能解决引擎拉取问题。
不知道哪些文件需要备份
面板设置、应用部署定义、数据库和上传文件分别核对。群晖方案保存 /volume1/docker/1panel 与各应用实际数据;如果应用另外使用 Docker 命名卷,也要备份相应卷。备份恢复后分别验证账号、应用页面、数据库和附件。
更新与备份
官方主机安装从面板检查更新,升级前保存面板和应用备份。第三方镜像的更新由其维护者提供,不能直接将现有数据当成可与官方 V2 互换。
群晖容器更新前,停止可能写入的任务,完成一致性备份,再在项目目录执行:
sudo docker compose pull
sudo docker compose up -d
sudo docker compose logs --tail=100 panel
更新后核对面板登录、已有应用、数据目录和备份任务。不要把删除卷、清空安装目录作为日常升级步骤。