ivada-infra/DOCS
3
0
Fork 0
Code Issues 1 Pull Requests 5 Actions Packages Projects Releases Wiki Activity

docs: Add troubleshooting guide for Gemini CLI, Slack, and network issues

Browse Source 
- 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>
This commit is contained in:
happybell80 2025-07-16 16:12:13 +09:00
parent 7e1e9f621a
commit ccaf367916
3 changed files with 463 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

149
docs/troubleshooting/20250716_SSD_용량_부족_및_Docker_정리.md Normal file
View File

@ -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로 이동

145
docs/troubleshooting/20250716_frontend_admin_dashboard_improvements.md Normal file
View File

@ -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 활동 표시 간소화

169
docs/troubleshooting/20250716_gemini_cli_slack_network_issues.md Normal file
View File

@ -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 설정 시 디렉토리 구조 변경 반영