dcdc8d1ddd
全栈知识治理平台首次入库(P1-P10 + 发布链路模拟验证闭环): - 治理核心:源目录/变更集/人工审核/发布批次/发布执行(fail-closed 闸口) - 测试通道:WeKnora 测试 KB 上传/轮询/验收;poll 完成时写入 parser_generation/index_generation,修复 manual/seed 路径发布闸口永久拦截 - 发布适配器 v071(本地 source=测试角色 / 云端 target=生产角色 模拟验证通过): * ES 导出/导入 mapping 自适应(.keyword 子字段、可选 tenant_id) * OSS locator 支持嵌套 scheme;chunks.seq_id 由目标序列分配 * bundle 归档同身份重试原子替换;verifier 按 bundle chunk_type 计数 * 回滚 job payload 支持 prior_execution_id(strict 解码) - 三通道发布+回滚演练实测:publish 4/4 verified,检索命中, rollback 4/4 rolled_back,目标端 PG is_enabled=false、ES is_enabled=false - 前端 A·Data-console 风格全站统一,120 用例通过 - 门禁:go vet / go test 全包通过,gofmt 干净
208 lines
10 KiB
Markdown
208 lines
10 KiB
Markdown
# 知识同步治理平台
|
||
|
||
独立的知识治理控制平面。当前包含P1持久任务队列、P2统一来源与PP历史接管、P3本地/测试WeKnora编排验收、P4来源只读扫描、P5知识工程师审核与封批门禁、默认关闭的P6三通道生产发布与回滚Worker,以及P7持久快照ChangeSet、真实运行监控和每50项一批的发布进度。
|
||
|
||
## 安全边界
|
||
|
||
- 本工程不修改 WeKnora、PP、AList、钉钉或 DobotAI 源码。
|
||
- PP接管与核验只读取指定的本地账本、manifest和测试WeKnora;不请求PP写接口,不修改来源文件。
|
||
- 普通Worker领取演示任务、`test.upload/test.poll/test.validate`和显式启用的`source.scan.pp`;只有普通Worker可挂载测试WeKnora Key和只读PP快照。
|
||
- Release Worker默认`RELEASE_WORKER_ENABLED=false`,禁用时不读取release config/生产secret,不连接生产数据面或治理数据库。
|
||
- P5封批只生成治理侧`sealed`记录,不创建生产发布Job;5条真实候选仍为待人工审核。
|
||
- P6生产请求另受`PRODUCTION_RELEASE_REQUESTS_ENABLED=false`保护;开启时还必须有服务端固定actor和0600 Bearer token文件。当前未授权、未配置、未发布生产。
|
||
- 凭据文件位于`secrets/`且被Git忽略;仓库只保留示例文件。
|
||
|
||
## 目录
|
||
|
||
```text
|
||
cmd/api HTTP API
|
||
cmd/worker 普通任务Worker
|
||
cmd/release-worker 默认关闭的发布Worker
|
||
cmd/pp-ledger-import PP历史账本一次性导入工具
|
||
internal/jobs 任务模型、租约和Worker循环
|
||
internal/governance 统一来源治理领域模型
|
||
internal/platform PostgreSQL仓库与Migration
|
||
internal/releasebundle v0.7.1发布bundle契约与摘要
|
||
internal/releaseadapter v0.7.1 PostgreSQL/ES/S3 Sidecar
|
||
internal/httpapi HTTP路由
|
||
web React TypeScript状态页
|
||
deploy Nginx配置
|
||
docs 验收计划
|
||
```
|
||
|
||
## P2.1来源数据底座
|
||
|
||
Migration 2创建五张空表:
|
||
|
||
```text
|
||
source_connections 来源连接配置,只保存secret引用名
|
||
source_items 来源内稳定对象身份与变化状态
|
||
content_objects 按完整SHA-256唯一的内容对象
|
||
source_item_versions 来源对象版本与内容对象关联
|
||
test_publications 测试知识库导入、处理、检索状态
|
||
```
|
||
|
||
`source_change`、`ingest_state`、`processing_state`和`retrieval_state`相互独立。只有同一来源连接内的`stable_external_id`唯一;只有完整小写SHA-256相同才能共享内容对象。
|
||
|
||
P2.1不会自动创建来源连接、读取PP账本或上传文档。完整验收步骤见`docs/P2_SOURCE_FOUNDATION_ACCEPTANCE.md`。
|
||
|
||
## P2.2 PP历史账本接管
|
||
|
||
一次性工具将PP append-only账本折叠为当前终态:
|
||
|
||
```text
|
||
1093 条历史事件
|
||
→ 559 个来源对象和版本
|
||
→ 530 个SHA内容对象
|
||
→ 530 条历史测试发布
|
||
→ 29 个content_alias共享canonical内容和Knowledge ID
|
||
```
|
||
|
||
75条旧`completed`记录缺少SHA时,只允许从locator hash匹配的本地manifest恢复,并重新校验文件大小和实际SHA-256。单文件继续遵守旧连接器50MiB上限。连接器默认关闭,历史发布的`retrieval_state`保持`unpublished`,等待未来对目标WeKnora逐条只读核验。
|
||
|
||
工具只执行幂等INSERT,不执行UPDATE或DELETE。完整验收步骤见`docs/P2_PP_LEDGER_TAKEOVER_ACCEPTANCE.md`。
|
||
|
||
## P2.3 PP完整清单与知识资产页
|
||
|
||
P2.3将manifest中未进入旧账本的54个超限来源纳入治理视图:
|
||
|
||
```text
|
||
559 个历史终态 + 54 个over_limit阻断项 = 613 个来源对象
|
||
530 个内容对象
|
||
613 个来源版本
|
||
530 条历史测试发布
|
||
历史已同步内容计划重新上传数 = 0
|
||
```
|
||
|
||
超限版本没有虚假ContentObject或TestPublication,保持`content_state=over_limit`和阻断状态。`GET /api/v1/source-items`提供只读分页清单,支持`state=completed|content_alias|over_limit`、`limit`和`offset`;响应不包含来源URL、URI哈希、raw记录或Knowledge ID。Web“知识资产”模块读取该真实API。完整验收见`docs/P2_PP_INVENTORY_ACCEPTANCE.md`。
|
||
|
||
## P3 WeKnora测试编排
|
||
|
||
普通Worker从只读Spool流式上传到测试WeKnora,持久保存远端身份,按单调`poll_sequence`轮询,并在完成后执行Knowledge/Chunk验收。API和Web只返回安全投影;人工重试只允许失败或停滞且仍有已验证制品的Publication。530条PP历史Knowledge已在测试服务器完成在线只读核验,没有重新上传。
|
||
|
||
本地、测试服务器、失败恢复、Worker重启和浏览器验收见`docs/P3_LOCAL_AND_CROSS_ENV_ACCEPTANCE.md`。
|
||
|
||
## P4.1 来源连接只读工作台
|
||
|
||
`GET /api/v1/source-connections`返回来源ID、类型、名称、启用状态、是否配置调度、健康枚举、对象数和更新时间。查询与响应均不包含`base_url`、`secret_ref`或原始健康错误正文。Web“来源管理”模块展示真实PostgreSQL数据,保留左侧导航和顶部多标签。
|
||
|
||
P4.1完整验收见`docs/P41_SOURCE_CONNECTIONS_ACCEPTANCE.md`。
|
||
|
||
## P4.2 PP只读扫描与变化入账
|
||
|
||
普通Worker在`PP_SCAN_ENABLED=true`且三个安全路径完整时注册`source.scan.pp` Handler。Compose仅给普通Worker只读挂载PP数据目录;API、Web和Release Worker均不挂载。Scanner拒绝越界、软链接、非普通文件和不完整manifest;54个历史`over_limit`项允许其制品未下载,但仍保持阻断。
|
||
|
||
Migration 5新增`source_scans`和`source_scan_changes`。触发Scan与创建Job原子执行,每个连接最多一个活动Scan;完成时聚合、变化与来源健康原子写入;失败只保存固定错误码。安全API支持触发、扫描历史和连接作用域详情,Web展示真实聚合与变化记录,不返回来源ID/revision/SHA/路径/URL或凭据。
|
||
|
||
真实PP快照只读扫描结果:
|
||
|
||
```text
|
||
observed=613
|
||
unchanged=559
|
||
over_limit=54
|
||
added=0
|
||
updated=0
|
||
missing=0
|
||
planned_uploads=0
|
||
```
|
||
|
||
过期`running`租约已由常驻Worker真实重领并以`attempt=2`完成;并发第二次触发返回`409`。完整迁移、备份、恢复、API和Firefox验收见`docs/P42_SOURCE_SCAN_ACCEPTANCE.md`。
|
||
|
||
## P5 知识工程师审核与封批
|
||
|
||
Migration 6新增追加式`publication_reviews`、`release_batches`和`release_batch_items`。审核决定绑定最新Acceptance run与Publication时间戳;批准仅允许完整结构门禁通过的候选,`retrieval_hit=manual_required`保持人工判断。创建draft和sealed封批均原子验证整个项目集合,任一项目失效则整批拒绝。
|
||
|
||
“发布管理”模块展示真实审核候选、固定门禁、决定可见性、草稿批次和封批记录,并明确显示“生产门禁保持关闭”“Release Worker保持关闭”“尚未发布”。当前535条Publication中,530条无逐条Acceptance的PP legacy不自动进入人工队列;5条manual合成验收项显示为ready/pending,持久库没有代替知识工程师创建Review或Batch。
|
||
|
||
P5 Store与HTTP写链路已在disposable PostgreSQL和临时API中验证`pending→approved→draft→sealed`,完成后临时数据库与临时密钥文件均清理;持久环境只应用空Migration 6。完整验收见`docs/P5_REVIEW_AND_SEAL_ACCEPTANCE.md`。
|
||
|
||
## P6 生产发布Worker与回滚
|
||
|
||
Migration 7新增`release_executions`与`release_item_executions`。只有受保护的生产授权请求才能把P5 sealed batch原子转换为`release.publish` Job;rollback只允许针对完整成功的publish execution。终态失败可在同一Bearer门禁下重排,仅重置failed items并重新验证sealed snapshot。API和Release Worker使用两个独立默认关闭的门禁,UI只展示执行审计,不提供一键生产授权按钮。
|
||
|
||
Release Worker按Knowledge Base精确路由,固定WeKnora `v0.7.1 / migration 74 / elasticsearch_v8 / 1024维`契约;同一release package协调复制以下内容且不触发生产解析/Embedding:
|
||
|
||
```text
|
||
PostgreSQL: knowledges/chunks/knowledge_tags/relations/resources/bindings
|
||
对象存储: referenced assets,staging→SHA校验→相同relative key
|
||
Elasticsearch: chunk text+vectors,先upsert新文档再清理同Knowledge旧_id
|
||
```
|
||
|
||
每个release revision写入0700目录中的0600 bundle并重验整包SHA。失败恢复旧bundle;首次发布无旧revision时禁用Knowledge/Chunk/ES,不删除行、文档或对象。生产WeKnora官方API最终验证Knowledge、Chunk数和knowledge-scoped检索。
|
||
|
||
本地真实验收使用完整v0.7.1 75个migration的source/target PostgreSQL、真实MinIO、状态化ES协议服务,已通过`publish v1 → publish v2 → rollback v1`以及PG disable、S3 Open/Put/Copy、Worker受限配置装配。模板见`config/release.v071.example.json`,完整边界与结果见`docs/P6_RELEASE_WORKER_ACCEPTANCE.md`。
|
||
|
||
当前生产状态保持:
|
||
|
||
```text
|
||
PRODUCTION_RELEASE_REQUESTS_ENABLED=false
|
||
RELEASE_WORKER_ENABLED=false
|
||
release executions/items/jobs=0/0/0
|
||
```
|
||
|
||
## 本地验证
|
||
|
||
要求Go 1.26、Node.js 22和npm。
|
||
|
||
```bash
|
||
make test
|
||
make vet
|
||
make build
|
||
make web-test
|
||
make web-typecheck
|
||
make web-build
|
||
```
|
||
|
||
## Docker Compose(由操作者执行)
|
||
|
||
先创建仅限本机的密钥文件:
|
||
|
||
```bash
|
||
cp secrets/postgres_password.example secrets/postgres_password
|
||
cp secrets/pgpass.example secrets/pgpass
|
||
# 将两个文件中的CHANGE_ME_LOCAL_ONLY替换为同一随机本地密码
|
||
chmod 600 secrets/postgres_password secrets/pgpass
|
||
docker compose up --build -d
|
||
```
|
||
|
||
Compose默认让三个Go进程以`1000:1000`运行,以读取宿主机Owner为1000且权限为600的密钥文件。若操作者UID/GID不同,启动前设置`APP_UID`和`APP_GID`为密钥文件Owner。
|
||
|
||
访问:
|
||
|
||
- 状态页:`http://127.0.0.1:8088/`
|
||
- 同源健康检查:`http://127.0.0.1:8088/health`
|
||
|
||
停止时保留数据库:
|
||
|
||
```bash
|
||
docker compose down
|
||
```
|
||
|
||
不要执行`docker compose down -v`,除非明确决定删除本地数据库数据。
|
||
|
||
## P1 API
|
||
|
||
创建普通演示任务:
|
||
|
||
```bash
|
||
curl -fsS -X POST http://127.0.0.1:8088/api/v1/jobs \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"type":"demo","payload":{},"idempotency_key":"demo:001"}'
|
||
```
|
||
|
||
创建可用于租约恢复验收的30秒任务:
|
||
|
||
```bash
|
||
curl -fsS -X POST http://127.0.0.1:8088/api/v1/jobs \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"type":"demo.sleep","payload":{"sleep_ms":30000},"idempotency_key":"demo:sleep:001"}'
|
||
```
|
||
|
||
查看最近任务:
|
||
|
||
```bash
|
||
curl -fsS 'http://127.0.0.1:8088/api/v1/jobs?limit=50'
|
||
```
|
||
|
||
完整人工步骤见`docs/P1_ACCEPTANCE_TEST_PLAN.md`。
|