A modern and elegant dashboard for network traffic visualization and analysis.
docs: update README and architecture docs with ClickHouse support
luolei4a6fc0e69d59
diff --git a/README.en.md b/README.en.mdindex 857cffe..4fe2948 100644--- a/README.en.md+++ b/README.en.md@@ -71,6 +71,7 @@ It is a lightweight analytics dashboard designed for modern gateway environments- [๐ First Use](#-first-use)- [๐ง Port Conflict Resolution](#-port-conflict-resolution)- [๐ณ Docker Configuration](#-docker-configuration)+- [๐๏ธ ClickHouse (Optional)](#-clickhouse-optional)- [๐ Reverse Proxy & Tunnel](#-reverse-proxy--tunnel)- [๐ Authentication & Security](#-authentication--security)- [โ FAQ](#-faq)@@ -429,6 +430,158 @@ Additional recommendations:> Advanced Agent details (install, config, release, compatibility) are maintained under `docs/agent/*`.+## ๐๏ธ ClickHouse (Optional)++SQLite is Neko Master's default storage engine and works well for most users.+Consider enabling ClickHouse if you need:++- Very large datasets (hundreds of thousands of domain/IP entries)+- Fast aggregation queries over long time ranges (โฅ 7 days)+- Separation of historical stats from configuration/metadata storage++> ClickHouse is entirely optional. SQLite remains as the configuration and metadata store regardless of whether ClickHouse is enabled.++### Architecture Overview++When ClickHouse is enabled, the system enters **dual-write mode**:++```+BatchBuffer.flush()+ โ+ โโโโ SQLite (config / metadata, always written)+ โโโโ ClickHouse (stats traffic data, dual-write)+ โโโ Buffer tables โ SummingMergeTree async merge+```++Read source is controlled by `STATS_QUERY_SOURCE` (default: `sqlite`).++### Enabling ClickHouse (Docker)++#### Step 1: Start the ClickHouse container++The `docker-compose.yml` includes a ClickHouse service gated by `profiles: [clickhouse]`:++```bash+docker compose --profile clickhouse up -d+```++> ClickHouse data is persisted to `./data/clickhouse`, separate from the main app data directory.++#### Step 2: Configure environment variables++Add to your `.env` (same directory as `docker-compose.yml`):++```env+# Enable ClickHouse connection+CH_ENABLED=1++# Enable dual-write+CH_WRITE_ENABLED=1++# Read source: sqlite (default) / auto (smart routing) / clickhouse (force)+STATS_QUERY_SOURCE=auto++# ClickHouse connection (defaults match docker-compose.yml, no change needed)+CH_HOST=clickhouse+CH_PORT=8123+CH_DATABASE=neko_master+CH_USER=neko+CH_PASSWORD=neko_master+```++Restart:++```bash+docker compose --profile clickhouse up -d+```++### ClickHouse Environment Variables++| Variable | Default | Description |+| :-- | :-- | :-- |+| `CH_ENABLED` | `0` | Enable ClickHouse connection (`1` to enable) |+| `CH_WRITE_ENABLED` | `0` | Enable dual-write (requires `CH_ENABLED=1`) |+| `CH_ONLY_MODE` | `0` | When CH is healthy, skip SQLite stats writes (CH-only mode) |+| `CH_HOST` | `clickhouse` | ClickHouse host address |+| `CH_PORT` | `8123` | ClickHouse HTTP port |+| `CH_DATABASE` | `neko_master` | Database name |+| `CH_USER` | `neko` | Username |+| `CH_PASSWORD` | `neko_master` | Password |+| `CH_SECURE` | `0` | Use HTTPS connection |+| `CH_REQUIRED` | `0` | Refuse to start if CH is unavailable |+| `CH_AUTO_CREATE_TABLES` | `1` | Auto-create tables on first start |+| `CH_WRITE_MAX_PENDING_BATCHES` | `200` | Max pending write batches |+| `CH_UNHEALTHY_THRESHOLD` | `5` | Consecutive failures before marking unhealthy (auto-fallback to SQLite) |+| `STATS_QUERY_SOURCE` | `sqlite` | Read source: `sqlite` / `auto` / `clickhouse` |+| `CH_COMPARE_ENABLED` | `0` | Enable SQLite โ ClickHouse consistency check |+| `CH_EXTERNAL_HTTP_PORT` | `8123` | ClickHouse HTTP external port (Compose mapping) |+| `CH_EXTERNAL_NATIVE_PORT` | `9000` | ClickHouse Native external port (Compose mapping) |++> **Health & Fallback**: After `CH_UNHEALTHY_THRESHOLD` consecutive write failures, the system automatically marks ClickHouse as unhealthy and resumes SQLite writesโeven when `CH_ONLY_MODE=1`. Once ClickHouse recovers, it is re-marked healthy and logged.++### Migration Guide for Existing Users++> Upgrading from a SQLite-only version? **Your data is safe.**+> The SQLite file (`./data/stats.db`) is fully preserved. Here is the recommended gradual migration path:++#### Phase 1: Dual-write (observation period, recommended starting point)++```env+CH_ENABLED=1+CH_WRITE_ENABLED=1+STATS_QUERY_SOURCE=sqlite # Keep reading from SQLite while CH accumulates data+```++Start and watch `[ClickHouse Writer]` logs to confirm successful writes.++#### Phase 2: Switch read source++```env+STATS_QUERY_SOURCE=auto # Smart routing: recent data from CH, historical from SQLite+# or+STATS_QUERY_SOURCE=clickhouse # Force all reads to ClickHouse+```++#### Phase 3 (optional): Migrate historical data++To move historical SQLite stats into ClickHouse:++```bash+# Standard migration (truncate CH then re-import, with consistency check)+./scripts/ch-migrate-docker.sh++# Append mode (keep existing CH data, incremental import)+./scripts/ch-migrate-docker.sh --append++# Specific time window+./scripts/ch-migrate-docker.sh --from 2026-02-01T00:00:00Z --to 2026-02-20T00:00:00Z+```++#### Phase 4 (optional): CH-only mode++Once ClickHouse is running stably, stop SQLite stats writes:++```env+CH_ONLY_MODE=1+```++> Even with `CH_ONLY_MODE=1`, if ClickHouse becomes unhealthy the system automatically falls back to SQLite writesโno data loss.++### Reverting to SQLite-only++You can always roll back completely:++```env+CH_ENABLED=0+CH_WRITE_ENABLED=0+CH_ONLY_MODE=0+STATS_QUERY_SOURCE=sqlite+```++Restart and everything returns to pure SQLite mode. Historical data remains intact.++---+## ๐ Reverse Proxy & TunnelRecommended approach: keep Web and WS under the same domain, with path routing:@@ -598,35 +751,6 @@ If you forgot the token, temporarily set `FORCE_ACCESS_CONTROL_OFF=true` to ente3. Reset token, then remove this flag and restart normally.-### ClickHouse Migration (Docker Users)--If you want to migrate stats from SQLite to ClickHouse (while keeping control/config in SQLite), use the one-command helper:--```bash-./scripts/ch-migrate-docker.sh-```--The script automatically:--1. Starts services with the `clickhouse` profile-2. Migrates SQLite stats into ClickHouse-3. Verifies SQLite vs ClickHouse consistency (default threshold: 1%)--Common options:--```bash-# Append import without truncating CH tables-./scripts/ch-migrate-docker.sh --append--# Migrate a specific time window-./scripts/ch-migrate-docker.sh --from 2026-02-01T00:00:00Z --to 2026-02-20T00:00:00Z-```--After migration, set `STATS_QUERY_SOURCE=auto` and restart:--```bash-docker compose up -d-```## โ FAQ@@ -705,8 +829,9 @@ If you want to quickly understand the system design depth, read in this order:Chinese: [`docs/architecture.md`](./docs/architecture.md)English: [`docs/architecture.en.md`](./docs/architecture.en.md)2. **Data Flow**: Clash / Surge collection pipelines and aggregation-3. **Data Model & Storage**: SQLite schema, cache tables, retention+3. **Data Model & Storage**: SQLite schema, ClickHouse Buffer tables, retention policy4. **Realtime Channel Design**: `RealtimeStore` merge strategy and WS push+5. **ClickHouse Module**: dual-write architecture, health fallback, read routing> This documentation covers the core design of collection, aggregation, caching, realtime push, and multi-backend management.@@ -749,7 +874,7 @@ neko-master/- **Charts**: [Recharts](https://recharts.org/)- **i18n**: [next-intl](https://next-intl-docs.vercel.app/)- **Backend**: [Node.js](https://nodejs.org/) + [Fastify](https://www.fastify.io/) + WebSocket-- **Database**: [SQLite](https://www.sqlite.org/) ([better-sqlite3](https://github.com/WiseLibs/better-sqlite3))+- **Database**: [SQLite](https://www.sqlite.org/) ([better-sqlite3](https://github.com/WiseLibs/better-sqlite3)) + [ClickHouse](https://clickhouse.com/) (optional)- **Build**: [pnpm](https://pnpm.io/) + [Turborepo](https://turbo.build/)## ๐ค Contributingdiff --git a/README.md b/README.mdindex b166741..4f2a193 100644--- a/README.md+++ b/README.md@@ -76,6 +76,7 @@ Neko Master ไธๆณจไบๅฏน็ฝ็ปๆต้่ฟ่ก่ฝป้ใ็ฒพ็กฎ็ๅๆไธๅฏ่งๅ- [๐ ้ฆๆฌกไฝฟ็จ](#-้ฆๆฌกไฝฟ็จ)- [๐ง ็ซฏๅฃๅฒ็ช่งฃๅณ](#-็ซฏๅฃๅฒ็ช่งฃๅณ)- [๐ณ Docker ้ ็ฝฎ](#-docker-้ ็ฝฎ)+- [๐๏ธ ClickHouse๏ผๅฏ้๏ผ](#-clickhouse-ๅฏ้)- [๐ ๅๅไปฃ็ไธ Tunnel](#-ๅๅไปฃ็ไธ-tunnel)- [๐ ่ฎค่ฏไธๅฎๅ จ](#-่ฎค่ฏไธๅฎๅ จ)- [โ ๅธธ่ง้ฎ้ข](#-ๅธธ่ง้ฎ้ข)@@ -420,6 +421,158 @@ COOKIE_SECRET=<่ณๅฐ32ๅญ่้ๆบๅญ็ฌฆไธฒ>> ่ฟ้ถ่ฏดๆ๏ผAgent ๆจกๅผ็ๅฎ่ฃ ใๅๆฐใๅๅธไธๅ ผๅฎน็ญ็ฅๅทฒ่ฟ็งปๅฐ `docs/agent/*`๏ผ่ฏทไปฅๆๆกฃไธบๅใ+## ๐๏ธ ClickHouse๏ผๅฏ้๏ผ++SQLite ๆฏ Neko Master ็้ป่ฎคๅญๅจๅผๆ๏ผๅฏนๅคงๅคๆฐ็จๆทๅทฒๅฎๅ จๅค็จใ+ๅฆๆไฝ ๆไปฅไธ้ๆฑ๏ผๅฏไปฅ้ขๅคๅฏ็จ ClickHouse๏ผ++- ๆฐๆฎ้ๅพๅคง๏ผๅๅ / IP ๆก็ฎๆฐๅไธไปฅไธ๏ผ+- ้่ฆๅฟซ้็้ฟๆถ้ด่ๅด๏ผโฅ 7 ๅคฉ๏ผ่ๅๆฅ่ฏข+- ๅธๆๅฐๅๅฒ็ป่ฎกๆฐๆฎไธ้ ็ฝฎๆฐๆฎๅๅฑๅญๅจ++> ClickHouse ๅฎๅ จๅฏ้ใSQLite ไฝไธบ้ ็ฝฎๅๅ ๆฐๆฎๅญๅจ๏ผๆ ่ฎบๆฏๅฆๅฏ็จ ClickHouse ้ฝไธไผ่ขซ็งป้คใ++### ๆถๆ่ฏดๆ++ๅฏ็จ ClickHouse ๅ๏ผ็ณป็ป่ฟๅ ฅ**ๅๅๆจกๅผ**๏ผ++```+BatchBuffer.flush()+ โ+ โโโโ SQLite๏ผ้ ็ฝฎ / ๅ ๆฐๆฎ๏ผๅง็ปๅๅ ฅ๏ผ+ โโโโ ClickHouse๏ผ็ป่ฎกๆต้ๆฐๆฎ๏ผๅๅ๏ผ+ โโโ Buffer ่กจ โ SummingMergeTree ๅผๆญฅๅๅนถ+```++่ฏปๅๆฅๆบ็ฑ `STATS_QUERY_SOURCE` ๆงๅถ๏ผ้ป่ฎคไปไธบ `sqlite`ใ++### ๅฏ็จ ClickHouse๏ผDocker๏ผ++#### ๆญฅ้ชคไธ๏ผๅฏๅจ ClickHouse ๅฎนๅจ++`docker-compose.yml` ๅ ็ฝฎไบ ClickHouse ๆๅก๏ผ้่ฟ `profiles: [clickhouse]` ้็ฆปใๅฏๅจๆถๅ ไธ profile๏ผ++```bash+docker compose --profile clickhouse up -d+```++> ClickHouse ๆฐๆฎๆไน ๅๅฐ `./data/clickhouse`๏ผไธไธปๅบ็จๆฐๆฎๅ็ฎๅฝๅญๅจใ++#### ๆญฅ้ชคไบ๏ผ้ ็ฝฎ็ฏๅขๅ้++ๅจ `.env` ไธญๆทปๅ ๏ผไธ `docker-compose.yml` ๅ็ฎๅฝ๏ผ๏ผ++```env+# ๅผๅฏ ClickHouse ่ฟๆฅ+CH_ENABLED=1++# ๅผๅฏๅๅ+CH_WRITE_ENABLED=1++# ่ฏปๅๆฅๆบ๏ผsqlite๏ผ้ป่ฎค๏ผ/ auto๏ผ่ชๅจ้ๆฉ๏ผ/ clickhouse๏ผๅผบๅถ๏ผ+STATS_QUERY_SOURCE=auto++# ClickHouse ่ฟๆฅไฟกๆฏ๏ผไฝฟ็จ docker-compose.yml ้ป่ฎคๅผๆถ๏ผไปฅไธๆ ้ไฟฎๆน๏ผ+CH_HOST=clickhouse+CH_PORT=8123+CH_DATABASE=neko_master+CH_USER=neko+CH_PASSWORD=neko_master+```++้ๅฏ๏ผ++```bash+docker compose --profile clickhouse up -d+```++### ClickHouse ็ฏๅขๅ้่ฏดๆ++| ๅ้ๅ | ้ป่ฎคๅผ | ่ฏดๆ |+| :-- | :-- | :-- |+| `CH_ENABLED` | `0` | ๆฏๅฆๅฏ็จ ClickHouse ่ฟๆฅ๏ผ`1` ๅผๅฏ๏ผ |+| `CH_WRITE_ENABLED` | `0` | ๆฏๅฆๅผๅฏๅๅ๏ผ้กปๅ ๅผ `CH_ENABLED`๏ผ |+| `CH_ONLY_MODE` | `0` | CH ๅฅๅบทๆถ่ทณ่ฟ SQLite ็ป่ฎกๅๅ ฅ๏ผ็บฏ CH ๆจกๅผ๏ผ |+| `CH_HOST` | `clickhouse` | ClickHouse ไธปๆบๅฐๅ |+| `CH_PORT` | `8123` | ClickHouse HTTP ็ซฏๅฃ |+| `CH_DATABASE` | `neko_master` | ๆฐๆฎๅบๅ็งฐ |+| `CH_USER` | `neko` | ็จๆทๅ |+| `CH_PASSWORD` | `neko_master` | ๅฏ็ |+| `CH_SECURE` | `0` | ๆฏๅฆไฝฟ็จ HTTPS ่ฟๆฅ |+| `CH_REQUIRED` | `0` | CH ไธๅฏ็จๆถๆ็ปๅฏๅจ๏ผ`1` ๅผๅฏ๏ผ |+| `CH_AUTO_CREATE_TABLES` | `1` | ้ฆๆฌกๅฏๅจๆถ่ชๅจๅปบ่กจ |+| `CH_WRITE_MAX_PENDING_BATCHES` | `200` | ๆๅคงๅๅ ฅ็งฏๅๆนๆฌกๆฐ |+| `CH_UNHEALTHY_THRESHOLD` | `5` | ่ฟ็ปญๅคฑ่ดฅๆฌกๆฐ่ถ ่ฟๆญคๅผๅๆ ่ฎฐไธบไธๅฅๅบท๏ผ่ชๅจๅ้ SQLite |+| `STATS_QUERY_SOURCE` | `sqlite` | ่ฏปๅๆฅๆบ๏ผ`sqlite` / `auto` / `clickhouse` |+| `CH_COMPARE_ENABLED` | `0` | ๅผๅฏ SQLite โ ClickHouse ๆฐๆฎๅฏน่ดฆ |+| `CH_EXTERNAL_HTTP_PORT` | `8123` | ClickHouse HTTP ๅค้จ็ซฏๅฃ๏ผCompose ๆ ๅฐ๏ผ |+| `CH_EXTERNAL_NATIVE_PORT` | `9000` | ClickHouse Native ๅค้จ็ซฏๅฃ๏ผCompose ๆ ๅฐ๏ผ |++> **ๅฅๅบทๅ้ๆบๅถ**๏ผClickHouse ่ฟ็ปญๅๅ ฅๅคฑ่ดฅ่ถ ่ฟ `CH_UNHEALTHY_THRESHOLD` ๆฌกๅ๏ผ็ณป็ป่ชๅจๆ ่ฎฐไธบไธๅฅๅบท๏ผSQLite ๅๅ ฅๆขๅค๏ผๅณไฝฟๅผๅฏไบ `CH_ONLY_MODE`๏ผใClickHouse ๆขๅคๆญฃๅธธๅ่ชๅจ้ๆฐๆ ่ฎฐไธบๅฅๅบทใ++### ่็จๆท่ฟ็งปๆๅผ++> ไป็บฏ SQLite ็ๆฌๅ็บงๆถ๏ผ**ไฝ ็ๆฐๆฎไธไผไธขๅคฑ**ใ+> SQLite ๆไปถ๏ผ`./data/stats.db`๏ผๅฎๆดไฟ็๏ผไปฅไธๆฏๆจ่็ๆธ่ฟ่ฟ็งป่ทฏๅพ๏ผ++#### ็ฌฌไธ้ถๆฎต๏ผๅๅ๏ผ่งๅฏๆ๏ผๆจ่่ตท็น๏ผ++```env+CH_ENABLED=1+CH_WRITE_ENABLED=1+STATS_QUERY_SOURCE=sqlite # ็ปง็ปญ่ฏป SQLite๏ผCH ๅจๅๅฐ็งฏ็ดฏๆฐๆฎ+```++ๅฏๅจๅนถ่งๅฏ `[ClickHouse Writer]` ๆฅๅฟ็กฎ่ฎคๅๅ ฅๆญฃๅธธใ++#### ็ฌฌไบ้ถๆฎต๏ผๅๆข่ฏปๅๆฅๆบ++```env+STATS_QUERY_SOURCE=auto # ่ชๅจ้ๆฉ๏ผๆ่ฟๆฐๆฎ่ตฐ CH๏ผๅๅฒ่ตฐ SQLite+# ๆ+STATS_QUERY_SOURCE=clickhouse # ๅผบๅถ่ฏป CH+```++#### ็ฌฌไธ้ถๆฎต๏ผๅฏ้๏ผ๏ผ่ฟ็งปๅๅฒๆฐๆฎ++ๅฆ้ๅฐ SQLite ๅๅฒ็ป่ฎกๆฐๆฎๆฌๅ ฅ ClickHouse๏ผ++```bash+# ๆ ๅ่ฟ็งป๏ผๆธ ็ฉบ CH ๅ้ๆฐๅฏผๅ ฅ๏ผ้ๅธฆๅฏน่ดฆ้ช่ฏ๏ผ+./scripts/ch-migrate-docker.sh++# ่ฟฝๅ ๆจกๅผ๏ผไฟ็ CH ็ฐๆๆฐๆฎ๏ผๅข้ๅฏผๅ ฅ๏ผ+./scripts/ch-migrate-docker.sh --append++# ๆๅฎๆถ้ด็ชๅฃ+./scripts/ch-migrate-docker.sh --from 2026-02-01T00:00:00Z --to 2026-02-20T00:00:00Z+```++#### ็ฌฌๅ้ถๆฎต๏ผๅฏ้๏ผ๏ผ็บฏ ClickHouse ๆจกๅผ++ๅฝ ClickHouse ็จณๅฎ่ฟ่กๅ๏ผๅฏๅๆญข SQLite ็ป่ฎกๅๅ ฅ๏ผ++```env+CH_ONLY_MODE=1+```++> ๅณไฝฟๅจ `CH_ONLY_MODE=1` ไธ๏ผ่ฅ ClickHouse ไธๅฅๅบท๏ผ็ณป็ปไผ่ชๅจๅ้ๅฐ SQLite ๅๅ ฅ๏ผๆฐๆฎไธไผไธขๅคฑใ++### ๅ้ๅฐ็บฏ SQLite++้ๆถๅฏไปฅๅฎๅ จๅ้๏ผ++```env+CH_ENABLED=0+CH_WRITE_ENABLED=0+CH_ONLY_MODE=0+STATS_QUERY_SOURCE=sqlite+```++้ๅฏๅๆขๅค็บฏ SQLite ๆจกๅผ๏ผๅๅฒๆฐๆฎๅฎๆดไฟ็ใ++---+## ๐ ๅๅไปฃ็ไธ Tunnelๆจ่ๅฐ Web ้กต้ขไธ WS ้ฝๆพๅจๅไธไธชๅๅไธ๏ผ้่ฟไธๅ่ทฏๅพ่ฝฌๅ๏ผ`/` โ `3000`๏ผ`/_cm_ws` โ `3002`ใ@@ -590,35 +743,6 @@ COOKIE_SECRET=<่ณๅฐ32ๅญ่้ๆบๅญ็ฌฆไธฒ>3. ้็ฝฎๅฏ็ ๅ๏ผๅๆฌกๅๆญขๅฎนๅจ๏ผๅป้ค่ฏฅๅๆฐๅนถ้ๅฏ๏ผๆขๅคๆญฃๅธธไฟๆคๆจกๅผใ-### ClickHouse ่ฟ็งป๏ผDocker ็จๆท๏ผ--ๅฆๆไฝ ๅๅคไป SQLite ็ป่ฎก่ฟ็งปๅฐ ClickHouse๏ผไฟ็้ ็ฝฎไปๅจ SQLite๏ผ๏ผๆจ่็ดๆฅไฝฟ็จไธ้ฎ่ๆฌ๏ผ--```bash-./scripts/ch-migrate-docker.sh-```--่ๆฌไผ่ชๅจๆง่ก๏ผ--1. ๅฏๅจ `clickhouse` profile ๅฎนๅจ-2. ่ฟ็งป SQLite ๆฐๆฎๅฐ ClickHouse-3. ๅฏน่ดฆ้ช่ฏ๏ผ้ป่ฎค้ๅผ 1%๏ผ--ๅธธ็จๅๆฐ๏ผ--```bash-# ไธๆธ ็ฉบ CH ๅๅฒๆฐๆฎ๏ผๅ่ฟฝๅ ๅฏผๅ ฅ-./scripts/ch-migrate-docker.sh --append--# ๆๅฎๆถ้ด็ชๅฃ่ฟ็งป-./scripts/ch-migrate-docker.sh --from 2026-02-01T00:00:00Z --to 2026-02-20T00:00:00Z-```--่ฟ็งปๅฎๆๅ๏ผๅปบ่ฎฎๅฐ `STATS_QUERY_SOURCE=auto` ๅนถ้ๅฏ๏ผ--```bash-docker compose up -d-```## โ ๅธธ่ง้ฎ้ข@@ -696,8 +820,9 @@ docker compose up -dไธญๆ๏ผ[`docs/architecture.md`](./docs/architecture.md)English: [`docs/architecture.en.md`](./docs/architecture.en.md)2. **ๆฐๆฎๆต่ฏฆ่งฃ**๏ผClash / Surge ไธคๆก้้้พ่ทฏไธ่ๅ่ฟ็จ-3. **ๆฐๆฎๆจกๅไธๅญๅจ**๏ผSQLite ่กจ็ปๆใ็ผๅญ่กจใไฟ็็ญ็ฅ+3. **ๆฐๆฎๆจกๅไธๅญๅจ**๏ผSQLite ่กจ็ปๆใClickHouse Buffer ่กจใไฟ็็ญ็ฅ4. **ๅฎๆถ้้่ฎพ่ฎก**๏ผ`RealtimeStore` ๅๅนถ็ญ็ฅไธ WS ๆจ้ๆบๅถ+5. **ClickHouse ๆจกๅ**๏ผๅๅๆถๆใๅฅๅบทๅ้ใ่ฏปๅ่ทฏ็ฑ> ่ฏฅๆๆกฃ่ฆ็้้ใ่ๅใ็ผๅญใๅฎๆถๆจ้ไธๅคๅ็ซฏ็ฎก็็ๆ ธๅฟ่ฎพ่ฎกใ@@ -737,7 +862,7 @@ neko-master/- **ๅ็ซฏ**: Next.js 16 + React 19 + TypeScript + Tailwind CSS- **UI ็ปไปถ**: shadcn/ui-- **ๆฐๆฎๆถ้**: Node.js + Fastify + WebSocket + SQLite+- **ๆฐๆฎๆถ้**: Node.js + Fastify + WebSocket + SQLite๏ผ+ ClickHouse ๅฏ้๏ผ- **ๅฏ่งๅ**: Recharts + D3.js- **ๅฝ้ ๅ**: next-intl๏ผไธญ/่ฑ๏ผ- **้จ็ฝฒ**: Docker + Docker Composediff --git a/docs/architecture.en.md b/docs/architecture.en.mdindex 3a70765..12d39ea 100644--- a/docs/architecture.en.md+++ b/docs/architecture.en.md@@ -132,13 +132,14 @@โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ- โ SQLite (better-sqlite3)+ โโโโ SQLite (better-sqlite3) [always written]+ โโโโ ClickHouse HTTP API [optional dual-write]โผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ Storage Layer โโ โโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ-โ โ SQLite Database (WAL Mode) โ โ+โ โ SQLite Database (WAL Mode) [always enabled] โ โโ โ โ โโ โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โโ โ โ Statistics Tables (partitioned by backend_id) โ โ โ@@ -171,6 +172,28 @@โ โ โ โโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโ โ โ โโ โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ+โ โ+โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ+โ โ ClickHouse Database [optional, enabled with CH_ENABLED=1] โ โ+โ โ โ โ+โ โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โ+โ โ โ Buffer Tables (async receive, ~5min merge) โ โ โ+โ โ โ โ โ โ+โ โ โ โโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโ โ โ โ+โ โ โ โ traffic_detail_bufferโ โ traffic_agg_buffer โ โ โ โ+โ โ โ โโโโโโโโโโโโโฌโโโโโโโโโโโโ โโโโโโโโโโโโฌโโโโโโโโโโโโโ โ โ โ+โ โ โ โ merge โ merge โ โ โ+โ โ โ โผ โผ โ โ โ+โ โ โ โโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโ โ โ โ+โ โ โ โ traffic_detail โ โ traffic_agg โ โ โ โ+โ โ โ โ (SummingMergeTree) โ โ (SummingMergeTree) โ โ โ โ+โ โ โ โโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโ โ โ โ+โ โ โ โ โ โ+โ โ โ โโโโโโโโโโโโโโโโโโโโโโโโโ โ โ โ+โ โ โ โ country_buffer โ โ country_stats (SummingMergeTree) โ โ โ+โ โ โ โโโโโโโโโโโโโโโโโโโโโโโโโ โ โ โ+โ โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โ+โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฒโ@@ -236,7 +259,8 @@ ClashCollectorโ - Batch cache optimizationโโโโ 4. Data Write- โ โโโโ SQLite (Persistence)+ โ โโโโ SQLite (Persistence, always written)+ โ โโโโ ClickHouse (optional dual-write, when CH_WRITE_ENABLED=1)โ โโโโ RealtimeStore (In-Memory)โโโโ 5. Trigger Broadcast@@ -271,7 +295,8 @@ SurgeCollectorโ - 30s flushโโโโ 5. Data Write- โ โโโโ SQLite (Persistence)+ โ โโโโ SQLite (Persistence, always written)+ โ โโโโ ClickHouse (optional dual-write, when CH_WRITE_ENABLED=1)โ โโโโ RealtimeStore (In-Memory)โโโโ 6. Trigger Broadcast@@ -288,7 +313,7 @@ WebSocketServerโ - Establish ClientInfo (backend, range, interval)โโโโ Data Preparation- โ - Query base data from SQLite+ โ - Query base data from SQLite or ClickHouse (controlled by STATS_QUERY_SOURCE)โ - RealtimeStore.merge*() merge real-time deltasโ - Summary cache (2s TTL)โ@@ -354,16 +379,29 @@ BaseRepository (Abstract Base Class)โโโ ... 13 shared utility methods total```-### Dual Write Pattern+### Triple Write Pattern```Collector receives traffic dataโ- โโโโ SQLite (Persistent Storage)- โ โโ For historical queries, aggregate statistics+ โโโโ SQLite (Persistent Storage, always written)+ โ โโ Config / metadata / historical stats (auto-fallback when CH is down)+ โ+ โโโโ ClickHouse (optional, when CH_WRITE_ENABLED=1)+ โ โโ Stats dual-write โ Buffer tables โ SummingMergeTree async merge+ โ โโ Health fallback: after CH_UNHEALTHY_THRESHOLD consecutive failures,+ โ automatically falls back to SQLite writesโโโโโ RealtimeStore (In-Memory Real-time)- โโ For real-time display, low-latency push+ โโ For real-time display, low-latency push (compensates Buffer delay)+```++**Read Routing (STATS_QUERY_SOURCE)**++```+STATS_QUERY_SOURCE=sqlite โ all reads from SQLite (default)+STATS_QUERY_SOURCE=clickhouse โ all reads from ClickHouse+STATS_QUERY_SOURCE=auto โ smart routing (recent โ CH, historical โ SQLite)```### Delta Merge Pattern@@ -418,6 +456,73 @@ SurgeCollector---+## ClickHouse Module Design++### Writer (ClickHouseWriter)++```+ClickHouseWriter+ โ+ โโโ Health Tracking+ โ consecutiveFailures โโ consecutive failure counter+ โ isHealthy() โโ true if < CH_UNHEALTHY_THRESHOLD+ โ+ โโโ insertRows()+ โ โโโ Normal path โ HTTP POST โ ClickHouse Buffer table+ โ โ success: reset consecutiveFailures, log recovery+ โ โโโ On error: consecutiveFailures+++ โ reaching threshold โ mark unhealthy + warn log+ โ+ โโโ Backpressure protection+ pendingBatches โฅ CH_WRITE_MAX_PENDING_BATCHES โ drop incoming batch+```++### Reader (ClickHouseReader)++```+ClickHouseReader+ โ+ โโโ query(sql)+ โ HTTP POST body carries SQL (avoids URL length limits)+ โ โ FORMAT JSON โ parse result set+ โ+ โโโ toDateTime(value)+ valid date โ format as ClickHouse datetime string+ invalid date โ clamp to current time (prevents epoch โ full table scan)+```++### Dual-Write Dispatcher (BatchBuffer)++```+BatchBuffer.flush()+ โ+ โโโ 1. Evaluate write mode+ โ clickHouseWriter.isHealthy() โ true+ โ โ shouldSkipSqliteStatsWrites(true)+ โ โ CH_ONLY_MODE=1: skip SQLite stats writes+ โ clickHouseWriter.isHealthy() โ false+ โ โ force SQLite write (regardless of CH_ONLY_MODE)+ โ+ โโโ 2. SQLite write (conditional on mode)+ โ+ โโโ 3. ClickHouse write (parallel, when CH_WRITE_ENABLED=1)+ failure โ does not affect SQLite; tracked internally by Writer+```++### Read Routing (StatsService)++```+STATS_QUERY_SOURCE env var+ โ+ โโโ sqlite โ all queries via SQLite Repository (default)+ โโโ clickhouse โ all queries via ClickHouseReader+ โโโ auto โ shouldUseClickHouse()+ โโโ valid time range โ ClickHouseReader+ โโโ invalid time range โ SQLite (fallback)+```++---+## Authentication Flow (Cookie-Based)```@@ -440,16 +545,18 @@ Subsequent requests automatically carry Cookie## Performance Optimization-| Layer | Optimization Technique | Effect |-| ------------ | ------------------------------------- | --------------------------- |-| **Collect** | Batch Write (Batch Buffer) | Reduce 90% DB writes |-| **Collect** | GeoIP Batch Query + Cache | Reduce 80% external requests|-| **Collect** | Policy Cache Sync | Reduce 95% API calls |-| **Collect** | Exponential Backoff Retry | Improve connection stability|-| **Query** | RealtimeStore Delta Merge | Real-time data < 100ms |-| **Query** | WebSocket Summary Cache (2s TTL) | Reduce 70% DB queries |-| **Storage** | SQLite WAL Mode | Concurrent read/write |-| **Storage** | Data Retention Policy (Auto-cleanup) | Control storage growth |+| Layer | Optimization Technique | Effect |+| ------------ | ------------------------------------- | -------------------------------- |+| **Collect** | Batch Write (Batch Buffer) | Reduce 90% DB writes |+| **Collect** | GeoIP Batch Query + Cache | Reduce 80% external requests |+| **Collect** | Policy Cache Sync | Reduce 95% API calls |+| **Collect** | Exponential Backoff Retry | Improve connection stability |+| **Query** | RealtimeStore Delta Merge | Real-time data < 100ms |+| **Query** | WebSocket Summary Cache (2s TTL) | Reduce 70% DB queries |+| **Query** | ClickHouse columnar storage (optional)| 10x+ speedup for wide time ranges|+| **Storage** | SQLite WAL Mode | Concurrent read/write |+| **Storage** | ClickHouse SummingMergeTree | Auto-dedup aggregation, less I/O |+| **Storage** | Data Retention Policy (Auto-cleanup) | Control storage growth |---@@ -524,7 +631,15 @@ neko-master/โ โ โโโ modules/ # Business modulesโ โ โ โโโ auth/ # Authenticationโ โ โ โโโ backend/ # Backend management-โ โ โ โโโ stats/ # Stats service+โ โ โ โโโ clickhouse/ # ClickHouse module (optional)+โ โ โ โ โโโ clickhouse.config.ts # Config loader+โ โ โ โ โโโ clickhouse.writer.ts # Writer (dual-write + health tracking)+โ โ โ โ โโโ clickhouse.reader.ts # Reader (POST-body SQL queries)+โ โ โ โโโ collector/ # Collector core+โ โ โ โ โโโ batch-buffer.ts # Batch buffer + dual-write dispatcher+โ โ โ โโโ stats/ # Stats service (read routing)+โ โ โ โ โโโ stats.service.ts # Read routing (STATS_QUERY_SOURCE)+โ โ โ โ โโโ stats-write-mode.ts # Write mode decisionโ โ โ โโโ surge/ # Surge serviceโ โ โ โโโ realtime/ # Real-time dataโ โ โ โโโ websocket/ # WebSocketdiff --git a/docs/architecture.md b/docs/architecture.mdindex d7b94ae..24e31b3 100644--- a/docs/architecture.md+++ b/docs/architecture.md@@ -132,13 +132,14 @@โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ- โ SQLite (better-sqlite3)+ โโโโ SQLite (better-sqlite3) [ๅง็ปๅๅ ฅ]+ โโโโ ClickHouse HTTP API [ๅฏ้ๅๅ]โผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ ๆฐๆฎๅญๅจๅฑ (Storage) โโ โโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ-โ โ SQLite Database (WAL Mode) โ โ+โ โ SQLite Database (WAL Mode) [ๅง็ปๅฏ็จ] โ โโ โ โ โโ โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โโ โ โ ็ป่ฎก่กจ (ๆ backend_id ๅๅบ) โ โ โ@@ -171,6 +172,29 @@โ โ โ โโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโ โ โ โโ โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ+โ โ+โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ+โ โ ClickHouse Database [ๅฏ้๏ผCH_ENABLED=1 ๆถๅฏ็จ] โ โ+โ โ โ โ+โ โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โ+โ โ โ Buffer ่กจ๏ผๅผๆญฅๆฅๆถๅๅ ฅ๏ผ็บฆ 5min ๅๅนถ๏ผ โ โ โ+โ โ โ โ โ โ+โ โ โ โโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโ โ โ โ+โ โ โ โ traffic_detail_bufferโ โ traffic_agg_buffer โ โ โ โ+โ โ โ โ (่ฟๆฅ่ฏฆๆ ) โ โ (่ๅ็ป่ฎก) โ โ โ โ+โ โ โ โโโโโโโโโโโโโฌโโโโโโโโโโโโ โโโโโโโโโโโโฌโโโโโโโโโโโโโ โ โ โ+โ โ โ โ merge โ merge โ โ โ+โ โ โ โผ โผ โ โ โ+โ โ โ โโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโ โ โ โ+โ โ โ โ traffic_detail โ โ traffic_agg โ โ โ โ+โ โ โ โ (SummingMergeTree) โ โ (SummingMergeTree) โ โ โ โ+โ โ โ โโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโ โ โ โ+โ โ โ โ โ โ+โ โ โ โโโโโโโโโโโโโโโโโโโโโโโโโ โ โ โ+โ โ โ โ country_buffer โ โ country_stats (SummingMergeTree) โ โ โ+โ โ โ โโโโโโโโโโโโโโโโโโโโโโโโโ โ โ โ+โ โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โ+โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฒโ@@ -236,7 +260,8 @@ ClashCollectorโ - ๆน้็ผๅญไผๅโโโโ 4. ๆฐๆฎๅๅ ฅ- โ โโโโ SQLite (ๆไน ๅ)+ โ โโโโ SQLite (ๆไน ๅ๏ผๅง็ปๅๅ ฅ)+ โ โโโโ ClickHouse (ๅฏ้ๅๅ๏ผCH_WRITE_ENABLED=1 ๆถ)โ โโโโ RealtimeStore (ๅ ๅญๅฎๆถ)โโโโ 5. ่งฆๅๅนฟๆญ@@ -271,7 +296,8 @@ SurgeCollectorโ - 30s ๅฎๆถ flushโโโโ 5. ๆฐๆฎๅๅ ฅ- โ โโโโ SQLite (ๆไน ๅ)+ โ โโโโ SQLite (ๆไน ๅ๏ผๅง็ปๅๅ ฅ)+ โ โโโโ ClickHouse (ๅฏ้ๅๅ๏ผCH_WRITE_ENABLED=1 ๆถ)โ โโโโ RealtimeStore (ๅ ๅญๅฎๆถ)โโโโ 6. ่งฆๅๅนฟๆญ@@ -288,7 +314,7 @@ WebSocketServerโ - ๅปบ็ซ ClientInfo (backend, range, interval)โโโโ ๆฐๆฎๅๅค- โ - ไป SQLite ๆฅ่ฏขๅบ็กๆฐๆฎ+ โ - ไป SQLite ๆ ClickHouse ๆฅ่ฏขๅบ็กๆฐๆฎ๏ผ็ฑ STATS_QUERY_SOURCE ๅณๅฎ๏ผโ - RealtimeStore.merge*() ๅๅนถๅฎๆถๅข้โ - ๆ่ฆ็ผๅญ (2s TTL)โ@@ -354,16 +380,28 @@ BaseRepository (ๆฝ่ฑกๅบ็ฑป)โโโ ... ๅ ฑ 13 ไธชๅ ฑไบซๅทฅๅ ทๆนๆณ```-### ๅๅๆจกๅผ (Dual Write)+### ไธๅๆจกๅผ (Triple Write)```Collector ๆถๅฐๆต้ๆฐๆฎโ- โโโโ SQLite (ๆไน ๅๅญๅจ)- โ โโ ็จไบๅๅฒๆฅ่ฏขใ่ๅ็ป่ฎก+ โโโโ SQLite (ๆไน ๅๅญๅจ๏ผๅง็ปๅๅ ฅ)+ โ โโ ้ ็ฝฎ / ๅ ๆฐๆฎ / ็ป่ฎกๅๅฒ๏ผCH ไธๅฏ็จๆถ่ชๅจๅ้๏ผ+ โ+ โโโโ ClickHouse (ๅฏ้๏ผCH_WRITE_ENABLED=1)+ โ โโ ๆต้็ป่ฎกๅๅ โ Buffer ่กจ โ SummingMergeTree ๅผๆญฅๅๅนถ+ โ โโ ๅฅๅบทๅ้๏ผ่ฟ็ปญๅคฑ่ดฅ CH_UNHEALTHY_THRESHOLD ๆฌกๅ่ชๅจๅ้ SQLiteโโโโโ RealtimeStore (ๅ ๅญๅฎๆถ)- โโ ็จไบๅฎๆถๅฑ็คบใไฝๅปถ่ฟๆจ้+ โโ ็จไบๅฎๆถๅฑ็คบใไฝๅปถ่ฟๆจ้๏ผ่กฅๅฟ Buffer ๅปถ่ฟ๏ผ+```++**่ฏปๅ่ทฏ็ฑ๏ผSTATS_QUERY_SOURCE๏ผ**++```+STATS_QUERY_SOURCE=sqlite โ ๅ จ้จ่ฏป SQLite๏ผ้ป่ฎค๏ผ+STATS_QUERY_SOURCE=clickhouse โ ๅ จ้จ่ฏป ClickHouse+STATS_QUERY_SOURCE=auto โ ๆบ่ฝ่ทฏ็ฑ๏ผ่ฟๆ่ตฐ CH๏ผๅๅฒ่ตฐ SQLite๏ผ```### ๅข้ๅๅนถๆจกๅผ (Delta Merge)@@ -418,6 +456,72 @@ SurgeCollector---+## ClickHouse ๆจกๅ่ฎพ่ฎก++### ๅๅ ฅๅจ (ClickHouseWriter)++```+ClickHouseWriter+ โ+ โโโ ๅฅๅบท็ถๆ่ฟฝ่ธช+ โ consecutiveFailures โโ ่ฟ็ปญๅคฑ่ดฅ่ฎกๆฐ+ โ isHealthy() โโ ๅคๆญๆฏๅฆๅฅๅบท๏ผ< CH_UNHEALTHY_THRESHOLD๏ผ+ โ+ โโโ insertRows()+ โ โโโ ๆญฃๅธธๅๅ ฅ โ HTTP POST โ ClickHouse Buffer ่กจ+ โ โ ๆๅๆถ: consecutiveFailures ๆธ ้ถ๏ผๆฅๅฟ่ฎฐๅฝๆขๅค+ โ โโโ ๅคฑ่ดฅๆถ: consecutiveFailures+++ โ ่พพๅฐ้ๅผ โ ๆ ่ฎฐไธๅฅๅบท + ๅ่ญฆๆฅๅฟ+ โ+ โโโ ๅๅ ฅ็งฏๅไฟๆค+ pendingBatches โฅ CH_WRITE_MAX_PENDING_BATCHES โ ไธขๅผๆฐๆนๆฌก+```++### ่ฏปๅๅจ (ClickHouseReader)++```+ClickHouseReader+ โ+ โโโ query(sql)+ โ HTTP POST body ไผ ้ SQL๏ผ้ฟๅ URL ้ฟๅบฆ้ๅถ๏ผ+ โ โ FORMAT JSON โ ่งฃๆ็ปๆ้+ โ+ โโโ toDateTime(value)+ ๆญฃๅธธๆฅๆ โ ๆ ผๅผๅไธบ ClickHouse datetime ๅญ็ฌฆไธฒ+ ๆ ๆๆฅๆ โ ๅๅฝๅๆถ้ด๏ผ้ฒๆญข epoch ๅฏผ่ดๅ จ่กจๆซๆ๏ผ+```++### ๅๅ่ฐๅบฆ (BatchBuffer)++```+BatchBuffer.flush()+ โ+ โโโ 1. ่ฏไผฐๅๅ ฅๆจกๅผ+ โ clickHouseWriter.isHealthy() โ true+ โ โ shouldSkipSqliteStatsWrites(true) โ CH_ONLY_MODE=1 ๆถ่ทณ่ฟ SQLite ็ป่ฎกๅๅ ฅ+ โ clickHouseWriter.isHealthy() โ false+ โ โ ๅผบๅถๅ SQLite๏ผๆ ่ฎบ CH_ONLY_MODE ๅฆไฝ๏ผ+ โ+ โโโ 2. SQLite ๅๅ ฅ๏ผๆๆจกๅผๅณๅฎๆฏๅฆๆง่ก๏ผ+ โ+ โโโ 3. ClickHouse ๅๅ ฅ๏ผCH_WRITE_ENABLED=1 ๆถๅนถ่กๆง่ก๏ผ+ ๅๅ ฅๅคฑ่ดฅ โ ไธๅฝฑๅ SQLite๏ผ้่ฏฏ็ฑ Writer ๅ ้จ่ฟฝ่ธช+```++### ่ฏปๅ่ทฏ็ฑ (StatsService)++```+STATS_QUERY_SOURCE ็ฏๅขๅ้+ โ+ โโโ sqlite โ ๅ จ้จ่ตฐ SQLite Repository๏ผ้ป่ฎค๏ผ+ โโโ clickhouse โ ๅ จ้จ่ตฐ ClickHouseReader+ โโโ auto โ shouldUseClickHouse()+ โโโ ๆถ้ด่ๅดๆๆ โ ClickHouseReader+ โโโ ๆถ้ด่ๅดๆ ๆ โ SQLite๏ผๅ ๅบ๏ผ+```++---+## ่ฎค่ฏๆต็จ (Cookie-Based)```@@ -448,7 +552,9 @@ POST /api/auth/login| **้้** | ๆๆฐ้้ฟ้่ฏ | ๆ้ซ่ฟๆฅ็จณๅฎๆง || **ๆฅ่ฏข** | RealtimeStore ๅข้ๅๅนถ | ๅฎๆถๆฐๆฎ < 100ms || **ๆฅ่ฏข** | WebSocket ๆ่ฆ็ผๅญ (2s TTL) | ๅๅฐ 70% DB ๆฅ่ฏข |+| **ๆฅ่ฏข** | ClickHouse ๅๅผๅญๅจ๏ผๅฏ้๏ผ | ๅคงๆถ้ด็ชๅฃ่ๅๆ้ 10x+ || **ๅญๅจ** | SQLite WAL Mode | ๅนถๅ่ฏปๅไผๅ |+| **ๅญๅจ** | ClickHouse SummingMergeTree | ่ชๅจๅป้่ๅ๏ผ่็ๅญๅจ || **ๅญๅจ** | ๆฐๆฎไฟ็็ญ็ฅ (่ชๅจๆธ ็) | ๆงๅถๅญๅจๅข้ฟ |---@@ -524,7 +630,15 @@ neko-master/โ โ โโโ modules/ # ไธๅกๆจกๅโ โ โ โโโ auth/ # ่ฎค่ฏโ โ โ โโโ backend/ # ๅ็ซฏ็ฎก็-โ โ โ โโโ stats/ # ็ป่ฎกๆๅก+โ โ โ โโโ clickhouse/ # ClickHouse ๆจกๅ๏ผๅฏ้๏ผ+โ โ โ โ โโโ clickhouse.config.ts # ้ ็ฝฎๅ ่ฝฝ+โ โ โ โ โโโ clickhouse.writer.ts # ๅๅ ฅๅจ๏ผๅๅ + ๅฅๅบท่ฟฝ่ธช๏ผ+โ โ โ โ โโโ clickhouse.reader.ts # ่ฏปๅๅจ๏ผPOST ๆฅ่ฏข๏ผ+โ โ โ โโโ collector/ # ้้ๆ ธๅฟ+โ โ โ โ โโโ batch-buffer.ts # ๆน้็ผๅฒ + ๅๅ่ฐๅบฆ+โ โ โ โโโ stats/ # ็ป่ฎกๆๅก๏ผ่ฏปๅ่ทฏ็ฑ๏ผ+โ โ โ โ โโโ stats.service.ts # ่ฏปๅ่ทฏ็ฑ๏ผSTATS_QUERY_SOURCE๏ผ+โ โ โ โ โโโ stats-write-mode.ts # ๅๅ ฅๆจกๅผๅณ็ญโ โ โ โโโ surge/ # Surge ๆๅกโ โ โ โโโ realtime/ # ๅฎๆถๆฐๆฎโ โ โ โโโ websocket/ # WebSocket