部署前准备与适用场景

FastGPT 是常见的 AI 知识库与智能问答平台，适合用于企业资料问答、客服辅助、内部文档检索、产品手册查询、研发知识沉淀等场景。它通常由 Web 服务、数据库、向量检索组件、缓存服务和模型接口共同组成。对于生产环境来说，能否开机自动启动、异常后自动恢复、日志可控、资源占用稳定，往往比“能跑起来”更重要。

建议服务器至少准备 2 核 CPU、4GB 内存和 40GB 可用磁盘空间；如果知识库文档较多、并发问答较高，建议 4 核 8GB 起步。系统可选择常见 Linux 发行版，提前安装 Docker 与 Docker Compose。部署前还应准备模型接口地址、密钥、域名或内网访问地址，并规划好数据目录，避免后续迁移时找不到数据库文件和上传文件。

基础安装思路

稳定版部署推荐使用 Docker Compose。首先创建目录，例如 /opt/fastgpt，并将 compose 配置、环境变量文件和数据目录统一放在该路径下。目录结构建议包括 config、data、logs、backup 四类，分别用于配置、持久化数据、日志和备份。不要把数据库数据放在临时目录，也不要直接依赖容器内部路径保存关键数据。

安装 Docker 后，可执行 docker version 与 docker compose version 检查环境是否可用。随后拉取 FastGPT 所需镜像，准备 .env 文件。环境变量至少应包含管理端初始信息、数据库连接信息、模型接口地址、向量模型配置、文件上传限制、站点访问地址等。所有密码和密钥都应使用高强度随机字符串，不建议使用默认值。

首次启动可在部署目录执行 docker compose up -d，随后使用 docker compose ps 查看容器状态。若 Web 服务、数据库、缓存服务均为 running 或 healthy，再访问配置的站点地址进行初始化。初始化完成后，应立即修改默认管理员口令，并验证知识库创建、文件导入、向量化处理和问答调用是否正常。

配置 systemd 自动启动服务

仅使用 docker compose up -d 可以让服务运行，但服务器重启后是否按预期恢复，还需要结合系统服务管理。推荐为 FastGPT 创建 systemd 服务，让系统启动后自动执行 Docker Compose，并在异常退出时进行恢复。

可创建服务文件 /etc/systemd/system/fastgpt.service。核心配置思路是：WorkingDirectory 指向 /opt/fastgpt，ExecStart 使用 /usr/bin/docker compose up -d，ExecStop 使用 /usr/bin/docker compose down，Restart 设置为 on-failure，After 依赖 docker.service。配置完成后执行 systemctl daemon-reload，再执行 systemctl enable fastgpt.service 设置开机自启，最后执行 systemctl start fastgpt.service 启动。

验证自动启动是否生效，可执行 systemctl status fastgpt.service 查看状态；再执行 docker compose ps 查看容器是否已启动。若需要模拟重启，可先确认已有备份，再重启服务器，启动后检查服务、日志和站点访问情况。不要只看 systemd 显示 active，还要确认 FastGPT 页面、数据库连接和模型调用都能正常工作。

Docker Compose 稳定性设置

Compose 文件中建议为关键容器配置 restart: unless-stopped，这样在 Docker 服务恢复后容器也会自动拉起。对于数据库、缓存和 FastGPT 主服务，应明确 volumes 持久化路径，避免容器重建导致数据丢失。日志方面建议加入 json-file 日志轮转参数，例如单文件 50MB、保留 3 到 5 个文件，防止日志长期增长占满磁盘。

如果服务器资源有限，可为容器设置合理的内存上限。FastGPT 主服务建议预留 1GB 到 2GB，数据库根据文档量和并发量预留更多空间。不要把所有服务的内存上限加到超过物理内存，否则高峰期容易触发系统回收进程，表现为问答中断、文件解析失败或容器反复重启。

还应增加健康检查机制。Web 服务可以检查 HTTP 端口是否可访问，数据库可以检查连接是否可用。健康检查不是为了“装饰”，而是为了让运维人员尽早发现服务假死、连接池耗尽、磁盘写入异常等问题。

性能优化参数建议

FastGPT 的性能瓶颈通常出现在三处：文件解析与向量化、数据库检索、模型接口响应。优化时不要盲目调大并发，应先观察 CPU、内存、磁盘 IO 和接口耗时。小型服务器更适合控制并发，保证稳定；大型服务器则可以适当增加任务处理能力。

Node 服务可通过 NODE_OPTIONS 设置内存上限，例如根据服务器内存设置 --max-old-space-size=1024 或 2048。若导入大文档较多，可适当提高文件上传限制，但要同步限制单次任务数量，避免多个大文件同时解析造成内存峰值过高。

数据库方面，若使用 PostgreSQL 与向量扩展，可根据内存设置 shared_buffers 为总内存的约 20% 到 25%，work_mem 不宜过大，避免多连接时内存被快速放大。若使用 MongoDB，应关注 WiredTiger 缓存占用，并为数据目录使用性能稳定的磁盘。缓存服务可设置 maxmemory 与淘汰策略，避免缓存无限增长。

检索参数也会影响体验。知识库分段过短会增加索引数量，过长又可能降低命中精度。一般可从 500 到 1000 字左右的分段范围开始测试，并设置合适的重叠长度。召回数量不宜过大，常见场景可从 5 到 10 条开始，根据回答质量和延迟再调整。

反向袋里与访问配置

生产环境建议通过 Nginx 或同类网关统一访问 FastGPT。袋里层可以配置 HTTPS、请求体大小、超时时间和访问日志。上传文档时，如果袋里层限制过小，会出现前端提示上传失败，而后端日志没有明显错误的情况。因此需要同步调整 client_max_body_size、proxy_read_timeout、proxy_send_timeout 等参数。

如果仅在内网使用，可以只开放 Web 端口，不要把数据库端口暴露到公网。若需要外部访问，应使用可信证书和强口令，并定期检查登录记录。模型接口密钥、数据库密码和管理口令都不应写入公开文档或提交到公共代码仓库。

备份与升级策略

稳定运行离不开备份。至少需要备份数据库、上传文件目录、配置文件和 compose 文件。建议每天做一次自动备份，保留 7 到 14 天；重要知识库更新前，先手动创建快照。备份文件应放在独立目录或独立存储位置，不要只放在同一数据盘中。

升级前先查看版本说明，确认是否涉及数据库结构变化、环境变量调整或镜像名称变化。操作顺序建议为：停止写入任务，备份数据，拉取新镜像，执行 docker compose up -d，观察日志，验证核心功能。若升级后出现严重异常，可使用旧 compose 文件和旧镜像标签回滚，同时恢复对应备份。

常见问题排查

问题一：服务启动后页面打不开。先检查 docker compose ps 是否有容器退出，再查看 docker compose logs fastgpt 的错误信息；同时确认端口未被其他程序占用，袋里配置是否指向正确容器端口。

问题二：知识库导入一直处理中。重点检查解析服务日志、模型接口响应、向量库连接和磁盘空间。大文件建议拆分后导入，扫描版 PDF 可能需要额外识别流程，不宜直接作为高质量知识源。

问题三：问答很慢。先区分是检索慢还是模型返回慢。检索慢通常与数据库索引、向量数据量、磁盘性能有关；模型慢则与接口质量、上下文长度和并发有关。可先降低召回数量、减少上下文长度，再逐步调优。

问题四：重启后服务没有恢复。检查 systemctl is-enabled fastgpt.service 是否已启用，确认 docker 服务是否正常启动，服务文件中的 WorkingDirectory 是否正确。若 docker 路径不是 /usr/bin/docker，需要使用 which docker 查询实际路径并更新服务文件。

安全边界与运维建议

FastGPT 可能承载企业文档、客户资料和内部知识，权限管理必须前置。不同团队应分配独立账号和知识库权限，离职或项目结束后及时回收账号。不要把高敏感资料直接导入公开可访问的知识库，也不要让测试环境连接生产数据。

日常运维建议每周检查一次磁盘容量、容器状态、错误日志和备份可用性。性能优化应以监控数据为依据，先定位瓶颈，再调整参数。对于重要场景，可增加只读备份实例或预发布环境，所有升级先在预发布环境验证，再安排正式环境维护窗口。这样配置后的 FastGPT 不仅能自动启动，也能在长期运行中保持更好的稳定性和可维护性。

《夸克》非常好用的免费AI浏览器

下载APP查看