我最初以为个人知识库的部署就是“起一个 Docker 容器上传 PDF然后调用模型”。真正运行后才发现问题并不止于模型 API构建镜像会卡住、依赖下载会断、容器会因内存不足被系统杀掉、旧资料会干扰新结论、回答看起来合理却找不到出处。这篇文章记录我为CoreNoteKnowledge Hub做个人 RAG 知识库部署和资料治理时最值得提前处理的一组问题资源、构建、资料准备、检索、来源核验与长期维护。官网https://corenote.cloud/知识指南https://corenote.cloud/knowledge-base.html开源仓库https://github.com/zhangjianxin477/knowledge-hub本文是个人项目/小团队场景的实践复盘不是“任意配置都可稳定运行”的承诺。涉及生产数据、模型回答、权限和安全的决策仍需要根据自己的环境测试与人工核验。一、先说结论个人知识库的难点不在“聊天”而在稳定的资料链路一个可长期使用的个人 RAG 知识库至少要同时解决五件事资料进得来PDF、Markdown、网页、项目文档等能被整理进同一知识入口资料找得到既能理解自然语言问题也能命中错误码、版本号、项目名、条款编号等精确词答案回得去回答要能关联文件、标题或上下文便于回到原始资料核验资料不会越用越乱新旧版本、重复文件、主题关系、归档状态必须可管理服务能活下来构建、解析、索引和模型调用都会占资源小内存服务器尤其需要有意识地控制并发和依赖体积。所以 CoreNote 的目标不是做一个“上传文档就能聊天”的页面而是把资料导入、文件组织、知识图谱、检索问答、持续追问与证据核验放进一条可复用的知识工作流中。二、架构先拆清楚不要把所有事情都交给大模型我目前把个人知识库看成如下链路PDF / Markdown / 网页 / 项目资料 ↓ 文件格式路由、解析、清洗、结构化 ↓ 来源 / 主题 / 时间 / 版本等元数据绑定 ↓ 父子分块、去重、Embedding、索引 ↓ 查询理解与检索路由 ↓ 向量检索 BM25 关键词检索 可选重排序 ↓ 回溯父文段、组装来源上下文 ↓ 基于证据回答、持续追问、低置信度降级 ↓ 记录 Badcase反向优化资料与检索这里没有哪一步是“可有可无”的装饰。不清洗 PDF分块和召回都会被页眉页脚、断行、目录页干扰不保留版本旧规则和新规则可能一起被召回只用向量检索专有名词和编号可能漏掉只用关键词检索语义相近的表达又容易找不到不保留来源线索最终得到的只是一个无法验证的段落不记录失败样本系统每次“答错”都无法转化为下一轮改进。三、第一个真实坑容器Exit 137不是“应用自己退出了”在一次部署中应用容器显示Exit 137同时在系统日志里可以看到类似Out of memory: Killed process ... (uvicorn)这说明当时并不是 Uvicorn 正常结束而是 Linux 的 OOM Killer 在全局内存紧张时杀掉了进程。137通常意味着进程收到SIGKILL但排查时不要只看到这个数字就下结论应该把它和内核日志、容器状态、内存占用一起看。1. 先确认容器状态docker-composeps-a重点看容器是否为Exit 137、Restarting或Up (healthy)反向代理容器是否仍然正常应用容器是否在频繁重启。2. 再看 Docker 记录的退出原因APP_ID$(docker-composeps-qtenant-a)dockerinspect$APP_ID\--formatexit{{.State.ExitCode}} oom_killed{{.State.OOMKilled}} started{{.State.StartedAt}} finished{{.State.FinishedAt}}如果oom_killedtrue说明 Docker 已经明确记录为内存不足导致的终止。3. 最后看系统层面的 OOM 日志dmesg-T|grep-Eiout of memory|oom-killer|killed process|tail-n80在部分系统上也可以尝试journalctl-k--no-pager|grep-Eiout of memory|oom-killer|killed process|tail-n80如果看到了Killed process ... uvicorn就可以把重点从“业务代码报错”转向“系统内存与负载控制”。四、为什么“明明设置了 deploy.resources”Docker Compose 仍然告警我的 Compose 输出曾出现类似警告WARNING: The following deploy sub-keys are not supported and have been ignored: resources.reservations.cpus这里的关键不是忽略警告而是理解它在说什么Compose 文件里写了资源声明不代表当前运行方式真的执行了全部资源约束。deploy段最初主要服务于 Swarm 部署模型不同 Docker Compose 版本、不同运行模式和不同子字段支持情况会不一样。尤其是老版本docker-compose经常会出现“配置写了但某个子字段被忽略”的情况。因此部署时建议分成两件事声明资源预期在 Compose 中表达服务希望的内存和 CPU 边界验证资源是否实际生效用运行时命令检查容器状态、实际限制和内存占用而不是只相信 YAML。下面的命令能快速看出当前实时资源占用dockerstats --no-streamfree-hdf-h如果你使用 Compose建议同时阅读自己所用版本对应的官方 Compose 文档而不是直接复制网上针对 Swarm 或旧版 Compose 的配置片段Docker Composedeploy参考https://docs.docker.com/reference/compose-file/deploy/Docker Compose 命令参考https://docs.docker.com/reference/cli/docker/compose/up/一个很容易误判的点“给容器加了 2G 限制”不等于“服务器一定有足够 2G 可用”。容器的内存上限是在主机总资源内分配的同一台机器上还可能有 Nginx、Docker daemon、系统缓存、其他容器、构建进程、日志和后台服务。没有 swap 或剩余内存很少时系统依然可能触发 OOM。五、小内存服务器的实用原则减少峰值而不是只改一个参数个人部署最容易忽视的是构建期、启动期、文档解析期和模型调用期的内存峰值并不相同。1. 保持单 Worker 是合理的起点CoreNote 的轻量启动命令使用了uvicorn app.main:app--host0.0.0.0--port8080--workers1--no-access-log在小内存机器上--workers 1的意义是避免多个 Python worker 同时加载应用依赖和运行时状态。它不能从根本上解决所有内存问题但比盲目提高 worker 数更适合作为起点。不要为了“看起来更高并发”直接把 worker 开大。对个人知识库而言稳定地完成导入、检索和问答比同时启动多个进程更重要。2. 解析和索引要避免同时处理大量文件PDF 解析、表格处理、Embedding、向量索引和 LLM 请求都可能占用较多内存。更稳妥的做法是先用少量真实资料验证流程大文件和批量文件拆分导入导入期间观察docker stats与free -h发生 OOM 时先降低并发和批量规模再讨论是否需要升级机器不要把“重启容器”当成长期解决方案。3. 控制数值计算库的隐式线程如果环境中包含 NumPy、scikit-learn 或其他数值计算依赖隐式并行也可能增加资源波动。项目的稳定性配置里可以保守地设置OPENBLAS_NUM_THREADS1 OMP_NUM_THREADS1 MKL_NUM_THREADS1这不是性能优化万能钥匙但在单核或低内存环境下能够减少某些任务突然拉起过多计算线程的概率。4. 先留出构建空间再构建镜像构建镜像时会同时存在下载层、中间层、构建上下文和旧镜像。磁盘空间不足会让构建报错或极慢网络慢则可能表现为依赖下载长时间没有进度。建议构建前先看df-hdockersystemdf清理前一定要先确认哪些镜像/容器仍在使用。不要直接复制破坏性清理命令在个人服务器上误删数据卷比“多占一点镜像空间”更麻烦。六、第二个真实坑构建卡在pip install不等于已经死掉部署时我遇到过日志长时间停在RUN pip install --no-cache-dir -r requirements-lite.txt或者某个大一点的 Python wheel / 源码包下载阶段。此时第一反应不应该是不断重复执行构建命令因为很可能会出现多个 Docker build 与 pip 进程同时跑反而占用更多网络、CPU、磁盘和内存。先确认有没有构建仍在运行ps-ef|grep-Edocker-compose|docker build|pip install|grep-vgrep如果还能看到docker build .../usr/local/bin/pip install ...或运行中的docker-compose up -d --build ...说明它并不是“卡死后什么都没发生”而是还在下载、编译或等待网络。此时应观察日志而不是再启动第二个构建。用日志观察不要在日志行前面输入命令如果使用后台构建nohupdocker-composebuild tenant-a/root/corenote-build.log21/dev/null观察方式是tail-f/root/corenote-build.log当你看到类似Step 7/27 : COPY frontend/ ./frontend/的输出时它只是日志不是要复制粘贴回终端执行的命令。等待构建完成并出现Successfully built、Successfully tagged后再执行容器重建。为什么不要一边构建一边强制重建同一个服务如果同时存在多个 build/recreate 流程常见后果有重复下载相同依赖构建缓存彼此争抢当前正常容器被提前停止老版本容器与新镜像状态难以判断小内存机器的资源峰值变得更高。更安全的顺序是确认没有旧构建 → 单独完成 build → 确认镜像生成 → 停止/移除旧应用容器 → 使用--no-build启动新容器 → 健康检查。七、构建上下文过大时问题不止是慢Docker 在构建前会把“构建上下文”发送给 Docker daemon。曾经出现过Sending build context to Docker daemon 801.4MB这说明需要关注.dockerignore是否真的排除了无关文件。对个人知识库项目来说下面这些目录通常不应该进入镜像构建上下文本地数据目录、上传文件、向量库Python 虚拟环境Git 历史与测试缓存备份文件、日志、模型文件部署环境里的真实.env与运行镜像无关的文档、演示素材和临时导出物。一个基础.dockerignore的方向可以是__pycache__/ *.pyc .git/ .venv/ venv/ data/ deploy/**/data/ deploy/**/backups/ *.log .env .env.* !.env.example注意Dockerfile.free.dockerignore这个命名并不会自动被 Docker 当作Dockerfile.free的忽略规则。Docker 默认读取构建上下文根目录的.dockerignore是否支持 Dockerfile 专属 ignore 文件要看你实际使用的 Docker/BuildKit 行为和命令。部署前要用构建日志中的Sending build context大小来验证而不是只凭文件名判断。有关构建缓存与构建上下文的官方说明可参考https://docs.docker.com/build/cache/八、资料导入前的准备比“换一个更大的模型”更重要真正影响问答质量的往往是资料本身是否适合被检索。1. Markdown给人看的笔记也要给检索系统留结构推荐让 Markdown 至少具备--- title: 项目部署说明 project: CoreNote version: 2026-09 status: active updated_at: 2026-09-27 --- # 部署前检查 ## 内存与磁盘 ...不一定需要固定这套 Frontmatter但应尽量保留标题、主题/项目、版本、状态、日期和清晰的标题层级。这样后续切分、过滤和来源展示都会更可靠。2. PDF优先导入“正文可复制、版本明确”的资料扫描件、复杂双栏、跨页表格和带大量页眉页脚的 PDF 并不是不能用但应预期解析质量会下降。对关键材料建议保留原始 PDF需要时同时准备人工整理的 Markdown 摘要明确文件版本与发布日期不要让“最终版”“最终版2”“最终版最终”成为唯一版本策略。3. 项目资料给结论补上适用范围很多项目文档的问题不在于没有答案而是缺少前提。将下面内容写清楚检索回答才不容易过度泛化此规则适用于哪个版本、哪个环境输入/输出示例是什么已知异常和例外情况结论由谁确认、是否仍然有效相关文件、接口、Issue 或决策记录在哪里。九、检索阶段向量和关键词不要二选一个人知识库中常见的两类问题对检索的要求不同用户问题更有价值的检索方式“有没有和这个研究方向相近的资料”向量语义检索“错误码 1305 出现在哪个文档”关键词检索“某项规则的例外条件是什么”结构化分块 父文段回溯“上次提到的部署限制还有什么”对话上下文 再检索“最新版 SOP 是什么”版本过滤 主题限定 检索CoreNote 可以将 Embedding 向量检索与 BM25 关键词检索组合为混合检索并在候选结果上进行去重、重排序和父文段回溯。这里的核心不是“用了多少模型”而是向量检索负责语义相近BM25负责精确术语Reranker在条件允许时提高候选排序质量父文段补足子 chunk 缺失的限定条件元数据防止把错误主题、旧版本或不适用资料混进来。十、持续追问不等于无限拼接聊天记录例如用户先问这个项目的部署限制是什么接着问那内存不足时应该先处理哪一步第二句话里的“那”依赖上一轮主题但答案仍然应该回到知识库重新找资料部署文档、资源限制、运行日志、历史 Badcase 等。若只是把过去所有对话无限塞进 Prompt历史结论会越来越多反而容易跑题和混淆。更可控的做法是保留必要的对话摘要、已确认条件和待解决问题将指代补全为更明确的检索查询继续从当前有效资料中召回证据回答时继续展示来源线索证据不足时承认不确定提示补充资料或人工确认。这就是“可持续追问”比普通聊天窗口更有价值的地方。十一、上线后的最小健康检查清单应用显示Up并不等于系统已经可用。一个最小检查可以分成四层。1. 容器层docker-composepsdockerstats --no-stream检查应用是否运行、是否健康、内存是否接近上限。2. 应用层curl-fsShttp://127.0.0.1:8080/api/v1/health如果是容器内服务可从容器内部或同一 Docker network 验证。实际 health endpoint 以项目配置为准。3. 反向代理与域名层curl-kIshttps://your-domain.example/curl-kLshttps://your-domain.example/robots.txtcurl-kLshttps://your-domain.example/sitemap.xmlcurl-kLshttps://your-domain.example/llms.txt这一步不只是在做 SEO。它也能证明反向代理、HTTPS、静态文件和应用路由是否正确连通。4. 业务层用一份公开或脱敏资料完成一次完整验证导入检查文件是否出现在对应知识空间用一个明确问题检索核验回答关联的文件或上下文再追问一个依赖上一轮主题的问题记录遗漏、错误引用或格式解析问题。如果只测“首页能打开”很多资料链路的错误不会暴露出来。十二、把错误当作知识库的一部分Badcase 要沉淀每次发生下面的情况都值得记录重要文件没有被召回旧版本文件排在新版本前表格被解析成没有含义的碎片关键词命中了但语义不相关回答缺少前提、例外或来源模型在证据不足时补写了结论部署因内存、构建、网络或配置不一致而失败。一个简短的 Badcase 模板可以是## Badcase旧版部署规范被错误召回 - 日期2026-09-27 - 问题询问“当前部署限制”时回答引用了旧版本规范 - 正确资料2026-09 版本部署说明 - 根因猜测旧版本未归档版本元数据缺失检索没有优先当前资料 - 修复动作标记旧文件 archived补齐版本/更新时间增加回归问题 - 验证问题当前部署限制是什么请给出资料来源和版本。Badcase 不是失败记录而是下一轮文档治理、分块策略、检索规则和评测集的来源。十三、一个可执行的最小部署顺序如果你从零部署个人知识库建议不要一上来导入几十 GB 文件也不要一开始同时启用所有解析和自动化能力。按下面顺序更稳妥确认机器资源检查内存、磁盘、Docker 状态和端口先构建一次确保只有一个构建流程在跑启动单个应用 worker先追求稳定不追求虚高并发检查健康接口与公网入口容器、代理、HTTPS、静态文件逐层验证导入少量脱敏资料一份 PDF、一篇 Markdown、一个项目文档即可设计十个真实问题包含关键词查询、语义查询、版本查询和追问记录 Badcase先改资料、元数据和检索边界再盲目换模型逐步扩容只有在确认瓶颈后再增加机器内存、调整容器限制或拆分服务。结语个人 RAG 的价值不在于让模型说得更像而在于让资料能被长期验证和复用把 PDF、Markdown 和项目资料放进知识库第一步只是开始。真正有价值的是资料有结构、有版本、有来源检索既能理解语义也能命中关键词回答可以回到原文核验系统遇到不知道的内容可以承认不确定部署问题和错误答案能够被记录、修复、复测。CoreNote 正在围绕这条路径演进让个人研究者、学生、AI 从业者、知识工作者和小团队把分散资料沉淀为可检索、可追问、可核验、可长期复用的知识工作台。如果你也在搭建个人 RAG 知识库欢迎交流你遇到的第一类问题资料太乱、检索不到、答案不可信还是服务器先扛不住官网https://corenote.cloud/知识指南https://corenote.cloud/knowledge-base.htmlGitHubhttps://github.com/zhangjianxin477/knowledge-hub 个人 RAG 知识库部署踩坑：PDF、Markdown 与项目资料如何做成可检索、可追问的知识工作台
我最初以为个人知识库的部署就是“起一个 Docker 容器上传 PDF然后调用模型”。真正运行后才发现问题并不止于模型 API构建镜像会卡住、依赖下载会断、容器会因内存不足被系统杀掉、旧资料会干扰新结论、回答看起来合理却找不到出处。这篇文章记录我为CoreNoteKnowledge Hub做个人 RAG 知识库部署和资料治理时最值得提前处理的一组问题资源、构建、资料准备、检索、来源核验与长期维护。官网https://corenote.cloud/知识指南https://corenote.cloud/knowledge-base.html开源仓库https://github.com/zhangjianxin477/knowledge-hub本文是个人项目/小团队场景的实践复盘不是“任意配置都可稳定运行”的承诺。涉及生产数据、模型回答、权限和安全的决策仍需要根据自己的环境测试与人工核验。一、先说结论个人知识库的难点不在“聊天”而在稳定的资料链路一个可长期使用的个人 RAG 知识库至少要同时解决五件事资料进得来PDF、Markdown、网页、项目文档等能被整理进同一知识入口资料找得到既能理解自然语言问题也能命中错误码、版本号、项目名、条款编号等精确词答案回得去回答要能关联文件、标题或上下文便于回到原始资料核验资料不会越用越乱新旧版本、重复文件、主题关系、归档状态必须可管理服务能活下来构建、解析、索引和模型调用都会占资源小内存服务器尤其需要有意识地控制并发和依赖体积。所以 CoreNote 的目标不是做一个“上传文档就能聊天”的页面而是把资料导入、文件组织、知识图谱、检索问答、持续追问与证据核验放进一条可复用的知识工作流中。二、架构先拆清楚不要把所有事情都交给大模型我目前把个人知识库看成如下链路PDF / Markdown / 网页 / 项目资料 ↓ 文件格式路由、解析、清洗、结构化 ↓ 来源 / 主题 / 时间 / 版本等元数据绑定 ↓ 父子分块、去重、Embedding、索引 ↓ 查询理解与检索路由 ↓ 向量检索 BM25 关键词检索 可选重排序 ↓ 回溯父文段、组装来源上下文 ↓ 基于证据回答、持续追问、低置信度降级 ↓ 记录 Badcase反向优化资料与检索这里没有哪一步是“可有可无”的装饰。不清洗 PDF分块和召回都会被页眉页脚、断行、目录页干扰不保留版本旧规则和新规则可能一起被召回只用向量检索专有名词和编号可能漏掉只用关键词检索语义相近的表达又容易找不到不保留来源线索最终得到的只是一个无法验证的段落不记录失败样本系统每次“答错”都无法转化为下一轮改进。三、第一个真实坑容器Exit 137不是“应用自己退出了”在一次部署中应用容器显示Exit 137同时在系统日志里可以看到类似Out of memory: Killed process ... (uvicorn)这说明当时并不是 Uvicorn 正常结束而是 Linux 的 OOM Killer 在全局内存紧张时杀掉了进程。137通常意味着进程收到SIGKILL但排查时不要只看到这个数字就下结论应该把它和内核日志、容器状态、内存占用一起看。1. 先确认容器状态docker-composeps-a重点看容器是否为Exit 137、Restarting或Up (healthy)反向代理容器是否仍然正常应用容器是否在频繁重启。2. 再看 Docker 记录的退出原因APP_ID$(docker-composeps-qtenant-a)dockerinspect$APP_ID\--formatexit{{.State.ExitCode}} oom_killed{{.State.OOMKilled}} started{{.State.StartedAt}} finished{{.State.FinishedAt}}如果oom_killedtrue说明 Docker 已经明确记录为内存不足导致的终止。3. 最后看系统层面的 OOM 日志dmesg-T|grep-Eiout of memory|oom-killer|killed process|tail-n80在部分系统上也可以尝试journalctl-k--no-pager|grep-Eiout of memory|oom-killer|killed process|tail-n80如果看到了Killed process ... uvicorn就可以把重点从“业务代码报错”转向“系统内存与负载控制”。四、为什么“明明设置了 deploy.resources”Docker Compose 仍然告警我的 Compose 输出曾出现类似警告WARNING: The following deploy sub-keys are not supported and have been ignored: resources.reservations.cpus这里的关键不是忽略警告而是理解它在说什么Compose 文件里写了资源声明不代表当前运行方式真的执行了全部资源约束。deploy段最初主要服务于 Swarm 部署模型不同 Docker Compose 版本、不同运行模式和不同子字段支持情况会不一样。尤其是老版本docker-compose经常会出现“配置写了但某个子字段被忽略”的情况。因此部署时建议分成两件事声明资源预期在 Compose 中表达服务希望的内存和 CPU 边界验证资源是否实际生效用运行时命令检查容器状态、实际限制和内存占用而不是只相信 YAML。下面的命令能快速看出当前实时资源占用dockerstats --no-streamfree-hdf-h如果你使用 Compose建议同时阅读自己所用版本对应的官方 Compose 文档而不是直接复制网上针对 Swarm 或旧版 Compose 的配置片段Docker Composedeploy参考https://docs.docker.com/reference/compose-file/deploy/Docker Compose 命令参考https://docs.docker.com/reference/cli/docker/compose/up/一个很容易误判的点“给容器加了 2G 限制”不等于“服务器一定有足够 2G 可用”。容器的内存上限是在主机总资源内分配的同一台机器上还可能有 Nginx、Docker daemon、系统缓存、其他容器、构建进程、日志和后台服务。没有 swap 或剩余内存很少时系统依然可能触发 OOM。五、小内存服务器的实用原则减少峰值而不是只改一个参数个人部署最容易忽视的是构建期、启动期、文档解析期和模型调用期的内存峰值并不相同。1. 保持单 Worker 是合理的起点CoreNote 的轻量启动命令使用了uvicorn app.main:app--host0.0.0.0--port8080--workers1--no-access-log在小内存机器上--workers 1的意义是避免多个 Python worker 同时加载应用依赖和运行时状态。它不能从根本上解决所有内存问题但比盲目提高 worker 数更适合作为起点。不要为了“看起来更高并发”直接把 worker 开大。对个人知识库而言稳定地完成导入、检索和问答比同时启动多个进程更重要。2. 解析和索引要避免同时处理大量文件PDF 解析、表格处理、Embedding、向量索引和 LLM 请求都可能占用较多内存。更稳妥的做法是先用少量真实资料验证流程大文件和批量文件拆分导入导入期间观察docker stats与free -h发生 OOM 时先降低并发和批量规模再讨论是否需要升级机器不要把“重启容器”当成长期解决方案。3. 控制数值计算库的隐式线程如果环境中包含 NumPy、scikit-learn 或其他数值计算依赖隐式并行也可能增加资源波动。项目的稳定性配置里可以保守地设置OPENBLAS_NUM_THREADS1 OMP_NUM_THREADS1 MKL_NUM_THREADS1这不是性能优化万能钥匙但在单核或低内存环境下能够减少某些任务突然拉起过多计算线程的概率。4. 先留出构建空间再构建镜像构建镜像时会同时存在下载层、中间层、构建上下文和旧镜像。磁盘空间不足会让构建报错或极慢网络慢则可能表现为依赖下载长时间没有进度。建议构建前先看df-hdockersystemdf清理前一定要先确认哪些镜像/容器仍在使用。不要直接复制破坏性清理命令在个人服务器上误删数据卷比“多占一点镜像空间”更麻烦。六、第二个真实坑构建卡在pip install不等于已经死掉部署时我遇到过日志长时间停在RUN pip install --no-cache-dir -r requirements-lite.txt或者某个大一点的 Python wheel / 源码包下载阶段。此时第一反应不应该是不断重复执行构建命令因为很可能会出现多个 Docker build 与 pip 进程同时跑反而占用更多网络、CPU、磁盘和内存。先确认有没有构建仍在运行ps-ef|grep-Edocker-compose|docker build|pip install|grep-vgrep如果还能看到docker build .../usr/local/bin/pip install ...或运行中的docker-compose up -d --build ...说明它并不是“卡死后什么都没发生”而是还在下载、编译或等待网络。此时应观察日志而不是再启动第二个构建。用日志观察不要在日志行前面输入命令如果使用后台构建nohupdocker-composebuild tenant-a/root/corenote-build.log21/dev/null观察方式是tail-f/root/corenote-build.log当你看到类似Step 7/27 : COPY frontend/ ./frontend/的输出时它只是日志不是要复制粘贴回终端执行的命令。等待构建完成并出现Successfully built、Successfully tagged后再执行容器重建。为什么不要一边构建一边强制重建同一个服务如果同时存在多个 build/recreate 流程常见后果有重复下载相同依赖构建缓存彼此争抢当前正常容器被提前停止老版本容器与新镜像状态难以判断小内存机器的资源峰值变得更高。更安全的顺序是确认没有旧构建 → 单独完成 build → 确认镜像生成 → 停止/移除旧应用容器 → 使用--no-build启动新容器 → 健康检查。七、构建上下文过大时问题不止是慢Docker 在构建前会把“构建上下文”发送给 Docker daemon。曾经出现过Sending build context to Docker daemon 801.4MB这说明需要关注.dockerignore是否真的排除了无关文件。对个人知识库项目来说下面这些目录通常不应该进入镜像构建上下文本地数据目录、上传文件、向量库Python 虚拟环境Git 历史与测试缓存备份文件、日志、模型文件部署环境里的真实.env与运行镜像无关的文档、演示素材和临时导出物。一个基础.dockerignore的方向可以是__pycache__/ *.pyc .git/ .venv/ venv/ data/ deploy/**/data/ deploy/**/backups/ *.log .env .env.* !.env.example注意Dockerfile.free.dockerignore这个命名并不会自动被 Docker 当作Dockerfile.free的忽略规则。Docker 默认读取构建上下文根目录的.dockerignore是否支持 Dockerfile 专属 ignore 文件要看你实际使用的 Docker/BuildKit 行为和命令。部署前要用构建日志中的Sending build context大小来验证而不是只凭文件名判断。有关构建缓存与构建上下文的官方说明可参考https://docs.docker.com/build/cache/八、资料导入前的准备比“换一个更大的模型”更重要真正影响问答质量的往往是资料本身是否适合被检索。1. Markdown给人看的笔记也要给检索系统留结构推荐让 Markdown 至少具备--- title: 项目部署说明 project: CoreNote version: 2026-09 status: active updated_at: 2026-09-27 --- # 部署前检查 ## 内存与磁盘 ...不一定需要固定这套 Frontmatter但应尽量保留标题、主题/项目、版本、状态、日期和清晰的标题层级。这样后续切分、过滤和来源展示都会更可靠。2. PDF优先导入“正文可复制、版本明确”的资料扫描件、复杂双栏、跨页表格和带大量页眉页脚的 PDF 并不是不能用但应预期解析质量会下降。对关键材料建议保留原始 PDF需要时同时准备人工整理的 Markdown 摘要明确文件版本与发布日期不要让“最终版”“最终版2”“最终版最终”成为唯一版本策略。3. 项目资料给结论补上适用范围很多项目文档的问题不在于没有答案而是缺少前提。将下面内容写清楚检索回答才不容易过度泛化此规则适用于哪个版本、哪个环境输入/输出示例是什么已知异常和例外情况结论由谁确认、是否仍然有效相关文件、接口、Issue 或决策记录在哪里。九、检索阶段向量和关键词不要二选一个人知识库中常见的两类问题对检索的要求不同用户问题更有价值的检索方式“有没有和这个研究方向相近的资料”向量语义检索“错误码 1305 出现在哪个文档”关键词检索“某项规则的例外条件是什么”结构化分块 父文段回溯“上次提到的部署限制还有什么”对话上下文 再检索“最新版 SOP 是什么”版本过滤 主题限定 检索CoreNote 可以将 Embedding 向量检索与 BM25 关键词检索组合为混合检索并在候选结果上进行去重、重排序和父文段回溯。这里的核心不是“用了多少模型”而是向量检索负责语义相近BM25负责精确术语Reranker在条件允许时提高候选排序质量父文段补足子 chunk 缺失的限定条件元数据防止把错误主题、旧版本或不适用资料混进来。十、持续追问不等于无限拼接聊天记录例如用户先问这个项目的部署限制是什么接着问那内存不足时应该先处理哪一步第二句话里的“那”依赖上一轮主题但答案仍然应该回到知识库重新找资料部署文档、资源限制、运行日志、历史 Badcase 等。若只是把过去所有对话无限塞进 Prompt历史结论会越来越多反而容易跑题和混淆。更可控的做法是保留必要的对话摘要、已确认条件和待解决问题将指代补全为更明确的检索查询继续从当前有效资料中召回证据回答时继续展示来源线索证据不足时承认不确定提示补充资料或人工确认。这就是“可持续追问”比普通聊天窗口更有价值的地方。十一、上线后的最小健康检查清单应用显示Up并不等于系统已经可用。一个最小检查可以分成四层。1. 容器层docker-composepsdockerstats --no-stream检查应用是否运行、是否健康、内存是否接近上限。2. 应用层curl-fsShttp://127.0.0.1:8080/api/v1/health如果是容器内服务可从容器内部或同一 Docker network 验证。实际 health endpoint 以项目配置为准。3. 反向代理与域名层curl-kIshttps://your-domain.example/curl-kLshttps://your-domain.example/robots.txtcurl-kLshttps://your-domain.example/sitemap.xmlcurl-kLshttps://your-domain.example/llms.txt这一步不只是在做 SEO。它也能证明反向代理、HTTPS、静态文件和应用路由是否正确连通。4. 业务层用一份公开或脱敏资料完成一次完整验证导入检查文件是否出现在对应知识空间用一个明确问题检索核验回答关联的文件或上下文再追问一个依赖上一轮主题的问题记录遗漏、错误引用或格式解析问题。如果只测“首页能打开”很多资料链路的错误不会暴露出来。十二、把错误当作知识库的一部分Badcase 要沉淀每次发生下面的情况都值得记录重要文件没有被召回旧版本文件排在新版本前表格被解析成没有含义的碎片关键词命中了但语义不相关回答缺少前提、例外或来源模型在证据不足时补写了结论部署因内存、构建、网络或配置不一致而失败。一个简短的 Badcase 模板可以是## Badcase旧版部署规范被错误召回 - 日期2026-09-27 - 问题询问“当前部署限制”时回答引用了旧版本规范 - 正确资料2026-09 版本部署说明 - 根因猜测旧版本未归档版本元数据缺失检索没有优先当前资料 - 修复动作标记旧文件 archived补齐版本/更新时间增加回归问题 - 验证问题当前部署限制是什么请给出资料来源和版本。Badcase 不是失败记录而是下一轮文档治理、分块策略、检索规则和评测集的来源。十三、一个可执行的最小部署顺序如果你从零部署个人知识库建议不要一上来导入几十 GB 文件也不要一开始同时启用所有解析和自动化能力。按下面顺序更稳妥确认机器资源检查内存、磁盘、Docker 状态和端口先构建一次确保只有一个构建流程在跑启动单个应用 worker先追求稳定不追求虚高并发检查健康接口与公网入口容器、代理、HTTPS、静态文件逐层验证导入少量脱敏资料一份 PDF、一篇 Markdown、一个项目文档即可设计十个真实问题包含关键词查询、语义查询、版本查询和追问记录 Badcase先改资料、元数据和检索边界再盲目换模型逐步扩容只有在确认瓶颈后再增加机器内存、调整容器限制或拆分服务。结语个人 RAG 的价值不在于让模型说得更像而在于让资料能被长期验证和复用把 PDF、Markdown 和项目资料放进知识库第一步只是开始。真正有价值的是资料有结构、有版本、有来源检索既能理解语义也能命中关键词回答可以回到原文核验系统遇到不知道的内容可以承认不确定部署问题和错误答案能够被记录、修复、复测。CoreNote 正在围绕这条路径演进让个人研究者、学生、AI 从业者、知识工作者和小团队把分散资料沉淀为可检索、可追问、可核验、可长期复用的知识工作台。如果你也在搭建个人 RAG 知识库欢迎交流你遇到的第一类问题资料太乱、检索不到、答案不可信还是服务器先扛不住官网https://corenote.cloud/知识指南https://corenote.cloud/knowledge-base.htmlGitHubhttps://github.com/zhangjianxin477/knowledge-hub