linkkf 로직수정중
This commit is contained in:
333
structure.md
Normal file
333
structure.md
Normal file
@@ -0,0 +1,333 @@
|
||||
# FlaskFarm 프로젝트 구조 및 흐름 분석
|
||||
|
||||
이 프로젝트는 **Flask 기반의 플러그인 확장 가능한 웹 프레임워크**입니다.
|
||||
|
||||
---
|
||||
|
||||
## 1. 전체 아키텍처
|
||||
|
||||
```
|
||||
main.py (진입점)
|
||||
↓
|
||||
framework.initialize()
|
||||
↓
|
||||
├─ Framework 초기화 (Singleton)
|
||||
├─ Flask App 생성
|
||||
├─ 시스템 모듈 로딩
|
||||
└─ 플러그인 동적 로딩
|
||||
↓
|
||||
Flask Server 시작
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 핵심 컴포넌트
|
||||
|
||||
### A. Framework (lib/framework/)
|
||||
|
||||
**싱글톤 패턴**으로 구현된 핵심 프레임워크:
|
||||
|
||||
- **init_main.py**: Framework 클래스 - 모든 컴포넌트의 중앙 관리자
|
||||
|
||||
- Flask, Celery, SQLAlchemy, SocketIO, Scheduler, Redis 초기화
|
||||
- 로깅 시스템 설정
|
||||
- config.yaml 기반 설정 관리
|
||||
|
||||
- **init_plugin.py**: PluginManager - 플러그인 동적 로딩
|
||||
|
||||
- `data/plugins/` 폴더에서 플러그인 자동 발견
|
||||
- `path_dev` 설정으로 개발 플러그인 경로 지원
|
||||
- 플러그인 화이트리스트/블랙리스트 필터링
|
||||
|
||||
- **scheduler.py**: APScheduler 래퍼
|
||||
- Interval/Cron 기반 스케줄링
|
||||
- Job 인스턴스 생명주기 관리
|
||||
- gevent/threading 모드 지원
|
||||
|
||||
---
|
||||
|
||||
### B. Plugin 시스템 (lib/plugin/)
|
||||
|
||||
**플러그인 구조** (3계층):
|
||||
|
||||
```
|
||||
Plugin
|
||||
└─ Module (기능 그룹)
|
||||
└─ Page (세부 페이지)
|
||||
```
|
||||
|
||||
**주요 파일**:
|
||||
|
||||
- **create_plugin.py**: PluginBase 클래스
|
||||
|
||||
- `info.yaml`에서 메타데이터 로드
|
||||
- Blueprint 등록 (URL prefix: `/플러그인명/`)
|
||||
- DB 바인딩 (SQLite per plugin)
|
||||
- ModelSetting으로 설정 관리
|
||||
|
||||
- **logic_module_base.py**: PluginModuleBase
|
||||
- 모듈별 라우팅 (menu, ajax, command, api)
|
||||
- 스케줄러 통합
|
||||
- 페이지 리스트 관리
|
||||
|
||||
---
|
||||
|
||||
### C. System 모듈 (lib/system/)
|
||||
|
||||
내장 시스템 기능:
|
||||
|
||||
- **mod_setting**: 일반 설정, 웹, 인증, 알림 등
|
||||
- **mod_plugin**: 플러그인 관리 UI
|
||||
- **mod_log**: 전체 로그 뷰어
|
||||
- **mod_tool**: Command, 업로드, Python REPL 등
|
||||
|
||||
---
|
||||
|
||||
## 3. 실행 흐름
|
||||
|
||||
### 시작 단계
|
||||
|
||||
1. **main.py** 실행
|
||||
|
||||
- gevent monkey patching
|
||||
- Celery 환경변수 설정
|
||||
- `framework.initialize()` 호출
|
||||
|
||||
2. **Framework 초기화**
|
||||
|
||||
```python
|
||||
F = Framework.get_instance() # Singleton
|
||||
F.__initialize()
|
||||
```
|
||||
|
||||
- config.yaml 로드
|
||||
- 로깅 시스템 구성
|
||||
- Flask app 생성
|
||||
- DB 초기화 (system + 각 플러그인)
|
||||
- Scheduler, SocketIO, Celery 설정
|
||||
|
||||
3. **시스템 모듈 로딩**
|
||||
|
||||
```python
|
||||
F.initialize_system()
|
||||
```
|
||||
|
||||
- system 패키지에서 기본 모듈 로드
|
||||
- 라우트 등록
|
||||
|
||||
4. **플러그인 로딩**
|
||||
|
||||
```python
|
||||
F.initialize_plugin()
|
||||
```
|
||||
|
||||
- PluginManager가 플러그인 목록 수집
|
||||
- 각 플러그인 info.yaml 파싱
|
||||
- setup.py에서 Plugin 인스턴스 생성
|
||||
- 모듈/페이지 초기화
|
||||
- DB 마이그레이션
|
||||
- 자동시작 설정된 스케줄러 등록
|
||||
|
||||
5. **서버 시작**
|
||||
```python
|
||||
frame.start()
|
||||
```
|
||||
- SocketIO 서버 실행 (gevent 또는 threading 모드)
|
||||
|
||||
---
|
||||
|
||||
## 4. 플러그인 개발 패턴
|
||||
|
||||
플러그인 구조 예시 (ffmpeg):
|
||||
|
||||
```
|
||||
ffmpeg/
|
||||
├── info.yaml # 메타데이터
|
||||
├── __init__.py # 플러그인 엔트리포인트
|
||||
├── setup.py # P = create_plugin_instance(setting)
|
||||
├── mod_download.py # Module 구현
|
||||
└── templates/ # Jinja2 템플릿
|
||||
```
|
||||
|
||||
**라우팅 자동 생성**:
|
||||
|
||||
- `/ffmpeg/download/list` → `mod_download.process_menu('list')`
|
||||
- `/ffmpeg/download/ajax/<sub>` → `mod_download.process_ajax(sub)`
|
||||
|
||||
---
|
||||
|
||||
## 5. 데이터 흐름
|
||||
|
||||
### 설정 관리
|
||||
|
||||
```
|
||||
config.yaml (글로벌)
|
||||
↓
|
||||
Framework.config (딕셔너리)
|
||||
↓
|
||||
각 플러그인의 ModelSetting (DB 저장)
|
||||
```
|
||||
|
||||
### 데이터 저장
|
||||
|
||||
```
|
||||
path_data/
|
||||
├── db/
|
||||
│ ├── system.db # 시스템 설정
|
||||
│ ├── ffmpeg.db # 플러그인별 DB
|
||||
│ └── ...
|
||||
├── log/ # 로테이션 로그
|
||||
├── plugins/ # 설치된 플러그인
|
||||
└── tmp/ # 임시 파일
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 비동기 작업 (Celery)
|
||||
|
||||
- Redis를 브로커로 사용
|
||||
- 각 모듈에서 `@celery.task` 데코레이터로 정의
|
||||
- `plugin_load_celery()` 훅으로 초기화
|
||||
- 백그라운드 작업 처리 (다운로드, 인코딩 등)
|
||||
|
||||
---
|
||||
|
||||
## 7. 스케줄링
|
||||
|
||||
```python
|
||||
Job 인스턴스 생성
|
||||
↓
|
||||
Scheduler.add_job_instance()
|
||||
↓
|
||||
APScheduler에 등록 (Interval/Cron)
|
||||
↓
|
||||
자동 실행 (랜덤 딜레이 포함)
|
||||
```
|
||||
|
||||
- 모듈별 `auto_start` 설정
|
||||
- DB 자동 삭제 기능 (`db_auto_delete`)
|
||||
- 실시간 상태 모니터링
|
||||
|
||||
---
|
||||
|
||||
## 8. 주요 기능
|
||||
|
||||
✅ **플러그인 시스템**: 동적 로드/언로드
|
||||
✅ **멀티 DB**: SQLite per plugin
|
||||
✅ **실시간 통신**: SocketIO
|
||||
✅ **스케줄링**: Interval/Cron 작업
|
||||
✅ **인증**: Flask-Login
|
||||
✅ **알림**: 텔레그램, 디스코드 지원
|
||||
✅ **로그 뷰어**: 웹 기반 실시간 로그
|
||||
✅ **파일 관리**: 업로드, 다운로드, 편집 (flaskcode)
|
||||
|
||||
---
|
||||
|
||||
## 9. 설정 우선순위
|
||||
|
||||
1. 환경변수 (REDIS_PORT 등)
|
||||
2. config.yaml
|
||||
3. DB의 SystemModelSetting
|
||||
4. 플러그인별 ModelSetting
|
||||
|
||||
---
|
||||
|
||||
## 10. 디렉토리 구조
|
||||
|
||||
```
|
||||
flaskfarm/
|
||||
├── main.py # 애플리케이션 진입점
|
||||
├── config.yaml # 글로벌 설정
|
||||
├── lib/ # 핵심 라이브러리
|
||||
│ ├── framework/ # 프레임워크 코어
|
||||
│ │ ├── init_main.py # Framework 클래스 (Singleton)
|
||||
│ │ ├── init_plugin.py # PluginManager
|
||||
│ │ ├── init_route.py # 글로벌 라우팅
|
||||
│ │ ├── scheduler.py # 스케줄러
|
||||
│ │ └── ...
|
||||
│ ├── plugin/ # 플러그인 베이스
|
||||
│ │ ├── create_plugin.py # PluginBase 클래스
|
||||
│ │ ├── logic_module_base.py
|
||||
│ │ ├── route.py # 플러그인 라우팅
|
||||
│ │ └── ...
|
||||
│ ├── system/ # 시스템 모듈
|
||||
│ │ ├── mod_setting.py # 설정 관리
|
||||
│ │ ├── mod_plugin.py # 플러그인 관리
|
||||
│ │ ├── mod_log.py # 로그 뷰어
|
||||
│ │ └── ...
|
||||
│ ├── support/ # 공통 유틸리티
|
||||
│ ├── tool/ # 도구 모음
|
||||
│ └── tool_base/ # 기본 도구
|
||||
├── data/ # 데이터 디렉토리
|
||||
│ ├── db/ # SQLite 데이터베이스
|
||||
│ ├── log/ # 로그 파일
|
||||
│ ├── plugins/ # 설치된 플러그인
|
||||
│ └── tmp/ # 임시 파일
|
||||
└── files/ # 템플릿 파일
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. 플러그인 생명주기
|
||||
|
||||
```
|
||||
1. 발견 (Discovery)
|
||||
- PluginManager.get_plugin_name_list()
|
||||
- data/plugins/ 또는 path_dev 스캔
|
||||
|
||||
2. 로딩 (Loading)
|
||||
- info.yaml 파싱
|
||||
- setup.py의 create_plugin_instance() 호출
|
||||
- Blueprint 등록
|
||||
- DB 바인딩
|
||||
|
||||
3. 초기화 (Initialization)
|
||||
- plugin_load() 호출
|
||||
- DB 마이그레이션
|
||||
- 스케줄러 등록
|
||||
- Celery 작업 등록
|
||||
|
||||
4. 실행 (Runtime)
|
||||
- HTTP 요청 처리
|
||||
- 스케줄 작업 실행
|
||||
- SocketIO 이벤트 처리
|
||||
|
||||
5. 언로딩 (Unloading)
|
||||
- plugin_unload() 호출
|
||||
- 스케줄러 작업 제거
|
||||
- 리소스 정리
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. 주요 API 엔드포인트
|
||||
|
||||
### 글로벌 엔드포인트
|
||||
|
||||
- `/` → 홈 (시스템 대시보드로 리다이렉트)
|
||||
- `/system/setting` → 시스템 설정
|
||||
- `/system/plugin` → 플러그인 관리
|
||||
- `/system/log` → 전체 로그
|
||||
- `/global/ajax/<sub>` → 공통 AJAX 처리
|
||||
|
||||
### 플러그인 엔드포인트 (예: ffmpeg)
|
||||
|
||||
- `/ffmpeg/` → 플러그인 홈
|
||||
- `/ffmpeg/<module>/<page>` → 모듈/페이지
|
||||
- `/ffmpeg/<module>/ajax/<sub>` → AJAX 요청
|
||||
- `/ffmpeg/<module>/command` → 커맨드 실행
|
||||
- `/ffmpeg/<module>/api/<sub>` → API 호출
|
||||
|
||||
---
|
||||
|
||||
## 결론
|
||||
|
||||
FlaskFarm은 **플러그인을 통한 기능 확장에 최적화**되어 있으며, 각 플러그인이 독립적인 DB, 스케줄러, 라우팅을 가지면서도 중앙 프레임워크의 공통 기능(로깅, 인증, 알림 등)을 활용할 수 있는 **모듈식 웹 애플리케이션 플랫폼**입니다.
|
||||
|
||||
주요 설계 원칙:
|
||||
|
||||
- **플러그인 독립성**: 각 플러그인은 자체 DB와 설정을 가짐
|
||||
- **확장성**: 새로운 플러그인을 쉽게 추가 가능
|
||||
- **중앙 관리**: Framework 싱글톤을 통한 통합 관리
|
||||
- **비동기 처리**: Celery를 통한 백그라운드 작업
|
||||
- **실시간 통신**: SocketIO를 통한 양방향 통신
|
||||
Reference in New Issue
Block a user