
FastGPT 4.17.1 introduced file-level permissions for knowledge bases: collaborators are configured per file or folder, inherited and independent states coexist, inheritance can be restored, and ownership can be transferred. The switch is off by default.
The effect on retrieval depends on the calling identity. Lists and details use the file grants; search tests and application retrieval with user authentication filter the current member’s readable collections. A preselected knowledge base without that authentication follows the application access configuration.
What the switch changes
With the switch off, files use knowledge-base permissions. Enabling it initialises existing files from the current knowledge-base collaborators. Inherited branches follow parent changes, while independent branches retain their own grants; turning the feature off removes collection-level collaborator configuration.
Permission also has a navigation rule worth knowing. When a member holds permission only on a child resource, the parent folder appears as a navigation entry without granting management rights on the parent. This removes a class of accidental over-permission that appears whenever folder structures are reorganised.
Prepare before enabling
Before enabling the feature, record current knowledge-base collaborators, the files requiring separate access and the intended inheritance tree. Allow initialisation to finish before changing individual grants. Use ordinary member accounts for acceptance, since the team owner and the self-hosted root account have elevated access.
After initialisation, review the resulting access list against the intended resource map. A missing result can arise from knowledge-base access, collection access, the application authentication path or the content itself, so preserve the test identity and expected file with the result.
Test with two identities
Pick two files with different collaborator sets and two accounts with different grants. Run the same question under each account and compare the returned file names and passage locations. Then change one file’s collaborators as an administrator, re-run, and observe whether the result follows.
Three steps produce evidence that the permission behaves as designed. Reading the configuration screen produces an opinion instead.
Publishing adds a snapshot layer
A published application checks static resources against the permission snapshot captured at publication, and dynamic resources against the running user. The two layers exist for different reasons: one preserves the state at publication, the other keeps access current.
When an access problem appears after publication, the first question is which layer is failing. A user who sees the interface but not the files is usually an issue at the running-user layer; a user who cannot open the application at all is usually a snapshot issue.
The feature and its inheritance rules are documented in FastGPT collection permissions .
Plan the folder structure before the permission model
Permission inherits along the folder tree, so a structure built for convenience becomes a permission problem later. Three patterns work: layers by department, folders by project, and exceptions at file level.
Mixing the three in one tree means a single permission change requires checking three places. Two extra folders are usually cheaper than one exception audit.
Document the intended pattern before enabling the switch. After enablement, the same document becomes the reference for the quarterly review, and the review is what keeps the model from drifting as staff change.
Keep a permission change log
Every change to collaborators should leave a line: what changed, who authorised it, and when. Three fields, one line per change, and the log answers most questions during an audit.
Without the log, reconstruction depends on memory, and memory is worst precisely for the changes that mattered most, those made under time pressure.
The log also shortens onboarding. A new administrator reads the last twenty changes and understands how the current model came to be, which is faster than reading a design document.
Review the model quarterly
Permission models drift as staff change and projects end. A quarterly review of three items keeps it aligned: files with no collaborator, folders whose inheritance state does not match the documented pattern, and accounts holding access no longer required.
Each item produces a list, and the list produces actions with owners. Without the review, the model remains documented but stops describing reality, which is worse than having no document at all.
The review record should identify the resources inspected, changes needed and owners, so the next administrator can continue the work.
What to tell users when they ask
Users who cannot find a file will report it as a system fault. A short internal note explains the two layers: access to the knowledge base, and access to the individual file.
With that note circulated, support requests arrive with the right question attached, which gives support a concrete access path to inspect and keeps the permission model from being blamed for content that was never uploaded.
Keeping the note current
Review the note whenever the permission model changes, and date it at the top. A note that describes last year’s model is worse than no note, because it answers with confidence and sends the reader to the wrong place.