happybell80
725ad0876c
- 모든 .md, .html 파일 권한을 644로 정상화 - .gitignore 파일 권한도 644로 수정 - 문서 파일에 실행 권한은 불필요하고 보안상 바람직하지 않음 - deprecated 아이디어 폴더 생성 및 레벨별 UI 변경 아이디어 이동
240 lines
6.2 KiB
Markdown
240 lines
6.2 KiB
Markdown
# 로빙 MVP 설정 가이드
|
|
|
|
## 📋 목차
|
|
1. [환경 설정](#환경-설정)
|
|
2. [Slack 앱 설정](#slack-앱-설정)
|
|
3. [OpenAI API 설정](#openai-api-설정)
|
|
4. [데이터베이스 설정](#데이터베이스-설정)
|
|
5. [서버 실행](#서버-실행)
|
|
6. [테스트](#테스트)
|
|
|
|
## 🔧 환경 설정
|
|
|
|
### 1. 시스템 요구사항
|
|
- Python 3.12+
|
|
- PostgreSQL 13+
|
|
- Git
|
|
|
|
### 2. 프로젝트 클론 및 설정
|
|
```bash
|
|
# 저장소 클론
|
|
git clone https://github.com/happybell80/ivada.git
|
|
cd ivada
|
|
|
|
# 가상환경 생성
|
|
python3 -m venv venv
|
|
source venv/bin/activate # Linux/Mac
|
|
# venv\Scripts\activate # Windows
|
|
|
|
# 의존성 설치
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### 3. 환경변수 설정
|
|
`.env` 파일을 생성하고 다음 내용을 입력:
|
|
|
|
```env
|
|
# Slack Configuration
|
|
SLACK_BOT_TOKEN=xoxb-your-bot-token
|
|
SLACK_SIGNING_SECRET=your-signing-secret
|
|
SLACK_APP_TOKEN=xapp-your-app-token
|
|
|
|
# OpenAI Configuration
|
|
OPENAI_API_KEY=your-openai-api-key
|
|
|
|
# Database Configuration
|
|
DATABASE_URL=postgresql://user:password@localhost/ivada_db
|
|
TEST_DATABASE_URL=postgresql://user:password@localhost/ivada_test_db
|
|
|
|
# JWT Configuration
|
|
JWT_SECRET_KEY=your-jwt-secret-key-change-in-production
|
|
JWT_ALGORITHM=HS256
|
|
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30
|
|
|
|
# Application Configuration
|
|
DEBUG=True
|
|
LOG_LEVEL=INFO
|
|
MAX_MEMORY_SIZE=1000
|
|
```
|
|
|
|
## 📱 Slack 앱 설정
|
|
|
|
### 1. Slack 앱 생성
|
|
1. https://api.slack.com/apps 접속
|
|
2. **"Create New App"** 클릭
|
|
3. **"From scratch"** 선택
|
|
4. App Name: **"Roving"** 입력
|
|
5. 워크스페이스 선택 후 **"Create App"** 클릭
|
|
|
|
### 2. Bot Token 권한 설정
|
|
**OAuth & Permissions** 페이지에서 다음 Bot Token Scopes 추가:
|
|
|
|
#### 필수 권한
|
|
- `app_mentions:read` - 앱 멘션 읽기
|
|
- `channels:read` - 채널 정보 읽기
|
|
- `chat:write` - 메시지 전송
|
|
- `chat:write.public` - 공개 채널에 메시지 전송
|
|
- `im:read` - DM 읽기
|
|
- `im:write` - DM 전송
|
|
- `users:read` - 사용자 정보 읽기
|
|
|
|
#### 선택 권한
|
|
- `mpim:read` - 그룹 DM 읽기
|
|
- `mpim:write` - 그룹 DM 전송
|
|
- `files:read` - 파일 읽기
|
|
- `files:write` - 파일 업로드
|
|
|
|
### 3. 앱 설치 및 토큰 획득
|
|
1. **"Install to Workspace"** 클릭
|
|
2. 권한 승인
|
|
3. **Bot User OAuth Token** 복사 (xoxb-로 시작)
|
|
4. **"Basic Information"** 페이지에서 **Signing Secret** 복사
|
|
|
|
### 4. 연동 방식 선택
|
|
|
|
#### 방법 A: HTTP 연동 (ngrok 사용)
|
|
|
|
1. **ngrok 설치**
|
|
```bash
|
|
# Linux/Mac
|
|
wget https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-linux-amd64.tgz
|
|
tar xzf ngrok-v3-stable-linux-amd64.tgz
|
|
|
|
# ngrok 계정 생성: https://dashboard.ngrok.com/signup
|
|
# authtoken 설정
|
|
./ngrok config add-authtoken YOUR_AUTHTOKEN
|
|
```
|
|
|
|
2. **Event Subscriptions 설정**
|
|
- Slack 앱 → **"Event Subscriptions"** → **"Enable Events"** ON
|
|
- **Request URL**: `https://your-ngrok-url.ngrok.io/api/slack/events`
|
|
- **Subscribe to bot events**:
|
|
- `app_mention`
|
|
- `message.channels`
|
|
- `message.groups`
|
|
- `message.im`
|
|
- `message.mpim`
|
|
|
|
#### 방법 B: Socket Mode 연동
|
|
|
|
1. **Socket Mode 활성화**
|
|
- Slack 앱 → **"Socket Mode"** → **"Enable Socket Mode"** ON
|
|
|
|
2. **App-Level Token 생성**
|
|
- Token Name: **"Roving Socket Token"**
|
|
- Scopes: `connections:write`
|
|
- **App Token** 복사 (xapp-로 시작)
|
|
|
|
## 🤖 OpenAI API 설정
|
|
|
|
### 1. API 키 발급
|
|
1. https://platform.openai.com/api-keys 접속
|
|
2. **"Create new secret key"** 클릭
|
|
3. API 키 복사하여 `.env`의 `OPENAI_API_KEY`에 설정
|
|
|
|
### 2. 사용량 모니터링
|
|
- https://platform.openai.com/usage 에서 사용량 확인
|
|
- 필요시 사용량 제한 설정
|
|
|
|
## 🗄️ 데이터베이스 설정
|
|
|
|
### 1. PostgreSQL 설치 및 설정
|
|
```bash
|
|
# Ubuntu/Debian
|
|
sudo apt update
|
|
sudo apt install postgresql postgresql-contrib
|
|
|
|
# macOS (Homebrew)
|
|
brew install postgresql
|
|
brew services start postgresql
|
|
|
|
# 데이터베이스 생성
|
|
sudo -u postgres createdb ivada_db
|
|
sudo -u postgres createdb ivada_test_db
|
|
```
|
|
|
|
### 2. 데이터베이스 사용자 생성
|
|
```sql
|
|
-- PostgreSQL 콘솔에서 실행
|
|
sudo -u postgres psql
|
|
|
|
CREATE USER ivada_user WITH ENCRYPTED PASSWORD 'your_password';
|
|
GRANT ALL PRIVILEGES ON DATABASE ivada_db TO ivada_user;
|
|
GRANT ALL PRIVILEGES ON DATABASE ivada_test_db TO ivada_user;
|
|
```
|
|
|
|
### 3. 환경변수 업데이트
|
|
```env
|
|
DATABASE_URL=postgresql://ivada_user:your_password@localhost/ivada_db
|
|
TEST_DATABASE_URL=postgresql://ivada_user:your_password@localhost/ivada_test_db
|
|
```
|
|
|
|
## 🚀 서버 실행
|
|
|
|
### 1. HTTP 서버 실행 (ngrok 사용)
|
|
```bash
|
|
# 터미널 1: FastAPI 서버
|
|
source venv/bin/activate
|
|
python run.py
|
|
|
|
# 터미널 2: ngrok 터널
|
|
./ngrok http 8000
|
|
```
|
|
|
|
### 2. Socket Mode 실행
|
|
```bash
|
|
source venv/bin/activate
|
|
python socket_run.py
|
|
```
|
|
|
|
### 3. 실행 확인
|
|
- HTTP: http://localhost:8000
|
|
- API 문서: http://localhost:8000/docs
|
|
- ngrok 모니터링: http://localhost:4040
|
|
|
|
## 🧪 테스트
|
|
|
|
### 1. API 테스트
|
|
```bash
|
|
# 서버 상태 확인
|
|
curl http://localhost:8000/health
|
|
|
|
# 메시지 처리 테스트
|
|
curl -X POST "http://localhost:8000/api/test/message" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"text": "안녕하세요", "user_id": "test_user"}'
|
|
```
|
|
|
|
### 2. Slack 테스트
|
|
1. **봇 초대**: `/invite @Roving`
|
|
2. **직접 메시지**: `안녕하세요 로빙!`
|
|
3. **멘션 테스트**: `@Roving 오늘 할 일을 정리해주세요`
|
|
|
|
### 3. 예상 응답
|
|
```
|
|
안녕하세요! 테스트 모드에서 실행 중입니다. 메시지를 받았습니다: '[메시지]'
|
|
```
|
|
|
|
## 🐛 문제 해결
|
|
|
|
### Slack 연동 문제
|
|
- **봇이 응답하지 않음**: Event Subscriptions 설정 확인
|
|
- **권한 오류**: Bot Token Scopes 재확인
|
|
- **URL 검증 실패**: ngrok URL 및 서버 실행 상태 확인
|
|
|
|
### 서버 실행 문제
|
|
- **포트 충돌**: `lsof -i :8000`으로 포트 사용 확인
|
|
- **의존성 오류**: `pip install -r requirements.txt` 재실행
|
|
- **환경변수 오류**: `.env` 파일 경로 및 내용 확인
|
|
|
|
### 데이터베이스 연결 문제
|
|
- **연결 실패**: PostgreSQL 서비스 실행 상태 확인
|
|
- **권한 오류**: 사용자 권한 재설정
|
|
- **인코딩 문제**: UTF-8 인코딩 설정 확인
|
|
|
|
## 📞 지원
|
|
|
|
추가 도움이 필요하시면:
|
|
- [GitHub Issues](https://github.com/happybell80/ivada/issues)
|
|
- [개발 일지](development-log.md) 참조
|
|
- [Slack API 문서](https://api.slack.com/web) 참조 |