# ruoyi-php

**Repository Path**: asd375zxcvb/ruoyi-php

## Basic Information

- **Project Name**: ruoyi-php
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-18
- **Last Updated**: 2026-01-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ruoyi-php 开发操作手册（Docker）

本项目采用 **Docker 多阶段构建** + **Docker Compose**，实现：

- 不在宿主机安装 PHP / Node / Composer。
- 开发环境与生产环境一致。
- 一条命令完成依赖安装、开发启动、构建与生产运行。

## 目录结构要点

- `compose.yaml`：开发/构建/预览编排（使用 ops/ 下的 Dockerfile）
- `ops/`：Dockerfile 与 Nginx 配置
- `docker/`：Nginx 配置与启动脚本
- `.env`：本地环境变量配置（不会进镜像）

## 环境准备

- 安装 Docker Desktop
- 本地无需安装 PHP / Composer / Node

## 一键安装依赖

在宿主机执行：

```bash
npm run docker:install
```

也可以拆分：

```bash
npm run install:vendor   # 安装 PHP 依赖 (vendor)
npm run install:node     # 安装前端依赖 (node_modules)
```

以上命令都会通过 `tools` 容器执行，依赖会写入卷（不依赖宿主机环境）。

## 启动开发环境

```bash
npm run docker:dev
```

- 应用访问：`http://localhost:8000`
- Vite/HMR：`http://localhost:5173`

默认使用 **轻量开发模式**（只启动 Laravel + Vite）。
如果需要队列和日志监听：

```bash
DEV_SCRIPT=dev npm run docker:dev
```

## 为什么需要 8000 和 5173 两个端口？

- **8000**：`php artisan serve` 提供 Laravel 后端服务
- **5173**：Vite 开发服务器，负责前端资源编译与 HMR 热更新

开发模式下，Blade 会自动引用 Vite 的开发服务器资源；生产模式才使用 `public/build` 中的静态文件。

## 构建与预览

```bash
npm run docker:build
```

- 仅构建产物，不启动容器
- 新增 npm run docker:preview，访问 `http://localhost`

如需停止生产容器：

```bash
docker compose --profile runtime down
```

## 非 Docker 环境（本机运行）

安装依赖：

```bash
composer install
npm install
```

启动开发环境（完整模式）：

```bash
composer run dev
```

轻量开发模式（不跑队列/日志）：

```bash
composer run dev:lite
```

也可分别启动：

```bash
php artisan serve --host 0.0.0.0 --port 8000
npm run dev -- --host 0.0.0.0 --port 5173
```

打包构建（生产前端资源）：

```bash
npm run build
```

## 数据库配置（使用你现有的 Postgres）

编辑 `.env`，例如：

``` env
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=postgres
DB_USERNAME=postgres
DB_PASSWORD=123456
```

如需使用容器内网络地址，可改为你当前环境对应的 IP。

数据库表尚未创建时，可在开发容器中执行：

```bash
docker compose exec app php artisan migrate
```

如果使用数据库队列：

- `.env` 已设置 `QUEUE_CONNECTION=database`
- 确保 `jobs` 表迁移已存在并执行过

## 常用维护操作

查看日志：

```bash
docker compose logs -f app
```

清理依赖并重装：

```bash
docker compose down -v
npm run docker:install
```

## 版本管理注意

`.gitignore` 已忽略以下内容：

- `vendor/`、`node_modules/`
- `public/build`、`public/hot`
- `.env`
- `*.lock` 与 `*-lock.json`

说明：`composer.lock` 与 `package-lock.json` **不纳入 Git 版本管理**。

## 故障排查

- **生产环境样式缺失**：确认 `public/hot` 已移除，生产使用 `public/build`
- **HMR 不生效**：确保 5173 端口可访问，开发容器在跑；必要时启用轮询（已在 `docker-compose.yml` 预设）
- **依赖冲突/奇怪错误**：尝试 `docker compose down -v` 重新安装依赖

---

如需调整开发脚本或镜像体积，请修改 `composer.json` 与 `ops/` 下的 Dockerfile。