Files
knowledge-governance/README.md
T
狐友 GXXP & Miku ad02e8bb9c
build / build (push) Successful in 1m43s
feat(settings): 页面录入测试/生产 WeKnora 连接与密钥并收敛可达性判定
连接(地址 + 写-only 密钥)从文件引用搬进治理库:AES-GCM 密文 + 独立 0600 主密钥,
页面与接口只回显尾 4 位;测试连接真实列库并区分 地址不可达/密钥无效/无权限/成功,
换地址或换密钥必须测通才能保存(迁移 000083)。

可达性判定收敛为 weknora.HTTPAllowed,客户端与监控探活共用;新增
WEKNORA_ALLOW_PRIVATE_HTTP 只放行 RFC1918/回环/链路本地。生产绑定只保留下拉,
保存后回报冻结/未冻结条数,已冻结目标不被改写。
2026-11-22 15:18:34 +08:00

175 lines
13 KiB
Markdown

# 知识治理平台
面向企业多数据源的知识同步、生命周期治理与持续运营平台。
企业知识分散在钉钉、文件目录与业务资料门户中,内容会不断新增、更新和失效。平台连接这些来源与 WeKnora 知识底座,组织资料发现、取件、处理、验收、发布和下架,让知识不只是被导入一次,而是能够持续维护、追踪和治理。
**同步是入口,知识库治理是核心,持续运营是目标。**
## 平台解决什么问题
- **资料分散**:统一查看来源与目录,按范围选择、标注和获取内容。
- **更新难追踪**:通过来源身份、内容摘要、版本、快照与变更集记录变化。
- **处理不透明**:查看任务和解析状态,定位失败、停滞和需要人工处理的项目。
- **知识边界不清**:区分对内、对外和禁止导入,绑定相应测试与生产知识库。
- **上线不可控**:先处理与验收,再按审核策略和生产门禁组织发布。
- **失效难治理**:识别需下架内容,提供移除、失败重排与发布回滚等处理机制。
自动同步不等于无条件自动发布。不同来源的扫描、取件、处理和调度能力存在差异;生产变更仍受配置、权限与授权约束。
## 在 DobotAI 体系中的位置
```text
业务资料来源:钉钉 / AList / PP(资料门户)
↓
知识治理平台:发现与同步 → 状态跟踪 → 验收与治理 → 发布与维护
↓
WeKnora:文档处理、知识组织、索引与检索
↓
Knowledge Adapter / DobotAI 网关
↓
钉钉问答 / 软件内 AI 助理 / Wiki 问答等业务入口
```
本仓库负责知识治理流程与控制,不重复建设问答应用或检索引擎,也不修改 WeKnora 官方源码。Knowledge Adapter、DobotAI 网关及业务入口属于关联系统,不由本项目部署。
## 核心能力与当前边界
下表描述仓库已有实现及文档记录的能力,**不代表任一部署环境已启用所有功能**。现场接线、运行开关与验收结果以对应环境为准。
| 能力 | 已有支持 | 边界 |
| --- | --- | --- |
| 来源与目录管理 | 来源连接、目录浏览、范围选择、对内/对外/禁止导入策略 | 标注是治理意图,不代表已取件、入库或发布 |
| 多源资料获取 | 钉钉取件、AList 来源接入、PP 清单与历史账本接管 | 格式、凭据、目录及调度限制不同,不承诺所有来源全自动同步 |
| 变化与资产管理 | 稳定来源身份、内容摘要去重、来源版本、快照与变更集 | 来源变化与目标知识库处理状态分别记录 |
| 测试处理与验收 | 后台上传、轮询、知识与切片验收、失败恢复 | 解析和索引由对接的知识底座完成;部分检索判断仍需人工 |
| 解析与任务监控 | 处理中、失败/死信、需下架、知识库差异及处理进度视图 | 指标、动作与实际覆盖程度见验收清单,不等于完整告警平台 |
| 审核与发布 | 可配置自动审核策略、人工审核、批次锁定、生产授权与结果追踪 | 对内自动审核默认策略与对外人工控制详见操作流程;锁定不等于发布 |
| 回滚与备份 | 发布回滚、目标库快照门禁、备份配置及恢复工具 | 依赖专用接线、权限和恢复验证,不能仅凭页面存在判定可用 |
| 权限与审计 | 管理员、文档工程师、只读角色与操作记录 | 不等于已实现所有来源到问答端的文档级授权 |
### 数据源支持
| 来源 | 当前接入方式 | 参考文档 |
| --- | --- | --- |
| 钉钉 | 知识库目录发现与取件;优先 dws,按错误类型决定是否回落兼容路径 | [钉钉取件](docs/DINGTALK_DWS_FETCHER.md) |
| AList | 来源目录与资料获取,依赖指定连接和凭据 | [用户操作流程](docs/OPERATIONS_RUNBOOK.md) |
| PP(资料门户) | 本地清单、历史账本接管与只读扫描 | [历史接管](docs/P2_PP_LEDGER_TAKEOVER_ACCEPTANCE.md)、[来源扫描](docs/P42_SOURCE_SCAN_ACCEPTANCE.md) |
IT、行政等是待扩展的业务资料范围,不是已经完成的新连接器。接入敏感资料前,需要先确认 Owner、有效版本、可见范围与知识库路由。
## 工作流程
1. **配置来源与知识库绑定**:确认凭据、可见范围和目标库。
2. **发现、标注与取件**:按目录或文件选择范围,记录资料身份和变化。
3. **处理与验收**:进入测试知识库,跟踪上传、解析、索引及验收结果。
4. **审核与组批**:应用审核策略;建立并锁定发布清单,保留可追踪快照。
5. **授权发布**:核验备份与发布门禁,再执行目标知识库变更并读回验证。
6. **持续维护**:跟踪后续更新、失败、失效与需下架内容,按流程重排、移除或回滚。
具体操作、确认语句和异常处理见 [操作 Runbook](docs/OPERATIONS_RUNBOOK.md);已实测、待验收和已知限制见 [用户流程验收清单](docs/USER_FLOWS_ACCEPTANCE.md)。
## 访问与部署
### 运行架构与访问入口
| 组件 | 职责 | 接手时从这里看 |
|---|---|---|
| React/Vite + Web Nginx | 提供静态页面,同源转发 `/api/` 和 `/health` | [前端开发代理](web/vite.config.ts)、[Compose 的 Nginx 配置](deploy/nginx.conf) |
| Go API + 治理 PostgreSQL | 认证、角色、来源、绑定、审核、任务与发布记录。云测试使用独立逻辑库 `knowledge_governance_test` | [API](cmd/api)、[接口契约](api/openapi.yaml) |
| 普通 worker + 测试 WeKnora | worker 取件、上传、轮询并记录验收结果。WeKnora 负责解析、切片和索引 | [worker](cmd/worker)、[来源接入](docs/OPERATIONS_RUNBOOK.md#接入外部平台) |
| 发布 worker + 生产 WeKnora | 按已锁定的批次和目标执行受控发布与读回。问答端通过下游服务使用已发布知识 | [发布 worker](cmd/release-worker)、[操作手册](docs/OPERATIONS_RUNBOOK.md) |
从自己的电脑做系统设置验收,使用 SSH 转发后的 `http://127.0.0.1:28189/`。云测试主控制台使用受限内网入口 `http://100.85.111.121:8088/`。仓内 Compose 则将宿主 `8088` 映射到 Web 容器 `8080`。选择入口时先确认要看的部署。隧道命令、生产 `090` 服务地址和 HTTPS 反代示例见[运维手册](docs/OPERATIONS_RUNBOOK.md#入口与反向代理)。
**平台入口展示当前部署版本,不是每次 CI 的构建预览。** CI 静态预览由独立链路提供;CI 通过不会自动更新运行服务。
### 部署前提
当前 [compose.yaml](compose.yaml) 面向已有接线环境,包含宿主目录、凭据挂载和外部 Docker 网络,**不是仅克隆仓库就能直接启动的通用安装包**。
部署者需先准备:
- Docker Compose,以及 `compose.yaml` 声明的外部网络。
- PostgreSQL、测试知识库及所启用来源的凭据文件与权限。
- 来源目录、spool 与运行状态挂载;按部署主机调整路径和 UID/GID。
- 测试 WeKnora 连接与对内/对外路由;生产发布按独立配置和授权接线。
仓内 Compose 含 `postgres` 演练服务。云测试和生产使用阿里云 RDS,部署前先核对目标逻辑库、当前迁移版本、待运行的迁移及所用的环境配置。API 和 worker 启动可执行迁移。已有环境先用 `docker compose config --services` 检查服务清单,按该环境的发布手册切换已验证的产物。前端开发可直接使用下面的 Vite 流程。
## 配置与安全边界
- 网页服务地址用于控制台探活与配置核验;真正的发布目标由受限发布运行时配置决定,两者不能混为一谈。
- 测试/生产 WeKnora 的地址与 API Key 可在「系统设置 → 测试/生产知识库绑定」里录入:密钥以 AES-GCM 密文存治理库(主密钥是独立 0600 文件),页面与接口只回显尾 4 位,日志、审计与响应都不出现明文。部署期仍可用文件引用作为兜底;示例配置不是真实凭据。
- 生产请求与 Release Worker 默认关闭;启用状态必须现场确认。测试处理成功、自动审核或批次锁定都不能绕过生产门禁。
- 来源扫描与取件不应改写原始业务资料;目标知识库的发布、移除和回滚属于独立受控动作。
- 发布与恢复前必须按目标环境准备备份,并核验可恢复性。
参考:[服务与操作配置](docs/OPERATIONS_RUNBOOK.md)、[生产备份与恢复](docs/PRODUCTION_BACKUP_RECOVERY.md)、[来源范围规则](docs/SOURCE_SCOPE_POLICY.md)。
## 开发与 CI
开发环境使用 Go 1.26、Node.js 22、npm 和 Python 3。前端可独立开发。先准备一个获准用于开发的测试治理 API,在开发机的 `localhost:8088` 上确认 `/health` 可达。Vite 按仓内配置将 `/api` 和 `/health` 转给该地址,浏览器中的操作会作用于所连的环境。
```bash
# 仓库根目录,检查测试后端及前端依赖,再启动开发页面
curl -fsS --max-time 5 http://localhost:8088/health
cd web
npm ci
npm run dev -- --host 127.0.0.1
```
打开 Vite 打印的地址。修改组件后运行 `npm test` 和 `npm run build`。后端改动在仓库根目录用 `go test ./internal/httpapi` 这类按包测试缩小范围,再运行下方完整门禁。涉及持久化的联调使用独立测试 RDS 逻辑库,启动 API 或 worker 前核实库名和迁移版本。真实页面的通过条件见[运维手册](docs/OPERATIONS_RUNBOOK.md#开发测试和现场验收)。
```bash
make verify # 完整检查入口:本地与 CI 使用同一套规则
make list # 查看检查清单与适用范围
```
单项测试或构建只用于定位问题,不能代替完整验证。远端 CI 校验事件提交身份、汇总必需检查,再按条件生成静态预览与通知;不默认执行部署。
版本与变更见 [CHANGELOG](CHANGELOG.md),正式版本流程见 [发布 Runbook](docs/RELEASE_RUNBOOK.md)。`make version` 查看构建身份;日常开发构建与正式构建分开标识,软件版本 tag 不等同于知识发布批次。
## 问答运营模型配置
管理员在「系统设置 → 服务配置 → 问答评估模型」填写 OpenAI 兼容基础地址、模型和 API Key。测试连接发送最小非业务请求;保存不会启动历史全量任务,自动分析/翻译默认关闭。密钥不回显,保留、更换和清除分别选择;录入只允许有效 HTTPS 或本机回环连接,不允许跳过证书校验。
API 和普通 worker 须只读挂载同一个独立的 **32 字节、0600 普通文件**,以 `QA_AI_MASTER_KEY_FILE` 指向容器内路径。文件属主应为实际运行 UID;不要复用 Agent 会话存储或把主密钥写进 Compose/Git。治理库只保存加密后的服务密钥;恢复时必须同时恢复治理库和这份独立主密钥。未配置主密钥时如实显示安全存储未就绪。
当本机代理的 Fake-IP DNS 导致公网端点被安全守卫拒绝时,可仅为这两个治理组件设置 `QA_AI_DNS_OVER_TLS=alidns`:通过证书验证的公共 DNS-over-TLS 解析,再按同样的公网 IP、HTTPS 和禁止重定向规则发请求;不修改系统 DNS、代理或隧道,不允许以启用私网访问替代修复。
问题流水支持先预览已执行筛选/单条范围,再创建持久后台批次;字段分析和原问题译中独立计数,仅补真正空白。暂停不撤回已发请求,共享任务若仍被另一活动批次需要会继续执行;恢复或重试失败项不扩大原批次分母。详情保留逐字段依据、模型/提示词版本及回填/跳过说明。自动处理首次启用排除历史,关闭暂停未开始的自动任务,重开恢复披露的增量积压;不因保存配置而全量外发。
## 后续方向
- 扩展多数据源调度与增量同步的覆盖范围。
- 完善处理监控、积压分析、告警及来源与目标知识库的一致性对账。
- 建设知识资产、新鲜度、更新超期与知识缺口报表。
- 对接评测和业务反馈,形成可归因的持续优化闭环。
- 细化敏感资料权限及生命周期规则。
这些是演进方向,不作为当前已上线能力承诺。待办见 [BACKLOG](docs/BACKLOG.md)。
## 文档导航
| 文档 | 用途 |
| --- | --- |
| [操作 Runbook](docs/OPERATIONS_RUNBOOK.md) | 使用步骤、配置、凭据续期与异常处理 |
| [用户流程验收](docs/USER_FLOWS_ACCEPTANCE.md) | 实测证据、待验收项及限制 |
| [领域模型](docs/DOMAIN_MODEL.md) / [状态机](docs/STATE_MACHINE.md) | 模块边界、数据与状态语义 |
| [发布与版本](docs/RELEASE_RUNBOOK.md) | 软件发布准备与只读预检 |
| [备份与恢复](docs/PRODUCTION_BACKUP_RECOVERY.md) | 知识库数据的备份、恢复与演练 |
| [旧 README 存档](docs/archive/README_BEFORE_PRODUCT_REWRITE.md) | 原阶段说明与历史验收记录;不是实时部署状态 |
## 仓库结构
```text
cmd/ API、任务 Worker、发布 Worker 与运维工具
internal/ 治理模型、任务队列、持久化、HTTP 与发布适配
web/ React / TypeScript 管理界面
deploy/ Nginx 配置
config/ 发布等受限配置的示例
scripts/ 检查、资料处理与运维脚本
docs/ 操作、设计、验收与历史档案
```