16 Commits

Author	SHA1	Message	Date
姚章浩	9300865d23	fix(library): 搬运复用前复验字节、回传游标分页与发布队列事务交接 ... 父独立审查退回的四个 finding，逐项修在本包内，不改架构。 1 复用路径没复验字节：remoteEvidence 只读清单+摘要就宣布可用。现在新增 libraryctl snapshot-verify（整版逐部件重算）并在复用前调用；blob 缺失/篡改必须 在入发布队列之前失败。新增真实 local 跨进程用例：清单不动、删 blob / 改 blob 后 再 Push 必须拒绝。 2 回传枚举被固定 LIMIT 50 截断：LibraryJobSnapshots 只取成功作业且按摘要字典序。 改为 LibrarySnapshotCandidates：合并 library_versions、library_jobs.snapshot_id、 library_jobs.target_snapshot_id 三处引用，按 (created_at, snapshot_id) 游标分页； 回传循环翻页到不足一页为止。失败/待恢复作业留下的预备份、第 51 条以后、历史恢复 输入快照都能被枚举。另修"本地只有清单、blob 已损坏就永远跳过"：改用整版 Load 判定， 并给 Unpack 增加显式 RepairCorruptBlobs（只在权威云端读回时开启）。 3 身份映射错误：搬运拿目标 tenant/KB 去核对封存快照，而封存清单写的是**源**身份 （云测试验收目标 a8e9c8ad/2e980686 与源 KB 必然不同）。现在 expectedSnapshotIdentity 按版本台账判定：test_sealed → 用部署注入的源绑定（LIBRARY_SOURCE_TENANT_ID / LIBRARY_SOURCE_KB_*）；预备份/生效/恢复版本 → 用目标绑定；没有登记或两类冲突一律拒绝。 身份永远来自独立绑定与台账，不接受包自证。 4 两步入队有竞态：Enqueue 成功后云执行器可能立刻领取并开始维护，Attach 失败却把作业 标失败并声称"未维护"。改为 EnqueueAndAttachLibraryJob 单事务（锁行 + 插入 + 关联 + 状态守卫），要么都成功要么都不发生；重复执行幂等，已关联别的队列作业则拒绝。 另修终态重放：AdvanceLibraryJob 无状态守卫，迟到的失败出口会把已成功作业改写； 新增 AdvanceLibraryJobIfActive（仅 pending/running 可推进），拿不到就明确记录"未覆盖"。 测试：libraryhandoff 用例覆盖跨租户/错误 scope/清单在而字节坏/本地损坏自愈； 隔离 fixture 库覆盖"校验通过才入队、失败不入队"、>50 条分页与失败作业预备份、 幂等重放不重复投递、迟到失败不改写终态。 未部署、未推送、未构建镜像；真实跨主机 SSH 链路仍未验证。	2026-10-30 19:10:02 +08:00
姚章浩	6400fd1bbe	feat(library): 快照搬运先于维护、双向校验与云端版本回传 ... 为什么改：云端 release-executor 与目标同机后，本机封存的快照必须"先到、先验证" 才允许开维护窗口。此前只有 pack/unpack 两条人工命令：UI 点发布时执行器读到的是 本机归档路径，云端根本没有这份快照，作业只能在装配阶段失败；而预备份落在云端， 本机页面也读不到。用户已批准补齐这条链路。 搬运（新包 internal/libraryhandoff）：本机 Load 逐 blob 重算 → Pack → SSH 流式写入 云端暂存 → 原子改名 → 云端 snapshot-unpack 再逐 blob 校验 → 读回版本清单摘要自证 → scope/tenant/知识库身份与治理库作业一致。只有全部通过才投递 library.sync|restore， 失败时发布作业根本不存在（目标不进维护、不写知识）。远端命令是固定 argv，容器名与 路径只来自部署配置；同 ID 异内容拒绝；同一快照本机 flock 串行化；暂存 bundle 用后即删， 归档本体永不自动清理。 回传：capture 角色按已成功作业的 snapshot_id 扫描，把本机缺失的云端快照 Fetch 回来 （云端 pack → SSH 流回 → 本机 Unpack 逐 blob 校验）。回传成功后 API/页面既有的列表、 详情、差异、存储与历史恢复路径读到的就是真实字节；失败则版本不出现在本机，不会被误报成可恢复。 角色：搬运与回传只注册在 capture；若接线到 full（同时消费发布作业）启动即失败， 避免与云端执行器抢同一批作业。release-executor 仍不拥有治理库 DDL，也不消费 QA/邮件/来源扫描。 验证：internal/libraryhandoff 全绿（跨进程 push/fetch、身份不符拒绝、幂等复用、 并发串行、篡改与未知快照不落版本、路径穿越拒绝、远端错误不当作"没有"）； cmd/worker 在隔离 fixture 库（独立测试 PG）上验证"校验通过才入队发布、失败不入队"； httpapi 队列决策单测；相关包 go test 全绿；go vet 全仓通过。 未部署、未推送、未构建镜像：云端接线与验收仍由父执行。真实云链路（含 SSH 通道） 本轮没有云侧写操作，只有本机跨进程与隔离 fixture 证据。	2026-10-30 18:58:34 +08:00
姚章浩	e6472b0ec6	feat(library): 云测试发布目标接入的角色分离、快照搬运与图谱门禁 ... 为什么改：发布执行链是"与目标同机"假设写死的（本机 docker.sock、本机 drain.json、 本机 Redis/PG），把目标换成云测试不能只改展示 URL；直接搬整套 worker 又会抢走 本机封存/QA/周报队列并按本机配置写错目标。所以先把"谁消费哪段队列"变成显式角色， 再补齐跨主机搬运与目标侧门禁。 角色（LIBRARY_WORKER_ROLE=full/release-executor/capture）不只影响 handler 列表， 还决定是否拥有 DDL（release-executor 只读校验迁移版本，落后即拒绝启动）、 收拾哪些 library_jobs.kind、是否跑 release 接管扫描、是否起 scheduler/QA/周报/探测。 capture 保留本机原有全部业务；release-executor 只挂 sync/restore/recover/baseline。 快照跨主机：新增内容寻址的 bundle（版本清单先落、blob 按 sha256 命名、清单最后 Link 作提交点），pack/unpack 幂等且拒绝覆盖与同名不同内容；执行器使用前仍逐 blob 重算 sha256，因此传输不可变有两道证据。 目标侧门禁：目标知识库 graph_enabled=true 时拒绝发布（发布只写 PG/ES/OSS，不写 Neo4j；未知也拒绝），只读检测、不改目标配置、不做图谱迁移。 云端入口：新增 drain 感知的 ingress 闸门（建连超时与读超时分离，半关闭单向传播， SIGTERM 排空后写 drain.json 并 exit 0/2）、compose 叠加片段（app 不再发布端口、 frontend 与 adapter 的入口收敛到闸门、指向真实网络 weknora-test-v071-network）、 执行器启动脚本与治理 PG 反向隧道脚本（默认 unix socket，不占 TCP）。 验证：deploy/cloud-test/test_gate.py 13 项全 PASS（含 12 秒静默流、半关闭、2MiB 完整、 排空 exit 0/active_at_close=1、排空超时 exit 2、上游不可达不挂住）；go test 相关包全绿； scripts/ci_checks.py 16 项全部 success（EXIT=0，1241 用例通过/0 失败/191 已声明可选集成跳过）； 云测试只读预检 17 项 / 6 FAIL，FAIL 项即当前部署缺口（无闸门、app 仍发布端口、 adapter 与 frontend 仍直连 app、云端归档根未建），未部署、未改云端任何状态。	2026-10-30 18:38:38 +08:00
姚章浩	cfad003499	fix(release-worker): 启动失败带端点与脱敏原因 ... 正式 release-worker 崩溃重启时日志只有一句 connect release target database， 主机名、库名和底层原因都不在里面。现在错误里带 host:port/db、路由标识与原因。 端点去口令不等于整条日志安全：pgx 的解析错误可能原样回显连接串。新增 internal/pgdsn.Redact（按已知口令精确替换 + 按 URL/keyword 形状兜底）， 错误保留 Unwrap 以便 errors.Is/As，技术原因不丢。cmd/worker 里只留库名的旧实现 换成同一个包，避免两份脱敏逻辑。libraryctl 用法补上 dead-letters。	2026-10-29 13:01:46 +08:00
姚章浩	c2402947a9	feat(library): 死信按精确指纹解除，保留上游记录 ... 上游 task_dead_letters 没有解决标记，purge/DELETE 会销毁"失败过"的唯一证据。 治理侧新增解除记录（迁移 073）：绑定实时行逐字节指纹、重放引用、源侧观测摘要与 操作人；行被改过、重放后又出现新死信、源侧未结清都不命中，封存照旧阻断。 指纹先压紧空白再摘要，避免 PG to_jsonb::text 与 json.Marshal 的空白差异。 试过：go test ./internal/{librarydeadletter,libraryagent,httpapi,releaseadapter/v071, platform/postgres}，make verify 15 项全绿。	2026-10-29 06:55:13 +08:00
姚章浩	4d6ecda310	feat(libraryctl): 源对象存储端点可按宿主机地址覆盖 ... 容器 env 里的 MINIO_ENDPOINT 往往是服务名（langfuse-minio:9000），封存跑在宿主机上 解析不到，真实封存报 read library resource 并整体失败。 新增 -source-s3-endpoint：只换访问入口，桶与对象键不变；缺 scheme 直接拒绝； status 会打印实际使用的 endpoint。 试过：make verify 15 项全绿；新增覆盖用例（生效 + 拒绝无 scheme）。	2026-10-29 06:09:56 +08:00
姚章浩	11c52ad81b	fix(libraryctl): 封存窗口接上实例级入口闸门与后台静默 ... 库级窗口永远拿不到在途排空证据：被代理的 WeKnora 收到 SIGTERM 就 exit(1)， 写者退出码不能当作请求已排空。capture/recover 改由 librarymaintenance.Manager 装配入口闸门、后台静默检查、目标指纹与入口探针（与发布链路同一套实现）， 排空证据来自闸门 drain 记录；缺 LIBRARY_TARGET_* 时在开窗口前拒绝并点名。 维护接线解析收敛到 internal/librarymaintenance/env.go，agent 与 worker 讲同一组 变量名；agent 启动如实打印接线状态；安装脚本强制 0600 agent.env。 试过：make verify 15 项全绿；新增 7 个用例（接线解析/身份绑定/缺闸门拒绝）。	2026-10-29 05:48:38 +08:00
姚章浩	1faf5137ea	fix(libraryctl): 用完整容器 ID 判定写入者归属 ... `docker ps -q` 默认输出 12 位短 ID，与 declared 里的 64 位 ID 永不相等， 结果连已声明的写入者都被判成"未声明的并发写入者"，封存永远开不了窗。 改用 --no-trunc 并按前缀双向匹配。	2026-10-29 05:02:10 +08:00
姚章浩	fd71ea349e	fix(libraryctl): 同镜像不等于同一个写入者 ... 共享业务栈与专用验收实例共用同一个 WeKnora 镜像，原来只按镜像判"未声明写入者"， 任何一台开着共享栈的机器都永远开不了窗。判据改为：同项目或无项目标签即冲突； 另一个项目只有数据库/队列目标与源相同才算冲突。单测覆盖六种组合。	2026-10-29 05:01:22 +08:00
姚章浩	906c282986	fix(libraryctl): 捕获/预检也走同一份 scope 映射 ... 上一提交只改了 status；capture/preflight 仍直接读 routing bindings， 所以 CLI 封存的还是 bindings 里的库，而不是 API 的目标——契约读取直接失败。	2026-10-29 04:59:57 +08:00
姚章浩	23cc6c0afe	fix(libraryctl): 支持 MinIO 源，并与 API 共用同一份 scope 映射 ... 为什么：专用验收实例用 S3 兼容的 MinIO，而 CLI 的源发现只认 oss 环境变量， `STORAGE_TYPE=minio` 直接失败；同时 CLI 只读 routing bindings，API 读 LIBRARY_PRODUCTION_KB_*，两边指向不同知识库时，"封存的是哪个库"就说不清。 怎么改：新增 objectStoreFromSourceEnv（oss/minio，端点/桶缺失即报错，不退回默认值）， scopeBindings 让环境变量优先、bindings 兜底。单测覆盖 minio http/https、oss 与未知类型。	2026-10-29 04:58:45 +08:00
姚章浩	3643e9bf82	fix(library): 维护收尾必须按预备份恢复并校验 ... 删掉会自己开入口、只看服务健康的 FinalizeAfterOperatorRecovery。 新的 RecoverWindow 绑定原作业/目标指纹/持久化预备份，在维护关闭下 执行恢复与逐类校验，通过才恢复服务与入口；失败继续维护。 预备份身份与内容风险在第一笔写入前一起落盘；后台任务必须静默后才停写者； 写入者发布端口即拒绝开窗口；维护占用改为按实例互斥（000072）。	2026-10-29 00:50:32 +08:00
姚章浩	962bed8f53	feat(library): 人工恢复后按证据收尾维护窗口 ... 回滚失败会按设计保持维护，但此前没有任何"人工确认后收尾"的路径： journal 一直非终态，之后所有窗口都会被拦住。新增 libraryctl finalize： 不启动服务、不释放治理占用，只核对原本在跑的服务与入口是否真的在服务， 通过才把 journal 标成 operator_recovered。	2026-10-28 23:42:28 +08:00
姚章浩	bb64c32654	feat(release): 发布管理整库视图 + R4/R5/R6/R7 修复 ... - R4：封存子进程 SIGTERM 宽限停、libraryctl 信号转 ctx；失败/超时后 agent 再做 有界 recover，恢复失败即降级阻断封存并给出原因；启动先恢复、关闭等恢复完成 - R5：封存闸口以已存 payload 为准，同作业号换范围 409 且不入新队；重放回显真实状态 - R6：作业列表按类型查询（ListByType），不再先取全局再过滤 - R7：根目录 libraryagent 二进制移出版本库，保留运行产物并精确忽略 - UI：发布管理只保留对内/对外两目标，整合快照/完整性/作业/存储；链路未接线项禁用 并标原因；整库版本独立导航并入；文档级旧流程折叠保留	2026-10-28 12:28:04 +08:00
姚章浩	c5e033dd0e	fix(library): 幂等重放、跨版本去重用量与契约复核 ... - 同作业号重跑读持久日志+已封存清单按首次请求重放（source_read=false, writers_stopped=false），换范围/绑定库或清单校验失败即拒绝 - 归档用量按跨版本去重统计内容字节，清单/未引用 blob/实际分配单列， 不再用各版本 unique 之和冒充归档占用 - 冻结窗口内复核来源契约，不一致即中止；拒绝组外同镜像运行容器 - 补齐整库只读接口的 OpenAPI 契约 - 按用户确认取消 A06：文档/页面/接口不再把效果测试列为封版门槛	2026-10-28 12:01:09 +08:00
姚章浩	045fc44f0e	feat(library): 接通整库封存真实入口与只读版本页 ... - 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 删除语义重算、 生产预备份/恢复演练/双闸/同步协调仍未完成。	2026-10-28 11:39:50 +08:00