# Session 관리 가이드

## 개요

본 애플리케이션은 **Redis**를 기본 세션 저장소로 사용하며, Redis 장애 시 **Database(MariaDB)**로 자동 폴백하는 이중화 구조를 가지고 있습니다.

## 아키텍처

### 세션 저장소

| 우선순위 | 핸들러 | 설명 | 성능 |
|---------|-------|------|------|
| 1순위 | **RedisHandler** | 메모리 기반 고속 세션 | ~0.03초 |
| 2순위 | **DatabaseHandler** | DB 기반 안정적 세션 | ~0.05초 (수동 전환 시) |

### 구성 요소

```
┌─────────────────────────────────────────┐
│  사용자 로그인 요청                       │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Session.php 생성자                      │
│  - Redis 연결 테스트                     │
│  - SESSION_FORCE_DATABASE 확인          │
└──────────────┬──────────────────────────┘
               │
        ┌──────┴──────┐
        │             │
    Redis 정상?   Redis 장애?
        │             │
        ▼             ▼
  RedisHandler   DatabaseHandler
   (ci_sessions     (ci_sessions
    테이블)          테이블)
        │             │
        └──────┬──────┘
               ▼
        세션 데이터 저장/조회
```

## 설정 파일

### 1. Session.php (`src/app/Config/Session.php`)

```php
public string $driver = RedisHandler::class;

public function __construct()
{
    // 환경변수로 강제 Database 모드 설정 가능
    $forceDatabase = env('SESSION_FORCE_DATABASE', false);

    if ($this->driver === RedisHandler::class && !$forceDatabase) {
        try {
            // Redis 연결 테스트 (타임아웃: 0.5초)
            $testRedis = get_redis_connection('session');
            
            if (!$testRedis) {
                throw new \Exception('Redis connection failed');
            }
            
            // Redis 정상 - Redis 사용
            $this->savePath = 'tcp://192.168.10.243:6379?database=0';
            
        } catch (\Exception $e) {
            // Redis 실패 - DatabaseHandler로 폴백
            $this->driver = DatabaseHandler::class;
            $this->savePath = 'ci_sessions';
        }
    } else {
        // Database 모드
        $this->savePath = 'ci_sessions';
    }
}
```

### 2. 환경 설정 (`.env`)

```bash
# Redis 세션 설정
SESSION_REDIS_HOST = 192.168.10.243
SESSION_REDIS_PORT = 6379
SESSION_REDIS_DATABASE = 0
#SESSION_REDIS_PASSWORD =

# 세션 강제 Database 모드 (Redis 장애 시 true로 변경)
SESSION_FORCE_DATABASE = false
```

### 3. Redis Helper (`src/app/Helpers/redis_helper.php`)

```php
function get_redis_connection(string $type = 'worker')
{
    $redis = new \Redis();
    
    // 타임아웃 0.5초로 빠른 실패 감지
    $timeout = 0.5;
    $success = $redis->connect($host, $port, $timeout);
    
    return $success ? $redis : false;
}
```

## 데이터베이스 테이블

### ci_sessions 테이블 구조

```sql
CREATE TABLE `ci_sessions` (
  `session_id` VARCHAR(40) NOT NULL DEFAULT '0',
  `ip_address` VARCHAR(16) NOT NULL DEFAULT '0',
  `user_agent` VARCHAR(120) NOT NULL,
  `last_activity` INT UNSIGNED NOT NULL DEFAULT 0,
  `user_data` VARCHAR(4000) NOT NULL,
  PRIMARY KEY (`session_id`)
) ENGINE = MEMORY;

CREATE INDEX `last_activity_idx` 
ON `ci_sessions` (`last_activity` ASC);
```

**주요 특징:**
- **ENGINE = MEMORY**: 메모리 기반 테이블로 매우 빠른 읽기/쓰기 성능
- **장점**: Redis와 비슷한 속도 (디스크 I/O 없음)
- **단점**: 서버 재시작 시 세션 데이터 소실 (일반적으로 문제없음 - 세션은 휘발성 데이터)
- **용량**: VARCHAR(4000)으로 충분한 세션 데이터 저장 가능

## 운영 가이드

### 1. Redis 장애 발생 시

#### 자동 폴백 (기본 동작)
- Redis 연결 실패 시 자동으로 DatabaseHandler로 전환
- **단점**: 매 요청마다 Redis 연결 시도 → 타임아웃 대기 (약 0.5초 추가)
- 사용자는 약간 느린 응답 시간을 경험

#### 수동 전환 (권장)
Redis 장애 감지 즉시 다음 조치:

```bash
# 1. .env 파일 수정
vi /path/to/src/.env

# SESSION_FORCE_DATABASE를 true로 변경
SESSION_FORCE_DATABASE = true

# 2. PHP-FPM 재시작 (선택사항, 다음 요청부터 자동 적용)
docker exec projects-admin_confirms kill -USR2 1
```

**장점**: Redis 연결 시도 없이 즉시 Database 사용 → 빠른 응답 (0.05초)

### 2. Redis 복구 후

```bash
# 1. .env 파일 원복
SESSION_FORCE_DATABASE = false

# 2. PHP-FPM 재시작
docker exec projects-admin_confirms kill -USR2 1
```

### 3. 모니터링

#### 로그 확인
```bash
# 세션 관련 로그 확인
docker exec projects-admin_confirms tail -f /var/www/html/writable/logs/log-$(date +%Y-%m-%d).log | grep -i session

# Redis 폴백 경고 확인
docker exec projects-admin_confirms grep "Redis unavailable" /var/www/html/writable/logs/log-$(date +%Y-%m-%d).log
```

#### 예상 로그 메시지

**Redis 정상:**
```
DEBUG - Session: Class initialized using 'CodeIgniter\Session\Handlers\RedisHandler' driver.
```

**Redis 장애 (자동 폴백):**
```
WARNING - Session: Redis unavailable (Redis connection failed), falling back to DatabaseHandler
DEBUG - Session: Class initialized using 'CodeIgniter\Session\Handlers\DatabaseHandler' driver.
```

**Database 강제 모드:**
```
INFO - Session: Forced to use DatabaseHandler (SESSION_FORCE_DATABASE=true)
DEBUG - Session: Class initialized using 'CodeIgniter\Session\Handlers\DatabaseHandler' driver.
```

### 4. 성능 모니터링

```bash
# 로그인 응답 시간 측정
for i in {1..5}; do
  curl -X POST http://localtest2-admin.confirms.co.kr/login/chkLogin \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "user_id=test&user_pw=test" \
    -o /dev/null -s -w "  Time: %{time_total}s\n"
done
```

**기대 성능:**
- Redis 정상: 0.03 ~ 0.05초
- Database (수동 전환): 0.05 ~ 0.08초
- 자동 폴백 (Redis 다운): 0.5 ~ 1.0초

## 사용자 알림

### 프론트엔드 경고 표시

Redis 장애 시 로그인 페이지에 자동으로 경고 배너가 표시됩니다:

```javascript
// login.php의 JavaScript
function checkSystemStatus(responseData) {
    if (responseData.system && responseData.system.redis_fallback) {
        // 경고 메시지: "세션 서버(Redis) 장애로 임시 모드로 운영 중입니다."
        showRedisWarning(responseData.system.warning_message);
    }
}
```

**API 응답 예시:**
```json
{
  "code": "0",
  "msg": "success",
  "system": {
    "redis_fallback": true,
    "warning_message": "세션 서버(Redis) 장애로 임시 모드로 운영 중입니다. 시스템 관리자에게 문의하세요."
  }
}
```

## 트러블슈팅

### 문제: 로그인이 느림 (2~3초)

**원인**: Redis 다운 상태에서 자동 폴백 모드 사용 중

**해결**:
```bash
# SESSION_FORCE_DATABASE=true로 수동 전환
echo "SESSION_FORCE_DATABASE = true" >> /path/to/src/.env
```

### 문제: 세션이 유지되지 않음

**원인**: ci_sessions 테이블이 없거나 권한 문제

**해결**:
```sql
-- 테이블 존재 확인
SHOW TABLES LIKE 'ci_sessions';

-- 권한 확인
SHOW GRANTS FOR 'confirms'@'%';

-- 테이블이 없는 경우 생성
CREATE TABLE `ci_sessions` (
  `session_id` VARCHAR(40) NOT NULL DEFAULT '0',
  `ip_address` VARCHAR(16) NOT NULL DEFAULT '0',
  `user_agent` VARCHAR(120) NOT NULL,
  `last_activity` INT UNSIGNED NOT NULL DEFAULT 0,
  `user_data` VARCHAR(4000) NOT NULL,
  PRIMARY KEY (`session_id`)
) ENGINE = MEMORY;

CREATE INDEX `last_activity_idx` 
ON `ci_sessions` (`last_activity` ASC);
```

### 문제: 서버 재시작 후 모든 세션이 사라짐

**원인**: ci_sessions가 MEMORY 엔진을 사용 (정상 동작)

**설명**: 
- MEMORY 엔진은 서버 재시작 시 데이터가 삭제됩니다
- 세션은 일시적 데이터이므로 일반적으로 문제가 되지 않습니다
- 사용자는 재로그인하면 됩니다

**영구 저장이 필요한 경우**:
```sql
-- InnoDB로 변경 (성능은 약간 느려짐)
ALTER TABLE ci_sessions ENGINE=InnoDB;
```

### 문제: Redis 연결 타임아웃이 너무 김

**원인**: redis_helper.php의 타임아웃 설정

**해결**:
```php
// src/app/Helpers/redis_helper.php
$timeout = 0.5;  // 0.1 ~ 1.0 사이 값으로 조정
$redis->connect($host, $port, $timeout);
```

## 관련 파일

| 파일 | 역할 |
|------|------|
| `src/app/Config/Session.php` | 세션 설정 및 폴백 로직 |
| `src/app/Helpers/redis_helper.php` | Redis 연결 헬퍼 함수 |
| `src/app/Controllers/Login.php` | 로그인 및 시스템 상태 체크 |
| `src/app/Views/pages/login.php` | 프론트엔드 경고 표시 |
| `src/.env` | 환경 설정 (Redis 연결 정보, 강제 모드) |

## Worker 및 API (참고)

### Worker (NaverWorker.php)
- Redis 큐 사용 (DB 9)
- Redis 장애 시 파일 기반 폴백 (`worker/fallback_queue/*.json`)

### API (api_receiver.php, KisoController.php)
- Redis 큐 사용 (DB 9)
- Redis 장애 시 파일 기반 폴백 (`worker/fallback_queue/*.json`)

## 추가 개선 사항

### 고려 중인 기능

1. **Redis Sentinel 도입** (고가용성)
   - 자동 장애 조치
   - 마스터/슬레이브 구조

2. **APM 연동**
   - New Relic, DataDog 등
   - 실시간 성능 모니터링

3. **헬스체크 엔드포인트**
   ```php
   // GET /health/session
   {
     "status": "ok",
     "driver": "RedisHandler",
     "redis_available": true,
     "response_time_ms": 12
   }
   ```

## 문의

세션 관련 문제 발생 시:
1. 로그 확인 (`/writable/logs/`)
2. Redis 서버 상태 확인
3. ci_sessions 테이블 상태 확인
4. 필요 시 수동 전환 수행

---

**Last Updated**: 2026-03-25  
**Version**: 1.0.0