Dillinger 生产环境 OAuth 配置清单：五大云存储服务商的回调地址与环境变量完整指南

前端开发工具【免费下载链接】dillingerThe last Markdown editor, ever.项目地址https://gitcode.com/gh_mirrors/di/dillinger点击查看免费下载本文以 DillingerNext.js 版 Markdown 编辑器的生产部署为背景系统讲解 Google Drive、OneDrive、GitHub、Dropbox、Bitbucket 五类云存储 OAuth 应用在生产环境下的回调地址配置、Vercel 环境变量设置、部署后验证流程并结合仓库源码解析NEXT_PUBLIC_APP_URL如何驱动全部 OAuth 重定向、token 如何以 HTTP-only Cookie 安全落盘帮助你在上线前一次性补齐所有云存储集成。为什么生产环境必须重新配置 OAuthDillinger 是支持云端连接的 Markdown 编辑器其核心卖点在于与 Google Drive、OneDriveMicrosoft、GitHub、Dropbox、Bitbucket 的深度集成——用户可以直接在编辑器中连接账户、列出文件、保存文档并导入内容。在本地开发阶段这些 OAuth 应用通常只配置了http://localhost:3000的回调地址一旦部署到生产域名所有回调地址都必须同步更新否则用户在浏览器中完成授权后OAuth 服务商将把回调请求重定向到一个根本不存在的本地地址导致连接流程直接失败。这正是 docs/PRODUCTION-OAUTH-CHECKLIST.md 这份清单存在的意义它把上线前必须完成的 OAuth 配置浓缩为一张可逐项勾选的操作表。本文以该清单为骨架结合仓库源码app/api/*/oauth与app/api/*/callback路由、lib/env.ts 以及 tests/routes/github.route.test.ts 测试展开讲解。生产 URL 的统一格式所有服务的回调地址遵循同一套模式Base URLhttps://your-production-domain.com示例https://dillinger.vercel.appCallback 模式https://your-production-domain.com/api/{service}/callback也就是说五个服务的回调地址分别是https://your-production-domain.com/api/google-drive/callback https://your-production-domain.com/api/onedrive/callback https://your-production-domain.com/api/github/callback https://your-production-domain.com/api/dropbox/callback https://your-production-domain.com/api/bitbucket/callback这条规律在源码中可以得到直接印证五个服务的oauth路由都用同一个工具函数构造重定向 URI。NEXT_PUBLIC_APP_URL是所有回调的源头在 lib/env.ts 中Dillinger 提供了一个统一的 URL 解析函数const DEFAULT_APP_URL http://localhost:3000; export function getAppUrl() { return ( process.env.NEXT_PUBLIC_APP_URL || process.env.NEXT_PUBLIC_BASE_URL || DEFAULT_APP_URL ).replace(/\/$/, ); }该函数的读取顺序为NEXT_PUBLIC_APP_URL→NEXT_PUBLIC_BASE_URL→ 默认值http://localhost:3000并自动去除末尾的斜杠。所有 OAuth 路由如 app/api/github/oauth/route.ts、app/api/google-drive/oauth/route.ts都通过getAppUrl()拼接回调地址const redirectUri ${getAppUrl()}/api/github/callback;这正是清单中强调NEXT_PUBLIC_APP_URL是 CRITICAL 级别变量的原因只要该变量指向生产域名所有回调 URI 就会自动指向生产地址若漏配所有服务会静默回落到http://localhost:3000即使你在 OAuth 应用后台配好了生产回调也无济于事。各云服务商生产配置步骤下面按清单顺序逐一给出五个服务的配置操作、回调地址与环境变量。每个小节同时标注对应源码路径便于上线前交叉核对。Google Drive操作步骤勾选清单打开Google Cloud Console的「API 与服务 → 凭据」页面选择你的OAuth 2.0 Client ID添加生产环境的 Authorized redirect URIhttps://your-production-domain.com/api/google-drive/callback更新 Vercel 环境变量GOOGLE_CLIENT_IDyour_client_id GOOGLE_CLIENT_SECRETyour_client_secret NEXT_PUBLIC_APP_URLhttps://your-production-domain.com源码级细节授权入口 app/api/google-drive/oauth/route.ts 使用openid email https://www.googleapis.com/auth/drive作用域并设置access_typeoffline与promptconsent——前者确保首次授权即返回可用于刷新 access token 的 refresh_token后者强制每次授权都弹出确认页避免用户在切换账号后拿到错误的 token。回调路由 app/api/google-drive/callback/route.ts 将access_token、refresh_token与expires_at序列化为 JSON写入名为google_drive_token的 HTTP-only Cookie。OneDriveMicrosoft操作步骤勾选清单打开Azure Portal的「应用注册」列表选择你的应用注册App Registration进入「身份验证Authentication」→「添加平台Add a platform」→「Web」添加生产重定向 URIhttps://your-production-domain.com/api/onedrive/callback更新 Vercel 环境变量ONEDRIVE_CLIENT_IDyour_client_id ONEDRIVE_CLIENT_SECRETyour_client_secret NEXT_PUBLIC_APP_URLhttps://your-production-domain.com源码级细节授权入口 app/api/onedrive/oauth/route.ts 请求User.Read Files.ReadWrite.All offline_access三个作用域并将授权端点指向https://login.microsoftonline.com/consumers/oauth2/v2.0/authorize——源码注释明确说明/consumers/面向个人 Microsoft 账户outlook.com、live.com、hotmail.com若你的 Azure AD 应用同时支持工作/学校账户与个人账户则需要改用/common/端点。回调路由 app/api/onedrive/callback/route.ts 与 Google Drive 同样将 token 以 JSON 形式存入onedrive_tokenCookie。配置前请先确认目标用户群端点选错会导致登录页报错。GitHub操作步骤勾选清单打开GitHub Developer Settings开发者设置选择你的OAuth App或为生产环境新建一个更新 Authorization callback URLhttps://your-production-domain.com/api/github/callback更新 Vercel 环境变量GITHUB_CLIENT_IDyour_client_id GITHUB_CLIENT_SECRETyour_client_secret NEXT_PUBLIC_APP_URLhttps://your-production-domain.com源码级细节授权入口 app/api/github/oauth/route.ts 固定请求scope repo,user其中repo用于读写用户的仓库文件user用于读取登录用户资料头像、名称等前端登录状态栏展示用。回调路由 app/api/github/callback/route.ts 将 access token 直接存入名为github_token的 HTTP-only Cookie过期时间 30 天并支持携带?github_connectedtrue或?github_error...参数重定向回首页让前端能够感知连接结果。GitHub 的 token 交换端点不接受application/x-www-form-urlencoded以外的内容类型因此源码中显式设置了Accept: application/json与Content-Type: application/json。Dropbox操作步骤勾选清单打开Dropbox App Console开发者后台选择你的应用在「OAuth 2」→「Redirect URIs」中添加https://your-production-domain.com/api/dropbox/callback更新 Vercel 环境变量DROPBOX_APP_KEYyour_app_key DROPBOX_APP_SECRETyour_app_secret NEXT_PUBLIC_APP_URLhttps://your-production-domain.com源码级细节Dropbox 是五个服务中唯一使用官方 SDK 构建授权流的服务。app/api/dropbox/oauth/route.ts 引入dropbox包中的DropboxAuth类const dbxAuth new DropboxAuth({ clientId }); const authUrl await dbxAuth.getAuthenticationUrl( redirectUri, undefined, code, // response_type授权码模式 offline, // token_access_type换取可刷新的 token undefined, undefined, false );code指定授权码Authorization Code模式offline表示需要 offline access即返回 refresh token——这两个参数决定了应用能否长期保持连接而无需用户反复授权。注意 Dropbox 的环境变量名与其余四家不同这里不是CLIENT_ID/SECRET而是DROPBOX_APP_KEY与DROPBOX_APP_SECRET配置时切勿张冠李戴。Bitbucket操作步骤勾选清单打开Bitbucket OAuth Consumers页面账户设置 → OAuth选择你的 OAuth consumer更新 Callback URLhttps://your-production-domain.com/api/bitbucket/callback更新 Vercel 环境变量BITBUCKET_CLIENT_IDyour_client_id BITBUCKET_CLIENT_SECRETyour_client_secret NEXT_PUBLIC_APP_URLhttps://your-production-domain.com源码级细节授权入口 app/api/bitbucket/oauth/route.ts 请求account repository作用域授权端点为https://bitbucket.org/site/oauth2/authorize。与 GitHub 类似Bitbucket 集成同样围绕列出仓库 → 读取文件 → 保存文件这一工作流设计作用域覆盖账户信息与仓库读写即可满足需求。Vercel 生产环境变量总览在 Vercel 控制台中需要为Production环境设置以下全部变量注意区分不同服务商之间的命名差异# Google Drive GOOGLE_CLIENT_ID GOOGLE_CLIENT_SECRET # OneDrive ONEDRIVE_CLIENT_ID ONEDRIVE_CLIENT_SECRET # GitHub GITHUB_CLIENT_ID GITHUB_CLIENT_SECRET # Dropbox DROPBOX_APP_KEY DROPBOX_APP_SECRET # Bitbucket BITBUCKET_CLIENT_ID BITBUCKET_CLIENT_SECRET # App URL (CRITICAL - used for all OAuth redirects) NEXT_PUBLIC_APP_URLhttps://your-production-domain.com # Node Environment NODE_ENVproduction几点提醒NEXT_PUBLIC_APP_URL的取值必须与 OAuth 应用后台填写的回调域名完全一致包含协议与域名如https://dillinger.vercel.app且不带末尾斜杠——getAppUrl()虽会自动去除末尾斜杠但最好在源头保持规范。NODE_ENVproduction不是装饰回调路由在写 Cookie 时正是依据它决定是否附加secure标志见下文源码解析同时 Next.js 生产构建也依赖该变量。建议同时为Preview与Development环境设置独立的、指向对应预览域名的NEXT_PUBLIC_APP_URL否则每次 PR 预览环境的 OAuth 回调都会指向生产域名。源码级验证OAuth 回调链与安全设计授权 → 回调的完整调用链以 GitHub 为例整个流程在仓库中清晰可循用户在编辑器侧边栏点击「Connect」前端请求GET /api/github/oauthapp/api/github/oauth/route.ts 校验GITHUB_CLIENT_ID是否存在缺失时返回 500 JSON 错误随后用getAppUrl()拼出redirectUri并302重定向到https://github.com/login/oauth/authorize?client_id...redirect_uri...scoperepo,user用户完成授权后GitHub 将用户浏览器重定向到https://your-production-domain.com/api/github/callback?code...app/api/github/callback/route.ts 用code向https://github.com/login/oauth/access_token换取 access token写入 HTTP-only Cookie最后重定向回/?github_connectedtrue。其余四个服务的链路完全同构差别仅在于授权端点、作用域与 Cookie 名称google_drive_token、onedrive_token、dropbox_token、bitbucket_token。Token 存储的安全设计所有回调路由的 Cookie 写入参数高度一致以 app/api/github/callback/route.ts 为例cookieStore.set(github_token, tokenData.access_token, { httpOnly: true, secure: process.env.NODE_ENV production, sameSite: lax, maxAge: 60 * 60 * 24 * 30, // 30 days path: /, });httpOnly: true防止浏览器脚本包括任何 XSS 载荷读取 tokensecure跟随NODE_ENV生产环境强制 HTTPS-only 传输sameSite: lax在防 CSRF 与可用性之间取得平衡token 有效期 30 天配合 Dropbox/Google/OneDrive 的 refresh token 机制可长期保持连接。这正是 CLAUDE.md 中OAuth Security准则token 存于 HTTP-only Cookie 而非 localStorage、所有 OAuth 流程走服务端路由的具体落地。测试用例如何验证回调链路仓库的 tests/routes/github.route.test.ts 通过 mockfetch与next/headers覆盖了 GitHub 集成的主要行为GET /api/github/status有 token 且 GitHub API 正常时返回connected: true与用户资料无 token 或 token 失效时返回connected: false——这是前端判断是否已连接的依据GET /api/github/repos无 token 返回 401缺少owner参数返回 400支持page/per_page分页参数透传GitHub API 出错时返回 500GET /api/github/orgs与GET /api/github/branches覆盖组织仓库列表与分支列表的获取与参数校验。在生产部署完成后你可以用同样的思路快速自检直接访问GET /api/github/status观察返回的connected字段是否为true。部署后的完整测试清单所有 OAuth 应用更新完毕并部署到生产后逐项验证以下内容对应清单原文可直接复制为上线验收单Test Google Drive连接 → 列出文件 → 保存文件 → 导入文件Test OneDrive连接 → 列出文件 → 保存文件 → 导入文件Test GitHub连接 → 列出仓库 → 列出文件 → 保存文件Test Dropbox连接 → 列出文件 → 保存文件 → 导入文件Test Bitbucket连接 → 列出仓库 → 列出文件 → 保存文件测试所有导出格式HTML、Markdown、PDF测试拖拽导入文件测试图片上传测试禅模式zen mode开关测试滚动同步开关测试夜间模式开关前五项是 OAuth 集成的主干流程务必每个服务都完整走一遍连接 → 浏览 → 读写后六项用于确认 OAuth 相关改动没有破坏编辑器核心功能导出、导入、上传、模式切换等。重要注意事项NEXT_PUBLIC_APP_URL是全局关键变量所有 OAuth 回调地址都由它拼接而来lib/env.ts漏配或配错会导致所有服务连接失败。本地开发地址可以保留OAuth 应用允许同时配置多个回调地址你可以在生产回调之外继续保留http://localhost:3000的回调开发与生产互不干扰。OAuth 应用支持多个回调 URI添加生产地址时不必删除 localhost 地址——这也是官方推荐做法避免破坏本地开发环境。部分服务商需要重新审核如果本次上线新增了 OAuth 作用域例如为 OneDrive 追加了新的 Graph API 权限部分应用可能需要重新提交审核并等待批准请预留时间。清理浏览器 Cookie部署后用户此前连接产生的旧 token 可能仍残留于浏览器 Cookie 中生产域名切换或作用域变更后建议提示用户重新连接账户以获取新 token。回调地址速查表五个服务的生产回调地址汇总如下可在各服务商后台逐一对号入座https://your-production-domain.com/api/google-drive/callback https://your-production-domain.com/api/onedrive/callback https://your-production-domain.com/api/github/callback https://your-production-domain.com/api/dropbox/callback https://your-production-domain.com/api/bitbucket/callback替换your-production-domain.com为实际部署域名后这组地址应当与 Vercel 上的NEXT_PUBLIC_APP_URL保持严格一致。全部配置完成后建议先部署一次空跑验证再按上文测试清单逐项验收即可确保五个云存储集成在生产环境全部就绪。赞分享前端开发工具【免费下载链接】dillingerThe last Markdown editor, ever.项目地址https://gitcode.com/gh_mirrors/di/dillinger点击查看免费下载相关推荐Gaffer实战案例基于道路使用数据的复杂网络分析Gaffer实战案例基于道路使用数据的复杂网络分析 Gaffer是一个支持属性聚合的大规模实体和关系数据库特别适合处理复杂网络数据的分析与挖掘。本文将通过道从克隆仓库到打开聊天窗口Text Generation Web UI 本地部署与调参笔记从克隆仓库到打开聊天窗口Text Generation Web UI 本地部署与调参笔记 Text Generation Web UI下文简称 TGW是一人工智能大模型本地部署模型推理服务AI 应用桌面应用工具调用FastAPI异常监控终极指南如何高效跟踪和调试API错误FastAPI异常监控终极指南如何高效跟踪和调试API错误 FastAPI作为现代Python Web框架不仅以高性能著称还提供了强大的异常监控和错误跟踪后端Web框架API设计上一篇Bash多行注释终极指南5种专业文档注释格式详解下一篇Cosmos-AnomalyGen-PCB-2B完全指南3步生成高质量PCB缺陷合成图像创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考