gper/Gnuboard7

0 Fork 0

Files

T

HeuJung fa8eba7a0d v7.0.0-beta.2 release

2026-04-20 20:37:49 +09:00

20 KiB

Raw Permalink Blame History

업그레이드 스텝 작성 가이드 (Upgrade Step Guide)

버전 업그레이드 시 실행되는 upgrades/Upgrade_X_Y_Z.php 작성 규정

TL;DR (5초 요약)

1. upgrade step 이 실행되는 환경은 경로에 따라 다르다 — 섹션 9 "업그레이드 경로" 먼저 읽기
2. 대부분의 코어 upgrade step = 경로 B (spawn) → 신규 클래스/메서드 자유 사용 가능
3. 인프라 재설계 릴리즈의 특수 경로 = 경로 C → docblock 에 `@upgrade-path C` 선언 + 로컬 로직 필수
4. 경로 A (모듈/플러그인) · 경로 C 규율: 기존 클래스의 신규 메서드 호출 금지, 로컬 private 헬퍼 우선
5. 모든 분기에 upgrade.log 출력 — 로그 없음 = 디버깅 단서 없음

1. 배경 — 왜 이 가이드가 필요한가

php artisan core:update 실행 흐름:

Step 7  applyUpdate         — 디스크의 app/**, config/**, upgrades/** 파일을 새 버전으로 덮어쓰기
Step 8  Composer / vendor   — 외부 프로세스 실행으로 vendor 재구성
Step 9  runMigrations       — DB 마이그레이션
Step 10 runUpgradeSteps     — upgrades/Upgrade_*.php 의 run() 호출 ← 여기
Step 11 Cleanup             — 캐시 초기화, 소유권 복원 등

주의: Step 10 시점에 실행되는 PHP 프로세스는 Step 1 부터 시작한 "이전 버전" 프로세스 이다. applyUpdate 로 디스크 파일이 모두 새 버전으로 바뀌어도, 이미 메모리에 로드된 클래스는 재로드되지 않는다.

즉:

require_once 되는 upgrade 파일 자체 → 신규 파일이므로 새 코드 로드 OK
upgrade 파일 안에서 참조하는 다른 클래스 → 이미 메모리에 있는 이전 버전 클래스를 사용

2. PHP 클래스 캐싱 제약

작동 원리

PHP 는 클래스를 한 번 로드하면 동일 프로세스 내에서 재정의 불가. Laravel 의 Composer autoloader 도 마찬가지 — 네임스페이스·클래스명 매핑이 캐시된 뒤에는 파일 교체가 무시된다.

구체 시나리오

이전 버전에서 App\Extension\Helpers\FilePermissionHelper 가 이미 사용되어 메모리에 로드된 상태에서:

// upgrades/Upgrade_X_Y_Z.php (새 버전 파일)
use App\Extension\Helpers\FilePermissionHelper;

// 새 버전에서 신설한 메서드
FilePermissionHelper::newMethod();
// → Call to undefined method FilePermissionHelper::newMethod() Fatal

디스크의 FilePermissionHelper.php 는 새 버전으로 바뀌어 newMethod() 가 정의되어 있어도, PHP 는 메모리의 이전 버전 클래스 를 사용하므로 Fatal.

영향 받지 않는 대상

신규 추가된 클래스 (이전 버전에 존재하지 않던 파일) → autoload 시 새 코드 로드
예: App\Models\NotificationDefinition 가 beta.2 에서 처음 도입된 경우, beta.1 → beta.2 upgrade step 에서 사용 가능

영향 받는 대상

이미 이전 버전에 존재하던 클래스에 새로 추가된 메서드/프로퍼티
이미 이전 버전에 존재하던 클래스의 시그니처 변경

3. 작성 규칙

원칙 1 — 로컬 private 로직 우선

upgrade step 이 필요로 하는 로직은 Upgrade 클래스 내부 private 메서드 로 직접 작성한다. 공용 Helper 에 유사 로직이 있더라도 이전 버전에 없는 메서드 라면 호출 금지.

class Upgrade_7_0_0_beta_2 implements UpgradeStepInterface
{
    public function run(UpgradeContext $context): void
    {
        $this->restoreVendorOwnership($context);
    }

    // ✅ 로컬 private 메서드 — 메모리의 이전 버전 클래스와 무관
    private function restoreVendorOwnership(UpgradeContext $context): void
    {
        // 로직 인라인 작성
    }
}

원칙 2 — 프레임워크/기존 클래스만 use

use 문은 아래 범주만 허용:

Illuminate\* (Laravel 프레임워크)
App\Contracts\Extension\UpgradeStepInterface, App\Extension\UpgradeContext
이전 버전에도 이미 존재하던 App\Models\*, App\Services\* 등
새 버전에서 처음 도입된 클래스 (예: 새 Seeder, 새 Model)

원칙 3 — 모든 분기에 upgrade.log 출력

upgrade step 의 로거는 storage/logs/upgrade-YYYY-MM-DD.log 에 기록된다. 조기 return 경로에도 이유를 명시 하는 로그를 남긴다.

if ($currentOwner === $expectedOwner) {
    $context->logger->info('[X.Y.Z] 이미 일치 — 복원 스킵');
    return;
}

로그 없음은 디버깅 불가를 의미한다. 실패 보고를 받았을 때 어느 분기에서 return 됐는지 추적할 수 없으면 원인 파악에 많은 시간이 소요된다.

원칙 4 — 멱등성 보장

upgrade step 은 동일 버전으로 재실행될 수 있다(--force 옵션). 어떤 분기에서든 반복 실행이 안전해야 한다.

파일 생성 전 File::exists() 체크
테이블/컬럼 조작 전 Schema::hasTable/hasColumn 체크
데이터 이관은 "이미 이관됨" 플래그로 skip 가능하게 설계

4. 허용/금지 패턴

❌ 금지 — 기존 클래스의 신규 메서드 호출

use App\Extension\Helpers\FilePermissionHelper;

// FilePermissionHelper 는 이전 버전에도 존재 → 메모리에 구 클래스 로드됨
// inferWebServerOwnership() 가 새 버전에서 신설된 메서드라면 Fatal
FilePermissionHelper::inferWebServerOwnership();

✅ 허용 — 로컬 헬퍼로 직접 구현

private function inferWebServerOwnershipLocal(): array
{
    $baseOwner = @fileowner(base_path());
    $candidates = ['storage/logs', 'storage/framework/views', /* ... */];

    foreach ($candidates as $candidate) {
        $owner = @fileowner(base_path($candidate));
        if ($owner !== false && $owner !== $baseOwner) {
            return [$owner, @filegroup(base_path($candidate)), $candidate];
        }
    }

    return [$baseOwner, @filegroup(base_path()), 'base_path'];
}

❌ 금지 — 기존 Model 의 신규 메서드/스코프 호출

use App\Models\User;

// User 가 이전 버전에도 존재 → 메모리 구 클래스
// 새 버전에서 추가된 scope 는 Fatal
User::scopeNewlyAdded()->get();

✅ 허용 — DB 파사드로 직접 쿼리

use Illuminate\Support\Facades\DB;

DB::table('users')->where(/* ... */)->get();

✅ 허용 — 새 버전에서 처음 도입된 클래스

// 새 버전에서 처음 추가된 Seeder
use Database\Seeders\NotificationDefinitionSeeder;

(new NotificationDefinitionSeeder())->run();

✅ 허용 — 프레임워크 파사드

use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\File;
use Illuminate\Support\Facades\Schema;
use Illuminate\Support\Facades\DB;

5. 체크리스트

upgrade step PR 검토 시 아래 항목을 모두 확인:

use App\* 중 이전 버전에 이미 존재하던 클래스의 새 버전에서 신설된 메서드·프로퍼티 호출이 없는가?
필요한 로직이 로컬 private 메서드로 작성되어 있는가?
모든 return 분기에 upgrade.log 메시지가 있는가?
--force 재실행 시 안전한 멱등 동작인가?
sudo 실행 환경에서 root 오염이 발생할 수 있는 파일 조작이 있다면 소유권 복원 로직이 포함되었는가?
테스트 환경(beta.N fresh → beta.N+1 update) 에서 수동 검증을 통과했는가?

6. sudo 환경 / 소유권 고려사항

sudo php artisan core:update 실행 시:

외부 프로세스(composer 등) 가 root 로 파일을 생성
파일 시스템 API(File::copy, mkdir 등) 도 root 소유로 생성
원본 소유자(www-data 등) 를 보존하려면 업데이트 후 명시적 chown 필요

beta.2 이후 버전은 CoreUpdateService::snapshotOwnership() + restoreOwnership() 공통 로직이 Step 11 Cleanup 에서 자동 수행. upgrade step 에서 별도 소유권 복원이 필요한 예외 상황(이전 버전에 해당 로직이 없음) 에서만 인라인 작성.

7. 생명주기와 제거 시점

각 upgrade step 은 해당 버전에서만 필요한 1회성 작업 을 담당한다. 일반적으로 다음 버전(N+2) 릴리즈 시점에 제거 가능 — 단 아래 조건을 모두 만족해야:

N → N+1 업그레이드를 수행해야 하는 사용자가 더 이상 없음
또는 N → N+2 직접 업그레이드를 공식적으로 미지원
upgrade step 이 수행한 DB/파일 정리가 새 설치에서는 불필요함

제거 시 upgrade 파일 자체를 삭제하면 된다. upgrade step 내부에서 참조했던 "공용 Helper 메서드" 는 다른 용도로 재사용될 수 있으므로 별도 판단.

8. 실전 사례

사례 A — beta.2 MailTemplate shim (클래스 캐싱 회피)

beta.1 의 CoreUpdateService::syncCoreMailTemplates() 가 App\Models\MailTemplate::where(...) 를 호출하는데, beta.2 에서 MailTemplate 이 제거되어 autoload 실패.

해결: beta.2 릴리즈에 App\Models\MailTemplate 의 극소 shim 을 포함. beta.2 upgrade step 에서 shim 파일과 테이블 자가 정리.

이 경우 shim 파일은 "upgrade step 의 의존성" 이지만 이전 버전(beta.1) 이 메모리에 올리는 대상 이므로 upgrade step 밖의 신규 파일로 작성되어야 했다. upgrade step 내부에서 class_exists 체크만으로 충분.

사례 B — vendor 소유권 복원 (sudo + 비대칭 환경)

beta.1 의 runComposerInstall(base_path()) 가 sudo 에서 vendor/ 를 root 로 재생성. beta.2 upgrade step 이 storage/ 디렉토리 기준으로 원본 웹서버 계정(www-data) 을 추정하여 vendor/ 복원.

여기서 FilePermissionHelper::inferWebServerOwnership() 을 호출했다가 beta.1 메모리 클래스 캐싱으로 undefined method Fatal 발생. 로컬 private 메서드로 재작성하여 해결.

이 사례가 본 가이드 작성의 직접 계기다. "공용 Helper 로 승격" 은 신규 버전 코드 기반에서만 안전 이라는 교훈.

9. 업그레이드 경로별 규율

본 가이드의 많은 규칙은 "upgrade step 이 이전 버전 PHP 프로세스 메모리에서 실행된다" 는 전제에서 출발한다. 하지만 그누보드7 에는 서로 다른 실행 환경을 가진 3개 경로 가 공존하므로, 자신이 작성하는 upgrade step 이 어느 경로인지 먼저 확인해야 한다.

경로 A — 모듈/플러그인 upgrade step (기존 규율 유지)

실행 주체: ModuleManager::updateModule() / PluginManager::updatePlugin()
실행 환경: 메인 PHP 프로세스 (Artisan 커맨드가 로드된 상태)
단, reloadModule/reloadPlugin 이 evalFreshModule 로 진입점 클래스만 재로드 (app/Extension/ModuleManager.php 의 evalFreshModule, PluginManager.php 의 evalFreshPlugin 참조)
진입점 메서드(getPermissions/getMenus 등)는 재로드 덕분에 최신 정의 반환
하지만 그 외 App* 클래스(Helper, Service, Model)는 여전히 이전 버전 메모리
적용 규율: 섹션 3~5 의 모든 작성 규칙 적용. 로컬 private 헬퍼 우선, 기존 클래스의 신규 메서드 호출 금지

경로 B — 코어 upgrade step (beta.3 이후, 규율 완화)

실행 주체: CoreUpdateCommand Step 10 → proc_open 으로 core:execute-upgrade-steps 커맨드 spawn
실행 환경: 별도 PHP 프로세스 (새로 시작되어 디스크의 최신 파일로 Composer autoload 수행)
모든 클래스·config 가 최신 버전 기준 으로 로드됨
적용 규율: 클래스 캐싱 제약 해제. upgrade step 이 beta.N+1 의 새 Service/Repository/Controller/Model 등을 자유롭게 호출 가능
예외: proc_open 미지원 환경에서는 in-process fallback 으로 전환되므로, 신중하게 설계된 upgrade step 은 여전히 경로 A/C 규율도 충족 하는 것이 안전
관련 구현: app/Console/Commands/Core/ExecuteUpgradeStepsCommand.php, CoreUpdateCommand::spawnUpgradeStepsProcess, CoreUpdateService::reloadCoreConfigAndResync

spawn 호출 시 필수 env 전파

proc_open 을 직접 사용할 때 $env 배열은 반드시 아래 패턴 으로 구성한다:

$env = array_merge(getenv(), $_ENV, [
    'G7_UPDATE_IN_PROGRESS' => '1',
    // 필요한 추가 env ...
]);

$_ENV 단독 사용 금지. variables_order php.ini 에 E 가 없는 환경에서는 $_ENV 가 비어있어 플래그 전파가 누락되고, 자식의 CoreServiceProvider::validateAndDeactivate* 가 발동해 활성 확장이 일괄 비활성화되는 회귀가 발생한다. getenv() 는 프로세스 environ 테이블을 직접 반환해 putenv 로 설정된 값까지 포함한다. 상세 배경: extension-update-system.md "업데이트 진행 플래그".

경로 C — 코어 upgrade step (이전 버전 in-process 실행 특수 경로)

실행 주체: 이전 버전 CoreUpdateCommand — 이미 운영 서버에 배포되어 변경 불가
실행 환경: 이전 버전의 메인 PHP 프로세스 — 새 릴리즈에서 도입된 spawn 커맨드를 모르므로 호출 안 함
새 릴리즈의 재작성된 CoreUpdateCommand / ExecuteUpgradeStepsCommand 가 설치되어 있어도 이전 버전 CoreUpdateCommand 가 호출하지 않으므로 무용
적용 규율: 섹션 3~5 의 모든 작성 규칙을 강하게 적용. upgrade step 파일 내부 로컬 private 로직으로 모든 후처리를 직접 수행
허용: 이전 버전에 이미 존재하던 클래스(예: App\Services\CoreUpdateService) 의 기존 메서드 호출 (예: syncCoreRolesAndPermissions, syncCoreMenus) — 단 내부에서 config() 로 읽는 값이 최신이어야 하므로 config(['core' => require config_path('core.php')]) 로 선행 재주입 필요
금지: 새 릴리즈에서 신설된 메서드(예: reloadCoreConfigAndResync) 호출 — 이전 버전 메모리에 존재하지 않음
역사적 인스턴스: upgrades/Upgrade_7_0_0_beta_2.php 의 resyncCorePermissionsAndMenus 로컬 메서드

경로 C 가 필요한 상황 — 발생 조건

대부분의 릴리즈는 경로 B(spawn) 만으로 충분하다. 경로 C 가 필요한 것은 아래 좁은 조건일 때만:

대상 릴리즈가 CoreUpdateCommand 의 업그레이드 흐름 자체를 구조적으로 변경 하여,

새 진입점(spawn 커맨드, 신규 Service 메서드, 신규 내부 단계 등)을 도입했고
해당 진입점은 새 버전이 실행 주체일 때만 활성화되며
이전 버전 CoreUpdateCommand 는 그 진입점을 호출하지 않는 경우

일반적인 기능 추가 / 버그 수정 / 데이터 마이그레이션 릴리즈는 모두 경로 B. 예: beta.3 → beta.4 에서 신규 모듈 도입이나 신규 권한 추가는 모두 경로 B 로 처리된다.

경로 C 는 주로 인프라 재설계 릴리즈 에서 1회씩 발생한다. 과거 예: beta.1 → beta.2 의 spawn 구조 도입.

경로 C 파일 선언 — 메타데이터 규약

경로 C 로 작성하는 upgrade step 파일은 docblock 에 메타데이터 를 명시한다:

/**
 * 코어 N.N.N 업그레이드 스텝
 *
 * @upgrade-path C
 *
 * 경로 C(이전 버전 CoreUpdateCommand 의 in-process 메모리에서 실행) 선언.
 * ... 구체적 사유 ...
 */
class Upgrade_N_N_N implements UpgradeStepInterface

@upgrade-path C 선언은 아래 자동화 스크립트가 인식한다:

.claude/scripts/validate-upgrade-step.cjs — 파일 내용을 파싱하여 경로 C 선언 시 강한 규율 경고 적용
.claude/scripts/file-rules.cjs — 동일 선언 기반으로 upgradeStep 규칙이 경로 C 위반(기존 코어 클래스 use 문) 감지

선언이 없으면 경로 B 로 판정되어 규율이 완화된다 (신규 클래스/메서드 자유 사용).

경로 판별 체크리스트

upgrade step 작성 전 다음을 확인:

확장(모듈/플러그인) upgrade step 인가? → 경로 A
코어 upgrade step 인가?
- 대상 릴리즈가 인프라 재설계(spawn 구조 등) 를 포함하여 이전 버전이 새 진입점을 모르는가?
  - 예 → 경로 C, 파일에 @upgrade-path C 선언 + 로컬 로직 필수
  - 아니오 → 경로 B, 규율 완화 (대부분의 경우)

경로 B 라고 판단했더라도, proc_open 차단 환경에서는 in-process fallback 이 작동하므로 가능하면 경로 A/C 규율도 충족 하도록 작성하는 것이 안전하다.

10. 경로 C 내부 inline spawn 패턴

경로 C 에서 새 릴리즈 클래스 로직이 꼭 필요한 경우, upgrade step 파일 자체가 proc_open 으로 새 PHP 프로세스를 띄우면 된다. 새 프로세스는 디스크의 최신 파일을 autoload 하므로 클래스 캐싱과 무관.

private function spawnResyncInline(UpgradeContext $context): bool
{
    if (! function_exists('proc_open')) {
        return false;
    }

    $basePath = base_path();
    $phpCode = <<<'PHP'
$base = getenv('G7_BASE_PATH');
chdir($base);
require $base.'/vendor/autoload.php';
$app = require $base.'/bootstrap/app.php';
$app->make(Illuminate\Contracts\Console\Kernel::class)->bootstrap();
app(App\Services\CoreUpdateService::class)->reloadCoreConfigAndResync();
echo "OK\n";
PHP;

    $cmd = escapeshellarg(PHP_BINARY).' -r '.escapeshellarg($phpCode).' 2>&1';
    $process = proc_open($cmd, [/* descriptors */], $pipes, $basePath,
        array_merge($_ENV, ['G7_BASE_PATH' => $basePath]));

    if (! is_resource($process)) return false;
    // ... stdout 수집 + proc_close 검증
    return $exitCode === 0 && str_contains($stdout, 'OK');
}

적용 원칙

전용 아티산 커맨드 금지: 1회성 로직이 beta.3 cleanup 시 upgrade step 파일 삭제와 함께 자연 소거되어야 함
Fallback 필수: proc_open 미지원 환경에서는 in-process fallback + 수동 복구 안내 로그
Idempotent 보장: spawn 성공/실패 무관하게 재실행 시 no-op

역사적 인스턴스

upgrades/Upgrade_7_0_0_beta_2.php::spawnResyncInlineLocal — 경로 C 에서 beta.2 최신 reloadCoreConfigAndResync() 호출

11. 업그레이드 후 데이터 정합성 (완전 동기화)

upgrade step 이 수행하는 데이터 변경은 단순 "마이그레이션" 이 아니라 완전 동기화 를 지향한다. 즉:

Upsert: config/seeder → DB 반영
Orphan Delete: config 에 없는 DB row 삭제 (user_overrides 무관)
Mapping Diff: 관계 테이블 재정렬
Dependent Cleanup: 삭제된 상위 엔티티 하위 정리

세부 정책과 Helper 사용법은 다음을 참조:

완전 동기화 원칙 — 4단계 패턴의 상세 정의
데이터 동기화 Helper 5종 — Menu/Role/Notification/FilePermission/Generic
사용자 수정 보존 (HasUserOverrides) — trait 사용 및 mass update 투명 추적

20 KiB Raw Permalink Blame History