feat(backup): 系统设置里的存储与备份——定时时间与储存天数可配、下发到目标主机 cron

需求:整库逻辑备份做定时,但要在「系统设置 → 存储与备份」里设置定时时间与储存天数。

后端
- migration 000045 backup_schedule(单行:enabled/schedule_time/retention_days/retention_months/
  last_applied_*),store + 领域校验(HH:MM、1~365 天、0~24 月,非法值 400 且不落库不下发)
- internal/backuphost:通过 ssh 在目标主机上读回/下发计划并立即备份(未接线时 Available=false,
  页面降级提示;主机侧错误带输出回传)。最近一次只认有 MANIFEST.json 的完整目录,跳 *.incomplete
- 接口 GET/PUT /api/v1/backup-schedule、GET …/host、POST …/apply、POST …/run;
  写操作经 classifyRole 限管理员;run 为异步 202 + 在途单飞(http 写超时 30s,备份约 35s)
- openapi.yaml 补齐 5 条路由(契约测试要求每条都写 400/500)

主机侧
- scripts/install_backup_schedule.sh(幂等):写 /etc/knowledge-governance/backup-schedule.env 与
  /etc/cron.d/kb-logical-backup,参数校验,--show/--disable,最后一行 SCHEDULE_APPLIED 供平台核对
- logical-backup.sh 从该文件读保留策略;失败或被中断把目录改名 *.incomplete,不留'像成功'的半成品
- install --show 只回显计划行(原先把 SHELL=/PATH= 当计划显示)

前端
- web/src/backupSchedule.ts(严格解析:缺计划字段即报错,不把默认值伪装成设置)
- BackupScheduleSection:容器 + 纯视图(管理员表单/只读、已一致/待下发、在途轮询)

运行前提(已落实):运行镜像加 openssh-client,且容器 uid 1000 在 /etc/passwd 有名字
(否则 ssh 报 No user exists for uid 1000);凭据只读挂载 secrets/backup-host(git 忽略)

实测:主机 cron 每天 03:30 / 保留 7 天 / 每月 3 份;立即备份一次 34 秒 / 742.7 MiB / 失败 0;
Go 与前端测试全绿(170 vitest)。
This commit is contained in:
姚章浩
2026-10-09 13:50:23 +08:00
parent 4455d02262
commit 3f603aa293
25 changed files with 2353 additions and 11 deletions
+163
View File
@@ -0,0 +1,163 @@
import { newOperationID } from './operationKey'
// 「系统设置 → 存储与备份」:整库逻辑备份的定时计划(时间 + 储存天数)与主机回执。
export interface BackupSchedule {
enabled: boolean
schedule_time: string
retention_days: number
retention_months: number
updated_by: string
updated_at: string
last_applied_at: string
last_applied_summary: string
host_configured: boolean
host_target: string
host_reachable: boolean
host_error: string
host_schedule_enabled: boolean
host_schedule_time: string
host_keep_days: number
host_keep_months: number
host_cron_lines: string[]
host_cron_service: string
host_script_present: boolean
last_run_stamp: string
last_run_created_at: string
last_run_duration_seconds: number
last_run_total_bytes: number
last_run_databases: string[]
last_run_failed_databases: string[]
last_run_error: string
in_sync: boolean
applied: boolean
apply_error: string
running: boolean
running_started_at: string
run_last_error: string
}
export interface BackupRunStart {
started: boolean
running: boolean
}
const record = (value: unknown): value is Record<string, unknown> =>
Boolean(value) && typeof value === 'object' && !Array.isArray(value)
const asString = (value: unknown): string => (typeof value === 'string' ? value : '')
const asNumber = (value: unknown): number => (typeof value === 'number' && Number.isFinite(value) ? value : 0)
const asStringList = (value: unknown): string[] =>
Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : []
// 严格解析:计划三要素(时间/天数/月数)必须是正确类型,缺一个就整块报错,
// 而不是让界面显示成"默认 03:30 / 7 天"这种假状态。
function scheduleProjection(item: Record<string, unknown>): BackupSchedule {
if (typeof item.schedule_time !== 'string' || typeof item.retention_days !== 'number' || typeof item.retention_months !== 'number') {
throw new Error('存储与备份响应缺少计划字段(schedule_time / retention_days / retention_months)')
}
return {
enabled: item.enabled === true,
schedule_time: item.schedule_time,
retention_days: item.retention_days,
retention_months: item.retention_months,
updated_by: asString(item.updated_by),
updated_at: asString(item.updated_at),
last_applied_at: asString(item.last_applied_at),
last_applied_summary: asString(item.last_applied_summary),
host_configured: item.host_configured === true,
host_target: asString(item.host_target),
host_reachable: item.host_reachable === true,
host_error: asString(item.host_error),
host_schedule_enabled: item.host_schedule_enabled === true,
host_schedule_time: asString(item.host_schedule_time),
host_keep_days: asNumber(item.host_keep_days),
host_keep_months: asNumber(item.host_keep_months),
host_cron_lines: asStringList(item.host_cron_lines),
host_cron_service: asString(item.host_cron_service),
host_script_present: item.host_script_present === true,
last_run_stamp: asString(item.last_run_stamp),
last_run_created_at: asString(item.last_run_created_at),
last_run_duration_seconds: asNumber(item.last_run_duration_seconds),
last_run_total_bytes: asNumber(item.last_run_total_bytes),
last_run_databases: asStringList(item.last_run_databases),
last_run_failed_databases: asStringList(item.last_run_failed_databases),
last_run_error: asString(item.last_run_error),
in_sync: item.in_sync === true,
applied: item.applied === true,
apply_error: asString(item.apply_error),
running: item.running === true,
running_started_at: asString(item.running_started_at),
run_last_error: asString(item.run_last_error),
}
}
async function readSchedule(path: string, failure: string, signal?: AbortSignal): Promise<BackupSchedule> {
const response = await fetch(path, { signal, headers: { Accept: 'application/json' } })
if (!response.ok) throw new Error(`${failure}(HTTP ${response.status})`)
const value = await response.json() as unknown
if (!record(value) || !record(value.data)) throw new Error('存储与备份响应无效')
return scheduleProjection(value.data)
}
export function fetchBackupSchedule(signal?: AbortSignal): Promise<BackupSchedule> {
return readSchedule('/api/v1/backup-schedule', '读取备份计划失败', signal)
}
// host 端点会 SSH 探测目标主机(计划 + 最近一次结果),单独调用以免拖慢首屏。
export function fetchBackupScheduleHost(signal?: AbortSignal): Promise<BackupSchedule> {
return readSchedule('/api/v1/backup-schedule/host', '读取目标主机上的备份状态失败', signal)
}
async function writeSchedule(path: string, method: string, body: unknown, failure: string, signal?: AbortSignal): Promise<BackupSchedule> {
const response = await fetch(path, {
method, signal,
headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'Idempotency-Key': newOperationID() },
body: body === undefined ? undefined : JSON.stringify(body),
})
if (!response.ok) {
let reason = `${failure}(HTTP ${response.status})`
try {
const payload = await response.json() as unknown
if (record(payload) && typeof payload.error === 'string') reason = payload.error
} catch { /* keep the status text */ }
throw new Error(reason)
}
const value = await response.json() as unknown
if (!record(value) || !record(value.data)) throw new Error('存储与备份响应无效')
return scheduleProjection(value.data)
}
export interface BackupScheduleInput {
enabled: boolean
schedule_time: string
retention_days: number
retention_months: number
// 默认 true:保存后立刻下发到目标主机(页面按钮"保存并下发")。
apply?: boolean
}
export function saveBackupSchedule(input: BackupScheduleInput, signal?: AbortSignal): Promise<BackupSchedule> {
return writeSchedule('/api/v1/backup-schedule', 'PUT', input, '保存备份计划失败', signal)
}
export function applyBackupSchedule(signal?: AbortSignal): Promise<BackupSchedule> {
return writeSchedule('/api/v1/backup-schedule/apply', 'POST', undefined, '下发备份计划失败', signal)
}
export async function runBackupNow(signal?: AbortSignal): Promise<BackupRunStart> {
const response = await fetch('/api/v1/backup-schedule/run', {
method: 'POST', signal,
headers: { Accept: 'application/json', 'Idempotency-Key': newOperationID() },
})
if (!response.ok) {
let reason = `触发备份失败(HTTP ${response.status})`
try {
const payload = await response.json() as unknown
if (record(payload) && typeof payload.error === 'string') reason = payload.error
} catch { /* keep the status text */ }
throw new Error(reason)
}
const value = await response.json() as unknown
if (!record(value) || !record(value.data)) throw new Error('触发备份响应无效')
return { started: value.data.started === true, running: value.data.running === true }
}