DeepTutor 本地部署教程：Docker、模型配置与代码执行安全设置

DeepTutor 是一个开源个性化学习系统，可以围绕资料进行问答、研究和学习规划，并通过代码执行生成 DOCX、PDF、PPTX 与 XLSX 文件。它适合搭建个人学习助手，但本地部署时必须同时处理模型、搜索、文件存储和代码执行权限。

快速答案

首次部署建议使用仓库提供的 Docker Compose 配置，而不是直接把后端装进宿主机。Compose 方案会把模型生成的代码交给独立、低权限的 Runner Sidecar，隔离强度高于直接在宿主机运行受限子进程。

部署前准备：

Docker 与 Docker Compose；
至少一个受支持模型的 API Key；
可选的 Embedding 与搜索服务；
持久化的 data/ 目录；
只在可信网络开放的访问地址。

配置文件在哪里

DeepTutor 的用户配置位于 data/user/settings/，常见文件包括：

文件	用途
`model_catalog.json`	LLM、Embedding、搜索服务与 API Key
`system.json`	端口、CORS、SSL、附件目录与上传限制
`auth.json`	登录开关、用户名、密码哈希和会话设置
`integrations.json`	PocketBase 与 Sidecar 集成
`interface.json`	语言、主题和界面偏好

官方推荐通过浏览器设置页面修改这些文件。手工编辑 JSON 时不要整段覆盖现有配置，先备份并检查逗号、引号和模型 ID。

为什么要关注代码执行

DeepTutor 的 Office Skills 会让模型生成 Python 脚本，再通过 exec 或 code_execution 执行。这样才能用 python-docx、reportlab、openpyxl 等库生成文件，但也意味着模型可以运行代码。

本地直接运行时，默认受限子进程仍位于宿主机；Docker Compose 则会优先使用独立 Runner。若不需要 Office 文件生成功能，可以关闭宿主机子进程执行：

1

DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS=0

也可以在 data/user/settings/system.json 中把 sandbox_allow_subprocess 设置为 false。关闭后，依赖代码执行的文件生成能力会不可用。

三种运行形态怎样选

DeepTutor 的本地运行大致可以分为直接运行、单容器和 Docker Compose。选择时不要只比较安装命令，还要看模型生成代码在哪里执行。

方式	优点	主要风险	适合场景
本地直接运行	调试方便、改代码快	受限子进程仍在宿主机	开发和可信资料测试
单容器	依赖较集中	应用与代码执行仍在同一容器边界	单用户体验
Docker Compose	独立 Runner、隔离更清楚	配置项与容器更多	长期自托管

只要开启 DOCX、PDF、PPTX 或 XLSX 生成，就应优先考虑 Compose。即使在个人电脑使用，也不要把“模型不是恶意的”当成安全控制。

部署前的资源规划

DeepTutor 本身不一定在本机运行大模型，但文档解析、Embedding、文件生成和并发任务仍会消耗资源。建议提前确认：

附件目录放在哪个磁盘；
上传文件和生成文件的保留周期；
Runner 是否设置 CPU、内存和进程限制；
模型 API 的并发与费用上限；
搜索 Provider 是否有地区和配额限制；
是否需要为多用户开启认证。

如果接入本地模型，还要单独计算显存和上下文长度。聊天能回复不代表长 PDF、检索和文件生成能在同一配置下稳定运行。

模型配置的正确顺序

先配置主对话模型

在 model_catalog.json 或设置页面中添加 Provider、API 地址、Key 和模型 ID。先用短问题测试连接，确认没有 401、404 或模型名错误。

再配置 Embedding

知识库检索需要向量化。Embedding 模型与聊天模型是两类配置，不能因为聊天成功就跳过。更换 Embedding 模型后，旧索引可能需要重建，否则维度或语义空间不一致。

最后接入搜索

外部搜索会把查询发送给第三方服务。先明确资料是否允许出网，再配置搜索 Provider。处理内部文档时，可以关闭外部搜索，只使用上传资料。

首次启动后的验证流程

验证一：普通对话

提一个不需要工具的短问题，查看模型返回与日志。目的是确认 Provider、模型 ID 和网络连接。

验证二：资料问答

上传一份不含隐私的短 PDF，提问一个可以在文中直接找到答案的问题，再追问页码或依据。若回答与原文不符，检查解析、Embedding 和检索，而不是立即更换聊天模型。

验证三：文件生成

让系统生成一个只包含标题和表格的测试 DOCX，确认 Runner 日志、下载链接和输出文件。不要第一次就使用复杂 PPT 或包含敏感数据的表格。

验证四：重启恢复

重启容器后检查设置、会话、上传资料和生成文件是否仍在。若内容消失，说明持久化卷没有正确映射。

反向代理与认证

如果需要从局域网或公网访问，应先开启 auth.json 中的认证，再配置 HTTPS 反向代理。还要同步检查：

system.json 的公共 API 地址；
CORS 只允许实际使用的域名；
Cookie 的安全属性；
上传大小和请求超时；
WebSocket 或流式响应是否被代理正确转发；
管理页面是否对外暴露。

不要仅靠一个难猜的 URL 保护服务。公网 DeepTutor 同时拥有文档、模型 Key 和代码执行能力，认证是最低要求。

备份哪些内容

至少备份 data/user/settings/、用户资料、会话数据库和生成附件。API Key 可以通过安全的密钥管理重新注入，不一定要进入普通备份文件。

升级前建议：

停止新任务；
备份持久化目录；
记录当前镜像或提交版本；
阅读配置迁移说明；
升级后重新执行四项验证。

常见错误对照表

现象	可能原因	排查方向
页面正常但模型无响应	Key、模型 ID、API Base 错误	Provider 日志与 HTTP 状态码
能聊天但资料问答差	解析或 Embedding 未配置	文档文本、索引和检索结果
Office 文件生成失败	Runner、依赖或目录权限	Sidecar 日志与挂载目录
重启后资料消失	持久化卷错误	Compose Volume 与宿主机路径
反向代理后流式中断	缓冲、超时或 WebSocket	代理配置
CPU 持续占满	解析任务、Runner 或本地模型	容器资源和进程列表

常见问题

页面能打开但模型不回复怎么办？

优先检查 model_catalog.json 的 Provider、模型 ID、API 地址和 Key 是否匹配，再查看容器日志中的 401、404、超时或上下文长度错误。

为什么生成 DOCX 或 PDF 失败？

确认沙箱没有被关闭，并检查 Runner 是否正常、所需 Python 包是否存在、附件目录是否可写。若只是聊天正常而 Office Skills 失败，问题通常不在模型连接。

可以多人共用一个部署吗？

可以评估，但必须先确认版本的用户隔离能力。模型 Key、上传资料、会话和生成文件不能只靠界面区分；没有经过验证前，按单用户服务使用更安全。

使用本地模型就不会泄露数据吗？

不一定。外部搜索、Embedding、遥测和反向代理仍可能产生出站请求。要通过网络日志确认每个 Provider 的实际去向。

关闭子进程后哪些功能受影响？

普通聊天和不依赖执行的检索仍可使用，但通过 Python 生成 Office、PDF 等文件的能力会受影响。关闭前先列出团队真正需要的 Skills。

Runner 还需要哪些限制

独立 Runner 比宿主机子进程更安全，但容器本身仍要配置：

只读根文件系统或尽量减少可写目录；
非 root 用户；
不挂载 Docker Socket；
不挂载宿主机主目录；
限制 CPU、内存、进程数和执行时间；
默认禁止外网或只允许必要目标；
每个任务使用独立临时目录并及时清理；
日志不输出上传文档和凭据。

若 Runner 可以访问应用数据库、模型 Key 或宿主机 Docker，它的独立容器就失去了大部分隔离意义。

上传资料的生命周期

部署前要明确文件从上传到删除经历哪些位置：浏览器临时缓存、应用附件目录、解析结果、向量索引、会话记录、生成文件和备份。用户在界面删除原文件后，其他副本是否同步删除也要测试。

对于内部资料，建议设置明确保留周期，并把备份与删除策略写入运维文档。不能因为服务部署在本地，就忽略日志、缓存和快照中的数据副本。

上线前最小验收表

项目	通过标准
模型	短问答和长上下文均可用
检索	能返回正确片段和来源
Runner	文件生成在独立容器执行
持久化	重启后资料和配置仍存在
认证	未登录无法访问资料与接口
代理	HTTPS、流式响应和上传正常
备份	能恢复到单独测试实例
删除	原文件、索引和生成物按策略清理

只有这些项目都验证过，才算完成可长期使用的本地部署。

总结

DeepTutor 的部署重点不是“把容器跑起来”，而是把模型配置、持久化、认证和代码执行边界一起配置好。面向个人使用也应优先采用 Docker Compose 的独立 Runner，并在不需要文件生成时关闭宿主机子进程执行。