MODSetter/SurfSense项目Docker部署完全指南

MODSetter/SurfSense项目Docker部署完全指南

SurfSense Highly Customizable AI Research Agent just like NotebookLM or Perplexity, connected to external sources such as search engines (Tavily), Slack, Notion, and more. 项目地址: https://gitcode.com/gh_mirrors/su/SurfSense

项目概述

MODSetter/SurfSense是一个基于现代Web技术栈构建的应用系统，采用Docker容器化技术实现快速部署。本文将详细介绍如何使用Docker Compose工具完成项目的完整部署流程。

环境准备

在开始部署前，请确保您的系统满足以下基础要求：

1. Docker环境：需要安装Docker引擎和Docker Compose组件
2. 硬件资源：建议至少4GB内存和2核CPU配置
3. 系统权限：当前用户需要具备执行docker命令的权限

环境变量配置详解

项目采用环境变量驱动的配置方式，主要分为以下几类：

前端服务配置

• FRONTEND_PORT：前端服务暴露的端口号，默认3000
• NEXT_PUBLIC_API_URL：前端访问后端API的基础地址

后端服务配置

• BACKEND_PORT：后端API服务暴露的端口号，默认8000

数据库配置

• POSTGRES_USER：PostgreSQL数据库用户名
• POSTGRES_PASSWORD：数据库密码
• POSTGRES_DB：默认数据库名称
• POSTGRES_PORT：数据库服务端口

pgAdmin配置

• PGADMIN_PORT：数据库管理工具端口
• PGADMIN_DEFAULT_EMAIL：管理员邮箱
• PGADMIN_DEFAULT_PASSWORD：管理员密码

配置方法推荐使用.env文件方式，可从项目中的示例文件复制创建：

cp .env.example .env

部署模式选择

项目提供两种典型的部署方案：

开发模式（全栈部署）

包含所有组件：

• 前端应用
• 后端API服务
• PostgreSQL数据库
• pgAdmin管理工具

启动命令：

docker compose up --build

生产模式（核心服务）

仅包含基础设施：

• PostgreSQL数据库
• pgAdmin管理工具

启动命令：

docker compose -f docker-compose.yml up --build

详细部署步骤

1. 初始化环境配置

   # 后端环境配置
   cp surfsense_backend/.env.example surfsense_backend/.env
   
   # 前端环境配置 
   cp surfsense_web/.env.example surfsense_web/.env
   

2. 构建并启动容器

   # 开发模式（前台运行）
   docker compose up --build
   
   # 生产模式（后台运行）
   docker compose -f docker-compose.yml up -d
   

3. 验证服务状态

   • 前端应用：访问 http://localhost:3000
   • 后端API：访问 http://localhost:8000
   • API文档：访问 http://localhost:8000/docs
   • 数据库管理：访问 http://localhost:5050

数据库管理指南

项目使用PostgreSQL数据库并集成了pgAdmin管理工具：

pgAdmin连接配置

1. 登录地址：http://localhost:5050
2. 创建新服务器连接：
   • 主机名：db（Docker网络内部名称）
   • 端口：5432
   • 用户名/密码：与.env中配置一致

数据库扩展

系统已预装pgvector扩展，支持向量数据类型操作。

运维管理命令

容器管理

# 停止所有服务
docker compose down

# 查看日志
docker compose logs -f [服务名]

# 重启特定服务
docker compose restart backend

容器内操作

# 执行后端测试
docker compose exec backend python -m pytest

# 执行前端代码检查
docker compose exec frontend pnpm lint

高级配置技巧

1. 自定义部署组合

   # 仅启动数据库相关服务
   docker compose up -d db pgadmin
   
   # 使用自定义覆盖文件
   docker compose -f docker-compose.yml -f custom-override.yml up -d
   

2. 端口冲突解决 修改.env文件中各服务的端口配置，确保不与本地已有服务冲突

3. 构建优化 开发过程中可使用--no-cache参数强制重新构建镜像：

   docker compose build --no-cache
   

常见问题排查

1. 权限问题：在Linux系统下可能需要使用sudo执行docker命令
2. 端口占用：检查端口冲突并调整环境变量配置
3. 数据库连接失败：确保pgAdmin中使用db作为主机名而非localhost
4. 依赖问题：可能需要根据具体错误调整前后端的Dockerfile配置

架构设计说明

项目采用Docker的标准覆盖机制：

• docker-compose.yml：定义基础服务（数据库+pgAdmin）
• docker-compose.override.yml：定义应用服务（前端+后端）

这种设计实现了：

• 生产/开发环境配置分离
• 更清晰的代码结构
• 灵活的部署组合能力

通过本指南，您应该能够顺利完成MODSetter/SurfSense项目的容器化部署。根据实际需求选择合适的部署模式，并善用提供的管理命令进行日常运维。

SurfSense Highly Customizable AI Research Agent just like NotebookLM or Perplexity, connected to external sources such as search engines (Tavily), Slack, Notion, and more. 项目地址: https://gitcode.com/gh_mirrors/su/SurfSense