xindaowei/1panel

docker-1panel-v2

在Docker容器中运行1Panel V2（通过DooD方式），支持OpenWRT/iStoreOS环境。

⚙️ 工作原理

1. 模拟systemctl：在容器内部增加模拟的systemctl脚本，模拟系统服务管理，满足1Panel对systemctl的依赖。
2. 魔改官方安装脚本：修改1Panel官方安装脚本，使其适应容器环境。
3. DooD模式(Docker-out-of-Docker)：通过挂载宿主机的/var/run/docker.sock到容器内部，使容器内的1Panel能直接访问和管理宿主机上的Docker守护进程及容器。

❤️ 特别感谢

• https://github.com/dph5199278/docker-1panel%EF%BC%9A%E6%8F%90%E4%BE%9B%E5%9C%A8Docker%E5%AE%B9%E5%99%A8%E4%B8%AD%E8%BF%90%E8%A1%8C1Panel%E7%9A%84%E5%88%9D%E6%AD%A5%E6%80%9D%E8%B7%AF%E4%B8%8E%E5%AE%89%E8%A3%85%E6%96%B9%E5%BC%8F%E3%80%82
• https://github.com/Xeath/1panel-in-docker%EF%BC%9A%E6%8F%90%E4%BE%9B%E8%BF%90%E8%A1%8C1Panel V2所需的Docker服务伪装脚本，解决1Panel在容器中对Docker环境的依赖。
• https://github.com/gdraheim/docker-systemctl-replacement%EF%BC%9A%E6%8F%90%E4%BE%9B%E5%9C%A8Docker%E5%AE%B9%E5%99%A8%E5%86%85%E9%83%A8%E4%BD%BF%E7%94%A8systemctl%E6%A8%A1%E6%8B%9F%E8%84%9A%E6%9C%AC%E7%9A%84%E5%AE%9E%E7%8E%B0%E3%80%82

📝 环境变量

• TZ：时区（默认：Asia/Shanghai）
• LANGUAGE：面板语言（可选：en、fa、pt-BR、ru、zh，默认：zh）
• INSTALL_MODE：安装模式（可选：stable、beta、dev，默认：stable）
• VERSION：版本号（可手动指定特定版本号，默认：在线获取最新稳定版本）
• PANEL_BASE_DIR：安装目录（默认：/opt）
• PANEL_PORT：面板端口（默认：9999）
• PANEL_ENTRANCE：安全入口（默认：entrance）
• PANEL_USERNAME：面板用户（默认：1panel）
• PANEL_PASSWORD：面板密码（默认：1panel_password）

📂 挂载目录

Docker进程套接字（不可修改）

/var/run/docker.sock:/var/run/docker.sock

允许容器内的1Panel直接与宿主机的Docker守护进程通信，管理宿主机上的Docker容器。

1Panel数据及应用安装目录（重要）

/path/to/your/data:/path/to/your/data
```（示例，**请务必替换为您的实际路径**）

此目录用于持久化存储1Panel的配置、数据以及通过它安装的所有应用。

**为保证所有应用正常工作，宿主机路径和容器内路径必须保持一致**。原因是1Panel安装应用时，会基于容器内的路径（由`PANEL_BASE_DIR`定义）来为应用创建数据卷。如果内外路径不匹配，1Panel本身可能正常运行，但其创建的应用将因找不到正确的数据目录而启动失败。

您可以选择直接挂载`PANEL_BASE_DIR`指定的目录，或其任何一级父目录，前提是`-v`参数冒号前后的路径必须完全相同。例如，如果`PANEL_BASE_DIR`是`/path/to/your/data`，那么`-v /path/to/your/data:/path/to/your/data`和`-v /path:/path`都是有效的配置。

## 🐳 部署方式

### Docker CLI部署示例

#### 1. 准备Docker镜像

您可以使用GitHub Container Registry上的最新版预构建Docker镜像：`ghcr.io/purainity/docker-1panel-v2:latest`，也可以在本地构建镜像。

如需在本地构建Docker镜像，请将本仓库中的所有文件复制到同一目录下，`cd`进入该目录后执行以下命令。您可以根据需要修改镜像名`docker-1panel-v2`。

```bash
docker build -t docker-1panel-v2 .

2. 运行Docker容器

使用以下命令运行1Panel容器。请务必根据您的实际需求修改配置参数。以下示例使用ghcr上的最新预构建镜像，容器名称为1panel，1Panel数据目录为/path/to/your/data，面板端口9999，安全入口entrance，面板用户1panel，面板密码1panel_password，并自动下载最新稳定版。

使用--network host可以避免额外的端口映射配置，使1Panel直接监听宿主机的端口。

使用--restart unless-stopped可以使1Panel容器在异常退出时自动重启。

bash
docker run -d \
--name 1panel \
--network host \
--restart unless-stopped \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /path/to/your/data:/path/to/your/data \
-e PANEL_BASE_DIR=/path/to/your/data \
-e PANEL_PORT=9999 \
-e PANEL_ENTRANCE=entrance \
-e PANEL_USERNAME=1panel \
-e PANEL_PASSWORD=1panel_password \
xindaowei/1panel:latest

3. 访问1Panel

1Panel安装完成后，您可以通过http://您的宿主机IP:面板端口/安全入口访问1Panel面板，并使用您在环境变量中设置的用户和密码登录。

Docker Compose部署示例

1. 创建docker-compose.yml文件

在项目根目录下创建一个名为docker-compose.yml的文件，内容如下。请务必根据您的实际需求修改配置参数。

yaml
version: '3.8'

services:
  1panel:
    # 如果使用ghcr上的最新版预构建镜像
    image: xindaowei/1panel:latest
    # 如果使用当前目录的Dockerfile本地构建镜像，请取消注释下一行，并注释上一行
    # build: . 
    container_name: 1panel # 容器名称
    network_mode: host # 使用宿主机网络
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock # 挂载Docker套接字
      - /path/to/your/data:/path/to/your/data # 挂载1Panel数据目录，请确保宿主机路径和容器内路径一致
    environment:
      TZ: Asia/Shanghai # 时区
      LANGUAGE: zh # 面板语言
      PANEL_BASE_DIR: /path/to/your/data # 安装目录
      PANEL_PORT: 9999 # 面板端口
      PANEL_ENTRANCE: entrance # 安全入口
      PANEL_USERNAME: 1panel # 面板用户
      PANEL_PASSWORD: 1panel_password # 面板密码
    restart: unless-stopped # 容器退出时自动重启，除非手动停止

2. 部署服务

在docker-compose.yml文件所在的目录下，执行以下命令构建镜像并启动服务。

bash
docker compose up -d --build

（如果您的系统使用的是旧版docker-compose，请使用docker-compose up -d --build）

3. 访问1Panel

1Panel安装完成后，您可以通过http://您的宿主机IP:面板端口/安全入口访问1Panel面板，并使用您在环境变量中设置的用户和密码登录。

❓ 常见问题

1. 运行容器后无法进入网页面板？

请使用以下命令查看容器日志，注意将容器名1panel修改为您的实际容器名称。

bash
docker logs -f 1panel

如果日志中未出现[INFO] listen at http://0.0.0.0:面板端口 [tcp4]，则说明1Panel还未启动，请耐心等待。如果重启容器后仍无法访问，请检查是否使用了host网络模式，若否，请检查是否正确配置了端口映射。

2. 网页面板出现请求错误，请检查该节点状态: stat /etc/1panel/agent.sock: no such file or directory？

这是1panel-agent服务还未完全启动。请耐心等待几秒钟后刷新网页即可。若长时间这样，请尝试重启容器。

3. 1Panel安装完成后，如何修改安全入口、面板用户、面板密码等设置？

环境变量中的设置仅在首次安装1Panel时有效。如果需要在安装完成后修改这些设置，请通过1Panel的网页面板进行操作。

4. 如何更换1Panel版本？

环境变量中的设置仅在首次安装1Panel时有效。对于常规升级，您可直接在1Panel的网页面板中进行在线更新。若需进行版本切换（如降级、或在stable与dev等通道间切换），则需要重建容器。请确保1Panel数据目录已正确持久化到宿主机，然后停止并删除旧容器，最后使用原部署命令，修改INSTALL_MODE或VERSION环境变量后重新创建容器。

5. 如何使用1pctl命令行操作？

请先使用以下命令进入容器内部Bash终端，然后输入1pctl即可操作，注意将容器名1panel修改为您的实际容器名称。

bash
docker exec -it 1panel bash

6. 能否不设置安全入口？

首次安装时必须设置安全入口。如果您想关闭安全入口，请在1Panel安装完成后，进入网页面板进行关闭操作。请勿手动将PANEL_ENTRANCE环境变量设置为空字符串，这会导致安装完成后1Panel无法启动！

7. 为什么不在镜像构建阶段就安装好1Panel，而是在运行容器时才安装？这是否违背了Docker的不变性原则？

1Panel版本更新频繁，本项目旨在提供一个通用的容器化运行环境，而非固化特定版本。采用运行时安装的方式，可以避免频繁构建容器镜像，并允许用户通过INSTALL_MODE和VERSION环境变量灵活指定需要安装的1Panel版本。