Skip to content

Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.

feat: 新增自定义脚本注入功能,支持管理员配置分析跟踪脚本

Teror Fox5af3e6eb800a
diff --git a/.nuxtrc b/.nuxtrc
index 1e780800..640f280a 100644
--- a/.nuxtrc
+++ b/.nuxtrc
@@ -1 +1 @@
-setups.@nuxt/test-utils="3.23.0"
\ No newline at end of file
+setups.@nuxt/test-utils="4.0.3"
\ No newline at end of file
diff --git a/.trae/documents/custom-script-injection.md b/.trae/documents/custom-script-injection.md
new file mode 100644
index 00000000..b017f629
--- /dev/null
+++ b/.trae/documents/custom-script-injection.md
@@ -0,0 +1,299 @@
+# 自定义 `<script>` 注入功能实现方案
+
+## Context(背景)
+
+ChronoFrame 当前只支持通过 `runtimeConfig.public.analytics.matomo` 硬编码配置 Matomo 统计(见 [analytics-tracker.client.ts](file:///c:/Users/imagi/Documents/Project/chronoframe/app/plugins/analytics-tracker.client.ts)),管理员无法在不修改代码/环境变量的情况下接入其他统计服务(GA、百度统计、Plausible、Umami、自托管脚本等)。
+
+本方案在不破坏现有 Matomo 集成的前提下,新增一个 **`analytics` settings namespace**,让管理员在后台粘贴完整 HTML 片段(含 `<script>` 标签),前端通过 `useHead` 响应式注入到页面 `<head>` 和 `<body>` 中。
+
+**用户已确认的需求**:
+- 输入方式:完整 HTML 片段(直接粘贴官方提供的 `<script>` 代码)
+- 注入位置:head + body 两处(独立 textarea)
+- Matomo 专用入口保留不动
+- 脚本内容通过 public settings API 暴露(脚本本就要嵌入给所有访客,无额外泄露风险)
+
+---
+
+## 方案概览
+
+| 层 | 改动 |
+|---|---|
+| 数据层 | `DEFAULT_SETTINGS` 新增 `analytics` namespace(2 个 string 字段,isPublic: true) |
+| UI 配置 | 新增 `ANALYTICS_SETTINGS_UI`,给 `FieldUIConfig` 增加可选 `rows` 字段 |
+| 设置页 | 新建 `app/pages/dashboard/settings/analytics.vue`(镜像 privacy.vue) |
+| 导航 | dashboard.vue 侧边栏添加菜单项 |
+| 脚本解析 | 新建 `app/utils/parseScriptTags.ts`(纯正则,SSR 安全) |
+| 脚本注入 | 新建 `app/plugins/custom-scripts.ts`(universal,`useSettingRef` + `computed` + `useHead`) |
+| 类型/组件 | `FieldUIConfig` 加 `rows?`;`SettingField.vue` 读取该值 |
+| i18n | 5 个 locale 文件加 8 个 key path |
+
+---
+
+## 详细变更
+
+### 1. 新建 `app/utils/parseScriptTags.ts`
+
+纯正则解析器,无 DOM API,SSR/CSR 一致。自动通过 Nuxt `app/utils/` 约定导入。
+
+**导出**:
+- `interface ParsedScriptTag` — 兼容 useHead 的 `script[]` 项格式:`{ src?, innerHTML?, async?, defer?, type?, crossorigin?, integrity?, nomodule?, referrerpolicy?, nonce? }`
+- `function parseScriptTags(raw: string): ParsedScriptTag[]`
+
+**行为**:
+- 先剥离 HTML 注释 `<!-- ... -->`
+- 正则同时匹配 `<script attrs>content</script>` 与自闭合 `<script attrs />`
+- 属性解析支持:布尔属性(async/defer/nomodule → true)、双引号/单引号/无引号值
+- 仅保留已知属性(src, async, defer, type, crossorigin, integrity, nomodule, referrerpolicy, nonce),未知属性丢弃
+- 跳过既无 src 又无 innerHTML 的空脚本
+- 不过滤 type(`application/ld+json`、`module` 等原样保留 — JSON-LD 是合法用例)
+- 永不抛错,输入非法返回 `[]`
+
+**核心正则**:
+```ts
+const COMMENT_RE = /<!--[\s\S]*?-->/g
+const SCRIPT_TAG_RE =
+ /<script\b([^>]*?)>([\s\S]*?)<\/script>|<script\b([^>]*?)\s*\/>/gi
+const ATTR_RE =
+ /([a-zA-Z_:][\w:-]*)\s*(?:=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g
+```
+
+**已知限制**:`[^>]*?` 无法处理属性值中含 `>` 的情况;统计代码场景罕见,JSDoc 中说明。
+
+### 2. 修改 `shared/types/settings.ts`
+
+在 `FieldUIConfig` 接口末尾(约 L79 `icon?: string` 后)增加可选字段:
+
+```ts
+/** 行数(仅 textarea 生效),SettingField.vue 默认 3 */
+rows?: number
+```
+
+非破坏性改动,其他字段不受影响。
+
+### 3. 修改 `app/components/setting/SettingField.vue`
+
+L99-L101 的 textarea 分支:
+
+```ts
+case 'textarea':
+ propsMap.rows = props.field.ui.rows ?? 3
+ break
+```
+
+### 4. 修改 `server/services/settings/contants.ts`
+
+在 `DEFAULT_SETTINGS` 数组末尾(L224 `] as const` 之前)追加:
+
+```ts
+// NAMESPACE: analytics
+{
+ namespace: 'analytics',
+ key: 'headScripts',
+ type: 'string',
+ defaultValue: '',
+ label: 'settings.analytics.headScripts.label',
+ description: 'settings.analytics.headScripts.description',
+ isPublic: true,
+},
+{
+ namespace: 'analytics',
+ key: 'bodyScripts',
+ type: 'string',
+ defaultValue: '',
+ label: 'settings.analytics.bodyScripts.label',
+ description: 'settings.analytics.bodyScripts.description',
+ isPublic: true,
+},
+```
+
+**为什么无需改其他服务端文件**:`settingNamespaces` 和 `settingKeys` 由 `[...new Set(DEFAULT_SETTINGS.map(...))]` 自动派生(L226-L231),因此 [batch.put.ts](file:///c:/Users/imagi/Documents/Project/chronoframe/server/api/system/settings/batch.put.ts) 的 zod enum 与 [fields.get.ts](file:///c:/Users/imagi/Documents/Project/chronoframe/server/api/system/settings/fields.get.ts) 的 allowedKeys 自动包含新 namespace。`settingsManager.init()` 会在启动时自动插入默认行。
+
+### 5. 修改 `server/services/settings/ui-config.ts`
+
+新增导出 `ANALYTICS_SETTINGS_UI`(参考 `PRIVACY_SETTINGS_UI` 的形式):
+
+```ts
+export const ANALYTICS_SETTINGS_UI: Record<string, FieldUIConfig> = {
+ headScripts: {
+ type: 'textarea',
+ rows: 12,
+ placeholder:
+ '<!-- Google Analytics -->\n<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXX"></script>\n<script>\n window.dataLayer = window.dataLayer || [];\n function gtag(){dataLayer.push(arguments);}\n gtag(\'js\', new Date());\n gtag(\'config\', \'G-XXXX\');\n</script>',
+ help: 'settings.analytics.headScripts.help',
+ },
+ bodyScripts: {
+ type: 'textarea',
+ rows: 12,
+ placeholder:
+ '<!-- Umami / Openpanel SDK -->\n<script src="https://analytics.example.com/script.js" data-website-id="xxx" defer></script>',
+ help: 'settings.analytics.bodyScripts.help',
+ },
+}
+```
+
+在 `getSettingUIConfig` 的 `uiConfigMap`(L339-L346)添加:
+
+```ts
+analytics: ANALYTICS_SETTINGS_UI,
+```
+
+### 6. 新建 `app/plugins/custom-scripts.ts`
+
+Universal 插件(无 `.client` 后缀),让脚本在 SSR HTML 中即出现(利于 SEO/JSON-LD 与首屏速度)。
+
+**为什么 universal 可行**:[app.vue](file:///c:/Users/imagi/Documents/Project/chronoframe/app/app.vue) setup 中 `await settingsStore.initSettings()` 在 SSR 渲染前完成;Pinia store 响应式更新会触发 `useSettingRef` 的 computed 重算;Unhead 在序列化前会重新求值 computed。客户端 hydration 时 computed 值一致,无水合不匹配。
+
+```ts
+import { parseScriptTags } from '~/utils/parseScriptTags'
+
+/**
+ * 将管理员配置的 <script> 标签注入到 <head> 和 <body>。
+ * 与 analytics-tracker.client.ts(Matomo)独立并行,互不干扰。
+ */
+export default defineNuxtPlugin(() => {
+ const headScriptsRef = useSettingRef('analytics:headScripts')
+ const bodyScriptsRef = useSettingRef('analytics:bodyScripts')
+
+ useHead(
+ computed(() => {
+ const head = parseScriptTags(String(headScriptsRef.value ?? '')).map(
+ (s, i) => ({ ...s, tagPosition: 'head' as const, key: `cf-head-${i}` }),
+ )
+ const body = parseScriptTags(String(bodyScriptsRef.value ?? '')).map(
+ (s, i) => ({ ...s, tagPosition: 'bodyOpen' as const, key: `cf-body-${i}` }),
+ )
+ return { script: [...head, ...body] }
+ }),
+ )
+})
+```
+
+**关键点**:
+- `key` 字段帮助 Unhead 在响应式更新时正确 diff,避免重复注入
+- `tagPosition: 'bodyOpen'` 让 body 脚本出现在 `<body>` 开头(useHead 不支持 `bodyClose`,`bodyOpen` 是标准选项;如需 body 底部,可后续评估)
+- `String(... ?? '')` 防御 null(未初始化时 store 返回 null)
+
+### 7. 新建 `app/pages/dashboard/settings/analytics.vue`
+
+镜像 [privacy.vue](file:///c:/Users/imagi/Documents/Project/chronoframe/app/pages/dashboard/settings/privacy.vue) 结构,单 section + 单 `useSettingsForm('analytics')`。差异点:
+- 使用 `analytics` 命名空间
+- 表单容器加 Tailwind 任意变体类 `[&_textarea]:font-mono [&_textarea]:text-xs` 让 textarea 显示等宽字体(适合粘贴代码)
+- 标题/描述用 `title.analyticsSettings` 与 `settings.analytics.sectionDescription`
+
+### 8. 修改 `app/layouts/dashboard.vue`
+
+在 `siteAdministration` children 末尾(L71 `systemSettings` 之后)追加:
+
+```ts
+{
+ label: $t('title.analyticsSettings'),
+ icon: 'tabler:chart-bar',
+ to: '/dashboard/settings/analytics',
+},
+```
+
+### 9. 修改 i18n locale 文件(5 个)
+
+在 `title` 段末尾(en.json L402 `systemSettings` 之后)加 `analyticsSettings`;在 `settings` 段加 `analytics` 子对象。
+
+**需新增的 key path**:
+```
+title.analyticsSettings
+settings.analytics.sectionDescription
+settings.analytics.headScripts.{label,description,help}
+settings.analytics.bodyScripts.{label,description,help}
+```
+
+**英文文案**:
+```json
+"analyticsSettings": "Analytics & Tracking"
+```
+```json
+"analytics": {
+ "sectionDescription": "Inject custom <script> tags into <head> and <body> for analytics, tracking, or structured data. Scripts run for all visitors. Only paste code you trust.",
+ "headScripts": {
+ "label": "Head Scripts",
+ "description": "HTML fragment with <script> tags to inject into <head>.",
+ "help": "Paste full <script>...</script> tags (multiple allowed). For GA, Baidu, Plausible, Umami, JSON-LD, etc. The existing Matomo integration runs independently."
+ },
+ "bodyScripts": {
+ "label": "Body Scripts",
+ "description": "HTML fragment with <script> tags to inject at the top of <body>.",
+ "help": "Paste full <script>...</script> tags (multiple allowed). Suitable for scripts that should run after the body opens."
+ }
+}
+```
+
+**简体中文(zh-Hans)参考**:
+- `analyticsSettings`: "分析与追踪"
+- `sectionDescription`: "将自定义 `<script>` 标签注入到页面 `<head>` 和 `<body>` 中,用于分析、追踪或结构化数据。脚本对所有访客执行,请仅粘贴可信代码。"
+- `headScripts.label`: "Head 脚本"
+- `headScripts.description`: "包含 `<script>` 标签的 HTML 片段,注入到页面 `<head>` 中。"
+- `headScripts.help`: "粘贴完整的 `<script>...</script>` 标签(支持多个)。适用于 GA、百度统计、Plausible、Umami、JSON-LD 等。已有的 Matomo 集成独立运行,互不干扰。"
+- `bodyScripts.label`: "Body 脚本"
+- `bodyScripts.description`: "包含 `<script>` 标签的 HTML 片段,注入到 `<body>` 开头。"
+- `bodyScripts.help`: "粘贴完整的 `<script>...</script>` 标签(支持多个)。适用于需要在 body 开始处执行的脚本。"
+
+zh-Hant-TW、zh-Hant-HK、ja 同步翻译,保持与现有 locale 文案语气一致。
+
+---
+
+## 验证方案
+
+### 手动验证流程
+
+1. **启动后默认行写入**:重启 dev server,检查 SQLite `settings` 表应出现 `analytics:headScripts` 与 `analytics:bodyScripts` 两行(`is_public=1`、`type='string'`)。可运行 `pnpm db:studio` 查看。
+
+2. **公开 API 暴露**:未登录访问 `GET /api/system/settings/all`,响应应包含 `analytics` namespace 与两个字段。
+
+3. **管理员字段获取**:登录管理员,`GET /api/system/settings/fields?namespace=analytics`,应返回 2 个 FieldDescriptor,`ui.type==='textarea'`、`ui.rows===12`、含 placeholder/help。
+
+4. **页面渲染**:访问 `/dashboard/settings/analytics`,确认:
+ - 标题显示"分析与追踪"
+ - 两个 12 行的等宽字体 textarea
+ - 修改后 Save 按钮启用,Reset 还原
+
+5. **保存 + 注入验证**:
+ - Head Scripts 粘贴 GA4 完整代码
+ - Body Scripts 粘贴 `<script src="https://umami.example.com/script.js" data-website-id="test" defer></script>`
+ - 保存后访问首页 `/`,查看页面源码:
+ - GA4 `<script>` 出现在 `<head>`(`async` 属性保留)
+ - Umami `<script>` 出现在 `<body>` 开头(`defer` 保留)
+ - 若 Matomo 已启用,其 `<script>` 仍在 `<head>`(未受影响)
+
+6. **属性保真**:测试自闭合 `<script src="x.js" async />`、`type="application/ld+json"` 内联脚本、带 `crossorigin`/`integrity` 的脚本,确认属性经过解析→注入后保留。
+
+7. **响应式**:在另一标签页修改脚本保存,原页面 `<head>`/`<body>` 应在 `refreshSettings()` 后自动更新(无需刷新)。
+
+8. **边界情况**:
+ - 空 textarea → 不注入任何标签
+ - 纯文本(无 `<script>`)→ 静默忽略
+ - 注释穿插在脚本之间 → 被剥离,脚本正常解析
+ - 畸形 `<script>未闭合` → 不匹配,静默丢弃
+
+9. **Matomo 非回归**:若 `NUXT_PUBLIC_ANALYTICS_MATOMO_ENABLED=true` 且配置了 url/siteId,Matomo tracker 仍正常加载。
+
+### 单元测试(可选)
+
+`parseScriptTags` 是纯函数,可用 vitest 测试:外链+async/defer、内联、自闭合、JSON-LD、多标签、注释、空输入、非法输入。
+
+---
+
+## 关键文件清单
+
+新建:
+- `app/utils/parseScriptTags.ts`
+- `app/plugins/custom-scripts.ts`
+- `app/pages/dashboard/settings/analytics.vue`
+
+修改:
+- `server/services/settings/contants.ts`(加 DEFAULT_SETTINGS 条目)
+- `server/services/settings/ui-config.ts`(加 ANALYTICS_SETTINGS_UI + 注册)
+- `shared/types/settings.ts`(FieldUIConfig 加 `rows?`)
+- `app/components/setting/SettingField.vue`(textarea 读取 `ui.rows`)
+- `app/layouts/dashboard.vue`(侧边栏菜单项)
+- `i18n/locales/en.json`、`zh-Hans.json`、`zh-Hant-TW.json`、`zh-Hant-HK.json`、`ja.json`(i18n keys)
+
+不动:
+- `app/plugins/analytics-tracker.client.ts`(Matomo 专用,保留)
+- `nuxt.config.ts` 中 `runtimeConfig.public.analytics.matomo`(保留)
diff --git a/app/components/setting/SettingField.vue b/app/components/setting/SettingField.vue
index bb03fd45..44386b98 100644
--- a/app/components/setting/SettingField.vue
+++ b/app/components/setting/SettingField.vue
@@ -97,7 +97,7 @@ const getComponentProps = (): Record<string, any> => {
: []
break
case 'textarea':
- propsMap.rows = 3
+ propsMap.rows = props.field.ui.rows ?? 3
break
}
diff --git a/app/layouts/dashboard.vue b/app/layouts/dashboard.vue
index c9c74f2a..b17a0766 100644
--- a/app/layouts/dashboard.vue
+++ b/app/layouts/dashboard.vue
@@ -68,6 +68,11 @@ const navItems = computed<NavigationMenuItem[][]>(() => [
icon: 'tabler:cpu',
to: '/dashboard/settings/system',
},
+ {
+ label: $t('title.analyticsSettings'),
+ icon: 'tabler:chart-bar',
+ to: '/dashboard/settings/analytics',
+ },
],
},
],
diff --git a/app/pages/dashboard/settings/analytics.vue b/app/pages/dashboard/settings/analytics.vue
new file mode 100644
index 00000000..8be88abf
--- /dev/null
+++ b/app/pages/dashboard/settings/analytics.vue
@@ -0,0 +1,141 @@
+<script lang="ts" setup>
+definePageMeta({
+ layout: 'dashboard',
+})
+
+useHead({
+ title: () => $t('title.analyticsSettings'),
+})
+
+const {
+ fields: analyticsFields,
+ state: analyticsState,
+ submit: submitAnalytics,
+ loading: analyticsLoading,
+} = useSettingsForm('analytics')
+
+const sameValue = (left: any, right: any) =>
+ JSON.stringify(left ?? null) === JSON.stringify(right ?? null)
+
+const isAnalyticsDirty = computed(() =>
+ analyticsFields.value.some(
+ (field) =>
+ !sameValue(
+ analyticsState[field.key],
+ field.value ?? field.defaultValue ?? null,
+ ),
+ ),
+)
+
+const resetAnalyticsSettings = () => {
+ analyticsFields.value.forEach((field) => {
+ analyticsState[field.key] = field.value ?? field.defaultValue ?? null
+ })
+}
+
+const handleAnalyticsSettingsSubmit = async () => {
+ const analyticsData = Object.fromEntries(
+ analyticsFields.value.map((f) => [f.key, analyticsState[f.key]]),
+ )
+ try {
+ await submitAnalytics(analyticsData)
+ } catch {
+ /* empty */
+ }
+}
+</script>
+
+<template>
+ <UDashboardPanel>
+ <template #header>
+ <UDashboardNavbar :title="$t('title.analyticsSettings')" />
+ </template>
+
+ <template #body>
+ <div class="mx-auto w-full max-w-5xl space-y-6">
+ <section
+ class="space-y-2 border-b border-neutral-200 pb-4 dark:border-neutral-800"
+ >
+ <h2
+ class="text-xl font-semibold text-neutral-900 dark:text-neutral-100"
+ >
+ {{ $t('title.analyticsSettings') }}
+ </h2>
+ <p class="text-sm text-neutral-600 dark:text-neutral-400">
+ {{ $t('settings.analytics.sectionDescription') }}
+ </p>
+ </section>
+
+ <section
+ class="rounded-md border border-neutral-200 bg-white dark:border-neutral-800 dark:bg-neutral-950"
+ >
+ <header
+ class="border-b border-neutral-200 px-5 py-4 dark:border-neutral-800"
+ >
+ <h3
+ class="text-base font-semibold text-neutral-900 dark:text-neutral-100"
+ >
+ {{ $t('title.analyticsSettings') }}
+ </h3>
+ </header>
+
+ <div
+ v-if="analyticsLoading && analyticsFields.length === 0"
+ class="space-y-4 px-5 py-5"
+ >
+ <USkeleton class="h-4 w-44" />
+ <USkeleton class="h-12 w-full" />
+ </div>
+
+ <UForm
+ v-else
+ id="analyticsSettingsForm"
+ class="space-y-5 px-5 py-5 [&_textarea]:font-mono [&_textarea]:text-xs"
+ @submit="handleAnalyticsSettingsSubmit"
+ >
+ <SettingField
+ v-for="field in analyticsFields"
+ :key="field.key"
+ :field="field"
+ :model-value="analyticsState[field.key]"
+ @update:model-value="(val) => (analyticsState[field.key] = val)"
+ />
+ </UForm>
+
+ <footer
+ class="border-t border-neutral-200 px-5 py-4 dark:border-neutral-800"
+ >
+ <div
+ v-if="isAnalyticsDirty"
+ class="mb-3 rounded-md border border-warning-200 bg-warning-50 px-3 py-2 text-sm text-warning-800 dark:border-warning-900/60 dark:bg-warning-950/30 dark:text-warning-200"
+ >
+ {{ $t('common.unsavedChanges') }}
+ </div>
+
+ <div class="flex items-center justify-end gap-2">
+ <UButton
+ color="neutral"
+ variant="outline"
+ :disabled="!isAnalyticsDirty"
+ @click="resetAnalyticsSettings"
+ >
+ {{ $t('common.actions.reset') }}
+ </UButton>
+ <UButton
+ :loading="analyticsLoading"
+ type="submit"
+ form="analyticsSettingsForm"
+ :disabled="!isAnalyticsDirty"
+ icon="tabler:device-floppy"
+ >
+ {{ $t('common.actions.saveSettings') }}
+ </UButton>
+ </div>
+ </footer>
+ </section>
+ </div>
+ </template>
+ </UDashboardPanel>
+</template>
+
+<style scoped></style>
diff --git a/app/plugins/custom-scripts.ts b/app/plugins/custom-scripts.ts
new file mode 100644
index 00000000..54d56fc8
--- /dev/null
+++ b/app/plugins/custom-scripts.ts
@@ -0,0 +1,47 @@
+import { parseScriptTags } from '~/utils/parseScriptTags'
+
+/**
+ * 将管理员配置的 <script> 标签注入到页面 <head> 和 <body> 中。
+ *
+ * 读取 settings store 中的 `analytics:headScripts` 与 `analytics:bodyScripts`
+ * (由 app.vue 中的 `await initSettings()` 在 SSR 渲染前完成填充),
+ * 通过正则解析为 useHead 接受的 script 数组。
+ *
+ * 与 analytics-tracker.client.ts(Matomo)独立并行,互不干扰:
+ * - 本插件负责管理员自定义脚本(GA、百度统计、Plausible、Umami、JSON-LD 等)
+ * - Matomo 插件负责 runtimeConfig 配置的 Matomo 实例
+ *
+ * 响应式:当 settings 通过 refreshSettings() 更新时,computed 会重算,
+ * useHead 自动同步 DOM。
+ */
+export default defineNuxtPlugin(() => {
+ const headScriptsRef = useSettingRef('analytics:headScripts')
+ const bodyScriptsRef = useSettingRef('analytics:bodyScripts')
+
+ useHead(
+ computed(() => {
+ // 防御 null:未初始化时 store 返回 null
+ const headParsed = parseScriptTags(String(headScriptsRef.value ?? ''))
+ const bodyParsed = parseScriptTags(String(bodyScriptsRef.value ?? ''))
+
+ // head 脚本注入到 <head>
+ const headScripts = headParsed.map((s, i) => ({
+ ...s,
+ tagPosition: 'head' as const,
+ // key 帮助 Unhead 在响应式更新时正确 diff,避免重复注入
+ key: `cf-analytics-head-${i}`,
+ }))
+
+ // body 脚本注入到 <body> 开头
+ const bodyScripts = bodyParsed.map((s, i) => ({
+ ...s,
+ tagPosition: 'bodyOpen' as const,
+ key: `cf-analytics-body-${i}`,
+ }))
+
+ return {
+ script: [...headScripts, ...bodyScripts],
+ }
+ }),
+ )
+})
diff --git a/app/utils/parseScriptTags.ts b/app/utils/parseScriptTags.ts
new file mode 100644
index 00000000..c4d07a01
--- /dev/null
+++ b/app/utils/parseScriptTags.ts
@@ -0,0 +1,159 @@
+export interface ParsedScriptTag {
+ /** 外链脚本 URL */
+ src?: string
+ /** 内联脚本内容 */
+ innerHTML?: string
+ /** 布尔属性:异步加载 */
+ async?: boolean
+ /** 布尔属性:延迟执行 */
+ defer?: boolean
+ /** 脚本类型(如 module / application/ld+json / application/json) */
+ type?: string
+ /** CORS 模式,true 表示 anonymous */
+ crossorigin?: boolean | 'anonymous' | 'use-credentials'
+ /** 子资源完整性哈希 */
+ integrity?: string
+ /** 布尔属性:仅在不支持 module 的浏览器执行 */
+ nomodule?: boolean
+ /** Referrer 策略 */
+ referrerpolicy?: string
+ /** CSP nonce */
+ nonce?: string
+}
+
+/** 剥离 HTML 注释(含多行) */
+const COMMENT_RE = /<!--[\s\S]*?-->/g
+
+/**
+ * 匹配 <script> 标签:
+ * - 分支 A:`<script attrs>content</script>`(含内容)
+ * - 分支 B:`<script attrs />`(自闭合,无内容)
+ *
+ * 已知限制:`[^>]*?` 无法处理属性值中包含 `>` 的情况。
+ * 统计代码场景中极为罕见,如遇到可手动拆分多个脚本。
+ */
+const SCRIPT_TAG_RE =
+ /<script\b([^>]*?)>([\s\S]*?)<\/script>|<script\b([^>]*?)\s*\/>/gi
+
+/**
+ * 属性解析:name(=value)?
+ * value 可为双引号、单引号或无引号形式。
+ * 布尔属性没有 =value 部分。
+ */
+const ATTR_RE =
+ /([a-zA-Z_:][\w:-]*)\s*(?:=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g
+
+/** 已知属性白名单 */
+const KNOWN_ATTRS = new Set([
+ 'src',
+ 'async',
+ 'defer',
+ 'type',
+ 'crossorigin',
+ 'integrity',
+ 'nomodule',
+ 'referrerpolicy',
+ 'nonce',
+])
+
+/** 布尔属性(出现即为 true) */
+const BOOLEAN_ATTRS = new Set(['async', 'defer', 'nomodule'])
+
+/**
+ * 将单个属性应用到输出对象上。
+ */
+function applyAttribute(
+ name: string,
+ value: string | true,
+ out: ParsedScriptTag,
+): void {
+ const lower = name.toLowerCase()
+ if (!KNOWN_ATTRS.has(lower)) return
+
+ if (BOOLEAN_ATTRS.has(lower)) {
+ ;(out as any)[lower] = true
+ return
+ }
+
+ if (lower === 'crossorigin') {
+ out.crossorigin = value === true ? true : (value as string)
+ return
+ }
+
+ ;(out as any)[lower] = value
+}
+
+/**
+ * 解析属性字符串为键值对并应用到输出对象。
+ */
+function parseAttributes(attrs: string, out: ParsedScriptTag): void {
+ ATTR_RE.lastIndex = 0
+ let match: RegExpExecArray | null
+ while ((match = ATTR_RE.exec(attrs)) !== null) {
+ const name = match[1]
+ // 优先级:双引号 > 单引号 > 无引号
+ const value = match[2] ?? match[3] ?? match[4]
+ applyAttribute(name, value === undefined ? true : value, out)
+ }
+}
+
+/**
+ * 解析原始 HTML 片段为 <script> 标签描述符数组。
+ *
+ * 行为:
+ * - 先剥离 HTML 注释
+ * - 同时匹配含内容与自闭合两种 <script> 形式
+ * - 解析 src/async/defer/type/crossorigin/integrity/nomodule/referrerpolicy/nonce
+ * - 跳过既无 src 又无 innerHTML 的空脚本
+ * - 不过滤 type(application/ld+json、module 等原样保留)
+ * - 永不抛错,输入非法或为空时返回 []
+ *
+ * @param raw 管理员粘贴的原始 HTML 片段
+ * @returns 解析后的 script 标签描述符数组,可直接传给 useHead({ script: [...] })
+ *
+ * @example
+ * parseScriptTags(`<script async src="a.js"></script>`)
+ * // => [{ src: 'a.js', async: true }]
+ *
+ * parseScriptTags(`<script>console.log('hi')</script>`)
+ * // => [{ innerHTML: "console.log('hi')" }]
+ */
+export function parseScriptTags(raw: string): ParsedScriptTag[] {
+ if (!raw || typeof raw !== 'string') return []
+
+ // 1. 剥离注释
+ const cleaned = raw.replace(COMMENT_RE, '')
+
+ const result: ParsedScriptTag[] = []
+
+ // 2. 逐个匹配 <script> 标签
+ SCRIPT_TAG_RE.lastIndex = 0
+ let match: RegExpExecArray | null
+ while ((match = SCRIPT_TAG_RE.exec(cleaned)) !== null) {
+ // 分支 A:含内容;分支 B:自闭合
+ const attrs = match[1] ?? match[3] ?? ''
+ const content = match[2] ?? ''
+
+ const tag: ParsedScriptTag = {}
+
+ // 3. 解析属性
+ parseAttributes(attrs, tag)
+
+ // 4. 填充内容:有 src 则不取 innerHTML,否则取文本内容
+ if (!tag.src) {
+ const trimmed = content.trim()
+ if (trimmed) {
+ tag.innerHTML = trimmed
+ }
+ }
+
+ // 5. 跳过空脚本(既无 src 又无 innerHTML)
+ if (!tag.src && !tag.innerHTML) {
+ continue
+ }
+
+ result.push(tag)
+ }
+
+ return result
+}
diff --git a/i18n/locales/en.json b/i18n/locales/en.json
index cd04c6bc..e1d758bf 100644
--- a/i18n/locales/en.json
+++ b/i18n/locales/en.json
@@ -399,7 +399,8 @@
"privacySettings": "Privacy Settings",
"mapAndLocation": "Map & Location",
"storageSettings": "Storage Settings",
- "systemSettings": "System Settings"
+ "systemSettings": "System Settings",
+ "analyticsSettings": "Analytics & Tracking"
},
"auth": {
"form": {
@@ -1385,6 +1386,19 @@
"create": "Create Storage"
}
},
+ "analytics": {
+ "sectionDescription": "Inject custom <script> tags into <head> and <body> for analytics, tracking, or structured data. Scripts run for all visitors. Only paste code you trust.",
+ "headScripts": {
+ "label": "Head Scripts",
+ "description": "HTML fragment with <script> tags to inject into <head>.",
+ "help": "Paste full <script>...</script> tags (multiple allowed). For GA, Baidu, Plausible, Umami, JSON-LD, etc. The existing Matomo integration runs independently."
+ },
+ "bodyScripts": {
+ "label": "Body Scripts",
+ "description": "HTML fragment with <script> tags to inject at the top of <body>.",
+ "help": "Paste full <script>...</script> tags (multiple allowed). Suitable for scripts that should run after the body opens."
+ }
+ },
"general": {
"description": "Manage the site's basic information and display appearance. Changes will immediately affect the dashboard and public-facing display."
},
diff --git a/i18n/locales/ja.json b/i18n/locales/ja.json
index f60bd1c3..64cf13c9 100644
--- a/i18n/locales/ja.json
+++ b/i18n/locales/ja.json
@@ -399,7 +399,8 @@
"mapAndLocation": "地図と場所",
"location": "位置情報サービス",
"storageSettings": "ストレージ設定",
- "systemSettings": "システム設定"
+ "systemSettings": "システム設定",
+ "analyticsSettings": "アナリティクスとトラッキング"
},
"auth": {
"form": {
@@ -1311,6 +1312,19 @@
"create": "ストレージを作成"
}
},
+ "analytics": {
+ "sectionDescription": "アナリティクス、トラッキング、または構造化データ用のカスタム <script> タグを <head> と <body> に注入します。スクリプトはすべての訪問者に実行されます。信頼できるコードのみ貼り付けてください。",
+ "headScripts": {
+ "label": "Head スクリプト",
+ "description": "<head> に注入する <script> タグを含む HTML 断片。",
+ "help": "完全な <script>...</script> タグを貼り付けます(複数可)。GA、百度統計、Plausible、Umami、JSON-LD などに適用。既存の Matomo 統合は独立して実行されます。"
+ },
+ "bodyScripts": {
+ "label": "Body スクリプト",
+ "description": "<body> の先頭に注入する <script> タグを含む HTML 断片。",
+ "help": "完全な <script>...</script> タグを貼り付けます(複数可)。body の開始時に実行する必要があるスクリプトに適しています。"
+ }
+ },
"general": {
"description": "サイトの基本情報と表示外観を管理します。変更はダッシュボードと公開側の表示に即時反映されます。"
},
diff --git a/i18n/locales/zh-Hans.json b/i18n/locales/zh-Hans.json
index 9964bc79..1a094a49 100644
--- a/i18n/locales/zh-Hans.json
+++ b/i18n/locales/zh-Hans.json
@@ -398,6 +398,7 @@
"storageSettings": "存储设置",
"privacySettings": "隐私设置",
"systemSettings": "系统设置",
+ "analyticsSettings": "分析与追踪",
"mapAndLocation": "地图和位置",
"location": "位置服务"
},
@@ -1385,6 +1386,19 @@
"create": "创建存储"
}
},
+ "analytics": {
+ "sectionDescription": "将自定义 <script> 标签注入到页面 <head> 和 <body> 中,用于分析、追踪或结构化数据。脚本对所有访客执行,请仅粘贴可信代码。",
+ "headScripts": {
+ "label": "Head 脚本",
+ "description": "包含 <script> 标签的 HTML 片段,注入到页面 <head> 中。",
+ "help": "粘贴完整的 <script>...</script> 标签(支持多个)。适用于 GA、百度统计、Plausible、Umami、JSON-LD 等。已有的 Matomo 集成独立运行,互不干扰。"
+ },
+ "bodyScripts": {
+ "label": "Body 脚本",
+ "description": "包含 <script> 标签的 HTML 片段,注入到 <body> 开头。",
+ "help": "粘贴完整的 <script>...</script> 标签(支持多个)。适用于需要在 body 开始处执行的脚本。"
+ }
+ },
"general": {
"description": "管理站点基础信息与展示外观。更改会立即影响控制台和前台展示。"
},
diff --git a/i18n/locales/zh-Hant-HK.json b/i18n/locales/zh-Hant-HK.json
index a4f71ade..97f151c8 100644
--- a/i18n/locales/zh-Hant-HK.json
+++ b/i18n/locales/zh-Hant-HK.json
@@ -399,7 +399,8 @@
"mapAndLocation": "地圖和位置",
"location": "位置服務",
"storageSettings": "儲存設定",
- "systemSettings": "系統設定"
+ "systemSettings": "系統設定",
+ "analyticsSettings": "分析與追蹤"
},
"auth": {
"form": {
@@ -1311,6 +1312,19 @@
"create": "建立儲存"
}
},
+ "analytics": {
+ "sectionDescription": "將自訂 <script> 標籤注入到頁面 <head> 和 <body> 中,用於分析、追蹤或結構化資料。指令碼對所有訪客執行,請僅貼上可信程式碼。",
+ "headScripts": {
+ "label": "Head 指令碼",
+ "description": "包含 <script> 標籤的 HTML 片段,注入到頁面 <head> 中。",
+ "help": "貼上完整的 <script>...</script> 標籤(支援多個)。適用於 GA、百度統計、Plausible、Umami、JSON-LD 等。已有的 Matomo 整合獨立執行,互不干擾。"
+ },
+ "bodyScripts": {
+ "label": "Body 指令碼",
+ "description": "包含 <script> 標籤的 HTML 片段,注入到 <body> 開頭。",
+ "help": "貼上完整的 <script>...</script> 標籤(支援多個)。適用於需要在 body 開始處執行的指令碼。"
+ }
+ },
"general": {
"description": "管理站點基礎資訊與展示外觀。更改會立即影響控制台和前台展示。"
},
diff --git a/i18n/locales/zh-Hant-TW.json b/i18n/locales/zh-Hant-TW.json
index a0a90867..a25ef09a 100644
--- a/i18n/locales/zh-Hant-TW.json
+++ b/i18n/locales/zh-Hant-TW.json
@@ -399,7 +399,8 @@
"mapAndLocation": "地圖和位置",
"location": "位置服務",
"storageSettings": "儲存設定",
- "systemSettings": "系統設定"
+ "systemSettings": "系統設定",
+ "analyticsSettings": "分析與追蹤"
},
"auth": {
"form": {
@@ -1311,6 +1312,19 @@
"create": "建立儲存"
}
},
+ "analytics": {
+ "sectionDescription": "將自訂 <script> 標籤注入到頁面 <head> 和 <body> 中,用於分析、追蹤或結構化資料。指令碼對所有訪客執行,請僅貼上可信程式碼。",
+ "headScripts": {
+ "label": "Head 指令碼",
+ "description": "包含 <script> 標籤的 HTML 片段,注入到頁面 <head> 中。",
+ "help": "貼上完整的 <script>...</script> 標籤(支援多個)。適用於 GA、百度統計、Plausible、Umami、JSON-LD 等。已有的 Matomo 整合獨立執行,互不干擾。"
+ },
+ "bodyScripts": {
+ "label": "Body 指令碼",
+ "description": "包含 <script> 標籤的 HTML 片段,注入到 <body> 開頭。",
+ "help": "貼上完整的 <script>...</script> 標籤(支援多個)。適用於需要在 body 開始處執行的指令碼。"
+ }
+ },
"general": {
"description": "管理站點基礎資訊與展示外觀。更改會立即影響控制台和前台展示。"
},
diff --git a/server/services/settings/contants.ts b/server/services/settings/contants.ts
index 206695e3..ba241252 100644
--- a/server/services/settings/contants.ts
+++ b/server/services/settings/contants.ts
@@ -221,6 +221,25 @@ export const DEFAULT_SETTINGS = [
label: 'settings.storage_provider.provider.label',
description: 'settings.storage_provider.provider.description',
},
+ // NAMESPACE: analytics
+ {
+ namespace: 'analytics',
+ key: 'headScripts',
+ type: 'string',
+ defaultValue: '',
+ label: 'settings.analytics.headScripts.label',
+ description: 'settings.analytics.headScripts.description',
+ isPublic: true,
+ },
+ {
+ namespace: 'analytics',
+ key: 'bodyScripts',
+ type: 'string',
+ defaultValue: '',
+ label: 'settings.analytics.bodyScripts.label',
+ description: 'settings.analytics.bodyScripts.description',
+ isPublic: true,
+ },
] as const satisfies SettingConfig[]
export const settingNamespaces = [
diff --git a/server/services/settings/ui-config.ts b/server/services/settings/ui-config.ts
index 59082335..cb5c598f 100644
--- a/server/services/settings/ui-config.ts
+++ b/server/services/settings/ui-config.ts
@@ -116,6 +116,23 @@ export const PRIVACY_SETTINGS_UI: Record<string, FieldUIConfig> = {
},
}
+export const ANALYTICS_SETTINGS_UI: Record<string, FieldUIConfig> = {
+ headScripts: {
+ type: 'textarea',
+ rows: 12,
+ placeholder:
+ '<!-- Google Analytics -->\n<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXX"></script>\n<script>\n window.dataLayer = window.dataLayer || [];\n function gtag(){dataLayer.push(arguments);}\n gtag(\'js\', new Date());\n gtag(\'config\', \'G-XXXX\');\n</script>',
+ help: 'settings.analytics.headScripts.help',
+ },
+ bodyScripts: {
+ type: 'textarea',
+ rows: 12,
+ placeholder:
+ '<!-- Umami / Openpanel SDK -->\n<script src="https://analytics.example.com/script.js" data-website-id="xxx" defer></script>',
+ help: 'settings.analytics.bodyScripts.help',
+ },
+}
+
export const SYSTEM_SETTINGS_UI: Record<string, FieldUIConfig> = {
'upload.maxFileSize': {
type: 'number',
@@ -343,6 +360,7 @@ export function getSettingUIConfig(
map: MAP_SETTINGS_UI,
location: LOCATION_SETTINGS_UI,
storage: STORAGE_SETTINGS_UI,
+ analytics: ANALYTICS_SETTINGS_UI,
}
return uiConfigMap[namespace]?.[key]
diff --git a/shared/types/settings.ts b/shared/types/settings.ts
index 27e90471..9916fa6f 100644
--- a/shared/types/settings.ts
+++ b/shared/types/settings.ts
@@ -76,6 +76,10 @@ export interface FieldUIConfig {
size?: 'sm' | 'md' | 'lg'
variant?: 'soft' | 'outline'
icon?: string
+
+ // 行数(仅用于 textarea 类型,可选)
+ // SettingField.vue 默认值为 3
+ rows?: number
}
/**