Files
knowledge-governance/web/src/librarySnapshots.ts
T
姚章浩 8d838d9cb4
build / build (push) Successful in 1m45s
feat(library): 整库发布身份、写集合与收尾边界
执行时真实时钟与持久授权回读(撤销/过期即停并保留预备份)、写集合写前落盘、
租约与 attempt 身份、恢复队列与原发送身份分离、成功收尾必须释放维护后再登记终态。
2026-11-01 11:35:10 +08:00

732 lines
25 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// 「整库版本」页的只读客户端:列已经封存的整库候选产物。
//
// 这里没有任何写操作:封存需要维护窗口(停真实写入者)与来源凭据,只能由运维
// 命令在目标主机执行。页面只负责如实展示已封存的内容,不提供"开始同步"这类
// 没接线的假按钮。
export interface LibrarySnapshotPart {
kind: string
name: string
sha256: string
count: number
bytes: number
}
export interface LibraryCompatibility {
weknora_version: string
schema_version: number
retriever_engine: string
embedding_model: string
embedding_dimension: number
index_mapping_sha256: string
}
export interface LibrarySnapshot {
source_id?: string
source_identity?: { project: string; app: string; scope: string; tenant_id: number; knowledge_base_id: string }
snapshot_id: string
scope: string
knowledge_base_id: string
tenant_id: number
created_at: string
validation_policy: string
format: string
compatibility: LibraryCompatibility
parts: LibrarySnapshotPart[]
logical_bytes: number
unique_bytes: number
shared_bytes: number
totals: Record<string, number>
}
export interface LibraryCaptureJob {
job_id: string
capture_job: string
scope: string
state: string
attempt: number
last_error: string
requested_by: string
created_at: string
updated_at: string
}
export interface LibraryCaptureAccepted {
job_id: string
capture_job: string
scope: string
state: string
// true when the idempotency key matched an existing job; the response then
// reports the stored job's scope, not the requested one.
reused: boolean
}
export interface LibrarySnapshotList {
available: boolean
reason: string
archive_root: string
snapshots: LibrarySnapshot[]
// 归档级口径:content_bytes 是跨版本去重后、被版本引用的内容字节;
// 其余字段是文件系统事实,都不是可回收空间。
versions: number
content_bytes: number
blob_file_bytes: number
blob_allocated_bytes: number
unreferenced_blobs: number
unreferenced_bytes: number
manifest_file_bytes: number
manifest_allocated_bytes: number
capture_note: string
capture_available: boolean
capture_reason: string
}
const record = (value: unknown): value is Record<string, unknown> =>
typeof value === 'object' && value !== null && !Array.isArray(value)
const text = (value: unknown) => (typeof value === 'string' ? value : '')
const num = (value: unknown) => (typeof value === 'number' && Number.isFinite(value) ? value : 0)
const bool = (value: unknown) => value === true
function parsePart(raw: unknown): LibrarySnapshotPart | null {
if (!record(raw)) return null
const kind = text(raw.kind)
const name = text(raw.name)
if (!kind || !name) return null
return { kind, name, sha256: text(raw.sha256), count: num(raw.count), bytes: num(raw.bytes) }
}
function parseSnapshot(raw: unknown): LibrarySnapshot | null {
if (!record(raw)) return null
const snapshotID = text(raw.snapshot_id)
if (!snapshotID) return null
const compatibility = record(raw.compatibility) ? raw.compatibility : {}
const totals: Record<string, number> = {}
if (record(raw.totals)) {
for (const [key, value] of Object.entries(raw.totals)) totals[key] = num(value)
}
return {
snapshot_id: snapshotID,
source_id: text(raw.source_id) || undefined,
source_identity: record(raw.source_identity)
? {
project: text(raw.source_identity.project),
app: text(raw.source_identity.app),
scope: text(raw.source_identity.scope),
tenant_id: num(raw.source_identity.tenant_id),
knowledge_base_id: text(raw.source_identity.knowledge_base_id),
}
: undefined,
scope: text(raw.scope),
knowledge_base_id: text(raw.knowledge_base_id),
tenant_id: num(raw.tenant_id),
created_at: text(raw.created_at),
validation_policy: text(raw.validation_policy),
format: text(raw.format),
compatibility: {
weknora_version: text(compatibility.weknora_version),
schema_version: num(compatibility.schema_version),
retriever_engine: text(compatibility.retriever_engine),
embedding_model: text(compatibility.embedding_model),
embedding_dimension: num(compatibility.embedding_dimension),
index_mapping_sha256: text(compatibility.index_mapping_sha256),
},
parts: Array.isArray(raw.parts)
? raw.parts.map(parsePart).filter((item): item is LibrarySnapshotPart => item !== null)
: [],
logical_bytes: num(raw.logical_bytes),
unique_bytes: num(raw.unique_bytes),
shared_bytes: num(raw.shared_bytes),
totals,
}
}
export async function fetchLibrarySnapshots(signal?: AbortSignal): Promise<LibrarySnapshotList> {
const response = await fetch('/api/v1/library/snapshots', {
headers: { Accept: 'application/json' },
signal,
})
const value = (await response.json().catch(() => null)) as unknown
if (!response.ok && !record(value)) {
throw new Error(`加载整库版本失败(HTTP ${response.status})`)
}
if (!record(value)) throw new Error('整库版本响应无效')
const snapshots = Array.isArray(value.snapshots)
? value.snapshots.map(parseSnapshot).filter((item): item is LibrarySnapshot => item !== null)
: []
return {
available: bool(value.available),
reason: text(value.reason),
archive_root: text(value.archive_root),
snapshots,
versions: num(value.versions),
content_bytes: num(value.content_bytes),
blob_file_bytes: num(value.blob_file_bytes),
blob_allocated_bytes: num(value.blob_allocated_bytes),
unreferenced_blobs: num(value.unreferenced_blobs),
unreferenced_bytes: num(value.unreferenced_bytes),
manifest_file_bytes: num(value.manifest_file_bytes),
manifest_allocated_bytes: num(value.manifest_allocated_bytes),
capture_note: text(value.capture_note),
capture_available: bool(value.capture_available),
capture_reason: text(value.capture_reason),
}
}
// 页面发起的封存只投递作业;停写入者、导出与恢复都在主机侧 agent 执行。
export async function enqueueLibraryCapture(scope: string): Promise<LibraryCaptureAccepted> {
const response = await fetch('/api/v1/library/captures', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
body: JSON.stringify({ scope }),
})
const value = (await response.json().catch(() => null)) as unknown
if (!response.ok) {
if (response.status === 403) throw new Error('只有知识工程师及以上可以发起封存。')
if (response.status === 503 && record(value)) {
throw new Error(text(value.reason) || '主机侧封存 agent 未接线')
}
throw new Error(`发起封存失败(HTTP ${response.status})`)
}
if (!record(value)) throw new Error('封存作业响应无效')
return {
job_id: text(value.job_id),
capture_job: text(value.capture_job),
scope: text(value.scope),
state: text(value.state),
reused: bool(value.reused),
}
}
// 恢复能不能点,由真实条件决定:双闸、这份快照的恢复授权、目标实例是否在维护。
export interface LibraryRestoreAvailability {
allowed: boolean
reasons: string[]
scope: string
snapshot_id: string
authorization: LibraryAuthorizationView
}
export async function fetchLibraryRestoreAvailability(
scope: string,
snapshotID: string,
signal?: AbortSignal
): Promise<LibraryRestoreAvailability | null> {
const query = `scope=${encodeURIComponent(scope)}&snapshot_id=${encodeURIComponent(snapshotID)}`
const response = await fetch(`/api/v1/library/restore-availability?${query}`, {
headers: { Accept: 'application/json' },
signal,
})
const value = (await response.json().catch(() => null)) as unknown
if (!record(value)) return null
return {
allowed: bool(value.allowed),
reasons: Array.isArray(value.reasons) ? value.reasons.map(text).filter(Boolean) : [],
scope: text(value.scope),
snapshot_id: text(value.snapshot_id),
authorization: record(value.authorization)
? {
state: text(value.authorization.state) === 'active' ? 'active' : 'none',
authorized_by: text(value.authorization.authorized_by) || undefined,
expires_at: text(value.authorization.expires_at) || undefined,
reason: text(value.authorization.reason) || undefined,
}
: { state: 'none' },
}
}
// 恢复整套生产知识状态:同一份快照的文档、分块、索引、资源与 Wiki 一起回放。
export interface LibraryRestoreAccepted {
job_id: string
scope: string
reused: boolean
}
export async function enqueueLibraryRestore(scope: string, snapshotID: string): Promise<LibraryRestoreAccepted> {
const response = await fetch('/api/v1/library/restores', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
body: JSON.stringify({ scope, snapshot_id: snapshotID }),
})
const value = (await response.json().catch(() => null)) as unknown
if (!response.ok) {
if (response.status === 403) throw new Error('按版本恢复仅管理员可发起。')
if (response.status === 503 && record(value)) {
const reasons = Array.isArray(value.reasons) ? value.reasons.map(text).filter(Boolean) : []
throw new Error(reasons.length > 0 ? reasons.join(';') : text(value.error) || '恢复条件不满足')
}
if (response.status === 409 && record(value)) throw new Error(text(value.error) || '该目标已有在飞作业')
throw new Error(`发起恢复失败(HTTP ${response.status})`)
}
if (!record(value) || !record(value.job)) throw new Error('恢复作业响应无效')
return { job_id: text(value.job.id), scope: text(value.job.scope), reused: bool(value.reused) }
}
export interface LibraryRestoreGrant {
id: string
authorized_by: string
expires_at: string
}
// 同步授权与执行是两步:授权把"范围 + 目标快照 + 参数摘要"钉死并给很短的有效期。
// 它不能顶替恢复授权(摘要不同),也不自动签发 —— 必须由管理员显式点击。
export async function createLibrarySyncAuthorization(
scope: string,
snapshotID: string,
minutes = 30
): Promise<LibraryRestoreGrant> {
const response = await fetch('/api/v1/library/authorizations', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
body: JSON.stringify({ scope, snapshot_id: snapshotID, action: 'sync', expires_in_minutes: minutes }),
})
const value = (await response.json().catch(() => null)) as unknown
if (!response.ok) {
if (response.status === 403) throw new Error('生产发布授权仅管理员可签发。')
if (response.status === 400 && record(value)) throw new Error(text(value.error) || '授权参数不合法')
throw new Error(`签发同步授权失败(HTTP ${response.status})`)
}
if (!record(value) || !record(value.authorization)) throw new Error('授权响应无效')
return {
id: text(value.authorization.id),
authorized_by: text(value.authorization.authorized_by),
expires_at: text(value.authorization.expires_at),
}
}
export interface LibrarySyncAccepted {
job_id: string
scope: string
reused: boolean
}
// 启动同步:闸口未齐时接口返回 503 与逐条缺项,页面照实显示,不假装已启动。
export async function enqueueLibrarySync(
scope: string,
targetSnapshotID: string,
sourceID: string
): Promise<LibrarySyncAccepted> {
const response = await fetch('/api/v1/library/syncs', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
body: JSON.stringify({ scope, target_snapshot_id: targetSnapshotID, source_id: sourceID }),
})
const value = (await response.json().catch(() => null)) as unknown
if (!response.ok) {
if (record(value) && Array.isArray(value.reasons)) {
const reasons = value.reasons.map(text).filter(Boolean)
if (reasons.length > 0) throw new Error(`启动同步被拒绝:${reasons.join(';')}`)
}
if (record(value) && text(value.error)) throw new Error(text(value.error))
throw new Error(`启动同步失败(HTTP ${response.status})`)
}
if (!record(value) || !record(value.job)) throw new Error('同步作业响应无效')
return { job_id: text(value.job.id), scope: text(value.job.scope), reused: bool(value.reused) }
}
// 建立目标权威基线:目标非空又没有生效版本时的唯一入口(维护隔离 + 真实捕获 + 校验)。
export async function enqueueLibraryBaseline(scope: string): Promise<LibrarySyncAccepted> {
const response = await fetch('/api/v1/library/baselines', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
body: JSON.stringify({ scope }),
})
const value = (await response.json().catch(() => null)) as unknown
if (!response.ok) {
if (response.status === 403) throw new Error('建立目标权威基线仅管理员可发起。')
if (record(value) && text(value.error)) throw new Error(text(value.error))
throw new Error(`建立基线失败(HTTP ${response.status})`)
}
if (!record(value) || !record(value.job)) throw new Error('基线作业响应无效')
return { job_id: text(value.job.id), scope: text(value.job.scope), reused: bool(value.reused) }
}
// 恢复授权与执行是两件事:授权把"目标 + 快照 + 参数"钉死并给很短的有效期,
// 同步授权不能顶替恢复授权(摘要不同)。
export async function createLibraryRestoreAuthorization(
scope: string,
snapshotID: string,
minutes = 30
): Promise<LibraryRestoreGrant> {
const response = await fetch('/api/v1/library/authorizations', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
body: JSON.stringify({ scope, snapshot_id: snapshotID, action: 'restore', expires_in_minutes: minutes }),
})
const value = (await response.json().catch(() => null)) as unknown
if (!response.ok) {
if (response.status === 403) throw new Error('生产发布授权仅管理员可签发。')
throw new Error(`签发恢复授权失败(HTTP ${response.status})`)
}
if (!record(value) || !record(value.authorization)) throw new Error('授权响应无效')
return {
id: text(value.authorization.id),
authorized_by: text(value.authorization.authorized_by),
expires_at: text(value.authorization.expires_at),
}
}
export async function fetchLibraryCaptures(signal?: AbortSignal): Promise<LibraryCaptureJob[]> {
const response = await fetch('/api/v1/library/captures', {
headers: { Accept: 'application/json' },
signal,
})
const value = (await response.json().catch(() => null)) as unknown
if (!response.ok || !record(value) || !Array.isArray(value.jobs)) return []
return value.jobs.filter(record).map((job) => ({
job_id: text(job.job_id),
capture_job: text(job.capture_job),
scope: text(job.scope),
state: text(job.state),
attempt: num(job.attempt),
last_error: text(job.last_error),
requested_by: text(job.requested_by),
created_at: text(job.created_at),
updated_at: text(job.updated_at),
}))
}
export function formatBytes(bytes: number): string {
if (!Number.isFinite(bytes) || bytes <= 0) return '0 B'
const units = ['B', 'KB', 'MB', 'GB', 'TB']
let index = 0
let value = bytes
while (value >= 1024 && index < units.length - 1) {
value /= 1024
index += 1
}
return `${value >= 10 || index === 0 ? value.toFixed(0) : value.toFixed(1)} ${units[index]}`
}
export function scopeLabel(scope: string): string {
if (scope === 'internal') return '对内'
if (scope === 'external') return '对外'
return scope || '未知范围'
}
// ---- 整库状态:测试封存 / 生产生效 / 生产预备份 三类版本 + 差异 + 持久作业 ----
export interface LibraryVersionRecord {
id: string
kind: 'test_sealed' | 'production_effective' | 'production_prebackup'
snapshot_id: string
version_label: string
source_job_id: string
evidence: Record<string, unknown>
created_by: string
created_at: string
superseded_at?: string | null
}
export interface LibraryKnown {
state: 'known' | 'unknown'
version?: LibraryVersionRecord
reason?: string
/** 只在预备份上有意义:这份备份的内容是否就是当前拟发布目标。 */
bound_to_target?: boolean
}
export interface LibraryDiff {
state: 'unknown' | 'computed'
reason?: string
added: unknown[]
updated: unknown[]
removed: unknown[]
/** 这次比对用的两个整库版本(生产 → 测试),避免把历史差异当成当前。 */
base_snapshot?: string
target_snapshot?: string
/**
* Wiki 逐页贡献级差异:来源文档 / 引用分块 / 出入边 / 目录分别比。
* 语义重算发生在源侧,这里只如实反映重算后的结果——撤销一份共享贡献时
* 页面通常还是"更新",要看 pages[].sources_removed 才知道那份贡献被摘掉了。
*/
wiki?: {
state: 'computed' | 'unknown'
reason?: string
added: number
updated: number
removed: number
sample: string[]
note: string
pages?: LibraryWikiPageChange[]
pages_truncated?: boolean
sources_added?: number
sources_removed?: number
base_count?: number
target_count?: number
}
}
export interface LibraryWikiPageChange {
slug: string
title: string
page_type?: string
status: 'added' | 'updated' | 'removed'
changed: string[]
sources_added?: string[]
sources_removed?: string[]
citations_before: number
citations_after: number
}
// ---- 目标维护窗口:级别、阶段、入口状态与恢复错误 ----
export interface LibraryMaintenanceRecord {
scope: string
owner_job_id: string
target_identity?: string
level: string
target_fingerprint?: string
services?: string[]
ingress_state: string
state: string
original_service_state?: string
note?: string
acquired_at: string
updated_at: string
released_at?: string | null
}
export interface LibraryInstanceMaintenanceRecord extends LibraryMaintenanceRecord {
instance: string
owner_scope: string
}
export interface LibraryMaintenanceView {
held: boolean
maintenance?: LibraryMaintenanceRecord | null
instance?: string
instance_maintenance?: LibraryInstanceMaintenanceRecord | null
// 能力是配置事实,和"此刻有没有窗口"分开:未运行维护 ≠ 没有维护能力。
capability?: LibraryMaintenanceCapability | null
}
export interface LibraryMaintenanceCapability {
configured: boolean
missing: string[]
instance?: string
project?: string
writers?: string[]
ingress_service?: string
note?: string
}
export async function fetchLibraryMaintenance(
scope: string,
signal?: AbortSignal
): Promise<LibraryMaintenanceView | null> {
const response = await fetch(`/api/v1/library/maintenance?scope=${encodeURIComponent(scope)}`, {
headers: { Accept: 'application/json' },
signal,
})
if (!response.ok) return null
const value = (await response.json().catch(() => null)) as unknown
if (!record(value)) return null
return value as unknown as LibraryMaintenanceView
}
export interface LibraryRecoveryAccepted {
accepted?: boolean
recovery_job?: string
state?: string
code?: string
error?: string
}
export async function enqueueLibraryRecovery(scope: string, windowJobID: string): Promise<LibraryRecoveryAccepted> {
const response = await fetch('/api/v1/library/maintenance/recover', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
body: JSON.stringify({ scope, window_job_id: windowJobID }),
})
const value = (await response.json().catch(() => ({}))) as unknown
const body = record(value) ? (value as LibraryRecoveryAccepted) : {}
if (!response.ok) {
throw new Error(body.error || `恢复请求被拒绝(HTTP ${response.status})`)
}
return body
}
export interface LibraryStageRow {
stage: string
state: string
total: number | null
completed: number | null
bytes_total: number | null
bytes_done: number | null
detail: string
updated_at: string
}
export interface LibraryJobRecord {
id: string
scope: string
kind: 'seal' | 'sync' | 'restore' | 'baseline'
state: 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'
stage: string
request_digest: string
queue_job_id: string
snapshot_id: string
target_snapshot_id: string
actor: string
error: string
recovery: string
created_at: string
updated_at: string
finished_at?: string | null
stages: LibraryStageRow[]
}
/**
* 已登记版本的轻量清单(不含 evidence)。
* 归档里不止"测试封存":目标基线与每次生产预备份也在同一个归档根下,
* 页面必须按登记过的 kind 给每份快照写类型,不能一律写"测试封存"。
*/
export interface LibraryVersionRef {
id: string
kind: 'test_sealed' | 'production_effective' | 'production_prebackup' | string
snapshot_id: string
version_label: string
source_job_id: string
created_at: string
superseded_at?: string | null
}
export interface LibraryAuthorizationView {
state: 'active' | 'none'
authorized_by?: string
expires_at?: string
reason?: string
}
export interface LibraryGate {
sync_allowed: boolean
reasons: string[]
}
export interface LibraryExecutorView {
available: boolean
reason?: string
instance?: string
project?: string
source_app?: string
archive_root?: string
busy: boolean
degraded?: string
observed_at?: string
}
export interface LibraryOverview {
scope: string
test_sealed?: LibrarySnapshot
test_sealed_reason?: string
production: LibraryKnown
prebackup: LibraryKnown
/** 已登记版本(轻量):页面据此给归档里的每份快照标类型。 */
versions?: LibraryVersionRef[]
diff: LibraryDiff
job?: LibraryJobRecord
jobs: LibraryJobRecord[]
gate: LibraryGate
authorization: LibraryAuthorizationView
capture_available: boolean
capture_reason?: string
// 执行器是 worker 的真实观测:指向哪个实例、何时观测、是否降级/在跑。
executor?: LibraryExecutorView
now: string
}
export async function fetchLibraryOverview(scope: string, signal?: AbortSignal): Promise<LibraryOverview | null> {
const response = await fetch(`/api/v1/library/overview?scope=${encodeURIComponent(scope)}`, {
headers: { Accept: 'application/json' },
signal,
})
// 非 2xx 的响应体会是 {error: ...},把它 cast 成 LibraryOverview 会让页面在
// `overview.gate.sync_allowed` 上抛 TypeError(F16)。这里必须先核状态码与结构,
// 结构不符就**报错**,让页面显示"读取失败"而不是崩溃或当成正常状态。
if (!response.ok) {
throw new Error(`发布状态读取失败(HTTP ${response.status})`)
}
const value = (await response.json().catch(() => null)) as unknown
if (
!record(value) ||
!record((value as { gate?: unknown }).gate) ||
!Array.isArray((value as { jobs?: unknown }).jobs)
) {
throw new Error('发布状态响应结构不符合预期(缺 gate/jobs)')
}
return value as unknown as LibraryOverview
}
// ---- 存储管理:容量、保留策略、依赖保护与清理预览(只读) ----
export interface LibraryStorageVersion {
id: string
kind: string
scope: string
created_at: string
protected: boolean
protected_by?: string[]
exclusive_bytes: number
shared_bytes: number
}
export interface LibraryRetentionPolicy {
keep_versions: number
keep_days: number
}
export interface LibraryCleanupCandidate {
id: string
kind: string
reason: string[]
exclusive_bytes: number
}
export interface LibraryRetentionPlan {
policy: LibraryRetentionPolicy
policy_configured: boolean
automatic_cleanup: boolean
version_count: number
total_bytes: number
protected: string[]
keep: string[]
candidates: LibraryCleanupCandidate[]
reclaim_preview_bytes: number
blocked: string[]
now: string
}
export interface LibraryCapacity {
budget_bytes: number
current_bytes: number
required_bytes: number
projected_bytes: number
configured: boolean
ok: boolean
reason?: string
}
export interface LibraryStorage {
available: boolean
reason?: string
archive_root?: string
versions: LibraryStorageVersion[]
content_bytes: number
blob_file_bytes: number
blob_allocated_bytes: number
unreferenced_blobs: number
unreferenced_bytes: number
manifest_file_bytes: number
policy: LibraryRetentionPolicy
plan?: LibraryRetentionPlan
capacity: LibraryCapacity
automatic_cleanup: boolean
notes: string[]
}
export async function fetchLibraryStorage(signal?: AbortSignal): Promise<LibraryStorage | null> {
const response = await fetch('/api/v1/library/storage', {
headers: { Accept: 'application/json' },
signal,
})
const value = (await response.json().catch(() => null)) as unknown
if (!record(value)) return null
return value as unknown as LibraryStorage
}