# laradox

**Repository Path**: java_doc/laradox

## Basic Information

- **Project Name**: laradox
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-22
- **Last Updated**: 2026-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Laradox

[![Tests](https://github.com/adityarizqi/laradox/workflows/Tests/badge.svg)](https://github.com/adityarizqi/laradox/actions)
[![Latest Stable Version](https://poser.pugx.org/adityarizqi/laradox/v)](https://packagist.org/packages/adityarizqi/laradox)
[![License](https://poser.pugx.org/adityarizqi/laradox/license)](https://packagist.org/packages/adityarizqi/laradox)

> **开箱即用的 Laravel Docker 环境，支持 FrankenPHP、Nginx 与 Octane**

Laradox 提供了一套面向生产环境的 Docker 环境，针对 Laravel Octane 与 FrankenPHP 做了优化。它同时适用于本地开发与生产部署，并借助 mkcert 提供自动 HTTPS 支持。

## 特性

- 基于 FrankenPHP 的 **Laravel Octane**，性能极快
- **HTTPS 支持** —— 开发环境可选，**生产环境必选**
- 面向开发与生产的 **Docker Compose** 配置
- 以 **Nginx** 作为反向代理，并附带优化配置
- 使用 Supervisor 管理的**队列工作进程**
- 使用 Supercronic 实现的**任务调度器**
- 用于 composer、npm 和 php 命令的**辅助脚本**
- 通过 Composer **轻松安装**

## 性能

在静态测试条件下，*不使用*与*使用* FrankenPHP 的性能对比：

| 不使用 FrankenPHP | 使用 FrankenPHP |
| --- | --- |
| ![不使用 FrankenPHP](https://dl.dropboxusercontent.com/scl/fi/lb72q5zzi6q2f6bdny5pn/with_out_franken_php.jpeg?rlkey=vew9og9gda25u7ofdq2vlsesd&e=1&st=d3nlrnvs&dl=0) | ![使用 FrankenPHP](https://dl.dropboxusercontent.com/scl/fi/ibskidxfhtgsx55ykrolw/with_franken_php.jpeg?rlkey=j9dnhycufuttrrcptjm4h786m&e=1&st=yqofcch2&dl=0) |

## 环境要求

- PHP 8.2 或更高版本（使用 Laravel 13.x 时需 PHP 8.3+）
- Laravel 10.x、11.x、12.x 或 13.x
- Docker 与 Docker Compose（自动检测，缺失时会提示安装）
- [mkcert](https://github.com/FiloSottile/mkcert)（自动检测，缺失时会提示安装）

## 安装

### 第 1 步：通过 Composer 安装

```bash
composer require adityarizqi/laradox --dev
```

### 使用 Gitee 源安装（国内加速 / 自定义 fork）

除了默认的 Packagist 源，还可以注册自定义 VCS 源，让 Composer 优先从 Gitee 仓库拉取本包（国内访问更快，也便于使用自己维护的 fork）：

```bash
# 注册 VCS 源（写入项目 composer.json 的 repositories 配置）
composer config repositories.laradox vcs https://gitee.com/java_doc/laradox.git

# 安装 / 更新（其余步骤与标准安装完全一致）
composer require adityarizqi/laradox --dev

# 验证安装来源
composer show adityarizqi/laradox
```

说明：`repositories` 源会参与所有依赖包的版本解析，但只有在该仓库中定义的包名（即 `adityarizqi/laradox`）才会命中此源，项目其它依赖仍正常从 Packagist 安装，零影响。当同一包名在多个源中同时存在时，Composer 选用版本号更高的一个。

### 第 2 步：安装 Laravel Octane

```bash
composer require laravel/octane
```

### 第 3 步：安装 Laradox

```bash
php artisan laradox:install
```

该命令会：
- 发布 Docker 配置文件
- 发布面向开发与生产的 Docker Compose 文件
- 发布辅助脚本（composer、npm、php）
- 创建必要的目录
- 为脚本赋予可执行权限

### 第 4 步：配置 SSL 证书

**开发环境（可选）：**

为受信任的 HTTPS 配置 SSL 证书：

```bash
php artisan laradox:setup-ssl
```

Laradox 会自动：
- 检测 mkcert 是否已安装
- 若缺失则提示安装 mkcert（支持 Ubuntu、Debian、Fedora、CentOS 与 macOS）
- 引导你完成安装过程
- 在 mkcert 可用后生成证书

也可以手动执行：

```bash
mkcert -install -cert-file ./docker/nginx/ssl/cert.pem -key-file ./docker/nginx/ssl/key.pem "*.docker.localhost" docker.localhost
```

> **开发环境**：SSL 是可选的。你可以在没有任何证书的情况下仅使用 HTTP（80 端口）运行，Laradox 会自动采用仅 HTTP 的配置。

**生产环境（必选）：**

生产环境中 SSL 证书是**强制要求**的。若没有有效的 SSL 证书，`laradox:up` 命令将拒绝启动生产容器。

```bash
php artisan laradox:setup-ssl
# 或者使用 --force-ssl=false 跳过（不推荐）
```

> **Windows 用户**：Windows 上不会自动安装 mkcert。请从 [mkcert releases](https://github.com/FiloSottile/mkcert/releases) 下载并手动运行。

> **WSL2 用户**：请在 Windows 侧运行 mkcert 命令，以便将证书安装到 Windows 的受信任证书存储中。

### 第 5 步：启动 Docker 容器

Laradox 在启动容器前会自动检查 Docker 与 Docker Compose。

**开发环境：**

```bash
php artisan laradox:up --detach
```

如果 Docker 未安装，Laradox 会：
- 检测你的操作系统（Ubuntu、Debian、Fedora、CentOS、macOS、Windows）
- 提供安装说明
- 提示自动安装 Docker（Linux 与 macOS）
- 引导你完成安装过程

也可以直接使用 Docker Compose：

```bash
docker compose -f docker-compose.development.yml up -d
```

**生产环境：**

```bash
php artisan laradox:up --environment=production --detach
```

### 第 6 步：安装依赖

```bash
./composer install
./npm install
./npm run dev
```

### 第 7 步：配置 Laravel

```bash
./php artisan key:generate
./php artisan migrate:fresh --seed
```

完成！打开 https://laravel.docker.localhost 即可查看你的应用（若未配置 SSL，则访问 http://laravel.docker.localhost）。

## 使用方法

### Artisan 命令

Laradox 提供了多个 artisan 命令来管理你的 Docker 环境：

```bash
# 安装 Laradox 文件
php artisan laradox:install [--force]

# 配置 SSL 证书
php artisan laradox:setup-ssl [--domain=example.com]

# 启动容器（自动检测 SSL）
php artisan laradox:up [--environment=development] [--detach] [--build]

# 强制使用 HTTPS（需要 SSL 证书）
php artisan laradox:up --force-ssl=true [--detach]

# 强制仅使用 HTTP（无 SSL）
php artisan laradox:up --force-ssl=false [--detach]

# 停止容器
php artisan laradox:down [--environment=development] [--volumes]

# 查看容器日志
php artisan laradox:logs [service] [--follow] [--tail=100] [--timestamps]

# 交互式进入容器 shell
php artisan laradox:shell [service] [--environment=development] [--user=www-data] [--shell=bash]

# 查看服务健康状态与资源占用
php artisan laradox:status [service] [--stats] [--watch] [--json]

# 在容器内构建（或清除）生产缓存
php artisan laradox:optimize [--environment=production] [--clear]

# 部署：拉取、构建、迁移、优化与健康检查
php artisan laradox:deploy [--environment=production] [--dry-run] [--force]

# 通过 HTTP 对应用进行基准测试
php artisan laradox:benchmark [url] [--requests=200] [--concurrency=10]
```

#### SSL 配置选项

`--force-ssl` 标志用于控制 SSL 行为：

- **未指定（默认）**：自动检测 SSL 证书
  - 开发环境：若缺失则提示，允许仅使用 HTTP
  - 生产环境：强制要求 SSL，缺失则失败
- **`--force-ssl=true`**：强制使用 HTTPS，需要有效证书
- **`--force-ssl=false`**：强制仅使用 HTTP，忽略证书

### 辅助脚本

借助辅助脚本，你无需进入容器即可在其中运行命令：

```bash
# 运行 composer 命令
./composer install
./composer update
./composer require vendor/package

# 运行 npm 命令
./npm install
./npm run dev
./npm run build

# 运行 PHP/Artisan 命令
./php artisan migrate
./php artisan queue:work
./php artisan tinker
```

### 交互式 Shell 访问

以交互方式进入容器，进行调试、探索或手动操作：

```bash
# 进入 PHP 容器（默认使用 sh shell）
php artisan laradox:shell

# 进入指定服务
php artisan laradox:shell nginx
php artisan laradox:shell node

# 使用不同的 shell（若不可用会自动回退到 sh）
php artisan laradox:shell --shell=bash
php artisan laradox:shell --shell=zsh

# 以指定用户运行
php artisan laradox:shell --user=www-data

# 生产环境
php artisan laradox:shell --environment=production
```

可用服务：`php`、`nginx`、`node`、`scheduler`、`queue`

### 服务健康与监控

`laradox:status` 会报告 compose 文件中声明的每一个服务——包括尚未创建容器的服务——及其状态、健康检查结果、运行时长和已发布端口：

```bash
# 单次报告
php artisan laradox:status

# 附加每个容器的 CPU、内存与网络占用
php artisan laradox:status --stats

# 保持报告在屏幕上，每 5 秒刷新一次
php artisan laradox:status --watch --stats --interval=10

# 单个服务
php artisan laradox:status php

# 机器可读的输出
php artisan laradox:status --json
```

当任何服务缺失、已停止、仍在启动或不健康时，该命令会以退出码 `1` 结束，因此可用于 CI 步骤或部署脚本的前置校验：

```bash
php artisan laradox:status --environment=production || echo "Something is down"
```

### 生产环境优化

`laradox:optimize` 会在容器**内部**执行 Laravel 的缓存预热，然后重启 Octane 工作进程，确保新的引导缓存真正生效：

```bash
# 自动加载器 + 配置/路由/视图/事件缓存 + octane:reload
php artisan laradox:optimize

# 撤销优化（optimize:clear + reload）
php artisan laradox:optimize --clear

# 跳过个别步骤
php artisan laradox:optimize --skip-autoloader --skip-reload

# 面向其他环境或服务
php artisan laradox:optimize --environment=development --service=php
```

Composer 自动加载器会以 `--classmap-authoritative` 方式生成，且仅在面向生产环境时附加 `--no-dev`。对开发环境执行优化时会先请求确认，因为缓存配置会把当前 `.env` 固化下来。

### 部署

`laradox:deploy` 按顺序执行整个发布流程，并在第一个失败处停止：

1. `git pull --ff-only`
2. 维护模式（可选）
3. `docker compose build`
4. `docker compose up -d --remove-orphans`
5. 等待所有服务报告健康
6. `composer install --no-dev --optimize-autoloader`
7. `npm ci && npm run build`
8. `php artisan migrate --force`
9. `laradox:optimize`
10. 退出维护模式

```bash
# 仅预览执行计划，不实际执行
php artisan laradox:deploy --dry-run

# 部署到生产环境
php artisan laradox:deploy

# 非交互式（CI），发布期间展示维护页面
php artisan laradox:deploy --force --maintenance

# 跳过不适用于你环境的步骤
php artisan laradox:deploy --force --no-pull --no-assets --no-migrate
```

每个步骤都可以通过 `--no-pull`、`--no-build`、`--no-composer`、`--no-assets`、`--no-migrate` 和 `--no-optimize` 跳过；启动容器与健康检查始终会执行。如果某个步骤失败，应用会被移出维护模式，且命令会提示去哪里排查。回滚意味着检出上一个版本并重新部署。

> **注意**：非交互式部署必须使用 `--force`，因此无人值守的运行绝不会意外执行迁移。

### 基准测试

`laradox:benchmark` 从宿主机发起并发 HTTP 请求，并报告延迟百分位数。它不需要外部压测工具——只需 PHP 的 cURL 扩展：

```bash
# 对配置的域名进行基准测试（存在证书时使用 HTTPS）
php artisan laradox:benchmark

# 调整压力参数
php artisan laradox:benchmark --requests=1000 --concurrency=50 --warmup=25

# 测试指定 URL，并忽略自签名的开发证书
php artisan laradox:benchmark https://laravel.docker.localhost/api/health --insecure

# 机器可读的输出，用于跟踪版本间的性能指标
php artisan laradox:benchmark --json > benchmark.json
```

报告涵盖吞吐量、成功率、传输字节数、状态码分布以及最小/平均/p50/p90/p95/p99/最大延迟。预热请求会被排除在外，以免 Octane 首次请求的开销影响百分位数统计。

### Docker Compose 命令

如需直接控制 Docker：

```bash
# 开发环境
docker compose -f docker-compose.development.yml up -d
docker compose -f docker-compose.development.yml down

# 生产环境
docker compose -f docker-compose.production.yml up -d --build
docker compose -f docker-compose.production.yml down

# 查看日志
docker compose -f docker-compose.development.yml logs -f

# 重启指定服务
docker compose -f docker-compose.development.yml restart php
```

## 配置

### Nginx 配置

Laradox 会根据你的环境和 SSL 可用性，自动使用合适的 nginx 配置：

**配置文件：**
- `app-http.conf` —— 仅 HTTP 的配置（80 端口）
- `app-https.conf` —— 带 HTTP→HTTPS 重定向的 HTTPS 配置
- `app.conf` —— 当前生效的配置（自动生成）

**自动选择逻辑：**
- **开发环境 + SSL**：使用 `app-https.conf`（启用 HTTPS）
- **开发环境无 SSL**：提示用户，使用 `app-http.conf`（仅 HTTP）
- **生产环境**：强制要求 SSL，始终使用 `app-https.conf`
- **`--force-ssl=true`**：始终使用 `app-https.conf`，无证书则失败
- **`--force-ssl=false`**：始终使用 `app-http.conf`，忽略证书

当你运行 `php artisan laradox:up` 时，配置会自动完成选择与复制。

> **注意**：你无需手动编辑 nginx 配置文件，Laradox 会自动处理。

**开箱即用的调优项：**

| 配置项 | 原因 |
|---------|-----|
| `pcre_jit on` | 加速 location 与 rewrite 匹配中的正则求值 |
| `http2 on` | 通过现行指令启用 HTTP/2，取代 nginx 1.25.1 中已弃用的 `listen ... http2` 参数 |
| `proxy_buffering` + 8×16k 缓冲区 | 响应一旦读取完毕即释放 FrankenPHP 工作进程，而不必为慢客户端一直占用 |
| 上游的 `keepalive_requests 1000` | 复用上游连接，并将重连分散到不同时间点 |
| `map $http_upgrade $connection_upgrade` | 让 WebSocket 与 Vite HMR 顺利透传，同时普通请求保持上游连接池存活 |
| `server_tokens off` | 响应与错误页中不暴露 nginx 版本号 |
| `ssl_buffer_size 4k` | 降低 TLS 连接的首字节时间 |
| `NGINX_ENVSUBST_FILTER=LARADOX_` | 模板替换只处理 `LARADOX_*`，不影响 nginx 自身的运行时变量 |

Gzip 特意保持关闭：FrankenPHP/Caddy 已经对响应做了压缩，压缩两次只会白白消耗 CPU。

### 环境变量

你可以在 `.env` 文件中通过环境变量自定义 Laradox 的行为：

```env
# 域名配置
LARADOX_DOMAIN=laravel.docker.localhost

# 环境
LARADOX_ENV=development

# 端口
LARADOX_HTTP_PORT=80
LARADOX_HTTPS_PORT=443
LARADOX_FRANKENPHP_PORT=8080

# 队列工作进程数（生产环境）
LARADOX_QUEUE_WORKERS=2

# 用户 ID（用于文件权限）
LARADOX_USER_ID=1000
LARADOX_GROUP_ID=1000
```

### 配置文件

发布并自定义配置文件：

```bash
php artisan vendor:publish --tag=laradox-config
```

编辑 `config/laradox.php` 即可自定义域名、端口、SSL 路径等。

## 服务

Laradox 包含以下服务：

- **nginx**：带 SSL 终结的反向代理
- **php**：搭载 Laravel Octane 的 FrankenPHP
- **node**：用于资源编译的 Node.js
- **scheduler**：Laravel 调度器（开发环境）或 Supercronic（生产环境）
- **queue**：由 Supervisor 管理的 Laravel 队列工作进程（仅生产环境）

### PHP 镜像

`php` 服务由 `docker/php/php.dockerfile` 构建——这是一个多阶段构建，所有编译都在一次性的 `builder` 阶段完成，因此运行时镜像只携带它真正需要的共享库。

**内置扩展：** `bcmath`、`excimer`、`gd`（含 JPEG/WebP/FreeType）、`intl`、`pcntl`、`pdo_mysql`、`pdo_pgsql`、`redis`、`uv`、`zip`，以及 FrankenPHP 基础镜像自带的一切（`opcache`、`mbstring`、`dom`、`curl`、`sqlite3` 等）。

**OPcache** 按环境分别调优：开发环境会校验时间戳，以便 `--watch` 重载时能感知代码改动；生产环境则关闭时间戳校验并启用 tracing JIT。由于生产环境会无限期缓存编译后的代码，部署时需要重建镜像或执行 `php artisan octane:reload`。

**构建参数** —— 在 compose 文件的 `build.args` 块中覆盖：

| 参数 | 默认值 | 用途 |
|-----|---------|---------|
| `FRANKENPHP_VERSION` | `1.12` | FrankenPHP 基础镜像版本 |
| `PHP_VERSION` | `8.4` | 基础镜像的 PHP 版本 |
| `ENVIRONMENT` | `development` | 选择 `development` 或 `production` 构建阶段 |
| `USER_ID` / `GROUP_ID` | `1000` | 宿主机 uid/gid，保证 bind mount 的文件保持可写 |
| `SUPERCRONIC_VERSION` | `0.2.48` | 要下载的 Supercronic 发行版本 |

该镜像支持多架构，可在 `amd64` 与 `arm64` 宿主机上构建（包括 Apple Silicon）。

**镜像体积** —— 运行时镜像只携带所选环境实际运行所需的内容：

- 编译好的扩展会剥离符号表，静态归档也会在离开 builder 阶段前被删除。
- Supervisor 与 Supercronic 仅安装在 `production` 阶段。开发环境用 `schedule:work` 运行调度器、用 `queue:work` 运行队列，因此两者在开发环境都不需要。
- 所有编译都发生在一次性的 `builder` 阶段；工具链永远不会进入运行时镜像。

在 `amd64`、FrankenPHP 1.12 / PHP 8.4、扩展列表不变的情况下实测：

| 阶段 | 优化前 | 优化后 |
|-------|--------|-------|
| `development` | 281 MB | **212 MB**（−25%） |
| `production` | 281 MB | **278 MB**（−1%） |

用以下命令检查你自己的构建：

```bash
docker images --format '{{.Repository}}:{{.Tag}} {{.Size}}' | grep php
```

### 调度器配置

调度器服务会根据环境以不同方式处理 Laravel 的任务调度：

**开发环境：**
- 使用 `php artisan schedule:work` 进行实时调度
- 自动检测并运行计划任务

**生产环境：**
- 使用 [Supercronic](https://github.com/aptible/supercronic) 实现可靠的 cron 执行
- 配置文件：`docker/php/config/schedule.cron`
- 每分钟运行一次 `php artisan schedule:run`

要在生产环境修改调度计划，请编辑 `docker/php/config/schedule.cron`：

```cron
* * * * * cd /srv && php artisan schedule:run >> /dev/null 2>&1
```

> **注意**：实际的计划任务请在 `app/Console/Kernel.php` 中使用 Laravel 的调度器定义。cron 文件只负责触发 Laravel 的调度器。

## 自定义

### 自定义域名

要使用自定义域名：

1. 在 `config/laradox.php` 或 `.env` 中更新域名：
   ```env
   LARADOX_DOMAIN=myapp.test
   ```

2. 生成 SSL 证书：
   ```bash
   php artisan laradox:setup-ssl --domain=myapp.test
   ```

3. 重启容器以应用域名变更：
   ```bash
   php artisan laradox:down
   php artisan laradox:up --detach
   ```

4. 将域名添加到你的 `/etc/hosts` 文件（如果不使用 .localhost 域名）

> **注意**：域名会通过环境变量自动配置到 Nginx 中，你无需手动编辑 `docker/nginx/conf.d/app.conf`。

### Docker 配置

你可以通过修改已发布的文件来自定义 Docker 环境：

- `docker-compose.development.yml` —— 开发环境
- `docker-compose.production.yml` —— 生产环境
- `docker/php/php.dockerfile` —— PHP/FrankenPHP 镜像
- `docker/nginx/nginx.conf` —— Nginx 配置
- `docker/nginx/conf.d/app.conf` —— 应用 server 块

## 故障排查

### 权限问题

如果遇到权限问题，请调整用户 ID：

```env
LARADOX_USER_ID=1000
LARADOX_GROUP_ID=1000
```

然后重建容器：

```bash
php artisan laradox:down --volumes
php artisan laradox:up --build --detach
```

### SSL 证书问题

重新安装 mkcert 并重新生成证书：

```bash
mkcert -uninstall
php artisan laradox:setup-ssl
```

### 端口冲突

如果 80/443 端口已被占用，请在 `.env` 中修改：

```env
LARADOX_HTTP_PORT=8080
LARADOX_HTTPS_PORT=8443
```

然后重启容器：

```bash
php artisan laradox:down
php artisan laradox:up --detach
```

### 容器已在运行

Laradox 会自动检测容器是否已在运行，并提示是否重启：

```bash
php artisan laradox:up
# 输出："⚠ Containers are already running!"
# 提示："Do you want to restart the containers?"
```

也可以手动停止再启动：

```bash
php artisan laradox:down
php artisan laradox:up --detach
```

## 生产环境：连接宝塔面板安装的 PostgreSQL / Redis

在 Aliyun ECS（Ubuntu）上，很多开发者会通过宝塔面板安装和管理 PostgreSQL 与 Redis。它们以宿主机原生服务的形式运行，并不在 Docker 容器内；而 Laradox 的应用栈（php、nginx、scheduler、queue）全部运行在 Docker Compose 容器中。本节说明如何让容器内的 Laravel 应用正确连接宿主机上的数据库与缓存服务。

**前提条件**：Laradox **v2.20.3+**。从该版本起，`docker-compose.production.yml` 已为 php / scheduler / queue 服务内置以下配置，将 `host.docker.internal` 解析到宿主机网关：

```yaml
extra_hosts:
  - "host.docker.internal:host-gateway"
```

这是 Linux Docker Engine 下的必需配置（Docker Desktop 自带该域名解析，Linux 原生 Engine 没有）。如果你仍在使用旧版本，请先升级 Laradox，或手动在 compose 文件的 php / scheduler / queue 三个服务下补上这段配置，否则容器内无法解析 `host.docker.internal`。

> **核心概念：容器内的 `127.0.0.1` 不是宿主机，而是容器自己。** 容器访问宿主机上运行的 PostgreSQL / Redis，必须使用 `host.docker.internal`。本节的所有配置都建立在这个前提上。

### 宝塔侧配置：放行 Docker 网段

默认配置下，PostgreSQL 只监听 `127.0.0.1`，Redis 也只绑定本机回环地址，容器发起的连接根本到不了服务。需要在宝塔面板中分别调整（路径参考：宝塔 → 软件商店 → 对应软件 → 设置 / 配置文件）。

**Redis**

编辑 Redis 配置文件：

```conf
# 原值为 bind 127.0.0.1，改为监听所有网卡
bind 0.0.0.0

# 必须设置强密码（见下文安全红线）
requirepass 你的强密码
```

保存后**重启 Redis 服务**。

**PostgreSQL**

1. 编辑 `postgresql.conf`，修改监听地址：

```conf
listen_addresses = '*'
```

2. 编辑 `pg_hba.conf`，在文件末尾追加一行，允许 Docker 默认网段（docker0 网桥，`172.17.0.0/16`）以密码方式连接：

```conf
# TYPE   DATABASE   USER   ADDRESS          METHOD
host     all        all    172.17.0.1/16    scram-sha-256
```

3. 保存后**重启 PostgreSQL 服务**。

> 提示：`172.17.0.1/16` 对应 Docker 默认网段。如果你自定义过 Docker 网络，请先在宿主机执行 `ip addr show docker0` 确认实际网段，再替换上述地址。

> 提示：`scram-sha-256` 认证需要 PostgreSQL 10 及以上版本；宝塔较新版本安装的 PostgreSQL 均已支持。若实例过旧无法使用，可临时改为 `md5`，但建议尽快升级。

两项服务都重启后，可在宿主机自检监听是否生效：

```bash
ss -tlnp | grep -E '5432|6379'
```

`Local Address:Port` 一列应显示 `0.0.0.0:5432` / `0.0.0.0:6379`（或 `*:5432`）。若仍是 `127.0.0.1:xxxx`，说明配置文件未生效或服务没有真正重启。

### 安全红线（务必逐条确认）

把端口从"仅本机监听"放开为"监听所有网卡"之后，安全防护必须同步跟上，否则等于把数据库暴露在公网：

1. **阿里云安全组绝对不要放行 5432 / 6379 的公网入方向**。请到阿里云控制台 → ECS → 安全组规则逐一核对，删除任何授权对象为 `0.0.0.0/0` 的 5432 / 6379 入方向规则。这两个端口只应被宿主机与 Docker 网段访问。
2. 若启用了 ufw 或宝塔防火墙，**仅允许 Docker 网段访问这两个端口**：

```bash
# 允许 Docker 默认网段访问 PostgreSQL 与 Redis
sudo ufw allow from 172.17.0.0/16 to any port 5432 proto tcp
sudo ufw allow from 172.17.0.0/16 to any port 6379 proto tcp
```

3. **Redis 必须设置 `requirepass`**，并使用强密码。未设密码的 Redis 一旦端口可被访问，等同于数据库被完全接管。
4. **PostgreSQL 用户必须使用强密码**，认证方式保持 `scram-sha-256`，不要改用 `trust`，也不要把超级用户账号交给应用连接。

### 项目 .env 配置

在项目根目录的 `.env` 中按如下方式配置：

```dotenv
DB_CONNECTION=pgsql
DB_HOST=host.docker.internal
DB_PORT=5432
DB_DATABASE=blog          # 宝塔里创建的库名
DB_USERNAME=blog          # 宝塔里创建的用户
DB_PASSWORD=强密码

CACHE_STORE=redis
QUEUE_CONNECTION=redis
SESSION_DRIVER=redis      # 可选

REDIS_CLIENT=phpredis
REDIS_HOST=host.docker.internal
REDIS_PORT=6379
REDIS_PASSWORD=强密码      # 宝塔 Redis 设置的 requirepass
```

注意：`DB_HOST` 与 `REDIS_HOST` 填 `host.docker.internal`。**不是** `127.0.0.1`（那是容器自己），也**不是**服务器公网 IP——流量经宿主机网关直达本机服务，不出公网；填公网 IP 不仅绕远路，还会把数据库流量暴露到外部网络路径上。

### 生效与验证

**1. 重建容器栈**

```bash
docker compose -f docker-compose.production.yml up -d
```

`extra_hosts` 属于容器创建参数，`restart` 不会重新加载，需要 `up -d` 让 Compose 按新定义重建受影响的容器。

**2. 验证容器到宿主机的连通性**

```bash
docker compose -f docker-compose.production.yml exec php ping -c1 host.docker.internal
```

能收到来自 `172.17.0.1` 的回复，即说明域名解析与路由正常。

**3. 执行迁移并确认数据库连接**

```bash
./php artisan migrate
./php artisan db:show
```

`db:show` 会列出当前连接的数据库名与表信息，正常输出即代表 PostgreSQL 连接成功。

**4. 验证 Redis 连接**

```bash
./php artisan tinker --execute='dump(Illuminate\Support\Facades\Redis::connection()->ping());'
```

返回 `true`（phpredis 客户端）即代表 Redis 连接与 `requirepass` 认证成功。

**5. 修改 `.env` 后重启应用容器**

```bash
docker compose -f docker-compose.production.yml restart php queue scheduler
```

Octane 与 queue worker 在进程启动时即缓存配置，仅 `reload` 不足以加载新的环境变量，必须 `restart`。

### 常见问题排查

- **Connection refused**：检查 Redis `bind` 与 PostgreSQL `listen_addresses` 是否已修改、服务是否真正重启过；可在宿主机执行 `ss -tlnp | grep -E '5432|6379'`，确认监听地址是 `0.0.0.0` 而非 `127.0.0.1`。
- **认证失败（password authentication failed）**：检查 `pg_hba.conf` 追加行的网段与实际 Docker 网段是否一致，密码是否与 `.env` 中一致。
- **容器内 ping 不通 `host.docker.internal`**：确认 Laradox 为 v2.20.3+，或已手动为 php / scheduler / queue 服务添加 `extra_hosts`；然后执行 `up -d` 重建容器（`restart` 无效）。
- **连接超时**：检查 ufw / 宝塔防火墙是否放行了来自 `172.17.0.0/16` 的连接，以及阿里云安全组是否误拦了内网方向流量。

---

如果以后想把数据库也容器化、收进 Laradox 栈统一管理，v2.20.3+ 的 compose 模板已内置 postgres / redis 服务定义（生产凭据必填），届时只需调整 `.env` 中的主机名并启用对应服务即可。

## 许可证

Laradox 是基于 [MIT 许可证](LICENSE)开源的软件。

## 测试

Laradox 包含覆盖全部功能的完整测试套件。所有测试必须通过，以确保正常运行。

### 运行测试

```bash
# 运行全部测试
composer test

# 运行并生成覆盖率报告
vendor/bin/phpunit --coverage-html build/coverage

# 运行指定的测试套件
vendor/bin/phpunit tests/Feature/
vendor/bin/phpunit tests/Unit/

# 运行指定的测试文件
vendor/bin/phpunit tests/Feature/InstallCommandTest.php
vendor/bin/phpunit tests/Unit/UpCommandTest.php
```

## 致谢

由 [Aditya Rizqi Januarta](https://github.com/adityarizqi) 创建

## 参与贡献

欢迎贡献代码！欢迎随时提交 Pull Request。