Mina Choi b9d598e214 env: 템플릿을 루트 한 벌로 모으고, .env 를 엉뚱한 데서 읽던 것을 고친다

★ 버그 — 백엔드가 루트 .env 를 안 읽고 있었다.
server_configs.py 의 _DOTENV_PATH 가 dirname 세 번이라 solution/.env 를 보고 있었다.
backend/ 가 solution/ 안으로 들어갈 때 계단을 안 늘린 것이다. 도커는 compose 가 env 를
직접 주입해서 안 드러나고, compose 밖(스크립트·로컬 실행)에서만 외부 API 키가 조용히
안 들어왔다 — 어댑터가 말없이 비활성되는 종류라 아무도 눈치채지 못한다.

solution/backend/.env.example 을 지웠다.
그 자리의 .env 는 위 버그를 고친 뒤에도 아무도 읽지 않는다(루트를 본다).
살아 있던 값은 루트로 옮겼다 — COLLECT_ADAPTERS(기본값을 코드와 맞췄다),
NAVER_COOKIES, SITE_PAYLOAD_DIR. COLLECT_USE_PERPLEXITY 는 버렸다: collect_service 가
"env 로 일괄 활성화하지 않는다" 며 요청 옵션으로 옮겨서, 코드가 더는 읽지 않는다.

루트 .env.example 을 코드·compose 와 맞췄다.
- 코드가 읽는데 템플릿에 없던 것: COLLECT_ADAPTERS · NAVER_COOKIES · SITE_PAYLOAD_DIR ·
SITE_OUTPUT_DIR · RENDER_TIMEOUT_SEC · ADMIN_API_PORT · JOB_LEASE_SEC · JOB_DEADLINE_SEC ·
WORKER_CONCURRENCY · JWT_*_EXPIRE_* · GEMINI_*_MODEL · VISION_CONFIDENCE_THRESHOLD
- compose 가 읽는데 템플릿에 없던 것: API_BIND · ADMIN_BIND · ADMIN_API_BIND ·
ADMIN_API_BASE_URL. 내부 두 개를 0.0.0.0 으로 열면 앱을 가른 의미가 없는데,
템플릿에 없으면 그 선택지가 있는 줄도 모른다.
- AZURE_STORAGE_PREFIX 기본값을 비웠다. 코드 기본값 ai-for-web 을 그대로 두면 HTML 이
가리키는 /assets/… 와 블롭 경로가 어긋나 CSS 가 404 다(AGENTS.md 함정).
- 카카오 주석 블록 안에 네이버 설명이 끼어 있고 KAKAO_REST_API_KEY 가 저 아래 떨어져
있던 것을 공급자별로 다시 묶었다.

앱 쪽 템플릿은 "여기 뭘 적으면 안 되는가"를 적었다.
site 는 런타임 env 를 안 쓴다는 사실을, admin/frontend 는 :9801 을 봐야 한다는 것을 남겼다.

2026-08-31 17:06:06 +09:00

8.4 KiB

Raw Blame History

AGENTS.md — 이 레포에서 작업하기 전에

에이전트와 신규 합류자가 먼저 읽는 파일이다. 여기에는 밟기 쉬운 함정과 규약만 둔다. 설명은 각 문서가 단일 출처다 — 여기로 복사하지 말고 링크한다.

궁금한 것	문서
이 제품이 뭘 푸나 · 안 하기로 한 것	docs/PRODUCT.md
어떻게 도나 · 앱 경계	docs/ARCHITECTURE.md
다음에 뭘 만드나 (우선순위 P0~P4)	docs/DEVELOPMENT_DIRECTION.md
미결 사항 · 코드가 그걸 어떻게 격리했나	docs/DECISIONS.md
서버에 올릴 때	docs/DEPLOY.md

이 레포의 한 가지 규칙

백엔드는 HTML 을 만들지 않는다. payload JSON 을 파일로 떨어뜨리고, Node 프리렌더가 그걸 읽어 정적 사이트를 굽는다. 두 쪽은 서로를 모르고 디렉토리 하나로만 만난다. 이 경계를 넘는 변경은 하기 전에 ARCHITECTURE.md 1절을 읽는다.

반드시 알아야 할 함정

밟으면 조용히 틀린다 — 빌드는 성공하고 화면도 뜨는데 결과가 잘못된 종류다.

번들 파일명은 콘텐츠 해시다. HTML 은 /assets/index-DvNTmLhy.css 를 루트 절대경로로 가리킨다. 경로는 프리렌더가 dist/client/.vite/manifest.json 에서 읽어 박는다 (prerender.ts:160). 렌더러 CSS 를 고치면 이름이 바뀐다.
로컬 out/assets 는 빌드마다 통째로 갈린다 (prerender.ts:573 rmSync). 옛 해시 파일이 사라지므로 새 번들로 일부 사이트만 구우면 나머지는 CSS 가 404 다. → 프리렌더 기동 시 전체 재굽기가 이 구멍을 메운다.
★ 프론트(solution/site)를 배포하면 반드시 전체 재굽기 + 전체 재업로드. azure_static.publish(slug) 는 공용 자산 + s/<slug> 만 올린다 — 렌더러를 고쳐도 다른 사이트에는 반영되지 않는다. → docker compose restart web 후 python scripts/republish_all.py
발행 호스트는 두 곳에 있고 같아야 한다. 백엔드 SITE_PUBLIC_HOST(기본 w4ai.o2o.kr, site_payload.py) ↔ 프론트 VITE_PUBLISH_HOST. canonical·og:url·sitemap·IndexNow 가 전부 이 값을 쓴다. 그리고 origin 은 payload JSON 에 구워진다 — 호스트를 바꾸면 프리렌더 재실행만으로는 안 되고 백엔드에서 재발행해 payload 를 다시 만들어야 한다.
AZURE_STORAGE_PREFIX 와 루트 절대경로는 충돌한다. HTML 이 /assets/… 를 가리키는데 블롭은 ai-for-web/assets/… 에 놓인다. 접두사를 쓰려면 오리진 경로를 /ai-for-web 로 잡는 CDN 을 앞에 세워야 한다. 아니면 비워라. (프리렌더는 서브패스 마운트를 지원한다 — basePath 가 /sites/s/joy 면 자산은 /sites/assets.)
AZURE_STORAGE_CONTAINER=$web — 셸에서 export 할 땐 반드시 작은따옴표('$web').
슬러그 규칙은 두 곳에 있고 같아야 한다: site_payload.publish_slug() ↔ solution/shared/src/lib/slug.ts publishUrl. 어긋나면 발행은 성공하고 주소만 404 다.
디렉토리 요청 → index.html. /s/<slug> 가 끝 슬래시 없이 열려야 한다. 정적 서버를 바꾸든 nginx 설정을 만지든 이 규칙부터 확인한다.

코드 규약

미결 사항은 코드로 풀지 않는다. DECISIONS.md 1절이 보류한 것은 플래그·어댑터로 격리해 두고, 결론이 나면 날짜와 함께 결론을 적고 격리를 제거한다.
수집 어댑터를 추가하기 전에 DECISIONS.md 1-1 과 DATA_SOURCE_RESEARCH.md를 읽는다. 봇 탐지 우회는 결론과 무관하게 영구 금지다.
주석은 "왜"를 적는다. 이 레포의 기존 주석이 그 톤이다 — 실측값, 밟았던 함정, 안 한 이유. 코드를 읽으면 알 수 있는 "무엇"은 쓰지 않는다.
문서는 코드와 같은 커밋에서 고친다. 동작을 바꿨는데 문서를 안 고쳤으면 미완이다.

레포 구조

solution/    사장님 — backend · frontend(빌더) · site(발행물) · shared(계약)
admin/       우리 — backend(진입점만, :9801) · frontend(운영 화면)

최상단은 프로젝트 단위다(o2o-negosium 과 같은 규약). frontend/ backend/ 를 최상단 묶음 폴더로 쓰지 않는다. 근거와 경계는 ARCHITECTURE.md 4절.

★ 의존 방향은 admin → solution 한 쪽뿐이다. admin 의 @ 별칭이 solution/frontend/src 를 가리키고, API 도 solution 백엔드를 본다. 반대 방향이 생기면 가른 의미가 사라진다.

★ 백엔드는 코드 한 벌, 진입점 둘이다.

	포트	진입점	권한
사장님 API	9800	`solution/backend/web_main.py`	엔드포인트별
내부 API	9801	`admin/backend/main.py` → `app.py`	앱 전체 role >= DEVELOPER

services·crud·models 은 그대로 공유한다. admin 화면이 부르는 게 사장님 빌더와 거의 같아서(place·fact, admin 전용은 local-content 하나) 도메인을 복제하지 않고 같은 router 객체를 다시 마운트하면서 앱 단위로 권한만 덧건다. 경로 접두어(/v1/admin/...)가 아니라 포트를 가른 이유: 접두어는 같은 프로세스라 사장님이 닿는 서버에 내부 엔드포인트가 존재한다. 포트를 가르면 아예 없다. ADMIN_API_BIND 기본값이 127.0.0.1 인 것도 같은 이유다 — 0.0.0.0 으로 열면 무의미하다. ⚠️ 단 /v1/admin/local-content 는 아직 :9800 에도 마운트돼 있다 — 남은 구멍이다 (ARCHITECTURE.md 4절).

실행

docker compose up -d    # api :9800 · api-admin :9801 · 워커 · web :3000 · admin :3002 · nginx :80
docker compose logs -f worker

사장님 앱 :3000(API :9800) · 내부 운영 :3002(API :9801, 로컬호스트에만 열림)
발행 사이트: http://localhost:3000/s/<slug> (빌더 Vite 가 :3001 정적서버로 프록시)
클론 직후 1회: cp .env.example .env · cp nginx/site.conf.example nginx/site.conf (후자를 빼먹으면 Docker 가 그 자리에 디렉토리를 만들어 nginx 가 설정 없이 뜬다)
DB 는 compose 밖이다 (호스트 PostgreSQL, host.docker.internal). 스키마는 postgres-init/init-data/init.sql 한 벌이다 — 누적 ALTER 파일은 없다
npm 워크스페이스 루트는 레포 루트다. npm install 은 루트에서 한 번. npm run dev:frontend / dev:admin / dev:site
백엔드 스크립트는 solution/backend/ 에서 .venv/bin/python scripts/<name>.py
테스트: solution/backend/ 에서 .venv/bin/pytest. APP_ENV=test 면 .env 를 읽지 않는다 — 실키가 테스트로 새어 외부 API 요금이 나가는 경로를 막아 뒀다

.env 는 어디에 두나

루트 .env 가 단일 출처다. compose 가 이 파일을 읽고(${...} 치환 + env_file), 백엔드도 compose 밖에서 띄우면 이 파일을 직접 읽는다(config/server_configs.py 의 python-dotenv). Vite 앱만 구조상 자기 디렉토리의 .env 를 읽는다 — 그래서 나뉘어 있는 것이지 취향이 아니다.

파일	담는 것
`.env`	DB · JWT · 외부 API 키 · 수집 어댑터 · 발행/색인 · 포트 바인딩 — 백엔드가 쓰는 전부
`solution/frontend/.env` · `admin/frontend/.env`	그 앱에만 있는 `VITE_*`. admin 은 API 가 :9801 이다
`solution/site`	없다. 렌더러는 런타임 env 를 안 쓴다 — 사이트별 값은 전부 `SitePayload` 로 들어온다
`solution/backend`	없다. 여기 `.env` 를 두면 아무도 읽지 않는다 (루트를 본다)

★ 두 곳에 같은 값을 적지 않는다. 발행 호스트는 compose 가 루트의 SITE_PUBLIC_HOST 를 VITE_PUBLISH_HOST 로 흘려보낸다. 각자 적으면 canonical 과 화면 주소가 조용히 갈라진다.

커밋

한 커밋 = 한 가지 변경. 문서와 그 문서가 설명하는 코드는 같은 커밋에 둔다.
커밋 메시지는 한국어로, 무엇을 왜 바꿨는지. 파일 목록은 git 이 이미 안다.

8.4 KiB Raw Blame History