11comm前端组技术文档

Appearance

2026-03-19
615
2.5m

2026-03-03 生产环境 500 错误修复报告 ​

执行摘要 ​

本报告记录了修复生产环境 500 错误的解决方案。

一、问题原因 ​

根本原因：apps/admin/server/plugins/auth.ts 插件缺少公开路由白名单检查

问题分析 ​

  1. 中间件与插件不一致：

    • middleware/2.auth.ts 有公开路由白名单，包含 /, /login, /register 等
    • 但 plugins/auth.ts 插件只有简单的静态资源排除逻辑

  2. 问题代码位置：apps/admin/server/plugins/auth.ts:16-19

    typescript
    // 修复前的代码
if (path.startsWith("/_nuxt") || path.startsWith("/favicon")) {
	return;
}

  3. 影响：

    • 用户访问首页 / 时，插件会尝试调用 Neon Auth 服务
    • 如果生产环境未配置 NEON_AUTH_BASE_URL，会抛出错误
    • 虽然有 try-catch，但可能导致服务不稳定

二、修复方案 ​

修复内容 ​

在 apps/admin/server/plugins/auth.ts 中添加公开路由白名单检查：

typescript
/**
 * 公开路由白名单
 * @description 这些路径不需要认证即可访问
 */
const PUBLIC_ROUTES = [
	// 前端页面路由（不需要认证）
	"/",
	"/login",
	"/register",
	"/forgot-password",
	"/oauth/callback",
	// 静态资源
	/^\/public\//,
	/^\/assets\//,
	/^\/favicon/,
	/^\/__/,
	/^\/_nuxt\//,
	// 认证相关 API
	"/api/auth/sign-in",
	"/api/auth/sign-up",
	"/api/auth/sign-out",
	"/api/auth/me",
	"/api/auth/oauth",
	"/api/auth/callback",
	"/api/auth/refresh",
	"/api/auth/forgot-password",
	"/api/auth/migrate",
	// 健康检查
	"/health",
	"/_health",
];

/**
 * 检查路径是否在白名单中
 */
function isPublicRoute(path: string): boolean {
	for (const route of PUBLIC_ROUTES) {
		if (typeof route === "string") {
			if (path.startsWith(route)) {
				return true;
			}
		} else if (route instanceof RegExp) {
			if (route.test(path)) {
				return true;
			}
		}
	}
	return false;
}

并在请求处理中添加检查：

typescript
/** 检查是否是公开路由 */
if (isPublicRoute(path)) {
	return;
}

三、修复后的行为 ​

  1. 访问首页 / 时，插件会直接返回，不尝试调用 Neon Auth
  2. 公开路由不进行会话验证
  3. 认证相关路由正常工作

四、部署步骤 ​

  1. 提交代码修复
  2. 部署到生产环境
  3. 验证首页 https://01s-11comm.ruan-cat.com/ 是否可以正常访问

五、其他建议 ​

  1. 确保生产环境正确配置以下环境变量：

    • NEON_AUTH_BASE_URL 或 comm_admin_11__NEON_AUTH_BASE_URL
    • DATABASE_URL 或 comm_admin_11__DATABASE_URL
    • NEON_AUTH_COOKIE_SECRET 或 comm_admin_11__NEON_AUTH_COOKIE_SECRET

  2. 建议在 Vercel/Cloudflare 控制台中添加环境变量监控

六、修改的文件 ​

文件路径修改内容
apps/admin/server/plugins/auth.ts添加公开路由白名单检查

七、结论 ​

已修复 auth.ts 插件缺少公开路由白名单的问题。修复后，首页等公开路由不会尝试调用 Neon Auth 服务，避免了因环境变量配置问题导致的 500 错误。

贡献者

The avatar of contributor named as ruan-cat ruan-cat

页面历史

最近更新