如何在 SurfSense Docker 部署中启用 NVIDIA GPU 加速？-育师

如何在 SurfSense Docker 部署中启用 NVIDIA GPU 加速？

【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense

SurfSense 官方推荐使用 Docker 部署（数据库、后端、前端、后台 worker、实时同步和反向代理均已预配置）。如果你的主机装有 NVIDIA GPU，可以让后端切换到 CUDA 镜像并让backend、celery_worker、celery_beat三个服务直接挂载 GPU。本文只讲一件事：在 Docker 部署中正确启用 GPU 加速，并确认服务健康地跑在 CUDA 变体上。

前置条件

Docker Desktop（或 Docker Engine + Compose）已安装并在运行；
主机装有 NVIDIA GPU，且nvidia-smi可用；
主机已安装 NVIDIA Container Toolkit。Docker 安装文档明确要求：使用 CUDA 后端镜像的主机必须有 NVIDIA Container Toolkit；
已有部署时，.env位于./surfsense/.env（安装脚本生成）或docker/.env（手动克隆仓库时）。

方式一：让安装脚本自动启用 GPU

SurfSense 提供的一行安装脚本（对应仓库中的 docker/scripts/install.sh，Linux/macOS 用 bash 版，Windows PowerShell 用 install.ps1）会主动处理 GPU：

脚本通过nvidia-smi检测 NVIDIA GPU；
检测 NVIDIA Container Toolkit 是否可用（检查docker info输出、nvidia-ctk或nvidia-container-runtime）；
检测到 GPU 时交互询问Use GPU acceleration? [Y/n]，回答 Y 后自动选择兼容的后端镜像变体。

脚本会根据驱动版本推荐变体：驱动主版本低于 570 时推荐cuda126（脚本注释说明 CUDA 12.8 一般需要 R570+ 驱动），否则推荐cuda。也可以跳过交互、显式指定：

bash install.sh --variant=cuda --gpu-count=1 --no-watchtower

参数说明（均来自脚本头部注释）：

--variant=cpu|cuda|cuda126：直接选择后端镜像变体；--gpu等价于--variant=cuda；
--gpu-count=N|all：启用 GPU 时预留的 GPU 数量，接受数字或all；
--no-watchtower：跳过自动每日更新（Watchtower 后台更新可能下载数 GB，不需要就加上此参数）。

注意：如果.env已经存在，脚本不会改动已有配置（它会提示To change variants later, edit SURFSENSE_VARIANT and COMPOSE_FILE）。已按 CPU 变体装好的环境，请改用下面的方式二手动切换。

方式二：手动在 .env 中启用

在 SurfSense 的.env文件中加入以下内容（Docker 安装文档给出的配置）：

SURFSENSE_VARIANT=cuda COMPOSE_FILE=docker-compose.yml:docker-compose.gpu.yml SURFSENSE_GPU_COUNT=1

然后执行：

docker compose pull && docker compose up -d --wait

三个配置项各做什么：

SURFSENSE_VARIANT：给后端镜像名追加-cuda后缀。docker/docker-compose.yml 中后端镜像为ghcr.io/modsetter/surfsense-backend:${SURFSENSE_VERSION:-latest}${SURFSENSE_VARIANT:+-${SURFSENSE_VARIANT}}，设为cuda后实际拉取的就是...-cuda镜像；
COMPOSE_FILE：叠加加载 docker/docker-compose.gpu.yml。该 overlay 给backend、celery_worker、celery_beat三个服务追加 GPU 设备预留（driver: ${SURFSENSE_GPU_DRIVER:-nvidia}、count: ${SURFSENSE_GPU_COUNT:-1}、capabilities: [gpu]）；
SURFSENSE_GPU_COUNT：预留的 GPU 数量，docker-compose.gpu.yml中默认为 1。

两个适用条件：

较老的 NVIDIA 驱动栈使用SURFSENSE_VARIANT=cuda126代替cuda；
Windows 上COMPOSE_FILE的分隔符用;而不是:，即COMPOSE_FILE=docker-compose.yml;docker-compose.gpu.yml。

如果走的是手动 Docker Compose 路径（克隆仓库后在docker/目录cp .env.example .env），确保.env中至少设置了SECRET_KEY（用openssl rand -base64 32生成），再按上面的命令启动。

验证结果

按文档给出的方式检查：

# 观察各服务状态：从 (health: starting) 变为 (healthy) docker compose ps # 查看某个服务的日志 docker compose logs -f backend

docker compose ps中各服务（包括backend）健康状态最终变为(healthy)，说明含 GPU 预留的栈已正常启动；
在docker compose ps输出中确认backend使用的镜像名带-cuda（或-cuda126）后缀，这能直接证明SURFSENSE_VARIANT生效；
启动完成后通过 Caddy 反向代理访问http://localhost:3929（后端 API 为http://localhost:3929/api/v1）确认服务可用。

限制与已知问题

检测到 GPU 但没有 NVIDIA Container Toolkit：脚本会打印NVIDIA GPU detected, but NVIDIA Container Toolkit was not detected，并回退到 CPU 变体，同时提示先安装 Toolkit 再启用 GPU 加速。手动方式下若不装 Toolkit，GPU 设备预留会在启动时失败，所以 Toolkit 是硬前提；
切换变体：文档明确说明后续切换方式就是编辑.env中的SURFSENSE_VARIANT和COMPOSE_FILE，然后docker compose up -d --wait；
更新时不会丢配置：Updating 文档说明.env中设置的 GPU overlay 与镜像变体在docker compose pull && docker compose up -d更新时会被保留；
端口冲突：如果 3929 端口被占用，改.env中的LISTEN_HTTP_PORT后重启。