🚀 使用 Docker Compose 部署 1Panel（Linux 可视化管理面板）

🚀 使用 Docker Compose 部署 1Panel

本文是一篇关于使用 Docker Compose 部署 1Panel 的详尽教程，旨在帮助您，特别是新手用户，轻松掌握这款现代化、开源的 Linux 服务器运维管理面板的部署和使用。

📝 项目简介

1Panel 是一个现代化、开源的 Linux 服务器运维管理面板。它通过 Web 图形界面，让用户能够轻松管理 Linux 服务器，实现主机监控、文件管理、数据库管理、容器管理等功能。1Panel 深度集成开源建站软件 WordPress 和 Halo，可以一键搞定域名绑定、SSL 证书配置等操作。其目标是降低运维复杂度，让开发者在自托管场景下快速上手。

核心特点：

• 高效管理：通过网页图形界面轻松管理 Linux 服务器，涵盖应用管理、数据库管理、容器编排等核心运维场景。
• 快速建站：深度集成主流建站工具如 WordPress 和 Halo，支持域名绑定与 SSL 证书配置。
• 丰富的应用商店：精选上架各类高质量的开源工具和应用软件（截至2025年3月已形成包含150余款应用的软件生态），协助用户轻松安装并升级。
• 安全可靠：基于容器管理并部署应用，实现最小的漏洞暴露面，同时提供防火墙和日志审计等功能。内置安全审计模块，保障服务器操作安全。
• 一键备份：支持一键备份和恢复，用户可以将数据备份到各类云端存储介质（支持阿里云 OSS、AWS S3 等主流云存储协议），永不丢失。

🔧 部署前准备

在开始部署之前，请确保您的环境满足以下要求，并完成必要的准备工作。

系统环境要求

• 操作系统：支持多种 Linux 发行版（如 Debian、RedHat 及国产操作系统）。
• Docker 引擎：确保已安装并启动 Docker 服务。
• Docker Compose：确保已安装 Docker Compose。
• 硬件架构：支持 x86_64, aarch64, armv7l, ppc64le 等多种硬件平台。
• 防火墙端口：确保计划使用的 10086 端口（或您自定义的端口）在防火墙中是放行的。

环境检查

1.检查 Docker 服务状态：

    systemctl status docker

确保 Docker 服务处于 active (running) 状态。

2.检查 Docker Compose 版本：

    docker compose version

确认版本符合要求。

创建部署目录

建议创建一个独立的目录来管理您的 1Panel 部署文件和数据，例如：

mkdir -p /home/compose/1panel && cd /home/compose/1panel

此目录将作为您的工作目录，后续的 docker-compose.yml 文件将放置于此。

⚙️ 配置 Docker Compose

接下来，我们需要创建 Docker Compose 配置文件。根据您提供的配置，以下是一个详细的解释和说明。

配置文件详解

在您的工作目录（例如 /home/compose/1panel）下，创建一个名为 docker-compose.yml 的文件，内容如下：

services:
  1panel:
    image: moelin/1panel:latest  # 1Panel 官方最新镜像（自动更新功能）
    environment:
      - TZ=Asia/Shanghai  # 时区设置（确保面板时间与本地一致，避免日志时间错乱）
    labels:
      createdBy: Apps  # 容器标签，用于识别面板容器
    container_name: 1panel  # 容器名称，便于管理（如停止/查看日志）
    restart: always  # 容器退出后自动重启（保障面板服务稳定）
    network_mode: host  # 关键！使用宿主机网络，无需端口映射，直接用宿主机 10086 端口
    volumes:
      # 1. Docker 管理依赖：挂载宿主机 Docker 守护进程，让 1Panel 控制 Docker
      - /var/run/docker.sock:/var/run/docker.sock
      # 2. 1Panel 核心配置目录：存储面板设置、用户数据
      - ./root:/root # 冒号前面映射新建root子文件夹路径
      # 3. Docker 数据卷目录：管理所有容器的持久化数据卷
      - ./volumes:/var/lib/docker/volumes # 冒号前面映射新建volumes子文件夹路径
      # 4. 宿主机 /opt 目录映射：便于 1Panel 管理 /opt 下的应用
      - ./opt:/opt # 冒号前面映射新建opt子文件夹路径
      # 5. Docker 配置目录映射：修改 Docker 全局配置（如镜像源）
      - ./docker:/etc/docker # 冒号前面映射新建docker子文件夹路径

      # 以下是用户自定义的挂载点，例如挂载现有的文档或项目目录：
      #- /home/compose/Docsify/docs:/docs1 # 脚本用的，也可以容器内执行丢给定时任务。
      # 6. 自定义挂载：Obsidian 仓库目录（面板中可直接管理 Obsidian 笔记）
      - '/home/compose/obsidian/obdocker/Obsidian Vault:/1/ob'
      # 7. 自定义挂载：MkDocs 文档目录（面板中管理 MkDocs 文档）
      - /home/compose/mkdocs/docs/my-project/docs:/1/mkdocs
      # 8. 自定义挂载：Docsify 文档目录（面板中管理 Docsify 文档）
      - /home/compose/Docsify/docs:/1/Docsify

#默认端口：10086
#默认账户：1panel
#默认密码：1panel_password
#默认入口：entrance

关键配置说明

1. 网络模式 (network_mode: host): 使用 host 网络模式意味着容器不会拥有自己独立的网络命名空间，而是直接使用宿主机的网络。这使得容器内应用（1Panel）可以直接使用宿主机的 IP 地址和端口，无需进行复杂的端口映射。因此，在 ports 部分不需要配置 10086:10086 这样的映射。您可以直接通过 http://<服务器IP>:10086 访问 1Panel。

2. 数据持久化 (volumes):

   • ./root:/root, ./volumes:/var/lib/docker/volumes, ./opt:/opt, ./docker:/etc/docker 这些挂载确保了 1Panel 的配置、数据和管理的 Docker 相关配置在容器重启后不会丢失。它们被保存在您当前目录下的相应子文件夹中。
   • 其余挂载（如到 /1/ob, /1/mkdocs 等）是自定义数据卷，用于将服务器上已有的目录（如 Obsidian 库、MkDocs 文档、Docsify 文档）挂载到 1Panel 容器内部，方便在 1Panel 中直接管理和使用这些资源。

3. 镜像选择 (image: moelin/1panel:latest): 此配置使用的是社区维护的 moelin/1panel 镜像。如果您希望使用官方镜像或其他特定版本的镜像，可以修改此字段。例如，有社区教程使用了 koryking/1panel:latest 镜像。

4. 环境变量 (environment):

   • TZ=Asia/Shanghai: 设置容器内的时区，这对于日志时间戳、计划任务等至关重要。请根据您服务器的实际地理位置进行调整。

关于应用安装路径的说明

有社区教程指出，在使用 Docker 部署 1Panel 时，需要注意 PANEL_BASE_DIR 环境变量的设置，它定义了 1Panel 应用商店中安装的应用的默认路径。在您提供的 Compose 文件中，通过 - ./opt:/opt 这一挂载，将容器内的 /opt 目录（1Panel 默认的应用安装目录之一）映射到了当前目录下的 ./opt 文件夹。如果您希望明确指定应用安装目录，可以参考社区做法，在 environment 部分添加 PANEL_BASE_DIR 环境变量，并确保其值与挂载的宿主机路径一致。例如：

environment:
  - TZ=Asia/Shanghai
  - PANEL_BASE_DIR=/your/custom/path/opt  # 此路径需与 volumes 中挂载的宿主机路径对应

同时，在 volumes 中也需要有相应的挂载：

volumes:
  - /your/custom/path/opt:/your/custom/path/opt

🚀 启动与验证

配置完成后，就可以启动 1Panel 服务了。

启动服务

在包含 docker-compose.yml 文件的目录下，执行以下命令来启动服务：

docker compose up -d

参数 -d 表示在后台运行容器。

验证服务状态

1. 检查容器状态： 执行 docker ps 命令，查看名为 1panel 的容器状态是否为 Up。

2. 查看服务日志（可选）： 如果无法访问，可以通过 docker compose logs 或 docker logs 1panel 查看容器日志以排查问题。

3. 访问 1Panel 管理界面：

   • 在浏览器中输入 http://您的服务器IP地址:10086。
   • 使用默认账户（1panel）和默认密码（1panel_password）登录。
   • 首次登录，系统可能会要求您设置一个安全入口（默认通常是 entrance），请按照页面提示操作。

重要安全提示：登录后，强烈建议您立即在 1Panel 的管理界面中修改默认的登录密码和安全入口，以增强安全性。

🔌 基础配置与使用

成功登录 1Panel 后，您将看到一个直观的 Web 管理界面。

初始界面浏览

• 仪表盘 (Dashboard)：通常展示系统的基础信息，如 CPU、内存、磁盘使用率、系统版本等。
• 主机监控：提供服务器资源使用的监控信息。
• 应用商店：在这里可以一键部署各类开源工具和应用软件。
• 网站：用于管理网站，支持反向代理和静态网站部署，可以轻松进行域名绑定和 SSL 证书配置。
• 数据库：支持数据库的创建和管理。
• 容器：可以查看和管理当前服务器上的 Docker 容器，并通过编排部署 Docker Compose 项目。

通过 Docker Compose 部署应用

1Panel 的一个强大功能是支持通过 Docker Compose 部署应用，这大大扩展了其部署灵活性。

1. 进入容器编排：在 1Panel 侧边栏找到并进入 "容器" 或 "编排" 模块。
2. 创建编排：点击 "创建编排" 按钮。
3. 编辑 Compose 文件：您可以直接在 1Panel 的 Web 编辑器中粘贴您的 docker-compose.yml 文件内容，或者选择服务器上已存在的 Compose 文件。
4. 部署与应用：保存后，1Panel 会根据 Compose 文件创建并启动服务。您可以在编排详情页面管理这些服务（启动、停止、查看日志等）。

创建反向代理网站

如果您希望通过域名访问部署在 1Panel 上的应用（例如您之前部署的 Halo 或其他 Web 服务），可以使用 1Panel 的反向代理功能。

1. 进入网站管理：在侧边栏找到 "网站" 并进入。
2. 创建网站：点击 "创建网站"，网站类型选择 "反向代理"。
3. 配置代理：
   • 域名：填写您已解析到当前服务器 IP 的域名。
   • 代理地址：填写您容器化应用的实际访问地址，例如 http://127.0.0.1:应用容器端口。
4. SSL 证书：1Panel 支持快速为域名申请并配置 SSL 证书，实现 HTTPS 访问，让网站更安全。

🛠️ 维护与管理

日常维护

• 服务启停：您可以直接在 1Panel 的容器管理界面中重启或停止 1Panel 自身的容器。或者，在 1Panel 的部署目录下使用 Docker Compose 命令：

    docker compose restart  # 重启服务
    docker compose down     # 停止并移除容器（数据在 volumes 中，不会丢失）
    docker compose up -d    # 再次启动服务

• 数据备份：1Panel 支持一键备份功能。您可以定期将 1Panel 的配置和数据（通常存储在您 Compose 文件挂载的 root, volumes, opt 等目录）备份到云端存储（如阿里云 OSS、AWS S3 等）。同时，也建议对服务器上重要的自定义数据卷（如 Obsidian 库、MkDocs 文档）进行定期备份。

监控与日志

• 资源监控：利用 1Panel 的主机监控功能，密切关注服务器 CPU、内存、磁盘和网络的使用情况。
• 日志查看：1Panel 提供日志审计功能。您可以在相应的功能模块（如网站、容器、系统）中查看详细的运行日志，这对于排查问题非常有帮助。

🐛 常见问题排查

在使用过程中，可能会遇到一些问题，以下是一些常见问题的排查思路：

1. 无法通过浏览器访问 1Panel

   • 检查防火墙：确认服务器安全组和防火墙是否放行了 10086 端口。
   • 检查容器状态：使用 docker ps 确认 1Panel 容器是否正常运行。如果状态异常，使用 docker logs 1panel 查看错误日志。
   • 确认端口占用：检查宿主机 10086 端口是否被其他进程占用。

2. 1Panel 中无法管理 Docker 或部署应用失败

   • 检查 Docker Socket 挂载：确保 Compose 文件中的 /var/run/docker.sock:/var/run/docker.sock 挂载正确无误。这是 1Panel 管理 Docker 的基础。
   • 查看容器日志：在 1Panel 的容器管理界面或通过 docker logs 命令查看具体应用的错误信息。

3. Web 终端连接失败

   • 如果 1Panel 的 Web 终端功能出现连接已断开的错误，可以参考社区经验，检查以下方面：
   • SSH 服务状态：在宿主机上执行 systemctl status sshd，确保 SSH 服务正在运行。
   • SSH 配置：检查 /etc/ssh/sshd_config 文件，确保包含 PermitRootLogin yes 和 PasswordAuthentication yes，修改后需重启 SSH 服务 (systemctl restart sshd)。
   • 重新配置主机连接：尝试在 1Panel 的"主机"管理界面中，重新添加或检查主机连接信息。

4. 应用商店安装应用失败或路径错误

   • 如果您通过 1Panel 的应用商店安装应用时遇到路径相关问题，请回顾本教程"关于应用安装路径的说明"部分，检查 PANEL_BASE_DIR 环境变量与卷挂载路径是否配置正确且一致。

5. 日志追踪功能异常

   • 在较早的 1Panel 版本中，曾有用户报告在查看运行环境日志时启用"追踪"功能后，即使关闭界面，系统仍会持续向服务器发送日志请求。这通常是由前端组件资源未正确释放引起的。如果遇到此类问题，考虑将 1Panel 升级到最新版本，此类问题通常会在后续版本中得到修复。

---

希望这篇教程能帮助您顺利完成 1Panel 的部署和使用。作为一款功能全面且不断发展的开源面板，1Panel 能显著提升您的服务器运维效率。如果在使用中遇到更复杂的问题，可以参考 1Panel 的官方文档或在社区寻求帮助。