chore: 모든 env 파일 구조·주석 정리 및 env↔example 규격 통일

- 죽은 설정 제거: GITEA_*/REPO_IMPORT_ADMIN_EMAIL (저장소·Gitea 기능 삭제됨) - 섹션 헤더 스타일을 # === 블록으로 전 파일 통일(루트/백엔드/프론트) - 루트: AI 섹션(AI_TIMEOUT_MS) 형식 통일 + production 파일에 누락됐던 AI 섹션 추가 - 백엔드: JWT/앱URL/OAuth/AI 4섹션으로 일관 정렬, production 에 누락됐던 URL/OAuth/AI 추가 - 프론트: 빌드 주입 변수 안내(VITE_API_BASE_URL·VITE_AI_TIMEOUT_MS) 명시 - 각 .env 와 .example 의 키·순서·주석을 동일하게(값만 실값/placeholder 차이) (실제 .env.* 는 gitignore 라 미커밋 — 로컬에선 동일 구조로 함께 정리함) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-21 13:21:40 +09:00
parent 042d724b3a
commit 1f2a93b01a
6 changed files with 100 additions and 76 deletions
@@ -1,5 +1,11 @@
 # ==========================================
-# 프로젝트 전역 설정
+# 루트 .env (development) — 모든 설정의 단일 진실 공급원(SSOT)
+# docker-compose 가 이 값을 backend/frontend/db/redis 에 주입한다.
+# .example 을 복사해 만들고 실제 값으로 채운다. (커밋 금지)
+# ==========================================
+
+# ==========================================
+# 프로젝트 전역
 # ==========================================
 PROJECT_NAME=comrelay
 APP_ENV=development
@@ -8,7 +14,7 @@ FRONTEND_DIR=frontend
 BACKEND_DIR=backend

 # ==========================================
-# 포트 설정
+# 포트
 # ==========================================
 FRONTEND_PORT=5273
 BACKEND_PORT=3100
@@ -17,7 +23,7 @@ DB_PORT=5532
 REDIS_PORT=6479

 # ==========================================
-# Database 설정
+# Database (PostgreSQL)
 # ==========================================
 DB_IMAGE=postgres:15-alpine
 DB_USER=dev_ttipo
@@ -26,21 +32,23 @@ DB_NAME=comrelay_db
 DB_DATA_DIR=./data/postgres

 # ==========================================
-# Redis 설정
+# Redis
 # ==========================================
 REDIS_IMAGE=redis:7-alpine
 REDIS_PASSWORD=change-me-redis-password
 REDIS_DATA_DIR=./data/redis

 # ==========================================
-# API 경로 설정
+# API 경로
 # ==========================================
+# BACKEND_API_URL: 프론트 빌드에 주입(VITE_API_BASE_URL)
+# CORS_ORIGIN    : 백엔드가 허용할 프론트 오리진
 BACKEND_API_URL=http://localhost:3100/api
 CORS_ORIGIN=http://localhost:5273

 # ==========================================
-# AI 설정 (백엔드·프론트 공통)
+# AI (백엔드·프론트 공통)
 # ==========================================
-# AI 요청 타임아웃(ms) — 백엔드 Claude 호출 abort + 프론트 axios 타임아웃에 동일 적용.
-# (프론트는 build arg VITE_AI_TIMEOUT_MS 로 주입됨)
+# AI_TIMEOUT_MS: AI 요청 타임아웃(ms). 백엔드 Claude 호출 abort + 프론트 axios 에 동일 적용.
+#   프론트에는 build arg VITE_AI_TIMEOUT_MS 로 주입된다.
 AI_TIMEOUT_MS=60000
@@ -1,5 +1,11 @@
 # ==========================================
-# 프로젝트 전역 설정
+# 루트 .env (production) — 모든 설정의 단일 진실 공급원(SSOT)
+# docker-compose 가 이 값을 backend/frontend/db/redis 에 주입한다.
+# .example 을 복사해 만들고 실제 값으로 채운다. (커밋 금지)
+# ==========================================
+
+# ==========================================
+# 프로젝트 전역
 # ==========================================
 PROJECT_NAME=comrelay
 APP_ENV=production
@@ -8,7 +14,7 @@ FRONTEND_DIR=frontend
 BACKEND_DIR=backend

 # ==========================================
-# 포트 설정
+# 포트
 # ==========================================
 FRONTEND_PORT=5173
 BACKEND_PORT=3000
@@ -17,7 +23,7 @@ DB_PORT=5432
 REDIS_PORT=6379

 # ==========================================
-# Database 설정
+# Database (PostgreSQL)
 # ==========================================
 DB_IMAGE=postgres:15-alpine
 DB_USER=prd_ttipo
@@ -26,14 +32,23 @@ DB_NAME=comrelay_db
 DB_DATA_DIR=./data/postgres

 # ==========================================
-# Redis 설정
+# Redis
 # ==========================================
 REDIS_IMAGE=redis:7-alpine
 REDIS_PASSWORD=change-me-redis-password
 REDIS_DATA_DIR=./data/redis

 # ==========================================
-# API 경로 설정
+# API 경로
 # ==========================================
+# BACKEND_API_URL: 프론트 빌드에 주입(VITE_API_BASE_URL) — 운영 도메인으로 교체
+# CORS_ORIGIN    : 백엔드가 허용할 프론트 오리진 — 운영 도메인으로 교체
 BACKEND_API_URL=http://localhost:3000/api
 CORS_ORIGIN=http://localhost:5173
+
+# ==========================================
+# AI (백엔드·프론트 공통)
+# ==========================================
+# AI_TIMEOUT_MS: AI 요청 타임아웃(ms). 백엔드 Claude 호출 abort + 프론트 axios 에 동일 적용.
+#   프론트에는 build arg VITE_AI_TIMEOUT_MS 로 주입된다.
+AI_TIMEOUT_MS=60000
@@ -1,29 +1,33 @@
 # ==========================================
-# 백엔드 고유 설정 — 루트 .env 에서 내려주지 않는 값만 작성 (JWT/Gitea 등)
-# DB/Redis/CORS/포트 등은 docker-compose 가 루트 .env.development 에서 주입한다.
-# .example 을 복사해 .env.development 를 만들고 실제 값으로 채운다.
+# 백엔드 고유 설정 (development)
+# 루트 .env 에서 주입하지 않는 값만 여기에 둔다.
+# DB/Redis/CORS/포트/AI_TIMEOUT_MS 는 docker-compose 가 루트 .env.development 에서 주입.
+# .example 을 복사해 만들고 실제 값으로 채운다. (커밋 금지)
 # ==========================================

-# JWT 시크릿 (access/refresh 분리) — 임의의 강력한 랜덤 문자열로 교체
-#   생성 예: node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
+# ==========================================
+# JWT / 인증 토큰
+# ==========================================
+# 시크릿은 강력한 랜덤 문자열로 교체:
+#   node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
 JWT_ACCESS_SECRET=change-me-access-secret
 JWT_REFRESH_SECRET=change-me-refresh-secret
-
-# 토큰 만료 시간
 JWT_ACCESS_TTL=15m
 JWT_REFRESH_TTL=14d

-# --- 앱 URL (소셜 로그인/이메일 인증 리다이렉트) ---
-# APP_API_URL: 백엔드 공개 주소(글로벌 prefix /api 포함) — 인증 메일 링크 생성에 사용.
-#   미설정 시 http://localhost:3100/api 로 폴백.
+# ==========================================
+# 앱 URL (리다이렉트)
+# ==========================================
+# APP_API_URL : 백엔드 공개 주소(/api 포함). 인증 메일 링크 생성용. 미설정 시 localhost:3100/api 폴백.
+# FRONTEND_URL: 프론트 공개 주소. 인증 완료·소셜 로그인 후 리다이렉트. 미설정 시 CORS_ORIGIN→localhost:5273 폴백.
 APP_API_URL=http://localhost:3100/api
-# FRONTEND_URL: 프론트 공개 주소 — 인증 완료/소셜 로그인 후 이 주소로 리다이렉트.
-#   미설정 시 CORS_ORIGIN → http://localhost:5273 순으로 폴백.
 FRONTEND_URL=http://localhost:5273

-# --- 소셜 로그인 (OAuth) ---
-# 각 제공자 콘솔에서 발급한 키. CLIENT_ID 가 비어 있으면 해당 소셜 로그인은 비활성화된다.
-# 콜백 URL 은 각 콘솔에 등록한 값과 정확히 일치해야 한다(글로벌 prefix /api 포함).
+# ==========================================
+# 소셜 로그인 (OAuth)
+# ==========================================
+# 각 제공자 콘솔 발급 키. CLIENT_ID 가 비면 해당 소셜 로그인 비활성.
+# CALLBACK_URL 은 콘솔 등록값과 정확히 일치해야 함(/api 포함).
 KAKAO_CLIENT_ID=change-me-kakao-rest-api-key
 KAKAO_CLIENT_SECRET=change-me-kakao-client-secret
 KAKAO_CALLBACK_URL=http://localhost:3100/api/auth/kakao/callback
@@ -31,8 +35,10 @@ GOOGLE_CLIENT_ID=change-me-google-client-id
 GOOGLE_CLIENT_SECRET=change-me-google-client-secret
 GOOGLE_CALLBACK_URL=http://localhost:3100/api/auth/google/callback

-# --- AI 에이전트 (Claude) ---
-# Claude(Anthropic) API 키 — AI 채팅 패널용. 미설정 시 AI 기능 비활성.
+# ==========================================
+# AI 에이전트 (Claude)
+# ==========================================
+# CLAUDE_API_KEY: Anthropic API 키. 미설정 시 AI 기능 비활성.
+# CLAUDE_MODEL  : 모델 ID. 미설정 시 claude-sonnet-4-6.
 CLAUDE_API_KEY=change-me-claude-api-key
-# 사용할 모델 ID — 미설정 시 claude-sonnet-4-6. 콘솔에서 사용 가능한 모델로 교체 가능.
 CLAUDE_MODEL=claude-sonnet-4-6
@@ -1,29 +1,33 @@
 # ==========================================
-# 백엔드 고유 설정 — 루트 .env 에서 내려주지 않는 값만 작성 (JWT/Gitea 등)
-# DB/Redis/CORS/포트 등은 docker-compose 가 루트 .env.production 에서 주입한다.
-# .example 을 복사해 .env.production 를 만들고 실제 값으로 채운다.
+# 백엔드 고유 설정 (production)
+# 루트 .env 에서 주입하지 않는 값만 여기에 둔다.
+# DB/Redis/CORS/포트/AI_TIMEOUT_MS 는 docker-compose 가 루트 .env.production 에서 주입.
+# .example 을 복사해 만들고 실제 값으로 채운다. (커밋 금지)
 # ==========================================

-# JWT 시크릿 (access/refresh 분리) — 임의의 강력한 랜덤 문자열로 교체
-#   생성 예: node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
+# ==========================================
+# JWT / 인증 토큰
+# ==========================================
+# 시크릿은 강력한 랜덤 문자열로 교체:
+#   node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
 JWT_ACCESS_SECRET=change-me-access-secret
 JWT_REFRESH_SECRET=change-me-refresh-secret
-
-# 토큰 만료 시간
 JWT_ACCESS_TTL=15m
 JWT_REFRESH_TTL=14d

-# --- 앱 URL (소셜 로그인/이메일 인증 리다이렉트) ---
-# APP_API_URL: 백엔드 공개 주소(글로벌 prefix /api 포함) — 인증 메일 링크 생성에 사용.
-#   미설정 시 http://localhost:3100/api 로 폴백하므로 운영 도메인으로 반드시 교체.
+# ==========================================
+# 앱 URL (리다이렉트) — 운영 도메인으로 교체
+# ==========================================
+# APP_API_URL : 백엔드 공개 주소(/api 포함). 인증 메일 링크 생성용.
+# FRONTEND_URL: 프론트 공개 주소. 인증 완료·소셜 로그인 후 리다이렉트.
 APP_API_URL=https://your-domain.com/api
-# FRONTEND_URL: 프론트 공개 주소 — 인증 완료/소셜 로그인 후 이 주소로 리다이렉트.
-#   미설정 시 CORS_ORIGIN → http://localhost:5273 순으로 폴백하므로 운영 도메인으로 교체.
 FRONTEND_URL=https://your-domain.com

-# --- 소셜 로그인 (OAuth) ---
-# 각 제공자 콘솔에서 발급한 키. CLIENT_ID 가 비어 있으면 해당 소셜 로그인은 비활성화된다.
-# 콜백 URL 은 각 콘솔에 등록한 운영 도메인 값과 정확히 일치해야 한다(글로벌 prefix /api 포함).
+# ==========================================
+# 소셜 로그인 (OAuth) — 운영 키/도메인으로 교체
+# ==========================================
+# 각 제공자 콘솔 발급 키. CLIENT_ID 가 비면 해당 소셜 로그인 비활성.
+# CALLBACK_URL 은 콘솔 등록값과 정확히 일치해야 함(/api 포함).
 KAKAO_CLIENT_ID=change-me-kakao-rest-api-key
 KAKAO_CLIENT_SECRET=change-me-kakao-client-secret
 KAKAO_CALLBACK_URL=https://your-domain.com/api/auth/kakao/callback
@@ -31,25 +35,10 @@ GOOGLE_CLIENT_ID=change-me-google-client-id
 GOOGLE_CLIENT_SECRET=change-me-google-client-secret
 GOOGLE_CALLBACK_URL=https://your-domain.com/api/auth/google/callback

-# --- Gitea 연동 (외부 Gitea 인스턴스) ---
-# 세 값(BASE_URL/TOKEN/ORG)이 모두 채워져야 연동 활성화. 비우면 Gitea 동기화 없이 동작한다.
-# 저장소 생성/수정/삭제 시 GITEA_ORG 조직 아래 repo 가 자동 동기화된다.
-# GITEA_BASE_URL: 끝 슬래시 없이 (/api/v1 는 코드가 붙임)
-GITEA_BASE_URL=https://gitea.example.com
-# GITEA_TOKEN: 조직 권한을 가진 액세스 토큰 (Gitea Settings → Applications → Generate Token)
-GITEA_TOKEN=change-me-gitea-token
-# GITEA_ORG: 저장소가 생성될 조직 이름 (Relay 의 owner 로도 사용)
-GITEA_ORG=marketing-team
-# 템플릿 저장소(생성 시 복제) — 미설정 시 기본 TtiPo/project-base 사용. Gitea 에서 template 설정 필요
-GITEA_TEMPLATE_OWNER=ttipo
-GITEA_TEMPLATE_REPO=project-base
-# import(역방향 동기화로 가져온, 멤버 0명) 저장소의 기본 owner-admin 으로 지정할 가입 사용자 이메일.
-#   동기화는 시스템 작업이라 실행 주체가 없으므로 여기서 지정한다.
-#   비우거나 미가입 이메일이면 import 저장소는 멤버 0명으로 남고(초대 불가), 가입 후 다음 동기화에서 지정된다.
-REPO_IMPORT_ADMIN_EMAIL=admin@example.com
-
-# --- AI 에이전트 (Claude) ---
-# Claude(Anthropic) API 키 — AI 채팅 패널용. 미설정 시 AI 기능 비활성.
+# ==========================================
+# AI 에이전트 (Claude)
+# ==========================================
+# CLAUDE_API_KEY: Anthropic API 키. 미설정 시 AI 기능 비활성.
+# CLAUDE_MODEL  : 모델 ID. 미설정 시 claude-sonnet-4-6.
 CLAUDE_API_KEY=change-me-claude-api-key
-# 사용할 모델 ID — 미설정 시 claude-sonnet-4-6. 콘솔에서 사용 가능한 모델로 교체 가능.
 CLAUDE_MODEL=claude-sonnet-4-6
@@ -1,7 +1,10 @@
 # ==========================================
-# 프론트엔드 고유 env — 현재 사용하는 고유 키는 없다.
-# VITE_API_BASE_URL 은 docker-compose 가 루트 .env.development 의 BACKEND_API_URL 을
-# build arg(VITE_API_BASE_URL)로 주입하므로 여기에 작성할 필요가 없다.
-# 단독 실행(non-Docker)으로 vite dev 를 띄울 때만 아래 줄의 주석을 풀어 사용한다.
+# 프론트엔드 env (development)
+# VITE_ 변수는 docker-compose 가 루트 .env.development 값을 build arg 로 주입한다:
+#   VITE_API_BASE_URL   ← BACKEND_API_URL
+#   VITE_AI_TIMEOUT_MS  ← AI_TIMEOUT_MS
+# 따라서 Docker 로 띄울 땐 이 파일에 작성할 필요가 없다.
+# 단독 실행(non-Docker)으로 vite dev 를 띄울 때만 아래 주석을 풀어 사용한다.
+# ==========================================
 # VITE_API_BASE_URL=http://localhost:3100/api
-# ==========================================
+# VITE_AI_TIMEOUT_MS=60000
@@ -1,7 +1,10 @@
 # ==========================================
-# 프론트엔드 고유 env — 현재 사용하는 고유 키는 없다.
-# VITE_API_BASE_URL 은 docker-compose 가 루트 .env.production 의 BACKEND_API_URL 을
-# build arg(VITE_API_BASE_URL)로 주입하므로 여기에 작성할 필요가 없다.
-# 단독 빌드(non-Docker)로 vite build 할 때만 아래 줄의 주석을 풀어 운영 도메인으로 사용한다.
+# 프론트엔드 env (production)
+# VITE_ 변수는 docker-compose 가 루트 .env.production 값을 build arg 로 주입한다:
+#   VITE_API_BASE_URL   ← BACKEND_API_URL
+#   VITE_AI_TIMEOUT_MS  ← AI_TIMEOUT_MS
+# 따라서 Docker 로 빌드할 땐 이 파일에 작성할 필요가 없다.
+# 단독 빌드(non-Docker)로 vite build 할 때만 아래 주석을 풀어 운영 도메인으로 사용한다.
+# ==========================================
 # VITE_API_BASE_URL=https://your-domain.com/api
-# ==========================================
+# VITE_AI_TIMEOUT_MS=60000