适用场景与准备工作

FastGPT 是常见的开源知识库问答与智能体搭建工具，免费方案通常指在自有服务器、本地电脑或云主机上自行部署开源版本，用于产品原型验证、内部资料问答、客服知识库测试、个人 AI 工作流搭建等场景。相比托管服务，自部署的优点是可控性更强，数据路径、模型接入、插件配置都能自行管理；缺点是需要维护运行环境、数据备份、版本升级和故障排查。

在开始安装或迁移前，建议先确认三件事：第一，机器资源是否足够，测试环境建议至少 2 核 CPU、4GB 内存，知识库数据较多时应预留更高内存与磁盘空间；第二，是否已安装 Docker 与 Docker Compose，因为多数 FastGPT 教程会采用容器化方式部署；第三，是否清楚当前数据目录位置。常见数据包括数据库卷、向量数据、对象存储文件、配置文件和日志目录，迁移时不能只复制应用目录，否则可能出现登录正常但知识库为空、文件无法预览、对话记录缺失等问题。

免费方案安装思路

免费自部署的核心流程可以概括为：下载部署文件、配置环境变量、启动依赖组件、访问后台初始化、接入模型服务、创建知识库并测试。新手不要急于修改太多配置，先使用官方示例文件跑通流程，再逐项调整域名、端口、模型 Key、文件存储路径等参数。

第一步，创建项目目录，例如 /opt/fastgpt，并把 docker-compose.yml、环境变量文件和初始化配置放在同一目录。第二步，检查 compose 文件中的服务，通常会包含 FastGPT 主服务、数据库、向量相关组件以及文件存储组件。第三步，编辑环境变量，重点关注访问地址、数据库连接、鉴权密钥、模型接口地址和默认管理员信息。密钥不要使用示例值，至少应使用随机长字符串，避免被他人猜到。

第四步，在项目目录执行 docker compose pull 拉取镜像，再执行 docker compose up -d 启动。启动后可用 docker compose ps 查看状态，用 docker compose logs -f fastgpt 观察主服务日志。第五步，通过浏览器访问配置好的地址，如果是首次安装，按页面提示完成初始化。第六步，进入模型配置页面，填入可用的大语言模型和向量模型参数，创建一个小型知识库，上传少量测试文档，确认解析、检索和回答流程正常。

为什么要迁移数据目录

数据目录迁移常见于三类情况：一是最初部署在系统盘，后期知识库文件增多导致空间不足；二是从测试机迁移到正式环境；三是需要把容器默认卷改为固定挂载目录，方便备份、审计和统一维护。对于 FastGPT 这类工具，目录迁移不只是搬文件，还涉及容器卷映射、权限、配置路径和依赖服务状态。

迁移前必须先梳理 compose 文件中所有 volumes 配置。若使用命名卷，例如 fastgpt_mongo_data、fastgpt_pg_data、minio_data，需要通过 docker volume inspect 查看真实宿主机路径；若使用绑定目录，例如 ./data/mongo:/data/db，则路径相对项目目录。建议把最终目录规划为 /data/fastgpt，并在其下区分 db、vector、object、config、logs、backup 等子目录，后续维护会清晰很多。

数据目录迁移全流程

第一步，记录当前状态。进入部署目录执行 docker compose ps，确认每个服务名称；再查看 docker-compose.yml 中的 volumes 段，把旧路径、新路径、容器内路径整理成表格。不要在服务运行时直接复制数据库目录，这样容易产生不一致数据。

第二步，完整备份。建议先导出配置文件与 compose 文件，再备份数据目录。可使用 tar 打包，也可用 rsync 复制到临时备份盘。若数据量较大，先做一次在线预复制，正式迁移时再停服增量同步，可缩短停机时间。备份完成后检查文件大小和目录数量，确认不是空目录。

第三步，停止服务。在部署目录执行 docker compose down。若担心误操作，可先执行 docker compose stop，确认没有新写入后再 down。对于重要环境，建议在业务低峰期操作，并提前告知使用者暂停上传文档和新建知识库。

第四步，创建新目录并复制数据。例如新目录为 /data/fastgpt，可先创建对应子目录，再用 rsync -aHAX 复制旧目录内容。复制完成后检查隐藏文件、权限和属主。容器内服务通常以特定用户运行，如果迁移后目录属于 root 且没有写权限，服务可能启动失败，日志中会出现 permission denied。此时应根据镜像要求调整 chown 或 chmod，不建议为了省事给全部目录设置过宽权限。

第五步，修改挂载配置。把 compose 文件中的旧路径改为新路径，例如将 ./data/mongo:/data/db 改为 /data/fastgpt/db/mongo:/data/db。多个组件都要逐项修改，尤其是对象文件目录和向量数据目录。修改后执行 docker compose config 检查配置是否能被正确解析，避免冒号、缩进或相对路径写错。

第六步，启动并校验。执行 docker compose up -d，然后查看各服务日志。重点验证四项：账号能否登录，历史知识库是否存在，已上传文件能否打开或重新解析，对话测试是否能检索到原有内容。若全部正常，再保留旧目录一段时间，不要马上删除。建议至少运行 3 到 7 天并完成一次新备份后，再清理旧数据。

回滚方案与安全边界

迁移一定要有回滚方案。最简单的做法是保留旧 compose 文件和旧数据目录，若新路径启动失败，立即停服，把 compose 文件恢复为旧路径，再启动服务。若已经产生新数据，则需要判断是继续修复新环境，还是丢弃迁移后的新增内容回到旧环境。为了减少这种两难情况，正式迁移期间应暂停用户写入。

安全边界方面，FastGPT 适合处理企业内部资料、产品文档、客服问答、学习笔记等内容，但不建议直接放入高敏资料。模型接口、管理后台和数据库端口不要裸露在公网；管理员密码、模型 Key、数据库口令应放在环境变量中并妥善保管；离职人员或临时测试账号要及时禁用。若需要对外提供服务，应加上访问控制、HTTPS、日志留存和限流策略，避免资源被滥用。

常见问题汇总

问题一：迁移后页面能打开，但知识库为空。通常是数据库目录没有迁移成功，或 compose 文件仍指向新建的空卷。检查 volumes 映射和 docker volume inspect 结果，确认容器读取的是原始数据副本。

问题二：文件列表存在，但预览或解析失败。多半是对象存储目录未迁移，或存储服务的访问地址、桶配置发生变化。检查文件存储组件日志，并确认旧目录中的对象文件已完整复制。

问题三：服务启动后不断重启。先看 docker compose logs 中的首个错误，不要只看最后一行。常见原因包括配置文件语法错误、端口被占用、目录权限不足、数据库未就绪、镜像版本不匹配。

问题四：迁移后检索效果变差。可能是向量数据目录缺失，系统重新建立了空索引；也可能是向量模型配置被改动，导致新旧向量不一致。应保持迁移前后的向量模型一致，必要时重新构建知识库索引。

问题五：能否只复制 FastGPT 主程序目录。不能。容器化部署中，真正重要的数据往往在挂载卷和依赖组件目录里，主程序目录通常只保存编排文件和配置。迁移时应以 compose 文件中的卷为准。

问题六：升级和迁移能否一起做。不建议。更稳妥的顺序是先在原版本完成数据目录迁移，确认稳定后再升级；或者先克隆一份测试环境，在测试环境完成升级验证。一次只改一个关键变量，排错成本最低。

实用建议

对于个人和小团队，最佳实践是从第一天就把数据放到独立目录，定期备份 compose 文件、环境变量和数据卷，并记录每次调整。安装完成后，不要只测试首页是否能打开，还要测试上传、解析、检索、对话、账号管理和重启恢复。迁移完成后，把旧路径、新路径、操作时间、镜像版本、模型配置和回滚方式写入运维记录，后续遇到故障会节省大量时间。

FastGPT 免费自部署并不复杂，难点在于数据边界和路径管理。只要做到迁移前盘点、迁移中停服复制、迁移后逐项校验，并始终保留可回退的备份，就能把安装和数据目录迁移的风险控制在可接受范围内。