feat(library): 恢复验证成为可页面发起的真实作业
build / build (push) Successful in 1m40s

根因:生产可恢复性只有 PRODUCTION_BACKUP_RESTORE_VERIFIED 这个手填 env 开关,
页面没有任何入口去真跑一次恢复;CLI(librarydrill)又不是 worker 能复用的实现,
所以"已验证"既证明不了跑过、也证明不了跑的是当前目标。

改动:
- 共享实现 internal/libraryverify(维护隔离→捕获→基线校验→canary→恢复→复核→关窗口),
  cmd/librarydrill 改为薄封装,CLI 与 worker 只允许一份执行体。
- verify 成为独立业务作业:kind + VerifyStages(capture/verify/canary/restore/finalize),
  与 sync/restore/baseline 共用同一把写互斥;迁移 79 加 kind 约束、重建部分唯一索引、
  新建 library_restore_verifications(按 target_id 绑定,换库/索引/桶旧证据自动失效,
  同 target+scope+job 幂等)。
- worker:admitLibraryJob + runOwnedLibraryAttempt 之后调用共享实现,阶段实时写
  library_job_stages,结束后写真实终态;通过写 passed 证据,失败写 failed+原因(不伪成功);
  中断接管按同一作业 id 收掉维护窗口。
- API:POST/GET /api/v1/library/verifications(管理员;闸口关闭/维护中拒绝;返回完整
  整库目标、最近证据、失败原因),OpenAPI 同步。
- 闸口:同步/恢复/续作的证据判断改为读当前目标证据;历史 env 仅在证据缺失时兜底,
  证据存在时以证据为准。
- 页面:生产保护与恢复面板加「恢复验证」块(完整 KB/索引/桶、状态、最近证据、失败原因、
  管理员按钮、5s 轮询),作业类型补 verify 文案。

测试:make verify 16/16 全绿(go 1387 例 + web 454 例 + 契约/迁移/密钥/依赖锁定);
新增用例覆盖证据四条件、闸口证据优先、页面无证据/失败/通过三种呈现与管理员可见性。
This commit is contained in:
姚章浩
2026-11-03 10:14:08 +08:00
parent 4421dd38ce
commit 5e1482e349
47 changed files with 2502 additions and 353 deletions
+26
View File
@@ -22,6 +22,7 @@ const base: BackupSchedule = {
last_applied_summary: '每天 03:30 · 保留 7 天 · 每月归档 3 份',
host_configured: true,
host_target: 'weknora-test',
host_endpoint: '100.85.111.121:22',
host_reachable: true,
host_error: '',
host_schedule_enabled: true,
@@ -88,6 +89,9 @@ describe('BackupScheduleView', () => {
'重新下发当前设置',
'立即备份一次',
'weknora-test · 已连接',
'拨号地址',
'100.85.111.121:22',
'全库,不是 scope 快照',
'每天 03:30 · 保留 7 天 · 每月 3 份',
'已一致',
'20261009T052909Z',
@@ -120,6 +124,28 @@ describe('BackupScheduleView', () => {
expect(html).toContain('disabled')
})
it('连不上主机:报连接失败与拨号地址,脚本状态写未知而不是"缺失"', () => {
const html = view({
host_reachable: false,
host_endpoint: '120.76.217.51:22',
host_error:
'目标主机 weknora-test 不可达(ssh: connect to host 120.76.217.51 port 22: Operation timed out);未执行任何主机侧脚本,脚本与计划状态未知(拨号地址 120.76.217.51:22)',
in_sync: false,
host_script_present: false,
})
expect(html).toContain('weknora-test · 连接失败')
expect(html).toContain('120.76.217.51:22')
expect(html).toContain('未知(未连上主机,未执行主机侧脚本)')
expect(html).not.toContain('缺失')
})
it('已连上且脚本真的不在:这时才显示"缺失"', () => {
const html = view({ host_reachable: true, host_script_present: false, in_sync: false })
expect(html).toContain('weknora-test · 已连接')
expect(html).toContain('缺失')
expect(html).not.toContain('未知(未连上主机')
})
it('待下发(主机上的计划与设置不一致)时提示', () => {
const html = view({ host_schedule_time: '05:00', in_sync: false })
expect(html).toContain('待下发')
+16 -5
View File
@@ -91,6 +91,12 @@ export function BackupScheduleView(props: BackupScheduleViewProps) {
: schedule.host_reachable
? `${schedule.host_target} · 已连接`
: `${schedule.host_target} · 连接失败`
// 只有真的连上并读回主机状态时,才能说脚本在不在;连不上是"未知"。
const scriptLine = !schedule.host_reachable
? '未知(未连上主机,未执行主机侧脚本)'
: schedule.host_script_present
? '存在'
: '缺失'
return (
<section className="settings-panel wide storage-settings-panel" id="settings-storage">
@@ -115,11 +121,12 @@ export function BackupScheduleView(props: BackupScheduleViewProps) {
<dl>
<dt>目标主机</dt>
<dd>{hostLine}</dd>
<dt>拨号地址</dt>
<dd>{schedule.host_endpoint || '—'}</dd>
<dt>备份脚本</dt>
<dd>{scriptLine}</dd>
<dt>主机 cron</dt>
<dd>
{schedule.host_cron_service ? `服务 ${schedule.host_cron_service}` : '—'}
{schedule.host_script_present ? '' : ' · 备份脚本缺失'}
</dd>
<dd>{schedule.host_cron_service ? `服务 ${schedule.host_cron_service}` : '—'}</dd>
<dt>最近一次备份</dt>
<dd>
{schedule.last_run_stamp || '—'}
@@ -213,8 +220,12 @@ export function BackupScheduleView(props: BackupScheduleViewProps) {
{busy === 'apply' ? '正在下发…' : '重新下发当前设置'}
</button>
<button onClick={onRunNow} disabled={busy !== null || !schedule.host_configured || schedule.running}>
{schedule.running ? '备份进行中…' : '立即备份一次'}
{schedule.running ? '备份进行中…' : '立即备份一次(全库,不是 scope 快照)'}
</button>
<p className="hint">
「立即备份一次」执行的是主机上的整库逻辑备份(该主机上全部业务库的 pg_dump 目录),
<strong>不是</strong>本次对内/对外 scope 的整库快照;scope 快照在「发布管理 → 整库版本」里封存。
</p>
{message ? (
<p className="success-message" role="status">
{message}
+101
View File
@@ -0,0 +1,101 @@
import { renderToStaticMarkup } from 'react-dom/server'
import { describe, expect, it, vi } from 'vitest'
import { ProductionBindingsView } from './ProductionBindingsSection'
import type { ProductionBindings } from './productionBindings'
const bindings = (overrides: Partial<ProductionBindings> = {}): ProductionBindings => ({
internal_kb_id: '0b217e8a-2a65-40a3-ab8f-34ac5c7a6f05',
external_kb_id: '9a1e5c11-0000-4000-8000-000000000002',
internal_kb_name: '对内知识库-wiki',
external_kb_name: '对外知识库-wiki',
updated_by: 'yaozhanghao',
production_base_url: 'https://weknora-test.dobot.cn',
production_connected: true,
production_message: '',
legacy_scope: '文档级发布(单篇文档写生产)· 旧路径',
whole_target: {
configured: true,
source: '部署环境 LIBRARY_PRODUCTION_*',
tenant_id: 10000,
internal_kb_id: 'a8e9c8ad-411c-4c53-8421-599d29e9b179',
external_kb_id: '2e980686-2233-4c4e-b5a6-8b0069477b8e',
database: 'pgm-wz9ohr9gk919pr1q.pg.rds.aliyuncs.com:5432/weknora_test',
elastic_index: 'weknora_test_chunks',
object_bucket: 'dobot-weknora-test',
missing_reason: '',
},
...overrides,
})
const view = (value: ProductionBindings | null, admin = true) =>
renderToStaticMarkup(
<ProductionBindingsView
bindings={value}
options={[]}
internalDraft={value?.internal_kb_id ?? ''}
externalDraft={value?.external_kb_id ?? ''}
isAdmin={admin}
loading={false}
saving={false}
error={null}
message=""
dirty={false}
sameSelection={false}
onInternalChange={vi.fn()}
onExternalChange={vi.fn()}
onSave={vi.fn()}
onReload={vi.fn()}
/>
)
describe('ProductionBindingsView', () => {
it('把实际整库目标(完整 ID + 端点)显示出来,而不是只显示可编辑的文档级绑定', () => {
const html = view(bindings())
expect(html).toContain('整库发布目标(实际写入,只读)')
// 完整 ID 必须可读:截断会让操作者核对不了 a8e9c8ad 与 0b217e8a 的区别。
expect(html).toContain('a8e9c8ad-411c-4c53-8421-599d29e9b179')
expect(html).toContain('2e980686-2233-4c4e-b5a6-8b0069477b8e')
expect(html).toContain('pgm-wz9ohr9gk919pr1q.pg.rds.aliyuncs.com:5432/weknora_test')
expect(html).toContain('weknora_test_chunks')
expect(html).toContain('dobot-weknora-test')
expect(html).toContain('部署环境 LIBRARY_PRODUCTION_*')
})
it('旧文档级绑定标成旧路径,不再声称"发布写入此库"', () => {
const html = view(bindings())
expect(html).toContain('文档级发布(单篇文档写生产)· 旧路径')
expect(html).toContain('仅文档级发布读取这组绑定;整库发布(封存/同步/恢复)不读它。')
expect(html).toContain('对内文档级目标')
expect(html).not.toContain('发布写入此库')
})
it('整库目标缺配置:点名缺哪个环境变量,且不拿文档级绑定顶上去', () => {
const html = view(
bindings({
whole_target: {
configured: false,
source: '部署环境 LIBRARY_PRODUCTION_*',
tenant_id: 0,
internal_kb_id: '',
external_kb_id: '',
database: '(未配置)',
elastic_index: '',
object_bucket: '',
missing_reason: '未配置:LIBRARY_PRODUCTION_DATABASE_URL、LIBRARY_PRODUCTION_KB_INTERNAL',
},
})
)
expect(html).toContain('LIBRARY_PRODUCTION_DATABASE_URL')
expect(html).toContain('整库目标配置不全')
// 文档级绑定仍然显示,但必须仍是"文档级"身份,不能冒充整库目标。
expect(html).toContain('对内文档级目标')
})
it('非管理员看得到目标,但没有保存入口', () => {
const html = view(bindings(), false)
expect(html).toContain('a8e9c8ad-411c-4c53-8421-599d29e9b179')
expect(html).not.toContain('保存文档级目标')
expect(html).toContain('仅管理员可修改文档级发布目标')
})
})
+196 -88
View File
@@ -5,8 +5,182 @@ import { fetchProductionBindingOptions, fetchProductionBindings, saveProductionB
import type { ProductionBindings } from './productionBindings'
import type { KnowledgeBaseOption } from './routingBindings'
// 「生产知识库绑定」:发布链路的 源库 → 目标库 映射。这里选的是发布要写入的
// 生产(目标)知识库,与上面的「测试知识库绑定」(测试端收件库)是两件事。
// 「生产知识库绑定」:这里同时涉及两条独立路径,页面必须分开写清楚:
// 1) 整库发布目标(封存/同步/恢复真正写入的库与端点)——来自部署配置,只读;
// 2) 文档级绑定(旧流程:单篇文档发布写哪个库)——可在这里编辑。
// 把 2 写成"发布写入此库"会让操作者以为整库发布会写进 0b217e8a 这类 2000+ 文档库。
export interface ProductionBindingsViewProps {
bindings: ProductionBindings | null
options: KnowledgeBaseOption[]
internalDraft: string
externalDraft: string
isAdmin: boolean
loading: boolean
saving: boolean
error: string | null
message: string
dirty: boolean
sameSelection: boolean
onInternalChange: (next: string) => void
onExternalChange: (next: string) => void
onSave: () => void
onReload: () => void
}
export function ProductionBindingsView(props: ProductionBindingsViewProps) {
const {
bindings,
options,
internalDraft,
externalDraft,
isAdmin,
loading,
saving,
error,
message,
dirty,
sameSelection,
onInternalChange,
onExternalChange,
onSave,
onReload,
} = props
const optionLabel = (base: KnowledgeBaseOption) => `${base.name}(${base.knowledge_count} 文档)`
const renderSide = (label: string, boundID: string, boundName: string) => (
<div className={`kb-binding-side ${boundID ? 'bound' : 'warn'}`}>
<b>{label}</b>
<span>
{boundID ? boundName || `${boundID.slice(0, 8)}…` : '未绑定 · 按同 ID 语义发布(目标端须存在同 ID 库)'}
</span>
<small>{boundID ? '文档级绑定 · 只影响单篇文档发布,不改整库目标' : '未绑定:沿用测试库 ID'}</small>
</div>
)
const whole = bindings?.whole_target
const wholeRows: [string, string][] = whole
? [
['对内目标知识库', whole.internal_kb_id || '未配置'],
['对外目标知识库', whole.external_kb_id || '未配置'],
['目标数据库', whole.database || '—'],
['检索索引', whole.elastic_index || '—'],
['对象存储桶', whole.object_bucket || '—'],
['租户', whole.tenant_id ? String(whole.tenant_id) : '—'],
['配置来源', whole.source || '—'],
]
: []
const editorFor = (value: string, onChange: (next: string) => void, placeholder: string) =>
options.length > 0 ? (
<select value={value} onChange={(event) => onChange(event.target.value)} aria-label={placeholder}>
<option value="">{placeholder}</option>
{options.map((base) => (
<option key={base.id} value={base.id}>
{optionLabel(base)}
</option>
))}
</select>
) : (
<input
value={value}
onChange={(event) => onChange(event.target.value.trim())}
placeholder={`${placeholder}(输入生产知识库 ID)`}
aria-label={placeholder}
/>
)
return (
<section className="settings-panel wide" id="settings-production-bindings">
<div className="settings-section-heading">
<div>
<h2>生产知识库绑定</h2>
<p>
这里有两件不同的事,页面分开显示:<strong>整库发布目标</strong>(封存/同步/恢复真正写入的目标,
由部署配置决定,只读)与<strong>文档级绑定</strong>(旧流程:单篇文档发布写哪个库,可在这里改)。
</p>
</div>
<button onClick={onReload} disabled={loading}>
{loading ? '读取中…' : '重新读取'}
</button>
</div>
{error ? (
<p className="error-message" role="alert">
{error}
</p>
) : null}
{bindings ? (
<div className="stack" id="settings-whole-library-target">
<h3>整库发布目标(实际写入,只读)</h3>
{whole?.configured === false ? (
<p className="hint">
整库目标配置不全:{whole.missing_reason}。整库封存/同步/恢复在补齐部署配置前会被拒绝,
页面不会用下面的文档级绑定顶上。
</p>
) : null}
{wholeRows.length ? (
<dl className="storage-settings-grid">
{wholeRows.map(([label, value]) => (
<div key={label}>
<dt>{label}</dt>
<dd>
<code>{value}</code>
</dd>
</div>
))}
</dl>
) : null}
<p className="hint">
这份目标来自部署环境,不在页面上编辑;改它需要改部署配置并重启 api/worker,不会由本页保存。
</p>
</div>
) : null}
{bindings ? (
<div className="stack">
<h3>{bindings.legacy_scope || '文档级绑定(旧路径)'}</h3>
<p className="hint">仅文档级发布读取这组绑定;整库发布(封存/同步/恢复)不读它。</p>
<div className="kb-binding-grid">
{renderSide('对内文档级目标', bindings.internal_kb_id, bindings.internal_kb_name)}
{renderSide('对外文档级目标', bindings.external_kb_id, bindings.external_kb_name)}
</div>
</div>
) : null}
{bindings && !bindings.production_connected ? (
<p className="hint">
生产端核对不可用:{bindings.production_message}。
{bindings.production_base_url ? `(生产地址:${bindings.production_base_url})` : ''}
</p>
) : null}
{bindings && bindings.production_connected && bindings.production_base_url ? (
<p className="hint">
生产端:{bindings.production_base_url}
{bindings.updated_by ? ` · 最近修改:${bindings.updated_by}` : ''}
</p>
) : null}
{isAdmin && bindings ? (
<div className="kb-binding-editor">
<label>
对内文档级目标 {editorFor(internalDraft, onInternalChange, '选择对内文档级目标库')}
</label>
<label>
对外文档级目标 {editorFor(externalDraft, onExternalChange, '选择对外文档级目标库')}
</label>
<p className="hint">保存时只改文档级绑定;整库发布目标由部署配置决定,本页不改它。</p>
<p className="hint">保存时会向生产端核对所选的库是否真实存在;对不上会拒收,生产端不可达则只提示。</p>
{sameSelection ? <p className="error-message">对内与对外必须绑定不同的生产知识库</p> : null}
<button onClick={onSave} disabled={saving || !dirty || sameSelection}>
{saving ? '正在核对并保存…' : '保存文档级目标'}
</button>
{message ? (
<p className="success-message" role="status">
{message}
</p>
) : null}
</div>
) : null}
{!isAdmin ? <p className="hint">仅管理员可修改文档级发布目标。</p> : null}
</section>
)
}
// 容器:读取 + 保存。整库目标只读展示,保存动作只写文档级绑定。
export function ProductionBindingsSection() {
const auth = useOptionalAuth()
const isAdmin = auth?.identity?.role === 'admin'
@@ -56,8 +230,8 @@ export function ProductionBindingsSection() {
const where = `对内 ${next.internal_kb_name || next.internal_kb_id.slice(0, 8) || '未绑定'} · 对外 ${next.external_kb_name || next.external_kb_id.slice(0, 8) || '未绑定'}`
setMessage(
next.production_connected
? `发布目标已更新:${where}。之后新发布的“对内/对外”内容会写入这两个生产库(已发布过的条目仍回到原目标)。`
: `发布目标已保存:${where};但当前核对不了生产端(${next.production_message}),下次发布前请确认。`
? `文档级发布目标已更新:${where}。只影响单篇文档发布;整库发布写的是上面那份「整库发布目标」。`
: `文档级发布目标已保存:${where};但当前核对不了生产端(${next.production_message}),下次发布前请确认。`
)
} catch (cause) {
setError(cause instanceof Error ? cause.message : '保存生产知识库绑定失败')
@@ -66,89 +240,23 @@ export function ProductionBindingsSection() {
}
}
const optionLabel = (base: KnowledgeBaseOption) => `${base.name}(${base.knowledge_count} 文档)`
const renderSide = (label: string, boundID: string, boundName: string) => (
<div className={`kb-binding-side ${boundID ? 'bound' : 'warn'}`}>
<b>{label}</b>
<span>
{boundID ? boundName || `${boundID.slice(0, 8)}…` : '未绑定 · 按同 ID 语义发布(目标端须存在同 ID 库)'}
</span>
<small>{boundID ? 'UI 绑定 · 发布写入此库' : '未绑定:沿用测试库 ID'}</small>
</div>
)
const editorFor = (value: string, onChange: (next: string) => void, placeholder: string) =>
options.length > 0 ? (
<select value={value} onChange={(event) => onChange(event.target.value)} aria-label={placeholder}>
<option value="">{placeholder}</option>
{options.map((base) => (
<option key={base.id} value={base.id}>
{optionLabel(base)}
</option>
))}
</select>
) : (
<input
value={value}
onChange={(event) => onChange(event.target.value.trim())}
placeholder={`${placeholder}(输入生产知识库 ID)`}
aria-label={placeholder}
/>
)
return (
<section className="settings-panel wide" id="settings-production-bindings">
<div className="settings-section-heading">
<div>
<h2>生产知识库绑定</h2>
<p>
发布链路的“源库 → 目标库”:新发布的对内 / 对外内容按这里的绑定写入生产 WeKnora
的对应知识库。留空表示未绑定,按同 ID 语义发布。
</p>
</div>
<button onClick={() => void load()} disabled={loading}>
{loading ? '读取中…' : '重新读取'}
</button>
</div>
{error ? (
<p className="error-message" role="alert">
{error}
</p>
) : null}
{bindings ? (
<div className="kb-binding-grid">
{renderSide('对内生产知识库', bindings.internal_kb_id, bindings.internal_kb_name)}
{renderSide('对外生产知识库', bindings.external_kb_id, bindings.external_kb_name)}
</div>
) : null}
{bindings && !bindings.production_connected ? (
<p className="hint">
生产端核对不可用:{bindings.production_message}。
{bindings.production_base_url ? `(生产地址:${bindings.production_base_url})` : ''}
</p>
) : null}
{bindings && bindings.production_connected && bindings.production_base_url ? (
<p className="hint">
生产端:{bindings.production_base_url}
{bindings.updated_by ? ` · 最近修改:${bindings.updated_by}` : ''}
</p>
) : null}
{isAdmin && bindings ? (
<div className="kb-binding-editor">
<label>对内目标库 {editorFor(internalDraft, setInternalDraft, '选择对内生产知识库')}</label>
<label>对外目标库 {editorFor(externalDraft, setExternalDraft, '选择对外生产知识库')}</label>
<p className="hint">保存时会向生产端核对所选的库是否真实存在;对不上会拒收,生产端不可达则只提示。</p>
{sameSelection ? <p className="error-message">对内与对外必须绑定不同的生产知识库</p> : null}
<button onClick={() => void save()} disabled={saving || !dirty || sameSelection}>
{saving ? '正在核对并保存…' : '保存发布目标'}
</button>
{message ? (
<p className="success-message" role="status">
{message}
</p>
) : null}
</div>
) : null}
{!isAdmin ? <p className="hint">仅管理员可修改发布目标。</p> : null}
</section>
<ProductionBindingsView
bindings={bindings}
options={options}
internalDraft={internalDraft}
externalDraft={externalDraft}
isAdmin={isAdmin}
loading={loading}
saving={saving}
error={error}
message={message}
dirty={dirty}
sameSelection={sameSelection}
onInternalChange={setInternalDraft}
onExternalChange={setExternalDraft}
onSave={() => void save()}
onReload={() => void load()}
/>
)
}
}
+9 -1
View File
@@ -27,6 +27,7 @@ import {
} from './librarySnapshots'
import { useOptionalAuth } from './auth'
import './releaseTargets.css'
import { RestoreVerificationSection } from './RestoreVerificationSection'
// 发布管理:按已确认稿实现——顶部两个知识库页签,下面是**一个**作业区。
//
@@ -260,6 +261,7 @@ export function jobKindText(kind?: string): string {
if (kind === 'sync') return '生产同步'
if (kind === 'restore') return '按版本恢复'
if (kind === 'baseline') return '建立目标基线'
if (kind === 'verify') return '恢复验证'
return kind ? kind : '—'
}
@@ -281,7 +283,9 @@ export function publishStateText(job?: LibraryJobRecord): string {
? '恢复进行中(目标在维护中)'
: job.kind === 'baseline'
? '建立基线进行中(只读捕获目标,不写内容)'
: '同步进行中(目标在维护中)'
: job.kind === 'verify'
? '恢复验证进行中(目标在维护中)'
: '同步进行中(目标在维护中)'
}
if (job.state === 'succeeded') return `${jobKindText(job.kind)}已完成 · ${stamp(job.finished_at ?? job.updated_at)}`
if (job.state === 'failed') return `${jobKindText(job.kind)}失败 · ${stamp(job.finished_at ?? job.updated_at)}`
@@ -718,6 +722,7 @@ function ProtectionCard({
targetSealed,
sync,
baseline,
scope,
onOpen,
}: {
production: LibraryOverview['production'] | null
@@ -730,6 +735,7 @@ function ProtectionCard({
targetSealed: boolean
sync: ReleaseSyncActions
baseline: ReleaseBaselineActions
scope: Scope
onOpen: () => void
}) {
const backupKnown = prebackup.state === 'known' && prebackup.version
@@ -798,6 +804,7 @@ function ProtectionCard({
<dt>恢复条件</dt>
<dd>{gate.reasons.length === 0 ? '已满足' : `缺 ${gate.reasons.length} 项`}</dd>
</dl>
<RestoreVerificationSection scope={scope} isAdmin={sync.canSign} />
{gate.reasons.length > 0 ? (
<ul className="rel-gate" aria-label="恢复与启动条件">
{gate.reasons.map((reason) => (
@@ -880,6 +887,7 @@ function ReadyBody({
targetSealed={Boolean(snapshot)}
sync={sync}
baseline={baseline}
scope={view.scope}
onOpen={onOpen}
/>
</div>
+103
View File
@@ -0,0 +1,103 @@
import { renderToStaticMarkup } from 'react-dom/server'
import { describe, expect, it } from 'vitest'
import { RestoreVerificationView } from './RestoreVerificationSection'
import type { LibraryVerificationView } from './restoreVerification'
const target = {
instance: 'weknora-test',
project: 'weknora',
internal_kb: 'a8e9c8ad-411c-4c53-8421-599d29e9b179',
external_kb: '2e980686-2233-4c4e-b5a6-8b0069477b8e',
index: 'weknora_test_chunks',
s3_bucket: 'dobot-weknora-test',
tenant_id: 10000,
database_configured: true,
}
const view = (overrides: Partial<LibraryVerificationView> = {}): LibraryVerificationView => ({
scope: 'internal',
target,
verified: false,
reason: '还没有对当前目标做过恢复验证',
latest: null,
history: [],
...overrides,
})
const render = (value: LibraryVerificationView | null, isAdmin = true, pending = false, error: string | null = null) =>
renderToStaticMarkup(
<RestoreVerificationView
view={value}
scope="internal"
isAdmin={isAdmin}
pending={pending}
error={error}
notice=""
onRun={() => undefined}
onReload={() => undefined}
/>
)
describe('RestoreVerificationView', () => {
it('没有证据时显示"还没有验证记录"并给出下一步,不显示已验证', () => {
const html = render(view())
expect(html).toContain('还没有验证记录')
expect(html).toContain('跑一次恢复验证')
expect(html).not.toContain('已验证(当前目标)')
})
it('管理员能看到发起按钮,工程师只看到证据与原因', () => {
expect(render(view(), true)).toContain('跑一次恢复验证')
const engineer = render(view(), false)
expect(engineer).not.toContain('跑一次恢复验证')
expect(engineer).toContain('仅管理员可发起')
})
it('通过后显示已验证、快照与完整目标', () => {
const html = render(
view({
verified: true,
reason: '',
latest: {
id: 'libverify-internal-job1',
scope: 'internal',
status: 'passed',
snapshot_id: '0f9b39a16738',
job_id: 'libverify-internal-1',
started_at: '2026-11-03T01:00:00Z',
finished_at: '2026-11-03T01:02:00Z',
},
})
)
expect(html).toContain('已验证(当前目标)')
expect(html).toContain('0f9b39a16738')
expect(html).toContain('a8e9c8ad-411c-4c53-8421-599d29e9b179')
expect(html).toContain('weknora_test_chunks')
})
it('失败时把失败原因写出来,按钮仍可重试', () => {
const html = render(
view({
latest: {
id: 'libverify-internal-job2',
scope: 'internal',
status: 'failed',
snapshot_id: 'snap-2',
job_id: 'libverify-internal-2',
failure: '恢复后内容仍与预备份不一致',
started_at: '2026-11-03T01:00:00Z',
finished_at: '2026-11-03T01:05:00Z',
},
})
)
expect(html).toContain('最近一次未通过')
expect(html).toContain('恢复后内容仍与预备份不一致')
expect(html).toContain('跑一次恢复验证')
})
it('投递被拒时显示后端逐条原因', () => {
const html = render(view(), true, false, '恢复验证被拒绝:生产写入闸口关闭')
expect(html).toContain('生产写入闸口关闭')
})
})
+140
View File
@@ -0,0 +1,140 @@
import { useCallback, useEffect, useRef, useState } from 'react'
import {
enqueueLibraryVerification,
fetchLibraryVerification,
verificationStatusText,
verificationTargetLines,
} from './restoreVerification'
import type { LibraryVerificationView } from './restoreVerification'
// 「恢复验证」面板:同步闸口认的"生产可恢复"证据只能由这里发起的一次真实演练产生。
//
// 为什么要有这个入口:以前只有 CLI(现为 internal/libraryverify 的薄封装)能跑演练,
// 页面只能看到一个 env 开关。运维在页面上看到"缺 1 项",却没有任何可点的下一步。
// 这里把"跑一次真实演练"变成正常流程:它会停写入者、写 canary、按预备份恢复,
// 全过程由 worker 执行并登记真实终态;页面只显示结果,不提供手填开关。
export interface RestoreVerificationViewProps {
view: LibraryVerificationView | null
scope: string
isAdmin: boolean
pending: boolean
error: string | null
notice: string
onRun: () => void
onReload: () => void
}
const stampText = (value: string): string => {
if (!value) return '—'
const parsed = new Date(value)
return Number.isNaN(parsed.getTime()) ? value : parsed.toLocaleString()
}
export function RestoreVerificationView(props: RestoreVerificationViewProps) {
const { view, scope, isAdmin, pending, error, notice, onRun, onReload } = props
const status = verificationStatusText(view)
const latest = view?.latest ?? null
const running = Boolean(view?.running)
const tone = view?.verified ? 'green' : latest?.status === 'failed' ? 'red' : 'gray'
return (
<section className="rel-verification" aria-label="恢复验证">
<header className="rel-between">
<h3>恢复验证(当前整库目标)</h3>
<span className={`rel-pill ${tone}`}>{status}</span>
</header>
{view ? (
<ul className="rel-target-lines" aria-label="恢复验证目标">
{verificationTargetLines(view.target, scope).map((line) => (
<li key={line}>{line}</li>
))}
</ul>
) : null}
<p className="rel-hint">{view?.reason || '还没有读到验证状态。'}</p>
{latest ? (
<p className="rel-hint">
最近一次:{latest.status === 'passed' ? '通过' : '未通过'} · 快照 {latest.snapshot_id.slice(0, 12) || '—'} ·{' '}
{stampText(latest.finished_at)} · 作业 {latest.job_id}
</p>
) : null}
{latest?.failure ? <p className="rel-warn">未通过原因:{latest.failure}</p> : null}
{error ? <p className="rel-warn">{error}</p> : null}
{notice ? <p className="rel-hint">{notice}</p> : null}
<div className="rel-drawer-actions">
{isAdmin ? (
<button type="button" className="rel-secondary" onClick={onRun} disabled={pending || running}>
{pending ? '投递中…' : running ? '验证执行中…' : '跑一次恢复验证(维护隔离)'}
</button>
) : (
<span className="rel-hint">恢复验证仅管理员可发起;工程师可以看到证据与原因。</span>
)}
<button type="button" className="rel-secondary" onClick={onReload} disabled={pending}>
刷新验证状态
</button>
</div>
<p className="rel-hint">
验证会停住目标写入者、写一个隔离 canary 证明校验有效、再按预备份恢复并逐类复核;
通过后证据按当前目标登记,换库/换索引/换桶后自动失效。
</p>
</section>
)
}
// 容器:挂载即读一次,之后每 5 秒刷新(验证作业在 worker 里跑,页面只读证据)。
export function RestoreVerificationSection({ scope, isAdmin }: { scope: string; isAdmin: boolean }) {
const [view, setView] = useState<LibraryVerificationView | null>(null)
const [pending, setPending] = useState(false)
const [error, setError] = useState<string | null>(null)
const [notice, setNotice] = useState('')
const mounted = useRef(true)
const reload = useCallback(
(signal?: AbortSignal) => {
fetchLibraryVerification(scope, signal)
.then((next) => {
if (mounted.current && next) setView(next)
})
.catch(() => undefined)
},
[scope]
)
useEffect(() => {
mounted.current = true
const controller = new AbortController()
reload(controller.signal)
const timer = setInterval(() => reload(controller.signal), 5000)
return () => {
mounted.current = false
controller.abort()
clearInterval(timer)
}
}, [reload])
const onRun = useCallback(() => {
setPending(true)
setError(null)
setNotice('')
enqueueLibraryVerification(scope)
.then((accepted) => {
setNotice(`已投递恢复验证作业 ${accepted.job_id};进度在作业进度里可见,完成后这里显示证据。`)
reload()
})
.catch((err: unknown) => setError(err instanceof Error ? err.message : '投递恢复验证失败'))
.finally(() => setPending(false))
}, [scope, reload])
return (
<RestoreVerificationView
view={view}
scope={scope}
isAdmin={isAdmin}
pending={pending}
error={error}
notice={notice}
onRun={onRun}
onReload={() => reload()}
/>
)
}
+2 -1
View File
@@ -332,7 +332,8 @@ describe('SystemSettingsView', () => {
// 发布目标(源库 → 目标库)是独立分区,与测试端收件库分开。
const target = view('production-bindings')
expect(target).toContain('id="settings-production-bindings"')
expect(target).toContain('新发布的对内 / 对外内容按这里的绑定写入生产 WeKnora 的对应知识库')
expect(target).toContain('整库发布目标')
expect(target).toContain('文档级绑定')
})
it('does not show healthy simulation when the settings data failed to load', () => {
const html = renderToStaticMarkup(
+3
View File
@@ -12,6 +12,8 @@ export interface BackupSchedule {
last_applied_summary: string
host_configured: boolean
host_target: string
// host_endpoint 是这条别名真实拨号的 host:port(来自挂载的 ssh 配置)。
host_endpoint: string
host_reachable: boolean
host_error: string
host_schedule_enabled: boolean
@@ -70,6 +72,7 @@ function scheduleProjection(item: Record<string, unknown>): BackupSchedule {
last_applied_summary: asString(item.last_applied_summary),
host_configured: item.host_configured === true,
host_target: asString(item.host_target),
host_endpoint: asString(item.host_endpoint),
host_reachable: item.host_reachable === true,
host_error: asString(item.host_error),
host_schedule_enabled: item.host_schedule_enabled === true,
+1 -1
View File
@@ -567,7 +567,7 @@ export interface LibraryStageRow {
export interface LibraryJobRecord {
id: string
scope: string
kind: 'seal' | 'sync' | 'restore' | 'baseline'
kind: 'seal' | 'sync' | 'restore' | 'baseline' | 'verify'
state: 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'
stage: string
request_digest: string
+34
View File
@@ -11,6 +11,22 @@ export interface ProductionBindings {
production_base_url: string
production_connected: boolean
production_message: string
// legacy_scope 标明这条记录属于旧文档级发布路径;整库发布不看它。
legacy_scope: string
// whole_target 是整库发布真正写入的目标(来自部署配置),只读。
whole_target: LibraryPublishTarget
}
export interface LibraryPublishTarget {
configured: boolean
source: string
tenant_id: number
internal_kb_id: string
external_kb_id: string
database: string
elastic_index: string
object_bucket: string
missing_reason: string
}
const record = (value: unknown): value is Record<string, unknown> =>
@@ -26,6 +42,24 @@ function projection(item: Record<string, unknown>): ProductionBindings {
production_base_url: typeof item.production_base_url === 'string' ? item.production_base_url : '',
production_connected: item.production_connected === true,
production_message: typeof item.production_message === 'string' ? item.production_message : '',
legacy_scope: typeof item.legacy_scope === 'string' ? item.legacy_scope : '',
whole_target: wholeTarget(item.whole_target),
}
}
// wholeTarget 只读投影:缺字段就说未配置,不拿可编辑的文档级绑定冒充整库目标。
function wholeTarget(value: unknown): LibraryPublishTarget {
const item = record(value) ? value : {}
return {
configured: item.configured === true,
source: typeof item.source === 'string' ? item.source : '',
tenant_id: typeof item.tenant_id === 'number' ? item.tenant_id : 0,
internal_kb_id: typeof item.internal_kb_id === 'string' ? item.internal_kb_id : '',
external_kb_id: typeof item.external_kb_id === 'string' ? item.external_kb_id : '',
database: typeof item.database === 'string' ? item.database : '',
elastic_index: typeof item.elastic_index === 'string' ? item.elastic_index : '',
object_bucket: typeof item.object_bucket === 'string' ? item.object_bucket : '',
missing_reason: typeof item.missing_reason === 'string' ? item.missing_reason : '',
}
}
+93
View File
@@ -0,0 +1,93 @@
import { describe, expect, it } from 'vitest'
import {
parseVerificationRecord,
parseVerificationView,
verificationStatusText,
verificationTargetLines,
} from './restoreVerification'
import type { LibraryVerificationView } from './restoreVerification'
const target = {
instance: 'weknora-test',
project: 'weknora',
internal_kb: 'a8e9c8ad-411c-4c53-8421-599d29e9b179',
external_kb: '2e980686-2233-4c4e-b5a6-8b0069477b8e',
index: 'weknora_test_chunks',
s3_bucket: 'dobot-weknora-test',
tenant_id: 10000,
database_configured: true,
}
const passed = {
id: 'libverify-internal-job1',
scope: 'internal',
status: 'passed',
snapshot_id: '0f9b39a16738',
job_id: 'libverify-internal-1',
started_at: '2026-11-03T01:00:00Z',
finished_at: '2026-11-03T01:02:00Z',
}
describe('restoreVerification parsing', () => {
it('只把后端明确 true 当作已验证', () => {
const view = parseVerificationView({ scope: 'internal', target, verified: 'true', reason: '', history: [] })
expect(view?.verified).toBe(false)
})
it('保留失败证据的失败原因', () => {
const record = parseVerificationRecord({ ...passed, status: 'failed', failure: '恢复后内容仍与预备份不一致' })
expect(record?.status).toBe('failed')
expect(record?.failure).toBe('恢复后内容仍与预备份不一致')
})
it('未知状态一律丢弃,不猜成通过', () => {
expect(parseVerificationRecord({ ...passed, status: 'running' })).toBeNull()
})
it('没有目标信息的响应视为无效', () => {
expect(parseVerificationView({ scope: 'internal', verified: true })).toBeNull()
})
})
describe('restoreVerification display', () => {
const base: LibraryVerificationView = {
scope: 'internal',
target,
verified: true,
reason: '',
latest: {
id: passed.id,
scope: 'internal',
status: 'passed',
snapshot_id: passed.snapshot_id,
job_id: passed.job_id,
started_at: passed.started_at,
finished_at: passed.finished_at,
},
history: [],
}
it('整库目标显示完整 KB ID 与索引/桶,不缩写成"2074 文档库"', () => {
const lines = verificationTargetLines(target, 'internal')
expect(lines.join(' | ')).toContain('a8e9c8ad-411c-4c53-8421-599d29e9b179')
expect(lines.join(' | ')).toContain('weknora_test_chunks')
expect(lines.join(' | ')).toContain('dobot-weknora-test')
})
it('对外 scope 显示对外目标', () => {
expect(verificationTargetLines(target, 'external').join(' | ')).toContain('2e980686-2233-4c4e-b5a6-8b0069477b8e')
})
it('状态文案区分已验证 / 最近失败 / 无记录', () => {
expect(verificationStatusText(base)).toBe('已验证(当前目标)')
expect(
verificationStatusText({
...base,
verified: false,
latest: { ...base.latest!, status: 'failed' },
})
).toBe('最近一次未通过')
expect(verificationStatusText({ ...base, verified: false, latest: null })).toBe('还没有验证记录')
})
})
+158
View File
@@ -0,0 +1,158 @@
// 恢复验证的页面数据层:读证据 + 投递真实演练。
//
// 关键约定:verified 只由后端证据回答(当前目标 + scope 的最近一次真实演练)。
// 页面不提供任何"我确认已验证"的开关——那正是旧实现的问题(一个可手填的 env)。
export type LibraryVerificationStatus = 'passed' | 'failed'
export interface LibraryVerificationRecord {
id: string
scope: string
status: LibraryVerificationStatus
snapshot_id: string
job_id: string
failure?: string
started_at: string
finished_at: string
}
export interface LibraryVerificationTarget {
instance: string
project: string
internal_kb: string
external_kb: string
index: string
s3_bucket: string
tenant_id: number
database_configured: boolean
}
export interface LibraryVerificationView {
scope: string
target: LibraryVerificationTarget
verified: boolean
reason: string
latest?: LibraryVerificationRecord | null
history: LibraryVerificationRecord[]
running?: boolean
job_id?: string
}
function record(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null
}
function text(value: unknown): string {
return typeof value === 'string' ? value : ''
}
function bool(value: unknown): boolean {
return value === true
}
export function parseVerificationTarget(value: unknown): LibraryVerificationTarget | null {
if (!record(value)) return null
return {
instance: text(value.instance),
project: text(value.project),
internal_kb: text(value.internal_kb),
external_kb: text(value.external_kb),
index: text(value.index),
s3_bucket: text(value.s3_bucket),
tenant_id: typeof value.tenant_id === 'number' ? value.tenant_id : 0,
database_configured: bool(value.database_configured),
}
}
export function parseVerificationRecord(value: unknown): LibraryVerificationRecord | null {
if (!record(value)) return null
const status = text(value.status)
if (status !== 'passed' && status !== 'failed') return null
return {
id: text(value.id),
scope: text(value.scope),
status,
snapshot_id: text(value.snapshot_id),
job_id: text(value.job_id),
failure: text(value.failure) || undefined,
started_at: text(value.started_at),
finished_at: text(value.finished_at),
}
}
export function parseVerificationView(value: unknown): LibraryVerificationView | null {
if (!record(value)) return null
const target = parseVerificationTarget(value.target)
if (!target) return null
const history = Array.isArray(value.history)
? value.history.map(parseVerificationRecord).filter((item): item is LibraryVerificationRecord => item !== null)
: []
const latest = parseVerificationRecord(value.latest) ?? null
return {
scope: text(value.scope),
target,
// 只有后端明确说 true 才算已验证:任何解析失败都退回"没有证据"。
verified: bool(value.verified),
reason: text(value.reason),
latest,
history,
running: bool(value.running),
job_id: text(value.job_id) || undefined,
}
}
export async function fetchLibraryVerification(
scope: string,
signal?: AbortSignal
): Promise<LibraryVerificationView | null> {
const response = await fetch(`/api/v1/library/verifications?scope=${encodeURIComponent(scope)}`, {
headers: { Accept: 'application/json' },
signal,
})
const value = (await response.json().catch(() => null)) as unknown
return parseVerificationView(value)
}
export interface LibraryVerificationAccepted {
job_id: string
scope: string
}
// 投递一次真实恢复验证。失败时把后端的逐条拒绝原因原样显示,
// 不把它包装成"稍后再试"——否则用户不知道是闸口、维护还是目标不可达。
export async function enqueueLibraryVerification(scope: string): Promise<LibraryVerificationAccepted> {
const response = await fetch('/api/v1/library/verifications', {
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) && 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) }
}
// 目标展示:整库目标必须显示完整 ID 与端点,避免"看着像 2074 文档库"这类误读。
export function verificationTargetLines(target: LibraryVerificationTarget, scope: string): string[] {
const kb = scope === 'internal' ? target.internal_kb : target.external_kb
return [
`实例 ${target.instance || '未配置'} · 项目 ${target.project || '未配置'}`,
`知识库 ${kb || '未配置'}`,
`索引 ${target.index || '未配置'} · 桶 ${target.s3_bucket || '未配置'}`,
`租户 ${target.tenant_id || '未配置'} · 数据库${target.database_configured ? '已配置' : '未配置'}`,
]
}
export function verificationStatusText(view: LibraryVerificationView | null): string {
if (!view) return '还没有读到验证状态'
if (view.verified) return '已验证(当前目标)'
if (view.latest) return view.latest.status === 'failed' ? '最近一次未通过' : '未通过'
return '还没有验证记录'
}