feat(seo): 사이트맵 안전 서빙·잡 견고화·분할 설정 + 캐시 설정 정합
봇 요청 스레드의 동기 생성을 제거하고 디스크 스트리밍 서빙으로 전환했다. 신선도가 만료되면 생성 잡만 예약하고 기존 세트(stale) 또는 503+Retry-After 로 응답해, 대용량에서 봇 요청이 OOM/타임아웃을 유발하던 경로를 끊었다. - 잡: ShouldBeUnique(고정 uniqueId)+uniqueFor+retryUntil, timeout 300→1800, backoff - 컨트롤러: 인덱스 stale/503 분기 + 자식 라우트(.xml/.xml.gz 동일 액션) - 스케줄 withoutOverlapping, 관리자 재생성 큐 이관 - 설정 4키(분할 기준·압축·stale 서빙·수집기 상한) + 고급탭 Sitemap 캐시 짝 - SitemapManager 응답 메시지 다국어화 설정 저장 테스트가 실제 설정 파일(사이트명/언어 포함)을 덮어쓰던 사전결함을 TestCase 전역 격리로 차단하고, 두 탭이 같은 다국어 키를 공유해 한쪽에 틀린 한도를 안내하던 사전결함을 키 분리로 해소했다.
This commit is contained in:
1 parent
21f666e4b5
commit
1c99547bc1
71 files changed
+3767
-2472
No files matched your search
+11
-8
@@ -152,9 +152,8 @@ _단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| last_updated_at | string | `2026-07-08T03:14:49+00:00` | last updated 일시 |
|
||||
| size_bytes | integer | `25489` | 크기 (바이트) |
|
||||
| ttl | integer | `86400` | 캐시 유효 시간 (Time To Live, 초). 고급 설정의 `cache.seo_sitemap_ttl` 이 기준값이며, SEO 설정 `seo.sitemap_cache_ttl` 에 값이 지정되어 있으면(null 이 아니면) 그 값이 우선합니다 |
|
||||
| status | string | `dispatched` | 예약 상태. 재생성 잡이 큐에 등록되었음을 의미합니다 |
|
||||
| last_updated_at | string\|null | `2026-07-08T03:14:49+00:00` | **예약 시점 기준** 마지막 생성 일시. 이번 재생성의 결과가 아니라 직전 생성 시각이며, 잡 완료 후 갱신됩니다 (아직 한 번도 생성되지 않았으면 null) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
@@ -165,11 +164,10 @@ HTTP/1.1 200
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Sitemap 재생성이 완료되었습니다.",
|
||||
"message": "Sitemap 재생성을 시작했습니다. 완료까지 시간이 걸릴 수 있습니다.",
|
||||
"data": {
|
||||
"last_updated_at": "2026-07-08T03:14:49+00:00",
|
||||
"size_bytes": 25489,
|
||||
"ttl": 86400
|
||||
"status": "dispatched",
|
||||
"last_updated_at": "2026-07-08T03:14:49+00:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -178,6 +176,7 @@ HTTP/1.1 200
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 400 | Bad Request | SEO 설정에서 sitemap 생성이 비활성(`seo.sitemap_enabled=false`)인 경우 (`seo.sitemap_disabled`) |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
|
||||
@@ -185,7 +184,11 @@ HTTP/1.1 200
|
||||
|
||||
**설명**
|
||||
|
||||
sitemap.xml 을 즉시 재생성합니다. SitemapManager 에 위임하며 큐 드라이버와 무관하게 동기(즉시) 실행되고, 완료 후 마지막 생성 시각을 갱신합니다. SEO 설정에서 sitemap 기능이 비활성인 경우 400(`seo.sitemap_disabled`), 생성 실패 시 500 을 반환합니다. 관리자가 콘텐츠 변경 후 검색엔진에 노출할 sitemap 을 스케줄 대기 없이 즉시 갱신할 때 사용합니다.
|
||||
sitemap.xml 재생성을 큐에 예약합니다. 응답은 예약 접수 결과이며 생성 완료를 의미하지 않습니다 — 실제 생성은 큐 워커가 `GenerateSitemapJob` 을 처리할 때 수행되고, 완료 후 마지막 생성 시각이 갱신됩니다.
|
||||
|
||||
요청 스레드에서 동기 생성하지 않는 이유는 대용량(수백만 URL) 사이트에서 생성이 수 분~수십 분 걸려 관리자 요청이 메모리 초과/타임아웃으로 실패하기 때문입니다. 잡은 유니크 락(`seo-sitemap`)을 사용하므로 재생성을 연속으로 요청해도 동시에 여러 건이 실행되지 않고 한 건만 큐에 남습니다.
|
||||
|
||||
생성 진행 상황은 이 응답으로 알 수 없습니다. 완료 여부는 `last_updated_at` 이 갱신되었는지로 확인합니다.
|
||||
|
||||
|
||||
### GET /api/admin/seo/stats
|
||||
|
||||
@@ -12,7 +12,8 @@
|
||||
5. seo-config.json: 텍스트 추출(text_props), 속성 매핑(attr_map), 허용 속성(allowed_attrs), 컴포넌트→HTML 매핑 — 모두 템플릿 선언
|
||||
6. 훅 시스템: core.seo.filter_context/filter_og_data/filter_twitter_data/filter_structured_data/filter_meta/filter_view_data + 봇 감지 훅 core.seo.resolve_is_bot
|
||||
7. 도메인 ownership: 모듈/플러그인이 `seoOgDefaults`/`seoTwitterDefaults`/`seoStructuredData` 메서드로 자기 도메인 OG/Twitter/JSON-LD 를 owned (이커머스 Product, 게시판 Article 등)
|
||||
7. Artisan: seo:warmup, seo:clear, seo:stats, seo:generate-sitemap
|
||||
8. Sitemap: 비공개 디스크에 분할 커밋(sitemapindex + sitemap-{n}.xml) 후 스트리밍 서빙 — 요청 스레드 생성 없음, 미스 시 잡 디스패치 + stale/503
|
||||
9. Artisan: seo:warmup, seo:clear, seo:stats, seo:generate-sitemap
|
||||
```
|
||||
|
||||
## 아키텍처 개요
|
||||
@@ -632,6 +633,36 @@ php artisan seo:generate-sitemap # Sitemap 생성 (큐 디스패치)
|
||||
php artisan seo:generate-sitemap --sync # Sitemap 동기 생성
|
||||
```
|
||||
|
||||
## Sitemap 분할 생성과 서빙
|
||||
|
||||
Sitemap 은 비공개 디스크(StorageInterface, `cache` 카테고리)에 분할 파일로 커밋되고, 컨트롤러가 스트리밍으로 서빙합니다. `public/storage` 심볼릭 링크에 의존하지 않으며 자식 파일을 메모리에 적재하지 않습니다.
|
||||
|
||||
**디스크 레이아웃** (SSoT: `SitemapFileStore` 상수):
|
||||
|
||||
```text
|
||||
sitemap/manifest.json 커밋 마커 + 자식 목록 메타 (이 파일 존재 = 서빙 가능)
|
||||
sitemap/sitemap.xml sitemapindex (항상 비압축)
|
||||
sitemap/sitemap-{n}.xml 자식 sitemap (gzip 시 .xml.gz)
|
||||
sitemap/_tmp/ 생성 중 임시 디렉토리 (커밋 시 정리)
|
||||
```
|
||||
|
||||
**라우트**: `/sitemap.xml`(인덱스) · `/sitemap-{n}.xml`, `/sitemap-{n}.xml.gz`(자식). 자식 경로는 `SitemapFileStore::childUrl()` 이 인덱스 `<loc>` 에 기록하는 값과 일치해야 합니다. gzip 여부는 manifest 가 결정하므로 두 경로를 같은 액션이 처리합니다.
|
||||
|
||||
**서빙 시맨틱** (요청 스레드에서 생성하지 않음):
|
||||
|
||||
| 상태 | 동작 |
|
||||
|------|------|
|
||||
| 메타 캐시 신선 + 세트 존재 | 디스크 세트 스트리밍 |
|
||||
| 메타 캐시 만료 | `GenerateSitemapJob` 디스패치 후 기존 세트 서빙 (`sitemap_serve_stale_on_miss=true`) |
|
||||
| 메타 캐시 만료 + stale 서빙 off | 잡 디스패치 후 503 + `Retry-After: 120` |
|
||||
| 세트 전무 (신규 설치) | 잡 디스패치 후 503 + `Retry-After: 120` |
|
||||
|
||||
봇 요청 스레드에서 동기 생성하면 대용량(수백만 URL)에서 메모리 초과·타임아웃이 발생하므로 생성은 항상 큐가 담당합니다. 잡은 유니크 락(`seo-sitemap`)을 쓰므로 캐시 미스가 몰려도 동시에 여러 건이 실행되지 않습니다.
|
||||
|
||||
**분할 기준**: `sitemap_urls_per_file`(기본 50000) 또는 파일 크기 임계(`SitemapWriter::MAX_FILE_BYTES`, 45MB) 중 먼저 도달하는 쪽. 둘 다 sitemaps.org 프로토콜 제한(50,000 URL / 50MB)을 지키기 위한 것입니다.
|
||||
|
||||
**관리자 수동 재생성**: `POST /api/admin/seo/sitemap/regenerate` 는 큐에 예약만 하고 즉시 응답합니다(`status: dispatched`). 완료 여부는 `sitemap_last_updated_at` 갱신으로 확인합니다.
|
||||
|
||||
## 설정값 (코어 seo.*)
|
||||
|
||||
| 키 | 타입 | 기본값 | 설명 |
|
||||
@@ -641,7 +672,11 @@ php artisan seo:generate-sitemap --sync # Sitemap 동기 생성
|
||||
| cache_enabled | boolean | true | SEO 캐시 ON/OFF |
|
||||
| cache_ttl | integer | 7200 | 캐시 TTL (초) |
|
||||
| sitemap_enabled | boolean | true | sitemap.xml 생성 ON/OFF |
|
||||
| sitemap_cache_ttl | integer | 86400 | Sitemap 캐시 TTL (초) |
|
||||
| sitemap_cache_ttl | integer\|null | null | Sitemap 캐시 TTL 오버라이드 (초). null=고급 탭 `cache.seo_sitemap_ttl` 을 따름 |
|
||||
| sitemap_urls_per_file | integer | 50000 | 자식 파일당 URL 수 (분할 기준). 1000~50000, 상한은 sitemaps.org 프로토콜 제한 |
|
||||
| sitemap_gzip | boolean | false | 자식 파일 gzip 압축. 인덱스 파일은 항상 비압축 |
|
||||
| sitemap_serve_stale_on_miss | boolean | true | 신선도 만료 시 기존 세트를 그대로 서빙(true) / 503 반환(false) |
|
||||
| sitemap_max_urls_per_contributor | integer | 0 | 수집기당 URL 상한 (0=무제한). 초과 시 경고 로그 + truncate |
|
||||
| sitemap_schedule | string | "daily" | 생성 주기 (hourly/daily/weekly) |
|
||||
| sitemap_schedule_time | string | "02:00" | 생성 시각 |
|
||||
| og_default_site_name | string | "" | og:site_name 기본값. 비면 `general.site_name` fallback |
|
||||
|
||||
@@ -14,12 +14,14 @@
|
||||
5. 테스트 실행 중 발견한 무관 에러도 같은 세션에서 함께 처리 (stale test 수정 or 로직 수정)
|
||||
6. 릴리스 전 composer test-smoke 통과 필수 (Installation 스위트)
|
||||
7. 백엔드: php artisan test --filter=TestName / _bundled 확장은 _bundled에서 직접 실행
|
||||
8. settings 디스크는 TestCase 가 전역 페이크 — 실제 설정 파일 오염 차단. 저장 직후 값 검증은 g7_core_settings() 말고 ConfigRepository::getCategory()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 목차
|
||||
|
||||
- [실제 환경 파일 보호 (settings 디스크 격리)](#실제-환경-파일-보호-settings-디스크-격리)
|
||||
- [기능 단위 시나리오 매트릭스](#기능-단위-시나리오-매트릭스)
|
||||
- [도메인별 테스트 전략 매트릭스](#도메인별-테스트-전략-매트릭스)
|
||||
- [Pre-release Smoke Suite](#pre-release-smoke-suite)
|
||||
@@ -211,6 +213,41 @@ beforeRefreshingDatabase()는 RefreshDatabase 트레이트가 부모 클래스
|
||||
|
||||
---
|
||||
|
||||
## 실제 환경 파일 보호 (settings 디스크 격리)
|
||||
|
||||
`settings` 디스크의 root 는 `storage/app/settings` — 개발/운영이 실제로 사용하는 설정 파일 그 자체다. 설정 저장 경로를 타는 테스트(설정 API 호출, `ConfigRepository::saveCategory()`)는 이 파일을 그대로 덮어쓰며, `RefreshDatabase` 는 DB 만 되돌리므로 오염이 잔류한다.
|
||||
|
||||
`Tests\TestCase` 가 앱 부팅 직후 `Storage::fake('settings')` 로 전역 격리한다. 테스트에서 별도 조치는 필요 없다.
|
||||
|
||||
```text
|
||||
✅ 설정 저장 테스트 = 추가 조치 불필요 (TestCase 가 이미 격리)
|
||||
❌ Storage::fake('settings') 를 테스트마다 중복 호출 — 불필요
|
||||
❌ 격리를 우회해 storage/app/settings 를 직접 읽고/쓰기 — 실제 환경 오염
|
||||
```
|
||||
|
||||
### 저장 직후 값 검증
|
||||
|
||||
`g7_core_settings()` / `config('g7_settings.*')` 는 **부팅 시점에 적재된 값**이라 같은 프로세스에서 저장 직후에는 갱신되지 않는다. 저장 결과를 검증하려면 저장소를 직접 읽는다.
|
||||
|
||||
```php
|
||||
// ❌ 저장했는데 부팅 시점 값이 나온다
|
||||
$this->assertSame(20000, g7_core_settings('seo.sitemap_urls_per_file'));
|
||||
|
||||
// ✅ 저장소 실제 값 조회
|
||||
$seo = app(ConfigRepositoryInterface::class)->getCategory('seo');
|
||||
$this->assertSame(20000, $seo['sitemap_urls_per_file']);
|
||||
```
|
||||
|
||||
### 배경 (회귀 사례)
|
||||
|
||||
격리 도입 전에는 `Storage::fake('settings')` 를 쓰는 테스트가 1개뿐이라, 설정 저장 테스트를 돌릴 때마다 개발 환경의 실제 설정이 테스트 값으로 대체됐다. 실측 피해: `general.json` 의 사이트명이 `"Test"`, 언어가 `ja` 로 바뀌어 **개발 사이트 언어가 일본어로 전환**되어 있었고, SEO/캐시 TTL 도 테스트 값으로 덮여 운영자가 지정한 값이 사라졌다. 테스트는 계속 green 이라 조용히 누적됐다.
|
||||
|
||||
회귀 가드: `tests/Feature/Settings/SettingsDiskIsolationTest.php` (격리 해제 시 FAIL).
|
||||
|
||||
`Storage::fake()` 는 **해석된 디스크 인스턴스만 교체**하고 `config('filesystems.disks.settings.root')` 는 실경로로 남는다. 격리 여부를 판정할 때는 `Storage::disk('settings')->path('')` 를 봐야 한다.
|
||||
|
||||
---
|
||||
|
||||
## 기능 단위 시나리오 매트릭스
|
||||
|
||||
```text
|
||||
|
||||
Reference in new issue
Block a user