Docker 部署

本文档将指导你在 Docker 环境下部署 Max-Search 项目的后端服务，并初始化数据库所需的环境。同时，还将介绍前端的运行方式。

1. 安装 PostgreSQL

在部署后端前，需要准备好 PostgreSQL 数据库，并确保其支持向量扩展。
你可以参阅官方文档或 tio-boot 的 PostgreSQL 教程 进行安装和基本配置。

2. 初始化数据库

  1. 创建数据库
    在 PostgreSQL 中创建名为 max_kb 的数据库：

    CREATE DATABASE max_kb;

  2. 切换到新数据库

    \c max_kb

  3. 启用向量扩展

    CREATE EXTENSION IF NOT EXISTS vector;

    确保在 max_kb 数据库中已成功安装 vector 扩展。

  4. 导入初始化数据
    将 db/init.sql 文件导入到 max_kb 数据库：

    psql -U <username> -d max_kb -f db/init.sql

    其中 <username> 替换为你的 PostgreSQL 用户名。

3. 部署后端

在完成数据库配置后，你可以使用 Docker 部署 Max-Search 后端容器。以下是基本的启动命令示例：

docker run -dit --net=host --name max-search-web \
  -e JDBC_URL=jdbc:postgresql://<ip>/max_kb \
  -e JDBC_PSWD=<your_database_password> \
  -e TAVILY_API_TOKEN=<tavily_api_token> \
  -e VOLCENGINE_API_KEY=<volcengine_api_key> \
  -e GEMINI_API_KEY=<gemini_api_key> \
  litongjava/max-search-web:1.0.0

说明：

  1. --net=host 参数表示容器将使用主机网络。你也可以根据需求修改网络模式。
  2. <ip> 替换为实际数据库的 IP 地址或域名，如果数据库在同一台机器上，可使用 localhost。
  3. <your_database_password> 替换为 PostgreSQL 数据库的密码。
  4. VOLCENGINE_API_KEY 火山引擎 DeepSeek Api Key
  5. GEMINI_API_KEY Google Gemini 引擎 Key
  6. `TAVILY_API_TOKEN 搜索引擎 TAVILY Api Key

当容器正常启动后，即可在浏览器或其他客户端通过相应端口访问后端服务。

4. 启动前端

目前前端暂不支持 Docker 部署，需要在本地或其他环境中直接运行。以下为大致步骤：

  1. 编辑配置文件
    在前端项目根目录的 .env.development（或对应的环境配置文件）中添加以下内容：

    NEXT_PUBLIC_API_URL=https://app-api.maxsearch.ai/api

    其中 NEXT_PUBLIC_API_URL 为后端服务地址，如你在本地测试，可将其改为 http://localhost/api 或其他真实后端地址。

  2. 启动前端

    yarn dev

    或者使用 npm：

    npm run dev

    前端将默认在 http://localhost:3000/（或配置的端口）启动服务。

5. 常见问题

  1. 数据库无法连接？

    • 请确保 JDBC_URL、数据库 IP、端口以及密码均正确无误。
    • 检查 PostgreSQL 是否允许远程连接（修改 pg_hba.conf 和 postgresql.conf）。

  2. 无法访问向量扩展？

    • 请确保在创建 max_kb 数据库后已执行 CREATE EXTENSION IF NOT EXISTS vector;。
    • 确认 PostgreSQL 版本支持该扩展。

  3. 后端服务无法访问？

    • 检查 Docker 容器是否启动正常，使用 docker logs max-search-web 查看日志。
    • 确认映射端口或网络配置是否正确。

  4. 前端无法请求后端 API？

    • 检查前端配置的 NEXT_PUBLIC_API_URL 是否和后端地址一致。
    • 确保后端已开启 CORS（跨域访问），或在前端和后端同域部署。

6. 结语

至此，你已完成 Max-Search 后端在 Docker 环境中的部署，并配置好了 PostgreSQL 数据库。前端目前不支持 Docker，可在本地环境或服务器上通过 Yarn/NPM 启动。若有更多疑问或遇到问题，可在项目的 GitHub Issues 中进行反馈，或查阅 tio-boot.com 上的相关文档获取帮助。

感谢你对 Max-Search 项目的关注与支持！祝你部署顺利、使用愉快。