diff --git a/book/300_architecture/300_README.md b/book/300_architecture/300_README.md index aede695..3eacac6 100644 --- a/book/300_architecture/300_README.md +++ b/book/300_architecture/300_README.md @@ -11,7 +11,7 @@ Part 2에서 우리는 게임 메커니즘을 활용한 설계를 소개했습 ## 목차 - 310_전체_시스템_구조_컨테이너와_마이크로서비스.md - 311_FastAPI_구조_원칙.md -- 312_문서_작성_원칙.md +- 312_writing-principles.md - 313_React_구조_원칙.md - 315_테스트_원칙.md - 320_Slack_기반_인터페이스_설계.md diff --git a/book/300_architecture/311_백엔드_구조_원칙.md b/book/300_architecture/311_백엔드_구조_원칙.md index 92fab9e..e5cdbf3 100644 --- a/book/300_architecture/311_백엔드_구조_원칙.md +++ b/book/300_architecture/311_백엔드_구조_원칙.md @@ -241,7 +241,7 @@ utils - [ ] LLM 호출 횟수 계산 및 최적화 검토 - [ ] 애매한 케이스는 LLM 우선 접근 원칙 적용 확인 - [ ] 복잡한 워크플로우는 LangGraph 활용 검토 -- [ ] 원칙 문서 확인 완료 (`311_FastAPI_구조_원칙.md`, `312_문서_작성_원칙.md`) +- [ ] 원칙 문서 확인 완료 (`311_FastAPI_구조_원칙.md`, `312_writing-principles.md`) - [ ] 웹훅 프록시 경로에서 원문 body 전달(`content=raw_body`) 여부 확인 - [ ] 인증 실패 상태코드(403/401)가 500으로 재매핑되지 않는지 확인 - [ ] 증상 완화용 폴백 대신 근본 원인 수정이 반영되었는지 확인 diff --git a/book/300_architecture/312_문서_작성_원칙.md b/book/300_architecture/312_writing-principles.md similarity index 93% rename from book/300_architecture/312_문서_작성_원칙.md rename to book/300_architecture/312_writing-principles.md index 5c5b450..7b2d816 100644 --- a/book/300_architecture/312_문서_작성_원칙.md +++ b/book/300_architecture/312_writing-principles.md @@ -3,12 +3,16 @@ **작성일**: 2025-10-13 **수정일**: 2026-03-05 (SSOT 관리 기준 명시) **참고**: AGENTS.md, 311_백엔드_구조_원칙.md +**상위 원칙**: [0_VALUE Writing Principles](../../../../0_VALUE/02_Governance/writing-principles.md) --- ## 0. SSOT 관리 기준 -- 문서 작성 상세 원칙의 SSOT는 본 문서(`312_문서_작성_원칙.md`)다. +- 문서 작성 상세 원칙의 SSOT는 본 문서(`312_writing-principles.md`)다. +- 상위 공통 원칙의 SSOT는 `0_VALUE/02_Governance/writing-principles.md`다. +- 본 문서는 robeing 프로젝트에 필요한 구체화 문서다. +- 원칙 충돌 시 상위 원칙을 먼저 검토하고, 예외가 필요하면 사용자에게 먼저 보고한 뒤 본 문서에 예외를 기록한다. - 하위 폴더 `README.md`와 개별 문서는 원칙 본문을 반복하지 않고 SSOT 링크만 둔다. - 동일 원칙을 여러 문서에 복제하지 않는다. 필요 시 본 문서를 수정하고 참조 링크만 갱신한다. - 실행/코드 정책(예: 폴백·예외 처리 최소화, 원인 경로 직접 수정)은 `AGENTS.md`를 SSOT로 본다. @@ -157,6 +161,11 @@ - 예: `https://github.com///blob//...` - 로컬 절대경로(`/home/...`, `C:\\...`)와 위키링크(`[[...]]`)는 GitHub 렌더링 호환성 이슈가 있어 기본 문서 본문에서 사용하지 않습니다. - 문서 추가/수정 시 링크 클릭 동작을 반드시 확인한 뒤 커밋합니다. +- 트러블슈팅/실행 기록 문서는 필요 시 문서 상단에 `tags: [tag1, tag2, ...]` 형식의 태그를 둡니다. +- 같은 계열 사건이 이어질 때는 기존 문서를 덮어쓰지 말고 새 문서로 분리한 뒤, 문서 하단에 `전후 관계 문서` 또는 `관련 문서` 링크를 둡니다. +- 원칙은 `기존 문서 보존 + 새 사건은 새 문서 + 관련 문서끼리 링크`입니다. +- 같은 목적의 상위 문서가 있으면 문서 상단에 `상위 원칙` 링크를 둡니다. +- 동일 목적 문서는 파일명을 상위 SSOT basename에 맞춥니다. ### 구조화된 정보 형식 (AI/사람 모두 읽기 좋게) @@ -288,7 +297,7 @@ ### 필수 항목 1. **원인**: 왜 문제가 발생했는가 2. **교훈**: 다음에 어떻게 방지할 것인가 -3. **원칙**: 위반한 원칙이 있는가 (원칙 문서 참조: `311_백엔드_구조_원칙.md`, `312_문서_작성_원칙.md`) +3. **원칙**: 위반한 원칙이 있는가 (원칙 문서 참조: `311_백엔드_구조_원칙.md`, `312_writing-principles.md`) ### 올바른 예시 ```markdown diff --git a/book/300_architecture/313_프론트_구조_원칙.md b/book/300_architecture/313_프론트_구조_원칙.md index ca1cb54..cd8cabe 100644 --- a/book/300_architecture/313_프론트_구조_원칙.md +++ b/book/300_architecture/313_프론트_구조_원칙.md @@ -2,7 +2,7 @@ **작성일**: 2025-11-29 **수정일**: 2026-01-21 (컴포넌트 분리 기준 300줄 → 500줄 완화) -**참고**: 311_FastAPI_구조_원칙.md, 312_문서_작성_원칙.md +**참고**: 311_FastAPI_구조_원칙.md, 312_writing-principles.md ## 1. 컴포넌트 설계 원칙 @@ -264,5 +264,5 @@ src/ - 상위 원칙: 이 문서는 일반적인 React 프로젝트 원칙을 다룹니다. - 프로젝트별 특화 규칙: 각 프로젝트의 README나 문서에 추가 규칙 명시 - 백엔드 원칙: `311_FastAPI_구조_원칙.md` 참고 -- 문서 작성 원칙: `312_문서_작성_원칙.md` 참고 +- 문서 작성 원칙: `312_writing-principles.md` 참고 diff --git a/book/300_architecture/314_인프라_설정_SSOT_원칙.md b/book/300_architecture/314_infrastructure-ssot-principle.md similarity index 82% rename from book/300_architecture/314_인프라_설정_SSOT_원칙.md rename to book/300_architecture/314_infrastructure-ssot-principle.md index 23ae988..636089f 100644 --- a/book/300_architecture/314_인프라_설정_SSOT_원칙.md +++ b/book/300_architecture/314_infrastructure-ssot-principle.md @@ -1,9 +1,16 @@ # 314 인프라 설정 SSOT 원칙 +**상위 원칙**: [0_VALUE Infrastructure SSOT Principle](../../../../0_VALUE/02_Governance/infrastructure-ssot-principle.md) + ## 1. 목적 - 인프라 핵심 설정(IP, 포트, 업스트림, 공통 URL, 환경별 엔드포인트)을 단일 출처(Single Source of Truth)로 관리한다. - 값 변경 1건이 다수 코드/설정/문서 수정을 유발하는 구조를 제거한다. +## 1.1 상위 원칙 관계 +- 상위 공통 원칙의 SSOT는 `0_VALUE/02_Governance/infrastructure-ssot-principle.md`다. +- 본 문서는 robeing 운영 구조에 맞춘 구체화 문서다. +- 원칙 충돌 시 상위 원칙을 먼저 검토하고, 예외가 필요하면 사용자에게 먼저 보고한 뒤 본 문서에 예외를 남긴다. + ## 2. 원칙 ### 2.1 단일 출처 - 런타임 설정의 기준 파일은 `/home/admin/infra-config/runtime.env` 단일 파일로 한다. diff --git a/book/300_architecture/315_테스트_원칙.md b/book/300_architecture/315_테스트_원칙.md index 7701b67..98edacf 100644 --- a/book/300_architecture/315_테스트_원칙.md +++ b/book/300_architecture/315_테스트_원칙.md @@ -2,7 +2,7 @@ **작성일**: 2025-01-03 **수정일**: 2026-02-04 (UX 검증 원칙 추가) -**참고**: 311_백엔드_구조_원칙.md, 312_문서_작성_원칙.md +**참고**: 311_백엔드_구조_원칙.md, 312_writing-principles.md --- @@ -229,5 +229,5 @@ docker compose down && docker compose up -d --build ## 10. 참고 - FastAPI 구조 원칙: `311_백엔드_구조_원칙.md` 섹션 18 (테스트 원칙) -- 문서 작성 원칙: `312_문서_작성_원칙.md` (troubleshooting 기록 방법) +- 문서 작성 원칙: `312_writing-principles.md` (troubleshooting 기록 방법) - 트러블슈팅: `journey/troubleshooting/251110_레거시_테스트_폴더_정리.md` diff --git a/journey/plans/251225_프롬프트_동적관리_계획.md b/journey/plans/251225_프롬프트_동적관리_계획.md index ce58709..da1b455 100644 --- a/journey/plans/251225_프롬프트_동적관리_계획.md +++ b/journey/plans/251225_프롬프트_동적관리_계획.md @@ -7,7 +7,7 @@ **원칙 참조**: - `book/300_architecture/311_백엔드_구조_원칙.md` (계층 분리, DB state 경유) -- `book/300_architecture/312_문서_작성_원칙.md` +- `book/300_architecture/312_writing-principles.md` - `book/300_architecture/315_테스트_원칙.md` (TDD) - `book/300_architecture/313_Gemini_프롬프트_설계_원칙.md` @@ -531,7 +531,7 @@ post_check_result: ## 참고 문서 - `book/300_architecture/311_백엔드_구조_원칙.md` -- `book/300_architecture/312_문서_작성_원칙.md` +- `book/300_architecture/312_writing-principles.md` - `book/300_architecture/315_테스트_원칙.md` - `book/300_architecture/313_Gemini_프롬프트_설계_원칙.md` - `journey/troubleshooting/250806_happybell80_동적프롬프트구현.md` diff --git a/journey/plans/260307_24서버_정상복구_초기서버_기준_계획.md b/journey/plans/260307_24서버_정상복구_초기서버_기준_계획.md new file mode 100644 index 0000000..261f7e0 --- /dev/null +++ b/journey/plans/260307_24서버_정상복구_초기서버_기준_계획.md @@ -0,0 +1,173 @@ +# 260307 24서버 정상복구 초기서버 기준 계획 + +**작성일**: 2026-03-07 +**상태**: draft +**전제**: 51124는 현재 빈 초기 서버에 가깝고, 51123이 `테스트 + 임시 운영` 역할을 겸하고 있다. + +--- + +## 1. 목표 +- 51124를 다시 robeing 프로덕션 실행 서버로 복구한다. +- 51123의 임시 수용 상태를 종료하고, 원래 역할인 `테스트 + 보조 + 인프라`로 되돌린다. +- 복구 후에도 IP/경로/시크릿 변경이 대량 수정으로 번지지 않도록 SSOT 구조를 함께 정착시킨다. + +## 2. 복구 원칙 +1. 24는 처음부터 다시 쌓는다고 가정한다. +- 과거 상태를 추측 복원하지 않는다. +- 필요한 구성요소를 체크리스트로 다시 올린다. + +2. 서비스보다 기반을 먼저 복구한다. +- OS/계정/권한/디렉터리/SSOT/네트워크가 먼저다. +- 이 기반 없이 컨테이너만 올리면 재장애 가능성이 높다. + +3. 프로덕션 판정은 24에서만 확정한다. +- 23에서 정상인 것은 사전 검증 근거일 뿐이다. +- 최종 정상 판정은 24의 실제 헬스체크와 실경로 검증으로만 내린다. + +## 3. 24 서버에 먼저 갖춰야 할 것 +### 3.1 운영 기본 계층 +- 배포 사용자 계정 및 SSH 접근 +- Docker / Docker Compose +- 기본 로그 경로 +- 시스템 시간대, 방화벽, 필수 패키지 +- 재부팅 후 자동 기동 정책(systemd 또는 compose 운영 규칙) + +### 3.2 프로젝트 루트 구조 +- `/home/admin/robeing` +- `/home/admin/infra-config` +- 서비스별 배포 루트 경로 +- 로그/데이터/마운트 경로 + +### 3.3 설정 SSOT 계층 +- `/home/admin/infra-config/runtime.env` +- `/home/admin/infra-config/secrets.env` +- 서비스별 `.env`는 비워 두거나 로컬 오버라이드 전용으로 유지 +- IP/포트/내부 호스트/외부 연계 주소는 runtime.env 기준으로만 관리 + +### 3.4 네트워크/연계 +- 24 -> 23 DB 접근 확인 +- 24 -> NAS 또는 대체 스토리지 접근 확인 +- 23 gateway가 24 upstream으로 다시 붙을 수 있는지 확인 +- 헬스체크/내부 포트/UFW 정책 선반영 + +## 4. 복구 대상 서비스 +### 4.1 우선 복구 +- `rb8001` +- `skill-email` +- `skill-calendar` +- `skill-news` +- `skill-slack` +- `skill-rag-file` +- `skill-embedding` +- `ChromaDB` + +### 4.2 조건부 복구 +- `robeing-monitor` +- 기타 실험/보조 컨테이너 + +원칙: +- 프로덕션 핵심 경로를 먼저 복구한다. +- 모니터링/실험 서비스는 핵심 경로 안정화 후 붙인다. + +## 5. 단계별 실행 계획 +### 5.1 Phase 1: 바닥 공사 +- 24 서버 기본 패키지, Docker, 사용자 권한, SSH 키, 방화벽 구성 +- 프로젝트 루트 디렉터리 생성 +- `infra-config` 배치 및 권한 적용 +- Gitea Actions가 접근할 배포 경로 생성 + +완료 기준: +- SSH 접속 가능 +- Docker 실행 가능 +- 배포 경로/권한 오류 없음 + +### 5.2 Phase 2: 설정 이식 +- 23 기준 운영값 중 24에 필요한 항목만 선별 +- `runtime.env`와 `secrets.env`에 반영 +- 하드코딩 IP/경로가 남아 있는 서비스는 이 단계에서 제거 + +완료 기준: +- 각 서비스 compose가 24에서 동일한 SSOT 파일을 읽음 +- 서비스 내부 코드에 23 전용 하드코딩이 남아 있지 않음 + +### 5.3 Phase 3: 데이터/스토리지 연계 +- PostgreSQL 연결 확인 +- ChromaDB 볼륨 및 데이터 경로 확인 +- NAS 또는 공유 스토리지 마운트 확인 +- 로그 저장 경로 확인 + +완료 기준: +- DB read/write 정상 +- 필요한 파일 마운트가 실제 경로에서 읽힘 +- 로그가 지정 경로에 기록됨 + +### 5.4 Phase 4: 서비스 기동 +- 핵심 서비스부터 `docker compose down && docker compose up -d --build` +- 각 서비스별 헬스체크 확인 +- 컨테이너 포트/네트워크 실제 바인딩 확인 + +완료 기준: +- `docker ps` 기준 핵심 컨테이너 running/healthy +- 서비스별 health endpoint 응답 정상 + +### 5.5 Phase 5: 23과 연결 복구 +- 23 gateway upstream을 24 기준으로 재설정 +- auth / gateway / upstream 로그를 같은 요청 기준으로 대조 +- 실제 도메인 기준 요청 흐름 검증 + +완료 기준: +- `ro-being.com` 실제 경로에서 핵심 API 응답 정상 +- gateway/nginx/upstream 로그가 한 요청 기준으로 이어짐 + +### 5.6 Phase 6: 역할 정상화 +- 24를 프로덕션으로 확정 +- 23의 임시 실행 컨테이너 정리 +- 23을 다시 `테스트 + 보조 + 인프라` 역할로 축소 +- 임시 예외 설정 제거 여부 확인 + +완료 기준: +- 프로덕션 트래픽 기준 서버가 24로 고정됨 +- 23은 테스트/보험 역할만 수행 + +## 6. 검증 체크리스트 +1. 인프라 +- SSH, Docker, disk, memory, UFW 정상 + +2. 데이터 +- 24에서 PostgreSQL 연결 정상 +- ChromaDB 경로/볼륨 정상 +- 공유 스토리지 접근 정상 + +3. 서비스 +- `rb8001` health 정상 +- 핵심 스킬 health 정상 +- monitor 필요 시 health 정상 + +4. 요청 흐름 +- 실제 도메인에서 gateway -> upstream 응답 정상 +- 인증 경로 정상 +- 로그가 요청 단위로 추적 가능 + +5. 운영 +- Actions 배포 성공 +- 재기동 후 자동 복구 가능 +- 23/24 역할 문서와 실제 구성이 일치 + +## 7. 실패 패턴 경계 +- 23의 임시값을 24 복구값으로 착각하는 것 +- `.env`, compose, 코드, 문서가 각각 다른 값을 갖는 것 +- 컨테이너만 살아 있고 실제 도메인 요청은 실패하는 상태를 정상으로 오판하는 것 +- 24 복구 전에 23 임시 설정을 정리해 버리는 것 + +## 8. 복구 완료 선언 조건 +- 24에서 핵심 서비스가 healthy +- 실제 도메인 기준 핵심 경로 응답 정상 +- 23 gateway와 24 upstream 연결 정상 +- 문서, runtime.env/secrets.env, 배포 경로가 서로 일치 +- 23 임시운영 예외 항목이 후속 문서에 정리됨 + +## 9. 후속 문서 연결 +- [260303_23테스트보조_24프로덕션_운영전환_계획](./260303_23테스트보조_24프로덕션_운영전환_계획.md) +- [260304_24장애시_23자동임시프로덕션전환_계획](./260304_24장애시_23자동임시프로덕션전환_계획.md) +- [260304_51123_임시복구_서비스연속성_조치내역](../troubleshooting/260304_51123_임시복구_서비스연속성_조치내역.md) +- [260307_gateway_SSOT_runtime_secrets_분리_적용_및_검증](../troubleshooting/260307_gateway_SSOT_runtime_secrets_분리_적용_및_검증.md) diff --git a/journey/plans/archive/250808_감정시스템_현실적용_5단계_로드맵.md b/journey/plans/archive/250808_감정시스템_현실적용_5단계_로드맵.md index 13b2774..6749547 100644 --- a/journey/plans/archive/250808_감정시스템_현실적용_5단계_로드맵.md +++ b/journey/plans/archive/250808_감정시스템_현실적용_5단계_로드맵.md @@ -40,6 +40,6 @@ - `book/200_core_design/225_온톨로지_기반_지식_표현.md` - `book/300_architecture/311_백엔드_구조_원칙.md` -- `book/300_architecture/312_문서_작성_원칙.md` +- `book/300_architecture/312_writing-principles.md` - `book/300_architecture/315_테스트_원칙.md` - `troubleshooting/251002_emotion_top-p_improvement.md` (감정 직접 노출 금지) diff --git a/journey/plans/archive/250906_news_system_integration.md b/journey/plans/archive/250906_news_system_integration.md index f6218d5..7dc3005 100644 --- a/journey/plans/archive/250906_news_system_integration.md +++ b/journey/plans/archive/250906_news_system_integration.md @@ -62,5 +62,5 @@ SKILL_PUBLISH_URL=http://localhost:8511 ### 원칙 문서 - `book/300_architecture/311_백엔드_구조_원칙.md` - 계층 분리, Repository 패턴, 테스트 원칙 -- `book/300_architecture/312_문서_작성_원칙.md` - 문서 작성 규칙 +- `book/300_architecture/312_writing-principles.md` - 문서 작성 규칙 - `book/300_architecture/database/tables.md` - rb_news 테이블 스키마 참고 diff --git a/journey/plans/archive/251016_ontology_coldmail_implementation.md b/journey/plans/archive/251016_ontology_coldmail_implementation.md index 4eecdf6..7564c97 100644 --- a/journey/plans/archive/251016_ontology_coldmail_implementation.md +++ b/journey/plans/archive/251016_ontology_coldmail_implementation.md @@ -6,7 +6,7 @@ **원칙 참조** (구현 전 필수 확인): - `311_백엔드_구조_원칙.md`: 계층 분리, DB는 state 경유 -- `312_문서_작성_원칙.md`: 핵심만 간결, 파일명:줄번호 +- `312_writing-principles.md`: 핵심만 간결, 파일명:줄번호 - `315_테스트_원칙.md`: 테스트는 TDD로 진행 (Red → Green → Refactor) --- diff --git a/journey/plans/archive/251206_skill_calendar_자동배포_구성.md b/journey/plans/archive/251206_skill_calendar_자동배포_구성.md index b79e289..112d24f 100644 --- a/journey/plans/archive/251206_skill_calendar_자동배포_구성.md +++ b/journey/plans/archive/251206_skill_calendar_자동배포_구성.md @@ -30,5 +30,5 @@ skill-calendar 서비스를 Gitea Actions를 통해 51124 서버에 자동 배 - `troubleshooting/251225_skill_calendar_자동배포_구성.md`: 구현 완료 기록 - `troubleshooting/250728_happybell80_nginx프록시및CI배포문제해결.md`: SSH 인증 실패 해결 -- `book/300_architecture/312_문서_작성_원칙.md`: 문서 작성 원칙 +- `book/300_architecture/312_writing-principles.md`: 문서 작성 원칙 diff --git a/journey/plans/archive/260202_뉴스브리핑_LangGraph_전환.md b/journey/plans/archive/260202_뉴스브리핑_LangGraph_전환.md index 192a832..d11c6f0 100644 --- a/journey/plans/archive/260202_뉴스브리핑_LangGraph_전환.md +++ b/journey/plans/archive/260202_뉴스브리핑_LangGraph_전환.md @@ -5,7 +5,7 @@ **관련 파일**: `rb8001/app/services/skills/startup_news_skill.py`, `rb8001/app/services/workflows/headlines_workflow.py`, `rb8001/tests/test_headlines_workflow.py` **원칙 참조** (구현 전 필수 확인): - `311_백엔드_구조_원칙.md`: LangGraph 워크플로우 (섹션 5), 계층 분리 -- `312_문서_작성_원칙.md`: 핵심만 간결, 파일명:줄번호 +- `312_writing-principles.md`: 핵심만 간결, 파일명:줄번호 - `315_테스트_원칙.md`: 테스트는 TDD로 진행 (Red → Green → Refactor) --- @@ -109,5 +109,5 @@ START → fetch_naver → fetch_sea → extract_terms → format → send → EN ## 참고 - `book/300_architecture/311_백엔드_구조_원칙.md` -- `book/300_architecture/312_문서_작성_원칙.md` +- `book/300_architecture/312_writing-principles.md` - `book/300_architecture/315_테스트_원칙.md` diff --git a/journey/plans/archive/260304_51124_먹통_근본원인_해결계획.md b/journey/plans/archive/260304_51124_먹통_근본원인_해결계획.md index 1c6303f..d5946aa 100644 --- a/journey/plans/archive/260304_51124_먹통_근본원인_해결계획.md +++ b/journey/plans/archive/260304_51124_먹통_근본원인_해결계획.md @@ -10,7 +10,7 @@ - [51124 먹통 원인 확정 리서치](../research/260304_51124_먹통_48시간_코드차분_원인확정_리서치.md) - [51124 먹통 사용자 시나리오](../scenarios/260304_아침브리핑_지연_먹통_복구_사용자시나리오.md) - [51123 임시복구 조치내역](../troubleshooting/260304_51123_임시복구_서비스연속성_조치내역.md) -- [문서 작성 원칙](../../book/300_architecture/312_문서_작성_원칙.md) +- [문서 작성 원칙](../../book/300_architecture/312_writing-principles.md) ## 2. 근본 원인(확정) - `INTENT_ENGINE=graph` + `INTENT_USE_LANGGRAPH=true`에서 diff --git a/journey/research/README.md b/journey/research/README.md index 690b9a7..7b4dbb6 100644 --- a/journey/research/README.md +++ b/journey/research/README.md @@ -3,7 +3,7 @@ ## 개요 로빙 프로젝트의 학술적 기반과 참고한 연구들을 정리한 섹션입니다. -리서치 문서 작성 원칙(SSOT): [`../../book/300_architecture/312_문서_작성_원칙.md`의 "리서치 문서" 섹션](../../book/300_architecture/312_%EB%AC%B8%EC%84%9C_%EC%9E%91%EC%84%B1_%EC%9B%90%EC%B9%99.md) +리서치 문서 작성 원칙(SSOT): [`../../book/300_architecture/312_writing-principles.md`의 "리서치 문서" 섹션](../../book/300_architecture/312_writing-principles.md) ## 연구 분야 diff --git a/journey/research/orchestration_tools/260205_openclaw_로빙_적용_리서치.md b/journey/research/orchestration_tools/260205_openclaw_로빙_적용_리서치.md index 2a5964f..68a1dce 100644 --- a/journey/research/orchestration_tools/260205_openclaw_로빙_적용_리서치.md +++ b/journey/research/orchestration_tools/260205_openclaw_로빙_적용_리서치.md @@ -1,7 +1,7 @@ # OpenClaw 아키텍처 분석 및 로빙 적용 리서치 **작성일**: 2026-02-05 (260226 보완) -**참고**: 312_문서_작성_원칙.md, 311_백엔드_구조_원칙.md +**참고**: 312_writing-principles.md, 311_백엔드_구조_원칙.md **원본**: https://github.com/openclaw/openclaw **로컬 클론**: `ivada/openclaw` (260226 클론) @@ -124,7 +124,7 @@ OpenClaw(구 Moltbot/Clawdbot)는 WhatsApp·Slack·Telegram 등 메신저로 대 ## 6. 참고 문서 - 311_백엔드_구조_원칙.md: 계층 분리, LangGraph 워크플로우 -- 312_문서_작성_원칙.md: 핵심만 간결, 파일명:줄번호 +- 312_writing-principles.md: 핵심만 간결, 파일명:줄번호 - 360_로빙_컨테이너_경량화_전략.md: Stateless Router + Microservices - orchestration_tools/250925_langgraph_vs_n8n_comparison.md: LangGraph vs n8n - orchestration_tools/260205_openclaw_official_docs_summary.md: OpenClaw 공식 문서 요약 (docs.openclaw.ai) diff --git a/journey/troubleshooting/250103_감정_기반_응답_길이_제어_구현.md b/journey/troubleshooting/250103_감정_기반_응답_길이_제어_구현.md index 590b95d..be3018b 100644 --- a/journey/troubleshooting/250103_감정_기반_응답_길이_제어_구현.md +++ b/journey/troubleshooting/250103_감정_기반_응답_길이_제어_구현.md @@ -77,6 +77,6 @@ emotion_length_map = { ## 참고 - `plans/archive/251016_emotion_integration_plan.md`: 원본 계획 문서 -- `312_문서_작성_원칙.md`: 문서 작성 원칙 +- `312_writing-principles.md`: 문서 작성 원칙 - `315_테스트_작성_원칙.md`: 테스트 작성 원칙 diff --git a/journey/troubleshooting/251019_claude_rb8001_미해결_이슈_정리.md b/journey/troubleshooting/251019_claude_rb8001_미해결_이슈_정리.md index 25e7bb2..c7decbb 100644 --- a/journey/troubleshooting/251019_claude_rb8001_미해결_이슈_정리.md +++ b/journey/troubleshooting/251019_claude_rb8001_미해결_이슈_정리.md @@ -2,7 +2,7 @@ **날짜**: 2025-10-19 **작성자**: Claude (51124) -**작성 원칙**: `DOCS/300_architecture/312_문서_작성_원칙.md` 준수 +**작성 원칙**: `DOCS/300_architecture/312_writing-principles.md` 준수 **참고**: `CLAUDE.md`의 트러블슈팅 작성 규칙 및 범위 --- diff --git a/journey/troubleshooting/251021_admin_gemini_single_model_and_ethics_visibility.md b/journey/troubleshooting/251021_admin_gemini_single_model_and_ethics_visibility.md index cc5cf90..756fbc9 100644 --- a/journey/troubleshooting/251021_admin_gemini_single_model_and_ethics_visibility.md +++ b/journey/troubleshooting/251021_admin_gemini_single_model_and_ethics_visibility.md @@ -83,4 +83,4 @@ Ethics violation detected: **윤리적 제약 위반**: 공정성 원칙 - `rb8001@daad1bd` rb8001: use only gemini-2.5-flash-lite; hide ethics text from user; dedup Gemini init; clarify ethics priority --- -문서 규칙: `DOCS/300_architecture/312_문서_작성_원칙.md` 준수 +문서 규칙: `DOCS/300_architecture/312_writing-principles.md` 준수 diff --git a/journey/troubleshooting/251021_admin_slack_doc_analysis_pipeline_langgraph.md b/journey/troubleshooting/251021_admin_slack_doc_analysis_pipeline_langgraph.md index cbf6755..3d34c96 100644 --- a/journey/troubleshooting/251021_admin_slack_doc_analysis_pipeline_langgraph.md +++ b/journey/troubleshooting/251021_admin_slack_doc_analysis_pipeline_langgraph.md @@ -90,4 +90,4 @@ Non-text message subtype ignored: message_changed - `rb8001@daad1bd` single gemini + hide ethics text --- -문서 규칙: `DOCS/300_architecture/312_문서_작성_원칙.md` 준수 +문서 규칙: `DOCS/300_architecture/312_writing-principles.md` 준수 diff --git a/journey/troubleshooting/251022_claude_OCR_파이프라인_개선_테스트.md b/journey/troubleshooting/251022_claude_OCR_파이프라인_개선_테스트.md index 76febe2..a9d36c1 100644 --- a/journey/troubleshooting/251022_claude_OCR_파이프라인_개선_테스트.md +++ b/journey/troubleshooting/251022_claude_OCR_파이프라인_개선_테스트.md @@ -110,4 +110,4 @@ 상세 내역: `251023_claude_skill-rag-file_OCR_품질_개선_배포.md` --- -문서 규칙: `DOCS/300_architecture/312_문서_작성_원칙.md` 준수 +문서 규칙: `DOCS/300_architecture/312_writing-principles.md` 준수 diff --git a/journey/troubleshooting/251022_claude_rb8001_web_search_미수행.md b/journey/troubleshooting/251022_claude_rb8001_web_search_미수행.md index 545fb02..b31c2e4 100644 --- a/journey/troubleshooting/251022_claude_rb8001_web_search_미수행.md +++ b/journey/troubleshooting/251022_claude_rb8001_web_search_미수행.md @@ -98,4 +98,4 @@ - CQR/엔티티링크·rerank 추가: resolve→link→cqr→search→rerank→summarize→format 파이프 및 AsyncSqliteSaver 도입 (커밋: `8cdb444`) --- -문서 규칙: `DOCS/300_architecture/312_문서_작성_원칙.md` 준수 +문서 규칙: `DOCS/300_architecture/312_writing-principles.md` 준수 diff --git a/journey/troubleshooting/251023_claude_skill-rag-file_OCR_품질_개선_배포.md b/journey/troubleshooting/251023_claude_skill-rag-file_OCR_품질_개선_배포.md index 54e44e3..c0a8ca9 100644 --- a/journey/troubleshooting/251023_claude_skill-rag-file_OCR_품질_개선_배포.md +++ b/journey/troubleshooting/251023_claude_skill-rag-file_OCR_품질_개선_배포.md @@ -160,4 +160,4 @@ curl -X POST http://localhost:8508/api/reindex \ - 재색인 API는 점진적 품질 개선과 A/B 테스트에 유용. force_ocr 플래그로 안전하게 제어 가능. --- -문서 규칙: `DOCS/300_architecture/312_문서_작성_원칙.md` 준수 +문서 규칙: `DOCS/300_architecture/312_writing-principles.md` 준수 diff --git a/journey/troubleshooting/251128_ir_deck_valuation_backend_architecture.md b/journey/troubleshooting/251128_ir_deck_valuation_backend_architecture.md index ed5b47f..14f5c74 100644 --- a/journey/troubleshooting/251128_ir_deck_valuation_backend_architecture.md +++ b/journey/troubleshooting/251128_ir_deck_valuation_backend_architecture.md @@ -184,4 +184,4 @@ CREATE TABLE ir_deck_feedback ( ## 관련 문서 - [IR Deck 배치 테스트 문제점 분석](./251128_ir_deck_batch_test_issues.md) - 배치 테스트 결과 및 해결 사항 -- `DOCS/book/300_architecture/312_문서_작성_원칙.md` - 문서 작성 규칙 +- `DOCS/book/300_architecture/312_writing-principles.md` - 문서 작성 규칙 diff --git a/journey/troubleshooting/251216_bayesian_presentation_ballquiz_redesign.md b/journey/troubleshooting/251216_bayesian_presentation_ballquiz_redesign.md index 66f00d7..33d26ac 100644 --- a/journey/troubleshooting/251216_bayesian_presentation_ballquiz_redesign.md +++ b/journey/troubleshooting/251216_bayesian_presentation_ballquiz_redesign.md @@ -113,7 +113,7 @@ - 포트 사용 전 `netstat` 또는 `ss` 명령어로 사용 중인 포트 확인 - nginx 설정 파일에서 프록시 포트 확인 (`/etc/nginx/sites-enabled/default`) - 다른 서비스와 충돌하지 않는 포트 사용 -- **원칙**: `312_문서_작성_원칙.md` - 확인된 사실만 기록 +- **원칙**: `312_writing-principles.md` - 확인된 사실만 기록 ### 프론트엔드/백엔드 기본값 일치 확인 - **원인**: Section 1 제거 후 프론트엔드만 section 2로 변경, 백엔드는 section 1 유지 diff --git a/journey/troubleshooting/260226_NAS_192_168_219_51_접속불가_임시백업복구.md b/journey/troubleshooting/260226_NAS_192_168_219_51_접속불가_임시백업복구.md index 278a225..b5ee469 100644 --- a/journey/troubleshooting/260226_NAS_192_168_219_51_접속불가_임시백업복구.md +++ b/journey/troubleshooting/260226_NAS_192_168_219_51_접속불가_임시백업복구.md @@ -35,3 +35,6 @@ ## 참고 - 기존 NAS 백업 체계 문서: `./250729_서버백업및로그관리체계구축.md` + +## 후속 문서 +- 다음 단계: [260307_NAS_192_168_0_101_SSOT_전환_및_CIFS_실마운트_복구](./260307_NAS_192_168_0_101_SSOT_전환_및_CIFS_실마운트_복구.md) diff --git a/journey/troubleshooting/260306_51123_gitea_lfs_permission_denied_502_복구.md b/journey/troubleshooting/260306_51123_gitea_lfs_permission_denied_502_복구.md index 434b09d..834b7ba 100644 --- a/journey/troubleshooting/260306_51123_gitea_lfs_permission_denied_502_복구.md +++ b/journey/troubleshooting/260306_51123_gitea_lfs_permission_denied_502_복구.md @@ -1,5 +1,7 @@ # 51123 Gitea LFS 권한 오류로 인한 git.ro-being.com 502 복구 +tags: [gitea, lfs, nas, recovery] + **날짜**: 2026-03-06 **작성자**: admin **관련 파일**: `/etc/gitea/app.ini`, `/etc/nginx/sites-enabled/default` @@ -37,3 +39,6 @@ - Gitea LFS가 NAS 경로를 사용하면, 서비스 기동 전 `마운트 상태 + 대상 디렉터리 소유권`이 동시에 만족되어야 함. - `502`만 보고 nginx 문제로 단정하면 오판 가능성이 높고, 반드시 `nginx(upstream) + systemd(gitea) + journal`을 같은 시각대로 교차 확인해야 함. - 스토리지 경로가 마운트 의존일 때는 마운트 해제/권한 변동 감시를 운영 체크리스트에 포함해야 함. + +## 후속 문서 +- 다음 단계: [260307_Gitea_LFS_NAS_권한정렬_및_실업로드_검증](./260307_Gitea_LFS_NAS_권한정렬_및_실업로드_검증.md) diff --git a/journey/troubleshooting/260307_Gitea_LFS_NAS_권한정렬_및_실업로드_검증.md b/journey/troubleshooting/260307_Gitea_LFS_NAS_권한정렬_및_실업로드_검증.md new file mode 100644 index 0000000..423d460 --- /dev/null +++ b/journey/troubleshooting/260307_Gitea_LFS_NAS_권한정렬_및_실업로드_검증.md @@ -0,0 +1,73 @@ +# 260307 Gitea LFS NAS 권한정렬 및 실업로드 검증 + +tags: [gitea, lfs, nas, cifs, ssot] + +**날짜**: 2026-03-07 +**작성자**: admin +**관련 파일**: `/etc/gitea/app.ini`, `/usr/local/bin/mount-nas-ssot.sh`, `/etc/systemd/system/mount-nas-ssot.service`, `/home/admin/infra-config/runtime.env`, `/home/admin/infra-config/secrets.env` + +--- + +## 문제 상황 +- Gitea는 기동 중이었고 `git.ro-being.com` 일반 Git push/pull도 정상 동작했다. +- 하지만 실제 `git lfs push` 검증에서는 `500 Internal Server Error`로 실패했다. +- 즉 "LFS 경로가 설정돼 있다"와 "실제 대용량 파일 업로드가 된다"가 분리된 상태였다. + +## 검증으로 확인한 사실 +1. 일반 Git 경로는 정상 +- `git push`, `git pull`은 정상 + +2. LFS 경로는 비정상 +- 실제 `git lfs` 업로드 테스트에서 반복적으로 `500` 발생 +- `journalctl -u gitea` 기준 실패 시각(2026-03-07 09:35 KST) 로그: + - `mkdir /mnt/nas/gitea-lfs/18: permission denied` + +3. 근본 원인 +- `gitea.service`는 `git:git (uid=131 gid=138)`로 실행 +- NAS CIFS 마운트는 `uid=1001,gid=1000,file_mode=0755,dir_mode=0755` 기준 +- 결과적으로 `/mnt/nas/gitea-lfs`는 `admin:xusers` 소유처럼 보였고, `git` 사용자는 쓰기 불가 + +## 실제 조치 +### 1. 마운트 권한 정렬 +- `/usr/local/bin/mount-nas-ssot.sh`의 CIFS 옵션을 아래 기준으로 조정 + - `uid=1001` + - `gid=1000` + - `forceuid,forcegid` + - `file_mode=0664` + - `dir_mode=0775` + +### 2. Gitea 실행 사용자 그룹 정렬 +- `git` 사용자를 `xusers` 그룹에 추가 +- 결과: `git` 사용자가 `/mnt/nas/gitea-lfs`에 그룹 쓰기 가능 + +### 3. 서비스 반영 +- NAS 재마운트 실행 +- `gitea.service` 재시작 +- `sudo -u git` 기준 직접 쓰기 테스트 성공 + +## 재검증 결과 +1. 권한 +- `id git` -> `groups=138(git),1000(xusers)` +- `/mnt/nas/gitea-lfs` -> `drwxrwxr-x` + +2. 실업로드 검증 +- `test-meta-skill` 저장소에 임시 브랜치 생성 후 1MB 바이너리 파일을 `git lfs`로 push +- 재클론 후 `git lfs pull` 수행 +- 원본과 재다운로드 파일 SHA256 일치 + +3. NAS 저장 확인 +- 실제 생성 경로: + - `/mnt/nas/gitea-lfs/4a/22/ae83cbb68dcdcddb9e053fdce9466e63463881c981597bb6c797ca4a0f7b` +- 검증 시점 기준 LFS 파일 수: + - before=0 + - after_push=1 + - after_pull=1 + +## 결론 +- 현재 Gitea LFS는 설정상 연결된 수준이 아니라, 실제로 NAS에 대용량 파일을 저장하는 상태까지 검증 완료됐다. +- 이번 조치로 `git lfs push -> Gitea -> /mnt/nas/gitea-lfs` 경로가 실동작함을 확인했다. +- 이후 동일 계열 문제 재발 시, `Gitea 상태`보다 먼저 `gitea 실행 사용자`와 `NAS 마운트 권한`을 함께 봐야 한다. + +## 전후 관계 문서 +- 이전: [260306_51123_gitea_lfs_permission_denied_502_복구](./260306_51123_gitea_lfs_permission_denied_502_복구.md) +- 관련: [260307_NAS_192_168_0_101_SSOT_전환_및_CIFS_실마운트_복구](./260307_NAS_192_168_0_101_SSOT_전환_및_CIFS_실마운트_복구.md) diff --git a/journey/troubleshooting/260307_NAS_192_168_0_101_SSOT_전환_및_CIFS_실마운트_복구.md b/journey/troubleshooting/260307_NAS_192_168_0_101_SSOT_전환_및_CIFS_실마운트_복구.md new file mode 100644 index 0000000..fd4f074 --- /dev/null +++ b/journey/troubleshooting/260307_NAS_192_168_0_101_SSOT_전환_및_CIFS_실마운트_복구.md @@ -0,0 +1,74 @@ +# 260307 NAS(192.168.0.101) SSOT 전환 및 CIFS 실마운트 복구 + +## 시간 +- 기준일: 2026-03-07 +- 작업 시각: 2026-03-07 오전 + +## 배경 +- 서버 이전 후 NAS 내부 사설 IP가 `192.168.219.51`에서 `192.168.0.101`로 변경되었다. +- 51123은 임시운영 상태에서 `/mnt/nas`를 다시 실NAS로 연결해야 했고, 동시에 SSOT 원칙에 맞게 NAS 설정을 정리할 필요가 있었다. +- 기존 `/mnt/nas`는 실제 마운트가 아니라 로컬 디렉터리처럼 남아 있었고, `weekly-backup.sh`가 기대하는 `/mnt/nas/backup/weekly`도 실NAS 기준으로는 정합성이 깨져 있었다. + +## 확인된 사실 +1. `192.168.0.101`은 실제 응답하는 NAS였다. +- `ping` 정상 응답 +- `22/80/443/139/445/5000/5001` 포트 오픈 확인 +- `5000/5001` 응답 기준 Synology DSM 장비 확인 + +2. NAS 내부에는 기존 백업 구조가 남아 있었다. +- `home` 공유 접근 가능 +- `backup/current/{robing,gitea,config}` 존재 +- `gitea-lfs` 디렉터리 존재 + +3. 서버 쪽 마운트 설정은 구식 값이 남아 있었다. +- `/etc/fstab`에 `//192.168.219.51/home /mnt/nas cifs username=admin,password=...` 형태의 평문 설정 존재 +- 이는 이전 IP 기준이며, SSOT 원칙에도 맞지 않았다. + +## 실제 조치 +### 1. NAS 접근 확인 +- `smbclient -L //192.168.0.101 -U admin%...` 로 `home`, `homes` 공유 확인 +- `smbclient //192.168.0.101/home ...` 로 `backup`, `gitea-lfs` 실제 존재 확인 + +### 2. SSOT 반영 +- `/home/admin/infra-config/runtime.env` + - `NAS_HOST=192.168.0.101` + - `NAS_SMB_PORT=445` + - `NAS_SHARE=home` + - `NAS_MOUNT_PATH=/mnt/nas` +- `/home/admin/infra-config/secrets.env` + - `NAS_USERNAME=admin` + - `NAS_PASSWORD=...` + +### 3. 마운트 방식 교체 +- `/etc/fstab`의 평문 CIFS 항목은 주석 처리 +- `/usr/local/bin/mount-nas-ssot.sh` 생성 + - `runtime.env`, `secrets.env`를 읽어 CIFS 마운트 수행 +- `/etc/systemd/system/mount-nas-ssot.service` 생성 및 enable + - 부팅 후 SSOT 기준으로 NAS 마운트 복구 가능하도록 구성 + +### 4. 권한 정합화 +- 초기 마운트는 `uid=1000` 기준이라 현재 사용자 `admin(uid=1001)`가 쓰기 불가 +- 마운트 옵션을 `uid=1001,gid=1000`으로 교정 +- 이후 `/mnt/nas/backup/weekly` 생성 및 쓰기 가능 확인 + +## 검증 결과 +1. 마운트 상태 +- `//192.168.0.101/home on /mnt/nas type cifs` 확인 +- `df -h /mnt/nas` 기준 5.3T 마운트 정상 + +2. 구조 확인 +- `/mnt/nas/backup/current` +- `/mnt/nas/backup/archives` +- `/mnt/nas/gitea-lfs` + +3. 쓰기 확인 +- `/mnt/nas/backup/weekly/latest.txt` 생성 및 기록 성공 + +## 결론 +- 51123의 `/mnt/nas`는 다시 실NAS(`192.168.0.101`)를 바라보도록 복구되었다. +- NAS 접속 정보는 `infra-config/runtime.env` + `secrets.env` 기준으로 SSOT화되었다. +- 기존 `nas-fallback` 임시 우회 상태에서 한 단계 진전했지만, fallback 데이터 동기화 여부는 별도 점검이 필요하다. + +## 전후 관계 문서 +- 이전: [260226_NAS_192_168_219_51_접속불가_임시백업복구](./260226_NAS_192_168_219_51_접속불가_임시백업복구.md) +- 관련: [260307_51123_성수이전_네트워크변경_운영기록](./260307_51123_성수이전_네트워크변경_운영기록.md)