---
title: "Laravel Sail: структура на .env, пренасочване на портове, CI и локална среда срещу продукция | DevSense"
description: "Разделяне на конфигурацията на Laravel Sail и хост машината: .env.example, портове FORWARD_*, APP_URL в Docker, опционален env_file, GitHub Actions с docker compose и чек-листи преди стартиране."
faq:
- question: "Защо получавам грешка 'port already allocated' (портът вече е зает) при стартиране на sail up?"
answer: "Това се случва, когато друга услуга на хост машината (като локален MySQL или друг стартиран проект на Sail) вече използва този порт. Можете да решите това, като промените FORWARD_DB_PORT или APP_PORT в .env файла."
- question: "Трябва ли да коммитвам своя .env файл в Git?"
answer: "Не, никога не трябва да коммитвате .env. Той съдържа тайни и индивидуални настройки за разработчика. Вместо това поддържайте безопасни стойности по подразбиране в .env.example."
- question: "Как да заредя специфични за разработчика контейнерни настройки без да променям споделената конфигурация?"
answer: "Можете да посочите списък 'env_file' под вашата услуга в docker-compose.yml, за да заредите допълнителен локален файл (напр. .env.docker.local), който съдържа локални пренаписвания."
- question: "Мога ли да стартирам Laravel Sail на продукционен сървър?"
answer: "Не. Sail е проектиран за удобство при разработка и му липсват защити за продукция, TLS терминиране, системи за архивиране и оптимизации за мащабиране. Внедрявайте приложението с помощта на специализирани инструменти (например Kubernetes, Ansible или Laravel Forge)."
---
# Sail: среди и деплой
Вие коммитвате локален файл `.env`, съдържащ пароли за база данни в GitHub, и вашите скенери за сигурност незабавно задействат предупреждение. Или колега изтегля вашето хранилище, стартира `sail up` и вижда как процесът се срива, тъй като неговият локален MySQL порт `3306` вече е зает от друг проект. Управлението на средите не е просто дефиниране на двойки ключ-стойност; то е за прокарване на строга граница между локалното удобство, CI/CD тестването и защитените продукционни среди.
Контейнеризираната разработка променя начина, по който се държат променливите на средата. Тъй като PHP работи вътре в контейнера `laravel.test`, докато базите данни се свързват с хост портове, пътищата, URL адресите и мапингите на портове трябва да се адаптират в зависимост от това дали се достъпват от хост машината или от мрежата на Docker Compose.
В това ръководство ще ви покажем как да структурирате `.env` файловете, да избягвате конфликти на портове на хоста, да настройвате CI пайплайни на базата на Docker и да проверявате конфигурациите си преди качване в продукция.
**Навигация:** [Всички инструменти](../) · [Sail обзор](sail#what-sail-is) · [Бази данни](sail-databases#networking) · [Опашки](sail-queues#connections) · [Диагностика](sail-troubleshooting#wsl-filesync)
## Съдържание
* [`.env`, `.env.example` и тайни](#env-files)
* [Портове `FORWARD_*` и конфликти](#forward-ports)
* [`APP_URL` и доверени проксита](#app-url)
* [Опционален `env_file` в Compose](#compose-env-file)
* [CI: Шаблон за GitHub Actions](#ci-example)
* [Sail срещу среди за разработка/staging/prod](#not-production)
* [Чек-лист преди пускане в експлоатация](#checklist)
* [Чести грешки](#common-mistakes)
* [Въпроси за самопроверка](#self-check)
---
## `.env`, `.env.example` и тайни
- **`.env`**: Съхранява локалните тайни и настройки на средата. **Никога не коммитвайте този файл в системата за контрол на версиите.**
- **`.env.example`**: Коммитва се в Git. Стойностите по подразбиране трябва да представляват безопасни локални настройки, така че нов разработчик да може да копира файла в `.env` и веднага да стартира проекта с `sail up`.
```dotenv
# .env.example
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
# Настройки за портове в Sail
FORWARD_DB_PORT=3306
FORWARD_REDIS_PORT=6379
```
---
## Портове `FORWARD_*` и конфликти
По подразбиране Sail свързва портовете на базата данни и уеб сървъра към localhost на вашия компютър. Ако стартирате няколко проекта едновременно, портове като `3306` (MySQL) или `80` (HTTP) ще се дублират.
За да поправите това, променете пренасочените портове в `.env`:
```dotenv
# .env
APP_PORT=8080
FORWARD_DB_PORT=3307
FORWARD_REDIS_PORT=6380
```
> [!NOTE]
> **Вътрешни срещу външни портове**
> Промяната на `FORWARD_DB_PORT` променя порта, който се достъпва от вашата хост машина. Вътре в Docker мрежата базата данни все още комуникира по стандартния си порт `3306`. Конфигурацията на Laravel не изисква промяна на `DB_PORT`.
---
## `APP_URL` и доверени проксита
Laravel използва `APP_URL` за генериране на подписани адреси и пренасочвания.
```dotenv
# .env
APP_URL=http://localhost:8080
```
Уверете се, че този адрес съответства на порта, пробросен към вашия хост. При внедряване зад балансиращо устройство или обратно прокси (като Nginx или Traefik) в продукция, конфигурирайте `TrustProxies` в Laravel за правилно разчитане на оригиналния IP и протокол (HTTPS) на клиента.
---
## Опционален `env_file` в Compose
Ако имате променливи на средата, които се прилагат единствено в Docker средата, можете да ги заредите в `docker-compose.yml`:
```yaml
# docker-compose.yml
services:
laravel.test:
env_file:
- .env
- .env.docker.local
```
Това предотвратява запълването на общия `.env` файл с променливи, които имат значение само вътре в контейнерите.
---
## CI: Шаблон за GitHub Actions
Можете да използвате Docker Compose услугите на Sail във вашия CI/CD конвейер, за да изпълнявате автоматизирани тестове в чиста среда.
```yaml
# .github/workflows/tests.yml
name: Run Tests
on: [push]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Copy CI Env
run: cp .env.ci .env
- name: Start Sail
run: docker compose up -d
- name: Run Pest/PHPUnit
run: docker compose exec -T laravel.test php artisan test
```
---
## Sail срещу среди за разработка/staging/prod
- **Sail** е оптимизиран за бързина при локална разработка (включва инструменти като Mailpit, Meilisearch и проследяване на промени по файловете).
- **Staging/Production** средите изискват засилена сигурност, агрегиране на логове, автоматично архивиране, SSL/TLS сертификати и отделни сървъри за БД (напр. AWS RDS).
> [!NOTE]
> Никога не се опитвайте да стартирате `sail up` на публичен сървър. Конфигурацията по подразбиране е небезопасна и отваря достъп до служебни инструменти отвън.
---
## Чек-лист преди пускане в експлоатация
- [ ] Включени `APP_ENV=production` и `APP_DEBUG=false` на продукционния сървър.
- [ ] Генериран сигурен `APP_KEY` с `php artisan key:generate`.
- [ ] Свързване с облачна база данни вместо с локален контейнер.
- [ ] `QUEUE_CONNECTION` е настроен на `redis` или `sqs` под управлението на Supervisor.
- [ ] Активиран SSL/HTTPS.
- [ ] Конфигурирани външни системи за логване (напр. Sentry или Bugsnag).
---
## ⚠️ Чести грешки
**1. Коммитване на `.env` файла в Git**
Разкриване на API ключове, пароли за бази данни и секрети в историята на Git хранилището.
*Решение:* Винаги проверявайте дали `.env` е добавен във вашия `.gitignore` файл преди коммит.
**2. Промяна на `DB_PORT` вместо на `FORWARD_DB_PORT` при локални конфликти**
Промяната на `DB_PORT=3307` в `.env` без промяна в Compose файла ще счупи вътрешната връзка, тъй като базата данни в контейнера все още работи на `3306`.
*Решение:* Запазете `DB_PORT=3306` (за вътрешна връзка) и конфигурирайте `FORWARD_DB_PORT=3307` (за външния порт на хост компютъра).
**3. Директно използване на `docker-compose.yml` на Sail в продукция**
Стартиране на бази данни в контейнери без репликация, бекапи и сигурни политики за достъп.
*Решение:* Конфигурацията на Sail е локален инструмент за разработка, а не манифест за деплой.
---
## 🧠 Въпроси за самопроверка
1. **Защо промяната на `DB_PORT=3307` в `.env` чупи миграциите в Sail, докато промяната на `FORWARD_DB_PORT=3307` работи коректно?**
2. **Какъв е рискът за сигурността при внедряване на Compose файла на Sail директно на публичен сървър?**
3. **Как използването на секцията `env_file` в `docker-compose.yml` помага за структурирането на настройките на проекта?**
4. **Кой файл трябва да актуализирате, за да уведомите колегите си за добавянето на нов задължителен API ключ?**
Покажи отговорите
1. Промяната на `DB_PORT` кара Laravel да търси базата данни на порт `3307` във вътрешната мрежа на контейнерите, където базата все още слуша на `3306`. Промяната на `FORWARD_DB_PORT` променя само външния порт, предоставен на хост машината, без да засяга вътрешните връзки на Docker.
2. Това ще изложи на публичен достъп помощни dev инструменти (Mailpit, Meilisearch), базите данни ще работят без архивиране и репликация, а контейнерите ще имат излишни права за достъп.
3. Позволява ви да разделите променливите си в множество файлове (например `.env` и `.env.docker.local`), като зареждате специфични за Docker настройки, без да претрупвате основната конфигурация.
4. Трябва да актуализирате `.env.example`, като добавите новото име на параметъра с празна стойност-плейсхолдър.