Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
fix(knowledge): make in-place file replacement race-safe
wizardchen079e96ae64b7
diff --git a/internal/application/service/knowledge.go b/internal/application/service/knowledge.goindex 16f148b7e..2e4ef0252 100644--- a/internal/application/service/knowledge.go+++ b/internal/application/service/knowledge.go@@ -424,6 +424,32 @@ func (s *knowledgeService) isKnowledgeAborted(return false, knowledge.ParseStatus}+// isKnowledgeSourceReplaced reports whether the stored source file no longer+// matches the in-memory knowledge this worker loaded. ReplaceKnowledgeFile+// changes file_path under a still-running ProcessDocument; the stale worker+// must not Save() the old path back or write chunks from the replaced file.+func (s *knowledgeService) isKnowledgeSourceReplaced(ctx context.Context, knowledge *types.Knowledge) bool {+ if knowledge == nil || knowledge.ID == "" || knowledge.FilePath == "" {+ return false+ }+ current, err := s.repo.GetKnowledgeByID(ctx, knowledge.TenantID, knowledge.ID)+ if err != nil || current == nil {+ return false+ }+ return current.FilePath != "" && current.FilePath != knowledge.FilePath+}++// updateKnowledgeUnlessSourceReplaced persists processing state only when this+// worker still owns the source file. A no-op skip is preferred over rolling+// file_path back to a blob ReplaceKnowledgeFile may already have deleted.+func (s *knowledgeService) updateKnowledgeUnlessSourceReplaced(ctx context.Context, knowledge *types.Knowledge) error {+ if s.isKnowledgeSourceReplaced(ctx, knowledge) {+ logger.Infof(ctx, "Skip knowledge update for %s: source file was replaced", knowledge.ID)+ return nil+ }+ return s.repo.UpdateKnowledge(ctx, knowledge)+}+// checkStorageEngineConfigured verifies that the knowledge base has a storage engine configured// (either at the KB level or via the tenant default).//diff --git a/internal/application/service/knowledge_process.go b/internal/application/service/knowledge_process.goindex 04e2210fb..7c028f007 100644--- a/internal/application/service/knowledge_process.go+++ b/internal/application/service/knowledge_process.go@@ -314,6 +314,10 @@ func (s *knowledgeService) processChunks(ctx context.Context,logger.Infof(ctx, "Knowledge aborted (%s), skipping chunk processing: %s", status, knowledge.ID)return}+ if s.isKnowledgeSourceReplaced(ctx, knowledge) {+ logger.Infof(ctx, "Knowledge source replaced, skipping chunk processing: %s", knowledge.ID)+ return+ }// Get embedding model for vectorization — only needed when vector/keyword indexing is enabledvar embeddingModel embedding.Embedder@@ -525,6 +529,10 @@ func (s *knowledgeService) processChunks(ctx context.Context,logger.Infof(ctx, "Knowledge aborted (%s), skipping chunk write: %s", status, knowledge.ID)return}+ if s.isKnowledgeSourceReplaced(ctx, knowledge) {+ logger.Infof(ctx, "Knowledge source replaced, skipping chunk write: %s", knowledge.ID)+ return+ }// Save chunks to database — ALWAYS, regardless of indexing strategy.// Chunks are needed for wiki generation, graph extraction, and summary generation@@ -609,6 +617,10 @@ func (s *knowledgeService) processChunks(ctx context.Context,// Check again before batch indexing (heavy operation).// deleting → row is going away anyway, drop the chunks we just wrote.// cancelled → user wants to keep what was already persisted, just stop.+ if s.isKnowledgeSourceReplaced(ctx, knowledge) {+ logger.Infof(ctx, "Knowledge source replaced, skipping indexing: %s", knowledge.ID)+ return+ }if aborted, status := s.isKnowledgeAborted(ctx, knowledge.TenantID, knowledge.ID); aborted {logger.Infof(ctx, "Knowledge aborted (%s) before indexing: %s", status, knowledge.ID)if status == types.ParseStatusDeleting {@@ -657,6 +669,10 @@ func (s *knowledgeService) processChunks(ctx context.Context,// deleting → drop chunks+index we just wrote.// cancelled → keep persisted data; the row stays in cancelled status// and downstream stages skip via the entry guards.+ if s.isKnowledgeSourceReplaced(ctx, knowledge) {+ logger.Infof(ctx, "Knowledge source replaced, skipping completion: %s", knowledge.ID)+ return+ }if aborted, status := s.isKnowledgeAborted(ctx, knowledge.TenantID, knowledge.ID); aborted {logger.Infof(ctx, "Knowledge aborted (%s) after indexing: %s", status, knowledge.ID)if status == types.ParseStatusDeleting {@@ -689,7 +705,7 @@ func (s *knowledgeService) processChunks(ctx context.Context,now,)- if err := s.repo.UpdateKnowledge(ctx, knowledge); err != nil {+ if err := s.updateKnowledgeUnlessSourceReplaced(ctx, knowledge); err != nil {logger.GetLogger(ctx).WithField("error", err).Errorf("processChunks update knowledge failed")}@@ -3346,11 +3362,23 @@ func (s *knowledgeService) ProcessDocument(ctx context.Context, t *asynq.Task) elogger.Infof(ctx, "Knowledge aborted (%s) before marking processing: %s", status, knowledge.ID)return nil}+ if payload.FilePath != "" && knowledge.FilePath != "" && payload.FilePath != knowledge.FilePath {+ logger.Infof(ctx, "Document source replaced, skipping stale process task: %s", payload.KnowledgeID)+ return nil+ }+ if s.isKnowledgeSourceReplaced(ctx, knowledge) {+ logger.Infof(ctx, "Document source replaced, skipping stale process task: %s", payload.KnowledgeID)+ return nil+ }markKnowledgeProcessing(knowledge, time.Now())- if err := s.repo.UpdateKnowledge(ctx, knowledge); err != nil {+ if err := s.updateKnowledgeUnlessSourceReplaced(ctx, knowledge); err != nil {logger.Errorf(ctx, "failed to update knowledge status to processing: %v", err)return nil}+ if s.isKnowledgeSourceReplaced(ctx, knowledge) {+ logger.Infof(ctx, "Document source replaced, aborting after status update: %s", payload.KnowledgeID)+ return nil+ }// Resolve the attempt for span tracking. The enqueue site sets// payload.Attempt to a fresh number for the initial parse and to@@ -3811,7 +3839,9 @@ func (s *knowledgeService) convert(knowledge.ParseStatus = "failed"knowledge.ErrorMessage = result.Errorknowledge.UpdatedAt = time.Now()- s.repo.UpdateKnowledge(ctx, knowledge)+ if err := s.updateKnowledgeUnlessSourceReplaced(ctx, knowledge); err != nil {+ logger.Errorf(ctx, "failed to persist parser error for %s: %v", knowledge.ID, err)+ }s.failStage(ctx, knowledge.ID, types.StageDocReader,werrors.ErrCodeDocReaderParseFailed, result.Error, nil)return nil, nil@@ -3910,11 +3940,17 @@ func (s *knowledgeService) failKnowledge(args ...interface{},) (*types.ReadResult, error) {errMsg := fmt.Sprintf(format, args...)+ if s.isKnowledgeSourceReplaced(ctx, knowledge) {+ logger.Infof(ctx, "Skip failing knowledge %s: source file was replaced", knowledge.ID)+ return nil, nil+ }if isLastRetry {knowledge.ParseStatus = "failed"knowledge.ErrorMessage = errMsgknowledge.UpdatedAt = time.Now()- s.repo.UpdateKnowledge(ctx, knowledge)+ if err := s.updateKnowledgeUnlessSourceReplaced(ctx, knowledge); err != nil {+ logger.Errorf(ctx, "failed to persist knowledge failure for %s: %v", knowledge.ID, err)+ }}return nil, fmt.Errorf(format, args...)}diff --git a/internal/application/service/knowledge_replace.go b/internal/application/service/knowledge_replace.goindex fe99569f8..ca20ef9f3 100644--- a/internal/application/service/knowledge_replace.go+++ b/internal/application/service/knowledge_replace.go@@ -4,6 +4,7 @@ import ("context""encoding/json""mime/multipart"+ "strings""time"werrors "github.com/Tencent/WeKnora/internal/errors"@@ -21,18 +22,22 @@ import (// Object storage is not transactional, so the steps are ordered to keep the// row pointing at a file that exists:// 1. save the new file under a fresh storage path;-// 2. point the row at it with a single UPDATE of the source columns;-// 3. ReparseKnowledge cleans the old chunks/index/graph and enqueues parsing;-// 4. only after that succeeds, delete the old file.+// 2. dequeue any in-flight parse of the previous source;+// 3. point the row at the new file and mark it pending in one UPDATE;+// 4. ReparseKnowledge cleans the old chunks/index/graph and enqueues parsing;+// 5. only after that succeeds, delete the old file.//-// If step 2 fails the new file is discarded. If step 3 fails the previous-// source columns are restored (marked failed, since cleanup may already have-// removed the old index) and the new file is discarded. A file is never-// deleted while the row may still reference it.+// If step 3 fails the new file is discarded, unless a re-read shows the write+// committed despite the error — in that case reparse continues so the row is+// not left completed against a new file. If step 4 fails the previous source+// columns are restored (marked failed, since cleanup may already have removed+// the old index) and the new file is discarded. A file is never deleted while+// the row may still reference it.//// Identical content under the same name and folder is not re-parsed: changed-// metadata is persisted and a DuplicateKnowledgeError carrying the knowledge-// is returned, mirroring CreateKnowledgeFromFile's duplicate contract.+// metadata is persisted and a DuplicateKnowledgeError carrying this knowledge+// is returned. Unlike CreateKnowledgeFromFile, this does not treat another+// knowledge's hash as a duplicate — path identity is what connectors need.func (s *knowledgeService) ReplaceKnowledgeFile(ctx context.Context,knowledgeID string, file *multipart.FileHeader, customFileName string, metadata map[string]string,) (*types.Knowledge, error) {@@ -43,6 +48,9 @@ func (s *knowledgeService) ReplaceKnowledgeFile(ctx context.Context,if err != nil {return nil, err}+ if kb != nil && kb.Type == types.KnowledgeBaseTypeFAQ {+ return nil, werrors.NewBadRequestError("FAQ 知识库不支持文件上传,请使用 FAQ 导入功能")+ }if existing.Type != "file" || existing.FilePath == "" {return nil, werrors.NewBadRequestError("only file knowledge can have its file replaced")}@@ -53,13 +61,18 @@ func (s *knowledgeService) ReplaceKnowledgeFile(ctx context.Context,return nil, err}- // Same naming rules as CreateKnowledgeFromFile: a path-qualified custom name- // places the knowledge in that folder; without one the folder is kept.fileName, folderPath := file.Filename, existing.FolderPathif customFileName != "" {- folderPath, fileName = types.SplitKnowledgeRelativePath(customFileName)- if fileName == "" {- fileName = file.Filename+ customFolder, customName := types.SplitKnowledgeRelativePath(customFileName)+ if customName == "" {+ customName = file.Filename+ }+ fileName = customName+ // A path-qualified name relocates the knowledge. A bare filename+ // keeps the existing folder so callers can pass file.Filename as+ // customFileName without moving the document to the KB root.+ if knowledgeCustomNameRelocates(customFileName) {+ folderPath = customFolder}}safeFileName, ok := secutils.ValidateInput(fileName)@@ -108,11 +121,6 @@ func (s *knowledgeService) ReplaceKnowledgeFile(ctx context.Context,return existing, types.NewDuplicateFileError(existing)}- if tenant, _ := ctx.Value(types.TenantInfoContextKey).(*types.Tenant); tenant != nil &&- tenant.StorageQuota > 0 && tenant.StorageUsed >= tenant.StorageQuota {- return nil, types.NewStorageQuotaExceededError()- }-fileSvc := s.resolveFileService(ctx, kb)newPath, err := fileSvc.SaveFile(ctx, file, existing.TenantID, existing.ID)if err != nil {@@ -131,20 +139,35 @@ func (s *knowledgeService) ReplaceKnowledgeFile(ctx context.Context,if len(previousMetadata) == 0 {previousMetadata = types.JSON("{}") // metadata is NOT NULL; an empty JSON writes NULL}- if err := s.repo.UpdateKnowledgeColumns(ctx, existing.ID, map[string]interface{}{- "title": title,- "file_name": safeFileName,- "folder_path": folderPath,- "file_type": fileType,- "file_size": file.Size,- "file_hash": hash,- "file_path": newPath,- "metadata": newMetadata,- "updated_at": time.Now(),- }); err != nil {- logger.Errorf(ctx, "Failed to point knowledge %s at its replacement file: %v", existing.ID, err)- s.discardReplacementFile(cleanupCtx, fileSvc, existing.TenantID, existing.ID, newPath)- return nil, err++ // Drop queued parse tasks of the previous source before the row+ // points at the new file. The new TypeDocumentProcess task is+ // enqueued later by ReparseKnowledge.+ s.dequeueKnowledgeTasks(cleanupCtx, existing.ID)++ sourceColumns := map[string]interface{}{+ "title": title,+ "file_name": safeFileName,+ "folder_path": folderPath,+ "file_type": fileType,+ "file_size": file.Size,+ "file_hash": hash,+ "file_path": newPath,+ "metadata": newMetadata,+ "parse_status": types.ParseStatusPending,+ "enable_status": "disabled",+ "error_message": "",+ "updated_at": time.Now(),+ }+ if err := s.repo.UpdateKnowledgeColumns(ctx, existing.ID, sourceColumns); err != nil {+ current, readErr := s.repo.GetKnowledgeByID(cleanupCtx, existing.TenantID, existing.ID)+ if readErr != nil || current == nil || current.FilePath != newPath {+ logger.Errorf(ctx, "Failed to point knowledge %s at its replacement file: %v", existing.ID, err)+ s.discardReplacementFile(cleanupCtx, fileSvc, existing.TenantID, existing.ID, newPath)+ return nil, err+ }+ logger.Warnf(ctx, "Source update for knowledge %s reported an error after committing; continuing reparse: %v",+ existing.ID, err)}reparsed, err := s.ReparseKnowledge(ctx, existing.ID, nil)@@ -171,7 +194,8 @@ func (s *knowledgeService) ReplaceKnowledgeFile(ctx context.Context,}if existing.FilePath != newPath {- if err := fileSvc.DeleteFile(cleanupCtx, existing.FilePath); err != nil {+ oldFileSvc := s.resolveFileServiceForPath(cleanupCtx, kb, existing.FilePath)+ if err := oldFileSvc.DeleteFile(cleanupCtx, existing.FilePath); err != nil {logger.Warnf(ctx, "Failed to delete replaced file %s of knowledge %s: %v",existing.FilePath, existing.ID, err)}@@ -184,6 +208,10 @@ func (s *knowledgeService) ReplaceKnowledgeFile(ctx context.Context,return reparsed, nil}+func knowledgeCustomNameRelocates(customFileName string) bool {+ return strings.Contains(strings.ReplaceAll(customFileName, "\\", "/"), "/")+}+// discardReplacementFile deletes a replacement file that did not become the// knowledge's source. It re-reads the row first: a write reported as failed// may still have committed, and a knowledge pointing at a deleted file isdiff --git a/internal/application/service/knowledge_replace_test.go b/internal/application/service/knowledge_replace_test.goindex 8ecf283bb..f802cc853 100644--- a/internal/application/service/knowledge_replace_test.go+++ b/internal/application/service/knowledge_replace_test.go@@ -76,6 +76,8 @@ func (r *replaceFileRepo) apply(values map[string]interface{}) {r.row.Metadata = value.(types.JSON)case "parse_status":r.row.ParseStatus = value.(string)+ case "enable_status":+ r.row.EnableStatus = value.(string)case "error_message":r.row.ErrorMessage = value.(string)}@@ -144,6 +146,16 @@ type replaceFileGraph struct {func (replaceFileGraph) DelGraph(context.Context, []types.NameSpace) error { return nil }+type replaceFileInspector struct {+ fakeTaskInspector+ events *[]string+}++func (i *replaceFileInspector) CancelTasksForKnowledge(_ context.Context, knowledgeID string) (int, int, error) {+ *i.events = append(*i.events, "dequeue:"+knowledgeID)+ return 1, 0, nil+}+type replaceFileHarness struct {svc *knowledgeServicerepo *replaceFileRepo@@ -180,13 +192,14 @@ func newReplaceFileHarness(t *testing.T) *replaceFileHarness {h.store = &replaceFileStore{events: &h.events}h.tasks = &replaceFileEnqueuer{events: &h.events}h.svc = &knowledgeService{- repo: h.repo,- kbService: &reparseFailureKBService{kb: kb},- fileSvc: h.store,- task: h.tasks,- chunkService: replaceFileChunkService{},- chunkRepo: replaceFileChunks{},- graphEngine: replaceFileGraph{},+ repo: h.repo,+ kbService: &reparseFailureKBService{kb: kb},+ fileSvc: h.store,+ task: h.tasks,+ taskInspector: &replaceFileInspector{events: &h.events},+ chunkService: replaceFileChunkService{},+ chunkRepo: replaceFileChunks{},+ graphEngine: replaceFileGraph{},}ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(7))ctx = context.WithValue(ctx, types.TenantInfoContextKey, &types.Tenant{ID: 7})@@ -200,7 +213,14 @@ func (h *replaceFileHarness) replace(t *testing.T, content, customFileName string, metadata map[string]string,) (*types.Knowledge, error) {t.Helper()- fh, err := bytesToFileHeader([]byte(content), "upload.md")+ return h.replaceNamed(t, content, "upload.md", customFileName, metadata)+}++func (h *replaceFileHarness) replaceNamed(+ t *testing.T, content, filename, customFileName string, metadata map[string]string,+) (*types.Knowledge, error) {+ t.Helper()+ fh, err := bytesToFileHeader([]byte(content), filename)require.NoError(t, err)return h.svc.ReplaceKnowledgeFile(h.ctx, h.original.ID, fh, customFileName, metadata)}@@ -236,8 +256,8 @@ func TestReplaceKnowledgeFilePreservesIDAndReparsesNewContent(t *testing.T) {require.Len(t, h.tasks.payloads, 1)assert.Equal(t, h.original.ID, h.tasks.payloads[0].KnowledgeID)assert.Equal(t, "new/file.md", h.tasks.payloads[0].FilePath)- assert.Equal(t, []string{"save", "enqueue", "delete:old/file.md"}, h.events,- "the old file is deleted only after the reparse was submitted")+ assert.Equal(t, []string{"save", "dequeue:knowledge-1", "enqueue", "delete:old/file.md"}, h.events,+ "queued parse tasks are dropped before reparse; the old file is deleted only after enqueue")}func TestReplaceKnowledgeFileUnchangedContentSkipsReparse(t *testing.T) {@@ -280,16 +300,19 @@ func TestReplaceKnowledgeFileSourceUpdateFailureDiscardsNewFile(t *testing.T) {assert.Empty(t, h.tasks.payloads)}-func TestReplaceKnowledgeFileCommittedUpdateReportedAsFailedKeepsNewFile(t *testing.T) {+func TestReplaceKnowledgeFileCommittedUpdateReportedAsFailedContinuesReparse(t *testing.T) {h := newReplaceFileHarness(t)h.repo.failColumnsCall = 1h.repo.commitThenFail = true- _, err := h.replace(t, "# new body", "notes/a.md", nil)+ got, err := h.replace(t, "# new body", "notes/a.md", nil)- require.Error(t, err)+ require.NoError(t, err)+ require.Equal(t, h.original.ID, got.ID)assert.Equal(t, "new/file.md", h.repo.row.FilePath)- assert.Empty(t, h.store.deleted, "a file the row references must not be deleted")+ assert.Equal(t, types.ParseStatusPending, h.repo.row.ParseStatus)+ assert.Equal(t, []string{"old/file.md"}, h.store.deleted)+ require.Len(t, h.tasks.payloads, 1)}func TestReplaceKnowledgeFileReparseFailureRestoresPreviousSource(t *testing.T) {@@ -343,3 +366,81 @@ func TestReplaceKnowledgeFileRejectsUnsupportedFileType(t *testing.T) {assert.Zero(t, h.store.saved)assert.Equal(t, h.original, h.repo.row)}++func TestReplaceKnowledgeFileEmptyCustomNameKeepsFolder(t *testing.T) {+ h := newReplaceFileHarness(t)++ _, err := h.replaceNamed(t, "# new body", "a.md", "", nil)++ require.NoError(t, err)+ assert.Equal(t, "notes", h.repo.row.FolderPath)+ assert.Equal(t, "a.md", h.repo.row.FileName)+}++func TestReplaceKnowledgeFileBareCustomNameKeepsFolder(t *testing.T) {+ h := newReplaceFileHarness(t)++ _, err := h.replace(t, "# new body", "b.md", nil)++ require.NoError(t, err)+ assert.Equal(t, "notes", h.repo.row.FolderPath, "a basename must not move the document to the KB root")+ assert.Equal(t, "b.md", h.repo.row.FileName)+}++func TestReplaceKnowledgeFileIgnoresStorageQuota(t *testing.T) {+ h := newReplaceFileHarness(t)+ h.ctx = context.WithValue(h.ctx, types.TenantInfoContextKey, &types.Tenant{+ ID: 7, StorageQuota: 1, StorageUsed: 1,+ })++ got, err := h.replace(t, "# new body", "notes/a.md", nil)++ require.NoError(t, err)+ require.Equal(t, h.original.ID, got.ID)+ assert.Equal(t, types.ParseStatusPending, h.repo.row.ParseStatus)+}++func TestReplaceKnowledgeFileDequeuesInProgressParse(t *testing.T) {+ h := newReplaceFileHarness(t)+ h.repo.row.ParseStatus = types.ParseStatusProcessing++ got, err := h.replace(t, "# new body", "notes/a.md", nil)++ require.NoError(t, err)+ require.Equal(t, h.original.ID, got.ID)+ assert.Contains(t, h.events, "dequeue:knowledge-1")+ assert.Equal(t, types.ParseStatusPending, h.repo.row.ParseStatus)+ assert.Equal(t, "disabled", h.repo.row.EnableStatus)+}++func TestReplaceKnowledgeFileRejectsFAQKnowledgeBase(t *testing.T) {+ h := newReplaceFileHarness(t)+ h.svc.kbService = &reparseFailureKBService{kb: &types.KnowledgeBase{+ ID: "kb-1", TenantID: 7, Type: types.KnowledgeBaseTypeFAQ,+ }}++ _, err := h.replace(t, "# new body", "notes/a.md", nil)++ require.Error(t, err)+ assert.Zero(t, h.store.saved)+}++func TestIsKnowledgeSourceReplaced(t *testing.T) {+ h := newReplaceFileHarness(t)+ loaded := h.original+ assert.False(t, h.svc.isKnowledgeSourceReplaced(h.ctx, &loaded))++ h.repo.row.FilePath = "new/file.md"+ assert.True(t, h.svc.isKnowledgeSourceReplaced(h.ctx, &loaded))+}++func TestUpdateKnowledgeUnlessSourceReplacedSkipsStaleSave(t *testing.T) {+ h := newReplaceFileHarness(t)+ stale := h.original+ stale.ParseStatus = types.ParseStatusFailed+ h.repo.row.FilePath = "new/file.md"++ require.NoError(t, h.svc.updateKnowledgeUnlessSourceReplaced(h.ctx, &stale))+ assert.Equal(t, "new/file.md", h.repo.row.FilePath)+ assert.NotEqual(t, types.ParseStatusFailed, h.repo.row.ParseStatus)+}diff --git a/internal/types/interfaces/knowledge.go b/internal/types/interfaces/knowledge.goindex 0ed7b91a4..27c01a3ae 100644--- a/internal/types/interfaces/knowledge.go+++ b/internal/types/interfaces/knowledge.go@@ -130,8 +130,9 @@ type KnowledgeService interface {) (*types.Knowledge, error)// ReplaceKnowledgeFile replaces the source file of an existing file knowledge// while preserving its ID, then re-parses it. A path-qualified customFileName- // also sets the folder; metadata entries are merged into the stored metadata.- // Identical content returns a DuplicateKnowledgeError without re-parsing.+ // also sets the folder; a bare filename keeps the current folder. Metadata+ // entries are merged into the stored metadata. Identical content on this+ // same path returns a DuplicateKnowledgeError without re-parsing.ReplaceKnowledgeFile(ctx context.Context,knowledgeID string,