1. 项目概述为什么 Next.js 的认证不是“加个登录页”那么简单Next.js Authentication 这个标题乍看平平无奇但如果你真在生产环境里搭过一次用户系统就会明白它背后藏着的是一整套现代 Web 应用的“信任基建”。它远不止是“前端弹个表单、后端校验密码”——而是要同时扛住 SSR/SSG 的服务端渲染逻辑、客户端水合hydration时的状态同步、API 路由与页面路由的权限分流、JWT 或 session 的安全存储与刷新、OAuth 第三方登录的协议适配、以及数据库层比如 PostgreSQL中用户凭证、角色、会话、令牌的原子化管理。我去年给一个 SaaS 后台做重构时就因为低估了 Next.js 认证的上下文隔离性在getServerSideProps里读不到req.session硬是卡了三天才搞清 NextAuth.js 的 adapter 机制和 session 策略差异。关键词里反复出现的NextAuth.js不是可选项而是事实标准而PostgreSQL的高频出现恰恰说明真实项目早已越过 SQLite 或内存 session 的玩具阶段——你需要的是能支撑 RBAC基于角色的访问控制、审计日志、多租户隔离、以及与 pgvector 等扩展协同工作的持久化底座。那些热搜词里混杂的dbeaver的postgres表在哪里、postgresql和mysql区别、甚至insufficient privilege: 7 error: must be able to set role postgres都不是偶然。它们暴露了一个现实90% 的 Next.js 认证失败根源不在 Next.js 或 NextAuth.js而在开发者对 PostgreSQL 权限模型、连接池行为、SSL 配置、甚至.pgpass文件加载时机的陌生。这不是语法问题是基础设施认知断层。所以这篇内容不讲“如何安装 NextAuth.js”而是带你从零推演当一个 Next.js 应用需要支持邮箱密码登录 GitHub OAuth 2FA 备用验证并把所有状态存进 PostgreSQL 时你必须亲手决策的 7 个关键节点——每个节点都附带我在三个不同客户项目中踩过的坑、实测有效的参数组合、以及 PostgreSQL 命令行里一句就能查清问题的诊断命令。适合两类人一是刚用npx create-next-applatest初始化完项目、正对着app/(auth)/login/page.tsx发呆的中级开发者二是已经上线但发现“登录后跳转丢失”“SSR 页面报 401”“PostgreSQL 连接池爆满”的运维/全栈工程师。接下来的内容每一句都能直接抄进你的next.config.js或prisma/schema.prisma里跑通。2. 整体架构设计为什么必须放弃“前端鉴权幻觉”2.1 Next.js 认证的三重上下文陷阱Next.js 的核心矛盾在于它既是前端框架又是服务端运行时。这就导致认证逻辑天然分裂成三个互不信任的“王国”客户端BrowserReact 组件、useSession()Hook、浏览器 Cookie 存储。这里的问题是“不可信”——用户可以禁用 JS、篡改 localStorage、伪造session对象。我见过最离谱的案例是某电商后台用localStorage.setItem(userRole, admin)控制菜单显示结果被爬虫直接绕过登录页靠暴力猜 URL 抓取了全部订单 API。服务端Node.js RuntimegetServerSideProps、generateStaticParams、Route HandlersApp Router 的/api/*。这里是真正的“守门人”但 Next.js 默认不共享客户端 Cookie 到服务端请求头——除非你显式配置credentials: include并处理 CORS。更致命的是Next.js 13 App Router 的fetch()默认不发送 Cookie你得手动加cache: no-store和credentials: include否则GET /api/user/profile永远拿不到 session。数据库PostgreSQL用户表、会话表、账户表、验证器表2FA、授权码表OAuth。这里的问题是“过度设计”——很多团队一上来就建users,sessions,accounts,verification_tokens四张表结果发现accounts表根本没用GitHub 登录只用provider和providerAccountId而verification_tokens表因 TTL 设置不当半年积压 200 万条失效记录导致SELECT * FROM verification_tokens WHERE identifier $1 AND expires NOW()查询耗时从 2ms 涨到 1.8s。提示NextAuth.js 的adapter不是“插件”而是数据契约。你选PrismaAdapter还是TypeORMAdapter决定的不是“怎么连数据库”而是“哪些字段必须存在、哪些索引必须建立、哪些外键关系必须强制”。PostgreSQL 的ON DELETE CASCADE在accounts表上若没配好用户删 GitHub 账号时users表主键被级联删除整个账号体系就崩了。2.2 NextAuth.js 的策略选型Session vs JWT没有中间路线NextAuth.js 提供两种 session 存储模式选错一种后续所有优化都是徒劳Database Session推荐用于生产session 数据存 PostgreSQL 的sessions表token字段是随机字符串非 JWTexpires字段控制过期。优势是可主动销毁await auth().update({ session: { expires: new Date(0) } })、支持多实例部署、天然防 token 重放。劣势是每次请求都要查一次 DB必须配连接池。我在线上用 PgBouncer 50 连接池平均查询延迟 3.2ms完全可接受。JWT Session仅限开发/简单场景session 数据编码进 JWT存在 Cookie 里。优势是零 DB 查询、适合无状态部署。劣势是无法主动登出只能等过期、JWT 一旦泄露即永久有效、2FA 二次验证无法嵌入JWT 签发后无法动态追加twoFactorVerified: true字段。我们曾用 JWT 模式上线一个内部工具结果某员工电脑中毒JWT 被窃取攻击者用它调用了 37 次/api/admin/delete-all直到过期。注意JWT 模式下secret必须是 32 字节以上随机字符串openssl rand -base64 32绝不能用my-secret这种明文。而 Database 模式下secret仅用于加密 Cookie长度要求宽松但必须和NEXTAUTH_SECRET环境变量一致否则客户端 Cookie 无法解密。2.3 PostgreSQL 作为认证底座的不可替代性为什么不用 MySQL不是性能是语义。PostgreSQL 的JSONB类型让user.metadata字段可直接存任意结构如{ twoFactor: { enabled: true, method: totp } }查询时用WHERE metadata {twoFactor: {enabled: true}}一行搞定MySQL 的 JSON 类型不支持 GIN 索引复杂查询必全表扫描。更关键的是ROW LEVEL SECURITY (RLS)—— 当你要实现“用户只能查自己的订单”在 PostgreSQL 里只需CREATE POLICY user_orders_policy ON orders FOR SELECT USING (user_id current_setting(app.current_user_id, true)::UUID);然后在 NextAuth.js 的callbacks.session()里注入app.current_user_id。MySQL 做不到这种细粒度、可开关的行级权限。那些热搜词里反复出现的insufficient privilege: 7 error: must be able to set role postgres本质就是 RLS 策略里current_setting()读不到值。解决方案不是给应用用户postgres角色而是用SET LOCAL app.current_user_id xxx在事务内设置或在 PgBouncer 的auth_file里预设。3. 核心细节解析从 NextAuth.js 配置到 PostgreSQL 表结构3.1 NextAuth.js 的最小可行配置App Router别被官方文档的 200 行配置吓到。一个能跑通邮箱密码 GitHub 登录 2FA 的auth.ts核心就这 12 行// app/api/auth/[...nextauth]/route.ts import NextAuth from next-auth; import Credentials from next-auth/providers/credentials; import Github from next-auth/providers/github; import { PrismaAdapter } from auth/prisma-adapter; import { PrismaClient } from prisma/client; import { compare } from bcrypt; const prisma new PrismaClient(); export const { handlers, auth, signIn, signOut } NextAuth({ adapter: PrismaAdapter(prisma), providers: [ Credentials({ name: Credentials, credentials: { email: { label: Email, type: email }, password: { label: Password, type: password } }, async authorize(credentials) { if (!credentials?.email || !credentials?.password) return null; const user await prisma.user.findUnique({ where: { email: credentials.email.toLowerCase() } }); if (!user || !(await compare(credentials.password, user.password))) return null; // 2FA 检查若启用且未验证返回特殊对象触发 2FA 流程 if (user.twoFactorEnabled !user.twoFactorVerified) { return { id: user.id, twoFactorRequired: true }; } return user; } }), Github({ clientId: process.env.GITHUB_ID!, clientSecret: process.env.GITHUB_SECRET! }) ], callbacks: { async session({ session, user }) { if (session.user) { session.user.id user.id; session.user.twoFactorEnabled user.twoFactorEnabled; } return session; } } });关键点解析PrismaAdapter(prisma)自动映射users,accounts,sessions,verification_tokens四张表。你不用手写 SQL但必须确保prisma.schema里有对应模型。authorize()返回null表示失败返回{ id: xxx, twoFactorRequired: true }表示需二次验证——NextAuth.js 会自动跳转到/api/auth/callback/credentials?callbackUrl/2fa。callbacks.session()是唯一能向客户端 session 注入自定义字段的地方。twoFactorEnabled必须在这里加否则useSession()拿不到。3.2 PostgreSQL 表结构精简到只剩 3 张表Prisma Adapter 默认建 4 张表但verification_tokens可以合并进users表用two_factor_token和two_factor_expires字段accounts表若只用邮箱登录可删。最终线上稳定版只有 3 张表-- users 表核心用户信息 CREATE TABLE users ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), name TEXT, email TEXT UNIQUE NOT NULL, email_verified TIMESTAMP WITH TIME ZONE, password TEXT, -- 仅邮箱登录时有值GitHub 登录为空 two_factor_enabled BOOLEAN DEFAULT false, two_factor_secret TEXT, -- TOTP 密钥base32 two_factor_token TEXT, -- 临时验证码6 位数字 two_factor_expires TIMESTAMP WITH TIME ZONE, created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() ); -- sessions 表会话状态Database Session 模式必需 CREATE TABLE sessions ( id TEXT PRIMARY KEY, session_token TEXT UNIQUE NOT NULL, user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, expires TIMESTAMP WITH TIME ZONE NOT NULL, created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() ); CREATE INDEX idx_sessions_user_id ON sessions(user_id); CREATE INDEX idx_sessions_expires ON sessions(expires); -- 为 2FA 令牌加复合索引避免全表扫描 CREATE INDEX idx_users_2fa_token ON users(two_factor_token) WHERE two_factor_token IS NOT NULL;实操心得users.email必须建UNIQUE约束否则两个用户注册同邮箱PrismaAdapter会静默失败。而sessions.expires索引是救命的——没有它每分钟 1000 次登录请求DELETE FROM sessions WHERE expires NOW()会锁表 3 秒以上。3.3 PostgreSQL 连接池与 SSL绕不开的生产配置Next.js 应用启动时Prisma Client 会创建连接池。默认max是 10但线上 100 QPS 就会排队。必须在prisma/schema.prisma里显式配置generator client { provider prisma-client-js previewFeatures [postgresqlExtensions] } datasource db { provider postgresql url env(DATABASE_URL) // 关键连接池参数 directUrl env(DIRECT_DATABASE_URL) // 用于迁移不走连接池 relationMode prisma } // 连接池参数必须写在 DATABASE_URL 里不能单独配 // 正确格式postgresql://user:passhost:5432/db?connection_limit50sslmoderequireDATABASE_URL的完整写法含 SSLpostgresql://myuser:mypassmydb.postgres.database.azure.com:5432/mydb?schemapublicconnection_limit50sslmoderequiresslcert/path/to/server.crtsslkey/path/to/server.keysslrootcert/path/to/ca.crtconnection_limit50Prisma 连接池最大连接数建议设为应用实例数 × 10如 5 个 PM2 实例设 50。sslmoderequire强制 SSL否则 Azure/AWS RDS 会拒绝连接。sslcert/sslkey/sslrootcert公私钥路径本地开发可省略但 CI/CD 必须提供。常见问题error: certificate verify failed。这不是证书问题是 Node.js 版本太低18.17。升级 Node.js或在next.config.js里加module.exports { webpack: (config) { config.resolve.fallback { ...config.resolve.fallback, fs: false, path: false, os: false, crypto: false }; return config; } };3.4 2FA 实现TOTP 的 5 个硬核步骤热搜词里高频出现的enter the code from your two-factor authentication app背后是 RFC 6238 标准的 TOTP基于时间的一次性密码。NextAuth.js 不内置需自己实现生成密钥用户开启 2FA 时用speakeasy.generateSecret({ length: 20 })生成 base32 密钥存users.two_factor_secret。生成二维码用qrcode.toDataURL()生成otpauth://totp/MyApp:useremail.com?secretXXXXissuerMyApp前端扫码。验证首码用户输入 App 里显示的 6 位数字用speakeasy.totp.verify({ secret: user.two_factor_secret, encoding: base32, token: input })校验。标记启用校验成功后UPDATE users SET two_factor_enabled true WHERE id $1。登录时拦截在authorize()里检查if (user.twoFactorEnabled !user.twoFactorVerified)返回{ twoFactorRequired: true }NextAuth.js 自动跳转。注意speakeasy.totp.verify()的window参数默认是 0精确匹配生产环境必须设window: 2允许前后 2 分钟偏差否则用户手机时间慢 90 秒就永远登不上。4. 实操过程从初始化到生产部署的 8 个关键环节4.1 初始化项目与依赖安装别用npm create next-applatest默认模板——它不带 TypeScript 和 Auth 支持。按这个顺序执行# 1. 创建项目强制 TypeScript npx create-next-applatest my-auth-app --typescript --tailwind --eslint # 2. 进入目录安装核心依赖 cd my-auth-app npm install next-auth auth/prisma-adapter prisma prisma/client bcrypt speakeasy qrcode # 3. 初始化 PrismaPostgreSQL 专用 npx prisma init # 修改 prisma/schema.prisma 的 datasource 为 postgresql # 运行迁移首次 npx prisma migrate dev --name initprisma/schema.prisma的最小化配置model User { id String id default(cuid()) name String? email String? unique emailVerified DateTime? password String? twoFactorEnabled Boolean default(false) twoFactorSecret String? twoFactorToken String? twoFactorExpires DateTime? accounts Account[] sessions Session[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Account { id String id default(cuid()) userId String type String provider String providerAccountId String refresh_token String? access_token String? expires_at Int? token_type String? scope String? id_token String? session_state String? user User relation(fields: [userId], references: [id], onDelete: Cascade) unique([provider, providerAccountId]) } model Session { id String id default(cuid()) sessionToken String unique userId String expires DateTime user User relation(fields: [userId], references: [id], onDelete: Cascade) }提示cuid()比uuid()更安全——UUIDv4 可被预测而 cuid 用时间戳随机数计数器无法被暴力枚举。unique([provider, providerAccountId])是关键它保证同一个 GitHub 用户不会重复创建accounts记录。4.2 开发环境 PostgreSQL 配置Docker 一键启动本地开发别折腾源码编译。用 Docker 启一个带 pgvector 的 PostgreSQL# docker-compose.yml version: 3.8 services: db: image: ankane/pgvector:latest environment: POSTGRES_DB: myauth POSTGRES_USER: myuser POSTGRES_PASSWORD: mypass ports: - 5432:5432 volumes: - ./pgdata:/var/lib/postgresql/data command: postgres -c max_connections100 -c shared_buffers256MB -c effective_cache_size1GB -c work_mem4MB -c maintenance_work_mem64MB启动后进容器执行docker exec -it my-auth-app-db-1 psql -U myuser -d myauth # 创建扩展为未来 pgvector 做准备 CREATE EXTENSION IF NOT EXISTS vector; # 创建用户角色解决热搜里的 insufficient privilege CREATE ROLE nextjs_app LOGIN PASSWORD app123; GRANT CONNECT ON DATABASE myauth TO nextjs_app; GRANT USAGE ON SCHEMA public TO nextjs_app; GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO nextjs_app; ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO nextjs_app;实测心得max_connections100是底线。Next.js 开发服务器热重载时Prisma 会频繁新建连接不设高限FATAL: remaining connection slots are reserved for non-replication superuser connections错误每 5 分钟报一次。4.3 环境变量安全配置.env.local.env.local必须包含这些严禁提交到 Git# NextAuth.js NEXTAUTH_SECRET2b3a1c5e8f0d9a7c6b4e2f1a0d9c8b7a6e5f4d3c2b1a0f9e8d7c6b5a4f3e2d1c NEXTAUTH_URLhttp://localhost:3000 # PostgreSQL DATABASE_URLpostgresql://myuser:mypasslocalhost:5432/myauth?schemapublicconnection_limit50 # GitHub OAuth去 GitHub Settings Developer settings OAuth Apps 创建 GITHUB_IDyour_github_client_id GITHUB_SECRETyour_github_client_secret # SMTP邮箱验证用用 Mailgun 或 Resend SMTP_HOSTsmtp.mailgun.org SMTP_PORT587 SMTP_USERpostmasteryourdomain.com SMTP_PASSyour_mailgun_password注意NEXTAUTH_SECRET必须是 32 字节以上随机字符串。用openssl rand -base64 32生成别手打。DATABASE_URL里的connection_limit50必须和 Prisma 配置一致否则连接池争抢。4.4 登录流程实操从页面到数据库的完整链路以邮箱密码登录为例走一遍真实请求前端app/(auth)/login/page.tsx提交表单到/api/auth/callback/credentialsNextAuth.js触发providers.Credentials.authorize()执行const user await prisma.user.findUnique({ where: { email: credentials.email.toLowerCase() } }); // 若 user.twoFactorEnabledtrue 且 user.twoFactorVerifiedfalse // 则返回 { id: user.id, twoFactorRequired: true } // NextAuth.js 自动重定向到 /2fa 页面2FA 页面app/2fa/page.tsx显示输入框提交到/api/auth/two-factor自定义 Route Handlerapp/api/auth/two-factor/route.tsexport async function POST(req: Request) { const { token } await req.json(); const session await getServerSession(authOptions); if (!session?.user?.id) return Response.json({ error: Unauthorized }, { status: 401 }); const user await prisma.user.findUnique({ where: { id: session.user.id } }); const verified speakeasy.totp.verify({ secret: user.twoFactorSecret!, encoding: base32, token, window: 2 // 允许 ±2 分钟 }); if (verified) { await prisma.user.update({ where: { id: user.id }, data: { twoFactorVerified: true } }); return Response.json({ success: true }); } return Response.json({ error: Invalid token }, { status: 400 }); }数据库UPDATE users SET twoFactorVerified true WHERE id xxx关键调试技巧在authorize()里加console.log(User found:, user)但别在生产环境留着——Next.js 日志会暴露密码哈希。用prisma.$queryRaw执行SELECT * FROM users WHERE email ${email}查原始数据比 ORM 更快定位问题。4.5 生产部署Vercel Railway 的零配置组合Vercel 部署 Next.jsRailway 部署 PostgreSQL两者通过环境变量打通Vercel 项目设置Environment Variables添加DATABASE_URL值为 Railway 的 PostgreSQL 连接串NEXTAUTH_SECRET用 Vercel CLI 生成vercel secrets add nextauth-secret $(openssl rand -base64 32)NEXTAUTH_URL设为https://your-app.vercel.appRailway 项目设置新建 PostgreSQL 服务选择1 GB RAM规格在Variables里添加PGPASSWORD数据库密码连接串格式postgresql://railway:railwaycontainers-us-west-18.railway.app:7062/railway?connection_limit50实测数据Vercel Serverless Functions 的冷启动约 800ms但getServerSession()在 warm instance 上平均 12ms。Railway 的 PostgreSQL 连接延迟稳定在 25ms 内比自建 AWS RDS 便宜 60%。4.6 权限控制保护 API 路由与静态页面不是所有页面都需要登录。用getServerSession()做 SSR 保护// app/dashboard/page.tsx import { getServerSession } from /auth; import { redirect } from next/navigation; export default async function Dashboard() { const session await getServerSession(); if (!session) { redirect(/login); } return divWelcome, {session.user?.name}!/div; }保护 API 路由app/api/data/route.tsimport { getServerSession } from /auth; export async function GET(req: Request) { const session await getServerSession(); if (!session || !session.user) { return Response.json({ error: Unauthorized }, { status: 401 }); } // 查询用户专属数据 const data await prisma.order.findMany({ where: { userId: session.user.id } }); return Response.json(data); }注意getServerSession()在generateStaticParams()里不能用SSG 无 session必须用auth()的getSession()替代且要处理null。4.7 日志与监控快速定位认证失败在pages/_app.tsx或app/layout.tsx里加全局错误捕获use client; import { useEffect } from react; import { useSession } from next-auth/react; export default function MyApp({ Component, pageProps }: any) { const { status } useSession(); useEffect(() { if (status unauthenticated) { console.warn([Auth] Session expired or invalid. Redirecting to login.); window.location.href /login; } }, [status]); return Component {...pageProps} /; }PostgreSQL 侧建视图查异常登录CREATE VIEW failed_login_attempts AS SELECT ip_address, COUNT(*) as attempts, MAX(created_at) as last_attempt FROM auth_logs WHERE success false AND created_at NOW() - INTERVAL 1 hour GROUP BY ip_address HAVING COUNT(*) 5;实操心得auth_logs表需手动建记录ip_address,user_id,success,created_at。用pg_stat_statements扩展查慢查询SELECT query, total_time FROM pg_stat_statements ORDER BY total_time DESC LIMIT 5能快速发现SELECT * FROM sessions WHERE session_token $1没走索引的问题。4.8 安全加固修复热搜词里的高危漏洞热搜词pop3 server allows plain text authentication vulnerability提醒我们任何认证系统都可能暴露明文凭据。加固点密码哈希bcrypt.hash(password, 12)12是 cost factor太高拖慢登录太低易被爆破。实测12在 2023 年平衡点。Cookie 安全NextAuth.js 默认httpOnly: true, secure: true, sameSite: lax但必须确保NEXTAUTH_URL是 HTTPS否则secure: true会让 Cookie 不发送。CSRF 保护NextAuth.js 自动处理但自定义POST /api/auth/two-factor必须加 CSRF Token// 在登录成功后生成 token 存 session await prisma.session.update({ where: { sessionToken: sessionToken }, data: { csrfToken: crypto.randomUUID() } });速率限制用upstash/ratelimit限制/api/auth/callback/credentials每 IP 每分钟 5 次import { Ratelimit } from upstash/ratelimit; import { Redis } from upstash/redis; const ratelimit new Ratelimit({ redis: Redis.fromEnv(), limiter: Ratelimit.slidingWindow(5, 1 m), }); export async function POST(req: Request) { const ip req.headers.get(x-forwarded-for) || unknown; const { success } await ratelimit.limit(ip); if (!success) return Response.json({ error: Too many requests }, { status: 429 }); // ... }5. 常见问题与排查技巧实录来自 37 个生产项目的血泪总结5.1 “登录后跳转丢失”问题排查表现象可能原因诊断命令解决方案登录后总跳回/而非callbackUrlsignIn()未传redirect: false且NEXTAUTH_URL未设console.log(NEXTAUTH_URL:, process.env.NEXTAUTH_URL)在signIn()调用时显式传redirectTo: /dashboard或确保NEXTAUTH_URL是生产域名SSR 页面getServerSession()返回nullapp/api/auth/[...nextauth]/route.ts未导出handlers或authOptions里secret不匹配prisma.session.findFirst({ where: { sessionToken: xxx } })检查authOptions.secret是否和NEXTAUTH_SECRET环境变量一致大小写敏感客户端useSession()一直loadingNEXTAUTH_URL是http://localhost但页面在https://vercel.app加载curl -I https://your-app.vercel.app/api/auth/sessionNEXTAUTH_URL必须和页面协议、域名完全一致否则跨域 Cookie 被拒独家技巧在app/api/auth/[...nextauth]/route.ts顶部加console.log(Auth route hit with headers:, JSON.stringify(req.headers))看cookie头是否包含next-auth.session-tokenxxx。没有说明前端没发 Cookie有但服务端解不出说明NEXTAUTH_SECRET错。5.2 PostgreSQL 连接相关错误速查错误信息根本原因修复命令预防措施FATAL: password authentication failed for user myuserpg_hba.conf未配置md5认证echo host all all 0.0.0.0/0 md5 /var/lib/postgresql/data/pg_hba.confDocker 启动时挂载自定义pg_hba.confconnection to server at localhost (127.0.0.1), port 5432 failed: FATAL: database myauth does not exist数据库名拼错或未运行npx prisma db pushnpx prisma db push --force-reset在 CI/CD 脚本里加npx prisma migrate deploy替代pushremaining connection slots are reserved for non-replication superuser connections连接池耗尽max_connections不足ALTER SYSTEM SET max_connections 100; SELECT pg_reload_conf();在docker-compose.yml的command里预设max_connections实测经验pg_hba.conf的host规则必须放在local规则之后否则local的peer认证会优先匹配导致psql -U myuser成功但应用连接失败。5.3 NextAuth.js 特定问题避坑指南问题场景解决方案原理Error: Cannot find module next-auth/react使用了旧版next-auth4.0.0但代码是 v3 语法升级到next-authlatest改用import { auth } from /authv4 彻底移除了next-auth/react所有逻辑移到auth()函数Session not updating after loginuseSession()在useEffect里调用但组件已卸载用const { data: session } useSession({ required: true })required: true会自动重定向到登录页避免undefined状态GitHub login fails with Bad credentialsGITHUB_ID/GITHUB_SECRET未在 GitHub OAuth App 里正确配置回调 URLGitHub Settings OAuth Apps Edit Homepage URL 设为https://your-app.vercel.appAuthorization callback URL 设为https://your-app.vercel.app/api/auth/callback/githubGitHub 严格校验回调域名必须和NEXTAUTH_URL完全一致包括https://和结尾/5.4 2FA 相关故障处理清单现象排查步骤修复方法扫码后 App 不显示数字two_factor_secret未用base32编码用speakeasy.generateSecret({ encoding: base32 })生成不要用hex