Merge pull request #706 from carexdk/fix/theme-extract-dir-perm

fix(theme): create extracted directories with 0755

.github/actions/build-frontend/action.yml

@@ -0,0 +1,74 @@
+name: Build frontend theme
+description: Clone komari-web, build the default theme, and optionally upload it as an artifact.
+
+inputs:
+  node-version:
+    description: Node.js version used to build komari-web.
+    default: "23"
+  repository:
+    description: komari-web repository URL.
+    default: https://github.com/komari-monitor/komari-web
+  ref:
+    description: Optional komari-web ref to build. Uses the repository default branch when empty.
+    default: ""
+  artifact-name:
+    description: Optional artifact name for the packed frontend theme.
+    default: ""
+
+runs:
+  using: composite
+  steps:
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ inputs.node-version }}
+
+    - name: Install zstd
+      shell: bash
+      run: |
+        set -euxo pipefail
+        if ! command -v zstd >/dev/null 2>&1; then
+          sudo apt-get update
+          sudo apt-get install -y zstd
+        fi
+
+    - name: Clone and build frontend
+      shell: bash
+      run: |
+        set -euxo pipefail
+        rm -rf komari-web
+        if [ -n "${{ inputs.ref }}" ]; then
+          git clone --depth=1 --branch "${{ inputs.ref }}" "${{ inputs.repository }}" komari-web
+        else
+          git clone --depth=1 "${{ inputs.repository }}" komari-web
+        fi
+        cd komari-web
+        npm install
+        npm run build
+        cd ..
+
+        mkdir -p web/public/defaultTheme
+        rm -rf web/public/defaultTheme/dist web/public/defaultTheme/dist.tar.zst
+        test -f komari-web/dist/index.html
+        tar -cf "$RUNNER_TEMP/komari-default-dist.tar" -C komari-web/dist .
+        zstd -19 -T0 -q -f "$RUNNER_TEMP/komari-default-dist.tar" -o web/public/defaultTheme/dist.tar.zst
+        rm -f "$RUNNER_TEMP/komari-default-dist.tar"
+        cp -f komari-web/komari-theme.json web/public/defaultTheme/
+        if [ -f komari-web/preview.png ]; then cp -f komari-web/preview.png web/public/defaultTheme/; fi
+        if [ -f komari-web/perview.png ]; then cp -f komari-web/perview.png web/public/defaultTheme/; fi
+        if [ -f web/public/defaultTheme/preview.png ] && [ ! -f web/public/defaultTheme/perview.png ]; then cp -f web/public/defaultTheme/preview.png web/public/defaultTheme/perview.png; fi
+        if [ -f web/public/defaultTheme/perview.png ] && [ ! -f web/public/defaultTheme/preview.png ]; then cp -f web/public/defaultTheme/perview.png web/public/defaultTheme/preview.png; fi
+
+    - name: Pack frontend artifact
+      if: ${{ inputs.artifact-name != '' }}
+      shell: bash
+      run: |
+        set -euxo pipefail
+        tar -czf "$RUNNER_TEMP/${{ inputs.artifact-name }}.tar.gz" -C web/public/defaultTheme .
+
+    - name: Upload frontend artifact
+      if: ${{ inputs.artifact-name != '' }}
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ inputs.artifact-name }}
+        path: ${{ runner.temp }}/${{ inputs.artifact-name }}.tar.gz

.github/actions/restore-frontend/action.yml

@@ -0,0 +1,25 @@
+name: Restore frontend theme
+description: Download and unpack a previously built frontend theme artifact.
+
+inputs:
+  artifact-name:
+    description: Frontend theme artifact name.
+    default: komari-frontend
+
+runs:
+  using: composite
+  steps:
+    - name: Download frontend artifact
+      uses: actions/download-artifact@v4
+      with:
+        name: ${{ inputs.artifact-name }}
+        path: ${{ runner.temp }}/frontend-artifact
+
+    - name: Extract frontend artifact
+      shell: bash
+      run: |
+        set -euxo pipefail
+        mkdir -p web/public/defaultTheme
+        rm -rf web/public/defaultTheme/*
+        tar -xzf "$RUNNER_TEMP/frontend-artifact/${{ inputs.artifact-name }}.tar.gz" -C web/public/defaultTheme
+        test -s web/public/defaultTheme/dist.tar.zst

.github/actions/setup-zig/action.yml

@@ -0,0 +1,31 @@
+name: Setup Zig
+description: Restore or install the Zig toolchain used for CGO cross-compilation.
+
+inputs:
+  zig-version:
+    description: Zig version to install.
+    default: 0.14.1
+
+runs:
+  using: composite
+  steps:
+    - name: Restore Zig cache
+      id: zig-cache
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/komari-zig/zig-x86_64-linux-${{ inputs.zig-version }}
+        key: zig-${{ runner.os }}-x86_64-${{ inputs.zig-version }}
+
+    - name: Download Zig
+      if: ${{ steps.zig-cache.outputs.cache-hit != 'true' }}
+      shell: bash
+      run: |
+        set -euxo pipefail
+        mkdir -p "$HOME/.cache/komari-zig"
+        curl -fsSL "https://ziglang.org/download/${{ inputs.zig-version }}/zig-x86_64-linux-${{ inputs.zig-version }}.tar.xz" -o "$RUNNER_TEMP/zig.tar.xz"
+        tar -C "$HOME/.cache/komari-zig" -Jxf "$RUNNER_TEMP/zig.tar.xz"
+
+    - name: Add Zig to PATH
+      shell: bash
+      run: |
+        echo "$HOME/.cache/komari-zig/zig-x86_64-linux-${{ inputs.zig-version }}" >> "$GITHUB_PATH"

.github/workflows/build.yml

@@ -1,16 +1,26 @@
-name: Build Binaries on Main Push and PR
+name: Build Binaries on PR
 
 on:
-  push:
-    branches:
-      - main
   pull_request:
     branches:
       - main
   workflow_dispatch:
 
 jobs:
+  build-frontend:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Build frontend artifact
+        uses: ./.github/actions/build-frontend
+        with:
+          artifact-name: komari-frontend
+
   build-binaries:
+    needs: build-frontend
     runs-on: ubuntu-latest
 
     strategy:
@@ -49,6 +59,10 @@ jobs:
             goarch: riscv64
             zig_target_triple: riscv64-linux-musl
             binary_extension: ""
+          - goos: linux
+            goarch: loong64
+            zig_target_triple: loongarch64-linux-musl
+            binary_extension: ""
 
         exclude:
           - goos: windows
@@ -58,27 +72,8 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "23"
-
-      - name: Clone and build frontend
-        run: |
-          git clone https://github.com/komari-monitor/komari-web komari-web
-          cd komari-web
-          npm install
-          npm run build
-          cd ..
-          mkdir -p web/public/defaultTheme/dist
-          rm -rf web/public/defaultTheme/dist/*
-          cp -r komari-web/dist/* web/public/defaultTheme/dist/
-          cp -f komari-web/komari-theme.json web/public/defaultTheme/
-          if [ -f komari-web/preview.png ]; then cp -f komari-web/preview.png web/public/defaultTheme/; fi
-          if [ -f komari-web/perview.png ]; then cp -f komari-web/perview.png web/public/defaultTheme/; fi
-          # Compatibility: ensure both filenames exist if only one is present
-          if [ -f web/public/defaultTheme/preview.png ] && [ ! -f web/public/defaultTheme/perview.png ]; then cp -f web/public/defaultTheme/preview.png web/public/defaultTheme/perview.png; fi
-          if [ -f web/public/defaultTheme/perview.png ] && [ ! -f web/public/defaultTheme/preview.png ]; then cp -f web/public/defaultTheme/perview.png web/public/defaultTheme/preview.png; fi
+      - name: Restore frontend artifact
+        uses: ./.github/actions/restore-frontend
 
       - name: Set up Go
         uses: actions/setup-go@v5
@@ -86,12 +81,7 @@ jobs:
           go-version: "1.23"
 
       - name: Install Zig cross-compiler toolchain
-        run: |
-          sudo apt-get update # Update apt package lists
-          sudo apt-get install -y build-essential curl
-          wget https://ziglang.org/download/0.14.1/zig-x86_64-linux-0.14.1.tar.xz
-          sudo tar -C /usr/local -Jxf zig-x86_64-linux-0.14.1.tar.xz
-          echo "PATH=$PATH:/usr/local/zig-x86_64-linux-0.14.1" >> $GITHUB_ENV
+        uses: ./.github/actions/setup-zig
 
       - name: Build binary
         env:
@@ -108,7 +98,11 @@ jobs:
           fi
           VERSION="${{ github.sha }}"
           VERSION_HASH="${{ github.sha }}"
-          go build -trimpath -ldflags="-s -w -X github.com/komari-monitor/komari/utils.CurrentVersion=${VERSION} -X github.com/komari-monitor/komari/utils.VersionHash=${VERSION_HASH}" -o $BINARY_NAME
+          LDFLAGS="-s -w -X github.com/komari-monitor/komari/utils.CurrentVersion=${VERSION} -X github.com/komari-monitor/komari/utils.VersionHash=${VERSION_HASH}"
+          if [ "${{ matrix.goos }}" = "linux" ]; then
+            LDFLAGS="$LDFLAGS -extldflags=-Wl,--strip-all"
+          fi
+          go build -trimpath -ldflags="$LDFLAGS" -o "$BINARY_NAME"
 
       - name: Upload binary as artifact
         uses: actions/upload-artifact@v4

.github/workflows/development.yml

@@ -14,27 +14,8 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      #- name: Create dummy index.html
-      #  run: |
-      #    mkdir -p web/public/defaultTheme/dist
-      #    echo "<html><body><h1>This is komari development server.</h1></body></html>" > web/public/defaultTheme/dist/index.html
-
       - name: Clone and build frontend
-        run: |
-          git clone https://github.com/komari-monitor/komari-web komari-web
-          cd komari-web
-          npm install
-          npm run build
-          cd ..
-          mkdir -p web/public/defaultTheme/dist
-          rm -rf web/public/defaultTheme/dist/*
-          cp -r komari-web/dist/* web/public/defaultTheme/dist/
-          cp -f komari-web/komari-theme.json web/public/defaultTheme/
-          if [ -f komari-web/preview.png ]; then cp -f komari-web/preview.png web/public/defaultTheme/; fi
-          if [ -f komari-web/perview.png ]; then cp -f komari-web/perview.png web/public/defaultTheme/; fi
-          # Compatibility: ensure both filenames exist if only one is present
-          if [ -f web/public/defaultTheme/preview.png ] && [ ! -f web/public/defaultTheme/perview.png ]; then cp -f web/public/defaultTheme/preview.png web/public/defaultTheme/perview.png; fi
-          if [ -f web/public/defaultTheme/perview.png ] && [ ! -f web/public/defaultTheme/preview.png ]; then cp -f web/public/defaultTheme/perview.png web/public/defaultTheme/preview.png; fi
+        uses: ./.github/actions/build-frontend
 
       - name: Set up Go
         uses: actions/setup-go@v5
@@ -47,7 +28,7 @@ jobs:
           GOARCH: amd64
         run: |
           VERSION_SHA="${{ github.sha }}"
-          go build -ldflags "-X github.com/komari-monitor/komari/utils.CurrentVersion=dev -X github.com/komari-monitor/komari/utils.VersionHash=${VERSION_SHA}" -o komari .
+          go build -ldflags "-s -w -extldflags=-Wl,--strip-all -X github.com/komari-monitor/komari/utils.CurrentVersion=dev -X github.com/komari-monitor/komari/utils.VersionHash=${VERSION_SHA}" -o komari .
 
       - name: Upload binary as artifact
         uses: actions/upload-artifact@v4

.github/workflows/docker-publish.yml

@@ -11,37 +11,28 @@ env:
   IMAGE_NAME: ${{ github.repository }}
 
 jobs:
-  build-and-push-multi-arch:
+  build-frontend:
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
 
     steps:
-      - name: Checkout repository
+      - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
+      - name: Build frontend artifact
+        uses: ./.github/actions/build-frontend
         with:
-          node-version: "23"
+          artifact-name: komari-frontend
 
-      - name: Clone and build frontend
-        run: |
-          git clone https://github.com/komari-monitor/komari-web komari-web
-          cd komari-web
-          npm install
-          npm run build
-          cd ..
-          mkdir -p web/public/defaultTheme/dist
-          rm -rf web/public/defaultTheme/dist/*
-          cp -r komari-web/dist/* web/public/defaultTheme/dist/
-          cp -f komari-web/komari-theme.json web/public/defaultTheme/
-          if [ -f komari-web/preview.png ]; then cp -f komari-web/preview.png web/public/defaultTheme/; fi
-          if [ -f komari-web/perview.png ]; then cp -f komari-web/perview.png web/public/defaultTheme/; fi
-          # Compatibility: ensure both filenames exist if only one is present
-          if [ -f web/public/defaultTheme/preview.png ] && [ ! -f web/public/defaultTheme/perview.png ]; then cp -f web/public/defaultTheme/preview.png web/public/defaultTheme/perview.png; fi
-          if [ -f web/public/defaultTheme/perview.png ] && [ ! -f web/public/defaultTheme/preview.png ]; then cp -f web/public/defaultTheme/perview.png web/public/defaultTheme/preview.png; fi
+  build-docker-binaries:
+    needs: build-frontend
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Restore frontend artifact
+        uses: ./.github/actions/restore-frontend
 
       - name: Set up Go
         uses: actions/setup-go@v5
@@ -49,10 +40,7 @@ jobs:
           go-version: "1.23"
 
       - name: Install Zig
-        run: |
-          wget https://ziglang.org/download/0.14.1/zig-x86_64-linux-0.14.1.tar.xz
-          sudo tar -C /usr/local -Jxf zig-x86_64-linux-0.14.1.tar.xz
-          echo "PATH=$PATH:/usr/local/zig-x86_64-linux-0.14.1" >> $GITHUB_ENV
+        uses: ./.github/actions/setup-zig
 
       - name: Build static binaries for multi-arch
         env:
@@ -62,7 +50,7 @@ jobs:
         run: |
           VERSION="${{ github.ref_name }}"
           VERSION_HASH="${{ github.sha }}"
-          LDFLAGS="-s -w -X github.com/komari-monitor/komari/utils.CurrentVersion=${VERSION} -X github.com/komari-monitor/komari/utils.VersionHash=${VERSION_HASH}"
+          LDFLAGS="-s -w -extldflags=-Wl,--strip-all -X github.com/komari-monitor/komari/utils.CurrentVersion=${VERSION} -X github.com/komari-monitor/komari/utils.VersionHash=${VERSION_HASH}"
 
           echo "Building for linux/amd64..."
           GOARCH=amd64 CC="zig cc -target x86_64-linux-musl" go build -trimpath -ldflags="$LDFLAGS" -o komari-linux-amd64
@@ -70,6 +58,29 @@ jobs:
           echo "Building for linux/arm64..."
           GOARCH=arm64 CC="zig cc -target aarch64-linux-musl" go build -trimpath -ldflags="$LDFLAGS" -o komari-linux-arm64
 
+      - name: Upload Docker binaries
+        uses: actions/upload-artifact@v4
+        with:
+          name: komari-docker-binaries
+          path: komari-linux-*
+
+  build-and-push-multi-arch:
+    needs: build-docker-binaries
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Download Docker binaries
+        uses: actions/download-artifact@v4
+        with:
+          name: komari-docker-binaries
+          path: .
+
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3
 

.github/workflows/generate-release-notes.yml

@@ -6,8 +6,12 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: "Release tag to regenerate notes for."
-        required: true
+        description: "Release tag to regenerate notes for. Leave empty to use the latest release."
+        required: false
+        type: string
+      base_ref:
+        description: "Base ref or SHA for the release comparison. Snapshot builds pass the previous main SHA."
+        required: false
         type: string
 
 permissions:
@@ -16,46 +20,588 @@ permissions:
 jobs:
   update-release-notes:
     runs-on: ubuntu-latest
+    if: ${{ github.event_name != 'release' || !startsWith(github.event.release.tag_name, 'Snapshot-') }}
 
     steps:
       - name: Generate and apply release notes
         uses: actions/github-script@v9
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENAI_BASE_URL: ${{ secrets.OPENAI_BASE_URL }}
+          OPENAI_MODEL: ${{ vars.OPENAI_MODEL }}
         with:
           script: |
-            const tag = context.payload.release?.tag_name || core.getInput("tag");
-            if (!tag) {
-              core.setFailed("No release tag was provided.");
-              return;
+            const { owner, repo } = context.repo;
+            const webRepo = { owner: "komari-monitor", repo: "komari-web" };
+
+            const AI_CONTEXT_CHAR_LIMIT = 120000;
+            const AI_MAX_COMMITS = 160;
+            const AI_MAX_CHANGED_FILES = 120;
+            const AI_MAX_PULL_REQUESTS = 80;
+            const AI_MAX_PATCH_CHARS_PER_FILE = 2200;
+            const OPENAI_TIMEOUT_MS = 120000;
+
+            const clean = (value) => (typeof value === "string" ? value.trim() : "");
+            const isSnapshotTag = (tag) => /^Snapshot-/i.test(clean(tag));
+            const releaseTimestamp = (release) => Date.parse(release.published_at || release.created_at || "");
+            const isStableRelease = (release) => !release.draft && !release.prerelease && !isSnapshotTag(release.tag_name);
+
+            function limitText(value, maxLength) {
+              const text = clean(value);
+              if (text.length <= maxLength) {
+                return text;
+              }
+
+              return `${text.slice(0, maxLength)}\n...[truncated ${text.length - maxLength} chars]`;
             }
 
-            const { owner, repo } = context.repo;
-            const release = context.payload.release?.tag_name === tag
-              ? context.payload.release
-              : (await github.rest.repos.getReleaseByTag({ owner, repo, tag })).data;
+            function appendWithinLimit(parts, value, maxLength) {
+              const text = clean(value);
+              if (!text) {
+                return false;
+              }
 
-            const generated = await github.request(
-              "POST /repos/{owner}/{repo}/releases/generate-notes",
-              {
+              const currentLength = parts.reduce((total, part) => total + part.length + 2, 0);
+              if (currentLength + text.length + 2 <= maxLength) {
+                parts.push(text);
+                return true;
+              }
+
+              const remaining = maxLength - currentLength - 64;
+              if (remaining > 500) {
+                parts.push(`${text.slice(0, remaining)}\n...[context truncated]`);
+              }
+
+              return false;
+            }
+
+            async function resolveRelease() {
+              const requestedTag = clean(context.payload.release?.tag_name)
+                || clean(context.payload.client_payload?.tag)
+                || clean(context.payload.inputs?.tag);
+
+              if (requestedTag) {
+                const release = context.payload.release?.tag_name === requestedTag
+                  ? context.payload.release
+                  : (await github.rest.repos.getReleaseByTag({ owner, repo, tag: requestedTag })).data;
+                return { tag: requestedTag, release };
+              }
+
+              const release = (await github.rest.repos.getLatestRelease({ owner, repo })).data;
+              return { tag: release.tag_name, release };
+            }
+
+            async function getPreviousReleaseTag(tag, release) {
+              const releases = await github.paginate(github.rest.repos.listReleases, {
+                owner,
+                repo,
+                per_page: 100,
+              });
+
+              const currentTime = releaseTimestamp(release);
+              const currentIsSnapshot = isSnapshotTag(tag);
+              const currentIsStable = isStableRelease(release);
+              const candidates = releases
+                .filter((item) => !item.draft && item.tag_name !== tag)
+                .filter((item) => {
+                  if (!Number.isFinite(currentTime)) {
+                    return true;
+                  }
+
+                  const itemTime = releaseTimestamp(item);
+                  return Number.isFinite(itemTime) && itemTime < currentTime;
+                })
+                .filter((item) => {
+                  if (currentIsSnapshot || currentIsStable) {
+                    return isStableRelease(item);
+                  }
+
+                  return item.prerelease && !isSnapshotTag(item.tag_name);
+                })
+                .sort((left, right) => releaseTimestamp(right) - releaseTimestamp(left));
+
+              return candidates[0]?.tag_name || "";
+            }
+
+            async function resolveComparisonBase(tag, release) {
+              const requestedBaseRef = clean(context.payload.client_payload?.base_ref)
+                || clean(context.payload.inputs?.base_ref);
+
+              if (requestedBaseRef) {
+                return {
+                  ref: requestedBaseRef,
+                  previousTag: "",
+                  source: "requested base ref",
+                };
+              }
+
+              const previousTag = await getPreviousReleaseTag(tag, release);
+              if (previousTag) {
+                return {
+                  ref: previousTag,
+                  previousTag,
+                  source: isSnapshotTag(tag) ? "previous stable release" : "previous release in the same channel",
+                };
+              }
+
+              if (isSnapshotTag(tag)) {
+                try {
+                  const commit = (await github.rest.repos.getCommit({
+                    owner,
+                    repo,
+                    ref: release.target_commitish || tag,
+                  })).data;
+                  const parentSha = commit.parents?.[0]?.sha || "";
+                  if (parentSha) {
+                    return {
+                      ref: parentSha,
+                      previousTag: "",
+                      source: "snapshot target parent commit",
+                    };
+                  }
+                } catch (error) {
+                  core.warning(`Failed to resolve parent commit for ${tag}: ${error.message}`);
+                }
+              }
+
+              return {
+                ref: "",
+                previousTag: "",
+                source: "none",
+              };
+            }
+
+            async function getGeneratedNotes(tag, release, previousTag) {
+              const params = {
                 owner,
                 repo,
                 tag_name: tag,
                 target_commitish: release.target_commitish || undefined,
-              },
-            );
+              };
 
-            const body = generated.data.body?.trim();
-            if (!body) {
-              core.setFailed(`GitHub returned empty release notes for ${tag}.`);
+              if (previousTag) {
+                params.previous_tag_name = previousTag;
+              }
+
+              const generated = await github.request(
+                "POST /repos/{owner}/{repo}/releases/generate-notes",
+                params,
+              );
+
+              return clean(generated.data.body);
+            }
+
+            async function getComparison(baseRef, tag) {
+              if (!baseRef) {
+                return { commits: [], files: [], htmlUrl: "" };
+              }
+
+              const commits = [];
+              let files = [];
+              let htmlUrl = "";
+
+              for (let page = 1; page <= 20; page += 1) {
+                const response = await github.rest.repos.compareCommitsWithBasehead({
+                  owner,
+                  repo,
+                  basehead: `${baseRef}...${tag}`,
+                  per_page: 100,
+                  page,
+                });
+
+                if (page === 1) {
+                  files = response.data.files || [];
+                  htmlUrl = response.data.html_url || "";
+                }
+
+                commits.push(...response.data.commits);
+
+                if (!response.headers.link?.includes('rel="next"')) {
+                  break;
+                }
+              }
+
+              return { commits, files, htmlUrl };
+            }
+
+            function renderCommitLine(commit) {
+              const subject = clean(commit.commit.message.split("\n")[0]) || "(no subject)";
+              const shortSha = commit.sha.slice(0, 7);
+              const author = commit.author?.login
+                ? ` @${commit.author.login}`
+                : (commit.commit.author?.name ? ` ${commit.commit.author.name}` : "");
+
+              return `- ${subject} ([${shortSha}](${commit.html_url}))${author}`;
+            }
+
+            function buildWhatsChangedSection(baseRef, tag, comparison) {
+              if (!baseRef) {
+                return "## What's Changed\n\nNo comparison base was found for this release.";
+              }
+
+              if (comparison.commits.length === 0) {
+                return `## What's Changed\n\nNo commits found between \`${baseRef}\` and \`${tag}\`.`;
+              }
+
+              const lines = ["## What's Changed", "", ...comparison.commits.map(renderCommitLine)];
+              if (comparison.htmlUrl) {
+                lines.push("", `**Full Changelog**: ${comparison.htmlUrl}`);
+              }
+
+              return lines.join("\n");
+            }
+
+            function appendCommitsToGeneratedNotes(generatedNotes, baseRef, tag, comparison) {
+              const notes = clean(generatedNotes);
+              if (!notes || comparison.commits.length === 0) {
+                return notes || buildWhatsChangedSection(baseRef, tag, comparison);
+              }
+
+              const lines = notes.split("\n");
+              const fullChangelogIndex = lines.findIndex((line) => /^\*\*Full Changelog\*\*:/i.test(line.trim()));
+              const nextTopLevelSectionIndex = lines.findIndex((line, index) => (
+                index > 0
+                && /^##\s+/.test(line)
+                && !/^##\s+What's Changed\b/i.test(line)
+              ));
+              const insertionIndex = nextTopLevelSectionIndex >= 0
+                ? nextTopLevelSectionIndex
+                : (fullChangelogIndex >= 0 ? fullChangelogIndex : lines.length);
+              const commitSection = [
+                "### Commits",
+                "",
+                ...comparison.commits.map(renderCommitLine),
+                "",
+              ];
+
+              lines.splice(insertionIndex, 0, ...commitSection);
+              return clean(lines.join("\n"));
+            }
+
+            async function getPullRequestContext(commits) {
+              const pullRequests = new Map();
+
+              for (const commit of commits.slice(0, AI_MAX_COMMITS)) {
+                try {
+                  const response = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+                    owner,
+                    repo,
+                    commit_sha: commit.sha,
+                  });
+
+                  for (const pullRequest of response.data || []) {
+                    pullRequests.set(pullRequest.html_url, pullRequest);
+                  }
+                } catch (error) {
+                  core.warning(`Failed to load pull requests for ${commit.sha.slice(0, 7)}: ${error.message}`);
+                }
+
+                if (pullRequests.size >= AI_MAX_PULL_REQUESTS) {
+                  break;
+                }
+              }
+
+              return [...pullRequests.values()].slice(0, AI_MAX_PULL_REQUESTS);
+            }
+
+            function buildChangedFilesContext(files) {
+              if (!files.length) {
+                return "No changed file metadata was returned by GitHub.";
+              }
+
+              return files.slice(0, AI_MAX_CHANGED_FILES).map((file) => {
+                const lines = [
+                  `File: ${file.filename}`,
+                  `Status: ${file.status}; additions: ${file.additions}; deletions: ${file.deletions}; changes: ${file.changes}`,
+                ];
+
+                if (file.patch) {
+                  lines.push("Patch excerpt:");
+                  lines.push(limitText(file.patch, AI_MAX_PATCH_CHARS_PER_FILE));
+                }
+
+                return lines.join("\n");
+              }).join("\n\n");
+            }
+
+            function buildCommitContext(commits) {
+              if (!commits.length) {
+                return "No commits were returned by GitHub.";
+              }
+
+              return commits.slice(0, AI_MAX_COMMITS).map((commit) => {
+                const shortSha = commit.sha.slice(0, 7);
+                const author = commit.author?.login || commit.commit.author?.name || "unknown";
+                const message = limitText(commit.commit.message, 1800);
+                return [
+                  `Commit: ${shortSha}`,
+                  `Author: ${author}`,
+                  `URL: ${commit.html_url}`,
+                  "Message:",
+                  message,
+                ].join("\n");
+              }).join("\n\n");
+            }
+
+            function buildPullRequestContext(pullRequests) {
+              if (!pullRequests.length) {
+                return "No associated pull requests were found for the compared commits.";
+              }
+
+              return pullRequests.map((pullRequest) => {
+                const labels = (pullRequest.labels || []).map((label) => label.name).filter(Boolean).join(", ") || "none";
+                return [
+                  `PR: #${pullRequest.number} ${pullRequest.title}`,
+                  `URL: ${pullRequest.html_url}`,
+                  `Author: ${pullRequest.user?.login || "unknown"}`,
+                  `Labels: ${labels}`,
+                  "Body:",
+                  limitText(pullRequest.body, 1800) || "(empty)",
+                ].join("\n");
+              }).join("\n\n");
+            }
+
+            function buildAiContext({ tag, release, comparisonBase, whatsChangedSection, comparison, pullRequests, webReleaseSection }) {
+              const sections = [];
+
+              appendWithinLimit(sections, [
+                `Repository: ${owner}/${repo}`,
+                `Release tag: ${tag}`,
+                `Release title: ${release.name || tag}`,
+                `Prerelease: ${release.prerelease ? "yes" : "no"}`,
+                `Snapshot tag: ${isSnapshotTag(tag) ? "yes" : "no"}`,
+                `Target commitish: ${release.target_commitish || "(unknown)"}`,
+                `Comparison base: ${comparisonBase.ref || "(none)"}`,
+                `Comparison base source: ${comparisonBase.source}`,
+                `Compare URL: ${comparison.htmlUrl || "(unavailable)"}`,
+              ].join("\n"), AI_CONTEXT_CHAR_LIMIT);
+
+              appendWithinLimit(sections, `What's Changed section:\n${whatsChangedSection}`, AI_CONTEXT_CHAR_LIMIT);
+              appendWithinLimit(sections, `Changed files and patch excerpts:\n${buildChangedFilesContext(comparison.files)}`, AI_CONTEXT_CHAR_LIMIT);
+              appendWithinLimit(sections, `Associated pull requests:\n${buildPullRequestContext(pullRequests)}`, AI_CONTEXT_CHAR_LIMIT);
+              appendWithinLimit(sections, `Commit details:\n${buildCommitContext(comparison.commits)}`, AI_CONTEXT_CHAR_LIMIT);
+
+              if (webReleaseSection) {
+                appendWithinLimit(sections, `Komari Web release notes for the same tag:\n${webReleaseSection}`, AI_CONTEXT_CHAR_LIMIT);
+              }
+
+              return sections.join("\n\n---\n\n");
+            }
+
+            function buildChatCompletionsUrl(baseUrl) {
+              const trimmed = clean(baseUrl).replace(/\/+$/, "");
+              if (!trimmed) {
+                return "";
+              }
+
+              if (trimmed.endsWith("/chat/completions")) {
+                return trimmed;
+              }
+
+              if (trimmed.endsWith("/v1")) {
+                return `${trimmed}/chat/completions`;
+              }
+
+              return `${trimmed}/v1/chat/completions`;
+            }
+
+            function normalizeReleaseSummary(markdown) {
+              const summary = clean(markdown);
+              if (!summary) {
+                return "";
+              }
+
+              const withoutAiHeading = clean(summary
+                .replace(/^#{1,6}\s+AI Summary\b\s*/im, "")
+                .replace(/^\*\*AI Summary\*\*\s*/im, ""));
+              const whatsChangedIndex = withoutAiHeading.search(/^##\s+What's Changed\b/im);
+              if (whatsChangedIndex >= 0) {
+                return clean(withoutAiHeading.slice(0, whatsChangedIndex));
+              }
+
+              return withoutAiHeading;
+            }
+
+            async function callOpenAiChatCompletion(url, apiKey, model, messages) {
+              const controller = new AbortController();
+              const timeout = setTimeout(() => controller.abort(), OPENAI_TIMEOUT_MS);
+
+              try {
+                const response = await fetch(url, {
+                  method: "POST",
+                  headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    "Content-Type": "application/json",
+                  },
+                  body: JSON.stringify({ model, messages, temperature: 0 }),
+                  signal: controller.signal,
+                });
+
+                const responseText = await response.text();
+                let responseJson = {};
+                try {
+                  responseJson = responseText ? JSON.parse(responseText) : {};
+                } catch {
+                  responseJson = {};
+                }
+
+                if (!response.ok) {
+                  const message = clean(responseJson.error?.message) || limitText(responseText, 500);
+                  throw new Error(`OpenAI request failed with ${response.status}: ${message}`);
+                }
+
+                return clean(responseJson.choices?.[0]?.message?.content);
+              } finally {
+                clearTimeout(timeout);
+              }
+            }
+
+            async function buildReleaseSummarySection({ tag, release, comparisonBase, whatsChangedSection, comparison, webReleaseSection }) {
+              const apiKey = clean(process.env.OPENAI_API_KEY);
+              const baseUrl = clean(process.env.OPENAI_BASE_URL);
+              const model = clean(process.env.OPENAI_MODEL);
+
+              if (!apiKey || !baseUrl || !model) {
+                core.warning("OPENAI_API_KEY, OPENAI_BASE_URL, or OPENAI_MODEL is missing. Skipping generated release summary.");
+                return "";
+              }
+
+              const pullRequests = await getPullRequestContext(comparison.commits);
+              const aiContext = buildAiContext({
+                tag,
+                release,
+                comparisonBase,
+                whatsChangedSection,
+                comparison,
+                pullRequests,
+                webReleaseSection,
+              });
+
+              const messages = [
+                {
+                  role: "system",
+                  content: [
+                    "You write accurate release notes for the Komari server project.",
+                    "Use only the supplied repository context.",
+                    "Include both Komari server changes and Komari Web frontend changes when frontend release notes are supplied.",
+                    "Prioritize user-visible behavior, compatibility or migration notes, operations/deployment changes, security fixes, and important bug fixes.",
+                    "Do not invent features or implementation details that are not supported by the context.",
+                    "Write concise Markdown in Simplified Chinese.",
+                  ].join(" "),
+                },
+                {
+                  role: "user",
+                  content: [
+                    `Create the release summary section for release ${tag}.`,
+                    comparisonBase.ref
+                      ? `Summarize only changes in the comparison ${comparisonBase.ref}...${tag}.`
+                      : "No comparison base was found, so summarize only the supplied release context.",
+                    "Return only Markdown for the summary section that appears before '## What's Changed'.",
+                    "Do not use the heading 'AI Summary'. Do not add a 'What's Changed' section.",
+                    "Use these top-level headings, in this order: '## 主要更新内容', '## Bug修复', and '## 其他'.",
+                    "Omit '## Bug修复' when there are no concrete bug fixes. Keep bullets short and specific.",
+                    "",
+                    aiContext,
+                  ].join("\n"),
+                },
+              ];
+
+              try {
+                const url = buildChatCompletionsUrl(baseUrl);
+                const summary = await callOpenAiChatCompletion(url, apiKey, model, messages);
+                return normalizeReleaseSummary(summary);
+              } catch (error) {
+                core.warning(`Generated release summary failed: ${error.message}`);
+                return "";
+              }
+            }
+
+            async function buildWebReleaseSection(tag) {
+              const demoteMarkdownHeadings = (markdown) => markdown.replace(/^(#{1,5})(\s+)/gm, "#$1$2");
+
+              try {
+                const webRelease = (await github.rest.repos.getReleaseByTag({
+                  owner: webRepo.owner,
+                  repo: webRepo.repo,
+                  tag,
+                })).data;
+
+                const webBody = clean(webRelease.body);
+                if (!webBody) {
+                  return `## Komari Web Release Notes\n\nKomari Web release [${tag}](${webRelease.html_url}) exists, but its release notes are empty.`;
+                }
+
+                return [
+                  "## Komari Web Release Notes",
+                  "",
+                  `Source: [komari-web ${tag}](${webRelease.html_url})`,
+                  "",
+                  demoteMarkdownHeadings(webBody),
+                ].join("\n");
+              } catch (error) {
+                if (error.status === 404) {
+                  core.info(`Komari Web release ${tag} does not exist yet. Skipping web release notes for now.`);
+                  return "";
+                }
+
+                throw error;
+              }
+            }
+
+            const { tag, release } = await resolveRelease();
+            if (!tag) {
+              core.setFailed("No release tag was provided or found.");
               return;
             }
 
-            await github.rest.repos.updateRelease({
-              owner,
-              repo,
-              release_id: release.id,
-              body,
+            const comparisonBase = await resolveComparisonBase(tag, release);
+            core.info(comparisonBase.ref
+              ? `Comparison base for ${tag}: ${comparisonBase.ref} (${comparisonBase.source}).`
+              : `No comparison base found for ${tag}.`);
+
+            const comparison = await getComparison(comparisonBase.ref, tag);
+            const whatsChangedSection = comparisonBase.previousTag
+              ? appendCommitsToGeneratedNotes(
+                await getGeneratedNotes(tag, release, comparisonBase.previousTag),
+                comparisonBase.ref,
+                tag,
+                comparison,
+              )
+              : (!comparisonBase.ref && !isSnapshotTag(tag)
+                ? await getGeneratedNotes(tag, release, "")
+                : buildWhatsChangedSection(comparisonBase.ref, tag, comparison));
+
+            if (!whatsChangedSection) {
+              core.setFailed(`Failed to build What's Changed section for ${tag}.`);
+              return;
+            }
+
+            const webReleaseSection = await buildWebReleaseSection(tag);
+            const releaseSummarySection = await buildReleaseSummarySection({
+              tag,
+              release,
+              comparisonBase,
+              whatsChangedSection,
+              comparison,
+              webReleaseSection,
             });
 
+            const body = [
+              releaseSummarySection,
+              whatsChangedSection,
+            ].filter(Boolean).join("\n\n");
+
+            if (clean(release.body) === clean(body)) {
+              core.info(`Release notes for ${tag} are already up to date.`);
+            } else {
+              await github.rest.repos.updateRelease({
+                owner,
+                repo,
+                release_id: release.id,
+                body,
+              });
+            }
+
             await core.summary
               .addHeading("Release Notes")
               .addRaw(`Updated release notes for ${tag}.`)

.github/workflows/rebuild-release.yml

@@ -0,0 +1,163 @@
+name: Rebuild Existing Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: Existing GitHub Release tag whose assets and version image will be replaced.
+        required: true
+        type: string
+      server_ref:
+        description: Server commit, branch, or tag to build.
+        required: true
+        type: string
+      frontend_ref:
+        description: komari-web commit, branch, or tag to build.
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  packages: write
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-frontend:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout workflow source
+        uses: actions/checkout@v4
+
+      - name: Build selected frontend artifact
+        uses: ./.github/actions/build-frontend
+        with:
+          artifact-name: komari-frontend
+          ref: ${{ inputs.frontend_ref }}
+
+  build-and-attach-binaries:
+    needs: build-frontend
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        include:
+          - goos: windows
+            goarch: amd64
+            zig_target_triple: x86_64-windows-gnu
+            binary_extension: .exe
+          - goos: windows
+            goarch: arm64
+            zig_target_triple: aarch64-windows-gnu
+            binary_extension: .exe
+          - goos: windows
+            goarch: 386
+            zig_target_triple: x86-windows-gnu
+            binary_extension: .exe
+          - goos: linux
+            goarch: amd64
+            zig_target_triple: x86_64-linux-musl
+            binary_extension: ""
+          - goos: linux
+            goarch: arm64
+            zig_target_triple: aarch64-linux-musl
+            binary_extension: ""
+          - goos: linux
+            goarch: 386
+            zig_target_triple: x86-linux-musl
+            binary_extension: ""
+          - goos: linux
+            goarch: riscv64
+            zig_target_triple: riscv64-linux-musl
+            binary_extension: ""
+
+    steps:
+      - name: Checkout server source
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.server_ref }}
+
+      - name: Restore frontend artifact
+        uses: komari-monitor/komari/.github/actions/restore-frontend@main
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.23"
+
+      - name: Install Zig cross-compiler toolchain
+        uses: komari-monitor/komari/.github/actions/setup-zig@main
+
+      - name: Build binary
+        env:
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          CGO_ENABLED: 1
+          CC: zig cc -target ${{ matrix.zig_target_triple }}
+          GIN_MODE: release
+          RELEASE_TAG: ${{ inputs.release_tag }}
+        run: |
+          BINARY_NAME=komari-${{ matrix.goos }}-${{ matrix.goarch }}${{ matrix.binary_extension }}
+          VERSION_HASH="$(git rev-parse HEAD)"
+          LDFLAGS="-s -w -X github.com/komari-monitor/komari/utils.CurrentVersion=${RELEASE_TAG} -X github.com/komari-monitor/komari/utils.VersionHash=${VERSION_HASH}"
+          if [ "${{ matrix.goos }}" = "linux" ]; then
+            LDFLAGS="$LDFLAGS -extldflags=-Wl,--strip-all"
+          fi
+          go build -trimpath -ldflags="$LDFLAGS" -o "$BINARY_NAME"
+
+      - name: Upload binary to release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ inputs.release_tag }}
+        run: |
+          BINARY_NAME=komari-${{ matrix.goos }}-${{ matrix.goarch }}${{ matrix.binary_extension }}
+          gh release upload "$RELEASE_TAG" "$BINARY_NAME" --clobber --repo "$GITHUB_REPOSITORY"
+
+      - name: Upload binary as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: komari-${{ matrix.goos }}-${{ matrix.goarch }}
+          path: komari-${{ matrix.goos }}-${{ matrix.goarch }}${{ matrix.binary_extension }}
+
+  build-and-push-docker:
+    needs: build-and-attach-binaries
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout server source
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.server_ref }}
+
+      - name: Download Docker binaries
+        uses: actions/download-artifact@v4
+        with:
+          pattern: komari-linux-*
+          path: .
+          merge-multiple: true
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to the Container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      - name: Build and push version Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ inputs.release_tag }}
+          no-cache: true
+          provenance: false

.github/workflows/release-docker.yml

@@ -1,9 +1,12 @@
-name: Publish Docker Image
+name: Publish Docker Image Manually
 
 on:
-  release:
-    types: [published]
   workflow_dispatch:
+    inputs:
+      version:
+        description: Docker image tag and embedded version.
+        required: true
+        type: string
 
 permissions:
   contents: read
@@ -14,7 +17,61 @@ env:
   IMAGE_NAME: ${{ github.repository }}
 
 jobs:
+  build-frontend:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Build frontend artifact
+        uses: ./.github/actions/build-frontend
+        with:
+          artifact-name: komari-frontend
+
+  build-docker-binaries:
+    needs: build-frontend
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Restore frontend artifact
+        uses: ./.github/actions/restore-frontend
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.23"
+
+      - name: Install Zig
+        uses: ./.github/actions/setup-zig
+
+      - name: Build static binaries for multi-arch
+        env:
+          GOOS: linux
+          CGO_ENABLED: 1
+          GIN_MODE: release
+          VERSION: ${{ github.event.inputs.version }}
+        run: |
+          VERSION_HASH="${{ github.sha }}"
+          LDFLAGS="-s -w -extldflags=-Wl,--strip-all -X github.com/komari-monitor/komari/utils.CurrentVersion=${VERSION} -X github.com/komari-monitor/komari/utils.VersionHash=${VERSION_HASH}"
+
+          echo "Building for linux/amd64..."
+          GOARCH=amd64 CC="zig cc -target x86_64-linux-musl" go build -trimpath -ldflags="$LDFLAGS" -o komari-linux-amd64
+
+          echo "Building for linux/arm64..."
+          GOARCH=arm64 CC="zig cc -target aarch64-linux-musl" go build -trimpath -ldflags="$LDFLAGS" -o komari-linux-arm64
+
+      - name: Upload Docker binaries
+        uses: actions/upload-artifact@v4
+        with:
+          name: komari-docker-binaries
+          path: komari-linux-*
+
   build-and-push-multi-arch:
+    needs: build-docker-binaries
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -24,54 +81,11 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
+      - name: Download Docker binaries
+        uses: actions/download-artifact@v4
         with:
-          node-version: "23"
-
-      - name: Clone and build frontend
-        run: |
-          git clone https://github.com/komari-monitor/komari-web komari-web
-          cd komari-web
-          npm install
-          npm run build
-          cd ..
-          mkdir -p web/public/defaultTheme/dist
-          rm -rf web/public/defaultTheme/dist/*
-          cp -r komari-web/dist/* web/public/defaultTheme/dist/
-          cp -f komari-web/komari-theme.json web/public/defaultTheme/
-          if [ -f komari-web/preview.png ]; then cp -f komari-web/preview.png web/public/defaultTheme/; fi
-          if [ -f komari-web/perview.png ]; then cp -f komari-web/perview.png web/public/defaultTheme/; fi
-          # Compatibility: ensure both filenames exist if only one is present
-          if [ -f web/public/defaultTheme/preview.png ] && [ ! -f web/public/defaultTheme/perview.png ]; then cp -f web/public/defaultTheme/preview.png web/public/defaultTheme/perview.png; fi
-          if [ -f web/public/defaultTheme/perview.png ] && [ ! -f web/public/defaultTheme/preview.png ]; then cp -f web/public/defaultTheme/perview.png web/public/defaultTheme/preview.png; fi
-
-      - name: Set up Go
-        uses: actions/setup-go@v5
-        with:
-          go-version: "1.23"
-
-      - name: Install Zig
-        run: |
-          wget https://ziglang.org/download/0.14.1/zig-x86_64-linux-0.14.1.tar.xz
-          sudo tar -C /usr/local -Jxf zig-x86_64-linux-0.14.1.tar.xz
-          echo "PATH=$PATH:/usr/local/zig-x86_64-linux-0.14.1" >> $GITHUB_ENV
-
-      - name: Build static binaries for multi-arch
-        env:
-          GOOS: linux
-          CGO_ENABLED: 1
-          GIN_MODE: release
-        run: |
-          VERSION="${{ github.event.release.tag_name }}"
-          VERSION_HASH="${{ github.sha }}"
-          LDFLAGS="-s -w -X github.com/komari-monitor/komari/utils.CurrentVersion=${VERSION} -X github.com/komari-monitor/komari/utils.VersionHash=${VERSION_HASH}"
-
-          echo "Building for linux/amd64..."
-          GOARCH=amd64 CC="zig cc -target x86_64-linux-musl" go build -trimpath -ldflags="$LDFLAGS" -o komari-linux-amd64
-
-          echo "Building for linux/arm64..."
-          GOARCH=arm64 CC="zig cc -target aarch64-linux-musl" go build -trimpath -ldflags="$LDFLAGS" -o komari-linux-arm64
+          name: komari-docker-binaries
+          path: .
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3
@@ -92,8 +106,7 @@ jobs:
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
-            type=raw,value=${{ github.event.release.tag_name }}
-            type=raw,value=latest
+            type=raw,value=${{ github.event.inputs.version }}
 
       - name: Build and push Docker image
         uses: docker/build-push-action@v5

.github/workflows/release.yml

@@ -13,7 +13,38 @@ env:
   IMAGE_NAME: ${{ github.repository }}
 
 jobs:
+  resolve-release:
+    runs-on: ubuntu-latest
+    outputs:
+      frontend_ref: ${{ steps.release.outputs.frontend_ref }}
+
+    steps:
+      - id: release
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          frontend_ref=""
+          if [[ "$TAG" =~ ^(.+)-fix[0-9]+$ ]]; then
+            frontend_ref="${BASH_REMATCH[1]}"
+          fi
+          echo "frontend_ref=$frontend_ref" >> "$GITHUB_OUTPUT"
+
+  build-frontend:
+    needs: resolve-release
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Build frontend artifact
+        uses: ./.github/actions/build-frontend
+        with:
+          artifact-name: komari-frontend
+          ref: ${{ needs.resolve-release.outputs.frontend_ref }}
+
   build-and-attach-binaries:
+    needs: build-frontend
     runs-on: ubuntu-latest
 
     strategy:
@@ -52,6 +83,10 @@ jobs:
             goarch: riscv64
             zig_target_triple: riscv64-linux-musl
             binary_extension: ""
+          - goos: linux
+            goarch: loong64
+            zig_target_triple: loongarch64-linux-musl
+            binary_extension: ""
 
         exclude:
           - goos: windows
@@ -61,27 +96,8 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "23"
-
-      - name: Clone and build frontend
-        run: |
-          git clone https://github.com/komari-monitor/komari-web komari-web
-          cd komari-web
-          npm install
-          npm run build
-          cd ..
-          mkdir -p web/public/defaultTheme/dist
-          rm -rf web/public/defaultTheme/dist/*
-          cp -r komari-web/dist/* web/public/defaultTheme/dist/
-          cp -f komari-web/komari-theme.json web/public/defaultTheme/
-          if [ -f komari-web/preview.png ]; then cp -f komari-web/preview.png web/public/defaultTheme/; fi
-          if [ -f komari-web/perview.png ]; then cp -f komari-web/perview.png web/public/defaultTheme/; fi
-          # Compatibility: ensure both filenames exist if only one is present
-          if [ -f web/public/defaultTheme/preview.png ] && [ ! -f web/public/defaultTheme/perview.png ]; then cp -f web/public/defaultTheme/preview.png web/public/defaultTheme/perview.png; fi
-          if [ -f web/public/defaultTheme/perview.png ] && [ ! -f web/public/defaultTheme/preview.png ]; then cp -f web/public/defaultTheme/perview.png web/public/defaultTheme/preview.png; fi
+      - name: Restore frontend artifact
+        uses: ./.github/actions/restore-frontend
 
       - name: Set up Go
         uses: actions/setup-go@v5
@@ -89,12 +105,7 @@ jobs:
           go-version: "1.23"
 
       - name: Install Zig cross-compiler toolchain
-        run: |
-          sudo apt-get update # Update apt package lists
-          sudo apt-get install -y build-essential curl
-          wget https://ziglang.org/download/0.14.1/zig-x86_64-linux-0.14.1.tar.xz
-          sudo tar -C /usr/local -Jxf zig-x86_64-linux-0.14.1.tar.xz
-          echo "PATH=$PATH:/usr/local/zig-x86_64-linux-0.14.1" >> $GITHUB_ENV
+        uses: ./.github/actions/setup-zig
 
       - name: Build binary
         env:
@@ -110,7 +121,17 @@ jobs:
           fi
           VERSION="${{ github.event.release.tag_name }}"
           VERSION_HASH="${{ github.sha }}" # Use commit SHA for hash
-          go build -trimpath -ldflags="-s -w -X github.com/komari-monitor/komari/utils.CurrentVersion=${VERSION} -X github.com/komari-monitor/komari/utils.VersionHash=${VERSION_HASH}" -o $BINARY_NAME
+          LDFLAGS="-s -w -X github.com/komari-monitor/komari/utils.CurrentVersion=${VERSION} -X github.com/komari-monitor/komari/utils.VersionHash=${VERSION_HASH}"
+          if [ "${{ matrix.goos }}" = "linux" ]; then
+            LDFLAGS="$LDFLAGS -extldflags=-Wl,--strip-all"
+          fi
+          go build -trimpath -ldflags="$LDFLAGS" -o "$BINARY_NAME"
+
+      - name: Upload binary as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: komari-${{ matrix.goos }}-${{ matrix.goarch }}
+          path: komari-${{ matrix.goos }}-${{ matrix.goarch }}*
 
       - name: Upload binary to release
         env:
@@ -124,3 +145,73 @@ jobs:
           # Upload the binary as a release asset using GitHub CLI
           gh release upload ${{ github.event.release.tag_name }} $BINARY_NAME --repo ${{ github.repository }}
         shell: bash
+
+  build-and-push-docker:
+    needs: build-and-attach-binaries
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Download Docker binaries
+        uses: actions/download-artifact@v4
+        with:
+          pattern: komari-linux-*
+          path: .
+          merge-multiple: true
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to the Container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Check whether this is the latest GitHub release
+        id: release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          is_latest="$(gh api graphql \
+            -f 'query=query($owner: String!, $name: String!, $tag: String!) { repository(owner: $owner, name: $name) { release(tagName: $tag) { isLatest } } }' \
+            -F owner="${{ github.repository_owner }}" \
+            -F name="${{ github.event.repository.name }}" \
+            -F tag="$TAG" \
+            --jq '.data.repository.release.isLatest')"
+          echo "is_latest=$is_latest" >> "$GITHUB_OUTPUT"
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=raw,value=${{ github.event.release.tag_name }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          no-cache: true
+          provenance: false
+
+      - name: Promote Docker latest tag
+        if: steps.release.outputs.is_latest == 'true'
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: docker buildx imagetools create --tag "${REGISTRY}/${IMAGE_NAME}:latest" "${REGISTRY}/${IMAGE_NAME}:${TAG}"

.github/workflows/snapshot.yml

@@ -0,0 +1,297 @@
+name: Publish Snapshot
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  packages: write
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+concurrency:
+  group: snapshot-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate-ref:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Ensure snapshot target is main
+        run: |
+          if [ "${GITHUB_REF}" != "refs/heads/main" ]; then
+            echo "Snapshot builds must run from refs/heads/main. Current ref: ${GITHUB_REF}"
+            exit 1
+          fi
+
+          git fetch --no-tags --depth=1 origin main
+          MAIN_SHA="$(git rev-parse FETCH_HEAD)"
+
+          if [ "${GITHUB_SHA}" != "${MAIN_SHA}" ]; then
+            echo "Snapshot builds must use the current main commit."
+            echo "Workflow SHA: ${GITHUB_SHA}"
+            echo "Current main: ${MAIN_SHA}"
+            exit 1
+          fi
+
+  prepare:
+    needs: validate-ref
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - name: Generate snapshot version
+        id: version
+        run: |
+          # Snapshot 版本号格式: Snapshot-yymmddhhMM (UTC+8)
+          VERSION="Snapshot-$(date -u -d '+8 hours' +%y%m%d%H%M)"
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Snapshot version: ${VERSION}"
+
+  build-frontend:
+    needs: validate-ref
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Build frontend artifact
+        uses: ./.github/actions/build-frontend
+        with:
+          artifact-name: komari-frontend
+
+  build-and-attach-binaries:
+    needs: [prepare, build-frontend]
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        goos: [windows, linux]
+        goarch: [amd64, arm64, 386, riscv64]
+        include:
+          # Windows
+          - goos: windows
+            goarch: amd64
+            zig_target_triple: x86_64-windows-gnu
+            binary_extension: .exe
+          - goos: windows
+            goarch: arm64
+            zig_target_triple: aarch64-windows-gnu
+            binary_extension: .exe
+          - goos: windows
+            goarch: 386
+            zig_target_triple: x86-windows-gnu
+            binary_extension: .exe
+
+          # Linux
+          - goos: linux
+            goarch: amd64
+            zig_target_triple: x86_64-linux-musl
+            binary_extension: ""
+          - goos: linux
+            goarch: arm64
+            zig_target_triple: aarch64-linux-musl
+            binary_extension: ""
+          - goos: linux
+            goarch: 386
+            zig_target_triple: x86-linux-musl
+            binary_extension: ""
+          - goos: linux
+            goarch: riscv64
+            zig_target_triple: riscv64-linux-musl
+            binary_extension: ""
+          - goos: linux
+            goarch: loong64
+            zig_target_triple: loongarch64-linux-musl
+            binary_extension: ""
+
+        exclude:
+          - goos: windows
+            goarch: riscv64
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Restore frontend artifact
+        uses: ./.github/actions/restore-frontend
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.23"
+
+      - name: Install Zig cross-compiler toolchain
+        uses: ./.github/actions/setup-zig
+
+      - name: Build binary
+        env:
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          CGO_ENABLED: 1
+          CC: zig cc -target ${{ matrix.zig_target_triple }}
+          GIN_MODE: release
+        run: |
+          BINARY_NAME=komari-${{ matrix.goos }}-${{ matrix.goarch }}
+          if [ "${{ matrix.binary_extension }}" != "" ]; then
+            BINARY_NAME=${BINARY_NAME}${{ matrix.binary_extension }}
+          fi
+          VERSION="${{ needs.prepare.outputs.version }}"
+          VERSION_HASH="${{ github.sha }}" # Use commit SHA for hash
+          LDFLAGS="-s -w -X github.com/komari-monitor/komari/utils.CurrentVersion=${VERSION} -X github.com/komari-monitor/komari/utils.VersionHash=${VERSION_HASH}"
+          if [ "${{ matrix.goos }}" = "linux" ]; then
+            LDFLAGS="$LDFLAGS -extldflags=-Wl,--strip-all"
+          fi
+          go build -trimpath -ldflags="$LDFLAGS" -o "$BINARY_NAME"
+
+      - name: Upload binary as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: komari-${{ matrix.goos }}-${{ matrix.goarch }}
+          path: komari-${{ matrix.goos }}-${{ matrix.goarch }}*
+
+  publish-snapshot-release:
+    needs: [prepare, build-and-attach-binaries]
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Ensure commit is still current main
+        run: |
+          git fetch --no-tags --depth=1 origin main
+          MAIN_SHA="$(git rev-parse FETCH_HEAD)"
+
+          if [ "${GITHUB_SHA}" != "${MAIN_SHA}" ]; then
+            echo "Snapshot publish skipped because a newer main commit exists."
+            echo "Workflow SHA: ${GITHUB_SHA}"
+            echo "Current main: ${MAIN_SHA}"
+            exit 1
+          fi
+
+      - name: Download all binaries
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+          merge-multiple: true
+
+      - name: Create snapshot prerelease and upload binaries
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ needs.prepare.outputs.version }}
+        run: |
+          set -euxo pipefail
+          echo "Snapshot version: ${VERSION}"
+          ls -alR artifacts
+
+          # 如果同名 release/tag 已存在（例如重跑），先删除避免创建冲突
+          if gh release view "${VERSION}" --repo "${{ github.repository }}" >/dev/null 2>&1; then
+            echo "Release ${VERSION} 已存在，正在删除以重新创建..."
+            gh release delete "${VERSION}" --repo "${{ github.repository }}" --cleanup-tag --yes
+          fi
+
+          # 创建预发布并上传所有二进制文件
+          gh release create "${VERSION}" \
+            --repo "${{ github.repository }}" \
+            --target "${{ github.sha }}" \
+            --title "${VERSION}" \
+            --notes "Automated snapshot build (${VERSION}) from commit ${{ github.sha }}." \
+            --prerelease \
+            artifacts/komari-*
+
+          gh workflow run generate-release-notes.yml \
+            --repo "${{ github.repository }}" \
+            --ref main \
+            -f tag="${VERSION}"
+
+          gh release list \
+            --repo "${{ github.repository }}" \
+            --limit 1000 \
+            --json tagName,isPrerelease \
+            --jq '.[] | select(.isPrerelease and (.tagName | startswith("Snapshot-"))) | .tagName' |
+          while IFS= read -r tag; do
+            if [ -z "${tag}" ] || [ "${tag}" = "${VERSION}" ]; then
+              continue
+            fi
+
+            echo "Deleting old snapshot release ${tag}..."
+            gh release delete "${tag}" --repo "${{ github.repository }}" --cleanup-tag --yes
+          done
+        shell: bash
+
+  build-and-push-docker:
+    needs: [prepare, build-and-attach-binaries, publish-snapshot-release]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Ensure commit is still current main
+        run: |
+          git fetch --no-tags --depth=1 origin main
+          MAIN_SHA="$(git rev-parse FETCH_HEAD)"
+
+          if [ "${GITHUB_SHA}" != "${MAIN_SHA}" ]; then
+            echo "Snapshot Docker publish skipped because a newer main commit exists."
+            echo "Workflow SHA: ${GITHUB_SHA}"
+            echo "Current main: ${MAIN_SHA}"
+            exit 1
+          fi
+
+      - name: Download Docker binaries
+        uses: actions/download-artifact@v4
+        with:
+          pattern: komari-linux-*
+          path: .
+          merge-multiple: true
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to the Container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=raw,value=snapshot
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          no-cache: true
+          provenance: false

.github/workflows/test.yml

@@ -0,0 +1,57 @@
+name: Test
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - dev
+  workflow_dispatch:
+
+concurrency:
+  group: test-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Download dependencies
+        run: go mod download
+
+      # NOTE: the repository stores Go sources with CRLF line endings, which
+      # gofmt normalises to LF, so "gofmt -l" currently lists ~327 files. Until
+      # that is normalised repo-wide this step is advisory only; flip it to a
+      # hard failure once the tree is clean.
+      - name: Formatting report (advisory)
+        run: |
+          count=$(gofmt -l . | grep -v '^web/node_modules' | wc -l)
+          echo "gofmt reports $count file(s) needing formatting."
+          gofmt -l . | grep -v '^web/node_modules' | head -20 || true
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Test
+        run: go test ./... -count=1 -timeout 10m
+
+      - name: Test (repeat for isolation)
+        run: go test ./... -count=2 -shuffle=on -timeout 15m
+
+      - name: Race detector
+        run: go test -race ./pkg/metric/ ./internal/metricstore/ ./internal/plugin/ ./web/connection/ ./web/api/terminal/ -count=1 -timeout 15m
+
+      - name: Coverage
+        run: |
+          go test ./... -count=1 -coverpkg=./... -coverprofile=coverage.out -timeout 15m
+          go tool cover -func=coverage.out | tail -1

.gitignore

@@ -15,6 +15,7 @@ komari.db
 /utils/geoip/data
 .vscode/
 /backup
+/cache
 
 # Test binary, built with `go test -c`
 *.test
@@ -34,4 +35,7 @@ go.work.sum
 
 # build
 komari
+/dist/
 .codex
+.gocache/
+/web/filemanager/data

Dockerfile

@@ -8,30 +8,11 @@ ARG TARGETARCH
 
 RUN apk add --no-cache ca-certificates curl tzdata
 
-RUN set -eux; \
-    case "${TARGETARCH}" in \
-      amd64) cloudflared_arch="amd64" ;; \
-      386) cloudflared_arch="386" ;; \
-      arm64) cloudflared_arch="arm64" ;; \
-      arm) cloudflared_arch="arm" ;; \
-      *) echo "Unsupported TARGETARCH: ${TARGETARCH}" >&2; exit 1 ;; \
-    esac; \
-    curl -fsSL "https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-${cloudflared_arch}" -o /usr/local/bin/cloudflared; \
-    chmod +x /usr/local/bin/cloudflared
-
-COPY komari-${TARGETOS}-${TARGETARCH} /app/komari
-
-RUN chmod +x /app/komari
+COPY --chmod=755 komari-${TARGETOS}-${TARGETARCH} /app/komari
 
 ENV GIN_MODE=release
-ENV KOMARI_DB_TYPE=sqlite
-ENV KOMARI_DB_FILE=/app/data/komari.db
-ENV KOMARI_DB_HOST=localhost
-ENV KOMARI_DB_PORT=3306
-ENV KOMARI_DB_USER=root
-ENV KOMARI_DB_PASS=
-ENV KOMARI_DB_NAME=komari
 ENV KOMARI_LISTEN=0.0.0.0:25774
+ENV GODEBUG=disablethp=1
 
 EXPOSE 25774
 

README.md

@@ -5,138 +5,64 @@
 
 ![komari](https://socialify.git.ci/komari-monitor/komari/image?description=1&font=Inter&forks=1&issues=1&language=1&logo=https%3A%2F%2Fraw.githubusercontent.com%2Fkomari-monitor%2Fkomari-web%2Fd54ce1288df41ead08aa19f8700186e68028a889%2Fpublic%2Ffavicon.png&name=1&owner=1&pattern=Plus&pulls=1&stargazers=1&theme=Auto)
 
-[简体中文](./docs/README_zh.md) | [繁體中文](./docs/README_zh-TW.md) | [日本語](./docs/README_ja.md)
+[English](./README.md) | [简体中文](./README_zh-cn.md)
 
-Komari is a lightweight, self-hosted server monitoring tool designed to provide a simple and efficient solution for monitoring server performance. It supports viewing server status through a web interface and collects data through a lightweight agent.
+Komari is a lightweight, self-hosted server monitoring solution. It provides a simple and efficient way to track server performance through a web interface, with metrics collected by a lightweight agent.
 
-[Documentation](https://komari-document.pages.dev/) | [文档(镜像站 By Geekertao)](https://www.komari.wiki) | [Telegram Group](https://t.me/komari_monitor)
+> [!WARNING]
+> Komari is a self-hosted monitoring and control application. Deploy it only on systems you own or are authorized to manage. You are solely responsible for how you deploy and use Komari. The developers accept no liability for unauthorized access, persistence, command execution, other misuse, or any resulting consequences.
+
+[Documentation](https://www.komari.wiki/) | [Telegram Group](https://t.me/komari_monitor)
 
 ## Features
 
-- **Lightweight and Efficient**: Low resource consumption, suitable for servers of all sizes.
-- **Self-hosted**: Complete control over data privacy, easy to deploy.
-- **Web Interface**: Intuitive monitoring dashboard, easy to use.
+- **Real-time monitoring**: Displays monitoring data at one-second intervals.
+- **Lightweight and efficient**: Uses minimal system resources and works well on servers of any size.
+- **Self-hosted**: Keeps you in control of your data and privacy.
+- **Web interface**: Provides an intuitive, easy-to-use monitoring dashboard.
+- **Extensible**: Supports custom themes and plugins.
 
 ## Quick Start
 
-### 0. One-click Deployment with Cloud Hosting
+| Platform                                                                                                                                                                                                  | Description                                                                                                                                                                                           |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a href="https://app.rainyun.com/apps/rca/store/6780/NzYxNzAz_"><img src="https://rainyun-apps.cn-nb1.rains3.com/materials/deploy-on-rainyun-cn.svg" alt="Rainyun" width="180"></a>                       | Deploy websites, databases, and hundreds of popular apps in seconds with flexible hourly billing. [Get started for just ¥5/month. Deploy now!](https://app.rainyun.com/apps/rca/store/6780/NzYxNzAz_) |
+| <a href="https://apps.fit2cloud.com/1panel/komari"><img src="https://raw.githubusercontent.com/komari-monitor/public/refs/heads/main/images/1panel-logo-blue.png" alt="1Panel App Store" width="180"></a> | A modern, open-source Linux server management panel for websites, databases, containers, files, backups, security, and AI, with one-click deployment from its app store.                              |
 
-- Rainyun - CNY 4.5/month
+For instructions on Docker deployment, binary installation, building from source, and updates, see the [installation guide](https://www.komari.wiki/en/install/quick-start).
 
-[![](https://rainyun-apps.cn-nb1.rains3.com/materials/deploy-on-rainyun-cn.svg)](https://app.rainyun.com/apps/rca/store/6780/NzYxNzAz_)
+## Screenshots
 
-- 1Panel App Store
+| Page                | Screenshot                                                                                                                                                             |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Home Dashboard      | <img src="https://b2.akz.moe/awesome-pictures/komari-screenshot/%E4%B8%BB%E9%A1%B5%E4%BB%AA%E8%A1%A8%E7%9B%98-en.webp" width="800" alt="Home Dashboard">               |
+| Admin Dashboard     | <img src="https://b2.akz.moe/awesome-pictures/komari-screenshot/%E5%90%8E%E5%8F%B0%E4%BB%AA%E8%A1%A8%E7%9B%98-en.webp" width="800" alt="Admin Dashboard">              |
+| History Charts      | <img src="https://b2.akz.moe/awesome-pictures/komari-screenshot/%E5%8E%86%E5%8F%B2%E5%9B%BE%E8%A1%A8-en.webp" width="800" alt="History Charts">                        |
+| Web Terminal        | <img src="https://b2.akz.moe/awesome-pictures/komari-screenshot/%E7%BD%91%E9%A1%B5%E7%BB%88%E7%AB%AF.webp" width="800" alt="Web Terminal">                             |
+| Customizable Themes | <img src="https://b2.akz.moe/awesome-pictures/komari-screenshot/%E4%B8%BB%E9%A2%98%E5%8F%AF%E8%87%AA%E5%AE%9A%E4%B9%89-en.webp" width="800" alt="Customizable Themes"> |
+| Theme Market        | <img src="https://b2.akz.moe/awesome-pictures/komari-screenshot/%E4%B8%BB%E9%A2%98%E5%B8%82%E5%9C%BA-en.webp" width="800" alt="Theme Market">                          |
 
-Available on 1Panel App Store. Install via **App Store > Utilities > Komari**.
+## Sponsors
 
-### 1. Use the One-click Install Script
+Interested in sponsoring Komari? Contact the developer via [email](mailto:komari@akz.moe) or [Telegram](https://t.me/mamomoe).
 
-Suitable for distributions using systemd (Ubuntu, Debian...).
+| Sponsor                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                   |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a href="https://mooproxy.net/?utm_source=komari"><img src="https://raw.githubusercontent.com/komari-monitor/public/refs/heads/main/images/Mooproxy-logo-transparent.png" alt="mooproxy.net" width="180"></a> | [MooProxy · Rotating residential proxies from $0.20/GB. Sign up for 500MB of free traffic and try it today!](https://mooproxy.net/?utm_source=komari) |
+| <a href="https://axisnow.io/zh?utm=komari"><img src="https://raw.githubusercontent.com/komari-monitor/public/refs/heads/main/images/AxisNow.jpg" alt="AxisNow" width="180"></a> | [Self-Hosted Private CDN \| Subscription-Based CDN-Like Service \| A Fully Controlled, Flexible, Modular CDN Network](https://axisnow.io/zh?utm=komari) |
+| <a href="https://whmcs.as211392.com/aff.php?aff=110"><img src="https://raw.githubusercontent.com/komari-monitor/public/refs/heads/main/images/dreamcloud.png" alt="Dream Cloud" width="180"></a> | Cost-effective Asia-Pacific hosting with direct connectivity and robust DDoS protection, backed by transparent capacity claims.                                                                                                                                               |
+| <a href="https://sharon.io"><img src="https://raw.githubusercontent.com/komari-monitor/public/refs/heads/main/images/sharon-networks.webp" alt="Sharon Networks" width="180"></a>                | Premium China-optimized connectivity from Asia-Pacific data centers, featuring low latency, high bandwidth, and Tbps-scale local DDoS mitigation. Join the [Telegram community](https://t.me/SharonNetwork) to participate in charitable initiatives and community giveaways. |
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/komari-monitor/komari/main/install-komari.sh -o install-komari.sh
-chmod +x install-komari.sh
-sudo ./install-komari.sh
-```
+## Contributors
 
-### 2. Docker Deployment
+Thanks to everyone who has contributed code, themes, plugins, documentation, translations, bug reports, or feedback to Komari.
 
-1. Create a data directory:
-   ```bash
-   mkdir -p ./data
-   ```
-2. Run the Docker container:
-   ```bash
-   docker run -d \
-     -p 25774:25774 \
-     -v $(pwd)/data:/app/data \
-     --name komari \
-     ghcr.io/komari-monitor/komari:latest
-   ```
-3. View the default username and password:
-   ```bash
-   docker logs komari
-   ```
-4. Access `http://<your_server_ip>:25774` in your browser.
+<a href="https://github.com/komari-monitor/komari/graphs/contributors"><img src="https://contributors-img.web.app/image?repo=komari-monitor/komari" alt="Komari contributors" width="600"></a>
 
-> [!NOTE]
-> You can also customize the initial username and password through the environment variables `ADMIN_USERNAME` and `ADMIN_PASSWORD`.
+## Support the Project
 
-### 3. Binary File Deployment
+If Komari has been useful to you, consider buying me a coffee. Thank you for your support!
 
-1. Visit Komari's [GitHub Release page](https://github.com/komari-monitor/komari/releases) to download the latest binary for your operating system.
-2. Run Komari:
-   ```bash
-   ./komari server -l 0.0.0.0:25774
-   ```
-3. Access `http://<your_server_ip>:25774` in your browser. The default port is `25774`.
-4. The default username and password can be found in the startup logs or set via the environment variables `ADMIN_USERNAME` and `ADMIN_PASSWORD`.
-
-> [!NOTE]
-> Ensure the binary has execute permissions (`chmod +x komari`). Data will be saved in the `data` folder in the running directory.
-
-### Manual Build
-
-#### Dependencies
-
-- Go 1.18+ and Node.js 20+ (for manual build)
-
-1. Build the frontend static files:
-   ```bash
-   git clone https://github.com/komari-monitor/komari-web
-   cd komari-web
-   npm install
-   npm run build
-   ```
-2. Build the backend:
-   ```bash
-   git clone https://github.com/komari-monitor/komari
-   cd komari
-   ```
-   Copy the static files generated in step 1 to the `/web/public/defaultTheme/dist` folder in the root of the `komari` project, and copy `komari-theme.json` + `preview.png`/`perview.png` to `/web/public/defaultTheme`.
-   ```bash
-   go build -o komari
-   ```
-3. Run:
-   ```bash
-   ./komari server -l 0.0.0.0:25774
-   ```
-   The default listening port is `25774`. Access `http://localhost:25774`.
-
-## Frontend Development Guide
-
-[Komari Theme Development Guide | Komari](https://komari-document.pages.dev/dev/theme.html)
-
-## Client Agent Development Guide
-
-[Komari Agent Information Reporting and Event Handling Documentation](https://komari-document.pages.dev/dev/agent.html)
-
-## Contributing
-
-Issues and Pull Requests are welcome!
-
-## Acknowledgements
-
-### 破碎工坊云
-
-[破碎工坊云 - 专业云计算服务平台，提供高效、稳定、安全的高防服务器与CDN解决方案](https://www.crash.work/)
-
-### DreamCloud
-
-[DreamCloud - 极高性价比解锁直连亚太高防](https://as211392.com/)
-
-### 🚀 Sponsored by SharonNetworks
-
-[![Sharon Networks](https://raw.githubusercontent.com/komari-monitor/public/refs/heads/main/images/sharon-networks.webp)](https://sharon.io)
-
-SharonNetworks 为您的业务起飞保驾护航！
-
-亚太数据中心提供顶级的中国优化网络接入 · 低延时&高带宽&提供Tbps级本地清洗高防服务, 为您的业务保驾护航, 为您的客户提供极致体验. 加入社区 [Telegram群组](https://t.me/SharonNetwork) 可参与公益募捐或群内抽奖免费使用
-
-### The open source software community
-
-All the developers who submitted PRs and created themes
-
-## Star History
-
-[![Star History Chart](https://api.star-history.com/svg?repos=komari-monitor/komari&type=Date)](https://www.star-history.com/#komari-monitor/komari&Date)
+| TRON Network                                                                                |
+| ------------------------------------------------------------------------------------------- |
+| ![TRON Network QR code](https://b2.akz.moe/awesome-pictures/PixPin_2026-08-07_15-16-52.png) |

README_zh-cn.md

@@ -0,0 +1,68 @@
+# Komari
+
+![Badge](https://hitscounter.dev/api/hit?url=https%3A%2F%2Fgithub.com%2Fkomari-monitor%2Fkomari&label=&icon=github&color=%23a370f7&message=&style=flat&tz=UTC)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/komari-monitor/komari)
+
+![komari](https://socialify.git.ci/komari-monitor/komari/image?description=1&font=Inter&forks=1&issues=1&language=1&logo=https%3A%2F%2Fraw.githubusercontent.com%2Fkomari-monitor%2Fkomari-web%2Fd54ce1288df41ead08aa19f8700186e68028a889%2Fpublic%2Ffavicon.png&name=1&owner=1&pattern=Plus&pulls=1&stargazers=1&theme=Auto)
+
+[English](./README.md) | [简体中文](./README_zh-cn.md)
+
+Komari 是一款轻量级的自托管服务器监控工具，旨在提供简单、高效的服务器性能监控解决方案。它支持通过 Web 界面查看服务器状态，并通过轻量级 Agent 收集数据。
+
+> [!WARNING]
+> Komari 是一款自托管的监控/控制程序，仅应部署在你拥有或已获得授权管理的系统上。在未获授权的情况下部署、访问、持久化、执行命令及从事其他滥用行为，用户需要自行承担部署和使用 Komari 的责任。开发者不对未经授权或滥用行为及其后果承担责任。
+
+[文档](https://www.komari.wiki/) | [Telegram 群](https://t.me/komari_monitor)
+
+## 特性
+
+- **实时监控**: 秒级实时数据展示。
+- **轻量高效**：低资源占用，适合各种规模的服务器。
+- **自托管**：完全掌控数据隐私，部署简单。
+- **Web 界面**：直观的监控仪表盘，易于使用。
+- **极强的可扩展性**: 支持自定义主题和插件。
+
+## 快速开始
+
+| 平台                                                                                                                                                                                                     | 介绍                                                                                                                                   |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| <a href="https://app.rainyun.com/apps/rca/store/6780/NzYxNzAz_"><img src="https://rainyun-apps.cn-nb1.rains3.com/materials/deploy-on-rainyun-cn.svg" alt="Rainyun" width="180"></a>                      | 秒级部署网站、数据库及数百款热门 App，并采用按小时灵活计费。[每月5元，立即部署](https://app.rainyun.com/apps/rca/store/6780/NzYxNzAz_) |
+| <a href="https://apps.fit2cloud.com/1panel/komari"><img src="https://raw.githubusercontent.com/komari-monitor/public/refs/heads/main/images/1panel-logo-blue.png" alt="1Panel Appstore" width="180"></a> | 现代化、开源的Linux 服务器运维管理面板，提供网站、数据库、容器、文件、备份、安全与AI 管理能力，支持应用商店一键部署。                  |
+
+Docker、二进制文件、源码构建和更新说明，请参阅 [安装指南](https://www.komari.wiki/install/quick-start).
+
+## 截图
+
+| 页面         | 截图                                                                                                                                                         |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 主页仪表盘   | <img src="https://b2.akz.moe/awesome-pictures/komari-screenshot/%E4%B8%BB%E9%A1%B5%E4%BB%AA%E8%A1%A8%E7%9B%98.webp" width="800" alt="主页仪表盘">            |
+| 后台仪表盘   | <img src="https://b2.akz.moe/awesome-pictures/komari-screenshot/%E5%90%8E%E5%8F%B0%E4%BB%AA%E8%A1%A8%E7%9B%98.webp" width="800" alt="后台仪表盘">            |
+| 历史图表     | <img src="https://b2.akz.moe/awesome-pictures/komari-screenshot/%E5%8E%86%E5%8F%B2%E5%9B%BE%E8%A1%A8.webp" width="800" alt="历史图表">                       |
+| 网页终端     | <img src="https://b2.akz.moe/awesome-pictures/komari-screenshot/%E7%BD%91%E9%A1%B5%E7%BB%88%E7%AB%AF.webp" width="800" alt="网页终端">                       |
+| 主题可自定义 | <img src="https://b2.akz.moe/awesome-pictures/komari-screenshot/%E4%B8%BB%E9%A2%98%E5%8F%AF%E8%87%AA%E5%AE%9A%E4%B9%89.webp" width="800" alt="主题可自定义"> |
+| 主题市场     | <img src="https://b2.akz.moe/awesome-pictures/komari-screenshot/%E4%B8%BB%E9%A2%98%E5%B8%82%E5%9C%BA.webp" width="800" alt="主题市场">                       |
+
+## 赞助商
+
+有意赞助 Komari？请通过 [电子邮箱](mailto:komari@akz.moe) 或 [Telegram](https://t.me/mamomoe) 联系开发者。
+
+| 赞助商                                                                                                                                                                                           | 描述                                                                                                                                                                                                                |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a href="https://mooproxy.net/?utm_source=komari"><img src="https://raw.githubusercontent.com/komari-monitor/public/refs/heads/main/images/Mooproxy-logo-transparent.png" alt="mooproxy.net" width="180"></a> | [MooProxy · 动态住宅代理IP低至 $0.20/GB，注册即送 500MB 免费流量，立即体验！](https://mooproxy.net/?utm_source=komari) |
+| <a href="https://axisnow.io/zh?utm=komari"><img src="https://raw.githubusercontent.com/komari-monitor/public/refs/heads/main/images/AxisNow.jpg" alt="AxisNow" width="180"></a> | [自建私有部署CDN \| 订阅式高仿CDN \| 自主可控、灵活组合的CDN网络](https://axisnow.io/zh?utm=komari) |
+| <a href="https://whmcs.as211392.com/aff.php?aff=110"><img src="https://raw.githubusercontent.com/komari-monitor/public/refs/heads/main/images/dreamcloud.png" alt="Dream Cloud" width="180"></a> | 极高性价比解锁直连亚太高防，真高防，不虚标，打死退款                                                                                                                                                                |
+| <a href="https://sharon.io"><img src="https://raw.githubusercontent.com/komari-monitor/public/refs/heads/main/images/sharon-networks.webp" alt="Sharon Networks" width="180"></a>                | 亚太数据中心提供顶级的中国优化网络接入 · 低延时&高带宽&提供Tbps级本地清洗高防服务, 为您的业务保驾护航, 为您的客户提供极致体验. 加入社区 [Telegram群组](https://t.me/SharonNetwork) 可参与公益募捐或群内抽奖免费使用 |
+
+## 贡献者
+
+感谢所有为 Komari 贡献代码、主题、插件、文档、翻译、问题报告或反馈的朋友。
+
+<a href="https://github.com/komari-monitor/komari/graphs/contributors"><img src="https://contributors-img.web.app/image?repo=komari-monitor/komari" alt="Komari 贡献者" width="600"></a>
+
+## 支持项目
+
+如果 Komari 对你有所帮助，欢迎请作者喝一杯奶茶。感谢你的支持！
+
+| TRON Network                                                                |
+| --------------------------------------------------------------------------- |
+| ![TRON](https://b2.akz.moe/awesome-pictures/PixPin_2026-08-07_15-16-52.png) |

cmd/flags/config.go

@@ -10,11 +10,6 @@ var (
 	// 数据库配置
 	DatabaseType string // 数据库类型：sqlite
 	DatabaseFile string // SQLite数据库文件路径
-	DatabaseHost string // 保留的兼容参数，当前未使用
-	DatabasePort string // 保留的兼容参数，当前未使用
-	DatabaseUser string // 保留的兼容参数，当前未使用
-	DatabasePass string // 保留的兼容参数，当前未使用
-	DatabaseName string // 保留的兼容参数，当前未使用
 
 	Listen string
 )

cmd/flags/config_test.go

@@ -1,20 +0,0 @@
-package flags
-
-import "testing"
-
-func TestNormalizeDatabaseType(t *testing.T) {
-	tests := map[string]string{
-		"":          DatabaseTypeSQLite,
-		"sqlite":    DatabaseTypeSQLite,
-		" SQLite ":  DatabaseTypeSQLite,
-		"SQLITE":    DatabaseTypeSQLite,
-		"postgres":  "postgres",
-		" postgres": "postgres",
-	}
-
-	for input, want := range tests {
-		if got := NormalizeDatabaseType(input); got != want {
-			t.Fatalf("NormalizeDatabaseType(%q) = %q, want %q", input, got, want)
-		}
-	}
-}

cmd/permitPasswordLogin.go

@@ -4,7 +4,7 @@ import (
 	"os"
 
 	"github.com/komari-monitor/komari/database/dbcore"
-	"github.com/komari-monitor/komari/pkg/config"
+	"github.com/komari-monitor/komari/internal/config"
 	"github.com/spf13/cobra"
 )
 

cmd/root.go

@@ -17,17 +17,6 @@ func GetEnv(key, defaultValue string) string {
 	return value
 }
 
-// 从环境变量获取默认值
-var (
-	dbTypeEnv = GetEnv("KOMARI_DB_TYPE", "sqlite")
-	dbFileEnv = GetEnv("KOMARI_DB_FILE", "./data/komari.db")
-	dbHostEnv = GetEnv("KOMARI_DB_HOST", "localhost")
-	dbPortEnv = GetEnv("KOMARI_DB_PORT", "3306")
-	dbUserEnv = GetEnv("KOMARI_DB_USER", "root")
-	dbPassEnv = GetEnv("KOMARI_DB_PASS", "")
-	dbNameEnv = GetEnv("KOMARI_DB_NAME", "komari")
-)
-
 var RootCmd = &cobra.Command{
 	Use:   "Komari",
 	Short: "Komari is a simple server monitoring tool",
@@ -47,15 +36,6 @@ func Execute() {
 }
 
 func init() {
-	// 设置命令行参数，提供环境变量作为默认值
-	RootCmd.PersistentFlags().StringVarP(&flags.DatabaseType, "db-type", "t", dbTypeEnv, "Database type (sqlite) [env: KOMARI_DB_TYPE]")
-	RootCmd.PersistentFlags().StringVarP(&flags.DatabaseFile, "database", "d", dbFileEnv, "SQLite database file path [env: KOMARI_DB_FILE]")
-	RootCmd.PersistentFlags().StringVar(&flags.DatabaseHost, "db-host", dbHostEnv, "Reserved database host parameter [env: KOMARI_DB_HOST]")
-	RootCmd.PersistentFlags().StringVar(&flags.DatabasePort, "db-port", dbPortEnv, "Reserved database port parameter [env: KOMARI_DB_PORT]")
-	RootCmd.PersistentFlags().StringVar(&flags.DatabaseUser, "db-user", dbUserEnv, "Reserved database username parameter [env: KOMARI_DB_USER]")
-	RootCmd.PersistentFlags().StringVar(&flags.DatabasePass, "db-pass", dbPassEnv, "Reserved database password parameter [env: KOMARI_DB_PASS]")
-	RootCmd.PersistentFlags().StringVar(&flags.DatabaseName, "db-name", dbNameEnv, "Reserved database name parameter [env: KOMARI_DB_NAME]")
-	for _, name := range []string{"db-host", "db-port", "db-user", "db-pass", "db-name"} {
-		_ = RootCmd.PersistentFlags().MarkHidden(name)
-	}
+	RootCmd.PersistentFlags().StringVarP(&flags.DatabaseType, "db-type", "t", "sqlite", "Database type (sqlite)")
+	RootCmd.PersistentFlags().StringVarP(&flags.DatabaseFile, "database", "d", "./data/komari.db", "SQLite database file path")
 }

cmd/server.go

@@ -1,40 +1,14 @@
 package cmd
 
 import (
-	"context"
-	"fmt"
-	"log"
-	"net/http"
+	"errors"
 	"os"
-	"os/signal"
-	"syscall"
-	"time"
 
-	"github.com/gin-gonic/gin"
+	appserver "github.com/komari-monitor/komari/internal/server"
+	logger "github.com/komari-monitor/komari/utils/log"
+	frontendpublic "github.com/komari-monitor/komari/web/public"
+
 	"github.com/komari-monitor/komari/cmd/flags"
-	"github.com/komari-monitor/komari/pkg/corn"
-	"github.com/komari-monitor/komari/web/api"
-
-	"github.com/komari-monitor/komari/database"
-	"github.com/komari-monitor/komari/database/accounts"
-	"github.com/komari-monitor/komari/database/auditlog"
-	"github.com/komari-monitor/komari/database/dbcore"
-	"github.com/komari-monitor/komari/database/models"
-	d_notification "github.com/komari-monitor/komari/database/notification"
-	"github.com/komari-monitor/komari/database/records"
-	"github.com/komari-monitor/komari/database/tasks"
-	"github.com/komari-monitor/komari/pkg/config"
-	"github.com/komari-monitor/komari/utils"
-	"github.com/komari-monitor/komari/utils/cloudflared"
-	"github.com/komari-monitor/komari/utils/geoip"
-	logutil "github.com/komari-monitor/komari/utils/log"
-	"github.com/komari-monitor/komari/utils/messageSender"
-	"github.com/komari-monitor/komari/utils/notifier"
-	"github.com/komari-monitor/komari/web/nezha"
-	"github.com/komari-monitor/komari/web/oauth"
-	report_cache "github.com/komari-monitor/komari/web/report"
-	"github.com/komari-monitor/komari/web/router"
-	"github.com/komari-monitor/komari/web/security"
 	"github.com/spf13/cobra"
 )
 
@@ -54,184 +28,100 @@ func init() {
 	RootCmd.AddCommand(ServerCmd)
 }
 
+// RunServer 按显式的生命周期阶段启动服务端。
+//
+// 具体各阶段的职责与顺序见 internal/server.App。这里只负责串联：
+// 任一初始化阶段失败即中止启动，避免在半初始化状态下对外提供服务。
 func RunServer() {
-	// #region 初始化
-	if err := os.MkdirAll("./data/theme", os.ModePerm); err != nil {
-		log.Fatalf("Failed to create theme directory: %v", err)
+	if err := frontendpublic.PrepareDefaultDist(); err != nil {
+		logger.Fatalf("server", "prepare default frontend failed: %v", err)
 	}
-	InitDatabase()
-	if utils.VersionHash != "unknown" {
-		gin.SetMode(gin.ReleaseMode)
+
+	app := appserver.New(appserver.Options{ListenAddr: flags.Listen})
+	if err := app.Bootstrap(); err != nil {
+		_ = app.Shutdown()
+		logger.Fatalf("server", "server startup failed at %q: %v", "bootstrap", err)
 	}
-	conf, err := config.GetManyAs[config.Settings]()
+
+	installRequired, err := app.InstallRequired()
 	if err != nil {
-		log.Fatal(err)
+		_ = app.Shutdown()
+		logger.Fatalf("server", "server startup failed at %q: %v", "detect-first-run-install", err)
 	}
-	go geoip.InitGeoIp()
-	go DoScheduledWork()
-	go messageSender.Initialize()
-	// oidcInit
-	go oauth.Initialize()
-
-	if conf.NezhaCompatEnabled {
-		go func() {
-			if err := nezha.StartNezhaCompat(conf.NezhaCompatListen); err != nil {
-				log.Printf("Nezha compat server error: %v", err)
-				auditlog.EventLog("error", fmt.Sprintf("Nezha compat server error: %v", err))
-			}
-		}()
-	}
-
-	config.Subscribe(func(event config.ConfigEvent) {
-		if ok, t := config.IsChangedT[string](event, config.OAuthProviderKey); ok {
-			if t == "" || t == "none" {
-				t = "github"
-			}
-			oidcProvider, err := database.GetOidcConfigByName(t)
-			if err != nil {
-				log.Printf("Failed to get OIDC provider config: %v", err)
-			} else {
-				log.Printf("Using %s as OIDC provider", oidcProvider.Name)
-			}
-			err = oauth.LoadProvider(oidcProvider.Name, oidcProvider.Addition)
-			if err != nil {
-				auditlog.EventLog("error", fmt.Sprintf("Failed to load OIDC provider: %v", err))
-			}
-		}
-
-		if ok, t := config.IsChangedT[bool](event, config.NezhaCompatEnabledKey); ok {
-			if t {
-				l, _ := config.GetAs[string](config.NezhaCompatListenKey)
-				if err := nezha.StartNezhaCompat(l); err != nil {
-					log.Printf("start Nezha compat server error: %v", err)
-					auditlog.EventLog("error", fmt.Sprintf("start Nezha compat server error: %v", err))
-				}
-			} else {
-				if err := nezha.StopNezhaCompat(); err != nil {
-					log.Printf("stop Nezha compat server error: %v", err)
-					auditlog.EventLog("error", fmt.Sprintf("stop Nezha compat server error: %v", err))
-				}
-			}
-		}
-
-	})
-	// 初始化 cloudflared
-	if err := cloudflared.AutoStart(GetEnv("KOMARI_CLOUDFLARED_TOKEN", "")); err != nil {
-		log.Printf("failed to auto start cloudflared: %v", err)
-	}
-
-	r := gin.New()
-	r.Use(logutil.GinLogger())
-	r.Use(logutil.GinRecovery())
-
-	config.Subscribe(func(event config.ConfigEvent) {
-		if event.IsChanged(config.GeoIpProviderKey) {
-			go geoip.InitGeoIp()
-		}
-
-		if event.IsChanged(config.NotificationMethodKey) {
-			go messageSender.Initialize()
-		}
-
-	})
-	r.Use(security.CorsMiddleware(conf.CorsOriginCheckEnabled, conf.CorsAllowedOrigins))
-
-	r.Use(api.IdentityMiddleware())
-	r.Use(api.PrivateSiteMiddleware())
-
-	r.Use(func(c *gin.Context) {
-		if len(c.Request.URL.Path) >= 4 && c.Request.URL.Path[:4] == "/api" {
-			c.Header("Cache-Control", "no-store")
-		}
-		c.Next()
-	})
-
-	router.Register(r)
-
-	srv := &http.Server{
-		Addr:    flags.Listen,
-		Handler: r,
-	}
-	log.Printf("Starting server on %s ...", flags.Listen)
-	go func() {
-		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
-			OnFatal(err)
-			log.Fatalf("listen: %s\n", err)
-		}
-	}()
-	quit := make(chan os.Signal, 1)
-	signal.Notify(quit, os.Interrupt, syscall.SIGTERM)
-	<-quit
-	OnShutdown()
-	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-	defer cancel()
-	if err := srv.Shutdown(ctx); err != nil {
-		log.Fatalf("Server forced to shutdown: %v", err)
-	}
-
-}
-
-func InitDatabase() {
-	var count int64 = 0
-	if dbcore.GetDBInstance().Model(&models.User{}).Count(&count); count == 0 {
-		user, passwd, err := accounts.CreateDefaultAdminAccount()
+	if installRequired {
+		completed, err := app.RunInstallGuide()
 		if err != nil {
-			panic(err)
+			_ = app.Shutdown()
+			logger.Fatalf("server", "server startup failed at %q: %v", "run-first-run-install", err)
 		}
-		log.Println("Default admin account created. Username:", user, ", Password:", passwd)
+		if !completed {
+			return
+		}
+	}
+
+	for {
+		requirement, err := app.DatabaseMigrationRequired()
+		if err != nil {
+			completed, recoveryErr := app.RunMetricStoreRecovery(err)
+			if recoveryErr != nil {
+				_ = app.Shutdown()
+				logger.Fatalf("server", "server startup failed at %q: %v", "database-migration-detection-recovery", recoveryErr)
+			}
+			if !completed {
+				return
+			}
+			continue
+		}
+		if !requirement.Required() {
+			break
+		}
+		completed, err := app.RunDatabaseMigration(requirement)
+		if err != nil {
+			_ = app.Shutdown()
+			logger.Fatalf("server", "server startup failed at %q: %v", "run-database-migration", err)
+		}
+		if !completed {
+			return
+		}
+	}
+
+	// Metric store 是唯一允许进入恢复向导的启动阶段：主库已经在
+	// Bootstrap 中就绪，因此可以保留登录能力并让管理员修正 DSN。
+	if err := app.ConnectMetricStoreWithRetry(); err != nil {
+		completed, recoveryErr := app.RunMetricStoreRecovery(err)
+		if recoveryErr != nil {
+			_ = app.Shutdown()
+			logger.Fatalf("server", "server startup failed at %q: %v", "metric-store-recovery", recoveryErr)
+		}
+		if !completed {
+			return
+		}
+	}
+
+	// 其余初始化阶段：任一步失败都不应继续对外服务。
+	type stage struct {
+		name string
+		fn   func() error
+	}
+	stages := []stage{
+		{"init-stores", app.InitStores},
+		{"init-providers", app.InitProviders},
+		{"start-background", app.StartBackground},
+		{"build-router", app.BuildRouter},
+	}
+	for _, s := range stages {
+		if err := s.fn(); err != nil {
+			// 已登记的资源尽力回收，再退出。
+			_ = app.Shutdown()
+			logger.Fatalf("server", "server startup failed at %q: %v", s.name, err)
+		}
+	}
+
+	if err := app.Run(); err != nil {
+		if errors.Is(err, appserver.ErrRestartRequested) {
+			logger.Infof("server", "Service stopped for restart: %v", err)
+			os.Exit(1)
+		}
+		logger.Fatalf("server", "server exited with error: %v", err)
 	}
 }
-
-// #region 定时任务
-func DoScheduledWork() {
-	if err := tasks.ReloadPingSchedule(); err != nil {
-		log.Println("Failed to reload ping schedule:", err)
-	}
-	if err := d_notification.ReloadLoadNotificationSchedule(); err != nil {
-		log.Println("Failed to reload load notification schedule:", err)
-	}
-	records.CompactRecord()
-
-	if err := corn.AddFunc("records:cleanup", "@every 30m", cleanupScheduledData); err != nil {
-		log.Println("Failed to add cleanup scheduled task:", err)
-	}
-	if err := corn.AddFunc("records:minute", "@every 1m", minuteScheduledWork); err != nil {
-		log.Println("Failed to add minute scheduled task:", err)
-	}
-	if err := corn.AddFunc("notifier:expire", "0 0 9 * * *", notifier.CheckExpireScheduledWork); err != nil {
-		log.Println("Failed to add expire notification scheduled task:", err)
-	}
-	notifier.InitTrafficReportSchedule()
-}
-
-func cleanupScheduledData() {
-	cfg, _ := config.GetManyAs[config.Settings]()
-	records.DeleteRecordBefore(time.Now().Add(-time.Hour * time.Duration(cfg.RecordPreserveTime)))
-	records.CompactRecord()
-	tasks.ClearTaskResultsByTimeBefore(time.Now().Add(-time.Hour * time.Duration(cfg.RecordPreserveTime)))
-	tasks.DeletePingRecordsBefore(time.Now().Add(-time.Hour * time.Duration(cfg.PingRecordPreserveTime)))
-	auditlog.RemoveOldLogs()
-	accounts.RemoveExpiredSessions()
-}
-
-func minuteScheduledWork() {
-	cfg, _ := config.GetManyAs[config.Settings]()
-	report_cache.SaveClientReportToDB()
-	if !cfg.RecordEnabled {
-		records.DeleteAll()
-		tasks.DeleteAllPingRecords()
-	}
-	// 每分钟检查一次流量提醒
-	notifier.CheckTraffic()
-}
-
-func OnShutdown() {
-	auditlog.Log("", "", "server is shutting down", "info")
-	corn.StopAll()
-	cloudflared.Shutdown()
-}
-
-func OnFatal(err error) {
-	auditlog.Log("", "", "server encountered a fatal error: "+err.Error(), "error")
-	cloudflared.Shutdown()
-}

database/accounts/2fa.go

@@ -35,21 +35,11 @@ func Enable2Fa(uuid, secret string) error {
 func Verify2Fa(uuid, code string) (bool, error) {
 	db := dbcore.GetDBInstance()
 	var user models.User
-	err := db.Where("uuid = ?", uuid).First(&user).Error
-	if err != nil {
+	if err := db.Where("uuid = ?", uuid).First(&user).Error; err != nil {
 		return false, err
 	}
-
-	if user.TwoFactor == "" {
-		return false, nil // 用户未启用2FA
-	}
-
-	valid := totp.Validate(code, user.TwoFactor)
-	if !valid {
-		return false, nil
-	}
-
-	return true, nil
+	// 用户未启用2FA时视为校验失败
+	return user.TwoFactor != "" && totp.Validate(code, user.TwoFactor), nil
 }
 
 func Disable2Fa(uuid string) error {

database/accounts/accounts.go

@@ -4,27 +4,22 @@ import (
 	"crypto/sha256"
 	"encoding/base64"
 	"fmt"
-	"os"
 	"time"
 
+	"github.com/google/uuid"
 	"github.com/komari-monitor/komari/database/dbcore"
 	"github.com/komari-monitor/komari/database/models"
-	"github.com/komari-monitor/komari/utils"
-
-	"github.com/google/uuid"
+	"gorm.io/gorm"
 )
 
 const constantSalt = "06Wm4Jv1Hkxx"
 
-// CheckPassword 检查密码是否正确
-//
-// 如果密码正确，返回用户的 UUID 和 true；否则返回空字符串和 false
-func CheckPassword(username, passwd string) (uuid string, success bool) {
+// CheckPassword 检查密码，正确时返回用户 UUID 和 true
+func CheckPassword(username, passwd string) (uuid string, ok bool) {
 	db := dbcore.GetDBInstance()
 	var user models.User
 	result := db.Where("username = ?", username).First(&user)
 	if result.Error != nil {
-		// 静默处理错误，不显示日志
 		return "", false
 	}
 	if hashPasswd(passwd) != user.Passwd {
@@ -34,7 +29,7 @@ func CheckPassword(username, passwd string) (uuid string, success bool) {
 }
 
 // ForceResetPassword 强制重置用户密码
-func ForceResetPassword(username, passwd string) (err error) {
+func ForceResetPassword(username, passwd string) error {
 	db := dbcore.GetDBInstance()
 	result := db.Model(&models.User{}).Where("username = ?", username).Update("passwd", hashPasswd(passwd))
 	if result.Error != nil {
@@ -48,109 +43,54 @@ func ForceResetPassword(username, passwd string) (err error) {
 
 // hashPasswd 对密码进行加盐哈希
 func hashPasswd(passwd string) string {
-	saltedPassword := passwd + constantSalt
-	hash := sha256.New()
-	hash.Write([]byte(saltedPassword))
-	hashedPassword := base64.StdEncoding.EncodeToString(hash.Sum(nil))
-	return hashedPassword
+	h := sha256.Sum256([]byte(passwd + constantSalt))
+	return base64.StdEncoding.EncodeToString(h[:])
 }
 
 func CreateAccount(username, passwd string) (user models.User, err error) {
-	db := dbcore.GetDBInstance()
-	hashedPassword := hashPasswd(passwd)
-	user = models.User{
+	return CreateAccountWithDB(dbcore.GetDBInstance(), username, passwd)
+}
+
+func CreateAccountWithDB(db *gorm.DB, username, passwd string) (models.User, error) {
+	user := models.User{
 		UUID:     uuid.New().String(),
 		Username: username,
-		Passwd:   hashedPassword,
+		Passwd:   hashPasswd(passwd),
 	}
-	err = db.Create(&user).Error
-	if err != nil {
-		return models.User{}, err
-	}
-	return user, nil
+	return user, db.Create(&user).Error
 }
 
 func DeleteAccountByUsername(username string) (err error) {
-	db := dbcore.GetDBInstance()
-	err = db.Where("username = ?", username).Delete(&models.User{}).Error
-	if err != nil {
-		return err
-	}
-	return nil
+	return DeleteAccountByUsernameWithDB(dbcore.GetDBInstance(), username)
 }
 
-// 创建默认管理员账户，使用环境变量 ADMIN_USERNAME 作为用户名，环境变量 ADMIN_PASSWORD 作为密码
-func CreateDefaultAdminAccount() (username, passwd string, err error) {
-	db := dbcore.GetDBInstance()
-
-	username = os.Getenv("ADMIN_USERNAME")
-	if username == "" {
-		username = "admin"
-	}
-
-	passwd = os.Getenv("ADMIN_PASSWORD")
-	if passwd == "" {
-		passwd = utils.GeneratePassword()
-	}
-
-	hashedPassword := hashPasswd(passwd)
-
-	user := models.User{
-		UUID:      uuid.New().String(),
-		Username:  username,
-		Passwd:    hashedPassword,
-		SSOID:     "",
-		CreatedAt: models.FromTime(time.Now()),
-		UpdatedAt: models.FromTime(time.Now()),
-	}
-
-	err = db.Create(&user).Error
-	if err != nil {
-		return "", "", err
-	}
-
-	return username, passwd, nil
+func DeleteAccountByUsernameWithDB(db *gorm.DB, username string) error {
+	return db.Where("username = ?", username).Delete(&models.User{}).Error
 }
 
-func GetUserByUUID(uuid string) (user models.User, err error) {
+func GetUserByUUID(uuid string) (models.User, error) {
+	var user models.User
+	return user, dbcore.GetDBInstance().Where("uuid = ?", uuid).First(&user).Error
+}
+
+// GetUserBySSO 通过 SSO 信息获取用户
+func GetUserBySSO(ssoID string) (models.User, error) {
 	db := dbcore.GetDBInstance()
-	err = db.Where("uuid = ?", uuid).First(&user).Error
-	if err != nil {
-		return models.User{}, err
+	var user models.User
+	if err := db.Where("sso_id = ?", ssoID).First(&user).Error; err != nil {
+		return models.User{}, fmt.Errorf("用户不存在：%s", ssoID)
 	}
 	return user, nil
 }
 
-// 通过 SSO 信息获取用户
-func GetUserBySSO(ssoID string) (user models.User, err error) {
-	db := dbcore.GetDBInstance()
-
-	// 首先尝试查找已存在的用户
-	err = db.Where("sso_id = ?", ssoID).First(&user).Error
-	if err == nil {
-		return user, nil
-	}
-
-	// 如果找不到用户，返回明确的错误信息
-	return models.User{}, fmt.Errorf("用户不存在：%s", ssoID)
-}
-
 func BindingExternalAccount(uuid string, sso_id string) error {
 	db := dbcore.GetDBInstance()
-	err := db.Model(&models.User{}).Where("uuid = ?", uuid).Update("sso_id", sso_id).Error
-	if err != nil {
-		return err
-	}
-	return nil
+	return db.Model(&models.User{}).Where("uuid = ?", uuid).Update("sso_id", sso_id).Error
 }
 
 func UnbindExternalAccount(uuid string) error {
 	db := dbcore.GetDBInstance()
-	err := db.Model(&models.User{}).Where("uuid = ?", uuid).Update("sso_id", "").Error
-	if err != nil {
-		return err
-	}
-	return nil
+	return db.Model(&models.User{}).Where("uuid = ?", uuid).Update("sso_id", "").Error
 }
 
 func UpdateUser(uuid string, name, password, sso_type *string) error {
@@ -171,9 +111,8 @@ func UpdateUser(uuid string, name, password, sso_type *string) error {
 	if sso_type != nil {
 		updates["sso_type"] = *sso_type
 	}
-	updates["updated_at"] = time.Now()
-	err := db.Model(&models.User{}).Where("uuid = ?", uuid).Updates(updates).Error
-	if err != nil {
+	updates["updated_at"] = time.Now().UTC()
+	if err := db.Model(&models.User{}).Where("uuid = ?", uuid).Updates(updates).Error; err != nil {
 		return err
 	}
 	if password != nil {

database/accounts/accounts_test.go

@@ -0,0 +1,220 @@
+package accounts
+
+import (
+	"testing"
+	"time"
+
+	"github.com/pquerna/otp/totp"
+)
+
+// TestHashPasswordIsSaltedAndStable pins the password hash contract: stable
+// for the same input, different for different passwords, and never equal to
+// the plaintext.
+func TestHashPasswordIsSaltedAndStable(t *testing.T) {
+	a := hashPasswd("correct horse battery staple")
+	b := hashPasswd("correct horse battery staple")
+	if a != b {
+		t.Fatal("hash is not deterministic for the same password")
+	}
+	if hashPasswd("other password") == a {
+		t.Fatal("different passwords produced the same hash")
+	}
+	if a == "correct horse battery staple" {
+		t.Fatal("hash equals the plaintext")
+	}
+	if a == hashPasswd("correct horse battery staplex") {
+		t.Fatal("hash is not sensitive to a one-character change")
+	}
+}
+
+// TestCheckPassword covers the credential check used by the login endpoint.
+func TestCheckPassword(t *testing.T) {
+	resetAccountsState(t)
+	user, err := CreateAccount("alice", "Strong-password1")
+	if err != nil {
+		t.Fatalf("create account: %v", err)
+	}
+
+	if uuid, ok := CheckPassword("alice", "Strong-password1"); !ok || uuid != user.UUID {
+		t.Fatalf("correct password rejected: uuid=%q ok=%v", uuid, ok)
+	}
+	if _, ok := CheckPassword("alice", "wrong-password"); ok {
+		t.Fatal("wrong password accepted")
+	}
+	if _, ok := CheckPassword("nobody", "Strong-password1"); ok {
+		t.Fatal("unknown user accepted")
+	}
+}
+
+// TestForceResetPasswordChangesCredential guards the admin recovery path.
+func TestForceResetPasswordChangesCredential(t *testing.T) {
+	resetAccountsState(t)
+	if _, err := CreateAccount("bob", "Old-password1"); err != nil {
+		t.Fatalf("create account: %v", err)
+	}
+	if err := ForceResetPassword("bob", "New-password1"); err != nil {
+		t.Fatalf("force reset: %v", err)
+	}
+	if _, ok := CheckPassword("bob", "Old-password1"); ok {
+		t.Fatal("old password still works after reset")
+	}
+	if _, ok := CheckPassword("bob", "New-password1"); !ok {
+		t.Fatal("new password does not work after reset")
+	}
+	if err := ForceResetPassword("nobody", "New-password1"); err == nil {
+		t.Fatal("reset of a missing user should fail")
+	}
+}
+
+// TestSessionLifecycle covers creation, lookup and deletion.
+func TestSessionLifecycle(t *testing.T) {
+	resetAccountsState(t)
+	user, err := CreateAccount("carol", "Strong-password1")
+	if err != nil {
+		t.Fatalf("create account: %v", err)
+	}
+
+	session, err := CreateSession(user.UUID, 3600, "ua", "127.0.0.1", "password")
+	if err != nil {
+		t.Fatalf("create session: %v", err)
+	}
+	if got, err := GetSession(session); err != nil || got != user.UUID {
+		t.Fatalf("GetSession = %q, %v; want %q", got, err, user.UUID)
+	}
+
+	if err := DeleteSession(session); err != nil {
+		t.Fatalf("delete session: %v", err)
+	}
+	if _, err := GetSession(session); err == nil {
+		t.Fatal("deleted session still resolves")
+	}
+}
+
+// TestExpiredSessionIsRejectedAndRemoved verifies GetSession both refuses an
+// expired session and cleans it up.
+func TestExpiredSessionIsRejectedAndRemoved(t *testing.T) {
+	resetAccountsState(t)
+	user, err := CreateAccount("dave", "Strong-password1")
+	if err != nil {
+		t.Fatalf("create account: %v", err)
+	}
+	// expires=-1 puts the record in the past.
+	session, err := CreateSession(user.UUID, -1, "ua", "127.0.0.1", "password")
+	if err != nil {
+		t.Fatalf("create session: %v", err)
+	}
+
+	if _, err := GetSession(session); err == nil {
+		t.Fatal("expired session resolved successfully")
+	}
+	if got := countSessions(t, "session = ?", session); got != 0 {
+		t.Fatalf("expired session was not removed, %d rows remain", got)
+	}
+}
+
+// TestRemoveExpiredSessionsOnlyDropsExpired pins the janitor's selectivity.
+func TestRemoveExpiredSessionsOnlyDropsExpired(t *testing.T) {
+	resetAccountsState(t)
+	user, err := CreateAccount("erin", "Strong-password1")
+	if err != nil {
+		t.Fatalf("create account: %v", err)
+	}
+	live, err := CreateSession(user.UUID, 3600, "ua", "127.0.0.1", "password")
+	if err != nil {
+		t.Fatalf("create live session: %v", err)
+	}
+	stale, err := CreateSession(user.UUID, -1, "ua", "127.0.0.1", "password")
+	if err != nil {
+		t.Fatalf("create stale session: %v", err)
+	}
+
+	if err := RemoveExpiredSessions(); err != nil {
+		t.Fatalf("remove expired sessions: %v", err)
+	}
+	if _, err := GetSession(live); err != nil {
+		t.Fatalf("live session was removed: %v", err)
+	}
+	if _, err := GetSession(stale); err == nil {
+		t.Fatal("stale session survived the janitor")
+	}
+}
+
+// TestUpdateUserRotatesPasswordAndDropsSessions pins the rule that changing a
+// password invalidates every existing session.
+func TestUpdateUserRotatesPasswordAndDropsSessions(t *testing.T) {
+	resetAccountsState(t)
+	user, err := CreateAccount("frank", "Strong-password1")
+	if err != nil {
+		t.Fatalf("create account: %v", err)
+	}
+	session, err := CreateSession(user.UUID, 3600, "ua", "127.0.0.1", "password")
+	if err != nil {
+		t.Fatalf("create session: %v", err)
+	}
+
+	newPassword := "Rotated-password1"
+	if err := UpdateUser(user.UUID, nil, &newPassword, nil); err != nil {
+		t.Fatalf("update user: %v", err)
+	}
+	if _, err := GetSession(session); err == nil {
+		t.Fatal("session survived a password rotation")
+	}
+	if _, ok := CheckPassword("frank", newPassword); !ok {
+		t.Fatal("rotated password does not work")
+	}
+	if err := UpdateUser("missing-uuid", nil, &newPassword, nil); err == nil {
+		t.Fatal("updating a missing user should fail")
+	}
+}
+
+// TestTwoFactorLifecycle covers enable, verify and disable.
+func TestTwoFactorLifecycle(t *testing.T) {
+	resetAccountsState(t)
+	user, err := CreateAccount("grace", "Strong-password1")
+	if err != nil {
+		t.Fatalf("create account: %v", err)
+	}
+
+	// Without a secret, verification must fail closed.
+	if ok, err := Verify2Fa(user.UUID, "123456"); err != nil || ok {
+		t.Fatalf("Verify2Fa before enabling = %v, %v; want false, nil", ok, err)
+	}
+
+	secret, img, err := Generate2Fa()
+	if err != nil {
+		t.Fatalf("generate 2fa: %v", err)
+	}
+	if secret == "" || img == nil {
+		t.Fatal("Generate2Fa returned an empty secret or image")
+	}
+	if err := Enable2Fa(user.UUID, secret); err != nil {
+		t.Fatalf("enable 2fa: %v", err)
+	}
+
+	code, err := totp.GenerateCode(secret, time.Now())
+	if err != nil {
+		t.Fatalf("generate totp code: %v", err)
+	}
+	if ok, err := Verify2Fa(user.UUID, code); err != nil || !ok {
+		t.Fatalf("Verify2Fa with a valid code = %v, %v; want true, nil", ok, err)
+	}
+	if ok, err := Verify2Fa(user.UUID, "000000"); err != nil || ok {
+		t.Fatalf("Verify2Fa with a wrong code = %v, %v; want false, nil", ok, err)
+	}
+
+	if err := Disable2Fa(user.UUID); err != nil {
+		t.Fatalf("disable 2fa: %v", err)
+	}
+	if ok, err := Verify2Fa(user.UUID, code); err != nil || ok {
+		t.Fatalf("Verify2Fa after disabling = %v, %v; want false, nil", ok, err)
+	}
+}
+
+// TestVerify2FaUnknownUserIsAnError distinguishes "no such user" from "wrong
+// code" so callers do not silently treat a lookup failure as a pass.
+func TestVerify2FaUnknownUserIsAnError(t *testing.T) {
+	resetAccountsState(t)
+	if _, err := Verify2Fa("missing-uuid", "123456"); err == nil {
+		t.Fatal("Verify2Fa for a missing user should return an error")
+	}
+}

database/accounts/main_test.go

@@ -0,0 +1,47 @@
+package accounts
+
+import (
+	"os"
+	"testing"
+
+	"github.com/komari-monitor/komari/cmd/flags"
+	"github.com/komari-monitor/komari/database/dbcore"
+	"github.com/komari-monitor/komari/database/models"
+)
+
+// TestMain wires a shared in-memory SQLite database for the accounts tests.
+func TestMain(m *testing.M) {
+	flags.DatabaseType = flags.DatabaseTypeSQLite
+	flags.DatabaseFile = "file:komari_accounts_test?mode=memory&cache=shared"
+	db := dbcore.GetDBInstance()
+	if sqlDB, err := db.DB(); err == nil {
+		sqlDB.SetMaxOpenConns(1)
+	}
+	os.Exit(m.Run())
+}
+
+// resetAccountsState clears users and sessions so each test starts clean.
+func resetAccountsState(t *testing.T) {
+	t.Helper()
+	clear := func() {
+		db := dbcore.GetDBInstance()
+		if err := db.Where("1 = 1").Delete(&models.User{}).Error; err != nil {
+			t.Fatalf("clear users: %v", err)
+		}
+		if err := db.Where("1 = 1").Delete(&models.Session{}).Error; err != nil {
+			t.Fatalf("clear sessions: %v", err)
+		}
+	}
+	clear()
+	t.Cleanup(clear)
+}
+
+// countSessions returns how many session rows match the query.
+func countSessions(t *testing.T, query string, args ...any) int64 {
+	t.Helper()
+	var count int64
+	if err := dbcore.GetDBInstance().Model(&models.Session{}).Where(query, args...).Count(&count).Error; err != nil {
+		t.Fatalf("count sessions: %v", err)
+	}
+	return count
+}

database/accounts/sessions.go

@@ -9,20 +9,17 @@ import (
 	"github.com/komari-monitor/komari/database/dbcore"
 	"github.com/komari-monitor/komari/database/models"
 	messageevent "github.com/komari-monitor/komari/database/models/messageEvent"
-	"github.com/komari-monitor/komari/pkg/config"
+	"github.com/komari-monitor/komari/internal/config"
 	"github.com/komari-monitor/komari/utils"
 	"github.com/komari-monitor/komari/utils/geoip"
 	"github.com/komari-monitor/komari/utils/messageSender"
 )
 
 // GetAllSessions 获取所有会话
-func GetAllSessions() (sessions []models.Session, err error) {
+func GetAllSessions() ([]models.Session, error) {
 	db := dbcore.GetDBInstance()
-	err = db.Find(&sessions).Error
-	if err != nil {
-		return nil, err
-	}
-	return sessions, nil
+	var sessions []models.Session
+	return sessions, db.Find(&sessions).Error
 }
 
 // CreateSession 创建新会话
@@ -33,11 +30,11 @@ func CreateSession(uuid string, expires int, userAgent, ip, login_method string)
 	sessionRecord := models.Session{
 		UUID:         uuid,
 		Session:      session,
-		Expires:      models.FromTime(time.Now().Add(time.Duration(expires) * time.Second)),
+		Expires:      time.Now().UTC().Add(time.Duration(expires) * time.Second),
 		UserAgent:    userAgent,
 		Ip:           ip,
 		LoginMethod:  login_method,
-		LatestOnline: models.FromTime(time.Now()),
+		LatestOnline: time.Now().UTC(),
 	}
 	go func() {
 		LoginNotification, _ := config.GetAs[bool](config.LoginNotificationKey, false)
@@ -48,32 +45,27 @@ func CreateSession(uuid string, expires int, userAgent, ip, login_method string)
 			if ipinfo != nil && ipinfo.Name != "" {
 				loc = ipinfo.Name
 			}
-			messageSender.SendEvent(models.EventMessage{
+			_ = messageSender.SendNotification(models.EventMessage{
 				Event:   messageevent.Login,
-				Time:    time.Now(),
+				Time:    time.Now().UTC(),
 				Message: fmt.Sprintf("%s: %s (%s)\n%s", login_method, ip, loc, userAgent),
 				Emoji:   "🔑",
 			})
 		}
 	}()
 
-	err := db.Create(&sessionRecord).Error
-	if err != nil {
-		return "", err
-	}
-	return session, nil
+	return session, db.Create(&sessionRecord).Error
 }
 
 // GetSession 根据会话 ID 获取 UUID
-func GetSession(session string) (uuid string, err error) {
+func GetSession(session string) (string, error) {
 	db := dbcore.GetDBInstance()
 	var sessionRecord models.Session
-	err = db.Where("session = ?", session).First(&sessionRecord).Error
-	if err != nil {
+	if err := db.Where("session = ?", session).First(&sessionRecord).Error; err != nil {
 		return "", err
 	}
 
-	if time.Now().After(sessionRecord.Expires.ToTime()) {
+	if time.Now().UTC().After(sessionRecord.Expires) {
 		// 会话已过期，删除它
 		_ = DeleteSession(session)
 		return "", errors.New("session expired")
@@ -83,52 +75,28 @@ func GetSession(session string) (uuid string, err error) {
 }
 
 func GetUserBySession(session string) (models.User, error) {
-	db := dbcore.GetDBInstance()
 	var sessionRecord models.Session
-	err := db.Where("session = ?", session).First(&sessionRecord).Error
-	if err != nil {
+	if err := dbcore.GetDBInstance().Where("session = ?", session).First(&sessionRecord).Error; err != nil {
 		return models.User{}, err
 	}
 	return GetUserByUUID(sessionRecord.UUID)
 }
 
 // DeleteSession 删除指定会话
-func DeleteSession(session string) (err error) {
+func DeleteSession(session string) error {
 	db := dbcore.GetDBInstance()
-	result := db.Where("session = ?", session).Delete(&models.Session{})
-	if result.Error != nil {
-		return result.Error
-	}
-	return nil
+	return db.Where("session = ?", session).Delete(&models.Session{}).Error
 }
 
 func DeleteAllSessions() error {
 	db := dbcore.GetDBInstance()
-	result := db.Where("1 = 1").Delete(&models.Session{})
-	if result.Error != nil {
-		return result.Error
-	}
-	return nil
-}
-
-func UpdateLatestOnline(session string) error {
-	db := dbcore.GetDBInstance()
-	return db.Model(&models.Session{}).Where("session = ?", session).Update("latest_online", time.Now()).Error
-}
-
-func UpdateLatestUserAgent(session, userAgent string) error {
-	db := dbcore.GetDBInstance()
-	return db.Model(&models.Session{}).Where("session = ?", session).Update("latest_user_agent", userAgent).Error
-}
-func UpdateLatestIp(session, ip string) error {
-	db := dbcore.GetDBInstance()
-	return db.Model(&models.Session{}).Where("session = ?", session).Update("latest_ip", ip).Error
+	return db.Where("1 = 1").Delete(&models.Session{}).Error
 }
 
 func UpdateLatest(session, useragent, ip string) error {
 	db := dbcore.GetDBInstance()
 	return db.Model(&models.Session{}).Where("session = ?", session).Updates(map[string]interface{}{
-		"latest_online":     time.Now(),
+		"latest_online":     time.Now().UTC(),
 		"latest_user_agent": useragent,
 		"latest_ip":         ip,
 	}).Error
@@ -136,9 +104,5 @@ func UpdateLatest(session, useragent, ip string) error {
 
 func RemoveExpiredSessions() error {
 	db := dbcore.GetDBInstance()
-	result := db.Where("expires < ?", time.Now()).Delete(&models.Session{})
-	if result.Error != nil {
-		return result.Error
-	}
-	return nil
+	return db.Where("expires < ?", time.Now().UTC()).Delete(&models.Session{}).Error
 }

database/auditlog/log.go

@@ -1,7 +1,7 @@
 package auditlog
 
 import (
-	"log"
+	logger "github.com/komari-monitor/komari/utils/log"
 	"time"
 
 	"github.com/komari-monitor/komari/database/dbcore"
@@ -9,16 +9,17 @@ import (
 )
 
 func Log(ip, uuid, message, msgType string) {
-	now := time.Now()
 	db := dbcore.GetDBInstance()
 	logEntry := &models.Log{
 		IP:      ip,
 		UUID:    uuid,
 		Message: message,
 		MsgType: msgType,
-		Time:    models.FromTime(now),
+		Time:    time.Now().UTC(),
+	}
+	if err := db.Create(logEntry).Error; err != nil {
+		logger.Error("audit", "failed to persist audit event", "error", err, "type", msgType)
 	}
-	db.Create(logEntry)
 }
 
 func EventLog(eventType, message string) {
@@ -28,8 +29,8 @@ func EventLog(eventType, message string) {
 // Delete logs older than 30 days
 func RemoveOldLogs() {
 	db := dbcore.GetDBInstance()
-	threshold := time.Now().AddDate(0, 0, -30)
+	threshold := time.Now().UTC().AddDate(0, 0, -30)
 	if err := db.Where("time < ?", threshold).Delete(&models.Log{}).Error; err != nil {
-		log.Println("Failed to remove old logs:", err)
+		logger.ErrorArgs("audit", "Failed to remove old logs:", err)
 	}
 }

database/clients/client.go

@@ -3,7 +3,7 @@ package clients
 import (
 	"encoding/json"
 	"fmt"
-	"log"
+	logger "github.com/komari-monitor/komari/utils/log"
 	"math"
 	"time"
 
@@ -11,18 +11,12 @@ import (
 	"github.com/komari-monitor/komari/database/models"
 	"github.com/komari-monitor/komari/database/tasks"
 	"github.com/komari-monitor/komari/utils"
-	"gorm.io/gorm"
 
 	"github.com/google/uuid"
 )
 
 func DeleteClient(clientUuid string) error {
-	db := dbcore.GetDBInstance()
-	err := db.Delete(&models.Client{}, "uuid = ?", clientUuid).Error
-	if err != nil {
-		return err
-	}
-	return nil
+	return dbcore.GetDBInstance().Delete(&models.Client{}, "uuid = ?", clientUuid).Error
 }
 
 func SaveClientInfo(update map[string]interface{}) error {
@@ -32,12 +26,7 @@ func SaveClientInfo(update map[string]interface{}) error {
 		return fmt.Errorf("invalid client UUID")
 	}
 
-	// 确保更新的字段不为空
-	if len(update) == 0 {
-		return fmt.Errorf("no fields to update")
-	}
-
-	update["updated_at"] = time.Now()
+	update["updated_at"] = time.Now().UTC()
 
 	toFloat64 := func(value interface{}) (float64, bool) {
 		switch typed := value.(type) {
@@ -115,29 +104,7 @@ func SaveClientInfo(update map[string]interface{}) error {
 		return err
 	}
 
-	err := db.Model(&models.Client{}).Where("uuid = ?", clientUUID).Updates(update).Error
-	if err != nil {
-		return err
-	}
-	return nil
-}
-
-func EditClientName(clientUUID, clientName string) error {
-	db := dbcore.GetDBInstance()
-	err := db.Model(&models.Client{}).Where("uuid = ?", clientUUID).Update("name", clientName).Error
-	if err != nil {
-		return err
-	}
-	return nil
-}
-
-func EditClientToken(clientUUID, token string) error {
-	db := dbcore.GetDBInstance()
-	err := db.Model(&models.Client{}).Where("uuid = ?", clientUUID).Update("token", token).Error
-	if err != nil {
-		return err
-	}
-	return nil
+	return db.Model(&models.Client{}).Where("uuid = ?", clientUUID).Updates(update).Error
 }
 
 // CreateClient 创建新客户端
@@ -150,16 +117,15 @@ func CreateClient() (clientUUID, token string, err error) {
 		UUID:      clientUUID,
 		Token:     token,
 		Name:      "client_" + clientUUID[0:8],
-		CreatedAt: models.FromTime(time.Now()),
-		UpdatedAt: models.FromTime(time.Now()),
+		CreatedAt: time.Now().UTC(),
+		UpdatedAt: time.Now().UTC(),
 	}
 
-	err = db.Create(&client).Error
-	if err != nil {
+	if err := db.Create(&client).Error; err != nil {
 		return "", "", err
 	}
 	if err := tasks.AddDefaultOnClientUUID(clientUUID); err != nil {
-		log.Println("Failed to apply default-on ping tasks to new client:", err)
+		logger.ErrorArgs("clients", "Failed to apply default-on ping tasks to new client:", err)
 	}
 	return clientUUID, token, nil
 }
@@ -175,68 +141,38 @@ func CreateClientWithName(name string) (clientUUID, token string, err error) {
 		UUID:      clientUUID,
 		Token:     token,
 		Name:      name,
-		CreatedAt: models.FromTime(time.Now()),
-		UpdatedAt: models.FromTime(time.Now()),
+		CreatedAt: time.Now().UTC(),
+		UpdatedAt: time.Now().UTC(),
 	}
 
-	err = db.Create(&client).Error
-	if err != nil {
+	if err := db.Create(&client).Error; err != nil {
 		return "", "", err
 	}
 	if err := tasks.AddDefaultOnClientUUID(clientUUID); err != nil {
-		log.Println("Failed to apply default-on ping tasks to new client:", err)
+		logger.ErrorArgs("clients", "Failed to apply default-on ping tasks to new client:", err)
 	}
 	return clientUUID, token, nil
 }
 
-/*
-// GetAllClients 获取所有客户端配置
-
-	func getAllClients() (clients []models.Client, err error) {
-		db := dbcore.GetDBInstance()
-		err = db.Find(&clients).Error
-		if err != nil {
-			return nil, err
-		}
-		return clients, nil
-	}
-*/
-func GetClientByUUID(uuid string) (client models.Client, err error) {
-	db := dbcore.GetDBInstance()
-	err = db.Where("uuid = ?", uuid).First(&client).Error
-	if err != nil {
-		return models.Client{}, err
-	}
-	return client, nil
-}
-
-// GetClientBasicInfo 获取指定 UUID 的客户端基本信息
-func GetClientBasicInfo(uuid string) (client models.Client, err error) {
-	db := dbcore.GetDBInstance()
-	err = db.Where("uuid = ?", uuid).First(&client).Error
-	if err != nil {
-		if err == gorm.ErrRecordNotFound {
-			return models.Client{}, fmt.Errorf("客户端不存在: %s", uuid)
-		}
-		return models.Client{}, err
-	}
-	return client, nil
-}
-
-func GetClientTokenByUUID(uuid string) (token string, err error) {
-	db := dbcore.GetDBInstance()
+func GetClientByUUID(uuid string) (models.Client, error) {
 	var client models.Client
-	err = db.Where("uuid = ?", uuid).First(&client).Error
-	if err != nil {
+	if err := dbcore.GetDBInstance().Where("uuid = ?", uuid).First(&client).Error; err != nil {
+		return models.Client{}, err
+	}
+	return client, nil
+}
+
+func GetClientTokenByUUID(uuid string) (string, error) {
+	var client models.Client
+	if err := dbcore.GetDBInstance().Where("uuid = ?", uuid).First(&client).Error; err != nil {
 		return "", err
 	}
 	return client.Token, nil
 }
 
-func GetAllClientBasicInfo() (clients []models.Client, err error) {
-	db := dbcore.GetDBInstance()
-	err = db.Find(&clients).Error
-	if err != nil {
+func GetAllClientBasicInfo() ([]models.Client, error) {
+	var clients []models.Client
+	if err := dbcore.GetDBInstance().Find(&clients).Error; err != nil {
 		return nil, err
 	}
 	return clients, nil
@@ -249,11 +185,6 @@ func SaveClient(updates map[string]interface{}) error {
 		return fmt.Errorf("invalid client UUID")
 	}
 
-	// 确保更新的字段不为空
-	if len(updates) == 0 {
-		return fmt.Errorf("no fields to update")
-	}
-
 	if v, exists := updates["traffic_limit"]; exists {
 		if val, ok := v.(float64); ok {
 			if val < 0 || val > math.MaxInt64-1 {
@@ -261,12 +192,30 @@ func SaveClient(updates map[string]interface{}) error {
 			}
 		}
 	}
-
-	updates["updated_at"] = time.Now()
-
-	err := db.Model(&models.Client{}).Where("uuid = ?", clientUUID).Updates(updates).Error
-	if err != nil {
-		return err
+	if value, exists := updates["expired_at"]; exists {
+		switch typed := value.(type) {
+		case nil:
+			updates["expired_at"] = nil
+		case time.Time:
+			updates["expired_at"] = typed.UTC()
+		case *time.Time:
+			if typed == nil {
+				updates["expired_at"] = nil
+			} else {
+				updates["expired_at"] = typed.UTC()
+			}
+		case string:
+			stamp, err := time.Parse(time.RFC3339Nano, typed)
+			if err != nil {
+				return fmt.Errorf("expired_at must be an RFC3339 timestamp with a timezone: %w", err)
+			}
+			updates["expired_at"] = stamp.UTC()
+		default:
+			return fmt.Errorf("expired_at must be an RFC3339 timestamp with a timezone")
+		}
 	}
-	return nil
+
+	updates["updated_at"] = time.Now().UTC()
+
+	return db.Model(&models.Client{}).Where("uuid = ?", clientUUID).Updates(updates).Error
 }

database/clients/report.go

@@ -1,101 +1,24 @@
 package clients
 
 import (
-	"encoding/json"
-	"errors"
 	"fmt"
 	"math"
-	"sync"
-	"time"
 
 	"github.com/komari-monitor/komari/database/dbcore"
 	"github.com/komari-monitor/komari/database/models"
-	v1 "github.com/komari-monitor/komari/protocol/v1"
-
-	"gorm.io/gorm"
+	v2 "github.com/komari-monitor/komari/protocol/v2"
 )
 
-var reportSaveLocks sync.Map
-
-func getReportSaveLock(clientUUID string) *sync.Mutex {
-	lock, _ := reportSaveLocks.LoadOrStore(clientUUID, &sync.Mutex{})
-	return lock.(*sync.Mutex)
-}
-
-func computeTrafficDelta(current, previous int64) int64 {
-	if previous < 0 {
-		return 0
-	}
-	if current >= previous {
-		return current - previous
-	}
-	// Counter reset or reboot: treat the new counter value as traffic since reset.
-	return current
-}
-
-func getLatestTrafficRecord(tx *gorm.DB, clientUUID string) (*models.Record, error) {
-	var record models.Record
-	err := tx.Where("client = ?", clientUUID).Order("time DESC").First(&record).Error
-	if err == nil {
-		return &record, nil
-	}
-	if !errors.Is(err, gorm.ErrRecordNotFound) {
-		return nil, err
-	}
-
-	err = tx.Table("records_long_term").Where("client = ?", clientUUID).Order("time DESC").First(&record).Error
-	if err == nil {
-		return &record, nil
-	}
-	if !errors.Is(err, gorm.ErrRecordNotFound) {
-		return nil, err
-	}
-
-	return nil, nil
-}
-
-// Report 表示客户端报告数据
-// SaveReport 保存报告数据
-func SaveReport(uuid string, data map[string]interface{}) (err error) {
-
-	report, err := ParseReport(data)
-	if err != nil {
-		return err
-	}
-	err = SaveClientReport(uuid, report)
-	if err != nil {
-
-		return err
-	}
-	return nil
-
-}
-
-func GetClientUUIDByToken(token string) (clientUUID string, err error) {
-	db := dbcore.GetDBInstance()
+func GetClientUUIDByToken(token string) (string, error) {
 	var client models.Client
-	err = db.Where("token = ?", token).First(&client).Error
-	if err != nil {
+	if err := dbcore.GetDBInstance().Where("token = ?", token).First(&client).Error; err != nil {
 		return "", err
 	}
 	return client.UUID, nil
 }
 
-func ParseReport(data map[string]interface{}) (report v1.Report, err error) {
-	jsonData, err := json.Marshal(data)
-	if err != nil {
-		return v1.Report{}, err
-	}
-	err = json.Unmarshal(jsonData, &report)
-	if err != nil {
-		return v1.Report{}, err
-	}
-	return report, nil
-}
-
-// 检查数据防止异常数据导致数据库损坏
-func ReportVerify(report v1.Report) error {
-	// 防止输入不合理范围
+// ReportVerify 检查上报数据，防止异常数据导致数据库损坏
+func ReportVerify(report v2.Report) error {
 	if report.CPU.Usage < 0 || report.CPU.Usage > 100 {
 		return fmt.Errorf("CPU.Usage must be between 0 and 100")
 	}
@@ -130,28 +53,24 @@ func ReportVerify(report v1.Report) error {
 	}
 
 	// [int64] 防止数据溢出
-	// Ram 验证
 	if err := checkInt64("Ram.Used", report.Ram.Used); err != nil {
 		return err
 	}
 	if err := checkInt64("Ram.Total", report.Ram.Total); err != nil {
 		return err
 	}
-	// Swap 验证
 	if err := checkInt64("Swap.Used", report.Swap.Used); err != nil {
 		return err
 	}
 	if err := checkInt64("Swap.Total", report.Swap.Total); err != nil {
 		return err
 	}
-	// Disk 验证
 	if err := checkInt64("Disk.Used", report.Disk.Used); err != nil {
 		return err
 	}
 	if err := checkInt64("Disk.Total", report.Disk.Total); err != nil {
 		return err
 	}
-	// Network 验证
 	if err := checkInt64("Network.Up", report.Network.Up); err != nil {
 		return err
 	}
@@ -164,7 +83,7 @@ func ReportVerify(report v1.Report) error {
 	if err := checkInt64("Network.TotalDown", report.Network.TotalDown); err != nil {
 		return err
 	}
-	// 拒绝所有负数Int
+	// 拒绝所有负数 Int
 	if report.Process < 0 {
 		return fmt.Errorf("Process must be non-negative: %d", report.Process)
 	}
@@ -176,132 +95,3 @@ func ReportVerify(report v1.Report) error {
 	}
 	return nil
 }
-
-// SaveClientReport 保存客户端报告到 Record 表
-func SaveClientReport(clientUUID string, report v1.Report) (err error) {
-	db := dbcore.GetDBInstance()
-	lock := getReportSaveLock(clientUUID)
-	lock.Lock()
-	defer lock.Unlock()
-
-	if err := ReportVerify(report); err != nil {
-		return fmt.Errorf("failed to save Record: %w", err)
-	}
-
-	// 保存GPU详细记录到独立表
-	currentTime := time.Now()
-	if report.GPU != nil && len(report.GPU.DetailedInfo) > 0 {
-		for idx, gpu := range report.GPU.DetailedInfo {
-			gpuRecord := models.GPURecord{
-				Client:      clientUUID,
-				Time:        models.FromTime(currentTime),
-				DeviceIndex: idx,
-				DeviceName:  gpu.Name,
-				MemTotal:    gpu.MemoryTotal,
-				MemUsed:     gpu.MemoryUsed,
-				Utilization: float32(gpu.Utilization),
-				Temperature: gpu.Temperature,
-			}
-			if err := db.Create(&gpuRecord).Error; err != nil {
-				return fmt.Errorf("failed to save GPU record: %w", err)
-			}
-		}
-	}
-
-	// 计算平均GPU使用率，用于向后兼容
-	averageGPUUsage := float32(0)
-	if report.GPU != nil && len(report.GPU.DetailedInfo) > 0 {
-		averageGPUUsage = float32(report.GPU.AverageUsage)
-	}
-
-	Record := models.Record{
-		Client:         clientUUID,
-		Time:           models.FromTime(currentTime),
-		Cpu:            float32(report.CPU.Usage),
-		Gpu:            averageGPUUsage, // 使用平均GPU使用率
-		Ram:            report.Ram.Used,
-		RamTotal:       report.Ram.Total,
-		Swap:           report.Swap.Used,
-		SwapTotal:      report.Swap.Total,
-		Load:           float32(report.Load.Load1), // 使用 Load1 作为主要负载指标
-		Temp:           0,                          // Report 未提供 TEMP，设为 0（与原 nil 行为类似）
-		Disk:           report.Disk.Used,
-		DiskTotal:      report.Disk.Total,
-		NetIn:          report.Network.Down,
-		NetOut:         report.Network.Up,
-		NetTotalUp:     report.Network.TotalUp,
-		NetTotalDown:   report.Network.TotalDown,
-		TrafficUp:      0,
-		TrafficDown:    0,
-		Process:        report.Process,
-		Connections:    report.Connections.TCP,
-		ConnectionsUdp: report.Connections.UDP,
-		//Uptime:         report.Uptime,
-	}
-
-	// 使用事务确保 Record 和 ClientsInfo 一致性
-	err = db.Transaction(func(tx *gorm.DB) error {
-		previous, err := getLatestTrafficRecord(tx, clientUUID)
-		if err != nil {
-			return fmt.Errorf("failed to load previous Record: %w", err)
-		}
-		if previous != nil {
-			Record.TrafficUp = computeTrafficDelta(report.Network.TotalUp, previous.NetTotalUp)
-			Record.TrafficDown = computeTrafficDelta(report.Network.TotalDown, previous.NetTotalDown)
-		}
-
-		// 保存 Record
-		if err := tx.Create(&Record).Error; err != nil {
-			return fmt.Errorf("failed to save Record: %w", err)
-		}
-		return nil
-	})
-
-	if err != nil {
-		return err
-	}
-
-	return nil
-}
-
-/*
-// getString 从 map 中获取字符串
-func getString(data map[string]interface{}, key string) string {
-	if val, ok := data[key]; ok {
-		if str, ok := val.(string); ok {
-			return str
-		}
-	}
-	return ""
-}
-
-// getInt 从 map 中获取整数
-func getInt(data map[string]interface{}, key string) int {
-	if val, ok := data[key]; ok {
-		if num, ok := val.(float64); ok {
-			return int(num)
-		}
-	}
-	return 0
-}
-
-// getInt64 从 map 中获取 int64
-func getInt64(data map[string]interface{}, key string) int64 {
-	if val, ok := data[key]; ok {
-		if num, ok := val.(float64); ok {
-			return int64(num)
-		}
-	}
-	return 0
-}
-
-// getFloat 从 map 中获取 float64
-func getFloat(data map[string]interface{}, key string) float64 {
-	if val, ok := data[key]; ok {
-		if num, ok := val.(float64); ok {
-			return num
-		}
-	}
-	return 0.0
-}
-*/

database/clients/report_test.go

@@ -1,82 +0,0 @@
-package clients
-
-import (
-	"sync"
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/assert"
-)
-
-func TestComputeTrafficDeltaHandlesZeroAndReset(t *testing.T) {
-	tests := []struct {
-		name     string
-		current  int64
-		previous int64
-		want     int64
-	}{
-		{name: "previous zero counts current delta", current: 120, previous: 0, want: 120},
-		{name: "monotonic counter uses difference", current: 250, previous: 200, want: 50},
-		{name: "counter reset uses current", current: 15, previous: 250, want: 15},
-		{name: "negative previous remains guarded", current: 15, previous: -1, want: 0},
-	}
-
-	for _, test := range tests {
-		t.Run(test.name, func(t *testing.T) {
-			assert.Equal(t, test.want, computeTrafficDelta(test.current, test.previous))
-		})
-	}
-}
-
-func TestReportSaveLockSerializesSameClient(t *testing.T) {
-	clientUUID := "client-lock-same"
-	lock := getReportSaveLock(clientUUID)
-	lock.Lock()
-	defer lock.Unlock()
-
-	acquired := make(chan struct{})
-	go func() {
-		secondLock := getReportSaveLock(clientUUID)
-		secondLock.Lock()
-		defer secondLock.Unlock()
-		close(acquired)
-	}()
-
-	select {
-	case <-acquired:
-		t.Fatal("same-client report save lock was acquired while already held")
-	case <-time.After(20 * time.Millisecond):
-	}
-
-	lock.Unlock()
-	select {
-	case <-acquired:
-	case <-time.After(time.Second):
-		t.Fatal("same-client report save lock was not released")
-	}
-	lock.Lock()
-}
-
-func TestReportSaveLockAllowsDifferentClients(t *testing.T) {
-	firstLock := getReportSaveLock("client-lock-a")
-	firstLock.Lock()
-	defer firstLock.Unlock()
-
-	var waitGroup sync.WaitGroup
-	waitGroup.Add(1)
-	acquired := make(chan struct{})
-	go func() {
-		defer waitGroup.Done()
-		secondLock := getReportSaveLock("client-lock-b")
-		secondLock.Lock()
-		defer secondLock.Unlock()
-		close(acquired)
-	}()
-
-	select {
-	case <-acquired:
-	case <-time.After(time.Second):
-		t.Fatal("different-client report save lock should not block")
-	}
-	waitGroup.Wait()
-}

database/clipboard/clipboard.go

@@ -1,58 +0,0 @@
-package clipboard
-
-import (
-	"github.com/komari-monitor/komari/database/dbcore"
-	"github.com/komari-monitor/komari/database/models"
-)
-
-// CreateClipboard 创建剪贴板记录
-func CreateClipboard(cb *models.Clipboard) error {
-	db := dbcore.GetDBInstance()
-	return db.Create(cb).Error
-}
-
-// GetClipboardByID 根据ID获取剪贴板记录
-func GetClipboardByID(id int) (*models.Clipboard, error) {
-	var cb models.Clipboard
-	db := dbcore.GetDBInstance()
-	if err := db.First(&cb, id).Error; err != nil {
-		return nil, err
-	}
-	return &cb, nil
-}
-
-// UpdateClipboardFields 更新剪贴板记录
-func UpdateClipboardFields(id int, fields map[string]interface{}) error {
-	db := dbcore.GetDBInstance()
-	return db.Model(&models.Clipboard{}).Where("id = ?", id).Updates(fields).Error
-}
-
-// DeleteClipboard 删除剪贴板记录
-func DeleteClipboard(id int) error {
-	db := dbcore.GetDBInstance()
-	// Check if record exists first
-	var cb models.Clipboard
-	if err := db.First(&cb, id).Error; err != nil {
-		return err // Record not found or other error
-	}
-	return db.Delete(&cb).Error
-}
-
-// DeleteClipboardBatch 批量删除剪贴板记录
-func DeleteClipboardBatch(ids []int) error {
-	if len(ids) == 0 {
-		return nil
-	}
-	db := dbcore.GetDBInstance()
-	return db.Where("id IN ?", ids).Delete(&models.Clipboard{}).Error
-}
-
-// ListClipboard 列出所有剪贴板记录
-func ListClipboard() ([]models.Clipboard, error) {
-	var list []models.Clipboard
-	db := dbcore.GetDBInstance()
-	if err := db.Find(&list).Error; err != nil {
-		return nil, err
-	}
-	return list, nil
-}

database/dbcore/dbcore.go

@@ -4,7 +4,6 @@ import (
 	"archive/zip"
 	"fmt"
 	"io"
-	"log"
 	"os"
 	"path/filepath"
 	"strings"
@@ -13,9 +12,10 @@ import (
 
 	"github.com/komari-monitor/komari/cmd/flags"
 	"github.com/komari-monitor/komari/database/models"
-	"github.com/komari-monitor/komari/pkg/config"
-	"github.com/komari-monitor/komari/pkg/migrations"
-	logutil "github.com/komari-monitor/komari/utils/log"
+	"github.com/komari-monitor/komari/internal/config"
+	"github.com/komari-monitor/komari/internal/migrations"
+	"github.com/komari-monitor/komari/internal/sqlitetune"
+	logger "github.com/komari-monitor/komari/utils/log"
 	"gorm.io/driver/sqlite"
 	"gorm.io/gorm"
 )
@@ -168,141 +168,320 @@ func unzipToDir(zipPath, dstDir string) error {
 var (
 	instance *gorm.DB
 	once     sync.Once
+	initErr  error
 )
 
-func GetDBInstance() *gorm.DB {
+// SystemVersionKey 是记录“上次启动所用版本标识”的配置键（存于 configs 表）。
+// 取代旧的 ./data/.komari-version 文件：版本标识随配置库一起备份/恢复，
+// 也避免额外的裸文件依赖。
+const SystemVersionKey = "system_version"
+
+const (
+	mainSQLiteBusyTimeout       = 5 * time.Second
+	mainSQLiteCacheSizeKB       = 8 * 1024
+	mainSQLiteWALAutoCheckpoint = 256
+	mainSQLiteJournalSizeLimit  = 1 << 20
+)
+
+// versionID 是当前构建的版本标识，由 SetVersionID 在 Initialize 前注入。
+var versionID string
+
+// nil means a fresh install; an empty value means an unmarked legacy install.
+var lastRunVersion *string
+
+func LastRunVersion() *string {
+	return lastRunVersion
+}
+
+// dbFileExistedAtStartup 记录本次进程启动、打开数据库之前 komari.db 是否已存在，
+// 用于区分“全新安装”与“从旧版升级（无版本标记）”。在 doInitialize 打开数据库
+// 之前采集。
+var dbFileExistedAtStartup bool
+
+// SetVersionID 设置当前构建的版本标识（通常为 CurrentVersion+"-"+VersionHash），
+// 用于版本升级检测与自动备份。应在 Initialize() 之前调用；为空则跳过升级备份。
+func SetVersionID(id string) {
+	versionID = id
+}
+
+// resolveDatabaseFile 返回当前使用的 SQLite 数据库文件路径。
+func resolveDatabaseFile() string {
+	dbFile := flags.DatabaseFile
+	if dbFile == "" {
+		dbFile = "./data/komari.db"
+	}
+	return dbFile
+}
+
+// backupOnVersionUpgrade 在检测到版本升级时，把当前 ./data 打包到
+// ./data/backup/upgrade-{time}.zip，便于升级（含 metrics 迁移）异常时回滚。
+//
+// 版本标识存放于配置库（configs 表，键 system_version），因此本函数必须在
+// config.SetDb 之后、一次性 metrics 迁移（InitStores）之前调用。
+//
+// 触发规则：
+//   - versionID 为空：跳过（未注入版本，如部分测试场景）。
+//   - 配置中无版本且启动前无数据库文件：全新安装，仅写版本，不备份。
+//   - 配置中无版本但启动前已有数据库文件：从无版本标记的旧稳定版升级，备份。
+//   - 配置中版本与当前不同：版本升级，备份。
+//   - 配置中版本与当前一致：无需备份。
+//
+// 备份失败不阻止启动，但打印明确错误；备份成功（或无需备份）后写入/更新版本。
+func backupOnVersionUpgrade() {
+	prevVersion, readErr := config.GetAs[string](SystemVersionKey)
+	prevVersion = strings.TrimSpace(prevVersion)
+	versionRecorded := readErr == nil && prevVersion != ""
+	lastRunVersion = nil
+	if versionRecorded || dbFileExistedAtStartup {
+		lastRunVersion = &prevVersion
+	}
+
+	if versionID == "" {
+		return
+	}
+
+	// 版本未变化，无需备份。
+	if versionRecorded && prevVersion == versionID {
+		return
+	}
+
+	// 全新安装：配置中无版本且启动前无数据库文件，直接写版本不备份。
+	if !versionRecorded && !dbFileExistedAtStartup {
+		writeVersionMarker()
+		return
+	}
+
+	// 需要备份（升级或从旧稳定版首次带版本标记启动）。
+	// 先做一次 WAL checkpoint，确保 komari.db 主文件包含最新数据，
+	// 避免备份出的库缺少仍留在 -wal 中的写入。
+	if instance != nil {
+		instance.Exec("PRAGMA wal_checkpoint(TRUNCATE);")
+	}
+
+	backupDir := filepath.Join(".", "data", "backup")
+	if err := os.MkdirAll(backupDir, 0755); err != nil {
+		logger.Errorf("dbcore", "[upgrade-backup] failed to create backup dir: %v", err)
+		return
+	}
+	tsName := time.Now().UTC().Format("20060102-150405")
+	bakPath := filepath.Join(backupDir, fmt.Sprintf("upgrade-%s.zip", tsName))
+	backupZipPath := filepath.Join(".", "data", "backup.zip")
+	if zipErr := zipDirectoryExcluding("./data", bakPath, map[string]struct{}{backupZipPath: {}, backupDir: {}}); zipErr != nil {
+		logger.Errorf("dbcore", "[upgrade-backup] failed to backup ./data before upgrade (from %q to %q): %v", prevVersion, versionID, zipErr)
+		return
+	}
+	logger.Infof("dbcore", "[upgrade-backup] ./data backed up to %s before upgrade (from %q to %q)", bakPath, prevVersion, versionID)
+
+	writeVersionMarker()
+}
+
+// writeVersionMarker 将当前 versionID 写入配置库。
+func writeVersionMarker() {
+	if err := config.Set(SystemVersionKey, versionID); err != nil {
+		logger.Errorf("dbcore", "[upgrade-backup] failed to persist version marker: %v", err)
+	}
+}
+
+func buildSQLiteDSN(databaseFile string) string {
+	if databaseFile == "" {
+		databaseFile = "./data/komari.db"
+	}
+
+	params := fmt.Sprintf("_busy_timeout=%d&_txlock=immediate", mainSQLiteBusyTimeout.Milliseconds())
+	separator := "?"
+	if strings.Contains(databaseFile, "?") {
+		separator = "&"
+	}
+
+	if strings.HasPrefix(databaseFile, "file:") {
+		return databaseFile + separator + params
+	}
+
+	if databaseFile == ":memory:" {
+		return "file::memory:?cache=shared&" + params
+	}
+
+	return "file:" + filepath.ToSlash(databaseFile) + separator + params
+}
+
+func mainSQLiteOptions() sqlitetune.Options {
+	return sqlitetune.Options{
+		BusyTimeout:           mainSQLiteBusyTimeout,
+		CacheSizeKB:           mainSQLiteCacheSizeKB,
+		MMapSizeBytes:         0,
+		TempStoreMemory:       false,
+		CacheSpill:            true,
+		WALAutoCheckpoint:     mainSQLiteWALAutoCheckpoint,
+		JournalSizeLimitBytes: mainSQLiteJournalSizeLimit,
+		Synchronous:           sqlitetune.SynchronousNormal,
+	}
+}
+
+// Initialize 显式初始化数据库连接与表结构，仅执行一次。
+// 与 GetDBInstance 不同，Initialize 返回错误而非直接退出进程，
+// 便于启动生命周期统一处理错误、以及在测试/CLI 命令中做隔离。
+func Initialize() error {
 	once.Do(func() {
-
-		var err error
-
-		// 在数据库初始化前执行：如果存在 ./data/backup.zip，则进行恢复逻辑
-		func() {
-			backupZipPath := filepath.Join(".", "data", "backup.zip")
-			if _, statErr := os.Stat(backupZipPath); statErr == nil {
-				// 4. 把除了 ./data/backup.zip 之外的所有文件压缩到 ./backup/{time}.zip
-				if err := os.MkdirAll("./backup", 0755); err != nil {
-					log.Printf("[restore] failed to create backup dir: %v", err)
-				} else {
-					tsName := time.Now().Format("20060102-150405")
-					bakPath := filepath.Join("./backup", fmt.Sprintf("%s.zip", tsName))
-					if zipErr := zipDirectoryExcluding("./data", bakPath, map[string]struct{}{backupZipPath: {}}); zipErr != nil {
-						log.Printf("[restore] failed to zip current data: %v", zipErr)
-					} else {
-						log.Printf("[restore] current data zipped to %s", bakPath)
-					}
-				}
-
-				// 5. 删除除了 ./data/backup.zip 之外的所有文件
-				if delErr := removeAllInDirExcept("./data", map[string]struct{}{backupZipPath: {}}); delErr != nil {
-					log.Printf("[restore] failed to cleanup data dir: %v", delErr)
-				}
-
-				// 6. 解压 ./data/backup.zip 到 ./data
-				if unzipErr := unzipToDir(backupZipPath, "./data"); unzipErr != nil {
-					log.Printf("[restore] failed to unzip backup into data: %v", unzipErr)
-				} else {
-					log.Printf("[restore] backup.zip extracted to ./data")
-				}
-
-				// 7. 删除 ./data/backup.zip
-				if rmErr := os.Remove(backupZipPath); rmErr != nil {
-					log.Printf("[restore] failed to remove backup.zip: %v", rmErr)
-				} else {
-					log.Printf("[restore] backup.zip removed")
-				}
-				// 8. 删除标记
-				if rmErr := os.Remove("./data/komari-backup-markup"); rmErr != nil {
-					log.Printf("[restore] failed to remove komari-backup-markup: %v", rmErr)
-				} else {
-					log.Printf("[restore] komari-backup-markup removed")
-				}
-			}
-		}()
-
-		logConfig := &gorm.Config{
-			Logger: logutil.NewGormLogger(),
-		}
-
-		// 根据数据库类型选择不同的连接方式
-		switch flags.ApplyDatabaseTypeNormalization() {
-		case flags.DatabaseTypeSQLite:
-			// SQLite 连接
-			instance, err = gorm.Open(sqlite.Open(flags.DatabaseFile), logConfig)
-			if err != nil {
-				log.Fatalf("Failed to connect to SQLite3 database: %v", err)
-			}
-			log.Printf("Using SQLite database file: %s", flags.DatabaseFile)
-			instance.Exec("PRAGMA wal = ON;")
-			if err := instance.Exec("PRAGMA journal_mode = WAL;").Error; err != nil {
-				log.Printf("Failed to enable WAL mode for SQLite: %v", err)
-			}
-			instance.Exec("PRAGMA synchronous = NORMAL;")
-			instance.Exec("PRAGMA cache_size = -65536;")
-			instance.Exec("PRAGMA temp_store = MEMORY;")
-			instance.Exec("PRAGMA wal_checkpoint(TRUNCATE);")
-		default:
-			log.Fatalf("Unsupported database type: %s (supported: %s)", flags.DatabaseType, flags.SupportedDatabaseTypes())
-		}
-		if err := migrations.Run(migrations.Context{DB: instance}); err != nil {
-			log.Fatalf("Failed to run startup migrations: %v", err)
-		}
-		config.SetDb(instance)
-		// 自动迁移模型
-		err = instance.AutoMigrate(
-			&models.User{},
-			&models.Client{},
-			&models.Record{},
-			&models.GPURecord{},
-			&models.Log{},
-			&models.Clipboard{},
-			&models.LoadNotification{},
-			&models.OfflineNotification{},
-			&models.TrafficReportNotification{},
-			&models.PingRecord{},
-			&models.PingTask{},
-			&models.OidcProvider{},
-			&models.MessageSenderProvider{},
-			&models.ThemeConfiguration{},
-		)
-		if err != nil {
-			log.Fatalf("Failed to create tables: %v", err)
-		}
-		err = instance.Table("records_long_term").AutoMigrate(
-			&models.Record{},
-		)
-		if err != nil {
-			log.Printf("Failed to create records_long_term table, it may already exist: %v", err)
-		}
-		err = instance.Table("gpu_records_long_term").AutoMigrate(
-			&models.GPURecord{},
-		)
-		if err != nil {
-			log.Printf("Failed to create gpu_records_long_term table, it may already exist: %v", err)
-		}
-		err = instance.AutoMigrate(
-			&models.Session{},
-		)
-		if err != nil {
-			log.Printf("Failed to create Session table, it may already exist: %v", err)
-		}
-		err = instance.AutoMigrate(
-			&models.Task{},
-			&models.TaskResult{},
-		)
-		if err != nil {
-			log.Printf("Failed to create Task and TaskResult table, it may already exist: %v", err)
-		}
-
-		// Manually create composite indexes
-		if flags.IsSQLite() {
-			instance.Exec("CREATE INDEX IF NOT EXISTS idx_record_client_time ON records(client, time)")
-			instance.Exec("CREATE INDEX IF NOT EXISTS idx_record_lt_client_time ON records_long_term(client, time)")
-			instance.Exec("CREATE INDEX IF NOT EXISTS idx_gpu_record_client_time ON gpu_records(client, time)")
-			instance.Exec("CREATE INDEX IF NOT EXISTS idx_gpu_record_lt_client_time ON gpu_records_long_term(client, time)")
-			instance.Exec("CREATE INDEX IF NOT EXISTS idx_ping_record_client_time ON ping_records(client, time)")
-		}
-
+		initErr = doInitialize()
 	})
+	return initErr
+}
 
+// GetDBInstance 返回全局数据库实例。
+// 为兼容既有大量调用点，这里保留“出错即退出”的语义；
+// 需要错误处理的启动流程应优先调用 Initialize()。
+func GetDBInstance() *gorm.DB {
+	if err := Initialize(); err != nil {
+		logger.Fatalf("dbcore", "Failed to initialize database: %v", err)
+	}
 	return instance
 }
+
+// Close 关闭底层数据库连接，供关闭流程调用。
+func Close() error {
+	if instance == nil {
+		return nil
+	}
+	sqlDB, err := instance.DB()
+	if err != nil {
+		return err
+	}
+	return sqlDB.Close()
+}
+
+func doInitialize() error {
+	var err error
+
+	// 在数据库初始化前执行：如果存在 ./data/backup.zip，则进行恢复逻辑
+	func() {
+		backupZipPath := filepath.Join(".", "data", "backup.zip")
+		if _, statErr := os.Stat(backupZipPath); statErr == nil {
+			// 4. 将当前数据快照保存到 ./data/backup/，并保留已有归档。
+			backupDir := filepath.Join(".", "data", "backup")
+			if err := os.MkdirAll(backupDir, 0755); err != nil {
+				logger.Errorf("dbcore", "[restore] failed to create backup dir: %v", err)
+			} else {
+				tsName := time.Now().UTC().Format("20060102-150405")
+				bakPath := filepath.Join(backupDir, fmt.Sprintf("pre-restore-%s.zip", tsName))
+				if zipErr := zipDirectoryExcluding("./data", bakPath, map[string]struct{}{backupZipPath: {}, backupDir: {}}); zipErr != nil {
+					logger.Errorf("dbcore", "[restore] failed to zip current data: %v", zipErr)
+				} else {
+					logger.Infof("dbcore", "[restore] current data zipped to %s", bakPath)
+				}
+			}
+
+			// 5. 删除数据文件，但保留归档目录和待恢复的 backup.zip。
+			if delErr := removeAllInDirExcept("./data", map[string]struct{}{backupZipPath: {}, backupDir: {}}); delErr != nil {
+				logger.Errorf("dbcore", "[restore] failed to cleanup data dir: %v", delErr)
+			}
+
+			// 6. 解压 ./data/backup.zip 到 ./data
+			if unzipErr := unzipToDir(backupZipPath, "./data"); unzipErr != nil {
+				logger.Errorf("dbcore", "[restore] failed to unzip backup into data: %v", unzipErr)
+			} else {
+				logger.Infof("dbcore", "[restore] backup.zip extracted to ./data")
+			}
+
+			// 7. 删除 ./data/backup.zip
+			if rmErr := os.Remove(backupZipPath); rmErr != nil {
+				logger.Errorf("dbcore", "[restore] failed to remove backup.zip: %v", rmErr)
+			} else {
+				logger.Infof("dbcore", "[restore] backup.zip removed")
+			}
+			// 8. 删除标记
+			if rmErr := os.Remove("./data/komari-backup-markup"); rmErr != nil {
+				logger.Errorf("dbcore", "[restore] failed to remove komari-backup-markup: %v", rmErr)
+			} else {
+				logger.Infof("dbcore", "[restore] komari-backup-markup removed")
+			}
+		}
+	}()
+
+	// 记录“打开数据库之前”komari.db 是否已存在，用于区分全新安装与旧版升级。
+	// 必须在（可能的）恢复逻辑之后、gorm.Open 之前采集：恢复会解压出旧库，
+	// gorm.Open 会创建空库。
+	if _, statErr := os.Stat(resolveDatabaseFile()); statErr == nil {
+		dbFileExistedAtStartup = true
+	}
+
+	logConfig := &gorm.Config{
+		Logger:  logger.NewGormLogger(),
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	}
+
+	// 根据数据库类型选择不同的连接方式
+	switch flags.ApplyDatabaseTypeNormalization() {
+	case flags.DatabaseTypeSQLite:
+		// _txlock=immediate lets writes acquire their lock before reads can
+		// turn into a lock-upgrade conflict. sqlitetune applies the remaining
+		// per-connection PRAGMAs whenever database/sql opens a connection.
+		dsn := buildSQLiteDSN(flags.DatabaseFile)
+		sqlDB, dbErr := sqlitetune.Open(dsn, mainSQLiteOptions())
+		if dbErr != nil {
+			return fmt.Errorf("open SQLite connection pool: %w", dbErr)
+		}
+		// SQLite has one writer. Keeping exactly one durable connection also
+		// keeps connection-local cache and WAL limits stable for the main DB.
+		sqlDB.SetMaxOpenConns(1)
+		sqlDB.SetMaxIdleConns(1)
+		sqlDB.SetConnMaxLifetime(0)
+		sqlDB.SetConnMaxIdleTime(0)
+
+		instance, err = gorm.Open(sqlite.New(sqlite.Config{Conn: sqlDB}), logConfig)
+		if err != nil {
+			_ = sqlDB.Close()
+			return fmt.Errorf("failed to connect to SQLite3 database: %w", err)
+		}
+		if err := instance.Exec("PRAGMA wal_checkpoint(TRUNCATE)").Error; err != nil {
+			logger.Errorf("dbcore", "Failed to checkpoint SQLite WAL at startup: %v", err)
+		}
+	default:
+		return fmt.Errorf("unsupported database type: %s (supported: %s)", flags.DatabaseType, flags.SupportedDatabaseTypes())
+	}
+	if err := migrations.Run(migrations.Context{DB: instance}); err != nil {
+		return fmt.Errorf("failed to run startup migrations: %w", err)
+	}
+	config.SetDb(instance)
+
+	// 配置库就绪后、执行后续 AutoMigrate 之前：
+	// 基于配置中的版本标记检测升级并自动备份 ./data，便于回滚。
+	backupOnVersionUpgrade()
+
+	// 自动迁移模型
+	//
+	// 注意：负载/GPU/ping 历史监控数据运行期全部走 metric store（默认 SQLite
+	// ./data/metrics.db，或配置的 MySQL/PostgreSQL）。旧的 records /
+	// records_long_term / gpu_records / ping_records 表不再建表、不再写入。
+	// 若升级时旧表仍存在，管理员可通过升级向导显式导入并清理。
+	// models.Record / models.PingRecord / models.GPURecord 结构体仍作为
+	// metric store 的读写 DTO 和旧表导入 DTO 保留在 models 包中。
+	// models.TrafficReportNotification 同样仅为旧数据库兼容保留，不再建表。
+
+	err = instance.AutoMigrate(
+		&models.User{},
+		&models.Client{},
+		&models.Log{},
+		&models.OfflineNotification{},
+		&models.PingTask{},
+		&models.OidcProvider{},
+		&models.MessageSenderProvider{},
+		&models.ThemeConfiguration{},
+		&models.PluginConfiguration{},
+	)
+	if err != nil {
+		return fmt.Errorf("failed to create tables: %w", err)
+	}
+	if err := instance.AutoMigrate(
+		&models.Session{},
+	); err != nil {
+		logger.Errorf("dbcore", "Failed to create Session table, it may already exist: %v", err)
+	}
+	if err := instance.AutoMigrate(
+		&models.Task{},
+		&models.TaskResult{},
+	); err != nil {
+		logger.Errorf("dbcore", "Failed to create Task and TaskResult table, it may already exist: %v", err)
+	}
+
+	return nil
+}

database/dbcore/maintenance.go

@@ -0,0 +1,92 @@
+package dbcore
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"os"
+	"strings"
+	"sync"
+
+	"github.com/komari-monitor/komari/cmd/flags"
+)
+
+var maintenanceMu sync.Mutex
+
+// StorageSize returns the bytes occupied by the main SQLite database and its
+// WAL/SHM sidecar files.
+func StorageSize() (int64, error) {
+	if !flags.IsSQLite() {
+		return 0, errors.New("main database size is only available for SQLite")
+	}
+	return sqliteFileSetSize(resolveDatabaseFile())
+}
+
+// ReclaimSpace checkpoints the main database WAL and rewrites the SQLite file.
+func ReclaimSpace(ctx context.Context) error {
+	if !flags.IsSQLite() {
+		return errors.New("main database maintenance is only supported for SQLite")
+	}
+
+	maintenanceMu.Lock()
+	defer maintenanceMu.Unlock()
+
+	db, err := GetDBInstance().DB()
+	if err != nil {
+		return fmt.Errorf("get main database connection: %w", err)
+	}
+	if err := checkpointSQLiteWAL(ctx, db); err != nil {
+		return err
+	}
+	if _, err := db.ExecContext(ctx, "VACUUM"); err != nil {
+		return fmt.Errorf("vacuum main database: %w", err)
+	}
+	return checkpointSQLiteWAL(ctx, db)
+}
+
+func checkpointSQLiteWAL(ctx context.Context, db *sql.DB) error {
+	var busy, logFrames, checkpointedFrames int
+	if err := db.QueryRowContext(ctx, "PRAGMA wal_checkpoint(TRUNCATE)").Scan(&busy, &logFrames, &checkpointedFrames); err != nil {
+		return fmt.Errorf("checkpoint main database WAL: %w", err)
+	}
+	if busy != 0 {
+		return fmt.Errorf(
+			"checkpoint main database WAL: database is busy (%d log frames, %d checkpointed)",
+			logFrames,
+			checkpointedFrames,
+		)
+	}
+	return nil
+}
+
+func sqliteFileSetSize(dsn string) (int64, error) {
+	path := strings.TrimPrefix(strings.TrimSpace(dsn), "file:")
+	if index := strings.IndexByte(path, '?'); index >= 0 {
+		path = path[:index]
+	}
+	if path == "" || path == ":memory:" || strings.Contains(strings.ToLower(dsn), "mode=memory") {
+		return 0, errors.New("database is not backed by a local file")
+	}
+
+	var total int64
+	foundDatabase := false
+	for _, suffix := range []string{"", "-wal", "-shm"} {
+		info, err := os.Stat(path + suffix)
+		switch {
+		case err == nil:
+			total += info.Size()
+			if suffix == "" {
+				foundDatabase = true
+			}
+		case errors.Is(err, os.ErrNotExist):
+			continue
+		default:
+			return 0, fmt.Errorf("stat database file %q: %w", path+suffix, err)
+		}
+	}
+	if !foundDatabase {
+		return 0, fmt.Errorf("database file %q does not exist", path)
+	}
+	return total, nil
+}

database/dbcore/maintenance_test.go

@@ -0,0 +1,37 @@
+package dbcore
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestSQLiteFileSetSizeIncludesWALAndSHM(t *testing.T) {
+	databasePath := filepath.Join(t.TempDir(), "komari.db")
+	files := map[string]int{
+		databasePath:          11,
+		databasePath + "-wal": 7,
+		databasePath + "-shm": 5,
+	}
+	for path, size := range files {
+		if err := os.WriteFile(path, make([]byte, size), 0o600); err != nil {
+			t.Fatalf("write fixture %s: %v", path, err)
+		}
+	}
+
+	got, err := sqliteFileSetSize("file:" + filepath.ToSlash(databasePath) + "?mode=rwc")
+	if err != nil {
+		t.Fatalf("sqliteFileSetSize: %v", err)
+	}
+	if got != 23 {
+		t.Fatalf("size = %d, want 23", got)
+	}
+}
+
+func TestSQLiteFileSetSizeRejectsNonFileDatabase(t *testing.T) {
+	for _, dsn := range []string{":memory:", "file:metrics?MODE=MEMORY&cache=shared"} {
+		if _, err := sqliteFileSetSize(dsn); err == nil {
+			t.Fatalf("sqliteFileSetSize(%q) should fail", dsn)
+		}
+	}
+}

database/dbcore/sqlite_tuning_test.go

@@ -0,0 +1,99 @@
+package dbcore
+
+import (
+	"database/sql"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/komari-monitor/komari/internal/sqlitetune"
+)
+
+func TestMainSQLiteConnectorAppliesBoundedSettings(t *testing.T) {
+	databasePath := filepath.Join(t.TempDir(), "komari.db")
+	db, err := sqlitetune.Open(buildSQLiteDSN(databasePath), mainSQLiteOptions())
+	if err != nil {
+		t.Fatalf("open SQLite connector: %v", err)
+	}
+	defer db.Close()
+
+	db.SetMaxOpenConns(1)
+	db.SetMaxIdleConns(1)
+
+	if got := sqlitePragmaInt(t, db, "busy_timeout"); got != mainSQLiteBusyTimeout.Milliseconds() {
+		t.Fatalf("busy_timeout = %d, want %d", got, mainSQLiteBusyTimeout.Milliseconds())
+	}
+	if got := sqlitePragmaInt(t, db, "synchronous"); got != 1 {
+		t.Fatalf("synchronous = %d, want NORMAL (1)", got)
+	}
+	if got := sqlitePragmaInt(t, db, "cache_size"); got != -mainSQLiteCacheSizeKB {
+		t.Fatalf("cache_size = %d, want %d", got, -mainSQLiteCacheSizeKB)
+	}
+	if got := sqlitePragmaInt(t, db, "mmap_size"); got != 0 {
+		t.Fatalf("mmap_size = %d, want 0", got)
+	}
+	if got := sqlitePragmaInt(t, db, "temp_store"); got != 1 {
+		t.Fatalf("temp_store = %d, want FILE (1)", got)
+	}
+	if got := sqlitePragmaInt(t, db, "cache_spill"); got == 0 {
+		t.Fatal("cache_spill is disabled")
+	}
+	if got := sqlitePragmaInt(t, db, "wal_autocheckpoint"); got != mainSQLiteWALAutoCheckpoint {
+		t.Fatalf("wal_autocheckpoint = %d, want %d", got, mainSQLiteWALAutoCheckpoint)
+	}
+	if got := sqlitePragmaInt(t, db, "journal_size_limit"); got != mainSQLiteJournalSizeLimit {
+		t.Fatalf("journal_size_limit = %d, want %d", got, mainSQLiteJournalSizeLimit)
+	}
+
+	var journalMode string
+	if err := db.QueryRow("PRAGMA journal_mode").Scan(&journalMode); err != nil {
+		t.Fatalf("read journal_mode: %v", err)
+	}
+	if !strings.EqualFold(journalMode, "wal") {
+		t.Fatalf("journal_mode = %q, want WAL", journalMode)
+	}
+}
+
+func TestMainSQLiteAutoCheckpointKeepsWALBounded(t *testing.T) {
+	databasePath := filepath.Join(t.TempDir(), "komari.db")
+	db, err := sqlitetune.Open(buildSQLiteDSN(databasePath), mainSQLiteOptions())
+	if err != nil {
+		t.Fatalf("open SQLite connector: %v", err)
+	}
+	defer db.Close()
+
+	db.SetMaxOpenConns(1)
+	db.SetMaxIdleConns(1)
+	if _, err := db.Exec("CREATE TABLE checkpoint_test (payload BLOB NOT NULL)"); err != nil {
+		t.Fatalf("create checkpoint test table: %v", err)
+	}
+
+	// This produces well beyond one auto-checkpoint interval. The checkpoint
+	// below reports the WAL frame count observed before its own work begins.
+	for range 1024 {
+		if _, err := db.Exec("INSERT INTO checkpoint_test (payload) VALUES (zeroblob(4096))"); err != nil {
+			t.Fatalf("insert checkpoint test row: %v", err)
+		}
+	}
+
+	var busy, logFrames, checkpointedFrames int
+	if err := db.QueryRow("PRAGMA wal_checkpoint(PASSIVE)").Scan(&busy, &logFrames, &checkpointedFrames); err != nil {
+		t.Fatalf("inspect automatic checkpoint: %v", err)
+	}
+	if busy != 0 {
+		t.Fatalf("automatic checkpoint left a busy WAL: %d", busy)
+	}
+	if logFrames >= 2*mainSQLiteWALAutoCheckpoint {
+		t.Fatalf("WAL retained %d frames after %d-frame auto-checkpoint interval", logFrames, mainSQLiteWALAutoCheckpoint)
+	}
+}
+
+func sqlitePragmaInt(t *testing.T, db *sql.DB, pragma string) int64 {
+	t.Helper()
+
+	var value int64
+	if err := db.QueryRow("PRAGMA " + pragma).Scan(&value); err != nil {
+		t.Fatalf("read %s: %v", pragma, err)
+	}
+	return value
+}

database/messageSender.go

@@ -5,15 +5,6 @@ import (
 	"github.com/komari-monitor/komari/database/models"
 )
 
-func GetAllMessageSenderConfigs() []models.MessageSenderProvider {
-	db := dbcore.GetDBInstance()
-	var result []models.MessageSenderProvider
-	if err := db.Find(&result).Error; err != nil {
-		return nil
-	}
-	return result
-}
-
 func GetMessageSenderConfigByName(name string) (*models.MessageSenderProvider, error) {
 	db := dbcore.GetDBInstance()
 	var config models.MessageSenderProvider

database/models/UTCTime.go

@@ -1,121 +0,0 @@
-package models
-
-import (
-	"database/sql/driver"
-	"fmt"
-	"log"
-	"os"
-	"strings"
-	"sync"
-	"time"
-)
-
-// LocalTime is a custom time type for GORM to handle time.Time correctly.
-// It ensures that all times are stored and retrieved based on the application's configured timezone.
-type LocalTime time.Time
-
-// Value implements the driver.Valuer interface.
-// It converts UTCTime to a TEXT format that the database understands.
-// The time is formatted as a string in the application's local timezone, without timezone information.
-func (t LocalTime) Value() (driver.Value, error) {
-	if time.Time(t).IsZero() {
-		return nil, nil
-	}
-	return time.Time(t).In(GetAppLocation()).Format("2006-01-02 15:04:05.0000000"), nil
-}
-
-// Scan implements the sql.Scanner interface.
-// It scans a value from the database into a UTCTime object.
-func (t *LocalTime) Scan(v interface{}) error {
-	if v == nil {
-		*t = LocalTime(time.Time{})
-		return nil
-	}
-
-	loc := GetAppLocation()
-
-	switch val := v.(type) {
-	case time.Time:
-		// CRITICAL FIX: When the driver reads a timezone-less string (e.g., "16:00:00"),
-		// it often incorrectly assumes it's UTC. We must correct this by re-interpreting
-		// the date and clock values in the application's actual timezone.
-		year, month, day := val.Date()
-		hour, min, sec := val.Clock()
-		nanosec := val.Nanosecond()
-		*t = LocalTime(time.Date(year, month, day, hour, min, sec, nanosec, loc))
-		return nil
-	case []byte:
-		return t.parseTime(string(val), loc)
-	case string:
-		return t.parseTime(val, loc)
-	default:
-		return fmt.Errorf("UTCTime scan source was not string, []byte or time.Time: %T (%v)", v, v)
-	}
-}
-
-// parseTime handles parsing a string into UTCTime.
-func (t *LocalTime) parseTime(timeStr string, loc *time.Location) error {
-	timeStr = strings.TrimSpace(timeStr)
-	if timeStr == "" {
-		*t = LocalTime(time.Time{})
-		return nil
-	}
-
-	layouts := []string{
-		time.RFC3339Nano, time.RFC3339,
-		"2006-01-02 15:04:05.0000000-07:00", "2006-01-02 15:04:05-07:00",
-		"2006-01-02 15:04:05.0000000", "2006-01-02 15:04:05", "2006-01-02",
-	}
-
-	for _, layout := range layouts {
-		if parsedTime, err := time.ParseInLocation(layout, timeStr, loc); err == nil {
-			*t = LocalTime(parsedTime)
-			return nil
-		}
-	}
-	return fmt.Errorf("unable to parse time string '%s' into UTCTime", timeStr)
-}
-
-// MarshalJSON implements the json.Marshaler interface.
-// Serializes UTCTime to JSON in RFC3339 format with the correct timezone offset.
-func (t LocalTime) MarshalJSON() ([]byte, error) {
-	if time.Time(t).IsZero() {
-		return []byte("null"), nil
-	}
-	formattedTime := time.Time(t).In(GetAppLocation()).Format(time.RFC3339)
-	return []byte(fmt.Sprintf(`"%s"`, formattedTime)), nil
-}
-
-// ToTime converts UTCTime to Go's native time.Time type.
-func (t LocalTime) ToTime() time.Time { return time.Time(t) }
-
-// FromTime converts Go's native time.Time type to UTCTime.
-func FromTime(t time.Time) LocalTime { return LocalTime(t) }
-
-// Now returns the current time in the application's configured location.
-func Now() LocalTime { return LocalTime(time.Now().In(GetAppLocation())) }
-
-var (
-	appLocation  *time.Location
-	locationOnce sync.Once
-)
-
-// GetAppLocation retrieves the application's global timezone from the "TZ" environment variable.
-func GetAppLocation() *time.Location {
-	locationOnce.Do(func() {
-		tz := os.Getenv("TZ")
-		if tz == "" {
-			tz = "UTC"
-		}
-		loc, err := time.LoadLocation(tz)
-		if err != nil {
-			log.Printf("Warning: Failed to load timezone '%s', falling back to UTC. Error: %v", tz, err)
-			appLocation = time.UTC
-		} else {
-			appLocation = loc
-		}
-		time.Local = appLocation
-		log.Printf("Application timezone is set to '%s'.", appLocation.String())
-	})
-	return appLocation
-}

database/models/clipboard.go

@@ -1,11 +0,0 @@
-package models
-
-type Clipboard struct {
-	Id        int       `json:"id" gorm:"primaryKey;autoIncrement;unique"`
-	Text      string    `json:"text" gorm:"type:longtext"`
-	Name      string    `json:"name" gorm:"type:varchar(255)"`
-	Weight    int       `json:"weight" gorm:"type:int"`
-	Remark    string    `json:"remark" gorm:"type:text"`
-	CreatedAt LocalTime `json:"created_at"`
-	UpdatedAt LocalTime `json:"updated_at"`
-}

database/models/log.go

@@ -1,10 +1,12 @@
 package models
 
+import "time"
+
 type Log struct {
 	ID      uint      `json:"id,omitempty" gorm:"primaryKey;autoIncrement"`
 	IP      string    `json:"ip" gorm:"type:varchar(45);"` // IPv4 or IPv6
 	UUID    string    `json:"uuid" gorm:"type:varchar(36);"`
 	Message string    `json:"message" gorm:"type:text;not null"`
-	MsgType string    `json:"msg_type" gorm:"type:varchar(20);not null"`
-	Time    LocalTime `json:"time" gorm:"autoCreateTime;not null"`
+	MsgType string    `json:"msg_type" gorm:"type:varchar(20);not null;index:idx_logs_msg_type_time,priority:1"`
+	Time    time.Time `json:"time" gorm:"autoCreateTime;not null;index:idx_logs_time;index:idx_logs_msg_type_time,priority:2"`
 }

database/models/messageEvent/MessageEvent.go

@@ -8,7 +8,4 @@ const (
 	Login   = "Login"
 	Alert   = "Alert"
 	Traffic = "Traffic"
-	DReport = "DReport" // 日报
-	WReport = "WReport" // 周报
-	MReport = "MReport" // 月报
 )

database/models/messageSender.go

@@ -8,9 +8,9 @@ type MessageSenderProvider struct {
 }
 
 type EventMessage struct {
-	Event   string    `json:"event"`
+	Event   any       `json:"event"`
 	Clients []Client  `json:"clients"`
 	Time    time.Time `json:"time"`
-	Message string    `json:"message"`
-	Emoji   string    `json:"emoji"`
+	Message any       `json:"message"`
+	Emoji   any       `json:"emoji"`
 }

database/models/models.go

@@ -4,43 +4,44 @@ import (
 	"database/sql/driver"
 	"encoding/json"
 	"fmt"
+	"time"
 )
 
 // Client represents a registered client device
 type Client struct {
-	UUID             string    `json:"uuid,omitempty" gorm:"type:varchar(36);primaryKey"`
-	Token            string    `json:"token,omitempty" gorm:"type:varchar(255);unique;not null"`
-	Name             string    `json:"name" gorm:"type:varchar(100)"`
-	CpuName          string    `json:"cpu_name" gorm:"type:varchar(100)"`
-	Virtualization   string    `json:"virtualization" gorm:"type:varchar(50)"`
-	Arch             string    `json:"arch" gorm:"type:varchar(50)"`
-	CpuCores         int       `json:"cpu_cores" gorm:"type:int"`
-	CpuPhysicalCores int       `json:"cpu_physical_cores" gorm:"type:int"`
-	OS               string    `json:"os" gorm:"type:varchar(100)"`
-	KernelVersion    string    `json:"kernel_version" gorm:"type:varchar(100)"`
-	GpuName          string    `json:"gpu_name" gorm:"type:varchar(100)"`
-	IPv4             string    `json:"ipv4,omitempty" gorm:"type:varchar(100)"`
-	IPv6             string    `json:"ipv6,omitempty" gorm:"type:varchar(100)"`
-	Region           string    `json:"region" gorm:"type:varchar(100)"`
-	Remark           string    `json:"remark,omitempty" gorm:"type:longtext"`
-	PublicRemark     string    `json:"public_remark,omitempty" gorm:"type:longtext"`
-	MemTotal         int64     `json:"mem_total" gorm:"type:bigint"`
-	SwapTotal        int64     `json:"swap_total" gorm:"type:bigint"`
-	DiskTotal        int64     `json:"disk_total" gorm:"type:bigint"`
-	Version          string    `json:"version,omitempty" gorm:"type:varchar(100)"`
-	Weight           int       `json:"weight" gorm:"type:int"`
-	Price            float64   `json:"price"`
-	BillingCycle     int       `json:"billing_cycle"`
-	AutoRenewal      bool      `json:"auto_renewal" gorm:"default:false"` // 是否自动续费
-	Currency         string    `json:"currency" gorm:"type:varchar(20);default:'$'"`
-	ExpiredAt        LocalTime `json:"expired_at" gorm:"type:timestamp"`
-	Group            string    `json:"group" gorm:"type:varchar(100)"`
-	Tags             string    `json:"tags" gorm:"type:text"` // split by ';'
-	Hidden           bool      `json:"hidden" gorm:"default:false"`
-	TrafficLimit     int64     `json:"traffic_limit" gorm:"type:bigint"`
-	TrafficLimitType string    `json:"traffic_limit_type" gorm:"type:varchar(10);default:'max'"` // 流量阈值类型：sum max min up down
-	CreatedAt        LocalTime `json:"created_at"`
-	UpdatedAt        LocalTime `json:"updated_at"`
+	UUID             string     `json:"uuid,omitempty" gorm:"type:varchar(36);primaryKey"`
+	Token            string     `json:"token,omitempty" gorm:"type:varchar(255);unique;not null"`
+	Name             string     `json:"name" gorm:"type:varchar(100)"`
+	CpuName          string     `json:"cpu_name" gorm:"type:varchar(100)"`
+	Virtualization   string     `json:"virtualization" gorm:"type:varchar(50)"`
+	Arch             string     `json:"arch" gorm:"type:varchar(50)"`
+	CpuCores         int        `json:"cpu_cores" gorm:"type:int"`
+	CpuPhysicalCores int        `json:"cpu_physical_cores" gorm:"type:int"`
+	OS               string     `json:"os" gorm:"type:varchar(100)"`
+	KernelVersion    string     `json:"kernel_version" gorm:"type:varchar(100)"`
+	GpuName          string     `json:"gpu_name" gorm:"type:varchar(100)"`
+	IPv4             string     `json:"ipv4,omitempty" gorm:"type:varchar(100)"`
+	IPv6             string     `json:"ipv6,omitempty" gorm:"type:varchar(100)"`
+	Region           string     `json:"region" gorm:"type:varchar(100)"`
+	Remark           string     `json:"remark,omitempty" gorm:"type:longtext"`
+	PublicRemark     string     `json:"public_remark,omitempty" gorm:"type:longtext"`
+	MemTotal         int64      `json:"mem_total" gorm:"type:bigint"`
+	SwapTotal        int64      `json:"swap_total" gorm:"type:bigint"`
+	DiskTotal        int64      `json:"disk_total" gorm:"type:bigint"`
+	Version          string     `json:"version,omitempty" gorm:"type:varchar(100)"`
+	Weight           int        `json:"weight" gorm:"type:int"`
+	Price            float64    `json:"price"`
+	BillingCycle     int        `json:"billing_cycle"`
+	AutoRenewal      bool       `json:"auto_renewal" gorm:"default:false"` // 是否自动续费
+	Currency         string     `json:"currency" gorm:"type:varchar(20);default:'$'"`
+	ExpiredAt        *time.Time `json:"expired_at" gorm:"type:timestamp"`
+	Group            string     `json:"group" gorm:"type:varchar(100)"`
+	Tags             string     `json:"tags" gorm:"type:text"` // split by ';'
+	Hidden           bool       `json:"hidden" gorm:"default:false"`
+	TrafficLimit     int64      `json:"traffic_limit" gorm:"type:bigint"`
+	TrafficLimitType string     `json:"traffic_limit_type" gorm:"type:varchar(10);default:'max'"` // 流量阈值类型：sum max min up down
+	CreatedAt        time.Time  `json:"created_at"`
+	UpdatedAt        time.Time  `json:"updated_at"`
 }
 
 // User represents an authenticated user
@@ -52,8 +53,8 @@ type User struct {
 	SSOID     string    `json:"sso_id" gorm:"type:varchar(100)"`                    // OAuth provider's user ID
 	TwoFactor string    `json:"two_factor,omitempty" gorm:"type:varchar(255)"`      // 2FA secret
 	Sessions  []Session `json:"sessions,omitempty" gorm:"foreignKey:UUID;references:UUID;constraint:OnDelete:CASCADE,OnUpdate:CASCADE"`
-	CreatedAt LocalTime `json:"created_at"`
-	UpdatedAt LocalTime `json:"updated_at"`
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
 }
 
 // Session manages user sessions
@@ -63,17 +64,17 @@ type Session struct {
 	UserAgent       string    `json:"user_agent" gorm:"type:text"`
 	Ip              string    `json:"ip" gorm:"type:varchar(100)"`
 	LoginMethod     string    `json:"login_method" gorm:"type:varchar(50)"`
-	LatestOnline    LocalTime `json:"latest_online" gorm:"type:timestamp"`
+	LatestOnline    time.Time `json:"latest_online" gorm:"type:timestamp"`
 	LatestUserAgent string    `json:"latest_user_agent" gorm:"type:text"`
 	LatestIp        string    `json:"latest_ip" gorm:"type:varchar(100)"`
-	Expires         LocalTime `json:"expires" gorm:"not null"`
-	CreatedAt       LocalTime `json:"created_at"`
+	Expires         time.Time `json:"expires" gorm:"not null"`
+	CreatedAt       time.Time `json:"created_at"`
 }
 
 // Record logs client metrics over time
 type Record struct {
 	Client         string    `json:"client" gorm:"type:varchar(36);index"`
-	Time           LocalTime `json:"time" gorm:"index"`
+	Time           time.Time `json:"time" gorm:"index"`
 	Cpu            float32   `json:"cpu" gorm:"type:decimal(5,2)"` // e.g., 75.50%
 	Gpu            float32   `json:"gpu" gorm:"type:decimal(5,2)"`
 	Ram            int64     `json:"ram" gorm:"type:bigint"`
@@ -99,7 +100,7 @@ type Record struct {
 // GPURecord logs individual GPU metrics over time
 type GPURecord struct {
 	Client      string    `json:"client" gorm:"type:varchar(36);index"` // 客户端UUID
-	Time        LocalTime `json:"time" gorm:"index"`                    // 记录时间
+	Time        time.Time `json:"time" gorm:"index"`                    // 记录时间
 	DeviceIndex int       `json:"device_index" gorm:"index"`            // GPU设备索引 (0,1,2...)
 	DeviceName  string    `json:"device_name" gorm:"type:varchar(100)"` // GPU型号
 	MemTotal    int64     `json:"mem_total" gorm:"type:bigint"`         // 显存总量(字节)

database/models/notification.go

@@ -1,25 +1,15 @@
 package models
 
+import "time"
+
 // Notification 定义了通知相关的数据库模型
 type OfflineNotification struct {
 	Client     string `json:"client" gorm:"type:varchar(36);not null;index;unique;constraint:OnDelete:CASCADE,OnUpdate:CASCADE;foreignKey:client;references:UUID"`
 	ClientInfo Client `json:"client_info,omitempty" gorm:"foreignKey:Client;references:UUID"`
 	Enable     bool   `json:"enable" gorm:"type:boolean;default:false"`
 	//Cooldown     int       `json:"cooldown" gorm:"type:int;not null;default:1800"`                // 冷却时间（秒），默认 30 分钟
-	GracePeriod  int       `json:"grace_period" gorm:"type:int;not null;default:180"` // 宽限期（秒），默认 3 分钟
-	LastNotified LocalTime `json:"last_notified"`                                     // 上次通知时间
-}
-
-// LoadNotification 定义了基于资源占用达标时间比的负载通知规则
-type LoadNotification struct {
-	Id           uint        `json:"id,omitempty" gorm:"primaryKey;autoIncrement"`
-	Name         string      `json:"name" gorm:"type:varchar(255)"`
-	Clients      StringArray `json:"clients" gorm:"type:longtext"`
-	Metric       string      `json:"metric" gorm:"type:varchar(50);not null;default:'cpu'"`     // 监控指标，如 cpu, ram, load
-	Threshold    float32     `json:"threshold" gorm:"type:decimal(5,2);not null;default:80.00"` // 阈值百分比
-	Ratio        float32     `json:"ratio" gorm:"type:decimal(5,2);not null;default:0.80"`      // 达标时间比
-	Interval     int         `json:"interval" gorm:"type:int;not null;default:15"`              // 监测间隔（分钟）
-	LastNotified LocalTime   `json:"last_notified"`                                             // 上次通知时间
+	GracePeriod  int        `json:"grace_period" gorm:"type:int;not null;default:180"` // 宽限期（秒），默认 3 分钟
+	LastNotified *time.Time `json:"last_notified"`                                     // 上次通知时间
 }
 
 // TrafficReportNotification 定义了流量定时报告的数据库模型
@@ -27,7 +17,7 @@ type TrafficReportNotification struct {
 	Client     string `json:"client" gorm:"type:varchar(36);not null;index;unique;constraint:OnDelete:CASCADE,OnUpdate:CASCADE;foreignKey:client;references:UUID"`
 	ClientInfo Client `json:"client_info,omitempty" gorm:"foreignKey:Client;references:UUID"`
 	Enable     bool   `json:"enable" gorm:"type:boolean;default:false"`
-	Daily      bool   `json:"daily" gorm:"type:boolean;default:false"`  // 日报
-	Weekly     bool   `json:"weekly" gorm:"type:boolean;default:false"` // 周报
+	Daily      bool   `json:"daily" gorm:"type:boolean;default:false"`   // 日报
+	Weekly     bool   `json:"weekly" gorm:"type:boolean;default:false"`  // 周报
 	Monthly    bool   `json:"monthly" gorm:"type:boolean;default:false"` // 月报
 }

database/models/pingTask.go

@@ -1,11 +1,13 @@
 package models
 
+import "time"
+
 type PingRecord struct {
 	Client     string    `json:"client" gorm:"type:varchar(36);not null;index"`
 	ClientInfo Client    `json:"client_info" gorm:"foreignKey:Client;references:UUID;constraint:OnDelete:CASCADE,OnUpdate:CASCADE"`
 	TaskId     uint      `json:"task_id" gorm:"not null;index"`
 	Task       PingTask  `json:"task" gorm:"foreignKey:TaskId;references:Id;constraint:OnDelete:CASCADE,OnUpdate:CASCADE;"`
-	Time       LocalTime `json:"time" gorm:"index;not null"`
+	Time       time.Time `json:"time" gorm:"index;not null"`
 	Value      int       `json:"value" gorm:"type:int;not null"` // Ping 值，单位毫秒
 }
 

database/models/plugin.go

@@ -0,0 +1,86 @@
+package models
+
+// Plugin is the manifest of an installed plugin (komari-plugin.json).
+//
+// Name, Description and Author accept either a plain string or an i18n map
+// like {"zh_CN": "...", "en": "..."}, mirroring the theme manifest. The
+// backend passes the value through and the frontend resolves it against the
+// current locale.
+type Plugin struct {
+	Name          any               `json:"name"`
+	Short         string            `json:"short"` // directory name under data/plugin
+	Description   any               `json:"description"`
+	Author        any               `json:"author"`
+	Version       string            `json:"version"`
+	URL           string            `json:"url"`
+	Icon          string            `json:"icon"`
+	Komari        string            `json:"komari"` // supported server version constraint, e.g. ">=0.0.1"
+	Entry         string            `json:"entry"`  // entry script, defaults to "script.js"
+	Permissions   PluginPermissions `json:"permissions"`
+	Configuration Configuration     `json:"configuration"`   // declared config items, same shape as themes
+	Pages         []PluginPage      `json:"pages,omitempty"` // injected admin pages
+}
+
+// PluginPermissions declares the plugin capabilities that require admin
+// approval. Every field defaults to its zero value: nothing is granted
+// unless declared.
+//
+// The following capabilities are always granted and never require approval:
+// reading the plugin's own configuration (server.getConfig), registering
+// plugin-owned RPC methods (server.registerRPC), and reading/writing files
+// inside the plugin directory.
+type PluginPermissions struct {
+	Node                bool  `json:"node"`                // Node.js compatibility modules (runtime setting, not approval-relevant)
+	AllowSystemRPC      bool  `json:"allowSystemRPC"`      // server.call: call system RPC methods with admin authority
+	AllowRoutes         bool  `json:"allowRoutes"`         // server.route: register HTTP routes on the host engine
+	AllowHooks          bool  `json:"allowHooks"`          // server.hook: modify HTTP requests/responses and intercept WebSocket connections/frames
+	AllowHTMLInject     bool  `json:"allowHTMLInject"`     // server.injectHTML: embed CSS/JS into every HTML response
+	AllowExec           bool  `json:"allowExec"`           // child_process: execute child processes
+	AllowListen         bool  `json:"allowListen"`         // net/http servers: listen on local ports
+	AllowAllFileAccess  bool  `json:"allowAllFileAccess"`  // access files outside the plugin directory
+	MaxHTTPBodyBytes    int64 `json:"maxHTTPBodyBytes"`    // runtime limit, not approval-relevant
+	MaxChildOutputBytes int   `json:"maxChildOutputBytes"` // runtime limit, not approval-relevant
+	TimeoutSeconds      int   `json:"timeout"`             // per-turn execution timeout in seconds, not approval-relevant
+}
+
+// PageVisibility controls who can reach a plugin page.
+type PageVisibility string
+
+const (
+	// PageVisibilityAdmin limits the page to the admin sidebar.
+	PageVisibilityAdmin PageVisibility = "admin"
+	// PageVisibilityPublic serves the page through the public route without
+	// navigation, mirroring the theme public behavior.
+	PageVisibilityPublic PageVisibility = "public"
+)
+
+// PageType controls how a plugin page is presented.
+type PageType string
+
+const (
+	// PageTypeIframe embeds a static file from the plugin directory.
+	PageTypeIframe PageType = "iframe"
+	// PageTypeRedirect navigates to an internal site path, mirroring the
+	// theme redirect configuration. The URL must stay on the same origin.
+	PageTypeRedirect PageType = "redirect"
+)
+
+// PluginPage declares a page provided by the plugin. An iframe page is served
+// from the plugin directory (File); a redirect page navigates to an internal
+// site path (URL). Visibility defaults to admin so existing packages keep
+// their current behavior.
+type PluginPage struct {
+	File       string         `json:"file"`
+	Title      any            `json:"title"`
+	Icon       string         `json:"icon"`
+	Type       PageType       `json:"type,omitempty"`
+	URL        string         `json:"url,omitempty"`
+	Visibility PageVisibility `json:"visibility,omitempty"`
+}
+
+// PluginConfiguration stores the saved configuration values of one plugin,
+// mirroring ThemeConfiguration.
+type PluginConfiguration struct {
+	Short string `json:"short" gorm:"primaryKey;unique;not null"`
+	Data  string `json:"data" gorm:"type:longtext" default:"{}"`
+}

database/models/task.go

@@ -1,5 +1,7 @@
 package models
 
+import "time"
+
 type Task struct {
 	TaskId  string       `json:"task_id" gorm:"type:varchar(36);primaryKey;unique"`
 	Clients StringArray  `json:"clients" gorm:"type:longtext"`
@@ -13,6 +15,6 @@ type TaskResult struct {
 	ClientInfo Client     `json:"client_info" gorm:"foreignKey:Client;references:UUID;constraint:OnDelete:CASCADE,OnUpdate:CASCADE"`
 	Result     string     `json:"result" gorm:"type:longtext"`
 	ExitCode   *int       `json:"exit_code" gorm:"type:int"`
-	FinishedAt *LocalTime `json:"finished_at" gorm:"type:timestamp"`
-	CreatedAt  LocalTime  `json:"created_at" gorm:"type:timestamp"`
+	FinishedAt *time.Time `json:"finished_at" gorm:"type:timestamp"`
+	CreatedAt  time.Time  `json:"created_at" gorm:"type:timestamp"`
 }

database/models/theme.go

@@ -15,16 +15,37 @@ const (
 
 // Theme represents a komari theme information
 type Theme struct {
-	Name          string        `json:"name"`          // 主题名称
+	Name          any           `json:"name"`          // 主题名称，支持字符串或多语言对象
 	Short         string        `json:"short"`         // 短名称，用作文件夹名
-	Description   string        `json:"description"`   // 主题描述
+	Description   any           `json:"description"`   // 主题描述，支持字符串或多语言对象
 	Version       string        `json:"version"`       // 版本号
-	Author        string        `json:"author"`        // 作者
+	Author        any           `json:"author"`        // 作者，支持字符串或多语言对象
 	URL           string        `json:"url"`           // 主题URL
 	Preview       string        `json:"preview"`       // 预览图片相对路径
 	Configuration Configuration `json:"configuration"` // 声明配置项
 }
 
+// IsLocalizedText reports whether a manifest text field has a usable value.
+func IsLocalizedText(value any) bool {
+	switch text := value.(type) {
+	case string:
+		return strings.TrimSpace(text) != ""
+	case map[string]any:
+		for _, item := range text {
+			if itemText, ok := item.(string); ok && strings.TrimSpace(itemText) != "" {
+				return true
+			}
+		}
+	case map[string]string:
+		for _, item := range text {
+			if strings.TrimSpace(item) != "" {
+				return true
+			}
+		}
+	}
+	return false
+}
+
 type Configuration struct {
 	Type string `json:"type"` // managed raw redirect
 	Icon string `json:"icon"` // 图标
@@ -36,7 +57,7 @@ type ManagedThemeConfigurationItem struct {
 	Key      string `json:"key"`
 	Name     any    `json:"name"`
 	Required bool   `json:"required"`
-	Type     string `json:"type"` // string number select switch title
+	Type     string `json:"type"` // string number select switch title textbox richtext nodes pingtasks
 	Options  string `json:"options"`
 	Default  any    `json:"default"`
 	Help     any    `json:"help"`

database/models/time_test.go

@@ -0,0 +1,77 @@
+package models
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+func TestTimeFieldsStoreAndSerializeAsUTCWithNanoseconds(t *testing.T) {
+	dsn := fmt.Sprintf("file:%s-%d?mode=memory&cache=shared", strings.ReplaceAll(t.Name(), "/", "_"), time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		Logger:  logger.Default.LogMode(logger.Silent),
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open database: %v", err)
+	}
+	if err := db.AutoMigrate(&Log{}); err != nil {
+		t.Fatalf("migrate log: %v", err)
+	}
+
+	stamp := time.Date(2026, 7, 17, 1, 2, 3, 123456789, time.UTC)
+	entry := Log{IP: "127.0.0.1", UUID: "test", Message: "test", MsgType: "info", Time: stamp}
+	if err := db.Create(&entry).Error; err != nil {
+		t.Fatalf("create log: %v", err)
+	}
+	var loaded Log
+	if err := db.First(&loaded, entry.ID).Error; err != nil {
+		t.Fatalf("load log: %v", err)
+	}
+	if !loaded.Time.Equal(stamp) || loaded.Time.Nanosecond() != stamp.Nanosecond() {
+		t.Fatalf("loaded time = %s, want %s", loaded.Time, stamp)
+	}
+
+	encoded, err := json.Marshal(loaded)
+	if err != nil {
+		t.Fatalf("marshal log: %v", err)
+	}
+	if !strings.Contains(string(encoded), `"time":"2026-07-17T01:02:03.123456789Z"`) {
+		t.Fatalf("unexpected JSON: %s", encoded)
+	}
+}
+
+func TestNullableTimeFieldReadsAndSerializesNull(t *testing.T) {
+	dsn := fmt.Sprintf("file:%s-%d?mode=memory&cache=shared", strings.ReplaceAll(t.Name(), "/", "_"), time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{Logger: logger.Default.LogMode(logger.Silent)})
+	if err != nil {
+		t.Fatalf("open database: %v", err)
+	}
+	if err := db.AutoMigrate(&Client{}); err != nil {
+		t.Fatalf("migrate client: %v", err)
+	}
+	if err := db.Exec(`INSERT INTO clients (uuid, token, expired_at) VALUES (?, ?, NULL)`, "nullable", "token").Error; err != nil {
+		t.Fatalf("insert client: %v", err)
+	}
+
+	var client Client
+	if err := db.First(&client, "uuid = ?", "nullable").Error; err != nil {
+		t.Fatalf("load client: %v", err)
+	}
+	if client.ExpiredAt != nil {
+		t.Fatalf("expired_at = %s, want nil", client.ExpiredAt)
+	}
+	encoded, err := json.Marshal(client)
+	if err != nil {
+		t.Fatalf("marshal client: %v", err)
+	}
+	if !strings.Contains(string(encoded), `"expired_at":null`) {
+		t.Fatalf("unexpected JSON: %s", encoded)
+	}
+}

database/notification/load.go

@@ -1,68 +0,0 @@
-package notification
-
-import (
-	"github.com/komari-monitor/komari/database/dbcore"
-	"github.com/komari-monitor/komari/database/models"
-	"github.com/komari-monitor/komari/utils/notifier"
-	"gorm.io/gorm"
-)
-
-func AddLoadNotification(clients []string, name string, metric string, threshold float32, ratio float32, interval int) (uint, error) {
-	db := dbcore.GetDBInstance()
-	notification := models.LoadNotification{
-		Clients:   clients,
-		Name:      name,
-		Metric:    metric,
-		Threshold: threshold,
-		Ratio:     ratio,
-		Interval:  interval,
-	}
-	if err := db.Create(&notification).Error; err != nil {
-		return 0, err
-	}
-
-	return notification.Id, ReloadLoadNotificationSchedule()
-}
-func DeleteLoadNotification(id []uint) error {
-	db := dbcore.GetDBInstance()
-	result := db.Where("id IN ?", id).Delete(&models.LoadNotification{})
-	if result.RowsAffected == 0 {
-		return gorm.ErrRecordNotFound
-	}
-	return ReloadLoadNotificationSchedule()
-}
-
-func EditLoadNotification(notifications []*models.LoadNotification) error {
-	db := dbcore.GetDBInstance()
-	for _, notification := range notifications {
-		result := db.Model(&models.LoadNotification{}).Where("id = ?", notification.Id).Updates(notification)
-		if result.RowsAffected == 0 {
-			return gorm.ErrRecordNotFound
-		}
-	}
-
-	return ReloadLoadNotificationSchedule()
-}
-
-func GetAllLoadNotifications() ([]models.LoadNotification, error) {
-	db := dbcore.GetDBInstance()
-	var notifications []models.LoadNotification
-	if err := db.Find(&notifications).Error; err != nil {
-		return nil, err
-	}
-	return notifications, nil
-}
-
-func SaveLoadNotification(record models.LoadNotification) error {
-	db := dbcore.GetDBInstance()
-	return db.Create(&record).Error
-}
-
-func ReloadLoadNotificationSchedule() error {
-	db := dbcore.GetDBInstance()
-	var loadNotifications []models.LoadNotification
-	if err := db.Find(&loadNotifications).Error; err != nil {
-		return err
-	}
-	return notifier.ReloadLoadNotificationSchedule(loadNotifications)
-}

database/notification/traffic_report.go

@@ -1,144 +0,0 @@
-package notification
-
-import (
-	"fmt"
-
-	"github.com/komari-monitor/komari/database/dbcore"
-	"github.com/komari-monitor/komari/database/models"
-	"gorm.io/gorm/clause"
-)
-
-func validateTrafficReportNotification(notification models.TrafficReportNotification) error {
-	if notification.Client == "" {
-		return fmt.Errorf("client UUID cannot be empty")
-	}
-	if notification.Enable && !notification.Daily && !notification.Weekly && !notification.Monthly {
-		return fmt.Errorf("at least one cadence must be selected when enabling traffic reports")
-	}
-	return nil
-}
-
-func ValidateTrafficReportNotifications(notifications []models.TrafficReportNotification) error {
-	for _, notification := range notifications {
-		if err := validateTrafficReportNotification(notification); err != nil {
-			return err
-		}
-	}
-	return nil
-}
-
-func buildEnabledTrafficReportNotifications(uuids []string, existing []models.TrafficReportNotification) ([]models.TrafficReportNotification, error) {
-	if len(uuids) == 0 {
-		return nil, fmt.Errorf("at least one client UUID is required")
-	}
-
-	existingByClient := make(map[string]models.TrafficReportNotification, len(existing))
-	for _, notification := range existing {
-		existingByClient[notification.Client] = notification
-	}
-
-	notifications := make([]models.TrafficReportNotification, 0, len(uuids))
-	for _, uuid := range uuids {
-		if uuid == "" {
-			return nil, fmt.Errorf("client UUID cannot be empty")
-		}
-		existingNotification, ok := existingByClient[uuid]
-		if !ok || (!existingNotification.Daily && !existingNotification.Weekly && !existingNotification.Monthly) {
-			return nil, fmt.Errorf("at least one cadence must be selected when enabling traffic reports")
-		}
-		notifications = append(notifications, models.TrafficReportNotification{
-			Client: uuid,
-			Enable: true,
-		})
-	}
-
-	return notifications, nil
-}
-
-// ListTrafficReportNotifications 获取所有流量定时报告配置（关联客户端信息）
-func ListTrafficReportNotifications() ([]models.TrafficReportNotification, error) {
-	db := dbcore.GetDBInstance()
-	var notifications []models.TrafficReportNotification
-	err := db.Model(&models.TrafficReportNotification{}).Preload("ClientInfo").Find(&notifications).Error
-	return notifications, err
-}
-
-// EditTrafficReportNotifications 批量更新流量定时报告配置
-func EditTrafficReportNotifications(notifications []models.TrafficReportNotification) error {
-	if err := ValidateTrafficReportNotifications(notifications); err != nil {
-		return err
-	}
-	db := dbcore.GetDBInstance()
-	return db.Model(&models.TrafficReportNotification{}).
-		Clauses(clause.OnConflict{
-			Columns:   []clause.Column{{Name: "client"}},
-			DoUpdates: clause.AssignmentColumns([]string{"enable", "daily", "weekly", "monthly"}),
-		}).
-		Select("client", "enable", "daily", "weekly", "monthly").
-		Create(notifications).Error
-}
-
-// EnableTrafficReportNotifications 批量启用（仅更新 enable 字段）
-func EnableTrafficReportNotifications(uuids []string) error {
-	if len(uuids) == 0 {
-		return fmt.Errorf("at least one client UUID is required")
-	}
-
-	db := dbcore.GetDBInstance()
-	var existing []models.TrafficReportNotification
-	if err := db.Where("client IN ?", uuids).Find(&existing).Error; err != nil {
-		return err
-	}
-	notifications, err := buildEnabledTrafficReportNotifications(uuids, existing)
-	if err != nil {
-		return err
-	}
-	return db.Model(&models.TrafficReportNotification{}).
-		Clauses(clause.OnConflict{
-			Columns:   []clause.Column{{Name: "client"}},
-			DoUpdates: clause.AssignmentColumns([]string{"enable"}),
-		}).
-		Select("client", "enable").
-		Create(notifications).Error
-}
-
-// DisableTrafficReportNotifications 批量禁用
-func DisableTrafficReportNotifications(uuids []string) error {
-	if len(uuids) == 0 {
-		return fmt.Errorf("at least one client UUID is required")
-	}
-	db := dbcore.GetDBInstance()
-	var notifications []models.TrafficReportNotification
-	for _, uuid := range uuids {
-		if uuid == "" {
-			return fmt.Errorf("client UUID cannot be empty")
-		}
-		notifications = append(notifications, models.TrafficReportNotification{
-			Client: uuid,
-			Enable: false,
-		})
-	}
-	return db.Model(&models.TrafficReportNotification{}).
-		Clauses(clause.OnConflict{
-			Columns:   []clause.Column{{Name: "client"}},
-			DoUpdates: clause.AssignmentColumns([]string{"enable"}),
-		}).
-		Select("client", "enable").
-		Create(notifications).Error
-}
-
-// GetEnabledTrafficReportByType 获取启用了指定类型报告的客户端配置
-func GetEnabledTrafficReportByType(daily, weekly, monthly bool) ([]models.TrafficReportNotification, error) {
-	db := dbcore.GetDBInstance()
-	var notifications []models.TrafficReportNotification
-	query := db.Model(&models.TrafficReportNotification{}).Where("enable = ?", true)
-	if daily {
-		query = query.Where("daily = ?", true)
-	} else if weekly {
-		query = query.Where("weekly = ?", true)
-	} else if monthly {
-		query = query.Where("monthly = ?", true)
-	}
-	err := query.Find(&notifications).Error
-	return notifications, err
-}

database/notification/traffic_report_test.go

@@ -1,36 +0,0 @@
-package notification
-
-import (
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-
-	"github.com/komari-monitor/komari/database/models"
-)
-
-func TestValidateTrafficReportNotificationsRejectsEnabledWithoutCadence(t *testing.T) {
-	err := ValidateTrafficReportNotifications([]models.TrafficReportNotification{{
-		Client: "client-a",
-		Enable: true,
-	}})
-
-	assert.Error(t, err)
-}
-
-func TestBuildEnabledTrafficReportNotificationsRequiresExistingCadence(t *testing.T) {
-	_, err := buildEnabledTrafficReportNotifications([]string{"client-a"}, nil)
-	assert.Error(t, err)
-
-	_, err = buildEnabledTrafficReportNotifications([]string{"client-a"}, []models.TrafficReportNotification{{Client: "client-a"}})
-	assert.Error(t, err)
-
-	notifications, err := buildEnabledTrafficReportNotifications([]string{"client-a"}, []models.TrafficReportNotification{{
-		Client: "client-a",
-		Daily:  true,
-	}})
-	require.NoError(t, err)
-	require.Len(t, notifications, 1)
-	assert.Equal(t, "client-a", notifications[0].Client)
-	assert.True(t, notifications[0].Enable)
-}

database/oauth.go

@@ -5,15 +5,6 @@ import (
 	"github.com/komari-monitor/komari/database/models"
 )
 
-func GetAllOidcConfigs() []models.OidcProvider {
-	db := dbcore.GetDBInstance()
-	var result []models.OidcProvider
-	if err := db.Find(&result).Error; err != nil {
-		return nil
-	}
-	return result
-}
-
 func GetOidcConfigByName(name string) (*models.OidcProvider, error) {
 	db := dbcore.GetDBInstance()
 	var config models.OidcProvider
@@ -23,10 +14,11 @@ func GetOidcConfigByName(name string) (*models.OidcProvider, error) {
 	return &config, nil
 }
 
-func SaveOidcConfig(config *models.OidcProvider) error {
+func DeleteOidcConfigByName(name string) error {
 	db := dbcore.GetDBInstance()
-	if err := db.Save(config).Error; err != nil {
-		return err
-	}
-	return nil
+	return db.Delete(&models.OidcProvider{}, "name = ?", name).Error
+}
+
+func SaveOidcConfig(config *models.OidcProvider) error {
+	return dbcore.GetDBInstance().Save(config).Error
 }

database/records/projection.go

@@ -0,0 +1,63 @@
+package records
+
+import "github.com/komari-monitor/komari/database/models"
+
+// LoadProjection is the field subset selected by a load_type request.
+type LoadProjection struct {
+	Cpu            *float32 `json:"cpu,omitempty"`
+	Gpu            *float32 `json:"gpu,omitempty"`
+	Ram            *int64   `json:"ram,omitempty"`
+	RamTotal       *int64   `json:"ram_total,omitempty"`
+	Swap           *int64   `json:"swap,omitempty"`
+	SwapTotal      *int64   `json:"swap_total,omitempty"`
+	Load           *float32 `json:"load,omitempty"`
+	Temp           *float32 `json:"temp,omitempty"`
+	Disk           *int64   `json:"disk,omitempty"`
+	DiskTotal      *int64   `json:"disk_total,omitempty"`
+	NetIn          *int64   `json:"net_in,omitempty"`
+	NetOut         *int64   `json:"net_out,omitempty"`
+	NetTotalUp     *int64   `json:"net_total_up,omitempty"`
+	NetTotalDown   *int64   `json:"net_total_down,omitempty"`
+	Process        *int     `json:"process,omitempty"`
+	Connections    *int     `json:"connections,omitempty"`
+	ConnectionsUdp *int     `json:"connections_udp,omitempty"`
+}
+
+// ProjectLoad returns the load_type projection for one record.
+func ProjectLoad(r models.Record, loadType string) LoadProjection {
+	var p LoadProjection
+	switch loadType {
+	case "cpu":
+		p.Cpu = ptr(r.Cpu)
+	case "gpu":
+		p.Gpu = ptr(r.Gpu)
+	case "ram":
+		p.Ram = ptr(r.Ram)
+		p.RamTotal = ptr(r.RamTotal)
+	case "swap":
+		p.Swap = ptr(r.Swap)
+		p.SwapTotal = ptr(r.SwapTotal)
+	case "load":
+		p.Load = ptr(r.Load)
+	case "temp":
+		p.Temp = ptr(r.Temp)
+	case "disk":
+		p.Disk = ptr(r.Disk)
+		p.DiskTotal = ptr(r.DiskTotal)
+	case "network":
+		p.NetIn = ptr(r.NetIn)
+		p.NetOut = ptr(r.NetOut)
+		p.NetTotalUp = ptr(r.NetTotalUp)
+		p.NetTotalDown = ptr(r.NetTotalDown)
+	case "process":
+		p.Process = ptr(r.Process)
+	case "connections":
+		p.Connections = ptr(r.Connections)
+		p.ConnectionsUdp = ptr(r.ConnectionsUdp)
+	default:
+		p.Cpu = ptr(r.Cpu)
+	}
+	return p
+}
+
+func ptr[T any](v T) *T { return &v }

database/records/records.go

@@ -1,524 +1,95 @@
 package records
 
 import (
-	"log"
-	"sort"
-	"strings"
+	"context"
 	"time"
 
-	"gorm.io/gorm"
-
-	"github.com/komari-monitor/komari/cmd/flags"
-	"github.com/komari-monitor/komari/database/dbcore"
 	"github.com/komari-monitor/komari/database/models"
+	"github.com/komari-monitor/komari/internal/metricstore"
 )
 
-func RecordOne(rec models.Record) error {
-	db := dbcore.GetDBInstance()
-	return db.Create(&rec).Error
-}
-
-func RecordGPU(rec models.GPURecord) error {
-	db := dbcore.GetDBInstance()
-	return db.Create(&rec).Error
-}
+// 历史监控数据已完全迁移到 metric store（默认 SQLite ./data/metrics.db，或配置的
+// MySQL/PostgreSQL）。旧的 records / records_long_term / gpu_records / ping_records
+// 表仅在启动一次性迁移时作为数据源读取，运行期的读写全部走 metric store。
+//
+// 因此本文件不再保留对旧表的任何读写、压缩（rollup）与流量增量修复逻辑：
+// metric store 自行管理 rollup 与保留策略，旧表压缩已无意义。
 
 func DeleteAll() error {
-	db := dbcore.GetDBInstance()
-	if err := db.Exec("DELETE FROM records_long_term").Error; err != nil {
-		return err
-	}
-	if err := db.Exec("DELETE FROM gpu_records_long_term").Error; err != nil {
-		return err
-	}
-	if err := db.Exec("DELETE FROM gpu_records").Error; err != nil {
-		return err
-	}
-	return db.Exec("DELETE FROM records").Error
+	return metricstore.DeleteAllRecords(context.Background())
 }
 
-// GetGPURecordsByClientAndTime 获取GPU记录数据
+// QueryGPURecords returns GPU records using the caller's cancellation context.
+func QueryGPURecords(ctx context.Context, uuid string, start, end time.Time) ([]models.GPURecord, error) {
+	return metricstore.GetGPURecordsByClientAndTime(ctx, uuid, start, end)
+}
+
+// GetGPURecordsByClientAndTime is a compatibility-only wrapper without cancellation.
+// New request handlers should use QueryGPURecords.
 func GetGPURecordsByClientAndTime(uuid string, start, end time.Time) ([]models.GPURecord, error) {
-	db := dbcore.GetDBInstance()
-	var records []models.GPURecord
-
-	fourHoursAgo := time.Now().Add(-4*time.Hour - time.Minute)
-
-	var recentRecords []models.GPURecord
-	recentStart := start
-	if end.After(fourHoursAgo) {
-		if recentStart.Before(fourHoursAgo) {
-			recentStart = fourHoursAgo
-		}
-		err := db.Where("client = ? AND time >= ? AND time <= ?", uuid, recentStart, end).
-			Order("time ASC, device_index ASC").Find(&recentRecords).Error
-		if err != nil {
-			log.Printf("Error fetching recent GPU records for client %s between %s and %s: %v", uuid, recentStart, end, err)
-			return nil, err
-		}
-	}
-
-	var longTermRecords []models.GPURecord
-	err := db.Table("gpu_records_long_term").Where("client = ? AND time >= ? AND time <= ?", uuid, start, end).
-		Order("time ASC, device_index ASC").Find(&longTermRecords).Error
-	if err != nil {
-		log.Printf("Error fetching long-term GPU records for client %s between %s and %s: %v", uuid, start, end, err)
-		return recentRecords, nil
-	}
-
-	// 合并结果 - 不再需要类型转换
-	records = append(records, recentRecords...)
-	records = append(records, longTermRecords...)
-
-	return records, nil
+	return QueryGPURecords(context.Background(), uuid, start, end)
 }
 
-func GetLatestRecord(uuid string) (Record []models.Record, err error) {
-	db := dbcore.GetDBInstance()
-	err = db.Where("client = ?", uuid).Order("time DESC").Limit(1).Find(&Record).Error
-	return
-}
+// RecordQueryOptions narrows metric selection and the response point budget.
+type RecordQueryOptions = metricstore.RecordQueryOptions
 
-func DeleteRecordBefore(before time.Time) error {
-	db := dbcore.GetDBInstance()
-	db.Table("records_long_term").Where("time < ?", before).Delete(&models.Record{})
-	db.Table("gpu_records_long_term").Where("time < ?", before).Delete(&models.GPURecord{})
-	db.Where("time < ?", before).Delete(&models.GPURecord{})
-	return db.Where("time < ?", before).Delete(&models.Record{}).Error
-}
-
-func GetRecordsByClientAndTime(uuid string, start, end time.Time) ([]models.Record, error) {
-	db := dbcore.GetDBInstance()
-	var records []models.Record
-
-	fourHoursAgo := time.Now().Add(-4*time.Hour - time.Minute)
-
-	var recentRecords []models.Record
-	recentStart := start
-	if end.After(fourHoursAgo) {
-		if recentStart.Before(fourHoursAgo) {
-			recentStart = fourHoursAgo
-		}
-		err := db.Where("client = ? AND time >= ? AND time <= ?", uuid, recentStart, end).Order("time ASC").Find(&recentRecords).Error
-		if err != nil {
-			log.Printf("Error fetching recent records for client %s between %s and %s: %v", uuid, recentStart, end, err)
-			return nil, err
-		}
-	}
-
-	var long_term []models.Record
-	err := db.Table("records_long_term").Where("client = ? AND time >= ? AND time <= ?", uuid, start, end).Order("time ASC").Find(&long_term).Error
-	if err != nil {
-		log.Printf("Error fetching long-term records for client %s between %s and %s: %v", uuid, start, end, err)
-		return recentRecords, nil
-	}
-
-	if len(long_term) == 0 {
-		// 没有查到long_term，返回全部recentRecords
-		records = append(records, recentRecords...)
-		return records, nil
-	}
-
-	// 查到了long_term，recentRecords按15分钟分组，每组只保留一条（取最新一条）
-	grouped := make(map[string]models.Record)
-	for _, rec := range recentRecords {
-		key := rec.Time.ToTime().Truncate(15 * time.Minute).Format(time.RFC3339)
-		if old, ok := grouped[key]; !ok || rec.Time.ToTime().After(old.Time.ToTime()) {
-			grouped[key] = rec
-		}
-	}
-	var groupedList []models.Record
-	for _, rec := range grouped {
-		groupedList = append(groupedList, rec)
-	}
-	sort.Slice(groupedList, func(i, j int) bool {
-		return groupedList[i].Time.ToTime().Before(groupedList[j].Time.ToTime())
-	})
-	records = append(records, groupedList...)
-	records = append(records, long_term...)
-	return records, nil
-}
-
-func GetAllRecords() ([]models.Record, error) {
-	db := dbcore.GetDBInstance()
-	var records []models.Record
-	var long_term []models.Record
-	err := db.Table("records").Order("time ASC").Find(&records).Error
-	if err != nil {
-		log.Printf("Error fetching all records: %v", err)
-		return nil, err
-	}
-	err = db.Table("records_long_term").Order("time ASC").Find(&long_term).Error
-	if err != nil {
-		log.Printf("Error fetching long-term records: %v", err)
-		return records, nil
-	}
-	records = append(records, long_term...)
-	return records, nil
-}
-
-// 压缩数据库
-func CompactRecord() error {
-	db := dbcore.GetDBInstance()
-	err := migrateOldRecords(db)
-	if err != nil {
-		log.Printf("Error migrating old records: %v", err)
-		return err
-	}
-
-	err = migrateGPURecords(db)
-	if err != nil {
-		log.Printf("Error migrating GPU records: %v", err)
-		return err
-	}
-
-	if flags.IsSQLite() {
-		db.Exec("PRAGMA wal_checkpoint(PASSIVE);")
-	}
-	//log.Printf("Record compaction completed")
-	return nil
-}
-
-func migrateOldRecords(db *gorm.DB) error {
-	return migrateOldRecordsAt(db, time.Now())
-}
-
-func compactRecordCutoff(now time.Time) time.Time {
-	return now.Add(-4 * time.Hour).Truncate(15 * time.Minute)
-}
-
-func migrateOldRecordsAt(db *gorm.DB, now time.Time) error {
-	cutoff := compactRecordCutoff(now)
-
-	// 查询 records 表中超过 4 小时的记录
-	var records []models.Record
-	if err := db.Table("records").Where("time < ?", cutoff).Find(&records).Error; err != nil {
-		return err
-	}
-
-	if len(records) == 0 {
+// LoadTypeMetricNames maps the RPC load_type to the stored metrics that back
+// that field. An empty result means "all load metrics" (including temp and
+// unknown values, which stay on the compatible full-query path).
+func LoadTypeMetricNames(loadType string) []string {
+	var names []string
+	switch loadType {
+	case "cpu":
+		return []string{metricstore.MetricCPU}
+	case "gpu":
+		names = []string{metricstore.MetricGPU}
+	case "ram":
+		names = []string{metricstore.MetricRAM}
+	case "swap":
+		names = []string{metricstore.MetricSwap}
+	case "load":
+		names = []string{metricstore.MetricLoad}
+	case "disk":
+		names = []string{metricstore.MetricDisk}
+	case "network":
+		names = []string{metricstore.MetricNetIn, metricstore.MetricNetOut, metricstore.MetricNetTotalUp, metricstore.MetricNetTotalDown}
+	case "process":
+		names = []string{metricstore.MetricProcess}
+	case "connections":
+		names = []string{metricstore.MetricConnections, metricstore.MetricConnectionsUDP}
+	default:
 		return nil
 	}
-
-	// 按 Client 和 15 分钟时间段分组，并存储所有记录以计算分位数
-	type groupData struct {
-		Cpu             []float32
-		Gpu             []float32
-		Load            []float32
-		Temp            []float32
-		Ram             []int64
-		RamTotal        []int64
-		Swap            []int64
-		SwapTotal       []int64
-		Disk            []int64
-		DiskTotal       []int64
-		NetIn           []int64
-		NetOut          []int64
-		NetTotalUp      []int64
-		NetTotalDown    []int64
-		TrafficUp       int64
-		TrafficDown     int64
-		LatestTime      time.Time
-		LatestTotalUp   int64
-		LatestTotalDown int64
-		Process         []int
-		Connections     []int
-		ConnectionsUdp  []int
-		Uptime          []int64
-	}
-
-	groupedRecords := make(map[string]*groupData)
-	for _, record := range records {
-		key := record.Client + "_" + record.Time.ToTime().Truncate(15*time.Minute).Format(time.RFC3339)
-		if _, ok := groupedRecords[key]; !ok {
-			groupedRecords[key] = &groupData{}
-		}
-		data := groupedRecords[key]
-		data.Cpu = append(data.Cpu, record.Cpu)
-		data.Gpu = append(data.Gpu, record.Gpu)
-		data.Load = append(data.Load, record.Load)
-		data.Temp = append(data.Temp, record.Temp)
-		data.Ram = append(data.Ram, record.Ram)
-		data.RamTotal = append(data.RamTotal, record.RamTotal)
-		data.Swap = append(data.Swap, record.Swap)
-		data.SwapTotal = append(data.SwapTotal, record.SwapTotal)
-		data.Disk = append(data.Disk, record.Disk)
-		data.DiskTotal = append(data.DiskTotal, record.DiskTotal)
-		data.NetIn = append(data.NetIn, record.NetIn)
-		data.NetOut = append(data.NetOut, record.NetOut)
-		data.NetTotalUp = append(data.NetTotalUp, record.NetTotalUp)
-		data.NetTotalDown = append(data.NetTotalDown, record.NetTotalDown)
-		data.TrafficUp += record.TrafficUp
-		data.TrafficDown += record.TrafficDown
-		if data.LatestTime.IsZero() || record.Time.ToTime().After(data.LatestTime) {
-			data.LatestTime = record.Time.ToTime()
-			data.LatestTotalUp = record.NetTotalUp
-			data.LatestTotalDown = record.NetTotalDown
-		}
-		data.Process = append(data.Process, record.Process)
-		data.Connections = append(data.Connections, record.Connections)
-		data.ConnectionsUdp = append(data.ConnectionsUdp, record.ConnectionsUdp)
-		//data.Uptime = append(data.Uptime, record.Uptime)
-	}
-
-	getPercentile := func(values []float64, percentile float64) float64 {
-		if len(values) == 0 {
-			return 0
-		}
-		sortedValues := make([]float64, len(values))
-		copy(sortedValues, values)
-		sort.Float64s(sortedValues)
-		index := float64(len(sortedValues)-1) * percentile
-		lowerIndex := int(index)
-		if lowerIndex >= len(sortedValues)-1 {
-			return sortedValues[len(sortedValues)-1]
-		}
-		frac := index - float64(lowerIndex)
-		return sortedValues[lowerIndex] + frac*(sortedValues[lowerIndex+1]-sortedValues[lowerIndex])
-	}
-
-	getIntPercentile := func(values []int64, percentile float64) int64 {
-		if len(values) == 0 {
-			return 0
-		}
-		floats := make([]float64, len(values))
-		for i, v := range values {
-			floats[i] = float64(v)
-		}
-		return int64(getPercentile(floats, percentile))
-	}
-
-	getInt32Percentile := func(values []int, percentile float64) int {
-		if len(values) == 0 {
-			return 0
-		}
-		floats := make([]float64, len(values))
-		for i, v := range values {
-			floats[i] = float64(v)
-		}
-		return int(getPercentile(floats, percentile))
-	}
-
-	return db.Transaction(func(tx *gorm.DB) error {
-		for key, data := range groupedRecords {
-			// 解析 Client 和时间
-			parts := strings.Split(key, "_")
-			clientUUID := parts[0]
-			timeSlot, err := time.Parse(time.RFC3339, strings.Join(parts[1:], "_"))
-			if err != nil {
-				return err
-			}
-
-			cpuFloats := make([]float64, len(data.Cpu))
-			for i, v := range data.Cpu {
-				cpuFloats[i] = float64(v)
-			}
-			gpuFloats := make([]float64, len(data.Gpu))
-			for i, v := range data.Gpu {
-				gpuFloats[i] = float64(v)
-			}
-			loadFloats := make([]float64, len(data.Load))
-			for i, v := range data.Load {
-				loadFloats[i] = float64(v)
-			}
-			tempFloats := make([]float64, len(data.Temp))
-			for i, v := range data.Temp {
-				tempFloats[i] = float64(v)
-			}
-			// 取高位
-			high_percentile := 0.7
-			// 检查 records_long_term 表中是否已存在相同的记录
-			var existingCount int64
-			if err := tx.Table("records_long_term").Where("client = ? AND time = ?", clientUUID, timeSlot).Count(&existingCount).Error; err != nil {
-				return err
-			}
-
-			newRec := models.Record{
-				Client:         clientUUID,
-				Time:           models.FromTime(timeSlot),
-				Cpu:            float32(getPercentile(cpuFloats, high_percentile)),
-				Gpu:            float32(getPercentile(gpuFloats, high_percentile)),
-				Load:           float32(getPercentile(loadFloats, high_percentile)),
-				Temp:           float32(getPercentile(tempFloats, high_percentile)),
-				Ram:            getIntPercentile(data.Ram, high_percentile),
-				RamTotal:       getIntPercentile(data.RamTotal, high_percentile),
-				Swap:           getIntPercentile(data.Swap, high_percentile),
-				SwapTotal:      getIntPercentile(data.SwapTotal, high_percentile),
-				Disk:           getIntPercentile(data.Disk, high_percentile),
-				DiskTotal:      getIntPercentile(data.DiskTotal, high_percentile),
-				NetIn:          getIntPercentile(data.NetIn, 0.2),
-				NetOut:         getIntPercentile(data.NetOut, 0.2),
-				NetTotalUp:     data.LatestTotalUp,
-				NetTotalDown:   data.LatestTotalDown,
-				TrafficUp:      data.TrafficUp,
-				TrafficDown:    data.TrafficDown,
-				Process:        getInt32Percentile(data.Process, high_percentile),
-				Connections:    getInt32Percentile(data.Connections, high_percentile),
-				ConnectionsUdp: getInt32Percentile(data.ConnectionsUdp, high_percentile),
-				//Uptime:         getIntPercentile(data.Uptime, high_percentile),
-			}
-
-			// 如果记录已存在则更新，否则创建新记录
-			if existingCount > 0 {
-				if err := tx.Table("records_long_term").Where("client = ? AND time = ?", clientUUID, timeSlot).Updates(&newRec).Error; err != nil {
-					return err
-				}
-			} else {
-				if err := tx.Table("records_long_term").Create(&newRec).Error; err != nil {
-					return err
-				}
-			}
-		}
-
-		// 删除 records 表中的旧数据
-		if err := tx.Table("records").Where("time < ?", cutoff.Add(-1*time.Hour)).Delete(&models.Record{}).Error; err != nil {
-			return err
-		}
-
-		return nil
-	})
+	// CPU is the common presence anchor: the previous implementation built one
+	// record per timestamp where any load metric existed. Including CPU keeps
+	// those timestamps (and zero values for a missing selected metric) without
+	// going back to all fifteen metrics.
+	return append(names, metricstore.MetricCPU)
 }
 
-// migrateGPURecords 压缩GPU记录数据
-func migrateGPURecords(db *gorm.DB) error {
-	cutoff := compactRecordCutoff(time.Now())
-
-	// 查询超过4小时的GPU记录
-	var gpuRecords []models.GPURecord
-	if err := db.Where("time < ?", cutoff).Find(&gpuRecords).Error; err != nil {
-		return err
+// QueryRecords returns one client's records, or all clients when uuid is empty.
+// Request handlers should use this context-aware entry point.
+func QueryRecords(ctx context.Context, uuid string, start, end time.Time, opts ...RecordQueryOptions) ([]models.Record, error) {
+	if uuid == "" {
+		return metricstore.GetRecordsByTime(ctx, start, end, opts...)
 	}
-
-	if len(gpuRecords) == 0 {
-		return nil
-	}
-
-	// 按Client + DeviceIndex + 15分钟时间窗口分组
-	type gpuGroupKey struct {
-		Client      string
-		DeviceIndex int
-		TimeSlot    time.Time
-		DeviceName  string
-	}
-
-	type gpuGroupData struct {
-		MemTotal    []int64
-		MemUsed     []int64
-		Utilization []float32
-		Temperature []int
-	}
-
-	groupedGPUs := make(map[gpuGroupKey]*gpuGroupData)
-
-	for _, record := range gpuRecords {
-		key := gpuGroupKey{
-			Client:      record.Client,
-			DeviceIndex: record.DeviceIndex,
-			TimeSlot:    record.Time.ToTime().Truncate(15 * time.Minute),
-			DeviceName:  record.DeviceName,
-		}
-
-		if _, ok := groupedGPUs[key]; !ok {
-			groupedGPUs[key] = &gpuGroupData{}
-		}
-
-		data := groupedGPUs[key]
-		data.MemTotal = append(data.MemTotal, record.MemTotal)
-		data.MemUsed = append(data.MemUsed, record.MemUsed)
-		data.Utilization = append(data.Utilization, record.Utilization)
-		data.Temperature = append(data.Temperature, record.Temperature)
-	}
-
-	// 百分位数计算函数 (复用传统Record压缩逻辑)
-	getPercentile := func(values []float64, percentile float64) float64 {
-		if len(values) == 0 {
-			return 0
-		}
-		sortedValues := make([]float64, len(values))
-		copy(sortedValues, values)
-		sort.Float64s(sortedValues)
-		index := float64(len(sortedValues)-1) * percentile
-		lowerIndex := int(index)
-		if lowerIndex >= len(sortedValues)-1 {
-			return sortedValues[len(sortedValues)-1]
-		}
-		frac := index - float64(lowerIndex)
-		return sortedValues[lowerIndex] + frac*(sortedValues[lowerIndex+1]-sortedValues[lowerIndex])
-	}
-
-	getIntPercentile := func(values []int64, percentile float64) int64 {
-		if len(values) == 0 {
-			return 0
-		}
-		floats := make([]float64, len(values))
-		for i, v := range values {
-			floats[i] = float64(v)
-		}
-		return int64(getPercentile(floats, percentile))
-	}
-
-	// 温度数据转换辅助函数
-	convertIntToInt64 := func(values []int) []int64 {
-		result := make([]int64, len(values))
-		for i, v := range values {
-			result[i] = int64(v)
-		}
-		return result
-	}
-
-	getFloat32Percentile := func(values []float32, percentile float64) float32 {
-		if len(values) == 0 {
-			return 0
-		}
-		floats := make([]float64, len(values))
-		for i, v := range values {
-			floats[i] = float64(v)
-		}
-		return float32(getPercentile(floats, percentile))
-	}
-
-	// 保持与传统Record压缩的一致性
-	high_percentile := 0.7
-
-	return db.Transaction(func(tx *gorm.DB) error {
-		for key, data := range groupedGPUs {
-			// 检查是否已存在记录
-			var existingCount int64
-			if err := tx.Table("gpu_records_long_term").Where("client = ? AND device_index = ? AND time = ?",
-				key.Client, key.DeviceIndex, key.TimeSlot).Count(&existingCount).Error; err != nil {
-				return err
-			}
-
-			compressedGPU := models.GPURecord{
-				Client:      key.Client,
-				DeviceIndex: key.DeviceIndex,
-				Time:        models.FromTime(key.TimeSlot),
-				DeviceName:  key.DeviceName,
-				MemTotal:    getIntPercentile(data.MemTotal, high_percentile),
-				MemUsed:     getIntPercentile(data.MemUsed, high_percentile),
-				Utilization: getFloat32Percentile(data.Utilization, high_percentile),
-				Temperature: int(getIntPercentile(convertIntToInt64(data.Temperature), high_percentile)),
-			}
-
-			if existingCount > 0 {
-				// 更新已存在记录
-				if err := tx.Table("gpu_records_long_term").Where("client = ? AND device_index = ? AND time = ?",
-					key.Client, key.DeviceIndex, key.TimeSlot).Updates(&compressedGPU).Error; err != nil {
-					return err
-				}
-			} else {
-				// 创建新记录
-				if err := tx.Table("gpu_records_long_term").Create(&compressedGPU).Error; err != nil {
-					return err
-				}
-			}
-		}
-
-		// 删除已压缩的原始GPU数据
-		if err := tx.Where("time < ?", cutoff.Add(-1*time.Hour)).Delete(&models.GPURecord{}).Error; err != nil {
-			return err
-		}
-
-		return nil
-	})
+	return metricstore.GetRecordsByClientAndTime(ctx, uuid, start, end, opts...)
+}
+
+// GetRecordsByClientAndTime is a compatibility-only wrapper without cancellation.
+// New request handlers should use QueryRecords.
+func GetRecordsByClientAndTime(uuid string, start, end time.Time, opts ...RecordQueryOptions) ([]models.Record, error) {
+	return metricstore.GetRecordsByClientAndTime(context.Background(), uuid, start, end, opts...)
+}
+
+// GetRecordMetricMaxByClientAndTime is a compatibility-only wrapper without cancellation.
+// New request handlers should use metricstore.GetRecordMetricMaxByClientAndTime.
+func GetRecordMetricMaxByClientAndTime(uuid, metricName string, start, end time.Time) ([]models.Record, error) {
+	return metricstore.GetRecordMetricMaxByClientAndTime(context.Background(), uuid, metricName, start, end)
+}
+
+// GetRecordsByTime is a compatibility-only wrapper without cancellation.
+// New request handlers should use QueryRecords with an empty uuid.
+func GetRecordsByTime(start, end time.Time, opts ...RecordQueryOptions) ([]models.Record, error) {
+	return metricstore.GetRecordsByTime(context.Background(), start, end, opts...)
 }

database/records/records_test.go

@@ -1,234 +0,0 @@
-package records
-
-import (
-	"encoding/csv"
-	"os"
-	"strconv"
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/assert"
-	"gorm.io/driver/sqlite"
-	"gorm.io/gorm"
-
-	"github.com/komari-monitor/komari/database/models"
-)
-
-var uuid = "7901508c-304f-49aa-b84f-957c33ae6f8a"
-
-var _ = func() bool {
-	// 确保 Test 环境中使用 sqlite 内存数据库
-	return true
-}()
-
-// TestCompactRecord tests the database compaction logic by inserting 4h30m of data (one record per minute),
-// then running migrateOldRecords and verifying the aggregation and cleanup.
-func TestCompactRecord(t *testing.T) {
-	const totalMinutes = 12*60 + 30
-	now := time.Now().UTC().Truncate(time.Minute)
-	threshold := compactRecordCutoff(now)
-	overlapCutoff := threshold.Add(-1 * time.Hour)
-
-	// 使用 sqlite 内存数据库并迁移表结构
-	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
-	assert.NoError(t, err)
-	assert.NoError(t, db.AutoMigrate(&models.Record{}))
-	assert.NoError(t, db.Table("records_long_term").AutoMigrate(&models.Record{}))
-
-	expectedGroups := make(map[time.Time]struct{})
-	expectedRawRemain := 0
-
-	// 插入数据
-	for i := 0; i < totalMinutes; i++ {
-		recTime := now.Add(-time.Duration(i) * time.Minute)
-		rec := models.Record{Client: uuid, Time: models.FromTime(recTime), Cpu: float32(i), Gpu: float32(i), Load: float32(i), Temp: float32(i), Ram: int64(i)}
-		err := db.Create(&rec).Error
-		assert.NoError(t, err)
-
-		if recTime.Before(threshold) {
-			slot := recTime.Truncate(15 * time.Minute)
-			expectedGroups[slot] = struct{}{}
-		}
-		if !recTime.Before(overlapCutoff) {
-			expectedRawRemain++
-		}
-	}
-
-	// 导出原始数据到 CSV
-	os.MkdirAll("../../data", 0755)
-	var origRecs []models.Record
-	db.Order("time desc").Find(&origRecs)
-	fOrig, err := os.Create("../../data/original.csv")
-	assert.NoError(t, err)
-	defer fOrig.Close()
-	wOrig := csv.NewWriter(fOrig)
-	defer wOrig.Flush()
-	wOrig.Write([]string{"Client", "Time", "Cpu", "Gpu", "Load", "Temp", "Ram"})
-	for _, r := range origRecs {
-		wOrig.Write([]string{
-			r.Client,
-			r.Time.ToTime().Format(time.RFC3339),
-			strconv.FormatFloat(float64(r.Cpu), 'f', -1, 32),
-			strconv.FormatFloat(float64(r.Gpu), 'f', -1, 32),
-			strconv.FormatFloat(float64(r.Load), 'f', -1, 32),
-			strconv.FormatFloat(float64(r.Temp), 'f', -1, 32),
-			strconv.FormatInt(r.Ram, 10),
-		})
-	}
-
-	// 运行压缩（迁移）逻辑
-	err = migrateOldRecordsAt(db, now)
-	assert.NoError(t, err)
-
-	// 验证 long-term 表中的聚合记录数
-	var longCount int64
-	assert.NoError(t, db.Table("records_long_term").Count(&longCount).Error)
-	assert.Equal(t, int64(len(expectedGroups)), longCount)
-
-	// 验证原始表中剩余记录数
-	var remainCount int64
-	assert.NoError(t, db.Table("records").Count(&remainCount).Error)
-	assert.Equal(t, int64(expectedRawRemain), remainCount)
-
-	// 导出压缩后的数据到 CSV
-	var compRecs []models.Record
-	db.Table("records_long_term").Order("time desc").Find(&compRecs)
-	fComp, err := os.Create("../../data/compressed.csv")
-	assert.NoError(t, err)
-	defer fComp.Close()
-	wComp := csv.NewWriter(fComp)
-	defer wComp.Flush()
-	wComp.Write([]string{"Client", "Time", "Cpu", "Gpu", "Load", "Temp", "Ram"})
-	for _, r := range compRecs {
-		wComp.Write([]string{
-			r.Client,
-			r.Time.ToTime().Format(time.RFC3339),
-			strconv.FormatFloat(float64(r.Cpu), 'f', -1, 32),
-			strconv.FormatFloat(float64(r.Gpu), 'f', -1, 32),
-			strconv.FormatFloat(float64(r.Load), 'f', -1, 32),
-			strconv.FormatFloat(float64(r.Temp), 'f', -1, 32),
-			strconv.FormatInt(r.Ram, 10),
-		})
-	}
-
-	db.Table("records").Order("time desc").Find(&compRecs)
-	fComp, err = os.Create("../../data/compressed_records.csv")
-	assert.NoError(t, err)
-	defer fComp.Close()
-	wComp = csv.NewWriter(fComp)
-	defer wComp.Flush()
-	wComp.Write([]string{"Client", "Time", "Cpu", "Gpu", "Load", "Temp", "Ram"})
-	for _, r := range compRecs {
-		wComp.Write([]string{
-			r.Client,
-			r.Time.ToTime().Format(time.RFC3339),
-			strconv.FormatFloat(float64(r.Cpu), 'f', -1, 32),
-			strconv.FormatFloat(float64(r.Gpu), 'f', -1, 32),
-			strconv.FormatFloat(float64(r.Load), 'f', -1, 32),
-			strconv.FormatFloat(float64(r.Temp), 'f', -1, 32),
-			strconv.FormatInt(r.Ram, 10),
-		})
-	}
-}
-
-func TestCompactRecordPreservesExactTrafficDelta(t *testing.T) {
-	currentTime := time.Now().UTC().Truncate(time.Minute)
-	now := currentTime.Truncate(15 * time.Minute).Add(-5*time.Hour + time.Minute)
-	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
-	assert.NoError(t, err)
-	assert.NoError(t, db.AutoMigrate(&models.Record{}))
-	assert.NoError(t, db.Table("records_long_term").AutoMigrate(&models.Record{}))
-
-	records := []models.Record{
-		{
-			Client:       uuid,
-			Time:         models.FromTime(now),
-			NetTotalUp:   100,
-			NetTotalDown: 200,
-			TrafficUp:    0,
-			TrafficDown:  0,
-		},
-		{
-			Client:       uuid,
-			Time:         models.FromTime(now.Add(5 * time.Minute)),
-			NetTotalUp:   150,
-			NetTotalDown: 260,
-			TrafficUp:    50,
-			TrafficDown:  60,
-		},
-		{
-			Client:       uuid,
-			Time:         models.FromTime(now.Add(10 * time.Minute)),
-			NetTotalUp:   10,
-			NetTotalDown: 30,
-			TrafficUp:    10,
-			TrafficDown:  30,
-		},
-	}
-
-	for _, rec := range records {
-		assert.NoError(t, db.Create(&rec).Error)
-	}
-
-	assert.NoError(t, migrateOldRecordsAt(db, currentTime))
-
-	var compacted []models.Record
-	assert.NoError(t, db.Table("records_long_term").Find(&compacted).Error)
-	assert.Len(t, compacted, 1)
-	assert.Equal(t, int64(60), compacted[0].TrafficUp)
-	assert.Equal(t, int64(90), compacted[0].TrafficDown)
-	assert.Equal(t, int64(10), compacted[0].NetTotalUp)
-	assert.Equal(t, int64(30), compacted[0].NetTotalDown)
-	assert.True(t, compacted[0].Time.ToTime().Equal(records[2].Time.ToTime().Truncate(15*time.Minute)))
-}
-
-func TestCompactRecordRetainsOneHourOverlapWindow(t *testing.T) {
-	now := time.Date(2026, 6, 7, 12, 7, 0, 0, time.UTC)
-	cutoff := compactRecordCutoff(now)
-	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
-	assert.NoError(t, err)
-	assert.NoError(t, db.AutoMigrate(&models.Record{}))
-	assert.NoError(t, db.Table("records_long_term").AutoMigrate(&models.Record{}))
-
-	records := []models.Record{
-		{Client: uuid, Time: models.FromTime(cutoff.Add(-time.Hour - time.Minute)), TrafficUp: 5},
-		{Client: uuid, Time: models.FromTime(cutoff.Add(-30 * time.Minute)), TrafficUp: 7},
-		{Client: uuid, Time: models.FromTime(now.Add(-3 * time.Hour)), TrafficUp: 11},
-	}
-	for _, rec := range records {
-		assert.NoError(t, db.Create(&rec).Error)
-	}
-
-	assert.NoError(t, migrateOldRecordsAt(db, now))
-
-	var remainTimes []models.Record
-	assert.NoError(t, db.Table("records").Order("time ASC").Find(&remainTimes).Error)
-	assert.Len(t, remainTimes, 2)
-	assert.True(t, remainTimes[0].Time.ToTime().Equal(records[1].Time.ToTime()))
-	assert.True(t, remainTimes[1].Time.ToTime().Equal(records[2].Time.ToTime()))
-}
-
-func TestCompactRecordOnlyMigratesCompleteFifteenMinuteBuckets(t *testing.T) {
-	now := time.Date(2026, 6, 7, 12, 7, 0, 0, time.UTC)
-	cutoff := compactRecordCutoff(now)
-	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
-	assert.NoError(t, err)
-	assert.NoError(t, db.AutoMigrate(&models.Record{}))
-	assert.NoError(t, db.Table("records_long_term").AutoMigrate(&models.Record{}))
-
-	compactable := models.Record{Client: uuid, Time: models.FromTime(cutoff.Add(-time.Minute)), TrafficUp: 5}
-	partialSlot := models.Record{Client: uuid, Time: models.FromTime(cutoff.Add(time.Minute)), TrafficUp: 7}
-	assert.NoError(t, db.Create(&compactable).Error)
-	assert.NoError(t, db.Create(&partialSlot).Error)
-
-	assert.NoError(t, migrateOldRecordsAt(db, now))
-
-	var compacted []models.Record
-	assert.NoError(t, db.Table("records_long_term").Order("time ASC").Find(&compacted).Error)
-	assert.Len(t, compacted, 1)
-	assert.True(t, compacted[0].Time.ToTime().Equal(compactable.Time.ToTime().Truncate(15*time.Minute)))
-
-	var rawCount int64
-	assert.NoError(t, db.Table("records").Where("time = ?", partialSlot.Time).Count(&rawCount).Error)
-	assert.Equal(t, int64(1), rawCount)
-}

database/tasks/ping.go

@@ -1,10 +1,13 @@
 package tasks
 
 import (
-	"time"
+	"context"
+	"slices"
+	"sort"
 
 	"github.com/komari-monitor/komari/database/dbcore"
 	"github.com/komari-monitor/komari/database/models"
+	"github.com/komari-monitor/komari/internal/metricstore"
 	"github.com/komari-monitor/komari/utils"
 	"gorm.io/gorm"
 )
@@ -25,17 +28,8 @@ func AddPingTask(clients []string, defaultOn bool, name string, target, task_typ
 		if err := tx.Create(&task).Error; err != nil {
 			return err
 		}
-
 		// Append by id to avoid races between concurrent create requests.
-		result := tx.Model(&models.PingTask{}).Where("id = ?", task.Id).Update("weight", int(task.Id))
-		if result.Error != nil {
-			return result.Error
-		}
-		if result.RowsAffected == 0 {
-			return gorm.ErrRecordNotFound
-		}
-
-		return nil
+		return tx.Model(&models.PingTask{}).Where("id = ?", task.Id).Update("weight", int(task.Id)).Error
 	})
 	if err != nil {
 		return 0, err
@@ -45,6 +39,12 @@ func AddPingTask(clients []string, defaultOn bool, name string, target, task_typ
 }
 
 func DeletePingTask(id []uint) error {
+	// The metric store is independent from the main database, so clean it first
+	// to avoid leaving history that can no longer be addressed through the task.
+	if err := DeletePingRecords(id); err != nil {
+		return err
+	}
+
 	db := dbcore.GetDBInstance()
 	result := db.Where("id IN ?", id).Delete(&models.PingTask{})
 	if result.RowsAffected == 0 {
@@ -98,22 +98,39 @@ func GetAllPingTasks() ([]models.PingTask, error) {
 func GetPingTasksByClient(uuid string) []models.PingTask {
 	db := dbcore.GetDBInstance()
 	var tasks []models.PingTask
-	if err := db.Where("clients LIKE ?", `%"`+uuid+`"%`).Find(&tasks).Error; err != nil {
+	if err := db.Where("clients LIKE ?", `%"`+uuid+`"%`).Order("weight ASC").Order("id ASC").Find(&tasks).Error; err != nil {
 		return nil
 	}
 	return tasks
 }
 
 func UpdatePingTaskOrder(order map[uint]int) error {
+	if len(order) == 0 {
+		return nil
+	}
+
 	db := dbcore.GetDBInstance()
 	err := db.Transaction(func(tx *gorm.DB) error {
-		for id, weight := range order {
-			result := tx.Model(&models.PingTask{}).Where("id = ?", id).Update("weight", weight)
-			if result.Error != nil {
-				return result.Error
-			}
-			if result.RowsAffected == 0 {
-				return gorm.ErrRecordNotFound
+		// Validate all ids before changing any weights. The update response is
+		// not a reliable existence check because some drivers report zero rows
+		// when the new value equals the current value.
+		ids := make([]uint, 0, len(order))
+		for id := range order {
+			ids = append(ids, id)
+		}
+		sort.Slice(ids, func(i, j int) bool { return ids[i] < ids[j] })
+
+		var existing int64
+		if err := tx.Model(&models.PingTask{}).Where("id IN ?", ids).Count(&existing).Error; err != nil {
+			return err
+		}
+		if existing != int64(len(ids)) {
+			return gorm.ErrRecordNotFound
+		}
+
+		for _, id := range ids {
+			if err := tx.Model(&models.PingTask{}).Where("id = ?", id).Update("weight", order[id]).Error; err != nil {
+				return err
 			}
 		}
 		return nil
@@ -125,38 +142,24 @@ func UpdatePingTaskOrder(order map[uint]int) error {
 	return nil
 }
 
-func SavePingRecord(record models.PingRecord) error {
-	db := dbcore.GetDBInstance()
-	return db.Create(&record).Error
-}
+// ping 记录已完全迁移到 metric store（指标 ping.latency_ms），运行期读写全部走
+// metric store，旧 ping_records 表不再参与。
 
-func DeletePingRecordsBefore(time time.Time) error {
-	db := dbcore.GetDBInstance()
-	err := db.Where("time < ?", time).Delete(&models.PingRecord{}).Error
-	return err
+func SavePingRecord(record models.PingRecord) error {
+	return metricstore.WritePingRecord(context.Background(), record)
 }
 
 func DeletePingRecords(id []uint) error {
-	db := dbcore.GetDBInstance()
-	result := db.Where("task_id IN ?", id).Delete(&models.PingRecord{})
-	if result.RowsAffected == 0 {
-		return gorm.ErrRecordNotFound
-	}
-	return result.Error
+	return metricstore.DeletePingRecordsByTask(context.Background(), id)
 }
 
 func DeleteAllPingRecords() error {
-	db := dbcore.GetDBInstance()
-	result := db.Exec("DELETE FROM ping_records")
-	if result.RowsAffected == 0 {
-		return gorm.ErrRecordNotFound
-	}
-	return result.Error
+	return metricstore.DeleteAllPingRecords(context.Background())
 }
+
 func ReloadPingSchedule() error {
-	db := dbcore.GetDBInstance()
-	var pingTasks []models.PingTask
-	if err := db.Find(&pingTasks).Error; err != nil {
+	pingTasks, err := GetAllPingTasks()
+	if err != nil {
 		return err
 	}
 	return utils.ReloadPingSchedule(pingTasks)
@@ -164,27 +167,14 @@ func ReloadPingSchedule() error {
 
 // AddDefaultOnClientUUID 在新客户端注册后，把该 UUID 追加到所有 default_on=true 的任务的 clients 中（去重）。
 func AddDefaultOnClientUUID(uuid string) error {
-	if uuid == "" {
-		return nil
-	}
 	db := dbcore.GetDBInstance()
 	var tasks []models.PingTask
 	if err := db.Where("all_clients = ?", true).Find(&tasks).Error; err != nil {
 		return err
 	}
-	if len(tasks) == 0 {
-		return nil
-	}
 	changed := false
 	for _, task := range tasks {
-		exists := false
-		for _, c := range task.Clients {
-			if c == uuid {
-				exists = true
-				break
-			}
-		}
-		if exists {
+		if slices.Contains(task.Clients, uuid) {
 			continue
 		}
 		next := append(models.StringArray{}, task.Clients...)
@@ -199,19 +189,3 @@ func AddDefaultOnClientUUID(uuid string) error {
 	}
 	return nil
 }
-
-func GetPingRecords(uuid string, taskId int, start, end time.Time) ([]models.PingRecord, error) {
-	db := dbcore.GetDBInstance()
-	var records []models.PingRecord
-	dbQuery := db.Model(&models.PingRecord{})
-	if uuid != "" {
-		dbQuery = dbQuery.Where("client = ?", uuid)
-	}
-	if taskId >= 0 {
-		dbQuery = dbQuery.Where("task_id = ?", uint(taskId))
-	}
-	if err := dbQuery.Where("time >= ? AND time <= ?", start, end).Order("time DESC").Find(&records).Error; err != nil {
-		return nil, err
-	}
-	return records, nil
-}

database/tasks/ping_summary.go

@@ -0,0 +1,180 @@
+package tasks
+
+import (
+	"math"
+	"sort"
+	"time"
+
+	"github.com/komari-monitor/komari/database/models"
+	"github.com/komari-monitor/komari/internal/sampling"
+)
+
+// PingClientSummary is the per-client aggregate shared by ping RPC adapters.
+type PingClientSummary struct {
+	Total       int
+	Loss        int
+	Min         int
+	Max         int
+	LossPercent float64
+}
+
+// PingTaskSummary is the per-task aggregate shared by ping RPC adapters.
+type PingTaskSummary struct {
+	Total       int
+	Loss        int
+	Valid       int
+	Min         int
+	Max         int
+	Avg         int
+	Latest      int
+	P50         int
+	P99         int
+	LossPercent float64
+	P99P50Ratio float64
+}
+
+// PingSummary aggregates records once so legacy and public ping handlers only
+// differ in response shape.
+type PingSummary struct {
+	Clients map[string]PingClientSummary
+	Tasks   map[uint]PingTaskSummary
+}
+
+type pingClientAccumulator struct {
+	total, loss, min, max int
+}
+
+type pingTaskAccumulator struct {
+	total, loss, min, max, sum, valid int
+	latest                            int
+	latestTime                        time.Time
+	latencies                         []int
+}
+
+// SummarizePingRecords computes client and task aggregates in one pass.
+func SummarizePingRecords(recs []models.PingRecord) PingSummary {
+	clients := make(map[string]*pingClientAccumulator)
+	taskMap := make(map[uint]*pingTaskAccumulator)
+	for _, r := range recs {
+		cs := clients[r.Client]
+		if cs == nil {
+			cs = &pingClientAccumulator{}
+			clients[r.Client] = cs
+		}
+		cs.total++
+		ts := taskMap[r.TaskId]
+		if ts == nil {
+			ts = &pingTaskAccumulator{latest: -1}
+			taskMap[r.TaskId] = ts
+		}
+		ts.total++
+		if r.Value < 0 {
+			cs.loss++
+			ts.loss++
+			continue
+		}
+		if cs.min == 0 || r.Value < cs.min {
+			cs.min = r.Value
+		}
+		if r.Value > cs.max {
+			cs.max = r.Value
+		}
+		ts.valid++
+		ts.sum += r.Value
+		if ts.min == 0 || r.Value < ts.min {
+			ts.min = r.Value
+		}
+		if r.Value > ts.max {
+			ts.max = r.Value
+		}
+		if ts.latestTime.IsZero() || r.Time.After(ts.latestTime) {
+			ts.latestTime = r.Time
+			ts.latest = r.Value
+		}
+		ts.latencies = append(ts.latencies, r.Value)
+	}
+
+	out := PingSummary{Clients: make(map[string]PingClientSummary, len(clients)), Tasks: make(map[uint]PingTaskSummary, len(taskMap))}
+	for client, v := range clients {
+		loss := 0.0
+		if v.total > 0 {
+			loss = float64(v.loss) / float64(v.total) * 100
+		}
+		out.Clients[client] = PingClientSummary{Total: v.total, Loss: v.loss, Min: v.min, Max: v.max, LossPercent: loss}
+	}
+	for id, v := range taskMap {
+		loss := 0.0
+		if v.total > 0 {
+			loss = float64(v.loss) / float64(v.total) * 100
+		}
+		avg := 0
+		if v.valid > 0 {
+			avg = v.sum / v.valid
+		}
+		p50, p99 := pingPercentiles(v.latencies)
+		ratio := 0.0
+		if p50 > 0 && p99 >= p50 {
+			adjustedBase := math.Max(math.Min(float64(p50), 50.0), 10.0)
+			ratio = float64(p99-p50) / adjustedBase
+		}
+		out.Tasks[id] = PingTaskSummary{
+			Total: v.total, Loss: v.loss, Valid: v.valid, Min: v.min, Max: v.max,
+			Avg: avg, Latest: v.latest, P50: p50, P99: p99, LossPercent: loss, P99P50Ratio: ratio,
+		}
+	}
+	return out
+}
+
+// SamplePingRecordsByTask applies the legacy ping maxCount policy: allocate
+// points proportionally by task, sample each task evenly and return ascending
+// by time. Statistics must be computed from the unsampled records.
+func SamplePingRecordsByTask(recs []models.PingRecord, maxCount int) []models.PingRecord {
+	if maxCount <= 0 || len(recs) <= maxCount {
+		return recs
+	}
+	groups := make(map[uint][]models.PingRecord)
+	for _, r := range recs {
+		groups[r.TaskId] = append(groups[r.TaskId], r)
+	}
+	meta := make([]sampling.Group[uint], 0, len(groups))
+	for id, points := range groups {
+		sort.Slice(points, func(i, j int) bool { return points[i].Time.Before(points[j].Time) })
+		groups[id] = points
+		meta = append(meta, sampling.Group[uint]{Key: id, Length: len(points)})
+	}
+	targets := sampling.AllocateTargets(meta, maxCount)
+	out := make([]models.PingRecord, 0, maxCount)
+	for id, points := range groups {
+		out = append(out, sampling.SampleEvenly(points, targets[id])...)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Time.Before(out[j].Time) })
+	return out
+}
+
+func pingPercentiles(values []int) (int, int) {
+	if len(values) == 0 {
+		return 0, 0
+	}
+	sort.Ints(values)
+	return pingPercentile(values, 0.50), pingPercentile(values, 0.99)
+}
+
+func pingPercentile(values []int, percentile float64) int {
+	if len(values) == 0 {
+		return 0
+	}
+	if percentile <= 0 {
+		return values[0]
+	}
+	if percentile >= 1 {
+		return values[len(values)-1]
+	}
+	pos := float64(len(values)-1) * percentile
+	lo := int(math.Floor(pos))
+	hi := int(math.Ceil(pos))
+	if lo == hi {
+		return values[lo]
+	}
+	frac := pos - float64(lo)
+	return int(math.Round(float64(values[lo]) + (float64(values[hi])-float64(values[lo]))*frac))
+}

database/tasks/tasks.go

@@ -9,7 +9,6 @@ import (
 
 func CreateTask(taskId string, clients []string, command string) error {
 	db := dbcore.GetDBInstance()
-	// Create a new task in the database with clients as JSON array
 	task := models.Task{
 		TaskId:  taskId,
 		Clients: models.StringArray(clients),
@@ -26,13 +25,13 @@ func CreateTask(taskId string, clients []string, command string) error {
 			Result:     "",
 			ExitCode:   nil,
 			FinishedAt: nil,
-			CreatedAt:  models.FromTime(time.Now()),
+			CreatedAt:  time.Now().UTC(),
 		})
 	}
-	if len(taskResults) > 0 {
-		return db.Create(&taskResults).Error
+	if len(taskResults) == 0 {
+		return nil
 	}
-	return nil
+	return db.Create(&taskResults).Error
 }
 func GetTaskByTaskId(taskId string) (*models.Task, error) {
 	var task models.Task
@@ -57,13 +56,6 @@ func GetSpecificTaskResult(taskId, clientId string) (*models.TaskResult, error)
 	return &result, nil
 }
 
-func GetAllTasksResultByUUID(uuid string) ([]models.TaskResult, error) {
-	var results []models.TaskResult
-	if err := dbcore.GetDBInstance().Where("client = ?", uuid).Find(&results).Error; err != nil {
-		return nil, err
-	}
-	return results, nil
-}
 func GetAllTasks() ([]models.Task, error) {
 	var tasks []models.Task
 	if err := dbcore.GetDBInstance().Find(&tasks).Error; err != nil {
@@ -79,21 +71,17 @@ func GetTaskResultsByTaskId(taskId string) ([]models.TaskResult, error) {
 	}
 	return results, nil
 }
-func DeleteTaskByTaskId(taskId string) error {
-	return dbcore.GetDBInstance().Where("task_id = ?", taskId).Delete(&models.Task{}).Error
-}
-
-func SaveTaskResult(taskId, clientId, result string, exitCode int, timestamp models.LocalTime) error {
+func SaveTaskResult(taskId, clientId, result string, exitCode int, timestamp time.Time) error {
 	return dbcore.GetDBInstance().
 		Model(&models.TaskResult{}).
 		Where("task_id = ? AND client = ?", taskId, clientId).
 		Updates(map[string]interface{}{
 			"result":      result,
 			"exit_code":   exitCode,
-			"finished_at": timestamp,
+			"finished_at": timestamp.UTC(),
 		}).Error
 }
 
 func ClearTaskResultsByTimeBefore(before time.Time) error {
-	return dbcore.GetDBInstance().Where("created_at < ?", before.Format(time.RFC3339)).Delete(&models.TaskResult{}).Error
+	return dbcore.GetDBInstance().Where("created_at < ?", before.UTC()).Delete(&models.TaskResult{}).Error
 }

database/tasks/tasks_test.go

@@ -0,0 +1,170 @@
+package tasks
+
+import (
+	"os"
+	"testing"
+	"time"
+
+	"github.com/komari-monitor/komari/cmd/flags"
+	"github.com/komari-monitor/komari/database/dbcore"
+	"github.com/komari-monitor/komari/database/models"
+)
+
+func TestClearTaskResultsByTimeBeforeUsesUTCTimeValue(t *testing.T) {
+	resetTaskTables(t)
+	db := dbcore.GetDBInstance()
+
+	taskID := "task-cleanup-time"
+	if err := db.Create(&models.Task{TaskId: taskID, Command: "true"}).Error; err != nil {
+		t.Fatalf("create task: %v", err)
+	}
+	cutoff := time.Date(2026, 7, 17, 12, 0, 0, 123456789, time.UTC)
+	results := []models.TaskResult{
+		{TaskId: taskID, Client: "old", CreatedAt: cutoff.Add(-time.Nanosecond)},
+		{TaskId: taskID, Client: "boundary", CreatedAt: cutoff},
+		{TaskId: taskID, Client: "new", CreatedAt: cutoff.Add(time.Nanosecond)},
+	}
+	if err := db.Create(&results).Error; err != nil {
+		t.Fatalf("create task results: %v", err)
+	}
+
+	localCutoff := cutoff.In(time.FixedZone("UTC+8", 8*60*60))
+	if err := ClearTaskResultsByTimeBefore(localCutoff); err != nil {
+		t.Fatalf("clear task results: %v", err)
+	}
+	var remaining []models.TaskResult
+	if err := db.Where("task_id = ?", taskID).Order("created_at").Find(&remaining).Error; err != nil {
+		t.Fatalf("load remaining results: %v", err)
+	}
+	if len(remaining) != 2 || remaining[0].Client != "boundary" || remaining[1].Client != "new" {
+		t.Fatalf("remaining results = %#v, want boundary and new", remaining)
+	}
+}
+
+func TestGetAllPingTasksOrdersByWeightThenID(t *testing.T) {
+	resetTaskTables(t)
+	db := dbcore.GetDBInstance()
+
+	tasks := []models.PingTask{
+		{Name: "third", Weight: 2, Type: "icmp", Target: "third.example", Interval: 60},
+		{Name: "first", Weight: 0, Type: "icmp", Target: "first.example", Interval: 60},
+		{Name: "second", Weight: 0, Type: "icmp", Target: "second.example", Interval: 60},
+	}
+	if err := db.Create(&tasks).Error; err != nil {
+		t.Fatalf("create ping tasks: %v", err)
+	}
+
+	ordered, err := GetAllPingTasks()
+	if err != nil {
+		t.Fatalf("get ordered ping tasks: %v", err)
+	}
+	if len(ordered) != len(tasks) {
+		t.Fatalf("ordered ping task count = %d, want %d", len(ordered), len(tasks))
+	}
+	if ordered[0].Id != tasks[1].Id || ordered[1].Id != tasks[2].Id || ordered[2].Id != tasks[0].Id {
+		t.Fatalf("ping task order = %#v, want ids [%d %d %d]", ordered, tasks[1].Id, tasks[2].Id, tasks[0].Id)
+	}
+}
+
+func TestUpdatePingTaskOrderAllowsUnchangedWeights(t *testing.T) {
+	resetTaskTables(t)
+	db := dbcore.GetDBInstance()
+
+	items := []models.PingTask{
+		{Name: "first", Weight: 0, Type: "icmp", Target: "first.example", Interval: 60},
+		{Name: "second", Weight: 1, Type: "icmp", Target: "second.example", Interval: 60},
+	}
+	if err := db.Create(&items).Error; err != nil {
+		t.Fatalf("create ping tasks: %v", err)
+	}
+
+	if err := UpdatePingTaskOrder(map[uint]int{
+		items[0].Id: 0,
+		items[1].Id: 2,
+	}); err != nil {
+		t.Fatalf("update ping task order: %v", err)
+	}
+
+	var first, second models.PingTask
+	if err := db.First(&first, items[0].Id).Error; err != nil {
+		t.Fatalf("load first ping task: %v", err)
+	}
+	if err := db.First(&second, items[1].Id).Error; err != nil {
+		t.Fatalf("load second ping task: %v", err)
+	}
+	if first.Weight != 0 || second.Weight != 2 {
+		t.Fatalf("weights = [%d, %d], want [0, 2]", first.Weight, second.Weight)
+	}
+}
+
+func TestGetPingTasksByClientOrdersByWeightThenID(t *testing.T) {
+	resetTaskTables(t)
+	db := dbcore.GetDBInstance()
+
+	items := []models.PingTask{
+		{Name: "third", Weight: 2, Clients: models.StringArray{"node-a"}, Type: "icmp", Target: "third.example", Interval: 60},
+		{Name: "first", Weight: 0, Clients: models.StringArray{"node-a"}, Type: "icmp", Target: "first.example", Interval: 60},
+		{Name: "other", Weight: 1, Clients: models.StringArray{"node-b"}, Type: "icmp", Target: "other.example", Interval: 60},
+	}
+	if err := db.Create(&items).Error; err != nil {
+		t.Fatalf("create ping tasks: %v", err)
+	}
+
+	ordered := GetPingTasksByClient("node-a")
+	if len(ordered) != 2 || ordered[0].Id != items[1].Id || ordered[1].Id != items[0].Id {
+		t.Fatalf("ping task order = %#v, want ids [%d %d]", ordered, items[1].Id, items[0].Id)
+	}
+}
+
+// TestMain pins a single shared in-memory database. dbcore.Initialize runs
+// once per process, so per-test DSN assignment would be ignored and leave the
+// tests fighting over whichever DSN happened to win.
+func TestMain(m *testing.M) {
+
+	flags.DatabaseType = flags.DatabaseTypeSQLite
+
+	flags.DatabaseFile = "file:komari_tasks_test?mode=memory&cache=shared"
+
+	db := dbcore.GetDBInstance()
+
+	if sqlDB, err := db.DB(); err == nil {
+
+		sqlDB.SetMaxOpenConns(1)
+
+	}
+
+	os.Exit(m.Run())
+
+}
+
+// resetTaskTables clears the shared in-memory tables so repeated runs and
+// shuffled execution start from a clean slate.
+func resetTaskTables(t *testing.T) {
+
+	t.Helper()
+
+	db := dbcore.GetDBInstance()
+
+	for _, model := range []any{&models.Task{}, &models.TaskResult{}, &models.PingTask{}} {
+
+		if err := db.Where("1 = 1").Delete(model).Error; err != nil {
+
+			t.Fatalf("reset %T: %v", model, err)
+
+		}
+
+	}
+
+	t.Cleanup(func() {
+
+		db := dbcore.GetDBInstance()
+
+		for _, model := range []any{&models.Task{}, &models.TaskResult{}, &models.PingTask{}} {
+
+			_ = db.Where("1 = 1").Delete(model).Error
+
+		}
+
+	})
+
+}

database/utils.go

@@ -1,16 +1,19 @@
 package database
 
 import (
+	"context"
 	"encoding/json"
-	"log"
 	"os"
 	"path/filepath"
-	"strings"
 
 	"github.com/gin-gonic/gin"
 	"github.com/komari-monitor/komari/database/dbcore"
 	"github.com/komari-monitor/komari/database/models"
-	"github.com/komari-monitor/komari/pkg/config"
+	"github.com/komari-monitor/komari/internal/config"
+	"github.com/komari-monitor/komari/internal/managedconfig"
+	"github.com/komari-monitor/komari/internal/metricstore"
+	logger "github.com/komari-monitor/komari/utils/log"
+	"github.com/komari-monitor/komari/web/public"
 )
 
 func GetPublicInfo() (map[string]interface{}, error) {
@@ -42,15 +45,6 @@ func GetPublicInfo() (map[string]interface{}, error) {
 	if !hasKey("o_auth_provider") {
 		cst.OAuthProvider = "github"
 	}
-	if !hasKey("record_enabled") {
-		cst.RecordEnabled = true
-	}
-	if !hasKey("record_preserve_time") {
-		cst.RecordPreserveTime = 720
-	}
-	if !hasKey("ping_record_preserve_time") {
-		cst.PingRecordPreserveTime = 24
-	}
 
 	// Fallback defaults if we couldn't enumerate keys.
 	if allErr != nil {
@@ -61,7 +55,10 @@ func GetPublicInfo() (map[string]interface{}, error) {
 			cst.Description = "Komari Monitor, a simple server monitoring tool."
 		}
 	}
-
+	retention, err := metricstore.GetRetentionSummary(context.Background())
+	if err != nil {
+		return nil, err
+	}
 	db := dbcore.GetDBInstance()
 	tc := models.ThemeConfiguration{}
 	err = db.Model(&models.ThemeConfiguration{}).Where("short = ?", cst.Theme).First(&tc).Error
@@ -71,60 +68,22 @@ func GetPublicInfo() (map[string]interface{}, error) {
 	tc_data := gin.H{}
 	err = json.Unmarshal([]byte(tc.Data), &tc_data)
 	if err != nil {
-		log.Printf("%v", err)
+		logger.Infof("database", "%v", err)
 	}
-	// Try to load theme declaration file and merge defaults for managed configuration
-	// Theme declarations live in ./data/theme/<short>/komari-theme.json
-	if cst.Theme != "" && cst.Theme != "default" {
-		themeConfigPath := filepath.Join("./data/theme", cst.Theme, "komari-theme.json")
-		if _, err := os.Stat(themeConfigPath); err == nil {
-			b, err := os.ReadFile(themeConfigPath)
-			if err == nil {
-				var themeDecl struct {
-					Configuration struct {
-						Type string                                 `json:"type"`
-						Data []models.ManagedThemeConfigurationItem `json:"data"`
-					} `json:"configuration"`
-				}
-				if err := json.Unmarshal(b, &themeDecl); err == nil {
-					if themeDecl.Configuration.Type == "managed" {
-						for _, item := range themeDecl.Configuration.Data {
-							if item.Key == "" {
-								continue
-							}
-							// missing
-							if _, exists := tc_data[item.Key]; !exists {
-								var def any = item.Default
-								// select
-								if item.Type == "select" {
-									if def == nil || def == "" {
-										if item.Options != "" {
-											opts := strings.Split(item.Options, ",")
-											if len(opts) > 0 {
-												def = strings.TrimSpace(opts[0])
-											}
-										}
-									}
-								}
-								// number->0, string->"", switch->false
-								if def == nil {
-									switch item.Type {
-									case "number":
-										def = 0
-									case "switch":
-										def = false
-									default:
-										def = ""
-									}
-								}
-								tc_data[item.Key] = def
-							}
-						}
-					}
-				}
+	items := themeConfigurationItems(cst.Theme)
+	if cst.Theme != "default" {
+		for _, item := range items {
+			if item.Key == "" {
+				continue
+			}
+			if _, exists := tc_data[item.Key]; !exists {
+				tc_data[item.Key] = managedconfig.DefaultValue(item)
 			}
 		}
 	}
+	if err := managedconfig.ResolveForOutput(tc_data, items); err != nil {
+		return nil, err
+	}
 
 	return gin.H{
 		"sitename":                  cst.Sitename,
@@ -135,11 +94,27 @@ func GetPublicInfo() (map[string]interface{}, error) {
 		"oauth_provider":            cst.OAuthProvider,
 		"disable_password_login":    cst.DisablePasswordLogin,
 		"cors_origin_check_enabled": cst.CorsOriginCheckEnabled,
-		"record_enabled":            cst.RecordEnabled,
-		"record_preserve_time":      cst.RecordPreserveTime,
-		"ping_record_preserve_time": cst.PingRecordPreserveTime,
+		"record_enabled":            retention.AllPositive, // 兼容旧版本主题
+		"record_preserve_time":      retention.MaxDays * 24,
+		"ping_record_preserve_time": retention.MaxDays * 24,
 		"private_site":              cst.PrivateSite,
 		"theme":                     cst.Theme,
 		"theme_settings":            tc_data,
 	}, nil
 }
+
+func themeConfigurationItems(short string) []models.ManagedThemeConfigurationItem {
+	var manifest models.Theme
+	if short == "default" {
+		data, err := public.PublicFS.ReadFile("defaultTheme/komari-theme.json")
+		if err != nil || json.Unmarshal(data, &manifest) != nil {
+			return nil
+		}
+	} else {
+		data, err := os.ReadFile(filepath.Join("./data/theme", short, "komari-theme.json"))
+		if err != nil || json.Unmarshal(data, &manifest) != nil {
+			return nil
+		}
+	}
+	return managedconfig.Items(manifest.Configuration)
+}

docs/README_ja.md

@@ -1,143 +0,0 @@
-# Komari
-
-![Badge](https://hitscounter.dev/api/hit?url=https%3A%2F%2Fgithub.com%2Fkomari-monitor%2Fkomari&label=&icon=github&color=%23a370f7&message=&style=flat&tz=UTC)
-
-![komari](https://socialify.git.ci/komari-monitor/komari/image?description=1&font=Inter&forks=1&issues=1&language=1&logo=https%3A%2F%2Fraw.githubusercontent.com%2Fkomari-monitor%2Fkomari-web%2Fd54ce1288df41ead08aa19f8700186e68028a889%2Fpublic%2Ffavicon.png&name=1&owner=1&pattern=Plus&pulls=1&stargazers=1&theme=Auto)
-
-Komariは、サーバーのパフォーマンスを監視するためのシンプルで効率的なソリューションを提供することを目的とした、軽量の自己ホスト型サーバー監視ツールです。Webインターフェースを介してサーバーのステータスを表示し、軽量エージェントを介してデータを収集します。
-
-[ドキュメント](https://komari-document.pages.dev/) | [Telegramグループ](https://t.me/komari_monitor)
-
-## 特徴
-
-- **軽量で効率的**: リソース消費が少なく、あらゆる規模のサーバーに適しています。
-- **自己ホスト型**: データプライバシーを完全に制御でき、展開も簡単です。
-- **Webインターフェース**: 直感的な監視ダッシュボードで、使いやすいです。
-
-## クイックスタート
-
-### 0. クラウドホスティングによるワンクリック展開
-
-- Rainyun - CNY 4.5/月
-
-[![](https://rainyun-apps.cn-nb1.rains3.com/materials/deploy-on-rainyun-cn.svg)](https://app.rainyun.com/apps/rca/store/6780/NzYxNzAz_)
-
-- 1Panel アプリストア
-
-1Panel アプリストアで利用可能です。「アプリストア」>「ユーティリティ」>「Komari」からインストールしてください。
-
-### 1. ワンクリックインストールスクリプトを使用する
-
-systemdを使用するディストリビューション（Ubuntu、Debianなど）に適しています。
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/komari-monitor/komari/main/install-komari.sh -o install-komari.sh
-chmod +x install-komari.sh
-sudo ./install-komari.sh
-```
-
-### 2. Docker展開
-
-1. データディレクトリを作成します:
-   ```bash
-   mkdir -p ./data
-   ```
-2. Dockerコンテナを実行します:
-   ```bash
-   docker run -d \
-     -p 25774:25774 \
-     -v $(pwd)/data:/app/data \
-     --name komari \
-     ghcr.io/komari-monitor/komari:latest
-   ```
-3. デフォルトのユーザー名とパスワードを表示します:
-   ```bash
-   docker logs komari
-   ```
-4. ブラウザで `http://<your_server_ip>:25774` にアクセスします。
-
-> [!NOTE]
-> 環境変数 `ADMIN_USERNAME` と `ADMIN_PASSWORD` を使用して、初期のユーザー名とパスワードをカスタマイズすることもできます。
-
-### 3. バイナリファイル展開
-
-1. Komariの[GitHubリリース](https://github.com/komari-monitor/komari/releases)ページにアクセスして、お使いのオペレーティングシステム用の最新のバイナリをダウンロードします。
-2. Komariを実行します:
-   ```bash
-   ./komari server -l 0.0.0.0:25774
-   ```
-3. ブラウザで `http://<your_server_ip>:25774` にアクセスします。デフォルトのポートは `25774` です。
-4. デフォルトのユーザー名とパスワードは、起動ログで確認するか、環境変数 `ADMIN_USERNAME` と `ADMIN_PASSWORD` を介して設定できます。
-
-> [!NOTE]
-> バイナリに実行権限があることを確認してください（`chmod +x komari`）。データは実行ディレクトリの `data` フォルダに保存されます。
-
-### 手動ビルド
-
-#### 依存関係
-
-- Go 1.18+ および Node.js 20+（手動ビルド用）
-
-1. フロントエンドの静的ファイルをビルドします:
-   ```bash
-   git clone https://github.com/komari-monitor/komari-web
-   cd komari-web
-   npm install
-   npm run build
-   ```
-2. バックエンドをビルドします:
-   ```bash
-   git clone https://github.com/komari-monitor/komari
-   cd komari
-   ```
-   ステップ1で生成された静的ファイルを `komari` プロジェクトのルートにある `/web/public/defaultTheme/dist` フォルダにコピーし、`komari-theme.json` と `preview.png`/`perview.png` を `/web/public/defaultTheme` にコピーします。
-   ```bash
-   go build -o komari
-   ```
-3. 実行:
-   ```bash
-   ./komari server -l 0.0.0.0:25774
-   ```
-   デフォルトのリスニングポートは `25774` です。`http://localhost:25774` にアクセスします。
-
-## フロントエンド開発ガイド
-
-[Komariテーマ開発ガイド | Komari](https://komari-document.pages.dev/dev/theme.html)
-
-[CrowdinでKomariを翻訳する](https://crowdin.com/project/komari/invite?h=cd051bf172c9a9f7f1360e87ffb521692507706)
-
-## クライアントエージェント開発ガイド
-
-[Komariエージェント情報レポートおよびイベント処理ドキュメント](https://komari-document.pages.dev/dev/agent.html)
-
-## 貢献
-
-IssueやPull Requestを歓迎します！
-
-## 謝辞
-
-### 破碎工坊云 (Crash Work)
-
-[破碎工坊云 - 効率的で安定した、安全な高防御サーバーとCDNソリューションを提供する専門的なクラウドコンピューティングプラットフォーム](https://www.crash.work/)
-
-### DreamCloud
-
-[DreamCloud - コストパフォーマンスに優れたアジア太平洋向け高防御直通](https://as211392.com/)
-
-### 🚀 SharonNetworks スポンサー
-
-[![Sharon Networks](https://raw.githubusercontent.com/komari-monitor/public/refs/heads/main/images/sharon-networks.webp)](https://sharon.io)
-
-SharonNetworks は、あなたのビジネスの離陸を力強くサポートします！
-
-アジア太平洋のデータセンターから中国最適化ネットワーク接続を提供。低レイテンシー & 高帯域幅、Tbps 級のローカル洗浄 DDoS 防御で、ビジネスとお客様の体験を守ります。コミュニティ [Telegram グループ](https://t.me/SharonNetwork) に参加すると、チャリティまたはグループ内抽選で無料利用のチャンスがあります。
-
-### オープンソースコミュニティ
-
-PR を送ってくれた方、テーマを作成してくれた全ての開発者
-
-—— そして：こんなに暇でいられる自分に感謝
-
-## Star履歴
-
-[![Star History Chart](https://api.star-history.com/svg?repos=komari-monitor/komari&type=Date)](https://www.star-history.com/#komari-monitor/komari&Date)

docs/README_zh-TW.md

@@ -1,143 +0,0 @@
-# Komari
-
-![Badge](https://hitscounter.dev/api/hit?url=https%3A%2F%2Fgithub.com%2Fkomari-monitor%2Fkomari&label=&icon=github&color=%23a370f7&message=&style=flat&tz=UTC)
-
-![komari](https://socialify.git.ci/komari-monitor/komari/image?description=1&font=Inter&forks=1&issues=1&language=1&logo=https%3A%2F%2Fraw.githubusercontent.com%2Fkomari-monitor%2Fkomari-web%2Fd54ce1288df41ead08aa19f8700186e68028a889%2Fpublic%2Ffavicon.png&name=1&owner=1&pattern=Plus&pulls=1&stargazers=1&theme=Auto)
-
-Komari 是一款輕量級的自託管伺服器監控工具，旨在提供簡單、高效的伺服器性能監控解決方案。它支援透過 Web 介面查看伺服器狀態，並透過輕量級 Agent 收集數據。
-
-[文檔](https://komari-document.pages.dev/) | [Telegram 群組](https://t.me/komari_monitor)
-
-## 特性
-
-- **輕量高效**：低資源佔用，適合各種規模的伺服器。
-- **自託管**：完全掌控數據隱私，部署簡單。
-- **Web 介面**：直觀的監控儀表盤，易於使用。
-
-## 快速開始
-
-### 0. 容器雲一鍵部署
-
-- 雨雲雲應用 - CNY 4.5/月
-
-[![](https://rainyun-apps.cn-nb1.rains3.com/materials/deploy-on-rainyun-cn.svg)](https://app.rainyun.com/apps/rca/store/6780/NzYxNzAz_)
-
-- 1Panel 應用商店
-
-已上架 1Panel 應用商店，應用商店-實用工具-Komari 即可安裝
-
-### 1. 使用一鍵安裝腳本
-
-適用於使用了 systemd 的發行版（Ubuntu、Debian...）。
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/komari-monitor/komari/main/install-komari.sh -o install-komari.sh
-chmod +x install-komari.sh
-sudo ./install-komari.sh
-```
-
-### 2. Docker 部署
-
-1. 建立資料目錄：
-   ```bash
-   mkdir -p ./data
-   ```
-2. 執行 Docker 容器：
-   ```bash
-   docker run -d \
-     -p 25774:25774 \
-     -v $(pwd)/data:/app/data \
-     --name komari \
-     ghcr.io/komari-monitor/komari:latest
-   ```
-3. 查看預設帳號和密碼：
-   ```bash
-   docker logs komari
-   ```
-4. 在瀏覽器中存取 `http://<your_server_ip>:25774`。
-
-> [!NOTE]
-> 你也可以透過環境變數 `ADMIN_USERNAME` 和 `ADMIN_PASSWORD` 自訂初始使用者名稱和密碼。
-
-### 3. 二進位檔案部署
-
-1. 存取 Komari 的 [GitHub Release 頁面](https://github.com/komari-monitor/komari/releases) 下載適用於你作業系統的最新二進位檔案。
-2. 執行 Komari：
-   ```bash
-   ./komari server -l 0.0.0.0:25774
-   ```
-3. 在瀏覽器中存取 `http://<your_server_ip>:25774`，預設監聽 `25774` 連接埠。
-4. 預設帳號和密碼可在啟動日誌中查看，或透過環境變數 `ADMIN_USERNAME` 和 `ADMIN_PASSWORD` 設定。
-
-> [!NOTE]
-> 確保二進位檔案具有可執行權限（`chmod +x komari`）。資料將保存在執行目錄下的 `data` 資料夾中。
-
-### 手工建置
-
-#### 依賴
-
-- Go 1.18+ 和 Node.js 20+（手工建置）
-
-1. 建置前端靜態檔案：
-   ```bash
-   git clone https://github.com/komari-monitor/komari-web
-   cd komari-web
-   npm install
-   npm run build
-   ```
-2. 建置後端：
-   ```bash
-   git clone https://github.com/komari-monitor/komari
-   cd komari
-   ```
-   將步驟1中產生的靜態檔案複製到 `komari` 專案根目錄下的 `/web/public/defaultTheme/dist` 資料夾，並將 `komari-theme.json` 與 `preview.png`/`perview.png` 複製到 `/web/public/defaultTheme`。
-   ```bash
-   go build -o komari
-   ```
-3. 執行：
-   ```bash
-   ./komari server -l 0.0.0.0:25774
-   ```
-   預設監聽 `25774` 連接埠，存取 `http://localhost:25774`。
-
-## 前端開發指南
-
-[Komari 主題開發指南 | Komari](https://komari-document.pages.dev/dev/theme.html)
-
-[在 Crowdin 上翻譯 Komari](https://crowdin.com/project/komari/invite?h=cd051bf172c9a9f7f1360e87ffb521692507706)
-
-## 客戶端 Agent 開發指南
-
-[Komari Agent 資訊上報與事件處理文檔](https://komari-document.pages.dev/dev/agent.html)
-
-## 貢獻
-
-歡迎提交 Issue 或 Pull Request！
-
-## 鳴謝
-
-### 破碎工坊雲
-
-[破碎工坊雲 - 專業雲計算服務平台，提供高效、穩定、安全的高防伺服器與CDN解決方案](https://www.crash.work/)
-
-### DreamCloud
-
-[DreamCloud - 極高性價比解鎖直連亞太高防](https://as211392.com/)
-
-### 🚀 由 SharonNetworks 贊助
-
-[![Sharon Networks](https://raw.githubusercontent.com/komari-monitor/public/refs/heads/main/images/sharon-networks.webp)](https://sharon.io)
-
-SharonNetworks 為您的業務起飛保駕護航！
-
-亞太資料中心提供頂級的中國優化網路接入 · 低延遲 & 高頻寬 & 提供 Tbps 級本地清洗高防服務，為您的業務保駕護航，為您的客戶提供極致體驗。加入社群 [Telegram 群組](https://t.me/SharonNetwork) 可參與公益募捐或群內抽獎免費使用。
-
-### 開源社群
-
-提交 PR、製作主題的各位開發者
-
-—— 以及：感謝我自己能這麼閒
-
-## Star History
-
-[![Star History Chart](https://api.star-history.com/svg?repos=komari-monitor/komari&type=Date)](https://www.star-history.com/#komari-monitor/komari&Date)

docs/README_zh.md

@@ -1,143 +0,0 @@
-# Komari
-
-![Badge](https://hitscounter.dev/api/hit?url=https%3A%2F%2Fgithub.com%2Fkomari-monitor%2Fkomari&label=&icon=github&color=%23a370f7&message=&style=flat&tz=UTC)
-
-![komari](https://socialify.git.ci/komari-monitor/komari/image?description=1&font=Inter&forks=1&issues=1&language=1&logo=https%3A%2F%2Fraw.githubusercontent.com%2Fkomari-monitor%2Fkomari-web%2Fd54ce1288df41ead08aa19f8700186e68028a889%2Fpublic%2Ffavicon.png&name=1&owner=1&pattern=Plus&pulls=1&stargazers=1&theme=Auto)
-
-Komari 是一款轻量级的自托管服务器监控工具，旨在提供简单、高效的服务器性能监控解决方案。它支持通过 Web 界面查看服务器状态，并通过轻量级 Agent 收集数据。
-
-[文档](https://komari-document.pages.dev/) | [文档(镜像站 By Geekertao)](https://www.komari.wiki) | [Telegram 群组](https://t.me/komari_monitor)
-
-## 特性
-
-- **轻量高效**：低资源占用，适合各种规模的服务器。
-- **自托管**：完全掌控数据隐私，部署简单。
-- **Web 界面**：直观的监控仪表盘，易于使用。
-
-## 快速开始
-
-### 0. 容器云一键部署
-
-- 雨云云应用 - CNY 4.5/月
-
-[![](https://rainyun-apps.cn-nb1.rains3.com/materials/deploy-on-rainyun-cn.svg)](https://app.rainyun.com/apps/rca/store/6780/NzYxNzAz_)
-
-- 1Panel 应用商店
-
-已上架1Panel应用商店，应用商店-实用工具-Komari 即可安装
-
-### 1. 使用一键安装脚本
-
-适用于使用了 systemd 的发行版（Ubuntu、Debian...）。
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/komari-monitor/komari/main/install-komari.sh -o install-komari.sh
-chmod +x install-komari.sh
-sudo ./install-komari.sh
-```
-
-### 2. Docker 部署
-
-1. 创建数据目录：
-   ```bash
-   mkdir -p ./data
-   ```
-2. 运行 Docker 容器：
-   ```bash
-   docker run -d \
-     -p 25774:25774 \
-     -v $(pwd)/data:/app/data \
-     --name komari \
-     ghcr.io/komari-monitor/komari:latest
-   ```
-3. 查看默认账号和密码：
-   ```bash
-   docker logs komari
-   ```
-4. 在浏览器中访问 `http://<your_server_ip>:25774`。
-
-> [!NOTE]
-> 你也可以通过环境变量 `ADMIN_USERNAME` 和 `ADMIN_PASSWORD` 自定义初始用户名和密码。
-
-### 3. 二进制文件部署
-
-1. 访问 Komari 的 [GitHub Release 页面](https://github.com/komari-monitor/komari/releases) 下载适用于你操作系统的最新二进制文件。
-2. 运行 Komari：
-   ```bash
-   ./komari server -l 0.0.0.0:25774
-   ```
-3. 在浏览器中访问 `http://<your_server_ip>:25774`，默认监听 `25774` 端口。
-4. 默认账号和密码可在启动日志中查看，或通过环境变量 `ADMIN_USERNAME` 和 `ADMIN_PASSWORD` 设置。
-
-> [!NOTE]
-> 确保二进制文件具有可执行权限（`chmod +x komari`）。数据将保存在运行目录下的 `data` 文件夹中。
-
-### 手工构建
-
-#### 依赖
-
-- Go 1.18+ 和 Node.js 20+（手工构建）
-
-1. 构建前端静态文件：
-   ```bash
-   git clone https://github.com/komari-monitor/komari-web
-   cd komari-web
-   npm install
-   npm run build
-   ```
-2. 构建后端：
-   ```bash
-   git clone https://github.com/komari-monitor/komari
-   cd komari
-   ```
-   将步骤1中生成的静态文件复制到 `komari` 项目根目录下的 `/web/public/defaultTheme/dist` 文件夹，并将 `komari-theme.json` 与 `preview.png`/`perview.png` 复制到 `/web/public/defaultTheme`。
-   ```bash
-   go build -o komari
-   ```
-3. 运行：
-   ```bash
-   ./komari server -l 0.0.0.0:25774
-   ```
-   默认监听 `25774` 端口，访问 `http://localhost:25774`。
-
-## 前端开发指南
-
-[Komari 主题开发指南 | Komari](https://komari-document.pages.dev/dev/theme.html)
-
-[在 Crowdin 上翻译 Komari](https://crowdin.com/project/komari/invite?h=cd051bf172c9a9f7f1360e87ffb521692507706)
-
-## 客户端 Agent 开发指南
-
-[Komari Agent 信息上报与事件处理文档](https://komari-document.pages.dev/dev/agent.html)
-
-## 贡献
-
-欢迎提交 Issue 或 Pull Request！
-
-## 鸣谢
-
-### 破碎工坊云
-
-[破碎工坊云 - 专业云计算服务平台，提供高效、稳定、安全的高防服务器与CDN解决方案](https://www.crash.work/)
-
-### DreamCloud
-
-[DreamCloud - 极高性价比解锁直连亚太高防](https://as211392.com/)
-
-### 🚀 由 SharonNetworks 赞助
-
-[![Sharon Networks](https://raw.githubusercontent.com/komari-monitor/public/refs/heads/main/images/sharon-networks.webp)](https://sharon.io)
-
-SharonNetworks 为您的业务起飞保驾护航！
-
-亚太数据中心提供顶级的中国优化网络接入 · 低延时 & 高带宽 & 提供 Tbps 级本地清洗高防服务，为您的业务保驾护航，为您的客户提供极致体验。加入社区 [Telegram 群组](https://t.me/SharonNetwork) 可参与公益募捐或群内抽奖免费使用。
-
-### 开源社区
-
-提交 PR、制作主题的各位开发者
-
-—— 以及：感谢我自己能这么闲
-
-## Star History
-
-[![Star History Chart](https://api.star-history.com/svg?repos=komari-monitor/komari&type=Date)](https://www.star-history.com/#komari-monitor/komari&Date)

go.mod

@@ -1,53 +1,53 @@
 module github.com/komari-monitor/komari
 
-go 1.24.0
-
-toolchain go1.24.11
+go 1.25.0
 
 require (
-	github.com/coreos/go-oidc/v3 v3.15.0
-	github.com/dop251/goja v0.0.0-20251008123653-cf18d89f3cf6
-	github.com/dop251/goja_nodejs v0.0.0-20251015164255-5e94316bedaf
+	github.com/Calcium-Ion/moejs v0.1.0-alpha.9
 	github.com/gin-gonic/gin v1.10.0
+	github.com/go-sql-driver/mysql v1.10.0
 	github.com/google/uuid v1.6.0
 	github.com/gorilla/websocket v1.5.3
+	github.com/jackc/pgx/v5 v5.10.0
+	github.com/klauspost/compress v1.17.11
+	github.com/mattn/go-sqlite3 v1.14.27
 	github.com/oschwald/maxminddb-golang v1.13.1
 	github.com/patrickmn/go-cache v2.1.0+incompatible
 	github.com/pquerna/otp v1.5.0
 	github.com/spf13/cobra v1.9.1
-	github.com/stretchr/testify v1.10.0
-	golang.org/x/image v0.35.0
-	google.golang.org/grpc v1.75.0
-	google.golang.org/protobuf v1.36.6
+	github.com/stretchr/testify v1.12.1
+	golang.org/x/sys v0.33.0
 	gorm.io/driver/sqlite v1.5.7
 	gorm.io/gorm v1.26.1
 )
 
+require go.yaml.in/yaml/v3 v3.0.5 // indirect
+
 // Misuse of ServerConfig.PublicKeyCallback may cause authorization bypass in golang.org/x/crypto #1
 // golang.org/x/crypto Vulnerable to Denial of Service (DoS) via Slow or Incomplete Key Exchange #3
-require golang.org/x/crypto v0.39.0 // indirect
+require golang.org/x/crypto v0.39.0
 
 // HTTP Proxy bypass using IPv6 Zone IDs in golang.org/x/net #2
 // golang.org/x/net vulnerable to Cross-site Scripting #4
-require golang.org/x/net v0.41.0 // indirect
+require golang.org/x/net v0.41.0
 
 require (
+	filippo.io/edwards25519 v1.2.0 // indirect
 	github.com/boombuler/barcode v1.0.1-0.20190219062509-6c824513bacc // indirect
 	github.com/bytedance/sonic v1.13.2 // indirect
 	github.com/bytedance/sonic/loader v0.2.4 // indirect
 	github.com/cloudwego/base64x v0.1.5 // indirect
-	github.com/davecgh/go-spew v1.1.1 // indirect
-	github.com/dlclark/regexp2 v1.11.4 // indirect
 	github.com/gabriel-vasile/mimetype v1.4.8 // indirect
 	github.com/gin-contrib/sse v1.0.0 // indirect
-	github.com/go-jose/go-jose/v4 v4.1.1 // indirect
 	github.com/go-playground/locales v0.14.1 // indirect
 	github.com/go-playground/universal-translator v0.18.1 // indirect
 	github.com/go-playground/validator/v10 v10.26.0 // indirect
-	github.com/go-sourcemap/sourcemap v2.1.4+incompatible // indirect
 	github.com/goccy/go-json v0.10.5 // indirect
-	github.com/google/pprof v0.0.0-20240727154555-813a5fbdbec8 // indirect
+	github.com/google/go-cmp v0.7.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/jinzhu/inflection v1.0.0 // indirect
 	github.com/jinzhu/now v1.1.5 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
@@ -55,20 +55,16 @@ require (
 	github.com/kr/text v0.2.0 // indirect
 	github.com/leodido/go-urn v1.4.0 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
-	github.com/mattn/go-sqlite3 v1.14.27 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.3 // indirect
-	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/rogpeppe/go-internal v1.8.0 // indirect
 	github.com/spf13/pflag v1.0.6 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/ugorji/go/codec v1.2.12 // indirect
 	golang.org/x/arch v0.15.0 // indirect
-	golang.org/x/oauth2 v0.30.0 // indirect
-	golang.org/x/sys v0.33.0 // indirect
-	golang.org/x/text v0.33.0 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20250707201910-8d1bb00bc6a7 // indirect
-	gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
+	golang.org/x/sync v0.19.0
+	golang.org/x/text v0.33.0
+	google.golang.org/protobuf v1.36.6 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -1,5 +1,7 @@
-github.com/Masterminds/semver/v3 v3.2.1 h1:RN9w6+7QoMeJVGyfmbcgs28Br8cvmnucEXnY0rYXWg0=
-github.com/Masterminds/semver/v3 v3.2.1/go.mod h1:qvl/7zhW3nngYb5+80sSMF+FG2BjYrf8m9wsX0PNOMQ=
+filippo.io/edwards25519 v1.2.0 h1:crnVqOiS4jqYleHd9vaKZ+HKtHfllngJIiOpNpoJsjo=
+filippo.io/edwards25519 v1.2.0/go.mod h1:xzAOLCNug/yB62zG1bQ8uziwrIqIuxhctzJT18Q77mc=
+github.com/Calcium-Ion/moejs v0.1.0-alpha.9 h1:WY1ebChegtafhPjHSQx3Q+gfnrjqYwHewHuO9k+v7e0=
+github.com/Calcium-Ion/moejs v0.1.0-alpha.9/go.mod h1:9YqHj36EV7pzV/vlEYSw49f3oggeJFdmqcjM9TmDpHs=
 github.com/boombuler/barcode v1.0.1-0.20190219062509-6c824513bacc h1:biVzkmvwrH8WK8raXaxBx6fRVTlJILwEwQGL1I/ByEI=
 github.com/boombuler/barcode v1.0.1-0.20190219062509-6c824513bacc/go.mod h1:paBWMcWSl3LHKBqUq+rly7CNSldXjb2rDl3JlRe0mD8=
 github.com/bytedance/sonic v1.13.2 h1:8/H1FempDZqC4VqjptGo14QQlJx8VdZJegxs6wwfqpQ=
@@ -10,31 +12,17 @@ github.com/bytedance/sonic/loader v0.2.4/go.mod h1:N8A3vUdtUebEY2/VQC0MyhYeKUFos
 github.com/cloudwego/base64x v0.1.5 h1:XPciSp1xaq2VCSt6lF0phncD4koWyULpl5bUxbfCyP4=
 github.com/cloudwego/base64x v0.1.5/go.mod h1:0zlkT4Wn5C6NdauXdJRhSKRlJvmclQ1hhJgA0rcu/8w=
 github.com/cloudwego/iasm v0.2.0/go.mod h1:8rXZaNYT2n95jn+zTI1sDr+IgcD2GVs0nlbbQPiEFhY=
-github.com/coreos/go-oidc/v3 v3.15.0 h1:R6Oz8Z4bqWR7VFQ+sPSvZPQv4x8M+sJkDO5ojgwlyAg=
-github.com/coreos/go-oidc/v3 v3.15.0/go.mod h1:HaZ3szPaZ0e4r6ebqvsLWlk2Tn+aejfmrfah6hnSYEU=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/dlclark/regexp2 v1.11.4 h1:rPYF9/LECdNymJufQKmri9gV604RvvABwgOA8un7yAo=
-github.com/dlclark/regexp2 v1.11.4/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
-github.com/dop251/goja v0.0.0-20251008123653-cf18d89f3cf6 h1:6dE1TmjqkY6tehR4A67gDNhvDtuZ54ocu7ab4K9o540=
-github.com/dop251/goja v0.0.0-20251008123653-cf18d89f3cf6/go.mod h1:MxLav0peU43GgvwVgNbLAj1s/bSGboKkhuULvq/7hx4=
-github.com/dop251/goja_nodejs v0.0.0-20251015164255-5e94316bedaf h1:gbmvliZnCut4NjaPSNOQlfqBoZ9C5Dpf72mHMMYhgVE=
-github.com/dop251/goja_nodejs v0.0.0-20251015164255-5e94316bedaf/go.mod h1:Tb7Xxye4LX7cT3i8YLvmPMGCV92IOi4CDZvm/V8ylc0=
 github.com/gabriel-vasile/mimetype v1.4.8 h1:FfZ3gj38NjllZIeJAmMhr+qKL8Wu+nOoI3GqacKw1NM=
 github.com/gabriel-vasile/mimetype v1.4.8/go.mod h1:ByKUIKGjh1ODkGM1asKUbQZOLGrPjydw3hYPU2YU9t8=
 github.com/gin-contrib/sse v1.0.0 h1:y3bT1mUWUxDpW4JLQg/HnTqV4rozuW4tC9eFKTxYI9E=
 github.com/gin-contrib/sse v1.0.0/go.mod h1:zNuFdwarAygJBht0NTKiSi3jRf6RbqeILZ9Sp6Slhe0=
 github.com/gin-gonic/gin v1.10.0 h1:nTuyha1TYqgedzytsKYqna+DfLos46nTv2ygFy86HFU=
 github.com/gin-gonic/gin v1.10.0/go.mod h1:4PMNQiOhvDRa013RKVbsiNwoyezlm2rm0uX/T7kzp5Y=
-github.com/go-jose/go-jose/v4 v4.1.1 h1:JYhSgy4mXXzAdF3nUx3ygx347LRXJRrpgyU3adRmkAI=
-github.com/go-jose/go-jose/v4 v4.1.1/go.mod h1:BdsZGqgdO3b6tTc6LSE56wcDbMMLuPsw5d4ZD5f94kA=
-github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
-github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
-github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
-github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
 github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
 github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
 github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
@@ -43,35 +31,40 @@ github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJn
 github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
 github.com/go-playground/validator/v10 v10.26.0 h1:SP05Nqhjcvz81uJaRfEV0YBSSSGMc/iMaVtFbr3Sw2k=
 github.com/go-playground/validator/v10 v10.26.0/go.mod h1:I5QpIEbmr8On7W0TktmJAumgzX4CA1XNl4ZmDuVHKKo=
-github.com/go-sourcemap/sourcemap v2.1.4+incompatible h1:a+iTbH5auLKxaNwQFg0B+TCYl6lbukKPc7b5x0n1s6Q=
-github.com/go-sourcemap/sourcemap v2.1.4+incompatible/go.mod h1:F8jJfvm2KbVjc5NqelyYJmf/v5J0dwNLS2mL4sNA1Jg=
+github.com/go-sql-driver/mysql v1.10.0 h1:Q+1LV8DkHJvSYAdR83XzuhDaTykuDx0l6fkXxoWCWfw=
+github.com/go-sql-driver/mysql v1.10.0/go.mod h1:M+cqaI7+xxXGG9swrdeUIoPG3Y3KCkF0pZej+SK+nWk=
 github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
 github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
-github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
-github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
-github.com/google/pprof v0.0.0-20240727154555-813a5fbdbec8 h1:FKHo8hFI3A+7w0aUQuYXQ+6EN5stWmeY/AZqtM8xk9k=
-github.com/google/pprof v0.0.0-20240727154555-813a5fbdbec8/go.mod h1:K1liHPHnj73Fdn/EKuT8nrFqBihUSKXoLYU0BuatOYo=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
 github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgx/v5 v5.10.0 h1:VhSvgU2jSli8o3AqIEOTJr7rZwAEUVo4E4XhR94Zfr0=
+github.com/jackc/pgx/v5 v5.10.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
+github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
+github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
 github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
 github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
 github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
 github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
 github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
 github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
+github.com/klauspost/compress v1.17.11 h1:In6xLpyWOi1+C7tXUUWv2ot1QvBjxevKAaI6IXrJmUc=
+github.com/klauspost/compress v1.17.11/go.mod h1:pMDklpSncoRMuLFrf1W9Ss9KT+0rH90U12bZKk7uwG0=
 github.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
 github.com/klauspost/cpuid/v2 v2.2.10 h1:tBs3QSyvjDyFTq3uoc/9xFpCuOsJQFNPiAhYdw2skhE=
 github.com/klauspost/cpuid/v2 v2.2.10/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
 github.com/knz/go-libedit v1.10.1/go.mod h1:MZTVkCWyz0oBc7JOWP3wNAzd002ZbM/5hgShxwh4x8M=
 github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
-github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
 github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0=
 github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk=
 github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
@@ -96,7 +89,6 @@ github.com/patrickmn/go-cache v2.1.0+incompatible/go.mod h1:3Qf8kWWT7OJRJbdiICTK
 github.com/pelletier/go-toml/v2 v2.2.3 h1:YmeHyLY8mFWbdkNWwpr+qIL2bEqT0o95WSdkNHvL12M=
 github.com/pelletier/go-toml/v2 v2.2.3/go.mod h1:MfCQTFTvCcUyyvvwm1+G6H/jORL20Xlb6rzQu9GuUkc=
 github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
-github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/pquerna/otp v1.5.0 h1:NMMR+WrmaqXU4EzdGJEE1aUUI0AMRzsp96fFFWNPwxs=
 github.com/pquerna/otp v1.5.0/go.mod h1:dkJfzwRKNiegxyNb54X/3fLwhCynbMspSyWKnvi1AEg=
@@ -117,45 +109,28 @@ github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
-github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE=
+github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg=
 github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
 github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
 github.com/ugorji/go/codec v1.2.12 h1:9LC83zGrHhuUA9l16C9AHXAqEV/2wBQ4nkvumAE65EE=
 github.com/ugorji/go/codec v1.2.12/go.mod h1:UNopzCgEMSXjBc6AOMqYvWC1ktqTAfzJZUZgYf6w6lg=
-go.opentelemetry.io/auto/sdk v1.1.0 h1:cH53jehLUN6UFLY71z+NDOiNJqDdPRaXzTel0sJySYA=
-go.opentelemetry.io/auto/sdk v1.1.0/go.mod h1:3wSPjt5PWp2RhlCcmmOial7AvC4DQqZb7a7wCow3W8A=
-go.opentelemetry.io/otel v1.37.0 h1:9zhNfelUvx0KBfu/gb+ZgeAfAgtWrfHJZcAqFC228wQ=
-go.opentelemetry.io/otel v1.37.0/go.mod h1:ehE/umFRLnuLa/vSccNq9oS1ErUlkkK71gMcN34UG8I=
-go.opentelemetry.io/otel/metric v1.37.0 h1:mvwbQS5m0tbmqML4NqK+e3aDiO02vsf/WgbsdpcPoZE=
-go.opentelemetry.io/otel/metric v1.37.0/go.mod h1:04wGrZurHYKOc+RKeye86GwKiTb9FKm1WHtO+4EVr2E=
-go.opentelemetry.io/otel/sdk v1.37.0 h1:ItB0QUqnjesGRvNcmAcU0LyvkVyGJ2xftD29bWdDvKI=
-go.opentelemetry.io/otel/sdk v1.37.0/go.mod h1:VredYzxUvuo2q3WRcDnKDjbdvmO0sCzOvVAiY+yUkAg=
-go.opentelemetry.io/otel/sdk/metric v1.37.0 h1:90lI228XrB9jCMuSdA0673aubgRobVZFhbjxHHspCPc=
-go.opentelemetry.io/otel/sdk/metric v1.37.0/go.mod h1:cNen4ZWfiD37l5NhS+Keb5RXVWZWpRE+9WyVCpbo5ps=
-go.opentelemetry.io/otel/trace v1.37.0 h1:HLdcFNbRQBE2imdSEgm/kwqmQj1Or1l/7bW6mxVK7z4=
-go.opentelemetry.io/otel/trace v1.37.0/go.mod h1:TlgrlQ+PtQO5XFerSPUYG0JSgGyryXewPGyayAWSBS0=
+go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw=
+go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg=
 golang.org/x/arch v0.15.0 h1:QtOrQd0bTUnhNVNndMpLHNWrDmYzZ2KDqSrEymqInZw=
 golang.org/x/arch v0.15.0/go.mod h1:JmwW7aLIoRUKgaTzhkiEFxvcEiQGyOg9BMonBJUS7EE=
 golang.org/x/crypto v0.39.0 h1:SHs+kF4LP+f+p14esP5jAoDpHU8Gu/v9lFRK6IT5imM=
 golang.org/x/crypto v0.39.0/go.mod h1:L+Xg3Wf6HoL4Bn4238Z6ft6KfEpN0tJGo53AAPC632U=
-golang.org/x/image v0.35.0 h1:LKjiHdgMtO8z7Fh18nGY6KDcoEtVfsgLDPeLyguqb7I=
-golang.org/x/image v0.35.0/go.mod h1:MwPLTVgvxSASsxdLzKrl8BRFuyqMyGhLwmC+TO1Sybk=
 golang.org/x/net v0.41.0 h1:vBTly1HeNPEn3wtREYfy4GZ/NECgw2Cnl+nK6Nz3uvw=
 golang.org/x/net v0.41.0/go.mod h1:B/K4NNqkfmg07DQYrbwvSluqCJOOXwUjeb/5lOisjbA=
-golang.org/x/oauth2 v0.30.0 h1:dnDm7JmhM45NNpd8FDDeLhK6FwqbOf4MLCM9zb1BOHI=
-golang.org/x/oauth2 v0.30.0/go.mod h1:B++QgG3ZKulg6sRPGD/mqlHQs5rB3Ml9erfeDY7xKlU=
+golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
+golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.33.0 h1:q3i8TbbEz+JRD9ywIRlyRAQbM0qF7hu24q3teo2hbuw=
 golang.org/x/sys v0.33.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
 golang.org/x/text v0.33.0 h1:B3njUFyqtHDUI5jMn1YIr5B0IE2U0qck04r6d4KPAxE=
 golang.org/x/text v0.33.0/go.mod h1:LuMebE6+rBincTi9+xWTY8TztLzKHc/9C1uBCG27+q8=
-gonum.org/v1/gonum v0.16.0 h1:5+ul4Swaf3ESvrOnidPp4GZbzf0mxVQpDCYUQE7OJfk=
-gonum.org/v1/gonum v0.16.0/go.mod h1:fef3am4MQ93R2HHpKnLk4/Tbh/s0+wqD5nfa6Pnwy4E=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20250707201910-8d1bb00bc6a7 h1:pFyd6EwwL2TqFf8emdthzeX+gZE1ElRq3iM8pui4KBY=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20250707201910-8d1bb00bc6a7/go.mod h1:qQ0YXyHHx3XkvlzUtpXDkS29lDSafHMZBAZDc03LQ3A=
-google.golang.org/grpc v1.75.0 h1:+TW+dqTd2Biwe6KKfhE5JpiYIBWq865PhKGSXiivqt4=
-google.golang.org/grpc v1.75.0/go.mod h1:JtPAzKiq4v1xcAB2hydNlWI2RnF85XXcV0mhKXr2ecQ=
 google.golang.org/protobuf v1.36.6 h1:z1NpPI8ku2WgiWnf+t9wTPsn6eP1L7ksHUlkfLvd9xY=
 google.golang.org/protobuf v1.36.6/go.mod h1:jduwjTPXsFjZGTmRluh+L6NjiWu7pchiJ2/5YcXBHnY=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
@@ -163,8 +138,6 @@ gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/errgo.v2 v2.1.0/go.mod h1:hNsd1EY+bozCKY1Ytp96fpM3vjJbqLJn88ws8XvfDNI=
-gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
-gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/config/config.go

@@ -3,11 +3,11 @@ package config
 import (
 	"encoding/json"
 	"fmt"
-	"log/slog"
 	"reflect"
 	"strings"
 	"sync"
 
+	logger "github.com/komari-monitor/komari/utils/log"
 	"gorm.io/gorm"
 	"gorm.io/gorm/clause"
 )
@@ -31,26 +31,6 @@ var (
 	}
 )
 
-// Get 获取原始值 (反序列化为 interface{})
-func Get(key string, defaul ...any) (any, error) {
-	var item ConfigItem
-	err := db.First(&item, "key = ?", key).Error
-	if err != nil {
-		if len(defaul) > 0 {
-			v := defaul[0]
-			err = Set(key, v)
-			return v, err
-		}
-		return nil, err
-	}
-
-	var val any
-	if err := json.Unmarshal([]byte(item.Value), &val); err != nil {
-		return nil, err
-	}
-	return val, nil
-}
-
 // GetAs 获取并转换为指定类型 (泛型)，支持数值类型自动转换
 func GetAs[T any](key string, defaul ...any) (T, error) {
 	var t T
@@ -125,7 +105,7 @@ func GetMany(keys map[string]any) (map[string]any, error) {
 				// 序列化后加入待写入列表
 				jsonBytes, err := json.Marshal(def)
 				if err != nil {
-					slog.Warn("marshal default value failed", "key", k, "error", err)
+					logger.Warn("config", "marshal default value failed", "key", k, "error", err)
 					continue
 				}
 				toInsert = append(toInsert, ConfigItem{
@@ -142,7 +122,7 @@ func GetMany(keys map[string]any) (map[string]any, error) {
 			Columns:   []clause.Column{{Name: "key"}},
 			DoUpdates: clause.AssignmentColumns([]string{"value"}),
 		}).Create(&toInsert).Error; err != nil {
-			slog.Warn("batch insert default config failed", "error", err)
+			logger.Warn("config", "batch insert default config failed", "error", err)
 		}
 	}
 
@@ -180,9 +160,8 @@ func GetManyAs[T any]() (*T, error) {
 		}
 
 		defaultTag := field.Tag.Get("default")
-		hasDefault := defaultTag != "" || field.Tag.Get("default") == ""
 		// 检查是否显式定义了 default tag (即使值为空)
-		_, hasDefault = field.Tag.Lookup("default")
+		_, hasDefault := field.Tag.Lookup("default")
 
 		fields = append(fields, fieldInfo{
 			index:      i,
@@ -220,18 +199,18 @@ func GetManyAs[T any]() (*T, error) {
 		if dbValue, found := foundItems[fi.key]; found {
 			// 数据库中存在，使用数据库值
 			if err := unmarshalToField(dbValue, fieldVal); err != nil {
-				slog.Warn("unmarshal config failed", "key", fi.key, "error", err)
+				logger.Warn("config", "unmarshal config failed", "key", fi.key, "error", err)
 			}
 		} else if fi.hasDefault {
 			// 数据库中不存在，但有 default tag，解析默认值并写入数据库
 			if err := parseDefaultToField(fi.defaultVal, fieldVal); err != nil {
-				slog.Warn("parse default value failed", "key", fi.key, "error", err)
+				logger.Warn("config", "parse default value failed", "key", fi.key, "error", err)
 				continue
 			}
 			// 序列化后写入数据库
 			jsonBytes, err := json.Marshal(fieldVal.Interface())
 			if err != nil {
-				slog.Warn("marshal default value failed", "key", fi.key, "error", err)
+				logger.Warn("config", "marshal default value failed", "key", fi.key, "error", err)
 				continue
 			}
 			toInsert = append(toInsert, ConfigItem{
@@ -248,7 +227,7 @@ func GetManyAs[T any]() (*T, error) {
 			Columns:   []clause.Column{{Name: "key"}},
 			DoUpdates: clause.AssignmentColumns([]string{"value"}),
 		}).Create(&toInsert).Error; err != nil {
-			slog.Warn("batch insert default config failed", "error", err)
+			logger.Warn("config", "batch insert default config failed", "error", err)
 		}
 	}
 
@@ -427,76 +406,6 @@ func Set(key string, value any) error {
 	return nil
 }
 
-// SetMany 将结构体保存为多个配置项
-func SetManyAs[T any](config T) error {
-	val := reflect.ValueOf(config)
-	if val.Kind() == reflect.Ptr {
-		val = val.Elem()
-	}
-
-	typ := val.Type()
-	var items []ConfigItem
-
-	for i := 0; i < val.NumField(); i++ {
-		fieldType := typ.Field(i)
-		tag := fieldType.Tag.Get("json")
-
-		if tag == "" || tag == "-" {
-			continue
-		}
-
-		fieldValue := val.Field(i).Interface()
-
-		bytes, err := json.Marshal(fieldValue)
-		if err != nil {
-			return fmt.Errorf("marshal field %s failed: %w", fieldType.Name, err)
-		}
-
-		items = append(items, ConfigItem{
-			Key:   tag,
-			Value: string(bytes),
-		})
-	}
-
-	if len(items) == 0 {
-		return nil
-	}
-
-	keys := make([]string, 0, len(items))
-	newVal := make(map[string]any, len(items))
-	for _, it := range items {
-		keys = append(keys, it.Key)
-		var parsed any
-		if err := json.Unmarshal([]byte(it.Value), &parsed); err == nil {
-			newVal[it.Key] = parsed
-		}
-	}
-
-	oldVal := map[string]any{}
-	if len(keys) > 0 {
-		var oldItems []ConfigItem
-		if err := db.Where("key IN ?", keys).Find(&oldItems).Error; err == nil {
-			for _, oi := range oldItems {
-				var parsed any
-				if err := json.Unmarshal([]byte(oi.Value), &parsed); err == nil {
-					oldVal[oi.Key] = parsed
-				}
-			}
-		}
-	}
-
-	err := db.Clauses(clause.OnConflict{
-		Columns:   []clause.Column{{Name: "key"}},
-		DoUpdates: clause.AssignmentColumns([]string{"value"}),
-	}).Create(&items).Error
-	if err != nil {
-		return err
-	}
-
-	publishEvent(oldVal, newVal)
-	return nil
-}
-
 func SetMany(cst map[string]any) error {
 	var items []ConfigItem
 	for k, v := range cst {

internal/config/settings.go

@@ -16,22 +16,20 @@ type Settings struct {
 	AutoDiscoveryKey       string `json:"auto_discovery_key" default:""`                       // 自动发现密钥
 	ScriptDomain           string `json:"script_domain" default:""`                            // 自定义脚本域名
 	SendIpAddrToGuest      bool   `json:"send_ip_addr_to_guest" default:"false"`               // 是否向访客页面发送 IP 地址，默认 false
+	SSRFProtectionEnabled  bool   `json:"ssrf_protection_enabled" default:"false"`             // 是否启用 SSRF 防护，默认关闭
 	EulaAccepted           bool   `json:"eula_accepted" default:"false"`
 	BaseScriptsURLKey      string `json:"base_scripts_url" default:""`
 	// GeoIP 配置
 	GeoIpEnabled  bool   `json:"geo_ip_enabled" default:"true"`
 	GeoIpProvider string `json:"geo_ip_provider" default:"ipinfo"` // empty, mmdb, ip-api, geojs
-	// Nezha 兼容（Agent gRPC）
-	NezhaCompatEnabled bool   `json:"nezha_compat_enabled" default:"false"`
-	NezhaCompatListen  string `json:"nezha_compat_listen" default:""` // 例如 0.0.0.0:5555
 	// OAuth 配置
-	OAuthEnabled          bool   `json:"o_auth_enabled" default:"false"`
-	OAuthProvider         string `json:"o_auth_provider" default:"github"`
-	DisablePasswordLogin  bool   `json:"disable_password_login" default:"false"`
-	CloudflareTunnelToken string `json:"cloudflare_tunnel_token" default:""`
+	OAuthEnabled         bool   `json:"o_auth_enabled" default:"false"`
+	OAuthProvider        string `json:"o_auth_provider" default:"github"`
+	DisablePasswordLogin bool   `json:"disable_password_login" default:"false"`
 	// 自定义美化
 	CustomHead string `json:"custom_head" default:""`
 	CustomBody string `json:"custom_body" default:""`
+
 	// 通知
 	NotificationEnabled        bool    `json:"notification_enabled" default:"true"` // 通知总开关
 	NotificationMethod         string  `json:"notification_method" default:"none"`
@@ -40,38 +38,33 @@ type Settings struct {
 	ExpireNotificationLeadDays int     `json:"expire_notification_lead_days" default:"7"`  // 过期前多少天通知，默认7天
 	LoginNotification          bool    `json:"login_notification" default:"true"`          // 登录通知
 	TrafficLimitPercentage     float64 `json:"traffic_limit_percentage" default:"80.00"`   // 流量限制百分比，默认80.00%
-	// Record
-	RecordEnabled          bool `json:"record_enabled" default:"true"`          // 是否启用记录功能
-	RecordPreserveTime     int  `json:"record_preserve_time" default:"720"`     // 记录保留时间，单位小时，默认30天
-	PingRecordPreserveTime int  `json:"ping_record_preserve_time" default:"24"` // Ping 记录保留时间，单位小时，默认1天
-	UpdatedAt              time.Time
+	UpdatedAt                  time.Time
 }
 
 const (
-	SitenameKey                   = "sitename"
-	DescriptionKey                = "description"
-	CorsOriginCheckEnabledKey     = "cors_origin_check_enabled"
-	CorsAllowedOriginsKey         = "cors_allowed_origins"
-	WsOriginCheckEnabledKey       = "ws_origin_check_enabled"
-	WsAllowedOriginsKey           = "ws_allowed_origins"
-	ThemeKey                      = "theme"
-	PrivateSiteKey                = "private_site"
-	ApiKeyKey                     = "api_key"
-	AutoDiscoveryKeyKey           = "auto_discovery_key"
-	ScriptDomainKey               = "script_domain"
-	SendIpAddrToGuestKey          = "send_ip_addr_to_guest"
-	EulaAcceptedKey               = "eula_accepted"
-	BaseScriptsURLKey             = "base_scripts_url"
-	GeoIpEnabledKey               = "geo_ip_enabled"
-	GeoIpProviderKey              = "geo_ip_provider"
-	NezhaCompatEnabledKey         = "nezha_compat_enabled"
-	NezhaCompatListenKey          = "nezha_compat_listen"
-	OAuthEnabledKey               = "o_auth_enabled"
-	OAuthProviderKey              = "o_auth_provider"
-	DisablePasswordLoginKey       = "disable_password_login"
-	CloudflareTunnelTokenKey      = "cloudflare_tunnel_token"
-	CustomHeadKey                 = "custom_head"
-	CustomBodyKey                 = "custom_body"
+	SitenameKey               = "sitename"
+	DescriptionKey            = "description"
+	CorsOriginCheckEnabledKey = "cors_origin_check_enabled"
+	CorsAllowedOriginsKey     = "cors_allowed_origins"
+	WsOriginCheckEnabledKey   = "ws_origin_check_enabled"
+	WsAllowedOriginsKey       = "ws_allowed_origins"
+	ThemeKey                  = "theme"
+	PrivateSiteKey            = "private_site"
+	ApiKeyKey                 = "api_key"
+	AutoDiscoveryKeyKey       = "auto_discovery_key"
+	ScriptDomainKey           = "script_domain"
+	SendIpAddrToGuestKey      = "send_ip_addr_to_guest"
+	SSRFProtectionEnabledKey  = "ssrf_protection_enabled"
+	EulaAcceptedKey           = "eula_accepted"
+	BaseScriptsURLKey         = "base_scripts_url"
+	GeoIpEnabledKey           = "geo_ip_enabled"
+	GeoIpProviderKey          = "geo_ip_provider"
+	OAuthEnabledKey           = "o_auth_enabled"
+	OAuthProviderKey          = "o_auth_provider"
+	DisablePasswordLoginKey   = "disable_password_login"
+	CustomHeadKey             = "custom_head"
+	CustomBodyKey             = "custom_body"
+
 	NotificationEnabledKey        = "notification_enabled"
 	NotificationMethodKey         = "notification_method"
 	NotificationTemplateKey       = "notification_template"
@@ -79,9 +72,7 @@ const (
 	ExpireNotificationLeadDaysKey = "expire_notification_lead_days"
 	LoginNotificationKey          = "login_notification"
 	TrafficLimitPercentageKey     = "traffic_limit_percentage"
-	RecordEnabledKey              = "record_enabled"
-	RecordPreserveTimeKey         = "record_preserve_time"
-	PingRecordPreserveTimeKey     = "ping_record_preserve_time"
 	UpdatedAtKey                  = "updated_at"
-	XtermjsSettingsKey            = "xtermjs_settings"
+	ThemeMarketSourcesKey         = "theme_market_sources"
+	PluginMarketSourcesKey        = "plugin_market_sources"
 )

internal/lifecycle/restart.go

@@ -0,0 +1,24 @@
+// Package lifecycle carries process-level requests without coupling web RPC
+// handlers to the server runtime.
+package lifecycle
+
+// RestartReason identifies why the current process must restart.
+type RestartReason string
+
+const RestartForMetricStoreStructureUpgrade RestartReason = "metric-store-structure-upgrade"
+
+var restartRequests = make(chan RestartReason, 1)
+
+// RequestRestart asks the running server to shut down cleanly and exit. A
+// pending request is sufficient because the process will be replaced.
+func RequestRestart(reason RestartReason) {
+	select {
+	case restartRequests <- reason:
+	default:
+	}
+}
+
+// RestartRequests returns process restart requests for the server runtime.
+func RestartRequests() <-chan RestartReason {
+	return restartRequests
+}

internal/managedconfig/selectors.go

@@ -0,0 +1,144 @@
+// Package managedconfig implements the shared managed-configuration behavior
+// used by themes and plugins.
+package managedconfig
+
+import (
+	"encoding/json"
+	"strings"
+
+	"github.com/komari-monitor/komari/database/dbcore"
+	"github.com/komari-monitor/komari/database/models"
+)
+
+const (
+	TypeNodes     = "nodes"
+	TypePingTasks = "pingtasks"
+)
+
+// Items returns the declared managed configuration items. An omitted type is
+// managed, matching the theme configuration default.
+func Items(configuration models.Configuration) []models.ManagedThemeConfigurationItem {
+	if configuration.Type != "" && !strings.EqualFold(configuration.Type, models.ThemeConfigurationManaged) {
+		return nil
+	}
+	raw, err := json.Marshal(configuration.Data)
+	if err != nil {
+		return nil
+	}
+	var items []models.ManagedThemeConfigurationItem
+	if err := json.Unmarshal(raw, &items); err != nil {
+		return nil
+	}
+	return items
+}
+
+func DefaultValue(item models.ManagedThemeConfigurationItem) any {
+	value := item.Default
+	if item.Type == "select" && (value == nil || value == "") && item.Options != "" {
+		options := strings.Split(item.Options, ",")
+		if len(options) > 0 {
+			return strings.TrimSpace(options[0])
+		}
+	}
+	if value != nil {
+		return value
+	}
+	switch item.Type {
+	case "number":
+		return float64(0)
+	case "switch":
+		return false
+	case TypeNodes, TypePingTasks:
+		return "[]"
+	default:
+		return ""
+	}
+}
+
+// ResolveForOutput decodes declared selectors, drops deleted references, and
+// returns typed arrays suitable for public theme settings and plugin config.
+func ResolveForOutput(values map[string]any, items []models.ManagedThemeConfigurationItem) error {
+	hasNodes := false
+	hasPingTasks := false
+	for _, item := range items {
+		switch item.Type {
+		case TypeNodes:
+			hasNodes = true
+		case TypePingTasks:
+			hasPingTasks = true
+		}
+	}
+
+	db := dbcore.GetDBInstance()
+	liveNodes := map[string]struct{}{}
+	if hasNodes {
+		var nodes []models.Client
+		if err := db.Select("uuid").Find(&nodes).Error; err != nil {
+			return err
+		}
+		for _, node := range nodes {
+			liveNodes[node.UUID] = struct{}{}
+		}
+	}
+	livePingTasks := map[uint]struct{}{}
+	if hasPingTasks {
+		var tasks []models.PingTask
+		if err := db.Select("id").Find(&tasks).Error; err != nil {
+			return err
+		}
+		for _, task := range tasks {
+			livePingTasks[task.Id] = struct{}{}
+		}
+	}
+
+	for _, item := range items {
+		if item.Key == "" {
+			continue
+		}
+		switch item.Type {
+		case TypeNodes:
+			selected := NodeIDs(values[item.Key])
+			filtered := make([]string, 0, len(selected))
+			for _, id := range selected {
+				if _, ok := liveNodes[id]; ok {
+					filtered = append(filtered, id)
+				}
+			}
+			values[item.Key] = filtered
+		case TypePingTasks:
+			selected := PingTaskIDs(values[item.Key])
+			filtered := make([]uint, 0, len(selected))
+			for _, id := range selected {
+				if _, ok := livePingTasks[id]; ok {
+					filtered = append(filtered, id)
+				}
+			}
+			values[item.Key] = filtered
+		}
+	}
+	return nil
+}
+
+func NodeIDs(value any) []string {
+	raw, ok := value.(string)
+	if !ok {
+		return nil
+	}
+	var ids []string
+	if json.Unmarshal([]byte(raw), &ids) != nil {
+		return nil
+	}
+	return ids
+}
+
+func PingTaskIDs(value any) []uint {
+	raw, ok := value.(string)
+	if !ok {
+		return nil
+	}
+	var ids []uint
+	if json.Unmarshal([]byte(raw), &ids) != nil {
+		return nil
+	}
+	return ids
+}

internal/metricstore/compaction.go

@@ -0,0 +1,60 @@
+package metricstore
+
+import (
+	"context"
+	"fmt"
+	"time"
+)
+
+func Compact(ctx context.Context, now time.Time) (int, error) {
+	if !compactOperations.TryAcquire() {
+		return 0, ErrCompactInProgress
+	}
+	defer compactOperations.Release()
+	if err := storeOperations.AcquireShared(ctx); err != nil {
+		return 0, fmt.Errorf("wait for metric store operation before compaction: %w", err)
+	}
+	defer storeOperations.ReleaseShared()
+
+	storeMu.RLock()
+	defer storeMu.RUnlock()
+	activeStore := store
+	if activeStore == nil {
+		return 0, fmt.Errorf("metric store not initialized")
+	}
+	total, err := activeStore.Flush(ctx, now)
+	if err != nil {
+		return 0, fmt.Errorf("flush closed metric minutes: %w", err)
+	}
+	coarse, err := activeStore.FlushCoarse(ctx, now)
+	if err != nil {
+		return total, fmt.Errorf("seal closed metric rollups: %w", err)
+	}
+	return total + coarse, nil
+}
+
+// CleanupExpired applies retention in a separate, low-frequency operation.
+// It intentionally shares Compact's gate so delete-heavy maintenance never
+// overlaps minute or coarse-rollup persistence.
+func CleanupExpired(ctx context.Context, now time.Time) (int64, error) {
+	if !compactOperations.TryAcquire() {
+		return 0, ErrCompactInProgress
+	}
+	defer compactOperations.Release()
+	if err := storeOperations.AcquireShared(ctx); err != nil {
+		return 0, fmt.Errorf("wait for metric store operation before retention cleanup: %w", err)
+	}
+	defer storeOperations.ReleaseShared()
+
+	storeMu.RLock()
+	defer storeMu.RUnlock()
+	activeStore := store
+	if activeStore == nil {
+		return 0, fmt.Errorf("metric store not initialized")
+	}
+	deleted, err := activeStore.CleanupExpired(ctx, now)
+	if err != nil {
+		return deleted, fmt.Errorf("clean up expired metric data: %w", err)
+	}
+	return deleted, nil
+}

internal/metricstore/config.go

@@ -0,0 +1,316 @@
+package metricstore
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/komari-monitor/komari/pkg/metric"
+)
+
+const (
+	// DefaultRollupRawRetention documents the fixed in-memory exact-sample
+	// window. Samples older than one minute are losslessly byte-encoded;
+	// older history is served by the persisted rollup ladder.
+	DefaultRollupRawRetention = 10 * time.Minute
+	DefaultRollupFinestTier   = time.Minute
+	defaultRollupPointLimit   = 600
+
+	defaultRollupMinuteRetentionMinutes     = defaultRollupPointLimit
+	defaultRollupFiveMinuteRetentionMinutes = 5 * defaultRollupPointLimit
+	defaultRollupHourRetentionHours         = defaultRollupPointLimit
+	defaultRollupDayRetentionDays           = 100 * 365
+)
+
+// MetricStoreConfig 保存 metric store 配置。
+//
+// 注意：metric store 现在始终启用（旧的 metric_store_enabled 开关已废弃）。
+// 未显式配置时默认使用 SQLite（./data/metrics.db）。
+type MetricStoreConfig struct {
+	Driver       string `json:"metric_db_driver" default:"sqlite"`         // 数据库类型: sqlite, mysql, postgresql
+	DSN          string `json:"metric_db_dsn" default:"./data/metrics.db"` // 数据库连接串
+	TablePrefix  string `json:"metric_table_prefix" default:"metric_"`     // 表名前缀
+	MaxOpenConns int    `json:"metric_max_open_conns" default:"25"`        // 最大连接数
+	MaxIdleConns int    `json:"metric_max_idle_conns" default:"5"`         // 最大空闲连接数
+	// RollupMinuteRetentionMinutes controls the persisted 1-minute bucket window.
+	RollupMinuteRetentionMinutes int `json:"metric_rollup_minute_retention_minutes" default:"600"`
+	// RollupFiveMinuteRetentionMinutes controls the persisted 5-minute bucket window.
+	RollupFiveMinuteRetentionMinutes int `json:"metric_rollup_five_minute_retention_minutes" default:"3000"`
+	// RollupHourRetentionHours controls the persisted 1-hour bucket window.
+	RollupHourRetentionHours int `json:"metric_rollup_hour_retention_hours" default:"600"`
+}
+
+// MetricStoreConfigKeys 配置键
+const (
+	MetricDBDriverKey                         = "metric_db_driver"
+	MetricDBDSNKey                            = "metric_db_dsn"
+	MetricTablePrefixKey                      = "metric_table_prefix"
+	MetricMaxOpenConnsKey                     = "metric_max_open_conns"
+	MetricMaxIdleConnsKey                     = "metric_max_idle_conns"
+	MetricRollupMinuteRetentionMinutesKey     = "metric_rollup_minute_retention_minutes"
+	MetricRollupFiveMinuteRetentionMinutesKey = "metric_rollup_five_minute_retention_minutes"
+	MetricRollupHourRetentionHoursKey         = "metric_rollup_hour_retention_hours"
+	// MigrationTargetKey 记录上一次成功完成手动迁移的目标指纹（driver+dsn），
+	// 用于在下一次管理员手动迁移时推断默认源库。
+	MigrationTargetKey = "metric_migration_target"
+)
+
+func targetFingerprint(cfg *MetricStoreConfig) string {
+	driver := ResolveDriverFromConfig(cfg.Driver, cfg.DSN)
+	dsn := strings.TrimSpace(cfg.DSN)
+	return fmt.Sprintf("%s|%s", driver, dsn)
+}
+
+// buildMetricConfig 根据 MetricStoreConfig 构造底层 metric.Config。
+// autoMigrate 控制是否在 Open 时自动建表：正式初始化/热加载时为 true，
+// 仅做连接测试时为 false（不写入 schema，避免对目标库产生副作用）。
+func buildMetricConfig(cfg *MetricStoreConfig, autoMigrate bool) (metric.Config, error) {
+	driver := ResolveDriverFromConfig(cfg.Driver, cfg.DSN)
+
+	tablePrefix := cfg.TablePrefix
+	if tablePrefix == "" {
+		tablePrefix = "metric_"
+	}
+	opts := []metric.Option{
+		metric.WithTablePrefix(tablePrefix),
+		metric.WithAutoMigrate(autoMigrate),
+	}
+	policy, err := rollupPolicyFromConfig(cfg)
+	if err != nil {
+		return metric.Config{}, err
+	}
+	opts = append(opts, metric.WithRollupPolicy(policy))
+
+	switch driver {
+	case metric.DriverSQLite:
+		dsn := cfg.DSN
+		if dsn == "" || dsn == "./data/metrics.db" {
+			// 注意：刻意不使用 cache=shared。SQLite 共享缓存模式使用表级锁，
+			// 当一个连接持有读锁、另一个连接尝试写入时会立即返回
+			// SQLITE_LOCKED（"database table is locked"），且 busy_timeout
+			// 对共享缓存的表级锁无效，迁移期间与前台查询/实时写入并发时必然报错。
+			// _txlock=immediate 让写事务开始即获取写锁，避免锁升级死锁。
+			dsn = "file:./data/metrics.db?mode=rwc&_txlock=immediate"
+		} else {
+			// 用户自定义 DSN 时，剥离 cache=shared，避免上述表级锁问题。
+			dsn = stripSharedCache(dsn)
+		}
+		// SQLite 串行化写入：固定单写连接以避免 "database is locked" 竞争，
+		// 同时启用独立的 WAL 只读连接池提升前台查询并发（写仍走单主连接）。
+		// 这里刻意忽略 cfg.MaxOpenConns/MaxIdleConns —— 对 SQLite 而言多写连接
+		// 只会引入锁竞争而非提升吞吐。
+		opts = append(opts, metric.WithMaxOpenConns(1), metric.WithMaxIdleConns(1))
+		opts = append(opts, metric.WithSQLiteReadPool(2))
+		return metric.SQLite(dsn, opts...), nil
+	case metric.DriverMySQL:
+		opts = append(opts,
+			metric.WithMaxOpenConns(cfg.MaxOpenConns),
+			metric.WithMaxIdleConns(cfg.MaxIdleConns),
+		)
+		return metric.MySQL(cfg.DSN, opts...), nil
+	case metric.DriverPostgreSQL:
+		opts = append(opts,
+			metric.WithMaxOpenConns(cfg.MaxOpenConns),
+			metric.WithMaxIdleConns(cfg.MaxIdleConns),
+		)
+		return metric.PostgreSQL(cfg.DSN, opts...), nil
+	default:
+		return metric.Config{}, fmt.Errorf("unsupported metric database driver: %s", cfg.Driver)
+	}
+}
+
+func defaultRollupPolicy() metric.RollupPolicy {
+	return rollupPolicyFromValues(
+		defaultRollupMinuteRetentionMinutes,
+		defaultRollupFiveMinuteRetentionMinutes,
+		defaultRollupHourRetentionHours,
+	)
+}
+
+func rollupPolicyFromConfig(cfg *MetricStoreConfig) (metric.RollupPolicy, error) {
+	minuteRetention := cfg.RollupMinuteRetentionMinutes
+	fiveMinuteRetention := cfg.RollupFiveMinuteRetentionMinutes
+	hourRetention := cfg.RollupHourRetentionHours
+	// Configs constructed by older callers do not have the new fields. Treat
+	// their zero values as omitted so recovery and migration remain compatible.
+	if minuteRetention == 0 {
+		minuteRetention = defaultRollupMinuteRetentionMinutes
+	}
+	if fiveMinuteRetention == 0 {
+		fiveMinuteRetention = defaultRollupFiveMinuteRetentionMinutes
+	}
+	if hourRetention == 0 {
+		hourRetention = defaultRollupHourRetentionHours
+	}
+	if minuteRetention < 0 || fiveMinuteRetention < 0 || hourRetention < 0 {
+		return metric.RollupPolicy{}, fmt.Errorf("metric rollup retention values must be positive integers")
+	}
+
+	minuteDuration, err := rollupDuration(minuteRetention, time.Minute)
+	if err != nil {
+		return metric.RollupPolicy{}, err
+	}
+	fiveMinuteDuration, err := rollupDuration(fiveMinuteRetention, time.Minute)
+	if err != nil {
+		return metric.RollupPolicy{}, err
+	}
+	hourDuration, err := rollupDuration(hourRetention, time.Hour)
+	if err != nil {
+		return metric.RollupPolicy{}, err
+	}
+
+	policy := rollupPolicyFromDurations(minuteDuration, fiveMinuteDuration, hourDuration)
+	if err := policy.Validate(); err != nil {
+		return metric.RollupPolicy{}, fmt.Errorf("invalid metric rollup retention policy: %w", err)
+	}
+	return policy, nil
+}
+
+func rollupPolicyFromValues(minuteRetentionMinutes, fiveMinuteRetentionMinutes, hourRetentionHours int) metric.RollupPolicy {
+	return rollupPolicyFromDurations(
+		time.Duration(minuteRetentionMinutes)*time.Minute,
+		time.Duration(fiveMinuteRetentionMinutes)*time.Minute,
+		time.Duration(hourRetentionHours)*time.Hour,
+	)
+}
+
+func rollupPolicyFromDurations(minuteRetention, fiveMinuteRetention, hourRetention time.Duration) metric.RollupPolicy {
+	return metric.RollupPolicy{
+		RawRetention: DefaultRollupRawRetention,
+		Tiers: []metric.RollupTier{
+			{Interval: time.Minute, Retention: minuteRetention},
+			{Interval: 5 * time.Minute, Retention: fiveMinuteRetention},
+			{Interval: time.Hour, Retention: hourRetention},
+			// Daily buckets form the terminal tier. They remain available until
+			// the metric's own retention policy removes them.
+			{Interval: 24 * time.Hour, Retention: time.Duration(defaultRollupDayRetentionDays) * 24 * time.Hour},
+		},
+		Compression: 30,
+	}
+}
+
+func rollupDuration(value int, unit time.Duration) (time.Duration, error) {
+	maxDurationValue := int64((time.Duration(1<<63 - 1)) / unit)
+	if value <= 0 || int64(value) > maxDurationValue {
+		return 0, fmt.Errorf("metric rollup retention value must be a positive duration")
+	}
+	return time.Duration(value) * unit, nil
+}
+
+// ResolveDriverFromConfig 根据 DSN 自动推断 metrics 数据库类型；当 DSN 不能可靠
+// 识别时回退到旧配置中的 driver，以兼容已有配置和非常规 DSN。
+func ResolveDriverFromConfig(configuredDriver, dsn string) metric.Driver {
+	if driver, ok := InferDriverFromDSN(dsn); ok {
+		return driver
+	}
+
+	switch driver := metric.Driver(strings.ToLower(strings.TrimSpace(configuredDriver))); driver {
+	case metric.DriverSQLite, metric.DriverMySQL, metric.DriverPostgreSQL:
+		return driver
+	default:
+		return metric.DriverSQLite
+	}
+}
+
+// InferDriverFromDSN 尽量根据常见 DSN 格式推断数据库类型。
+// 返回 ok=false 表示格式不够明确，调用方应使用已有配置作为兜底。
+func InferDriverFromDSN(dsn string) (metric.Driver, bool) {
+	raw := strings.TrimSpace(dsn)
+	if raw == "" {
+		return metric.DriverSQLite, true
+	}
+	lower := strings.ToLower(raw)
+
+	// PostgreSQL URL DSN: postgres://... 或 postgresql://...
+	if strings.HasPrefix(lower, "postgres://") || strings.HasPrefix(lower, "postgresql://") {
+		return metric.DriverPostgreSQL, true
+	}
+
+	// SQLite 常见文件/内存 DSN。
+	if raw == ":memory:" || strings.HasPrefix(lower, "file:") || strings.HasPrefix(lower, "sqlite://") || strings.HasPrefix(lower, "sqlite3://") {
+		return metric.DriverSQLite, true
+	}
+
+	// MySQL URL（虽然 go-sql-driver/mysql 原生 DSN 通常不是 URL，但这里用于给出
+	// 类型推断；连接测试仍会校验 DSN 是否可被驱动接受）。
+	if strings.HasPrefix(lower, "mysql://") {
+		return metric.DriverMySQL, true
+	}
+
+	// PostgreSQL 关键字/值 DSN: host=... user=... dbname=...
+	if looksLikePostgreSQLKeyValueDSN(lower) {
+		return metric.DriverPostgreSQL, true
+	}
+
+	// go-sql-driver/mysql DSN: user:pass@tcp(host:3306)/db、user@unix(...)/db、user:pass@/db 等。
+	if looksLikeMySQLDSN(lower) {
+		return metric.DriverMySQL, true
+	}
+
+	// SQLite 路径：./data/metrics.db、/var/lib/metrics.sqlite3、metrics.sqlite 等。
+	if looksLikeSQLitePath(lower) {
+		return metric.DriverSQLite, true
+	}
+
+	return "", false
+}
+
+func looksLikePostgreSQLKeyValueDSN(lower string) bool {
+	if !strings.Contains(lower, "=") || strings.Contains(lower, "://") {
+		return false
+	}
+	keys := []string{"host=", "user=", "password=", "dbname=", "port=", "sslmode="}
+	matched := 0
+	for _, key := range keys {
+		if strings.Contains(lower, key) {
+			matched++
+		}
+	}
+	// dbname= 基本是 PostgreSQL libpq DSN 的强特征；否则至少匹配两个常见键。
+	return strings.Contains(lower, "dbname=") || matched >= 2
+}
+
+func looksLikeMySQLDSN(lower string) bool {
+	if strings.Contains(lower, "://") || strings.Contains(lower, " ") {
+		return false
+	}
+	if strings.Contains(lower, "@tcp(") || strings.Contains(lower, "@unix(") || strings.Contains(lower, "@/") {
+		return true
+	}
+	// user:pass@host/db、user@host/db 这类虽然不是推荐格式，但也明显偏 MySQL。
+	return strings.Contains(lower, "@") && strings.Contains(lower, "/")
+}
+
+func looksLikeSQLitePath(lower string) bool {
+	path := lower
+	if idx := strings.IndexAny(path, "?"); idx >= 0 {
+		path = path[:idx]
+	}
+	return strings.HasSuffix(path, ".db") || strings.HasSuffix(path, ".sqlite") || strings.HasSuffix(path, ".sqlite3")
+}
+
+// stripSharedCache 从 SQLite DSN 中移除 cache=shared 参数，避免共享缓存模式下的
+// 表级锁（SQLITE_LOCKED "database table is locked"）。其它参数保持不变。
+func stripSharedCache(dsn string) string {
+	if !strings.Contains(dsn, "cache=shared") {
+		return dsn
+	}
+	idx := strings.Index(dsn, "?")
+	if idx < 0 {
+		return dsn
+	}
+	base := dsn[:idx]
+	query := dsn[idx+1:]
+	parts := strings.Split(query, "&")
+	kept := parts[:0]
+	for _, p := range parts {
+		if p == "cache=shared" {
+			continue
+		}
+		kept = append(kept, p)
+	}
+	if len(kept) == 0 {
+		return base
+	}
+	return base + "?" + strings.Join(kept, "&")
+}

internal/metricstore/definitions.go

@@ -0,0 +1,104 @@
+package metricstore
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/komari-monitor/komari/pkg/metric"
+)
+
+const defaultBuiltinMetricRetentionDays = 1
+
+// RetentionSummary is the compatibility view of all persisted metric policies.
+type RetentionSummary struct {
+	AllPositive bool
+	MaxDays     int
+}
+
+// GetRetentionSummary aggregates the active store's metric definitions. An
+// empty definition set is not considered record-enabled.
+func GetRetentionSummary(ctx context.Context) (RetentionSummary, error) {
+	s := GetStore()
+	if s == nil {
+		return RetentionSummary{}, fmt.Errorf("metric store not initialized")
+	}
+	defs, err := s.ListMetrics(ctx)
+	if err != nil {
+		return RetentionSummary{}, err
+	}
+	return summarizeRetentionDefinitions(defs), nil
+}
+
+func summarizeRetentionDefinitions(defs []metric.Definition) RetentionSummary {
+	if len(defs) == 0 {
+		return RetentionSummary{}
+	}
+	summary := RetentionSummary{AllPositive: true}
+	for _, def := range defs {
+		if def.RetentionDays <= 0 {
+			summary.AllPositive = false
+		}
+		if def.RetentionDays > summary.MaxDays {
+			summary.MaxDays = def.RetentionDays
+		}
+	}
+	return summary
+}
+
+// createMetricDefinitions creates built-in definitions with explicit policies.
+func createMetricDefinitions(ctx context.Context, s *metric.Store) error {
+	return createMetricDefinitionsWithDefaultRetention(ctx, s, defaultBuiltinMetricRetentionDays)
+}
+
+// EnsureBuiltinMetricDefinitions registers definitions for the server's
+// built-in report and ping writers before a standalone Store receives points.
+func EnsureBuiltinMetricDefinitions(ctx context.Context, s *metric.Store) error {
+	return createMetricDefinitions(ctx, s)
+}
+
+func createMetricDefinitionsWithDefaultRetention(ctx context.Context, s *metric.Store, defaultRetentionDays int) error {
+	if defaultRetentionDays < defaultBuiltinMetricRetentionDays {
+		defaultRetentionDays = defaultBuiltinMetricRetentionDays
+	}
+	definitions := []metric.Definition{
+		{Name: MetricCPU, Type: metric.TypeGauge, Unit: "%", Description: "CPU usage percentage", RetentionDays: defaultRetentionDays},
+		{Name: MetricGPU, Type: metric.TypeGauge, Unit: "%", Description: "GPU usage percentage", RetentionDays: defaultRetentionDays},
+		{Name: MetricGPUDeviceUsage, Type: metric.TypeGauge, Unit: "%", Description: "Per-device GPU utilization", RetentionDays: defaultRetentionDays},
+		{Name: MetricGPUMem, Type: metric.TypeGauge, Unit: "bytes", Description: "GPU memory used", RetentionDays: defaultRetentionDays},
+		{Name: MetricGPUMemTotal, Type: metric.TypeGauge, Unit: "bytes", Description: "GPU memory total", RetentionDays: defaultRetentionDays},
+		{Name: MetricGPUTemp, Type: metric.TypeGauge, Unit: "°C", Description: "GPU temperature", RetentionDays: defaultRetentionDays},
+		{Name: MetricRAM, Type: metric.TypeGauge, Unit: "bytes", Description: "RAM used", RetentionDays: defaultRetentionDays},
+		{Name: MetricSwap, Type: metric.TypeGauge, Unit: "bytes", Description: "Swap used", RetentionDays: defaultRetentionDays},
+		{Name: MetricLoad, Type: metric.TypeGauge, Unit: "", Description: "System load average", RetentionDays: defaultRetentionDays},
+		{Name: MetricDisk, Type: metric.TypeGauge, Unit: "bytes", Description: "Disk used", RetentionDays: defaultRetentionDays},
+		{Name: MetricNetIn, Type: metric.TypeGauge, Unit: "bytes/s", Description: "Network in rate", RetentionDays: defaultRetentionDays},
+		{Name: MetricNetOut, Type: metric.TypeGauge, Unit: "bytes/s", Description: "Network out rate", RetentionDays: defaultRetentionDays},
+		{Name: MetricNetTotalUp, Type: metric.TypeCounter, Unit: "bytes", Description: "Network total upload", RetentionDays: defaultRetentionDays},
+		{Name: MetricNetTotalDown, Type: metric.TypeCounter, Unit: "bytes", Description: "Network total download", RetentionDays: defaultRetentionDays},
+		{Name: MetricTrafficUp, Type: metric.TypeGauge, Unit: "bytes", Description: "Traffic upload delta", RetentionDays: defaultRetentionDays},
+		{Name: MetricTrafficDown, Type: metric.TypeGauge, Unit: "bytes", Description: "Traffic download delta", RetentionDays: defaultRetentionDays},
+		{Name: MetricProcess, Type: metric.TypeGauge, Unit: "count", Description: "Process count", RetentionDays: defaultRetentionDays},
+		{Name: MetricConnections, Type: metric.TypeGauge, Unit: "count", Description: "TCP connections", RetentionDays: defaultRetentionDays},
+		{Name: MetricConnectionsUDP, Type: metric.TypeGauge, Unit: "count", Description: "UDP connections", RetentionDays: defaultRetentionDays},
+		{Name: MetricPingLatency, Type: metric.TypeGauge, Unit: "ms", Description: "Ping latency", RetentionDays: defaultRetentionDays},
+		{Name: MetricPingLoss, Type: metric.TypeGauge, Unit: "ratio", Description: "Ping packet loss indicator", RetentionDays: defaultRetentionDays},
+	}
+
+	for _, def := range definitions {
+		existing, err := s.GetMetric(ctx, def.Name)
+		if err != nil && !errors.Is(err, metric.ErrNotFound) {
+			return fmt.Errorf("failed to get metric %s: %w", def.Name, err)
+		}
+		if err == nil {
+			if existing.RetentionDays == 0 {
+				continue
+			}
+			def.RetentionDays = existing.RetentionDays
+		}
+		if err := s.UpsertMetric(ctx, def); err != nil {
+			return fmt.Errorf("failed to create metric %s: %w", def.Name, err)
+		}
+	}
+	return nil
+}

internal/metricstore/deletion.go

@@ -0,0 +1,104 @@
+package metricstore
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	logger "github.com/komari-monitor/komari/utils/log"
+
+	"github.com/komari-monitor/komari/pkg/metric"
+)
+
+// farFuture 返回一个足够远的未来时间，用于以 DeleteBefore 语义清空某指标的全部数据。
+func farFuture() time.Time {
+	return time.Now().UTC().Add(24 * 365 * time.Hour)
+}
+
+// DeleteAllRecords 删除所有负载/系统类记录（保留指标定义，不含 ping）。
+func DeleteAllRecords(ctx context.Context) error {
+	s := GetStore()
+	if s == nil {
+		return fmt.Errorf("metric store not enabled")
+	}
+
+	for _, metricName := range recordMetricNames {
+		if _, err := s.DeleteBefore(ctx, metricName, farFuture()); err != nil {
+			logger.Errorf("metricstore", "Failed to delete metric %s: %v", metricName, err)
+		}
+	}
+	clearReportTrafficStates()
+
+	return nil
+}
+
+// DeleteAllPingRecords 删除全部 ping 记录（保留指标定义）。
+func DeleteAllPingRecords(ctx context.Context) error {
+	s := GetStore()
+	if s == nil {
+		return fmt.Errorf("metric store not enabled")
+	}
+	for _, metricName := range pingMetricNames {
+		if _, err := s.DeleteBefore(ctx, metricName, farFuture()); err != nil {
+			return fmt.Errorf("failed to delete ping records: %w", err)
+		}
+	}
+	return nil
+}
+
+// DeletePingRecordsByTask 删除指定任务（task_id）的全部 ping 记录。
+func DeletePingRecordsByTask(ctx context.Context, taskIDs []uint) error {
+	s := GetStore()
+	if s == nil {
+		return fmt.Errorf("metric store not enabled")
+	}
+	for _, id := range taskIDs {
+		for _, metricName := range pingMetricNames {
+			if _, err := s.DeleteSeries(ctx, metric.Query{
+				MetricName: metricName,
+				Tags:       map[string]string{"task_id": fmt.Sprintf("%d", id)},
+			}); err != nil {
+				return fmt.Errorf("failed to delete ping records for task %d: %w", id, err)
+			}
+		}
+	}
+	return nil
+}
+
+// DeleteEntity 删除指定 agent 在所有指标下的历史数据。
+func DeleteEntity(ctx context.Context, entityID string) error {
+	s := GetStore()
+	if s == nil {
+		return fmt.Errorf("metric store not enabled")
+	}
+	if _, err := s.DeleteEntity(ctx, entityID); err != nil {
+		return fmt.Errorf("failed to delete metric records for entity %s: %w", entityID, err)
+	}
+	deleteReportTrafficState(entityID)
+	return nil
+}
+
+// DeleteEntityAsync clears one agent's metric history without delaying the
+// client deletion response.
+func DeleteEntityAsync(entityID string) {
+	go func() {
+		if err := DeleteEntity(context.Background(), entityID); err != nil {
+			logger.Errorf("metricstore", "Failed to delete metric records for entity %s: %v", entityID, err)
+		}
+	}()
+}
+
+// DeleteMetricDataAsync clears disabled metric history without delaying an
+// admin retention-policy update response.
+func DeleteMetricDataAsync(metricName string) {
+	go func() {
+		s := GetStore()
+		if s == nil {
+			logger.Errorf("metricstore", "Failed to delete disabled metric %s: metric store not enabled", metricName)
+			return
+		}
+		if _, err := s.DeleteMetricDataIfDisabled(context.Background(), metricName); err != nil {
+			logger.Errorf("metricstore", "Failed to delete disabled metric %s: %v", metricName, err)
+		}
+	}()
+}

internal/metricstore/legacy_records.go

@@ -0,0 +1,307 @@
+package metricstore
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"time"
+
+	"github.com/komari-monitor/komari/database/models"
+	"github.com/komari-monitor/komari/pkg/metric"
+)
+
+// RecordQueryOptions narrows the record reconstruction work. MetricNames
+// limits which stored load metrics are queried; empty means all load metrics.
+// MaxPoints is a total response-point budget; it is applied before aggregation,
+// so an all-client query does not materialize thousands of points per client
+// only to sample them afterwards.
+type RecordQueryOptions struct {
+	MetricNames []string
+	MaxPoints   int
+}
+
+// GetRecordsByClientAndTime 从 metric store 查询记录并重构为 models.Record。
+// opts 为空表示兼容旧行为；有值时用于指标选择和点数预算。
+func GetRecordsByClientAndTime(ctx context.Context, clientUUID string, start, end time.Time, opts ...RecordQueryOptions) ([]models.Record, error) {
+	s := GetStore()
+	if s == nil {
+		return nil, fmt.Errorf("metric store not enabled")
+	}
+
+	return getRecordsFromSeries(ctx, s, clientUUID, start, end, false, firstRecordOptions(opts))
+}
+
+func firstRecordOptions(opts []RecordQueryOptions) RecordQueryOptions {
+	if len(opts) == 0 {
+		return RecordQueryOptions{}
+	}
+	return opts[0]
+}
+
+// GetRecordMetricMaxByClientAndTime 查询单项监控指标在各时间桶内的最大值。
+func GetRecordMetricMaxByClientAndTime(ctx context.Context, clientUUID, recordMetric string, start, end time.Time) ([]models.Record, error) {
+	s := GetStore()
+	if s == nil {
+		return nil, fmt.Errorf("metric store not enabled")
+	}
+
+	return getRecordMetricMaxByClientAndTimeFromSeries(ctx, s, clientUUID, recordMetric, start, end)
+}
+
+// GetRecordsByTime 从 metric store 查询所有客户端在时间范围内的记录。
+// opts 为空表示兼容旧行为；有值时用于指标选择和总点数预算。
+func GetRecordsByTime(ctx context.Context, start, end time.Time, opts ...RecordQueryOptions) ([]models.Record, error) {
+	s := GetStore()
+	if s == nil {
+		return nil, fmt.Errorf("metric store not enabled")
+	}
+
+	// Query all entities together. Entity-only grouping retains the old per-client
+	// aggregation across tags without repeating the tier scan for every client.
+	return getRecordsFromSeries(ctx, s, "", start, end, true, firstRecordOptions(opts))
+}
+
+type recordSeriesKey struct {
+	client string
+	ts     int64
+}
+
+func getRecordsFromSeries(ctx context.Context, s *metric.Store, clientUUID string, start, end time.Time, allEntities bool, opts RecordQueryOptions) ([]models.Record, error) {
+	metricNames := opts.MetricNames
+	if len(metricNames) == 0 {
+		metricNames = loadRecordMetricNames
+	}
+	specs := make([]MetricSpec, 0, len(metricNames))
+	for _, name := range metricNames {
+		specs = append(specs, MetricSpec{Name: name, Aggregations: []metric.Aggregation{recordMetricAggregation(name)}})
+	}
+	entities := EntityScope{All: allEntities}
+	grouping := GroupMerged
+	if allEntities {
+		grouping = GroupEntity
+	} else {
+		entities.IDs = []string{clientUUID}
+	}
+	rounding := RoundFloor
+	if opts.MaxPoints > 0 {
+		rounding = RoundCeil
+	}
+	loaded, err := QueryMetrics(ctx, MetricsQuery{
+		Store: s, Mode: QuerySeries, Source: SourceRollup,
+		OmitTags: true, OmitLabels: true, CompactDefinitions: true,
+		Entities: entities, Specs: specs, Start: start, End: end,
+		Order: metric.OrderAsc, Grouping: grouping,
+		Budget:   PointBudget{PerSeries: 500, Total: opts.MaxPoints},
+		Rounding: rounding, AllowMissing: true,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("failed to query metrics: %w", err)
+	}
+	return assembleRecordsFromSeries(loaded.Values, clientUUID), nil
+}
+
+// assembleRecordsFromSeries unions metric buckets without allocating a record per key.
+func assembleRecordsFromSeries(values map[string]map[metric.Aggregation][]metric.AggregatePoint, clientUUID string) []models.Record {
+	// Aligned metrics normally share buckets: the largest selected metric is a
+	// conservative capacity estimate, not the sum of the metric fanout. Missing
+	// buckets can grow the union beyond it (and duplicate seconds can shrink it).
+	capacity := 0
+	for name, aggregations := range values {
+		if n := len(aggregations[recordMetricAggregation(name)]); n > capacity {
+			capacity = n
+		}
+	}
+	records := make([]models.Record, 0, capacity)
+	recordIndex := make(map[recordSeriesKey]int, capacity)
+	for metricName, aggMap := range values {
+		agg := recordMetricAggregation(metricName)
+		points, ok := aggMap[agg]
+		if !ok {
+			continue
+		}
+		for _, point := range points {
+			entityID := point.EntityID
+			if entityID == "" {
+				entityID = clientUUID
+			}
+			key := recordSeriesKey{client: entityID, ts: point.Bucket.Unix()}
+			index, exists := recordIndex[key]
+			if !exists {
+				index = len(records)
+				recordIndex[key] = index
+				records = append(records, models.Record{
+					Client: entityID,
+					Time:   point.Bucket.UTC(),
+				})
+			}
+			// Resolve the address after append: the backing array may have moved.
+			applyRecordMetricValue(&records[index], metricName, point.Value)
+		}
+	}
+
+	sortRecords(records)
+	return records
+}
+
+func getRecordMetricMaxByClientAndTimeFromSeries(ctx context.Context, s *metric.Store, clientUUID, recordMetric string, start, end time.Time) ([]models.Record, error) {
+	metricName, ok := metricNameForRecordField(recordMetric)
+	if !ok {
+		return nil, fmt.Errorf("unsupported record metric %q", recordMetric)
+	}
+
+	loaded, err := QueryMetrics(ctx, MetricsQuery{
+		Store: s, Mode: QuerySeries, Source: SourceRollup,
+		OmitTags: true, OmitLabels: true, CompactDefinitions: true,
+		Entities: EntityScope{IDs: []string{clientUUID}},
+		Specs:    []MetricSpec{{Name: metricName, Aggregations: []metric.Aggregation{metric.AggMax}}},
+		Start:    start, End: end, Order: metric.OrderAsc, Grouping: GroupMerged,
+		Budget: PointBudget{PerSeries: 500}, Rounding: RoundFloor, AllowMissing: true,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("failed to query metric %s: %w", metricName, err)
+	}
+
+	points := loaded.Values[metricName][metric.AggMax]
+	records := make([]models.Record, 0, len(points))
+	for _, point := range points {
+		entityID := point.EntityID
+		if entityID == "" {
+			entityID = clientUUID
+		}
+		record := models.Record{Client: entityID, Time: point.Bucket.UTC()}
+		applyRecordMetricValue(&record, metricName, point.Value)
+		records = append(records, record)
+	}
+	return records, nil
+}
+
+func recordMetricAggregation(metricName string) metric.Aggregation {
+	switch metricName {
+	case MetricTrafficUp, MetricTrafficDown:
+		return metric.AggSum
+	case MetricNetTotalUp, MetricNetTotalDown:
+		return metric.AggLast
+	default:
+		return metric.AggAvg
+	}
+}
+
+func applyRecordMetricValue(rec *models.Record, metricName string, value float64) {
+	switch metricName {
+	case MetricCPU:
+		rec.Cpu = float32(value)
+	case MetricGPU:
+		rec.Gpu = float32(value)
+	case MetricRAM:
+		rec.Ram = int64(value)
+	case MetricSwap:
+		rec.Swap = int64(value)
+	case MetricLoad:
+		rec.Load = float32(value)
+	case MetricDisk:
+		rec.Disk = int64(value)
+	case MetricNetIn:
+		rec.NetIn = int64(value)
+	case MetricNetOut:
+		rec.NetOut = int64(value)
+	case MetricNetTotalUp:
+		rec.NetTotalUp = int64(value)
+	case MetricNetTotalDown:
+		rec.NetTotalDown = int64(value)
+	case MetricTrafficUp:
+		rec.TrafficUp = int64(value)
+	case MetricTrafficDown:
+		rec.TrafficDown = int64(value)
+	case MetricProcess:
+		rec.Process = int(value)
+	case MetricConnections:
+		rec.Connections = int(value)
+	case MetricConnectionsUDP:
+		rec.ConnectionsUdp = int(value)
+	}
+}
+
+func sortRecords(records []models.Record) {
+	sort.Slice(records, func(i, j int) bool {
+		if records[i].Client != records[j].Client {
+			return records[i].Client < records[j].Client
+		}
+		return records[i].Time.Before(records[j].Time)
+	})
+}
+
+// GetGPURecordsByClientAndTime 从 metric store 查询 GPU 记录
+func GetGPURecordsByClientAndTime(ctx context.Context, clientUUID string, start, end time.Time) ([]models.GPURecord, error) {
+	s := GetStore()
+	if s == nil {
+		return nil, fmt.Errorf("metric store not enabled")
+	}
+
+	// 查询 GPU 相关指标（每设备利用率使用独立指标 gpu.device.usage）
+	gpuMetrics := []string{MetricGPUDeviceUsage, MetricGPUMem, MetricGPUMemTotal, MetricGPUTemp}
+
+	// 按设备索引和时间组织数据
+	type gpuKey struct {
+		deviceIndex int
+		timestamp   int64
+	}
+	recordMap := make(map[gpuKey]*models.GPURecord)
+
+	specs := make([]MetricSpec, 0, len(gpuMetrics))
+	for _, name := range gpuMetrics {
+		specs = append(specs, MetricSpec{Name: name})
+	}
+	loaded, err := QueryMetrics(ctx, MetricsQuery{
+		Store: s, Mode: QueryPoints, Source: SourceRaw,
+		OmitLabels: true, CompactDefinitions: true,
+		Entities: EntityScope{IDs: []string{clientUUID}}, Specs: specs,
+		Start: start, End: end, Order: metric.OrderAsc, AllowMissing: true,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("failed to query GPU metrics: %w", err)
+	}
+	for _, metricName := range gpuMetrics {
+		points := loaded.Raw[metricName]
+
+		for _, p := range points {
+			deviceIndex := 0
+			deviceName := ""
+			if idx, ok := p.Tags["device_index"]; ok {
+				fmt.Sscanf(idx, "%d", &deviceIndex)
+			}
+			if name, ok := p.Tags["device_name"]; ok {
+				deviceName = name
+			}
+
+			key := gpuKey{deviceIndex: deviceIndex, timestamp: p.Timestamp.Unix()}
+			if recordMap[key] == nil {
+				recordMap[key] = &models.GPURecord{
+					Client:      clientUUID,
+					Time:        p.Timestamp.UTC(),
+					DeviceIndex: deviceIndex,
+					DeviceName:  deviceName,
+				}
+			}
+			rec := recordMap[key]
+
+			switch metricName {
+			case MetricGPUDeviceUsage:
+				rec.Utilization = float32(p.Value)
+			case MetricGPUMem:
+				rec.MemUsed = int64(p.Value)
+			case MetricGPUMemTotal:
+				rec.MemTotal = int64(p.Value)
+			case MetricGPUTemp:
+				rec.Temperature = int(p.Value)
+			}
+		}
+	}
+
+	// 转换为切片
+	records := make([]models.GPURecord, 0, len(recordMap))
+	for _, rec := range recordMap {
+		records = append(records, *rec)
+	}
+
+	return records, nil
+}

internal/metricstore/maintenance.go

@@ -0,0 +1,114 @@
+package metricstore
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/komari-monitor/komari/pkg/metric"
+)
+
+var (
+	ErrStoreNotInitialized = errors.New("metric store not initialized")
+	ErrStoreBusy           = errors.New("metric store is busy")
+)
+
+// StorageInfo describes the physical storage owned by the active metric store.
+// Size remains useful even when the store points at an external database because
+// pkg/metric limits its query to the three tables managed by this Store.
+type StorageInfo struct {
+	Driver metric.Driver
+	Action metric.MaintenanceAction
+	Size   int64
+}
+
+// MaintenanceResult keeps measurement failures separate from the maintenance
+// error. A database may allow table maintenance while denying catalog queries,
+// and callers should still be able to report that the operation succeeded.
+type MaintenanceResult struct {
+	Driver          metric.Driver
+	Action          metric.MaintenanceAction
+	Before          int64
+	After           int64
+	BeforeSizeError error
+	AfterSizeError  error
+}
+
+// InspectStorage reads physical storage information while preventing a store
+// reload from closing the active connection underneath the query.
+func InspectStorage(ctx context.Context) (StorageInfo, error) {
+	if err := storeOperations.AcquireShared(ctx); err != nil {
+		return StorageInfo{}, fmt.Errorf("wait for metric store operations before inspection: %w", err)
+	}
+	defer storeOperations.ReleaseShared()
+
+	storeMu.RLock()
+	activeStore := store
+	storeMu.RUnlock()
+	if activeStore == nil {
+		return StorageInfo{}, ErrStoreNotInitialized
+	}
+
+	info := StorageInfo{
+		Driver: activeStore.Driver(),
+		Action: activeStore.MaintenanceAction(),
+	}
+	size, err := activeStore.StorageSize(ctx)
+	info.Size = size
+	return info, err
+}
+
+// ReclaimSpace performs the driver-specific physical maintenance operation.
+// It takes the exclusive operation lock, so a table/file rewrite cannot run
+// concurrently with report writes or compaction.
+func ReclaimSpace(ctx context.Context) (MaintenanceResult, error) {
+	// Reclamation is intentionally non-cancellable. It waits for all active
+	// operations, then keeps the store gate until digest conversion, VACUUM,
+	// and the final checkpoint have completed.
+	_ = ctx
+	if err := storeOperations.Acquire(context.Background()); err != nil {
+		return MaintenanceResult{}, err
+	}
+	defer storeOperations.Release()
+
+	storeMu.RLock()
+	activeStore := store
+	storeMu.RUnlock()
+	if activeStore == nil {
+		return MaintenanceResult{}, ErrStoreNotInitialized
+	}
+
+	result := MaintenanceResult{
+		Driver: activeStore.Driver(),
+		Action: activeStore.MaintenanceAction(),
+	}
+	maintenanceCtx := context.Background()
+	result.Before, result.BeforeSizeError = activeStore.StorageSize(maintenanceCtx)
+	maintenanceErr := deleteUndefinedMetrics(maintenanceCtx, activeStore)
+	if maintenanceErr == nil {
+		maintenanceErr = activeStore.ReclaimSpace(maintenanceCtx)
+	}
+	result.After, result.AfterSizeError = activeStore.StorageSize(maintenanceCtx)
+	return result, maintenanceErr
+}
+
+func deleteUndefinedMetrics(ctx context.Context, s *metric.Store) error {
+	definitions, err := s.ListMetrics(ctx)
+	if err != nil {
+		return fmt.Errorf("list metric definitions before reclaim: %w", err)
+	}
+
+	builtin := make(map[string]struct{}, len(builtinMetricNames))
+	for _, name := range builtinMetricNames {
+		builtin[name] = struct{}{}
+	}
+	for _, definition := range definitions {
+		if _, ok := builtin[definition.Name]; ok {
+			continue
+		}
+		if err := s.DeleteMetric(ctx, definition.Name); err != nil {
+			return fmt.Errorf("delete undefined metric %q before reclaim: %w", definition.Name, err)
+		}
+	}
+	return nil
+}

internal/metricstore/maintenance_test.go

@@ -0,0 +1,196 @@
+package metricstore
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/komari-monitor/komari/pkg/metric"
+)
+
+func TestInspectAndReclaimStorage(t *testing.T) {
+	ctx := context.Background()
+	s, err := metric.Open(ctx, metric.SQLite(":memory:"))
+	if err != nil {
+		t.Fatalf("open metric store: %v", err)
+	}
+	installTestStore(t, s)
+
+	info, err := InspectStorage(ctx)
+	if err != nil {
+		t.Fatalf("inspect storage: %v", err)
+	}
+	if info.Driver != metric.DriverSQLite || info.Action != metric.MaintenanceVacuum {
+		t.Fatalf("unexpected storage info: %#v", info)
+	}
+	if info.Size != 0 {
+		t.Fatalf("in-memory storage size = %d, want 0", info.Size)
+	}
+
+	result, err := ReclaimSpace(ctx)
+	if err != nil {
+		t.Fatalf("reclaim space: %v", err)
+	}
+	if result.Driver != metric.DriverSQLite || result.Action != metric.MaintenanceVacuum {
+		t.Fatalf("unexpected maintenance result: %#v", result)
+	}
+	if result.BeforeSizeError != nil || result.AfterSizeError != nil {
+		t.Fatalf("unexpected size errors: before=%v after=%v", result.BeforeSizeError, result.AfterSizeError)
+	}
+}
+
+func TestReclaimSpaceWaitsForStore(t *testing.T) {
+	s, err := metric.Open(context.Background(), metric.SQLite(":memory:"))
+	if err != nil {
+		t.Fatalf("open metric store: %v", err)
+	}
+	installTestStore(t, s)
+
+	if err := storeOperations.AcquireShared(context.Background()); err != nil {
+		t.Fatalf("acquire shared store operation gate: %v", err)
+	}
+	done := make(chan struct{})
+	var result MaintenanceResult
+	var reclaimErr error
+	canceledCtx, cancel := context.WithCancel(context.Background())
+	cancel()
+	go func() {
+		result, reclaimErr = ReclaimSpace(canceledCtx)
+		close(done)
+	}()
+	select {
+	case <-done:
+		t.Fatal("reclaim returned while another operation held the gate")
+	case <-time.After(25 * time.Millisecond):
+	}
+	storeOperations.ReleaseShared()
+	select {
+	case <-done:
+	case <-time.After(time.Second):
+		t.Fatal("reclaim did not resume after the gate was released")
+	}
+	if reclaimErr != nil {
+		t.Fatalf("reclaim error: %v", reclaimErr)
+	}
+	if result.Driver != metric.DriverSQLite || result.Action != metric.MaintenanceVacuum {
+		t.Fatalf("reclaim result lost store metadata: %#v", result)
+	}
+	if result.BeforeSizeError != nil || result.AfterSizeError != nil {
+		t.Fatalf("unexpected size errors: before=%v after=%v", result.BeforeSizeError, result.AfterSizeError)
+	}
+	compactCtx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	if _, err := Compact(compactCtx, time.Now()); err != nil {
+		t.Fatalf("compact should not wait for report writes: %v", err)
+	}
+	if !compactOperations.TryAcquire() {
+		t.Fatal("acquire compact operation gate")
+	}
+	defer compactOperations.Release()
+	if _, err := Compact(context.Background(), time.Now()); !errors.Is(err, ErrCompactInProgress) {
+		t.Fatalf("overlapping compact error = %v, want %v", err, ErrCompactInProgress)
+	}
+	if _, err := CleanupExpired(context.Background(), time.Now()); !errors.Is(err, ErrCompactInProgress) {
+		t.Fatalf("overlapping retention cleanup error = %v, want %v", err, ErrCompactInProgress)
+	}
+}
+
+func TestInspectStorageRequiresInitializedStore(t *testing.T) {
+	storeMu.Lock()
+	previous := store
+	store = nil
+	storeMu.Unlock()
+	t.Cleanup(func() {
+		storeMu.Lock()
+		store = previous
+		storeMu.Unlock()
+	})
+
+	if _, err := InspectStorage(context.Background()); !errors.Is(err, ErrStoreNotInitialized) {
+		t.Fatalf("inspect error = %v, want %v", err, ErrStoreNotInitialized)
+	}
+}
+
+func TestCloseStoreContextCancelsMigrationBeforeTakingStoreLock(t *testing.T) {
+	s, err := metric.Open(context.Background(), metric.SQLite(":memory:"))
+	if err != nil {
+		t.Fatalf("open metric store: %v", err)
+	}
+	installTestStore(t, s)
+
+	migrationCtx, cancelMigration := context.WithCancel(context.Background())
+	done := make(chan struct{})
+	if !storeOperations.TryAcquire() {
+		t.Fatal("acquire store operation gate")
+	}
+	storeMigMu.Lock()
+	storeMigCancel = cancelMigration
+	storeMigDone = done
+	storeMigMu.Unlock()
+
+	go func() {
+		<-migrationCtx.Done()
+		storeOperations.Release()
+		storeMigMu.Lock()
+		storeMigCancel = nil
+		storeMigDone = nil
+		close(done)
+		storeMigMu.Unlock()
+	}()
+
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	if err := CloseStoreContext(ctx); err != nil {
+		t.Fatalf("close store: %v", err)
+	}
+	if migrationCtx.Err() == nil {
+		t.Fatal("store migration was not canceled before close")
+	}
+	if err := Reload(context.Background()); !errors.Is(err, ErrStoreBusy) {
+		t.Fatalf("reload after close error = %v, want %v", err, ErrStoreBusy)
+	}
+}
+
+func TestStoreOperationWaitsRespectContext(t *testing.T) {
+	if !storeOperations.TryAcquire() {
+		t.Fatal("acquire store operation gate")
+	}
+	defer storeOperations.Release()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	if _, err := InspectStorage(ctx); !errors.Is(err, context.Canceled) {
+		t.Fatalf("inspect error = %v, want context canceled", err)
+	}
+	if err := Reload(ctx); !errors.Is(err, context.Canceled) {
+		t.Fatalf("reload error = %v, want context canceled", err)
+	}
+	if err := CloseStoreContext(ctx); !errors.Is(err, context.Canceled) {
+		t.Fatalf("close error = %v, want context canceled", err)
+	}
+}
+
+func installTestStore(t *testing.T, s *metric.Store) {
+	t.Helper()
+	storeMigMu.Lock()
+	previousClosing := storeClosing
+	storeClosing = false
+	storeMigMu.Unlock()
+	storeMu.Lock()
+	previous := store
+	previousFingerprint := storeFingerprint
+	store = s
+	storeFingerprint = "test|memory"
+	storeMu.Unlock()
+	t.Cleanup(func() {
+		storeMigMu.Lock()
+		storeClosing = previousClosing
+		storeMigMu.Unlock()
+		storeMu.Lock()
+		store = previous
+		storeFingerprint = previousFingerprint
+		storeMu.Unlock()
+		_ = s.Close()
+	})
+}

internal/metricstore/metrics.go

@@ -0,0 +1,95 @@
+package metricstore
+
+const (
+	MetricCPU            = "cpu.usage"
+	MetricGPU            = "gpu.usage"
+	MetricGPUDeviceUsage = "gpu.device.usage"
+	MetricGPUMem         = "gpu.memory.used"
+	MetricGPUMemTotal    = "gpu.memory.total"
+	MetricGPUTemp        = "gpu.temperature"
+	MetricRAM            = "memory.used"
+	MetricSwap           = "swap.used"
+	MetricLoad           = "load.average"
+	MetricDisk           = "disk.used"
+	MetricNetIn          = "net.in.rate"
+	MetricNetOut         = "net.out.rate"
+	MetricNetTotalUp     = "net.total.up"
+	MetricNetTotalDown   = "net.total.down"
+	MetricTrafficUp      = "traffic.up"
+	MetricTrafficDown    = "traffic.down"
+	MetricProcess        = "process.count"
+	MetricConnections    = "connections.tcp"
+	MetricConnectionsUDP = "connections.udp"
+	MetricPingLatency    = "ping.latency_ms"
+	MetricPingLoss       = "ping.loss"
+)
+
+// loadRecordMetricNames are the entity-level metrics used to reconstruct the
+// legacy Record response shape.
+var loadRecordMetricNames = []string{
+	MetricCPU, MetricGPU, MetricRAM, MetricSwap, MetricLoad, MetricDisk, MetricNetIn, MetricNetOut,
+	MetricNetTotalUp, MetricNetTotalDown, MetricTrafficUp, MetricTrafficDown,
+	MetricProcess, MetricConnections, MetricConnectionsUDP,
+}
+
+// gpuDeviceRecordMetricNames are stored separately from the entity-level GPU
+// average and are included when deleting all system records.
+var gpuDeviceRecordMetricNames = []string{
+	MetricGPUDeviceUsage, MetricGPUMem, MetricGPUMemTotal, MetricGPUTemp,
+}
+
+var recordMetricNames = joinMetricNames(loadRecordMetricNames, gpuDeviceRecordMetricNames)
+
+// Ping has an independent retention and cleanup boundary.
+var pingMetricNames = []string{MetricPingLatency, MetricPingLoss}
+
+var builtinMetricNames = joinMetricNames(recordMetricNames, pingMetricNames)
+
+func metricNameForRecordField(name string) (string, bool) {
+	switch name {
+	case "cpu":
+		return MetricCPU, true
+	case "gpu":
+		return MetricGPU, true
+	case "ram":
+		return MetricRAM, true
+	case "swap":
+		return MetricSwap, true
+	case "load":
+		return MetricLoad, true
+	case "disk":
+		return MetricDisk, true
+	case "net_in", "netin":
+		return MetricNetIn, true
+	case "net_out", "netout":
+		return MetricNetOut, true
+	case "net_total_up":
+		return MetricNetTotalUp, true
+	case "net_total_down":
+		return MetricNetTotalDown, true
+	case "traffic_up":
+		return MetricTrafficUp, true
+	case "traffic_down":
+		return MetricTrafficDown, true
+	case "process":
+		return MetricProcess, true
+	case "connections":
+		return MetricConnections, true
+	case "connections_udp":
+		return MetricConnectionsUDP, true
+	default:
+		return "", false
+	}
+}
+
+func joinMetricNames(groups ...[]string) []string {
+	total := 0
+	for _, group := range groups {
+		total += len(group)
+	}
+	names := make([]string, 0, total)
+	for _, group := range groups {
+		names = append(names, group...)
+	}
+	return names
+}

internal/metricstore/metricstore_test.go

@@ -0,0 +1,649 @@
+package metricstore
+
+import (
+	"context"
+	"database/sql"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/komari-monitor/komari/database/models"
+	"github.com/komari-monitor/komari/pkg/metric"
+	v2 "github.com/komari-monitor/komari/protocol/v2"
+)
+
+func TestDefaultRollupPolicy(t *testing.T) {
+	policy := defaultRollupPolicy()
+	if err := policy.Validate(); err != nil {
+		t.Fatalf("default rollup policy should validate: %v", err)
+	}
+	if policy.RawRetention != DefaultRollupRawRetention {
+		t.Fatalf("raw retention = %s, want %s", policy.RawRetention, DefaultRollupRawRetention)
+	}
+	if len(policy.Tiers) != 4 {
+		t.Fatalf("expected 4 rollup tiers, got %d", len(policy.Tiers))
+	}
+
+	wantIntervals := []time.Duration{time.Minute, 5 * time.Minute, time.Hour, 24 * time.Hour}
+	wantRetentions := []time.Duration{600 * time.Minute, 600 * 5 * time.Minute, 600 * time.Hour, 100 * 365 * 24 * time.Hour}
+	for i := range wantIntervals {
+		if policy.Tiers[i].Interval != wantIntervals[i] {
+			t.Fatalf("tier %d interval = %s, want %s", i, policy.Tiers[i].Interval, wantIntervals[i])
+		}
+		if policy.Tiers[i].Retention != wantRetentions[i] {
+			t.Fatalf("tier %d retention = %s, want %s", i, policy.Tiers[i].Retention, wantRetentions[i])
+		}
+	}
+}
+
+func TestBuildMetricConfigEnablesDefaultRollupPolicy(t *testing.T) {
+	cfg, err := buildMetricConfig(&MetricStoreConfig{
+		Driver:      "sqlite",
+		DSN:         ":memory:",
+		TablePrefix: "metric_",
+	}, false)
+	if err != nil {
+		t.Fatalf("build metric config: %v", err)
+	}
+	if !cfg.RollupPolicy.Enabled() {
+		t.Fatal("expected default rollup policy to be enabled")
+	}
+	if cfg.RollupPolicy.RawRetention != DefaultRollupRawRetention {
+		t.Fatalf("raw retention = %s, want %s", cfg.RollupPolicy.RawRetention, DefaultRollupRawRetention)
+	}
+	if cfg.SQLite.ReadPoolSize != 2 {
+		t.Fatalf("metric store read pool = %d, want fixed size 2", cfg.SQLite.ReadPoolSize)
+	}
+}
+
+func TestBuildMetricConfigLeavesFinalRetentionToMetricDefinition(t *testing.T) {
+	cfg, err := buildMetricConfig(&MetricStoreConfig{
+		Driver: "sqlite",
+		DSN:    ":memory:",
+	}, false)
+	if err != nil {
+		t.Fatalf("build metric config: %v", err)
+	}
+	wantRollupRetention := 100 * 365 * 24 * time.Hour
+	lastTier := cfg.RollupPolicy.Tiers[len(cfg.RollupPolicy.Tiers)-1]
+	if lastTier.Retention != wantRollupRetention {
+		t.Fatalf("rollup retention = %s, want %s", lastTier.Retention, wantRollupRetention)
+	}
+}
+
+func TestBuildMetricConfigUsesCustomRollupRetention(t *testing.T) {
+	cfg, err := buildMetricConfig(&MetricStoreConfig{
+		Driver:                           "sqlite",
+		DSN:                              ":memory:",
+		RollupMinuteRetentionMinutes:     30,
+		RollupFiveMinuteRetentionMinutes: 150,
+		RollupHourRetentionHours:         300,
+	}, false)
+	if err != nil {
+		t.Fatalf("build metric config: %v", err)
+	}
+
+	want := []time.Duration{30 * time.Minute, 150 * time.Minute, 300 * time.Hour}
+	if len(cfg.RollupPolicy.Tiers) != 4 {
+		t.Fatalf("tier count = %d, want 4", len(cfg.RollupPolicy.Tiers))
+	}
+	for i, retention := range want {
+		if cfg.RollupPolicy.Tiers[i].Retention != retention {
+			t.Fatalf("tier %d retention = %s, want %s", i, cfg.RollupPolicy.Tiers[i].Retention, retention)
+		}
+	}
+}
+
+func TestBuildMetricConfigRejectsInvalidRollupRetention(t *testing.T) {
+	tests := []MetricStoreConfig{
+		{
+			Driver:                       "sqlite",
+			DSN:                          ":memory:",
+			RollupMinuteRetentionMinutes: -1,
+		},
+		{
+			Driver:                           "sqlite",
+			DSN:                              ":memory:",
+			RollupMinuteRetentionMinutes:     120,
+			RollupFiveMinuteRetentionMinutes: 60,
+			RollupHourRetentionHours:         600,
+		},
+		{
+			Driver:                           "sqlite",
+			DSN:                              ":memory:",
+			RollupMinuteRetentionMinutes:     30,
+			RollupFiveMinuteRetentionMinutes: 150,
+			RollupHourRetentionHours:         1,
+		},
+	}
+	for i, cfg := range tests {
+		if _, err := buildMetricConfig(&cfg, false); err == nil {
+			t.Fatalf("case %d: expected invalid rollup retention error", i)
+		}
+	}
+}
+
+func TestBuildMetricConfigDefaultsOmittedRollupRetention(t *testing.T) {
+	cfg, err := buildMetricConfig(&MetricStoreConfig{Driver: "sqlite", DSN: ":memory:"}, false)
+	if err != nil {
+		t.Fatalf("build metric config: %v", err)
+	}
+	if got, want := cfg.RollupPolicy.Tiers[0].Retention, 600*time.Minute; got != want {
+		t.Fatalf("minute retention = %s, want %s", got, want)
+	}
+	if got, want := cfg.RollupPolicy.Tiers[1].Retention, 3000*time.Minute; got != want {
+		t.Fatalf("five-minute retention = %s, want %s", got, want)
+	}
+}
+
+func TestConfigFromFingerprintPreservesRollupRetention(t *testing.T) {
+	base := &MetricStoreConfig{
+		TablePrefix:                      "metrics_",
+		MaxOpenConns:                     11,
+		MaxIdleConns:                     4,
+		RollupMinuteRetentionMinutes:     30,
+		RollupFiveMinuteRetentionMinutes: 150,
+		RollupHourRetentionHours:         300,
+	}
+
+	got, err := configFromFingerprint("mysql|user:password@tcp(host:3306)/metrics", base)
+	if err != nil {
+		t.Fatalf("config from fingerprint: %v", err)
+	}
+	if got.RollupMinuteRetentionMinutes != base.RollupMinuteRetentionMinutes ||
+		got.RollupFiveMinuteRetentionMinutes != base.RollupFiveMinuteRetentionMinutes ||
+		got.RollupHourRetentionHours != base.RollupHourRetentionHours {
+		t.Fatalf("rollup retention was not preserved: %#v", got)
+	}
+}
+
+func TestBuildMetricConfigAlwaysEnablesDownsampling(t *testing.T) {
+	cfg, err := buildMetricConfig(&MetricStoreConfig{
+		Driver: "sqlite",
+		DSN:    ":memory:",
+	}, false)
+	if err != nil {
+		t.Fatalf("build metric config: %v", err)
+	}
+	if !cfg.RollupPolicy.Enabled() {
+		t.Fatal("expected rollup policy to be enabled")
+	}
+}
+
+func TestGetPingRecordsReadsRollupsAfterRawCompaction(t *testing.T) {
+	ctx := context.Background()
+	now := time.Now().UTC().Truncate(time.Second)
+	s, err := metric.Open(ctx, metric.SQLite(":memory:",
+		metric.WithMaxOpenConns(1),
+		metric.WithRollupPolicy(defaultRollupPolicy()),
+	))
+	if err != nil {
+		t.Fatalf("open metric store: %v", err)
+	}
+	defer s.Close()
+	if err := s.UpsertMetric(ctx, metric.Definition{
+		Name:          MetricPingLatency,
+		Type:          metric.TypeGauge,
+		RetentionDays: 30,
+	}); err != nil {
+		t.Fatalf("create ping metric: %v", err)
+	}
+	if err := s.WriteBatch(ctx, []metric.Point{
+		{MetricName: MetricPingLatency, EntityID: "node-a", Timestamp: now.Add(-20 * time.Minute), Value: 20, Tags: map[string]string{"task_id": "7"}},
+		{MetricName: MetricPingLatency, EntityID: "node-a", Timestamp: now.Add(-10 * time.Minute), Value: 10, Tags: map[string]string{"task_id": "7"}},
+		{MetricName: MetricPingLatency, EntityID: "node-a", Timestamp: now.Add(-5 * time.Minute), Value: 5, Tags: map[string]string{"task_id": "7"}},
+	}); err != nil {
+		t.Fatalf("write ping points: %v", err)
+	}
+	if _, err := s.Compact(ctx, now); err != nil {
+		t.Fatalf("compact ping points: %v", err)
+	}
+
+	storeMu.Lock()
+	oldStore := store
+	store = s
+	storeMu.Unlock()
+	defer func() {
+		storeMu.Lock()
+		store = oldStore
+		storeMu.Unlock()
+	}()
+
+	records, err := GetPingRecords(ctx, "node-a", 7, now.Add(-30*time.Minute), now)
+	if err != nil {
+		t.Fatalf("get ping records: %v", err)
+	}
+	if len(records) != 3 {
+		t.Fatalf("expected 3 ping records across raw and rollup data, got %d: %#v", len(records), records)
+	}
+	if records[0].Value != 5 || records[1].Value != 10 || records[2].Value != 20 {
+		t.Fatalf("unexpected ping values in descending order: %#v", records)
+	}
+}
+
+func TestCreateMetricDefinitionsUsesExplicitRetentionAndPreservesOverrides(t *testing.T) {
+	if defaultBuiltinMetricRetentionDays != 1 {
+		t.Fatalf("default built-in metric retention = %d, want 1 day", defaultBuiltinMetricRetentionDays)
+	}
+
+	ctx := context.Background()
+	s, err := metric.Open(ctx, metric.SQLite(":memory:", metric.WithMaxOpenConns(1)))
+	if err != nil {
+		t.Fatalf("open metric store: %v", err)
+	}
+	defer s.Close()
+
+	if err := createMetricDefinitions(ctx, s); err != nil {
+		t.Fatalf("create definitions: %v", err)
+	}
+	defs, err := s.ListMetrics(ctx)
+	if err != nil {
+		t.Fatalf("list definitions: %v", err)
+	}
+	if len(defs) != 21 {
+		t.Fatalf("definition count = %d, want 21", len(defs))
+	}
+	for _, def := range defs {
+		if def.RetentionDays != defaultBuiltinMetricRetentionDays {
+			t.Fatalf("%s retention = %d, want %d", def.Name, def.RetentionDays, defaultBuiltinMetricRetentionDays)
+		}
+	}
+
+	cpu, err := s.GetMetric(ctx, MetricCPU)
+	if err != nil {
+		t.Fatalf("get cpu definition: %v", err)
+	}
+	cpu.RetentionDays = 60
+	if err := s.UpsertMetric(ctx, cpu); err != nil {
+		t.Fatalf("override cpu retention: %v", err)
+	}
+	if err := createMetricDefinitions(ctx, s); err != nil {
+		t.Fatalf("recreate definitions: %v", err)
+	}
+	cpu, err = s.GetMetric(ctx, MetricCPU)
+	if err != nil {
+		t.Fatalf("reload cpu definition: %v", err)
+	}
+	if cpu.RetentionDays != 60 {
+		t.Fatalf("cpu retention = %d, want preserved override 60", cpu.RetentionDays)
+	}
+	if _, err := s.SetMetricRetention(ctx, MetricCPU, 0); err != nil {
+		t.Fatalf("disable cpu retention: %v", err)
+	}
+	if err := createMetricDefinitions(ctx, s); err != nil {
+		t.Fatalf("refresh disabled definition: %v", err)
+	}
+	cpu, err = s.GetMetric(ctx, MetricCPU)
+	if err != nil {
+		t.Fatalf("reload disabled cpu definition: %v", err)
+	}
+	if cpu.RetentionDays != 0 {
+		t.Fatalf("cpu retention = %d, want preserved disabled state", cpu.RetentionDays)
+	}
+}
+
+func TestCreateMetricDefinitionsKeepsExistingMetrics(t *testing.T) {
+	ctx := context.Background()
+	s, err := metric.Open(ctx, metric.SQLite(":memory:", metric.WithMaxOpenConns(1)))
+	if err != nil {
+		t.Fatalf("open metric store: %v", err)
+	}
+	defer s.Close()
+	if err := s.CreateMetric(ctx, metric.Definition{Name: "memory.total", Type: metric.TypeGauge, RetentionDays: 1}); err != nil {
+		t.Fatalf("create obsolete definition: %v", err)
+	}
+	if err := s.Write(ctx, metric.Point{MetricName: "memory.total", EntityID: "node-a", Timestamp: time.Now().UTC(), Value: 1024}); err != nil {
+		t.Fatalf("write obsolete point: %v", err)
+	}
+	if err := createMetricDefinitions(ctx, s); err != nil {
+		t.Fatalf("refresh built-in definitions: %v", err)
+	}
+	definition, err := s.GetMetric(ctx, "memory.total")
+	if err != nil {
+		t.Fatalf("existing definition was removed: %v", err)
+	}
+	if definition.RetentionDays != 1 {
+		t.Fatalf("existing retention = %d, want 1", definition.RetentionDays)
+	}
+	points, err := s.Query(ctx, metric.Query{MetricName: "memory.total", EntityID: "node-a", Start: time.Now().UTC().Add(-time.Hour), End: time.Now().UTC().Add(time.Hour)})
+	if err != nil {
+		t.Fatalf("query existing points: %v", err)
+	}
+	if len(points) != 1 || points[0].Value != 1024 {
+		t.Fatalf("existing points were removed: %#v", points)
+	}
+}
+
+func TestCreateMetricDefinitionsUsesLegacySpanOnlyForNewDefinitions(t *testing.T) {
+	ctx := context.Background()
+	s, err := metric.Open(ctx, metric.SQLite(":memory:", metric.WithMaxOpenConns(1)))
+	if err != nil {
+		t.Fatalf("open metric store: %v", err)
+	}
+	defer s.Close()
+
+	if err := createMetricDefinitionsWithDefaultRetention(ctx, s, 10); err != nil {
+		t.Fatalf("create migration definitions: %v", err)
+	}
+	defs, err := s.ListMetrics(ctx)
+	if err != nil {
+		t.Fatalf("list migration definitions: %v", err)
+	}
+	for _, def := range defs {
+		if def.RetentionDays != 10 {
+			t.Fatalf("%s retention = %d, want legacy span 10", def.Name, def.RetentionDays)
+		}
+	}
+
+	cpu, err := s.GetMetric(ctx, MetricCPU)
+	if err != nil {
+		t.Fatalf("get CPU definition: %v", err)
+	}
+	cpu.RetentionDays = 3
+	if err := s.UpsertMetric(ctx, cpu); err != nil {
+		t.Fatalf("override CPU retention: %v", err)
+	}
+	if err := createMetricDefinitionsWithDefaultRetention(ctx, s, 20); err != nil {
+		t.Fatalf("refresh migration definitions: %v", err)
+	}
+	cpu, err = s.GetMetric(ctx, MetricCPU)
+	if err != nil {
+		t.Fatalf("reload CPU definition: %v", err)
+	}
+	if cpu.RetentionDays != 3 {
+		t.Fatalf("existing CPU retention = %d, want preserved 3", cpu.RetentionDays)
+	}
+}
+
+func TestGetRetentionSummaryUsesAllMetricDefinitions(t *testing.T) {
+	ctx := context.Background()
+	s, err := metric.Open(ctx, metric.SQLite(":memory:", metric.WithMaxOpenConns(1)))
+	if err != nil {
+		t.Fatalf("open metric store: %v", err)
+	}
+	defer s.Close()
+
+	storeMu.Lock()
+	oldStore := store
+	store = s
+	storeMu.Unlock()
+	defer func() {
+		storeMu.Lock()
+		store = oldStore
+		storeMu.Unlock()
+	}()
+
+	empty, err := GetRetentionSummary(ctx)
+	if err != nil {
+		t.Fatalf("summarize empty store: %v", err)
+	}
+	if empty.AllPositive || empty.MaxDays != 0 {
+		t.Fatalf("unexpected empty summary: %#v", empty)
+	}
+	for _, def := range []metric.Definition{
+		{Name: "short", Type: metric.TypeGauge, RetentionDays: 7},
+		{Name: "long", Type: metric.TypeGauge, RetentionDays: 60},
+	} {
+		if err := s.UpsertMetric(ctx, def); err != nil {
+			t.Fatalf("upsert %s: %v", def.Name, err)
+		}
+	}
+	summary, err := GetRetentionSummary(ctx)
+	if err != nil {
+		t.Fatalf("summarize definitions: %v", err)
+	}
+	if !summary.AllPositive || summary.MaxDays != 60 {
+		t.Fatalf("unexpected summary: %#v", summary)
+	}
+	if _, err := s.SetMetricRetention(ctx, "short", 0); err != nil {
+		t.Fatalf("disable short metric: %v", err)
+	}
+	summary, err = GetRetentionSummary(ctx)
+	if err != nil {
+		t.Fatalf("summarize disabled metric: %v", err)
+	}
+	if summary.AllPositive || summary.MaxDays != 60 {
+		t.Fatalf("unexpected disabled summary: %#v", summary)
+	}
+}
+
+func TestSummarizeRetentionDefinitionsRequiresEveryMetricToBePositive(t *testing.T) {
+	summary := summarizeRetentionDefinitions([]metric.Definition{
+		{Name: "enabled", RetentionDays: 30},
+		{Name: "disabled", RetentionDays: 0},
+		{Name: "long", RetentionDays: 60},
+	})
+	if summary.AllPositive || summary.MaxDays != 60 {
+		t.Fatalf("unexpected summary: %#v", summary)
+	}
+}
+
+func TestCompactCleansPointsOutsideFixedRawWindow(t *testing.T) {
+	ctx := context.Background()
+	s, err := metric.Open(ctx, metric.SQLite(":memory:", metric.WithMaxOpenConns(1), metric.WithRollupPolicy(metric.RollupPolicy{})))
+	if err != nil {
+		t.Fatalf("open metric store: %v", err)
+	}
+	if err := s.UpsertMetric(ctx, metric.Definition{
+		Name:          "raw.metric",
+		Type:          metric.TypeGauge,
+		RetentionDays: 1,
+	}); err != nil {
+		t.Fatalf("upsert metric: %v", err)
+	}
+
+	now := time.Now().UTC()
+	if err := s.WriteBatch(ctx, []metric.Point{
+		{MetricName: "raw.metric", EntityID: "node", Timestamp: now.Add(-11 * time.Minute), Value: 1},
+		{MetricName: "raw.metric", EntityID: "node", Timestamp: now.Add(-30 * time.Second), Value: 2},
+	}); err != nil {
+		t.Fatalf("write points: %v", err)
+	}
+
+	storeMu.Lock()
+	oldStore := store
+	store = s
+	storeMu.Unlock()
+	defer func() {
+		storeMu.Lock()
+		store = oldStore
+		storeMu.Unlock()
+		_ = s.Close()
+	}()
+
+	if _, err := Compact(ctx, now); err != nil {
+		t.Fatalf("compact: %v", err)
+	}
+	points, err := s.Query(ctx, metric.Query{
+		MetricName: "raw.metric",
+		EntityID:   "node",
+		Start:      now.Add(-time.Hour),
+		End:        now,
+	})
+	if err != nil {
+		t.Fatalf("query points: %v", err)
+	}
+	if len(points) != 1 || points[0].Value != 2 {
+		t.Fatalf("expected only the retained raw point, got %#v", points)
+	}
+}
+
+func TestRetentionCleanupReportsDeleteFailure(t *testing.T) {
+	ctx := context.Background()
+	dsn := filepath.Join(t.TempDir(), "compact.db")
+	s, err := metric.Open(ctx, metric.SQLite(dsn,
+		metric.WithMaxOpenConns(1),
+		metric.WithRollupPolicy(defaultRollupPolicy()),
+	))
+	if err != nil {
+		t.Fatalf("open metric store: %v", err)
+	}
+	t.Cleanup(func() { _ = s.Close() })
+	for _, name := range []string{"a.invalid", "b.healthy"} {
+		if err := s.CreateMetric(ctx, metric.Definition{Name: name, Type: metric.TypeGauge, RetentionDays: 1}); err != nil {
+			t.Fatalf("create metric %s: %v", name, err)
+		}
+	}
+
+	now := time.Date(2026, 7, 20, 12, 0, 0, 0, time.UTC)
+	old := now.Add(-48 * time.Hour)
+	if err := s.WriteBatch(ctx, []metric.Point{
+		{MetricName: "a.invalid", EntityID: "node", Timestamp: old, Value: 1},
+		{MetricName: "b.healthy", EntityID: "node", Timestamp: old, Value: 2},
+	}); err != nil {
+		t.Fatalf("write compact fixtures: %v", err)
+	}
+
+	rawDB, err := sql.Open("sqlite3", dsn)
+	if err != nil {
+		t.Fatalf("open raw sqlite connection: %v", err)
+	}
+	_, err = rawDB.ExecContext(ctx, `CREATE TRIGGER fail_invalid_metric_rollup
+		BEFORE DELETE ON metric_rollups
+		WHEN OLD.series_id IN (SELECT id FROM metric_series WHERE metric_name = 'a.invalid')
+		BEGIN SELECT RAISE(FAIL, 'forced compact failure'); END`)
+	_ = rawDB.Close()
+	if err != nil {
+		t.Fatalf("create compact failure trigger: %v", err)
+	}
+
+	storeMu.Lock()
+	previousStore := store
+	store = s
+	storeMu.Unlock()
+	t.Cleanup(func() {
+		storeMu.Lock()
+		store = previousStore
+		storeMu.Unlock()
+	})
+
+	if _, err := CleanupExpired(ctx, now); err == nil {
+		t.Fatal("expected retention cleanup to report the forced delete failure")
+	}
+	points, err := s.Query(ctx, metric.Query{
+		MetricName: "b.healthy",
+		EntityID:   "node",
+		Start:      old.Add(-time.Minute),
+		End:        now,
+	})
+	if err != nil {
+		t.Fatalf("query healthy rollups: %v", err)
+	}
+	if len(points) != 0 {
+		t.Fatalf("retention cleanup unexpectedly changed healthy metric data: %#v", points)
+	}
+}
+
+func TestGetRecordsByClientAndTimeReadsRollupsAfterRawCompaction(t *testing.T) {
+	ctx := context.Background()
+	s, err := metric.Open(ctx, metric.SQLite(":memory:",
+		metric.WithMaxOpenConns(1),
+		metric.WithRollupPolicy(defaultRollupPolicy()),
+	))
+	if err != nil {
+		t.Fatalf("open metric store: %v", err)
+	}
+	if err := createMetricDefinitions(ctx, s); err != nil {
+		t.Fatalf("create metric definitions: %v", err)
+	}
+
+	storeMu.Lock()
+	oldStore := store
+	store = s
+	storeMu.Unlock()
+	defer func() {
+		storeMu.Lock()
+		store = oldStore
+		storeMu.Unlock()
+		_ = s.Close()
+	}()
+
+	now := time.Now().UTC().Truncate(time.Minute)
+	ts := now.Add(-time.Hour)
+	rec := models.Record{
+		Client:         "node-a",
+		Time:           ts,
+		Cpu:            42.5,
+		Ram:            123456,
+		RamTotal:       999999,
+		Disk:           456789,
+		DiskTotal:      777777,
+		Load:           0.75,
+		Connections:    321,
+		ConnectionsUdp: 12,
+	}
+	if _, err := WriteReport(ctx, v2.Report{
+		UUID:      rec.Client,
+		UpdatedAt: ts,
+		CPU:       v2.CPUReport{Usage: float64(rec.Cpu)},
+		Ram:       v2.RamReport{Used: rec.Ram, Total: rec.RamTotal},
+		Load:      v2.LoadReport{Load1: float64(rec.Load)},
+		Disk:      v2.DiskReport{Used: rec.Disk, Total: rec.DiskTotal},
+		Process:   rec.Process,
+		Connections: v2.ConnectionsReport{
+			TCP: rec.Connections,
+			UDP: rec.ConnectionsUdp,
+		},
+	}); err != nil {
+		t.Fatalf("write record: %v", err)
+	}
+	if _, err := s.Compact(ctx, now); err != nil {
+		t.Fatalf("compact raw into rollup: %v", err)
+	}
+	got, err := GetRecordsByClientAndTime(ctx, rec.Client, ts.Add(-time.Minute), now)
+	if err != nil {
+		t.Fatalf("get records: %v", err)
+	}
+	if len(got) != 1 {
+		t.Fatalf("expected 1 reconstructed record from rollup, got %d: %#v", len(got), got)
+	}
+	if got[0].Cpu == 0 || got[0].Ram == 0 || got[0].Disk == 0 || got[0].Connections == 0 {
+		t.Fatalf("record was not reconstructed from rollup: %#v", got[0])
+	}
+
+	all, err := GetRecordsByTime(ctx, ts.Add(-time.Minute), now)
+	if err != nil {
+		t.Fatalf("get all records: %v", err)
+	}
+	if len(all) != 1 || all[0].Client != rec.Client || all[0].Cpu == 0 {
+		t.Fatalf("all-client records were not reconstructed from rollup: %#v", all)
+	}
+}
+
+func TestGetRecordMetricMaxByClientAndTimeQueriesOnlySelectedMetric(t *testing.T) {
+	ctx := context.Background()
+	s, err := metric.Open(ctx, metric.SQLite(":memory:",
+		metric.WithMaxOpenConns(1),
+		metric.WithRollupPolicy(defaultRollupPolicy()),
+	))
+	if err != nil {
+		t.Fatalf("open metric store: %v", err)
+	}
+	defer s.Close()
+	if err := createMetricDefinitions(ctx, s); err != nil {
+		t.Fatalf("create metric definitions: %v", err)
+	}
+
+	base := time.Now().UTC().Truncate(time.Minute).Add(-time.Minute)
+	if err := s.WriteBatch(ctx, []metric.Point{
+		{MetricName: MetricCPU, EntityID: "node-a", Timestamp: base.Add(10 * time.Second), Value: 10},
+		{MetricName: MetricCPU, EntityID: "node-a", Timestamp: base.Add(20 * time.Second), Value: 90},
+		{MetricName: MetricRAM, EntityID: "node-a", Timestamp: base.Add(20 * time.Second), Value: 123456},
+	}); err != nil {
+		t.Fatalf("write metric points: %v", err)
+	}
+
+	got, err := getRecordMetricMaxByClientAndTimeFromSeries(ctx, s, "node-a", "cpu", base, base.Add(time.Minute))
+	if err != nil {
+		t.Fatalf("get CPU max records: %v", err)
+	}
+	if len(got) != 1 {
+		t.Fatalf("record count = %d, want 1: %#v", len(got), got)
+	}
+	if got[0].Cpu != 90 {
+		t.Fatalf("CPU max = %v, want 90", got[0].Cpu)
+	}
+	if got[0].Ram != 0 {
+		t.Fatalf("unselected RAM value = %d, want 0", got[0].Ram)
+	}
+}

internal/metricstore/migration_store.go

@@ -0,0 +1,112 @@
+package metricstore
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/komari-monitor/komari/pkg/metric"
+	logger "github.com/komari-monitor/komari/utils/log"
+)
+
+const storeMigrationBatchSize = 500
+
+// configFromFingerprint 从目标指纹（driver|dsn）重建一个 MetricStoreConfig，
+// 用于以只读方式打开“上一次的 metrics 目标库”。表前缀、保留天数、连接数等
+// 沿用当前配置（切换后端时这些通常不变）。
+func configFromFingerprint(fingerprint string, base *MetricStoreConfig) (*MetricStoreConfig, error) {
+	idx := strings.Index(fingerprint, "|")
+	if idx < 0 {
+		return nil, fmt.Errorf("invalid target fingerprint: %q", fingerprint)
+	}
+	driver := fingerprint[:idx]
+	dsn := fingerprint[idx+1:]
+	if strings.TrimSpace(driver) == "" {
+		return nil, fmt.Errorf("empty driver in target fingerprint: %q", fingerprint)
+	}
+	return &MetricStoreConfig{
+		Driver:                           driver,
+		DSN:                              dsn,
+		TablePrefix:                      base.TablePrefix,
+		MaxOpenConns:                     base.MaxOpenConns,
+		MaxIdleConns:                     base.MaxIdleConns,
+		RollupMinuteRetentionMinutes:     base.RollupMinuteRetentionMinutes,
+		RollupFiveMinuteRetentionMinutes: base.RollupFiveMinuteRetentionMinutes,
+		RollupHourRetentionHours:         base.RollupHourRetentionHours,
+	}, nil
+}
+
+// openSourceStore 打开一个已存在的 metrics 目标库作为数据搬运的源库读取。
+//
+// 使用 autoMigrate=true 确保规范化表和索引存在；创建语句不会删除已有数据。
+// 当源库文件/表不存在（例如老快照记录了 completed 但 metrics.db 缺失）时，
+// 创建空表可让后续 ListMetrics 返回空集，把“无历史可迁移”识别为正常情况。
+func openSourceStore(ctx context.Context, cfg *MetricStoreConfig) (*metric.Store, error) {
+	metricCfg, err := buildMetricConfig(cfg, true)
+	if err != nil {
+		return nil, err
+	}
+	return metric.Open(ctx, metricCfg)
+}
+
+// defaultSQLiteFingerprint 返回默认 SQLite metrics 库（./data/metrics.db）的目标指纹。
+// 老快照的 metrics 数据固定落在该 SQLite 文件，用于在缺失指纹时推断上一个源库。
+func defaultSQLiteFingerprint() string {
+	return targetFingerprint(&MetricStoreConfig{Driver: "sqlite", DSN: "./data/metrics.db"})
+}
+
+// storeMigrationObserver 在 store-to-store 迁移过程中接收进度回调。
+//   - currentMetric：当前正在搬运的指标名。
+//   - metricIndex：该指标在全部指标中的序号（0 起），即已完成的指标数。
+//   - totalMetrics：指标定义总数。
+//   - addedPoints：本次新写入目标库的 rollup 行数（用于外部累计）。
+type storeMigrationObserver func(currentMetric string, metricIndex, totalMetrics int, addedPoints int64)
+
+// 观察者 observe（为 nil 时行为与旧版本完全一致）。WebUI/API 手动触发的迁移传入
+// 回调以实时更新进度。
+func migrateBetweenStores(ctx context.Context, src, dst *metric.Store, observe storeMigrationObserver) (int64, error) {
+	if src == nil || dst == nil {
+		return 0, fmt.Errorf("source or destination metric store is nil")
+	}
+
+	defs, err := src.ListMetrics(ctx)
+	if err != nil {
+		return 0, fmt.Errorf("list source metrics: %w", err)
+	}
+
+	var total int64
+	for i, def := range defs {
+		if observe != nil {
+			// 进入下一个指标：已完成 i 个指标。
+			observe(def.Name, i, len(defs), 0)
+		}
+		// 目标库先建立指标定义，保证后续写入的指标存在。
+		if err := dst.UpsertMetric(ctx, def); err != nil {
+			return total, fmt.Errorf("upsert metric %q on target: %w", def.Name, err)
+		}
+		if def.RetentionDays == 0 {
+			continue
+		}
+		var migrated int64
+		_, err := src.ExportRollups(ctx, def.Name, storeMigrationBatchSize, func(batch []metric.PersistedRollup) error {
+			if err := dst.ImportRollups(ctx, batch); err != nil {
+				return fmt.Errorf("write metric %q rollup batch to target: %w", def.Name, err)
+			}
+			count := int64(len(batch))
+			migrated += count
+			total += count
+			if observe != nil {
+				observe(def.Name, i, len(defs), count)
+			}
+			return nil
+		})
+		if err != nil {
+			return total, fmt.Errorf("export metric %q rollups: %w", def.Name, err)
+		}
+		if migrated > 0 {
+			logger.Infof("metricstore", "[store-migration] metric %q: migrated %d rollups", def.Name, migrated)
+		}
+	}
+
+	return total, nil
+}

internal/metricstore/operation_gate.go

@@ -0,0 +1,40 @@
+package metricstore
+
+import (
+	"context"
+
+	"golang.org/x/sync/semaphore"
+)
+
+// storeOperationGate keeps an active Store stable while allowing regular
+// reads, report writes, and compaction to proceed together. Store replacement
+// and maintenance take the whole gate exclusively.
+type storeOperationGate struct {
+	semaphore *semaphore.Weighted
+}
+
+const storeOperationGateWeight int64 = 1024
+
+func newStoreOperationGate() *storeOperationGate {
+	return &storeOperationGate{semaphore: semaphore.NewWeighted(storeOperationGateWeight)}
+}
+
+func (g *storeOperationGate) Acquire(ctx context.Context) error {
+	return g.semaphore.Acquire(ctx, storeOperationGateWeight)
+}
+
+func (g *storeOperationGate) TryAcquire() bool {
+	return g.semaphore.TryAcquire(storeOperationGateWeight)
+}
+
+func (g *storeOperationGate) Release() {
+	g.semaphore.Release(storeOperationGateWeight)
+}
+
+func (g *storeOperationGate) AcquireShared(ctx context.Context) error {
+	return g.semaphore.Acquire(ctx, 1)
+}
+
+func (g *storeOperationGate) ReleaseShared() {
+	g.semaphore.Release(1)
+}

internal/metricstore/ping_records.go

@@ -0,0 +1,113 @@
+package metricstore
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"time"
+
+	"github.com/komari-monitor/komari/database/models"
+	"github.com/komari-monitor/komari/pkg/metric"
+)
+
+// WritePingRecord 将 ping 记录写入 metric store
+func WritePingRecord(ctx context.Context, rec models.PingRecord) error {
+	s := GetStore()
+	if s == nil {
+		return fmt.Errorf("metric store not enabled")
+	}
+
+	reportBatcherMu.Lock()
+	worker := reportBatcher
+	reportBatcherMu.Unlock()
+	if worker != nil {
+		return worker.enqueuePing(ctx, rec)
+	}
+	return writePingRecords(ctx, []models.PingRecord{rec})
+}
+
+func writePingRecords(ctx context.Context, records []models.PingRecord) error {
+	s := GetStore()
+	if s == nil {
+		return fmt.Errorf("metric store not enabled")
+	}
+	if len(records) == 0 {
+		return nil
+	}
+
+	points := make([]metric.Point, 0, len(records)*2)
+	for _, rec := range records {
+		tags := map[string]string{"task_id": fmt.Sprintf("%d", rec.TaskId)}
+		loss := 0.0
+		if rec.Value < 0 {
+			loss = 1
+		}
+		points = append(points,
+			metric.Point{
+				MetricName: MetricPingLatency,
+				EntityID:   rec.Client,
+				Timestamp:  rec.Time,
+				Value:      float64(rec.Value),
+				Tags:       tags,
+			},
+			metric.Point{
+				MetricName: MetricPingLoss,
+				EntityID:   rec.Client,
+				Timestamp:  rec.Time,
+				Value:      loss,
+				Tags:       tags,
+			},
+		)
+	}
+	return s.WriteBatch(ctx, points)
+}
+
+// GetPingRecords returns legacy-shaped ping records, newest first.
+func GetPingRecords(ctx context.Context, clientUUID string, taskID int, start, end time.Time) ([]models.PingRecord, error) {
+	s := GetStore()
+	if s == nil {
+		return nil, fmt.Errorf("metric store not enabled")
+	}
+
+	query := MetricsQuery{
+		Store: s, Mode: QuerySeries, Source: SourceRollup,
+		CompactDefinitions: true,
+		Entities:           EntityScope{All: clientUUID == ""},
+		Specs:              []MetricSpec{{Name: MetricPingLatency, Aggregations: []metric.Aggregation{metric.AggLast}}},
+		Start:              start, End: end, Order: metric.OrderAsc, Grouping: GroupSeries,
+		Budget: PointBudget{PerSeries: 4000}, Rounding: RoundFloor, AllowMissing: true,
+	}
+	if clientUUID != "" {
+		query.Entities.IDs = []string{clientUUID}
+	}
+	if taskID >= 0 {
+		query.Tags = map[string]string{"task_id": fmt.Sprintf("%d", taskID)}
+	}
+	loaded, err := QueryMetrics(ctx, query)
+	if err != nil {
+		return nil, err
+	}
+
+	points := loaded.Values[MetricPingLatency][metric.AggLast]
+	records := make([]models.PingRecord, 0, len(points))
+	for _, p := range points {
+		taskIDVal := uint(0)
+		if tid, ok := p.Tags["task_id"]; ok {
+			var t uint64
+			fmt.Sscanf(tid, "%d", &t)
+			taskIDVal = uint(t)
+		}
+
+		records = append(records, models.PingRecord{
+			Client: p.EntityID,
+			TaskId: taskIDVal,
+			Time:   p.Bucket.UTC(),
+			Value:  int(p.Value),
+		})
+	}
+	sort.Slice(records, func(i, j int) bool {
+		return records[i].Time.After(records[j].Time)
+	})
+
+	return records, nil
+}

internal/metricstore/query.go

@@ -0,0 +1,766 @@
+package metricstore
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/komari-monitor/komari/pkg/metric"
+)
+
+// QueryMode selects exact samples, adaptive series, or exclusive-boundary lookups.
+type QueryMode string
+
+const (
+	QueryPoints       QueryMode = "points"
+	QuerySeries       QueryMode = "series"
+	QueryLatestBefore QueryMode = "latest_before"
+)
+
+type QuerySource string
+
+const (
+	SourceAuto   QuerySource = "auto"
+	SourceRaw    QuerySource = "raw"
+	SourceRollup QuerySource = "rollup"
+)
+
+type QueryGrouping string
+
+const (
+	GroupMerged QueryGrouping = "merged"
+	GroupEntity QueryGrouping = "entity"
+	GroupSeries QueryGrouping = "series"
+)
+
+type IntervalRounding string
+
+const (
+	RoundFloor IntervalRounding = "floor"
+	RoundCeil  IntervalRounding = "ceil"
+)
+
+// EntityScope deliberately distinguishes an empty authorized set from all entities.
+// All and IDs are mutually exclusive. IDs are deduplicated without modifying callers.
+type EntityScope struct {
+	All bool
+	IDs []string
+}
+type MetricSpec struct {
+	Name         string
+	Aggregations []metric.Aggregation
+	// Positive intervals are explicit and are preserved, even for historical data.
+	Interval time.Duration
+	// Zero inherits Budget.PerSeries, then 500. -1 disables adaptive downsampling:
+	// a zero Interval then selects the finest compatible tier, not a whole-window bucket.
+	MaxPoints int
+}
+
+// PointBudget controls adaptive interval planning, not a raw-row SQL LIMIT.
+// Total divides the point target across entities (metrics may be columns of one
+// legacy record); it is not a hard cap across metrics, aggregations or tag variants.
+// Raw queries and explicit intervals retain their exact historical semantics.
+// Response adapters can impose their existing final sampling policy separately.
+type PointBudget struct {
+	Total     int
+	PerSeries int
+}
+type FillPolicy struct {
+	Gaps               bool
+	PingNegativeAsNull bool
+}
+
+// QueryProjection controls retained result representations. The default keeps all
+// source data for compatibility; chart requires Fill and retains only Filled.
+type QueryProjection string
+
+const (
+	ProjectionFull  QueryProjection = "full"
+	ProjectionChart QueryProjection = "chart"
+)
+
+type MetricsQuery struct {
+	// Output omissions are opt-in; filtering and aggregation identity are unchanged.
+	OmitTags           bool
+	OmitLabels         bool
+	CompactDefinitions bool
+	Projection         QueryProjection
+	Store              *metric.Store
+	Mode               QueryMode
+	Source             QuerySource
+	Entities           EntityScope
+	Specs              []MetricSpec
+	Start, End         time.Time
+	Tags               map[string]string
+	Order              metric.Order
+	Grouping           QueryGrouping
+	Budget             PointBudget
+	Rounding           IntervalRounding
+	Fill               FillPolicy
+	AllowMissing       bool
+	Now                time.Time
+}
+type MetricsResult struct {
+	Definitions map[string]metric.Definition
+	Raw         map[string][]metric.Point
+	Values      map[string]map[metric.Aggregation][]metric.AggregatePoint
+	Intervals   map[string]time.Duration
+	IsRaw       bool
+	Filled      []MetricSeries
+	// Latest is keyed by metric name, then entity; missing samples are absent.
+	Latest map[string]map[string]metric.Point
+}
+type MetricSeries struct {
+	MetricName, EntityID string
+	Aggregation          metric.Aggregation
+	Tags                 map[string]string
+	Interval             time.Duration
+	Points               []MetricValue
+}
+type MetricValue struct {
+	Time         time.Time
+	Value        *float64
+	Count        int
+	Tags, Labels map[string]string
+}
+
+// DownsampleInterval returns a standard interval that keeps rangeDuration
+// within about maxPoints buckets, never finer than one second. roundUp is used
+// by point budgets: flooring can exceed the budget, while compatibility queries
+// preserve the historical floor behavior.
+func DownsampleInterval(rangeDuration time.Duration, maxPoints int, roundUp bool) time.Duration {
+	if maxPoints < 1 {
+		maxPoints = 1
+	}
+	points := time.Duration(maxPoints)
+	interval := (rangeDuration + points - 1) / points
+	if interval < time.Second {
+		return time.Second
+	}
+	if roundUp {
+		return metric.CeilStandardInterval(interval)
+	}
+	return metric.FloorStandardInterval(interval)
+}
+
+// QueryMetrics is the shared query policy boundary. Raw and aggregate slices are
+// transferred directly from batch primitives; nullable chart data is allocated only
+// when explicitly requested by Fill. All work uses ctx and one captured clock.
+func QueryMetrics(ctx context.Context, req MetricsQuery) (MetricsResult, error) {
+	if ctx == nil {
+		return MetricsResult{}, fmt.Errorf("%w: context is required", metric.ErrInvalidArgument)
+	}
+	if err := ctx.Err(); err != nil {
+		return MetricsResult{}, err
+	}
+	result := MetricsResult{Definitions: map[string]metric.Definition{}, Raw: map[string][]metric.Point{}, Values: map[string]map[metric.Aggregation][]metric.AggregatePoint{}, Intervals: map[string]time.Duration{}, Latest: map[string]map[string]metric.Point{}}
+	if req.Mode == "" {
+		req.Mode = QuerySeries
+	}
+	if req.Source == "" {
+		req.Source = SourceAuto
+	}
+	if req.Grouping == "" {
+		req.Grouping = GroupMerged
+	}
+	if req.Order == "" {
+		req.Order = metric.OrderAsc
+	}
+	if req.Rounding == "" {
+		req.Rounding = RoundFloor
+	}
+	if err := validateMetricsQuery(req); err != nil {
+		return result, err
+	}
+	now := req.Now
+	if now.IsZero() {
+		now = time.Now()
+	}
+	now = now.UTC()
+	req.Start, req.End = req.Start.UTC(), req.End.UTC()
+	req.Entities.IDs = uniqueQueryIDs(req.Entities.IDs)
+	// Never let the primitive's empty entity filter broaden an empty authorized set.
+
+	s := req.Store
+	if s == nil {
+		s = GetStore()
+	}
+	if s == nil {
+		return result, fmt.Errorf("metric store not enabled")
+	}
+	names := make([]string, 0, len(req.Specs))
+	for _, spec := range req.Specs {
+		names = append(names, spec.Name)
+	}
+	loadDefinitions := s.GetMetrics
+	if req.CompactDefinitions {
+		loadDefinitions = s.GetMetricsCompact
+	}
+	if !req.Entities.All && len(req.Entities.IDs) == 0 {
+		definitions, err := loadDefinitions(ctx, names)
+		if err != nil {
+			return result, err
+		}
+		result.Definitions = definitions
+		result.IsRaw = req.Source == SourceRaw || (req.Source == SourceAuto && (req.Mode == QueryPoints || UsesRawWindow(req.Start, req.End, now)))
+		if err := checkQueryDefinitions(names, definitions, req.AllowMissing); err != nil {
+			return result, err
+		}
+		return result, ctx.Err()
+	}
+	if req.Mode == QueryLatestBefore {
+		definitions, err := loadDefinitions(ctx, names)
+		if err != nil {
+			return result, err
+		}
+		result.Definitions = definitions
+		if err := checkQueryDefinitions(names, definitions, req.AllowMissing); err != nil {
+			return result, err
+		}
+		for _, name := range names {
+			if _, ok := definitions[name]; !ok {
+				continue
+			}
+			ids := req.Entities.IDs
+
+			for _, id := range ids {
+				if err := ctx.Err(); err != nil {
+					return result, err
+				}
+				point, found, err := s.LatestBefore(ctx, name, id, req.End)
+				if err != nil {
+					return result, err
+				}
+				if found {
+					if result.Latest[name] == nil {
+						result.Latest[name] = map[string]metric.Point{}
+					}
+					result.Latest[name][id] = point
+				}
+			}
+		}
+		return result, ctx.Err()
+	}
+	result.IsRaw = req.Source == SourceRaw || (req.Source == SourceAuto && (req.Mode == QueryPoints || UsesRawWindow(req.Start, req.End, now)))
+	if result.IsRaw {
+		definitions, err := loadDefinitions(ctx, names)
+		if err != nil {
+			return result, err
+		}
+		result.Definitions = definitions
+		if err := checkQueryDefinitions(names, definitions, req.AllowMissing); err != nil {
+			return result, err
+		}
+		known := make([]string, 0, len(names))
+		for _, name := range names {
+			if _, ok := definitions[name]; ok {
+				known = append(known, name)
+				result.Intervals[name] = 0
+			}
+		}
+		if len(known) > 0 {
+			result.Raw, err = s.QueryBatch(ctx, metric.BatchQuery{MetricNames: known, EntityIDs: req.Entities.IDs, Start: req.Start, End: req.End, Tags: req.Tags, Order: req.Order, OmitTags: req.OmitTags, OmitLabels: req.OmitLabels, IncludeSeriesIdentity: req.Fill.Gaps || req.Fill.PingNegativeAsNull})
+			if err != nil {
+				return result, err
+			}
+		}
+	} else {
+		entityCount := len(req.Entities.IDs)
+		if needsTotalEntityCount(req) {
+			if req.Entities.All {
+				count, err := s.CountEntities(ctx, names)
+				if err != nil {
+					return result, err
+				}
+				entityCount = count
+			}
+			// Explicit IDs are a conservative dictionary-count upper bound; never
+			// scan every metric/tier simply to plan a response budget.
+		}
+		if entityCount < 1 {
+			entityCount = 1
+		}
+		specs := make([]metric.BatchSeriesSpec, 0, len(req.Specs))
+		for _, spec := range req.Specs {
+			interval := spec.Interval
+			if interval == 0 {
+				points := spec.MaxPoints
+				if points == 0 {
+					points = req.Budget.PerSeries
+				}
+				if points == 0 {
+					points = 500
+				}
+				if points == 500 && spec.MaxPoints == 0 && req.Budget.PerSeries == 0 && req.Budget.Total == -1 {
+					points = -1
+				}
+				interval = time.Second
+				if points != -1 {
+					if req.Budget.Total > 0 {
+						budget := req.Budget.Total / entityCount
+						if budget < 1 {
+							budget = 1
+						}
+						if budget < points {
+							points = budget
+						}
+					}
+					interval = DownsampleInterval(req.End.Sub(req.Start), points, req.Rounding == RoundCeil)
+				}
+				interval = s.CompatibleSeriesInterval(req.Start, now, interval)
+				if interval <= 0 {
+					interval = time.Second
+				}
+			}
+			aggregations := spec.Aggregations
+			if len(aggregations) == 0 {
+				aggregations = []metric.Aggregation{metric.AggAvg}
+			}
+			specs = append(specs, metric.BatchSeriesSpec{MetricName: spec.Name, Aggregations: aggregations, Interval: interval, PreserveSeries: req.Grouping == GroupSeries, GroupByEntity: req.Grouping == GroupEntity})
+			result.Intervals[spec.Name] = interval
+		}
+		batch, err := s.SeriesBatch(ctx, metric.BatchSeriesQuery{Specs: specs, EntityIDs: req.Entities.IDs, Start: req.Start, End: req.End, Tags: req.Tags, Order: req.Order, OmitTags: req.OmitTags, CompactDefinitions: req.CompactDefinitions, IncludeSeriesIdentity: req.Fill.Gaps || req.Fill.PingNegativeAsNull}, now)
+		if err != nil {
+			return result, err
+		}
+		result.Definitions, result.Values = batch.Definitions, batch.Values
+		// SeriesBatch already loads metadata. Validate its result rather than issue a
+		// second metadata query; unknown metrics otherwise look like empty series.
+		if err := checkQueryDefinitions(names, batch.Definitions, req.AllowMissing); err != nil {
+			return result, err
+		}
+		for _, name := range names {
+			if _, ok := batch.Definitions[name]; !ok {
+				delete(result.Intervals, name)
+				delete(result.Values, name)
+			}
+		}
+	}
+	if req.Fill.Gaps || req.Fill.PingNegativeAsNull {
+		filled, err := buildQuerySeriesOwned(ctx, req, result, req.Projection == ProjectionChart)
+		if err != nil {
+			return result, err
+		}
+		result.Filled = filled
+		if req.Projection == ProjectionChart {
+			result.Raw, result.Values = nil, nil
+		}
+	}
+	return result, ctx.Err()
+}
+
+// needsTotalEntityCount excludes explicit intervals and unlimited specs: neither
+// consumes the total adaptive budget. Keep its precedence aligned with planning.
+func needsTotalEntityCount(req MetricsQuery) bool {
+	if req.Budget.Total <= 0 {
+		return false
+	}
+	for _, spec := range req.Specs {
+		if spec.Interval != 0 {
+			continue
+		}
+		points := spec.MaxPoints
+		if points == 0 {
+			points = req.Budget.PerSeries
+		}
+		if points != -1 {
+			return true
+		}
+	}
+	return false
+}
+
+func validateMetricsQuery(req MetricsQuery) error {
+	invalid := func(message string) error { return fmt.Errorf("%w: %s", metric.ErrInvalidArgument, message) }
+	if req.OmitTags && (req.Fill.Gaps || req.Fill.PingNegativeAsNull) {
+		return invalid("omitting tags with filled output is unsupported: series identity must be preserved")
+	}
+	if req.Mode == QueryLatestBefore && (req.OmitTags || req.OmitLabels) {
+		return invalid("latest-before output omissions are unsupported")
+	}
+	switch req.Mode {
+	case QueryPoints, QuerySeries, QueryLatestBefore:
+	default:
+		return invalid("unsupported query mode")
+	}
+	switch req.Source {
+	case SourceAuto, SourceRaw, SourceRollup:
+	default:
+		return invalid("unsupported query source")
+	}
+	switch req.Grouping {
+	case GroupMerged, GroupEntity, GroupSeries:
+	default:
+		return invalid("unsupported query grouping")
+	}
+	switch req.Projection {
+	case "", ProjectionFull:
+	case ProjectionChart:
+		if req.Mode == QueryLatestBefore || (!req.Fill.Gaps && !req.Fill.PingNegativeAsNull) {
+			return invalid("chart projection requires fill and does not support latest-before")
+		}
+	default:
+		return invalid("unsupported query projection")
+	}
+	switch req.Rounding {
+	case RoundFloor, RoundCeil:
+	default:
+		return invalid("unsupported interval rounding")
+	}
+	if req.Order != metric.OrderAsc && req.Order != metric.OrderDesc {
+		return invalid("unsupported query order")
+	}
+	if req.Entities.All && len(req.Entities.IDs) > 0 {
+		return invalid("all entities and explicit IDs are mutually exclusive")
+	}
+	for _, id := range req.Entities.IDs {
+		if strings.TrimSpace(id) == "" {
+			return invalid("entity ID cannot be empty")
+		}
+	}
+	if req.End.IsZero() {
+		return invalid("end time is required")
+	}
+	if req.Mode != QueryLatestBefore && (req.Start.IsZero() || req.End.Before(req.Start)) {
+		return invalid("valid start and end times are required")
+	}
+	if req.Mode == QueryLatestBefore && (len(req.Tags) > 0 || req.Source != SourceAuto) {
+		return invalid("latest-before requires auto source and does not support tag filters")
+	}
+	if req.Mode == QueryPoints && req.Source == SourceRollup {
+		return invalid("points mode requires raw or auto source")
+	}
+	if req.Mode == QueryLatestBefore && req.Entities.All {
+		return invalid("latest-before requires explicit entity IDs")
+	}
+	if req.Budget.Total < -1 || req.Budget.PerSeries < -1 {
+		return invalid("invalid point budget")
+	}
+	if len(req.Specs) == 0 {
+		return invalid("at least one metric specification is required")
+	}
+	seen := map[string]bool{}
+	for _, spec := range req.Specs {
+		if strings.TrimSpace(spec.Name) == "" || seen[spec.Name] {
+			return invalid("metric names must be nonempty and unique")
+		}
+		seen[spec.Name] = true
+		if spec.Interval < 0 || spec.MaxPoints < -1 {
+			return invalid("invalid metric interval or point budget")
+		}
+		for _, agg := range spec.Aggregations {
+			// Reuse primitive aggregation validation even when the selected source is raw.
+			if err := (metric.AggregateQuery{Query: metric.Query{MetricName: spec.Name, Start: req.End, End: req.End}, Aggregation: agg, Interval: time.Second}).Validate(); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+// UsesRawWindow selects the public adaptive raw window; its end boundary is strict.
+func UsesRawWindow(start, end, now time.Time) bool {
+	return end.Sub(start) <= 10*time.Minute && end.After(now.Add(-10*time.Minute))
+}
+
+func uniqueQueryIDs(ids []string) []string {
+	out := make([]string, 0, len(ids))
+	seen := map[string]bool{}
+	for _, id := range ids {
+		if !seen[id] {
+			out = append(out, id)
+			seen[id] = true
+		}
+	}
+	return out
+}
+func checkQueryDefinitions(names []string, definitions map[string]metric.Definition, allowMissing bool) error {
+	if !allowMissing {
+		for _, name := range names {
+			if _, ok := definitions[name]; !ok {
+				return fmt.Errorf("%w: metric %q", metric.ErrNotFound, name)
+			}
+		}
+	}
+	return nil
+}
+
+// querySeriesKey consumes storage's immutable, collision-free output identity.
+// Manually constructed points (and low-level queries without the opt-in) retain
+// the old canonical fallback. Neither grouping nor ordering uses a hash.
+func querySeriesKey(entity string, tags map[string]string, identity *metric.SeriesIdentity) string {
+	if key := identity.Key(); key != "" {
+		return key
+	}
+	return metric.NewSeriesIdentity(entity, tags).Key()
+}
+
+func buildQuerySeries(ctx context.Context, req MetricsQuery, result MetricsResult) ([]MetricSeries, error) {
+	return buildQuerySeriesOwned(ctx, req, result, false)
+}
+
+// detach is only valid for QueryMetrics-owned source maps. Release each source
+// array after conversion, before allocating gaps or processing the next metric.
+func buildQuerySeriesOwned(ctx context.Context, req MetricsQuery, result MetricsResult, detach bool) ([]MetricSeries, error) {
+	out := []MetricSeries{}
+	for _, spec := range req.Specs {
+		if err := ctx.Err(); err != nil {
+			return nil, err
+		}
+		if _, ok := result.Definitions[spec.Name]; !ok {
+			continue
+		}
+		aggregations := spec.Aggregations
+		if result.IsRaw {
+			aggregations = []metric.Aggregation{""}
+		} else if len(aggregations) == 0 {
+			aggregations = []metric.Aggregation{metric.AggAvg}
+		}
+		for aggIndex, agg := range aggregations {
+			if err := ctx.Err(); err != nil {
+				return nil, err
+			}
+			var seenEntities map[string]bool
+			if len(req.Entities.IDs) > 0 && (result.IsRaw || req.Grouping != GroupMerged) {
+				seenEntities = make(map[string]bool, len(req.Entities.IDs))
+			}
+			groups := map[string]*MetricSeries{}
+			add := func(entity string, tags map[string]string, identity *metric.SeriesIdentity, value MetricValue) {
+				// Exact samples always preserve identity; aggregate identity is determined by
+				// the requested primitive grouping and must not be collapsed again here.
+				key := querySeriesKey(entity, tags, identity)
+				series := groups[key]
+				if series == nil {
+					series = &MetricSeries{MetricName: spec.Name, EntityID: entity, Aggregation: agg, Tags: tags, Interval: result.Intervals[spec.Name]}
+					groups[key] = series
+					if seenEntities != nil {
+						seenEntities[entity] = true
+					}
+				}
+				if req.Fill.PingNegativeAsNull && (spec.Name == MetricPingLatency || spec.Name == MetricPingLoss) && value.Value != nil && *value.Value == -1 {
+					value.Value = nil
+				}
+				series.Points = append(series.Points, value)
+			}
+			if result.IsRaw {
+				for i, p := range result.Raw[spec.Name] {
+					if i%256 == 0 {
+						if err := ctx.Err(); err != nil {
+							return nil, err
+						}
+					}
+					v := p.Value
+					add(p.EntityID, p.Tags, p.SeriesIdentity, MetricValue{Time: p.Timestamp, Value: &v, Count: 1, Tags: p.Tags, Labels: p.Labels})
+				}
+			} else {
+				for i, p := range result.Values[spec.Name][agg] {
+					if i%256 == 0 {
+						if err := ctx.Err(); err != nil {
+							return nil, err
+						}
+					}
+					v := p.Value
+					add(p.EntityID, p.Tags, p.SeriesIdentity, MetricValue{Time: p.Bucket, Value: &v, Count: p.Count, Tags: p.Tags})
+				}
+			}
+			if detach {
+				if result.IsRaw {
+					delete(result.Raw, spec.Name)
+				} else {
+					// Duplicate aggregation specs historically produce duplicate series.
+					needed := false
+					for _, next := range aggregations[aggIndex+1:] {
+						needed = needed || next == agg
+					}
+					if !needed {
+						delete(result.Values[spec.Name], agg)
+					}
+				}
+			}
+			// Seed missing entities directly; do not scan all groups for each ID or
+			// allocate a placeholder point only to discard it.
+			seed := func(id string) {
+				groups[querySeriesKey(id, req.Tags, nil)] = &MetricSeries{MetricName: spec.Name, EntityID: id, Aggregation: agg, Tags: req.Tags, Interval: result.Intervals[spec.Name]}
+				if seenEntities != nil {
+					seenEntities[id] = true
+				}
+			}
+			if result.IsRaw || req.Grouping != GroupMerged {
+				for i, id := range req.Entities.IDs {
+					if i%256 == 0 {
+						if err := ctx.Err(); err != nil {
+							return nil, err
+						}
+					}
+					if !seenEntities[id] {
+						seed(id)
+					}
+				}
+			}
+			if len(groups) == 0 {
+				ids := req.Entities.IDs
+				if len(ids) == 0 || (!result.IsRaw && req.Grouping == GroupMerged) {
+					ids = []string{""}
+				}
+				for _, id := range ids {
+					seed(id)
+				}
+			}
+
+			keys := make([]string, 0, len(groups))
+			for key := range groups {
+				if len(keys)%256 == 0 {
+					if err := ctx.Err(); err != nil {
+						return nil, err
+					}
+				}
+				keys = append(keys, key)
+			}
+			if err := ctx.Err(); err != nil {
+				return nil, err
+			}
+			sort.Strings(keys)
+			for _, key := range keys {
+				if err := ctx.Err(); err != nil {
+					return nil, err
+				}
+				series := *groups[key]
+				sort.SliceStable(series.Points, func(i, j int) bool { return series.Points[i].Time.Before(series.Points[j].Time) })
+				if err := ctx.Err(); err != nil {
+					return nil, err
+				}
+				if req.Fill.Gaps {
+					var err error
+					series, err = fillMetricSeriesOwned(ctx, series, req.Start, req.End)
+					if err != nil {
+						return nil, err
+					}
+				}
+				if req.Order == metric.OrderDesc {
+					for i, j := 0, len(series.Points)-1; i < j; i, j = i+1, j-1 {
+						if i%256 == 0 {
+							if err := ctx.Err(); err != nil {
+								return nil, err
+							}
+						}
+						series.Points[i], series.Points[j] = series.Points[j], series.Points[i]
+					}
+				}
+				out = append(out, series)
+			}
+		}
+	}
+	return out, ctx.Err()
+}
+
+// FillMetricSeries matches the public chart's adaptive lower-quartile gap policy.
+func FillMetricSeries(series MetricSeries, start, end time.Time) MetricSeries {
+	filled, _ := fillMetricSeries(context.Background(), series, start, end)
+	return filled
+}
+
+func fillMetricSeries(ctx context.Context, series MetricSeries, start, end time.Time) (MetricSeries, error) {
+	if err := ctx.Err(); err != nil {
+		return series, err
+	}
+	// Public callers retain ownership, including spare capacity. Never write there.
+	series.Points = append([]MetricValue(nil), series.Points...)
+	return fillMetricSeriesOwned(ctx, series, start, end)
+}
+
+// fillMetricSeriesOwned inserts gaps backwards into exclusively owned storage.
+// Dense series reuse their point array; sparse series grow only when capacity
+// cannot accommodate the exact number of gaps, rather than always copying into
+// a second full point array. The public wrapper above remains non-mutating.
+func fillMetricSeriesOwned(ctx context.Context, series MetricSeries, start, end time.Time) (MetricSeries, error) {
+	if err := ctx.Err(); err != nil {
+		return series, err
+	}
+	deltas := make([]time.Duration, 0, len(series.Points))
+	for i := 1; i < len(series.Points); i++ {
+		if i%256 == 0 {
+			if err := ctx.Err(); err != nil {
+				return series, err
+			}
+		}
+		if d := series.Points[i].Time.Sub(series.Points[i-1].Time); d > 0 {
+			deltas = append(deltas, d)
+		}
+	}
+	if err := ctx.Err(); err != nil {
+		return series, err
+	}
+	expected := series.Interval
+	if len(deltas) >= 2 {
+		sort.Slice(deltas, func(i, j int) bool { return deltas[i] < deltas[j] })
+		if observed := deltas[(len(deltas)-1)/4]; observed > expected {
+			expected = observed
+		}
+	}
+	if err := ctx.Err(); err != nil {
+		return series, err
+	}
+	if expected > 0 {
+		series.Interval = expected
+	}
+	null := func(at time.Time) MetricValue { return MetricValue{Time: at.UTC(), Tags: series.Tags} }
+	n := len(series.Points)
+	if n == 0 {
+		series.Points = append(series.Points, null(start), null(end))
+		return series, ctx.Err()
+	}
+	leading := start.Before(series.Points[0].Time)
+	gap := func(i int) bool {
+		return i > 0 && expected > 0 && series.Points[i-1].Value != nil && series.Points[i].Value != nil && series.Points[i].Time.Sub(series.Points[i-1].Time) > expected+expected/2
+	}
+	extra := 0
+	if leading {
+		extra++
+	}
+	for i := 1; i < n; i++ {
+		if i%256 == 0 {
+			if err := ctx.Err(); err != nil {
+				return series, err
+			}
+		}
+		if gap(i) {
+			extra++
+		}
+	}
+	if extra == 0 {
+		return series, ctx.Err()
+	}
+	if cap(series.Points) < n+extra {
+		points := make([]MetricValue, n+extra)
+		copy(points, series.Points)
+		series.Points = points
+	} else {
+		series.Points = series.Points[:n+extra]
+	}
+	write := n + extra - 1
+	for i := n - 1; i >= 0; i-- {
+		if i%256 == 0 {
+			if err := ctx.Err(); err != nil {
+				return series, err
+			}
+		}
+		// Decide before moving: write may equal i, but never precedes it.
+		insert := gap(i)
+		var at time.Time
+		if insert {
+			at = series.Points[i-1].Time.Add(expected)
+		}
+		series.Points[write] = series.Points[i]
+		write--
+		if insert {
+			series.Points[write] = null(at)
+			write--
+		}
+	}
+	if leading {
+		series.Points[0] = null(start)
+	}
+	return series, ctx.Err()
+}

internal/metricstore/raw_sql.go

@@ -0,0 +1,63 @@
+package metricstore
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+
+	"github.com/komari-monitor/komari/pkg/metric"
+)
+
+// QueryContext runs a raw read query against the active metric store. The
+// caller must invoke the returned release function after closing rows.
+func QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, metric.Driver, func(), error) {
+	return QueryForDriver(ctx, func(metric.Driver) (string, error) {
+		return query, nil
+	}, args...)
+}
+
+// QueryForDriver runs a raw read query whose SQL depends on the active store's
+// driver. The caller must invoke the returned release function after closing rows.
+func QueryForDriver(ctx context.Context, query func(metric.Driver) (string, error), args ...any) (*sql.Rows, metric.Driver, func(), error) {
+	if err := storeOperations.AcquireShared(ctx); err != nil {
+		return nil, "", nil, fmt.Errorf("wait for metric store operations before query: %w", err)
+	}
+
+	storeMu.RLock()
+	activeStore := store
+	storeMu.RUnlock()
+	if activeStore == nil {
+		storeOperations.ReleaseShared()
+		return nil, "", nil, ErrStoreNotInitialized
+	}
+
+	statement, err := query(activeStore.Driver())
+	if err != nil {
+		storeOperations.ReleaseShared()
+		return nil, "", nil, err
+	}
+	rows, err := activeStore.QueryContext(ctx, statement, args...)
+	if err != nil {
+		storeOperations.ReleaseShared()
+		return nil, "", nil, err
+	}
+	return rows, activeStore.Driver(), storeOperations.ReleaseShared, nil
+}
+
+// ExecContext runs a raw statement against the active metric store.
+func ExecContext(ctx context.Context, query string, args ...any) (sql.Result, metric.Driver, error) {
+	if err := storeOperations.Acquire(ctx); err != nil {
+		return nil, "", fmt.Errorf("wait for metric store operations before execution: %w", err)
+	}
+	defer storeOperations.Release()
+
+	storeMu.RLock()
+	activeStore := store
+	storeMu.RUnlock()
+	if activeStore == nil {
+		return nil, "", ErrStoreNotInitialized
+	}
+
+	result, err := activeStore.ExecContext(ctx, query, args...)
+	return result, activeStore.Driver(), err
+}

internal/metricstore/recovery_test.go

@@ -0,0 +1,164 @@
+package metricstore
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"path/filepath"
+	"testing"
+
+	"github.com/komari-monitor/komari/internal/config"
+	"github.com/komari-monitor/komari/pkg/metric"
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+)
+
+func prepareRecoveryTest(t *testing.T) {
+	t.Helper()
+	configDB, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open config db: %v", err)
+	}
+	config.SetDb(configDB)
+
+	storeInitMu.Lock()
+	storeMigMu.Lock()
+	previousClosing := storeClosing
+	storeClosing = false
+	storeMigMu.Unlock()
+	storeMu.Lock()
+	previousStore := store
+	previousFingerprint := storeFingerprint
+	store = nil
+	storeFingerprint = ""
+	storeMu.Unlock()
+	storeInitMu.Unlock()
+
+	t.Cleanup(func() {
+		_ = CloseStoreContext(context.Background())
+		storeMigMu.Lock()
+		storeClosing = previousClosing
+		storeMigMu.Unlock()
+		storeMu.Lock()
+		store = previousStore
+		storeFingerprint = previousFingerprint
+		storeMu.Unlock()
+	})
+}
+
+func TestRecoverStoreFailureKeepsCurrentConfig(t *testing.T) {
+	prepareRecoveryTest(t)
+	if err := config.SetMany(map[string]any{
+		MetricDBDriverKey: "sqlite",
+		MetricDBDSNKey:    "old.db",
+	}); err != nil {
+		t.Fatalf("save original config: %v", err)
+	}
+
+	missing := "file:" + filepath.ToSlash(filepath.Join(t.TempDir(), "missing.db")) + "?mode=ro"
+	err := RecoverStore(context.Background(), &MetricStoreConfig{Driver: "sqlite", DSN: missing})
+	if err == nil {
+		t.Fatal("recovery unexpectedly opened a missing read-only database")
+	}
+	if got, _ := config.GetAs[string](MetricDBDSNKey, ""); got != "old.db" {
+		t.Fatalf("DSN changed after failed recovery: %q", got)
+	}
+	if GetStore() != nil {
+		t.Fatal("failed recovery installed a store")
+	}
+}
+
+func TestRecoverStoreRecordsManualMigrationSource(t *testing.T) {
+	prepareRecoveryTest(t)
+	dsn := filepath.ToSlash(filepath.Join(t.TempDir(), "recovered.db"))
+	t.Cleanup(func() { _ = CloseStoreContext(context.Background()) })
+	cfg := &MetricStoreConfig{Driver: "sqlite", DSN: dsn}
+	if err := RecoverStore(context.Background(), cfg); err != nil {
+		t.Fatalf("recover store: %v", err)
+	}
+	if GetStore() == nil {
+		t.Fatal("successful recovery did not install a store")
+	}
+	wantTarget := targetFingerprint(cfg)
+	if got, _ := config.GetAs[string](MigrationTargetKey, ""); got != wantTarget {
+		t.Fatalf("migration target = %q, want %q", got, wantTarget)
+	}
+}
+
+func TestRecoverStorePersistsLegacyStoreForStructureGuide(t *testing.T) {
+	prepareRecoveryTest(t)
+	dsn := filepath.ToSlash(filepath.Join(t.TempDir(), "legacy.db"))
+	db, err := sql.Open("sqlite3", dsn)
+	if err != nil {
+		t.Fatalf("open legacy store: %v", err)
+	}
+	if _, err := db.Exec(`CREATE TABLE metric_definitions (
+		name TEXT PRIMARY KEY, type TEXT NOT NULL, unit TEXT NOT NULL,
+		description TEXT NOT NULL, retention_days INTEGER NOT NULL,
+		metadata TEXT NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+	)`); err != nil {
+		_ = db.Close()
+		t.Fatalf("create legacy definition table: %v", err)
+	}
+	if err := db.Close(); err != nil {
+		t.Fatalf("close legacy store: %v", err)
+	}
+
+	cfg := &MetricStoreConfig{Driver: "sqlite", DSN: dsn}
+	if err := RecoverStore(context.Background(), cfg); err != nil {
+		t.Fatalf("recover legacy store: %v", err)
+	}
+	if GetStore() != nil {
+		t.Fatal("legacy recovery installed the store before structure upgrade")
+	}
+	if got, _ := config.GetAs[string](MetricDBDSNKey, ""); got != dsn {
+		t.Fatalf("saved legacy DSN = %q, want %q", got, dsn)
+	}
+	required, err := StructureUpgradeRequired(context.Background())
+	if err != nil {
+		t.Fatalf("detect structure upgrade after recovery: %v", err)
+	}
+	if !required {
+		t.Fatal("legacy recovery did not lead to the structure upgrade guide")
+	}
+}
+
+func TestReloadRejectsLegacyStoreForStructureUpgrade(t *testing.T) {
+	prepareRecoveryTest(t)
+	active, err := metric.Open(context.Background(), metric.SQLite(":memory:"))
+	if err != nil {
+		t.Fatalf("open active metric store: %v", err)
+	}
+	installTestStore(t, active)
+
+	dsn := filepath.ToSlash(filepath.Join(t.TempDir(), "legacy.db"))
+	db, err := sql.Open("sqlite3", dsn)
+	if err != nil {
+		t.Fatalf("open legacy store: %v", err)
+	}
+	if _, err := db.Exec(`CREATE TABLE metric_definitions (
+		name TEXT PRIMARY KEY, type TEXT NOT NULL, unit TEXT NOT NULL,
+		description TEXT NOT NULL, retention_days INTEGER NOT NULL,
+		metadata TEXT NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+	)`); err != nil {
+		_ = db.Close()
+		t.Fatalf("create legacy definition table: %v", err)
+	}
+	if err := db.Close(); err != nil {
+		t.Fatalf("close legacy store: %v", err)
+	}
+	if err := config.SetMany(map[string]any{
+		MetricDBDriverKey: "sqlite",
+		MetricDBDSNKey:    dsn,
+	}); err != nil {
+		t.Fatalf("save legacy metric store config: %v", err)
+	}
+
+	err = Reload(context.Background())
+	if !errors.Is(err, ErrStructureUpgradeRequired) {
+		t.Fatalf("reload error = %v, want %v", err, ErrStructureUpgradeRequired)
+	}
+	if GetStore() != active {
+		t.Fatal("legacy target replaced the active metric store during hot reload")
+	}
+}

internal/metricstore/redact.go

@@ -0,0 +1,22 @@
+package metricstore
+
+import (
+	"regexp"
+	"strings"
+)
+
+var (
+	metricCredentialPattern    = regexp.MustCompile(`(?i)\b(password|passwd)\s*=\s*('[^']*'|"[^"]*"|[^\s,;)&]+)`)
+	metricURLCredentialPattern = regexp.MustCompile(`(?i)([a-z0-9_.-]+):([^@\s]+)@`)
+)
+
+// RedactConnectionError removes the supplied DSN and common password fragments
+// before a connection error is shown to an administrator or written to a log.
+func RedactConnectionError(message, dsn string) string {
+	message = strings.TrimSpace(message)
+	if dsn != "" {
+		message = strings.ReplaceAll(message, dsn, "[redacted]")
+	}
+	message = metricCredentialPattern.ReplaceAllString(message, "$1=[redacted]")
+	return metricURLCredentialPattern.ReplaceAllString(message, "$1:[redacted]@")
+}

internal/metricstore/report_batcher.go

@@ -0,0 +1,405 @@
+package metricstore
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"time"
+
+	logger "github.com/komari-monitor/komari/utils/log"
+
+	"github.com/komari-monitor/komari/database/models"
+	"github.com/komari-monitor/komari/pkg/metric"
+	v2 "github.com/komari-monitor/komari/protocol/v2"
+)
+
+type reportTrafficState struct {
+	mu sync.Mutex
+
+	reportTrafficValues
+}
+
+type reportTrafficValues struct {
+	initialized bool
+	timestamp   time.Time
+	hasUp       bool
+	totalUp     int64
+	totalUpAt   time.Time
+	hasDown     bool
+	totalDown   int64
+	totalDownAt time.Time
+}
+
+var (
+	reportTrafficStates sync.Map
+	reportWriteMu       sync.Mutex
+)
+
+const (
+	reportBatchInterval     = 3 * time.Second
+	reportBatchQueueSize    = 512
+	pingBatchQueueSize      = 4096
+	pingBatchMaxRecords     = 512
+	reportBatchWriteTimeout = 10 * time.Second
+	// Longer gaps have no reliable per-bucket traffic attribution.
+	maxTrafficReportGap = 15 * time.Minute
+)
+
+var (
+	reportBatcherMu sync.Mutex
+	reportBatcher   *reportBatchWorker
+)
+
+var (
+	ErrReportBatchQueueFull = errors.New("metric report batch queue is full")
+	ErrReportBatchStopped   = errors.New("metric report batcher is stopped")
+	ErrPingBatchQueueFull   = errors.New("ping batch queue is full")
+)
+
+type reportBatchRequest struct {
+	ctx  context.Context
+	done chan error
+	stop bool
+}
+
+type reportBatchWorker struct {
+	mu        sync.Mutex
+	queue     chan v2.Report
+	pingQueue chan models.PingRecord
+	requests  chan reportBatchRequest
+	done      chan struct{}
+	stopping  bool
+}
+
+// StartReportBatcher starts the shared report writer. Exact samples are kept in
+// the short raw window while the same writes update in-memory minute buckets.
+func StartReportBatcher() {
+	reportBatcherMu.Lock()
+	defer reportBatcherMu.Unlock()
+	if reportBatcher != nil {
+		return
+	}
+	worker := &reportBatchWorker{
+		queue:     make(chan v2.Report, reportBatchQueueSize),
+		pingQueue: make(chan models.PingRecord, pingBatchQueueSize),
+		requests:  make(chan reportBatchRequest, 1),
+		done:      make(chan struct{}),
+	}
+	reportBatcher = worker
+	go worker.run()
+}
+
+// StopReportBatcher stops the report writer after flushing all queued reports.
+func StopReportBatcher(ctx context.Context) error {
+	reportBatcherMu.Lock()
+	worker := reportBatcher
+	if worker == nil {
+		reportBatcherMu.Unlock()
+		return nil
+	}
+	worker.mu.Lock()
+	worker.stopping = true
+	worker.mu.Unlock()
+	reportBatcherMu.Unlock()
+
+	request := reportBatchRequest{ctx: ctx, done: make(chan error, 1), stop: true}
+	select {
+	case worker.requests <- request:
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+	select {
+	case err := <-request.done:
+		<-worker.done
+		reportBatcherMu.Lock()
+		if reportBatcher == worker {
+			reportBatcher = nil
+		}
+		reportBatcherMu.Unlock()
+		return err
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}
+
+// FlushReportBatch synchronously flushes the current queue. It is useful for
+// controlled handoff points and deterministic tests; normal operation uses the
+// worker ticker and the active mode's flush interval.
+func FlushReportBatch(ctx context.Context) error {
+	reportBatcherMu.Lock()
+	worker := reportBatcher
+	reportBatcherMu.Unlock()
+	if worker == nil {
+		return nil
+	}
+	request := reportBatchRequest{ctx: ctx, done: make(chan error, 1)}
+	worker.mu.Lock()
+	stopping := worker.stopping
+	worker.mu.Unlock()
+	if stopping {
+		return ErrReportBatchStopped
+	}
+	select {
+	case worker.requests <- request:
+	case <-worker.done:
+		return ErrReportBatchStopped
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+	select {
+	case err := <-request.done:
+		return err
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}
+
+// WriteReport persists one agent report and adds it to in-memory minute
+// summaries using the same server receive time. Traffic deltas remain summable
+// after rollup.
+func WriteReport(ctx context.Context, report v2.Report) (v2.Report, error) {
+	if report.UUID == "" {
+		return v2.Report{}, fmt.Errorf("report UUID is required")
+	}
+	if report.UpdatedAt.IsZero() {
+		return v2.Report{}, fmt.Errorf("report receive time is required")
+	}
+	report.UpdatedAt = report.UpdatedAt.UTC()
+	if GetStore() == nil {
+		return v2.Report{}, fmt.Errorf("metric store not enabled")
+	}
+
+	reportBatcherMu.Lock()
+	worker := reportBatcher
+	reportBatcherMu.Unlock()
+	if worker != nil {
+		if err := worker.enqueue(ctx, report); err != nil {
+			return v2.Report{}, err
+		}
+		return report, nil
+	}
+
+	saved, err := writeReportBatch(ctx, []v2.Report{report})
+	if err != nil {
+		return v2.Report{}, err
+	}
+	return saved[0], nil
+}
+
+func (w *reportBatchWorker) enqueue(ctx context.Context, report v2.Report) error {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	if w.stopping {
+		return ErrReportBatchStopped
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	select {
+	case w.queue <- report:
+		return nil
+	default:
+		return ErrReportBatchQueueFull
+	}
+}
+
+func (w *reportBatchWorker) run() {
+	ticker := time.NewTicker(reportBatchInterval)
+	defer ticker.Stop()
+
+	var pending []v2.Report
+	var pendingPings []models.PingRecord
+	for {
+		select {
+		case request := <-w.requests:
+			pending = append(pending, drainQueue(w.queue, reportBatchQueueSize)...)
+			pendingPings = append(pendingPings, drainQueue(w.pingQueue, pingBatchQueueSize)...)
+			err := errors.Join(
+				writePendingReports(request.ctx, &pending),
+				writePendingPingRecords(request.ctx, &pendingPings),
+			)
+			if request.stop {
+				if err != nil {
+					logger.Errorf("metricstore", "failed to flush metric report batch during shutdown: %v", err)
+				}
+				close(w.done)
+				request.done <- err
+				return
+			}
+			request.done <- err
+		case <-ticker.C:
+			pendingPings = append(pendingPings, drainQueue(w.pingQueue, pingBatchQueueSize)...)
+			if err := writePendingPingRecords(context.Background(), &pendingPings); err != nil {
+				logger.Errorf("metricstore", "failed to flush ping batch: %v", err)
+			}
+			pending = append(pending, drainQueue(w.queue, reportBatchQueueSize)...)
+			if err := writePendingReports(context.Background(), &pending); err != nil {
+				logger.Errorf("metricstore", "failed to flush metric report batch: %v", err)
+			}
+		}
+	}
+}
+
+func (w *reportBatchWorker) enqueuePing(ctx context.Context, record models.PingRecord) error {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	if w.stopping {
+		return ErrReportBatchStopped
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	select {
+	case w.pingQueue <- record:
+		return nil
+	default:
+		return ErrPingBatchQueueFull
+	}
+}
+
+// drainQueue takes up to limit queued items without blocking.
+func drainQueue[T any](queue <-chan T, limit int) []T {
+	n := min(len(queue), limit)
+	if n <= 0 {
+		return nil
+	}
+	items := make([]T, 0, n)
+	for len(items) < limit {
+		select {
+		case item := <-queue:
+			items = append(items, item)
+		default:
+			return items
+		}
+	}
+	return items
+}
+
+// writePendingReports commits all pending reports as one batch and keeps them
+// for the next attempt when the write fails.
+func writePendingReports(ctx context.Context, pending *[]v2.Report) error {
+	if len(*pending) == 0 {
+		return nil
+	}
+	writeCtx, cancel := context.WithTimeout(ctx, reportBatchWriteTimeout)
+	defer cancel()
+	if _, err := writeReportBatch(writeCtx, *pending); err != nil {
+		return err
+	}
+	*pending = (*pending)[:0]
+	return nil
+}
+
+func writePendingPingRecords(ctx context.Context, pending *[]models.PingRecord) error {
+	for len(*pending) > 0 {
+		batchSize := len(*pending)
+		if batchSize > pingBatchMaxRecords {
+			batchSize = pingBatchMaxRecords
+		}
+		writeCtx, cancel := context.WithTimeout(ctx, reportBatchWriteTimeout)
+		err := writePingRecords(writeCtx, (*pending)[:batchSize])
+		cancel()
+		if err != nil {
+			return err
+		}
+		*pending = (*pending)[batchSize:]
+	}
+	return nil
+}
+
+func writeReportBatch(ctx context.Context, reports []v2.Report) ([]v2.Report, error) {
+	if len(reports) == 0 {
+		return nil, nil
+	}
+	if err := storeOperations.AcquireShared(ctx); err != nil {
+		return nil, fmt.Errorf("wait for metric store operation before writing reports: %w", err)
+	}
+	defer storeOperations.ReleaseShared()
+
+	// Serialize baseline reads and commits, including direct writes without
+	// the background batcher.
+	reportWriteMu.Lock()
+	defer reportWriteMu.Unlock()
+
+	s := GetStore()
+	if s == nil {
+		return nil, fmt.Errorf("metric store not enabled")
+	}
+
+	prepared := make([]v2.Report, len(reports))
+	copy(prepared, reports)
+	points := make([]metric.Point, 0, len(reports)*20)
+	pendingStates := make(map[*reportTrafficState]reportTrafficValues)
+	for i, report := range prepared {
+		stateValue, _ := reportTrafficStates.LoadOrStore(report.UUID, &reportTrafficState{})
+		state := stateValue.(*reportTrafficState)
+		values, ok := pendingStates[state]
+		if !ok {
+			state.mu.Lock()
+			values = state.reportTrafficValues
+			state.mu.Unlock()
+		}
+		if !values.initialized {
+			totalUp, hasUp, err := latestReportPoint(ctx, s, MetricNetTotalUp, report.UUID, report.UpdatedAt)
+			if err != nil {
+				logger.Errorf("metricstore", "failed to restore previous upload counter for %s: %v", report.UUID, err)
+			} else {
+				values.totalUp = int64(totalUp.Value)
+				values.totalUpAt = totalUp.Timestamp
+				values.hasUp = hasUp
+			}
+			totalDown, hasDown, err := latestReportPoint(ctx, s, MetricNetTotalDown, report.UUID, report.UpdatedAt)
+			if err != nil {
+				logger.Errorf("metricstore", "failed to restore previous download counter for %s: %v", report.UUID, err)
+			} else {
+				values.totalDown = int64(totalDown.Value)
+				values.totalDownAt = totalDown.Timestamp
+				values.hasDown = hasDown
+			}
+			values.initialized = true
+			// Keep only the restored baseline on failure. WriteBatch may have
+			// accepted raw samples before a rollup flush fails, so restoring
+			// again on retry could otherwise read this uncommitted batch.
+			state.mu.Lock()
+			state.reportTrafficValues = values
+			state.mu.Unlock()
+		}
+
+		if !values.timestamp.IsZero() && !report.UpdatedAt.After(values.timestamp) {
+			report.UpdatedAt = values.timestamp.Add(time.Millisecond)
+		}
+		trafficUp := int64(0)
+		if values.hasUp && !values.totalUpAt.IsZero() && report.UpdatedAt.Sub(values.totalUpAt) <= maxTrafficReportGap {
+			trafficUp = TrafficCounterDelta(report.Network.TotalUp, values.totalUp)
+		}
+		trafficDown := int64(0)
+		if values.hasDown && !values.totalDownAt.IsZero() && report.UpdatedAt.Sub(values.totalDownAt) <= maxTrafficReportGap {
+			trafficDown = TrafficCounterDelta(report.Network.TotalDown, values.totalDown)
+		}
+		points = append(points, reportMetricPoints(report, trafficUp, trafficDown)...)
+		values.timestamp = report.UpdatedAt
+		values.hasUp = true
+		values.totalUp = report.Network.TotalUp
+		values.totalUpAt = report.UpdatedAt
+		values.hasDown = true
+		values.totalDown = report.Network.TotalDown
+		values.totalDownAt = report.UpdatedAt
+		pendingStates[state] = values
+		prepared[i] = report
+	}
+
+	if err := s.WriteBatch(ctx, points); err != nil {
+		return nil, err
+	}
+
+	// Advance counters and timestamps only after success. Retried batches
+	// must replace the same samples, not manufacture resets or new timestamps.
+	for state, values := range pendingStates {
+		state.mu.Lock()
+		state.reportTrafficValues = values
+		state.mu.Unlock()
+	}
+
+	return prepared, nil
+}

internal/metricstore/report_mapping.go

@@ -0,0 +1,142 @@
+package metricstore
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"time"
+
+	"github.com/komari-monitor/komari/database/models"
+	"github.com/komari-monitor/komari/pkg/metric"
+	v2 "github.com/komari-monitor/komari/protocol/v2"
+)
+
+func reportMetricPoints(report v2.Report, trafficUp, trafficDown int64) []metric.Point {
+	entityID := report.UUID
+	ts := report.UpdatedAt
+	points := []metric.Point{
+		{MetricName: MetricCPU, EntityID: entityID, Timestamp: ts, Value: report.CPU.Usage},
+		{MetricName: MetricRAM, EntityID: entityID, Timestamp: ts, Value: float64(report.Ram.Used)},
+		{MetricName: MetricSwap, EntityID: entityID, Timestamp: ts, Value: float64(report.Swap.Used)},
+		{MetricName: MetricLoad, EntityID: entityID, Timestamp: ts, Value: report.Load.Load1},
+		{MetricName: MetricDisk, EntityID: entityID, Timestamp: ts, Value: float64(report.Disk.Used)},
+		{MetricName: MetricNetIn, EntityID: entityID, Timestamp: ts, Value: float64(report.Network.Down)},
+		{MetricName: MetricNetOut, EntityID: entityID, Timestamp: ts, Value: float64(report.Network.Up)},
+		{MetricName: MetricNetTotalUp, EntityID: entityID, Timestamp: ts, Value: float64(report.Network.TotalUp)},
+		{MetricName: MetricNetTotalDown, EntityID: entityID, Timestamp: ts, Value: float64(report.Network.TotalDown)},
+		{MetricName: MetricTrafficUp, EntityID: entityID, Timestamp: ts, Value: float64(trafficUp)},
+		{MetricName: MetricTrafficDown, EntityID: entityID, Timestamp: ts, Value: float64(trafficDown)},
+		{MetricName: MetricProcess, EntityID: entityID, Timestamp: ts, Value: float64(report.Process)},
+		{MetricName: MetricConnections, EntityID: entityID, Timestamp: ts, Value: float64(report.Connections.TCP)},
+		{MetricName: MetricConnectionsUDP, EntityID: entityID, Timestamp: ts, Value: float64(report.Connections.UDP)},
+	}
+	if report.GPU == nil {
+		return points
+	}
+	points = append(points, metric.Point{MetricName: MetricGPU, EntityID: entityID, Timestamp: ts, Value: report.GPU.AverageUsage})
+	for deviceIndex, gpu := range report.GPU.DetailedInfo {
+		tags := map[string]string{
+			"device_index": strconv.Itoa(deviceIndex),
+			"device_name":  gpu.Name,
+		}
+		points = append(points,
+			metric.Point{MetricName: MetricGPUMem, EntityID: entityID, Timestamp: ts, Value: float64(gpu.MemoryUsed), Tags: tags},
+			metric.Point{MetricName: MetricGPUMemTotal, EntityID: entityID, Timestamp: ts, Value: float64(gpu.MemoryTotal), Tags: tags},
+			metric.Point{MetricName: MetricGPUDeviceUsage, EntityID: entityID, Timestamp: ts, Value: gpu.Utilization, Tags: tags},
+			metric.Point{MetricName: MetricGPUTemp, EntityID: entityID, Timestamp: ts, Value: float64(gpu.Temperature), Tags: tags},
+		)
+	}
+	return points
+}
+
+// latestReportPoint preserves independent counter restoration errors: one failed
+// direction must not prevent the other from restoring its baseline.
+func latestReportPoint(ctx context.Context, s *metric.Store, metricName, entityID string, before time.Time) (metric.Point, bool, error) {
+	loaded, err := QueryMetrics(ctx, MetricsQuery{
+		Store: s, Mode: QueryLatestBefore, Source: SourceAuto,
+		Entities: EntityScope{IDs: []string{entityID}},
+		Specs:    []MetricSpec{{Name: metricName}}, End: before, AllowMissing: true,
+	})
+	if err != nil {
+		return metric.Point{}, false, err
+	}
+	point, ok := loaded.Latest[metricName][entityID]
+	return point, ok, nil
+}
+
+func latestReportCounter(ctx context.Context, s *metric.Store, metricName, entityID string, before time.Time) (int64, bool, error) {
+	point, ok, err := latestReportPoint(ctx, s, metricName, entityID, before)
+	if err != nil {
+		return 0, false, err
+	}
+	if !ok {
+		return 0, false, nil
+	}
+	return int64(point.Value), true, nil
+}
+
+// GetLatestTrafficBefore returns the latest retained upload/download counters
+// before a boundary, transparently reading raw points or rollup summaries.
+func GetLatestTrafficBefore(ctx context.Context, entityIDs []string, before time.Time) (map[string]models.Record, error) {
+	s := GetStore()
+	if s == nil {
+		return nil, fmt.Errorf("metric store not enabled")
+	}
+	result := make(map[string]models.Record, len(entityIDs))
+	for _, entityID := range entityIDs {
+		if entityID == "" {
+			continue
+		}
+		up, hasUp, err := latestReportCounter(ctx, s, MetricNetTotalUp, entityID, before)
+		if err != nil {
+			return nil, err
+		}
+		down, hasDown, err := latestReportCounter(ctx, s, MetricNetTotalDown, entityID, before)
+		if err != nil {
+			return nil, err
+		}
+		if !hasUp && !hasDown {
+			continue
+		}
+		result[entityID] = models.Record{
+			Client:       entityID,
+			Time:         before.UTC().Add(-time.Nanosecond),
+			NetTotalUp:   up,
+			NetTotalDown: down,
+		}
+	}
+	return result, nil
+}
+
+// maxResetAwareDelta is the largest per-sample increase accepted when a
+// counter appears to reset. A "reset" whose current value is larger than this
+// is treated as jitter of a still-huge counter, not a wrap or reboot leftover.
+const maxResetAwareDelta int64 = 64 << 30
+
+// TrafficCounterDelta returns a reset-aware increase between two cumulative
+// traffic counters. After a wrap or reboot, the current counter is the new
+// increase. A tiny dip of a TB-scale counter is not a reset: counting the
+// still-huge current value would inject a multi-terabyte spike.
+func TrafficCounterDelta(current, previous int64) int64 {
+	if current < 0 || previous < 0 {
+		return 0
+	}
+	if current >= previous {
+		return current - previous
+	}
+	if current > maxResetAwareDelta {
+		return 0
+	}
+	return current
+}
+
+func deleteReportTrafficState(entityID string) {
+	reportTrafficStates.Delete(entityID)
+}
+
+func clearReportTrafficStates() {
+	reportTrafficStates.Range(func(key, _ any) bool {
+		reportTrafficStates.Delete(key)
+		return true
+	})
+}

internal/metricstore/report_test.go

@@ -0,0 +1,840 @@
+package metricstore
+
+import (
+	"context"
+	"database/sql"
+	"database/sql/driver"
+	"errors"
+	"fmt"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/komari-monitor/komari/database/models"
+	"github.com/komari-monitor/komari/pkg/metric"
+	v2 "github.com/komari-monitor/komari/protocol/v2"
+	sqlite3 "github.com/mattn/go-sqlite3"
+)
+
+func useReportTestStore(t *testing.T, policy *metric.RollupPolicy) *metric.Store {
+	t.Helper()
+	ctx := context.Background()
+	opts := []metric.Option{metric.WithMaxOpenConns(1)}
+	if policy != nil {
+		opts = append(opts, metric.WithRollupPolicy(*policy))
+	}
+	dsn := fmt.Sprintf("file:report-%d?mode=memory&cache=shared", time.Now().UnixNano())
+	s, err := metric.Open(ctx, metric.SQLite(dsn, opts...))
+	if err != nil {
+		t.Fatalf("open metric store: %v", err)
+	}
+	if err := createMetricDefinitions(ctx, s); err != nil {
+		_ = s.Close()
+		t.Fatalf("create metric definitions: %v", err)
+	}
+
+	storeMu.Lock()
+	previous := store
+	store = s
+	storeMu.Unlock()
+	clearReportTrafficStates()
+	t.Cleanup(func() {
+		clearReportTrafficStates()
+		storeMu.Lock()
+		store = previous
+		storeMu.Unlock()
+		_ = s.Close()
+	})
+	return s
+}
+
+type reportCounterFault struct {
+	remaining atomic.Int32
+	denied    atomic.Int32
+	failWrite atomic.Bool
+}
+
+func (f *reportCounterFault) denyRollupRead() bool {
+	for {
+		remaining := f.remaining.Load()
+		if remaining <= 0 {
+			return false
+		}
+		if f.remaining.CompareAndSwap(remaining, remaining-1) {
+			f.denied.Add(1)
+			return true
+		}
+	}
+}
+
+type reportSQLiteConnector struct {
+	driver *sqlite3.SQLiteDriver
+	dsn    string
+}
+
+func (c *reportSQLiteConnector) Connect(context.Context) (driver.Conn, error) {
+	return c.driver.Open(c.dsn)
+}
+
+func (c *reportSQLiteConnector) Driver() driver.Driver {
+	return c.driver
+}
+
+// useReportCounterFailureStore denies exactly two rollup reads after schema
+// setup, exercising failed counter restoration while leaving writes usable.
+func useReportCounterFailureStore(t *testing.T) (*metric.Store, *reportCounterFault) {
+	t.Helper()
+	fault := &reportCounterFault{}
+	dsn := fmt.Sprintf("file:report-counter-fault-%d?mode=memory&cache=shared", time.Now().UnixNano())
+	driver := &sqlite3.SQLiteDriver{
+		ConnectHook: func(conn *sqlite3.SQLiteConn) error {
+			conn.RegisterAuthorizer(func(op int, arg1, _, _ string) int {
+				if op == sqlite3.SQLITE_TRANSACTION && arg1 == "BEGIN" && fault.failWrite.Load() {
+					return sqlite3.SQLITE_DENY
+				}
+				if op == sqlite3.SQLITE_READ && arg1 == "metric_rollups" && fault.denyRollupRead() {
+					return sqlite3.SQLITE_DENY
+				}
+				return sqlite3.SQLITE_OK
+			})
+			return nil
+		},
+	}
+	db := sql.OpenDB(&reportSQLiteConnector{driver: driver, dsn: dsn})
+	s, err := metric.Open(context.Background(), metric.SQLite("", metric.WithDB(db), metric.WithMaxOpenConns(1)))
+	if err != nil {
+		_ = db.Close()
+		t.Fatalf("open metric store: %v", err)
+	}
+	if err := createMetricDefinitions(context.Background(), s); err != nil {
+		_ = s.Close()
+		_ = db.Close()
+		t.Fatalf("create metric definitions: %v", err)
+	}
+	fault.remaining.Store(2)
+	storeMu.Lock()
+	previous := store
+	store = s
+	storeMu.Unlock()
+	t.Cleanup(func() {
+		clearReportTrafficStates()
+		storeMu.Lock()
+		store = previous
+		storeMu.Unlock()
+		_ = s.Close()
+		_ = db.Close()
+	})
+	return s, fault
+}
+
+func TestReportBatchCounterRestoreFailureInitializesStateOnce(t *testing.T) {
+	s, fault := useReportCounterFailureStore(t)
+	ctx := context.Background()
+	base := time.Now().UTC().Truncate(time.Second)
+	first := v2.Report{
+		UUID:      "counter-restore-failure",
+		UpdatedAt: base,
+		CPU:       v2.CPUReport{Usage: 10},
+		Network:   v2.NetworkReport{TotalUp: 100, TotalDown: 200},
+	}
+
+	if _, err := writeReportBatch(ctx, []v2.Report{first}); err != nil {
+		t.Fatalf("write first report after counter restore failure: %v", err)
+	}
+	if fault.denied.Load() != 2 {
+		t.Fatalf("counter restore queries = %d, want 2", fault.denied.Load())
+	}
+	stateValue, ok := reportTrafficStates.Load(first.UUID)
+	if !ok {
+		t.Fatal("report traffic state was not persisted")
+	}
+	state := stateValue.(*reportTrafficState)
+	state.mu.Lock()
+	initialized := state.initialized
+	state.mu.Unlock()
+	if !initialized {
+		t.Fatal("report traffic state was not initialized after restore failure")
+	}
+
+	second := first
+	second.UpdatedAt = base.Add(time.Second)
+	second.Network.TotalUp = 150
+	second.Network.TotalDown = 260
+	if _, err := writeReportBatch(ctx, []v2.Report{second}); err != nil {
+		t.Fatalf("write second report: %v", err)
+	}
+	if fault.denied.Load() != 2 {
+		t.Fatalf("counter restore queries after second batch = %d, want no repeat", fault.denied.Load())
+	}
+	assertMetricValues(t, s, MetricTrafficUp, first.UUID, base.Add(-time.Second), base.Add(2*time.Second), []float64{0, 50})
+	assertMetricValues(t, s, MetricTrafficDown, first.UUID, base.Add(-time.Second), base.Add(2*time.Second), []float64{0, 60})
+}
+
+func TestReportBatchRetryDoesNotCountHistoricalTraffic(t *testing.T) {
+	for _, existingBaseline := range []bool{false, true} {
+		t.Run(fmt.Sprintf("existing-baseline-%v", existingBaseline), func(t *testing.T) {
+			s, fault := useReportCounterFailureStore(t)
+			fault.remaining.Store(0)
+			ctx := context.Background()
+			base := time.Now().UTC().Truncate(time.Minute).Add(-2 * time.Minute)
+			report := v2.Report{
+				UUID: "retry-node", UpdatedAt: base,
+				Network: v2.NetworkReport{TotalUp: 12 << 30, TotalDown: 30 << 30},
+			}
+			if existingBaseline {
+				if _, err := writeReportBatch(ctx, []v2.Report{report}); err != nil {
+					t.Fatal(err)
+				}
+			}
+			first := report
+			first.UpdatedAt = base.Add(3 * time.Second)
+			first.Network.TotalUp += 100
+			first.Network.TotalDown += 200
+			second := first
+			second.UpdatedAt = base.Add(6 * time.Second)
+			second.Network.TotalUp += 50
+			second.Network.TotalDown += 60
+			pending := []v2.Report{first, second}
+
+			fault.failWrite.Store(true)
+			for attempt := 0; attempt < 2; attempt++ {
+				if err := writePendingReports(ctx, &pending); err == nil {
+					t.Fatal("expected injected rollup write failure")
+				}
+				if len(pending) != 2 {
+					t.Fatal("failed reports were removed from pending batch")
+				}
+				value, _ := reportTrafficStates.Load(report.UUID)
+				state := value.(*reportTrafficState)
+				state.mu.Lock()
+				baseline := state.reportTrafficValues
+				state.mu.Unlock()
+				if baseline.hasUp != existingBaseline || baseline.hasDown != existingBaseline ||
+					(existingBaseline && (baseline.totalUp != report.Network.TotalUp ||
+						baseline.totalDown != report.Network.TotalDown || !baseline.timestamp.Equal(base))) {
+					t.Fatal("failed write advanced the committed counter baseline")
+				}
+			}
+			fault.failWrite.Store(false)
+			if err := writePendingReports(ctx, &pending); err != nil {
+				t.Fatalf("retry failed: %v", err)
+			}
+			if len(pending) != 0 {
+				t.Fatal("successful reports remained pending")
+			}
+
+			wantUp, wantDown := []float64{0, 50}, []float64{0, 60}
+			if existingBaseline {
+				wantUp, wantDown = []float64{0, 100, 50}, []float64{0, 200, 60}
+			}
+			assertMetricValues(t, s, MetricTrafficUp, report.UUID, base.Add(-time.Second), base.Add(time.Minute), wantUp)
+			assertMetricValues(t, s, MetricTrafficDown, report.UUID, base.Add(-time.Second), base.Add(time.Minute), wantDown)
+			var sumUp, sumDown float64
+			for i := range wantUp {
+				sumUp += wantUp[i]
+				sumDown += wantDown[i]
+			}
+			assertMetricAggregate(t, s, MetricTrafficUp, report.UUID, base.Add(-time.Second), base.Add(time.Minute), metric.AggSum, sumUp, len(wantUp))
+			assertMetricAggregate(t, s, MetricTrafficDown, report.UUID, base.Add(-time.Second), base.Add(time.Minute), metric.AggSum, sumDown, len(wantDown))
+		})
+	}
+}
+
+func TestWriteReportStoresMinuteMetricsAndResetAwareTraffic(t *testing.T) {
+	ctx := context.Background()
+	policy := defaultRollupPolicy()
+	s := useReportTestStore(t, &policy)
+	base := time.Now().UTC().Truncate(time.Minute).Add(5 * time.Second)
+	now := base.Add(45 * time.Second)
+
+	report := v2.Report{
+		UUID:        "node-a",
+		UpdatedAt:   base,
+		CPU:         v2.CPUReport{Usage: 12.5},
+		Ram:         v2.RamReport{Used: 100, Total: 1000},
+		Swap:        v2.RamReport{Used: 20, Total: 200},
+		Load:        v2.LoadReport{Load1: 0.5},
+		Disk:        v2.DiskReport{Used: 300, Total: 3000},
+		Network:     v2.NetworkReport{Up: 3, Down: 4, TotalUp: 100, TotalDown: 200},
+		Process:     7,
+		Connections: v2.ConnectionsReport{TCP: 8, UDP: 9},
+		GPU: &v2.GPUDetailReport{
+			AverageUsage: 25,
+			DetailedInfo: []v2.GPUDeviceInfo{{
+				Name: "GPU 0", MemoryUsed: 400, MemoryTotal: 800, Utilization: 30, Temperature: 55,
+			}},
+		},
+	}
+	if _, err := WriteReport(ctx, report); err != nil {
+		t.Fatalf("write first report: %v", err)
+	}
+
+	report.UpdatedAt = base.Add(3 * time.Second)
+	report.Network.TotalUp = 150
+	report.Network.TotalDown = 260
+	if _, err := WriteReport(ctx, report); err != nil {
+		t.Fatalf("write second report: %v", err)
+	}
+
+	report.UpdatedAt = base.Add(6 * time.Second)
+	report.Network.TotalUp = 20
+	report.Network.TotalDown = 30
+	if _, err := WriteReport(ctx, report); err != nil {
+		t.Fatalf("write reset report: %v", err)
+	}
+
+	assertMetricValues(t, s, MetricTrafficUp, report.UUID, base.Add(-time.Second), base.Add(time.Minute), []float64{0, 50, 20})
+	assertMetricValues(t, s, MetricTrafficDown, report.UUID, base.Add(-time.Second), base.Add(time.Minute), []float64{0, 60, 30})
+	assertMetricValues(t, s, MetricNetTotalUp, report.UUID, base.Add(-time.Second), base.Add(time.Minute), []float64{100, 150, 20})
+	assertMetricAggregate(t, s, MetricTrafficUp, report.UUID, base.Add(-time.Second), base.Add(time.Minute), metric.AggSum, 70, 3)
+	assertMetricAggregate(t, s, MetricTrafficDown, report.UUID, base.Add(-time.Second), base.Add(time.Minute), metric.AggSum, 90, 3)
+
+	gpuPoints, err := s.Query(ctx, metric.Query{
+		MetricName: MetricGPUDeviceUsage,
+		EntityID:   report.UUID,
+		Start:      base.Add(-time.Second),
+		End:        base.Add(time.Minute),
+		Tags:       map[string]string{"device_index": "0"},
+		Order:      metric.OrderAsc,
+	})
+	if err != nil {
+		t.Fatalf("query GPU points: %v", err)
+	}
+	if len(gpuPoints) != 3 || !gpuPoints[2].Timestamp.Equal(base.Add(6*time.Second)) || gpuPoints[2].Tags["device_name"] != "GPU 0" {
+		t.Fatalf("unexpected GPU points: %#v", gpuPoints)
+	}
+
+	if _, err := s.Compact(ctx, now); err != nil {
+		t.Fatalf("compact reports: %v", err)
+	}
+	deleteReportTrafficState(report.UUID)
+	report.UpdatedAt = now
+	report.Network.TotalUp = 35
+	report.Network.TotalDown = 50
+	if _, err := WriteReport(ctx, report); err != nil {
+		t.Fatalf("write after restoring rollup baseline: %v", err)
+	}
+	assertMetricValues(t, s, MetricTrafficUp, report.UUID, now.Add(-time.Second), now.Add(time.Second), []float64{15})
+	assertMetricValues(t, s, MetricTrafficDown, report.UUID, now.Add(-time.Second), now.Add(time.Second), []float64{20})
+}
+
+func TestWriteReportSkipsMetricsWithoutAgentData(t *testing.T) {
+	ctx := context.Background()
+	s := useReportTestStore(t, nil)
+	timestamp := time.Now().UTC()
+	if _, err := WriteReport(ctx, v2.Report{
+		UUID: "node-without-gpu", UpdatedAt: timestamp,
+	}); err != nil {
+		t.Fatalf("write report: %v", err)
+	}
+	points, err := s.Query(ctx, metric.Query{
+		MetricName: MetricGPU, EntityID: "node-without-gpu",
+		Start: timestamp.Add(-time.Second), End: timestamp.Add(time.Second),
+	})
+	if err != nil {
+		t.Fatalf("query GPU metric: %v", err)
+	}
+	if len(points) != 0 {
+		t.Fatalf("GPU metric was written without GPU data: %#v", points)
+	}
+}
+
+func TestReportBatcherFlushesQueuedReports(t *testing.T) {
+	ctx := context.Background()
+	s := useReportTestStore(t, nil)
+	StartReportBatcher()
+	t.Cleanup(func() {
+		if err := StopReportBatcher(ctx); err != nil {
+			t.Errorf("stop report batcher: %v", err)
+		}
+	})
+
+	base := time.Now().UTC().Truncate(time.Minute).Add(10 * time.Second)
+	first := v2.Report{
+		UUID:      "batched-node",
+		UpdatedAt: base,
+		CPU:       v2.CPUReport{Usage: 10},
+		Network:   v2.NetworkReport{TotalUp: 100, TotalDown: 200},
+	}
+	second := first
+	second.UpdatedAt = base.Add(3 * time.Second)
+	second.CPU.Usage = 20
+	second.Network.TotalUp = 150
+	second.Network.TotalDown = 260
+
+	if _, err := WriteReport(ctx, first); err != nil {
+		t.Fatalf("queue first report: %v", err)
+	}
+	if _, err := WriteReport(ctx, second); err != nil {
+		t.Fatalf("queue second report: %v", err)
+	}
+	points, err := s.Query(ctx, metric.Query{
+		MetricName: MetricCPU,
+		EntityID:   first.UUID,
+		Start:      base.Add(-time.Second),
+		End:        base.Add(time.Minute),
+		Order:      metric.OrderAsc,
+	})
+	if err != nil {
+		t.Fatalf("query before flush: %v", err)
+	}
+	if len(points) != 0 {
+		t.Fatalf("queued reports were written before flush: %#v", points)
+	}
+
+	if err := FlushReportBatch(ctx); err != nil {
+		t.Fatalf("flush report batch: %v", err)
+	}
+	assertMetricValues(t, s, MetricCPU, first.UUID, base.Add(-time.Second), base.Add(time.Minute), []float64{10, 20})
+	assertMetricValues(t, s, MetricTrafficUp, first.UUID, base.Add(-time.Second), base.Add(time.Minute), []float64{0, 50})
+	assertMetricValues(t, s, MetricTrafficDown, first.UUID, base.Add(-time.Second), base.Add(time.Minute), []float64{0, 60})
+	assertMetricAggregate(t, s, MetricCPU, first.UUID, base.Add(-time.Second), base.Add(time.Minute), metric.AggAvg, 15, 2)
+}
+
+func TestPingBatcherFlushesLatencyAndLossTogether(t *testing.T) {
+	ctx := context.Background()
+	s := useReportTestStore(t, nil)
+	StartReportBatcher()
+	t.Cleanup(func() {
+		if err := StopReportBatcher(ctx); err != nil {
+			t.Errorf("stop report batcher: %v", err)
+		}
+	})
+
+	base := time.Now().UTC().Truncate(time.Second)
+	records := []models.PingRecord{
+		{Client: "ping-node", TaskId: 7, Time: base, Value: 24},
+		{Client: "ping-node", TaskId: 7, Time: base.Add(time.Minute), Value: -1},
+		{Client: "ping-node", TaskId: 8, Time: base, Value: 31},
+	}
+	for _, record := range records {
+		if err := WritePingRecord(ctx, record); err != nil {
+			t.Fatalf("queue ping record: %v", err)
+		}
+	}
+
+	for _, name := range []string{MetricPingLatency, MetricPingLoss} {
+		points, err := s.Query(ctx, metric.Query{
+			MetricName: name,
+			EntityID:   "ping-node",
+			Start:      base.Add(-time.Second),
+			End:        base.Add(2 * time.Minute),
+		})
+		if err != nil {
+			t.Fatalf("query queued %s points: %v", name, err)
+		}
+		if len(points) != 0 {
+			t.Fatalf("queued %s points were written before flush: %#v", name, points)
+		}
+	}
+
+	if err := FlushReportBatch(ctx); err != nil {
+		t.Fatalf("flush ping batch: %v", err)
+	}
+
+	latency, err := s.Query(ctx, metric.Query{
+		MetricName: MetricPingLatency,
+		EntityID:   "ping-node",
+		Tags:       map[string]string{"task_id": "7"},
+		Start:      base.Add(-time.Second),
+		End:        base.Add(2 * time.Minute),
+		Order:      metric.OrderAsc,
+	})
+	if err != nil {
+		t.Fatalf("query flushed latency points: %v", err)
+	}
+	if len(latency) != 2 || latency[0].Value != 24 || latency[1].Value != -1 {
+		t.Fatalf("latency points = %#v, want both original samples", latency)
+	}
+
+	loss, err := s.Query(ctx, metric.Query{
+		MetricName: MetricPingLoss,
+		EntityID:   "ping-node",
+		Tags:       map[string]string{"task_id": "7"},
+		Start:      base.Add(-time.Second),
+		End:        base.Add(2 * time.Minute),
+		Order:      metric.OrderAsc,
+	})
+	if err != nil {
+		t.Fatalf("query flushed loss points: %v", err)
+	}
+	if len(loss) != 2 || loss[0].Value != 0 || loss[1].Value != 1 {
+		t.Fatalf("loss points = %#v, want success and loss samples", loss)
+	}
+}
+
+func TestReportBatchKeepsEverySample(t *testing.T) {
+	ctx := context.Background()
+	s := useReportTestStore(t, nil)
+	base := time.Now().UTC().Truncate(time.Second)
+	pending := []v2.Report{
+		{UUID: "node-a", UpdatedAt: base, CPU: v2.CPUReport{Usage: 10}, Network: v2.NetworkReport{TotalUp: 100}},
+		{UUID: "node-a", UpdatedAt: base, CPU: v2.CPUReport{Usage: 20}, Network: v2.NetworkReport{TotalUp: 150}},
+		{UUID: "node-b", UpdatedAt: base, CPU: v2.CPUReport{Usage: 30}, Network: v2.NetworkReport{TotalUp: 200}},
+		{UUID: "node-b", UpdatedAt: base.Add(time.Second), CPU: v2.CPUReport{Usage: 40}, Network: v2.NetworkReport{TotalUp: 260}},
+	}
+
+	if err := writePendingReports(ctx, &pending); err != nil {
+		t.Fatalf("write report batch: %v", err)
+	}
+	if len(pending) != 0 {
+		t.Fatalf("pending reports = %d, want 0", len(pending))
+	}
+	assertMetricValues(t, s, MetricCPU, "node-a", base.Add(-time.Second), base.Add(time.Minute), []float64{10, 20})
+	assertMetricValues(t, s, MetricCPU, "node-b", base.Add(-time.Second), base.Add(time.Minute), []float64{30, 40})
+}
+
+func TestReportQueueFullReturnsError(t *testing.T) {
+	ctx := context.Background()
+	useReportTestStore(t, nil)
+	worker := &reportBatchWorker{
+		queue:    make(chan v2.Report, 1),
+		requests: make(chan reportBatchRequest, 1),
+		done:     make(chan struct{}),
+	}
+	worker.queue <- v2.Report{UUID: "already-queued"}
+	reportBatcherMu.Lock()
+	reportBatcher = worker
+	reportBatcherMu.Unlock()
+	t.Cleanup(func() {
+		reportBatcherMu.Lock()
+		if reportBatcher == worker {
+			reportBatcher = nil
+		}
+		reportBatcherMu.Unlock()
+	})
+
+	report := v2.Report{
+		UUID:      "realtime-node",
+		UpdatedAt: time.Now().UTC(),
+	}
+	_, err := WriteReport(ctx, report)
+	if !errors.Is(err, ErrReportBatchQueueFull) {
+		t.Fatalf("queue-full error = %v, want %v", err, ErrReportBatchQueueFull)
+	}
+}
+
+func TestRecordReconstructionUsesMetricSpecificAggregation(t *testing.T) {
+	ctx := context.Background()
+	s := useReportTestStore(t, nil)
+	base := time.Now().UTC().Truncate(time.Minute)
+	entityID := "node-aggregation"
+	points := []metric.Point{
+		{MetricName: MetricCPU, EntityID: entityID, Timestamp: base.Add(time.Second), Value: 10},
+		{MetricName: MetricCPU, EntityID: entityID, Timestamp: base.Add(2 * time.Second), Value: 30},
+		{MetricName: MetricNetTotalUp, EntityID: entityID, Timestamp: base.Add(time.Second), Value: 100},
+		{MetricName: MetricNetTotalUp, EntityID: entityID, Timestamp: base.Add(2 * time.Second), Value: 200},
+		{MetricName: MetricTrafficUp, EntityID: entityID, Timestamp: base.Add(time.Second), Value: 10},
+		{MetricName: MetricTrafficUp, EntityID: entityID, Timestamp: base.Add(2 * time.Second), Value: 20},
+	}
+	if err := s.WriteBatch(ctx, points); err != nil {
+		t.Fatalf("write points: %v", err)
+	}
+
+	records, err := GetRecordsByClientAndTime(ctx, entityID, base, base.Add(time.Hour))
+	if err != nil {
+		t.Fatalf("reconstruct records: %v", err)
+	}
+	if len(records) != 1 {
+		t.Fatalf("records = %#v, want one bucket", records)
+	}
+	if records[0].Cpu != 20 || records[0].NetTotalUp != 200 || records[0].TrafficUp != 30 {
+		t.Fatalf("unexpected aggregation result: %#v", records[0])
+	}
+}
+
+func TestTrafficCounterDelta(t *testing.T) {
+	const (
+		oneGB = int64(1_000_000_000)
+		oneTB = int64(1_000_000_000_000)
+	)
+	tests := []struct {
+		name     string
+		current  int64
+		previous int64
+		want     int64
+	}{
+		{name: "previous zero", current: 120, previous: 0, want: 120},
+		{name: "monotonic counter", current: 250, previous: 200, want: 50},
+		{name: "unchanged counter", current: 100, previous: 100, want: 0},
+		{name: "counter reset", current: 15, previous: 250, want: 15},
+		{name: "negative current", current: -1, previous: 100, want: 0},
+		{name: "negative previous", current: 15, previous: -1, want: 0},
+		{name: "tb-scale monotonic", current: 2*oneTB + 5*oneGB, previous: 2 * oneTB, want: 5 * oneGB},
+		{name: "32-bit wrap leftover", current: 800_000_000, previous: 3*oneGB + 900_000_000, want: 800_000_000},
+		{name: "reboot leftover below cap", current: 8 * oneGB, previous: 2 * oneTB, want: 8 * oneGB},
+		{name: "tb-scale tiny dip", current: 2*oneTB - 100, previous: 2 * oneTB, want: 0},
+		{name: "tb-scale false reset", current: 2*oneTB + 5*oneGB - 1000, previous: 2*oneTB + 5*oneGB, want: 0},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if got := TrafficCounterDelta(test.current, test.previous); got != test.want {
+				t.Fatalf("TrafficCounterDelta(%d, %d) = %d, want %d", test.current, test.previous, got, test.want)
+			}
+		})
+	}
+}
+
+func TestWriteReportRebasesTrafficAfterAgentRestart(t *testing.T) {
+	ctx := context.Background()
+	s := useReportTestStore(t, nil)
+	base := time.Now().UTC().Truncate(time.Minute).Add(5 * time.Second)
+	report := v2.Report{
+		UUID:      "restarted-node",
+		UpdatedAt: base,
+		Uptime:    1000,
+		Network:   v2.NetworkReport{TotalUp: 100, TotalDown: 200},
+	}
+	if _, err := WriteReport(ctx, report); err != nil {
+		t.Fatalf("write first report: %v", err)
+	}
+
+	report.UpdatedAt = base.Add(3 * time.Second)
+	report.Uptime = 1003
+	report.Network.TotalUp = 150
+	report.Network.TotalDown = 260
+	if _, err := WriteReport(ctx, report); err != nil {
+		t.Fatalf("write continuous report: %v", err)
+	}
+
+	report.UpdatedAt = base.Add(6 * time.Second)
+	report.Uptime = 1
+	report.Network.TotalUp = 155
+	report.Network.TotalDown = 265
+	if _, err := WriteReport(ctx, report); err != nil {
+		t.Fatalf("write report after agent restart: %v", err)
+	}
+
+	report.UpdatedAt = base.Add(9 * time.Second)
+	report.Uptime = 4
+	report.Network.TotalUp = 180
+	report.Network.TotalDown = 300
+	if _, err := WriteReport(ctx, report); err != nil {
+		t.Fatalf("write report after new baseline: %v", err)
+	}
+
+	assertMetricValues(t, s, MetricTrafficUp, report.UUID, base.Add(-time.Second), base.Add(time.Minute), []float64{0, 50, 5, 25})
+	assertMetricValues(t, s, MetricTrafficDown, report.UUID, base.Add(-time.Second), base.Add(time.Minute), []float64{0, 60, 5, 35})
+}
+
+func TestWriteReportCountsTBScaleTrafficDeltas(t *testing.T) {
+	const (
+		oneGB = int64(1_000_000_000)
+		oneTB = int64(1_000_000_000_000)
+	)
+	ctx := context.Background()
+	s := useReportTestStore(t, nil)
+	base := time.Now().UTC().Truncate(time.Minute).Add(5 * time.Second)
+	report := v2.Report{
+		UUID:      "tb-node",
+		UpdatedAt: base,
+		Uptime:    10_000,
+		Network:   v2.NetworkReport{TotalUp: 2 * oneTB, TotalDown: 3 * oneTB},
+	}
+	if _, err := WriteReport(ctx, report); err != nil {
+		t.Fatalf("write first report: %v", err)
+	}
+
+	report.UpdatedAt = base.Add(3 * time.Second)
+	report.Uptime = 10_003
+	report.Network.TotalUp = 2*oneTB + 5*oneGB
+	report.Network.TotalDown = 3*oneTB + 7*oneGB
+	if _, err := WriteReport(ctx, report); err != nil {
+		t.Fatalf("write growing report: %v", err)
+	}
+
+	assertMetricValues(t, s, MetricTrafficUp, report.UUID, base.Add(-time.Second), base.Add(time.Minute), []float64{0, float64(5 * oneGB)})
+	assertMetricValues(t, s, MetricTrafficDown, report.UUID, base.Add(-time.Second), base.Add(time.Minute), []float64{0, float64(7 * oneGB)})
+}
+
+func TestWriteReportRestoresTBScaleCountersFromStore(t *testing.T) {
+	const (
+		oneGB = int64(1_000_000_000)
+		oneTB = int64(1_000_000_000_000)
+	)
+	ctx := context.Background()
+	policy := defaultRollupPolicy()
+	s := useReportTestStore(t, &policy)
+	base := time.Now().UTC().Truncate(time.Minute).Add(5 * time.Second)
+	now := base.Add(45 * time.Second)
+	report := v2.Report{
+		UUID:      "tb-restore-node",
+		UpdatedAt: base,
+		Uptime:    10_000,
+		Network:   v2.NetworkReport{TotalUp: 2*oneTB + 123, TotalDown: 4*oneTB + 456},
+	}
+	if _, err := WriteReport(ctx, report); err != nil {
+		t.Fatalf("write first report: %v", err)
+	}
+
+	restoredUp, hasUp, err := latestReportCounter(ctx, s, MetricNetTotalUp, report.UUID, now)
+	if err != nil {
+		t.Fatalf("restore upload counter: %v", err)
+	}
+	if !hasUp || restoredUp != report.Network.TotalUp {
+		t.Fatalf("restored upload counter = %d (has=%v), want %d", restoredUp, hasUp, report.Network.TotalUp)
+	}
+	restoredDown, hasDown, err := latestReportCounter(ctx, s, MetricNetTotalDown, report.UUID, now)
+	if err != nil {
+		t.Fatalf("restore download counter: %v", err)
+	}
+	if !hasDown || restoredDown != report.Network.TotalDown {
+		t.Fatalf("restored download counter = %d (has=%v), want %d", restoredDown, hasDown, report.Network.TotalDown)
+	}
+
+	if _, err := s.Compact(ctx, now); err != nil {
+		t.Fatalf("compact reports: %v", err)
+	}
+	deleteReportTrafficState(report.UUID)
+	report.UpdatedAt = now
+	report.Uptime = 10_045
+	report.Network.TotalUp = 2*oneTB + 123 + 5*oneGB
+	report.Network.TotalDown = 4*oneTB + 456 + 7*oneGB
+	if _, err := WriteReport(ctx, report); err != nil {
+		t.Fatalf("write after restoring tb-scale baseline: %v", err)
+	}
+	assertMetricValues(t, s, MetricTrafficUp, report.UUID, now.Add(-time.Second), now.Add(time.Second), []float64{float64(5 * oneGB)})
+	assertMetricValues(t, s, MetricTrafficDown, report.UUID, now.Add(-time.Second), now.Add(time.Second), []float64{float64(7 * oneGB)})
+}
+
+func TestWriteReportCountsTrafficAfterHighRateCounterWrap(t *testing.T) {
+	const oneGB = int64(1_000_000_000)
+	ctx := context.Background()
+	s := useReportTestStore(t, nil)
+	base := time.Now().UTC().Truncate(time.Minute).Add(5 * time.Second)
+	report := v2.Report{
+		UUID:      "wrap-node",
+		UpdatedAt: base,
+		Uptime:    10_000,
+		Network:   v2.NetworkReport{TotalUp: 3*oneGB + 900_000_000, TotalDown: 3*oneGB + 800_000_000},
+	}
+	if _, err := WriteReport(ctx, report); err != nil {
+		t.Fatalf("write first report: %v", err)
+	}
+
+	report.UpdatedAt = base.Add(3 * time.Second)
+	report.Uptime = 10_003
+	report.Network.TotalUp = 800_000_000
+	report.Network.TotalDown = 900_000_000
+	if _, err := WriteReport(ctx, report); err != nil {
+		t.Fatalf("write wrapped report: %v", err)
+	}
+
+	assertMetricValues(t, s, MetricTrafficUp, report.UUID, base.Add(-time.Second), base.Add(time.Minute), []float64{0, 800_000_000})
+	assertMetricValues(t, s, MetricTrafficDown, report.UUID, base.Add(-time.Second), base.Add(time.Minute), []float64{0, 900_000_000})
+}
+
+func TestWriteReportIgnoresTinyDipOfTBScaleCounter(t *testing.T) {
+	const (
+		oneGB = int64(1_000_000_000)
+		oneTB = int64(1_000_000_000_000)
+	)
+	ctx := context.Background()
+	s := useReportTestStore(t, nil)
+	base := time.Now().UTC().Truncate(time.Minute).Add(5 * time.Second)
+	report := v2.Report{
+		UUID:      "tb-jitter-node",
+		UpdatedAt: base,
+		Uptime:    10_000,
+		Network:   v2.NetworkReport{TotalUp: 2 * oneTB, TotalDown: 3 * oneTB},
+	}
+	if _, err := WriteReport(ctx, report); err != nil {
+		t.Fatalf("write first report: %v", err)
+	}
+
+	report.UpdatedAt = base.Add(3 * time.Second)
+	report.Uptime = 10_003
+	report.Network.TotalUp = 2*oneTB + 5*oneGB
+	report.Network.TotalDown = 3*oneTB + 7*oneGB
+	if _, err := WriteReport(ctx, report); err != nil {
+		t.Fatalf("write growing report: %v", err)
+	}
+
+	report.UpdatedAt = base.Add(6 * time.Second)
+	report.Uptime = 10_006
+	report.Network.TotalUp = 2*oneTB + 5*oneGB - 1000
+	report.Network.TotalDown = 3*oneTB + 7*oneGB - 2000
+	if _, err := WriteReport(ctx, report); err != nil {
+		t.Fatalf("write jitter report: %v", err)
+	}
+
+	report.UpdatedAt = base.Add(9 * time.Second)
+	report.Uptime = 10_009
+	report.Network.TotalUp = 2*oneTB + 6*oneGB
+	report.Network.TotalDown = 3*oneTB + 8*oneGB
+	if _, err := WriteReport(ctx, report); err != nil {
+		t.Fatalf("write recovered report: %v", err)
+	}
+
+	assertMetricValues(t, s, MetricTrafficUp, report.UUID, base.Add(-time.Second), base.Add(time.Minute), []float64{0, float64(5 * oneGB), 0, float64(oneGB + 1000)})
+	assertMetricValues(t, s, MetricTrafficDown, report.UUID, base.Add(-time.Second), base.Add(time.Minute), []float64{0, float64(7 * oneGB), 0, float64(oneGB + 2000)})
+}
+
+func TestWriteReportNormalizesReceiveTimeToUTC(t *testing.T) {
+	ctx := context.Background()
+	s := useReportTestStore(t, nil)
+	local := time.FixedZone("UTC+8", 8*60*60)
+	receiveTime := time.Now().In(local).Add(-10 * time.Second)
+	report := v2.Report{
+		UUID:      "utc-report",
+		UpdatedAt: receiveTime,
+		CPU:       v2.CPUReport{Usage: 10},
+		Network:   v2.NetworkReport{TotalUp: 1, TotalDown: 2},
+	}
+
+	saved, err := WriteReport(ctx, report)
+	if err != nil {
+		t.Fatalf("write report: %v", err)
+	}
+	if !saved.UpdatedAt.Equal(receiveTime) || saved.UpdatedAt.Location() != time.UTC {
+		t.Fatalf("saved receive time = %s (%s), want UTC", saved.UpdatedAt, saved.UpdatedAt.Location())
+	}
+	points, err := s.Query(ctx, metric.Query{
+		MetricName: MetricCPU,
+		EntityID:   report.UUID,
+		Start:      receiveTime.Add(-time.Nanosecond),
+		End:        receiveTime.Add(time.Nanosecond),
+	})
+	if err != nil {
+		t.Fatalf("query stored point: %v", err)
+	}
+	if len(points) != 1 || points[0].Timestamp.Location() != time.UTC || points[0].Timestamp.UnixMilli() != receiveTime.UnixMilli() {
+		t.Fatalf("stored points = %#v, want one UTC millisecond point", points)
+	}
+}
+
+func assertMetricValues(t *testing.T, s *metric.Store, metricName, entityID string, start, end time.Time, want []float64) {
+	t.Helper()
+	points, err := s.Query(context.Background(), metric.Query{
+		MetricName: metricName,
+		EntityID:   entityID,
+		Start:      start,
+		End:        end,
+		Order:      metric.OrderAsc,
+	})
+	if err != nil {
+		t.Fatalf("query %s: %v", metricName, err)
+	}
+	if len(points) != len(want) {
+		t.Fatalf("%s point count = %d, want %d: %#v", metricName, len(points), len(want), points)
+	}
+	for i := range want {
+		if points[i].Value != want[i] {
+			t.Fatalf("%s point %d = %v, want %v", metricName, i, points[i].Value, want[i])
+		}
+	}
+}
+
+func assertMetricAggregate(t *testing.T, s *metric.Store, metricName, entityID string, start, end time.Time, aggregation metric.Aggregation, want float64, wantCount int) {
+	t.Helper()
+	points, err := s.Series(context.Background(), metric.AggregateQuery{
+		Query:       metric.Query{MetricName: metricName, EntityID: entityID, Start: start, End: end},
+		Aggregation: aggregation, Interval: time.Minute, PreserveSeries: true,
+	}, end)
+	if err != nil {
+		t.Fatalf("aggregate %s: %v", metricName, err)
+	}
+	if len(points) != 1 || points[0].Value != want || points[0].Count != wantCount {
+		t.Fatalf("aggregate %s = %#v, want value=%v count=%d", metricName, points, want, wantCount)
+	}
+}

internal/metricstore/restructure.go

@@ -0,0 +1,105 @@
+package metricstore
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/komari-monitor/komari/internal/config"
+	"github.com/komari-monitor/komari/pkg/metric"
+)
+
+// RestructureProgress is the authenticated guide's stable progress payload.
+type RestructureProgress struct {
+	Phase         string
+	CurrentMetric string
+	RowsDone      int64
+	RowsTotal     int64
+	MetricsDone   int
+	MetricsTotal  int
+}
+
+type RestructureResult struct {
+	BeforeBytes int64
+	AfterBytes  int64
+	RowsCopied  int64
+	Metrics     int
+}
+
+// StructureUpgradeRequired checks the configured metric store without creating
+// tables. It is called before normal metric-store initialization so an existing
+// installation is never rebuilt at startup without an administrator action.
+func StructureUpgradeRequired(ctx context.Context) (bool, error) {
+	cfg, err := config.GetManyAs[MetricStoreConfig]()
+	if err != nil {
+		return false, err
+	}
+	return structureUpgradeRequiredForConfig(ctx, cfg)
+}
+
+func structureUpgradeRequiredForConfig(ctx context.Context, cfg *MetricStoreConfig) (bool, error) {
+	s, err := openWithoutMigration(ctx, cfg)
+	if err != nil {
+		return false, err
+	}
+	defer s.Close()
+	return s.NeedsRestructure(ctx)
+}
+
+// openWithoutMigration opens cfg without creating or altering any table.
+func openWithoutMigration(ctx context.Context, cfg *MetricStoreConfig) (*metric.Store, error) {
+	metricCfg, err := buildMetricConfig(cfg, false)
+	if err != nil {
+		return nil, err
+	}
+	return metric.Open(ctx, metricCfg)
+}
+
+// RestructureConfiguredStore performs the explicit data copy, table swap and
+// one physical reclaim pass used by the upgrade guide.
+func RestructureConfiguredStore(ctx context.Context, report func(RestructureProgress)) (RestructureResult, error) {
+	return rebuildConfiguredStore(ctx, report, (*metric.Store).Restructure)
+}
+
+// DiscardConfiguredStoreHistory completes the same schema upgrade as
+// RestructureConfiguredStore but drops every historical sample instead of
+// copying it. Metric definitions remain available for new ingest.
+func DiscardConfiguredStoreHistory(ctx context.Context, report func(RestructureProgress)) (RestructureResult, error) {
+	return rebuildConfiguredStore(ctx, report, (*metric.Store).DiscardHistory)
+}
+
+type storeRebuild func(*metric.Store, context.Context, func(metric.RestructureProgress)) (metric.RestructureResult, error)
+
+func rebuildConfiguredStore(ctx context.Context, report func(RestructureProgress), rebuild storeRebuild) (RestructureResult, error) {
+	if report == nil {
+		report = func(RestructureProgress) {}
+	}
+	cfg, err := config.GetManyAs[MetricStoreConfig]()
+	if err != nil {
+		return RestructureResult{}, err
+	}
+	s, err := openWithoutMigration(ctx, cfg)
+	if err != nil {
+		return RestructureResult{}, err
+	}
+	defer s.Close()
+
+	before, err := s.LegacyStorageSize(ctx)
+	if err != nil {
+		return RestructureResult{}, fmt.Errorf("measure legacy metric storage: %w", err)
+	}
+	result, err := rebuild(s, ctx, func(progress metric.RestructureProgress) {
+		report(RestructureProgress{Phase: progress.Phase, CurrentMetric: progress.Current, RowsDone: progress.RowsDone, RowsTotal: progress.RowsTotal, MetricsDone: progress.MetricsDone, MetricsTotal: progress.MetricsTotal})
+	})
+	if err != nil {
+		return RestructureResult{}, err
+	}
+	report(RestructureProgress{Phase: "reclaiming", RowsDone: result.RowsCopied, RowsTotal: result.RowsCopied, MetricsDone: result.Metrics, MetricsTotal: result.Metrics})
+	if err := s.ReclaimSpace(ctx); err != nil {
+		return RestructureResult{}, fmt.Errorf("reclaim metric storage: %w", err)
+	}
+	after, err := s.StorageSize(ctx)
+	if err != nil {
+		return RestructureResult{}, fmt.Errorf("measure rebuilt metric storage: %w", err)
+	}
+	return RestructureResult{BeforeBytes: before, AfterBytes: after, RowsCopied: result.RowsCopied, Metrics: result.Metrics}, nil
+}

internal/metricstore/store.go

@@ -0,0 +1,257 @@
+package metricstore
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+
+	logger "github.com/komari-monitor/komari/utils/log"
+
+	"github.com/komari-monitor/komari/internal/config"
+	"github.com/komari-monitor/komari/pkg/metric"
+)
+
+var (
+	store             *metric.Store
+	storeFingerprint  string
+	storeMu           sync.RWMutex
+	storeInitMu       sync.Mutex
+	storeOperations   = newStoreOperationGate()
+	compactOperations = newStoreOperationGate()
+)
+
+var ErrCompactInProgress = errors.New("metric store compact already in progress")
+
+// ErrStructureUpgradeRequired reports that the configured store must be
+// migrated by the restricted startup guide before it can be opened normally.
+var ErrStructureUpgradeRequired = errors.New("metric store structure upgrade is required")
+
+// openStore 按配置打开 metric store 并创建指标定义。
+func openStore(ctx context.Context, cfg *MetricStoreConfig) (*metric.Store, error) {
+	return openStoreWithDefaultRetention(ctx, cfg, defaultBuiltinMetricRetentionDays)
+}
+
+func openStoreWithDefaultRetention(ctx context.Context, cfg *MetricStoreConfig, defaultRetentionDays int) (*metric.Store, error) {
+	metricCfg, err := buildMetricConfig(cfg, true)
+	if err != nil {
+		return nil, err
+	}
+
+	s, err := metric.Open(ctx, metricCfg)
+	if err != nil {
+		return nil, fmt.Errorf("failed to open metric store: %w", err)
+	}
+
+	if err := createMetricDefinitionsWithDefaultRetention(ctx, s, defaultRetentionDays); err != nil {
+		s.Close()
+		return nil, fmt.Errorf("failed to create metric definitions: %w", err)
+	}
+
+	return s, nil
+}
+
+// OpenStoreForMigration opens an isolated target and uses the legacy data span
+// as the initial retention for definitions that do not exist yet. Existing
+// definitions keep their configured retention, including an explicit zero.
+func OpenStoreForMigration(ctx context.Context, cfg *MetricStoreConfig, legacyRetentionDays int) (*metric.Store, error) {
+	if legacyRetentionDays < defaultBuiltinMetricRetentionDays {
+		legacyRetentionDays = defaultBuiltinMetricRetentionDays
+	}
+	return openStoreWithDefaultRetention(ctx, cfg, legacyRetentionDays)
+}
+
+// TestConnection 使用给定配置尝试连接 metrics 数据库（不影响当前运行的 store）。
+// 仅打开连接并 Ping，不执行自动建表，连接成功后立即关闭。失败时返回可读错误。
+func TestConnection(ctx context.Context, cfg *MetricStoreConfig) error {
+	s, err := openWithoutMigration(ctx, cfg)
+	if err != nil {
+		return err
+	}
+	defer s.Close()
+	return s.Ping(ctx)
+}
+
+// InitializeStore 初始化 metric store（启动时调用，可在失败后重试）。
+func InitializeStore() error {
+	storeInitMu.Lock()
+	defer storeInitMu.Unlock()
+
+	// A previous failed connection must remain retryable. The old sync.Once
+	// implementation consumed the one-time call on failure and returned nil on
+	// every later call while the store was still nil.
+	storeMu.RLock()
+	initialized := store != nil
+	storeMu.RUnlock()
+	if initialized {
+		return nil
+	}
+
+	cfg, err := config.GetManyAs[MetricStoreConfig]()
+	if err != nil {
+		return fmt.Errorf("failed to load metric store config: %w", err)
+	}
+
+	// metric store 始终启用；未配置时默认 SQLite（./data/metrics.db）。
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	s, err := openStore(ctx, cfg)
+	if err != nil {
+		return err
+	}
+
+	activateStore(s, targetFingerprint(cfg), "initialization")
+	clearStoreClosing()
+
+	logger.Infof("metricstore", "Metric store initialized successfully (driver=%s)", ResolveDriverFromConfig(cfg.Driver, cfg.DSN))
+	return nil
+}
+
+// RecoverStore opens, persists, and activates a replacement store selected
+// from the restricted recovery page. It records that target as the current
+// manual-migration source, but does not copy data from the unavailable store.
+func RecoverStore(ctx context.Context, cfg *MetricStoreConfig) error {
+	storeInitMu.Lock()
+	defer storeInitMu.Unlock()
+	if err := storeOperations.Acquire(ctx); err != nil {
+		return fmt.Errorf("wait for metric store operations before recovery: %w", err)
+	}
+	defer storeOperations.Release()
+	if isStoreClosing() {
+		return ErrStoreBusy
+	}
+
+	recovered := *cfg
+	recovered.DSN = strings.TrimSpace(recovered.DSN)
+	recovered.Driver = string(ResolveDriverFromConfig(recovered.Driver, recovered.DSN))
+	target := targetFingerprint(&recovered)
+	restructureRequired, err := structureUpgradeRequiredForConfig(ctx, &recovered)
+	if err != nil {
+		return err
+	}
+	if restructureRequired {
+		if err := saveRecoveredTarget(&recovered, target); err != nil {
+			return err
+		}
+		logger.Infof("metricstore", "Metric store connection recovered; structure upgrade is required (driver=%s)", recovered.Driver)
+		return nil
+	}
+	s, err := openStore(ctx, &recovered)
+	if err != nil {
+		return err
+	}
+	if err := saveRecoveredTarget(&recovered, target); err != nil {
+		_ = s.Close()
+		return err
+	}
+	activateStore(s, target, "recovery")
+	clearStoreClosing()
+	logger.Infof("metricstore", "Metric store recovered successfully (driver=%s)", recovered.Driver)
+	return nil
+}
+
+// saveRecoveredTarget persists the recovered connection and records it as the
+// default source for the next manual store migration.
+func saveRecoveredTarget(cfg *MetricStoreConfig, target string) error {
+	if err := config.SetMany(map[string]any{
+		MetricDBDriverKey:  cfg.Driver,
+		MetricDBDSNKey:     cfg.DSN,
+		MigrationTargetKey: target,
+	}); err != nil {
+		return fmt.Errorf("save recovered metric store config: %w", err)
+	}
+	return nil
+}
+
+// activateStore publishes s as the active store, then closes the store it
+// replaced. Callers must hold the exclusive operation gate or storeInitMu.
+func activateStore(s *metric.Store, fingerprint, reason string) {
+	storeMu.Lock()
+	old := store
+	store = s
+	storeFingerprint = fingerprint
+	storeMu.Unlock()
+	if old == nil {
+		return
+	}
+	if err := old.Close(); err != nil {
+		logger.Errorf("metricstore", "Failed to close previous metric store during %s: %v", reason, err)
+	}
+}
+
+// Reload 根据最新配置热重载 metric store，无需重启进程。
+// metric store 始终启用：用新配置打开并建表（内部已 Ping 校验连接），
+// 成功后再替换运行中的 store，最后关闭旧实例。任何失败都会保留旧 store 不变。
+//
+// 注意：Reload 只切换运行中的连接，不会把旧目标（如 SQLite）中的历史数据
+// 搬运到新目标（如 MySQL/PostgreSQL）。跨库数据迁移必须由管理员手动启动。
+func Reload(ctx context.Context) error {
+	if err := storeOperations.Acquire(ctx); err != nil {
+		return fmt.Errorf("wait for metric store operations before reload: %w", err)
+	}
+	defer storeOperations.Release()
+	if isStoreClosing() {
+		return ErrStoreBusy
+	}
+
+	cfg, err := config.GetManyAs[MetricStoreConfig]()
+	if err != nil {
+		return fmt.Errorf("failed to load metric store config: %w", err)
+	}
+
+	// Do not let the normal hot-reload path run AutoMigrate against an old
+	// point-backed schema. That schema must go through the authenticated
+	// structure-upgrade guide first; otherwise index creation can reference
+	// columns such as resolution_id that do not exist yet.
+	needsRestructure, err := structureUpgradeRequiredForConfig(ctx, cfg)
+	if err != nil {
+		return fmt.Errorf("inspect metric store structure: %w", err)
+	}
+	if needsRestructure {
+		return fmt.Errorf("%w before hot reload", ErrStructureUpgradeRequired)
+	}
+
+	// 用新配置打开并建表（内部已 Ping 校验连接）。
+	s, err := openStore(ctx, cfg)
+	if err != nil {
+		return err
+	}
+
+	activateStore(s, targetFingerprint(cfg), "reload")
+	logger.Infof("metricstore", "Metric store reloaded successfully (driver=%s)", ResolveDriverFromConfig(cfg.Driver, cfg.DSN))
+	return nil
+}
+
+// GetStore 获取 metric store 实例（如果未启用返回 nil）
+func GetStore() *metric.Store {
+	storeMu.RLock()
+	defer storeMu.RUnlock()
+	return store
+}
+
+// CloseStoreContext stops the asynchronous store migration before taking the
+// store write lock, so shutdown cannot wait forever on the migration's lease.
+func CloseStoreContext(ctx context.Context) error {
+	if err := StopStoreMigrationForShutdown(ctx); err != nil {
+		clearStoreClosing()
+		return err
+	}
+	if err := storeOperations.Acquire(ctx); err != nil {
+		clearStoreClosing()
+		return fmt.Errorf("wait for metric store operations before close: %w", err)
+	}
+	defer storeOperations.Release()
+
+	storeMu.Lock()
+	defer storeMu.Unlock()
+	var err error
+	if store != nil {
+		err = store.Close()
+		store = nil
+	}
+	storeFingerprint = ""
+	return err
+}

internal/metricstore/store_migration.go

@@ -0,0 +1,298 @@
+package metricstore
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+
+	logger "github.com/komari-monitor/komari/utils/log"
+
+	"github.com/komari-monitor/komari/internal/config"
+	"github.com/komari-monitor/komari/pkg/metric"
+)
+
+// store_migration.go
+//
+// 面向 WebUI/API 的“存储后端迁移”支撑：把一个 metrics 源库（默认本地 SQLite
+// ./data/metrics.db）中的全部指标数据搬运到当前正在运行的 metrics 目标库
+// （通常是用户新配置并热重载后的 MySQL/PostgreSQL）。
+//
+// 此迁移仅能由管理员在 WebUI 中「切换数据库后」手动触发，异步执行并可查询进度 /
+// 取消。服务启动和指标库热重载均不会复制历史数据。数据以 upsert 写入，可安全重复执行。
+//
+// 典型流程：
+//  1. 管理员在设置中把 metric_db_dsn 改为 MySQL/PostgreSQL，保存 → 后端连接测试
+//     通过后热重载，当前 store 切到远端（此时远端为空）。
+//  2. 管理员调用 startMetricMigration（不带 source 参数），系统以上一个 metrics
+//     目标（默认 SQLite metrics.db）为源，把历史数据搬运到远端。
+//  3. 完成后登记目标指纹，供下一次手动迁移默认选择源库。
+
+// StoreMigrationProgress 描述一次 store-to-store 迁移的实时进度。
+type StoreMigrationProgress struct {
+	Status         string    `json:"status"`          // idle, running, completed, failed, canceled
+	SourceDriver   string    `json:"source_driver"`   // 源库驱动
+	SourceDSN      string    `json:"source_dsn"`      // 源库 DSN（脱敏后）
+	TargetDriver   string    `json:"target_driver"`   // 目标库驱动
+	TargetDSN      string    `json:"target_dsn"`      // 目标库 DSN（脱敏后）
+	TotalMetrics   int       `json:"total_metrics"`   // 指标定义总数
+	CurrentMetric  string    `json:"current_metric"`  // 当前正在搬运的指标名
+	MetricsDone    int       `json:"metrics_done"`    // 已完成的指标数
+	MigratedPoints int64     `json:"migrated_points"` // 已搬运的采样点数
+	StartTime      time.Time `json:"start_time"`      // 开始时间
+	EndTime        time.Time `json:"end_time"`        // 结束时间
+	Error          string    `json:"error,omitempty"` // 错误信息
+}
+
+var (
+	storeMigMu       sync.Mutex
+	storeMigProgress StoreMigrationProgress
+	storeMigCancel   context.CancelFunc
+	storeMigDone     chan struct{}
+	storeClosing     bool
+)
+
+// IsStoreMigrationRunning 报告是否有 store-to-store 迁移正在运行。
+func IsStoreMigrationRunning() bool {
+	storeMigMu.Lock()
+	defer storeMigMu.Unlock()
+	return storeMigCancel != nil
+}
+
+// GetStoreMigrationProgress 返回当前 store-to-store 迁移进度快照。
+func GetStoreMigrationProgress() StoreMigrationProgress {
+	storeMigMu.Lock()
+	defer storeMigMu.Unlock()
+	return storeMigProgress
+}
+
+// ResolveStoreMigrationSourceFingerprint 推断本次 store 迁移的源库指纹。
+//
+// 优先级：
+//  1. 显式传入的 driver+dsn（driver 可留空，交由 DSN 推断）。
+//  2. 已保存的上一个 metrics 目标指纹（MigrationTargetKey）。
+//  3. 默认 SQLite（./data/metrics.db）。
+func ResolveStoreMigrationSourceFingerprint(driver, dsn string) string {
+	dsn = strings.TrimSpace(dsn)
+	if dsn != "" {
+		d := ResolveDriverFromConfig(driver, dsn)
+		return fmt.Sprintf("%s|%s", d, dsn)
+	}
+	if saved, _ := config.GetAs[string](MigrationTargetKey, ""); saved != "" {
+		return saved
+	}
+	return defaultSQLiteFingerprint()
+}
+
+// StartStoreMigration 异步启动一次 store-to-store 迁移：把源库（由 sourceDriver +
+// sourceDSN 指定，留空则自动推断）的全部指标数据搬运到当前运行中的 metrics 目标库。
+//
+// 返回错误表示“未能启动”（例如已有迁移在跑、源与目标相同、目标未初始化等）；
+// 迁移过程中的错误通过 GetStoreMigrationProgress().Status == "failed" 与 Error 暴露。
+func StartStoreMigration(sourceDriver, sourceDSN string) error {
+	cfg, err := config.GetManyAs[MetricStoreConfig]()
+	if err != nil {
+		return fmt.Errorf("failed to load metric store config: %w", err)
+	}
+	targetFP := targetFingerprint(cfg)
+	sourceFP := ResolveStoreMigrationSourceFingerprint(sourceDriver, sourceDSN)
+
+	if sourceFP == targetFP {
+		return fmt.Errorf("source and target metrics database are the same; nothing to migrate")
+	}
+
+	srcCfg, err := configFromFingerprint(sourceFP, cfg)
+	if err != nil {
+		return fmt.Errorf("resolve source metrics store: %w", err)
+	}
+	if !storeOperations.TryAcquire() {
+		return ErrStoreBusy
+	}
+	exclusiveLeaseHandedOff := false
+	defer func() {
+		if !exclusiveLeaseHandedOff {
+			storeOperations.Release()
+		}
+	}()
+
+	storeMu.RLock()
+	dst := store
+	activeFingerprint := storeFingerprint
+	storeMu.RUnlock()
+	if dst == nil {
+		return ErrStoreNotInitialized
+	}
+	if activeFingerprint != targetFP {
+		return fmt.Errorf("active metric store does not match the configured migration target; wait for hot reload and retry")
+	}
+
+	storeMigMu.Lock()
+	if storeClosing {
+		storeMigMu.Unlock()
+		return ErrStoreBusy
+	}
+	if storeMigCancel != nil {
+		storeMigMu.Unlock()
+		return fmt.Errorf("a store migration is already in progress")
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+	storeMigCancel = cancel
+	storeMigDone = done
+	storeMigProgress = StoreMigrationProgress{
+		Status:       "running",
+		SourceDriver: string(ResolveDriverFromConfig(srcCfg.Driver, srcCfg.DSN)),
+		SourceDSN:    maskDSN(srcCfg.DSN),
+		TargetDriver: string(ResolveDriverFromConfig(cfg.Driver, cfg.DSN)),
+		TargetDSN:    maskDSN(cfg.DSN),
+		StartTime:    time.Now().UTC(),
+	}
+	storeMigMu.Unlock()
+
+	exclusiveLeaseHandedOff = true
+	go runStoreMigration(ctx, cancel, done, srcCfg, cfg, dst, targetFP)
+	return nil
+}
+
+// runStoreMigration 执行实际的搬运逻辑（在独立 goroutine 中）。
+func runStoreMigration(ctx context.Context, cancel context.CancelFunc, done chan struct{}, srcCfg *MetricStoreConfig, cfg *MetricStoreConfig, dst *metric.Store, targetFP string) {
+	defer func() {
+		cancel()
+		storeOperations.Release()
+
+		storeMigMu.Lock()
+		storeMigCancel = nil
+		storeMigDone = nil
+		close(done)
+		storeMigMu.Unlock()
+	}()
+
+	src, err := openSourceStore(ctx, srcCfg)
+	if err != nil {
+		finishStoreMigration("failed", fmt.Errorf("open source metrics store: %w", err))
+		return
+	}
+	defer src.Close()
+
+	observe := func(currentMetric string, metricIndex, totalMetrics int, addedPoints int64) {
+		storeMigMu.Lock()
+		storeMigProgress.CurrentMetric = currentMetric
+		storeMigProgress.MetricsDone = metricIndex
+		storeMigProgress.TotalMetrics = totalMetrics
+		storeMigProgress.MigratedPoints += addedPoints
+		storeMigMu.Unlock()
+	}
+
+	total, err := migrateBetweenStores(ctx, src, dst, observe)
+	if err != nil {
+		if ctx.Err() != nil {
+			finishStoreMigration("canceled", nil)
+			logger.Warnf("metricstore", "[store-migration] canceled after %d points", total)
+			return
+		}
+		finishStoreMigration("failed", err)
+		return
+	}
+
+	// 搬运成功：登记当前目标指纹，供下一次手动迁移推断源库。
+	if err := config.Set(MigrationTargetKey, targetFP); err != nil {
+		logger.Errorf("metricstore", "[store-migration] failed to persist migration target fingerprint: %v", err)
+	}
+	finishStoreMigration("completed", nil)
+	logger.Infof("metricstore", "[store-migration] completed via API (%d points) target_driver=%s", total, ResolveDriverFromConfig(cfg.Driver, cfg.DSN))
+}
+
+// finishStoreMigration 统一收尾：设置终态状态、结束时间与错误信息。
+func finishStoreMigration(status string, err error) {
+	storeMigMu.Lock()
+	defer storeMigMu.Unlock()
+	storeMigProgress.Status = status
+	storeMigProgress.EndTime = time.Now().UTC()
+	if err != nil {
+		storeMigProgress.Error = err.Error()
+	}
+	// 完成/取消时把当前指标标记为已全部处理，便于前端进度条归位。
+	if status == "completed" && storeMigProgress.TotalMetrics > 0 {
+		storeMigProgress.MetricsDone = storeMigProgress.TotalMetrics
+	}
+}
+
+// CancelStoreMigration 请求取消正在运行的 store-to-store 迁移，并等待其退出。
+// 由于写入是幂等 upsert，取消后可安全重新发起，不会产生重复数据。
+func CancelStoreMigration() error {
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+	storeMigMu.Lock()
+	stop, done := storeMigCancel, storeMigDone
+	storeMigMu.Unlock()
+	if stop == nil {
+		return fmt.Errorf("no store migration is currently running")
+	}
+	return awaitStoreMigrationStop(ctx, stop, done)
+}
+
+// StopStoreMigrationForShutdown prevents a new store migration and waits for
+// an active one to release its exclusive lease before report batches flush.
+func StopStoreMigrationForShutdown(ctx context.Context) error {
+	storeMigMu.Lock()
+	storeClosing = true
+	stop, done := storeMigCancel, storeMigDone
+	storeMigMu.Unlock()
+	if stop == nil {
+		return nil
+	}
+	return awaitStoreMigrationStop(ctx, stop, done)
+}
+
+func awaitStoreMigrationStop(ctx context.Context, stop context.CancelFunc, done <-chan struct{}) error {
+	stop()
+	select {
+	case <-done:
+		return nil
+	case <-ctx.Done():
+		return fmt.Errorf("wait for store migration to cancel: %w", ctx.Err())
+	}
+}
+
+func clearStoreClosing() {
+	storeMigMu.Lock()
+	storeClosing = false
+	storeMigMu.Unlock()
+}
+
+func isStoreClosing() bool {
+	storeMigMu.Lock()
+	defer storeMigMu.Unlock()
+	return storeClosing
+}
+
+// maskDSN 对 DSN 做粗粒度脱敏，避免在 API 响应/日志中泄露密码。
+// 处理两类常见格式：URL（scheme://user:pass@host/...）与 key=value（password=...）。
+func maskDSN(dsn string) string {
+	dsn = strings.TrimSpace(dsn)
+	if dsn == "" {
+		return ""
+	}
+	// key=value 形式：屏蔽 password=... 段。
+	if strings.Contains(dsn, "password=") {
+		parts := strings.Fields(dsn)
+		for i, p := range parts {
+			if strings.HasPrefix(strings.ToLower(p), "password=") {
+				parts[i] = "password=***"
+			}
+		}
+		return strings.Join(parts, " ")
+	}
+	// URL / user:pass@host 形式：屏蔽 user:pass@ 中的密码。
+	if at := strings.LastIndex(dsn, "@"); at > 0 {
+		head := dsn[:at]
+		tail := dsn[at:]
+		if colon := strings.LastIndex(head, ":"); colon >= 0 {
+			// 保留 scheme://user，屏蔽密码。
+			return head[:colon] + ":***" + tail
+		}
+	}
+	return dsn
+}

internal/migrations/legacy.go

@@ -0,0 +1,30 @@
+package migrations
+
+import "time"
+
+// ClientInfo is the legacy table shape for migrating pre-Client model data.
+type ClientInfo struct {
+	UUID           string     `json:"uuid,omitempty" gorm:"type:varchar(36);primaryKey;foreignKey:ClientUUID;references:UUID;constraint:OnDelete:CASCADE"`
+	Name           string     `json:"name" gorm:"type:varchar(100);not null"`
+	CpuName        string     `json:"cpu_name" gorm:"type:varchar(100)"`
+	Virtualization string     `json:"virtualization" gorm:"type:varchar(50)"`
+	Arch           string     `json:"arch" gorm:"type:varchar(50)"`
+	CpuCores       int        `json:"cpu_cores" gorm:"type:int"`
+	OS             string     `json:"os" gorm:"type:varchar(100)"`
+	GpuName        string     `json:"gpu_name" gorm:"type:varchar(100)"`
+	IPv4           string     `json:"ipv4,omitempty" gorm:"type:varchar(100)"`
+	IPv6           string     `json:"ipv6,omitempty" gorm:"type:varchar(100)"`
+	Region         string     `json:"region" gorm:"type:varchar(100)"`
+	Remark         string     `json:"remark,omitempty" gorm:"type:longtext"`
+	PublicRemark   string     `json:"public_remark,omitempty" gorm:"type:longtext"`
+	MemTotal       int64      `json:"mem_total" gorm:"type:bigint"`
+	SwapTotal      int64      `json:"swap_total" gorm:"type:bigint"`
+	DiskTotal      int64      `json:"disk_total" gorm:"type:bigint"`
+	Version        string     `json:"version,omitempty" gorm:"type:varchar(100)"`
+	Weight         int        `json:"weight" gorm:"type:int"`
+	Price          float64    `json:"price"`
+	BillingCycle   int        `json:"billing_cycle"`
+	ExpiredAt      *time.Time `json:"expired_at" gorm:"type:timestamp"`
+	CreatedAt      time.Time
+	UpdatedAt      time.Time
+}

internal/migrations/legacy_monitoring.go

@@ -0,0 +1,677 @@
+package migrations
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"fmt"
+	logger "github.com/komari-monitor/komari/utils/log"
+	"math"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/komari-monitor/komari/internal/metricstore"
+	"github.com/komari-monitor/komari/database/models"
+	appconfig "github.com/komari-monitor/komari/internal/config"
+	"github.com/komari-monitor/komari/pkg/metric"
+	"gorm.io/gorm"
+)
+
+const (
+	legacyMonitoringMigrationDoneKey = "migration_legacy_monitoring_to_metric_store_done"
+	legacyMonitoringBatchSize        = 500
+	legacyMonitoringInterval         = time.Hour
+)
+
+var legacyMonitoringTables = []string{"records", "records_long_term", "gpu_records", "ping_records"}
+
+type LegacyMonitoringStats struct {
+	Records int64
+	GPU     int64
+	Ping    int64
+}
+
+// LegacyMonitoringSummary describes the full legacy source data shown by the
+// pre-start migration guide. Every source row participates in the migration;
+// EstimatedPoints is the number of hourly P95 points expected after grouping.
+type LegacyMonitoringSummary struct {
+	LoadRows        int64      `json:"load_rows"`
+	GPURows         int64      `json:"gpu_rows"`
+	LatencyRows     int64      `json:"latency_rows"`
+	MonitoringRows  int64      `json:"monitoring_rows"`
+	EstimatedPoints int64      `json:"estimated_points"`
+	ServerCount     int64      `json:"server_count"`
+	RetentionDays   int        `json:"retention_days"`
+	OldestAt        *time.Time `json:"oldest_at,omitempty"`
+	NewestAt        *time.Time `json:"newest_at,omitempty"`
+}
+
+type LegacyMonitoringProgress struct {
+	Phase           string `json:"phase"`
+	Table           string `json:"table,omitempty"`
+	SourceRowsDone  int64  `json:"source_rows_done"`
+	SourceRowsTotal int64  `json:"source_rows_total"`
+	WrittenPoints   int64  `json:"written_points"`
+}
+
+type legacyMonitoringBounds struct {
+	Oldest string `gorm:"column:oldest"`
+	Newest string `gorm:"column:newest"`
+}
+
+type legacyBatchProgress func(table string, rows, points int64)
+
+type legacyP95Group struct {
+	metricName string
+	entityID   string
+	tags       map[string]string
+	values     []float64
+}
+
+type legacyHourlyP95Aggregator struct {
+	store        *metric.Store
+	partitionKey string
+	bucket       time.Time
+	groups       map[string]*legacyP95Group
+}
+
+// LegacyMonitoringMigrationRequired reports whether startup must enter the
+// restricted 1.2.7 upgrade flow. The migration itself runs only after an
+// administrator explicitly starts it from that guide.
+func LegacyMonitoringMigrationRequired(db *gorm.DB) (bool, LegacyMonitoringSummary, error) {
+	done, err := appconfig.GetAs[bool](legacyMonitoringMigrationDoneKey, false)
+	if err != nil {
+		return false, LegacyMonitoringSummary{}, fmt.Errorf("read legacy monitoring migration marker: %w", err)
+	}
+	summary, err := InspectLegacyMonitoring(db)
+	if err != nil {
+		return false, LegacyMonitoringSummary{}, err
+	}
+	return !done && summary.MonitoringRows > 0, summary, nil
+}
+
+func InspectLegacyMonitoring(db *gorm.DB) (LegacyMonitoringSummary, error) {
+	var summary LegacyMonitoringSummary
+	if db == nil {
+		return summary, fmt.Errorf("migration database is nil")
+	}
+	if db.Migrator().HasTable(&models.Client{}) {
+		if err := db.Model(&models.Client{}).Count(&summary.ServerCount).Error; err != nil {
+			return summary, fmt.Errorf("count monitored servers: %w", err)
+		}
+	}
+
+	counts := map[string]*int64{
+		"records":           &summary.LoadRows,
+		"records_long_term": &summary.LoadRows,
+		"gpu_records":       &summary.GPURows,
+		"ping_records":      &summary.LatencyRows,
+	}
+	var oldest, newest time.Time
+	for _, table := range legacyMonitoringTables {
+		if !db.Migrator().HasTable(table) {
+			continue
+		}
+		var count int64
+		if err := db.Table(table).Count(&count).Error; err != nil {
+			return summary, fmt.Errorf("count legacy %s: %w", table, err)
+		}
+		*counts[table] += count
+		if count == 0 {
+			continue
+		}
+		var bounds legacyMonitoringBounds
+		if err := db.Table(table).Select("MIN(time) AS oldest, MAX(time) AS newest").Scan(&bounds).Error; err != nil {
+			return summary, fmt.Errorf("inspect legacy %s time range: %w", table, err)
+		}
+		tableOldest, err := parseLegacyTimestamp(bounds.Oldest, time.UTC)
+		if err != nil {
+			return summary, fmt.Errorf("parse legacy %s oldest time: %w", table, err)
+		}
+		tableNewest, err := parseLegacyTimestamp(bounds.Newest, time.UTC)
+		if err != nil {
+			return summary, fmt.Errorf("parse legacy %s newest time: %w", table, err)
+		}
+		if oldest.IsZero() || (!tableOldest.IsZero() && tableOldest.Before(oldest)) {
+			oldest = tableOldest
+		}
+		if newest.IsZero() || tableNewest.After(newest) {
+			newest = tableNewest
+		}
+	}
+
+	summary.MonitoringRows = summary.LoadRows + summary.GPURows + summary.LatencyRows
+	if !oldest.IsZero() {
+		oldestCopy := oldest
+		summary.OldestAt = &oldestCopy
+	}
+	if !newest.IsZero() {
+		newestCopy := newest
+		summary.NewestAt = &newestCopy
+	}
+	if !oldest.IsZero() && !newest.IsZero() {
+		estimatedPoints, err := estimateLegacyHourlyP95Points(db, summary, oldest, newest)
+		if err != nil {
+			return summary, err
+		}
+		summary.EstimatedPoints = estimatedPoints
+		retentionEnd := time.Now().UTC()
+		if newest.After(retentionEnd) {
+			retentionEnd = newest
+		}
+		summary.RetentionDays = int(math.Ceil(retentionEnd.Sub(oldest).Hours() / 24))
+		if summary.RetentionDays == 0 && summary.MonitoringRows > 0 {
+			summary.RetentionDays = 1
+		}
+	}
+	return summary, nil
+}
+
+func MigrateLegacyMonitoring(ctx context.Context, db *gorm.DB, s *metric.Store, progress func(LegacyMonitoringProgress)) (LegacyMonitoringStats, error) {
+	if err := metricstore.EnsureBuiltinMetricDefinitions(ctx, s); err != nil {
+		return LegacyMonitoringStats{}, fmt.Errorf("ensure built-in metric definitions: %w", err)
+	}
+	return migrateLegacyMonitoringTables(ctx, db, s, progress)
+}
+
+// CompleteLegacyMonitoringMigration removes the legacy tables, runs any
+// caller-owned database maintenance, and only then persists the completion
+// marker. Keeping the marker last prevents a failed finalization from being
+// reported as a completed migration.
+func CompleteLegacyMonitoringMigration(db *gorm.DB, finalize func() error) error {
+	if err := dropLegacyMonitoringTables(db); err != nil {
+		return err
+	}
+	if finalize != nil {
+		if err := finalize(); err != nil {
+			return fmt.Errorf("finalize legacy monitoring migration: %w", err)
+		}
+	}
+	if err := appconfig.Set(legacyMonitoringMigrationDoneKey, true); err != nil {
+		return fmt.Errorf("mark legacy monitoring migration done: %w", err)
+	}
+	return nil
+}
+
+func runLegacyMonitoringMigration(ctx context.Context, db *gorm.DB, s *metric.Store, done bool, markDone func() error) (LegacyMonitoringStats, error) {
+	var stats LegacyMonitoringStats
+	if done {
+		return stats, nil
+	}
+	if db == nil {
+		return stats, fmt.Errorf("migration database is nil")
+	}
+	if s == nil {
+		return stats, fmt.Errorf("metric store is nil")
+	}
+	if markDone == nil {
+		return stats, fmt.Errorf("migration marker writer is nil")
+	}
+
+	stats, err := migrateLegacyMonitoringTables(ctx, db, s, nil)
+	if err != nil {
+		return stats, err
+	}
+	if err := dropLegacyMonitoringTables(db); err != nil {
+		return stats, err
+	}
+	if err := markDone(); err != nil {
+		return stats, fmt.Errorf("mark legacy monitoring migration done: %w", err)
+	}
+	return stats, nil
+}
+
+func migrateLegacyMonitoringTables(ctx context.Context, db *gorm.DB, s *metric.Store, progress func(LegacyMonitoringProgress)) (LegacyMonitoringStats, error) {
+	var stats LegacyMonitoringStats
+	summary, err := InspectLegacyMonitoring(db)
+	if err != nil {
+		return stats, err
+	}
+	var rowsDone, writtenPoints int64
+	emit := func(table string, rows, points int64) {
+		rowsDone += rows
+		writtenPoints += points
+		if progress != nil {
+			progress(LegacyMonitoringProgress{
+				Phase:           "migrating",
+				Table:           table,
+				SourceRowsDone:  rowsDone,
+				SourceRowsTotal: summary.MonitoringRows,
+				WrittenPoints:   writtenPoints,
+			})
+		}
+	}
+	if progress != nil {
+		emit("", 0, 0)
+	}
+	n, err := migrateLegacyRecordTables(ctx, s, db, []string{"records", "records_long_term"}, emit)
+	if err != nil {
+		return stats, err
+	}
+	stats.Records += n
+
+	n, err = migrateLegacyGPURecordTable(ctx, s, db, "gpu_records", emit)
+	if err != nil {
+		return stats, err
+	}
+	stats.GPU += n
+
+	n, err = migrateLegacyPingRecordTable(ctx, s, db, "ping_records", emit)
+	if err != nil {
+		return stats, err
+	}
+	stats.Ping += n
+
+	return stats, nil
+}
+
+func migrateLegacyRecordTables(ctx context.Context, s *metric.Store, db *gorm.DB, tables []string, progress legacyBatchProgress) (int64, error) {
+	var existing []string
+	var total int64
+	for _, table := range tables {
+		if !db.Migrator().HasTable(table) {
+			continue
+		}
+		var count int64
+		if err := db.Table(table).Count(&count).Error; err != nil {
+			return 0, fmt.Errorf("count legacy %s: %w", table, err)
+		}
+		if count > 0 {
+			existing = append(existing, table)
+			total += count
+		}
+	}
+	if len(existing) == 0 {
+		return 0, nil
+	}
+
+	parts := make([]string, 0, len(existing))
+	for _, table := range existing {
+		projection, err := legacyRecordProjection(db, table)
+		if err != nil {
+			return 0, err
+		}
+		parts = append(parts, projection)
+	}
+	query := strings.Join(parts, " UNION ALL ") + " ORDER BY client ASC, time ASC"
+	rows, err := db.Raw(query).Rows()
+	if err != nil {
+		return 0, fmt.Errorf("stream legacy record tables: %w", err)
+	}
+	defer rows.Close()
+
+	logger.Infof("migration", "[legacy-migration] aggregating %d rows from %s into 1h P95 points", total, strings.Join(existing, ","))
+	migrated, err := migrateLegacyStream(ctx, db, s, rows, "records", func() *models.Record { return &models.Record{} }, func(value models.Record) []metric.Point {
+		return recordToPoints(value)
+	}, progress)
+	if err != nil {
+		return migrated, fmt.Errorf("aggregate legacy record tables: %w", err)
+	}
+	logger.Infof("migration", "[legacy-migration] aggregated %d rows from %s", migrated, strings.Join(existing, ","))
+	return migrated, nil
+}
+
+func migrateLegacyGPURecordTable(ctx context.Context, s *metric.Store, db *gorm.DB, table string, progress legacyBatchProgress) (int64, error) {
+	if !db.Migrator().HasTable(table) {
+		return 0, nil
+	}
+
+	var total int64
+	if err := db.Table(table).Count(&total).Error; err != nil {
+		return 0, fmt.Errorf("count legacy %s: %w", table, err)
+	}
+	if total == 0 {
+		return 0, nil
+	}
+
+	rows, err := db.Table(table).Select("*").Order("client ASC, device_index ASC, device_name ASC, time ASC").Rows()
+	if err != nil {
+		return 0, fmt.Errorf("stream legacy %s: %w", table, err)
+	}
+	defer rows.Close()
+	logger.Infof("migration", "[legacy-migration] aggregating %d rows from %s into 1h P95 points", total, table)
+	migrated, err := migrateLegacyStream(ctx, db, s, rows, table, func() *models.GPURecord { return &models.GPURecord{} }, func(value models.GPURecord) []metric.Point {
+		return gpuRecordToPoints(value)
+	}, progress)
+	if err != nil {
+		return migrated, fmt.Errorf("aggregate legacy %s: %w", table, err)
+	}
+	logger.Infof("migration", "[legacy-migration] aggregated %d rows from %s", migrated, table)
+	return migrated, nil
+}
+
+func migrateLegacyPingRecordTable(ctx context.Context, s *metric.Store, db *gorm.DB, table string, progress legacyBatchProgress) (int64, error) {
+	if !db.Migrator().HasTable(table) {
+		return 0, nil
+	}
+
+	var total int64
+	if err := db.Table(table).Count(&total).Error; err != nil {
+		return 0, fmt.Errorf("count legacy %s: %w", table, err)
+	}
+	if total == 0 {
+		return 0, nil
+	}
+
+	rows, err := db.Table(table).Select("*").Order("client ASC, task_id ASC, time ASC").Rows()
+	if err != nil {
+		return 0, fmt.Errorf("stream legacy %s: %w", table, err)
+	}
+	defer rows.Close()
+	logger.Infof("migration", "[legacy-migration] aggregating %d rows from %s into 1h P95 points", total, table)
+	migrated, err := migrateLegacyStream(ctx, db, s, rows, table, func() *models.PingRecord { return &models.PingRecord{} }, func(value models.PingRecord) []metric.Point {
+		return pingRecordToPoints(value)
+	}, progress)
+	if err != nil {
+		return migrated, fmt.Errorf("aggregate legacy %s: %w", table, err)
+	}
+	logger.Infof("migration", "[legacy-migration] aggregated %d rows from %s", migrated, table)
+	return migrated, nil
+}
+
+func migrateLegacyStream[T any](ctx context.Context, db *gorm.DB, s *metric.Store, rows *sql.Rows, table string, newValue func() *T, toPoints func(T) []metric.Point, progress legacyBatchProgress) (int64, error) {
+	aggregator := &legacyHourlyP95Aggregator{store: s}
+	var migrated, batchRows, batchPoints int64
+	emit := func(force bool) {
+		if progress != nil && (batchRows > 0 || force && batchPoints > 0) {
+			progress(table, batchRows, batchPoints)
+		}
+		batchRows = 0
+		batchPoints = 0
+	}
+	for rows.Next() {
+		select {
+		case <-ctx.Done():
+			return migrated, ctx.Err()
+		default:
+		}
+		value := newValue()
+		if err := db.ScanRows(rows, value); err != nil {
+			return migrated, err
+		}
+		written, err := aggregator.Add(ctx, toPoints(*value))
+		if err != nil {
+			return migrated, err
+		}
+		migrated++
+		batchRows++
+		batchPoints += written
+		if batchRows >= legacyMonitoringBatchSize {
+			emit(false)
+		}
+	}
+	if err := rows.Err(); err != nil {
+		return migrated, err
+	}
+	written, err := aggregator.Flush(ctx)
+	if err != nil {
+		return migrated, err
+	}
+	batchPoints += written
+	emit(true)
+	return migrated, nil
+}
+
+func legacyRecordProjection(db *gorm.DB, table string) (string, error) {
+	columnTypes, err := db.Migrator().ColumnTypes(table)
+	if err != nil {
+		return "", fmt.Errorf("inspect legacy %s columns: %w", table, err)
+	}
+	available := make(map[string]struct{}, len(columnTypes))
+	for _, column := range columnTypes {
+		available[strings.ToLower(column.Name())] = struct{}{}
+	}
+	for _, required := range []string{"client", "time"} {
+		if _, ok := available[required]; !ok {
+			return "", fmt.Errorf("legacy %s is missing required column %s", table, required)
+		}
+	}
+	columns := []string{
+		"client", "time", "cpu", "gpu", "ram", "swap", "load", "disk",
+		"net_in", "net_out", "net_total_up", "net_total_down", "traffic_up",
+		"traffic_down", "process", "connections", "connections_udp",
+	}
+	projection := make([]string, 0, len(columns))
+	for _, column := range columns {
+		if _, ok := available[column]; ok {
+			projection = append(projection, column)
+		} else {
+			projection = append(projection, "0 AS "+column)
+		}
+	}
+	return "SELECT " + strings.Join(projection, ", ") + " FROM " + table, nil
+}
+
+func (a *legacyHourlyP95Aggregator) Add(ctx context.Context, points []metric.Point) (int64, error) {
+	var written int64
+	for _, point := range points {
+		bucket := point.Timestamp.UTC().Truncate(legacyMonitoringInterval)
+		partition, err := legacyPointPartition(point)
+		if err != nil {
+			return written, err
+		}
+		if a.groups != nil && (partition != a.partitionKey || !bucket.Equal(a.bucket)) {
+			if partition == a.partitionKey && bucket.Before(a.bucket) {
+				return written, fmt.Errorf("legacy points are not ordered within series: %s before %s", bucket, a.bucket)
+			}
+			n, err := a.Flush(ctx)
+			written += n
+			if err != nil {
+				return written, err
+			}
+		}
+		if a.groups == nil {
+			a.partitionKey = partition
+			a.bucket = bucket
+			a.groups = make(map[string]*legacyP95Group)
+		}
+		group := a.groups[point.MetricName]
+		if group == nil {
+			group = &legacyP95Group{
+				metricName: point.MetricName,
+				entityID:   point.EntityID,
+				tags:       cloneLegacyTags(point.Tags),
+			}
+			a.groups[point.MetricName] = group
+		}
+		group.values = append(group.values, point.Value)
+	}
+	return written, nil
+}
+
+func (a *legacyHourlyP95Aggregator) Flush(ctx context.Context) (int64, error) {
+	if len(a.groups) == 0 {
+		return 0, nil
+	}
+	names := make([]string, 0, len(a.groups))
+	for name := range a.groups {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	points := make([]metric.Point, 0, len(names))
+	for _, name := range names {
+		group := a.groups[name]
+		points = append(points, metric.Point{
+			MetricName: group.metricName,
+			EntityID:   group.entityID,
+			Timestamp:  a.bucket,
+			Value:      legacyP95(group.values),
+			Tags:       group.tags,
+		})
+	}
+	if err := a.store.ReplaceRollupPoints(ctx, legacyMonitoringInterval, points); err != nil {
+		return 0, err
+	}
+	a.partitionKey = ""
+	a.bucket = time.Time{}
+	a.groups = nil
+	return int64(len(points)), nil
+}
+
+func legacyP95(values []float64) float64 {
+	if len(values) == 0 {
+		return 0
+	}
+	sort.Float64s(values)
+	if len(values) == 1 {
+		return values[0]
+	}
+	position := 0.95 * float64(len(values)-1)
+	lower := int(math.Floor(position))
+	upper := int(math.Ceil(position))
+	if lower == upper {
+		return values[lower]
+	}
+	weight := position - float64(lower)
+	return values[lower]*(1-weight) + values[upper]*weight
+}
+
+func legacyPointPartition(point metric.Point) (string, error) {
+	tags, err := json.Marshal(point.Tags)
+	if err != nil {
+		return "", fmt.Errorf("encode legacy point tags: %w", err)
+	}
+	return point.EntityID + "\x00" + string(tags), nil
+}
+
+func cloneLegacyTags(tags map[string]string) map[string]string {
+	if len(tags) == 0 {
+		return nil
+	}
+	cloned := make(map[string]string, len(tags))
+	for key, value := range tags {
+		cloned[key] = value
+	}
+	return cloned
+}
+
+func estimateLegacyHourlyP95Points(db *gorm.DB, summary LegacyMonitoringSummary, oldest, newest time.Time) (int64, error) {
+	type estimate struct {
+		Count int64 `gorm:"column:count"`
+	}
+	countSeries := func(query string) (int64, error) {
+		var result estimate
+		if err := db.Raw("SELECT COUNT(*) AS count FROM (" + query + ")").Scan(&result).Error; err != nil {
+			return 0, err
+		}
+		return result.Count, nil
+	}
+	firstHour := oldest.UTC().Truncate(legacyMonitoringInterval)
+	lastHour := newest.UTC().Truncate(legacyMonitoringInterval)
+	hours := int64(lastHour.Sub(firstHour)/legacyMonitoringInterval) + 1
+	if hours < 1 {
+		hours = 1
+	}
+
+	var recordParts []string
+	for _, table := range []string{"records", "records_long_term"} {
+		if db.Migrator().HasTable(table) {
+			recordParts = append(recordParts, "SELECT client FROM "+table)
+		}
+	}
+	var total int64
+	if len(recordParts) > 0 {
+		series, err := countSeries(strings.Join(recordParts, " UNION "))
+		if err != nil {
+			return 0, fmt.Errorf("estimate load series: %w", err)
+		}
+		total += minLegacyBuckets(summary.LoadRows, series*hours) * 15
+	}
+	if db.Migrator().HasTable("gpu_records") {
+		series, err := countSeries("SELECT client, device_index, device_name FROM gpu_records GROUP BY client, device_index, device_name")
+		if err != nil {
+			return 0, fmt.Errorf("estimate GPU series: %w", err)
+		}
+		total += minLegacyBuckets(summary.GPURows, series*hours) * 4
+	}
+	if db.Migrator().HasTable("ping_records") {
+		series, err := countSeries("SELECT client, task_id FROM ping_records GROUP BY client, task_id")
+		if err != nil {
+			return 0, fmt.Errorf("estimate ping series: %w", err)
+		}
+		total += minLegacyBuckets(summary.LatencyRows, series*hours) * 2
+	}
+	return total, nil
+}
+
+func minLegacyBuckets(sourceRows, estimatedBuckets int64) int64 {
+	if sourceRows < estimatedBuckets {
+		return sourceRows
+	}
+	return estimatedBuckets
+}
+
+func recordToPoints(rec models.Record) []metric.Point {
+	ts := rec.Time
+	entityID := rec.Client
+	return []metric.Point{
+		{MetricName: metricstore.MetricCPU, EntityID: entityID, Timestamp: ts, Value: float64(rec.Cpu)},
+		{MetricName: metricstore.MetricGPU, EntityID: entityID, Timestamp: ts, Value: float64(rec.Gpu)},
+		{MetricName: metricstore.MetricRAM, EntityID: entityID, Timestamp: ts, Value: float64(rec.Ram)},
+		{MetricName: metricstore.MetricSwap, EntityID: entityID, Timestamp: ts, Value: float64(rec.Swap)},
+		{MetricName: metricstore.MetricLoad, EntityID: entityID, Timestamp: ts, Value: float64(rec.Load)},
+		{MetricName: metricstore.MetricDisk, EntityID: entityID, Timestamp: ts, Value: float64(rec.Disk)},
+		{MetricName: metricstore.MetricNetIn, EntityID: entityID, Timestamp: ts, Value: float64(rec.NetIn)},
+		{MetricName: metricstore.MetricNetOut, EntityID: entityID, Timestamp: ts, Value: float64(rec.NetOut)},
+		{MetricName: metricstore.MetricNetTotalUp, EntityID: entityID, Timestamp: ts, Value: float64(rec.NetTotalUp)},
+		{MetricName: metricstore.MetricNetTotalDown, EntityID: entityID, Timestamp: ts, Value: float64(rec.NetTotalDown)},
+		{MetricName: metricstore.MetricTrafficUp, EntityID: entityID, Timestamp: ts, Value: float64(rec.TrafficUp)},
+		{MetricName: metricstore.MetricTrafficDown, EntityID: entityID, Timestamp: ts, Value: float64(rec.TrafficDown)},
+		{MetricName: metricstore.MetricProcess, EntityID: entityID, Timestamp: ts, Value: float64(rec.Process)},
+		{MetricName: metricstore.MetricConnections, EntityID: entityID, Timestamp: ts, Value: float64(rec.Connections)},
+		{MetricName: metricstore.MetricConnectionsUDP, EntityID: entityID, Timestamp: ts, Value: float64(rec.ConnectionsUdp)},
+	}
+}
+
+func gpuRecordToPoints(rec models.GPURecord) []metric.Point {
+	ts := rec.Time
+	tags := map[string]string{
+		"device_index": fmt.Sprintf("%d", rec.DeviceIndex),
+		"device_name":  rec.DeviceName,
+	}
+	return []metric.Point{
+		{MetricName: metricstore.MetricGPUMem, EntityID: rec.Client, Timestamp: ts, Value: float64(rec.MemUsed), Tags: tags},
+		{MetricName: metricstore.MetricGPUMemTotal, EntityID: rec.Client, Timestamp: ts, Value: float64(rec.MemTotal), Tags: tags},
+		{MetricName: metricstore.MetricGPUDeviceUsage, EntityID: rec.Client, Timestamp: ts, Value: float64(rec.Utilization), Tags: tags},
+		{MetricName: metricstore.MetricGPUTemp, EntityID: rec.Client, Timestamp: ts, Value: float64(rec.Temperature), Tags: tags},
+	}
+}
+
+func pingRecordToPoints(rec models.PingRecord) []metric.Point {
+	ts := rec.Time
+	tags := map[string]string{"task_id": fmt.Sprintf("%d", rec.TaskId)}
+	loss := 0.0
+	if rec.Value < 0 {
+		loss = 1
+	}
+	return []metric.Point{
+		{
+			MetricName: metricstore.MetricPingLatency,
+			EntityID:   rec.Client,
+			Timestamp:  ts,
+			Value:      float64(rec.Value),
+			Tags:       tags,
+		},
+		{
+			MetricName: metricstore.MetricPingLoss,
+			EntityID:   rec.Client,
+			Timestamp:  ts,
+			Value:      loss,
+			Tags:       tags,
+		},
+	}
+}
+
+func dropLegacyMonitoringTables(db *gorm.DB) error {
+	for _, table := range legacyMonitoringTables {
+		if !db.Migrator().HasTable(table) {
+			continue
+		}
+		logger.Infof("migration", "[legacy-migration] dropping legacy table %s", table)
+		if err := db.Migrator().DropTable(table); err != nil {
+			return fmt.Errorf("drop legacy table %s: %w", table, err)
+		}
+	}
+	return nil
+}

internal/migrations/legacy_monitoring_test.go

@@ -0,0 +1,303 @@
+package migrations
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"math"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/komari-monitor/komari/internal/metricstore"
+	"github.com/komari-monitor/komari/database/models"
+	appconfig "github.com/komari-monitor/komari/internal/config"
+	"github.com/komari-monitor/komari/pkg/metric"
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+)
+
+func TestLegacyMonitoringTablesMigratedByOneShotMigration(t *testing.T) {
+	ctx := context.Background()
+	mainDB, err := gorm.Open(sqlite.Open("file:"+filepath.ToSlash(filepath.Join(t.TempDir(), "komari.db"))+"?mode=rwc"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open legacy db: %v", err)
+	}
+	if sqlDB, err := mainDB.DB(); err == nil {
+		t.Cleanup(func() { _ = sqlDB.Close() })
+	} else {
+		t.Fatalf("legacy sql db: %v", err)
+	}
+	if err := mainDB.AutoMigrate(&models.Record{}, &models.GPURecord{}, &models.PingRecord{}); err != nil {
+		t.Fatalf("migrate legacy tables: %v", err)
+	}
+	if err := mainDB.Table("records_long_term").AutoMigrate(&models.Record{}); err != nil {
+		t.Fatalf("migrate legacy long-term table: %v", err)
+	}
+
+	base := time.Date(2026, 7, 8, 23, 42, 0, 0, time.UTC)
+	if err := mainDB.Create(&models.Record{Client: "client-a", Time: base, Cpu: 12.5, Ram: 2048}).Error; err != nil {
+		t.Fatalf("seed records: %v", err)
+	}
+	if err := mainDB.Table("records_long_term").Create(&models.Record{Client: "client-a", Time: base.Add(time.Minute), Cpu: 22.5, Ram: 4096}).Error; err != nil {
+		t.Fatalf("seed records_long_term: %v", err)
+	}
+	if err := mainDB.Create(&models.GPURecord{Client: "client-a", Time: base, DeviceIndex: 0, DeviceName: "GPU 0", MemUsed: 1024, MemTotal: 2048, Utilization: 67, Temperature: 55}).Error; err != nil {
+		t.Fatalf("seed gpu_records: %v", err)
+	}
+	if err := mainDB.Create(&models.PingRecord{Client: "client-a", TaskId: 7, Time: base, Value: 36}).Error; err != nil {
+		t.Fatalf("seed ping_records: %v", err)
+	}
+	if err := mainDB.Create(&models.PingRecord{Client: "client-a", TaskId: 7, Time: base.Add(30 * time.Second), Value: -1}).Error; err != nil {
+		t.Fatalf("seed loss ping_records: %v", err)
+	}
+	summary, err := InspectLegacyMonitoring(mainDB)
+	if err != nil {
+		t.Fatalf("inspect legacy monitoring summary: %v", err)
+	}
+	if summary.LoadRows != 2 || summary.GPURows != 1 || summary.LatencyRows != 2 || summary.MonitoringRows != 5 {
+		t.Fatalf("unexpected legacy monitoring summary: %#v", summary)
+	}
+	if summary.EstimatedPoints != 21 || summary.RetentionDays < 1 {
+		t.Fatalf("unexpected legacy point estimate or retention: %#v", summary)
+	}
+
+	metricDB, err := sql.Open("sqlite3", "file:"+filepath.ToSlash(filepath.Join(t.TempDir(), "metrics.db"))+"?mode=rwc")
+	if err != nil {
+		t.Fatalf("open metric db: %v", err)
+	}
+	metricStore, err := metric.Open(ctx, metric.SQLite("", metric.WithDB(metricDB)))
+	if err != nil {
+		t.Fatalf("open metric store: %v", err)
+	}
+	t.Cleanup(func() {
+		_ = metricStore.Close()
+		_ = metricDB.Close()
+	})
+
+	markDoneCalls := 0
+	var lastProgress LegacyMonitoringProgress
+	if _, err := MigrateLegacyMonitoring(ctx, mainDB, metricStore, func(progress LegacyMonitoringProgress) {
+		lastProgress = progress
+	}); err != nil {
+		t.Fatalf("migrate legacy monitoring with progress: %v", err)
+	}
+	if lastProgress.SourceRowsDone != 5 || lastProgress.SourceRowsTotal != 5 || lastProgress.WrittenPoints != 21 {
+		t.Fatalf("unexpected final migration progress: %#v", lastProgress)
+	}
+
+	stats, err := runLegacyMonitoringMigration(ctx, mainDB, metricStore, false, func() error {
+		markDoneCalls++
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("run legacy monitoring migration: %v", err)
+	}
+	if markDoneCalls != 1 {
+		t.Fatalf("expected migration marker to be written once, got %d", markDoneCalls)
+	}
+	if stats.Records != 2 || stats.GPU != 1 || stats.Ping != 2 {
+		t.Fatalf("unexpected stats: %#v", stats)
+	}
+
+	hour := base.Truncate(time.Hour)
+	cpuPoints := queryLegacyRollups(t, ctx, metricStore, metric.Query{MetricName: metricstore.MetricCPU, EntityID: "client-a", Start: hour.Add(-time.Second), End: hour.Add(time.Hour)})
+	if len(cpuPoints) != 1 || math.Abs(cpuPoints[0].Value-22) > 1e-9 || !cpuPoints[0].Bucket.Equal(hour) {
+		t.Fatalf("unexpected cpu points: %#v", cpuPoints)
+	}
+
+	gpuPoints := queryLegacyRollups(t, ctx, metricStore, metric.Query{MetricName: metricstore.MetricGPUDeviceUsage, EntityID: "client-a", Start: hour.Add(-time.Second), End: hour.Add(time.Hour), Tags: map[string]string{"device_index": "0"}})
+	if len(gpuPoints) != 1 || gpuPoints[0].Value != 67 {
+		t.Fatalf("unexpected gpu points: %#v", gpuPoints)
+	}
+
+	pingPoints := queryLegacyRollups(t, ctx, metricStore, metric.Query{MetricName: metricstore.MetricPingLatency, EntityID: "client-a", Start: hour.Add(-time.Second), End: hour.Add(time.Hour), Tags: map[string]string{"task_id": "7"}})
+	if len(pingPoints) != 1 || math.Abs(pingPoints[0].Value-34.15) > 1e-9 || !pingPoints[0].Bucket.Equal(hour) {
+		t.Fatalf("unexpected ping points: %#v", pingPoints)
+	}
+
+	pingLossPoints := queryLegacyRollups(t, ctx, metricStore, metric.Query{MetricName: metricstore.MetricPingLoss, EntityID: "client-a", Start: hour.Add(-time.Second), End: hour.Add(time.Hour), Tags: map[string]string{"task_id": "7"}})
+	if len(pingLossPoints) != 1 || math.Abs(pingLossPoints[0].Value-0.95) > 1e-9 || !pingLossPoints[0].Bucket.Equal(hour) {
+		t.Fatalf("unexpected ping loss points: %#v", pingLossPoints)
+	}
+
+	for _, table := range legacyMonitoringTables {
+		if mainDB.Migrator().HasTable(table) {
+			t.Fatalf("legacy table %s still exists", table)
+		}
+	}
+
+	stats, err = runLegacyMonitoringMigration(ctx, mainDB, metricStore, true, func() error {
+		markDoneCalls++
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("rerun completed legacy monitoring migration: %v", err)
+	}
+	if stats != (LegacyMonitoringStats{}) {
+		t.Fatalf("completed migration should not scan legacy tables, got %#v", stats)
+	}
+	if markDoneCalls != 1 {
+		t.Fatalf("completed migration rewrote marker, calls=%d", markDoneCalls)
+	}
+}
+
+func TestLegacyHourlyP95PreservesHoursAndTaggedSeries(t *testing.T) {
+	ctx := context.Background()
+	metricDB, err := sql.Open("sqlite3", "file:"+filepath.ToSlash(filepath.Join(t.TempDir(), "hourly-p95.db"))+"?mode=rwc")
+	if err != nil {
+		t.Fatalf("open metric db: %v", err)
+	}
+	store, err := metric.Open(ctx, metric.SQLite("", metric.WithDB(metricDB)))
+	if err != nil {
+		t.Fatalf("open metric store: %v", err)
+	}
+	t.Cleanup(func() {
+		_ = store.Close()
+		_ = metricDB.Close()
+	})
+	if err := store.UpsertMetric(ctx, metric.Definition{Name: "test.p95", Type: metric.TypeGauge, RetentionDays: 1}); err != nil {
+		t.Fatalf("create test metric: %v", err)
+	}
+
+	base := time.Date(2026, 7, 8, 10, 0, 0, 0, time.UTC)
+	aggregator := &legacyHourlyP95Aggregator{store: store}
+	inputs := [][]metric.Point{
+		{{MetricName: "test.p95", EntityID: "node-a", Timestamp: base.Add(time.Minute), Value: 10, Tags: map[string]string{"task_id": "1"}}},
+		{{MetricName: "test.p95", EntityID: "node-a", Timestamp: base.Add(2 * time.Minute), Value: 20, Tags: map[string]string{"task_id": "1"}}},
+		{{MetricName: "test.p95", EntityID: "node-a", Timestamp: base.Add(time.Hour), Value: 30, Tags: map[string]string{"task_id": "1"}}},
+		{{MetricName: "test.p95", EntityID: "node-a", Timestamp: base.Add(time.Minute), Value: 100, Tags: map[string]string{"task_id": "2"}}},
+	}
+	for _, points := range inputs {
+		if _, err := aggregator.Add(ctx, points); err != nil {
+			t.Fatalf("add aggregate input: %v", err)
+		}
+	}
+	if _, err := aggregator.Flush(ctx); err != nil {
+		t.Fatalf("flush aggregate input: %v", err)
+	}
+
+	taskOne := queryLegacyRollups(t, ctx, store, metric.Query{
+		MetricName: "test.p95", EntityID: "node-a", Start: base.Add(-time.Second), End: base.Add(2 * time.Hour),
+		Tags: map[string]string{"task_id": "1"}, Order: metric.OrderAsc,
+	})
+	if len(taskOne) != 2 || math.Abs(taskOne[0].Value-19.5) > 1e-9 || taskOne[1].Value != 30 {
+		t.Fatalf("unexpected task one aggregates: %#v", taskOne)
+	}
+	taskTwo := queryLegacyRollups(t, ctx, store, metric.Query{
+		MetricName: "test.p95", EntityID: "node-a", Start: base.Add(-time.Second), End: base.Add(2 * time.Hour),
+		Tags: map[string]string{"task_id": "2"}, Order: metric.OrderAsc,
+	})
+	if len(taskTwo) != 1 || taskTwo[0].Value != 100 || !taskTwo[0].Bucket.Equal(base) {
+		t.Fatalf("unexpected task two aggregates: %#v", taskTwo)
+	}
+}
+
+func queryLegacyRollups(t *testing.T, ctx context.Context, store *metric.Store, query metric.Query) []metric.AggregatePoint {
+	t.Helper()
+	points, err := store.Series(ctx, metric.AggregateQuery{
+		Query: query, Aggregation: metric.AggLast, Interval: time.Hour, PreserveSeries: true,
+	}, query.End)
+	if err != nil {
+		t.Fatalf("query %s rollups: %v", query.MetricName, err)
+	}
+	return points
+}
+
+func TestLegacyRecordProjectionFillsMissingMetricColumns(t *testing.T) {
+	db, err := gorm.Open(sqlite.Open("file:"+filepath.ToSlash(filepath.Join(t.TempDir(), "minimal-legacy.db"))+"?mode=rwc"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open minimal legacy db: %v", err)
+	}
+	if sqlDB, err := db.DB(); err == nil {
+		t.Cleanup(func() { _ = sqlDB.Close() })
+	} else {
+		t.Fatalf("minimal legacy sql db: %v", err)
+	}
+	if err := db.Exec("CREATE TABLE records_minimal (client TEXT NOT NULL, time DATETIME NOT NULL, cpu REAL NOT NULL)").Error; err != nil {
+		t.Fatalf("create minimal legacy table: %v", err)
+	}
+	base := time.Date(2026, 7, 8, 10, 0, 0, 0, time.UTC)
+	if err := db.Exec("INSERT INTO records_minimal (client, time, cpu) VALUES (?, ?, ?)", "node-a", base, 42.5).Error; err != nil {
+		t.Fatalf("insert minimal legacy row: %v", err)
+	}
+	projection, err := legacyRecordProjection(db, "records_minimal")
+	if err != nil {
+		t.Fatalf("build legacy projection: %v", err)
+	}
+	var record models.Record
+	if err := db.Raw(projection).Scan(&record).Error; err != nil {
+		t.Fatalf("scan projected legacy row: %v", err)
+	}
+	if record.Client != "node-a" || !record.Time.Equal(base) || record.Cpu != 42.5 {
+		t.Fatalf("unexpected projected record: %#v", record)
+	}
+	if record.ConnectionsUdp != 0 || record.NetTotalDown != 0 {
+		t.Fatalf("missing metric columns were not zero-filled: %#v", record)
+	}
+}
+
+func TestCompleteLegacyMonitoringMigrationFinalizesBeforeMarkingDone(t *testing.T) {
+	db, err := gorm.Open(sqlite.Open("file:"+filepath.ToSlash(filepath.Join(t.TempDir(), "finalize.db"))+"?mode=rwc"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open finalization database: %v", err)
+	}
+	if sqlDB, err := db.DB(); err == nil {
+		t.Cleanup(func() { _ = sqlDB.Close() })
+	} else {
+		t.Fatalf("finalization sql db: %v", err)
+	}
+	appconfig.SetDb(db)
+	if err := db.AutoMigrate(&models.Record{}); err != nil {
+		t.Fatalf("migrate legacy table: %v", err)
+	}
+	if err := appconfig.Set(legacyMonitoringMigrationDoneKey, false); err != nil {
+		t.Fatalf("reset completion marker: %v", err)
+	}
+
+	finalized := false
+	if err := CompleteLegacyMonitoringMigration(db, func() error {
+		finalized = true
+		if db.Migrator().HasTable(&models.Record{}) {
+			t.Fatal("legacy table still exists during finalization")
+		}
+		done, err := appconfig.GetAs[bool](legacyMonitoringMigrationDoneKey, false)
+		if err != nil {
+			return err
+		}
+		if done {
+			t.Fatal("completion marker was written before finalization")
+		}
+		return nil
+	}); err != nil {
+		t.Fatalf("complete legacy migration: %v", err)
+	}
+	if !finalized {
+		t.Fatal("finalizer was not called")
+	}
+	done, err := appconfig.GetAs[bool](legacyMonitoringMigrationDoneKey, false)
+	if err != nil {
+		t.Fatalf("read completion marker: %v", err)
+	}
+	if !done {
+		t.Fatal("completion marker was not written after finalization")
+	}
+
+	if err := db.AutoMigrate(&models.Record{}); err != nil {
+		t.Fatalf("restore legacy table: %v", err)
+	}
+	if err := appconfig.Set(legacyMonitoringMigrationDoneKey, false); err != nil {
+		t.Fatalf("reset completion marker after success: %v", err)
+	}
+	finalizeErr := errors.New("vacuum failed")
+	if err := CompleteLegacyMonitoringMigration(db, func() error { return finalizeErr }); !errors.Is(err, finalizeErr) {
+		t.Fatalf("finalization error = %v, want %v", err, finalizeErr)
+	}
+	done, err = appconfig.GetAs[bool](legacyMonitoringMigrationDoneKey, false)
+	if err != nil {
+		t.Fatalf("read completion marker after failure: %v", err)
+	}
+	if done {
+		t.Fatal("failed finalization wrote the completion marker")
+	}
+}

internal/migrations/migrations.go

@@ -3,13 +3,13 @@ package migrations
 import (
 	"encoding/json"
 	"fmt"
-	"log"
+	logger "github.com/komari-monitor/komari/utils/log"
 	"reflect"
 	"strings"
 	"time"
 
 	"github.com/komari-monitor/komari/database/models"
-	appconfig "github.com/komari-monitor/komari/pkg/config"
+	appconfig "github.com/komari-monitor/komari/internal/config"
 	"gorm.io/gorm"
 	"gorm.io/gorm/clause"
 )
@@ -27,8 +27,6 @@ type legacyModelConfig struct {
 	EulaAccepted               bool    `json:"eula_accepted" gorm:"default:false"`
 	GeoIpEnabled               bool    `json:"geo_ip_enabled" gorm:"default:true"`
 	GeoIpProvider              string  `json:"geo_ip_provider" gorm:"type:varchar(20);default:'ip-api'"`
-	NezhaCompatEnabled         bool    `json:"nezha_compat_enabled" gorm:"default:false"`
-	NezhaCompatListen          string  `json:"nezha_compat_listen" gorm:"type:varchar(100);default:''"`
 	OAuthEnabled               bool    `json:"o_auth_enabled" gorm:"default:false"`
 	OAuthProvider              string  `json:"o_auth_provider" gorm:"type:varchar(50);default:'github'"`
 	DisablePasswordLogin       bool    `json:"disable_password_login" gorm:"default:false"`
@@ -41,11 +39,8 @@ type legacyModelConfig struct {
 	ExpireNotificationLeadDays int     `json:"expire_notification_lead_days" gorm:"default:7"`
 	LoginNotification          bool    `json:"login_notification" gorm:"default:false"`
 	TrafficLimitPercentage     float64 `json:"traffic_limit_percentage" gorm:"default:80.00"`
-	RecordEnabled              bool    `json:"record_enabled" gorm:"default:true"`
-	RecordPreserveTime         int     `json:"record_preserve_time" gorm:"default:720"`
-	PingRecordPreserveTime     int     `json:"ping_record_preserve_time" gorm:"default:24"`
-	CreatedAt                  models.LocalTime
-	UpdatedAt                  models.LocalTime
+	CreatedAt                  time.Time
+	UpdatedAt                  time.Time
 }
 
 func (legacyModelConfig) TableName() string {
@@ -66,12 +61,9 @@ type legacyConfig struct {
 	BaseScriptsURLKey          string    `json:"base_scripts_url"`
 	GeoIpEnabled               bool      `json:"geo_ip_enabled"`
 	GeoIpProvider              string    `json:"geo_ip_provider"`
-	NezhaCompatEnabled         bool      `json:"nezha_compat_enabled"`
-	NezhaCompatListen          string    `json:"nezha_compat_listen"`
 	OAuthEnabled               bool      `json:"o_auth_enabled"`
 	OAuthProvider              string    `json:"o_auth_provider"`
 	DisablePasswordLogin       bool      `json:"disable_password_login"`
-	CloudflareTunnelToken      string    `json:"cloudflare_tunnel_token"`
 	CustomHead                 string    `json:"custom_head"`
 	CustomBody                 string    `json:"custom_body"`
 	NotificationEnabled        bool      `json:"notification_enabled"`
@@ -81,9 +73,6 @@ type legacyConfig struct {
 	ExpireNotificationLeadDays int       `json:"expire_notification_lead_days"`
 	LoginNotification          bool      `json:"login_notification"`
 	TrafficLimitPercentage     float64   `json:"traffic_limit_percentage"`
-	RecordEnabled              bool      `json:"record_enabled"`
-	RecordPreserveTime         int       `json:"record_preserve_time"`
-	PingRecordPreserveTime     int       `json:"ping_record_preserve_time"`
 	UpdatedAt                  time.Time `json:"updated_at"`
 }
 
@@ -108,6 +97,9 @@ func Run(ctx Context) error {
 	}
 
 	legacyConfigTable := hasLegacyConfigTable(db)
+	if err := migrateLegacyTimestampColumns(db); err != nil {
+		return err
+	}
 
 	if legacyConfigTable {
 		if err := migrateLegacyOidcConfig(db); err != nil {
@@ -117,13 +109,9 @@ func Run(ctx Context) error {
 			return err
 		}
 	}
-
 	if err := migrateLegacyClientInfo(db); err != nil {
 		return err
 	}
-	if err := migrateLegacyLoadNotification(db); err != nil {
-		return err
-	}
 	if err := migrateLegacyPingAllClientsExpansion(db); err != nil {
 		return err
 	}
@@ -132,10 +120,37 @@ func Run(ctx Context) error {
 			return err
 		}
 	}
+	if err := migrateDeprecatedMetricRetentionConfig(db); err != nil {
+		return err
+	}
+	if err := migrateRemovedCompatibilityConfig(db); err != nil {
+		return err
+	}
+	if err := markTimestampMigrationDone(db); err != nil {
+		return fmt.Errorf("mark UTC timestamp migration done: %w", err)
+	}
 
 	return nil
 }
 
+func migrateDeprecatedMetricRetentionConfig(db *gorm.DB) error {
+	if !db.Migrator().HasTable(&appconfig.ConfigItem{}) {
+		return nil
+	}
+	return db.Delete(&appconfig.ConfigItem{}, "key = ?", "metric_retention_days").Error
+}
+
+func migrateRemovedCompatibilityConfig(db *gorm.DB) error {
+	if !db.Migrator().HasTable(&appconfig.ConfigItem{}) {
+		return nil
+	}
+	return db.Delete(&appconfig.ConfigItem{}, "key IN ?", []string{
+		"nezha_compat_enabled",
+		"nezha_compat_listen",
+		"low_resource_mode",
+	}).Error
+}
+
 func hasLegacyConfigTable(db *gorm.DB) bool {
 	if !db.Migrator().HasTable("configs") {
 		return false
@@ -157,20 +172,12 @@ func hasTableColumn(db *gorm.DB, tableName, columnName string) bool {
 	return false
 }
 
-func migrateLegacyLoadNotification(db *gorm.DB) error {
-	if db.Migrator().HasColumn(&models.LoadNotification{}, "client") {
-		log.Println("[>0.1.4] Rebuilding LoadNotification table....")
-		return db.Migrator().DropTable(&models.LoadNotification{})
-	}
-	return nil
-}
-
 func migrateLegacyOidcConfig(db *gorm.DB) error {
 	if db.Migrator().HasTable(&models.OidcProvider{}) {
 		return nil
 	}
 
-	log.Println("[>1.0.2] Merge OidcProvider table....")
+	logger.InfoArgs("migration", "[>1.0.2] Merge OidcProvider table....")
 	var oldData struct {
 		OAuthClientID     string `gorm:"column:o_auth_client_id"`
 		OAuthClientSecret string `gorm:"column:o_auth_client_secret"`
@@ -207,7 +214,7 @@ func migrateLegacyMessageSenderConfig(db *gorm.DB) error {
 		return nil
 	}
 
-	log.Println("[>1.0.2] Migrate MessageSender configuration....")
+	logger.InfoArgs("migration", "[>1.0.2] Migrate MessageSender configuration....")
 	var oldData struct {
 		TelegramBotToken   string `gorm:"column:telegram_bot_token"`
 		TelegramChatID     string `gorm:"column:telegram_chat_id"`
@@ -291,7 +298,7 @@ func saveLegacyMessageSenderConfig(db *gorm.DB, name string, config map[string]i
 }
 
 func migrateLegacyConfigToItems(db *gorm.DB) error {
-	log.Println("[>1.1.4] Moving legacy config data...")
+	logger.InfoArgs("migration", "[>1.1.4] Moving legacy config data...")
 
 	var oldData legacyConfig
 	if err := db.Order("id desc").First(&oldData).Error; err != nil {
@@ -354,7 +361,7 @@ func migrateLegacyClientInfo(db *gorm.DB) error {
 		return nil
 	}
 
-	log.Println("[>0.0.5] Legacy ClientInfo table detected, starting data migration...")
+	logger.InfoArgs("migration", "[>0.0.5] Legacy ClientInfo table detected, starting data migration...")
 	if err := db.AutoMigrate(&models.Client{}); err != nil {
 		return err
 	}
@@ -367,7 +374,7 @@ func migrateLegacyClientInfo(db *gorm.DB) error {
 	for _, info := range clientInfos {
 		var client models.Client
 		if err := db.Where("uuid = ?", info.UUID).First(&client).Error; err != nil {
-			log.Printf("Could not find Client record with UUID %s: %v", info.UUID, err)
+			logger.Errorf("migration", "Could not find Client record with UUID %s: %v", info.UUID, err)
 			continue
 		}
 
@@ -390,7 +397,7 @@ func migrateLegacyClientInfo(db *gorm.DB) error {
 		client.Weight = info.Weight
 		client.Price = info.Price
 		client.BillingCycle = info.BillingCycle
-		client.ExpiredAt = models.FromTime(info.ExpiredAt)
+		client.ExpiredAt = info.ExpiredAt
 		if err := db.Save(&client).Error; err != nil {
 			return fmt.Errorf("update Client record %s: %w", info.UUID, err)
 		}
@@ -399,7 +406,7 @@ func migrateLegacyClientInfo(db *gorm.DB) error {
 	if err := db.Migrator().RenameTable("client_infos", "client_infos_backup"); err != nil {
 		return fmt.Errorf("backup legacy ClientInfo table: %w", err)
 	}
-	log.Println("Data migration completed, old table has been backed up as client_infos_backup")
+	logger.InfoArgs("migration", "Data migration completed, old table has been backed up as client_infos_backup")
 	return nil
 }
 

internal/migrations/migrations_test.go

@@ -2,12 +2,13 @@ package migrations
 
 import (
 	"encoding/json"
+	"fmt"
 	"strings"
 	"testing"
 	"time"
 
 	"github.com/komari-monitor/komari/database/models"
-	appconfig "github.com/komari-monitor/komari/pkg/config"
+	appconfig "github.com/komari-monitor/komari/internal/config"
 	"gorm.io/driver/sqlite"
 	"gorm.io/gorm"
 )
@@ -15,7 +16,7 @@ import (
 func openTestDB(t *testing.T, name string) *gorm.DB {
 	t.Helper()
 
-	dsn := "file:" + strings.ReplaceAll(name, " ", "_") + "?mode=memory&cache=shared"
+	dsn := fmt.Sprintf("file:%s-%d?mode=memory&cache=shared", strings.ReplaceAll(name, " ", "_"), time.Now().UnixNano())
 	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{})
 	if err != nil {
 		t.Fatalf("open sqlite test db: %v", err)
@@ -79,6 +80,60 @@ func TestRunSkipsLegacyConfigMigrationForCurrentConfigItemTable(t *testing.T) {
 	}
 }
 
+func TestRunRemovesDeprecatedMetricRetentionConfig(t *testing.T) {
+	db := openTestDB(t, "migrations_remove_metric_retention")
+	if err := db.AutoMigrate(&appconfig.ConfigItem{}); err != nil {
+		t.Fatalf("migrate config item table: %v", err)
+	}
+	if err := db.Create(&appconfig.ConfigItem{Key: "metric_retention_days", Value: "90"}).Error; err != nil {
+		t.Fatalf("seed deprecated config: %v", err)
+	}
+	if err := Run(Context{DB: db}); err != nil {
+		t.Fatalf("run migrations: %v", err)
+	}
+	var count int64
+	if err := db.Model(&appconfig.ConfigItem{}).Where("key = ?", "metric_retention_days").Count(&count).Error; err != nil {
+		t.Fatalf("count deprecated config: %v", err)
+	}
+	if count != 0 {
+		t.Fatalf("deprecated metric retention config was not removed: %d", count)
+	}
+}
+
+func TestRunRemovesCompatibilityConfig(t *testing.T) {
+	db := openTestDB(t, "migrations_remove_compatibility_config")
+	if err := db.AutoMigrate(&appconfig.ConfigItem{}); err != nil {
+		t.Fatalf("migrate config item table: %v", err)
+	}
+	for _, key := range []string{"nezha_compat_enabled", "nezha_compat_listen", "low_resource_mode"} {
+		if err := db.Create(&appconfig.ConfigItem{Key: key, Value: "true"}).Error; err != nil {
+			t.Fatalf("seed removed config %q: %v", key, err)
+		}
+	}
+	if err := db.Create(&appconfig.ConfigItem{Key: "sitename", Value: `"Komari"`}).Error; err != nil {
+		t.Fatalf("seed retained config: %v", err)
+	}
+
+	if err := Run(Context{DB: db}); err != nil {
+		t.Fatalf("run migrations: %v", err)
+	}
+
+	var count int64
+	if err := db.Model(&appconfig.ConfigItem{}).Where("key IN ?", []string{
+		"nezha_compat_enabled",
+		"nezha_compat_listen",
+		"low_resource_mode",
+	}).Count(&count).Error; err != nil {
+		t.Fatalf("count removed config: %v", err)
+	}
+	if count != 0 {
+		t.Fatalf("removed compatibility config remains: %d", count)
+	}
+	if err := db.First(&appconfig.ConfigItem{}, "key = ?", "sitename").Error; err != nil {
+		t.Fatalf("unrelated config was removed: %v", err)
+	}
+}
+
 func TestRunPreservesVersion120RuntimeShape(t *testing.T) {
 	db := openTestDB(t, "migrations_v120_runtime_shape")
 	if err := db.AutoMigrate(
@@ -90,7 +145,7 @@ func TestRunPreservesVersion120RuntimeShape(t *testing.T) {
 	); err != nil {
 		t.Fatalf("migrate 1.2.0 runtime shape: %v", err)
 	}
-	now := models.FromTime(time.Now())
+	now := time.Now().UTC()
 	if err := db.Create(&models.Client{UUID: "client-a", Token: "token-a", CreatedAt: now, UpdatedAt: now}).Error; err != nil {
 		t.Fatalf("seed client: %v", err)
 	}
@@ -169,9 +224,6 @@ func TestRunMigratesLegacyConfigTableToConfigItems(t *testing.T) {
 		OAuthProvider:              "github",
 		NotificationMethod:         "none",
 		TrafficLimitPercentage:     66.5,
-		RecordEnabled:              true,
-		RecordPreserveTime:         48,
-		PingRecordPreserveTime:     12,
 		ExpireNotificationLeadDays: 3,
 	}
 	if err := db.Create(&legacy).Error; err != nil {
@@ -218,7 +270,7 @@ func TestRunExpandsLegacyPingAllClientsTasks(t *testing.T) {
 	`).Error; err != nil {
 		t.Fatalf("create legacy ping_tasks: %v", err)
 	}
-	now := models.FromTime(time.Now())
+	now := time.Now().UTC()
 	clients := []models.Client{
 		{UUID: "client-a", Token: "token-a", CreatedAt: now, UpdatedAt: now},
 		{UUID: "client-b", Token: "token-b", CreatedAt: now, UpdatedAt: now},

internal/migrations/timestamp.go

@@ -0,0 +1,239 @@
+package migrations
+
+import (
+	"database/sql"
+	"fmt"
+	logger "github.com/komari-monitor/komari/utils/log"
+	"math"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+
+	appconfig "github.com/komari-monitor/komari/internal/config"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+const timestampUTCMigrationKey = "internal_timestamp_utc_migrated"
+
+type timestampColumn struct {
+	table  string
+	column string
+}
+
+var legacyTimestampColumns = [...]timestampColumn{
+	{table: "clients", column: "expired_at"},
+	{table: "clients", column: "created_at"},
+	{table: "clients", column: "updated_at"},
+	{table: "client_infos", column: "expired_at"},
+	{table: "client_infos", column: "created_at"},
+	{table: "client_infos", column: "updated_at"},
+	{table: "users", column: "created_at"},
+	{table: "users", column: "updated_at"},
+	{table: "sessions", column: "latest_online"},
+	{table: "sessions", column: "expires"},
+	{table: "sessions", column: "created_at"},
+	{table: "logs", column: "time"},
+	{table: "offline_notifications", column: "last_notified"},
+	{table: "task_results", column: "finished_at"},
+	{table: "task_results", column: "created_at"},
+	{table: "records", column: "time"},
+	{table: "records_long_term", column: "time"},
+	{table: "gpu_records", column: "time"},
+	{table: "ping_records", column: "time"},
+	{table: "configs", column: "created_at"},
+	{table: "configs", column: "updated_at"},
+}
+
+var legacyTimestampLayouts = [...]string{
+	"2006-01-02 15:04:05.999999999-07:00",
+	"2006-01-02 15:04:05-07:00",
+	"2006-01-02 15:04:05.999999999",
+	"2006-01-02 15:04:05",
+	"2006-01-02T15:04:05.999999999",
+	"2006-01-02T15:04:05",
+	"2006-01-02",
+}
+
+type timestampRow struct {
+	rowID int64
+	value sql.NullString
+}
+
+// migrateLegacyTimestampColumns makes old offset-free SQLite values
+// unambiguous before any current model scans them as time.Time.
+func migrateLegacyTimestampColumns(db *gorm.DB) error {
+	if timestampMigrationDone(db) {
+		return nil
+	}
+
+	location := legacyTimestampLocation()
+	var converted int64
+	err := db.Transaction(func(tx *gorm.DB) error {
+		for _, target := range legacyTimestampColumns {
+			if !tx.Migrator().HasTable(target.table) || !tx.Migrator().HasColumn(target.table, target.column) {
+				continue
+			}
+			count, err := migrateTimestampColumn(tx, target, location)
+			if err != nil {
+				return err
+			}
+			converted += count
+		}
+		return nil
+	})
+	if err != nil {
+		return err
+	}
+	if converted > 0 {
+		logger.Infof("migration", "Converted %d legacy timestamp values to explicit UTC", converted)
+	}
+	return nil
+}
+
+func migrateTimestampColumn(db *gorm.DB, target timestampColumn, location *time.Location) (int64, error) {
+	table := quoteSQLiteIdentifier(target.table)
+	column := quoteSQLiteIdentifier(target.column)
+	var converted int64
+	var lastRowID int64
+
+	for {
+		query := fmt.Sprintf(
+			"SELECT rowid, CAST(%s AS TEXT) FROM %s WHERE rowid > ? AND %s IS NOT NULL ORDER BY rowid LIMIT 1000",
+			column, table, column,
+		)
+		rows, err := db.Raw(query, lastRowID).Rows()
+		if err != nil {
+			return converted, fmt.Errorf("read legacy timestamp %s.%s: %w", target.table, target.column, err)
+		}
+
+		batch := make([]timestampRow, 0, 1000)
+		for rows.Next() {
+			var row timestampRow
+			if err := rows.Scan(&row.rowID, &row.value); err != nil {
+				rows.Close()
+				return converted, fmt.Errorf("scan legacy timestamp %s.%s: %w", target.table, target.column, err)
+			}
+			batch = append(batch, row)
+			lastRowID = row.rowID
+		}
+		if err := rows.Err(); err != nil {
+			rows.Close()
+			return converted, fmt.Errorf("iterate legacy timestamp %s.%s: %w", target.table, target.column, err)
+		}
+		rows.Close()
+		if len(batch) == 0 {
+			break
+		}
+
+		for _, row := range batch {
+			raw := strings.TrimSpace(row.value.String)
+			if !row.value.Valid || raw == "" {
+				continue
+			}
+			stamp, err := parseLegacyTimestamp(raw, location)
+			if err != nil {
+				return converted, fmt.Errorf("convert legacy timestamp %s.%s rowid=%d: %w", target.table, target.column, row.rowID, err)
+			}
+			update := fmt.Sprintf("UPDATE %s SET %s = ? WHERE rowid = ?", table, column)
+			if err := db.Exec(update, stamp.UTC(), row.rowID).Error; err != nil {
+				return converted, fmt.Errorf("write UTC timestamp %s.%s rowid=%d: %w", target.table, target.column, row.rowID, err)
+			}
+			converted++
+		}
+		if len(batch) < 1000 {
+			break
+		}
+	}
+	return converted, nil
+}
+
+func parseLegacyTimestamp(value string, location *time.Location) (time.Time, error) {
+	raw := strings.TrimSpace(value)
+	if raw == "" {
+		return time.Time{}, fmt.Errorf("timestamp is empty")
+	}
+	if location == nil {
+		location = time.UTC
+	}
+	if stamp, err := time.Parse(time.RFC3339Nano, raw); err == nil {
+		return stamp.UTC(), nil
+	}
+	for _, layout := range legacyTimestampLayouts {
+		if stamp, err := time.ParseInLocation(layout, raw, location); err == nil {
+			return stamp.UTC(), nil
+		}
+	}
+	epoch, err := strconv.ParseInt(raw, 10, 64)
+	if err != nil {
+		return time.Time{}, fmt.Errorf("unsupported legacy timestamp %q", value)
+	}
+	return legacyEpochTime(epoch), nil
+}
+
+func legacyEpochTime(value int64) time.Time {
+	abs := value
+	if abs < 0 {
+		if abs == math.MinInt64 {
+			return time.Unix(0, value).UTC()
+		}
+		abs = -abs
+	}
+	switch {
+	case abs >= 1e17:
+		return time.Unix(0, value).UTC()
+	case abs >= 1e14:
+		return time.Unix(0, value*int64(time.Microsecond)).UTC()
+	case abs >= 1e11:
+		return time.UnixMilli(value).UTC()
+	default:
+		return time.Unix(value, 0).UTC()
+	}
+}
+
+// legacyTimestampLocation is intentionally migration-only. The old custom
+// type used TZ and defaulted to UTC; current runtime code uses system time.Local.
+func legacyTimestampLocation() *time.Location {
+	name := strings.TrimSpace(os.Getenv("TZ"))
+	if name == "" {
+		return time.UTC
+	}
+	location, err := time.LoadLocation(name)
+	if err != nil {
+		logger.Infof("migration", "Legacy timezone %q cannot be loaded; interpreting old timestamps as UTC: %v", name, err)
+		return time.UTC
+	}
+	return location
+}
+
+func timestampMigrationDone(db *gorm.DB) bool {
+	if !db.Migrator().HasTable(&appconfig.ConfigItem{}) || hasLegacyConfigTable(db) {
+		return false
+	}
+	var item appconfig.ConfigItem
+	if err := db.Where("key = ?", timestampUTCMigrationKey).First(&item).Error; err != nil {
+		return false
+	}
+	return item.Value == "true"
+}
+
+func markTimestampMigrationDone(db *gorm.DB) error {
+	if hasLegacyConfigTable(db) {
+		return fmt.Errorf("new config item table is unavailable")
+	}
+	if !db.Migrator().HasTable(&appconfig.ConfigItem{}) {
+		if err := db.AutoMigrate(&appconfig.ConfigItem{}); err != nil {
+			return fmt.Errorf("create config item table: %w", err)
+		}
+	}
+	item := appconfig.ConfigItem{Key: timestampUTCMigrationKey, Value: "true"}
+	return db.Clauses(clause.OnConflict{
+		Columns:   []clause.Column{{Name: "key"}},
+		DoUpdates: clause.AssignmentColumns([]string{"value"}),
+	}).Create(&item).Error
+}
+
+func quoteSQLiteIdentifier(value string) string {
+	return `"` + strings.ReplaceAll(value, `"`, `""`) + `"`
+}

internal/migrations/timestamp_test.go

@@ -0,0 +1,99 @@
+package migrations
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+func TestLegacyTimestampMigrationDefaultsToUTC(t *testing.T) {
+	t.Setenv("TZ", "")
+	db := openTimestampMigrationDB(t)
+	insertLegacyLogTime(t, db, "2026-07-17 09:30:00.1234567")
+
+	if err := migrateLegacyTimestampColumns(db); err != nil {
+		t.Fatalf("migrate timestamps: %v", err)
+	}
+	want := time.Date(2026, 7, 17, 9, 30, 0, 123456700, time.UTC)
+	assertMigratedLogTime(t, db, want)
+}
+
+func TestLegacyTimestampMigrationUsesLegacyTZ(t *testing.T) {
+	t.Setenv("TZ", "Asia/Shanghai")
+	db := openTimestampMigrationDB(t)
+	insertLegacyLogTime(t, db, "2026-07-17 09:30:00.123456789")
+
+	if err := migrateLegacyTimestampColumns(db); err != nil {
+		t.Fatalf("migrate timestamps: %v", err)
+	}
+	want := time.Date(2026, 7, 17, 1, 30, 0, 123456789, time.UTC)
+	assertMigratedLogTime(t, db, want)
+}
+
+func TestParseLegacyTimestampAcceptsHistoricalEpochUnits(t *testing.T) {
+	stamp := time.Date(2026, 7, 17, 1, 30, 0, 123456789, time.UTC)
+	tests := map[string]struct {
+		value string
+		want  time.Time
+	}{
+		"seconds":      {value: fmt.Sprint(stamp.Unix()), want: stamp.Truncate(time.Second)},
+		"milliseconds": {value: fmt.Sprint(stamp.UnixMilli()), want: stamp.Truncate(time.Millisecond)},
+		"microseconds": {value: fmt.Sprint(stamp.UnixMicro()), want: stamp.Truncate(time.Microsecond)},
+		"nanoseconds":  {value: fmt.Sprint(stamp.UnixNano()), want: stamp},
+	}
+	for name, test := range tests {
+		t.Run(name, func(t *testing.T) {
+			got, err := parseLegacyTimestamp(test.value, time.UTC)
+			if err != nil {
+				t.Fatalf("parse legacy timestamp: %v", err)
+			}
+			if !got.Equal(test.want) {
+				t.Fatalf("parsed timestamp = %s, want %s", got, test.want)
+			}
+		})
+	}
+}
+
+func openTimestampMigrationDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:%s-%d?mode=memory&cache=shared", strings.ReplaceAll(t.Name(), "/", "_"), time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{Logger: logger.Default.LogMode(logger.Silent)})
+	if err != nil {
+		t.Fatalf("open database: %v", err)
+	}
+	if err := db.Exec(`CREATE TABLE logs (id INTEGER PRIMARY KEY, time TIMESTAMP)`).Error; err != nil {
+		t.Fatalf("create logs table: %v", err)
+	}
+	return db
+}
+
+func insertLegacyLogTime(t *testing.T, db *gorm.DB, value string) {
+	t.Helper()
+	if err := db.Exec(`INSERT INTO logs (time) VALUES (?)`, value).Error; err != nil {
+		t.Fatalf("insert legacy timestamp: %v", err)
+	}
+}
+
+func assertMigratedLogTime(t *testing.T, db *gorm.DB, want time.Time) {
+	t.Helper()
+	var got time.Time
+	if err := db.Raw(`SELECT time FROM logs LIMIT 1`).Scan(&got).Error; err != nil {
+		t.Fatalf("read migrated timestamp: %v", err)
+	}
+	if !got.Equal(want) || got.Nanosecond() != want.Nanosecond() {
+		t.Fatalf("migrated time = %s, want %s", got, want)
+	}
+
+	var raw string
+	if err := db.Raw(`SELECT CAST(time AS TEXT) FROM logs LIMIT 1`).Scan(&raw).Error; err != nil {
+		t.Fatalf("read raw migrated timestamp: %v", err)
+	}
+	if !strings.HasSuffix(raw, "+00:00") {
+		t.Fatalf("stored timestamp %q has no explicit UTC offset", raw)
+	}
+}

internal/notifications/notifications.go

@@ -0,0 +1,64 @@
+// Package notifications wires the built-in notification channels into the
+// shared messageSender registry.
+package notifications
+
+import (
+	"encoding/json"
+	"errors"
+
+	"github.com/komari-monitor/komari/database"
+	"github.com/komari-monitor/komari/database/models"
+	"github.com/komari-monitor/komari/internal/managedconfig"
+	"github.com/komari-monitor/komari/utils/messageSender"
+	"github.com/komari-monitor/komari/utils/messageSender/javascript"
+	"github.com/komari-monitor/komari/utils/messageSender/webhook"
+)
+
+// Initialize registers the built-in channels and seeds their defaults.
+func Initialize() (err error) {
+	if err := webhook.Register(); err != nil {
+		return err
+	}
+	registered := []string{"webhook"}
+	defer func() {
+		if err != nil {
+			for _, id := range registered {
+				err = errors.Join(err, messageSender.UnregisterNotificationChannel(id))
+			}
+		}
+	}()
+	if err := javascript.Register(); err != nil {
+		return err
+	}
+	registered = append(registered, javascript.ChannelID)
+	for _, item := range messageSender.ListNotificationChannels() {
+		if _, err := database.GetMessageSenderConfigByName(item.ID); err == nil {
+			continue
+		}
+		values := map[string]any{}
+		for _, field := range managedconfig.Items(item.Configuration) {
+			if field.Key != "" {
+				values[field.Key] = managedconfig.DefaultValue(field)
+			}
+		}
+		raw, err := json.Marshal(values)
+		if err != nil {
+			return err
+		}
+		if err := database.SaveMessageSenderConfig(&models.MessageSenderProvider{
+			Name:     item.ID,
+			Addition: string(raw),
+		}); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// Shutdown unregisters the built-in channels and releases their runtimes.
+func Shutdown() error {
+	return errors.Join(
+		messageSender.UnregisterNotificationChannel(javascript.ChannelID),
+		messageSender.UnregisterNotificationChannel("webhook"),
+	)
+}