Skip to content

配置开发环境 ​

开发 EduSoho 企培版需要 PHP、MySQL、Nginx、Node.js 等环境。推荐用 Docker 运行 PHP-FPM 和 MySQL,Nginx、Node.js 装在本机,各系统步骤一致,也不会和本机已有的 PHP 冲突。

0. 选择安装方式 ​

安装方式适用系统说明章节
Docker(推荐)macOS、Linux、Windows(WSL2)PHP-FPM、MySQL 跑在容器里,Nginx、Node.js 装在本机§1
原生安装Ubuntu 22.04 / 24.04用 Ondřej Surý PPA 安装 PHP§2

PHP 版本:企培版代码需兼容 PHP 7.2,开发环境默认使用 PHP 7.2。如需在 PHP 8.3 下验证(企培版 24.2.6 及以上支持),把下文所有 7.2 替换为 8.3,并从扩展列表中删除 php8.3-json(已内置)和 php8.3-mcrypt。

约定:EduSoho 代码放在 /var/www/edusoho,与安装 EduSoho 企培系统保持一致。


1. Docker 方式(推荐) ​

思路:PHP-FPM 容器监听本机 127.0.0.1:9072,MySQL 容器监听 127.0.0.1:3306;本机 Nginx 把 PHP 请求转给 9072 端口,前端实时编译服务仍在本机运行。

1.1 前提 ​

  • macOS / Windows:安装 Docker Desktop。
  • Linux:安装 Docker Engine 及 docker compose 插件。

确认可用:

bash
docker version
docker compose version

1.2 准备目录 ​

bash
sudo mkdir -p /var/www
sudo chown -R $(whoami) /var/www
mkdir -p ~/edusoho-docker
cd ~/edusoho-docker

1.3 创建 Dockerfile ​

在 ~/edusoho-docker/ 下创建 Dockerfile:

dockerfile
FROM ubuntu:24.04

RUN sed -i 's@//.*archive.ubuntu.com@//mirrors.aliyun.com@g' /etc/apt/sources.list.d/ubuntu.sources && \
    sed -i 's@//security.ubuntu.com@//mirrors.aliyun.com@g' /etc/apt/sources.list.d/ubuntu.sources && \
    sed -i 's@//ports.ubuntu.com@//mirrors.aliyun.com@g' /etc/apt/sources.list.d/ubuntu.sources

ENV TZ=Asia/Shanghai
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

RUN apt-get update && \
    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends software-properties-common ca-certificates && \
    LC_ALL=C.UTF-8 add-apt-repository -y ppa:ondrej/php && \
    apt-get clean && rm -rf /var/lib/apt/lists/*

RUN apt-get update && \
    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
      locales git unzip php-pear \
      php7.2-cli php7.2-common php7.2-curl php7.2-dev php7.2-fpm php7.2-json \
      php7.2-mbstring php7.2-mcrypt php7.2-mysql php7.2-opcache php7.2-zip \
      php7.2-intl php7.2-gd php7.2-xml php7.2-redis php7.2-ldap && \
    locale-gen zh_CN.UTF-8 en_US.UTF-8 && \
    apt-get clean && rm -rf /var/lib/apt/lists/*

# Composer 2.2 是 LTS 版本,仍支持 PHP 7.2
COPY --from=composer:2.2 /usr/bin/composer /usr/local/bin/composer

# 容器内监听 9000,由 docker-compose 映射到本机 127.0.0.1:9072;开发环境放宽内存与上传限制
RUN sed -i 's|^listen = .*|listen = 9000|' /etc/php/7.2/fpm/pool.d/www.conf && \
    printf 'memory_limit = 1024M\nupload_max_filesize = 100M\npost_max_size = 100M\nmax_execution_time = 300\n' \
      | tee /etc/php/7.2/fpm/conf.d/99-dev.ini /etc/php/7.2/cli/conf.d/99-dev.ini > /dev/null && \
    mkdir -p /run/php && \
    ln -sf /usr/sbin/php-fpm7.2 /usr/local/bin/php-fpm

ENV LANG=zh_CN.UTF-8
ENV LC_ALL=zh_CN.UTF-8

WORKDIR /var/www

# -F 强制前台运行,避免 php-fpm 自行 daemonize 导致容器退出
CMD ["php-fpm", "-F"]

1.4 创建 docker-compose.yml ​

yaml
services:
  php:
    build: .
    image: edusoho/php:7.2-dev
    restart: unless-stopped
    ports:
      - "127.0.0.1:9072:9000"
    volumes:
      - /var/www:/var/www
    depends_on:
      - mysql

  mysql:
    image: mysql:5.7
    # Apple Silicon(M 系列芯片)没有 mysql:5.7 原生镜像,以 amd64 方式模拟运行
    platform: linux/amd64
    restart: unless-stopped
    ports:
      - "127.0.0.1:3306:3306"
    environment:
      MYSQL_ALLOW_EMPTY_PASSWORD: "yes"
      TZ: Asia/Shanghai
    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
    volumes:
      - ./data/mysql:/var/lib/mysql

说明:

  • 容器内路径必须与 Nginx 传给 PHP-FPM 的路径一致。 Nginx 配置使用 $realpath_root,会把软链接解析成真实路径:
    • Linux:保持 /var/www:/var/www。
    • macOS:/var 是 /private/var 的软链接,需改为 - /private/var/www:/private/var/www。
  • macOS 上该目录还必须共享给 Docker 虚拟机,否则容器里看到的是空目录:Docker Desktop 默认已共享 /private(可在 Settings → Resources → File sharing 确认);Colima 默认只共享用户主目录,需用 colima start --mount /private/var/www:w 启动。
  • MySQL root 密码为空,仅用于本机开发,端口只绑定在 127.0.0.1。数据保存在 ~/edusoho-docker/data/mysql。
  • 本机已经装了 MySQL 并占用 3306 时,先停掉本机 MySQL,或把映射改为 "127.0.0.1:3307:3306"。

1.5 构建并启动 ​

bash
cd ~/edusoho-docker
docker compose up -d --build
docker compose ps          # php、mysql 状态应为 running
docker compose logs php    # 确认无报错

1.6 本机安装 Nginx ​

Ubuntu:

bash
sudo apt-get update
sudo apt-get install -y nginx

macOS(Homebrew):

bash
brew install nginx
mkdir -p $(brew --prefix)/etc/nginx/sites-enabled

macOS 还需在 $(brew --prefix)/etc/nginx/nginx.conf 的 http { } 块末尾加上 include sites-enabled/*;,之后站点配置都放在 sites-enabled 目录下。Homebrew 的 Nginx 默认监听 8080,要监听 80 端口需用 sudo brew services start nginx 启动。

提示

​

Apple Silicon 上 $(brew --prefix) 为 /opt/homebrew,Intel 上为 /usr/local。安装 EduSoho 企培系统中写的 /usr/local/etc/nginx 请按实际前缀替换。

1.7 本机安装 Node.js 和 Git ​

前端编译要求 Node.js 16.20.2,推荐用 nvm 管理版本:

bash
nvm install 16.20.2
nvm use 16.20.2
npm config set registry https://registry.npmmirror.com

Git:Ubuntu 执行 sudo apt-get install -y git;macOS 执行 xcode-select --install 或 brew install git。

1.8 与《安装 EduSoho 企培系统》的差异 ​

按安装 EduSoho 企培系统继续操作时,Docker 方式有以下几处不同:

步骤Docker 方式的做法
创建数据库cd ~/edusoho-docker && docker compose exec mysql mysql -uroot -e 'CREATE DATABASE `edusoho` DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci'
parameters.yml 数据库地址database_host: mysql(PHP 在容器内,通过服务名访问 MySQL)
执行 app/console、composer 等 PHP 命令进入容器后执行,见下方命令
Nginx fastcgi_pass改为 127.0.0.1:9072

进入 PHP 容器(以本机当前用户身份运行,避免生成的文件归属 root):

bash
cd ~/edusoho-docker
docker compose exec -u $(id -u):$(id -g) -e HOME=/tmp php bash
cd /var/www/edusoho     # macOS 为 /private/var/www/edusoho

npm install、npm run dev 等前端命令仍在本机执行。

注意

​

Linux 下 PHP-FPM 以 www-data(UID 33)运行。app/cache、app/logs、app/data、web/files 需要可写,按安装文档执行 chmod 777 即可。

1.9 验证 ​

bash
cd ~/edusoho-docker
docker compose exec php php -v   # 输出 PHP 7.2.x
docker compose exec php php -m   # 确认 mysqli、pdo_mysql、redis、gd、intl 等扩展存在
docker compose exec mysql mysql -uroot -e 'SELECT VERSION();'

数据库客户端(Navicat、TablePlus、phpMyAdmin 等)连接 127.0.0.1:3306,用户 root,密码为空。

1.10 常用命令 ​

bash
cd ~/edusoho-docker
docker compose restart php   # 修改 PHP 配置后重启
docker compose logs -f php   # 查看 PHP-FPM 日志
docker compose stop          # 停止
docker compose up -d         # 启动

2. Ubuntu 22.04 / 24.04 原生安装 ​

2.1 安装 PHP ​

bash
sudo LC_ALL=C.UTF-8 add-apt-repository -y ppa:ondrej/php
sudo apt-get update
sudo apt-get install -y php-pear \
    php7.2-cli php7.2-common php7.2-curl php7.2-dev php7.2-fpm php7.2-json \
    php7.2-mbstring php7.2-mcrypt php7.2-mysql php7.2-opcache php7.2-zip \
    php7.2-intl php7.2-gd php7.2-xml php7.2-redis php7.2-ldap

国内服务器访问 Launchpad 可能较慢或超时,必要时请配置代理后再执行。

修改 PHP-FPM 监听方式为 127.0.0.1:9000,并重启:

bash
sudo sed -i 's/^listen = .*/listen = 127.0.0.1:9000/' /etc/php/7.2/fpm/pool.d/www.conf
sudo systemctl restart php7.2-fpm

2.2 安装 MySQL ​

推荐 MySQL 5.7。Ubuntu 22.04 / 24.04 自带的是 MySQL 8.0,最简单的做法是只用 Docker 跑 MySQL:按 §1.4 创建 docker-compose.yml 后执行 docker compose up -d mysql。

2.3 安装 Nginx、Node.js、Git ​

bash
sudo apt-get install -y nginx git

Node.js 按 §1.7 用 nvm 安装 16.20.2。

完成后按安装 EduSoho 企培系统继续,Nginx 的 fastcgi_pass 保持 127.0.0.1:9000。