Files
backup-orchestrator/scripts/shinkan/shinkan-backup-manifest
T

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())