知识治理平台

面向企业多数据源的知识同步、生命周期治理与持续运营平台。

企业知识分散在钉钉、文件目录与业务资料门户中，内容会不断新增、更新和失效。平台连接这些来源与 WeKnora 知识底座，组织资料发现、取件、处理、验收、发布和下架，让知识不只是被导入一次，而是能够持续维护、追踪和治理。

同步是入口，知识库治理是核心，持续运营是目标。

平台解决什么问题

• 资料分散：统一查看来源与目录，按范围选择、标注和获取内容。
• 更新难追踪：通过来源身份、内容摘要、版本、快照与变更集记录变化。
• 处理不透明：查看任务和解析状态，定位失败、停滞和需要人工处理的项目。
• 知识边界不清：区分对内、对外和禁止导入，绑定相应测试与生产知识库。
• 上线不可控：先处理与验收，再按审核策略和生产门禁组织发布。
• 失效难治理：识别需下架内容，提供移除、失败重排与发布回滚等处理机制。

自动同步不等于无条件自动发布。不同来源的扫描、取件、处理和调度能力存在差异；生产变更仍受配置、权限与授权约束。

在 DobotAI 体系中的位置

业务资料来源：钉钉 / AList / PP（资料门户）
                  ↓
知识治理平台：发现与同步 → 状态跟踪 → 验收与治理 → 发布与维护
                  ↓
WeKnora：文档处理、知识组织、索引与检索
                  ↓
Knowledge Adapter / DobotAI 网关
                  ↓
钉钉问答 / 软件内 AI 助理 / Wiki 问答等业务入口

本仓库负责知识治理流程与控制，不重复建设问答应用或检索引擎，也不修改 WeKnora 官方源码。Knowledge Adapter、DobotAI 网关及业务入口属于关联系统，不由本项目部署。

核心能力与当前边界

下表描述仓库已有实现及文档记录的能力，不代表任一部署环境已启用所有功能。现场接线、运行开关与验收结果以对应环境为准。

能力	已有支持	边界
来源与目录管理	来源连接、目录浏览、范围选择、对内/对外/禁止导入策略	标注是治理意图，不代表已取件、入库或发布
多源资料获取	钉钉取件、AList 来源接入、PP 清单与历史账本接管	格式、凭据、目录及调度限制不同，不承诺所有来源全自动同步
变化与资产管理	稳定来源身份、内容摘要去重、来源版本、快照与变更集	来源变化与目标知识库处理状态分别记录
测试处理与验收	后台上传、轮询、知识与切片验收、失败恢复	解析和索引由对接的知识底座完成；部分检索判断仍需人工
解析与任务监控	处理中、失败/死信、需下架、知识库差异及处理进度视图	指标、动作与实际覆盖程度见验收清单，不等于完整告警平台
审核与发布	可配置自动审核策略、人工审核、批次锁定、生产授权与结果追踪	对内自动审核默认策略与对外人工控制详见操作流程；锁定不等于发布
回滚与备份	发布回滚、目标库快照门禁、备份配置及恢复工具	依赖专用接线、权限和恢复验证，不能仅凭页面存在判定可用
权限与审计	管理员、文档工程师、只读角色与操作记录	不等于已实现所有来源到问答端的文档级授权

数据源支持

来源	当前接入方式	参考文档
钉钉	知识库目录发现与取件；优先 dws，按错误类型决定是否回落兼容路径	钉钉取件
AList	来源目录与资料获取，依赖指定连接和凭据	用户操作流程
PP（资料门户）	本地清单、历史账本接管与只读扫描	历史接管、来源扫描

IT、行政等是待扩展的业务资料范围，不是已经完成的新连接器。接入敏感资料前，需要先确认 Owner、有效版本、可见范围与知识库路由。

工作流程

1. 配置来源与知识库绑定：确认凭据、可见范围和目标库。
2. 发现、标注与取件：按目录或文件选择范围，记录资料身份和变化。
3. 处理与验收：进入测试知识库，跟踪上传、解析、索引及验收结果。
4. 审核与组批：应用审核策略；建立并锁定发布清单，保留可追踪快照。
5. 授权发布：核验备份与发布门禁，再执行目标知识库变更并读回验证。
6. 持续维护：跟踪后续更新、失败、失效与需下架内容，按流程重排、移除或回滚。

具体操作、确认语句和异常处理见 操作 Runbook；已实测、待验收和已知限制见 用户流程验收清单。

访问与部署

已部署环境

Compose 中网页入口固定映射为 宿主机 8088 → Web 容器 8080。网页和 /api/ 使用同源入口。

• 本机访问：http://127.0.0.1:8088/
• 局域网访问：http://<服务器内网IP>:8088/
• 健康入口：http://127.0.0.1:8088/health

可以由 NAS 反向代理提供 HTTPS 域名入口，目标为平台服务器的 8088，保持路径原样转发。公网开放前必须验证鉴权、访问控制及转发头配置，不直接暴露数据库或内部管理接口。

平台入口展示当前部署版本，不是每次 CI 的构建预览。 CI 静态预览由独立链路提供；CI 通过不会自动更新运行服务。

部署前提

当前 compose.yaml 面向已有接线环境，包含宿主目录、凭据挂载和外部 Docker 网络，不是仅克隆仓库就能直接启动的通用安装包。

部署者需先准备：

• Docker Compose，以及 compose.yaml 声明的外部网络。
• PostgreSQL、测试知识库及所启用来源的凭据文件与权限。
• 来源目录、spool 与运行状态挂载；按部署主机调整路径和 UID/GID。
• 测试 WeKnora 连接与对内/对外路由；生产发布按独立配置和授权接线。

准备完成后，由获授权的操作者执行：

docker compose up --build -d

主机需要提权时，由操作者按本机权限规则执行，不在自动化中默认使用 sudo。停止服务可用 docker compose down；不要执行 docker compose down -v，除非明确批准删除数据库卷。

配置与安全边界

• 网页服务地址用于控制台探活与配置核验；真正的发布目标由受限发布运行时配置决定，两者不能混为一谈。
• 密钥通过文件或 secret 引用提供，不写入 Git、网页响应或日志。示例配置不是真实凭据。
• 生产请求与 Release Worker 默认关闭；启用状态必须现场确认。测试处理成功、自动审核或批次锁定都不能绕过生产门禁。
• 来源扫描与取件不应改写原始业务资料；目标知识库的发布、移除和回滚属于独立受控动作。
• 发布与恢复前必须按目标环境准备备份，并核验可恢复性。

参考：服务与操作配置、生产备份与恢复、来源范围规则。

开发与 CI

基础环境：Go 1.26、Node.js 22、npm，以及检查脚本所需的 Python 3 和工具链。依赖以仓库锁文件和实际 CI 配置为准。

make verify  # 完整检查入口：本地与 CI 使用同一套规则
make list    # 查看检查清单与适用范围

单项测试或构建只用于定位问题，不能代替完整验证。远端 CI 校验事件提交身份、汇总必需检查，再按条件生成静态预览与通知；不默认执行部署。

版本与变更见 CHANGELOG，正式版本流程见 发布 Runbook。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。

文档导航

文档	用途
操作 Runbook	使用步骤、配置、凭据续期与异常处理
用户流程验收	实测证据、待验收项及限制
领域模型 / 状态机	模块边界、数据与状态语义
发布与版本	软件发布准备与只读预检
备份与恢复	知识库数据的备份、恢复与演练
旧 README 存档	原阶段说明与历史验收记录；不是实时部署状态

仓库结构

cmd/        API、任务 Worker、发布 Worker 与运维工具
internal/   治理模型、任务队列、持久化、HTTP 与发布适配
web/        React / TypeScript 管理界面
deploy/     Nginx 配置
config/     发布等受限配置的示例
scripts/    检查、资料处理与运维脚本
docs/       操作、设计、验收与历史档案