From be8f4f8512dfb2952a09de658fe22c3395b13343 Mon Sep 17 00:00:00 2001
From: npmrun <1549469775@qq.com>
Date: Fri, 17 Apr 2026 01:13:49 +0800
Subject: [PATCH] feat: add global configuration management and error handling
 component

Introduce a new error handling component to display user-friendly error messages based on HTTP status codes. Implement global configuration management to control registration availability across the application. Update various components and pages to utilize the new configuration, ensuring consistent behavior for registration links and error handling. Enhance middleware to bypass authentication for specific paths and improve overall user experience.
---
 app/components/AppShell.vue            |   4 +-
 app/composables/useGlobalConfig.ts     |  36 ++++++++++
 app/error.vue                          | 126 +++++++++++++++++++++++++++++++++
 app/middleware/auth.global.ts          |   9 +++
 app/pages/index/index.vue              |   3 +-
 app/pages/login/index.vue              |   3 +-
 app/pages/register/index.vue           |   9 +++
 server/api/auth/register.post.ts       |   8 +++
 server/api/config/global.get.ts        |   4 +-
 server/plugins/00.global.ts            |  45 ------------
 server/plugins/00.req-time.ts          |  36 ++++++++++
 server/plugins/01.context.ts           |  45 ++++++++++++
 server/plugins/01.req-time.ts          |  36 ----------
 server/plugins/02.well-known-ignore.ts |   2 +-
 14 files changed, 279 insertions(+), 87 deletions(-)
 create mode 100644 app/composables/useGlobalConfig.ts
 create mode 100644 app/error.vue
 delete mode 100644 server/plugins/00.global.ts
 create mode 100644 server/plugins/00.req-time.ts
 create mode 100644 server/plugins/01.context.ts
 delete mode 100644 server/plugins/01.req-time.ts

diff --git a/app/components/AppShell.vue b/app/components/AppShell.vue
index b3d778c..08cf7b2 100644
--- a/app/components/AppShell.vue
+++ b/app/components/AppShell.vue
@@ -44,6 +44,8 @@ const menuItems = [
     },
   ],
 ]
+
+const { allowRegister } = useGlobalConfig()
 </script>
 
 <template>
@@ -62,7 +64,7 @@ const menuItems = [
 
           <div v-if="showAuthActions" class="flex items-center gap-2">
             <UButton color="neutral" variant="ghost" to="/login" label="登录" />
-            <UButton color="neutral" variant="outline" to="/register" label="注册" />
+            <UButton v-if="allowRegister" color="neutral" variant="outline" to="/register" label="注册" />
           </div>
         </UContainer>
       </header>
diff --git a/app/composables/useGlobalConfig.ts b/app/composables/useGlobalConfig.ts
new file mode 100644
index 0000000..61f1e89
--- /dev/null
+++ b/app/composables/useGlobalConfig.ts
@@ -0,0 +1,36 @@
+import { request, unwrapApiBody, type ApiResponse } from '../utils/http/factory'
+
+export type GlobalConfig = {
+  allowRegister: boolean
+}
+
+type GlobalConfigResult = {
+  config: GlobalConfig
+}
+
+const DEFAULT_GLOBAL_CONFIG: GlobalConfig = {
+  allowRegister: true,
+}
+
+export function useGlobalConfig() {
+  const { data, pending, error, refresh } = useAsyncData(
+    'global:config',
+    async () => {
+      const payload = await request<ApiResponse<GlobalConfigResult>>('/api/config/global')
+      return unwrapApiBody(payload).config
+    },
+    {
+      default: () => ({ ...DEFAULT_GLOBAL_CONFIG }),
+    },
+  )
+
+  const config = computed<GlobalConfig>(() => data.value ?? DEFAULT_GLOBAL_CONFIG)
+
+  return {
+    config,
+    allowRegister: computed(() => config.value.allowRegister),
+    pending,
+    error,
+    refresh,
+  }
+}
diff --git a/app/error.vue b/app/error.vue
new file mode 100644
index 0000000..bdffa10
--- /dev/null
+++ b/app/error.vue
@@ -0,0 +1,126 @@
+<script setup lang="ts">
+import type { NuxtError } from "#app";
+
+const props = defineProps<{
+  error: NuxtError;
+}>();
+
+const statusCode = computed(() => props.error?.statusCode ?? 500);
+const statusMessage = computed(() => {
+  if (props.error?.statusMessage) {
+    return props.error.statusMessage;
+  }
+  return statusCode.value >= 500 ? "服务暂时不可用，请稍后重试" : "请求失败，请检查后重试";
+});
+const errorTitle = computed(() => {
+  if (statusCode.value === 401) return "未登录或会话已失效";
+  if (statusCode.value === 403) return "当前账号无访问权限";
+  if (statusCode.value === 404) return "页面不存在";
+  if (statusCode.value >= 500) return "服务开小差了";
+  return "发生了一点异常";
+});
+const tips = computed(() => {
+  if (statusCode.value === 401) return "请重新登录后再继续操作。";
+  if (statusCode.value === 403) return "如需访问此页面，请联系管理员开通权限。";
+  if (statusCode.value === 404) return "你访问的地址可能已变更或被移除。";
+  if (statusCode.value >= 500) return "我们正在处理该问题，请稍后再试。";
+  return "你可以先返回首页，或点击重试。";
+});
+const levelTag = computed(() => {
+  if (statusCode.value >= 500) return "P1 / 高优先级";
+  if (statusCode.value === 401 || statusCode.value === 403) return "P2 / 权限类";
+  if (statusCode.value === 404) return "P3 / 资源类";
+  return "P3 / 一般异常";
+});
+const actionHints = computed(() => {
+  if (statusCode.value === 401) {
+    return ["确认登录状态是否过期", "重新登录后刷新页面", "检查接口鉴权中间件配置"];
+  }
+  if (statusCode.value === 403) {
+    return ["确认账号角色与权限策略", "检查后端权限拦截规则", "联系管理员开通访问权限"];
+  }
+  if (statusCode.value === 404) {
+    return ["确认访问路径是否正确", "检查路由或接口是否已下线", "核对部署环境与 baseURL 配置"];
+  }
+  if (statusCode.value >= 500) {
+    return ["查看服务端日志定位堆栈", "检查依赖服务和数据库连接", "确认最新变更是否引入回归"];
+  }
+  return ["查看浏览器控制台错误信息", "检查网络请求返回内容", "重试并记录复现路径"];
+});
+
+const handleBackHome = () => clearError({ redirect:  "/" });
+const handleRetry = async () => {
+  if (statusCode.value === 401 || statusCode.value === 403) {
+    await clearError({ redirect: "/login" });
+    return;
+  }
+
+  if (import.meta.client) {
+    window.location.reload();
+    return;
+  }
+
+  await clearError({ redirect: "/" });
+};
+</script>
+
+<template>
+  <main class="min-h-screen bg-default text-default">
+    <section class="mx-auto w-full max-w-5xl px-4 py-10 sm:px-6">
+      <header class="mb-4 flex items-center justify-between rounded-xl border border-default bg-elevated px-4 py-3">
+        <div class="flex items-center gap-2">
+          <span class="size-2 rounded-full bg-error" />
+          <p class="text-sm font-semibold text-toned">运行异常面板</p>
+        </div>
+        <span class="rounded-md border border-default px-2 py-1 text-xs text-muted">
+          {{ levelTag }}
+        </span>
+      </header>
+
+      <div class="grid gap-4 lg:grid-cols-[1.35fr,1fr]">
+        <article class="rounded-xl border border-default bg-elevated p-6 sm:p-7">
+          <p class="mb-1 text-xs tracking-wide text-muted">状态码</p>
+          <p class="mb-3 font-mono text-5xl font-semibold leading-none text-error sm:text-6xl">
+            {{ statusCode }}
+          </p>
+          <h1 class="mb-2 text-3xl font-semibold tracking-tight">
+            {{ errorTitle }}
+          </h1>
+          <p class="mb-2 text-toned">
+            {{ statusMessage }}
+          </p>
+          <p class="mb-6 text-sm text-muted">
+            {{ tips }}
+          </p>
+
+          <div class="flex flex-wrap gap-3">
+            <UButton color="error" variant="solid" size="md" @click="handleRetry">
+              立即重试
+            </UButton>
+            <UButton color="neutral" variant="outline" size="md" @click="handleBackHome">
+              返回首页
+            </UButton>
+          </div>
+        </article>
+
+        <aside class="rounded-xl border border-default bg-elevated p-6 sm:p-7">
+          <p class="mb-3 text-xs tracking-wide text-muted">建议排查项</p>
+          <ul class="mb-5 space-y-2 text-sm text-toned">
+            <li v-for="hint in actionHints" :key="hint" class="rounded-lg border border-default bg-default px-3 py-2">
+              {{ hint }}
+            </li>
+          </ul>
+
+          <details v-if="error?.message" class="rounded-lg border border-default bg-default p-3 mt-2">
+            <summary class="cursor-pointer select-none text-sm font-medium text-toned">
+              查看错误详情
+            </summary>
+            <p class="mt-2 break-words text-xs text-muted">
+              {{ error.message }}
+            </p>
+          </details>
+        </aside>
+      </div>
+    </section>
+  </main>
+</template>
diff --git a/app/middleware/auth.global.ts b/app/middleware/auth.global.ts
index e680556..453620c 100644
--- a/app/middleware/auth.global.ts
+++ b/app/middleware/auth.global.ts
@@ -7,6 +7,15 @@ import {
 import { useAuthSession } from "../composables/useAuthSession";
 
 export default defineNuxtRouteMiddleware(async (to) => {
+  if(to.path.startsWith("/__nuxt_error")) {
+    return
+  }
+  if(to.path.startsWith("/api")) {
+    return
+  }
+  if(to.path.startsWith("/public")) {
+    return
+  }
   const { initialized, loggedIn, refresh } = useAuthSession();
   if (!initialized.value) {
     await refresh();
diff --git a/app/pages/index/index.vue b/app/pages/index/index.vue
index a953a52..1b9462e 100644
--- a/app/pages/index/index.vue
+++ b/app/pages/index/index.vue
@@ -3,6 +3,7 @@ import { request, unwrapApiBody, type ApiResponse } from '../../utils/http/facto
 import { useAuthSession } from '../../composables/useAuthSession'
 
 const { loggedIn, user, clear } = useAuthSession()
+const { allowRegister } = useGlobalConfig()
 
 const logoutLoading = ref(false)
 
@@ -80,7 +81,7 @@ async function logout() {
 
       <div class="mt-5 flex gap-3">
         <UButton to="/login">去登录</UButton>
-        <UButton to="/register" color="neutral" variant="outline">去注册</UButton>
+        <UButton v-if="allowRegister" to="/register" color="neutral" variant="outline">去注册</UButton>
       </div>
     </UCard>
   </div>
diff --git a/app/pages/login/index.vue b/app/pages/login/index.vue
index 42df85e..4760b67 100644
--- a/app/pages/login/index.vue
+++ b/app/pages/login/index.vue
@@ -33,6 +33,7 @@ const resultType = ref<'success' | 'error' | ''>('')
 const resultMessage = ref('')
 const route = useRoute()
 const { refresh } = useAuthSession()
+const { allowRegister } = useGlobalConfig()
 
 const validate = (formState: LoginFormState): FormError[] => {
   const errors: FormError[] = []
@@ -139,7 +140,7 @@ const onSubmit = async (_event: FormSubmitEvent<LoginFormState>) => {
         class="mt-4"
       />
 
-      <div class="mt-4 flex items-center justify-center text-sm">
+      <div v-if="allowRegister" class="mt-4 flex items-center justify-center text-sm">
         <NuxtLink to="/register" class="text-primary hover:underline">
           没有账号？去注册
         </NuxtLink>
diff --git a/app/pages/register/index.vue b/app/pages/register/index.vue
index 31ab7b5..12f940e 100644
--- a/app/pages/register/index.vue
+++ b/app/pages/register/index.vue
@@ -6,6 +6,15 @@ import { normalizeSafeRedirect } from '../../utils/auth-routes'
 definePageMeta({
   title: '注册',
   layout: 'blank',
+  middleware: [
+    async () => {
+      const { allowRegister, refresh } = useGlobalConfig()
+      await refresh()
+      if (!allowRegister.value) {
+        return navigateTo('/login')
+      }
+    },
+  ],
 })
 
 type RegisterFormState = {
diff --git a/server/api/auth/register.post.ts b/server/api/auth/register.post.ts
index c46e633..490dafb 100644
--- a/server/api/auth/register.post.ts
+++ b/server/api/auth/register.post.ts
@@ -7,6 +7,14 @@ type RegisterBody = {
 };
 
 export default defineWrappedResponseHandler(async (event) => {
+    const allowRegister = await event.context.config.getGlobal("allowRegister");
+    if (!allowRegister) {
+        throw createError({
+            statusCode: 403,
+            statusMessage: "当前已关闭注册",
+        });
+    }
+
     try {
         const body = await readBody<RegisterBody>(event);
         const user = await registerUser(body);
diff --git a/server/api/config/global.get.ts b/server/api/config/global.get.ts
index 0db70fd..13879a8 100644
--- a/server/api/config/global.get.ts
+++ b/server/api/config/global.get.ts
@@ -1,10 +1,10 @@
-import { KNOWN_CONFIG_KEYS } from "#server/service/config/registry";
+import { KNOWN_CONFIG_KEYS, KnownConfigKey, KnownConfigValue } from "#server/service/config/registry";
 
 export default defineWrappedResponseHandler(async (event) => {
     const entries = await Promise.all(
         KNOWN_CONFIG_KEYS.map(async (key) => {
             const value = await event.context.config.getGlobal(key);
-            return [key, value] as const;
+            return [key, value] as const satisfies [KnownConfigKey, KnownConfigValue<KnownConfigKey>];
         }),
     );
 
diff --git a/server/plugins/00.global.ts b/server/plugins/00.global.ts
deleted file mode 100644
index e9379e3..0000000
--- a/server/plugins/00.global.ts
+++ /dev/null
@@ -1,45 +0,0 @@
-
-import { createAuthContext } from "../service/auth/context";
-import { getGlobalConfigValue, getMergedConfigValue, getUserConfigValue } from "../service/config";
-import type { KnownConfigKey, KnownConfigValue } from "../service/config/registry";
-
-if (import.meta.dev) {
-    console.log("plugin: 00.global");
-}
-
-export default defineNitroPlugin(async (nitroApp) => {
-    nitroApp.hooks.hook("request", (event) => {
-        const requestCache = new Map<string, Promise<unknown>>();
-        event.context.auth = createAuthContext(event);
-
-        event.context.config = {
-            getGlobal: async <K extends KnownConfigKey>(key: K) => {
-                const cacheKey = `global:${key}`;
-                if (!requestCache.has(cacheKey)) {
-                    requestCache.set(cacheKey, getGlobalConfigValue(key));
-                }
-                return requestCache.get(cacheKey) as Promise<KnownConfigValue<K>>;
-            },
-            getUser: async <K extends KnownConfigKey>(key: K) => {
-                const cacheKey = `user:${key}`;
-                if (!requestCache.has(cacheKey)) {
-                    requestCache.set(cacheKey, (async () => {
-                        const user = await event.context.auth.getCurrent();
-                        return getUserConfigValue(user?.id, key);
-                    })());
-                }
-                return requestCache.get(cacheKey) as Promise<KnownConfigValue<K> | undefined>;
-            },
-            get: async <K extends KnownConfigKey>(key: K) => {
-                const cacheKey = `merged:${key}`;
-                if (!requestCache.has(cacheKey)) {
-                    requestCache.set(cacheKey, (async () => {
-                        const user = await event.context.auth.getCurrent();
-                        return getMergedConfigValue(user?.id, key);
-                    })());
-                }
-                return requestCache.get(cacheKey) as Promise<KnownConfigValue<K>>;
-            },
-        };
-    });
-})
diff --git a/server/plugins/00.req-time.ts b/server/plugins/00.req-time.ts
new file mode 100644
index 0000000..d201118
--- /dev/null
+++ b/server/plugins/00.req-time.ts
@@ -0,0 +1,36 @@
+import log4js from "logger";
+import { randomUUID } from "crypto";
+
+const logger = log4js.getLogger("APP")
+
+if (import.meta.dev) {
+    console.log("plugin: 00.req-time");
+}
+
+declare module "http" {
+    interface IncomingMessage {
+        $beginTime: number;
+        $requestId: string;
+    }
+}
+
+export default defineNitroPlugin((nitroApp) => {
+    nitroApp.hooks.hook('request', async (event) => {
+        const incoming = event.node.req.headers["x-request-id"];
+        const requestId =
+            typeof incoming === "string" && incoming.trim().length > 0
+                ? incoming.trim()
+                : randomUUID();
+
+        event.node.req.$requestId = requestId;
+        event.node.req.$beginTime = new Date().getTime();
+        event.node.res.setHeader("X-Request-Id", requestId);
+        logger.info(`[${requestId}]`, `[${event.method}-${event.path}]`, "开始请求");
+    })
+    nitroApp.hooks.hook('afterResponse', async (event) => {
+        const requestId = event.node.req.$requestId ?? "(no-request-id)";
+        let curTime = new Date().getTime()
+        let offsetTime = curTime - event.node.req.$beginTime
+        logger.info(`[${requestId}]`, `[${event.method}-${event.path}]`, "请求结束，花费了", offsetTime, "ms");
+    })
+})
diff --git a/server/plugins/01.context.ts b/server/plugins/01.context.ts
new file mode 100644
index 0000000..f15e42c
--- /dev/null
+++ b/server/plugins/01.context.ts
@@ -0,0 +1,45 @@
+
+import { createAuthContext } from "../service/auth/context";
+import { getGlobalConfigValue, getMergedConfigValue, getUserConfigValue } from "../service/config";
+import type { KnownConfigKey, KnownConfigValue } from "../service/config/registry";
+
+if (import.meta.dev) {
+    console.log("plugin: 01.context");
+}
+
+export default defineNitroPlugin((nitroApp) => {
+    nitroApp.hooks.hook("request", (event) => {
+        const requestCache = new Map<string, Promise<unknown>>();
+        event.context.auth = createAuthContext(event);
+
+        event.context.config = {
+            getGlobal: async <K extends KnownConfigKey>(key: K) => {
+                const cacheKey = `global:${key}`;
+                if (!requestCache.has(cacheKey)) {
+                    requestCache.set(cacheKey, getGlobalConfigValue(key));
+                }
+                return requestCache.get(cacheKey) as Promise<KnownConfigValue<K>>;
+            },
+            getUser: async <K extends KnownConfigKey>(key: K) => {
+                const cacheKey = `user:${key}`;
+                if (!requestCache.has(cacheKey)) {
+                    requestCache.set(cacheKey, (async () => {
+                        const user = await event.context.auth.getCurrent();
+                        return getUserConfigValue(user?.id, key);
+                    })());
+                }
+                return requestCache.get(cacheKey) as Promise<KnownConfigValue<K> | undefined>;
+            },
+            get: async <K extends KnownConfigKey>(key: K) => {
+                const cacheKey = `merged:${key}`;
+                if (!requestCache.has(cacheKey)) {
+                    requestCache.set(cacheKey, (async () => {
+                        const user = await event.context.auth.getCurrent();
+                        return getMergedConfigValue(user?.id, key);
+                    })());
+                }
+                return requestCache.get(cacheKey) as Promise<KnownConfigValue<K>>;
+            },
+        };
+    });
+})
diff --git a/server/plugins/01.req-time.ts b/server/plugins/01.req-time.ts
deleted file mode 100644
index 81a9819..0000000
--- a/server/plugins/01.req-time.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-import log4js from "logger";
-import { randomUUID } from "crypto";
-
-const logger = log4js.getLogger("APP")
-
-if (import.meta.dev) {
-    console.log("plugin: 1.error-handler");
-}
-
-declare module "http" {
-    interface IncomingMessage {
-        $beginTime: number;
-        $requestId: string;
-    }
-}
-
-export default defineNitroPlugin((nitroApp) => {
-    nitroApp.hooks.hook('request', async (event) => {
-        const incoming = event.node.req.headers["x-request-id"];
-        const requestId =
-            typeof incoming === "string" && incoming.trim().length > 0
-                ? incoming.trim()
-                : randomUUID();
-
-        event.node.req.$requestId = requestId;
-        event.node.req.$beginTime = new Date().getTime();
-        event.node.res.setHeader("X-Request-Id", requestId);
-        logger.info(`[${requestId}]`, `[${event.method}-${event.path}]`, "开始请求");
-    })
-    nitroApp.hooks.hook('afterResponse', async (event) => {
-        const requestId = event.node.req.$requestId ?? "(no-request-id)";
-        let curTime = new Date().getTime()
-        let offsetTime = curTime - event.node.req.$beginTime
-        logger.info(`[${requestId}]`, `[${event.method}-${event.path}]`, "请求结束，花费了", offsetTime, "ms");
-    })
-})
diff --git a/server/plugins/02.well-known-ignore.ts b/server/plugins/02.well-known-ignore.ts
index 9dd4587..97dbcb0 100644
--- a/server/plugins/02.well-known-ignore.ts
+++ b/server/plugins/02.well-known-ignore.ts
@@ -1,5 +1,5 @@
 if (import.meta.dev) {
-    console.log("plugin: 01.well-known-ignore");
+    console.log("plugin: 02.well-known-ignore");
 }
 
 export default defineNitroPlugin(() => {