feat(library): 接通整库封存真实入口与只读版本页
build / build (push) Failing after 19s

- libraryctl:status/preflight/capture/list/verify/recover,只读来源会话、
  结清检查、契约推导、维护窗口内停写者、导出十表+索引+对象+Wiki、封存候选后恢复
- libraryfreeze.ProjectController:按 Compose 项目逐服务声明固定身份,
  未声明服务/容器重建即拒绝,仅 SIGTERM,恢复后必须 healthy
- httpapi:GET /api/v1/library/snapshots[/{id}] 只读列出封存产物
- web:「整库版本」页(只读、未接线显示原因、无假按钮)
- api:LIBRARY_ARCHIVE_ROOT + 归档根只读挂载
- docs/library-capture.md:运维手册与 2026-10-28 两次真实封存实测

不代表整库业务验收通过:内容/问答/性能验收、跨系统切点、Wiki 删除语义重算、
生产预备份/恢复演练/双闸/同步协调仍未完成。
This commit is contained in:
姚章浩
2026-10-28 11:39:50 +08:00
parent 864a1632e0
commit 045fc44f0e
18 changed files with 2221 additions and 4 deletions
+4
View File
@@ -4,6 +4,7 @@ import { DocumentWorkbench } from './DocumentWorkbench'
import { SourceCatalogBrowser } from './SourceCatalogBrowser'
import { WeKnoraMonitor } from './WeKnoraMonitor'
import { VersionHistory } from './VersionHistory'
import { LibraryVersions } from './LibraryVersions'
import { QAOperations } from './QAOperations'
import { SourceLinkManager } from './SourceLinkManager'
import { SystemSettings } from './SystemSettings'
@@ -62,6 +63,7 @@ const modules: ReadonlyArray<{ id: ModuleId; label: string; icon: string }> = [
{ id: 'tasks', label: '解析监控', icon: '↻' },
{ id: 'qaops', label: '问答运营', icon: '▤' },
{ id: 'releases', label: '发布管理', icon: '⇧' },
{ id: 'library', label: '整库版本', icon: '▦' },
{ id: 'settings', label: '系统设置', icon: '⚙' },
{ id: 'versions', label: '版本记录', icon: '⌥' },
]
@@ -2970,6 +2972,8 @@ export default function App() {
<SystemSettings />
) : workspace.activeTab === 'knowledge' ? (
<DocumentWorkbench mode="attention" connections={connectionPage.items} />
) : workspace.activeTab === 'library' ? (
<LibraryVersions />
) : workspace.activeTab === 'versions' ? (
<VersionHistory />
) : workspace.activeTab === 'qaops' ? (
+258
View File
@@ -0,0 +1,258 @@
import { useCallback, useEffect, useMemo, useState } from 'react'
import {
fetchLibrarySnapshots,
formatBytes,
scopeLabel,
type LibrarySnapshot,
type LibrarySnapshotList,
} from './librarySnapshots'
import './libraryVersions.css'
// 「整库版本」页:只读展示已封存的整库候选产物(对内/对外各一份最新)。
// 页面不提供封存按钮:封存要停真实写入者并读来源凭据,只能在目标主机用
// scripts/library-capture.sh 执行。候选 != 验收通过,也 != 可发布。
const stamp = (value: string) =>
value && Number.isFinite(new Date(value).getTime())
? new Date(value).toLocaleString('zh-CN', {
timeZone: 'Asia/Shanghai',
year: 'numeric',
month: '2-digit',
day: '2-digit',
hour: '2-digit',
minute: '2-digit',
hour12: false,
})
: '—'
const metric = (snapshot: LibrarySnapshot, key: string) => String(snapshot.totals[key] ?? 0)
export function LibraryVersions() {
const [page, setPage] = useState<LibrarySnapshotList | null>(null)
const [loading, setLoading] = useState(true)
const [error, setError] = useState<string | null>(null)
const [expanded, setExpanded] = useState<string | null>(null)
const [scopeFilter, setScopeFilter] = useState<'all' | 'internal' | 'external'>('all')
const load = useCallback(async (signal?: AbortSignal) => {
setLoading(true)
try {
const result = await fetchLibrarySnapshots(signal)
setPage(result)
setError(null)
} catch (loadError) {
if ((loadError as Error).name === 'AbortError') return
setError(loadError instanceof Error ? loadError.message : '加载整库版本失败')
} finally {
setLoading(false)
}
}, [])
useEffect(() => {
const controller = new AbortController()
void load(controller.signal)
return () => controller.abort()
}, [load])
const snapshots = page?.snapshots ?? []
const latestByScope = useMemo(() => {
const map: Record<string, LibrarySnapshot | undefined> = {}
for (const snapshot of snapshots) {
if (!map[snapshot.scope]) map[snapshot.scope] = snapshot
}
return map
}, [snapshots])
const visible = snapshots.filter((snapshot) => scopeFilter === 'all' || snapshot.scope === scopeFilter)
return (
<section className="library-versions" aria-label="整库版本">
<header className="library-versions-header">
<div>
<h2>整库版本</h2>
<p className="library-versions-sub">
每个条目是一份<b>完整封存</b>的整库候选:数据库十表、原始索引正文与向量、对象资源与 Wiki 快照,
带逐项摘要与兼容契约。封存期间真实写入者被停住,完成后已恢复。
</p>
</div>
<div className="library-versions-actions">
<span className="library-versions-usage">
共 {snapshots.length} 份 · 归档占用 {formatBytes(page?.stored_bytes ?? 0)}
</span>
<button type="button" onClick={() => void load()} disabled={loading}>
{loading ? '刷新中…' : '刷新'}
</button>
</div>
</header>
{page && !page.available ? (
<div className="library-versions-blocked">
<strong>未接线</strong>
<p>{page.reason || '归档根未配置'}</p>
</div>
) : null}
{error ? (
<div className="library-versions-blocked">
<strong>读取失败</strong>
<p>{error}</p>
</div>
) : null}
{page?.available ? (
<>
<div className="library-versions-scopes">
{(['internal', 'external'] as const).map((scope) => {
const latest = latestByScope[scope]
return (
<article key={scope} className={`library-scope-card ${latest ? '' : 'empty'}`}>
<header>
<h3>{scopeLabel(scope)}</h3>
<span className="library-scope-state">{latest ? '已封存' : '尚无封存'}</span>
</header>
{latest ? (
<>
<p className="library-scope-time">封存于 {stamp(latest.created_at)}</p>
<dl className="library-scope-metrics">
<div>
<dt>文档</dt>
<dd>{metric(latest, 'documents')}</dd>
</div>
<div>
<dt>分块</dt>
<dd>{metric(latest, 'chunks')}</dd>
</div>
<div>
<dt>索引</dt>
<dd>{metric(latest, 'index_documents')}</dd>
</div>
<div>
<dt>资源</dt>
<dd>{metric(latest, 'resources')}</dd>
</div>
<div>
<dt>Wiki 页</dt>
<dd>{metric(latest, 'wiki_pages')}</dd>
</div>
<div>
<dt>体积</dt>
<dd>{formatBytes(latest.logical_bytes)}</dd>
</div>
</dl>
<p className="library-scope-id">
快照 <code>{latest.snapshot_id.slice(0, 16)}</code>
</p>
</>
) : (
<p className="library-scope-hint">
该库没有封存产物。封存在目标主机执行:
<code>scripts/library-capture.sh capture -scope {scope}</code>
</p>
)}
</article>
)
})}
</div>
<div className="library-versions-toolbar">
<div className="library-versions-filters" role="group" aria-label="按范围筛选">
{(
[
{ id: 'all', label: '全部' },
{ id: 'internal', label: '对内' },
{ id: 'external', label: '对外' },
] as const
).map((item) => (
<button
key={item.id}
type="button"
className={scopeFilter === item.id ? 'active' : ''}
onClick={() => setScopeFilter(item.id)}
>
{item.label}
</button>
))}
</div>
<span className="library-versions-note">{page.capture_note}</span>
</div>
{visible.length === 0 ? (
<p className="library-versions-empty">还没有封存产物。</p>
) : (
<table className="library-versions-table">
<thead>
<tr>
<th>封存时间</th>
<th>范围</th>
<th>文档</th>
<th>分块</th>
<th>索引</th>
<th>资源</th>
<th>Wiki</th>
<th>体积</th>
<th>模型 / 维度</th>
<th>快照</th>
</tr>
</thead>
<tbody>
{visible.map((snapshot) => (
<tr key={snapshot.snapshot_id}>
<td>{stamp(snapshot.created_at)}</td>
<td>{scopeLabel(snapshot.scope)}</td>
<td>{metric(snapshot, 'documents')}</td>
<td>{metric(snapshot, 'chunks')}</td>
<td>{metric(snapshot, 'index_documents')}</td>
<td>{metric(snapshot, 'resources')}</td>
<td>{metric(snapshot, 'wiki_pages')}</td>
<td title={`逻辑 ${snapshot.logical_bytes} 字节 · 去重后 ${snapshot.unique_bytes} 字节`}>
{formatBytes(snapshot.logical_bytes)}
</td>
<td>
{snapshot.compatibility.embedding_model || '—'} / {snapshot.compatibility.embedding_dimension}
</td>
<td>
<button
type="button"
className="library-snapshot-toggle"
onClick={() =>
setExpanded(expanded === snapshot.snapshot_id ? null : snapshot.snapshot_id)
}
aria-expanded={expanded === snapshot.snapshot_id}
>
<code>{snapshot.snapshot_id.slice(0, 12)}</code>
{expanded === snapshot.snapshot_id ? ' 收起' : ' 分项'}
</button>
</td>
</tr>
))}
</tbody>
</table>
)}
{visible
.filter((snapshot) => snapshot.snapshot_id === expanded)
.map((snapshot) => (
<div key={snapshot.snapshot_id} className="library-snapshot-parts">
<header>
<strong>{scopeLabel(snapshot.scope)} · {snapshot.snapshot_id}</strong>
<span>
策略 {snapshot.validation_policy || '—'} · WeKnora {snapshot.compatibility.weknora_version} ·
schema {snapshot.compatibility.schema_version} · 映射{' '}
{snapshot.compatibility.index_mapping_sha256.slice(0, 12)}
</span>
</header>
<ul>
{snapshot.parts.map((part) => (
<li key={`${part.kind}-${part.name}`}>
<span className="library-part-kind">{part.kind}</span>
<span className="library-part-name">{part.name}</span>
<span>{part.count} 项</span>
<span>{formatBytes(part.bytes)}</span>
<code title={part.sha256}>{part.sha256.slice(0, 12)}</code>
</li>
))}
</ul>
</div>
))}
</>
) : null}
</section>
)
}
+137
View File
@@ -0,0 +1,137 @@
// 「整库版本」页的只读客户端:列已经封存的整库候选产物。
//
// 这里没有任何写操作:封存需要维护窗口(停真实写入者)与来源凭据,只能由运维
// 命令在目标主机执行。页面只负责如实展示已封存的内容,不提供"开始同步"这类
// 没接线的假按钮。
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 {
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 LibrarySnapshotList {
available: boolean
reason: string
archive_root: string
snapshots: LibrarySnapshot[]
stored_bytes: number
capture_note: 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,
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,
stored_bytes: num(value.stored_bytes),
capture_note: text(value.capture_note),
}
}
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 || '未知范围'
}
+265
View File
@@ -0,0 +1,265 @@
/* Whole-library versions: scope cards first, then a compact sealed-artifact table. */
.library-versions {
display: flex;
flex-direction: column;
gap: 18px;
min-width: 0;
padding: 24px;
color: var(--ink-base);
}
.library-versions-header,
.library-versions-toolbar,
.library-snapshot-parts,
.library-scope-card {
background: var(--bg-panel, #fff);
border: 1px solid var(--border-base, #e2e8f0);
border-radius: 10px;
padding: 20px;
min-width: 0;
}
.library-versions-header {
display: flex;
align-items: flex-start;
justify-content: space-between;
gap: 16px;
flex-wrap: wrap;
}
.library-versions h2 {
margin: 0 0 6px;
font-size: 22px;
}
.library-versions-sub {
margin: 0;
max-width: 68ch;
color: var(--ink-mute, #64748b);
font-size: 13px;
line-height: 1.6;
}
.library-versions-actions {
display: flex;
align-items: center;
gap: 12px;
flex-shrink: 0;
}
.library-versions-usage {
font-size: 13px;
color: var(--ink-mute, #64748b);
font-variant-numeric: tabular-nums;
}
.library-versions-actions button,
.library-versions-filters button {
padding: 7px 14px;
border-radius: 8px;
border: 1px solid var(--border-base, #e2e8f0);
background: var(--bg-panel, #fff);
color: inherit;
cursor: pointer;
}
.library-versions-actions button:disabled {
cursor: progress;
opacity: 0.6;
}
.library-versions-blocked {
border: 1px solid #f3c2b8;
background: #fff6f3;
border-radius: 10px;
padding: 16px 20px;
}
.library-versions-blocked strong {
display: block;
margin-bottom: 4px;
color: #a03a1e;
}
.library-versions-blocked p {
margin: 0;
font-size: 13px;
color: #7c2d12;
}
.library-versions-scopes {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
gap: 16px;
}
.library-scope-card header {
display: flex;
align-items: baseline;
justify-content: space-between;
gap: 12px;
}
.library-scope-card h3 {
margin: 0;
font-size: 18px;
}
.library-scope-state {
font-size: 12px;
padding: 2px 10px;
border-radius: 999px;
background: #ecfdf5;
color: #047857;
border: 1px solid #a7f3d0;
}
.library-scope-card.empty .library-scope-state {
background: #f8fafc;
color: #64748b;
border-color: #e2e8f0;
}
.library-scope-time {
margin: 8px 0 14px;
font-size: 12px;
color: var(--ink-mute, #64748b);
}
.library-scope-metrics {
display: grid;
grid-template-columns: repeat(3, minmax(0, 1fr));
gap: 10px;
margin: 0 0 12px;
}
.library-scope-metrics div {
border: 1px solid var(--border-base, #e2e8f0);
border-radius: 8px;
padding: 8px 10px;
}
.library-scope-metrics dt {
font-size: 12px;
color: var(--ink-mute, #64748b);
}
.library-scope-metrics dd {
margin: 2px 0 0;
font-size: 18px;
font-variant-numeric: tabular-nums;
}
.library-scope-id,
.library-scope-hint {
margin: 0;
font-size: 12px;
color: var(--ink-mute, #64748b);
overflow-wrap: anywhere;
}
.library-scope-hint code,
.library-scope-id code {
font-size: 12px;
background: #f1f5f9;
border-radius: 5px;
padding: 1px 6px;
}
.library-versions-toolbar {
display: flex;
align-items: center;
justify-content: space-between;
gap: 16px;
padding: 12px 16px;
flex-wrap: wrap;
}
.library-versions-filters {
display: flex;
gap: 8px;
}
.library-versions-filters button.active {
border-color: #2563eb;
color: #1d4ed8;
background: #eff6ff;
}
.library-versions-note {
font-size: 12px;
color: var(--ink-mute, #64748b);
max-width: 70ch;
line-height: 1.5;
}
.library-versions-empty {
margin: 0;
padding: 24px;
border: 1px dashed var(--border-base, #e2e8f0);
border-radius: 10px;
color: var(--ink-mute, #64748b);
font-size: 13px;
}
.library-versions-table {
width: 100%;
border-collapse: collapse;
background: var(--bg-panel, #fff);
border: 1px solid var(--border-base, #e2e8f0);
border-radius: 10px;
overflow: hidden;
font-size: 13px;
}
.library-versions-table th,
.library-versions-table td {
padding: 10px 12px;
text-align: left;
border-bottom: 1px solid var(--border-base, #eef2f7);
white-space: nowrap;
}
.library-versions-table th {
font-weight: 600;
font-size: 12px;
color: var(--ink-mute, #64748b);
background: #f8fafc;
}
.library-versions-table td {
font-variant-numeric: tabular-nums;
}
.library-snapshot-toggle {
border: 1px solid var(--border-base, #e2e8f0);
border-radius: 7px;
background: #fff;
padding: 4px 8px;
cursor: pointer;
font-size: 12px;
color: inherit;
}
.library-snapshot-parts header {
display: flex;
flex-direction: column;
gap: 4px;
margin-bottom: 12px;
font-size: 12px;
color: var(--ink-mute, #64748b);
overflow-wrap: anywhere;
}
.library-snapshot-parts header strong {
font-size: 14px;
color: var(--ink-base);
}
.library-snapshot-parts ul {
list-style: none;
margin: 0;
padding: 0;
display: flex;
flex-direction: column;
gap: 6px;
}
.library-snapshot-parts li {
display: grid;
grid-template-columns: 90px minmax(140px, 2fr) 80px 90px 110px;
gap: 10px;
align-items: center;
font-size: 12px;
padding: 6px 8px;
border-radius: 7px;
background: #f8fafc;
overflow-wrap: anywhere;
}
.library-part-kind {
font-size: 11px;
text-transform: uppercase;
letter-spacing: 0.04em;
color: var(--ink-mute, #64748b);
}
.library-part-name {
font-weight: 600;
}
@media (max-width: 760px) {
.library-versions {
padding: 12px;
}
.library-versions-table {
display: block;
overflow-x: auto;
}
.library-snapshot-parts li {
grid-template-columns: 1fr;
}
.library-scope-metrics {
grid-template-columns: repeat(2, minmax(0, 1fr));
}
}
+11 -2
View File
@@ -1,11 +1,20 @@
export type ModuleId = 'dashboard' | 'sources' | 'knowledge' | 'tasks' | 'releases' | 'settings' | 'versions' | 'qaops'
export type ModuleId =
| 'dashboard'
| 'sources'
| 'knowledge'
| 'tasks'
| 'releases'
| 'library'
| 'settings'
| 'versions'
| 'qaops'
export interface WorkspaceState {
openTabs: ModuleId[]
activeTab: ModuleId
}
const moduleIds = new Set<ModuleId>(['dashboard', 'tasks', 'releases', 'settings', 'qaops'])
const moduleIds = new Set<ModuleId>(['dashboard', 'tasks', 'releases', 'library', 'settings', 'qaops'])
export const initialWorkspace: WorkspaceState = {
openTabs: ['dashboard'],