fix: 收敛正确性缺口并补齐质量门禁

备份、隧道生命周期、日志、会话与设置项存在一批「静默失效」问题，本次一并收敛。

正确性：
- 备份归档补上 session_secret 与 frp 配置。缺密钥时换机恢复后库里所有凭据都解不开，
  界面表现为「配置都在、一执行就报解密失败」；同时支持口令加密（scrypt + AES-256-GCM）。
- 修复「立即备份」必失败：tar 头用的是遍历时的文件尺寸，而 logs、frpc 配置在打包期间
  还在增长，读出的字节多于声明值导致 archive/tar 报错、整份备份作废。改为打开后重新
  取尺寸并用 LimitReader 兜住，被截短时补零保持条目结构完整。
- 数据库改用 VACUUM INTO 生成一致性快照。直接打包正在写入的 SQLite 文件可能得到
  结构完整但内容自相矛盾的副本，恢复后才暴露。
- Cloudflare 启动改用 StartAuto，Shutdown 显式 StopAll，子进程绑定应用 ctx。此前
  重启会把用户手动停掉的隧道重新拉起，退出也可能留下孤儿进程。
- Nginx 访问/错误日志加轮转（200MB 阈值、gzip 归档、USR1 重开），读取改为从文件尾
  分块倒读，并跨当日归档统计。此前日志只增不减，读接口每次全量扫描。
- 过期会话改由日任务清理；删除反代规则时同步清掉流量累计，避免同名规则重建继承旧读数。
- 启动加就绪门：Nginx bootstrap 完成后再放行 FRP 对账、Agent 隧道与 Cloudflare 自启。

设置项：
- 新增设置项注册表（internal/settings/registry.go），白名单与默认值从它派生，
  并记录每个键的消费者，防止再出现「界面能改、后端没人读」的黑洞设置。
- 接上三个此前不生效的设置项：timezone（启动与保存时应用到 time.Local）、
  theme（后端为权威源，挂载时覆盖本地偏好、顶栏切换回写）、log_retention_days
  （控制日志归档保留天数）。

工程质量：
- gofmt 全量格式化 23 个历史文件，CI 增加格式化门禁。
- 前端引入 ESLint（flat config）与 lint 脚本，CI 增加 lint 步骤；顺带修掉
  logDisplay 的 let→const 与 LogsView 模板内直接改 prop 两处问题。
- 删除无引用的 pnpm-lock.yaml，prototype/ 加入忽略列表。
- 打包版本对齐：Docker manifest 同步到 2.0.0，CI 校验 VERSION 与 package.json 一致。

验证：gofmt 0 文件、go vet、go test ./...、npm run lint/typecheck/test/build 全绿。

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

web/eslint.config.js

@@ -0,0 +1,103 @@
+import js from '@eslint/js'
+import pluginVue from 'eslint-plugin-vue'
+import tseslint from 'typescript-eslint'
+
+// 说明：这份配置刻意只开「低争议」规则。
+// 项目里已有 2.7 万行前端代码，一次性打开 recommended 全量会砸出几千条告警，
+// 反而没人看。先把「未使用变量 / 未定义变量 / == 与 ===」这类真问题卡住，
+// 再逐步加规则。vite.config.ts 里已经在 build 前跑 vue-tsc，类型问题由它兜。
+export default tseslint.config(
+  {
+    ignores: ['dist/**', 'node_modules/**', 'src/**/*.d.ts'],
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  ...pluginVue.configs['flat/essential'],
+  {
+    files: ['**/*.{ts,vue}'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      // Vue SFC 的 <script setup lang="ts"> 必须显式指定 TS 解析器，
+      // 否则 eslint-plugin-vue 用的默认解析器不认识类型标注，会报
+      // 「Parsing error: Unexpected token XxxType」。
+      parserOptions: {
+        parser: tseslint.parser,
+        extraFileExtensions: ['.vue'],
+        ecmaFeatures: { jsx: false },
+      },
+      globals: {
+        // 浏览器环境
+        window: 'readonly',
+        document: 'readonly',
+        navigator: 'readonly',
+        localStorage: 'readonly',
+        sessionStorage: 'readonly',
+        fetch: 'readonly',
+        FormData: 'readonly',
+        Blob: 'readonly',
+        URL: 'readonly',
+        EventSource: 'readonly',
+        WebSocket: 'readonly',
+        ResizeObserver: 'readonly',
+        MutationObserver: 'readonly',
+        HTMLElement: 'readonly',
+        HTMLInputElement: 'readonly',
+        HTMLTextAreaElement: 'readonly',
+        HTMLDivElement: 'readonly',
+        HTMLCanvasElement: 'readonly',
+        Node: 'readonly',
+        Element: 'readonly',
+        Event: 'readonly',
+        KeyboardEvent: 'readonly',
+        MouseEvent: 'readonly',
+        AbortController: 'readonly',
+        setTimeout: 'readonly',
+        clearTimeout: 'readonly',
+        setInterval: 'readonly',
+        clearInterval: 'readonly',
+        requestAnimationFrame: 'readonly',
+        cancelAnimationFrame: 'readonly',
+        matchMedia: 'readonly',
+        console: 'readonly',
+        crypto: 'readonly',
+        performance: 'readonly',
+        // 构建期注入
+        __APP_VERSION__: 'readonly',
+      },
+    },
+    rules: {
+      // 真问题：未使用变量、未定义变量
+      'no-unused-vars': 'off',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          caughtErrors: 'none',
+        },
+      ],
+      // 宽松处理 any：现有 API 类型里有历史遗留，先不拦
+      '@typescript-eslint/no-explicit-any': 'off',
+      // 空块与空接口在这类前端代码里常用于「占位」，不视为错误
+      'no-empty': ['error', { allowEmptyCatch: true }],
+      // Vue：多词组件名不强求（现有单文件组件已大量单词名）
+      'vue/multi-word-component-names': 'off',
+      // 未使用组件显式注册检查交由 vue-tsc
+      'vue/no-unused-components': 'off',
+      // TaskProviderForm / LogsView 里的 form、autoRefresh 都是 v-model 双向绑定的 prop。
+      // 这是 Vue 官方推荐写法（父组件传 ref，子组件 v-model 直接改），规则默认会误报。
+      'vue/no-mutating-props': ['error', { shallowOnly: true }],
+    },
+  },
+  {
+    // 配置文件与脚本允许 CommonJS 风格的环境
+    files: ['*.config.{ts,js}', 'vite.config.ts'],
+    languageOptions: {
+      globals: {
+        process: 'readonly',
+        __dirname: 'readonly',
+      },
+    },
+  },
+)

web/package.json

@@ -9,7 +9,8 @@
     "build": "vue-tsc --noEmit && vite build",
     "preview": "vite preview",
     "typecheck": "vue-tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "lint": "eslint . --max-warnings=0"
   },
   "dependencies": {
     "@codemirror/commands": "^6.11.1",
@@ -33,9 +34,14 @@
     "vue-router": "^4.5.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.5",
     "@types/sortablejs": "^1.15.9",
     "@vitejs/plugin-vue": "^5.2.1",
+    "eslint": "^9.39.4",
+    "eslint-plugin-vue": "^9.33.0",
+    "globals": "^15.15.0",
     "typescript": "^5.7.2",
+    "typescript-eslint": "^8.72.0",
     "vite": "^6.0.3",
     "vitest": "^5.0.1",
     "vue-tsc": "^2.2.0"

web/src/api/client.ts

@@ -61,6 +61,14 @@ export function asList<T>(value: T[] | null | undefined): T[] {
   return Array.isArray(value) ? value : []
 }
 
+// backupHeaders 把可选的归档口令放进请求头。
+// 用请求头而不是查询串：查询串会进 Nginx 访问日志，口令不该落盘。
+function backupHeaders(passphrase?: string): HeadersInit | undefined {
+  const value = passphrase?.trim()
+  if (!value) return undefined
+  return { 'X-Backup-Passphrase': value }
+}
+
 const REQUEST_TIMEOUT_MS = 30_000
 const CERT_REQUEST_TIMEOUT_MS = 10 * 60_000
 const AGENT_OPERATION_TIMEOUT_MS = 5 * 60_000
@@ -455,8 +463,11 @@ export const api = {
     return request<DiscoveredService[]>(`/api/discovery/scan?${q}`)
   },
 
-  async exportBackup() {
-    const response = await fetch(withBase('/api/backup/export'), { credentials: 'include' })
+  async exportBackup(passphrase?: string) {
+    const response = await fetch(withBase('/api/backup/export'), {
+      credentials: 'include',
+      headers: backupHeaders(passphrase),
+    })
     if (!response.ok) {
       throw new Error('导出备份失败')
     }
@@ -471,10 +482,16 @@ export const api = {
 
   listBackupArchives: () =>
     request<{ archives: import('./types').BackupArchive[]; keep: number }>('/api/backup/archives'),
-  createBackupArchive: () =>
-    request<{ name: string; removed: number }>('/api/backup/archives', { method: 'POST' }),
-  restoreBackupArchive: (name: string) =>
-    request<{ message: string }>(`/api/backup/archives/${encodeURIComponent(name)}/restore`, { method: 'POST' }),
+  createBackupArchive: (passphrase?: string) =>
+    request<{ name: string; removed: number }>('/api/backup/archives', {
+      method: 'POST',
+      headers: backupHeaders(passphrase),
+    }),
+  restoreBackupArchive: (name: string, passphrase?: string) =>
+    request<{ message: string }>(`/api/backup/archives/${encodeURIComponent(name)}/restore`, {
+      method: 'POST',
+      headers: backupHeaders(passphrase),
+    }),
   deleteBackupArchive: (name: string) =>
     request<{ ok: boolean }>(`/api/backup/archives/${encodeURIComponent(name)}`, { method: 'DELETE' }),
   async downloadBackupArchive(name: string) {
@@ -491,12 +508,13 @@ export const api = {
     URL.revokeObjectURL(url)
   },
 
-  async restoreBackup(file: File) {
+  async restoreBackup(file: File, passphrase?: string) {
     const form = new FormData()
     form.append('file', file)
     const response = await fetch(withBase('/api/backup/restore'), {
       method: 'POST',
       credentials: 'include',
+      headers: backupHeaders(passphrase),
       body: form,
     })
     if (!response.ok) {

web/src/composables/useTheme.ts

@@ -115,6 +115,19 @@ export function useTheme() {
     themeMode.value = isDark.value ? 'light' : 'dark'
   }
 
+  // syncFromSettings 用后端设置覆盖本地偏好。
+  //
+  // 后端 settings.theme 是唯一权威来源（这样换浏览器、换设备看到的是同一个主题），
+  // localStorage 只作为「拿到后端值之前」的快速回显，避免首屏闪一下浅色。
+  // 调用方在登录后拉一次 /api/settings 时调用它。
+  function syncFromSettings(mode: string | undefined) {
+    const value = (mode ?? '').trim()
+    if (!value) return
+    if (value !== 'system' && value !== 'light' && value !== 'dark') return
+    if (value === themeMode.value) return
+    themeMode.value = value
+  }
+
   watch(
     themeMode,
     (value) => {
@@ -132,5 +145,5 @@ export function useTheme() {
     })
   }
 
-  return { themeMode, naiveTheme, themeOverrides, isDark, toggleTheme, setThemeMode }
+  return { themeMode, naiveTheme, themeOverrides, isDark, toggleTheme, setThemeMode, syncFromSettings }
 }

web/src/layouts/AppLayout.vue

@@ -77,7 +77,7 @@
       <header class="topbar">
         <span class="topbar__datetime">{{ datetime }}</span>
         <div class="topbar__right">
-          <n-button quaternary circle @click="toggleTheme">
+          <n-button quaternary circle @click="handleToggleTheme">
             <template #icon>
               <n-icon :component="isDark ? MoonOutline : SunnyOutline" />
             </template>
@@ -148,7 +148,7 @@ import UpdateModal from '../components/UpdateModal.vue'
 const route = useRoute()
 const router = useRouter()
 const message = useMessage()
-const { isDark, toggleTheme } = useTheme()
+const { isDark, themeMode, toggleTheme, syncFromSettings } = useTheme()
 const collapsed = ref(false)
 const datetime = ref('')
 const appVersion = ref(__APP_VERSION__)
@@ -243,6 +243,18 @@ function handleMenu(key: string) {
   router.push({ name: key })
 }
 
+// handleToggleTheme 顶栏的快捷切换：本地立即生效，同时回写后端设置。
+// 不回写的话会出现「这里切了、设置页显示的还是旧值」，下次任何一次保存设置
+// 又会把主题改回去。
+async function handleToggleTheme() {
+  toggleTheme()
+  try {
+    await api.saveSettings({ theme: themeMode.value })
+  } catch {
+    // 回写失败不影响当前会话的外观，下次进设置页仍能看到服务端的值
+  }
+}
+
 async function handleUserMenu(key: string) {
   if (key === 'logout') {
     await api.logout()
@@ -255,6 +267,16 @@ onMounted(() => {
   loadVersion()
   updateClock()
   clockTimer = window.setInterval(updateClock, 30_000)
+  // 主题以后端设置为准：localStorage 只是首屏回显，登录后要用服务端的值覆盖，
+  // 否则换设备/换浏览器两个人看到的是不同主题（而设置页显示的是服务端那个）。
+  api
+    .getSettings()
+    .then((settings) => {
+      syncFromSettings(settings.theme)
+    })
+    .catch(() => {
+      // 读不到设置就沿用本地偏好，不影响使用
+    })
 })
 
 onUnmounted(() => {

web/src/utils/logDisplay.ts

@@ -43,7 +43,7 @@ export function displaySystemLog(entry: SystemLogEntry): DisplaySystemLogEntry {
   const message = entry.message.trim()
   const msgLower = message.toLowerCase()
   let level = entry.level.trim().toUpperCase()
-  let displayModule = systemModuleLabel(entry.module)
+  const displayModule = systemModuleLabel(entry.module)
 
   if (
     level === 'INFO' &&

web/src/views/LogsView.vue

@@ -130,7 +130,7 @@
           :show-status="true"
           :auto-refresh="autoRefresh"
           @refresh="loadAccess"
-          @toggle-auto="autoRefresh = !autoRefresh"
+          @toggle-auto="toggleAutoRefresh"
         />
         <n-data-table
           v-if="filteredAccessLogs.length > 0"
@@ -318,6 +318,13 @@ const tab = ref(resolveTab(route.query.tab))
 const pageError = ref('')
 const autoRefresh = ref(false)
 
+// toggleAutoRefresh 用函数而不是在模板里直接赋值：
+// LogToolbar 是 defineComponent + props 的子组件，在模板里写 autoRefresh = !autoRefresh
+// 会被 eslint 判成「修改 prop」（模板作用域里分不清 ref 与 prop），也容易误改到子组件状态。
+function toggleAutoRefresh() {
+  autoRefresh.value = !autoRefresh.value
+}
+
 const accessLogs = ref<AccessLogEntry[]>([])
 const proxyRules = ref<ProxyRule[]>([])
 const proxyBindingIndex = computed(() => buildProxyBindingIndex(proxyRules.value))

web/src/views/SettingsView.vue

@@ -34,7 +34,7 @@
         <div class="settings-block settings-block--spaced">
           <div class="settings-block__label">时区</div>
           <n-select v-model:value="form.timezone" :options="timezoneOptions" />
-          <p class="field-hint">影响日志、证书到期时间等显示</p>
+          <p class="field-hint">决定通知消息里的时间戳与后端日志时间（保存后立即生效）</p>
         </div>
       </HavlineCard>
 
@@ -59,7 +59,9 @@
               <span class="settings-field__label">日志保留天数</span>
               <n-input-number v-model:value="logRetention" :min="1" :max="365" class="settings-field__input" />
             </div>
-            <p class="field-hint">超过保留天数的日志将被自动清理</p>
+            <p class="field-hint">
+              Nginx 访问/错误日志超过 200MB 会轮转归档，这里控制归档文件保留多少天
+            </p>
           </div>
         </div>
       </HavlineCard>
@@ -130,6 +132,19 @@
             </div>
           </n-upload>
         </div>
+        <div class="backup-passphrase">
+          <n-input
+            v-model:value="backupPassphrase"
+            type="password"
+            show-password-on="click"
+            placeholder="归档口令（可选）"
+            class="backup-passphrase__input"
+          />
+          <p class="field-hint">
+            填写后导出与「立即备份」会产出加密归档，恢复与校验时需要同一个口令；
+            自动备份不加密（口令存在同一台设备上等于没有加密）。留空则使用原有未加密格式。
+          </p>
+        </div>
         <div class="backup-auto">
           <div class="form-switch-row">
             <div class="form-switch-row__text">
@@ -917,6 +932,8 @@ const backupKeepCount = ref(DEFAULT_BACKUP_KEEP_COUNT)
 const backupArchives = ref<BackupArchive[]>([])
 const backupBusy = ref<string | null>(null)
 const backupError = ref('')
+// 可选的归档口令：只放内存，不写 localStorage（加密归档的口令不该留在浏览器里）
+const backupPassphrase = ref('')
 
 // 公开状态页：开关与访问码走设置项（访问码按「掩码往返」处理）
 const statusPageEnabled = ref(false)
@@ -1700,7 +1717,7 @@ async function createBackupArchive() {
   if (backupBusy.value) return
   backupBusy.value = 'create'
   try {
-    await api.createBackupArchive()
+    await api.createBackupArchive(backupPassphrase.value)
     await loadBackupArchives()
     message.success('已创建一份备份')
   } catch (error) {
@@ -1730,7 +1747,7 @@ async function downloadBackupArchive(archive: BackupArchive) {
 async function restoreBackupArchive(archive: BackupArchive) {
   backupBusy.value = `restore:${archive.name}`
   try {
-    const result = await api.restoreBackupArchive(archive.name)
+    const result = await api.restoreBackupArchive(archive.name, backupPassphrase.value)
     message.success(result.message || '备份已恢复，建议重启 Havline')
   } catch (error) {
     message.error(error instanceof Error ? error.message : '恢复失败')
@@ -1756,7 +1773,7 @@ function openStatusPage() {
 async function exportBackup() {
   exporting.value = true
   try {
-    await api.exportBackup()
+    await api.exportBackup(backupPassphrase.value)
     message.success('备份已开始下载')
   } catch (error) {
     message.error(error instanceof Error ? error.message : '导出失败')
@@ -1769,7 +1786,7 @@ async function onRestoreFile({ file }: { file: UploadFileInfo }) {
   if (!file.file) return
   restoring.value = true
   try {
-    const result = await api.restoreBackup(file.file)
+    const result = await api.restoreBackup(file.file, backupPassphrase.value)
     message.success(result.message)
   } catch (error) {
     message.error(error instanceof Error ? error.message : '恢复失败')
@@ -1925,6 +1942,12 @@ useVisibilityPolling(loadChinaCIDRStatus, 2000, { enabled: chinaCIDRPolling })
 .config-versions__error { margin: 8px 0 0; font-size: 12px; color: var(--havline-error); line-height: 1.6; }
 
 /* 自动备份：开关 + 保留份数 + 备份列表 */
+.backup-passphrase {
+  display: grid; gap: 6px;
+  margin-top: var(--havline-space-4); padding-top: var(--havline-space-4);
+  border-top: 1px solid var(--havline-border);
+}
+.backup-passphrase__input { max-width: 320px; }
 .backup-auto {
   display: grid; gap: var(--havline-space-3);
   margin-top: var(--havline-space-4); padding-top: var(--havline-space-4);