自托管 SurfSense 如何配置一个 Google Cloud OAuth 应用启用 Drive、Gmail 与 Calendar 连接器？-开发者社区

自托管 SurfSense 如何配置一个 Google Cloud OAuth 应用启用 Drive、Gmail 与 Calendar 连接器？

【免费下载链接】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 实例上，Google Drive、Gmail 与 Google Calendar 三个连接器共用同一个 Google Cloud OAuth 应用：在 Google Cloud 控制台创建项目、启用对应 API、配置 OAuth 同意屏幕与客户端，再把 Client ID / Client Secret 和每个连接器的重定向 URI 写进 SurfSense 的.env，重启后三个连接器即可被工作区内所有用户连接。Drive 属于文件源，授权后文件出现在 Documents 侧边栏的Import菜单里，供你挑选并索引进知识库；Gmail 与 Calendar 则是 Agent 的实时工具，可搜索、读取、起草/发送邮件、搜索与管理日历事件。

这套配置只在自托管部署时需要。SurfSense Cloud 上这些连接已经配好，直接点Connect即可。

准备：确认部署方式与`.env`位置

重定向 URI 使用哪个地址取决于你的部署方式，这决定了 OAuth 客户端里要填哪一组 URI：

Docker 安装（默认公开地址http://localhost:3929，对应 compose 里LISTEN_HTTP_PORT的默认值 3929）；
手动安装使用后端地址（如http://localhost:8000）；
生产环境使用你的公开域名。

.env文件位置：用安装脚本部署时在./surfsense/.env，手动 clone 仓库部署时在docker/.env。仓库里的 docker/.env.example 内联注释了所有变量，本文后面的变量名均出自其中。

第一步：创建 Google Cloud 项目

打开 Google Cloud Console（console.cloud.google.com），选择一个已有项目或新建一个项目。

第二步：启用所需 API

进入APIs & Services>Library，搜索并启用：

People API（Google OAuth 本身必需，始终要启用）；
Google Drive API（Drive 连接器）；
Gmail API（Gmail 连接器）；
Google Calendar API（Calendar 连接器）。

只启用你计划使用的连接器的 API 即可——People API 是唯一"始终必需"的一项。

第三步：配置 OAuth 同意屏幕

进入APIs & Services>OAuth consent screen。
用户类型选择External（如果用的是 Google Workspace 则选 Internal）。
填写必填信息：App name填SurfSense，User support email与Developer contact information填你的邮箱。
点Save and Continue。
点Add or Remove Scopes，按下表添加范围：

Scope	用途
`openid`、`.../auth/userinfo.email`、`.../auth/userinfo.profile`	基础 OAuth（所有连接器共用）
`https://www.googleapis.com/auth/drive`	Drive 连接器
`https://www.googleapis.com/auth/gmail.modify`	Gmail 连接器
`https://www.googleapis.com/auth/calendar.events`	Calendar 连接器

注意写权限范围（drive、gmail.modify、calendar.events）是 Agent 能创建文件、发送邮件、管理事件的前提——文档说明这些写操作在聊天中始终会先征求你的确认。如果你只想要只读访问，改用drive.readonly、gmail.readonly和calendar.readonly，但对应的写工具将不可用。

第四步：创建 OAuth 客户端并登记重定向 URI

进入APIs & Services>Credentials。
点Create Credentials>OAuth client ID。
应用类型选择Web application。
Name填SurfSense。
在Authorized redirect URIs下，为计划启用的每个连接器各加一个 URI。Docker 安装（http://localhost:3929）下完整的一组是：

http://localhost:3929/api/v1/auth/google/drive/connector/callback http://localhost:3929/api/v1/auth/google/gmail/connector/callback http://localhost:3929/api/v1/auth/google/calendar/connector/callback

手动安装把前缀换成后端地址http://localhost:8000，生产环境换成你的公开域名。

点Create，从确认对话框中复制Client ID与Client Secret。

第五步：把凭据写入 SurfSense 的`.env`

编辑你的.env（surfsense/.env或docker/.env）。按 docker/.env.example 的结构，Client ID 与 Secret 位于 "Google OAuth" 段，三个重定向 URI 位于 "Connector OAuth Keys" 段：

# Google OAuth GOOGLE_OAUTH_CLIENT_ID=<你的 Client ID> GOOGLE_OAUTH_CLIENT_SECRET=<你的 Client Secret> # Connector OAuth Keys GOOGLE_CALENDAR_REDIRECT_URI=http://localhost:3929/api/v1/auth/google/calendar/connector/callback GOOGLE_GMAIL_REDIRECT_URI=http://localhost:3929/api/v1/auth/google/gmail/connector/callback GOOGLE_DRIVE_REDIRECT_URI=http://localhost:3929/api/v1/auth/google/drive/connector/callback

两点说明：

三个重定向 URI 的默认值与.env.example中的注释一致，即 Docker 部署下与第四步登记的 URI 相同；手动安装或生产环境需同步改为第四步骤中的地址。
按 Google 连接器文档，同一组 Client ID 和 Secret 被 Google 登录与三个连接器共享，只需填一次。.env.example中该段注释标注 "only if AUTH_TYPE=GOOGLE"，若你的实例登录模式不同，以.env.example中相应注释为准。
Client Secret 属于敏感凭据，不要公开分享。

重启并验证连接

修改.env后重启 SurfSense：

docker compose up -d

重启完成后三个 Google 连接器即处于可连接状态。按各自入口验证：

Gmail / Calendar：打开工作区的Connectors对话框，选择对应服务点Connect，完成 Google 授权后，连接卡片出现在Active标签页中，可看到实时状态；
Drive：它是文件源，不出现在连接器目录里。打开Documents侧边栏，点Import，选择 Google Drive，授权后浏览并勾选要导入的文件——文件被索引进知识库，与你的上传和笔记一起可被检索。

后续维护也在Connectors对话框中进行：token 过期时卡片会提示Reconnect重新授权；Disconnect会移除连接，对于 Drive 这类知识库连接器，断开时同时会删除它已索引的文档，操作前确认。