fix: #626 CPU占用过大

* feat(api): 添加备份文件分块上传接口

* refactor(backup): 优化备份机制，引入白名单与短时去重

* fix: harden backup chunk uploads

* fix: serialize backup restore operations

* fix: stop cancelled backup merge

* refactor: simplify backup chunk staging

---------

Co-authored-by: Akizon77 <i@akz.moe>

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

@@ -8,6 +8,9 @@ inputs:
   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: ""
@@ -25,7 +28,11 @@ runs:
       run: |
         set -euxo pipefail
         rm -rf komari-web
-        git clone --depth=1 "${{ inputs.repository }}" 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

.github/workflows/build.yml

@@ -59,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

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

@@ -3,11 +3,6 @@ name: Generate Release Notes
 on:
   release:
     types: [published]
-  repository_dispatch:
-    types:
-      - komari-web-release-published
-  schedule:
-    - cron: "41 * * * *"
   workflow_dispatch:
     inputs:
       tag:

.github/workflows/rebuild-release.yml

@@ -0,0 +1,159 @@
+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)"
+          go build -trimpath -ldflags="-s -w -X github.com/komari-monitor/komari/utils.CurrentVersion=${RELEASE_TAG} -X github.com/komari-monitor/komari/utils.VersionHash=${VERSION_HASH}" -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

@@ -107,7 +107,6 @@ jobs:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
             type=raw,value=${{ github.event.inputs.version }}
-            type=raw,value=latest
 
       - name: Build and push Docker image
         uses: docker/build-push-action@v5

.github/workflows/release.yml

@@ -13,7 +13,24 @@ 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:
@@ -24,6 +41,7 @@ jobs:
         uses: ./.github/actions/build-frontend
         with:
           artifact-name: komari-frontend
+          ref: ${{ needs.resolve-release.outputs.frontend_ref }}
 
   build-and-attach-binaries:
     needs: build-frontend
@@ -65,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
@@ -151,6 +173,20 @@ jobs:
           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
@@ -158,7 +194,6 @@ jobs:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
             type=raw,value=${{ github.event.release.tag_name }}
-            type=raw,value=latest
 
       - name: Build and push Docker image
         uses: docker/build-push-action@v5
@@ -170,3 +205,9 @@ jobs:
           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

@@ -112,6 +112,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

Dockerfile

@@ -14,13 +14,6 @@ COPY komari-${TARGETOS}-${TARGETARCH} /app/komari
 RUN chmod +x /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
 
 EXPOSE 25774

README.md

@@ -5,7 +5,7 @@
 
 ![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)
+[简体中文](./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.
 
@@ -14,7 +14,7 @@ Komari is a lightweight, self-hosted server monitoring tool designed to provide
 > Users are solely responsible for how they deploy and operate Komari. The developers do not accept responsibility for unauthorized or abusive use, or for any resulting consequences.
 > On Windows, when remote control is enabled, the client displays a Windows notification at each user login to remind the user that Komari is remote control software.
 
-[Documentation](https://komari-document.pages.dev/) | [文档(镜像站 By Geekertao)](https://www.komari.wiki) | [Telegram Group](https://t.me/komari_monitor)
+[文档/Documentation](https://komari-document.pages.dev/) | [文档(镜像站 By Geekertao)](https://www.komari.wiki) | [Telegram Group](https://t.me/komari_monitor)
 
 ## Features
 
@@ -22,9 +22,7 @@ Komari is a lightweight, self-hosted server monitoring tool designed to provide
 - **Self-hosted**: Complete control over data privacy, easy to deploy.
 - **Web Interface**: Intuitive monitoring dashboard, easy to use.
 
-## Quick Start
-
-### 0. One-click Deployment with Cloud Hosting
+## One-click Deployment
 
 - Rainyun - CNY 4.5/month
 
@@ -34,87 +32,7 @@ Komari is a lightweight, self-hosted server monitoring tool designed to provide
 
 Available on 1Panel App Store. Install via **App Store > Utilities > Komari**.
 
-### 1. Use the One-click Install Script
-
-Suitable for distributions using 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 Deployment
-
-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.
-
-> [!NOTE]
-> You can also customize the initial username and password through the environment variables `ADMIN_USERNAME` and `ADMIN_PASSWORD`.
-
-### 3. Binary File Deployment
-
-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)
+For Docker, binary, source-build, and update instructions, see the [installation guide](https://komari-document.pages.dev/en/install/quick-start).
 
 ## Contributing
 
@@ -122,26 +40,8 @@ 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)
+| Acknowledgement                                                                                                                                                                                  | Details                                                                                                                                                                                                             |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <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) 可参与公益募捐或群内抽奖免费使用 |
+| Open-source community                                                                                                                                                                            | Everyone who has submitted pull requests or created themes.                                                                                                                                                         |

README_zh-cn.md

@@ -0,0 +1,49 @@
+# 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)
+
+[简体中文](./README_zh-cn.md)
+
+Komari 是一款轻量级的自托管服务器监控工具，旨在提供简单、高效的服务器性能监控解决方案。它支持通过 Web 界面查看服务器状态，并通过轻量级 Agent 收集数据。
+
+> [!WARNING]
+> Komari 是一款自托管的监控/控制程序，仅应部署在你拥有或已获得授权管理的系统上。请勿将 Komari 武器化，或在未获授权的情况下部署、访问、持久化、执行命令及从事其他滥用行为。关于现实中的滥用风险，可参考 Huntress 的分析：[Komari C2 agent abuse](https://www.huntress.com/blog/komari-c2-agent-abuse)。
+> 用户需要自行承担部署和使用 Komari 的责任。开发者不对未经授权或滥用行为及其后果承担责任。
+> 在 Windows 端开启远程控制后，客户端会在每次用户登录时通过 Windows 通知提醒用户 Komari 是一款远程控制软件。
+
+[文档/Documentation](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 即可安装
+
+Docker、二进制文件、源码构建和更新说明，请参阅 [安装指南](https://www.komari.wiki/install/quick-start).
+
+## 贡献
+
+欢迎提交 Issue 或 Pull Request！
+
+## 鸣谢
+
+| 赞助商                                                                                                                                                                                           | 描述                                                                                                                                                                                                                |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <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) 可参与公益募捐或群内抽奖免费使用 |
+| 开源社区                                                                                                                                                                                         | 提交 PR、制作主题的各位开发者                                                                                                                                                                                       |

cmd/app.go

@@ -1,445 +0,0 @@
-package cmd
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"log"
-	"net/http"
-	"os"
-	"os/signal"
-	"syscall"
-	"time"
-
-	"github.com/gin-gonic/gin"
-
-	"github.com/komari-monitor/komari/cmd/flags"
-	"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/metricstore"
-	"github.com/komari-monitor/komari/database/models"
-	d_notification "github.com/komari-monitor/komari/database/notification"
-	"github.com/komari-monitor/komari/database/tasks"
-	"github.com/komari-monitor/komari/pkg/config"
-	"github.com/komari-monitor/komari/pkg/corn"
-	"github.com/komari-monitor/komari/pkg/migrations"
-	"github.com/komari-monitor/komari/utils"
-	"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/api"
-	"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"
-)
-
-// cleanupFunc 是一个关闭阶段执行的清理函数。
-type cleanupFunc struct {
-	name string
-	fn   func(ctx context.Context) error
-}
-
-// App 显式建模服务端的启动生命周期。
-//
-// 过去 RunServer 把目录创建、数据库、metric store、GeoIP、定时任务、通知、OAuth、
-// Nezha、Gin 中间件、路由、HTTP 启动与 shutdown 全部混在一个函数里，
-// 启动顺序只能靠通读整段代码推断，异步初始化过早且吞掉错误，关闭也不完整。
-//
-// App 把这些拆成有序阶段：
-//
-//	Bootstrap    基础设施：目录、数据库、默认管理员、配置快照
-//	InitStores   存储：metric store
-//	InitProviders 外部 provider：OAuth（同步，路由依赖）、GeoIP、消息发送、Nezha 兼容
-//	StartBackground 后台：定时任务
-//	BuildRouter  构建 Gin 引擎与路由
-//	Run          启动 HTTP 服务并阻塞直到收到信号
-//	Shutdown     反序执行已登记的清理函数
-//
-// 每个阶段返回错误即可让上层决定是否中止启动；各资源在创建时把对应清理登记到
-// cleanup 栈，关闭时按后进先出（LIFO）顺序释放。
-type App struct {
-	settings *config.Settings
-	engine   *gin.Engine
-	server   *http.Server
-	reload   *ReloadManager
-	dbReady  bool
-
-	cleanups []cleanupFunc
-}
-
-// NewApp 构造一个空的 App。真正的初始化在各阶段方法中完成。
-func NewApp() *App {
-	return &App{
-		reload: NewReloadManager(),
-	}
-}
-
-// addCleanup 登记一个关闭阶段的清理函数（后进先出执行）。
-func (a *App) addCleanup(name string, fn func(ctx context.Context) error) {
-	a.cleanups = append(a.cleanups, cleanupFunc{name: name, fn: fn})
-}
-
-// Bootstrap 初始化基础设施：数据目录、数据库、默认管理员账号、配置快照。
-func (a *App) Bootstrap() error {
-	if err := os.MkdirAll("./data/theme", os.ModePerm); err != nil {
-		return fmt.Errorf("failed to create theme directory: %w", err)
-	}
-
-	// 注入版本标识，供 dbcore 在检测到版本升级时自动备份 ./data。
-	// 必须在 Initialize() 之前设置。
-	dbcore.SetVersionID(utils.CurrentVersion + "-" + utils.VersionHash)
-
-	// 显式初始化数据库（返回错误而非在 getter 里 log.Fatal）。
-	if err := dbcore.Initialize(); err != nil {
-		return fmt.Errorf("failed to initialize database: %w", err)
-	}
-
-	a.dbReady = true
-	a.addCleanup("database", func(context.Context) error {
-		return dbcore.Close()
-	})
-
-	if utils.VersionHash != "unknown" {
-		gin.SetMode(gin.ReleaseMode)
-	}
-
-	// 首次启动创建默认管理员账号。
-	if err := ensureDefaultAdmin(); err != nil {
-		return fmt.Errorf("failed to ensure default admin account: %w", err)
-	}
-
-	conf, err := config.GetManyAs[config.Settings]()
-	if err != nil {
-		return fmt.Errorf("failed to load settings: %w", err)
-	}
-	a.settings = conf
-	return nil
-}
-
-// InitStores 初始化独立存储组件（metric store）并执行 metrics 迁移。
-//
-// metric store 现在始终启用（旧的 metric_store_enabled 开关已废弃）：
-// 未显式配置时使用 SQLite（./data/metrics.db），否则使用配置的 MySQL/PostgreSQL。
-// 初始化失败即启动失败，不再静默 fallback 到旧 records 表。
-//
-// 初始化成功后先执行需要 metric store 的一次性迁移，再执行启动迁移：当 metrics
-// 存储后端发生变化（例如从默认 SQLite 切换到 MySQL/PostgreSQL）时，把上一个
-// metrics 目标库的数据搬运到当前目标。迁移失败同样让启动失败，并打印明确错误。
-func (a *App) InitStores() error {
-	if err := metricstore.InitializeStore(); err != nil {
-		auditlog.EventLog("error", fmt.Sprintf("Failed to initialize metric store: %v", err))
-		return fmt.Errorf("failed to initialize metric store: %w", err)
-	}
-	a.addCleanup("metric-store", func(ctx context.Context) error {
-		return metricstore.CloseStoreContext(ctx)
-	})
-
-	if err := migrations.RunMetricStoreMigrations(migrations.MetricContext{
-		DB:    dbcore.GetDBInstance(),
-		Store: metricstore.GetStore(),
-	}); err != nil {
-		auditlog.EventLog("error", fmt.Sprintf("Metric store one-shot migrations failed: %v", err))
-		return fmt.Errorf("metric store one-shot migrations failed: %w", err)
-	}
-
-	// 存储后端切换时把上一个 metrics 目标库的数据搬运到当前目标（失败即启动失败）。
-	if err := metricstore.RunStartupMigration(); err != nil {
-		auditlog.EventLog("error", fmt.Sprintf("Metrics startup migration failed: %v", err))
-
-		return fmt.Errorf("metrics startup migration failed: %w", err)
-	}
-	return nil
-}
-
-// InitProviders 初始化外部 provider。
-//
-// OAuth 必须在 HTTP 服务开始接收请求之前同步完成，否则 oauth.CurrentProvider()
-// 存在空指针风险；GeoIP 与消息发送允许后台初始化；Nezha 兼容按配置决定是否启动。
-func (a *App) InitProviders() error {
-	// OAuth：同步初始化并处理错误，保证路由可用前 provider 已就绪。
-	if err := oauth.Initialize(); err != nil {
-		// 记录但不致命：Initialize 内部在失败时已回退到 github provider。
-		log.Printf("Failed to initialize OAuth provider: %v", err)
-		auditlog.EventLog("error", fmt.Sprintf("Failed to initialize OAuth provider: %v", err))
-	}
-	a.addCleanup("oauth", func(context.Context) error {
-		return oauth.Shutdown()
-	})
-
-	// GeoIP：可能涉及下载/加载 mmdb，放后台执行避免拖慢启动。
-	go geoip.InitGeoIp()
-	a.addCleanup("geoip", func(context.Context) error {
-		return geoip.Shutdown()
-	})
-
-	// 消息发送 provider。
-	messageSender.Initialize()
-	a.addCleanup("message-sender", func(context.Context) error {
-		return messageSender.Shutdown()
-	})
-
-	// Nezha 兼容 gRPC 服务：按配置启动，且无论初始是否启动都登记清理，
-	// 以覆盖运行期通过热重载开启的情况。
-	if a.settings.NezhaCompatEnabled {
-		listen := a.settings.NezhaCompatListen
-		go func() {
-			if err := nezha.StartNezhaCompat(listen); err != nil {
-				log.Printf("Nezha compat server error: %v", err)
-				auditlog.EventLog("error", fmt.Sprintf("Nezha compat server error: %v", err))
-			}
-		}()
-	}
-	a.addCleanup("nezha-compat", func(context.Context) error {
-		// 未运行时 StopNezhaCompat 返回错误，属正常情况，忽略即可。
-		_ = nezha.StopNezhaCompat()
-		return nil
-	})
-
-	return nil
-}
-
-// StartBackground 启动后台工作：定时任务。
-func (a *App) StartBackground() error {
-	registerScheduledWork()
-	a.addCleanup("scheduler", func(context.Context) error {
-		corn.StopAll()
-		return nil
-	})
-	return nil
-}
-
-// registerReloadHandlers 把此前散落各处的 config.Subscribe 统一登记到 reload 管理器。
-func (a *App) registerReloadHandlers(cors *security.CorsController) {
-	// OAuth provider 切换。
-	a.reload.Register("oauth-provider", 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)
-				return
-			}
-			log.Printf("Using %s as OIDC provider", oidcProvider.Name)
-			if err := oauth.LoadProvider(oidcProvider.Name, oidcProvider.Addition); err != nil {
-				auditlog.EventLog("error", fmt.Sprintf("Failed to load OIDC provider: %v", err))
-			}
-		}
-	})
-
-	// Nezha 兼容服务开关。
-	a.reload.Register("nezha-compat", func(event config.ConfigEvent) {
-		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))
-				}
-			}
-		}
-	})
-
-	// GeoIP provider 切换。
-	a.reload.Register("geoip-provider", func(event config.ConfigEvent) {
-		if event.IsChanged(config.GeoIpProviderKey) {
-			go geoip.InitGeoIp()
-		}
-	})
-
-	// 消息发送方式切换。
-	a.reload.Register("message-sender", func(event config.ConfigEvent) {
-		if event.IsChanged(config.NotificationMethodKey) {
-			go messageSender.Initialize()
-		}
-	})
-
-	// CORS 配置热更新。
-	a.reload.Register("cors", func(event config.ConfigEvent) {
-		cors.Update(event)
-	})
-}
-
-// BuildRouter 构建 Gin 引擎、中间件与全部路由，并登记热重载处理器。
-func (a *App) BuildRouter() error {
-	r := gin.New()
-	r.Use(logutil.GinLogger())
-	r.Use(logutil.GinRecovery())
-
-	cors := security.NewCorsController(a.settings.CorsOriginCheckEnabled, a.settings.CorsAllowedOrigins)
-	r.Use(cors.Middleware())
-
-	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)
-
-	// 集中登记并启动热重载订阅。
-	a.registerReloadHandlers(cors)
-	a.reload.Start()
-
-	a.engine = r
-	return nil
-}
-
-// Run 启动 HTTP 服务并阻塞直到收到中断信号或服务异常退出。
-func (a *App) Run() error {
-	a.server = &http.Server{
-		Addr:    flags.Listen,
-		Handler: a.engine,
-	}
-
-	serverErr := make(chan error, 1)
-	log.Printf("Starting server on %s ...", flags.Listen)
-	go func() {
-		if err := a.server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
-			serverErr <- err
-		}
-	}()
-
-	quit := make(chan os.Signal, 1)
-	signal.Notify(quit, os.Interrupt, syscall.SIGTERM)
-
-	select {
-	case err := <-serverErr:
-		a.onFatal(err)
-		return fmt.Errorf("listen: %w", err)
-	case <-quit:
-		return a.Shutdown()
-	}
-}
-
-// Shutdown 优雅关闭：先停止接收新请求，再反序执行已登记的清理函数。
-func (a *App) Shutdown() error {
-	if a.dbReady {
-		auditlog.Log("", "", "server is shutting down", "info")
-	}
-
-	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-	defer cancel()
-
-	// 先关闭 HTTP 服务，停止接收新请求。
-	if a.server != nil {
-		if err := a.server.Shutdown(ctx); err != nil {
-			log.Printf("HTTP server forced to shutdown: %v", err)
-		}
-	}
-
-	// 反序释放资源（后进先出）。
-	for i := len(a.cleanups) - 1; i >= 0; i-- {
-		c := a.cleanups[i]
-		if err := c.fn(ctx); err != nil {
-			log.Printf("cleanup %q failed: %v", c.name, err)
-		}
-	}
-	return nil
-}
-
-// onFatal 处理 HTTP 服务致命错误：尽力释放已登记资源。
-func (a *App) onFatal(err error) {
-	if a.dbReady {
-		auditlog.Log("", "", "server encountered a fatal error: "+err.Error(), "error")
-	}
-	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-	defer cancel()
-	for i := len(a.cleanups) - 1; i >= 0; i-- {
-		c := a.cleanups[i]
-		if cerr := c.fn(ctx); cerr != nil {
-			log.Printf("cleanup %q failed: %v", c.name, cerr)
-		}
-	}
-}
-
-// ensureDefaultAdmin 首次启动（无任何用户）时创建默认管理员账号。
-func ensureDefaultAdmin() error {
-	var count int64
-	dbcore.GetDBInstance().Model(&models.User{}).Count(&count)
-	if count != 0 {
-		return nil
-	}
-	user, passwd, err := accounts.CreateDefaultAdminAccount()
-	if err != nil {
-		return err
-	}
-	log.Println("Default admin account created. Username:", user, ", Password:", passwd)
-	return nil
-}
-
-// registerScheduledWork 注册所有定时任务与首启动同步逻辑。
-func registerScheduledWork() {
-	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)
-	}
-
-	if err := corn.AddFunc("records:cleanup", "@every 30m", cleanupScheduledData); err != nil {
-		log.Println("Failed to add cleanup scheduled task:", err)
-	}
-	if err := corn.AddContextFunc("metrics:compact", "@every 5m", true, compactMetricStore); err != nil {
-		log.Println("Failed to add metric compact 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[metricstore.MetricStoreConfig]()
-	retentionDays := cfg.RetentionDays
-	if retentionDays <= 0 {
-		retentionDays = 30
-	}
-	before := time.Now().Add(-24 * time.Hour * time.Duration(retentionDays))
-	tasks.ClearTaskResultsByTimeBefore(before)
-
-	auditlog.RemoveOldLogs()
-	accounts.RemoveExpiredSessions()
-}
-
-func compactMetricStore(ctx context.Context) {
-	compactCtx, cancel := context.WithTimeout(ctx, 15*time.Minute)
-	defer cancel()
-
-	written, err := metricstore.Compact(compactCtx, time.Now())
-	if errors.Is(err, metricstore.ErrCompactInProgress) {
-		return
-	}
-	if err != nil {
-		log.Printf("Failed to compact metric store after writing %d rollup buckets: %v", written, err)
-		return
-	}
-	if written > 0 {
-		log.Printf("Metric store compacted %d rollup buckets", written)
-	}
-}
-
-func minuteScheduledWork() {
-	report_cache.SaveClientReportToDB()
-	// 每分钟检查一次流量提醒
-	notifier.CheckTraffic()
-}

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/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,7 +1,11 @@
 package cmd
 
 import (
-	"log"
+	"errors"
+	"os"
+
+	appserver "github.com/komari-monitor/komari/internal/server"
+	logger "github.com/komari-monitor/komari/utils/log"
 
 	"github.com/komari-monitor/komari/cmd/flags"
 	"github.com/spf13/cobra"
@@ -25,18 +29,76 @@ func init() {
 
 // RunServer 按显式的生命周期阶段启动服务端。
 //
-// 具体各阶段的职责与顺序见 App（cmd/app.go）。这里只负责串联：
+// 具体各阶段的职责与顺序见 internal/server.App。这里只负责串联：
 // 任一初始化阶段失败即中止启动，避免在半初始化状态下对外提供服务。
 func RunServer() {
-	app := NewApp()
+	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)
+	}
 
-	// 初始化阶段：任一步失败都不应继续对外服务。
+	installRequired, err := app.InstallRequired()
+	if err != nil {
+		_ = app.Shutdown()
+		logger.Fatalf("server", "server startup failed at %q: %v", "detect-first-run-install", err)
+	}
+	if installRequired {
+		completed, err := app.RunInstallGuide()
+		if err != nil {
+			_ = app.Shutdown()
+			logger.Fatalf("server", "server startup failed at %q: %v", "run-first-run-install", err)
+		}
+		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{
-		{"bootstrap", app.Bootstrap},
 		{"init-stores", app.InitStores},
 		{"init-providers", app.InitProviders},
 		{"start-background", app.StartBackground},
@@ -46,11 +108,15 @@ func RunServer() {
 		if err := s.fn(); err != nil {
 			// 已登记的资源尽力回收，再退出。
 			_ = app.Shutdown()
-			log.Fatalf("server startup failed at %q: %v", s.name, err)
+			logger.Fatalf("server", "server startup failed at %q: %v", s.name, err)
 		}
 	}
 
 	if err := app.Run(); err != nil {
-		log.Fatalf("server exited with error: %v", err)
+		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)
 	}
 }

database/accounts/accounts.go

@@ -4,14 +4,12 @@ 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"
@@ -56,7 +54,10 @@ func hashPasswd(passwd string) string {
 }
 
 func CreateAccount(username, passwd string) (user models.User, err error) {
-	db := dbcore.GetDBInstance()
+	return CreateAccountWithDB(dbcore.GetDBInstance(), username, passwd)
+}
+
+func CreateAccountWithDB(db *gorm.DB, username, passwd string) (user models.User, err error) {
 	hashedPassword := hashPasswd(passwd)
 	user = models.User{
 		UUID:     uuid.New().String(),
@@ -71,7 +72,10 @@ func CreateAccount(username, passwd string) (user models.User, err error) {
 }
 
 func DeleteAccountByUsername(username string) (err error) {
-	db := dbcore.GetDBInstance()
+	return DeleteAccountByUsernameWithDB(dbcore.GetDBInstance(), username)
+}
+
+func DeleteAccountByUsernameWithDB(db *gorm.DB, username string) (err error) {
 	err = db.Where("username = ?", username).Delete(&models.User{}).Error
 	if err != nil {
 		return err
@@ -79,39 +83,6 @@ func DeleteAccountByUsername(username string) (err error) {
 	return nil
 }
 
-// 创建默认管理员账户，使用环境变量 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 GetUserByUUID(uuid string) (user models.User, err error) {
 	db := dbcore.GetDBInstance()
 	err = db.Where("uuid = ?", uuid).First(&user).Error
@@ -171,7 +142,7 @@ func UpdateUser(uuid string, name, password, sso_type *string) error {
 	if sso_type != nil {
 		updates["sso_type"] = *sso_type
 	}
-	updates["updated_at"] = time.Now()
+	updates["updated_at"] = time.Now().UTC()
 	err := db.Model(&models.User{}).Where("uuid = ?", uuid).Updates(updates).Error
 	if err != nil {
 		return err

database/accounts/sessions.go

@@ -9,7 +9,7 @@ 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"
@@ -33,11 +33,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)
@@ -50,7 +50,7 @@ func CreateSession(uuid string, expires int, userAgent, ip, login_method string)
 			}
 			messageSender.SendEvent(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:   "🔑",
 			})
@@ -73,7 +73,7 @@ func GetSession(session string) (uuid string, err error) {
 		return "", err
 	}
 
-	if time.Now().After(sessionRecord.Expires.ToTime()) {
+	if time.Now().UTC().After(sessionRecord.Expires) {
 		// 会话已过期，删除它
 		_ = DeleteSession(session)
 		return "", errors.New("session expired")
@@ -111,24 +111,10 @@ func DeleteAllSessions() 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
-}
-
 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,7 +122,7 @@ func UpdateLatest(session, useragent, ip string) error {
 
 func RemoveExpiredSessions() error {
 	db := dbcore.GetDBInstance()
-	result := db.Where("expires < ?", time.Now()).Delete(&models.Session{})
+	result := db.Where("expires < ?", time.Now().UTC()).Delete(&models.Session{})
 	if result.Error != nil {
 		return result.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,7 +11,6 @@ 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"
 )
@@ -37,7 +36,7 @@ func SaveClientInfo(update map[string]interface{}) error {
 		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) {
@@ -122,24 +121,6 @@ func SaveClientInfo(update map[string]interface{}) error {
 	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
-}
-
 // CreateClient 创建新客户端
 func CreateClient() (clientUUID, token string, err error) {
 	db := dbcore.GetDBInstance()
@@ -150,8 +131,8 @@ 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
@@ -159,7 +140,7 @@ func CreateClient() (clientUUID, token string, err error) {
 		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,8 +156,8 @@ 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
@@ -184,7 +165,7 @@ func CreateClientWithName(name string) (clientUUID, token string, err error) {
 		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
 }
@@ -210,19 +191,6 @@ func GetClientByUUID(uuid string) (client models.Client, err error) {
 	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()
 	var client models.Client
@@ -261,8 +229,30 @@ func SaveClient(updates map[string]interface{}) error {
 			}
 		}
 	}
+	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")
+		}
+	}
 
-	updates["updated_at"] = time.Now()
+	updates["updated_at"] = time.Now().UTC()
 
 	err := db.Model(&models.Client{}).Where("uuid = ?", clientUUID).Updates(updates).Error
 	if err != nil {

database/clients/report_test.go

@@ -1,28 +0,0 @@
-package clients
-
-import (
-	"testing"
-
-	"github.com/komari-monitor/komari/utils"
-	"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, utils.ComputeTrafficDelta(test.current, test.previous))
-		})
-	}
-}

database/clipboard/clipboard.go

@@ -1,6 +1,8 @@
 package clipboard
 
 import (
+	"time"
+
 	"github.com/komari-monitor/komari/database/dbcore"
 	"github.com/komari-monitor/komari/database/models"
 )
@@ -8,6 +10,8 @@ import (
 // CreateClipboard 创建剪贴板记录
 func CreateClipboard(cb *models.Clipboard) error {
 	db := dbcore.GetDBInstance()
+	cb.CreatedAt = time.Now().UTC()
+	cb.UpdatedAt = cb.CreatedAt
 	return db.Create(cb).Error
 }
 
@@ -24,6 +28,8 @@ func GetClipboardByID(id int) (*models.Clipboard, error) {
 // UpdateClipboardFields 更新剪贴板记录
 func UpdateClipboardFields(id int, fields map[string]interface{}) error {
 	db := dbcore.GetDBInstance()
+	delete(fields, "created_at")
+	fields["updated_at"] = time.Now().UTC()
 	return db.Model(&models.Clipboard{}).Where("id = ?", id).Updates(fields).Error
 }
 

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"
 )
@@ -176,6 +176,13 @@ var (
 // 也避免额外的裸文件依赖。
 const SystemVersionKey = "system_version"
 
+const (
+	mainSQLiteBusyTimeout       = 5 * time.Second
+	mainSQLiteCacheSizeKB       = 8 * 1024
+	mainSQLiteWALAutoCheckpoint = 256
+	mainSQLiteJournalSizeLimit  = 1 << 20
+)
+
 // versionID 是当前构建的版本标识，由 SetVersionID 在 Initialize 前注入。
 var versionID string
 
@@ -200,7 +207,7 @@ func resolveDatabaseFile() string {
 }
 
 // backupOnVersionUpgrade 在检测到版本升级时，把当前 ./data 打包到
-// ./backup/upgrade-{time}.zip，便于升级（含 metrics 迁移）异常时回滚。
+// ./data/backup/upgrade-{time}.zip，便于升级（含 metrics 迁移）异常时回滚。
 //
 // 版本标识存放于配置库（configs 表，键 system_version），因此本函数必须在
 // config.SetDb 之后、一次性 metrics 迁移（InitStores）之前调用。
@@ -240,18 +247,19 @@ func backupOnVersionUpgrade() {
 		instance.Exec("PRAGMA wal_checkpoint(TRUNCATE);")
 	}
 
-	if err := os.MkdirAll("./backup", 0755); err != nil {
-		log.Printf("[upgrade-backup] failed to create backup dir: %v", err)
+	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().Format("20060102-150405")
-	bakPath := filepath.Join("./backup", fmt.Sprintf("upgrade-%s.zip", tsName))
+	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: {}}); zipErr != nil {
-		log.Printf("[upgrade-backup] failed to backup ./data before upgrade (from %q to %q): %v", prevVersion, versionID, zipErr)
+	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
 	}
-	log.Printf("[upgrade-backup] ./data backed up to %s before upgrade (from %q to %q)", bakPath, prevVersion, versionID)
+	logger.Infof("dbcore", "[upgrade-backup] ./data backed up to %s before upgrade (from %q to %q)", bakPath, prevVersion, versionID)
 
 	writeVersionMarker()
 }
@@ -259,7 +267,7 @@ func backupOnVersionUpgrade() {
 // writeVersionMarker 将当前 versionID 写入配置库。
 func writeVersionMarker() {
 	if err := config.Set(SystemVersionKey, versionID); err != nil {
-		log.Printf("[upgrade-backup] failed to persist version marker: %v", err)
+		logger.Errorf("dbcore", "[upgrade-backup] failed to persist version marker: %v", err)
 	}
 }
 
@@ -268,7 +276,7 @@ func buildSQLiteDSN(databaseFile string) string {
 		databaseFile = "./data/komari.db"
 	}
 
-	params := "_busy_timeout=5000&_txlock=immediate&_journal_mode=WAL&_synchronous=NORMAL"
+	params := fmt.Sprintf("_busy_timeout=%d&_txlock=immediate", mainSQLiteBusyTimeout.Milliseconds())
 	separator := "?"
 	if strings.Contains(databaseFile, "?") {
 		separator = "&"
@@ -285,6 +293,19 @@ func buildSQLiteDSN(databaseFile string) string {
 	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 命令中做隔离。
@@ -300,7 +321,7 @@ func Initialize() error {
 // 需要错误处理的启动流程应优先调用 Initialize()。
 func GetDBInstance() *gorm.DB {
 	if err := Initialize(); err != nil {
-		log.Fatalf("Failed to initialize database: %v", err)
+		logger.Fatalf("dbcore", "Failed to initialize database: %v", err)
 	}
 	return instance
 }
@@ -324,42 +345,43 @@ func doInitialize() error {
 	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)
+			// 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().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)
+				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 {
-					log.Printf("[restore] current data zipped to %s", bakPath)
+					logger.Infof("dbcore", "[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)
+			// 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 {
-				log.Printf("[restore] failed to unzip backup into data: %v", unzipErr)
+				logger.Errorf("dbcore", "[restore] failed to unzip backup into data: %v", unzipErr)
 			} else {
-				log.Printf("[restore] backup.zip extracted to ./data")
+				logger.Infof("dbcore", "[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)
+				logger.Errorf("dbcore", "[restore] failed to remove backup.zip: %v", rmErr)
 			} else {
-				log.Printf("[restore] backup.zip removed")
+				logger.Infof("dbcore", "[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)
+				logger.Errorf("dbcore", "[restore] failed to remove komari-backup-markup: %v", rmErr)
 			} else {
-				log.Printf("[restore] komari-backup-markup removed")
+				logger.Infof("dbcore", "[restore] komari-backup-markup removed")
 			}
 		}
 	}()
@@ -372,47 +394,36 @@ func doInitialize() error {
 	}
 
 	logConfig := &gorm.Config{
-		Logger: logutil.NewGormLogger(),
+		Logger:  logger.NewGormLogger(),
+		NowFunc: func() time.Time { return time.Now().UTC() },
 	}
 
 	// 根据数据库类型选择不同的连接方式
 	switch flags.ApplyDatabaseTypeNormalization() {
 	case flags.DatabaseTypeSQLite:
-		// SQLite 连接
-		// 通过 DSN 传入 _busy_timeout / _txlock 等参数，确保连接池中的每一条连接
-		// 都生效：
-		//   - _busy_timeout=5000：遇到写锁时最多等待 5s 再返回，避免瞬时
-		//     "database is locked" 直接失败（仅靠后续 PRAGMA Exec 只作用于
-		//     当时执行该语句的单条连接，池内其它连接不生效）。
-		//   - _txlock=immediate：事务一开始即获取写锁，避免「先 SELECT 后写」
-		//     的锁升级在并发写入下产生死锁式的立即 SQLITE_BUSY。
-		//   - _journal_mode=WAL / _synchronous=NORMAL：与下方 PRAGMA 保持一致，
-		//     在 DSN 层为所有连接预设。
+		// _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)
-		instance, err = gorm.Open(sqlite.Open(dsn), logConfig)
+		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)
 		}
-		log.Printf("Using SQLite database file: %s", flags.DatabaseFile)
-		if sqlDB, dbErr := instance.DB(); dbErr == nil {
-			// SQLite 同一时刻只允许一个写者；限制连接数可避免连接池层面的写写竞争。
-			// 负载历史每分钟会执行包含读和写的事务，若连接池允许多个连接，容易与
-			// ping 结果等短写入撞锁并导致整批负载记录回滚。
-			sqlDB.SetMaxOpenConns(1)
-			sqlDB.SetMaxIdleConns(1)
-			sqlDB.SetConnMaxLifetime(0)
-		} else {
-			log.Printf("Failed to access underlying sql.DB for SQLite tuning: %v", dbErr)
+		if err := instance.Exec("PRAGMA wal_checkpoint(TRUNCATE)").Error; err != nil {
+			logger.Errorf("dbcore", "Failed to checkpoint SQLite WAL at startup: %v", err)
 		}
-		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 busy_timeout = 5000;")
-		instance.Exec("PRAGMA cache_size = -65536;")
-		instance.Exec("PRAGMA temp_store = MEMORY;")
-		instance.Exec("PRAGMA wal_checkpoint(TRUNCATE);")
 	default:
 		return fmt.Errorf("unsupported database type: %s (supported: %s)", flags.DatabaseType, flags.SupportedDatabaseTypes())
 	}
@@ -421,7 +432,7 @@ func doInitialize() error {
 	}
 	config.SetDb(instance)
 
-	// 配置库就绪后、执行后续 AutoMigrate 与一次性 metrics 迁移之前：
+	// 配置库就绪后、执行后续 AutoMigrate 之前：
 	// 基于配置中的版本标记检测升级并自动备份 ./data，便于回滚。
 	backupOnVersionUpgrade()
 
@@ -430,7 +441,7 @@ func doInitialize() error {
 	// 注意：负载/GPU/ping 历史监控数据运行期全部走 metric store（默认 SQLite
 	// ./data/metrics.db，或配置的 MySQL/PostgreSQL）。旧的 records /
 	// records_long_term / gpu_records / ping_records 表不再建表、不再写入。
-	// 若升级时旧表仍存在，会在 pkg/migrations.RunMetricStoreMigrations 中先导入再清理。
+	// 若升级时旧表仍存在，管理员可通过升级向导显式导入并清理。
 	// models.Record / models.PingRecord / models.GPURecord 结构体仍作为
 	// metric store 的读写 DTO 和旧表导入 DTO 保留在 models 包中。
 
@@ -453,13 +464,13 @@ func doInitialize() error {
 	if err := instance.AutoMigrate(
 		&models.Session{},
 	); err != nil {
-		log.Printf("Failed to create Session table, it may already exist: %v", err)
+		logger.Errorf("dbcore", "Failed to create Session table, it may already exist: %v", err)
 	}
 	if err := instance.AutoMigrate(
 		&models.Task{},
 		&models.TaskResult{},
 	); err != nil {
-		log.Printf("Failed to create Task and TaskResult table, it may already exist: %v", err)
+		logger.Errorf("dbcore", "Failed to create Task and TaskResult table, it may already exist: %v", err)
 	}
 
 	return nil

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/metricstore/maintenance.go

@@ -37,10 +37,10 @@ type MaintenanceResult struct {
 // 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.Acquire(ctx); err != nil {
+	if err := storeOperations.AcquireShared(ctx); err != nil {
 		return StorageInfo{}, fmt.Errorf("wait for metric store operations before inspection: %w", err)
 	}
-	defer storeOperations.Release()
+	defer storeOperations.ReleaseShared()
 
 	storeMu.RLock()
 	activeStore := store
@@ -59,8 +59,8 @@ func InspectStorage(ctx context.Context) (StorageInfo, error) {
 }
 
 // ReclaimSpace performs the driver-specific physical maintenance operation.
-// It shares the exclusive operation lock with Compact so retention compaction
-// and a table/file rewrite can never run against the metric store concurrently.
+// 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) {
 	if !storeOperations.TryAcquire() {
 		storeMu.RLock()

database/metricstore/maintenance_test.go

@@ -2,7 +2,9 @@ package metricstore
 
 import (
 	"context"
+	"database/sql"
 	"errors"
+	"path/filepath"
 	"testing"
 	"time"
 
@@ -40,6 +42,54 @@ func TestInspectAndReclaimStorage(t *testing.T) {
 	}
 }
 
+func TestRetryMetricWALCheckpointDefersBusyReader(t *testing.T) {
+	ctx := context.Background()
+	path := filepath.Join(t.TempDir(), "checkpoint.db")
+	s, err := metric.Open(ctx, metric.SQLite(path, metric.WithSQLiteWALAutoCheckpoint(1_000_000)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = s.Close() })
+	if err := s.CreateMetric(ctx, metric.Definition{Name: "before", Type: metric.TypeGauge, RetentionDays: 1}); err != nil {
+		t.Fatal(err)
+	}
+
+	reader, err := sql.Open("sqlite3", path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = reader.Close() })
+	tx, err := reader.BeginTx(ctx, &sql.TxOptions{ReadOnly: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var definitions int
+	if err := tx.QueryRowContext(ctx, `SELECT COUNT(*) FROM metric_definitions`).Scan(&definitions); err != nil {
+		_ = tx.Rollback()
+		t.Fatal(err)
+	}
+	if err := s.CreateMetric(ctx, metric.Definition{Name: "after", Type: metric.TypeGauge, RetentionDays: 1}); err != nil {
+		_ = tx.Rollback()
+		t.Fatal(err)
+	}
+
+	previousPending := checkpointPending
+	checkpointPending = true
+	t.Cleanup(func() { checkpointPending = previousPending })
+	retryMetricWALCheckpoint(ctx, s)
+	if !checkpointPending {
+		_ = tx.Rollback()
+		t.Fatal("busy reader unexpectedly cleared pending checkpoint")
+	}
+	if err := tx.Rollback(); err != nil {
+		t.Fatal(err)
+	}
+	retryMetricWALCheckpoint(ctx, s)
+	if checkpointPending {
+		t.Fatal("checkpoint remained pending after reader released")
+	}
+}
+
 func TestReclaimSpaceReportsBusyStore(t *testing.T) {
 	s, err := metric.Open(context.Background(), metric.SQLite(":memory:"))
 	if err != nil {
@@ -47,10 +97,10 @@ func TestReclaimSpaceReportsBusyStore(t *testing.T) {
 	}
 	installTestStore(t, s)
 
-	if !storeOperations.TryAcquire() {
-		t.Fatal("acquire store operation gate")
+	if err := storeOperations.AcquireShared(context.Background()); err != nil {
+		t.Fatalf("acquire shared store operation gate: %v", err)
 	}
-	defer storeOperations.Release()
+	defer storeOperations.ReleaseShared()
 
 	result, err := ReclaimSpace(context.Background())
 	if !errors.Is(err, ErrStoreBusy) {
@@ -62,8 +112,17 @@ func TestReclaimSpaceReportsBusyStore(t *testing.T) {
 	if !errors.Is(result.BeforeSizeError, ErrStoreBusy) || !errors.Is(result.AfterSizeError, ErrStoreBusy) {
 		t.Fatalf("busy result should mark both measurements unavailable: %#v", result)
 	}
+	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("compact error = %v, want %v", err, ErrCompactInProgress)
+		t.Fatalf("overlapping compact error = %v, want %v", err, ErrCompactInProgress)
 	}
 }
 

database/metricstore/metrics.go

@@ -0,0 +1,100 @@
+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,
+}
+
+var obsoleteBuiltinMetricNames = []string{
+	"memory.total",
+	"swap.total",
+	"temperature",
+	"disk.total",
+}
+
+// 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}
+
+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
+}

database/metricstore/metricstore_test.go

@@ -2,27 +2,31 @@ package metricstore
 
 import (
 	"context"
+	"database/sql"
+	"errors"
+	"path/filepath"
 	"testing"
 	"time"
 
 	"github.com/komari-monitor/komari/database/models"
 	"github.com/komari-monitor/komari/pkg/metric"
+	v1 "github.com/komari-monitor/komari/protocol/v1"
 )
 
 func TestDefaultRollupPolicy(t *testing.T) {
-	policy := defaultRollupPolicy(30)
+	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) != 3 {
-		t.Fatalf("expected 3 rollup tiers, got %d", len(policy.Tiers))
+	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}
-	wantRetentions := []time.Duration{48 * time.Hour, 14 * 24 * time.Hour, 30 * 24 * time.Hour}
+	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])
@@ -35,11 +39,9 @@ func TestDefaultRollupPolicy(t *testing.T) {
 
 func TestBuildMetricConfigEnablesDefaultRollupPolicy(t *testing.T) {
 	cfg, err := buildMetricConfig(&MetricStoreConfig{
-		Driver:              "sqlite",
-		DSN:                 ":memory:",
-		RetentionDays:       30,
-		DownsamplingEnabled: true,
-		TablePrefix:         "metric_",
+		Driver:      "sqlite",
+		DSN:         ":memory:",
+		TablePrefix: "metric_",
 	}, false)
 	if err != nil {
 		t.Fatalf("build metric config: %v", err)
@@ -50,51 +52,289 @@ func TestBuildMetricConfigEnablesDefaultRollupPolicy(t *testing.T) {
 	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 TestBuildMetricConfigDefaultsRetentionToNinetyDays(t *testing.T) {
+func TestBuildMetricConfigLeavesFinalRetentionToMetricDefinition(t *testing.T) {
 	cfg, err := buildMetricConfig(&MetricStoreConfig{
-		Driver:              "sqlite",
-		DSN:                 ":memory:",
-		DownsamplingEnabled: true,
+		Driver: "sqlite",
+		DSN:    ":memory:",
 	}, false)
 	if err != nil {
 		t.Fatalf("build metric config: %v", err)
 	}
-	if cfg.DefaultRetentionDays != DefaultMetricRetentionDays {
-		t.Fatalf(
-			"default retention = %d, want %d",
-			cfg.DefaultRetentionDays,
-			DefaultMetricRetentionDays,
-		)
-	}
-	wantRollupRetention := time.Duration(DefaultMetricRetentionDays) * 24 * time.Hour
+	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 TestBuildMetricConfigCanDisableDownsampling(t *testing.T) {
+func TestBuildMetricConfigAlwaysEnablesDownsampling(t *testing.T) {
 	cfg, err := buildMetricConfig(&MetricStoreConfig{
-		Driver:              "sqlite",
-		DSN:                 ":memory:",
-		DownsamplingEnabled: false,
+		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 disabled")
+	if !cfg.RollupPolicy.Enabled() {
+		t.Fatal("expected rollup policy to be enabled")
 	}
 }
 
-func TestCompactCleansExpiredRawPointsWhenDownsamplingDisabled(t *testing.T) {
+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 TestCreateMetricDefinitionsRemovesObsoleteMetrics(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)
+	}
+	if _, err := s.GetMetric(ctx, "memory.total"); !errors.Is(err, metric.ErrNotFound) {
+		t.Fatalf("obsolete definition error = %v, want ErrNotFound", err)
+	}
+	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 obsolete points: %v", err)
+	}
+	if len(points) != 0 {
+		t.Fatalf("obsolete points remain: %#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,
@@ -103,10 +343,10 @@ func TestCompactCleansExpiredRawPointsWhenDownsamplingDisabled(t *testing.T) {
 		t.Fatalf("upsert metric: %v", err)
 	}
 
-	now := time.Date(2026, 7, 11, 12, 0, 0, 0, time.UTC)
+	now := time.Now().UTC()
 	if err := s.WriteBatch(ctx, []metric.Point{
-		{MetricName: "raw.metric", EntityID: "node", Timestamp: now.Add(-48 * time.Hour), Value: 1},
-		{MetricName: "raw.metric", EntityID: "node", Timestamp: now.Add(-time.Hour), Value: 2},
+		{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)
 	}
@@ -131,7 +371,7 @@ func TestCompactCleansExpiredRawPointsWhenDownsamplingDisabled(t *testing.T) {
 	points, err := s.Query(ctx, metric.Query{
 		MetricName: "raw.metric",
 		EntityID:   "node",
-		Start:      now.Add(-72 * time.Hour),
+		Start:      now.Add(-time.Hour),
 		End:        now,
 	})
 	if err != nil {
@@ -142,11 +382,80 @@ func TestCompactCleansExpiredRawPointsWhenDownsamplingDisabled(t *testing.T) {
 	}
 }
 
+func TestCompactContinuesAfterOneMetricFails(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
+	previousCompactAt := compactAt
+	store = s
+	compactAt = 0
+	storeMu.Unlock()
+	t.Cleanup(func() {
+		storeMu.Lock()
+		store = previousStore
+		compactAt = previousCompactAt
+		storeMu.Unlock()
+	})
+
+	if _, err := Compact(ctx, now); err == nil {
+		t.Fatal("expected malformed metric to fail compaction")
+	}
+	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("healthy metric was blocked by another metric failure: %#v", points)
+	}
+}
+
 func TestCompactKeepsRotatingCursorAfterFullCycle(t *testing.T) {
 	ctx := context.Background()
 	s, err := metric.Open(ctx, metric.SQLite(":memory:",
 		metric.WithMaxOpenConns(1),
-		metric.WithRollupPolicy(defaultRollupPolicy(30)),
+		metric.WithRollupPolicy(defaultRollupPolicy()),
 	))
 	if err != nil {
 		t.Fatalf("open metric store: %v", err)
@@ -183,7 +492,7 @@ func TestGetRecordsByClientAndTimeReadsRollupsAfterRawCompaction(t *testing.T) {
 	ctx := context.Background()
 	s, err := metric.Open(ctx, metric.SQLite(":memory:",
 		metric.WithMaxOpenConns(1),
-		metric.WithRollupPolicy(defaultRollupPolicy(30)),
+		metric.WithRollupPolicy(defaultRollupPolicy()),
 	))
 	if err != nil {
 		t.Fatalf("open metric store: %v", err)
@@ -210,7 +519,7 @@ func TestGetRecordsByClientAndTimeReadsRollupsAfterRawCompaction(t *testing.T) {
 	ts := now.Add(-time.Hour)
 	rec := models.Record{
 		Client:         "node-a",
-		Time:           models.FromTime(ts),
+		Time:           ts,
 		Cpu:            42.5,
 		Ram:            123456,
 		RamTotal:       999999,
@@ -220,25 +529,24 @@ func TestGetRecordsByClientAndTimeReadsRollupsAfterRawCompaction(t *testing.T) {
 		Connections:    321,
 		ConnectionsUdp: 12,
 	}
-	if err := WriteRecord(ctx, rec); err != nil {
+	if _, err := WriteReport(ctx, v1.Report{
+		UUID:      rec.Client,
+		UpdatedAt: ts,
+		CPU:       v1.CPUReport{Usage: float64(rec.Cpu)},
+		Ram:       v1.RamReport{Used: rec.Ram, Total: rec.RamTotal},
+		Load:      v1.LoadReport{Load1: float64(rec.Load)},
+		Disk:      v1.DiskReport{Used: rec.Disk, Total: rec.DiskTotal},
+		Process:   rec.Process,
+		Connections: v1.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)
 	}
-	raw, err := s.Query(ctx, metric.Query{
-		MetricName: MetricCPU,
-		EntityID:   rec.Client,
-		Start:      ts.Add(-time.Minute),
-		End:        now,
-	})
-	if err != nil {
-		t.Fatalf("query raw cpu: %v", err)
-	}
-	if len(raw) != 0 {
-		t.Fatalf("expected old raw cpu point to be deleted after compaction, got %d", len(raw))
-	}
-
 	got, err := GetRecordsByClientAndTime(ctx, rec.Client, ts.Add(-time.Minute), now)
 	if err != nil {
 		t.Fatalf("get records: %v", err)
@@ -258,3 +566,41 @@ func TestGetRecordsByClientAndTimeReadsRollupsAfterRawCompaction(t *testing.T) {
 		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)
+	}
+}

database/metricstore/migration.go

@@ -1,72 +0,0 @@
-package metricstore
-
-import (
-	"fmt"
-	"log"
-	"strings"
-
-	"github.com/komari-monitor/komari/pkg/config"
-)
-
-// migration.go
-//
-// 启动阶段的 metrics 数据迁移。这里只处理 metrics 存储后端切换时的数据搬运
-// （例如默认 SQLite ./data/metrics.db 切换到 MySQL/PostgreSQL）。旧 komari.db
-// 监控表导入属于一次性迁移，见 pkg/migrations.RunMetricStoreMigrations。
-
-// targetFingerprint 返回当前 metrics 目标库的指纹（driver + 归一化 DSN），
-// 用于判断 metrics 存储后端是否发生变化（例如从 SQLite 切换到 MySQL/PostgreSQL）。
-func targetFingerprint(cfg *MetricStoreConfig) string {
-	driver := ResolveDriverFromConfig(cfg.Driver, cfg.DSN)
-	dsn := strings.TrimSpace(cfg.DSN)
-	return fmt.Sprintf("%s|%s", driver, dsn)
-}
-
-// RunStartupMigration 在服务启动时检查 metrics 存储后端是否发生变化，
-// 若变化则把上一个 metrics 目标库的全部数据搬运到当前目标。
-//
-// 判定依据 MigrationTargetKey（记录“数据当前完整所在的 metrics 目标指纹”）：
-//   - saved == current：数据已在当前目标，无需处理。
-//   - saved == ""：无历史目标记录。老快照的 metrics 数据固定落在默认 SQLite
-//     （./data/metrics.db）；若当前目标不是默认 SQLite（例如已切到 MySQL/PostgreSQL），
-//     把默认 SQLite 中可能存在的历史数据搬运过来，否则仅登记指纹。
-//   - saved != current：后端已切换，把上一个目标（saved）的数据搬运到当前目标。
-//
-// 搬运以 upsert 写入，幂等，中断后重启可安全重跑。任一失败都返回错误，
-// 调用方应让启动失败并打印明确错误。
-func RunStartupMigration() error {
-	s := GetStore()
-	if s == nil {
-		return fmt.Errorf("metric store not initialized")
-	}
-
-	cfg, err := config.GetManyAs[MetricStoreConfig]()
-	if err != nil {
-		return fmt.Errorf("failed to load metric store config: %w", err)
-	}
-
-	current := targetFingerprint(cfg)
-	saved, _ := config.GetAs[string](MigrationTargetKey, "")
-
-	// 数据已完整位于当前目标：无需搬运。
-	if saved == current {
-		return nil
-	}
-
-	// 上一个目标：优先使用已保存指纹；无记录时按老快照默认 SQLite 推断。
-	prev := saved
-	if prev == "" {
-		prev = defaultSQLiteFingerprint()
-	}
-
-	if prev != current {
-		if err := migrateFromPreviousStore(prev, cfg, s); err != nil {
-			return err
-		}
-	}
-
-	if err := config.Set(MigrationTargetKey, current); err != nil {
-		log.Printf("Failed to persist migration target fingerprint: %v", err)
-	}
-	return nil
-}

database/metricstore/migration_store.go

@@ -3,16 +3,13 @@ package metricstore
 import (
 	"context"
 	"fmt"
-	"log"
 	"strings"
-	"time"
 
 	"github.com/komari-monitor/komari/pkg/metric"
+	logger "github.com/komari-monitor/komari/utils/log"
 )
 
-// storeMigrationWindow 是 store-to-store 迁移时按时间分窗查询的窗口大小。
-// 采样点按时间窗口分批拉取，避免一次性把整段序列读入内存。
-const storeMigrationWindow = 6 * time.Hour
+const storeMigrationBatchSize = 500
 
 // configFromFingerprint 从目标指纹（driver|dsn）重建一个 MetricStoreConfig，
 // 用于以只读方式打开“上一次的 metrics 目标库”。表前缀、保留天数、连接数等
@@ -28,22 +25,19 @@ func configFromFingerprint(fingerprint string, base *MetricStoreConfig) (*Metric
 		return nil, fmt.Errorf("empty driver in target fingerprint: %q", fingerprint)
 	}
 	return &MetricStoreConfig{
-		Driver:              driver,
-		DSN:                 dsn,
-		RetentionDays:       base.RetentionDays,
-		DownsamplingEnabled: base.DownsamplingEnabled,
-		TablePrefix:         base.TablePrefix,
-		MaxOpenConns:        base.MaxOpenConns,
-		MaxIdleConns:        base.MaxIdleConns,
+		Driver:       driver,
+		DSN:          dsn,
+		TablePrefix:  base.TablePrefix,
+		MaxOpenConns: base.MaxOpenConns,
+		MaxIdleConns: base.MaxIdleConns,
 	}, nil
 }
 
 // openSourceStore 打开一个已存在的 metrics 目标库作为数据搬运的源库读取。
 //
-// 使用 autoMigrate=true：GORM 的 AutoMigrate 只新增表/列/索引、从不删除数据，
-// 因此对真实旧库幂等无害；而当源库文件/表不存在（例如老快照记录了 completed
-// 但 metrics.db 缺失）时，可创建空表让后续 ListMetrics 返回空集而非报
-// "no such table"，从而把“无历史可迁移”识别为正常情况而非错误。
+// 使用 autoMigrate=true 确保规范化表和索引存在；创建语句不会删除已有数据。
+// 当源库文件/表不存在（例如老快照记录了 completed 但 metrics.db 缺失）时，
+// 创建空表可让后续 ListMetrics 返回空集，把“无历史可迁移”识别为正常情况。
 func openSourceStore(ctx context.Context, cfg *MetricStoreConfig) (*metric.Store, error) {
 	metricCfg, err := buildMetricConfig(cfg, true)
 	if err != nil {
@@ -59,9 +53,10 @@ func defaultSQLiteFingerprint() string {
 }
 
 // migrateFromPreviousStore 打开由 prevFingerprint 指定的上一个 metrics 目标库作为源，
-// 把其中的全部指标搬运到当前目标 dst（例如 SQLite metrics.db → MySQL/PostgreSQL）。
+// 把其中的全部指标定义和持久化 rollup 搬运到当前目标 dst（例如 SQLite
+// metrics.db → MySQL/PostgreSQL）。
 //
-// 该过程幂等：dst 以 (metric, entity, tags, ts) upsert 写入，中断后重启可安全重跑。
+// 该过程幂等：dst 以 (series, resolution, labels, bucket) upsert 写入，中断后重启可安全重跑。
 func migrateFromPreviousStore(prevFingerprint string, cfg *MetricStoreConfig, dst *metric.Store) error {
 	prevCfg, err := configFromFingerprint(prevFingerprint, cfg)
 	if err != nil {
@@ -75,12 +70,12 @@ func migrateFromPreviousStore(prevFingerprint string, cfg *MetricStoreConfig, ds
 	}
 	defer src.Close()
 
-	log.Printf("Migrating metrics from previous store %s to current target...", prevFingerprint)
+	logger.Infof("metricstore", "Migrating metrics from previous store %s to current target...", prevFingerprint)
 	total, err := MigrateBetweenStores(ctx, src, dst)
 	if err != nil {
 		return fmt.Errorf("store-to-store metrics migration failed: %w", err)
 	}
-	log.Printf("Store-to-store metrics migration completed (%d points)", total)
+	logger.Infof("metricstore", "Store-to-store metrics migration completed (%d rollups)", total)
 	return nil
 }
 
@@ -88,24 +83,24 @@ func migrateFromPreviousStore(prevFingerprint string, cfg *MetricStoreConfig, ds
 //   - currentMetric：当前正在搬运的指标名。
 //   - metricIndex：该指标在全部指标中的序号（0 起），即已完成的指标数。
 //   - totalMetrics：指标定义总数。
-//   - addedPoints：本次新写入目标库的采样点数（用于外部累计）。
+//   - addedPoints：本次新写入目标库的 rollup 行数（用于外部累计）。
 type storeMigrationObserver func(currentMetric string, metricIndex, totalMetrics int, addedPoints int64)
 
-// MigrateBetweenStores 把 src metric store 的全部指标定义与采样点搬运到 dst。
+// MigrateBetweenStores 把 src metric store 的全部指标定义与持久化 rollup 搬运到 dst。
 //
 // 用于 metrics 后端切换（例如默认 SQLite metrics.db → MySQL/PostgreSQL）：
 //   - 先在 dst 建立/更新全部指标定义；
-//   - 再按指标、按时间窗口分批读取源库采样点并写入 dst。
+//   - 再按指标流式读取源库 rollup 并分批写入 dst。
 //
-// 采样点在 dst 以 (metric_name, entity_id, tags, ts) upsert 写入，窗口边界重叠也
-// 幂等，因此整个过程可安全重试。返回搬运的采样点总数。
+// rollup 在 dst 以 (series, resolution, labels, bucket) upsert 写入，因此整个
+// 过程可安全重试。返回搬运的 rollup 行数。
 func MigrateBetweenStores(ctx context.Context, src, dst *metric.Store) (int64, error) {
 	return migrateBetweenStores(ctx, src, dst, nil)
 }
 
 // migrateBetweenStores 是 MigrateBetweenStores 的内部实现，额外接受一个可选的进度
-// 观察者 observe（为 nil 时行为与旧版本完全一致）。启动迁移走 nil，WebUI/API 触发
-// 的迁移传入回调以实时更新进度。
+// 观察者 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")
@@ -126,84 +121,29 @@ func migrateBetweenStores(ctx context.Context, src, dst *metric.Store, observe s
 		if err := dst.UpsertMetric(ctx, def); err != nil {
 			return total, fmt.Errorf("upsert metric %q on target: %w", def.Name, err)
 		}
-
-		earliest, latest, ok, err := metricTimeBounds(ctx, src, def.Name)
-		if err != nil {
-			return total, fmt.Errorf("resolve time bounds for metric %q: %w", def.Name, err)
-		}
-		if !ok {
-			// 该指标只有定义没有数据，跳过。
+		if def.RetentionDays == 0 {
 			continue
 		}
-
 		var migrated int64
-		for windowStart := earliest; !windowStart.After(latest); windowStart = windowStart.Add(storeMigrationWindow) {
-			select {
-			case <-ctx.Done():
-				return total, ctx.Err()
-			default:
+		_, 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)
 			}
-
-			windowEnd := windowStart.Add(storeMigrationWindow)
-			points, err := src.Query(ctx, metric.Query{
-				MetricName: def.Name,
-				Start:      windowStart,
-				End:        windowEnd,
-				Order:      metric.OrderAsc,
-			})
-			if err != nil {
-				return total, fmt.Errorf("query metric %q window [%s,%s): %w", def.Name, windowStart, windowEnd, err)
-			}
-			if len(points) == 0 {
-				continue
-			}
-			if err := dst.WriteBatch(ctx, points); err != nil {
-				return total, fmt.Errorf("write metric %q batch to target: %w", def.Name, err)
-			}
-			migrated += int64(len(points))
-			total += int64(len(points))
+			count := int64(len(batch))
+			migrated += count
+			total += count
 			if observe != nil {
-				observe(def.Name, i, len(defs), int64(len(points)))
+				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 {
-			log.Printf("[store-migration] metric %q: migrated %d points", def.Name, migrated)
+			logger.Infof("metricstore", "[store-migration] metric %q: migrated %d rollups", def.Name, migrated)
 		}
 	}
 
 	return total, nil
 }
-
-// metricTimeBounds 返回某指标在 src 中最早/最晚采样时间。ok=false 表示无数据。
-// 通过升/降序各取一条采样点定位边界，避免把整段序列读入内存。
-func metricTimeBounds(ctx context.Context, src *metric.Store, name string) (time.Time, time.Time, bool, error) {
-	wide := metric.Query{
-		MetricName: name,
-		Start:      time.Unix(0, 0),
-		End:        time.Now().Add(24 * time.Hour),
-	}
-
-	asc := wide
-	asc.Order = metric.OrderAsc
-	asc.Limit = 1
-	first, err := src.Query(ctx, asc)
-	if err != nil {
-		return time.Time{}, time.Time{}, false, err
-	}
-	if len(first) == 0 {
-		return time.Time{}, time.Time{}, false, nil
-	}
-
-	desc := wide
-	desc.Order = metric.OrderDesc
-	desc.Limit = 1
-	last, err := src.Query(ctx, desc)
-	if err != nil {
-		return time.Time{}, time.Time{}, false, err
-	}
-	if len(last) == 0 {
-		return time.Time{}, time.Time{}, false, nil
-	}
-
-	return first[0].Timestamp, last[0].Timestamp, true, nil
-}

database/metricstore/migration_store_test.go

@@ -0,0 +1,152 @@
+package metricstore
+
+import (
+	"context"
+	"path/filepath"
+	"reflect"
+	"testing"
+	"time"
+
+	"github.com/komari-monitor/komari/pkg/metric"
+)
+
+func TestMigrateBetweenStoresCopiesPersistedRollupsAfterReopen(t *testing.T) {
+	ctx := context.Background()
+	policy := defaultRollupPolicy()
+	sourcePath := filepath.Join(t.TempDir(), "source.db")
+	source, err := metric.Open(ctx, metric.SQLite(sourcePath,
+		metric.WithMaxOpenConns(1),
+		metric.WithMaxIdleConns(1),
+		metric.WithRollupPolicy(policy),
+	))
+	if err != nil {
+		t.Fatalf("open source: %v", err)
+	}
+
+	definitions := []metric.Definition{
+		{Name: "a.metric", Description: "migrated definition", Type: metric.TypeGauge, Unit: "%", RetentionDays: 30, Metadata: map[string]string{"owner": "test"}},
+		{Name: "z.empty", Type: metric.TypeCounter, Unit: "bytes", RetentionDays: 7, Metadata: map[string]string{}},
+	}
+	for _, definition := range definitions {
+		if err := source.UpsertMetric(ctx, definition); err != nil {
+			t.Fatalf("upsert source metric %q: %v", definition.Name, err)
+		}
+	}
+
+	base := time.Date(2026, 7, 26, 12, 0, 0, 0, time.UTC)
+	digest := metric.NewTDigest(policy.Compression)
+	for _, value := range []float64{10, 20, 30} {
+		digest.Add(value, 1)
+	}
+	sourceRollups := []metric.PersistedRollup{
+		{
+			MetricName: "a.metric", EntityID: "agent-1", Tags: map[string]string{"device": "cpu0"}, Labels: map[string]string{"zone": "ap"},
+			Resolution: time.Minute, Bucket: base, Count: 3, Sum: 60, SumSq: 1400, Min: 10, Max: 30,
+			FirstValue: 10, FirstTime: base.Add(time.Second), LastValue: 30, LastTime: base.Add(40 * time.Second),
+			Digest: digest.Encode(), CreatedAt: base.Add(time.Hour),
+		},
+		{
+			MetricName: "a.metric", EntityID: "agent-2", Tags: map[string]string{}, Labels: map[string]string{"zone": "eu"},
+			Resolution: time.Hour, Bucket: base, Count: 12, Sum: 60, SumSq: 300, Min: 5, Max: 5,
+			FirstValue: 5, FirstTime: base.Add(time.Minute), LastValue: 5, LastTime: base.Add(50 * time.Minute),
+			CreatedAt: base.Add(time.Hour),
+		},
+	}
+	if err := source.ImportRollups(ctx, sourceRollups); err != nil {
+		t.Fatalf("seed source rollups: %v", err)
+	}
+	if err := source.Close(); err != nil {
+		t.Fatalf("close source: %v", err)
+	}
+
+	source, err = metric.Open(ctx, metric.SQLite(sourcePath,
+		metric.WithMaxOpenConns(1),
+		metric.WithMaxIdleConns(1),
+		metric.WithRollupPolicy(policy),
+	))
+	if err != nil {
+		t.Fatalf("reopen source: %v", err)
+	}
+	defer source.Close()
+	raw, err := source.Query(ctx, metric.Query{
+		MetricName: "a.metric", Start: base.Add(-time.Hour), End: base.Add(2 * time.Hour),
+	})
+	if err != nil {
+		t.Fatalf("query reopened raw window: %v", err)
+	}
+	if len(raw) != 0 {
+		t.Fatalf("reopened source raw points = %d, want 0", len(raw))
+	}
+
+	target, err := metric.Open(ctx, metric.SQLite(filepath.Join(t.TempDir(), "target.db"),
+		metric.WithMaxOpenConns(1),
+		metric.WithMaxIdleConns(1),
+		metric.WithRollupPolicy(policy),
+	))
+	if err != nil {
+		t.Fatalf("open target: %v", err)
+	}
+	defer target.Close()
+
+	type progressEvent struct {
+		metricName                string
+		metricIndex, totalMetrics int
+		added                     int64
+	}
+	var events []progressEvent
+	total, err := migrateBetweenStores(ctx, source, target, func(name string, index, definitions int, added int64) {
+		events = append(events, progressEvent{name, index, definitions, added})
+	})
+	if err != nil {
+		t.Fatalf("migrate stores: %v", err)
+	}
+	if total != int64(len(sourceRollups)) {
+		t.Fatalf("migrated rollups = %d, want %d", total, len(sourceRollups))
+	}
+	wantEvents := []progressEvent{
+		{metricName: "a.metric", metricIndex: 0, totalMetrics: 2},
+		{metricName: "a.metric", metricIndex: 0, totalMetrics: 2, added: 2},
+		{metricName: "z.empty", metricIndex: 1, totalMetrics: 2},
+	}
+	if !reflect.DeepEqual(events, wantEvents) {
+		t.Fatalf("migration events = %#v, want %#v", events, wantEvents)
+	}
+
+	for _, want := range definitions {
+		got, err := target.GetMetric(ctx, want.Name)
+		if err != nil {
+			t.Fatalf("get target metric %q: %v", want.Name, err)
+		}
+		if got.Name != want.Name || got.Description != want.Description || got.Type != want.Type || got.Unit != want.Unit || got.RetentionDays != want.RetentionDays || !reflect.DeepEqual(got.Metadata, want.Metadata) {
+			t.Fatalf("target definition = %#v, want mutable fields from %#v", got, want)
+		}
+	}
+
+	exported := exportMigrationTestRollups(t, target, "a.metric")
+	if !reflect.DeepEqual(exported, sourceRollups) {
+		t.Fatalf("target rollups differ:\n got: %#v\nwant: %#v", exported, sourceRollups)
+	}
+	secondTotal, err := MigrateBetweenStores(ctx, source, target)
+	if err != nil {
+		t.Fatalf("repeat migration: %v", err)
+	}
+	if secondTotal != total {
+		t.Fatalf("repeat migrated rollups = %d, want %d", secondTotal, total)
+	}
+	if got := exportMigrationTestRollups(t, target, "a.metric"); !reflect.DeepEqual(got, sourceRollups) {
+		t.Fatalf("repeat migration changed target rollups: %#v", got)
+	}
+}
+
+func exportMigrationTestRollups(t *testing.T, store *metric.Store, metricName string) []metric.PersistedRollup {
+	t.Helper()
+	var result []metric.PersistedRollup
+	_, err := store.ExportRollups(context.Background(), metricName, 1, func(batch []metric.PersistedRollup) error {
+		result = append(result, batch...)
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("export %q rollups: %v", metricName, err)
+	}
+	return result
+}

database/metricstore/operation_gate.go

@@ -1,38 +1,40 @@
 package metricstore
 
-import "context"
+import (
+	"context"
 
-// storeOperationGate serializes operations that need a stable active Store.
-// A channel-backed gate supports both non-blocking scheduled work and
-// context-aware admin/shutdown waits.
+	"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 {
-	token chan struct{}
+	semaphore *semaphore.Weighted
 }
 
+const storeOperationGateWeight int64 = 1024
+
 func newStoreOperationGate() *storeOperationGate {
-	gate := &storeOperationGate{token: make(chan struct{}, 1)}
-	gate.token <- struct{}{}
-	return gate
+	return &storeOperationGate{semaphore: semaphore.NewWeighted(storeOperationGateWeight)}
 }
 
 func (g *storeOperationGate) Acquire(ctx context.Context) error {
-	select {
-	case <-g.token:
-		return nil
-	case <-ctx.Done():
-		return ctx.Err()
-	}
+	return g.semaphore.Acquire(ctx, storeOperationGateWeight)
 }
 
 func (g *storeOperationGate) TryAcquire() bool {
-	select {
-	case <-g.token:
-		return true
-	default:
-		return false
-	}
+	return g.semaphore.TryAcquire(storeOperationGateWeight)
 }
 
 func (g *storeOperationGate) Release() {
-	g.token <- struct{}{}
+	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)
 }

database/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")
+	}
+}

database/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]@")
+}

database/metricstore/report.go

@@ -0,0 +1,519 @@
+package metricstore
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	logger "github.com/komari-monitor/komari/utils/log"
+	"strconv"
+	"sync"
+	"time"
+
+	"github.com/komari-monitor/komari/database/models"
+	"github.com/komari-monitor/komari/pkg/metric"
+	v1 "github.com/komari-monitor/komari/protocol/v1"
+)
+
+type reportTrafficState struct {
+	mu sync.Mutex
+
+	reportTrafficValues
+}
+
+type reportTrafficValues struct {
+	initialized bool
+	timestamp   time.Time
+	hasUp       bool
+	totalUp     int64
+	hasDown     bool
+	totalDown   int64
+}
+
+var reportTrafficStates sync.Map
+
+const (
+	reportBatchInterval     = 3 * time.Second
+	reportBatchQueueSize    = 4096
+	pingBatchMaxRecords     = 512
+	reportBatchWriteTimeout = 10 * time.Second
+)
+
+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 v1.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 v1.Report, reportBatchQueueSize),
+		pingQueue: make(chan models.PingRecord, reportBatchQueueSize),
+		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 v1.Report) (v1.Report, error) {
+	if report.UUID == "" {
+		return v1.Report{}, fmt.Errorf("report UUID is required")
+	}
+	if report.UpdatedAt.IsZero() {
+		return v1.Report{}, fmt.Errorf("report receive time is required")
+	}
+	report.UpdatedAt = report.UpdatedAt.UTC()
+	if GetStore() == nil {
+		return v1.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 v1.Report{}, err
+		}
+		return report, nil
+	}
+
+	saved, err := writeReportBatch(ctx, []v1.Report{report})
+	if err != nil {
+		return v1.Report{}, err
+	}
+	return saved[0], nil
+}
+
+func (w *reportBatchWorker) enqueue(ctx context.Context, report v1.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 []v1.Report
+	var pendingPings []models.PingRecord
+	for {
+		select {
+		case request := <-w.requests:
+			pending = append(pending, drainReportQueue(w.queue, reportBatchQueueSize)...)
+			pendingPings = append(pendingPings, drainPingQueue(w.pingQueue, reportBatchQueueSize)...)
+			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, drainPingQueue(w.pingQueue, reportBatchQueueSize)...)
+			if err := writePendingPingRecords(context.Background(), &pendingPings); err != nil {
+				logger.Errorf("metricstore", "failed to flush ping batch: %v", err)
+			}
+			pending = append(pending, drainReportQueue(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
+	}
+}
+
+func drainReportQueue(queue <-chan v1.Report, limit int) []v1.Report {
+	if limit <= 0 {
+		return nil
+	}
+	capacity := len(queue)
+	if capacity > limit {
+		capacity = limit
+	}
+	if capacity == 0 {
+		return nil
+	}
+	reports := make([]v1.Report, 0, capacity)
+	for len(reports) < limit {
+		select {
+		case report := <-queue:
+			reports = append(reports, report)
+		default:
+			return reports
+		}
+	}
+	return reports
+}
+
+func drainPingQueue(queue <-chan models.PingRecord, limit int) []models.PingRecord {
+	if limit <= 0 {
+		return nil
+	}
+	capacity := len(queue)
+	if capacity > limit {
+		capacity = limit
+	}
+	if capacity == 0 {
+		return nil
+	}
+	records := make([]models.PingRecord, 0, capacity)
+	for len(records) < limit {
+		select {
+		case record := <-queue:
+			records = append(records, record)
+		default:
+			return records
+		}
+	}
+	return records
+}
+
+func writePendingReports(ctx context.Context, pending *[]v1.Report) error {
+	if len(*pending) == 0 {
+		return nil
+	}
+	batchSize := len(*pending)
+	for len(*pending) > 0 {
+		if batchSize > len(*pending) {
+			batchSize = len(*pending)
+		}
+		writeCtx, cancel := context.WithTimeout(ctx, reportBatchWriteTimeout)
+		_, err := writeReportBatch(writeCtx, (*pending)[:batchSize])
+		cancel()
+		if err != nil {
+			return err
+		}
+		*pending = (*pending)[batchSize:]
+	}
+	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 []v1.Report) ([]v1.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()
+
+	s := GetStore()
+	if s == nil {
+		return nil, fmt.Errorf("metric store not enabled")
+	}
+
+	prepared := make([]v1.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 := latestReportCounter(ctx, s, MetricNetTotalUp, report.UUID, report.UpdatedAt)
+			if err == nil {
+				values.totalUp = totalUp
+				values.hasUp = hasUp
+			} else if ctx.Err() == nil {
+				logger.Errorf("metricstore", "failed to restore previous upload counter for %s: %v", report.UUID, err)
+			}
+			totalDown, hasDown, err := latestReportCounter(ctx, s, MetricNetTotalDown, report.UUID, report.UpdatedAt)
+			if err == nil {
+				values.totalDown = totalDown
+				values.hasDown = hasDown
+			} else if ctx.Err() == nil {
+				logger.Errorf("metricstore", "failed to restore previous download counter for %s: %v", report.UUID, err)
+			}
+			if err := ctx.Err(); err != nil {
+				return nil, err
+			}
+			values.initialized = true
+		}
+
+		if !values.timestamp.IsZero() && !report.UpdatedAt.After(values.timestamp) {
+			report.UpdatedAt = values.timestamp.Add(time.Millisecond)
+		}
+		trafficUp := int64(0)
+		if values.hasUp {
+			trafficUp = TrafficCounterDelta(report.Network.TotalUp, values.totalUp)
+		}
+		trafficDown := int64(0)
+		if values.hasDown {
+			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.hasDown = true
+		values.totalDown = report.Network.TotalDown
+		pendingStates[state] = values
+		prepared[i] = report
+	}
+
+	if err := s.WriteBatch(ctx, points); err != nil {
+		return nil, err
+	}
+	for state, values := range pendingStates {
+		state.mu.Lock()
+		state.reportTrafficValues = values
+		state.mu.Unlock()
+	}
+	return prepared, nil
+}
+
+func reportMetricPoints(report v1.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
+}
+
+func latestReportCounter(ctx context.Context, s *metric.Store, metricName, entityID string, before time.Time) (int64, bool, error) {
+	point, ok, err := s.LatestBefore(ctx, 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
+}
+
+// TrafficCounterDelta returns a reset-aware increase between two cumulative
+// traffic counters. After a reset, the current counter is the new increase.
+func TrafficCounterDelta(current, previous int64) int64 {
+	if current < 0 || previous < 0 {
+		return 0
+	}
+	if current >= previous {
+		return current - previous
+	}
+	return current
+}
+
+func deleteReportTrafficState(entityID string) {
+	reportTrafficStates.Delete(entityID)
+}
+
+func clearReportTrafficStates() {
+	reportTrafficStates.Range(func(key, _ any) bool {
+		reportTrafficStates.Delete(key)
+		return true
+	})
+}

database/metricstore/report_test.go

@@ -0,0 +1,440 @@
+package metricstore
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/komari-monitor/komari/database/models"
+	"github.com/komari-monitor/komari/pkg/metric"
+	v1 "github.com/komari-monitor/komari/protocol/v1"
+)
+
+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
+}
+
+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 := v1.Report{
+		UUID:        "node-a",
+		UpdatedAt:   base,
+		CPU:         v1.CPUReport{Usage: 12.5},
+		Ram:         v1.RamReport{Used: 100, Total: 1000},
+		Swap:        v1.RamReport{Used: 20, Total: 200},
+		Load:        v1.LoadReport{Load1: 0.5},
+		Disk:        v1.DiskReport{Used: 300, Total: 3000},
+		Network:     v1.NetworkReport{Up: 3, Down: 4, TotalUp: 100, TotalDown: 200},
+		Process:     7,
+		Connections: v1.ConnectionsReport{TCP: 8, UDP: 9},
+		GPU: &v1.GPUDetailReport{
+			AverageUsage: 25,
+			DetailedInfo: []v1.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, v1.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 := v1.Report{
+		UUID:      "batched-node",
+		UpdatedAt: base,
+		CPU:       v1.CPUReport{Usage: 10},
+		Network:   v1.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 := []v1.Report{
+		{UUID: "node-a", UpdatedAt: base, CPU: v1.CPUReport{Usage: 10}, Network: v1.NetworkReport{TotalUp: 100}},
+		{UUID: "node-a", UpdatedAt: base, CPU: v1.CPUReport{Usage: 20}, Network: v1.NetworkReport{TotalUp: 150}},
+		{UUID: "node-b", UpdatedAt: base, CPU: v1.CPUReport{Usage: 30}, Network: v1.NetworkReport{TotalUp: 200}},
+		{UUID: "node-b", UpdatedAt: base.Add(time.Second), CPU: v1.CPUReport{Usage: 40}, Network: v1.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 v1.Report, 1),
+		requests: make(chan reportBatchRequest, 1),
+		done:     make(chan struct{}),
+	}
+	worker.queue <- v1.Report{UUID: "already-queued"}
+	reportBatcherMu.Lock()
+	reportBatcher = worker
+	reportBatcherMu.Unlock()
+	t.Cleanup(func() {
+		reportBatcherMu.Lock()
+		if reportBatcher == worker {
+			reportBatcher = nil
+		}
+		reportBatcherMu.Unlock()
+	})
+
+	report := v1.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) {
+	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},
+	}
+	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 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 := v1.Report{
+		UUID:      "utc-report",
+		UpdatedAt: receiveTime,
+		CPU:       v1.CPUReport{Usage: 10},
+		Network:   v1.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)
+	}
+}

database/metricstore/restructure.go

@@ -0,0 +1,137 @@
+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) {
+	metricCfg, err := buildMetricConfig(cfg, false)
+	if err != nil {
+		return false, err
+	}
+	store, err := metric.Open(ctx, metricCfg)
+	if err != nil {
+		return false, err
+	}
+	defer store.Close()
+	return store.NeedsRestructure(ctx)
+}
+
+// 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) {
+	cfg, err := config.GetManyAs[MetricStoreConfig]()
+	if err != nil {
+		return RestructureResult{}, err
+	}
+	metricCfg, err := buildMetricConfig(cfg, false)
+	if err != nil {
+		return RestructureResult{}, err
+	}
+	store, err := metric.Open(ctx, metricCfg)
+	if err != nil {
+		return RestructureResult{}, err
+	}
+	defer store.Close()
+
+	before, err := store.LegacyStorageSize(ctx)
+	if err != nil {
+		return RestructureResult{}, fmt.Errorf("measure legacy metric storage: %w", err)
+	}
+	result, err := store.Restructure(ctx, func(progress metric.RestructureProgress) {
+		if report == nil {
+			return
+		}
+		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
+	}
+	if report != nil {
+		report(RestructureProgress{Phase: "reclaiming", RowsDone: result.RowsCopied, RowsTotal: result.RowsCopied, MetricsDone: result.Metrics, MetricsTotal: result.Metrics})
+	}
+	if err := store.ReclaimSpace(ctx); err != nil {
+		return RestructureResult{}, fmt.Errorf("reclaim metric storage: %w", err)
+	}
+	after, err := store.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
+}
+
+// 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) {
+	cfg, err := config.GetManyAs[MetricStoreConfig]()
+	if err != nil {
+		return RestructureResult{}, err
+	}
+	metricCfg, err := buildMetricConfig(cfg, false)
+	if err != nil {
+		return RestructureResult{}, err
+	}
+	store, err := metric.Open(ctx, metricCfg)
+	if err != nil {
+		return RestructureResult{}, err
+	}
+	defer store.Close()
+
+	before, err := store.LegacyStorageSize(ctx)
+	if err != nil {
+		return RestructureResult{}, fmt.Errorf("measure legacy metric storage: %w", err)
+	}
+	result, err := store.DiscardHistory(ctx, func(progress metric.RestructureProgress) {
+		if report == nil {
+			return
+		}
+		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
+	}
+	if report != nil {
+		report(RestructureProgress{Phase: "reclaiming", RowsDone: result.RowsCopied, RowsTotal: result.RowsCopied, MetricsDone: result.Metrics, MetricsTotal: result.Metrics})
+	}
+	if err := store.ReclaimSpace(ctx); err != nil {
+		return RestructureResult{}, fmt.Errorf("reclaim metric storage: %w", err)
+	}
+	after, err := store.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
+}

database/metricstore/store_migration.go

@@ -3,12 +3,12 @@ package metricstore
 import (
 	"context"
 	"fmt"
-	"log"
+	logger "github.com/komari-monitor/komari/utils/log"
 	"strings"
 	"sync"
 	"time"
 
-	"github.com/komari-monitor/komari/pkg/config"
+	"github.com/komari-monitor/komari/internal/config"
 	"github.com/komari-monitor/komari/pkg/metric"
 )
 
@@ -18,18 +18,15 @@ import (
 // ./data/metrics.db）中的全部指标数据搬运到当前正在运行的 metrics 目标库
 // （通常是用户新配置并热重载后的 MySQL/PostgreSQL）。
 //
-// 与启动迁移（RunStartupMigration）的区别：
-//   - 启动迁移在进程启动时自动、同步执行（komari.db → 当前 metrics 目标，或上一个
-//     metrics 目标 → 当前目标）。
-//   - 此处的 store 迁移由管理员在 WebUI 中「切换数据库后」手动触发，异步执行并可
-//     查询进度 / 取消。数据以 upsert 写入，可安全重复执行。
+// 此迁移仅能由管理员在 WebUI 中「切换数据库后」手动触发，异步执行并可查询进度 /
+// 取消。服务启动和指标库热重载均不会复制历史数据。数据以 upsert 写入，可安全重复执行。
 //
 // 典型流程：
 //  1. 管理员在设置中把 metric_db_dsn 改为 MySQL/PostgreSQL，保存 → 后端连接测试
 //     通过后热重载，当前 store 切到远端（此时远端为空）。
 //  2. 管理员调用 startMetricMigration（不带 source 参数），系统以上一个 metrics
 //     目标（默认 SQLite metrics.db）为源，把历史数据搬运到远端。
-//  3. 完成后登记目标指纹，下次启动不再重复搬运。
+//  3. 完成后登记目标指纹，供下一次手动迁移默认选择源库。
 
 // StoreMigrationProgress 描述一次 store-to-store 迁移的实时进度。
 type StoreMigrationProgress struct {
@@ -149,7 +146,7 @@ func StartStoreMigration(sourceDriver, sourceDSN string) error {
 		SourceDSN:    maskDSN(srcCfg.DSN),
 		TargetDriver: string(ResolveDriverFromConfig(cfg.Driver, cfg.DSN)),
 		TargetDSN:    maskDSN(cfg.DSN),
-		StartTime:    time.Now(),
+		StartTime:    time.Now().UTC(),
 	}
 	storeMigMu.Unlock()
 
@@ -191,19 +188,19 @@ func runStoreMigration(ctx context.Context, cancel context.CancelFunc, done chan
 	if err != nil {
 		if ctx.Err() != nil {
 			finishStoreMigration("canceled", nil)
-			log.Printf("[store-migration] canceled after %d points", total)
+			logger.Warnf("metricstore", "[store-migration] canceled after %d points", total)
 			return
 		}
 		finishStoreMigration("failed", err)
 		return
 	}
 
-	// 搬运成功：登记当前目标指纹，避免下次启动重复搬运。
+	// 搬运成功：登记当前目标指纹，供下一次手动迁移推断源库。
 	if err := config.Set(MigrationTargetKey, targetFP); err != nil {
-		log.Printf("[store-migration] failed to persist migration target fingerprint: %v", err)
+		logger.Errorf("metricstore", "[store-migration] failed to persist migration target fingerprint: %v", err)
 	}
 	finishStoreMigration("completed", nil)
-	log.Printf("[store-migration] completed via API (%d points) target_driver=%s", total, ResolveDriverFromConfig(cfg.Driver, cfg.DSN))
+	logger.Infof("metricstore", "[store-migration] completed via API (%d points) target_driver=%s", total, ResolveDriverFromConfig(cfg.Driver, cfg.DSN))
 }
 
 // finishStoreMigration 统一收尾：设置终态状态、结束时间与错误信息。
@@ -211,7 +208,7 @@ func finishStoreMigration(status string, err error) {
 	storeMigMu.Lock()
 	defer storeMigMu.Unlock()
 	storeMigProgress.Status = status
-	storeMigProgress.EndTime = time.Now()
+	storeMigProgress.EndTime = time.Now().UTC()
 	if err != nil {
 		storeMigProgress.Error = err.Error()
 	}
@@ -270,6 +267,12 @@ func stopStoreMigrationForClose(ctx context.Context) error {
 	}
 }
 
+// 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 {
+	return stopStoreMigrationForClose(ctx)
+}
+
 func clearStoreClosing() {
 	storeMigMu.Lock()
 	storeClosing = false

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 +1,13 @@
 package models
 
+import "time"
+
 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"`
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `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/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,13 +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"`                                     // 上次通知时间
+	GracePeriod  int        `json:"grace_period" gorm:"type:int;not null;default:180"` // 宽限期（秒），默认 3 分钟
+	LastNotified *time.Time `json:"last_notified"`                                     // 上次通知时间
 }
 
 // LoadNotification 定义了基于资源占用达标时间比的负载通知规则
@@ -19,7 +21,7 @@ type LoadNotification struct {
 	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"`                                             // 上次通知时间
+	LastNotified *time.Time  `json:"last_notified"`                                             // 上次通知时间
 }
 
 // TrafficReportNotification 定义了流量定时报告的数据库模型
@@ -27,7 +29,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/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/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?mode=memory&cache=shared", strings.ReplaceAll(t.Name(), "/", "_"))
+	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?mode=memory&cache=shared", strings.ReplaceAll(t.Name(), "/", "_"))
+	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/records/records.go

@@ -24,14 +24,15 @@ func GetGPURecordsByClientAndTime(uuid string, start, end time.Time) ([]models.G
 	return metricstore.GetGPURecordsByClientAndTime(context.Background(), uuid, start, end)
 }
 
-func DeleteRecordBefore(before time.Time) error {
-	return metricstore.DeleteRecordsBefore(context.Background(), before)
-}
-
 func GetRecordsByClientAndTime(uuid string, start, end time.Time) ([]models.Record, error) {
 	return metricstore.GetRecordsByClientAndTime(context.Background(), uuid, start, end)
 }
 
+// GetRecordMetricMaxByClientAndTime 获取单项监控指标在各时间桶内的最大值。
+func GetRecordMetricMaxByClientAndTime(uuid, metricName string, start, end time.Time) ([]models.Record, error) {
+	return metricstore.GetRecordMetricMaxByClientAndTime(context.Background(), uuid, metricName, start, end)
+}
+
 // GetRecordsByTime 获取所有客户端在时间范围内的记录。
 func GetRecordsByTime(start, end time.Time) ([]models.Record, error) {
 	return metricstore.GetRecordsByTime(context.Background(), start, end)

database/tasks/ping.go

@@ -47,6 +47,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 {
@@ -134,10 +140,6 @@ func SavePingRecord(record models.PingRecord) error {
 	return metricstore.WritePingRecord(context.Background(), record)
 }
 
-func DeletePingRecordsBefore(time time.Time) error {
-	return metricstore.DeletePingRecordsBefore(context.Background(), time)
-}
-
 func DeletePingRecords(id []uint) error {
 	return metricstore.DeletePingRecordsByTask(context.Background(), id)
 }
@@ -147,9 +149,8 @@ func DeleteAllPingRecords() error {
 }
 
 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)

database/tasks/tasks.go

@@ -26,7 +26,7 @@ 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 {
@@ -57,13 +57,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 +72,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,68 @@
+package tasks
+
+import (
+	"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) {
+	flags.DatabaseType = flags.DatabaseTypeSQLite
+	flags.DatabaseFile = "file:task_cleanup_time?mode=memory&cache=shared"
+	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) {
+	flags.DatabaseType = flags.DatabaseTypeSQLite
+	flags.DatabaseFile = "file:ping_task_order?mode=memory&cache=shared"
+	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)
+	}
+}

database/utils.go

@@ -1,8 +1,9 @@
 package database
 
 import (
+	"context"
 	"encoding/json"
-	"log"
+	logger "github.com/komari-monitor/komari/utils/log"
 	"os"
 	"path/filepath"
 	"strings"
@@ -11,7 +12,7 @@ import (
 	"github.com/komari-monitor/komari/database/dbcore"
 	"github.com/komari-monitor/komari/database/metricstore"
 	"github.com/komari-monitor/komari/database/models"
-	"github.com/komari-monitor/komari/pkg/config"
+	"github.com/komari-monitor/komari/internal/config"
 )
 
 func GetPublicInfo() (map[string]interface{}, error) {
@@ -53,7 +54,7 @@ func GetPublicInfo() (map[string]interface{}, error) {
 			cst.Description = "Komari Monitor, a simple server monitoring tool."
 		}
 	}
-	metricCfg, err := config.GetManyAs[metricstore.MetricStoreConfig]()
+	retention, err := metricstore.GetRetentionSummary(context.Background())
 	if err != nil {
 		return nil, err
 	}
@@ -66,7 +67,7 @@ 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
@@ -130,11 +131,11 @@ func GetPublicInfo() (map[string]interface{}, error) {
 		"oauth_provider":            cst.OAuthProvider,
 		"disable_password_login":    cst.DisablePasswordLogin,
 		"cors_origin_check_enabled": cst.CorsOriginCheckEnabled,
-		"record_enabled":            metricCfg.RetentionDays > 0,  //兼容旧版本主题
-		"record_preserve_time":      metricCfg.RetentionDays * 24, //兼容旧版本主题
-		"ping_record_preserve_time": metricCfg.RetentionDays * 24, //兼容旧版本主题
-		"metric_retention_days":     metricCfg.RetentionDays,
+		"record_enabled":            retention.AllPositive, // 兼容旧版本主题
+		"record_preserve_time":      retention.MaxDays * 24,
+		"ping_record_preserve_time": retention.MaxDays * 24,
 		"private_site":              cst.PrivateSite,
+		"visitor_audit_enabled":     cst.VisitorAuditEnabled,
 		"theme":                     cst.Theme,
 		"theme_settings":            tc_data,
 	}, nil

docs/README_ja.md

@@ -1,148 +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インターフェースを介してサーバーのステータスを表示し、軽量エージェントを介してデータを収集します。
-
-> [!WARNING]
-> Komariは、自己ホスト型の監視/制御プログラムであり、所有しているシステム、または管理権限を得ているシステムでのみ使用してください。Komariを武器化したり、許可なく展開、アクセス、永続化、コマンド実行、その他の不正利用に使用したりしないでください。実際の悪用リスクについては、Huntressの分析をご参照ください：[Komari C2 agent abuse](https://www.huntress.com/blog/komari-c2-agent-abuse)。
-> Komariの展開および運用方法については、利用者自身が責任を負います。開発者は、無許可または不正な利用、およびその結果について責任を負いません。
-> Windows端末でリモートコントロールを有効にした場合、クライアントはユーザーがログインするたびに、KomariがリモートコントロールソフトウェアであることをWindows通知で知らせます。
-
-[ドキュメント](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,148 +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 收集數據。
-
-> [!WARNING]
-> Komari 是一款自託管的監控/控制程式，僅應部署在你擁有或已獲授權管理的系統上。請勿將 Komari 武器化，或在未獲授權的情況下部署、存取、持久化、執行命令及從事其他濫用行為。關於現實中的濫用風險，可參考 Huntress 的分析：[Komari C2 agent abuse](https://www.huntress.com/blog/komari-c2-agent-abuse)。
-> 使用者需要自行承擔部署和使用 Komari 的責任。開發者不對未經授權或濫用行為及其後果承擔責任。
-> 在 Windows 端啟用遠端控制後，客戶端會在每次使用者登入時透過 Windows 通知提醒使用者 Komari 是一款遠端控制軟體。
-
-[文檔](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,148 +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 收集数据。
-
-> [!WARNING]
-> Komari 是一款自托管的监控/控制程序，仅应部署在你拥有或已获得授权管理的系统上。请勿将 Komari 武器化，或在未获授权的情况下部署、访问、持久化、执行命令及从事其他滥用行为。关于现实中的滥用风险，可参考 Huntress 的分析：[Komari C2 agent abuse](https://www.huntress.com/blog/komari-c2-agent-abuse)。
-> 用户需要自行承担部署和使用 Komari 的责任。开发者不对未经授权或滥用行为及其后果承担责任。
-> 在 Windows 端开启远程控制后，客户端会在每次用户登录时通过 Windows 通知提醒用户 Komari 是一款远程控制软件。
-
-[文档](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

@@ -17,12 +17,12 @@ require (
 	github.com/spf13/cobra v1.9.1
 	github.com/stretchr/testify v1.11.1
 	golang.org/x/image v0.35.0
-	google.golang.org/grpc v1.75.0
-	google.golang.org/protobuf v1.36.6
 	gorm.io/driver/sqlite v1.5.7
 	gorm.io/gorm v1.26.1
 )
 
+require golang.org/x/sys v0.33.0 // 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
@@ -46,6 +46,7 @@ require (
 	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/go-cmp v0.7.0 // indirect
 	github.com/google/pprof v0.0.0-20240727154555-813a5fbdbec8 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
@@ -67,9 +68,8 @@ require (
 	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/sync v0.19.0 // indirect
-	golang.org/x/sys v0.33.0 // indirect
+	golang.org/x/sync v0.19.0
 	golang.org/x/text v0.33.0 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20250707201910-8d1bb00bc6a7 // indirect
+	google.golang.org/protobuf v1.36.6 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -29,10 +29,6 @@ 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-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=
@@ -47,8 +43,6 @@ github.com/go-sql-driver/mysql v1.10.0 h1:Q+1LV8DkHJvSYAdR83XzuhDaTykuDx0l6fkXxo
 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=
@@ -131,18 +125,6 @@ github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS
 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=
 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=
@@ -158,12 +140,6 @@ 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=

install-komari.sh

@@ -226,6 +226,9 @@ detect_arch() {
         riscv64)
             echo "riscv64"
             ;;
+        loongarch64|loong64)
+            echo "loong64"
+            ;;
         *)
             log_error "不支持的架构: $arch"
             exit 1
@@ -365,13 +368,7 @@ install_binary() {
     if systemctl is-active --quiet ${SERVICE_NAME}.service; then
         log_success "Komari 服务启动成功"
 
-        log_step "正在获取初始密码..."
-        sleep 5
-        local password=$(journalctl -u ${SERVICE_NAME} --since "1 minute ago" | grep "admin account created." | tail -n 1 | sed -e 's/.*admin account created.//')
-        if [ -z "$password" ]; then
-            log_error "未能获取初始密码，请检查日志"
-        fi
-        show_access_info "$password" "$LISTEN_PORT"
+        show_access_info "$LISTEN_PORT"
     else
         ui_msgbox "错误" "Komari 服务启动失败。\n\n查看日志: journalctl -u ${SERVICE_NAME} -f"
         return 1
@@ -405,16 +402,13 @@ EOF
 
 # Show access information
 show_access_info() {
-    local password=$1
-    local port=${2:-$DEFAULT_PORT}
+    local port=${1:-$DEFAULT_PORT}
     local ip=$(hostname -I | awk '{print $1}')
 
     local content="安装完成！\n\n"
     content+="访问信息：\n"
     content+="  URL: http://${ip}:${port}\n"
-    if [ -n "$password" ]; then
-        content+="  初始登录信息（仅显示一次）: ${password}\n"
-    fi
+    content+="\n首次使用请访问上述地址，按安装向导创建管理员账号。\n"
     content+="\n服务管理命令：\n"
     content+="  状态: systemctl status $SERVICE_NAME\n"
     content+="  启动: systemctl start $SERVICE_NAME\n"

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,14 +16,12 @@ 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
+	VisitorAuditEnabled    bool   `json:"visitor_audit_enabled" default:"false"`               // 是否允许公开访客事件写入审计日志，默认 false
 	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"`
@@ -56,12 +54,11 @@ const (
 	AutoDiscoveryKeyKey       = "auto_discovery_key"
 	ScriptDomainKey           = "script_domain"
 	SendIpAddrToGuestKey      = "send_ip_addr_to_guest"
+	VisitorAuditEnabledKey    = "visitor_audit_enabled"
 	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"
@@ -77,4 +74,5 @@ const (
 	TrafficLimitPercentageKey     = "traffic_limit_percentage"
 	UpdatedAtKey                  = "updated_at"
 	XtermjsSettingsKey            = "xtermjs_settings"
+	ThemeMarketSourcesKey         = "theme_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/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/database/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/database/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,8 +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"`
-	CreatedAt                  models.LocalTime
-	UpdatedAt                  models.LocalTime
+	CreatedAt                  time.Time
+	UpdatedAt                  time.Time
 }
 
 func (legacyModelConfig) TableName() string {
@@ -63,8 +61,6 @@ 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"`
@@ -101,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 {
@@ -110,7 +109,6 @@ func Run(ctx Context) error {
 			return err
 		}
 	}
-
 	if err := migrateLegacyClientInfo(db); err != nil {
 		return err
 	}
@@ -125,10 +123,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
@@ -152,7 +177,7 @@ func hasTableColumn(db *gorm.DB, tableName, columnName string) bool {
 
 func migrateLegacyLoadNotification(db *gorm.DB) error {
 	if db.Migrator().HasColumn(&models.LoadNotification{}, "client") {
-		log.Println("[>0.1.4] Rebuilding LoadNotification table....")
+		logger.InfoArgs("migration", "[>0.1.4] Rebuilding LoadNotification table....")
 		return db.Migrator().DropTable(&models.LoadNotification{})
 	}
 	return nil
@@ -163,7 +188,7 @@ func migrateLegacyOidcConfig(db *gorm.DB) error {
 		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"`
@@ -200,7 +225,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"`
@@ -284,7 +309,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 {
@@ -347,7 +372,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
 	}
@@ -360,7 +385,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
 		}
 
@@ -383,7 +408,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)
 		}
@@ -392,7 +417,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

@@ -7,7 +7,7 @@ import (
 	"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"
 )
@@ -79,6 +79,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 +144,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)
 	}
@@ -215,7 +269,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,242 @@
+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: "clipboards", column: "created_at"},
+	{table: "clipboards", column: "updated_at"},
+	{table: "offline_notifications", column: "last_notified"},
+	{table: "load_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?mode=memory&cache=shared", strings.ReplaceAll(t.Name(), "/", "_"))
+	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/scheduler/scheduler.go

@@ -1,9 +1,9 @@
-package corn
+package scheduler
 
 import (
 	"context"
 	"fmt"
-	"log"
+	logger "github.com/komari-monitor/komari/utils/log"
 	"strconv"
 	"strings"
 	"sync"
@@ -40,7 +40,7 @@ type cronSchedule struct {
 }
 
 func (s cronSchedule) Next(t time.Time) time.Time {
-	next := t.Truncate(time.Second).Add(time.Second)
+	next := t.UTC().Truncate(time.Second).Add(time.Second)
 	limit := next.Add(366 * 24 * time.Hour)
 	for next.Before(limit) {
 		if s.match(next) {
@@ -52,6 +52,7 @@ func (s cronSchedule) Next(t time.Time) time.Time {
 }
 
 func (s cronSchedule) match(t time.Time) bool {
+	t = t.In(time.Local)
 	_, okSecond := s.seconds[t.Second()]
 	_, okMinute := s.minutes[t.Minute()]
 	_, okHour := s.hours[t.Hour()]
@@ -171,7 +172,7 @@ func (m *Manager) run(ctx context.Context, name string, s schedule, runImmediate
 
 	nextTick := s.Next(time.Now())
 	if nextTick.IsZero() {
-		log.Printf("corn job %s has no next run time", name)
+		logger.Warnf("scheduler", "corn job %s has no next run time", name)
 		return
 	}
 	timer := time.NewTimer(time.Until(nextTick))
@@ -202,7 +203,7 @@ func resetTimer(timer *time.Timer, duration time.Duration) {
 func safeRun(ctx context.Context, name string, fn Func) {
 	defer func() {
 		if r := recover(); r != nil {
-			log.Printf("corn job %s panic: %v", name, r)
+			logger.Errorf("scheduler", "corn job %s panic: %v", name, r)
 		}
 	}()
 

internal/scheduler/scheduler_test.go

@@ -0,0 +1,35 @@
+package scheduler
+
+import (
+	"testing"
+	"time"
+)
+
+func TestCronScheduleUsesSystemLocalWallClock(t *testing.T) {
+	originalLocal := time.Local
+	time.Local = time.FixedZone("UTC+8", 8*60*60)
+	t.Cleanup(func() { time.Local = originalLocal })
+
+	schedule, err := Parse("0 0 9 * * *")
+	if err != nil {
+		t.Fatalf("parse schedule: %v", err)
+	}
+	after := time.Date(2026, 7, 17, 0, 30, 0, 0, time.UTC)
+	want := time.Date(2026, 7, 17, 1, 0, 0, 0, time.UTC)
+	if got := schedule.Next(after); !got.Equal(want) {
+		t.Fatalf("next run = %s, want %s", got, want)
+	} else if got.Location() != time.UTC {
+		t.Fatalf("next run location = %s, want UTC", got.Location())
+	}
+}
+
+func TestEverySchedulePreservesElapsedDuration(t *testing.T) {
+	schedule, err := Parse("@every 90s")
+	if err != nil {
+		t.Fatalf("parse schedule: %v", err)
+	}
+	after := time.Now()
+	if got := schedule.Next(after); got.Sub(after) != 90*time.Second {
+		t.Fatalf("interval = %s, want 90s", got.Sub(after))
+	}
+}

internal/server/app.go

@@ -0,0 +1,47 @@
+package server
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"github.com/komari-monitor/komari/internal/config"
+)
+
+// cleanupFunc is a cleanup action run during shutdown.
+type cleanupFunc struct {
+	name string
+	fn   func(ctx context.Context) error
+}
+
+// App owns the server lifecycle. Individual phases live in focused files:
+// bootstrap, metric store, providers, guides, router, and runtime.
+type App struct {
+	listenAddr              string
+	settings                *config.Settings
+	engine                  *gin.Engine
+	server                  *http.Server
+	reload                  *ReloadManager
+	dbReady                 bool
+	oauthReady              bool
+	metricStoreCleanupAdded bool
+
+	cleanups []cleanupFunc
+}
+
+// Options configures the process-wide application runtime.
+type Options struct {
+	ListenAddr string
+}
+
+// New constructs an empty application. Initialization happens in the
+// explicit lifecycle phases called by the command entrypoint.
+func New(options Options) *App {
+	return &App{listenAddr: options.ListenAddr, reload: NewReloadManager()}
+}
+
+// addCleanup registers a cleanup action. Shutdown executes actions in LIFO
+// order, mirroring resource initialization order.
+func (a *App) addCleanup(name string, fn func(ctx context.Context) error) {
+	a.cleanups = append(a.cleanups, cleanupFunc{name: name, fn: fn})
+}

internal/server/app_test.go

@@ -0,0 +1,82 @@
+package server
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+func TestRetryMetricStoreConnectionStopsAfterRecovery(t *testing.T) {
+	wantErr := errors.New("temporary connection failure")
+	attempts := 0
+	err := retryMetricStoreConnection(3, 0, func() error {
+		attempts++
+		if attempts < 3 {
+			return wantErr
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("retry returned error after recovery: %v", err)
+	}
+	if attempts != 3 {
+		t.Fatalf("attempts = %d, want 3", attempts)
+	}
+}
+
+func TestGuideNoRouteRejectsUnknownAPIAndRedirectsPages(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	router.Use(noStoreAPIResponses())
+	router.NoRoute(guideNoRoute("/install", "Not found in install mode", nil))
+
+	apiResponse := httptest.NewRecorder()
+	router.ServeHTTP(apiResponse, httptest.NewRequest(http.MethodGet, "/api/unknown", nil))
+	if apiResponse.Code != http.StatusNotFound {
+		t.Fatalf("API status = %d, want %d", apiResponse.Code, http.StatusNotFound)
+	}
+	if got := apiResponse.Header().Get("Cache-Control"); got != "no-store" {
+		t.Fatalf("API cache control = %q, want no-store", got)
+	}
+
+	pageResponse := httptest.NewRecorder()
+	router.ServeHTTP(pageResponse, httptest.NewRequest(http.MethodGet, "/stale-guide", nil))
+	if pageResponse.Code != http.StatusTemporaryRedirect {
+		t.Fatalf("page status = %d, want %d", pageResponse.Code, http.StatusTemporaryRedirect)
+	}
+	if got := pageResponse.Header().Get("Location"); got != "/install" {
+		t.Fatalf("redirect location = %q, want /install", got)
+	}
+}
+
+func TestRetryMetricStoreConnectionReturnsLastError(t *testing.T) {
+	wantErr := errors.New("connection unavailable")
+	attempts := 0
+	err := retryMetricStoreConnection(3, 0, func() error {
+		attempts++
+		return wantErr
+	})
+	if !errors.Is(err, wantErr) {
+		t.Fatalf("error = %v, want %v", err, wantErr)
+	}
+	if attempts != 3 {
+		t.Fatalf("attempts = %d, want 3", attempts)
+	}
+}
+
+func TestShutdownReturnsCleanupError(t *testing.T) {
+	wantErr := errors.New("queued reports were not flushed")
+	app := New(Options{})
+	app.addCleanup("metric-report-batcher", func(_ context.Context) error {
+		return wantErr
+	})
+
+	err := app.Shutdown()
+	if !errors.Is(err, wantErr) {
+		t.Fatalf("shutdown error = %v, want %v", err, wantErr)
+	}
+}

internal/server/bootstrap.go

@@ -0,0 +1,34 @@
+package server
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	"github.com/gin-gonic/gin"
+	"github.com/komari-monitor/komari/database/dbcore"
+	"github.com/komari-monitor/komari/internal/config"
+	"github.com/komari-monitor/komari/utils"
+)
+
+// Bootstrap initializes the data directory, primary database, and settings.
+func (a *App) Bootstrap() error {
+	if err := os.MkdirAll("./data/theme", os.ModePerm); err != nil {
+		return fmt.Errorf("failed to create theme directory: %w", err)
+	}
+
+	dbcore.SetVersionID(utils.CurrentVersion + "-" + utils.VersionHash)
+	if err := dbcore.Initialize(); err != nil {
+		return fmt.Errorf("failed to initialize database: %w", err)
+	}
+	a.dbReady = true
+	a.addCleanup("database", func(context.Context) error { return dbcore.Close() })
+
+	gin.SetMode(gin.ReleaseMode)
+	settings, err := config.GetManyAs[config.Settings]()
+	if err != nil {
+		return fmt.Errorf("failed to load settings: %w", err)
+	}
+	a.settings = settings
+	return nil
+}

internal/server/guide_server.go

@@ -0,0 +1,118 @@
+package server
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	logger "github.com/komari-monitor/komari/utils/log"
+	"github.com/komari-monitor/komari/web/api"
+	frontendpublic "github.com/komari-monitor/komari/web/public"
+	"github.com/komari-monitor/komari/web/security"
+)
+
+type guideController interface {
+	Activate()
+	Deactivate()
+	Register(*gin.Engine)
+	Done() <-chan struct{}
+}
+
+type guideServerConfig struct {
+	pagePath         string
+	missingAPI       string
+	logMessage       string
+	requireIdentity  bool
+	restrictedStatic bool
+}
+
+// runGuideServer hosts one temporary, narrowly scoped guide. It deliberately
+// constructs a new Gin engine for each mode so normal routes never leak into
+// installation, upgrade, or recovery flows.
+func (a *App) runGuideServer(controller guideController, cfg guideServerConfig) (bool, error) {
+	controller.Activate()
+	defer controller.Deactivate()
+
+	r := gin.New()
+	r.Use(logger.GinLogger(), logger.GinRecovery(), noStoreAPIResponses())
+	if cfg.requireIdentity {
+		cors := security.NewCorsController(a.settings.CorsOriginCheckEnabled, a.settings.CorsAllowedOrigins)
+		r.Use(cors.Middleware(), api.IdentityMiddleware())
+	}
+	controller.Register(r)
+
+	serveStatic := frontendpublic.Static
+	if cfg.restrictedStatic {
+		serveStatic = frontendpublic.StaticRestricted
+	}
+	serveStatic(r.Group("/"), func(handlers ...gin.HandlerFunc) {
+		r.NoRoute(guideNoRoute(cfg.pagePath, cfg.missingAPI, handlers))
+	})
+
+	server := &http.Server{Addr: a.listenAddr, Handler: r}
+	a.engine = r
+	a.server = server
+	serverErr := make(chan error, 1)
+	logger.Infof("server", cfg.logMessage, a.listenAddr)
+	go func() {
+		if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			serverErr <- err
+		}
+	}()
+
+	quit := make(chan os.Signal, 1)
+	signal.Notify(quit, os.Interrupt, syscall.SIGTERM)
+	defer signal.Stop(quit)
+
+	select {
+	case err := <-serverErr:
+		return false, fmt.Errorf("listen in guide mode: %w", err)
+	case <-quit:
+		return false, a.Shutdown()
+	case <-controller.Done():
+		ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancel()
+		if err := server.Shutdown(ctx); err != nil {
+			return false, fmt.Errorf("stop guide server: %w", err)
+		}
+		a.server = nil
+		a.engine = nil
+		return true, nil
+	}
+}
+
+func noStoreAPIResponses() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if strings.HasPrefix(c.Request.URL.Path, "/api") {
+			c.Header("Cache-Control", "no-store")
+		}
+		c.Next()
+	}
+}
+
+func guideNoRoute(pagePath, missingAPI string, handlers []gin.HandlerFunc) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		requestPath := c.Request.URL.Path
+		if strings.HasPrefix(requestPath, "/api") {
+			api.RespondError(c, http.StatusNotFound, missingAPI)
+			return
+		}
+		if c.Request.Method == http.MethodGet && requestPath != pagePath && filepath.Ext(requestPath) == "" {
+			c.Redirect(http.StatusTemporaryRedirect, pagePath)
+			return
+		}
+		for _, handler := range handlers {
+			handler(c)
+			if c.IsAborted() {
+				return
+			}
+		}
+	}
+}

internal/server/guides.go

@@ -0,0 +1,96 @@
+package server
+
+import (
+	"context"
+
+	"github.com/komari-monitor/komari/database/dbcore"
+	"github.com/komari-monitor/komari/database/metricstore"
+	"github.com/komari-monitor/komari/database/models"
+	"github.com/komari-monitor/komari/internal/migrations"
+	installweb "github.com/komari-monitor/komari/web/install"
+	migrationweb "github.com/komari-monitor/komari/web/migration"
+	recoveryweb "github.com/komari-monitor/komari/web/recovery"
+)
+
+// InstallRequired reports whether the instance still needs the first-run guide.
+func (a *App) InstallRequired() (bool, error) {
+	var count int64
+	if err := dbcore.GetDBInstance().Model(&models.User{}).Count(&count).Error; err != nil {
+		return false, err
+	}
+	return count == 0, nil
+}
+
+type DatabaseMigrationRequirement struct {
+	mode    migrationweb.Mode
+	summary migrations.LegacyMonitoringSummary
+}
+
+func (r DatabaseMigrationRequirement) Required() bool { return r.mode != "" }
+
+// DatabaseMigrationRequired checks both supported migration inputs before the
+// normal Metric Store connection is initialized. Structure upgrades run first
+// when both inputs exist, then the startup loop detects the legacy tables on
+// its next pass.
+func (a *App) DatabaseMigrationRequired() (DatabaseMigrationRequirement, error) {
+	structureRequired, err := metricstore.StructureUpgradeRequired(context.Background())
+	if err != nil {
+		return DatabaseMigrationRequirement{}, err
+	}
+	if structureRequired {
+		return DatabaseMigrationRequirement{mode: migrationweb.ModeMetricStructure}, nil
+	}
+	legacyRequired, summary, err := migrations.LegacyMonitoringMigrationRequired(dbcore.GetDBInstance())
+	if err != nil {
+		return DatabaseMigrationRequirement{}, err
+	}
+	if legacyRequired {
+		return DatabaseMigrationRequirement{mode: migrationweb.ModeLegacyMonitoring, summary: summary}, nil
+	}
+	return DatabaseMigrationRequirement{}, nil
+}
+
+// RunInstallGuide exposes only first-run installation APIs. It intentionally
+// does not mount authentication or normal application routes.
+func (a *App) RunInstallGuide() (bool, error) {
+	return a.runGuideServer(installweb.NewController(dbcore.GetDBInstance()), guideServerConfig{
+		pagePath:   installweb.PagePath,
+		missingAPI: "Not found in install mode",
+		logMessage: "First-run installation guide is available on %s",
+	})
+}
+
+// RunMetricStoreRecovery keeps login available while exposing only the
+// administrator-protected metric-store recovery API.
+func (a *App) RunMetricStoreRecovery(initialErr error) (bool, error) {
+	a.initOAuth()
+	return a.runGuideServer(recoveryweb.NewController(initialErr, metricStoreReconnectAttempts), guideServerConfig{
+		pagePath:         recoveryweb.PagePath,
+		missingAPI:       "Not found in database recovery mode",
+		logMessage:       "Metric store recovery is available on %s",
+		requireIdentity:  true,
+		restrictedStatic: true,
+	})
+}
+
+// RunDatabaseMigration serves the same authenticated guide and status model
+// for either migration input while leaving each conversion engine independent.
+func (a *App) RunDatabaseMigration(requirement DatabaseMigrationRequirement) (bool, error) {
+	a.initOAuth()
+	var controller guideController
+	switch requirement.mode {
+	case migrationweb.ModeMetricStructure:
+		controller = migrationweb.NewStructureController()
+	case migrationweb.ModeLegacyMonitoring:
+		controller = migrationweb.NewLegacyController(dbcore.GetDBInstance(), requirement.summary)
+	default:
+		return false, nil
+	}
+	return a.runGuideServer(controller, guideServerConfig{
+		pagePath:         migrationweb.PagePath,
+		missingAPI:       "Not found in database migration mode",
+		logMessage:       "Database migration guide is available on %s",
+		requireIdentity:  true,
+		restrictedStatic: true,
+	})
+}

internal/server/metric_store.go

@@ -0,0 +1,90 @@
+package server
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/komari-monitor/komari/database/auditlog"
+	"github.com/komari-monitor/komari/database/metricstore"
+	"github.com/komari-monitor/komari/internal/config"
+	logger "github.com/komari-monitor/komari/utils/log"
+)
+
+const (
+	metricStoreReconnectAttempts = 3
+	metricStoreReconnectInterval = 5 * time.Second
+)
+
+// ConnectMetricStore performs one connection attempt and registers cleanup
+// only after a store has actually opened.
+func (a *App) ConnectMetricStore() error {
+	if err := metricstore.InitializeStore(); err != nil {
+		return fmt.Errorf("failed to initialize metric store: %s", redactMetricStoreError(err))
+	}
+	if !a.metricStoreCleanupAdded {
+		a.addCleanup("metric-store", metricstore.CloseStoreContext)
+		a.metricStoreCleanupAdded = true
+	}
+	return nil
+}
+
+func redactMetricStoreError(err error) string {
+	if err == nil {
+		return ""
+	}
+	dsn := ""
+	if cfg, cfgErr := config.GetManyAs[metricstore.MetricStoreConfig](); cfgErr == nil {
+		dsn = cfg.DSN
+	}
+	return metricstore.RedactConnectionError(err.Error(), dsn)
+}
+
+// ConnectMetricStoreWithRetry retries the monitoring database connection.
+func (a *App) ConnectMetricStoreWithRetry() error {
+	attempt := 0
+	err := retryMetricStoreConnection(metricStoreReconnectAttempts, metricStoreReconnectInterval, func() error {
+		attempt++
+		err := a.ConnectMetricStore()
+		if err != nil {
+			logger.Warn("server", "Metric store connection attempt failed", "attempt", attempt, "max_attempts", metricStoreReconnectAttempts, "error", err)
+		}
+		return err
+	})
+	if err == nil && attempt > 1 {
+		logger.Infof("server", "Metric store connection recovered on attempt %d/%d", attempt, metricStoreReconnectAttempts)
+	}
+	return err
+}
+
+func retryMetricStoreConnection(attempts int, interval time.Duration, connect func() error) error {
+	if attempts < 1 {
+		return fmt.Errorf("metric store retry attempts must be positive")
+	}
+	var lastErr error
+	for attempt := 1; attempt <= attempts; attempt++ {
+		if attempt > 1 {
+			time.Sleep(interval)
+		}
+		if err := connect(); err == nil {
+			return nil
+		} else {
+			lastErr = err
+		}
+	}
+	return lastErr
+}
+
+// InitStores opens the metric store and starts its report batcher. Historical
+// data migrations are started only through an explicit administrator action.
+func (a *App) InitStores() error {
+	if err := a.ConnectMetricStore(); err != nil {
+		auditlog.EventLog("error", fmt.Sprintf("Failed to initialize metric store: %v", err))
+		return err
+	}
+	metricstore.StartReportBatcher()
+	a.addCleanup("metric-report-batcher", metricstore.StopReportBatcher)
+	// A store-to-store migration holds the exclusive operation lease. Stop it
+	// before flushing queued reports, which need the shared lease to write.
+	a.addCleanup("metric-store-migration", metricstore.StopStoreMigrationForShutdown)
+	return nil
+}

internal/server/providers.go

@@ -0,0 +1,38 @@
+package server
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/komari-monitor/komari/database/auditlog"
+	"github.com/komari-monitor/komari/utils/geoip"
+	logger "github.com/komari-monitor/komari/utils/log"
+	"github.com/komari-monitor/komari/utils/messageSender"
+	"github.com/komari-monitor/komari/web/oauth"
+)
+
+// InitProviders initializes providers needed by the normal application.
+func (a *App) InitProviders() error {
+	a.initOAuth()
+
+	go geoip.InitGeoIp()
+	a.addCleanup("geoip", func(context.Context) error { return geoip.Shutdown() })
+
+	messageSender.Initialize()
+	a.addCleanup("message-sender", func(context.Context) error { return messageSender.Shutdown() })
+	return nil
+}
+
+// initOAuth initializes OAuth once. Restricted authenticated guides need it
+// before the normal provider initialization phase.
+func (a *App) initOAuth() {
+	if a.oauthReady {
+		return
+	}
+	if err := oauth.Initialize(); err != nil {
+		logger.Errorf("server", "Failed to initialize OAuth provider: %v", err)
+		auditlog.EventLog("error", fmt.Sprintf("Failed to initialize OAuth provider: %v", err))
+	}
+	a.oauthReady = true
+	a.addCleanup("oauth", func(context.Context) error { return oauth.Shutdown() })
+}

internal/server/reload.go

@@ -1,9 +1,9 @@
-package cmd
+package server
 
 import (
-	"log"
+	logger "github.com/komari-monitor/komari/utils/log"
 
-	"github.com/komari-monitor/komari/pkg/config"
+	"github.com/komari-monitor/komari/internal/config"
 )
 
 // reloadHandler 是单个配置热重载处理器。
@@ -60,7 +60,7 @@ func (m *ReloadManager) Start() {
 func (m *ReloadManager) dispatch(h reloadHandler, event config.ConfigEvent) {
 	defer func() {
 		if r := recover(); r != nil {
-			log.Printf("config reload handler %q panicked: %v", h.name, r)
+			logger.Errorf("reload", "config reload handler %q panicked: %v", h.name, r)
 		}
 	}()
 	h.handler(event)

internal/server/runtime.go

@@ -0,0 +1,221 @@
+package server
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"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/metricstore"
+	d_notification "github.com/komari-monitor/komari/database/notification"
+	"github.com/komari-monitor/komari/database/tasks"
+	"github.com/komari-monitor/komari/internal/config"
+	"github.com/komari-monitor/komari/internal/lifecycle"
+	"github.com/komari-monitor/komari/internal/scheduler"
+	"github.com/komari-monitor/komari/utils/geoip"
+	logger "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/api"
+	"github.com/komari-monitor/komari/web/oauth"
+	recoveryweb "github.com/komari-monitor/komari/web/recovery"
+	"github.com/komari-monitor/komari/web/router"
+	"github.com/komari-monitor/komari/web/security"
+)
+
+// ErrRestartRequested is returned after a clean shutdown when a configuration
+// change requires the next startup to enter a restricted guide.
+var ErrRestartRequested = errors.New("server restart requested")
+
+const (
+	// Give in-flight HTTP requests time to finish before the listener closes.
+	httpShutdownTimeout = 10 * time.Second
+	// Keep an independent budget for report flushing and store teardown. Reusing
+	// the HTTP deadline here can skip queued metric writes after a slow request.
+	resourceCleanupTimeout = 30 * time.Second
+)
+
+// StartBackground starts scheduled work after all stores are ready.
+func (a *App) StartBackground() error {
+	registerScheduledWork()
+	a.addCleanup("scheduler", func(context.Context) error {
+		scheduler.StopAll()
+		return nil
+	})
+	return nil
+}
+
+func (a *App) registerReloadHandlers(cors *security.CorsController) {
+	a.reload.Register("oauth-provider", func(event config.ConfigEvent) {
+		if ok, providerName := config.IsChangedT[string](event, config.OAuthProviderKey); ok {
+			if providerName == "" || providerName == "none" {
+				providerName = "github"
+			}
+			oidcProvider, err := database.GetOidcConfigByName(providerName)
+			if err != nil {
+				logger.Errorf("server", "Failed to get OIDC provider config: %v", err)
+				return
+			}
+			logger.Infof("server", "Using %s as OIDC provider", oidcProvider.Name)
+			if err := oauth.LoadProvider(oidcProvider.Name, oidcProvider.Addition); err != nil {
+				auditlog.EventLog("error", fmt.Sprintf("Failed to load OIDC provider: %v", err))
+			}
+		}
+	})
+	a.reload.Register("geoip-provider", func(event config.ConfigEvent) {
+		if event.IsChanged(config.GeoIpProviderKey) {
+			go geoip.InitGeoIp()
+		}
+	})
+	a.reload.Register("message-sender", func(event config.ConfigEvent) {
+		if event.IsChanged(config.NotificationMethodKey) {
+			go messageSender.Initialize()
+		}
+	})
+	a.reload.Register("cors", func(event config.ConfigEvent) { cors.Update(event) })
+}
+
+// BuildRouter constructs the normal application router and starts reloads.
+func (a *App) BuildRouter() error {
+	r := gin.New()
+	r.Use(logger.GinLogger(), logger.GinRecovery())
+	cors := security.NewCorsController(a.settings.CorsOriginCheckEnabled, a.settings.CorsAllowedOrigins)
+	r.Use(cors.Middleware(), api.IdentityMiddleware(), api.PrivateSiteMiddleware(), noStoreAPIResponses())
+
+	// The recovery UI belongs only to its temporary restricted listener.
+	r.GET(recoveryweb.PagePath, func(c *gin.Context) {
+		c.Redirect(http.StatusTemporaryRedirect, "/")
+	})
+	router.Register(r)
+	a.registerReloadHandlers(cors)
+	a.reload.Start()
+	a.engine = r
+	return nil
+}
+
+// Run starts the normal HTTP server and blocks until shutdown or fatal error.
+func (a *App) Run() error {
+	a.server = &http.Server{Addr: a.listenAddr, Handler: a.engine}
+	serverErr := make(chan error, 1)
+	logger.Infof("server", "Starting server on %s ...", a.listenAddr)
+	go func() {
+		if err := a.server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			serverErr <- err
+		}
+	}()
+
+	quit := make(chan os.Signal, 1)
+	signal.Notify(quit, os.Interrupt, syscall.SIGTERM)
+	defer signal.Stop(quit)
+	select {
+	case err := <-serverErr:
+		a.onFatal(err)
+		return fmt.Errorf("listen: %w", err)
+	case reason := <-lifecycle.RestartRequests():
+		logger.Infof("server", "Restarting service for %s", reason)
+		if err := a.Shutdown(); err != nil {
+			logger.Errorf("server", "Cleanup before restart failed: %v", err)
+		}
+		return fmt.Errorf("%w: %s", ErrRestartRequested, reason)
+	case <-quit:
+		return a.Shutdown()
+	}
+}
+
+// Shutdown stops HTTP first, then releases registered resources in LIFO order.
+func (a *App) Shutdown() error {
+	if a.dbReady {
+		auditlog.Log("", "", "server is shutting down", "info")
+	}
+	httpCtx, cancelHTTP := context.WithTimeout(context.Background(), httpShutdownTimeout)
+	defer cancelHTTP()
+	if a.server != nil {
+		if err := a.server.Shutdown(httpCtx); err != nil {
+			logger.Infof("server", "HTTP server forced to shutdown: %v", err)
+		}
+	}
+
+	cleanupCtx, cancelCleanup := context.WithTimeout(context.Background(), resourceCleanupTimeout)
+	defer cancelCleanup()
+	return a.runCleanups(cleanupCtx)
+}
+
+func (a *App) onFatal(err error) {
+	if a.dbReady {
+		auditlog.Log("", "", "server encountered a fatal error: "+err.Error(), "error")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), resourceCleanupTimeout)
+	defer cancel()
+	if cleanupErr := a.runCleanups(ctx); cleanupErr != nil {
+		logger.Errorf("server", "Cleanup after fatal server error failed: %v", cleanupErr)
+	}
+}
+
+func (a *App) runCleanups(ctx context.Context) error {
+	var cleanupErrors []error
+	for i := len(a.cleanups) - 1; i >= 0; i-- {
+		cleanup := a.cleanups[i]
+		if err := cleanup.fn(ctx); err != nil {
+			logger.Errorf("server", "cleanup %q failed: %v", cleanup.name, err)
+			cleanupErrors = append(cleanupErrors, fmt.Errorf("cleanup %q: %w", cleanup.name, err))
+		}
+	}
+	return errors.Join(cleanupErrors...)
+}
+
+func registerScheduledWork() {
+	if err := tasks.ReloadPingSchedule(); err != nil {
+		logger.ErrorArgs("server", "Failed to reload ping schedule:", err)
+	}
+	if err := d_notification.ReloadLoadNotificationSchedule(); err != nil {
+		logger.ErrorArgs("server", "Failed to reload load notification schedule:", err)
+	}
+	if err := scheduler.AddFunc("records:cleanup", "@every 30m", cleanupScheduledData); err != nil {
+		logger.ErrorArgs("server", "Failed to add cleanup scheduled task:", err)
+	}
+	if err := scheduler.AddContextFunc("metrics:compact", "@every 5m", true, compactMetricStore); err != nil {
+		logger.ErrorArgs("server", "Failed to add metric compact scheduled task:", err)
+	}
+	if err := scheduler.AddFunc("notifier:traffic", "@every 1m", notifier.CheckTraffic); err != nil {
+		logger.ErrorArgs("server", "Failed to add traffic notification task:", err)
+	}
+	if err := scheduler.AddFunc("notifier:expire", "0 0 9 * * *", notifier.CheckExpireScheduledWork); err != nil {
+		logger.ErrorArgs("server", "Failed to add expire notification task:", err)
+	}
+	notifier.InitTrafficReportSchedule()
+}
+
+const taskResultRetentionDays = 30
+
+func cleanupScheduledData() {
+	before := time.Now().UTC().Add(-24 * time.Hour * taskResultRetentionDays)
+	if err := tasks.ClearTaskResultsByTimeBefore(before); err != nil {
+		logger.Errorf("server", "Failed to clean expired task results: %v", err)
+	}
+	auditlog.RemoveOldLogs()
+	accounts.RemoveExpiredSessions()
+}
+
+func compactMetricStore(ctx context.Context) {
+	compactCtx, cancel := context.WithTimeout(ctx, 15*time.Minute)
+	defer cancel()
+	written, err := metricstore.Compact(compactCtx, time.Now().UTC())
+	if errors.Is(err, metricstore.ErrCompactInProgress) {
+		return
+	}
+	if err != nil {
+		logger.Errorf("server", "Failed to compact metric store after writing %d rollup buckets: %v", written, err)
+		return
+	}
+	if written > 0 {
+		logger.Infof("server", "Metric store compacted %d rollup buckets", written)
+	}
+}

internal/sqlitetune/connector.go

@@ -0,0 +1,181 @@
+// Package sqlitetune applies a consistent SQLite baseline to every physical
+// connection opened through database/sql.
+package sqlitetune
+
+import (
+	"context"
+	"database/sql"
+	"database/sql/driver"
+	"fmt"
+	"math"
+	"time"
+
+	sqlite3 "github.com/mattn/go-sqlite3"
+)
+
+// SynchronousMode selects SQLite's synchronous durability mode.
+type SynchronousMode string
+
+const (
+	// SynchronousNormal balances write throughput and durability in WAL mode.
+	SynchronousNormal SynchronousMode = "NORMAL"
+	// SynchronousOff favors throughput over durability.
+	SynchronousOff SynchronousMode = "OFF"
+	// SynchronousFull favors durability over write throughput.
+	SynchronousFull SynchronousMode = "FULL"
+)
+
+// Options configures the SQLite PRAGMAs applied to every physical connection.
+// WAL mode is always enabled. Zero mmap size explicitly disables memory
+// mapping; it is not treated as an unset value.
+type Options struct {
+	PageSize              int
+	ForeignKeys           bool
+	BusyTimeout           time.Duration
+	CacheSizeKB           int
+	MMapSizeBytes         int64
+	TempStoreMemory       bool
+	CacheSpill            bool
+	WALAutoCheckpoint     int
+	JournalSizeLimitBytes int64
+	Synchronous           SynchronousMode
+}
+
+// Open returns a database/sql pool whose new SQLite connections are configured
+// before they are handed to callers.
+func Open(dsn string, options Options) (*sql.DB, error) {
+	options, err := normalize(options)
+	if err != nil {
+		return nil, err
+	}
+
+	driver := &sqlite3.SQLiteDriver{
+		ConnectHook: func(conn *sqlite3.SQLiteConn) error {
+			return applyDriverConn(conn, options)
+		},
+	}
+	return sql.OpenDB(&connector{driver: driver, dsn: dsn}), nil
+}
+
+// Apply configures one physical connection from a caller-owned pool. Future
+// connections in that pool remain the caller's responsibility; use Open when
+// this package owns the pool and every physical connection must be configured.
+func Apply(ctx context.Context, db *sql.DB, options Options) error {
+	options, err := normalize(options)
+	if err != nil {
+		return err
+	}
+
+	conn, err := db.Conn(ctx)
+	if err != nil {
+		return fmt.Errorf("sqlite tune: acquire connection: %w", err)
+	}
+	defer conn.Close()
+
+	for _, pragma := range pragmas(options) {
+		if _, err := conn.ExecContext(ctx, pragma); err != nil {
+			return fmt.Errorf("sqlite tune: apply %q: %w", pragma, err)
+		}
+	}
+	return nil
+}
+
+type connector struct {
+	driver *sqlite3.SQLiteDriver
+	dsn    string
+}
+
+func (c *connector) Connect(ctx context.Context) (driver.Conn, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	conn, err := c.driver.Open(c.dsn)
+	if err != nil {
+		return nil, err
+	}
+	if err := ctx.Err(); err != nil {
+		_ = conn.Close()
+		return nil, err
+	}
+	return conn, nil
+}
+
+func (c *connector) Driver() driver.Driver {
+	return c.driver
+}
+
+func applyDriverConn(conn *sqlite3.SQLiteConn, options Options) error {
+	for _, pragma := range pragmas(options) {
+		if _, err := conn.Exec(pragma, nil); err != nil {
+			return fmt.Errorf("sqlite tune: apply %q: %w", pragma, err)
+		}
+	}
+	return nil
+}
+
+func normalize(options Options) (Options, error) {
+	if options.Synchronous == "" {
+		options.Synchronous = SynchronousNormal
+	}
+	switch options.Synchronous {
+	case SynchronousNormal, SynchronousOff, SynchronousFull:
+	default:
+		return options, fmt.Errorf("sqlite tune: unsupported synchronous mode %q", options.Synchronous)
+	}
+	if options.PageSize < 0 {
+		return options, fmt.Errorf("sqlite tune: page size cannot be negative")
+	}
+	if options.BusyTimeout < 0 {
+		return options, fmt.Errorf("sqlite tune: busy timeout cannot be negative")
+	}
+	if options.CacheSizeKB <= 0 {
+		return options, fmt.Errorf("sqlite tune: cache size must be positive")
+	}
+	if options.MMapSizeBytes < 0 {
+		return options, fmt.Errorf("sqlite tune: mmap size cannot be negative")
+	}
+	if options.WALAutoCheckpoint <= 0 {
+		return options, fmt.Errorf("sqlite tune: WAL auto-checkpoint must be positive")
+	}
+	// SQLite uses -1 to disable the post-checkpoint WAL size limit. Preserve
+	// that documented value for callers that explicitly opt out of the cap.
+	if options.JournalSizeLimitBytes < -1 {
+		return options, fmt.Errorf("sqlite tune: journal size limit cannot be less than -1")
+	}
+	return options, nil
+}
+
+func pragmas(options Options) []string {
+	pragmas := make([]string, 0, 11)
+	if options.PageSize > 0 {
+		pragmas = append(pragmas, fmt.Sprintf("PRAGMA page_size = %d", options.PageSize))
+	}
+	pragmas = append(pragmas, "PRAGMA journal_mode = WAL")
+	if options.ForeignKeys {
+		pragmas = append(pragmas, "PRAGMA foreign_keys = ON")
+	}
+	pragmas = append(pragmas,
+		fmt.Sprintf("PRAGMA synchronous = %s", options.Synchronous),
+		fmt.Sprintf("PRAGMA busy_timeout = %d", durationMillis(options.BusyTimeout)),
+		fmt.Sprintf("PRAGMA cache_size = -%d", options.CacheSizeKB),
+		fmt.Sprintf("PRAGMA mmap_size = %d", options.MMapSizeBytes),
+	)
+	if options.TempStoreMemory {
+		pragmas = append(pragmas, "PRAGMA temp_store = MEMORY")
+	} else {
+		pragmas = append(pragmas, "PRAGMA temp_store = FILE")
+	}
+	if options.CacheSpill {
+		pragmas = append(pragmas, "PRAGMA cache_spill = ON")
+	} else {
+		pragmas = append(pragmas, "PRAGMA cache_spill = OFF")
+	}
+	return append(pragmas,
+		fmt.Sprintf("PRAGMA wal_autocheckpoint = %d", options.WALAutoCheckpoint),
+		fmt.Sprintf("PRAGMA journal_size_limit = %d", options.JournalSizeLimitBytes),
+	)
+}
+
+func durationMillis(d time.Duration) int {
+	return int(math.Ceil(float64(d) / float64(time.Millisecond)))
+}

internal/sqlitetune/connector_test.go

@@ -0,0 +1,21 @@
+package sqlitetune
+
+import (
+	"testing"
+	"time"
+)
+
+func TestNormalizeAllowsUnlimitedJournalSize(t *testing.T) {
+	options, err := normalize(Options{
+		BusyTimeout:           5 * time.Second,
+		CacheSizeKB:           8,
+		WALAutoCheckpoint:     1,
+		JournalSizeLimitBytes: -1,
+	})
+	if err != nil {
+		t.Fatalf("normalize unlimited journal size: %v", err)
+	}
+	if options.JournalSizeLimitBytes != -1 {
+		t.Fatalf("journal size limit = %d, want -1", options.JournalSizeLimitBytes)
+	}
+}

main.go

@@ -1,22 +1,21 @@
 package main
 
 import (
-	"log"
 	"log/slog"
 
 	"github.com/komari-monitor/komari/cmd"
 	"github.com/komari-monitor/komari/utils"
-	logutil "github.com/komari-monitor/komari/utils/log"
+	logger "github.com/komari-monitor/komari/utils/log"
 )
 
 func main() {
 	if utils.VersionHash == "unknown" {
-		logutil.SetupGlobalLogger(slog.LevelDebug)
+		logger.Setup(slog.LevelDebug)
 	} else {
-		logutil.SetupGlobalLogger(slog.LevelInfo)
+		logger.Setup(slog.LevelInfo)
 	}
 
-	log.Printf("Komari Monitor %s (hash: %s)", utils.CurrentVersion, utils.VersionHash)
+	logger.Infof("server", "Komari Monitor %s (hash: %s)", utils.CurrentVersion, utils.VersionHash)
 
 	cmd.Execute()
 }

pkg/metric/aggregate.go

@@ -26,9 +26,6 @@ func AggregatePoints(points []Point, query AggregateQuery) ([]AggregatePoint, er
 		return nil, err
 	}
 	if len(points) == 0 {
-		if query.FillEmpty {
-			return emptyBuckets(query), nil
-		}
 		return []AggregatePoint{}, nil
 	}
 
@@ -60,34 +57,11 @@ func AggregatePoints(points []Point, query AggregateQuery) ([]AggregatePoint, er
 		}
 	}
 
-	var keys []aggregateGroupKey
-	if query.FillEmpty {
-		seriesKeys := sortedAggregateSeriesKeys(seriesTags)
-		if len(seriesKeys) == 0 {
-			tagsHash, _, err := tagsFingerprint(query.Tags)
-			if err != nil {
-				return nil, err
-			}
-			series := aggregateSeriesKey{
-				metricName: query.MetricName,
-				entityID:   query.EntityID,
-				tagsHash:   tagsHash,
-			}
-			seriesKeys = append(seriesKeys, series)
-			seriesTags[series] = cloneStringMap(query.Tags)
-		}
-		for t := alignTime(query.Start, query.Interval); !t.After(query.End); t = t.Add(query.Interval) {
-			bucket := t.UnixNano()
-			for _, series := range seriesKeys {
-				keys = append(keys, aggregateGroupKey{aggregateSeriesKey: series, bucket: bucket})
-			}
-		}
-	} else {
-		for key := range groups {
-			keys = append(keys, key)
-		}
-		sortAggregateGroupKeys(keys)
+	keys := make([]aggregateGroupKey, 0, len(groups))
+	for key := range groups {
+		keys = append(keys, key)
 	}
+	sortAggregateGroupKeys(keys)
 
 	out := make([]AggregatePoint, 0, len(keys))
 	for _, key := range keys {
@@ -108,23 +82,6 @@ func AggregatePoints(points []Point, query AggregateQuery) ([]AggregatePoint, er
 	return out, nil
 }
 
-func sortedAggregateSeriesKeys(tags map[aggregateSeriesKey]map[string]string) []aggregateSeriesKey {
-	keys := make([]aggregateSeriesKey, 0, len(tags))
-	for key := range tags {
-		keys = append(keys, key)
-	}
-	sort.Slice(keys, func(i, j int) bool {
-		if keys[i].metricName != keys[j].metricName {
-			return keys[i].metricName < keys[j].metricName
-		}
-		if keys[i].entityID != keys[j].entityID {
-			return keys[i].entityID < keys[j].entityID
-		}
-		return keys[i].tagsHash < keys[j].tagsHash
-	})
-	return keys
-}
-
 func sortAggregateGroupKeys(keys []aggregateGroupKey) {
 	sort.Slice(keys, func(i, j int) bool {
 		if keys[i].bucket != keys[j].bucket {
@@ -346,19 +303,3 @@ func alignTime(t time.Time, interval time.Duration) time.Time {
 	rem := ((nano % size) + size) % size
 	return time.Unix(0, nano-rem).UTC()
 }
-
-// emptyBuckets builds zero-count aggregate buckets for an empty range.
-//
-// emptyBuckets 根据查询范围生成空聚合桶，用于 FillEmpty 场景。
-func emptyBuckets(query AggregateQuery) []AggregatePoint {
-	var out []AggregatePoint
-	for t := alignTime(query.Start, query.Interval); !t.After(query.End); t = t.Add(query.Interval) {
-		out = append(out, AggregatePoint{
-			MetricName: query.MetricName,
-			EntityID:   query.EntityID,
-			Bucket:     t,
-			Tags:       cloneStringMap(query.Tags),
-		})
-	}
-	return out
-}

pkg/metric/config.go

@@ -33,10 +33,6 @@ type Config struct {
 	//
 	// TablePrefix 是 Store 管理的所有表名前缀。
 	TablePrefix string
-	// DefaultRetentionDays is used when a metric definition omits retention.
-	//
-	// DefaultRetentionDays 在指标定义未设置保留时间时使用。
-	DefaultRetentionDays int
 	// AutoMigrate controls whether Open creates or updates the schema.
 	//
 	// AutoMigrate 控制 Open 是否创建或更新表结构。
@@ -62,12 +58,10 @@ type Config struct {
 	// SQLite 保存 SQLite 专用选项。
 	SQLite SQLiteOptions
 
-	// RollupPolicy configures downsampling tiers and tiered retention. When it
-	// defines tiers, Store.Compact materializes them and enforces every
-	// retention window. The zero value disables rollups (raw points only).
+	// RollupPolicy configures downsampling tiers and tiered retention. Exact raw
+	// samples use the Store's fixed ten-minute in-memory window.
 	//
-	// RollupPolicy 配置降采样层级和分层保留时间；定义层级后，
-	// Store.Compact 会生成 rollup 并执行保留策略。零值表示禁用 rollup。
+	// RollupPolicy 配置降采样层级和分层保留时间。
 	RollupPolicy RollupPolicy
 }
 
@@ -103,6 +97,8 @@ type SQLiteOptions struct {
 	//
 	// WALAutoCheckpoint 设置 SQLite WAL 自动 checkpoint 页数。
 	WALAutoCheckpoint int
+	// JournalSizeLimitBytes caps the WAL retained after checkpoints.
+	JournalSizeLimitBytes int64
 	// ReadPoolSize, when > 0, opens a second read-only connection pool with
 	// this many connections for SELECT-style calls. SQLite serializes writes,
 	// but WAL lets readers run concurrently, so a read pool lifts read
@@ -151,22 +147,32 @@ type Option func(*Config)
 // DefaultConfig 返回指定后端的默认配置。
 func DefaultConfig(driver Driver, dsn string) Config {
 	return Config{
-		Driver:               driver,
-		DSN:                  dsn,
-		TablePrefix:          "metric_",
-		DefaultRetentionDays: 90,
-		AutoMigrate:          true,
-		MaxOpenConns:         25,
-		MaxIdleConns:         5,
-		ConnMaxLifetime:      time.Hour,
-		ConnectTimeout:       10 * time.Second,
+		Driver:          driver,
+		DSN:             dsn,
+		TablePrefix:     "metric_",
+		AutoMigrate:     true,
+		MaxOpenConns:    25,
+		MaxIdleConns:    5,
+		ConnMaxLifetime: time.Hour,
+		ConnectTimeout:  10 * time.Second,
 		SQLite: SQLiteOptions{
-			PerformanceProfile: SQLiteProfileBalanced,
-			BusyTimeout:        5 * time.Second,
-			CacheSizeKB:        64 * 1024,
-			TempStoreMemory:    true,
-			MMapSizeBytes:      256 * 1024 * 1024,
-			WALAutoCheckpoint:  1000,
+			PerformanceProfile:    SQLiteProfileBalanced,
+			BusyTimeout:           5 * time.Second,
+			CacheSizeKB:           16 * 1024,
+			TempStoreMemory:       false,
+			MMapSizeBytes:         32 * 1024 * 1024,
+			WALAutoCheckpoint:     1000,
+			JournalSizeLimitBytes: 4 * 1024 * 1024,
+		},
+		RollupPolicy: RollupPolicy{
+			RawRetention: 10 * time.Minute,
+			Tiers: []RollupTier{
+				{Interval: time.Minute, Retention: 600 * time.Minute},
+				{Interval: 5 * time.Minute, Retention: 600 * 5 * time.Minute},
+				{Interval: time.Hour, Retention: 600 * time.Hour},
+				{Interval: 24 * time.Hour, Retention: 100 * 365 * 24 * time.Hour},
+			},
+			Compression: 30,
 		},
 	}
 }
@@ -233,6 +239,10 @@ func SQLiteConfig(dsn string) Config {
 	// is honored instead of being mistaken for "unset".
 	cfg.MaxOpenConns = 1
 	cfg.MaxIdleConns = 1
+	// SQLite benefits from warm page caches. Unlike client/server backends,
+	// rotating its local file connections only adds churn, so the default keeps
+	// them until the Store closes. Callers can still set a lifetime explicitly.
+	cfg.ConnMaxLifetime = 0
 	return cfg
 }
 
@@ -268,15 +278,6 @@ func WithTablePrefix(prefix string) Option {
 	}
 }
 
-// WithDefaultRetention sets the default metric retention in days.
-//
-// WithDefaultRetention 设置指标默认保留天数。
-func WithDefaultRetention(days int) Option {
-	return func(c *Config) {
-		c.DefaultRetentionDays = days
-	}
-}
-
 // WithAutoMigrate controls whether Open creates the schema automatically.
 //
 // WithAutoMigrate 控制 Open 时是否自动创建表结构。
@@ -385,6 +386,13 @@ func WithSQLiteWALAutoCheckpoint(pages int) Option {
 	}
 }
 
+// WithSQLiteJournalSizeLimit sets the WAL bytes retained after checkpoints.
+func WithSQLiteJournalSizeLimit(bytes int64) Option {
+	return func(c *Config) {
+		c.SQLite.JournalSizeLimitBytes = bytes
+	}
+}
+
 // WithSQLiteReadPool enables a dedicated read-only connection pool of n
 // connections for SQLite. Writes stay on the single primary connection
 // (SQLite serializes them); reads fan out across the pool, which WAL mode
@@ -401,10 +409,10 @@ func WithSQLiteReadPool(n int) Option {
 
 // WithRollupPolicy sets the downsampling/retention ladder. Compact uses it to
 // build rollup tiers (each progressively coarser and longer-lived) and to age
-// out raw points and expired tiers.
+// out expired summary tiers.
 //
 // WithRollupPolicy 设置降采样与保留时间阶梯；Compact 会据此构建逐级
-// 更粗、保留更久的 rollup，并清理过期原始点和过期层级。
+// 更粗、保留更久的 rollup，并清理过期层级。
 func WithRollupPolicy(p RollupPolicy) Option {
 	return func(c *Config) {
 		c.RollupPolicy = p
@@ -442,8 +450,17 @@ func (c Config) Validate() error {
 			return fmt.Errorf("%w: table prefix must contain only letters, digits, and underscores", ErrInvalidArgument)
 		}
 	}
-	if c.DefaultRetentionDays <= 0 {
-		return fmt.Errorf("%w: default retention days must be positive", ErrInvalidArgument)
+	// Bound generated index names to the backend identifier limit. Restructure
+	// performs the stricter check required by its temporary "rebuild_" prefix.
+	switch c.Driver {
+	case DriverMySQL:
+		if len(c.TablePrefix) > 35 {
+			return fmt.Errorf("%w: table prefix is too long for MySQL identifiers", ErrInvalidArgument)
+		}
+	case DriverPostgreSQL:
+		if len(c.TablePrefix) > 34 {
+			return fmt.Errorf("%w: table prefix is too long for PostgreSQL identifiers", ErrInvalidArgument)
+		}
 	}
 	if err := c.RollupPolicy.Validate(); err != nil {
 		return err

pkg/metric/config_test.go

@@ -12,7 +12,6 @@ func TestBackendBuildersApplyOptions(t *testing.T) {
 	cfg := SQLite(
 		"file:metrics.db?cache=shared",
 		WithTablePrefix("x_metric_"),
-		WithDefaultRetention(180),
 		WithAutoMigrate(false),
 		WithMaxOpenConns(10),
 		WithMaxIdleConns(2),
@@ -26,9 +25,6 @@ func TestBackendBuildersApplyOptions(t *testing.T) {
 	if cfg.TablePrefix != "x_metric_" {
 		t.Fatalf("table prefix option was not applied: %q", cfg.TablePrefix)
 	}
-	if cfg.DefaultRetentionDays != 180 {
-		t.Fatalf("default retention option was not applied: %d", cfg.DefaultRetentionDays)
-	}
 	if cfg.AutoMigrate {
 		t.Fatalf("auto migrate option was not applied")
 	}

pkg/metric/dialect.go

@@ -1,7 +1,6 @@
 package metric
 
 import (
-	"database/sql"
 	"fmt"
 	"strings"
 )
@@ -24,7 +23,6 @@ type dialect interface {
 	autoIncrementPrimaryKey() string
 	nowExpr() string
 	insertDefinitionSQL(t tables) string
-	upsertPointSQL(t tables, rowCount int) string
 	// jsonExtractEquals renders a boolean predicate comparing the text value at
 	// key inside a JSON column to a bind placeholder. The key is interpolated
 	// into the SQL (callers must restrict it to a safe charset); the compared
@@ -38,21 +36,6 @@ type dialect interface {
 	//
 	// blobType 是 rollup t-digest sketch 的列类型。
 	blobType() string
-	// upsertRollupSQL builds a single-row upsert for one rollup bucket cell.
-	//
-	// upsertRollupSQL 为单个 rollup 桶单元构造单行 upsert。
-	upsertRollupSQL(t tables) string
-	// compactTxOptions returns the transaction options used for the compaction
-	// transaction. PostgreSQL/MySQL escalate to SERIALIZABLE so the raw scan and
-	// the raw deletion share one snapshot and a point inserted between them
-	// cannot be deleted without first being rolled up. SQLite returns nil
-	// (its default) because a single connection already serializes writes.
-	//
-	// compactTxOptions 返回 compaction 事务使用的事务选项。PostgreSQL/MySQL 会
-	// 提升到 SERIALIZABLE，使 raw 扫描和 raw 删除共享同一个快照，让两者之间写入
-	// 的点不会在尚未进入 rollup 前被删除。SQLite 返回 nil（默认），因为单连接
-	// 已经串行化写入。
-	compactTxOptions() *sql.TxOptions
 }
 
 // tables stores the physical table names used by a Store.
@@ -63,14 +46,20 @@ type tables struct {
 	//
 	// definitions 是指标定义表。
 	definitions string
-	// points is the raw points table.
-	//
-	// points 是原始采样点表。
+	// points and watermarks name legacy tables read only by the explicit
+	// structure rebuild. The normalized schema never creates either table.
 	points string
+	// series interns the name/entity/tag/tag-hash tuple.
+	series string
+	// resolutions interns rollup intervals in milliseconds.
+	resolutions string
+	// labels interns labels independently from series tags.
+	labels string
 	// rollups is the downsampled rollups table.
 	//
 	// rollups 是降采样 rollup 表。
-	rollups string
+	rollups    string
+	watermarks string
 }
 
 // newDialect returns the SQL dialect implementation for a backend.
@@ -122,7 +111,7 @@ func (sqliteDialect) nowExpr() string { return "CURRENT_TIMESTAMP" }
 // insertDefinitionSQL 构造 SQLite 指标定义 upsert SQL。
 func (sqliteDialect) insertDefinitionSQL(t tables) string {
 	return fmt.Sprintf(`INSERT INTO %s
-		(name, type, unit, description, retention_days, metadata, created_at, updated_at)
+		(name, type, unit, description, retention_days, metadata, created_at_milli, updated_at_milli)
 		VALUES (?, ?, ?, ?, ?, ?, ?, ?)
 		ON CONFLICT(name) DO UPDATE SET
 			type = excluded.type,
@@ -130,18 +119,7 @@ func (sqliteDialect) insertDefinitionSQL(t tables) string {
 			description = excluded.description,
 			retention_days = excluded.retention_days,
 			metadata = excluded.metadata,
-			updated_at = excluded.updated_at`, t.definitions)
-}
-
-// upsertPointSQL builds SQL for inserting or updating metric points.
-//
-// upsertPointSQL 构造 SQLite 采样点批量 upsert SQL。
-func (sqliteDialect) upsertPointSQL(t tables, rowCount int) string {
-	return buildInsertPointsSQL(t.points, sqliteDialect{}, rowCount, `ON CONFLICT(metric_name, entity_id, tags_hash, ts_nano) DO UPDATE SET
-		value = excluded.value,
-		tags = excluded.tags,
-		labels = excluded.labels,
-		created_at = excluded.created_at`)
+			updated_at_milli = excluded.updated_at_milli`, t.definitions)
 }
 
 // mysqlDialect implements SQL rendering for MySQL.
@@ -179,7 +157,7 @@ func (mysqlDialect) nowExpr() string { return "CURRENT_TIMESTAMP" }
 // insertDefinitionSQL 构造 MySQL 指标定义 upsert SQL。
 func (mysqlDialect) insertDefinitionSQL(t tables) string {
 	return fmt.Sprintf(`INSERT INTO %s
-		(name, type, unit, description, retention_days, metadata, created_at, updated_at)
+		(name, type, unit, description, retention_days, metadata, created_at_milli, updated_at_milli)
 		VALUES (?, ?, ?, ?, ?, ?, ?, ?)
 		ON DUPLICATE KEY UPDATE
 			type = VALUES(type),
@@ -187,18 +165,7 @@ func (mysqlDialect) insertDefinitionSQL(t tables) string {
 			description = VALUES(description),
 			retention_days = VALUES(retention_days),
 			metadata = VALUES(metadata),
-			updated_at = VALUES(updated_at)`, t.definitions)
-}
-
-// upsertPointSQL builds SQL for inserting or updating metric points.
-//
-// upsertPointSQL 构造 MySQL 采样点批量 upsert SQL。
-func (mysqlDialect) upsertPointSQL(t tables, rowCount int) string {
-	return buildInsertPointsSQL(t.points, mysqlDialect{}, rowCount, `ON DUPLICATE KEY UPDATE
-		value = VALUES(value),
-		tags = VALUES(tags),
-		labels = VALUES(labels),
-		created_at = VALUES(created_at)`)
+			updated_at_milli = VALUES(updated_at_milli)`, t.definitions)
 }
 
 // postgresDialect implements SQL rendering for PostgreSQL.
@@ -236,7 +203,7 @@ func (postgresDialect) nowExpr() string { return "CURRENT_TIMESTAMP" }
 // insertDefinitionSQL 构造 PostgreSQL 指标定义 upsert SQL。
 func (postgresDialect) insertDefinitionSQL(t tables) string {
 	return fmt.Sprintf(`INSERT INTO %s
-		(name, type, unit, description, retention_days, metadata, created_at, updated_at)
+		(name, type, unit, description, retention_days, metadata, created_at_milli, updated_at_milli)
 		VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7, $8)
 		ON CONFLICT(name) DO UPDATE SET
 			type = EXCLUDED.type,
@@ -244,52 +211,7 @@ func (postgresDialect) insertDefinitionSQL(t tables) string {
 			description = EXCLUDED.description,
 			retention_days = EXCLUDED.retention_days,
 			metadata = EXCLUDED.metadata,
-			updated_at = EXCLUDED.updated_at`, t.definitions)
-}
-
-// upsertPointSQL builds SQL for inserting or updating metric points.
-//
-// upsertPointSQL 构造 PostgreSQL 采样点批量 upsert SQL。
-func (postgresDialect) upsertPointSQL(t tables, rowCount int) string {
-	return buildInsertPointsSQL(t.points, postgresDialect{}, rowCount, `ON CONFLICT(metric_name, entity_id, tags_hash, ts_nano) DO UPDATE SET
-		value = EXCLUDED.value,
-		tags = EXCLUDED.tags,
-		labels = EXCLUDED.labels,
-		created_at = EXCLUDED.created_at`)
-}
-
-// buildInsertPointsSQL builds a multi-row insert statement for metric points.
-//
-// buildInsertPointsSQL 构造多行采样点 INSERT/UPSERT SQL。
-func buildInsertPointsSQL(table string, d dialect, rowCount int, suffix string) string {
-	var b strings.Builder
-	b.WriteString("INSERT INTO ")
-	b.WriteString(table)
-	b.WriteString(" (metric_name, entity_id, tags_hash, ts_nano, value, tags, labels, created_at) VALUES ")
-	arg := 1
-	rows := make([]string, rowCount)
-	for i := 0; i < rowCount; i++ {
-		parts := make([]string, 8)
-		for j := range parts {
-			// Columns are (metric_name, entity_id, tags_hash, ts_nano, value, tags,
-			// labels, created_at); positions 5 and 6 (0-indexed) are JSON values.
-			// tags_hash makes the tag set part of a point's identity, so points
-			// that share entity+timestamp but differ in tags no longer collide.
-			if j == 5 || j == 6 {
-				parts[j] = d.jsonPlaceholder(arg)
-			} else {
-				parts[j] = d.placeholder(arg)
-			}
-			arg++
-		}
-		rows[i] = "(" + strings.Join(parts, ", ") + ")"
-	}
-	b.WriteString(strings.Join(rows, ", "))
-	if suffix != "" {
-		b.WriteByte(' ')
-		b.WriteString(suffix)
-	}
-	return b.String()
+			updated_at_milli = EXCLUDED.updated_at_milli`, t.definitions)
 }
 
 // tableName combines a table prefix and logical table name.
@@ -306,7 +228,7 @@ func tableName(prefix, name string) string {
 // insertDefinitionOnlySQL 构造普通 INSERT（不带 upsert），供
 // CreateMetric 保持“只创建”语义；重复名称会暴露为唯一约束错误。
 func insertDefinitionOnlySQL(d dialect, t tables) string {
-	cols := "(name, type, unit, description, retention_days, metadata, created_at, updated_at)"
+	cols := "(name, type, unit, description, retention_days, metadata, created_at_milli, updated_at_milli)"
 	ph := []string{
 		d.placeholder(1),
 		d.placeholder(2),

pkg/metric/dialect_rollup.go

@@ -1,160 +1,6 @@
 package metric
 
-import (
-	"database/sql"
-	"fmt"
-	"strings"
-)
-
-// rollupColumns is the fixed column list for the rollups table, shared by the
-// upsert builder and the row scanner so they cannot drift apart. tags_hash is a
-// stable fingerprint of the (canonical) tag set; tags carries the tag map itself
-// so reads can return it and tag filters can be pushed down. Including the tag
-// dimension in the key is what keeps each distinct tag combination (e.g. a GPU
-// device_index) as its own rollup series instead of being merged together.
-//
-// rollupColumns 是 rollups 表固定列清单，由 upsert 构造器和行扫描器共用，
-// 避免二者漂移。tags_hash 是（规范化）标签集合的稳定指纹；tags 携带标签 map
-// 本身，因此读取时可以返回它，也能下推标签过滤。把标签维度纳入 key，正是让
-// 每个不同标签组合（例如 GPU 的 device_index）保留为自己的 rollup 序列、
-// 而不是被合并在一起的原因。
-const rollupColumns = "metric_name, entity_id, tags_hash, tags, resolution_nano, bucket_nano, " +
-	"count, sum, sum_sq, min_val, max_val, first_val, first_ts, last_val, last_ts, digest, created_at"
-
-// rollupColumnCount is the number of columns in rollupColumns.
-//
-// rollupColumnCount 是 rollupColumns 中的列数量。
-const rollupColumnCount = 17
-
-// rollupTagsArgIndex is the 1-based position of the `tags` JSON column in
-// rollupColumns. PostgreSQL needs a ::jsonb cast on that bind placeholder.
-//
-// rollupTagsArgIndex 是 tags JSON 列在 rollupColumns 中的 1 基位置；
-// PostgreSQL 需要在对应占位符上追加 ::jsonb 转换。
-const rollupTagsArgIndex = 4
-
-// blobType returns the column type used to store the t-digest sketch.
-//
-// blobType 返回用于保存 t-digest 摘要的二进制列类型。
-func (sqliteDialect) blobType() string { return "BLOB" }
-
-// blobType returns the binary column type used for t-digest blobs.
-//
-// blobType 返回 MySQL 用于保存 t-digest 摘要的二进制列类型。
-func (mysqlDialect) blobType() string { return "LONGBLOB" }
-
-// blobType returns the binary column type used for t-digest blobs.
-//
-// blobType 返回 PostgreSQL 用于保存 t-digest 摘要的二进制列类型。
+// blobType returns the backend-specific column type for t-digest sketches.
+func (sqliteDialect) blobType() string   { return "BLOB" }
+func (mysqlDialect) blobType() string    { return "LONGBLOB" }
 func (postgresDialect) blobType() string { return "BYTEA" }
-
-// compactTxOptions returns nil so SQLite uses its default isolation. A single
-// write connection already serializes the compaction transaction against
-// concurrent writers, so the raw scan and the raw deletion observe a stable
-// view without escalating the isolation level.
-//
-// compactTxOptions 返回 nil，让 SQLite 使用默认隔离级别。单个写连接已经把
-// compaction 事务与并发写入串行化，因此 raw 扫描和 raw 删除无需提升隔离级别
-// 即可观察到稳定视图。
-func (sqliteDialect) compactTxOptions() *sql.TxOptions { return nil }
-
-// compactTxOptions escalates to SERIALIZABLE so a point inserted between the raw
-// scan and the raw deletion cannot be deleted without first being rolled up.
-// InnoDB's SERIALIZABLE turns the scan into a locking read that blocks such a
-// concurrent insert in the scanned range until the compaction commits.
-//
-// compactTxOptions 提升到 SERIALIZABLE，使在 raw 扫描和 raw 删除之间写入的点
-// 不会在尚未进入 rollup 前被删除。InnoDB 的 SERIALIZABLE 会把扫描变为加锁读，
-// 在 compaction 提交前阻塞扫描范围内的此类并发插入。
-func (mysqlDialect) compactTxOptions() *sql.TxOptions {
-	return &sql.TxOptions{Isolation: sql.LevelSerializable}
-}
-
-// compactTxOptions escalates to SERIALIZABLE so the raw scan and the raw
-// deletion share one snapshot. A concurrent insert into the scanned range that
-// would otherwise be deleted without a rollup instead triggers a serialization
-// failure that CompactMetric retries on a fresh snapshot.
-//
-// compactTxOptions 提升到 SERIALIZABLE，使 raw 扫描和 raw 删除共享同一个快照。
-// 对扫描范围内的并发插入（否则会被删除却没有进入 rollup）会触发序列化失败，
-// 由 CompactMetric 在新快照上重试。
-func (postgresDialect) compactTxOptions() *sql.TxOptions {
-	return &sql.TxOptions{Isolation: sql.LevelSerializable}
-}
-
-// upsertRollupSQL builds a single-row upsert for a rollup cell, keyed by
-// (metric_name, entity_id, tags_hash, resolution_nano, bucket_nano). Compact
-// recomputes a bucket wholesale from its inputs each run, so the conflict action
-// replaces every summary column rather than trying to merge in SQL.
-//
-// upsertRollupSQL 构造单个 rollup 单元的 upsert SQL，其 key 为
-// (metric_name, entity_id, tags_hash, resolution_nano, bucket_nano)。Compact
-// 每次都会从输入整体重新计算一个桶，因此冲突动作会替换每个摘要列，
-// 而不是尝试在 SQL 中合并。
-func (d sqliteDialect) upsertRollupSQL(t tables) string {
-	return buildUpsertRollupSQL(t.rollups, d, sqliteRollupConflict)
-}
-
-// upsertRollupSQL builds backend-specific SQL for upserting a rollup cell.
-//
-// upsertRollupSQL 构造 MySQL rollup 单元 upsert SQL。
-func (d mysqlDialect) upsertRollupSQL(t tables) string {
-	return buildUpsertRollupSQL(t.rollups, d, mysqlRollupConflict)
-}
-
-// upsertRollupSQL builds backend-specific SQL for upserting a rollup cell.
-//
-// upsertRollupSQL 构造 PostgreSQL rollup 单元 upsert SQL。
-func (d postgresDialect) upsertRollupSQL(t tables) string {
-	return buildUpsertRollupSQL(t.rollups, d, postgresRollupConflict)
-}
-
-// sqliteRollupConflict is the SQLite conflict clause for replacing rollup cells.
-//
-// sqliteRollupConflict 是 SQLite 用于替换 rollup 单元的冲突处理子句。
-const sqliteRollupConflict = `ON CONFLICT(metric_name, entity_id, tags_hash, resolution_nano, bucket_nano) DO UPDATE SET
-	tags = excluded.tags,
-	count = excluded.count, sum = excluded.sum, sum_sq = excluded.sum_sq,
-	min_val = excluded.min_val, max_val = excluded.max_val,
-	first_val = excluded.first_val, first_ts = excluded.first_ts,
-	last_val = excluded.last_val, last_ts = excluded.last_ts,
-	digest = excluded.digest, created_at = excluded.created_at`
-
-// postgresRollupConflict is the PostgreSQL conflict clause for replacing rollup cells.
-//
-// postgresRollupConflict 是 PostgreSQL 用于替换 rollup 单元的冲突处理子句。
-const postgresRollupConflict = `ON CONFLICT(metric_name, entity_id, tags_hash, resolution_nano, bucket_nano) DO UPDATE SET
-	tags = EXCLUDED.tags,
-	count = EXCLUDED.count, sum = EXCLUDED.sum, sum_sq = EXCLUDED.sum_sq,
-	min_val = EXCLUDED.min_val, max_val = EXCLUDED.max_val,
-	first_val = EXCLUDED.first_val, first_ts = EXCLUDED.first_ts,
-	last_val = EXCLUDED.last_val, last_ts = EXCLUDED.last_ts,
-	digest = EXCLUDED.digest, created_at = EXCLUDED.created_at`
-
-// mysqlRollupConflict is the MySQL conflict clause for replacing rollup cells.
-//
-// mysqlRollupConflict 是 MySQL 用于替换 rollup 单元的冲突处理子句。
-const mysqlRollupConflict = `ON DUPLICATE KEY UPDATE
-	tags = VALUES(tags),
-	count = VALUES(count), sum = VALUES(sum), sum_sq = VALUES(sum_sq),
-	min_val = VALUES(min_val), max_val = VALUES(max_val),
-	first_val = VALUES(first_val), first_ts = VALUES(first_ts),
-	last_val = VALUES(last_val), last_ts = VALUES(last_ts),
-	digest = VALUES(digest), created_at = VALUES(created_at)`
-
-// buildUpsertRollupSQL builds a single-row rollup upsert statement.
-//
-// buildUpsertRollupSQL 构造单行 rollup upsert SQL。
-func buildUpsertRollupSQL(table string, d dialect, conflict string) string {
-	ph := make([]string, rollupColumnCount)
-	for i := 0; i < rollupColumnCount; i++ {
-		if i+1 == rollupTagsArgIndex {
-			// The tags column is JSON; PostgreSQL requires an explicit ::jsonb cast.
-			ph[i] = d.jsonPlaceholder(i + 1)
-		} else {
-			ph[i] = d.placeholder(i + 1)
-		}
-	}
-	return fmt.Sprintf("INSERT INTO %s (%s) VALUES (%s) %s",
-		table, rollupColumns, strings.Join(ph, ", "), conflict)
-}

pkg/metric/dialect_test.go

@@ -1,9 +1,6 @@
 package metric
 
-import (
-	"strings"
-	"testing"
-)
+import "testing"
 
 // TestDialectsGenerateBackendSpecificSQL verifies backend-specific SQL rendering.
 //
@@ -13,29 +10,29 @@ func TestDialectsGenerateBackendSpecificSQL(t *testing.T) {
 		name        string
 		driver      Driver
 		placeholder string
-		upsert      string
 		jsonType    string
+		blobType    string
 	}{
 		{
 			name:        "sqlite",
 			driver:      DriverSQLite,
 			placeholder: "?",
-			upsert:      "ON CONFLICT(metric_name, entity_id, tags_hash, ts_nano)",
 			jsonType:    "TEXT",
+			blobType:    "BLOB",
 		},
 		{
 			name:        "mysql",
 			driver:      DriverMySQL,
 			placeholder: "?",
-			upsert:      "ON DUPLICATE KEY UPDATE",
 			jsonType:    "JSON",
+			blobType:    "LONGBLOB",
 		},
 		{
 			name:        "postgresql",
 			driver:      DriverPostgreSQL,
 			placeholder: "$1",
-			upsert:      "ON CONFLICT(metric_name, entity_id, tags_hash, ts_nano)",
 			jsonType:    "JSONB",
+			blobType:    "BYTEA",
 		},
 	}
 
@@ -48,12 +45,8 @@ func TestDialectsGenerateBackendSpecificSQL(t *testing.T) {
 			if got := d.jsonType(); got != tt.jsonType {
 				t.Fatalf("json type: expected %q, got %q", tt.jsonType, got)
 			}
-			sql := d.upsertPointSQL(tables{points: "metric_points"}, 2)
-			if !strings.Contains(sql, "metric_points") {
-				t.Fatalf("upsert sql should reference metric_points: %s", sql)
-			}
-			if !strings.Contains(sql, tt.upsert) {
-				t.Fatalf("upsert sql should contain %q: %s", tt.upsert, sql)
+			if got := d.blobType(); got != tt.blobType {
+				t.Fatalf("blob type: expected %q, got %q", tt.blobType, got)
 			}
 		})
 	}

pkg/metric/example_test.go

@@ -20,7 +20,7 @@ func Example_rollupTags() {
 	store, err := metric.Open(ctx, metric.SQLite(
 		"file:metric-example?mode=memory&cache=shared",
 		metric.WithRollupPolicy(metric.RollupPolicy{
-			RawRetention: 2 * time.Minute,
+			RawRetention: 10 * time.Minute,
 			Tiers: []metric.RollupTier{
 				{Interval: time.Minute, Retention: 24 * time.Hour},
 			},
@@ -32,10 +32,10 @@ func Example_rollupTags() {
 	defer store.Close()
 
 	if err := store.CreateMetric(ctx, metric.Definition{
-		Name: "gpu.usage",
-		Type: metric.TypeGauge,
-		Unit: "%",
-	}); err != nil {
+		Name:          "gpu.usage",
+		Type:          metric.TypeGauge,
+		Unit:          "%",
+		RetentionDays: 30}); err != nil {
 		log.Fatal(err)
 	}
 
@@ -63,8 +63,8 @@ func Example_rollupTags() {
 		log.Fatal(err)
 	}
 
-	// Compact builds one rollup series per tag set. Raw points older than the
-	// policy's RawRetention are deleted after their rollups are materialized.
+	// Compact builds one rollup series per tag set. Exact raw points stay only
+	// in the Store's fixed ten-minute memory window.
 	now := base.Add(time.Hour)
 	if _, err := store.Compact(ctx, now); err != nil {
 		log.Fatal(err)
@@ -104,7 +104,7 @@ func Example_agentFleetLifecycle() {
 	store, err := metric.Open(ctx, metric.SQLite(
 		"file:metric-agent-fleet?mode=memory&cache=shared",
 		metric.WithRollupPolicy(metric.RollupPolicy{
-			RawRetention: 2 * time.Minute,
+			RawRetention: 10 * time.Minute,
 			Tiers: []metric.RollupTier{
 				{Interval: time.Minute, Retention: 24 * time.Hour},
 				{Interval: 5 * time.Minute, Retention: 30 * 24 * time.Hour},
@@ -117,15 +117,15 @@ func Example_agentFleetLifecycle() {
 	defer store.Close()
 
 	for _, def := range []metric.Definition{
-		{Name: "cpu.usage", Type: metric.TypeGauge, Unit: "%"},
-		{Name: "mem.usage", Type: metric.TypeGauge, Unit: "%"},
-		{Name: "disk.usage", Type: metric.TypeGauge, Unit: "%"},
-		{Name: "swap.usage", Type: metric.TypeGauge, Unit: "%"},
-		{Name: "net.in.bytes", Type: metric.TypeCounter, Unit: "bytes"},
-		{Name: "net.out.bytes", Type: metric.TypeCounter, Unit: "bytes"},
-		{Name: "process.count", Type: metric.TypeGauge, Unit: "count"},
-		{Name: "gpu.usage", Type: metric.TypeGauge, Unit: "%"},
-		{Name: "ping.latency_ms", Type: metric.TypeGauge, Unit: "ms"},
+		{Name: "cpu.usage", Type: metric.TypeGauge, Unit: "%", RetentionDays: 30},
+		{Name: "mem.usage", Type: metric.TypeGauge, Unit: "%", RetentionDays: 30},
+		{Name: "disk.usage", Type: metric.TypeGauge, Unit: "%", RetentionDays: 30},
+		{Name: "swap.usage", Type: metric.TypeGauge, Unit: "%", RetentionDays: 30},
+		{Name: "net.in.bytes", Type: metric.TypeCounter, Unit: "bytes", RetentionDays: 30},
+		{Name: "net.out.bytes", Type: metric.TypeCounter, Unit: "bytes", RetentionDays: 30},
+		{Name: "process.count", Type: metric.TypeGauge, Unit: "count", RetentionDays: 30},
+		{Name: "gpu.usage", Type: metric.TypeGauge, Unit: "%", RetentionDays: 30},
+		{Name: "ping.latency_ms", Type: metric.TypeGauge, Unit: "ms", RetentionDays: 30},
 	} {
 		if err := store.UpsertMetric(ctx, def); err != nil {
 			log.Fatal(err)
@@ -158,7 +158,7 @@ func Example_agentFleetLifecycle() {
 			}
 			if err := store.UpsertMetric(ctx, metric.Definition{
 				Name: "ping.latency_ms", Type: metric.TypeGauge, Unit: "ms",
-			}); err != nil {
+				RetentionDays: 30}); err != nil {
 				log.Fatal(err)
 			}
 		case 85:

pkg/metric/hot_rollup.go

@@ -0,0 +1,290 @@
+package metric
+
+import (
+	"context"
+	"sort"
+	"time"
+)
+
+// hotRollupKey identifies one active minute bucket. The dictionary dimensions
+// remain compact strings; full tag and label JSON lives only on the bucket.
+type hotRollupKey struct {
+	metricName string
+	entityID   string
+	tagsHash   string
+	labelsHash string
+	bucket     int64
+}
+
+type hotRollup struct {
+	key     hotRollupKey
+	bucket  *rollupBucket
+	replace bool
+}
+
+func (s *Store) writePreparedHotRollups(ctx context.Context, prepared []preparedMetricPoint, now time.Time, rebuild map[hotRollupKey]struct{}) error {
+	minuteMillis := time.Minute.Milliseconds()
+	compression := s.cfg.RollupPolicy.compression()
+	if len(rebuild) > 0 {
+		s.rollupViewMu.Lock()
+		defer s.rollupViewMu.Unlock()
+	}
+	s.hotMu.Lock()
+	for _, point := range prepared {
+		key := hotRollupKey{
+			metricName: point.metricName,
+			entityID:   point.entityID,
+			tagsHash:   point.tagsHash,
+			labelsHash: point.labelsHash,
+			bucket:     bucketStartMillis(point.timestamp, minuteMillis),
+		}
+		bucket := s.hot[key]
+		if bucket == nil {
+			bucket = newRollupBucket(compression)
+			bucket.tagsHash, bucket.tagsJSON = point.tagsHash, point.tagsJSON
+			bucket.labelsHash, bucket.labelsJSON = point.labelsHash, point.labelsJSON
+			s.hot[key] = bucket
+		}
+		bucket.addPoint(point.value, point.timestamp)
+	}
+	if len(rebuild) > 0 {
+		s.rebuildHotRollupsLocked(rebuild, compression)
+	}
+	s.hotMu.Unlock()
+	var err error
+	if len(rebuild) > 0 {
+		_, err = s.flushClosedHotRollupsUnderView(ctx, now)
+	} else {
+		_, err = s.flushClosedHotRollups(ctx, now)
+	}
+	return err
+}
+
+func (s *Store) rebuildHotRollupsLocked(keys map[hotRollupKey]struct{}, compression float64) {
+	s.rawMu.RLock()
+	defer s.rawMu.RUnlock()
+	minuteMillis := time.Minute.Milliseconds()
+	for key := range keys {
+		series := s.raw[rawSeriesKey{metricName: key.metricName, entityID: key.entityID, tagsHash: key.tagsHash}]
+		bucket := newRollupBucket(compression)
+		bucket.tagsHash = key.tagsHash
+		bucket.labelsHash = key.labelsHash
+		if series != nil {
+			bucket.tagsJSON = series.tagsJSON
+			if labelID, ok := series.labelIDs[key.labelsHash]; ok {
+				bucket.labelsJSON = series.labelsJSON[labelID]
+			}
+			for _, sample := range series.allSamples() {
+				if bucketStartMillis(sample.timestamp, minuteMillis) != key.bucket || series.labelHashes[sample.labelID] != key.labelsHash {
+					continue
+				}
+				bucket.labelsJSON = series.labelsJSON[sample.labelID]
+				bucket.addPoint(sample.value, sample.timestamp)
+			}
+		}
+		s.hot[key] = bucket
+		s.hotReplace[key] = struct{}{}
+	}
+}
+
+func (s *Store) flushClosedHotRollups(ctx context.Context, now time.Time) (int, error) {
+	s.rollupViewMu.Lock()
+	defer s.rollupViewMu.Unlock()
+	return s.flushClosedHotRollupsUnderView(ctx, now)
+}
+
+func (s *Store) flushClosedHotRollupsUnderView(ctx context.Context, now time.Time) (int, error) {
+	flushBefore := bucketStartMillis(now.UTC().UnixMilli(), time.Minute.Milliseconds())
+	closed := s.takeClosedHotRollups(flushBefore)
+	if len(closed) == 0 {
+		return 0, nil
+	}
+	if err := s.persistHotRollups(ctx, closed); err != nil {
+		s.restoreHotRollups(closed)
+		return 0, err
+	}
+	return len(closed), nil
+}
+
+func (s *Store) flushAllHotRollups(ctx context.Context) error {
+	s.rollupViewMu.Lock()
+	defer s.rollupViewMu.Unlock()
+	s.hotMu.Lock()
+	all := make([]hotRollup, 0, len(s.hot))
+	for key, bucket := range s.hot {
+		_, replace := s.hotReplace[key]
+		all = append(all, hotRollup{key: key, bucket: bucket, replace: replace})
+		delete(s.hot, key)
+		delete(s.hotReplace, key)
+	}
+	s.hotMu.Unlock()
+	if len(all) == 0 {
+		return nil
+	}
+	if err := s.persistHotRollups(ctx, all); err != nil {
+		s.restoreHotRollups(all)
+		return err
+	}
+	return nil
+}
+
+func (s *Store) takeClosedHotRollups(currentBucket int64) []hotRollup {
+	s.hotMu.Lock()
+	defer s.hotMu.Unlock()
+	closed := make([]hotRollup, 0)
+	for key, bucket := range s.hot {
+		if key.bucket < currentBucket {
+			_, replace := s.hotReplace[key]
+			closed = append(closed, hotRollup{key: key, bucket: bucket, replace: replace})
+			delete(s.hot, key)
+			delete(s.hotReplace, key)
+		}
+	}
+	return closed
+}
+
+func (s *Store) restoreHotRollups(closed []hotRollup) {
+	s.hotMu.Lock()
+	defer s.hotMu.Unlock()
+	for _, item := range closed {
+		current, exists := s.hot[item.key]
+		_, currentReplaces := s.hotReplace[item.key]
+		if !exists {
+			s.hot[item.key] = item.bucket
+			if item.replace {
+				s.hotReplace[item.key] = struct{}{}
+			}
+			continue
+		}
+		if currentReplaces {
+			continue
+		}
+		if item.replace {
+			item.bucket.mergeStored(current)
+			s.hot[item.key] = item.bucket
+			s.hotReplace[item.key] = struct{}{}
+			continue
+		}
+		current.mergeStored(item.bucket)
+	}
+}
+
+func (s *Store) persistHotRollups(ctx context.Context, closed []hotRollup) error {
+	type metricBuckets struct {
+		merge   map[rollupKey]*rollupBucket
+		replace map[rollupKey]*rollupBucket
+	}
+	byMetric := make(map[string]*metricBuckets)
+	for _, item := range closed {
+		buckets := byMetric[item.key.metricName]
+		if buckets == nil {
+			buckets = &metricBuckets{merge: make(map[rollupKey]*rollupBucket), replace: make(map[rollupKey]*rollupBucket)}
+			byMetric[item.key.metricName] = buckets
+		}
+		key := rollupKey{entityID: item.key.entityID, tagsHash: item.key.tagsHash, labelsHash: item.key.labelsHash, bucket: item.key.bucket}
+		if item.replace {
+			buckets.replace[key] = item.bucket
+		} else {
+			buckets.merge[key] = item.bucket
+		}
+	}
+	names := make([]string, 0, len(byMetric))
+	for name := range byMetric {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	tx, err := s.db.BeginTx(ctx, nil)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = tx.Rollback() }()
+	for _, name := range names {
+		buckets := byMetric[name]
+		if _, err := s.writeTierCascadeTx(ctx, name, buckets.merge, tx); err != nil {
+			return err
+		}
+		if err := s.replaceMinuteRollupsTx(ctx, name, buckets.replace, tx); err != nil {
+			return err
+		}
+	}
+	return tx.Commit()
+}
+
+func (s *Store) hotRollupRows(metricName, entityID string, tags map[string]string, start, end time.Time, needDigest bool) ([]storedRollup, error) {
+	startMilli, endMilli := start.UTC().UnixMilli(), end.UTC().UnixMilli()
+	s.hotMu.RLock()
+	defer s.hotMu.RUnlock()
+	out := make([]storedRollup, 0)
+	for key, bucket := range s.hot {
+		if key.metricName != metricName || key.bucket+time.Minute.Milliseconds() <= startMilli || key.bucket > endMilli || (entityID != "" && key.entityID != entityID) {
+			continue
+		}
+		if bucket.count == 0 {
+			continue
+		}
+		bucketTags, err := rollupTagsFromJSON(bucket.tagsJSON)
+		if err != nil {
+			return nil, err
+		}
+		matched := true
+		for name, value := range tags {
+			if bucketTags[name] != value {
+				matched = false
+				break
+			}
+		}
+		if !matched {
+			continue
+		}
+		out = append(out, storedRollup{entityID: key.entityID, bucket: key.bucket, bucketData: bucket.clone(needDigest)})
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].bucket < out[j].bucket })
+	return out, nil
+}
+
+// deleteHotRollups removes active minute buckets matched by the same series
+// dimensions used by persisted deletes. A non-nil cutoff removes only buckets
+// whose minute starts before it.
+func (s *Store) deleteHotRollups(metricName, entityID string, tags map[string]string, cutoff *time.Time) (int64, error) {
+	s.hotMu.Lock()
+	defer s.hotMu.Unlock()
+
+	var cutoffMilli int64
+	if cutoff != nil {
+		cutoffMilli = cutoff.UTC().UnixMilli()
+	}
+	matched := make([]hotRollupKey, 0)
+	for key, bucket := range s.hot {
+		if metricName != "" && key.metricName != metricName {
+			continue
+		}
+		if entityID != "" && key.entityID != entityID {
+			continue
+		}
+		if cutoff != nil && key.bucket >= cutoffMilli {
+			continue
+		}
+		if len(tags) > 0 {
+			bucketTags, err := rollupTagsFromJSON(bucket.tagsJSON)
+			if err != nil {
+				return 0, err
+			}
+			matches := true
+			for name, value := range tags {
+				if bucketTags[name] != value {
+					matches = false
+					break
+				}
+			}
+			if !matches {
+				continue
+			}
+		}
+		matched = append(matched, key)
+	}
+	for _, key := range matched {
+		delete(s.hot, key)
+		delete(s.hotReplace, key)
+	}
+	return int64(len(matched)), nil
+}

pkg/metric/hot_rollup_test.go

@@ -0,0 +1,771 @@
+package metric
+
+import (
+	"context"
+	"fmt"
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestWriteBatchKeepsRawInMemoryAndBuildsMinuteRollup(t *testing.T) {
+	ctx := context.Background()
+	s, err := Open(ctx, SQLite(":memory:", WithRollupPolicy(RollupPolicy{
+		RawRetention: time.Minute,
+		Tiers:        []RollupTier{{Interval: time.Minute, Retention: time.Hour}},
+		Compression:  30,
+	})))
+	if err != nil {
+		t.Fatalf("open store: %v", err)
+	}
+	defer s.Close()
+	if err := s.CreateMetric(ctx, Definition{Name: "hot", RetentionDays: 1}); err != nil {
+		t.Fatalf("create metric: %v", err)
+	}
+	base := time.Now().UTC().Truncate(time.Minute)
+	if err := s.WriteBatch(ctx, []Point{
+		{MetricName: "hot", EntityID: "n1", Timestamp: base.Add(10 * time.Second), Value: 10},
+		{MetricName: "hot", EntityID: "n1", Timestamp: base.Add(20 * time.Second), Value: 20},
+	}); err != nil {
+		t.Fatalf("write samples: %v", err)
+	}
+	var rawTableCount int
+	if err := s.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name = ?`, s.tables.points).Scan(&rawTableCount); err != nil {
+		t.Fatalf("inspect points table: %v", err)
+	}
+	if rawTableCount != 0 {
+		t.Fatalf("metric_points table count = %d, want 0", rawTableCount)
+	}
+	points, err := s.Query(ctx, Query{MetricName: "hot", EntityID: "n1", Start: base, End: base.Add(time.Minute)})
+	if err != nil {
+		t.Fatalf("query minute rollup: %v", err)
+	}
+	if len(points) != 2 || points[0].Value != 10 || points[1].Value != 20 {
+		t.Fatalf("points = %#v, want both raw samples", points)
+	}
+	series, err := s.Series(ctx, AggregateQuery{
+		Query:       Query{MetricName: "hot", EntityID: "n1", Start: base, End: base.Add(time.Minute)},
+		Aggregation: AggAvg, Interval: time.Minute, PreserveSeries: true,
+	}, base.Add(2*time.Minute))
+	if err != nil {
+		t.Fatalf("query minute rollup: %v", err)
+	}
+	if len(series) != 1 || series[0].Count != 2 || series[0].Value != 15 {
+		t.Fatalf("minute rollup = %#v, want avg=15 count=2", series)
+	}
+}
+
+func TestClosedMinutePersistsAndAcceptsExactUpsert(t *testing.T) {
+	ctx := context.Background()
+	s, err := Open(ctx, SQLite(":memory:", WithRollupPolicy(RollupPolicy{
+		RawRetention: time.Minute,
+		Tiers:        []RollupTier{{Interval: time.Minute, Retention: time.Hour}},
+		Compression:  30,
+	})))
+	if err != nil {
+		t.Fatalf("open store: %v", err)
+	}
+	defer s.Close()
+	if err := s.CreateMetric(ctx, Definition{Name: "late-upsert", RetentionDays: 1}); err != nil {
+		t.Fatalf("create metric: %v", err)
+	}
+
+	now := time.Date(2026, 7, 27, 12, 0, 10, 0, time.UTC)
+	at := now.Add(-20 * time.Second)
+	for _, value := range []float64{1, 2} {
+		prepared, err := prepareMetricPoints([]Point{{MetricName: "late-upsert", EntityID: "n1", Timestamp: at, Value: value}})
+		if err != nil {
+			t.Fatalf("prepare point: %v", err)
+		}
+		rebuild := s.writeRawPointsAt(prepared, now)
+		if err := s.writePreparedHotRollups(ctx, prepared, now, rebuild); err != nil {
+			t.Fatalf("write hot rollup: %v", err)
+		}
+	}
+
+	var persisted int
+	if err := s.db.QueryRowContext(ctx, "SELECT COUNT(*) FROM "+s.tables.rollups).Scan(&persisted); err != nil {
+		t.Fatalf("count early persisted rollups: %v", err)
+	}
+	if persisted != 1 {
+		t.Fatalf("persisted closed-minute rollups = %d, want 1", persisted)
+	}
+	series, err := s.Series(ctx, AggregateQuery{
+		Query:       Query{MetricName: "late-upsert", EntityID: "n1", Start: at.Add(-time.Minute), End: now},
+		Aggregation: AggCount, Interval: time.Minute, PreserveSeries: true,
+	}, now)
+	if err != nil {
+		t.Fatalf("query hot rollup: %v", err)
+	}
+	if len(series) != 1 || series[0].Count != 1 || series[0].Value != 1 {
+		t.Fatalf("late upsert was counted twice: %#v", series)
+	}
+
+	var count int
+	if err := s.db.QueryRowContext(ctx, "SELECT count FROM "+s.tables.rollups).Scan(&count); err != nil {
+		t.Fatalf("read persisted rollup: %v", err)
+	}
+	if count != 1 {
+		t.Fatalf("persisted rollup count = %d, want 1", count)
+	}
+}
+
+func TestRawWindowKeepsCompressedAndDirectSamples(t *testing.T) {
+	ctx := context.Background()
+	now := time.Now().UTC()
+	s, err := Open(ctx, SQLite(":memory:", WithRollupPolicy(RollupPolicy{
+		RawRetention: time.Minute,
+		Tiers:        []RollupTier{{Interval: time.Minute, Retention: time.Hour}},
+		Compression:  30,
+	})))
+	if err != nil {
+		t.Fatalf("open store: %v", err)
+	}
+	defer s.Close()
+	if err := s.CreateMetric(ctx, Definition{Name: "raw-window", RetentionDays: 1}); err != nil {
+		t.Fatalf("create metric: %v", err)
+	}
+	if err := s.WriteBatch(ctx, []Point{
+		{MetricName: "raw-window", EntityID: "n1", Timestamp: now.Add(-70 * time.Second), Value: 1},
+		{MetricName: "raw-window", EntityID: "n1", Timestamp: now.Add(-50 * time.Second), Value: 2},
+		{MetricName: "raw-window", EntityID: "n1", Timestamp: now.Add(-40 * time.Second), Value: 3},
+	}); err != nil {
+		t.Fatalf("write samples: %v", err)
+	}
+	if _, err := s.Compact(ctx, now); err != nil {
+		t.Fatalf("compact: %v", err)
+	}
+	raw, err := s.Query(ctx, Query{MetricName: "raw-window", EntityID: "n1", Start: now.Add(-time.Hour), End: now})
+	if err != nil {
+		t.Fatalf("query raw: %v", err)
+	}
+	if len(raw) != 3 || raw[0].Value != 1 || raw[1].Value != 2 || raw[2].Value != 3 {
+		t.Fatalf("retained raw = %#v, want all ten-minute samples", raw)
+	}
+	series, err := s.Series(ctx, AggregateQuery{
+		Query:       Query{MetricName: "raw-window", EntityID: "n1", Start: now.Add(-time.Hour), End: now},
+		Aggregation: AggCount, Interval: time.Minute, PreserveSeries: true,
+	}, now)
+	if err != nil {
+		t.Fatalf("query rollup: %v", err)
+	}
+	var count int
+	for _, point := range series {
+		count += point.Count
+	}
+	if count != 3 {
+		t.Fatalf("rollups lost samples after raw cleanup: %#v", series)
+	}
+}
+
+func TestOldestRawMinuteRebuildKeepsHiddenPrefix(t *testing.T) {
+	ctx := context.Background()
+	policy := RollupPolicy{
+		RawRetention: rawMemoryRetention,
+		Tiers:        []RollupTier{{Interval: time.Minute, Retention: time.Hour}},
+		Compression:  30,
+	}
+	s, err := Open(ctx, SQLite(":memory:", WithRollupPolicy(policy)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer s.Close()
+	if err := s.CreateMetric(ctx, Definition{Name: "oldest-minute", RetentionDays: 1}); err != nil {
+		t.Fatal(err)
+	}
+	now := time.Date(2026, 7, 27, 12, 10, 30, 0, time.UTC)
+	oldestMinute := now.Add(-rawMemoryRetention).Truncate(time.Minute)
+	write := func(points ...Point) {
+		t.Helper()
+		prepared, err := prepareMetricPoints(points)
+		if err != nil {
+			t.Fatal(err)
+		}
+		rebuild := s.writeRawPointsAt(prepared, now)
+		if err := s.writePreparedHotRollups(ctx, prepared, now, rebuild); err != nil {
+			t.Fatal(err)
+		}
+	}
+	write(
+		Point{MetricName: "oldest-minute", EntityID: "n1", Timestamp: oldestMinute.Add(5 * time.Second), Value: 1},
+		Point{MetricName: "oldest-minute", EntityID: "n1", Timestamp: oldestMinute.Add(40 * time.Second), Value: 2},
+	)
+	write(Point{MetricName: "oldest-minute", EntityID: "n1", Timestamp: oldestMinute.Add(40 * time.Second), Value: 4})
+
+	rows, err := s.scanRollupRowsBetween(ctx, "oldest-minute", "n1", nil, time.Minute.Milliseconds(), oldestMinute.UnixMilli(), oldestMinute.UnixMilli(), false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(rows) != 1 || rows[0].bucketData.count != 2 || rows[0].bucketData.sum != 5 {
+		t.Fatalf("rebuilt oldest minute = %#v, want count=2 sum=5", rows)
+	}
+}
+
+func TestLateLabelReplacementRebuildsPersistedCascade(t *testing.T) {
+	ctx := context.Background()
+	policy := RollupPolicy{
+		RawRetention: rawMemoryRetention,
+		Tiers: []RollupTier{
+			{Interval: time.Minute, Retention: 24 * time.Hour},
+			{Interval: 5 * time.Minute, Retention: 7 * 24 * time.Hour},
+			{Interval: time.Hour, Retention: 30 * 24 * time.Hour},
+			{Interval: 24 * time.Hour, Retention: 365 * 24 * time.Hour},
+		},
+		Compression: 30,
+	}
+	s, err := Open(ctx, SQLite(":memory:", WithRollupPolicy(policy)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer s.Close()
+	if err := s.CreateMetric(ctx, Definition{Name: "cascade-replace", RetentionDays: 30}); err != nil {
+		t.Fatal(err)
+	}
+	now := time.Date(2026, 7, 27, 12, 2, 10, 0, time.UTC)
+	at := now.Add(-90 * time.Second)
+	write := func(point Point) {
+		t.Helper()
+		prepared, err := prepareMetricPoints([]Point{point})
+		if err != nil {
+			t.Fatal(err)
+		}
+		rebuild := s.writeRawPointsAt(prepared, now)
+		if err := s.writePreparedHotRollups(ctx, prepared, now, rebuild); err != nil {
+			t.Fatal(err)
+		}
+	}
+	write(Point{MetricName: "cascade-replace", EntityID: "n1", Timestamp: at, Value: 1, Labels: map[string]string{"source": "old"}})
+	write(Point{MetricName: "cascade-replace", EntityID: "n1", Timestamp: at, Value: 7, Labels: map[string]string{"source": "new"}})
+
+	for _, tier := range policy.Tiers {
+		start := bucketStartMillis(at.UnixMilli(), tier.Interval.Milliseconds())
+		rows, err := s.scanRollupRowsBetween(ctx, "cascade-replace", "n1", nil, tier.Interval.Milliseconds(), start, start, true)
+		if err != nil {
+			t.Fatalf("scan %s tier: %v", tier.Interval, err)
+		}
+		if len(rows) != 1 || rows[0].bucketData.count != 1 || rows[0].bucketData.sum != 7 {
+			t.Fatalf("%s replacement rows = %#v, want one count=1 sum=7 row", tier.Interval, rows)
+		}
+		labels, err := decodeMapString(rows[0].bucketData.labelsJSON)
+		if err != nil || labels["source"] != "new" {
+			t.Fatalf("%s replacement labels = %#v, %v", tier.Interval, labels, err)
+		}
+	}
+}
+
+func TestFlushTrimsInactiveRawWindow(t *testing.T) {
+	ctx := context.Background()
+	s := newMemStore(t)
+	if err := s.CreateMetric(ctx, Definition{Name: "idle-raw", RetentionDays: 1}); err != nil {
+		t.Fatal(err)
+	}
+	now := time.Now().UTC()
+	prepared, err := prepareMetricPoints([]Point{{MetricName: "idle-raw", EntityID: "n1", Timestamp: now.Add(-time.Minute), Value: 1}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	rebuild := s.writeRawPointsAt(prepared, now)
+	if err := s.writePreparedHotRollups(ctx, prepared, now, rebuild); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := s.Flush(ctx, now.Add(12*time.Minute)); err != nil {
+		t.Fatal(err)
+	}
+	s.rawMu.RLock()
+	defer s.rawMu.RUnlock()
+	if len(s.raw) != 0 {
+		t.Fatalf("inactive raw series retained after scheduled flush: %#v", s.raw)
+	}
+}
+
+func TestConcurrentHotPercentileQueriesUseDigestSnapshots(t *testing.T) {
+	ctx := context.Background()
+	s := newMemStore(t)
+	if err := s.CreateMetric(ctx, Definition{Name: "hot-percentile", RetentionDays: 1}); err != nil {
+		t.Fatal(err)
+	}
+	base := time.Now().UTC()
+	if err := s.Write(ctx, Point{MetricName: "hot-percentile", EntityID: "n1", Timestamp: base, Value: 1}); err != nil {
+		t.Fatal(err)
+	}
+
+	errCh := make(chan error, 2)
+	var workers sync.WaitGroup
+	workers.Add(2)
+	go func() {
+		defer workers.Done()
+		for i := 1; i <= 200; i++ {
+			if err := s.Write(ctx, Point{MetricName: "hot-percentile", EntityID: "n1", Timestamp: base.Add(time.Duration(i) * time.Millisecond), Value: float64(i)}); err != nil {
+				errCh <- err
+				return
+			}
+		}
+	}()
+	go func() {
+		defer workers.Done()
+		for i := 0; i < 200; i++ {
+			points, err := s.Series(ctx, AggregateQuery{
+				Query:       Query{MetricName: "hot-percentile", EntityID: "n1", Start: base.Add(-time.Minute), End: base.Add(time.Minute)},
+				Aggregation: AggP95, Interval: time.Minute, PreserveSeries: true,
+			}, base)
+			if err != nil {
+				errCh <- err
+				return
+			}
+			if len(points) == 0 {
+				errCh <- fmt.Errorf("percentile query returned no points")
+				return
+			}
+		}
+	}()
+	workers.Wait()
+	close(errCh)
+	for err := range errCh {
+		t.Fatal(err)
+	}
+}
+
+func TestConcurrentPersistedReplacementQueriesStayConsistent(t *testing.T) {
+	ctx := context.Background()
+	policy := RollupPolicy{
+		RawRetention: rawMemoryRetention,
+		Tiers:        []RollupTier{{Interval: time.Minute, Retention: time.Hour}},
+		Compression:  30,
+	}
+	s, err := Open(ctx, SQLite(":memory:", WithRollupPolicy(policy)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer s.Close()
+	if err := s.CreateMetric(ctx, Definition{Name: "replacement-view", RetentionDays: 1}); err != nil {
+		t.Fatal(err)
+	}
+	now := time.Now().UTC()
+	at := now.Add(-90 * time.Second)
+	if err := s.Write(ctx, Point{MetricName: "replacement-view", EntityID: "n1", Timestamp: at, Value: 1}); err != nil {
+		t.Fatal(err)
+	}
+
+	errCh := make(chan error, 2)
+	var workers sync.WaitGroup
+	workers.Add(2)
+	go func() {
+		defer workers.Done()
+		for i := 2; i <= 100; i++ {
+			if err := s.Write(ctx, Point{MetricName: "replacement-view", EntityID: "n1", Timestamp: at, Value: float64(i)}); err != nil {
+				errCh <- err
+				return
+			}
+		}
+	}()
+	go func() {
+		defer workers.Done()
+		for i := 0; i < 300; i++ {
+			points, err := s.Series(ctx, AggregateQuery{
+				Query:       Query{MetricName: "replacement-view", EntityID: "n1", Start: at.Add(-time.Minute), End: now},
+				Aggregation: AggCount, Interval: time.Minute, PreserveSeries: true,
+			}, now)
+			if err != nil {
+				errCh <- err
+				return
+			}
+			if len(points) != 1 || points[0].Count != 1 || points[0].Value != 1 {
+				errCh <- fmt.Errorf("replacement query observed a split view: %#v", points)
+				return
+			}
+		}
+	}()
+	workers.Wait()
+	close(errCh)
+	for err := range errCh {
+		t.Fatal(err)
+	}
+}
+
+func TestRawQueryOffsetWithoutLimit(t *testing.T) {
+	ctx := context.Background()
+	s := newMemStore(t)
+	if err := s.CreateMetric(ctx, Definition{Name: "raw-page", RetentionDays: 1}); err != nil {
+		t.Fatalf("create metric: %v", err)
+	}
+	base := time.Now().UTC().Truncate(time.Second)
+	if err := s.WriteBatch(ctx, []Point{
+		{MetricName: "raw-page", EntityID: "n1", Timestamp: base, Value: 1},
+		{MetricName: "raw-page", EntityID: "n1", Timestamp: base.Add(time.Second), Value: 2},
+		{MetricName: "raw-page", EntityID: "n1", Timestamp: base.Add(2 * time.Second), Value: 3},
+	}); err != nil {
+		t.Fatalf("write samples: %v", err)
+	}
+	points, err := s.Query(ctx, Query{MetricName: "raw-page", Start: base, End: base.Add(2 * time.Second), Offset: 1})
+	if err != nil {
+		t.Fatalf("query offset: %v", err)
+	}
+	if len(points) != 2 || points[0].Value != 2 || points[1].Value != 3 {
+		t.Fatalf("offset raw points = %#v", points)
+	}
+}
+
+func TestSeriesMergesLabelsWithoutCollapsingRawShape(t *testing.T) {
+	ctx := context.Background()
+	s, err := Open(ctx, SQLite(":memory:", WithRollupPolicy(RollupPolicy{
+		Tiers:       []RollupTier{{Interval: time.Minute, Retention: time.Hour}},
+		Compression: 30,
+	})))
+	if err != nil {
+		t.Fatalf("open store: %v", err)
+	}
+	defer s.Close()
+	if err := s.CreateMetric(ctx, Definition{Name: "labels", RetentionDays: 1}); err != nil {
+		t.Fatalf("create metric: %v", err)
+	}
+	base := time.Now().UTC().Add(-30 * time.Second)
+	if err := s.WriteBatch(ctx, []Point{
+		{MetricName: "labels", EntityID: "n1", Timestamp: base.Add(10 * time.Second), Value: 10, Tags: map[string]string{"disk": "sda"}, Labels: map[string]string{"source": "a"}},
+		{MetricName: "labels", EntityID: "n1", Timestamp: base.Add(20 * time.Second), Value: 20, Tags: map[string]string{"disk": "sda"}, Labels: map[string]string{"source": "b"}},
+	}); err != nil {
+		t.Fatalf("write labeled samples: %v", err)
+	}
+
+	series, err := s.Series(ctx, AggregateQuery{
+		Query:          Query{MetricName: "labels", EntityID: "n1", Start: base, End: base.Add(time.Minute)},
+		Aggregation:    AggAvg,
+		Interval:       time.Minute,
+		PreserveSeries: true,
+	}, base.Add(2*time.Minute))
+	if err != nil {
+		t.Fatalf("aggregate labels: %v", err)
+	}
+	var count int
+	var sum float64
+	for _, point := range series {
+		count += point.Count
+		sum += point.Value * float64(point.Count)
+	}
+	if count != 2 || sum/float64(count) != 15 {
+		t.Fatalf("label sets split the public series: %#v", series)
+	}
+
+	points, err := s.Query(ctx, Query{MetricName: "labels", EntityID: "n1", Start: base, End: base.Add(time.Minute)})
+	if err != nil {
+		t.Fatalf("query labeled raw samples: %v", err)
+	}
+	if len(points) != 2 {
+		t.Fatalf("query lost independently indexed label sets: %#v", points)
+	}
+}
+
+func TestCoveringSeriesResolutionUsesFinestTierCoveringStart(t *testing.T) {
+	ctx := context.Background()
+	policy := RollupPolicy{
+		Tiers: []RollupTier{
+			{Interval: time.Minute, Retention: 10 * time.Hour},
+			{Interval: 5 * time.Minute, Retention: 50 * time.Hour},
+			{Interval: time.Hour, Retention: 25 * 24 * time.Hour},
+			{Interval: 24 * time.Hour, Retention: 100 * 365 * 24 * time.Hour},
+		},
+		Compression: 30,
+	}
+	s, err := Open(ctx, SQLite(":memory:", WithRollupPolicy(policy)))
+	if err != nil {
+		t.Fatalf("open store: %v", err)
+	}
+	defer s.Close()
+	if err := s.CreateMetric(ctx, Definition{Name: "coverage-tier", RetentionDays: 60}); err != nil {
+		t.Fatalf("create metric: %v", err)
+	}
+
+	tagsHash, tagsJSON, err := tagsFingerprint(nil)
+	if err != nil {
+		t.Fatalf("fingerprint tags: %v", err)
+	}
+	now := time.Date(2026, 7, 24, 12, 0, 0, 0, time.UTC)
+	tx, err := s.db.BeginTx(ctx, nil)
+	if err != nil {
+		t.Fatalf("begin seed transaction: %v", err)
+	}
+	for _, seed := range []struct {
+		interval time.Duration
+		at       time.Time
+	}{
+		{interval: time.Minute, at: now.Add(-30 * time.Minute)},
+		{interval: 5 * time.Minute, at: now.Add(-7 * time.Hour)},
+		{interval: 5 * time.Minute, at: now.Add(-5 * time.Hour)},
+		{interval: time.Hour, at: now.Add(-30 * 24 * time.Hour)},
+	} {
+		bucket := newRollupBucket(policy.compression())
+		bucket.tagsHash, bucket.tagsJSON = tagsHash, tagsJSON
+		bucket.labelsHash, bucket.labelsJSON = emptyLabelsHash, "{}"
+		bucket.addPoint(1, seed.at.UnixMilli())
+		key := rollupKey{entityID: "n1", tagsHash: tagsHash, labelsHash: emptyLabelsHash, bucket: bucketStartMillis(seed.at.UnixMilli(), seed.interval.Milliseconds())}
+		if _, err := s.writeRollupBucketsTx(ctx, "coverage-tier", seed.interval, map[rollupKey]*rollupBucket{key: bucket}, tx); err != nil {
+			_ = tx.Rollback()
+			t.Fatalf("seed %s tier: %v", seed.interval, err)
+		}
+	}
+	if err := tx.Commit(); err != nil {
+		t.Fatalf("commit seed tiers: %v", err)
+	}
+
+	resolution, err := s.coveringSeriesResolution(ctx, Query{MetricName: "coverage-tier", EntityID: "n1", Start: now.Add(-6 * time.Hour), End: now}, time.Minute)
+	if err != nil {
+		t.Fatalf("select covering tier: %v", err)
+	}
+	if resolution != 5*time.Minute {
+		t.Fatalf("covering tier = %s, want 5m", resolution)
+	}
+}
+
+func TestSeriesFallsBackWhenPreferredPolicyTierHasNoRows(t *testing.T) {
+	ctx := context.Background()
+	policy := RollupPolicy{
+		Tiers: []RollupTier{
+			{Interval: time.Minute, Retention: 10 * time.Hour},
+			{Interval: time.Hour, Retention: 25 * 24 * time.Hour},
+		},
+		Compression: 30,
+	}
+	s, err := Open(ctx, SQLite(":memory:", WithRollupPolicy(policy)))
+	if err != nil {
+		t.Fatalf("open store: %v", err)
+	}
+	defer s.Close()
+	if err := s.CreateMetric(ctx, Definition{Name: "missing-fine-tier", RetentionDays: 60}); err != nil {
+		t.Fatalf("create metric: %v", err)
+	}
+	now := time.Date(2026, 7, 24, 12, 30, 0, 0, time.UTC)
+	at := now.Add(-30 * time.Minute)
+	tagsHash, tagsJSON, err := tagsFingerprint(nil)
+	if err != nil {
+		t.Fatalf("fingerprint tags: %v", err)
+	}
+	bucket := newRollupBucket(policy.compression())
+	bucket.tagsHash, bucket.tagsJSON = tagsHash, tagsJSON
+	bucket.labelsHash, bucket.labelsJSON = emptyLabelsHash, "{}"
+	bucket.addPoint(42, at.UnixMilli())
+	key := rollupKey{entityID: "n1", tagsHash: tagsHash, labelsHash: emptyLabelsHash, bucket: bucketStartMillis(at.UnixMilli(), time.Hour.Milliseconds())}
+	tx, err := s.db.BeginTx(ctx, nil)
+	if err != nil {
+		t.Fatalf("begin seed transaction: %v", err)
+	}
+	if _, err := s.writeRollupBucketsTx(ctx, "missing-fine-tier", time.Hour, map[rollupKey]*rollupBucket{key: bucket}, tx); err != nil {
+		_ = tx.Rollback()
+		t.Fatalf("seed hourly tier: %v", err)
+	}
+	if err := tx.Commit(); err != nil {
+		t.Fatalf("commit hourly tier: %v", err)
+	}
+
+	got, err := s.Series(ctx, AggregateQuery{
+		Query:       Query{MetricName: "missing-fine-tier", EntityID: "n1", Start: now.Add(-time.Hour), End: now},
+		Aggregation: AggAvg,
+		Interval:    time.Minute,
+	}, now)
+	if err != nil {
+		t.Fatalf("query series: %v", err)
+	}
+	if len(got) != 1 || got[0].Value != 42 || got[0].Count != 1 {
+		t.Fatalf("series did not fall back to existing hourly tier: %#v", got)
+	}
+}
+
+func TestSeriesDoesNotFallBackWhenPreferredTierCoversWindow(t *testing.T) {
+	ctx := context.Background()
+	policy := RollupPolicy{
+		Tiers: []RollupTier{
+			{Interval: time.Minute, Retention: 10 * time.Hour},
+			{Interval: 24 * time.Hour, Retention: 100 * 365 * 24 * time.Hour},
+		},
+		Compression: 30,
+	}
+	s, err := Open(ctx, SQLite(":memory:", WithRollupPolicy(policy)))
+	if err != nil {
+		t.Fatalf("open store: %v", err)
+	}
+	defer s.Close()
+	if err := s.CreateMetric(ctx, Definition{Name: "new-series", RetentionDays: 60}); err != nil {
+		t.Fatalf("create metric: %v", err)
+	}
+
+	now := time.Date(2026, 7, 27, 3, 0, 0, 0, time.UTC)
+	tagsHash, tagsJSON, err := tagsFingerprint(nil)
+	if err != nil {
+		t.Fatalf("fingerprint tags: %v", err)
+	}
+	tx, err := s.db.BeginTx(ctx, nil)
+	if err != nil {
+		t.Fatalf("begin seed transaction: %v", err)
+	}
+	for _, seed := range []struct {
+		interval time.Duration
+		at       time.Time
+		value    float64
+	}{
+		{interval: 24 * time.Hour, at: now.Add(-30 * 24 * time.Hour), value: 10},
+		{interval: time.Minute, at: now.Add(-5 * time.Minute), value: 20},
+	} {
+		bucket := newRollupBucket(policy.compression())
+		bucket.tagsHash, bucket.tagsJSON = tagsHash, tagsJSON
+		bucket.labelsHash, bucket.labelsJSON = emptyLabelsHash, "{}"
+		bucket.addPoint(seed.value, seed.at.UnixMilli())
+		key := rollupKey{entityID: "n1", tagsHash: tagsHash, labelsHash: emptyLabelsHash, bucket: bucketStartMillis(seed.at.UnixMilli(), seed.interval.Milliseconds())}
+		if _, err := s.writeRollupBucketsTx(ctx, "new-series", seed.interval, map[rollupKey]*rollupBucket{key: bucket}, tx); err != nil {
+			_ = tx.Rollback()
+			t.Fatalf("seed %s tier: %v", seed.interval, err)
+		}
+	}
+	if err := tx.Commit(); err != nil {
+		t.Fatalf("commit seed tiers: %v", err)
+	}
+
+	got, err := s.Series(ctx, AggregateQuery{
+		Query:       Query{MetricName: "new-series", EntityID: "n1", Start: now.Add(-time.Hour), End: now},
+		Aggregation: AggAvg,
+		Interval:    time.Minute,
+	}, now)
+	if err != nil {
+		t.Fatalf("query recent series: %v", err)
+	}
+	if len(got) != 1 || got[0].Bucket.Before(now.Add(-time.Hour)) || got[0].Value != 20 {
+		t.Fatalf("recent query fell back to an older coarse tier: %#v", got)
+	}
+}
+
+func TestDeleteBeforeKeepsBucketsThatStraddleCutoff(t *testing.T) {
+	ctx := context.Background()
+	policy := RollupPolicy{
+		Tiers: []RollupTier{
+			{Interval: time.Minute, Retention: 10 * time.Hour},
+			{Interval: 5 * time.Minute, Retention: 50 * time.Hour},
+			{Interval: time.Hour, Retention: 25 * 24 * time.Hour},
+			{Interval: 24 * time.Hour, Retention: 100 * 365 * 24 * time.Hour},
+		},
+		Compression: 30,
+	}
+	s, err := Open(ctx, SQLite(":memory:", WithRollupPolicy(policy)))
+	if err != nil {
+		t.Fatalf("open store: %v", err)
+	}
+	defer s.Close()
+	if err := s.CreateMetric(ctx, Definition{Name: "retention-boundary", RetentionDays: 60}); err != nil {
+		t.Fatalf("create metric: %v", err)
+	}
+	day := time.Now().UTC().Truncate(24 * time.Hour).Add(-48 * time.Hour)
+	if err := s.WriteBatch(ctx, []Point{
+		{MetricName: "retention-boundary", EntityID: "n1", Timestamp: day.Add(12 * time.Hour), Value: 10},
+		{MetricName: "retention-boundary", EntityID: "n1", Timestamp: day.Add(20 * time.Hour), Value: 20},
+	}); err != nil {
+		t.Fatalf("write daily boundary points: %v", err)
+	}
+	if _, err := s.DeleteBefore(ctx, "retention-boundary", day.Add(18*time.Hour)); err != nil {
+		t.Fatalf("delete before cutoff: %v", err)
+	}
+	var dailyCount int64
+	if err := s.db.QueryRowContext(ctx, fmt.Sprintf(`SELECT r.count FROM %s r
+		JOIN %s series ON series.id = r.series_id
+		JOIN %s resolutions ON resolutions.id = r.resolution_id
+		WHERE series.metric_name = ? AND resolutions.resolution_milli = ?`,
+		s.tables.rollups, s.tables.series, s.tables.resolutions), "retention-boundary", (24 * time.Hour).Milliseconds()).Scan(&dailyCount); err != nil {
+		t.Fatalf("read straddling daily bucket: %v", err)
+	}
+	if dailyCount != 2 {
+		t.Fatalf("straddling daily bucket count = %d, want 2", dailyCount)
+	}
+
+	futureMinute := time.Now().UTC().Truncate(time.Minute).Add(2 * time.Minute)
+	if err := s.Write(ctx, Point{MetricName: "retention-boundary", EntityID: "n1", Timestamp: futureMinute.Add(40 * time.Second), Value: 30}); err != nil {
+		t.Fatalf("write active boundary point: %v", err)
+	}
+	if _, err := s.DeleteBefore(ctx, "retention-boundary", futureMinute.Add(30*time.Second)); err != nil {
+		t.Fatalf("delete before active-minute cutoff: %v", err)
+	}
+	if len(s.hot) != 1 {
+		t.Fatalf("active minute was deleted across a partial cutoff: %#v", s.hot)
+	}
+}
+
+func TestCompatibleIntervalsCoverDashboardRanges(t *testing.T) {
+	now := time.Date(2026, 7, 24, 12, 0, 0, 0, time.UTC)
+	policy := RollupPolicy{
+		RawRetention: time.Minute,
+		Tiers: []RollupTier{
+			{Interval: time.Minute, Retention: 10 * time.Hour},
+			{Interval: 5 * time.Minute, Retention: 50 * time.Hour},
+			{Interval: time.Hour, Retention: 25 * 24 * time.Hour},
+			{Interval: 24 * time.Hour, Retention: 100 * 365 * 24 * time.Hour},
+		},
+	}
+	s := &Store{cfg: Config{RollupPolicy: policy}}
+	for _, test := range []struct {
+		rangeDuration time.Duration
+		interval      time.Duration
+	}{
+		{time.Hour, time.Minute},
+		{6 * time.Hour, time.Minute},
+		{7 * 24 * time.Hour, 15 * time.Minute},
+		{30 * 24 * time.Hour, time.Hour},
+		{60 * 24 * time.Hour, time.Hour},
+	} {
+		got := s.CompatibleSeriesInterval(now.Add(-test.rangeDuration), now, test.interval)
+		if got <= 0 {
+			t.Fatalf("range %s returned invalid interval %s", test.rangeDuration, got)
+		}
+		if got < time.Minute {
+			t.Fatalf("range %s returned %s below persisted minute precision", test.rangeDuration, got)
+		}
+	}
+}
+
+func TestSeriesHasNoTrailingEmptyBucketAcrossDashboardRanges(t *testing.T) {
+	ctx := context.Background()
+	policy := RollupPolicy{
+		RawRetention: time.Minute,
+		Tiers: []RollupTier{
+			{Interval: time.Minute, Retention: 10 * time.Hour},
+			{Interval: 5 * time.Minute, Retention: 50 * time.Hour},
+			{Interval: time.Hour, Retention: 25 * 24 * time.Hour},
+			{Interval: 24 * time.Hour, Retention: 100 * 365 * 24 * time.Hour},
+		},
+		Compression: 30,
+	}
+	s, err := Open(ctx, SQLite(":memory:", WithRollupPolicy(policy)))
+	if err != nil {
+		t.Fatalf("open store: %v", err)
+	}
+	defer s.Close()
+	if err := s.CreateMetric(ctx, Definition{Name: "coverage", RetentionDays: 90}); err != nil {
+		t.Fatalf("create metric: %v", err)
+	}
+	now := time.Date(2026, 7, 24, 12, 0, 0, 0, time.UTC)
+	points := make([]Point, 0, 60*24*60)
+	for at := now.Add(-60 * 24 * time.Hour); at.Before(now); at = at.Add(time.Minute) {
+		points = append(points, Point{MetricName: "coverage", EntityID: "n1", Timestamp: at, Value: 1})
+	}
+	if err := s.WriteBatch(ctx, points); err != nil {
+		t.Fatalf("write history: %v", err)
+	}
+	if _, err := s.Compact(ctx, now); err != nil {
+		t.Fatalf("compact history: %v", err)
+	}
+	for _, duration := range []time.Duration{time.Hour, 6 * time.Hour, 7 * 24 * time.Hour, 30 * 24 * time.Hour, 60 * 24 * time.Hour} {
+		interval := s.CompatibleSeriesInterval(now.Add(-duration), now, time.Minute)
+		series, err := s.Series(ctx, AggregateQuery{
+			Query:       Query{MetricName: "coverage", EntityID: "n1", Start: now.Add(-duration), End: now},
+			Aggregation: AggAvg,
+			Interval:    interval,
+		}, now)
+		if err != nil {
+			t.Fatalf("query %s: %v", duration, err)
+		}
+		if len(series) == 0 {
+			t.Fatalf("query %s returned no retained buckets", duration)
+		}
+		if series[len(series)-1].Count == 0 {
+			t.Fatalf("query %s ended with an empty bucket: %#v", duration, series[len(series)-1])
+		}
+		for i := 1; i < len(series); i++ {
+			if delta := series[i].Bucket.Sub(series[i-1].Bucket); delta != interval {
+				t.Fatalf("query %s has a break between %s and %s: got %s, want %s", duration, series[i-1].Bucket, series[i].Bucket, delta, interval)
+			}
+		}
+	}
+}

pkg/metric/improvements_test.go

@@ -28,7 +28,7 @@ func newMemStore(t *testing.T) *Store {
 func TestCreateMetricRejectsDuplicate(t *testing.T) {
 	ctx := context.Background()
 	s := newMemStore(t)
-	def := Definition{Name: "dup.metric", Type: TypeGauge}
+	def := Definition{Name: "dup.metric", Type: TypeGauge, RetentionDays: 30}
 	if err := s.CreateMetric(ctx, def); err != nil {
 		t.Fatalf("first create: %v", err)
 	}
@@ -44,10 +44,10 @@ func TestCreateMetricRejectsDuplicate(t *testing.T) {
 func TestUpsertMetricOverwrites(t *testing.T) {
 	ctx := context.Background()
 	s := newMemStore(t)
-	if err := s.CreateMetric(ctx, Definition{Name: "m", Type: TypeGauge, Unit: "ms"}); err != nil {
+	if err := s.CreateMetric(ctx, Definition{Name: "m", Type: TypeGauge, Unit: "ms", RetentionDays: 30}); err != nil {
 		t.Fatalf("create: %v", err)
 	}
-	if err := s.UpsertMetric(ctx, Definition{Name: "m", Type: TypeCounter, Unit: "count"}); err != nil {
+	if err := s.UpsertMetric(ctx, Definition{Name: "m", Type: TypeCounter, Unit: "count", RetentionDays: 30}); err != nil {
 		t.Fatalf("upsert: %v", err)
 	}
 	got, err := s.GetMetric(ctx, "m")
@@ -65,10 +65,10 @@ func TestUpsertMetricOverwrites(t *testing.T) {
 func TestTagFilterPushdownWithPaging(t *testing.T) {
 	ctx := context.Background()
 	s := newMemStore(t)
-	if err := s.CreateMetric(ctx, Definition{Name: "req", Type: TypeCounter}); err != nil {
+	if err := s.CreateMetric(ctx, Definition{Name: "req", Type: TypeCounter, RetentionDays: 30}); err != nil {
 		t.Fatalf("create: %v", err)
 	}
-	base := time.Date(2026, 6, 18, 0, 0, 0, 0, time.UTC)
+	base := time.Now().UTC().Truncate(time.Minute)
 	var batch []Point
 	for i := 0; i < 6; i++ {
 		env := "prod"
@@ -77,7 +77,7 @@ func TestTagFilterPushdownWithPaging(t *testing.T) {
 		}
 		batch = append(batch, Point{
 			MetricName: "req", EntityID: "n1",
-			Timestamp: base.Add(time.Duration(i) * time.Minute),
+			Timestamp: base.Add(time.Duration(i) * 5 * time.Second),
 			Value:     float64(i),
 			Tags:      map[string]string{"env": env},
 		})
@@ -89,7 +89,7 @@ func TestTagFilterPushdownWithPaging(t *testing.T) {
 	// tag-filtered set, returning the first two prod points in time order.
 	got, err := s.Query(ctx, Query{
 		MetricName: "req", EntityID: "n1",
-		Start: base, End: base.Add(time.Hour),
+		Start: base, End: base.Add(time.Minute),
 		Tags:  map[string]string{"env": "prod"},
 		Limit: 2,
 	})
@@ -110,16 +110,16 @@ func TestTagFilterPushdownWithPaging(t *testing.T) {
 func TestSQLAggregateMatchesInMemory(t *testing.T) {
 	ctx := context.Background()
 	s := newMemStore(t)
-	if err := s.CreateMetric(ctx, Definition{Name: "g", Type: TypeGauge}); err != nil {
+	if err := s.CreateMetric(ctx, Definition{Name: "g", Type: TypeGauge, RetentionDays: 30}); err != nil {
 		t.Fatalf("create: %v", err)
 	}
-	base := time.Date(2026, 6, 18, 0, 0, 0, 0, time.UTC)
+	base := time.Now().UTC().Truncate(time.Minute)
 	var batch []Point
 	vals := []float64{5, 15, 25, 35, 100, 200}
 	for i, v := range vals {
 		batch = append(batch, Point{
 			MetricName: "g", EntityID: "n1",
-			Timestamp: base.Add(time.Duration(i) * time.Minute),
+			Timestamp: base.Add(time.Duration(i) * 5 * time.Second),
 			Value:     v,
 		})
 	}
@@ -127,9 +127,9 @@ func TestSQLAggregateMatchesInMemory(t *testing.T) {
 		t.Fatalf("write: %v", err)
 	}
 	q := AggregateQuery{
-		Query:       Query{MetricName: "g", EntityID: "n1", Start: base, End: base.Add(time.Hour)},
+		Query:       Query{MetricName: "g", EntityID: "n1", Start: base, End: base.Add(time.Minute)},
 		Aggregation: AggAvg,
-		Interval:    3 * time.Minute,
+		Interval:    15 * time.Second,
 	}
 	// SQL pushdown path.
 	sqlRes, err := s.Aggregate(ctx, q)
@@ -159,7 +159,7 @@ func TestSQLAggregateMatchesInMemory(t *testing.T) {
 //
 // TestCounterRateHandlesReset 验证计数器重置时速率计算仍然稳定。
 func TestCounterRateHandlesReset(t *testing.T) {
-	base := time.Date(2026, 6, 18, 0, 0, 0, 0, time.UTC)
+	base := time.Now().UTC().Truncate(time.Minute)
 	// Counter goes 0 -> 10 -> reset -> 5; naive (last-first)/sec would give a
 	// positive-but-wrong 5/30s. Correct counter rate sums positive deltas:
 	// (10-0) + (5-0 after reset) = 15 over 30s = 0.5/s.
@@ -195,12 +195,12 @@ func TestAlignTimeNegativeTimestamp(t *testing.T) {
 func TestLatestReturnsMostRecent(t *testing.T) {
 	ctx := context.Background()
 	s := newMemStore(t)
-	if err := s.CreateMetric(ctx, Definition{Name: "l", Type: TypeGauge}); err != nil {
+	if err := s.CreateMetric(ctx, Definition{Name: "l", Type: TypeGauge, RetentionDays: 30}); err != nil {
 		t.Fatalf("create: %v", err)
 	}
-	base := time.Date(2026, 6, 18, 0, 0, 0, 0, time.UTC)
+	base := time.Now().UTC().Add(-30 * time.Second)
 	for i := 0; i < 5; i++ {
-		if err := s.Write(ctx, Point{MetricName: "l", EntityID: "n1", Timestamp: base.Add(time.Duration(i) * time.Minute), Value: float64(i)}); err != nil {
+		if err := s.Write(ctx, Point{MetricName: "l", EntityID: "n1", Timestamp: base.Add(time.Duration(i) * 5 * time.Second), Value: float64(i)}); err != nil {
 			t.Fatalf("write: %v", err)
 		}
 	}
@@ -219,7 +219,7 @@ func TestLatestReturnsMostRecent(t *testing.T) {
 func TestStatsDistinguishesNoDataFromUnknownMetric(t *testing.T) {
 	ctx := context.Background()
 	s := newMemStore(t)
-	base := time.Date(2026, 6, 18, 0, 0, 0, 0, time.UTC)
+	base := time.Now().UTC().Truncate(time.Minute)
 
 	// Unknown metric -> ErrNotFound.
 	_, err := s.Stats(ctx, Query{MetricName: "nope", Start: base, End: base.Add(time.Hour)})
@@ -228,7 +228,7 @@ func TestStatsDistinguishesNoDataFromUnknownMetric(t *testing.T) {
 	}
 
 	// Known metric but empty window -> ErrNoData.
-	if err := s.CreateMetric(ctx, Definition{Name: "known", Type: TypeGauge}); err != nil {
+	if err := s.CreateMetric(ctx, Definition{Name: "known", Type: TypeGauge, RetentionDays: 30}); err != nil {
 		t.Fatalf("create: %v", err)
 	}
 	_, err = s.Stats(ctx, Query{MetricName: "known", Start: base, End: base.Add(time.Hour)})
@@ -266,19 +266,19 @@ func TestStdDevPopMatchesCalculateStats(t *testing.T) {
 func TestAggregateStdDevSQLiteUsesMemoryPath(t *testing.T) {
 	ctx := context.Background()
 	s := newMemStore(t)
-	if err := s.CreateMetric(ctx, Definition{Name: "sd", Type: TypeGauge}); err != nil {
+	if err := s.CreateMetric(ctx, Definition{Name: "sd", Type: TypeGauge, RetentionDays: 30}); err != nil {
 		t.Fatalf("create: %v", err)
 	}
-	base := time.Date(2026, 6, 18, 0, 0, 0, 0, time.UTC)
+	base := time.Now().UTC().Truncate(time.Minute)
 	var batch []Point
 	for i, v := range []float64{10, 20, 30} {
-		batch = append(batch, Point{MetricName: "sd", EntityID: "n1", Timestamp: base.Add(time.Duration(i) * time.Minute), Value: v})
+		batch = append(batch, Point{MetricName: "sd", EntityID: "n1", Timestamp: base.Add(time.Duration(i) * 5 * time.Second), Value: v})
 	}
 	if err := s.WriteBatch(ctx, batch); err != nil {
 		t.Fatalf("write: %v", err)
 	}
 	res, err := s.Aggregate(ctx, AggregateQuery{
-		Query:       Query{MetricName: "sd", EntityID: "n1", Start: base, End: base.Add(time.Hour)},
+		Query:       Query{MetricName: "sd", EntityID: "n1", Start: base, End: base.Add(time.Minute)},
 		Aggregation: AggStdDev,
 		Interval:    time.Hour,
 	})
@@ -342,10 +342,10 @@ func TestSQLiteReadPoolOpens(t *testing.T) {
 		t.Fatalf("reader() should return the dedicated read pool")
 	}
 	// Round-trip a write (primary) and a read (read pool).
-	if err := store.CreateMetric(ctx, Definition{Name: "rp", Type: TypeGauge}); err != nil {
+	if err := store.CreateMetric(ctx, Definition{Name: "rp", Type: TypeGauge, RetentionDays: 30}); err != nil {
 		t.Fatalf("create: %v", err)
 	}
-	base := time.Date(2026, 6, 18, 0, 0, 0, 0, time.UTC)
+	base := time.Now().UTC()
 	if err := store.Write(ctx, Point{MetricName: "rp", EntityID: "n1", Timestamp: base, Value: 7}); err != nil {
 		t.Fatalf("write: %v", err)
 	}
@@ -379,7 +379,7 @@ func TestMemoryDSNSkipsReadPool(t *testing.T) {
 func TestWriteBatchAtomicAcrossChunks(t *testing.T) {
 	ctx := context.Background()
 	s := newMemStore(t)
-	if err := s.CreateMetric(ctx, Definition{Name: "atom", Type: TypeGauge}); err != nil {
+	if err := s.CreateMetric(ctx, Definition{Name: "atom", Type: TypeGauge, RetentionDays: 30}); err != nil {
 		t.Fatalf("create: %v", err)
 	}
 	base := time.Date(2026, 6, 18, 0, 0, 0, 0, time.UTC)
@@ -409,23 +409,23 @@ func TestWriteBatchAtomicAcrossChunks(t *testing.T) {
 func TestAggregateBucketPagingSQLPath(t *testing.T) {
 	ctx := context.Background()
 	s := newMemStore(t)
-	if err := s.CreateMetric(ctx, Definition{Name: "bp", Type: TypeGauge}); err != nil {
+	if err := s.CreateMetric(ctx, Definition{Name: "bp", Type: TypeGauge, RetentionDays: 30}); err != nil {
 		t.Fatalf("create: %v", err)
 	}
-	base := time.Date(2026, 6, 18, 0, 0, 0, 0, time.UTC)
-	// 6 points across 6 one-minute buckets, values 0..5.
+	base := time.Now().UTC().Truncate(time.Minute)
+	// 6 points across 6 ten-second buckets, values 0..5.
 	var batch []Point
 	for i := 0; i < 6; i++ {
-		batch = append(batch, Point{MetricName: "bp", EntityID: "n1", Timestamp: base.Add(time.Duration(i) * time.Minute), Value: float64(i)})
+		batch = append(batch, Point{MetricName: "bp", EntityID: "n1", Timestamp: base.Add(time.Duration(i) * 10 * time.Second), Value: float64(i)})
 	}
 	if err := s.WriteBatch(ctx, batch); err != nil {
 		t.Fatalf("write: %v", err)
 	}
-	// AggAvg -> SQL pushdown path. One bucket per minute. Page: offset 1, limit 2.
+	// One bucket per ten seconds. Page: offset 1, limit 2.
 	res, err := s.Aggregate(ctx, AggregateQuery{
-		Query:        Query{MetricName: "bp", EntityID: "n1", Start: base, End: base.Add(time.Hour)},
+		Query:        Query{MetricName: "bp", EntityID: "n1", Start: base, End: base.Add(time.Minute)},
 		Aggregation:  AggAvg,
-		Interval:     time.Minute,
+		Interval:     10 * time.Second,
 		BucketLimit:  2,
 		BucketOffset: 1,
 	})
@@ -447,25 +447,25 @@ func TestAggregateBucketPagingSQLPath(t *testing.T) {
 func TestAggregateBucketPagingMemoryPathMatchesSQL(t *testing.T) {
 	ctx := context.Background()
 	s := newMemStore(t)
-	if err := s.CreateMetric(ctx, Definition{Name: "bp2", Type: TypeGauge}); err != nil {
+	if err := s.CreateMetric(ctx, Definition{Name: "bp2", Type: TypeGauge, RetentionDays: 30}); err != nil {
 		t.Fatalf("create: %v", err)
 	}
-	base := time.Date(2026, 6, 18, 0, 0, 0, 0, time.UTC)
+	base := time.Now().UTC().Truncate(time.Minute)
 	var batch []Point
 	for i := 0; i < 6; i++ {
-		batch = append(batch, Point{MetricName: "bp2", EntityID: "n1", Timestamp: base.Add(time.Duration(i) * time.Minute), Value: float64(i * 10)})
+		batch = append(batch, Point{MetricName: "bp2", EntityID: "n1", Timestamp: base.Add(time.Duration(i) * 10 * time.Second), Value: float64(i * 10)})
 	}
 	if err := s.WriteBatch(ctx, batch); err != nil {
 		t.Fatalf("write: %v", err)
 	}
-	q := Query{MetricName: "bp2", EntityID: "n1", Start: base, End: base.Add(time.Hour)}
+	q := Query{MetricName: "bp2", EntityID: "n1", Start: base, End: base.Add(time.Minute)}
 	// AggMin (SQL pushdown) and AggP50 (memory fallback on sqlite) with identical
 	// bucket paging must select the same bucket window (the same timestamps).
-	sqlPaged, err := s.Aggregate(ctx, AggregateQuery{Query: q, Aggregation: AggMin, Interval: time.Minute, BucketLimit: 3, BucketOffset: 2})
+	sqlPaged, err := s.Aggregate(ctx, AggregateQuery{Query: q, Aggregation: AggMin, Interval: 10 * time.Second, BucketLimit: 3, BucketOffset: 2})
 	if err != nil {
 		t.Fatalf("sql aggregate: %v", err)
 	}
-	memPaged, err := s.Aggregate(ctx, AggregateQuery{Query: q, Aggregation: AggP50, Interval: time.Minute, BucketLimit: 3, BucketOffset: 2})
+	memPaged, err := s.Aggregate(ctx, AggregateQuery{Query: q, Aggregation: AggP50, Interval: 10 * time.Second, BucketLimit: 3, BucketOffset: 2})
 	if err != nil {
 		t.Fatalf("mem aggregate: %v", err)
 	}
@@ -488,10 +488,10 @@ func TestAggregateBucketPagingMemoryPathMatchesSQL(t *testing.T) {
 func TestAggregateSeparatesTagSeries(t *testing.T) {
 	ctx := context.Background()
 	s := newMemStore(t)
-	if err := s.CreateMetric(ctx, Definition{Name: "tagged.util", Type: TypeGauge}); err != nil {
+	if err := s.CreateMetric(ctx, Definition{Name: "tagged.util", Type: TypeGauge, RetentionDays: 30}); err != nil {
 		t.Fatalf("create: %v", err)
 	}
-	base := time.Date(2026, 6, 18, 0, 0, 0, 0, time.UTC)
+	base := time.Now().UTC().Truncate(time.Minute)
 	points := []Point{
 		{MetricName: "tagged.util", EntityID: "n1", Timestamp: base.Add(10 * time.Second), Value: 10, Tags: map[string]string{"device": "0"}},
 		{MetricName: "tagged.util", EntityID: "n1", Timestamp: base.Add(20 * time.Second), Value: 30, Tags: map[string]string{"device": "0"}},
@@ -546,13 +546,13 @@ func assertTaggedAggregate(t *testing.T, points []AggregatePoint, device string,
 func TestAggregateIgnoresRawPointLimit(t *testing.T) {
 	ctx := context.Background()
 	s := newMemStore(t)
-	if err := s.CreateMetric(ctx, Definition{Name: "ig", Type: TypeGauge}); err != nil {
+	if err := s.CreateMetric(ctx, Definition{Name: "ig", Type: TypeGauge, RetentionDays: 30}); err != nil {
 		t.Fatalf("create: %v", err)
 	}
-	base := time.Date(2026, 6, 18, 0, 0, 0, 0, time.UTC)
+	base := time.Now().UTC().Truncate(time.Minute)
 	var batch []Point
 	for i := 0; i < 6; i++ {
-		batch = append(batch, Point{MetricName: "ig", EntityID: "n1", Timestamp: base.Add(time.Duration(i) * time.Minute), Value: float64(i)})
+		batch = append(batch, Point{MetricName: "ig", EntityID: "n1", Timestamp: base.Add(time.Duration(i) * 5 * time.Second), Value: float64(i)})
 	}
 	if err := s.WriteBatch(ctx, batch); err != nil {
 		t.Fatalf("write: %v", err)
@@ -578,10 +578,10 @@ func TestAggregateIgnoresRawPointLimit(t *testing.T) {
 func TestJSONTagKeyWithSpecialChars(t *testing.T) {
 	ctx := context.Background()
 	s := newMemStore(t)
-	if err := s.CreateMetric(ctx, Definition{Name: "tk", Type: TypeGauge}); err != nil {
+	if err := s.CreateMetric(ctx, Definition{Name: "tk", Type: TypeGauge, RetentionDays: 30}); err != nil {
 		t.Fatalf("create: %v", err)
 	}
-	base := time.Date(2026, 6, 18, 0, 0, 0, 0, time.UTC)
+	base := time.Now().UTC().Truncate(time.Minute)
 	// Keys containing a dot, a hyphen, a space, and a quote.
 	tags := map[string]string{
 		"region.zone": "ap-1",
@@ -592,7 +592,7 @@ func TestJSONTagKeyWithSpecialChars(t *testing.T) {
 		t.Fatalf("write: %v", err)
 	}
 	// A second point that should NOT match the filter below.
-	if err := s.Write(ctx, Point{MetricName: "tk", EntityID: "n1", Timestamp: base.Add(time.Minute), Value: 2, Tags: map[string]string{"region.zone": "eu-1"}}); err != nil {
+	if err := s.Write(ctx, Point{MetricName: "tk", EntityID: "n1", Timestamp: base.Add(10 * time.Second), Value: 2, Tags: map[string]string{"region.zone": "eu-1"}}); err != nil {
 		t.Fatalf("write 2: %v", err)
 	}
 

pkg/metric/interval.go

@@ -0,0 +1,48 @@
+package metric
+
+import "time"
+
+var standardQueryIntervals = [...]time.Duration{
+	time.Second,
+	5 * time.Second,
+	10 * time.Second,
+	15 * time.Second,
+	30 * time.Second,
+	time.Minute,
+	2 * time.Minute,
+	5 * time.Minute,
+	10 * time.Minute,
+	15 * time.Minute,
+	30 * time.Minute,
+	time.Hour,
+	2 * time.Hour,
+	3 * time.Hour,
+	6 * time.Hour,
+	12 * time.Hour,
+	24 * time.Hour,
+}
+
+// FloorStandardInterval returns the largest standard query interval that does
+// not exceed interval. Values below one second use the minimum interval.
+func FloorStandardInterval(interval time.Duration) time.Duration {
+	selected := standardQueryIntervals[0]
+	for _, candidate := range standardQueryIntervals {
+		if candidate > interval {
+			break
+		}
+		selected = candidate
+	}
+	return selected
+}
+
+// CeilStandardInterval returns the smallest standard query interval that is
+// at least interval. Values above one day are rounded up to whole days.
+func CeilStandardInterval(interval time.Duration) time.Duration {
+	for _, candidate := range standardQueryIntervals {
+		if candidate >= interval {
+			return candidate
+		}
+	}
+	day := standardQueryIntervals[len(standardQueryIntervals)-1]
+	return ((interval-1)/day + 1) * day
+}

pkg/metric/interval_test.go

@@ -0,0 +1,31 @@
+package metric
+
+import (
+	"testing"
+	"time"
+)
+
+func TestStandardIntervals(t *testing.T) {
+	tests := []struct {
+		name     string
+		interval time.Duration
+		floor    time.Duration
+		ceil     time.Duration
+	}{
+		{name: "below minimum", interval: 500 * time.Millisecond, floor: time.Second, ceil: time.Second},
+		{name: "exact", interval: 5 * time.Minute, floor: 5 * time.Minute, ceil: 5 * time.Minute},
+		{name: "between standards", interval: 7 * time.Minute, floor: 5 * time.Minute, ceil: 10 * time.Minute},
+		{name: "above one day", interval: 25 * time.Hour, floor: 24 * time.Hour, ceil: 48 * time.Hour},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if got := FloorStandardInterval(test.interval); got != test.floor {
+				t.Fatalf("FloorStandardInterval(%s) = %s, want %s", test.interval, got, test.floor)
+			}
+			if got := CeilStandardInterval(test.interval); got != test.ceil {
+				t.Fatalf("CeilStandardInterval(%s) = %s, want %s", test.interval, got, test.ceil)
+			}
+		})
+	}
+}

pkg/metric/maintenance.go

@@ -46,11 +46,10 @@ func (s *Store) MaintenanceAction() MaintenanceAction {
 
 // StorageSize returns the physical bytes occupied by this Store. SQLite
 // includes the main database, WAL, and shared-memory files. Server backends
-// include only the definitions, points, and rollups tables managed by Store.
+// include only the definition, dictionary, and rollup tables managed by Store.
 //
 // StorageSize 返回当前 Store 占用的物理字节数。SQLite 会统计主数据库、WAL
-// 和共享内存文件；服务端数据库只统计 Store 管理的 definitions、points 和
-// rollups 三张表。
+// 和共享内存文件；服务端数据库只统计 Store 管理的定义、字典和 rollup 表。
 func (s *Store) StorageSize(ctx context.Context) (int64, error) {
 	s.maintenanceMu.RLock()
 	defer s.maintenanceMu.RUnlock()
@@ -76,6 +75,22 @@ func (s *Store) StorageSize(ctx context.Context) (int64, error) {
 	return size, nil
 }
 
+// CheckpointWAL copies committed SQLite WAL pages into the main database and
+// truncates the sidecar. Other backends have no local WAL sidecar.
+func (s *Store) CheckpointWAL(ctx context.Context) error {
+	s.maintenanceMu.Lock()
+	defer s.maintenanceMu.Unlock()
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	if s.closed || s.db == nil {
+		return ErrClosed
+	}
+	if s.cfg.Driver != DriverSQLite {
+		return nil
+	}
+	return sqliteCheckpoint(ctx, s.db)
+}
+
 // ReclaimSpace performs the backend-specific blocking operation that returns
 // unused database pages to the filesystem. It serializes against other
 // maintenance calls and keeps Close from closing the pool mid-operation.
@@ -91,6 +106,9 @@ func (s *Store) ReclaimSpace(ctx context.Context) error {
 	if s.closed || s.db == nil {
 		return ErrClosed
 	}
+	if _, err := s.cleanupOrphanedMetricData(ctx); err != nil {
+		return err
+	}
 
 	switch s.cfg.Driver {
 	case DriverSQLite:
@@ -123,6 +141,41 @@ func (s *Store) ReclaimSpace(ctx context.Context) error {
 	}
 }
 
+// cleanupOrphanedMetricData removes rows whose metric definition no longer
+// exists. It runs immediately before an explicit space-reclaim operation so
+// the physical rewrite returns the freed pages to the filesystem in the same
+// maintenance window.
+func (s *Store) cleanupOrphanedMetricData(ctx context.Context) (int64, error) {
+	var deleted int64
+	result, err := s.db.ExecContext(ctx, fmt.Sprintf(
+		`DELETE FROM %s WHERE NOT EXISTS (SELECT 1 FROM %s s JOIN %s d ON d.name = s.metric_name WHERE s.id = %s.series_id)`,
+		s.tables.rollups, s.tables.series, s.tables.definitions, s.tables.rollups))
+	if err != nil {
+		return deleted, fmt.Errorf("metric: delete orphaned rows from %s: %w", s.tables.rollups, err)
+	}
+	count, err := result.RowsAffected()
+	if err != nil {
+		return deleted, err
+	}
+	deleted += count
+	for _, statement := range []string{
+		fmt.Sprintf(`DELETE FROM %s WHERE NOT EXISTS (SELECT 1 FROM %s r WHERE r.series_id = %s.id)`, s.tables.series, s.tables.rollups, s.tables.series),
+		fmt.Sprintf(`DELETE FROM %s WHERE NOT EXISTS (SELECT 1 FROM %s r WHERE r.label_id = %s.id)`, s.tables.labels, s.tables.rollups, s.tables.labels),
+		fmt.Sprintf(`DELETE FROM %s WHERE NOT EXISTS (SELECT 1 FROM %s r WHERE r.resolution_id = %s.id)`, s.tables.resolutions, s.tables.rollups, s.tables.resolutions),
+	} {
+		result, err := s.db.ExecContext(ctx, statement)
+		if err != nil {
+			return deleted, err
+		}
+		count, err := result.RowsAffected()
+		if err != nil {
+			return deleted, err
+		}
+		deleted += count
+	}
+	return deleted, nil
+}
+
 func (s *Store) sqliteStorageSize(ctx context.Context) (int64, error) {
 	rows, err := s.db.QueryContext(ctx, "PRAGMA database_list")
 	if err != nil {
@@ -235,21 +288,27 @@ func maintenanceActionFor(driver Driver) MaintenanceAction {
 
 func managedStorageSizeQuery(driver Driver, t tables) (string, []any, error) {
 	names := managedTableNames(t)
+	d := newDialect(driver)
+	placeholders := make([]string, len(names))
+	for i := range names {
+		placeholders[i] = d.placeholder(i + 1)
+	}
+	inClause := strings.Join(placeholders, ", ")
 	switch driver {
 	case DriverMySQL:
-		return `SELECT COALESCE(SUM(DATA_LENGTH + INDEX_LENGTH), 0)
+		return fmt.Sprintf(`SELECT COALESCE(SUM(DATA_LENGTH + INDEX_LENGTH), 0)
 FROM information_schema.TABLES
 WHERE TABLE_SCHEMA = DATABASE()
-  AND TABLE_NAME IN (?, ?, ?)`, stringsToAny(names), nil
+	  AND TABLE_NAME IN (%s)`, inClause), stringsToAny(names), nil
 	case DriverPostgreSQL:
 		for i := range names {
 			names[i] = strings.ToLower(names[i])
 		}
-		return `SELECT COALESCE(SUM(pg_total_relation_size(c.oid)), 0)
+		return fmt.Sprintf(`SELECT COALESCE(SUM(pg_total_relation_size(c.oid)), 0)
 FROM pg_catalog.pg_class AS c
 JOIN pg_catalog.pg_namespace AS n ON n.oid = c.relnamespace
 WHERE n.nspname = current_schema()
-  AND c.relname IN ($1, $2, $3)`, stringsToAny(names), nil
+	  AND c.relname IN (%s)`, inClause), stringsToAny(names), nil
 	default:
 		return "", nil, fmt.Errorf("%w: storage-size query is unavailable for driver %q", ErrInvalidArgument, driver)
 	}
@@ -276,7 +335,7 @@ func managedReclaimQuery(driver Driver, t tables) (string, error) {
 }
 
 func managedTableNames(t tables) []string {
-	return []string{t.definitions, t.points, t.rollups}
+	return []string{t.definitions, t.series, t.labels, t.resolutions, t.rollups}
 }
 
 func quoteMaintenanceIdentifier(driver Driver, identifier string) string {

pkg/metric/maintenance_test.go

@@ -3,11 +3,13 @@ package metric
 import (
 	"context"
 	"errors"
+	"fmt"
 	"os"
 	"path/filepath"
 	"reflect"
 	"strings"
 	"testing"
+	"time"
 )
 
 func TestSQLiteStorageSizeAndReclaimSpace(t *testing.T) {
@@ -73,10 +75,63 @@ func TestSQLiteStorageSizeAndReclaimSpace(t *testing.T) {
 	}
 }
 
+func TestCleanupOrphanedMetricData(t *testing.T) {
+	ctx := context.Background()
+	store := newMemStore(t)
+	if err := store.CreateMetric(ctx, Definition{Name: "known", Type: TypeGauge, RetentionDays: 1}); err != nil {
+		t.Fatalf("create known definition: %v", err)
+	}
+	// Simulate a pre-constraint store containing orphaned rows. New stores
+	// reject this state through their database foreign keys.
+	if _, err := store.db.ExecContext(ctx, "PRAGMA foreign_keys = OFF"); err != nil {
+		t.Fatalf("disable foreign keys for legacy fixture: %v", err)
+	}
+	now := time.Now().UTC().UnixMilli()
+	if _, err := store.db.ExecContext(ctx, fmt.Sprintf(`INSERT INTO %s (metric_name, entity_id, tags_hash, tags) VALUES (?, ?, ?, ?)`, store.tables.series), "orphan", "node-1", "hash", "{}"); err != nil {
+		t.Fatalf("seed orphan series: %v", err)
+	}
+	if _, err := store.db.ExecContext(ctx, fmt.Sprintf(`INSERT INTO %s (labels_hash, labels) VALUES (?, ?)`, store.tables.labels), emptyLabelsHash, "{}"); err != nil {
+		t.Fatalf("seed orphan labels: %v", err)
+	}
+	if _, err := store.db.ExecContext(ctx, fmt.Sprintf(`INSERT INTO %s (resolution_milli) VALUES (?)`, store.tables.resolutions), time.Minute.Milliseconds()); err != nil {
+		t.Fatalf("seed orphan resolution: %v", err)
+	}
+	if _, err := store.db.ExecContext(ctx, fmt.Sprintf(
+		`INSERT INTO %s (series_id, resolution_id, label_id, bucket_milli, count, sum, sum_sq, min_val, max_val, first_val, first_ts_milli, last_val, last_ts_milli, digest, created_at_milli)
+		 SELECT s.id, r.id, l.id, ?, 1, 1, 1, 1, 1, 1, ?, 1, ?, NULL, ? FROM %s s, %s r, %s l WHERE s.metric_name = ?`,
+		store.tables.rollups, store.tables.series, store.tables.resolutions, store.tables.labels,
+	), now, now, now, now, "orphan"); err != nil {
+		t.Fatalf("seed orphan rollup: %v", err)
+	}
+	if _, err := store.db.ExecContext(ctx, "PRAGMA foreign_keys = ON"); err != nil {
+		t.Fatalf("restore foreign keys after legacy fixture: %v", err)
+	}
+
+	deleted, err := store.cleanupOrphanedMetricData(ctx)
+	if err != nil {
+		t.Fatalf("clean orphaned metric data: %v", err)
+	}
+	if deleted != 4 {
+		t.Fatalf("deleted rows = %d, want 4", deleted)
+	}
+	for _, table := range []string{store.tables.series, store.tables.labels, store.tables.resolutions, store.tables.rollups} {
+		var count int
+		if err := store.db.QueryRowContext(ctx, fmt.Sprintf(`SELECT COUNT(*) FROM %s`, table)).Scan(&count); err != nil {
+			t.Fatalf("count orphan rows in %s: %v", table, err)
+		}
+		if count != 0 {
+			t.Fatalf("orphan rows remain in %s: %d", table, count)
+		}
+	}
+}
+
 func TestMaintenanceMappings(t *testing.T) {
 	tables := tables{
 		definitions: "Metric_definitions",
 		points:      "Metric_points",
+		series:      "Metric_series",
+		labels:      "Metric_label_sets",
+		resolutions: "Metric_resolutions",
 		rollups:     "Metric_rollups",
 	}
 
@@ -100,18 +155,18 @@ func TestMaintenanceMappings(t *testing.T) {
 			name:       "mysql",
 			driver:     DriverMySQL,
 			action:     MaintenanceOptimize,
-			reclaim:    "OPTIMIZE TABLE `Metric_definitions`, `Metric_points`, `Metric_rollups`",
-			sizeParts:  []string{"information_schema.TABLES", "TABLE_SCHEMA = DATABASE()", "TABLE_NAME IN (?, ?, ?)"},
-			sizeArgs:   []any{"Metric_definitions", "Metric_points", "Metric_rollups"},
+			reclaim:    "OPTIMIZE TABLE `Metric_definitions`, `Metric_series`, `Metric_label_sets`, `Metric_resolutions`, `Metric_rollups`",
+			sizeParts:  []string{"information_schema.TABLES", "TABLE_SCHEMA = DATABASE()", "TABLE_NAME IN (?, ?, ?, ?, ?)"},
+			sizeArgs:   []any{"Metric_definitions", "Metric_series", "Metric_label_sets", "Metric_resolutions", "Metric_rollups"},
 			hasSizeSQL: true,
 		},
 		{
 			name:       "postgresql",
 			driver:     DriverPostgreSQL,
 			action:     MaintenanceVacuumFull,
-			reclaim:    `VACUUM (FULL, ANALYZE) "metric_definitions", "metric_points", "metric_rollups"`,
-			sizeParts:  []string{"pg_total_relation_size(c.oid)", "n.nspname = current_schema()", "c.relname IN ($1, $2, $3)"},
-			sizeArgs:   []any{"metric_definitions", "metric_points", "metric_rollups"},
+			reclaim:    `VACUUM (FULL, ANALYZE) "metric_definitions", "metric_series", "metric_label_sets", "metric_resolutions", "metric_rollups"`,
+			sizeParts:  []string{"pg_total_relation_size(c.oid)", "n.nspname = current_schema()", "c.relname IN ($1, $2, $3, $4, $5)"},
+			sizeArgs:   []any{"metric_definitions", "metric_series", "metric_label_sets", "metric_resolutions", "metric_rollups"},
 			hasSizeSQL: true,
 		},
 	}

pkg/metric/migrations.go

@@ -2,181 +2,146 @@ package metric
 
 import (
 	"context"
+	"database/sql"
 	"fmt"
 )
 
-// Migrate creates the tables and indexes used by the metric store.
-//
-// Migrate 创建 metric 包需要的表和索引。
+// Migrate creates the normalized metric schema. Series, labels, and
+// resolutions are interned once and every stored timestamp is Unix
+// milliseconds. Exact samples live only in the Store's ten-minute memory
+// window and are never persisted.
+// Existing installations are rebuilt explicitly by the administrator guide,
+// rather than being changed during startup.
 func (s *Store) Migrate(ctx context.Context) error {
 	if err := s.ensureOpen(); err != nil {
 		return err
 	}
+	for _, statement := range s.normalizedSchemaStatements() {
+		if _, err := s.db.ExecContext(ctx, statement); err != nil {
+			return err
+		}
+	}
+	return s.createNormalizedIndexes(ctx)
+}
+
+func (s *Store) normalizedSchemaStatements() []string {
 	d := s.dialect
 	jsonType := d.jsonType()
 	pk := d.autoIncrementPrimaryKey()
-	blob := d.blobType()
-
-	statements := []string{
+	return []string{
 		fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (
-			name VARCHAR(191) PRIMARY KEY,
-			type VARCHAR(32) NOT NULL,
-			unit VARCHAR(64) NOT NULL DEFAULT '',
-			description TEXT NOT NULL DEFAULT '',
-			retention_days INTEGER NOT NULL DEFAULT 0,
-			metadata %s NOT NULL,
-			created_at BIGINT NOT NULL,
-			updated_at BIGINT NOT NULL
+			name VARCHAR(191) PRIMARY KEY, type VARCHAR(32) NOT NULL,
+			unit VARCHAR(64) NOT NULL DEFAULT '', description TEXT NOT NULL,
+			retention_days INTEGER NOT NULL DEFAULT 0, metadata %s NOT NULL,
+			created_at_milli BIGINT NOT NULL, updated_at_milli BIGINT NOT NULL
 		)`, s.tables.definitions, jsonType),
 		fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (
-			id %s,
-			metric_name VARCHAR(191) NOT NULL,
-			entity_id VARCHAR(191) NOT NULL,
-			tags_hash VARCHAR(64) NOT NULL,
-			ts_nano BIGINT NOT NULL,
-			value DOUBLE PRECISION NOT NULL,
-			tags %s NOT NULL,
-			labels %s NOT NULL,
-			created_at BIGINT NOT NULL,
-			UNIQUE(metric_name, entity_id, tags_hash, ts_nano)
-		)`, s.tables.points, pk, jsonType, jsonType),
-		fmt.Sprintf(`CREATE INDEX IF NOT EXISTS %s_points_metric_entity_time_idx ON %s (metric_name, entity_id, ts_nano)`, s.cfg.TablePrefix, s.tables.points),
-		fmt.Sprintf(`CREATE INDEX IF NOT EXISTS %s_points_metric_time_idx ON %s (metric_name, ts_nano)`, s.cfg.TablePrefix, s.tables.points),
-		fmt.Sprintf(`CREATE INDEX IF NOT EXISTS %s_points_entity_time_idx ON %s (entity_id, ts_nano)`, s.cfg.TablePrefix, s.tables.points),
+			id %s, labels_hash VARCHAR(64) NOT NULL, labels %s NOT NULL,
+			UNIQUE(labels_hash)
+		)`, s.tables.labels, pk, jsonType),
 		fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (
-			id %s,
-			metric_name VARCHAR(191) NOT NULL,
-			entity_id VARCHAR(191) NOT NULL,
-			tags_hash VARCHAR(64) NOT NULL,
-			tags %s NOT NULL,
-			resolution_nano BIGINT NOT NULL,
-			bucket_nano BIGINT NOT NULL,
-			count BIGINT NOT NULL,
-			sum DOUBLE PRECISION NOT NULL,
-			sum_sq DOUBLE PRECISION NOT NULL,
-			min_val DOUBLE PRECISION NOT NULL,
-			max_val DOUBLE PRECISION NOT NULL,
-			first_val DOUBLE PRECISION NOT NULL,
-			first_ts BIGINT NOT NULL,
-			last_val DOUBLE PRECISION NOT NULL,
-			last_ts BIGINT NOT NULL,
-			digest %s,
-			created_at BIGINT NOT NULL,
-			UNIQUE(metric_name, entity_id, tags_hash, resolution_nano, bucket_nano)
-		)`, s.tables.rollups, pk, jsonType, blob),
-		fmt.Sprintf(`CREATE INDEX IF NOT EXISTS %s_rollups_lookup_idx ON %s (metric_name, entity_id, tags_hash, resolution_nano, bucket_nano)`, s.cfg.TablePrefix, s.tables.rollups),
-		fmt.Sprintf(`CREATE INDEX IF NOT EXISTS %s_rollups_res_time_idx ON %s (metric_name, resolution_nano, bucket_nano)`, s.cfg.TablePrefix, s.tables.rollups),
+			id %s, metric_name VARCHAR(191) NOT NULL, entity_id VARCHAR(191) NOT NULL,
+			tags_hash VARCHAR(64) NOT NULL, tags %s NOT NULL,
+			UNIQUE(metric_name, entity_id, tags_hash),
+			FOREIGN KEY (metric_name) REFERENCES %s(name) ON DELETE CASCADE
+		)`, s.tables.series, pk, jsonType, s.tables.definitions),
+		fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (
+			id %s, resolution_milli BIGINT NOT NULL, UNIQUE(resolution_milli)
+		)`, s.tables.resolutions, pk),
+		fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (
+			series_id BIGINT NOT NULL, resolution_id BIGINT NOT NULL, label_id BIGINT NOT NULL, bucket_milli BIGINT NOT NULL,
+			count BIGINT NOT NULL, sum DOUBLE PRECISION NOT NULL, sum_sq DOUBLE PRECISION NOT NULL,
+			min_val DOUBLE PRECISION NOT NULL, max_val DOUBLE PRECISION NOT NULL,
+			first_val DOUBLE PRECISION NOT NULL, first_ts_milli BIGINT NOT NULL,
+			last_val DOUBLE PRECISION NOT NULL, last_ts_milli BIGINT NOT NULL,
+			digest %s, created_at_milli BIGINT NOT NULL,
+			UNIQUE(series_id, resolution_id, label_id, bucket_milli),
+			FOREIGN KEY (series_id) REFERENCES %s(id) ON DELETE CASCADE,
+			FOREIGN KEY (resolution_id) REFERENCES %s(id) ON DELETE CASCADE,
+			FOREIGN KEY (label_id) REFERENCES %s(id) ON DELETE CASCADE
+		)`, s.tables.rollups, d.blobType(), s.tables.series, s.tables.resolutions, s.tables.labels),
 	}
+}
 
+type normalizedIndex struct {
+	name    string
+	table   string
+	columns string
+}
+
+type sqlExecer interface {
+	ExecContext(context.Context, string, ...any) (sql.Result, error)
+}
+
+func (s *Store) normalizedIndexes() []normalizedIndex {
+	return normalizedIndexesFor(s.cfg.TablePrefix, s.tables)
+}
+
+func normalizedIndexesFor(prefix string, tables tables) []normalizedIndex {
+	return []normalizedIndex{
+		{name: prefix + "series_metric_entity_idx", table: tables.series, columns: "metric_name, entity_id"},
+		{name: prefix + "rollups_resolution_bucket_idx", table: tables.rollups, columns: "resolution_id, bucket_milli"},
+	}
+}
+
+func (s *Store) createNormalizedIndexes(ctx context.Context) error {
 	if s.cfg.Driver == DriverMySQL {
-		statements = []string{
-			fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (
-				name VARCHAR(191) PRIMARY KEY,
-				type VARCHAR(32) NOT NULL,
-				unit VARCHAR(64) NOT NULL DEFAULT '',
-				description TEXT NOT NULL,
-				retention_days INT NOT NULL DEFAULT 0,
-				metadata %s NOT NULL,
-				created_at BIGINT NOT NULL,
-				updated_at BIGINT NOT NULL
-			) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`, s.tables.definitions, jsonType),
-			fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (
-				id %s,
-				metric_name VARCHAR(191) NOT NULL,
-				entity_id VARCHAR(191) NOT NULL,
-				tags_hash VARCHAR(64) NOT NULL,
-				ts_nano BIGINT NOT NULL,
-				value DOUBLE NOT NULL,
-				tags %s NOT NULL,
-				labels %s NOT NULL,
-				created_at BIGINT NOT NULL,
-				UNIQUE KEY uq_metric_entity_time (metric_name, entity_id, tags_hash, ts_nano),
-				INDEX idx_metric_entity_time (metric_name, entity_id, ts_nano),
-				INDEX idx_metric_time (metric_name, ts_nano),
-				INDEX idx_entity_time (entity_id, ts_nano)
-			) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`, s.tables.points, pk, jsonType, jsonType),
-			fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (
-				id %s,
-				metric_name VARCHAR(191) NOT NULL,
-				entity_id VARCHAR(191) NOT NULL,
-				tags_hash VARCHAR(64) NOT NULL,
-				tags %s NOT NULL,
-				resolution_nano BIGINT NOT NULL,
-				bucket_nano BIGINT NOT NULL,
-				count BIGINT NOT NULL,
-				sum DOUBLE NOT NULL,
-				sum_sq DOUBLE NOT NULL,
-				min_val DOUBLE NOT NULL,
-				max_val DOUBLE NOT NULL,
-				first_val DOUBLE NOT NULL,
-				first_ts BIGINT NOT NULL,
-				last_val DOUBLE NOT NULL,
-				last_ts BIGINT NOT NULL,
-				digest %s,
-				created_at BIGINT NOT NULL,
-				UNIQUE KEY uq_rollup (metric_name, entity_id, tags_hash, resolution_nano, bucket_nano),
-				INDEX idx_rollup_res_time (metric_name, resolution_nano, bucket_nano)
-			) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`, s.tables.rollups, pk, jsonType, blob),
+		for _, index := range s.normalizedIndexes() {
+			exists, err := s.mysqlIndexExists(ctx, index.table, index.name)
+			if err != nil {
+				return err
+			}
+			if exists {
+				continue
+			}
+			if _, err := s.db.ExecContext(ctx, fmt.Sprintf("CREATE INDEX %s ON %s (%s)", index.name, index.table, index.columns)); err != nil {
+				return err
+			}
 		}
+		return nil
 	}
+	return s.createPortableNormalizedIndexes(ctx, s.db)
+}
 
-	if s.cfg.Driver == DriverPostgreSQL {
-		statements = []string{
-			fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (
-				name VARCHAR(191) PRIMARY KEY,
-				type VARCHAR(32) NOT NULL,
-				unit VARCHAR(64) NOT NULL DEFAULT '',
-				description TEXT NOT NULL DEFAULT '',
-				retention_days INTEGER NOT NULL DEFAULT 0,
-				metadata %s NOT NULL,
-				created_at BIGINT NOT NULL,
-				updated_at BIGINT NOT NULL
-			)`, s.tables.definitions, jsonType),
-			fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (
-				id %s,
-				metric_name VARCHAR(191) NOT NULL,
-				entity_id VARCHAR(191) NOT NULL,
-				tags_hash VARCHAR(64) NOT NULL,
-				ts_nano BIGINT NOT NULL,
-				value DOUBLE PRECISION NOT NULL,
-				tags %s NOT NULL,
-				labels %s NOT NULL,
-				created_at BIGINT NOT NULL,
-				UNIQUE(metric_name, entity_id, tags_hash, ts_nano)
-			)`, s.tables.points, pk, jsonType, jsonType),
-			fmt.Sprintf(`CREATE INDEX IF NOT EXISTS %s_points_metric_entity_time_idx ON %s (metric_name, entity_id, ts_nano)`, s.cfg.TablePrefix, s.tables.points),
-			fmt.Sprintf(`CREATE INDEX IF NOT EXISTS %s_points_metric_time_idx ON %s (metric_name, ts_nano)`, s.cfg.TablePrefix, s.tables.points),
-			fmt.Sprintf(`CREATE INDEX IF NOT EXISTS %s_points_entity_time_idx ON %s (entity_id, ts_nano)`, s.cfg.TablePrefix, s.tables.points),
-			fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (
-				id %s,
-				metric_name VARCHAR(191) NOT NULL,
-				entity_id VARCHAR(191) NOT NULL,
-				tags_hash VARCHAR(64) NOT NULL,
-				tags %s NOT NULL,
-				resolution_nano BIGINT NOT NULL,
-				bucket_nano BIGINT NOT NULL,
-				count BIGINT NOT NULL,
-				sum DOUBLE PRECISION NOT NULL,
-				sum_sq DOUBLE PRECISION NOT NULL,
-				min_val DOUBLE PRECISION NOT NULL,
-				max_val DOUBLE PRECISION NOT NULL,
-				first_val DOUBLE PRECISION NOT NULL,
-				first_ts BIGINT NOT NULL,
-				last_val DOUBLE PRECISION NOT NULL,
-				last_ts BIGINT NOT NULL,
-				digest %s,
-				created_at BIGINT NOT NULL,
-				UNIQUE(metric_name, entity_id, tags_hash, resolution_nano, bucket_nano)
-			)`, s.tables.rollups, pk, jsonType, blob),
-			fmt.Sprintf(`CREATE INDEX IF NOT EXISTS %s_rollups_lookup_idx ON %s (metric_name, entity_id, tags_hash, resolution_nano, bucket_nano)`, s.cfg.TablePrefix, s.tables.rollups),
-			fmt.Sprintf(`CREATE INDEX IF NOT EXISTS %s_rollups_res_time_idx ON %s (metric_name, resolution_nano, bucket_nano)`, s.cfg.TablePrefix, s.tables.rollups),
-		}
-	}
-
-	for _, stmt := range statements {
-		if _, err := s.db.ExecContext(ctx, stmt); err != nil {
+func (s *Store) createPortableNormalizedIndexes(ctx context.Context, exec sqlExecer) error {
+	for _, index := range s.normalizedIndexes() {
+		if _, err := exec.ExecContext(ctx, fmt.Sprintf("CREATE INDEX IF NOT EXISTS %s ON %s (%s)", index.name, index.table, index.columns)); err != nil {
 			return err
 		}
 	}
 	return nil
 }
+
+func (s *Store) dropNormalizedIndexes(ctx context.Context) error {
+	for _, index := range s.normalizedIndexes() {
+		if s.cfg.Driver == DriverMySQL {
+			exists, err := s.mysqlIndexExists(ctx, index.table, index.name)
+			if err != nil {
+				return err
+			}
+			if exists {
+				if _, err := s.db.ExecContext(ctx, fmt.Sprintf("ALTER TABLE %s DROP INDEX %s", index.table, index.name)); err != nil {
+					return err
+				}
+			}
+			continue
+		}
+		if _, err := s.db.ExecContext(ctx, "DROP INDEX IF EXISTS "+index.name); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (s *Store) mysqlIndexExists(ctx context.Context, table, index string) (bool, error) {
+	var found int
+	err := s.db.QueryRowContext(ctx, `SELECT 1 FROM information_schema.STATISTICS
+		WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND INDEX_NAME = ? LIMIT 1`, table, index).Scan(&found)
+	if err == sql.ErrNoRows {
+		return false, nil
+	}
+	if err != nil {
+		return false, err
+	}
+	return true, nil
+}

pkg/metric/migrations_test.go

@@ -0,0 +1,120 @@
+package metric
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+)
+
+type sqliteForeignKey struct {
+	table    string
+	from     string
+	to       string
+	onDelete string
+}
+
+func TestNormalizedSchemaDeclaresPortableForeignKeys(t *testing.T) {
+	for _, driver := range []Driver{DriverSQLite, DriverMySQL, DriverPostgreSQL} {
+		t.Run(string(driver), func(t *testing.T) {
+			s := schemaTestStore(driver, "er_")
+			ddl := strings.Join(s.normalizedSchemaStatements(), "\n")
+			for _, clause := range []string{
+				"FOREIGN KEY (metric_name) REFERENCES er_definitions(name) ON DELETE CASCADE",
+				"FOREIGN KEY (series_id) REFERENCES er_series(id) ON DELETE CASCADE",
+				"FOREIGN KEY (resolution_id) REFERENCES er_resolutions(id) ON DELETE CASCADE",
+				"FOREIGN KEY (label_id) REFERENCES er_label_sets(id) ON DELETE CASCADE",
+			} {
+				if !strings.Contains(ddl, clause) {
+					t.Fatalf("%s schema is missing %q:\n%s", driver, clause, ddl)
+				}
+			}
+		})
+	}
+}
+
+func TestSQLiteSchemaExposesERRelationships(t *testing.T) {
+	ctx := context.Background()
+	store := newMemStore(t)
+
+	var enabled int
+	if err := store.db.QueryRowContext(ctx, "PRAGMA foreign_keys").Scan(&enabled); err != nil {
+		t.Fatalf("query foreign key enforcement: %v", err)
+	}
+	if enabled != 1 {
+		t.Fatalf("foreign key enforcement = %d, want 1", enabled)
+	}
+
+	want := map[string]sqliteForeignKey{
+		"metric_name":   {table: store.tables.definitions, from: "metric_name", to: "name", onDelete: "CASCADE"},
+		"series_id":     {table: store.tables.series, from: "series_id", to: "id", onDelete: "CASCADE"},
+		"resolution_id": {table: store.tables.resolutions, from: "resolution_id", to: "id", onDelete: "CASCADE"},
+		"label_id":      {table: store.tables.labels, from: "label_id", to: "id", onDelete: "CASCADE"},
+	}
+	got := make(map[string]sqliteForeignKey)
+	for _, table := range []string{store.tables.series, store.tables.rollups} {
+		rows, err := store.db.QueryContext(ctx, "PRAGMA foreign_key_list("+table+")")
+		if err != nil {
+			t.Fatalf("list foreign keys for %s: %v", table, err)
+		}
+		for rows.Next() {
+			var id, seq int
+			var fk sqliteForeignKey
+			var onUpdate, match string
+			if err := rows.Scan(&id, &seq, &fk.table, &fk.from, &fk.to, &onUpdate, &fk.onDelete, &match); err != nil {
+				_ = rows.Close()
+				t.Fatalf("scan foreign key for %s: %v", table, err)
+			}
+			got[fk.from] = fk
+		}
+		if err := rows.Close(); err != nil {
+			t.Fatalf("close foreign key rows for %s: %v", table, err)
+		}
+	}
+	if len(got) != len(want) {
+		t.Fatalf("foreign keys = %#v, want %#v", got, want)
+	}
+	for column, expected := range want {
+		if actual := got[column]; actual != expected {
+			t.Fatalf("foreign key for %s = %#v, want %#v", column, actual, expected)
+		}
+	}
+
+	if err := store.CreateMetric(ctx, Definition{Name: "cascade", Type: TypeGauge, RetentionDays: 1}); err != nil {
+		t.Fatalf("create metric: %v", err)
+	}
+	at := time.Now().UTC().Truncate(time.Minute).Add(-2 * time.Minute)
+	if err := store.WriteBatch(ctx, []Point{{MetricName: "cascade", EntityID: "node-1", Timestamp: at, Value: 1}}); err != nil {
+		t.Fatalf("write metric: %v", err)
+	}
+	if err := store.flushAllHotRollups(ctx); err != nil {
+		t.Fatalf("flush rollup: %v", err)
+	}
+	if _, err := store.db.ExecContext(ctx, fmt.Sprintf("DELETE FROM %s WHERE name = ?", store.tables.definitions), "cascade"); err != nil {
+		t.Fatalf("delete definition: %v", err)
+	}
+	for _, table := range []string{store.tables.series, store.tables.rollups} {
+		var count int
+		if err := store.db.QueryRowContext(ctx, "SELECT COUNT(*) FROM "+table).Scan(&count); err != nil {
+			t.Fatalf("count %s after cascade: %v", table, err)
+		}
+		if count != 0 {
+			t.Fatalf("%s rows after cascade = %d, want 0", table, count)
+		}
+	}
+}
+
+func schemaTestStore(driver Driver, prefix string) *Store {
+	return &Store{
+		cfg:     Config{Driver: driver, TablePrefix: prefix},
+		dialect: newDialect(driver),
+		tables: tables{
+			definitions: prefix + "definitions",
+			series:      prefix + "series",
+			labels:      prefix + "label_sets",
+			resolutions: prefix + "resolutions",
+			rollups:     prefix + "rollups",
+		},
+	}
+}

pkg/metric/normalized_rollup.go

@@ -0,0 +1,223 @@
+package metric
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"time"
+)
+
+const normalizedRollupColumns = "(series_id, resolution_id, label_id, bucket_milli, count, sum, sum_sq, min_val, max_val, first_val, first_ts_milli, last_val, last_ts_milli, digest, created_at_milli)"
+
+type normalizedRollupRow struct {
+	seriesID       int64
+	resolutionID   int64
+	labelID        int64
+	bucketMilli    int64
+	count          int64
+	sum            float64
+	sumSq          float64
+	min            float64
+	max            float64
+	firstVal       float64
+	firstTSMilli   int64
+	lastVal        float64
+	lastTSMilli    int64
+	digest         []byte
+	createdAtMilli int64
+}
+
+// rollupDictionaryCache is scoped to one write transaction. It avoids repeated
+// dictionary lookups across buckets and tiers without retaining every series
+// id for the lifetime of the Store.
+type rollupDictionaryCache struct {
+	series      map[string]int64
+	labels      map[string]int64
+	resolutions map[int64]int64
+}
+
+func newRollupDictionaryCache() *rollupDictionaryCache {
+	return &rollupDictionaryCache{
+		series:      make(map[string]int64),
+		labels:      make(map[string]int64),
+		resolutions: make(map[int64]int64),
+	}
+}
+
+func (c *rollupDictionaryCache) seriesID(ctx context.Context, s *Store, tx *sql.Tx, metricName string, key rollupKey, tagsJSON string) (int64, error) {
+	cacheKey := metricName + "\x00" + key.entityID + "\x00" + key.tagsHash
+	if id, ok := c.series[cacheKey]; ok {
+		return id, nil
+	}
+	id, err := s.internSeriesTx(ctx, metricName, key.entityID, key.tagsHash, tagsJSON, tx)
+	if err == nil {
+		c.series[cacheKey] = id
+	}
+	return id, err
+}
+
+func (c *rollupDictionaryCache) labelID(ctx context.Context, s *Store, tx *sql.Tx, hash, labelsJSON string) (int64, error) {
+	if id, ok := c.labels[hash]; ok {
+		return id, nil
+	}
+	id, err := s.internLabelsTx(ctx, hash, labelsJSON, tx)
+	if err == nil {
+		c.labels[hash] = id
+	}
+	return id, err
+}
+
+func (c *rollupDictionaryCache) resolutionID(ctx context.Context, s *Store, tx *sql.Tx, interval time.Duration) (int64, error) {
+	milli := interval.Milliseconds()
+	if id, ok := c.resolutions[milli]; ok {
+		return id, nil
+	}
+	id, err := s.internResolutionTx(ctx, interval, tx)
+	if err == nil {
+		c.resolutions[milli] = id
+	}
+	return id, err
+}
+
+func (s *Store) insertIgnoreSQL(table, columns, values string) string {
+	switch s.cfg.Driver {
+	case DriverMySQL:
+		return fmt.Sprintf("INSERT IGNORE INTO %s %s VALUES %s", table, columns, values)
+	case DriverPostgreSQL:
+		return fmt.Sprintf("INSERT INTO %s %s VALUES %s ON CONFLICT DO NOTHING", table, columns, values)
+	default:
+		return fmt.Sprintf("INSERT OR IGNORE INTO %s %s VALUES %s", table, columns, values)
+	}
+}
+
+// internSeriesTx stores the immutable name/entity/tag tuple once. Labels are
+// intentionally not part of this dictionary: a label set is independently
+// interned and referenced by each rollup row.
+func (s *Store) internSeriesTx(ctx context.Context, metricName, entityID, tagsHash, tagsJSON string, tx *sql.Tx) (int64, error) {
+	if tagsJSON == "" {
+		tagsJSON = "{}"
+	}
+	var id int64
+	lookup := fmt.Sprintf(
+		"SELECT id FROM %s WHERE metric_name = %s AND entity_id = %s AND tags_hash = %s",
+		s.tables.series, s.dialect.placeholder(1), s.dialect.placeholder(2), s.dialect.placeholder(3),
+	)
+	if err := tx.QueryRowContext(ctx, lookup, metricName, entityID, tagsHash).Scan(&id); err == nil {
+		return id, nil
+	} else if err != sql.ErrNoRows {
+		return 0, err
+	}
+	if _, err := tx.ExecContext(ctx,
+		s.insertIgnoreSQL(s.tables.series, "(metric_name, entity_id, tags_hash, tags)",
+			"("+joinSQL([]string{s.dialect.placeholder(1), s.dialect.placeholder(2), s.dialect.placeholder(3), s.dialect.jsonPlaceholder(4)})+")"),
+		metricName, entityID, tagsHash, tagsJSON,
+	); err != nil {
+		return 0, err
+	}
+	err := tx.QueryRowContext(ctx, lookup, metricName, entityID, tagsHash).Scan(&id)
+	return id, err
+}
+
+func (s *Store) internLabelsTx(ctx context.Context, labelsHash, labelsJSON string, tx *sql.Tx) (int64, error) {
+	if labelsJSON == "" {
+		labelsJSON = "{}"
+	}
+	var id int64
+	lookup := fmt.Sprintf("SELECT id FROM %s WHERE labels_hash = %s", s.tables.labels, s.dialect.placeholder(1))
+	if err := tx.QueryRowContext(ctx, lookup, labelsHash).Scan(&id); err == nil {
+		return id, nil
+	} else if err != sql.ErrNoRows {
+		return 0, err
+	}
+	if _, err := tx.ExecContext(ctx, s.insertIgnoreSQL(s.tables.labels, "(labels_hash, labels)", "("+s.dialect.placeholder(1)+", "+s.dialect.jsonPlaceholder(2)+")"), labelsHash, labelsJSON); err != nil {
+		return 0, err
+	}
+	err := tx.QueryRowContext(ctx, lookup, labelsHash).Scan(&id)
+	return id, err
+}
+
+func (s *Store) internResolutionTx(ctx context.Context, interval time.Duration, tx *sql.Tx) (int64, error) {
+	milli := interval.Milliseconds()
+	var id int64
+	lookup := fmt.Sprintf("SELECT id FROM %s WHERE resolution_milli = %s", s.tables.resolutions, s.dialect.placeholder(1))
+	if err := tx.QueryRowContext(ctx, lookup, milli).Scan(&id); err == nil {
+		return id, nil
+	} else if err != sql.ErrNoRows {
+		return 0, err
+	}
+	if _, err := tx.ExecContext(ctx, s.insertIgnoreSQL(s.tables.resolutions, "(resolution_milli)", "("+s.dialect.placeholder(1)+")"), milli); err != nil {
+		return 0, err
+	}
+	err := tx.QueryRowContext(ctx, lookup, milli).Scan(&id)
+	return id, err
+}
+
+func joinSQL(parts []string) string {
+	if len(parts) == 0 {
+		return ""
+	}
+	out := parts[0]
+	for _, part := range parts[1:] {
+		out += ", " + part
+	}
+	return out
+}
+
+func (s *Store) normalizedRollupUpsertSuffix() string {
+	switch s.cfg.Driver {
+	case DriverMySQL:
+		return " ON DUPLICATE KEY UPDATE count=VALUES(count), sum=VALUES(sum), sum_sq=VALUES(sum_sq), min_val=VALUES(min_val), max_val=VALUES(max_val), first_val=VALUES(first_val), first_ts_milli=VALUES(first_ts_milli), last_val=VALUES(last_val), last_ts_milli=VALUES(last_ts_milli), digest=VALUES(digest), created_at_milli=VALUES(created_at_milli)"
+	case DriverPostgreSQL:
+		return " ON CONFLICT(series_id, resolution_id, label_id, bucket_milli) DO UPDATE SET count=EXCLUDED.count, sum=EXCLUDED.sum, sum_sq=EXCLUDED.sum_sq, min_val=EXCLUDED.min_val, max_val=EXCLUDED.max_val, first_val=EXCLUDED.first_val, first_ts_milli=EXCLUDED.first_ts_milli, last_val=EXCLUDED.last_val, last_ts_milli=EXCLUDED.last_ts_milli, digest=EXCLUDED.digest, created_at_milli=EXCLUDED.created_at_milli"
+	default:
+		return " ON CONFLICT(series_id, resolution_id, label_id, bucket_milli) DO UPDATE SET count=excluded.count, sum=excluded.sum, sum_sq=excluded.sum_sq, min_val=excluded.min_val, max_val=excluded.max_val, first_val=excluded.first_val, first_ts_milli=excluded.first_ts_milli, last_val=excluded.last_val, last_ts_milli=excluded.last_ts_milli, digest=excluded.digest, created_at_milli=excluded.created_at_milli"
+	}
+}
+
+func (s *Store) upsertNormalizedRollupRowsTx(ctx context.Context, rows []normalizedRollupRow, tx *sql.Tx) error {
+	if len(rows) == 0 {
+		return nil
+	}
+	valueGroups := make([]string, 0, len(rows))
+	args := make([]any, 0, len(rows)*15)
+	placeholder := 1
+	for _, row := range rows {
+		values := make([]string, 15)
+		for i := range values {
+			values[i] = s.dialect.placeholder(placeholder)
+			placeholder++
+		}
+		valueGroups = append(valueGroups, "("+joinSQL(values)+")")
+		args = append(args,
+			row.seriesID, row.resolutionID, row.labelID, row.bucketMilli,
+			row.count, row.sum, row.sumSq, row.min, row.max,
+			row.firstVal, row.firstTSMilli, row.lastVal, row.lastTSMilli,
+			row.digest, row.createdAtMilli,
+		)
+	}
+	_, err := tx.ExecContext(ctx, fmt.Sprintf("INSERT INTO %s %s VALUES %s%s",
+		s.tables.rollups, normalizedRollupColumns, joinSQL(valueGroups), s.normalizedRollupUpsertSuffix()), args...)
+	return err
+}
+
+func (s *Store) upsertRollupWithDictionaryTx(ctx context.Context, metricName string, interval time.Duration, key rollupKey, bucket *rollupBucket, cache *rollupDictionaryCache, tx *sql.Tx) error {
+	seriesID, err := cache.seriesID(ctx, s, tx, metricName, key, bucket.tagsJSON)
+	if err != nil {
+		return err
+	}
+	labelID, err := cache.labelID(ctx, s, tx, key.labelsHash, bucket.labelsJSON)
+	if err != nil {
+		return err
+	}
+	resolutionID, err := cache.resolutionID(ctx, s, tx, interval)
+	if err != nil {
+		return err
+	}
+	return s.upsertNormalizedRollupRowsTx(ctx, []normalizedRollupRow{{
+		seriesID: seriesID, resolutionID: resolutionID, labelID: labelID,
+		bucketMilli: key.bucket, count: bucket.count, sum: bucket.sum, sumSq: bucket.sumSq,
+		min: bucket.min, max: bucket.max, firstVal: bucket.firstVal, firstTSMilli: bucket.firstTS,
+		lastVal: bucket.lastVal, lastTSMilli: bucket.lastTS, digest: bucket.encodedDigest(),
+		createdAtMilli: timeMillis(time.Now()),
+	}}, tx)
+}

pkg/metric/postgres_integration_test.go

@@ -19,6 +19,7 @@ func TestPostgreSQLIntegration(t *testing.T) {
 	}
 
 	runSQLIntegration(t, "postgres", PostgreSQL(dsn), true)
+	runSQLRestructureIntegration(t, "postgres", PostgreSQL(dsn))
 }
 
 // TestMySQLIntegration runs the MySQL integration test when configured.
@@ -31,6 +32,7 @@ func TestMySQLIntegration(t *testing.T) {
 	}
 
 	runSQLIntegration(t, "mysql", MySQL(dsn), false)
+	runSQLRestructureIntegration(t, "mysql", MySQL(dsn))
 }
 
 // runSQLIntegration exercises the SQL store against an external database.
@@ -39,10 +41,14 @@ func TestMySQLIntegration(t *testing.T) {
 func runSQLIntegration(t *testing.T, name string, cfg Config, expectSQLPercentile bool) {
 	t.Helper()
 
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	ctx, cancel := context.WithTimeout(context.Background(), 6*time.Minute)
 	defer cancel()
 
-	prefix := fmt.Sprintf("it_%d_", time.Now().UnixNano())
+	prefixBase := "it"
+	if cfg.Driver == DriverPostgreSQL {
+		prefixBase = "IT"
+	}
+	prefix := fmt.Sprintf("%s_%d_", prefixBase, time.Now().UnixNano())
 	cfg.TablePrefix = prefix
 	store, err := Open(ctx, cfg)
 	if err != nil {
@@ -50,20 +56,21 @@ func runSQLIntegration(t *testing.T, name string, cfg Config, expectSQLPercentil
 	}
 	defer store.Close()
 	defer dropIntegrationTables(t, store, prefix)
+	assertIntegrationForeignKeys(t, store)
 
 	if err := store.CreateMetric(ctx, Definition{
-		Name:        "http.latency",
-		Type:        TypeGauge,
-		Unit:        "ms",
-		Description: "HTTP latency",
-		Metadata:    map[string]string{"source": "integration"},
-	}); err != nil {
+		Name:          "http.latency",
+		Type:          TypeGauge,
+		Unit:          "ms",
+		Description:   "HTTP latency",
+		Metadata:      map[string]string{"source": "integration"},
+		RetentionDays: 30}); err != nil {
 		t.Fatalf("create metric: %v", err)
 	}
-	if err := store.CreateMetric(ctx, Definition{Name: "http.latency", Type: TypeGauge}); err == nil {
+	if err := store.CreateMetric(ctx, Definition{Name: "http.latency", Type: TypeGauge, RetentionDays: 30}); err == nil {
 		t.Fatalf("duplicate CreateMetric should fail")
 	}
-	if err := store.UpsertMetric(ctx, Definition{Name: "http.latency", Type: TypeGauge, Unit: "milliseconds"}); err != nil {
+	if err := store.UpsertMetric(ctx, Definition{Name: "http.latency", Type: TypeGauge, Unit: "milliseconds", RetentionDays: 30}); err != nil {
 		t.Fatalf("upsert metric: %v", err)
 	}
 	def, err := store.GetMetric(ctx, "http.latency")
@@ -74,12 +81,16 @@ func runSQLIntegration(t *testing.T, name string, cfg Config, expectSQLPercentil
 		t.Fatalf("upsert did not update unit: %#v", def)
 	}
 
-	base := time.Date(2026, 6, 20, 1, 0, 0, 0, time.UTC)
+	now := time.Now().UTC()
+	base := now.Truncate(time.Minute)
+	if elapsed := now.Sub(base); elapsed < time.Second {
+		time.Sleep(time.Second - elapsed)
+	}
 	points := []Point{
 		{MetricName: "http.latency", EntityID: "api-1", Timestamp: base, Value: 10, Tags: map[string]string{"region.zone": "ap-1", "route-name": "/v1/nodes"}},
-		{MetricName: "http.latency", EntityID: "api-1", Timestamp: base.Add(time.Minute), Value: 20, Tags: map[string]string{"region.zone": "ap-1", "route-name": "/v1/nodes"}},
-		{MetricName: "http.latency", EntityID: "api-1", Timestamp: base.Add(2 * time.Minute), Value: 30, Tags: map[string]string{"region.zone": "ap-1", "route-name": "/v1/nodes"}},
-		{MetricName: "http.latency", EntityID: "api-1", Timestamp: base.Add(3 * time.Minute), Value: 40, Tags: map[string]string{"region.zone": "eu-1", "route-name": "/v1/nodes"}},
+		{MetricName: "http.latency", EntityID: "api-1", Timestamp: base.Add(100 * time.Millisecond), Value: 20, Tags: map[string]string{"region.zone": "ap-1", "route-name": "/v1/nodes"}},
+		{MetricName: "http.latency", EntityID: "api-1", Timestamp: base.Add(200 * time.Millisecond), Value: 30, Tags: map[string]string{"region.zone": "ap-1", "route-name": "/v1/nodes"}},
+		{MetricName: "http.latency", EntityID: "api-1", Timestamp: base.Add(300 * time.Millisecond), Value: 40, Tags: map[string]string{"region.zone": "eu-1", "route-name": "/v1/nodes"}},
 	}
 	if err := store.WriteBatch(ctx, points); err != nil {
 		t.Fatalf("write batch: %v", err)
@@ -89,7 +100,7 @@ func runSQLIntegration(t *testing.T, name string, cfg Config, expectSQLPercentil
 		MetricName: "http.latency",
 		EntityID:   "api-1",
 		Start:      base.Add(-time.Second),
-		End:        base.Add(5 * time.Minute),
+		End:        base.Add(time.Second),
 		Tags:       map[string]string{"region.zone": "ap-1", "route-name": "/v1/nodes"},
 	})
 	if err != nil {
@@ -103,7 +114,7 @@ func runSQLIntegration(t *testing.T, name string, cfg Config, expectSQLPercentil
 		MetricName: "http.latency",
 		EntityID:   "api-1",
 		Start:      base,
-		End:        base.Add(5 * time.Minute),
+		End:        base.Add(time.Second),
 	})
 	if err != nil {
 		t.Fatalf("stats: %v", err)
@@ -117,17 +128,18 @@ func runSQLIntegration(t *testing.T, name string, cfg Config, expectSQLPercentil
 			MetricName: "http.latency",
 			EntityID:   "api-1",
 			Start:      base,
-			End:        base.Add(5 * time.Minute),
+			End:        base.Add(time.Second),
+			Tags:       map[string]string{"region.zone": "ap-1"},
 		},
 		Aggregation:  AggAvg,
-		Interval:     2 * time.Minute,
+		Interval:     200 * time.Millisecond,
 		BucketLimit:  1,
 		BucketOffset: 1,
 	})
 	if err != nil {
 		t.Fatalf("avg aggregate: %v", err)
 	}
-	if len(avgBuckets) != 1 || avgBuckets[0].Value != 35 || avgBuckets[0].Count != 2 {
+	if len(avgBuckets) != 1 || avgBuckets[0].Value != 30 || avgBuckets[0].Count != 1 {
 		t.Fatalf("unexpected bucket-paged avg aggregate: %#v", avgBuckets)
 	}
 
@@ -136,7 +148,8 @@ func runSQLIntegration(t *testing.T, name string, cfg Config, expectSQLPercentil
 			MetricName: "http.latency",
 			EntityID:   "api-1",
 			Start:      base,
-			End:        base.Add(5 * time.Minute),
+			End:        base.Add(time.Second),
+			Tags:       map[string]string{"region.zone": "ap-1"},
 		},
 		Aggregation: AggP95,
 		Interval:    10 * time.Minute,
@@ -144,7 +157,7 @@ func runSQLIntegration(t *testing.T, name string, cfg Config, expectSQLPercentil
 	if err != nil {
 		t.Fatalf("p95 aggregate: %v", err)
 	}
-	if len(p95Buckets) != 1 || p95Buckets[0].Count != 4 || p95Buckets[0].Value <= 38 {
+	if len(p95Buckets) != 1 || p95Buckets[0].Count != 3 || p95Buckets[0].Value <= 28 {
 		t.Fatalf("unexpected p95 aggregate: %#v", p95Buckets)
 	}
 	if _, ok := sqlAggValueExpr(cfg.Driver, AggP95); ok != expectSQLPercentile {
@@ -158,8 +171,26 @@ func runSQLIntegration(t *testing.T, name string, cfg Config, expectSQLPercentil
 	if len(latest) != 1 || latest[0].Value != 40 {
 		t.Fatalf("unexpected latest point: %#v", latest)
 	}
+	if err := store.flushAllHotRollups(ctx); err != nil {
+		t.Fatalf("flush rollups: %v", err)
+	}
+	var transferred []PersistedRollup
+	total, err := store.ExportRollups(ctx, "http.latency", 2, func(batch []PersistedRollup) error {
+		transferred = append(transferred, batch...)
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("export rollups: %v", err)
+	}
+	if total == 0 || total != int64(len(transferred)) {
+		t.Fatalf("exported rollups = %d, buffered %d", total, len(transferred))
+	}
+	if err := store.ImportRollups(ctx, transferred); err != nil {
+		t.Fatalf("idempotently import exported rollups: %v", err)
+	}
+	assertIntegrationLateReplacement(t, ctx, store)
 
-	deleted, err := store.DeleteBefore(ctx, "http.latency", base.Add(2*time.Minute))
+	deleted, err := store.DeleteBefore(ctx, "http.latency", base.Add(200*time.Millisecond))
 	if err != nil {
 		t.Fatalf("delete before: %v", err)
 	}
@@ -180,6 +211,319 @@ func runSQLIntegration(t *testing.T, name string, cfg Config, expectSQLPercentil
 	if err := store.Ping(ctx); err != nil {
 		t.Fatalf("store unusable after space reclaim: %v", err)
 	}
+	discarded, err := store.DiscardHistory(ctx, nil)
+	if err != nil {
+		t.Fatalf("discard %s history: %v", name, err)
+	}
+	if discarded.Metrics != 2 || discarded.RowsCopied == 0 {
+		t.Fatalf("discard %s result = %#v", name, discarded)
+	}
+	if needs, err := store.NeedsRestructure(ctx); err != nil || needs {
+		t.Fatalf("discarded %s store needs restructure: needs=%v err=%v", name, needs, err)
+	}
+	if _, err := store.GetMetric(ctx, "http.latency"); err != nil {
+		t.Fatalf("discard removed %s definition: %v", name, err)
+	}
+	if err := store.Write(ctx, Point{MetricName: "http.latency", EntityID: "api-1", Timestamp: time.Now().UTC(), Value: 50}); err != nil {
+		t.Fatalf("write after %s discard: %v", name, err)
+	}
+}
+
+func assertIntegrationLateReplacement(t *testing.T, ctx context.Context, store *Store) {
+	t.Helper()
+	const metricName = "late.replacement"
+	if err := store.CreateMetric(ctx, Definition{Name: metricName, Type: TypeGauge, RetentionDays: 30}); err != nil {
+		t.Fatalf("create replacement metric: %v", err)
+	}
+	at := time.Now().UTC().Truncate(time.Minute).Add(-30 * time.Second)
+	for _, point := range []Point{
+		{MetricName: metricName, EntityID: "api-1", Timestamp: at, Value: 1, Labels: map[string]string{"source": "old"}},
+		{MetricName: metricName, EntityID: "api-1", Timestamp: at, Value: 7, Labels: map[string]string{"source": "new"}},
+	} {
+		if err := store.Write(ctx, point); err != nil {
+			t.Fatalf("write replacement point: %v", err)
+		}
+	}
+	for _, tier := range store.cfg.RollupPolicy.Tiers {
+		bucket := bucketStartMillis(at.UnixMilli(), tier.Interval.Milliseconds())
+		rows, err := store.scanRollupRowsBetween(ctx, metricName, "api-1", nil, tier.Interval.Milliseconds(), bucket, bucket, true)
+		if err != nil {
+			t.Fatalf("scan replacement %s tier: %v", tier.Interval, err)
+		}
+		if len(rows) != 1 || rows[0].bucketData.count != 1 || rows[0].bucketData.sum != 7 {
+			t.Fatalf("replacement %s tier = %#v, want one count=1 sum=7 row", tier.Interval, rows)
+		}
+		labels, err := decodeMapString(rows[0].bucketData.labelsJSON)
+		if err != nil || labels["source"] != "new" {
+			t.Fatalf("replacement %s labels = %#v, %v", tier.Interval, labels, err)
+		}
+	}
+}
+
+func runSQLRestructureIntegration(t *testing.T, name string, cfg Config) {
+	t.Helper()
+	ctx, cancel := context.WithTimeout(context.Background(), 6*time.Minute)
+	defer cancel()
+
+	prefixBase := "rit"
+	if cfg.Driver == DriverPostgreSQL {
+		prefixBase = "RIT"
+	}
+	prefix := fmt.Sprintf("%s_%d_", prefixBase, time.Now().UnixNano())
+	cfg.TablePrefix = prefix
+	cfg.AutoMigrate = false
+	store, err := Open(ctx, cfg)
+	if err != nil {
+		t.Fatalf("open legacy %s store: %v", name, err)
+	}
+	defer store.Close()
+	defer dropIntegrationTables(t, store, prefix)
+
+	d := store.dialect
+	legacyDDL := []string{
+		fmt.Sprintf(`CREATE TABLE %s (
+			name VARCHAR(191) PRIMARY KEY, type VARCHAR(32) NOT NULL, unit VARCHAR(64) NOT NULL,
+			description TEXT NOT NULL, retention_days INTEGER NOT NULL, metadata %s NOT NULL,
+			created_at BIGINT NOT NULL, updated_at BIGINT NOT NULL)`, store.tables.definitions, d.jsonType()),
+		fmt.Sprintf(`CREATE TABLE %s (
+			id BIGINT PRIMARY KEY, metric_name VARCHAR(191) NOT NULL, entity_id VARCHAR(191) NOT NULL,
+			tags_hash VARCHAR(64) NOT NULL, ts_nano BIGINT NOT NULL, value DOUBLE PRECISION NOT NULL,
+			tags %s NOT NULL, labels %s NOT NULL, created_at BIGINT NOT NULL)`, store.tables.points, d.jsonType(), d.jsonType()),
+		fmt.Sprintf(`CREATE TABLE %s (
+			id BIGINT PRIMARY KEY, metric_name VARCHAR(191) NOT NULL, entity_id VARCHAR(191) NOT NULL,
+			tags_hash VARCHAR(64) NOT NULL, tags %s NOT NULL, resolution_nano BIGINT NOT NULL,
+			bucket_nano BIGINT NOT NULL, count BIGINT NOT NULL, sum DOUBLE PRECISION NOT NULL,
+			sum_sq DOUBLE PRECISION NOT NULL, min_val DOUBLE PRECISION NOT NULL, max_val DOUBLE PRECISION NOT NULL,
+			first_val DOUBLE PRECISION NOT NULL, first_ts BIGINT NOT NULL, last_val DOUBLE PRECISION NOT NULL,
+			last_ts BIGINT NOT NULL, digest %s, created_at BIGINT NOT NULL)`, store.tables.rollups, d.jsonType(), d.blobType()),
+		fmt.Sprintf(`CREATE TABLE %s (metric_name VARCHAR(191) PRIMARY KEY, watermark_nano BIGINT NOT NULL, updated_at BIGINT NOT NULL)`, store.tables.watermarks),
+	}
+	for _, statement := range legacyDDL {
+		if _, err := store.db.ExecContext(ctx, statement); err != nil {
+			t.Fatalf("create legacy %s schema: %v", name, err)
+		}
+	}
+
+	at := time.Now().UTC().Truncate(time.Minute).Add(-2 * time.Minute)
+	created := at.UnixNano()
+	definitionSQL := fmt.Sprintf(`INSERT INTO %s
+		(name, type, unit, description, retention_days, metadata, created_at, updated_at)
+		VALUES (%s, %s, %s, %s, %s, %s, %s, %s)`, store.tables.definitions,
+		d.placeholder(1), d.placeholder(2), d.placeholder(3), d.placeholder(4),
+		d.placeholder(5), d.jsonPlaceholder(6), d.placeholder(7), d.placeholder(8))
+	if _, err := store.db.ExecContext(ctx, definitionSQL, "legacy.metric", TypeGauge, "ms", "legacy fixture", 30, "{}", created, created); err != nil {
+		t.Fatalf("seed legacy %s definition: %v", name, err)
+	}
+	tagsHash, tagsJSON, err := tagsFingerprint(map[string]string{"source": "legacy"})
+	if err != nil {
+		t.Fatalf("fingerprint legacy tags: %v", err)
+	}
+	pointSQL := fmt.Sprintf(`INSERT INTO %s
+		(id, metric_name, entity_id, tags_hash, ts_nano, value, tags, labels, created_at)
+		VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s)`, store.tables.points,
+		d.placeholder(1), d.placeholder(2), d.placeholder(3), d.placeholder(4), d.placeholder(5),
+		d.placeholder(6), d.jsonPlaceholder(7), d.jsonPlaceholder(8), d.placeholder(9))
+	for i, value := range []float64{10, 20} {
+		pointAt := at.Add(time.Duration(i) * 10 * time.Second)
+		if _, err := store.db.ExecContext(ctx, pointSQL, i+1, "legacy.metric", "node-1", tagsHash, pointAt.UnixNano(), value, tagsJSON, "{}", created); err != nil {
+			t.Fatalf("seed legacy %s point %d: %v", name, i, err)
+		}
+	}
+	hourAt := at.Add(-2 * time.Hour).Truncate(time.Hour)
+	rollupSQL := fmt.Sprintf(`INSERT INTO %s
+		(id, metric_name, entity_id, tags_hash, tags, resolution_nano, bucket_nano, count,
+		 sum, sum_sq, min_val, max_val, first_val, first_ts, last_val, last_ts, digest, created_at)
+		VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)`, store.tables.rollups,
+		d.placeholder(1), d.placeholder(2), d.placeholder(3), d.placeholder(4), d.jsonPlaceholder(5), d.placeholder(6),
+		d.placeholder(7), d.placeholder(8), d.placeholder(9), d.placeholder(10), d.placeholder(11), d.placeholder(12),
+		d.placeholder(13), d.placeholder(14), d.placeholder(15), d.placeholder(16), d.placeholder(17), d.placeholder(18))
+	if _, err := store.db.ExecContext(ctx, rollupSQL,
+		1, "legacy.metric", "node-1", tagsHash, tagsJSON, time.Hour.Nanoseconds(), hourAt.UnixNano(),
+		1, 7, 49, 7, 7, 7, hourAt.UnixNano(), 7, hourAt.UnixNano(), nil, created,
+	); err != nil {
+		t.Fatalf("seed legacy %s rollup: %v", name, err)
+	}
+
+	result, err := store.Restructure(ctx, nil)
+	if err != nil {
+		t.Fatalf("restructure legacy %s store: %v", name, err)
+	}
+	if result.RowsCopied != 3 || result.Metrics != 1 {
+		t.Fatalf("legacy %s restructure result = %#v", name, result)
+	}
+	if needs, err := store.NeedsRestructure(ctx); err != nil || needs {
+		t.Fatalf("legacy %s still needs restructure: needs=%v err=%v", name, needs, err)
+	}
+	if exists, err := store.tableExists(ctx, store.tables.points); err != nil || exists {
+		t.Fatalf("legacy %s points table remains: exists=%v err=%v", name, exists, err)
+	}
+	assertIntegrationForeignKeys(t, store)
+	minute, err := store.AggregateRollup(ctx, AggregateQuery{
+		Query:       Query{MetricName: "legacy.metric", EntityID: "node-1", Start: at.Add(-time.Minute), End: at.Add(time.Minute)},
+		Aggregation: AggAvg,
+		Interval:    time.Minute,
+	}, time.Minute)
+	if err != nil {
+		t.Fatalf("query restructured %s minute rollup: %v", name, err)
+	}
+	if len(minute) != 1 || minute[0].Count != 2 || minute[0].Value != 15 {
+		t.Fatalf("restructured %s minute rollup = %#v", name, minute)
+	}
+	dropIntegrationForeignKeys(t, ctx, store)
+	if needs, err := store.NeedsRestructure(ctx); err != nil || !needs {
+		t.Fatalf("%s schema without foreign keys needs repair: needs=%v err=%v", name, needs, err)
+	}
+	repaired, err := store.Restructure(ctx, nil)
+	if err != nil {
+		t.Fatalf("repair %s foreign keys: %v", name, err)
+	}
+	if repaired.RowsCopied == 0 || repaired.Metrics != 1 {
+		t.Fatalf("%s foreign-key repair result = %#v", name, repaired)
+	}
+	assertIntegrationForeignKeys(t, store)
+	minute, err = store.AggregateRollup(ctx, AggregateQuery{
+		Query:       Query{MetricName: "legacy.metric", EntityID: "node-1", Start: at.Add(-time.Minute), End: at.Add(time.Minute)},
+		Aggregation: AggAvg,
+		Interval:    time.Minute,
+	}, time.Minute)
+	if err != nil || len(minute) != 1 || minute[0].Count != 2 || minute[0].Value != 15 {
+		t.Fatalf("%s rollup after foreign-key repair = %#v, err=%v", name, minute, err)
+	}
+	if store.cfg.Driver == DriverMySQL {
+		renameIntegrationIndexesToRebuild(t, ctx, store)
+		backup := store.tables.definitions + "_legacy"
+		if _, err := store.db.ExecContext(ctx, fmt.Sprintf("CREATE TABLE %s LIKE %s", backup, store.tables.definitions)); err != nil {
+			t.Fatalf("create interrupted MySQL backup: %v", err)
+		}
+		if needs, err := store.NeedsRestructure(ctx); err != nil || !needs {
+			t.Fatalf("interrupted MySQL backup needs cleanup: needs=%v err=%v", needs, err)
+		}
+		if _, err := store.Restructure(ctx, nil); err != nil {
+			t.Fatalf("clean interrupted MySQL backup: %v", err)
+		}
+		if exists, err := store.tableExists(ctx, backup); err != nil || exists {
+			t.Fatalf("interrupted MySQL backup remains: exists=%v err=%v", exists, err)
+		}
+		if needs, err := store.NeedsRestructure(ctx); err != nil || needs {
+			t.Fatalf("MySQL store still needs cleanup: needs=%v err=%v", needs, err)
+		}
+		assertMySQLCanonicalIndexes(t, ctx, store)
+	}
+}
+
+func renameIntegrationIndexesToRebuild(t *testing.T, ctx context.Context, store *Store) {
+	t.Helper()
+	current := store.normalizedIndexes()
+	rebuild := normalizedIndexesFor(store.cfg.TablePrefix+"rebuild_", store.tables)
+	for i := range current {
+		statement := fmt.Sprintf("ALTER TABLE %s RENAME INDEX %s TO %s",
+			current[i].table, current[i].name, rebuild[i].name)
+		if _, err := store.db.ExecContext(ctx, statement); err != nil {
+			t.Fatalf("simulate interrupted MySQL index switch: %v", err)
+		}
+	}
+}
+
+func assertMySQLCanonicalIndexes(t *testing.T, ctx context.Context, store *Store) {
+	t.Helper()
+	current := store.normalizedIndexes()
+	rebuild := normalizedIndexesFor(store.cfg.TablePrefix+"rebuild_", store.tables)
+	for i := range current {
+		canonicalExists, err := store.mysqlIndexExists(ctx, current[i].table, current[i].name)
+		if err != nil {
+			t.Fatalf("inspect canonical MySQL index %s: %v", current[i].name, err)
+		}
+		rebuildExists, err := store.mysqlIndexExists(ctx, current[i].table, rebuild[i].name)
+		if err != nil {
+			t.Fatalf("inspect rebuild MySQL index %s: %v", rebuild[i].name, err)
+		}
+		if !canonicalExists || rebuildExists {
+			t.Fatalf("MySQL index recovery for %s: canonical=%v rebuild=%v", current[i].table, canonicalExists, rebuildExists)
+		}
+	}
+}
+
+func dropIntegrationForeignKeys(t *testing.T, ctx context.Context, store *Store) {
+	t.Helper()
+	seriesTable, rollupsTable := store.tables.series, store.tables.rollups
+	var query string
+	switch store.cfg.Driver {
+	case DriverMySQL:
+		query = `SELECT TABLE_NAME, CONSTRAINT_NAME FROM information_schema.TABLE_CONSTRAINTS
+			WHERE CONSTRAINT_SCHEMA = DATABASE() AND CONSTRAINT_TYPE = 'FOREIGN KEY'
+			AND TABLE_NAME IN (?, ?)`
+	case DriverPostgreSQL:
+		seriesTable, rollupsTable = strings.ToLower(seriesTable), strings.ToLower(rollupsTable)
+		query = `SELECT table_name, constraint_name FROM information_schema.table_constraints
+			WHERE table_schema = current_schema() AND constraint_type = 'FOREIGN KEY'
+			AND table_name IN ($1, $2)`
+	default:
+		t.Fatalf("unexpected integration driver %q", store.cfg.Driver)
+	}
+	rows, err := store.db.QueryContext(ctx, query, seriesTable, rollupsTable)
+	if err != nil {
+		t.Fatalf("list %s foreign keys: %v", store.cfg.Driver, err)
+	}
+	type constraint struct{ table, name string }
+	constraints := make([]constraint, 0, 4)
+	for rows.Next() {
+		var item constraint
+		if err := rows.Scan(&item.table, &item.name); err != nil {
+			_ = rows.Close()
+			t.Fatalf("scan %s foreign key: %v", store.cfg.Driver, err)
+		}
+		constraints = append(constraints, item)
+	}
+	if err := rows.Err(); err != nil {
+		_ = rows.Close()
+		t.Fatalf("iterate %s foreign keys: %v", store.cfg.Driver, err)
+	}
+	if err := rows.Close(); err != nil {
+		t.Fatalf("close %s foreign keys: %v", store.cfg.Driver, err)
+	}
+	if len(constraints) != 4 {
+		t.Fatalf("%s foreign keys before removal = %d, want 4", store.cfg.Driver, len(constraints))
+	}
+	clause := "DROP CONSTRAINT"
+	if store.cfg.Driver == DriverMySQL {
+		clause = "DROP FOREIGN KEY"
+	}
+	for _, item := range constraints {
+		statement := fmt.Sprintf("ALTER TABLE %s %s %s",
+			quoteMaintenanceIdentifier(store.cfg.Driver, item.table), clause,
+			quoteMaintenanceIdentifier(store.cfg.Driver, item.name))
+		if _, err := store.db.ExecContext(ctx, statement); err != nil {
+			t.Fatalf("drop %s foreign key %s: %v", store.cfg.Driver, item.name, err)
+		}
+	}
+}
+
+func assertIntegrationForeignKeys(t *testing.T, store *Store) {
+	t.Helper()
+	var query string
+	switch store.cfg.Driver {
+	case DriverMySQL:
+		query = `SELECT COUNT(*) FROM information_schema.TABLE_CONSTRAINTS
+			WHERE CONSTRAINT_SCHEMA = DATABASE() AND CONSTRAINT_TYPE = 'FOREIGN KEY'
+			AND TABLE_NAME IN (?, ?)`
+	case DriverPostgreSQL:
+		query = `SELECT COUNT(*) FROM information_schema.table_constraints
+			WHERE table_schema = current_schema() AND constraint_type = 'FOREIGN KEY'
+			AND table_name IN ($1, $2)`
+	default:
+		t.Fatalf("unexpected integration driver %q", store.cfg.Driver)
+	}
+	var count int
+	seriesTable, rollupsTable := store.tables.series, store.tables.rollups
+	if store.cfg.Driver == DriverPostgreSQL {
+		seriesTable, rollupsTable = strings.ToLower(seriesTable), strings.ToLower(rollupsTable)
+	}
+	if err := store.db.QueryRow(query, seriesTable, rollupsTable).Scan(&count); err != nil {
+		t.Fatalf("query foreign key metadata: %v", err)
+	}
+	if count != 4 {
+		t.Fatalf("foreign key count = %d, want 4", count)
+	}
 }
 
 // dropIntegrationTables drops integration-test tables.
@@ -190,7 +534,28 @@ func dropIntegrationTables(t *testing.T, store *Store, prefix string) {
 	if strings.TrimSpace(prefix) == "" {
 		t.Fatal("refusing to drop tables with empty prefix")
 	}
-	for _, name := range []string{prefix + "rollups", prefix + "points", prefix + "definitions"} {
+	for _, name := range []string{
+		prefix + "rebuild_points",
+		prefix + "rebuild_rollups",
+		prefix + "rebuild_series",
+		prefix + "rebuild_label_sets",
+		prefix + "rebuild_resolutions",
+		prefix + "rebuild_definitions",
+		prefix + "compaction_watermarks_legacy",
+		prefix + "points_legacy",
+		prefix + "rollups_legacy",
+		prefix + "series_legacy",
+		prefix + "label_sets_legacy",
+		prefix + "resolutions_legacy",
+		prefix + "definitions_legacy",
+		prefix + "compaction_watermarks",
+		prefix + "points",
+		prefix + "rollups",
+		prefix + "series",
+		prefix + "label_sets",
+		prefix + "resolutions",
+		prefix + "definitions",
+	} {
 		if _, err := store.db.Exec("DROP TABLE IF EXISTS " + name); err != nil {
 			t.Fatalf("drop integration table %s: %v", name, err)
 		}

pkg/metric/raw_points.go

@@ -0,0 +1,642 @@
+package metric
+
+import (
+	"context"
+	"database/sql"
+	"encoding/binary"
+	"fmt"
+	"math"
+	"sort"
+	"time"
+)
+
+const (
+	// directRawRetention keeps the newest samples in a directly searchable
+	// slice. The rest of rawMemoryRetention is losslessly byte-encoded.
+	directRawRetention = time.Minute
+	rawMemoryRetention = 10 * time.Minute
+)
+
+type rawSeriesKey struct {
+	metricName string
+	entityID   string
+	tagsHash   string
+}
+
+type rawSample struct {
+	timestamp int64
+	value     float64
+	labelID   uint32
+}
+
+// compressedRawSamples stores older raw samples without aggregating them.
+// Timestamps and label ids use varints; values remain IEEE-754 bits so the
+// raw API can return the original samples exactly.
+type compressedRawSamples struct {
+	data      []byte
+	count     int
+	lastStamp int64
+}
+
+// rawSeries stores exact samples compactly for one logical series. Tags are
+// shared by the series and labels are interned into small integer ids.
+type rawSeries struct {
+	tagsJSON    string
+	labelIDs    map[string]uint32
+	labelHashes []string
+	labelsJSON  []string
+	samples     []rawSample
+	compressed  compressedRawSamples
+}
+
+// preparedMetricPoint holds the compact dictionary keys shared by the raw
+// writer and the in-memory minute accumulator.
+type preparedMetricPoint struct {
+	metricName string
+	entityID   string
+	tagsHash   string
+	tagsJSON   string
+	labelsHash string
+	labelsJSON string
+	timestamp  int64
+	value      float64
+}
+
+func prepareMetricPoints(points []Point) ([]preparedMetricPoint, error) {
+	prepared := make([]preparedMetricPoint, 0, len(points))
+	for i, point := range points {
+		if err := point.Validate(); err != nil {
+			return nil, fmt.Errorf("point %d (metric %q, entity %q): %w", i, point.MetricName, point.EntityID, err)
+		}
+		point = point.normalized()
+		tagsHash, tagsJSON, err := tagsFingerprint(point.Tags)
+		if err != nil {
+			return nil, err
+		}
+		labelsHash, labelsJSON, err := tagsFingerprint(point.Labels)
+		if err != nil {
+			return nil, err
+		}
+		prepared = append(prepared, preparedMetricPoint{
+			metricName: point.MetricName,
+			entityID:   point.EntityID,
+			tagsHash:   tagsHash,
+			tagsJSON:   tagsJSON,
+			labelsHash: labelsHash,
+			labelsJSON: labelsJSON,
+			timestamp:  point.Timestamp.UnixMilli(),
+			value:      point.Value,
+		})
+	}
+	return prepared, nil
+}
+
+// writeRawPoints keeps the newest minute in a directly addressable form. The
+// surrounding nine minutes remain individual raw samples in a compact byte
+// representation; only their minute rollups are eventually persisted.
+func (s *Store) writeRawPoints(ctx context.Context, points []preparedMetricPoint) (map[hotRollupKey]struct{}, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	if len(points) == 0 {
+		return nil, nil
+	}
+	return s.writeRawPointsAt(points, time.Now().UTC()), nil
+}
+
+func (s *Store) writeRawPointsAt(points []preparedMetricPoint, now time.Time) map[hotRollupKey]struct{} {
+	now = now.UTC()
+	directCutoff := now.Add(-directRawRetention).UnixMilli()
+	rawCutoff := rawMemoryCutoff(now)
+	rebuild := make(map[hotRollupKey]struct{})
+	dirtyLabels := make(map[*rawSeries]struct{})
+	s.rawMu.Lock()
+	defer s.rawMu.Unlock()
+	s.compressRawBeforeLocked("", directCutoff)
+	s.pruneRawBeforeLocked("", rawCutoff)
+	for _, point := range points {
+		if point.timestamp < rawCutoff {
+			continue
+		}
+		key := rawSeriesKey{metricName: point.metricName, entityID: point.entityID, tagsHash: point.tagsHash}
+		series := s.raw[key]
+		if series == nil {
+			series = &rawSeries{tagsJSON: point.tagsJSON, labelIDs: make(map[string]uint32)}
+			s.raw[key] = series
+		}
+		labelID, ok := series.labelIDs[point.labelsHash]
+		if !ok {
+			labelID = uint32(len(series.labelsJSON))
+			series.labelIDs[point.labelsHash] = labelID
+			series.labelHashes = append(series.labelHashes, point.labelsHash)
+			series.labelsJSON = append(series.labelsJSON, point.labelsJSON)
+		}
+		sample := rawSample{timestamp: point.timestamp, value: point.value, labelID: labelID}
+		if point.timestamp < directCutoff {
+			old, replaced := series.replaceCompressed(sample)
+			if replaced {
+				markRawRebuild(rebuild, point, series.labelHashes[old.labelID])
+				if old.labelID != sample.labelID {
+					dirtyLabels[series] = struct{}{}
+				}
+			}
+			markRawRebuild(rebuild, point, point.labelsHash)
+			continue
+		}
+		index := sort.Search(len(series.samples), func(i int) bool {
+			return series.samples[i].timestamp >= point.timestamp
+		})
+		if index < len(series.samples) && series.samples[index].timestamp == point.timestamp {
+			old := series.samples[index]
+			markRawRebuild(rebuild, point, series.labelHashes[old.labelID])
+			markRawRebuild(rebuild, point, point.labelsHash)
+			series.samples[index] = sample
+			if old.labelID != sample.labelID {
+				dirtyLabels[series] = struct{}{}
+			}
+			continue
+		}
+		series.samples = append(series.samples, rawSample{})
+		copy(series.samples[index+1:], series.samples[index:])
+		series.samples[index] = sample
+	}
+	for series := range dirtyLabels {
+		compactRawLabels(series)
+	}
+	return rebuild
+}
+
+func markRawRebuild(rebuild map[hotRollupKey]struct{}, point preparedMetricPoint, labelsHash string) {
+	rebuild[hotRollupKey{metricName: point.metricName, entityID: point.entityID, tagsHash: point.tagsHash, labelsHash: labelsHash, bucket: bucketStartMillis(point.timestamp, time.Minute.Milliseconds())}] = struct{}{}
+}
+
+func (s *Store) queryRawPoints(ctx context.Context, query Query) ([]Point, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	start, end := query.Start.UnixMilli(), query.End.UnixMilli()
+	s.rawMu.Lock()
+	defer s.rawMu.Unlock()
+	now := time.Now().UTC()
+	visibleCutoff := now.Add(-rawMemoryRetention).UnixMilli()
+	if start < visibleCutoff {
+		start = visibleCutoff
+	}
+	s.compressRawBeforeLocked("", now.Add(-directRawRetention).UnixMilli())
+	s.pruneRawBeforeLocked("", rawMemoryCutoff(now))
+
+	type resultPoint struct {
+		point    Point
+		entityID string
+		tagsHash string
+	}
+	matched := make([]resultPoint, 0)
+	for key, series := range s.raw {
+		if key.metricName != query.MetricName || (query.EntityID != "" && key.entityID != query.EntityID) {
+			continue
+		}
+		tags, ok, err := matchRawTags(series.tagsJSON, query.Tags)
+		if err != nil {
+			return nil, err
+		}
+		if !ok {
+			continue
+		}
+		all := series.allSamples()
+		labels := make(map[uint32]map[string]string)
+		first := sort.Search(len(all), func(i int) bool { return all[i].timestamp >= start })
+		for _, sample := range all[first:] {
+			if sample.timestamp > end {
+				break
+			}
+			labelMap := labels[sample.labelID]
+			if labelMap == nil {
+				labelMap, err = decodeMapString(series.labelsJSON[sample.labelID])
+				if err != nil {
+					return nil, err
+				}
+				labels[sample.labelID] = labelMap
+			}
+			matched = append(matched, resultPoint{
+				point:    Point{MetricName: key.metricName, EntityID: key.entityID, Timestamp: fromMillis(sample.timestamp), Value: sample.value, Tags: cloneStringMap(tags), Labels: cloneStringMap(labelMap)},
+				entityID: key.entityID,
+				tagsHash: key.tagsHash,
+			})
+		}
+	}
+	sort.Slice(matched, func(i, j int) bool {
+		left, right := matched[i], matched[j]
+		less := left.point.Timestamp.Before(right.point.Timestamp)
+		if left.point.Timestamp.Equal(right.point.Timestamp) {
+			less = left.entityID < right.entityID || (left.entityID == right.entityID && left.tagsHash < right.tagsHash)
+		}
+		if query.Order == OrderDesc {
+			return !less && !(left.point.Timestamp.Equal(right.point.Timestamp) && left.entityID == right.entityID && left.tagsHash == right.tagsHash)
+		}
+		return less
+	})
+	startIndex := query.Offset
+	if startIndex > len(matched) {
+		startIndex = len(matched)
+	}
+	endIndex := len(matched)
+	if query.Limit > 0 && startIndex+query.Limit < endIndex {
+		endIndex = startIndex + query.Limit
+	}
+	result := make([]Point, 0, endIndex-startIndex)
+	for _, item := range matched[startIndex:endIndex] {
+		result = append(result, item.point)
+	}
+	return result, nil
+}
+
+func (s *Store) rawEntityIDs(ctx context.Context, query Query) ([]string, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	start, end := query.Start.UnixMilli(), query.End.UnixMilli()
+	s.rawMu.Lock()
+	defer s.rawMu.Unlock()
+	now := time.Now().UTC()
+	visibleCutoff := now.Add(-rawMemoryRetention).UnixMilli()
+	if start < visibleCutoff {
+		start = visibleCutoff
+	}
+	s.compressRawBeforeLocked("", now.Add(-directRawRetention).UnixMilli())
+	s.pruneRawBeforeLocked("", rawMemoryCutoff(now))
+	seen := make(map[string]struct{})
+	for key, series := range s.raw {
+		if key.metricName != query.MetricName || (query.EntityID != "" && key.entityID != query.EntityID) {
+			continue
+		}
+		_, ok, err := matchRawTags(series.tagsJSON, query.Tags)
+		if err != nil {
+			return nil, err
+		}
+		if !ok {
+			continue
+		}
+		all := series.allSamples()
+		index := sort.Search(len(all), func(i int) bool { return all[i].timestamp >= start })
+		if index < len(all) && all[index].timestamp <= end {
+			seen[key.entityID] = struct{}{}
+		}
+	}
+	result := make([]string, 0, len(seen))
+	for entityID := range seen {
+		result = append(result, entityID)
+	}
+	sort.Strings(result)
+	return result, nil
+}
+
+func matchRawTags(raw string, filter map[string]string) (map[string]string, bool, error) {
+	tags, err := decodeMapString(raw)
+	if err != nil {
+		return nil, false, err
+	}
+	for key, value := range filter {
+		if tags[key] != value {
+			return tags, false, nil
+		}
+	}
+	return tags, true, nil
+}
+
+// rawMemoryCutoff keeps the complete oldest minute internally so a late
+// replacement can rebuild that minute without dropping its earlier samples.
+// Query visibility is still clamped to the exact ten-minute window.
+func rawMemoryCutoff(now time.Time) int64 {
+	return bucketStartMillis(now.UTC().Add(-rawMemoryRetention).UnixMilli(), time.Minute.Milliseconds())
+}
+
+func (s *Store) trimRawWindow(now time.Time) int64 {
+	now = now.UTC()
+	s.rawMu.Lock()
+	defer s.rawMu.Unlock()
+	s.compressRawBeforeLocked("", now.Add(-directRawRetention).UnixMilli())
+	return s.pruneRawBeforeLocked("", rawMemoryCutoff(now))
+}
+
+func (s *Store) deleteRawPoints(metricName, entityID string, tags map[string]string) (int64, error) {
+	s.rawMu.Lock()
+	defer s.rawMu.Unlock()
+	var deleted int64
+	for key, series := range s.raw {
+		if metricName != "" && key.metricName != metricName {
+			continue
+		}
+		if entityID != "" && key.entityID != entityID {
+			continue
+		}
+		_, ok, err := matchRawTags(series.tagsJSON, tags)
+		if err != nil {
+			return deleted, err
+		}
+		if !ok {
+			continue
+		}
+		deleted += int64(len(series.samples) + series.compressed.count)
+		delete(s.raw, key)
+	}
+	return deleted, nil
+}
+
+func (s *Store) deleteRawBefore(metricName string, beforeMilli int64) int64 {
+	s.rawMu.Lock()
+	defer s.rawMu.Unlock()
+	s.compressRawBeforeLocked(metricName, beforeMilli)
+	return s.pruneRawBeforeLocked(metricName, beforeMilli)
+}
+
+func (s *Store) pruneRawBeforeLocked(metricName string, beforeMilli int64) int64 {
+	var deleted int64
+	for key, series := range s.raw {
+		if metricName != "" && key.metricName != metricName {
+			continue
+		}
+		compressed := series.decodeCompressed()
+		compressedIndex := sort.Search(len(compressed), func(i int) bool { return compressed[i].timestamp >= beforeMilli })
+		if compressedIndex > 0 {
+			compressed = compressed[compressedIndex:]
+			series.compressed.set(compressed)
+			deleted += int64(compressedIndex)
+		}
+		if len(compressed) == 0 {
+			series.compressed = compressedRawSamples{}
+		}
+		directIndex := sort.Search(len(series.samples), func(i int) bool { return series.samples[i].timestamp >= beforeMilli })
+		if directIndex > 0 {
+			deleted += int64(directIndex)
+			series.samples = append([]rawSample(nil), series.samples[directIndex:]...)
+		}
+		if series.compressed.count == 0 && len(series.samples) == 0 {
+			delete(s.raw, key)
+			continue
+		}
+		if compressedIndex > 0 || directIndex > 0 {
+			compactRawLabels(series)
+		}
+	}
+	return deleted
+}
+
+func (s *Store) compressRawBeforeLocked(metricName string, beforeMilli int64) {
+	for key, series := range s.raw {
+		if metricName != "" && key.metricName != metricName {
+			continue
+		}
+		index := sort.Search(len(series.samples), func(i int) bool { return series.samples[i].timestamp >= beforeMilli })
+		if index == 0 {
+			continue
+		}
+		series.compressed.append(series.samples[:index])
+		series.samples = append([]rawSample(nil), series.samples[index:]...)
+	}
+}
+
+func (s *rawSeries) decodeCompressed() []rawSample {
+	if s.compressed.count == 0 {
+		return nil
+	}
+	result := make([]rawSample, 0, s.compressed.count)
+	for offset, previous := 0, int64(0); offset < len(s.compressed.data); {
+		var timestamp int64
+		if len(result) == 0 {
+			first, n := binary.Varint(s.compressed.data[offset:])
+			if n <= 0 {
+				return result
+			}
+			offset += n
+			timestamp = first
+		} else {
+			delta, dn := binary.Uvarint(s.compressed.data[offset:])
+			if dn <= 0 {
+				return result
+			}
+			offset += dn
+			timestamp = previous + int64(delta)
+		}
+		if offset+8 > len(s.compressed.data) {
+			return result
+		}
+		value := math.Float64frombits(binary.LittleEndian.Uint64(s.compressed.data[offset:]))
+		offset += 8
+		labelID, ln := binary.Uvarint(s.compressed.data[offset:])
+		if ln <= 0 {
+			return result
+		}
+		offset += ln
+		result = append(result, rawSample{timestamp: timestamp, value: value, labelID: uint32(labelID)})
+		previous = timestamp
+	}
+	return result
+}
+
+func (s *rawSeries) allSamples() []rawSample {
+	compressed := s.decodeCompressed()
+	result := make([]rawSample, 0, len(compressed)+len(s.samples))
+	result = append(result, compressed...)
+	result = append(result, s.samples...)
+	return result
+}
+
+func (s *rawSeries) replaceCompressed(sample rawSample) (rawSample, bool) {
+	samples := s.decodeCompressed()
+	index := sort.Search(len(samples), func(i int) bool { return samples[i].timestamp >= sample.timestamp })
+	var old rawSample
+	replaced := index < len(samples) && samples[index].timestamp == sample.timestamp
+	if replaced {
+		old = samples[index]
+		samples[index] = sample
+	} else {
+		samples = append(samples, rawSample{})
+		copy(samples[index+1:], samples[index:])
+		samples[index] = sample
+	}
+	s.compressed.set(samples)
+	return old, replaced
+}
+
+func (c *compressedRawSamples) append(samples []rawSample) {
+	if len(samples) == 0 {
+		return
+	}
+	if c.count > 0 && samples[0].timestamp <= c.lastStamp {
+		merged := make([]rawSample, 0, c.count+len(samples))
+		merged = append(merged, c.decode()...)
+		for _, sample := range samples {
+			index := sort.Search(len(merged), func(i int) bool { return merged[i].timestamp >= sample.timestamp })
+			if index < len(merged) && merged[index].timestamp == sample.timestamp {
+				merged[index] = sample
+				continue
+			}
+			merged = append(merged, rawSample{})
+			copy(merged[index+1:], merged[index:])
+			merged[index] = sample
+		}
+		c.set(merged)
+		return
+	}
+	for _, sample := range samples {
+		if c.count == 0 {
+			c.data = appendVarint(c.data, sample.timestamp)
+		} else {
+			c.data = appendUvarint(c.data, uint64(sample.timestamp-c.lastStamp))
+		}
+		c.data = appendRawSample(c.data, sample)
+		c.count++
+		c.lastStamp = sample.timestamp
+	}
+}
+
+func (c *compressedRawSamples) decode() []rawSample {
+	series := rawSeries{compressed: *c}
+	return series.decodeCompressed()
+}
+
+func (c *compressedRawSamples) set(samples []rawSample) {
+	c.data = nil
+	c.count = 0
+	c.lastStamp = 0
+	for _, sample := range samples {
+		if c.count == 0 {
+			c.data = appendVarint(c.data, sample.timestamp)
+		} else {
+			c.data = appendUvarint(c.data, uint64(sample.timestamp-c.lastStamp))
+		}
+		c.data = appendRawSample(c.data, sample)
+		c.count++
+		c.lastStamp = sample.timestamp
+	}
+}
+
+func appendRawSample(dst []byte, sample rawSample) []byte {
+	var value [8]byte
+	binary.LittleEndian.PutUint64(value[:], math.Float64bits(sample.value))
+	dst = append(dst, value[:]...)
+	return appendUvarint(dst, uint64(sample.labelID))
+}
+
+func appendVarint(dst []byte, value int64) []byte {
+	var encoded [binary.MaxVarintLen64]byte
+	n := binary.PutVarint(encoded[:], value)
+	return append(dst, encoded[:n]...)
+}
+
+func appendUvarint(dst []byte, value uint64) []byte {
+	var encoded [binary.MaxVarintLen64]byte
+	n := binary.PutUvarint(encoded[:], value)
+	return append(dst, encoded[:n]...)
+}
+
+func compactRawLabels(series *rawSeries) {
+	if len(series.labelHashes) <= 1 {
+		return
+	}
+	all := series.allSamples()
+	used := make([]bool, len(series.labelHashes))
+	for _, sample := range all {
+		used[sample.labelID] = true
+	}
+	usedCount := 0
+	for _, keep := range used {
+		if keep {
+			usedCount++
+		}
+	}
+	if usedCount == len(used) {
+		return
+	}
+	remap := make([]uint32, len(used))
+	labelHashes := make([]string, 0, usedCount)
+	labelsJSON := make([]string, 0, usedCount)
+	labelIDs := make(map[string]uint32, usedCount)
+	for oldID, keep := range used {
+		if !keep {
+			continue
+		}
+		newID := uint32(len(labelHashes))
+		remap[oldID] = newID
+		hash := series.labelHashes[oldID]
+		labelHashes = append(labelHashes, hash)
+		labelsJSON = append(labelsJSON, series.labelsJSON[oldID])
+		labelIDs[hash] = newID
+	}
+	compressed := series.decodeCompressed()
+	for i := range compressed {
+		compressed[i].labelID = remap[compressed[i].labelID]
+	}
+	series.compressed.set(compressed)
+	for i := range series.samples {
+		series.samples[i].labelID = remap[series.samples[i].labelID]
+	}
+	series.labelHashes = labelHashes
+	series.labelsJSON = labelsJSON
+	series.labelIDs = labelIDs
+}
+
+func (s *Store) latestRollupBefore(ctx context.Context, metricName, entityID string, before time.Time) (Point, bool, error) {
+	s.rollupViewMu.RLock()
+	defer s.rollupViewMu.RUnlock()
+	end := before.Add(-time.Nanosecond)
+	endMilli := end.UnixMilli()
+	var latest Point
+	found := false
+	for _, tier := range s.cfg.RollupPolicy.Tiers {
+		var value float64
+		var timestamp int64
+		var rawTags, rawLabels any
+		err := s.reader().QueryRowContext(ctx, fmt.Sprintf(`SELECT r.last_val, r.last_ts_milli, s.tags, l.labels
+			FROM %s r JOIN %s s ON s.id = r.series_id JOIN %s l ON l.id = r.label_id
+			WHERE r.series_id IN (SELECT id FROM %s WHERE metric_name = %s AND entity_id = %s)
+			AND r.resolution_id IN (SELECT id FROM %s WHERE resolution_milli = %s)
+			AND r.last_ts_milli <= %s
+			ORDER BY r.last_ts_milli DESC LIMIT 1`,
+			s.tables.rollups, s.tables.series, s.tables.labels, s.tables.series,
+			s.dialect.placeholder(1), s.dialect.placeholder(2), s.tables.resolutions,
+			s.dialect.placeholder(3), s.dialect.placeholder(4)),
+			metricName, entityID, tier.Interval.Milliseconds(), endMilli,
+		).Scan(&value, &timestamp, &rawTags, &rawLabels)
+		if err == sql.ErrNoRows {
+			continue
+		}
+		if err != nil {
+			return Point{}, false, err
+		}
+		if found && timestamp <= latest.Timestamp.UnixMilli() {
+			continue
+		}
+		tags, err := decodeMap(rawTags)
+		if err != nil {
+			return Point{}, false, err
+		}
+		labels, err := decodeMap(rawLabels)
+		if err != nil {
+			return Point{}, false, err
+		}
+		latest = Point{MetricName: metricName, EntityID: entityID, Timestamp: fromMillis(timestamp), Value: value, Tags: tags, Labels: labels}
+		found = true
+	}
+
+	hot, err := s.hotRollupRows(metricName, entityID, nil, time.Unix(0, 0), end, false)
+	if err != nil {
+		return Point{}, false, err
+	}
+	for _, row := range hot {
+		if row.bucketData.lastTS > endMilli || (found && row.bucketData.lastTS <= latest.Timestamp.UnixMilli()) {
+			continue
+		}
+		tags, err := rollupTagsFromJSON(row.bucketData.tagsJSON)
+		if err != nil {
+			return Point{}, false, err
+		}
+		labels, err := rollupTagsFromJSON(row.bucketData.labelsJSON)
+		if err != nil {
+			return Point{}, false, err
+		}
+		latest = Point{MetricName: metricName, EntityID: entityID, Timestamp: fromMillis(row.bucketData.lastTS), Value: row.bucketData.lastVal, Tags: tags, Labels: labels}
+		found = true
+	}
+	return latest, found, nil
+}