# STM32 펌웨어 및 Cafe24 서버 설치 설명서 v2606

이 문서는 서버실 온습도(SHT30) 모니터링 시스템 v2606을 실제 운영 환경에 배포할 때 STM32F407VGT6 펌웨어와 Cafe24 PHP/MySQL 서버에 각각 무엇을 설치하고 설정해야 하는지 정리한 설치용 문서입니다.

> **참고:** 이 문서는 **STM32 펌웨어 중심**의 설치 문서입니다. Raspberry Pi 4 모듈(누수+카메라 / SHT30) 배포자는 [docs/DEPLOYMENT_PLAN_RPI4x3.md](./DEPLOYMENT_PLAN_RPI4x3.md)와 [SYSTEM_OVERVIEW.md](../SYSTEM_OVERVIEW.md)를 먼저 참고하세요. 서버 설치 절차(§3~§6)는 공통입니다.

## 1. 설치 대상

| 구분 | 설치 위치 | 역할 |
|---|---|---|
| Cafe24 서버 | `public_html/raspi_leck_detecter/` | 센서 API 수신, DB 저장, 임계 판정, SMS 발송, 대시보드/보고서 제공 |
| Cafe24 MySQL | Cafe24 DB | 센서 로그, 온습도 측정값, SMS 로그, 장비 상태 저장 |
| STM32F407VGT6 (`sht30_fw`) | 펌웨어 플래시 | SHT30 I2C 측정, 5분 주기 보고, raw-body 서명 |
| 서버 cron | Cafe24 cron 또는 외부 스케줄러 | `cron_heartbeat.php` 주기 실행(장비 오프라인 감지) |

## 2. 설치 전 준비물

- STM32F407VGT6 보드 (STM32F4-DISCOVERY 계열 또는 동등 커스텀 PCB)
- SHT30 온습도 모듈 (한진데이터 P4422-3, I2C)
- LAN8720 Ethernet PHY 모듈 (RMII) + LAN 케이블
- I2C 풀업 저항 4.7kΩ × 2 (모듈 내장 풀업 시 생략)
- 외부 3.3V USB-UART 어댑터 (USART3 PD8/PD9 콘솔 로그용)
- Cafe24 PHP 호스팅
- Cafe24 MySQL DB
- Cafe24 SMS 서비스 계정 및 secure key
- 운영 담당자 SMS 수신 번호
- HTTPS 접속 가능한 도메인 또는 호스팅 경로 + Cafe24 루트 CA

배선은 [wiring_diagram.md](./wiring_diagram.md)를 먼저 적용합니다. SHT30 I2C(PB6 SCL / PB7 SDA, 주소 0x44, 3.3V/GND, 4.7kΩ 풀업)와 LAN8720 RMII 결선은 [firmware/docs/HARDWARE.md](../firmware/docs/HARDWARE.md)를 따릅니다.

## 3. 서버에 설치할 파일

Cafe24 웹 루트 아래에 **repo 의 `php/` 트리 전체를 그대로 업로드**합니다. 개별 파일을 선별해 올리면 누수 사진 파이프라인(`api/photo_upload.php`, `photo.php`, `var/photos/`)이 빠지기 쉽습니다.

```text
public_html/raspi_leck_detecter/     ← php/ 트리 전체 업로드
  .htaccess
  blocked.php
  config.php
  config.local.php                   ← 서버에서 example 복사 후 작성(저장소에 없음)
  config.local.example.php
  ops_checks.php
  sms_send.php
  cron_heartbeat.php
  dashboard.php
  photo.php                          ← 누수 사진 조회(관리자 인증 필요)
  setup_mfa.php
  admin_security.php
  setup_wizard.php
  security_evidence.php
  monthly_report.php
  login.php
  retention_cleanup.php
  setup_hash.php
  test_mobile.php
  api/
    sensor_data.php
    photo_upload.php                 ← 누수 사진 업로드 API
  var/
    .gitkeep
    .htaccess                        ← var/ 웹 직접 접근 차단(403)
    index.html
    photos/                          ← 누수 사진 저장 폴더(.htaccess/index.html 포함,
      .htaccess                         없으면 첫 업로드 시 자동 생성 시도)
      index.html
```

운영 서버에는 `config.local.php`가 반드시 필요합니다. `config.local.example.php`를 복사해서 만들고 실제 운영 값으로 교체합니다.

```php
<?php
return [
    'DB_HOST' => 'localhost',
    'DB_PORT' => 3306,
    'DB_NAME' => 'your_db_name',
    'DB_USER' => 'your_db_user',
    'DB_PASS' => 'your_db_password',

    'API_KEY' => 'replace-with-long-random-secret',

    'SMS_USER_ID' => 'your-cafe24-sms-user-id',
    'SMS_SECURE' => 'your-cafe24-sms-secure-key',
    'SMS_SENDER' => '01000000000',
    'SMS_RECIPIENTS' => [
        '01000000000',
    ],

    'ADMIN_USER' => 'admin',
    'ADMIN_PASSWORD_HASH' => '$2y$10$replace.with.password_hash.output',
    'ADMIN_TOTP_SECRET' => 'replace-with-base32-secret',
    'MFA_SETUP_TOKEN' => 'replace-with-temporary-random-token',

    // 온습도 임계 override (기본값은 config.php 의 METRIC_*)
    'METRIC_TEMP_HIGH_C' => 30,
    'METRIC_TEMP_LOW_C' => 10,
    'METRIC_RH_HIGH' => 70,
    'METRIC_RH_LOW' => 20,

    'SMS_LOG_RETENTION_DAYS' => 365,
    'SENSOR_LOG_RETENTION_DAYS' => 365,
    'SENSOR_METRIC_RETENTION_DAYS' => 365,
    'ADMIN_AUDIT_RETENTION_DAYS' => 365,
];
```

`API_KEY`는 STM32 펌웨어 `firmware/common/secrets.h`의 `APP_API_KEY`와 반드시 바이트 단위로 같아야 합니다(raw-body 서명 `X-Signature = lowercase_hex(HMAC-SHA256(키=API_KEY, 메시지=요청본문 바이트))`).

`ADMIN_TOTP_SECRET`은 Google Authenticator, Microsoft Authenticator, Authy 등 TOTP 인증 앱에 등록한 Base32 비밀키입니다. 이 값이 없으면 관리자 로그인을 허용하지 않습니다. 담당자 변경 시 관리자 비밀번호와 TOTP 비밀키를 모두 교체하고 변경 기록을 운영 인수인계 자료에 남깁니다.

최초 등록은 `MFA_SETUP_TOKEN`을 임시로 설정한 뒤 다음 주소에서 진행합니다.

```text
https://your-domain.example/raspi_leck_detecter/setup_mfa.php?token=임시토큰
```

`setup_mfa.php`에서 생성된 수동 입력 키를 Google Authenticator에 등록하고 6자리 코드를 검증한 뒤, 화면에 표시되는 `ADMIN_TOTP_SECRET` 줄을 `config.local.php`에 반영합니다. 등록 완료 후 `MFA_SETUP_TOKEN`은 빈 값으로 바꾸거나 삭제합니다.

## 4. 서버 DB 설치

신규 설치라면 Cafe24 phpMyAdmin 또는 MySQL 콘솔에서 다음 파일을 실행합니다.

```sql
SOURCE /path/to/sql/schema_sht30.sql;
```

phpMyAdmin에서는 [schema_sht30.sql](../sql/schema_sht30.sql) 내용을 복사해서 SQL 실행 창에 붙여넣습니다. 생성 테이블은 총 7개 — `leak_sensor_log`, `leak_sensor_status`, `leak_sensor_metric`, `leak_sms_log`, `leak_ingest_nonce`(재전송 방어), `leak_incident`, `leak_photo`(누수 사고/사진) — 이며, 신규 설치는 이 파일 하나로 완결됩니다(누수 컬럼/테이블 포함). 모든 테이블은 `leak_` 접두사를 사용해 같은 DB 의 다른 테이블과 격리됩니다.

## 5. 서버 권한 및 관리자 설정

상태 파일 폴더는 PHP가 쓸 수 있어야 합니다.

```text
php/var/
```

관리자 비밀번호 해시는 서버 CLI에서 생성합니다.

```bash
php setup_hash.php "새관리자비밀번호"
```

출력된 해시를 `config.local.php`의 `ADMIN_PASSWORD_HASH`에 넣습니다. 관리자 인증 앱 비밀키도 `config.local.php`의 `ADMIN_TOTP_SECRET`에 설정합니다.

서버 설정 후 브라우저에서 아래 화면을 확인합니다.

```text
https://your-domain.example/raspi_leck_detecter/setup_wizard.php
```

점검 화면에서 확인할 항목은 다음과 같습니다.

- DB 연결
- 필수 테이블 존재 여부(`leak_sensor_log`, `leak_sensor_status`, `leak_sensor_metric`, `leak_sms_log`)
- API 키 기본값 교체 여부
- 관리자 해시 설정 여부
- 관리자 TOTP 설정 여부
- SMS 수신자 설정 여부
- 상태 파일 폴더 쓰기 권한
- 테스트 SMS 발송

## 6. 서버 cron 설정

장비 오프라인 감지를 위해 `cron_heartbeat.php`를 주기 실행합니다. Cafe24 cron 또는 외부 스케줄러에서 다음 URL을 1분 간격으로 호출합니다.

```text
https://your-domain.example/raspi_leck_detecter/cron_heartbeat.php?key=<CRON_SECRET>
```

HTTP 호출에는 `?key=<CRON_SECRET>` 파라미터가 **필수**입니다(누락 시 403). `CRON_SECRET`은 `API_KEY`에서 파생되며 다음으로 계산합니다: `php -r "echo hash_hmac('sha256','cron','<API_KEY>');"`

서버 CLI cron을 사용할 수 있다면 다음처럼 구성할 수 있습니다(CLI 실행에는 key가 필요 없습니다).

```cron
* * * * * php /home/hosting_user/public_html/raspi_leck_detecter/cron_heartbeat.php
```

호스팅 환경마다 실제 절대 경로가 다르므로 Cafe24 파일 관리자 또는 `phpinfo()`로 경로를 확인합니다. 마지막 수신 후 `HEARTBEAT_TIMEOUT_SEC`(기본 1200초=20분)을 초과하면 오프라인으로 판정합니다.

## 7. STM32 펌웨어 빌드 (폐쇄망)

폐쇄망 빌드 머신에서 펌웨어를 빌드합니다. 의존성 벤더링과 오프라인 빌드/플래시 절차는 [firmware/docs/BUILD_OFFLINE.md](../firmware/docs/BUILD_OFFLINE.md)를 따릅니다.

```bash
cp firmware/common/secrets.h.example firmware/common/secrets.h
# secrets.h 의 APP_API_KEY 를 서버 config.local.php 의 API_KEY 와 바이트 단위로 동일하게 채운다.
```

빌드 전 확인할 설정값:

| 위치 | 설정 |
|---|---|
| `firmware/common/secrets.h` | `APP_API_KEY` = 서버 `API_KEY` |
| `firmware/common/app_config.h` | `APP_API_HOST`, `APP_API_PATH`(`/raspi_leck_detecter/api/sensor_data.php`), 네트워크(DHCP/static) |
| `firmware/common/app_config.h` | `APP_SHT30_REPORT_INTERVAL_SEC`(기본 300초), `APP_SHT30_I2C_ADDR`(0x44) |
| `firmware/certs/server_ca.c` | 자리표시자 CA → 실제 Cafe24 루트 CA |

`sht30_fw` 타깃을 빌드해 `sht30_fw.bin`을 생성하고 보드에 플래시합니다.

## 8. STM32 펌웨어 동작 확인

USART3(PD8 TX / PD9 RX, 115200 8N1)에 외부 3.3V USB-UART 어댑터를 연결해 콘솔 로그를 확인합니다.

첫 부팅 후 확인할 항목:

- I2C1 초기화 및 SHT30 주소 0x44 응답
- 첫 측정값(온도/습도)
- 네트워크(DHCP/static) → SNTP 시간 동기 → TLS 핸드셰이크
- 서버 200 응답 및 `startup` 보고

상태 LED(PD12) 패턴: 부팅=점등 / 정상 보고=느린 토글 / 망 단절·TLS 실패=빠른 점멸.

## 9. 설치 후 최종 확인

서버에서 확인합니다.

```text
https://your-domain.example/raspi_leck_detecter/setup_wizard.php
https://your-domain.example/raspi_leck_detecter/dashboard.php
https://your-domain.example/raspi_leck_detecter/monthly_report.php
https://your-domain.example/raspi_leck_detecter/security_evidence.php
```

정상 설치 기준은 다음과 같습니다.

- `setup_wizard.php`의 필수 점검 항목이 통과
- `dashboard.php`에 최신 온도/습도와 센서 상태(`sensor_id=2`)가 표시
- `security_evidence.php`에서 운영 점검 결과와 보안통제 매트릭스 조회 가능
- STM32 콘솔 로그에 서버 200 응답 기록 확인
- `leak_sensor_metric`에 주기 측정값(periodic) 저장
- 임계 초과 테스트 시 `metric_status` 경보 기록 및 SMS 수신
- 월간 보고서에서 임계 경보/복귀/오프라인 내역 조회 가능

## 10. 문제 해결

| 증상 | 확인 지점 |
|---|---|
| API 403 | 서버 `API_KEY`와 펌웨어 `APP_API_KEY` 일치 여부, raw-body 서명 |
| API 500 | Cafe24 PHP 오류 로그, DB 접속 정보, 테이블 생성 여부 |
| 로그인 불가 | `ADMIN_PASSWORD_HASH`, `ADMIN_TOTP_SECRET`, 인증 앱 시간 동기화 |
| SMS 미발송 | Cafe24 SMS 계정, secure key, 발신번호 등록, 잔액, `leak_sms_log` |
| 온습도 미표시 | I2C 배선(PB6/PB7, 0x44), 4.7kΩ 풀업, `leak_sensor_metric` 테이블, 펌웨어 측정 로그 |
| 임계 경보 미발송 | `config.php`/`config.local.php`의 `METRIC_*`, `METRIC_ALERT_COOLDOWN_SEC`(1800초) |
| TLS 실패 | `firmware/certs/server_ca.c` 실제 CA 반영, SNTP 시간 동기(인증서 유효기간 검증) |
| 오프라인 알림 과다/지연 | `HEARTBEAT_CHECK_INTERVAL_SEC`, `HEARTBEAT_TIMEOUT_SEC`(기본 1200초), cron 주기 |

## 11. 운영자가 보관해야 할 값

다음 값은 코드 저장소에 넣지 말고 운영자만 별도로 보관합니다.

- Cafe24 DB 이름, 계정, 비밀번호
- `API_KEY` / 펌웨어 `APP_API_KEY`
- Cafe24 SMS user id
- Cafe24 SMS secure key
- SMS 발신번호
- SMS 수신자 번호
- 관리자 계정과 원문 비밀번호, `ADMIN_TOTP_SECRET`
- 서버 업로드 경로
- 장비 ID(`stm32-sht30-01`)와 설치 위치