355 lines
13 KiB
Python
355 lines
13 KiB
Python
#!/usr/bin/env python3
|
|
"""Generate Shinkan backup manifest, SHA256 sidecar, and incremental media.jsonl index.
|
|
|
|
Implements RECOVERY_CONTRACT.md section 3.1 and Backup-Orchestrator v0.4 Manifest Schema v1.
|
|
Read-only against database and media storage; writes sidecar files next to the dump.
|
|
"""
|
|
|
|
import argparse
|
|
import datetime as dt
|
|
import hashlib
|
|
import json
|
|
import os
|
|
from pathlib import Path
|
|
import platform
|
|
import re
|
|
import socket
|
|
import subprocess
|
|
import sys
|
|
from urllib.request import urlopen
|
|
|
|
EXIT_OK = 0
|
|
EXIT_EXEC_ERROR = 1
|
|
EXIT_PRECONDITION = 2
|
|
|
|
TARGETS = {
|
|
'pi-prod': {
|
|
'host': 'raspberrypi5',
|
|
'arch': 'aarch64',
|
|
'app_dir': '/home/lars/docker/shinkan',
|
|
'db_container': 'shinkan-db-prod',
|
|
'db_name': 'shinkan',
|
|
'db_user': 'shinkan_user',
|
|
'media_dir': '/shinkan-media/prod',
|
|
'version_url': 'http://127.0.0.1:8003/api/version',
|
|
},
|
|
'llm-prod': {
|
|
'host': 'llm-node',
|
|
'arch': 'x86_64',
|
|
'app_dir': '/home/llmadmin/docker/shinkan-prod',
|
|
'db_container': 'shinkan-db-prod',
|
|
'db_name': 'shinkan',
|
|
'db_user': 'shinkan_user',
|
|
'media_dir': '/srv/shinkan/prod/media',
|
|
'version_url': 'http://127.0.0.1:8003/api/version',
|
|
},
|
|
}
|
|
|
|
|
|
def now_iso():
|
|
return dt.datetime.now(dt.timezone.utc).astimezone().isoformat(timespec='seconds')
|
|
|
|
|
|
def compute_sha256(path):
|
|
h = hashlib.sha256()
|
|
with Path(path).open('rb') as fp:
|
|
while True:
|
|
chunk = fp.read(65536)
|
|
if not chunk:
|
|
break
|
|
h.update(chunk)
|
|
return h.hexdigest()
|
|
|
|
|
|
def detect_dump_format(path):
|
|
with Path(path).open('rb') as fp:
|
|
return 'custom' if fp.read(5) == b'PGDMP' else 'plain'
|
|
|
|
|
|
def atomic_write_text(path, content):
|
|
path = Path(path)
|
|
tmp = path.with_name(f'.{path.name}.{os.getpid()}.tmp')
|
|
try:
|
|
tmp.write_text(content, encoding='utf-8')
|
|
tmp.replace(path)
|
|
finally:
|
|
if tmp.exists():
|
|
tmp.unlink()
|
|
|
|
|
|
def query_version_info(tcfg):
|
|
app_version = 'unknown'
|
|
try:
|
|
with urlopen(tcfg['version_url'], timeout=5) as resp:
|
|
if resp.status == 200:
|
|
data = json.loads(resp.read(8192).decode('utf-8'))
|
|
app_version = data.get('app_version', 'unknown')
|
|
except Exception:
|
|
pass
|
|
git_commit = 'unknown'
|
|
app_dir = Path(tcfg['app_dir'])
|
|
if (app_dir / '.git').exists():
|
|
try:
|
|
proc = subprocess.run(
|
|
['git', '-C', str(app_dir), 'rev-parse', 'HEAD'],
|
|
capture_output=True, text=True, timeout=5,
|
|
)
|
|
if proc.returncode == 0 and proc.stdout.strip():
|
|
git_commit = proc.stdout.strip()
|
|
except Exception:
|
|
pass
|
|
return app_version, git_commit
|
|
|
|
|
|
def query_db_metadata(tcfg, dump_path):
|
|
"""Query migrations and informative table row counts from container or fallback to SQL dump."""
|
|
migrations = []
|
|
row_counts = {}
|
|
engine_version = ''
|
|
sql_script = """
|
|
SELECT 'MIG:' || migration FROM schema_migrations ORDER BY id;
|
|
SELECT 'VER:' || server_version FROM pg_settings WHERE name = 'server_version';
|
|
SELECT 'CNT:' || relname || ':' || n_live_tup::bigint
|
|
FROM pg_stat_user_tables
|
|
WHERE schemaname = 'public'
|
|
ORDER BY relname;
|
|
"""
|
|
try:
|
|
proc = subprocess.run(
|
|
[
|
|
'docker', 'exec', tcfg['db_container'],
|
|
'sh', '-ec',
|
|
'export PGPASSWORD="${POSTGRES_PASSWORD:-}"; '
|
|
'psql -U "${POSTGRES_USER:-shinkan_user}" -d "${POSTGRES_DB:-shinkan}" -At -c '
|
|
+ json.dumps(sql_script),
|
|
],
|
|
capture_output=True, text=True, timeout=15,
|
|
)
|
|
if proc.returncode == 0:
|
|
for line in proc.stdout.splitlines():
|
|
if line.startswith('MIG:'):
|
|
migrations.append(line[4:].strip())
|
|
elif line.startswith('VER:'):
|
|
engine_version = line[4:].strip()
|
|
elif line.startswith('CNT:'):
|
|
parts = line[4:].split(':', 1)
|
|
if len(parts) == 2 and parts[1].isdigit():
|
|
row_counts[parts[0]] = int(parts[1])
|
|
except Exception:
|
|
pass
|
|
|
|
# Fallback: parse migrations from plain SQL dump if container query was unavailable
|
|
if not migrations and detect_dump_format(dump_path) == 'plain':
|
|
in_copy = False
|
|
with Path(dump_path).open('r', encoding='utf-8', errors='replace') as fp:
|
|
for line in fp:
|
|
if not in_copy:
|
|
if line.startswith('COPY public.schema_migrations ') or line.startswith('COPY schema_migrations '):
|
|
in_copy = True
|
|
continue
|
|
else:
|
|
if line.startswith('\\.'):
|
|
break
|
|
parts = line.rstrip('\r\n').split('\t')
|
|
if len(parts) >= 2:
|
|
migrations.append(parts[1])
|
|
|
|
def sort_key(stem):
|
|
m = re.match(r'^(\d+)', stem)
|
|
return (int(m.group(1)) if m else 0, stem)
|
|
|
|
migrations = sorted(set(migrations), key=sort_key)
|
|
return migrations, row_counts, engine_version
|
|
|
|
|
|
def build_media_jsonl(media_dir, out_jsonl_path, cache_path):
|
|
"""Write <dump>.media.jsonl with incremental sha256 cache over (path, size, mtime_ns)."""
|
|
media_root = Path(media_dir)
|
|
cache = {}
|
|
if cache_path.is_file():
|
|
try:
|
|
cache = json.loads(cache_path.read_text(encoding='utf-8'))
|
|
except Exception:
|
|
cache = {}
|
|
|
|
new_cache = {}
|
|
lines = []
|
|
total_bytes = 0
|
|
if media_root.is_dir():
|
|
for item in sorted(media_root.rglob('*')):
|
|
if not item.is_file() or item.name.startswith('.'):
|
|
continue
|
|
rel = item.relative_to(media_root).as_posix()
|
|
if rel.startswith('#recycle/') or rel.startswith('.Trash'):
|
|
continue
|
|
st = item.stat()
|
|
size = st.st_size
|
|
mtime = int(st.st_mtime)
|
|
cache_key = f'{rel}|{size}|{mtime}'
|
|
sha = cache.get(cache_key)
|
|
if not sha:
|
|
sha = compute_sha256(item)
|
|
new_cache[cache_key] = sha
|
|
total_bytes += size
|
|
lines.append(json.dumps({
|
|
'path': rel, 'size': size, 'mtime': mtime, 'sha256': sha,
|
|
}, ensure_ascii=False))
|
|
|
|
atomic_write_text(out_jsonl_path, ('\n'.join(lines) + '\n') if lines else '')
|
|
try:
|
|
atomic_write_text(cache_path, json.dumps(new_cache, ensure_ascii=False))
|
|
except OSError:
|
|
pass
|
|
return len(lines), total_bytes, compute_sha256(out_jsonl_path)
|
|
|
|
|
|
def write_result(path, payload):
|
|
if path:
|
|
atomic_write_text(path, json.dumps(payload, ensure_ascii=False, indent=2) + '\n')
|
|
|
|
|
|
def main():
|
|
parser = argparse.ArgumentParser(description='Create Shinkan backup manifest and checksums')
|
|
parser.add_argument('--target', required=True, choices=sorted(TARGETS))
|
|
parser.add_argument('--dump', required=True, type=Path)
|
|
parser.add_argument('--out-dir', type=Path)
|
|
parser.add_argument('--result', type=Path)
|
|
args = parser.parse_args()
|
|
|
|
tcfg = dict(TARGETS[args.target])
|
|
if os.environ.get('SHINKAN_MEDIA_DIR_OVERRIDE'):
|
|
tcfg['media_dir'] = os.environ['SHINKAN_MEDIA_DIR_OVERRIDE']
|
|
if os.environ.get('SHINKAN_APP_DIR_OVERRIDE'):
|
|
tcfg['app_dir'] = os.environ['SHINKAN_APP_DIR_OVERRIDE']
|
|
|
|
cur_host = socket.gethostname()
|
|
cur_arch = platform.machine()
|
|
if os.environ.get('SHINKAN_SKIP_HOST_GUARD') != '1':
|
|
if cur_host != tcfg['host'] or cur_arch != tcfg['arch']:
|
|
msg = f"Host/arch mismatch: running on {cur_host}/{cur_arch}, expected {tcfg['host']}/{tcfg['arch']}"
|
|
write_result(args.result, {'status': 'error', 'exit_code': EXIT_PRECONDITION, 'detail': msg})
|
|
print(f'ERROR: {msg}', file=sys.stderr)
|
|
return EXIT_PRECONDITION
|
|
|
|
dump_path = args.dump.resolve()
|
|
if not dump_path.is_file() or dump_path.stat().st_size == 0:
|
|
msg = f'Dump file missing or empty: {dump_path}'
|
|
write_result(args.result, {'status': 'error', 'exit_code': EXIT_PRECONDITION, 'detail': msg})
|
|
print(f'ERROR: {msg}', file=sys.stderr)
|
|
return EXIT_PRECONDITION
|
|
|
|
out_dir = (args.out_dir or dump_path.parent).resolve()
|
|
out_dir.mkdir(parents=True, exist_ok=True)
|
|
|
|
try:
|
|
dump_sha256 = compute_sha256(dump_path)
|
|
dump_bytes = dump_path.stat().st_size
|
|
dump_format = detect_dump_format(dump_path)
|
|
|
|
sha_file = out_dir / (dump_path.name + '.sha256')
|
|
atomic_write_text(sha_file, f'{dump_sha256} {dump_path.name}\n')
|
|
|
|
media_file = out_dir / (dump_path.name + '.media.jsonl')
|
|
cache_file = out_dir / '.shinkan-media-sha256-cache.json'
|
|
media_count, media_bytes, media_sha256 = build_media_jsonl(tcfg['media_dir'], media_file, cache_file)
|
|
|
|
app_version, git_commit = query_version_info(tcfg)
|
|
migrations, row_counts, engine_version = query_db_metadata(tcfg, dump_path)
|
|
last_migration = migrations[-1] if migrations else None
|
|
created_at = now_iso()
|
|
point_id = f"shinkan-{args.target}-{dt.datetime.now().strftime('%Y%m%dT%H%M%S')}-{dump_sha256[:8]}"
|
|
|
|
manifest = {
|
|
'schemaVersion': 1,
|
|
'created_at': created_at,
|
|
'host': cur_host,
|
|
'target': args.target,
|
|
'app_version': app_version,
|
|
'git_commit': git_commit,
|
|
'migrations': migrations,
|
|
'last_migration': last_migration,
|
|
'dump_format': dump_format,
|
|
'dump_bytes': dump_bytes,
|
|
'dump_sha256': dump_sha256,
|
|
'row_counts': row_counts,
|
|
'media_manifest': {
|
|
'file': media_file.name,
|
|
'sha256': media_sha256,
|
|
'file_count': media_count,
|
|
'total_bytes': media_bytes,
|
|
},
|
|
'application': {
|
|
'id': 'shinkan',
|
|
'environment': 'production',
|
|
'target': args.target,
|
|
'sourceHost': cur_host,
|
|
'sourceArch': cur_arch,
|
|
},
|
|
'recoveryPoint': {
|
|
'id': point_id,
|
|
'createdAt': created_at,
|
|
'status': 'consistent' if (migrations and app_version != 'unknown') else 'verified',
|
|
'validatedAt': None,
|
|
'consistency': {
|
|
'mode': 'hot_indexed',
|
|
'dbTransactional': True,
|
|
'mediaSynchronized': False,
|
|
'limitations': [
|
|
'PostgreSQL dump created in a single transaction; media index scanned immediately afterwards without write freeze.'
|
|
],
|
|
},
|
|
},
|
|
'release': {
|
|
'repository': 'http://192.168.2.144:3000/Lars/shinkan-jinkendo.git',
|
|
'appVersion': app_version,
|
|
'gitCommit': git_commit,
|
|
},
|
|
'database': {
|
|
'engine': 'postgresql',
|
|
'engineVersion': engine_version,
|
|
'dumpFormat': dump_format,
|
|
'artifact': dump_path.name,
|
|
'bytes': dump_bytes,
|
|
'sha256': dump_sha256,
|
|
'schemaVersion': last_migration or '',
|
|
'lastMigration': last_migration,
|
|
'migrations': migrations,
|
|
'rowCounts': row_counts,
|
|
},
|
|
'media': {
|
|
'storageType': 'nfs4_shared',
|
|
'containerMount': '/app/media',
|
|
'manifestArtifact': media_file.name,
|
|
'manifestSha256': media_sha256,
|
|
'fileCount': media_count,
|
|
'totalBytes': media_bytes,
|
|
},
|
|
}
|
|
|
|
manifest_file = out_dir / (dump_path.name + '.manifest.json')
|
|
atomic_write_text(manifest_file, json.dumps(manifest, ensure_ascii=False, indent=2) + '\n')
|
|
|
|
res = {
|
|
'status': 'ok',
|
|
'exit_code': EXIT_OK,
|
|
'recovery_point_id': point_id,
|
|
'dump_path': str(dump_path),
|
|
'sha256_path': str(sha_file),
|
|
'manifest_path': str(manifest_file),
|
|
'media_manifest_path': str(media_file),
|
|
'dump_sha256': dump_sha256,
|
|
'last_migration': last_migration,
|
|
'media_file_count': media_count,
|
|
}
|
|
write_result(args.result, res)
|
|
print(f'OK: Manifest created for {dump_path.name} (point={point_id}, migrations={len(migrations)}, media_files={media_count})')
|
|
return EXIT_OK
|
|
except Exception as exc:
|
|
write_result(args.result, {'status': 'error', 'exit_code': EXIT_EXEC_ERROR, 'detail': str(exc)})
|
|
print(f'ERROR: {exc}', file=sys.stderr)
|
|
return EXIT_EXEC_ERROR
|
|
|
|
|
|
if __name__ == '__main__':
|
|
sys.exit(main())
|