EasyWI 6.2.2 Docker Compose 部署指南

用 Docker Compose 从零部署 EasyWI 6.2.2 面板（php:7.4-apache 自建 + mariadb:10.11），含安装向导、登录与 API 初始化及排障实录，全部命令实测回显。

EasyWIEasyWI面板Docker部署MariaDB2026/11/02

EasyWI 6.2.2 Docker Compose 部署指南

目标：用 Docker Compose 从零部署 EasyWI（easy-wi）6.2.2 管理面板，完成安装向导、管理员登录与 API 凭据初始化。本文全部命令与回显均来自本机实验栈 easywi-622-stack 实测（2026-11-02），版本数据溯源见 《EasyWI 介绍与选型指南》。

一、环境信息

本文实测环境的关键信息如下，全部来自真实执行回显：

  • 部署工具：Docker 29.9.2 / Docker Compose v5.6.1（实测回显见 4.1 节）
  • 软件版本：EasyWI developer v6.2.2（GitHub releases/latest 稳定版，查询日期 2026-11-02）
  • Web 端：自建镜像 easywi-622-stack-web（基于 php:7.4-apache，实测 PHP 7.4.33、Apache/2.4.54）
  • 数据库端：mariadb:10.11 官方镜像
  • 端口映射：宿主机 8138 → Web 端 80
  • 专用网络：easywi-net，显式子网 10.89.65.0/24
  • 数据持久化：命名卷 easywi-db-data（数据库）+ bind mount（面板源码目录）
  • 演示账号：面板管理员 admin / q1w2e3r4；API 用户 apiuser / q1w2e3r4；数据库口令 q1w2e3r4

二、镜像选型说明

2.1 为什么自建 Web 镜像

EasyWI 官方不提供 Docker 镜像，只提供源码包（GitHub 仓库 easy-wi/developer）。官方 README 要求 PHP 5.4+ 并列出必需扩展：openssl、json、hash、ftp、SimpleXML、curl、gd、PDO、pdo_mysql（查询日期 2026-11-02）。其中 json/hash/curl/PDO 等在 php 官方镜像内已内置或默认启用，需要补装的是 gd、ftp、pdo_mysql（以及 zip 便于解包类操作），因此以 php:7.4-apache 为基础镜像做一层薄封装即可。

💡 技术拓展：Web 面板类软件选 PHP 基础镜像的常见档位对比——

基础镜像状态适配 EasyWI 的取舍
php:5.6 / 7.0-apache上游已停维护满足"5.4+"下限但镜像本身带安全风险，不选
php:7.4-apache停止官方维护，镜像仍可得语法兼容性好、扩展编译资料全，本文实测选它
php:8.x-apache当前受支持老代码对 8.x 的严格类型/废弃函数兼容性未验证，风险高

本文采用 php:7.4-apache，是"能编译全部必需扩展 + 老代码兼容"的折中；上生产前建议先在测试栈验证目标 PHP 大版本。

2.2 Dockerfile 全文

deploy/web/Dockerfile（实测构建通过）：

FROM php:7.4-apache

RUN apt-get update && apt-get install -y --no-install-recommends \
        libpng-dev \
        libjpeg62-turbo-dev \
        libfreetype6-dev \
        libzip-dev \
        zlib1g-dev \
        libssl-dev \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j"$(nproc)" gd zip ftp pdo_mysql \
    && rm -rf /var/lib/apt/lists/*

COPY easywi.ini /usr/local/etc/php/conf.d/easywi.ini

逐项说明：libpng/libjpeg/libfreetype 是 gd 扩展的图像库依赖；libzip 对应 zip 扩展；docker-php-ext-configure gd --with-freetype --with-jpeg 是 PHP 7.4 下 gd 的新式配置参数（旧式 --with-png-dir 已废弃）；ftp 与 pdo_mysql 对应 README 必需扩展；最后把 PHP 运行参数文件拷入 conf.d（见八、配置文件挂载）。

2.3 数据库镜像

选 mariadb:10.11：EasyWI 的 SQL 兼容 MySQL/MariaDB，MariaDB 10.11 为长期维护线，且官方镜像自带 healthcheck.sh 可供 compose 健康检查（实测见 4.4 节）。

三、前置条件

3.1 主机能力

  • 已安装 Docker 与 Compose v2 子命令（回显见 4.1 节）。
  • 宿主机端口 8138 未被占用（ss -ltn | grep 8138 无输出）。
  • 自定义网络子网需显式指定且避开已占用网段：本栈用 10.89.65.0/24，部署前用 docker network ls 与 docker network inspect 确认该段未被其他栈占用。

3.2 获取软件源码包

从 GitHub tags 下载 v6.2.2 源码包并解包（实测）：

cd /opt/data/quzuo/tmp/easywi
wget https://github.com/easy-wi/developer/archive/refs/tags/v6.2.2.tar.gz -O developer-6.2.2.tar.gz
tar xzf developer-6.2.2.tar.gz
ls -l developer-6.2.2.tar.gz

-rw-r--r-- 1 root root 6488215 Nov  2 20:42 developer-6.2.2.tar.gz

解包后目录为 developer-6.2.2/，将整体 bind mount 进 Web 端充当面板源码（升级即换目录，数据全在数据库卷里）。

四、部署步骤

4.1 确认部署工具版本

docker --version
docker compose version

Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1

4.2 目录结构

tmp/easywi/
├── developer-6.2.2/            # 面板源码（bind mount 进 Web 端）
└── deploy/
    ├── docker-compose.yml
    └── web/
        ├── Dockerfile
        └── easywi.ini

4.3 编写 docker-compose.yml

deploy/docker-compose.yml 全文（实测在跑）：

name: easywi-6.2.2-stack
services:
  web:
    build: ./web
    container_name: easywi-6.2.2-web
    restart: unless-stopped
    ports:
      - "8138:80"
    volumes:
      - ../developer-6.2.2:/var/www/html
    depends_on:
      db:
        condition: service_healthy
    networks:
      - easywi-net
  db:
    image: mariadb:10.11
    container_name: easywi-6.2.2-db
    restart: unless-stopped
    environment:
      MARIADB_ROOT_PASSWORD: q1w2e3r4
      MARIADB_DATABASE: easywi
      MARIADB_USER: easywi
      MARIADB_PASSWORD: q1w2e3r4
    volumes:
      - easywi-db-data:/var/lib/mysql
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 5s
      timeout: 5s
      retries: 12
    networks:
      - easywi-net
networks:
  easywi-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.65.0/24
volumes:
  easywi-db-data:

要点：首行 name: 显式固定项目名（防与其他组件同名目录互删）；depends_on.db.condition: service_healthy 保证 Web 启动时数据库已可写；网络显式子网便于 API IP 白名单固定填写。

4.4 构建并启动

cd deploy
docker compose build
docker compose up -d

构建输出节选（实测首尾）：

#9 exporting to image
#9 naming to docker.io/library/easywi-622-stack-web:latest done
#9 unpacking to docker.io/library/easywi-622-stack-web:latest done
#9 DONE 0.0s
#10 resolving provenance for metadata file
#10 DONE 0.0s
 Image easywi-622-stack-web Built

启动输出（实测）：

 Container easywi-6.2.2-web Running 
 Container easywi-6.2.2-db Running 
 Container easywi-6.2.2-db Waiting 
 Container easywi-6.2.2-db Healthy

db Healthy 即健康检查通过，验证命令与回显：

docker compose ps

NAME               IMAGE                  COMMAND                  SERVICE   CREATED       STATUS                    PORTS
easywi-6.2.2-db    mariadb:10.11          "docker-entrypoint.s…"   db        2 hours ago   Up 33 minutes (healthy)   3306/tcp
easywi-6.2.2-web   easywi-622-stack-web   "docker-php-entrypoi…"   web       2 hours ago   Up 33 minutes             0.0.0.0:8138->80/tcp, [::]:8138->80/tcp

4.5 运行安装向导

浏览器访问 http://localhost:8138/install/ 进入官方安装向导（页头实测文本 Easy-WI.com Installer 6.2.2，标题 "Easy-Wi Installer"）。按向导逐步完成：

  1. 系统检查页确认 PHP 版本与必需扩展全部就绪；
  2. 填入数据库连接：主机 db、库 easywi、用户 easywi、口令 q1w2e3r4；
  3. 设置站点标题与管理员账号（本文用 admin / q1w2e3r4）；
  4. 向导写入配置文件并初始化数据表。

验证安装结果——配置文件已由向导生成（Web 端内实测 cat /var/www/html/stuff/config.php，全文见 七、配置参数说明）；版本表实测：

docker exec easywi-6.2.2-db mariadb -ueasywi -pq1w2e3r4 easywi -e "SELECT * FROM easywi_version;"

id	version	de	en
1	6.2.2

4.6 删除 install 目录（强制）

安装完成后必须删除源码包中的 install/ 目录。程序内置守卫：login.php 与 api.php 开头检测该目录存在即 die('Please remove the "install" folder')。实测删除后 ls /var/www/html/ | grep install 无输出。

4.7 登录验证（实测）

curl -s -c jar.txt "http://localhost:8138/login.php?gamestring=k27a906h3f8m"
curl -s -b jar.txt -c jar.txt -X POST http://localhost:8138/login.php -d "username=admin&password=q1w2e3r4" -w "http_code=%{http_code} redirect=%{redirect_url}\n"

http_code=302 redirect=http://localhost:8138/admin.php

curl -s -b jar.txt "http://localhost:8138/admin.php?w=sa" -w "%{http_code} %{size_download}\n"

200 24755

302 跳转到 admin.php、管理首页 200 且返回 24755 字节页面，登录链路验证通过。

4.8 初始化 API 用户与 IP 白名单（实测）

后台 Admin 区域创建 API 用户 apiuser（口令 q1w2e3r4），并在 API 设置的 IP 白名单中加入调用方 IP。落库结果实测：

docker exec easywi-6.2.2-db mariadb -ueasywi -pq1w2e3r4 easywi -e "SELECT * FROM api_ips;"

ip	resellerID
10.89.65.1	0

10.89.65.1 即宿主机在 easywi-net（10.89.65.0/24）中的地址。API 鉴权链与 403 排障实录见《EasyWI 6.2.2 配置参数详解》篇。

五、数据持久化说明

数据载体实测位置说明
数据库命名卷 easywi-db-data挂载至 db 端 /var/lib/mysql面板全部业务数据（settings/userdata/api 等表）所在，备份即备此卷
面板源码bind mount../developer-6.2.2 → /var/www/html换版本=换目录；源码本身不含状态
生成的配置随 bind mount/var/www/html/stuff/config.php安装向导写入，升级换目录后需重新生成或保留该文件
PHP 参数镜像内/usr/local/etc/php/conf.d/easywi.ini由 Dockerfile COPY 进镜像

宿主机重启后栈自动拉起（restart: unless-stopped 实测生效）：docker compose ps 中 CREATED About an hour ago 而 STATUS Up 14 minutes，即重启后由 Docker 自动恢复，数据无损。

六、环境变量表

变量作用对象实测值说明
MARIADB_ROOT_PASSWORDdbq1w2e3r4root 口令
MARIADB_DATABASEdbeasywi预建库名，安装向导直接可用
MARIADB_USERdbeasywi面板连接账号
MARIADB_PASSWORDdbq1w2e3r4面板连接口令，需与 config.php $pwd 一致
--character-set-serverdb commandutf8mb4服务端字符集
--collation-serverdb commandutf8mb4_unicode_ci排序规则

⚠️ 注意：以上口令为文档演示值（按规范直接落值）。生产环境请替换为强口令，并同步修改安装向导填入值与 stuff/config.php。

七、配置参数说明

安装向导生成的 stuff/config.php 全文（实测 cat）：

<?php
// This file was generated by the easy-wi.com installer
$host = 'db';
$user = 'easywi';
$db = 'easywi';
$pwd = 'q1w2e3r4';
$captcha = '';
$title = 'Easy-Wi';
$debug = '0';
$timezone = 'Europe/Berlin';
$coloreddashboard = false;
$easywitweets = true;
$examplemodule = true;

逐项含义：

键实测值含义
$host/$user/$db/$pwddb/easywi/easywi/q1w2e3r4PDO 连接串，对应 compose 环境变量
$captcha''（空）空即关闭登录验证码；非空填入 reCAPTCHA 私钥则启用
$titleEasy-Wi站点标题
$debug0调试开关，生产保持 0
$timezoneEurope/BerlinPHP 时区（上游默认德国）
$coloreddashboardfalse首页彩色卡片样式
$easywitweetstrue是否拉取官方动态
$examplemoduletrue是否加载示例模块

数据库侧 settings 表为单行宽表（非键值对），安装后实测关键列值：version=6.2.2、language=en、template=default、templateColor=blue、brandname=quzuo.net、paneldomain=http://localhost:8138/、faillogins=5、cronjob_ips 为空、lastCronWarn* 全为 Y。逐列详解见《EasyWI 6.2.2 配置参数详解》篇。

八、配置文件挂载

Web 端 PHP 运行参数通过 deploy/web/easywi.ini 挂载进镜像（Dockerfile 末行 COPY），全文（实测）：

date.timezone = Europe/Berlin
memory_limit = 256M
max_execution_time = 300
upload_max_filesize = 64M
post_max_size = 64M
参数值为什么这样设
date.timezoneEurope/Berlin与面板 $timezone 一致，避免 PHP 时区告警
memory_limit256M面板批量查询服务器状态时默认 128M 偏紧
max_execution_time300开服/备份等长操作防超时中断
upload_max_filesize / post_max_size64M上传服务器配置/备份文件的余量

如需改参数而不重建镜像，可把该文件改为 volume 挂载：在 compose 的 web.volumes 追加 - ./web/easywi.ini:/usr/local/etc/php/conf.d/easywi.ini:ro 后 docker compose up -d web。

九、等价 docker run 命令

以下由 compose 文件逐字段翻译而来（等价形式说明，本栈全程以 compose 管理，未单独用 run 复测）：

# 数据库
docker run -d --name easywi-6.2.2-db --network easywi-net \
  -e MARIADB_ROOT_PASSWORD=q1w2e3r4 -e MARIADB_DATABASE=easywi \
  -e MARIADB_USER=easywi -e MARIADB_PASSWORD=q1w2e3r4 \
  -v easywi-db-data:/var/lib/mysql \
  mariadb:10.11 --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci

# Web 面板
docker run -d --name easywi-6.2.2-web --network easywi-net \
  -p 8138:80 -v $(pwd)/../developer-6.2.2:/var/www/html \
  easywi-622-stack-web

十、常用运维命令

docker compose ps                    # 状态与健康（回显见 4.4）
docker compose logs -f web           # 跟踪面板日志
docker compose restart web           # 重启面板
docker compose down                  # 停止并移除容器/网络（保留卷）
docker exec -it easywi-6.2.2-db mariadb -ueasywi -pq1w2e3r4 easywi   # 进数据库
docker exec easywi-6.2.2-web php -v  # 验证 PHP

php -v 实测回显：

PHP 7.4.33 (cli) (built: Nov 15 2022 06:03:30) ( NTS )
Copyright (c) The PHP Group

Apache 日志位于 Web 端 /var/log/apache2/{access,error}.log。四个 cron 脚本（statuscheck/jobs/startupdates/cloud）的部署与实测回显见《EasyWI 6.2.2 常用 CLI 命令与工具详解》篇。

十一、常见问题

11.1 安装向导页顶部刷 Notice/Warning

实测安装向导各步骤页面顶部打印：

Notice : Undefined index: HTTP_ACCEPT_LANGUAGE in /var/www/html/install/install.php on line 65
Warning : simplexml_load_file(): /var/www/html/install/languages/en.xml:107: parser error : Opening and ending tag mismatch: system_check_ok_folder_2 line 82 and sprache in /var/www/html/install/install.php on line 69

定位：install.php:65 直接读 $_SERVER['HTTP_ACCEPT_LANGUAGE']，客户端未带该头时报 Notice；install/languages/en.xml 第 107 行标签闭合错误导致 SimpleXML 解析告警。结论：不阻塞安装主流程（本栈在此噪音下完成全部步骤并成功登录），可忽略继续；若追求干净输出，可给请求显式设置 Accept-Language 头，或修复语言包 XML 后重试。

11.2 打开 login.php 提示 Please remove the "install" folder

安装完成后 install/ 目录未删，login.php/api.php 的守卫直接 die。解决：删除源码目录中的 install/（见 4.6），无需改任何配置。

11.3 登录页没有验证码输入框

stuff/config.php 中 $captcha = '' 即关闭验证码（实测登录表单只有 username、password 两个字段）。需要启用时填入 reCAPTCHA 私钥，模板 login.tpl 会渲染出 pattern="^[\w]{4}$" 的验证码输入。

11.4 web 端启动即退出 / 连不上数据库

depends_on 只保证先后不保证就绪，本栈用 condition: service_healthy + MariaDB healthcheck.sh --connect --innodb_initialized 兜底。若仍失败，docker compose logs db 确认卷是否残留了旧口令数据（换口令需 docker compose down -v 清卷重建）。

十二、参考链接

EasyWI 6.2.2 Docker Compose 部署指南 - Quzuo