在使用QoderWake知识库上传文件时，许多用户近期反映控制台长时间停留在“上传中”状态、进度条停滞不前、弹出“解析失败”提示，甚至直接返回空白错误码。这类问题通常并非由网络中断引起，而是源于文件格式不兼容、单个文件超出限制、权限拦截或后台服务未启动等深层原因。

确认文件是否符合上传规格

第一步：检查文件扩展名是否在允许的白名单中——仅支持PDF、Markdown（.md）、Word（.docx）、纯文本（.txt）这四种格式。其他格式如.xlsx、.pptx、.epub以及加密PDF，系统前端会直接拒绝，不会生成日志，也不会触发后端解析。

第二步：查看文件属性，确认单个文件大小不超过200MB，且页数不超过500页。如果是扫描版PDF，务必确保已启用OCR文字识别层（可借助Adobe Acrobat打开，依次点击“工具”→“增强扫描”进行验证），否则系统会判定为“无文本内容”，上传后状态将一直显示“待处理”。

排查本地配置与服务状态

方法一：验证知识库后端服务是否正常运行。在终端中运行以下命令：qoderctl service status --module knowledge。如果返回status: offline或error: connection refused，则表示Tablestore RAG流水线尚未启动，需要先执行qoderctl service start --module knowledge，然后再重新尝试上传。

方法二：检查配置目录的写入权限。Windows用户请进入%USERPROFILE%AppDataRoamingQoderWakeuploadtemp，右键点击文件夹，选择“属性”→“安全”，确认当前用户具有“修改”权限。Linux/macOS用户可执行：ls -ld ~/.config/qoderwake/upload，查看输出中第三组字符（others）是否至少包含r，若没有，则需要运行：chmod o+r ~/.config/qoderwake/upload。

绕过前端限制，用CLI强制注入文档

当控制台持续失败且确认文件合规时，可跳过Web UI，直接调用CLI工具完成结构化注入：

① 将文件放置于本地路径中，例如：/home/user/docs/manual_v2.md；

② 执行命令：qoderctl knowledge inject --file /home/user/docs/manual_v2.md --tags "product, v2" --chunk-size 512；

③ 观察终端输出信息：如果出现✓ Injected 127 chunks into vector index以及sync completed，则表示文档已成功载入知识库，无需等待控制台刷新。

注意：CLI注入方式不会校验页数上限，但会自动按语义进行切块，chunk-size超过1024可能会导致检索精度下降，建议保持默认值512或设置为256。

目前，用户可按照上述步骤依次尝试。如果仍然无法上传，建议联系官方技术支持以获取进一步帮助。