fix(core): 공개 확장 번들의 캐시 우선 서빙 + SEO 봇 캐시 상한

공개 번들 엔드포인트가 캐시 파일이 있어도 요청마다 다시 병합했다. 캐시 키는
(type, kind, version) 인자만으로 계산되는데 "병합 결과가 비면 파일을 만들지
않는다" 는 규칙을 먼저 두느라 빌드를 앞세운 것이 원인이다. 그래서 캐시 적중
경로에도 활성 확장 열거와 산출물 전량 읽기가 붙었고, 원본이 소실되면 멀쩡한
캐시를 두고 빈 경로가 반환되어 503 이 됐다. 응답은 정상 200 이라 타이밍 말고는
드러나는 증상이 없다.

프로덕션에서 캐시 존재를 병합보다 먼저 확인하고, 캐시 미스는 같은 키의 잠금으로
1회 빌드에 수렴시킨 뒤 잠금 뒤 캐시를 재확인한다. 잠금 대기 초과·저장소 장애는
실패로 바꾸지 않고 각자 빌드로 폴백한다.

병합 결과가 비어도 선언 산출물이 전부 존재하거나 선언이 0이면 0바이트 캐시를
만들어 정적 게시까지 보낸다. 만들지 않으면 그 구성의 자산 URL 이 API 로 폴백해
방문자의 모든 페이지 로드가 PHP 를 거치고, 그 요청마다 컨트롤러가 열거를 세 번
반복한다. 캐시하지 않는 것은 산출물 소실(503 판정 보존)과 디스크 쓰기 실패뿐이라
응답 계약은 바뀌지 않는다 — 컨트롤러와 트레이트는 손대지 않았다.

같은 결의 결함이 검색봇 캐시에도 있었다. 봇 판정은 User-Agent 문자열뿐인데 캐시
키가 경로 + 전체 쿼리여서, 물음표 뒤 값만 바꾼 반복 요청이 매번 미스가 되고 그
미스마다 레이아웃 병합·표현식 평가·자기 API 루프백 호출이 일어나며 결과가 무제한
저장됐다. 키를 정규화하고(시스템 파라미터 제외·개수/길이 상한), IP 당 분당 미스
렌더 예산과 저장 규모 상한을 뒀다. 초과분은 차단이 아니라 일반 SPA 응답을 받는다
— 봇에게 오류를 주면 그 URL 이 색인에서 빠지기 때문이다.

저장 상한은 만료 항목을 걷어낸 뒤 판정한다. 인덱스는 페이지보다 오래 살아
(30일 vs 기본 2시간) 정리 없이 세면 상한이 "지금 저장된 양"이 아니라 "과거에
저장한 적이 있는 양"을 재게 되어 일방향 래치가 된다. 정리는 인덱스 전체를
훑으므로 최소 60초 간격으로만 수행한다. put 과 putWithLayout 은 같은 자원을
쓰므로 단일 저장 경로로 합쳤다 — 한쪽만 상한 밖이면 그쪽이 우회로가 되고,
인터페이스는 확장에 열려 있어 "지금 호출부가 없다" 는 방어가 되지 않는다.

캐시 적중·미적중을 기록하는 호출처가 없어 관리자 SEO 통계와 seo:stats 가 항상
0 이었던 것도 함께 고쳤다. 기록 자체에도 IP 당 상한을 둬 통계 테이블이 새 증식
축이 되지 않게 했다.

(KISA 측에서 제보해주셨습니다 — KVE-2026-2191)
This commit is contained in:
HeuJung committed 2026-09-08 00:31:20 +09:00
1 parent 893c63c605
commit f506c040c1
21 files changed
+1537 -81

No files matched your search

+111 -12
View File
@@ -9,6 +9,8 @@ use App\Extension\Traits\ClearsTemplateCaches;
use App\Http\View\Composers\TemplateComposer;
use App\Support\AssetCssUrlRewriter;
use App\Support\AssetUrl;
use Illuminate\Contracts\Cache\LockTimeoutException;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Log;
/**
@@ -49,6 +51,21 @@ class ExtensionBundleService
*/
private const TEMP_BUNDLE_STALE_SECONDS = 600;
/**
* 캐시 미스 빌드를 (type, kind, version) 단위로 수렴시키는 잠금 키 접두사.
*/
private const BUILD_LOCK_PREFIX = 'ext-bundles.build.';
/**
* 빌드 잠금의 보유 상한 (초). 좀비 잠금 방지용이며 실제 빌드는 밀리초 단위다.
*/
private const BUILD_LOCK_TTL_SECONDS = 30;
/**
* 다른 프로세스의 빌드를 기다리는 상한 (초). 초과하면 잠금 없이 각자 빌드한다.
*/
private const BUILD_LOCK_WAIT_SECONDS = 5;
/**
* 서비스 주입
*
@@ -251,22 +268,18 @@ class ExtensionBundleService
* 디스크 캐시하며, 비프로덕션(dev/watch)에서는 캐시하지 않고 매 요청 build 해
* rebuild 를 즉시 반영한다.
*
* 프로덕션에서 **캐시 존재 확인이 빌드보다 먼저** 온다. 캐시 키는 인자만으로
* 계산되므로 빌드가 필요 없는데, 빌드를 앞세우면 캐시가 있어도 요청마다 활성 확장을
* 열거하고 산출물을 전부 읽는다. 응답은 정상 200 이라 그 반복은 타이밍 말고는 드러나지
* 않고, 원본이 사라지는 순간에는 멀쩡한 캐시를 두고 빈 경로가 반환되어 503 이 된다.
*
* @param string $type 'module' | 'plugin'
* @param string $kind 'js' | 'css'
* @param int $version 확장 캐시 버전(ClearsTemplateCaches::getExtensionCacheVersion)
* @return string 캐시(또는 방금 build 한) 파일의 절대 경로. 병합 결과가 빈 문자열이면 빈 문자열.
* @return string 캐시(또는 방금 build 한) 파일의 절대 경로. 캐시할 수 없으면 빈 문자열.
*/
public function getBundleFilePath(string $type, string $kind, int $version): string
{
$content = $kind === 'css'
? $this->buildCssBundle($type)
: $this->buildJsBundle($type);
// 병합할 에셋이 하나도 없으면 파일을 만들지 않는다(호출측이 빈 문자열로 판단).
if ($content === '') {
return '';
}
$relativeName = $this->bundleFileName($type, $kind, $version);
// 디스크 캐시는 **최적화**다 — 쓰기 실패가 공개 엔드포인트의 500 이 되면 안 된다.
@@ -279,15 +292,22 @@ class ExtensionBundleService
// 비프로덕션은 캐시하지 않고 임시 파일로 매번 build → rebuild 즉시 반영
if (! app()->environment('production')) {
$content = $this->buildBundleContent($type, $kind);
// 병합할 에셋이 하나도 없으면 파일을 만들지 않는다(호출측이 빈 문자열로 판단).
if ($content === '') {
return '';
}
return $this->writeAtomically($storage, $relativeName, $content, cache: false);
}
// 프로덕션: 동일 version 캐시가 있으면 그대로 사용
// 프로덕션: 동일 version 캐시가 있으면 빌드 없이 그대로 사용
if ($storage->exists('', $relativeName)) {
return $storage->getBasePath('').'/'.$relativeName;
}
return $this->writeAtomically($storage, $relativeName, $content, cache: true);
return $this->buildAndCacheOnce($storage, $type, $kind, $version, $relativeName);
} catch (\Throwable $e) {
Log::warning('확장 번들 디스크 캐시 실패 — 메모리 병합 결과로 서빙합니다', [
'type' => $type,
@@ -300,6 +320,85 @@ class ExtensionBundleService
}
}
/**
* 캐시 미스에서 한 번만 병합해 캐시 파일을 만들고 그 절대 경로를 반환합니다.
*
* 같은 (type, kind, version) 의 동시 요청은 잠금으로 하나에 수렴시킨다 — 버전 교체
* 직후에는 캐시가 없는 상태로 요청이 몰리고, 각자 병합하면 그 비용이 워커 수만큼 곱해진다.
* 잠금은 **최적화**이므로 대기 초과·저장소 장애는 실패로 바꾸지 않고 각자 빌드로 폴백한다
* (정적 게시 잠금 `ext-static.publish.{v}` 와 같은 저장소·같은 규율이며 키가 달라 자기
* 교착이 없다).
*
* 병합 결과가 비어 있어도 선언한 산출물이 **전부 존재하면**(또는 선언이 0이면) 0바이트
* 캐시 파일을 만든다. 그래야 정적 게시 대상이 되어 방문자가 웹서버에서 직접 받는다 —
* 만들지 않으면 그 구성의 모든 페이지 로드가 PHP 를 거친다. 선언한 산출물이 **소실**된
* 경우에만 캐시하지 않아, 호출측의 503 판정이 그대로 유지된다.
*
* @param CoreStorageDriver $storage 번들 디스크 스토리지
* @param string $type 'module' | 'plugin'
* @param string $kind 'js' | 'css'
* @param int $version 확장 캐시 버전
* @param string $relativeName 캐시 파일명
* @return string 캐시 파일의 절대 경로 (캐시하지 않았으면 빈 문자열)
*/
private function buildAndCacheOnce(
CoreStorageDriver $storage,
string $type,
string $kind,
int $version,
string $relativeName
): string {
$lock = null;
$acquired = false;
try {
$lock = Cache::lock(self::BUILD_LOCK_PREFIX."{$type}.{$kind}.{$version}", self::BUILD_LOCK_TTL_SECONDS);
$acquired = (bool) $lock->block(self::BUILD_LOCK_WAIT_SECONDS);
} catch (LockTimeoutException $e) {
// 대기 초과는 정상적인 경합이다 — 흔적만 남기고 각자 빌드한다.
Log::debug('확장 번들 빌드 잠금 대기 초과 — 잠금 없이 병합합니다', [
'type' => $type,
'kind' => $kind,
'version' => $version,
]);
} catch (\Throwable $e) {
// 저장소가 잠금을 제공하지 못한다(드라이버 미지원, 캐시 디렉토리 권한 등).
// 번들 서빙 자체를 막지는 않으므로 사유만 남기고 계속한다.
Log::warning('확장 번들 빌드 잠금 획득 불가 — 잠금 없이 병합합니다', [
'type' => $type,
'kind' => $kind,
'version' => $version,
'store' => config('cache.default'),
'error' => $e->getMessage(),
]);
}
try {
// 기다리는 동안 다른 프로세스가 완성했을 수 있다 — 병합 전에 다시 본다.
if ($storage->exists('', $relativeName)) {
return $storage->getBasePath('').'/'.$relativeName;
}
$content = $this->buildBundleContent($type, $kind);
// 비었는데 선언한 산출물이 소실이면 캐시하지 않는다 — 배포 중 dist 가 잠깐 빈
// 장애가 0바이트 캐시로 굳어 정상(빈 200)으로 위장되면 안 된다.
if ($content === '' && $this->findMissingDeclaredAssets($type, $kind) !== []) {
return '';
}
return $this->writeAtomically($storage, $relativeName, $content, cache: true);
} finally {
if ($acquired && $lock !== null) {
try {
$lock->release();
} catch (\Throwable $e) {
// 해제 실패는 TTL 이 정리한다 — 서빙에는 영향이 없다.
}
}
}
}
/**
* 번들을 서빙할 때 쓸 병합 결과를 반환합니다 (디스크 캐시 실패 시 메모리 폴백용).
*