fix(core,installer): dev vendor 설치본의 코어 업데이트 중단 수정 — stale 패키지 매니페스트 3계층

Laravel PackageManifest 는 bootstrap/cache/packages.php 가 있으면 stale 여부를 검사하지
않고 그대로 읽어 등재된 provider 를 new 한다. 코어 업데이트는 Step 6/8 에서 vendor 를
--no-dev 로 교체하지만 그 파일은 Step 11 까지 이전 설치본의 것이 남으므로, 옵션 없는
`composer install` 로 깔린 사이트에서는 Step 10 spawn 자식이 새 vendor 에 없는 provider 를
찾다 부팅 단계에서 죽는다. 부팅 전이라 앱 로그에 흔적이 없고 부모에게는 자식의 비정상
종료로만 보여, 운영자에게는 「Class ... not found」 와 수동 재개 안내만 남는다.
(sir.kr 커뮤니티 제보, 7.0.9 → 7.0.10)

3계층으로 막는다.

 1. 부모 — spawn 직전 PackageManifestCacheHelper::clear
 2. 자식 — bootstrap/app.php 가 G7_UPDATE_IN_PROGRESS 를 보고 스스로 정리한다.
 이미 배포된 7.0.9·7.0.10 부모는 고칠 수 없으므로 그 아래에서 도는 신버전
 자식의 유일한 방어다. App\ 클래스를 참조하지 않고 실패는 무시한다.
 3. 범위 — CoreVersionChecker 의 env APP_VERSION 우선을 CoreUpdateContext 트리 안으로
 축소한다. 업데이트 전에 뜬 artisan serve·큐 워커가 옛 값을 물고 확장을
 incompatible_core 로 끄던 경로를 닫는다(관리자 템플릿이 대상이면 복구 UI
 자체에 도달할 수 없다).

업데이트 트리 판정은 App\Support\CoreUpdateContext 가 단독 소유하고
CoreServiceProvider::isCoreUpdateInProgress 는 위임으로 남는다. bootstrap/app.php 의
복제본은 부팅 전이라 불가피한 예외이며, 두 조건의 동형성을 테스트가 단언한다.

실측 중 드러난 결함 2건을 함께 고쳤다.

 - ConfigCacheHelper::withPreservedContainer 가 파사드 애플리케이션을 되돌리지 않아
 Step 11 이 `Target class [command.tinker] does not exist` 로 실패·롤백했다.
 - updateVersionInEnv 가 프로세스 환경을 갱신하지 않아 config 캐시에 이전 버전이 구워졌다
 (Laravel env 저장소가 불변이라 재부팅으로도 덮이지 않는다).

인스톨러는 재사용 vendor 의 개발용 패키지를 installed.json 으로 감지해 설치 환경 확인
카드·설치 로그로 알리되 설치를 차단하지 않고( 결정 D1), 재사용 경로에서도 컴파일 캐시를
정리한다. 실행되는 명령만이 아니라 실패 시 안내하는 수동 명령까지 --no-dev 로 맞췄다.
코어 업데이트 완료·핸드오프·단독 재개 사후 단계에서 queue:restart 신호를 보낸다(D3).

코어 7.0.10 → 7.0.11.
This commit is contained in:
HeuJung committed 2026-09-08 09:46:57 +09:00
1 parent 21177c8e17
commit ffab451b4a
42 files changed
+2660 -82

No files matched your search

+93
View File
@@ -0,0 +1,93 @@
<?php
namespace App\Support;
/**
* vendor 디렉토리가 개발용(require-dev 포함) 설치인지 판정하는 유틸리티.
*
* `composer install`(옵션 없음)은 require-dev 와 그 전이 의존성까지 설치하고, 그 목록이
* `bootstrap/cache/packages.php` 에 provider 로 등재된다. 운영 사이트가 그 상태로 남으면
* 이후 코어 업데이트가 vendor 를 `--no-dev` 로 교체할 때 매니페스트에만 남은 provider 를
* 찾다 부팅이 깨진다. 그래서 인스톨러와 코어 업데이트가 이 판정으로 운영자에게 알린다.
*
* 프레임워크에 의존하지 않는다 — 인스톨러는 Laravel 오토로드 없이 도는 순수 PHP 라
* 이 클래스를 `require_once` 로 직접 읽는다.
*/
final class ComposerInstallInfo
{
/**
* vendor 디렉토리 기준 Composer 설치 정보 파일의 상대 경로
*/
public const INSTALLED_JSON = 'composer/installed.json';
/**
* vendor 디렉토리의 Composer 설치 구성을 조사합니다.
*
* 판정: `installed.json` 의 최상위 `dev` 가 true 이거나 `dev-package-names` 가 비어 있지
* 않으면 개발용 설치. 두 신호를 OR 로 보는 이유는 Composer 버전에 따라 한쪽만 채워질 수
* 있기 때문이다.
*
* @param string $vendorPath vendor 디렉토리 절대 경로
* @return array{dev: bool|null, packages: array<int, string>} dev 가 null 이면 판정 불가
* (파일 부재 · JSON 오류 · Composer 1 형식)
*/
public static function inspect(string $vendorPath): array
{
$unknown = ['dev' => null, 'packages' => []];
$path = rtrim($vendorPath, '/\\').'/'.self::INSTALLED_JSON;
if (! is_file($path)) {
return $unknown;
}
$raw = @file_get_contents($path);
if ($raw === false || $raw === '') {
return $unknown;
}
$decoded = json_decode($raw, true);
// Composer 1 은 최상위가 패키지 배열이라 dev 정보 자체가 없다 — 판정 불가로 둔다.
if (! is_array($decoded) || ! array_key_exists('packages', $decoded)) {
return $unknown;
}
$names = [];
if (isset($decoded['dev-package-names']) && is_array($decoded['dev-package-names'])) {
foreach ($decoded['dev-package-names'] as $name) {
if (is_string($name) && trim($name) !== '') {
$names[] = $name;
}
}
}
$devFlag = $decoded['dev'] ?? null;
return [
'dev' => $devFlag === true || $names !== [],
'packages' => $names,
];
}
/**
* vendor 가 개발용 설치인지 반환합니다.
*
* @param string $vendorPath vendor 디렉토리 절대 경로
* @return bool|null 판정 불가 시 null
*/
public static function isDevInstall(string $vendorPath): ?bool
{
return self::inspect($vendorPath)['dev'];
}
/**
* vendor 에 설치된 개발용(require-dev) 패키지 이름 목록을 반환합니다.
*
* @param string $vendorPath vendor 디렉토리 절대 경로
* @return array<int, string> 개발용 패키지가 없거나 판정 불가면 빈 배열
*/
public static function devPackageNames(string $vendorPath): array
{
return self::inspect($vendorPath)['packages'];
}
}
+30 -8
View File
@@ -4,6 +4,7 @@ namespace App\Support;
use Illuminate\Container\Container;
use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\Facade;
use Illuminate\Support\Facades\File;
use Illuminate\Support\Facades\Log;
@@ -62,26 +63,47 @@ class ConfigCacheHelper
}
/**
* 콜백 실행 뒤 전역 컨테이너 인스턴스를 원래 앱으로 되돌립니다.
* 콜백 실행 뒤 전역 컨테이너 인스턴스와 파사드 애플리케이션을 원래 앱으로 되돌립니다.
*
* `config:cache` 는 신선한 설정을 얻기 위해 **새 Application 을 부팅**하는데, `Application` 생성자가
* `Container::setInstance()` 를 호출하므로 그 순간부터 `app()` 헬퍼가 실행 중인 앱이 아니라 그
* 일회용 앱을 가리킨다(파사드는 별도 참조라 그대로다). 같은 프로세스에서 그 뒤에 등록되는
* `app()->terminating()` 콜백은 종료되지 않는 앱에 걸려 **영원히 실행되지 않는다** — 설정 저장
* 뒤의 확장 캐시 버전 bump 가 예약한 정적 재게시가 그렇게 조용히 사라졌다(#651 F5 실측: 버전은
* 올랐는데 게시는 다음 렌더의 자가 치유까지 미뤄짐). 예외도 로그도 없고, 자가 치유가 한 렌더
* 뒤에 덮어 주므로 "한 박자 늦게 반영" 으로만 나타난다.
* `config:cache` 는 신선한 설정을 얻기 위해 **새 Application 을 부팅**하는데, 그 부팅이 전역 상태를
* 두 군데 바꾼다.
*
* 1. `Application` 생성자의 `Container::setInstance()` — 그 순간부터 `app()` 헬퍼가 실행 중인 앱이
* 아니라 일회용 앱을 가리킨다. 같은 프로세스에서 그 뒤에 등록되는 `app()->terminating()` 콜백은
* 종료되지 않는 앱에 걸려 **영원히 실행되지 않는다** — 설정 저장 뒤의 확장 캐시 버전 bump 가
* 예약한 정적 재게시가 그렇게 조용히 사라졌다(#651 F5 실측: 버전은 올랐는데 게시는 다음 렌더의
* 자가 치유까지 미뤄짐).
* 2. `registerBaseBindings()` 의 `Facade::clearResolvedInstances()` + `Facade::setFacadeApplication()`
* — 그 순간부터 **모든 파사드**(`Artisan`·`Log`·`DB`·`Cache` …)가 일회용 앱에서 새 인스턴스를
* 해석한다. 컨테이너만 되돌리면 이 축이 남는다.
*
* 2번이 코어 업데이트에서 드러난 형태: Step 11 의 `ConfigCacheHelper::rebuild()` 뒤에 오는
* `RouteCacheHelper::rebuild()` 의 `Artisan::call('route:clear')` 가 일회용 앱에서 **새 콘솔 Kernel** 을
* 해석하고, 그 Kernel 은 콘솔 Application 을 처음부터 구성하며 등록된 커맨드를 전부 resolve 한다.
* 부팅 시점 vendor 가 개발용이었다면 그 목록에 `command.tinker` 같은 require-dev 커맨드가 들어
* 있는데, Step 8 이 vendor 를 `--no-dev` 로 이미 교체했으므로 그 클래스가 없어
* `Target class [command.tinker] does not exist.` 로 업데이트 전체가 실패·롤백한다
* (2026-09-07 7.0.9 → 7.0.11 실측). 프로세스에 이미 등록된 provider 목록은 vendor 교체로 갱신되지
* 않으므로, 방어는 "교체 뒤에 콘솔 Application 을 다시 구성하지 않는 것" 이다.
*
* @param callable $callback 전역 인스턴스를 바꿔 놓을 수 있는 작업
*/
public static function withPreservedContainer(callable $callback): void
{
$app = Container::getInstance();
$facadeApp = Facade::getFacadeApplication();
try {
$callback();
} finally {
Container::setInstance($app);
// 일회용 앱이 남긴 파사드 해석 결과를 버리고 원래 앱으로 되돌린다.
// 순서 주의: clear 를 먼저 해야 일회용 앱에서 해석된 인스턴스가 캐시에 남지 않는다.
Facade::clearResolvedInstances();
if ($facadeApp !== null) {
Facade::setFacadeApplication($facadeApp);
}
}
}
+63
View File
@@ -0,0 +1,63 @@
<?php
namespace App\Support;
/**
* 현재 PHP 프로세스가 코어 업데이트 프로세스 트리 안에 있는지 판정하는 단일 SSoT.
*
* 코어 업데이트는 부모 `core:update` 가 `core:execute-upgrade-steps` 를 `proc_open` 으로
* spawn 하고, 그 자식이 다시 `config:cache` 등으로 일회용 Application 을 부팅하는 다층 구조다.
* 이 트리 안에서만 켜져야 하는 예외 동작이 여럿이라(확장 자동 비활성화 스킵, 코어 버전의
* env 우선 판독, `bootstrap/app.php` 의 패키지 매니페스트 자가 치유) 판정이 흩어지면
* 한 곳만 어긋나도 그 경로가 조용히 다르게 동작한다 — 판정을 여기 한 곳에 둔다.
*
* 판정 채널이 둘인 이유: `G7_UPDATE_IN_PROGRESS` env 는 부모가 세우고 spawn 자식에게
* `$env` 로 전파되지만, `variables_order` 에 `E` 가 없는 호스팅에서는 `$_ENV` 가 비어 있을 수
* 있어 argv 보조 판정을 함께 둔다.
*
* 주의: `bootstrap/app.php` 의 자가 치유 블록은 부팅 전이라 이 클래스를 참조할 수 없어
* 같은 판정을 순수 PHP 로 복제한다. 조건을 바꾸면 그쪽도 함께 고친다.
*/
final class CoreUpdateContext
{
/**
* 코어 업데이트를 수행하는 artisan 커맨드 이름 (argv 보조 판정용)
*/
private const UPDATE_COMMANDS = ['core:update', 'core:execute-upgrade-steps'];
/**
* 현재 프로세스가 코어 업데이트 트리(부모 core:update 또는 그 spawn 자식) 안에 있는지 판정합니다.
*
* 판정 조건 (OR):
* 1. 환경변수 `G7_UPDATE_IN_PROGRESS=1` — 부모가 시작 시 설정하고 spawn 자식에 전파
* 2. artisan 커맨드 이름이 `core:update` / `core:execute-upgrade-steps` — 1 이 전파되지
* 않은 극단 상황 대비 보조 판정
*
* @return bool 업데이트 트리 안이면 true
*/
public static function isInProgress(): bool
{
if (self::hasEnvFlag()) {
return true;
}
$argv = $_SERVER['argv'] ?? [];
return in_array($argv[1] ?? '', self::UPDATE_COMMANDS, true);
}
/**
* `G7_UPDATE_IN_PROGRESS=1` 환경변수 플래그만 확인합니다 (argv 보조 판정 없음).
*
* spawn 자식 여부를 가려야 하는 지점(자식은 사전·사후 단계를 부모에 위임)에서 쓴다.
* argv 판정을 섞으면 `core:execute-upgrade-steps` 단독 실행이 자식으로 오판된다.
*
* @return bool env 플래그가 켜져 있으면 true
*/
public static function hasEnvFlag(): bool
{
$flag = $_ENV['G7_UPDATE_IN_PROGRESS'] ?? $_SERVER['G7_UPDATE_IN_PROGRESS'] ?? getenv('G7_UPDATE_IN_PROGRESS');
return $flag === '1' || $flag === 1 || $flag === true;
}
}
@@ -0,0 +1,60 @@
<?php
namespace App\Support;
use Illuminate\Support\Facades\Artisan;
/**
* 패키지 매니페스트 캐시(bootstrap/cache/packages.php · services.php) 정리·재생성 헬퍼.
*
* Laravel 의 `PackageManifest::getManifest()` 는 `packages.php` 가 존재하면 stale 여부를
* 검사하지 않고 그대로 읽고, `ProviderRepository::load()` 가 거기 등재된 eager provider 를
* `new` 한다. 그래서 vendor 를 교체한 뒤 그 파일을 남겨 두면 다음에 부팅하는 프로세스가
* 새 vendor 에 없는 클래스를 찾다 **부팅 단계에서** 죽는다 — 앱 로그가 아직 열리기 전이라
* 예외도 남지 않고, 부모 프로세스에는 자식의 비정상 종료로만 보인다.
*
* `ConfigCacheHelper`/`RouteCacheHelper` 와 같은 자리의 헬퍼로, vendor 를 바꾼 뒤 새 PHP
* 프로세스를 띄우는 지점이 이 헬퍼를 경유한다. 삭제 로직을 호출부마다 `@unlink` 로 복제하면
* 한 곳만 빠져도 그 경로가 조용히 옛 매니페스트로 부팅한다.
*/
class PackageManifestCacheHelper
{
/**
* 패키지 매니페스트 캐시 두 파일을 삭제합니다 (재생성 없음).
*
* 경로는 `Application` 의 게터로 읽어 `APP_PACKAGES_CACHE`/`APP_SERVICES_CACHE` 환경변수
* 재지정을 존중한다(테스트 격리가 이 경로 재지정에 의존한다).
*
* 삭제 실패(권한 · Windows 파일 핸들 점유)는 치명적이지 않다 — 종전 상태로 남을 뿐이며
* 코어 업데이트의 마지막 단계(`clearAllCaches()`)가 다시 시도한다.
*
* @return void
*/
public static function clear(): void
{
$app = app();
foreach ([$app->getCachedServicesPath(), $app->getCachedPackagesPath()] as $path) {
if (is_file($path)) {
@unlink($path);
}
}
clearstatcache();
}
/**
* 패키지 매니페스트 캐시를 비우고 현재 vendor 기준으로 다시 만듭니다.
*
* `package:discover` 는 새 Application 을 부팅하지 않으므로(현재 앱의 `PackageManifest` 를
* 그대로 쓴다) `ConfigCacheHelper::withPreservedContainer()` 로 감쌀 필요가 없다.
*
* @return void
*/
public static function rebuild(): void
{
self::clear();
Artisan::call('package:discover');
}
}