From ccaf367916041bf58ad490c044db20d6972837d9 Mon Sep 17 00:00:00 2001
From: happybell80 <goeun2dcc@gmail.com>
Date: Wed, 16 Jul 2025 16:12:13 +0900
Subject: [PATCH] docs: Add troubleshooting guide for Gemini CLI, Slack, and
 network issues
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Document Gemini CLI executable not found solution
- Add USE_ASYNC_RESPONSE configuration fix
- Explain network integration for backend communication
- Include CI/CD path migration from test_api to rb10508_test

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 ...716_SSD_용량_부족_및_Docker_정리.md | 149 +++++++++++++++
 ...6_frontend_admin_dashboard_improvements.md | 145 +++++++++++++++
 ...0250716_gemini_cli_slack_network_issues.md | 169 ++++++++++++++++++
 3 files changed, 463 insertions(+)
 create mode 100644 docs/troubleshooting/20250716_SSD_용량_부족_및_Docker_정리.md
 create mode 100644 docs/troubleshooting/20250716_frontend_admin_dashboard_improvements.md
 create mode 100644 docs/troubleshooting/20250716_gemini_cli_slack_network_issues.md

diff --git a/docs/troubleshooting/20250716_SSD_용량_부족_및_Docker_정리.md b/docs/troubleshooting/20250716_SSD_용량_부족_및_Docker_정리.md
new file mode 100644
index 0000000..183bdd1
--- /dev/null
+++ b/docs/troubleshooting/20250716_SSD_용량_부족_및_Docker_정리.md
@@ -0,0 +1,149 @@
+# SSD 용량 부족 및 Docker 정리
+
+**날짜**: 2025-07-16  
+**문제**: Ubuntu 서버 SSD 용량 부족으로 인한 시스템 성능 저하  
+**해결 시간**: 약 2시간  
+**담당자**: admin  
+
+## 문제 상황
+
+- Ubuntu 서버 SSD 용량 부족 (228GB 중 65GB 사용, 30%)
+- Docker 이미지 및 캐시가 38.62GB 차지 (37.27GB 재사용 가능)
+- 불필요한 파일들이 /home/admin/에 산재
+
+## 원인 분석
+
+### 1. Docker 관련 (58GB - 최대 원인)
+- `/var/lib/docker/overlay2`: 52GB (컨테이너 레이어)
+- `/var/lib/docker/volumes`: 6.2GB
+- 미사용 이미지 43개, 빌드 캐시 218개
+
+### 2. 불필요한 디렉토리 (57MB)
+- `/home/admin/test_api/`: 17M (rb10508 이전 버전)
+- `/home/admin/github-migration/`: 21M (GitHub→Gitea 마이그레이션 도구)
+- `/home/admin/logs/`: 13M (오래된 로그)
+- `/home/admin/robeing-nginx/`: 36K
+
+### 3. 중복 파일
+- Docker 관련 파일들 (Dockerfile, requirements.txt, docker-compose.yml)
+- Python 캐시 (.cache/uv/archive-v0/)
+
+## 해결 과정
+
+### 1단계: 불필요한 디렉토리 정리
+
+```bash
+# HDD dump 디렉토리 생성
+mkdir -p /mnt/hdd/dump
+
+# 불필요한 디렉토리들을 HDD로 이동
+sudo cp -r /home/admin/test_api /mnt/hdd/dump/ && sudo rm -rf /home/admin/test_api
+sudo cp -r /home/admin/github-migration /mnt/hdd/dump/ && sudo rm -rf /home/admin/github-migration
+sudo cp -r /home/admin/robeing-nginx /mnt/hdd/dump/ && sudo rm -rf /home/admin/robeing-nginx
+sudo cp -r /home/admin/logs /mnt/hdd/dump/ && sudo rm -rf /home/admin/logs
+
+# 임시 파일 삭제
+rm -rf /home/admin/temp/
+```
+
+### 2단계: Docker 시스템 정리
+
+```bash
+# 미사용 이미지 정리 (34개 삭제)
+docker image prune -f
+
+# 중단된 컨테이너 정리 (2개, 1.65MB)
+docker container prune -f
+
+# 미사용 네트워크 정리
+docker network prune -f
+
+# 미사용 볼륨 정리 (15개, 4.95GB)
+docker volume prune -f
+
+# 빌드 캐시 정리 (218개 → 47개, 30.12GB)
+docker builder prune -f
+```
+
+### 3단계: 자동화 스크립트 개선
+
+```bash
+# 백업 스크립트 이름 변경 및 기능 확장
+mv /home/admin/backup-to-nas.sh /home/admin/maintenance-scheduler.sh
+
+# Docker 정리 섹션 추가 (일요일마다 실행)
+# - 미사용 이미지/컨테이너/네트워크 정리
+# - 1주일 이상된 빌드 캐시 정리
+
+# crontab 업데이트
+echo "0 2 * * * /home/admin/maintenance-scheduler.sh >> /var/log/maintenance/cron.log 2>&1" | sudo crontab -
+```
+
+## 결과
+
+- **SSD 사용률**: 30% → 14% (35GB 절약)
+- **여유 공간**: 152GB → 187GB
+- **Docker 용량**: 38.62GB → 8.46GB
+- **정리된 항목**: 이미지 34개, 볼륨 15개, 빌드 캐시 218개
+
+## 예방 조치
+
+### 1. 자동 정리 스케줄
+- **매일 새벽 2시**: 데이터 백업
+- **매주 일요일**: Docker 시스템 정리
+- **매월 1일**: 월간 아카이브 생성
+
+### 2. 모니터링
+- maintenance-scheduler.sh에서 정리 결과 로깅
+- /var/log/maintenance/ 디렉토리에 작업 로그 저장
+
+### 3. 구조 개선
+- 로그 파일들을 HDD로 이동 (심링크 연결)
+- 백업 파일들을 /mnt/hdd/frontend-backups/로 이동
+
+## 교훈
+
+- Docker는 정기적인 정리 없이는 지속적으로 용량을 차지함
+- 빌드 캐시가 가장 큰 용량을 차지하므로 우선 정리 대상
+- 자동화된 정리 스크립트가 필수적
+- 로그와 백업은 HDD를 활용하여 SSD 공간 절약
+
+## 관련 명령어
+
+### 용량 확인
+```bash
+# 디스크 사용량 확인
+df -h
+
+# Docker 용량 확인
+docker system df
+
+# 디렉토리별 용량 확인
+du -sh /var/lib/docker/*
+```
+
+### 정기 정리 명령어
+```bash
+# 전체 Docker 정리 (주의: 실행 중인 컨테이너 제외)
+docker system prune -a -f
+
+# 빌드 캐시만 정리
+docker builder prune -f
+
+# 1주일 이상된 빌드 캐시 정리
+docker builder prune --filter until=168h -f
+```
+
+## 후속 조치
+
+1. **maintenance-scheduler.sh 스크립트 개선**
+   - Docker 정리 로직 추가
+   - 용량 임계치 모니터링 기능 추가
+
+2. **모니터링 대시보드 구축**
+   - SSD/HDD 용량 실시간 모니터링
+   - Docker 용량 추적
+
+3. **백업 전략 개선**
+   - 중요 데이터는 SSD에 유지
+   - 로그 및 아카이브는 HDD로 이동
\ No newline at end of file
diff --git a/docs/troubleshooting/20250716_frontend_admin_dashboard_improvements.md b/docs/troubleshooting/20250716_frontend_admin_dashboard_improvements.md
new file mode 100644
index 0000000..70e6856
--- /dev/null
+++ b/docs/troubleshooting/20250716_frontend_admin_dashboard_improvements.md
@@ -0,0 +1,145 @@
+# Frontend Admin Dashboard 개선 및 문제 해결
+
+**날짜**: 2025-07-16  
+**문제**: Admin 대시보드 서비스 상태 표시 오류 및 Git 활동 미표시  
+**해결 시간**: 약 3시간  
+**담당자**: happybell  
+
+## 문제 상황
+
+### 1. 서비스 상태 표시 오류
+- 증상: Admin 대시보드에서 서비스 상태가 `undefined`로 표시
+- 원인: API 응답 구조 변경으로 인한 프론트엔드 호환성 문제
+- 기존: `return services_status` (직접 반환)
+- 변경: `return { "services": services_status, ... }` (객체로 감싸서 반환)
+
+### 2. Git 활동 미표시
+- 증상: 최근 Git 활동 섹션이 빈 상태로 표시
+- 원인: `/host_home/github-migration/` 경로가 존재하지 않음
+- 배경: 해당 디렉토리는 SSD 용량 문제로 HDD로 이동되었음
+
+### 3. UI 레이아웃 문제
+- Gitea Runners 섹션이 공간을 차지하나 실제 사용되지 않음
+- Git 활동 섹션이 좁아서 저장소명과 커밋 메시지가 잘림
+
+## 해결 과정
+
+### 1. 동적 서비스 발견 기능 추가
+
+```python
+# 서비스 자동 발견 함수 추가
+def discover_docker_services():
+    """Docker 컨테이너에서 노출된 포트 발견"""
+    # Docker 컨테이너 목록에서 포트 정보 추출
+    # 이미 알려진 서비스 제외하고 새로운 서비스만 반환
+
+def add_discovered_service(service_name, port, url=None, health_path="/"):
+    """발견된 서비스를 SERVICES에 추가"""
+    # 동적으로 서비스 목록 업데이트
+```
+
+**새로운 API 엔드포인트**:
+- `GET /admin/services/discover` - 수동 서비스 발견
+- `POST /admin/services/add` - 서비스 수동 추가
+- `DELETE /admin/services/{name}` - 서비스 제거
+- `GET /admin/services/list` - 전체 서비스 목록
+- `GET /admin/services/status?auto_discover=true` - 자동 발견 포함 상태 체크
+
+### 2. Gitea API를 통한 Git 활동 조회
+
+**기존 방식 (파일시스템 접근)**:
+```python
+repos = [
+    "/host_home/github-migration/nginx-infra",
+    "/host_home/github-migration/frontend-base",
+    ...
+]
+# subprocess로 git 명령어 실행
+```
+
+**새로운 방식 (Gitea API)**:
+```python
+GITEA_URL = "http://172.17.0.1:3000"
+GITEA_TOKEN = "b18d3b01a802f001f3e2649cbd750008710a1d99"
+
+# Gitea REST API 사용
+- /api/v1/repos/{owner}/{repo} - 저장소 정보
+- /api/v1/repos/{owner}/{repo}/commits - 최근 커밋
+```
+
+### 3. UI 레이아웃 개선
+
+**변경 전**:
+```
+[Nginx 상태 (1칸)] [Gitea Runners (1칸)] [Git 활동 (1칸)]
+```
+
+**변경 후**:
+```
+[Nginx 상태 (1칸)] [Git 활동 (2칸 - 확장)]
+```
+
+- Gitea Runners 섹션 제거
+- Git 활동을 `grid-column: span 2`로 확장
+- 테이블 형식으로 간소화 (레포당 한 줄)
+
+## 구현 결과
+
+### 1. 서비스 상태 API 복구
+- 원래 구조로 복구하여 프론트엔드 호환성 유지
+- 자동 발견 기능은 별도 엔드포인트로 분리
+
+### 2. Git 활동 정상 표시
+- 5개 주요 저장소의 최근 활동 표시
+- 각 저장소별 최근 커밋 메시지와 시간 표시
+- API 에러 처리 추가
+
+### 3. 개선된 레이아웃
+- 더 많은 공간 활용으로 가독성 향상
+- 긴 저장소명과 커밋 메시지 잘림 문제 해결
+
+## 기술적 고려사항
+
+### 1. Gitea API 권한
+- 현재 토큰: `write:repository` 권한만 있음
+- 제약사항: `/api/v1/user`, `/api/v1/orgs` 접근 불가
+- 해결책: 알려진 저장소 목록 하드코딩
+
+### 2. 네트워크 설정
+- Backend 컨테이너 → Gitea: `http://172.17.0.1:3000`
+- Backend 컨테이너 → 호스트 서비스: `http://172.17.0.1:{port}`
+- Docker 네트워크: `appnet` (external)
+
+### 3. 자동 발견 성능
+- 포트 스캔 시 ThreadPoolExecutor 사용 (50 workers)
+- 타임아웃 설정: 1초 (포트 스캔), 5초 (health check)
+
+## 남은 이슈
+
+### rb8001_8001 서비스 timeout
+- 포트 8001에서 실행 중인 서비스가 응답하지 않음
+- 자동 발견으로 추가되었으나 health check 실패
+- 추가 조사 필요:
+  - Docker 컨테이너 상태 확인
+  - 네트워크 연결 확인
+  - 서비스 로그 확인
+
+## 교훈
+
+1. **API 변경 시 호환성 고려**
+   - 프론트엔드가 기대하는 응답 구조 확인 필수
+   - Breaking change는 신중하게 접근
+
+2. **외부 의존성 관리**
+   - 파일시스템 경로 의존성은 취약함
+   - API 기반 접근이 더 안정적
+
+3. **권한 관리**
+   - API 토큰 권한은 필요한 만큼만 부여
+   - 권한 부족 시 대안 방법 준비
+
+## 관련 커밋
+- `8ff8fe5` - 동적 서비스 감지 기능 추가
+- `98b2577` - Git 활동 조회를 Gitea API로 대체
+- `969cc72` - Gitea Runners 제거 및 Git 활동 확장
+- `ca2e566` - Git 활동 표시 간소화
\ No newline at end of file
diff --git a/docs/troubleshooting/20250716_gemini_cli_slack_network_issues.md b/docs/troubleshooting/20250716_gemini_cli_slack_network_issues.md
new file mode 100644
index 0000000..afaa775
--- /dev/null
+++ b/docs/troubleshooting/20250716_gemini_cli_slack_network_issues.md
@@ -0,0 +1,169 @@
+# Gemini CLI, Slack 연결, 네트워크 통합 문제 해결
+
+**날짜**: 2025-07-16  
+**작업자**: Claude & happybell
+
+## 개요
+
+rb8001과 rb10508_test 컨테이너에서 발생한 여러 문제들을 해결하는 과정
+
+## 1. Gemini CLI 실행 문제
+
+### 증상
+- rb8001: "Gemini CLI가 설치되지 않았습니다" 에러
+- rb10508_test (test-api-container): 정상 작동
+- 에러: `exec: "gemini": executable file not found in $PATH`
+
+### 원인 분석
+- Docker 컨테이너는 Python 기반으로 Node.js가 포함되지 않음
+- 서버에는 이미 설치되어 있지만 컨테이너 내부에서 접근 불가
+- test-api-container는 Node.js를 마운트하여 사용 중
+
+### 해결 방법
+
+#### 1. docker-compose.yml에 Node.js 마운트 추가
+```yaml
+volumes:
+  # 기존 볼륨들...
+  # Node.js 및 Gemini CLI 마운트
+  - /home/admin/.nvm/versions/node/v24.4.0:/usr/local/node:ro
+
+environment:
+  # 기존 환경변수들...
+  # Node.js PATH 추가
+  - PATH=/usr/local/node/bin:$PATH
+```
+
+#### 2. gemini_service.py에서 절대 경로 사용
+```python
+# 기존
+cmd = ["gemini", "-m", "gemini-2.5-flash", "-p", full_prompt]
+
+# 수정
+cmd = ["/usr/local/node/bin/gemini", "-m", "gemini-2.5-flash", "-p", full_prompt]
+```
+
+## 2. Slack 연결 문제
+
+### 증상
+- rb10508_test 컨테이너 시작은 성공하지만 Slack 대화 불가
+- 에러: `AttributeError: 'Settings' object has no attribute 'USE_ASYNC_RESPONSE'`
+
+### 원인
+- app/api/slack.py에서 settings.USE_ASYNC_RESPONSE 참조
+- app/core/config.py의 Settings 클래스에 해당 속성 미정의
+
+### 해결 방법
+
+config.py의 Settings 클래스에 추가:
+```python
+# Application Configuration
+DEBUG: bool = True
+LOG_LEVEL: str = "INFO"
+MAX_MEMORY_SIZE: int = 1000
+USE_ASYNC_RESPONSE: bool = True  # 추가
+```
+
+## 3. 네트워크 통합 문제
+
+### 배경
+- 로빙들이 frontend-backend와 상태를 주고받아야 함
+- Docker 네트워크 격리로 인해 통신 불가
+
+### 현황
+- frontend-backend-1: appnet 네트워크
+- rb8001: host 네트워크 (보안 취약)
+- rb10508_test: 자체 bridge 네트워크 (격리됨)
+
+### 해결 방법
+
+#### rb10508_test/docker-compose.yml
+```yaml
+services:
+  test-api:
+    # ...
+    networks:
+      - default
+      - appnet
+
+networks:
+  appnet:
+    external: true
+```
+
+#### rb8001/docker-compose.yml
+```yaml
+services:
+  rb8001:
+    # network_mode: host 제거
+    networks:
+      - appnet
+    ports:
+      - "8001:8001"
+
+networks:
+  appnet:
+    external: true
+```
+
+### 장점
+- 보안 향상 (host 네트워크 제거)
+- 선택적 컨테이너 간 통신
+- backend와 안전한 상태 공유 가능
+
+## 4. CI/CD 경로 문제
+
+### 증상
+- GitHub Actions 실패: `/home/admin/test_api: 그런 파일이나 디렉터리가 없습니다`
+
+### 원인
+- 디렉토리 구조 변경: test_api → rb10508_test
+- CI/CD 워크플로우가 구 경로 참조
+
+### 해결 방법
+
+.gitea/workflows/cicd.yml 수정:
+- `/home/admin/test_api` → `/home/admin/rb10508_test`
+- 코드 복사 경로를 rb8001과 동일하게 변경:
+  ```bash
+  cp -r /home/admin/.cache/act/*/hostexecutor/* /home/admin/rb10508_test/
+  ```
+
+## 적용 순서
+
+1. 로컬에서 코드 수정 및 푸시
+2. 서버에서 .env 파일 확인/생성
+3. 기존 컨테이너 정리:
+   ```bash
+   docker stop test-api-container
+   docker rm test-api-container
+   ```
+4. 새 컨테이너 시작:
+   ```bash
+   cd /home/admin/rb8001
+   docker-compose down && docker-compose up -d
+   
+   cd /home/admin/rb10508_test
+   docker-compose up -d
+   ```
+
+## 검증
+
+```bash
+# Gemini CLI 확인
+docker exec rb8001 /usr/local/node/bin/gemini --version
+docker exec rb10508_test /usr/local/node/bin/gemini --version
+
+# 네트워크 확인
+docker network inspect appnet
+
+# Slack 대화 테스트
+# Slack에서 @Ro-being, @Ro-being_test로 대화
+```
+
+## 교훈
+
+1. **컨테이너 환경 고려**: 서버에 설치된 도구가 컨테이너에서는 없을 수 있음
+2. **설정 동기화**: 새 기능 추가 시 모든 관련 파일 업데이트 필요
+3. **네트워크 설계**: 초기부터 컨테이너 간 통신 고려
+4. **경로 일관성**: CI/CD 설정 시 디렉토리 구조 변경 반영
\ No newline at end of file