DeepTutor 本地部署教程：Docker、模型配置與程式碼執行安全設定

DeepTutor 是一個開源個性化學習系統，可以圍繞資料進行問答、研究和學習規劃，並透過程式碼執行生成 DOCX、PDF、PPTX 與 XLSX 檔案。它適合搭建個人學習助手，但本地部署時必須同時處理模型、搜尋、檔案儲存和程式碼執行許可權。

專案地址：HKUDS/DeepTutor

快速答案

首次部署建議使用倉庫提供的 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，並在不需要檔案生成時關閉宿主機子程序執行。