move_detect/server/tools/backup.php

<?php
/**
 * 백업 — DB 덤프 + 스냅샷 아카이브.
 *
 *   php tools/backup.php --out=/path/to/backups
 *   php tools/backup.php --out=/path --no-snapshots      (DB만; 이미지가 클 때)
 *
 * 왜 필요한가
 *     납품 후 고객이 스스로 하기 가장 어려운 일이 백업이다. 카페24 관리자 화면의 DB 백업은
 *     `move_` 표만 골라내지 못하고, 스냅샷 파일은 아예 대상이 아니다. 사고 기록과 그 증거
 *     이미지가 함께 남지 않으면 백업의 의미가 절반이다 — 조사에서 필요한 것은 둘 다이다.
 *
 * 왜 mysqldump 를 쓰지 않는가
 *     공유호스팅에는 shell_exec 도 mysqldump 도 없는 경우가 흔하다. PDO 로 읽어 SQL 텍스트를
 *     직접 쓰면 어디서든 돈다. 대신 대용량에서는 느리므로, 이벤트 표는 청크로 읽는다.
 *
 * 복구
 *     phpMyAdmin 에서 덤프 SQL 을 실행하고, 스냅샷 tar 를 storage/snapshots/ 에 풀면 된다.
 *     자세한 절차는 출력 파일 옆의 RESTORE.txt 에 함께 기록된다.
 */
declare(strict_types=1);

require __DIR__ . '/bootstrap.php';

[$cfg, $pdo] = tool_boot();
$args = tool_args($argv);

$outDir = rtrim((string)($args['out'] ?? ''), '/\\');
if ($outDir === '') {
    fwrite(STDERR, "사용법: php tools/backup.php --out=<디렉터리> [--no-snapshots]\n");
    exit(2);
}
if (!is_dir($outDir) && !@mkdir($outDir, 0700, true)) {
    fwrite(STDERR, "출력 디렉터리를 만들 수 없습니다: $outDir\n");
    exit(2);
}
// 백업 파일에는 전 현장의 사고 기록과 작업자 이미지(개인정보)가 들어 있다. 웹에서 읽히는
// 위치에 두면 그 자체가 사고다 — 파일명은 `move_detect-YYYYmmdd-HHMMSS.sql` 로 하루 범위만
// 알면 추측 가능하다.
//
// 감사 지적(A3): 예전 검사는 `str_contains($real, '/www/')` 였다. 하위 경로
// (/home/acct/www/backups)는 막았지만 **docroot 자체**(/home/acct/www)는 슬래시가 뒤에
// 없어 그대로 통과했다. 가장 흔한 오사용이 정확히 그 케이스다.
// 이제 경로를 세그먼트로 쪼개 웹 루트 이름이 하나라도 있으면 거부한다.
const WEB_DIR_NAMES = ['www', 'public_html', 'htdocs', 'html', 'web', 'public'];
$real = realpath($outDir);
if ($real !== false) {
    $segments = array_filter(explode('/', str_replace('\\', '/', $real)), 'strlen');
    foreach ($segments as $seg) {
        if (in_array(strtolower($seg), WEB_DIR_NAMES, true)) {
            fwrite(STDERR,
                "거부: 백업 대상 경로에 웹 공개 디렉터리('{$seg}')가 포함되어 있습니다.\n"
                . "  경로: {$real}\n"
                . "  이 파일은 전 현장의 사고 기록과 작업자 이미지를 담습니다. www/ 밖(FTP 최상위\n"
                . "  또는 그 상위)의 비공개 디렉터리를 지정하세요.\n");
            exit(2);
        }
    }
}

$stamp = date('Ymd-His');
$sqlPath = $outDir . '/move_detect-' . $stamp . '.sql';
$fh = fopen($sqlPath, 'wb');
if ($fh === false) { fwrite(STDERR, "덤프 파일을 열 수 없습니다.\n"); exit(2); }

// 이 순서는 복구 시 참조 무결성 순서다 (events 가 snapshots/alert_log 보다 먼저).
$TABLES = [
    'move_users', 'move_devices', 'move_cameras', 'move_zones', 'move_thresholds',
    'move_events', 'move_event_snapshots', 'move_actions', 'move_audit_log',
    'move_suppressions', 'move_alert_channels', 'move_alert_log',
    'move_shift_handovers', 'move_risk_controls', 'move_device_metrics',
];
// nonce / rate_limits 는 재생성되는 휘발성 데이터라 일부러 제외한다.

function q(PDO $pdo, $v): string
{
    if ($v === null) return 'NULL';
    if (is_int($v) || is_float($v)) return (string)$v;
    return $pdo->quote((string)$v);
}

fwrite($fh, "-- move_detect backup {$stamp}\n");
fwrite($fh, "-- 복구: phpMyAdmin 에서 이 파일을 실행한 뒤 스냅샷 아카이브를 storage/snapshots/ 에 풉니다.\n");
fwrite($fh, "SET NAMES utf8mb4;\nSET FOREIGN_KEY_CHECKS=0;\n\n");

$counts = [];
foreach ($TABLES as $table) {
    try {
        $probe = $pdo->query("SELECT * FROM {$table} LIMIT 1");
    } catch (Throwable $e) {
        // 마이그레이션 전 DB 에는 없는 표가 있다. 백업이 그걸로 실패하면 안 된다.
        $counts[$table] = 'skipped';
        continue;
    }
    $cols = [];
    for ($i = 0; $i < $probe->columnCount(); $i++) {
        $cols[] = $probe->getColumnMeta($i)['name'];
    }
    $colList = '`' . implode('`, `', $cols) . '`';

    $n = 0;
    $offset = 0;
    fwrite($fh, "\n-- {$table}\n");
    while (true) {
        // 청크 단위: 이벤트가 수십만 건인 현장에서 한 번에 fetchAll 하면 메모리가 터진다.
        $st = $pdo->prepare("SELECT * FROM {$table} LIMIT 500 OFFSET {$offset}");
        $st->execute();
        $rows = $st->fetchAll(PDO::FETCH_ASSOC);
        if ($rows === []) break;
        foreach ($rows as $row) {
            $vals = [];
            foreach ($cols as $c) $vals[] = q($pdo, $row[$c] ?? null);
            fwrite($fh, "INSERT INTO {$table} ({$colList}) VALUES (" . implode(', ', $vals) . ");\n");
            $n++;
        }
        $offset += 500;
    }
    $counts[$table] = $n;
}
fwrite($fh, "\nSET FOREIGN_KEY_CHECKS=1;\n");
fclose($fh);
@chmod($sqlPath, 0600);

// ---- 스냅샷 ---------------------------------------------------------------------------
$snapNote = 'skipped (--no-snapshots)';
if (!isset($args['no-snapshots'])) {
    $dir = rtrim($cfg->snapshotDir(), '/\\');
    if (!is_dir($dir)) {
        $snapNote = 'snapshot dir 없음';
    } elseif (!class_exists('ZipArchive')) {
        // ext-zip 이 없으면 아카이브를 만들 수 없다. 조용히 넘어가면 이미지 없는 백업을
        // 완전한 백업으로 착각하게 된다.
        $snapNote = 'ZipArchive 없음 — storage/snapshots/ 를 FTP 로 별도 내려받으세요';
    } else {
        $zipPath = $outDir . '/move_detect-snapshots-' . $stamp . '.zip';
        $zip = new ZipArchive();
        if ($zip->open($zipPath, ZipArchive::CREATE | ZipArchive::OVERWRITE) === true) {
            $files = glob($dir . '/*.jpg') ?: [];
            foreach ($files as $f) $zip->addFile($f, basename($f));
            $zip->close();
            @chmod($zipPath, 0600);
            $snapNote = count($files) . '개 -> ' . basename($zipPath);
        } else {
            $snapNote = '아카이브를 만들지 못했습니다';
        }
    }
}

// ---- 복구 안내 -------------------------------------------------------------------------
$restore = $outDir . '/RESTORE.txt';
file_put_contents($restore, implode("\n", [
    'move_detect 복구 절차',
    '',
    '1. 새 DB 를 만들고 schema.sql 을 먼저 실행합니다 (표 구조).',
    '2. migrations/ 의 SQL 을 날짜 순서대로 실행합니다.',
    '3. 이 폴더의 move_detect-<시각>.sql 을 실행합니다 (데이터).',
    '4. move_detect-snapshots-<시각>.zip 을 풀어 storage/snapshots/ 에 넣습니다.',
    '5. config.php 의 DB 접속 정보를 새 DB 로 맞춥니다.',
    '',
    '주의:',
    '- 이 백업에는 사고 기록과 작업자 이미지(개인정보)가 들어 있습니다.',
    '  웹에서 접근 가능한 경로에 두지 마십시오.',
    '- move_nonces / move_rate_limits 는 휘발성이라 백업에 포함되지 않습니다 (자동 재생성).',
    '- 복구 후 tools/verify_audit_chain.php 로 감사로그 무결성을 확인하십시오.',
    '',
    '생성: ' . date('c'),
]) . "\n");

fwrite(STDOUT, "DB 덤프: {$sqlPath}\n");
foreach ($counts as $t => $n) fwrite(STDOUT, sprintf("  %-24s %s\n", $t, $n));
fwrite(STDOUT, "스냅샷: {$snapNote}\n");
fwrite(STDOUT, "복구 안내: {$restore}\n");
exit(0);