Skip to content

A modern and elegant dashboard for network traffic visualization and analysis.

docs: add branch review report and fix implementation plan

luolei7c66fe0381f1
diff --git a/docs/plans/2026-02-22-fix-clickhouse-agent-issues.md b/docs/plans/2026-02-22-fix-clickhouse-agent-issues.md
new file mode 100644
index 0000000..df9572b
--- /dev/null
+++ b/docs/plans/2026-02-22-fix-clickhouse-agent-issues.md
@@ -0,0 +1,510 @@
+# ClickHouse + Agent 问题修复实施计划
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 修复 refactor/clickhouse 分支 review 中识别的 P0/P1/P2 级别问题,提升系统在 ClickHouse 故障场景下的健壮性。
+
+**Architecture:** 最小化改动原则——每个修复只改动其直接相关代码,不做额外重构。修复后运行现有测试确认无回归。
+
+**Tech Stack:** TypeScript (Node.js, vitest), Go (1.21+), POSIX sh
+
+---
+
+## Task 1:ClickHouseWriter 增加运行时健康追踪(P0-1)
+
+**Files:**
+- Modify: `apps/collector/src/modules/clickhouse/clickhouse.writer.ts`
+- Modify: `apps/collector/src/modules/collector/batch-buffer.ts`
+- Modify: `apps/collector/src/modules/stats/stats-write-mode.ts`
+- Modify: `apps/collector/src/modules/stats/stats-write-mode.test.ts`
+
+**背景:** `isEnabled()` 是静态配置判断,CH 宕机时仍返回 true,导致 SQLite 写入被错误跳过而 CH 写入失败,数据双丢失。
+
+**Step 1:在 `ClickHouseWriter` 中增加健康追踪字段和方法**
+
+在 `clickhouse.writer.ts` 中,于 `pendingBatches = 0;` 下方增加:
+
+```typescript
+private consecutiveFailures = 0;
+private readonly maxConsecutiveFailures = Math.max(
+ 1,
+ Number.parseInt(process.env.CH_UNHEALTHY_THRESHOLD || '5', 10) || 5,
+);
+```
+
+在 `isEnabled()` 方法后增加:
+
+```typescript
+isHealthy(): boolean {
+ return this.writeEnabled && this.consecutiveFailures < this.maxConsecutiveFailures;
+}
+```
+
+在 `insertRows` 的 catch 块中(`this.metrics.failures += 1;` 之后)增加:
+
+```typescript
+this.consecutiveFailures += 1;
+if (this.consecutiveFailures === this.maxConsecutiveFailures) {
+ console.warn(
+ `[ClickHouse Writer] Marked unhealthy after ${this.maxConsecutiveFailures} consecutive failures. SQLite writes will resume as fallback.`,
+ );
+}
+```
+
+在 `insertRows` 成功路径(`this.metrics.trafficBatches += 1;` 之前)增加:
+
+```typescript
+if (this.consecutiveFailures > 0) {
+ console.info('[ClickHouse Writer] Recovered from failure, marking healthy again.');
+ this.consecutiveFailures = 0;
+}
+```
+
+**Step 2:更新 `shouldSkipSqliteStatsWrites` 的参数语义**
+
+`apps/collector/src/modules/stats/stats-write-mode.ts`:
+- 将参数名 `clickHouseWriterEnabled` 改为 `clickHouseWriterHealthy`(语义更准确,实际行为不变)
+
+**Step 3:更新 `batch-buffer.ts` 调用点**
+
+`apps/collector/src/modules/collector/batch-buffer.ts`:
+
+```typescript
+// 旧:
+const skipSqliteStatsWrites = shouldSkipSqliteStatsWrites(
+ clickHouseWriter.isEnabled(),
+);
+// 改为:
+const skipSqliteStatsWrites = shouldSkipSqliteStatsWrites(
+ clickHouseWriter.isHealthy(),
+);
+```
+
+```typescript
+// 旧(第 139 行):
+const reduceSQLiteWrites = clickHouseWriter.isEnabled() && process.env.CH_DISABLE_SQLITE_REDUCTION !== '1';
+// 改为:
+const reduceSQLiteWrites = clickHouseWriter.isHealthy() && process.env.CH_DISABLE_SQLITE_REDUCTION !== '1';
+```
+
+(第 143、179 行的 `clickHouseWriter.isEnabled()` 用于判断是否发起 CH 写入,保持不变——我们仍尝试写入,失败会计入 consecutiveFailures。)
+
+**Step 4:更新测试**
+
+`apps/collector/src/modules/stats/stats-write-mode.test.ts` 中测试描述和变量名更新为使用 `healthy` 语义,测试用例本身 `true/false` 逻辑不变:
+
+```typescript
+it('should keep sqlite writes when CH_ONLY_MODE is disabled', async () => {
+ const mode = await import('./stats-write-mode.js');
+ expect(mode.shouldSkipSqliteStatsWrites(true)).toBe(false); // healthy=true but mode off
+ expect(mode.shouldSkipSqliteStatsWrites(false)).toBe(false); // healthy=false and mode off
+});
+it('should keep sqlite writes and warn when writer is unhealthy', async () => {
+ process.env.CH_ONLY_MODE = '1';
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const mode = await import('./stats-write-mode.js');
+ expect(mode.shouldSkipSqliteStatsWrites(false)).toBe(false); // healthy=false → keep sqlite
+ expect(warn).toHaveBeenCalledTimes(1);
+});
+it('should skip sqlite writes when writer is healthy', async () => {
+ process.env.CH_ONLY_MODE = '1';
+ const info = vi.spyOn(console, 'info').mockImplementation(() => {});
+ const mode = await import('./stats-write-mode.js');
+ expect(mode.shouldSkipSqliteStatsWrites(true)).toBe(true); // healthy=true → skip sqlite
+ expect(info).toHaveBeenCalledTimes(1);
+});
+```
+
+**Step 5:运行测试**
+
+```bash
+pnpm --filter collector test -- --reporter=verbose
+```
+
+Expected: 所有 stats-write-mode 测试通过
+
+**Step 6:TypeScript 检查**
+
+```bash
+pnpm --filter collector exec tsc --noEmit
+```
+
+Expected: 无错误
+
+**Step 7:提交**
+
+```bash
+git add apps/collector/src/modules/clickhouse/clickhouse.writer.ts \
+ apps/collector/src/modules/collector/batch-buffer.ts \
+ apps/collector/src/modules/stats/stats-write-mode.ts \
+ apps/collector/src/modules/stats/stats-write-mode.test.ts
+git commit -m "fix(clickhouse): track runtime health in writer to prevent data loss when CH is down"
+```
+
+---
+
+## Task 2:nekoagent stop 等待时间修复(P0-2)
+
+**Files:**
+- Modify: `apps/agent/nekoagent`
+
+**背景:** agent 的优雅停机需要 10 秒,但 `nekoagent stop` 只等 1 秒就 SIGKILL,丢失最后一批数据。
+
+**Step 1:定位并修改等待时间**
+
+在 `apps/agent/nekoagent` 中找到 `cmd_stop()` 函数(约第 317-333 行):
+
+```sh
+# 旧:
+kill "$pid" >/dev/null 2>&1 || true
+sleep 1
+if kill -0 "$pid" >/dev/null 2>&1; then
+ kill -9 "$pid" >/dev/null 2>&1 || true
+fi
+
+# 改为:
+kill "$pid" >/dev/null 2>&1 || true
+# Wait up to 12s for graceful shutdown (agent needs up to 10s for final flush)
+i=0
+while [ $i -lt 12 ] && kill -0 "$pid" >/dev/null 2>&1; do
+ sleep 1
+ i=$((i + 1))
+done
+if kill -0 "$pid" >/dev/null 2>&1; then
+ kill -9 "$pid" >/dev/null 2>&1 || true
+fi
+```
+
+**Step 2:手动验证(可选)**
+
+```bash
+# 启动一个测试实例后立即停止,确认 stop 等待行为
+nekoagent status <instance_name>
+time nekoagent stop <instance_name>
+# Expected: 进程在 12 秒内自然退出,耗时 < 12 秒
+```
+
+**Step 3:提交**
+
+```bash
+git add apps/agent/nekoagent
+git commit -m "fix(agent): extend stop grace period to 12s to allow final flush"
+```
+
+---
+
+## Task 3:ClickHouseReader 改用 POST body 传 SQL(P1-1)
+
+**Files:**
+- Modify: `apps/collector/src/modules/clickhouse/clickhouse.reader.ts`
+
+**背景:** 将 SQL 放 URL query 参数,长查询可能超过 URL 长度限制(8-16KB)。
+
+**Step 1:修改 `query()` 方法**
+
+找到 `clickhouse.reader.ts` 末尾的 `private async query<T>` 方法(约第 1193 行),修改 fetch 调用:
+
+```typescript
+// 旧:
+const response = await fetch(
+ `${baseUrl}/?database=${encodeURIComponent(this.config.database)}&query=${encodeURIComponent(`${query}\nFORMAT JSON`)}`,
+ {
+ method: 'POST',
+ headers: {
+ ...(authHeader ? { Authorization: authHeader } : {}),
+ },
+ signal: AbortSignal.timeout(this.config.timeoutMs),
+ },
+);
+
+// 改为:
+const response = await fetch(
+ `${baseUrl}/?database=${encodeURIComponent(this.config.database)}`,
+ {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'text/plain; charset=utf-8',
+ ...(authHeader ? { Authorization: authHeader } : {}),
+ },
+ body: `${query}\nFORMAT JSON`,
+ signal: AbortSignal.timeout(this.config.timeoutMs),
+ },
+);
+```
+
+**Step 2:TypeScript 检查**
+
+```bash
+pnpm --filter collector exec tsc --noEmit
+```
+
+**Step 3:提交**
+
+```bash
+git add apps/collector/src/modules/clickhouse/clickhouse.reader.ts
+git commit -m "fix(clickhouse): send reader SQL via POST body instead of URL query param"
+```
+
+---
+
+## Task 4:`toDateTime` 无效日期保护(P1-2)
+
+**Files:**
+- Modify: `apps/collector/src/modules/clickhouse/clickhouse.reader.ts`
+
+**背景:** 无效日期时返回 epoch(1970-01-01),导致全表扫描。
+
+**Step 1:修改 `toDateTime` 返回 null 并更新调用点**
+
+将 `toDateTime` 方法修改为返回 `string | null`:
+
+```typescript
+private toDateTime(value: string): string | null {
+ const date = new Date(value);
+ if (Number.isNaN(date.getTime())) {
+ return null;
+ }
+ return date.toISOString().slice(0, 19).replace('T', ' ');
+}
+```
+
+在所有使用 `this.toDateTime(start)` / `this.toDateTime(end)` 的查询方法顶部增加守卫:
+
+```typescript
+// 在每个使用 toDateTime 的 async 方法开头
+const startDT = this.toDateTime(start);
+const endDT = this.toDateTime(end);
+if (!startDT || !endDT) return null;
+// 然后在 SQL 中使用 startDT / endDT 代替内联调用
+```
+
+注意:`toDateTime` 在模板字符串中被内联调用(如 `toDateTime('${this.toDateTime(start)}')`),需要将这些改为先赋值再使用,避免出现 `'null'` 字符串进入 SQL。
+
+**Step 2:TypeScript 检查**
+
+```bash
+pnpm --filter collector exec tsc --noEmit
+```
+
+**Step 3:提交**
+
+```bash
+git add apps/collector/src/modules/clickhouse/clickhouse.reader.ts
+git commit -m "fix(clickhouse): guard against invalid dates in reader to prevent full table scans"
+```
+
+---
+
+## Task 5:恢复路由指标日志输出(P1-3)
+
+**Files:**
+- Modify: `apps/collector/src/modules/stats/stats.service.ts`
+
+**背景:** 路由统计数据被收集但 console.info 被注释掉,形成无意义的计算和运维盲点。
+
+**Step 1:找到 `maybeLogRouteMetrics` 中被注释的日志行**
+
+位置约 `stats.service.ts:137`:
+
+```typescript
+// 旧(被注释):
+// Stats route metrics logging removed
+
+// 改为:
+console.info(
+ `[StatsService] Route metrics: ${parts} window_sec=${(elapsedMs / 1000).toFixed(1)}`,
+);
+```
+
+完整的修复区域是在 `if (entries.length > 0)` 块内,变量 `parts` 已经在上方正确构建,只需恢复 `console.info` 调用。
+
+**Step 2:TypeScript 检查**
+
+```bash
+pnpm --filter collector exec tsc --noEmit
+```
+
+**Step 3:提交**
+
+```bash
+git add apps/collector/src/modules/stats/stats.service.ts
+git commit -m "fix(stats): restore route metrics logging for observability"
+```
+
+---
+
+## Task 6:`syncPolicyState` 增加 MD5 去重(P1-4)
+
+**Files:**
+- Modify: `apps/agent/internal/agent/runner.go`
+
+**背景:** 每 30 秒无条件 POST 策略状态,即使没有变化。
+
+**Step 1:在 `Runner` struct 中增加 `lastPolicyHash` 字段**
+
+```go
+// 在 lastConfigHash string 下方增加:
+lastPolicyHash string
+```
+
+**Step 2:修改 `syncPolicyState` 方法增加去重逻辑**
+
+```go
+func (r *Runner) syncPolicyState(ctx context.Context) error {
+ snap, err := r.gatewayClient.GetPolicyStateSnapshot(ctx)
+ if err != nil {
+ return err
+ }
+
+ // Skip POST if policy state unchanged
+ data, _ := json.Marshal(snap)
+ hash := fmt.Sprintf("%x", md5.Sum(data))
+
+ r.mu.Lock()
+ unchanged := hash == r.lastPolicyHash
+ r.mu.Unlock()
+
+ if unchanged {
+ return nil
+ }
+
+ snap.Timestamp = time.Now().UnixMilli()
+
+ payload := policyStatePayload{
+ BackendID: r.cfg.BackendID,
+ AgentID: r.cfg.AgentID,
+ PolicyState: snap,
+ }
+
+ if err := r.postJSON(ctx, "/agent/policy-state", payload); err != nil {
+ return err
+ }
+
+ r.mu.Lock()
+ r.lastPolicyHash = hash
+ r.mu.Unlock()
+ return nil
+}
+```
+
+**Step 3:编译验证**
+
+```bash
+cd apps/agent && go build ./...
+```
+
+Expected: 无错误
+
+**Step 4:提交**
+
+```bash
+git add apps/agent/internal/agent/runner.go
+git commit -m "fix(agent): skip policy state sync POST when state is unchanged"
+```
+
+---
+
+## Task 7:`install.sh` 参数拼接安全修复(P2-1)
+
+**Files:**
+- Modify: `apps/agent/install.sh`
+
+**背景:** 第 332-333 行使用 `$()` 展开加参数,依赖 word splitting,存在空格安全隐患。
+
+**Step 1:找到末尾的 `nekoagent add` 调用(约第 326-334 行)**
+
+```sh
+# 旧:
+"$cli_target" add "$NEKO_INSTANCE_NAME" \
+ --server-url "$NEKO_SERVER" \
+ --backend-id "$NEKO_BACKEND_ID" \
+ --backend-token "$NEKO_BACKEND_TOKEN" \
+ --gateway-type "$NEKO_GATEWAY_TYPE" \
+ --gateway-url "$NEKO_GATEWAY_URL" \
+ $(if [ -n "$NEKO_GATEWAY_TOKEN" ]; then echo "--gateway-token $NEKO_GATEWAY_TOKEN"; fi) \
+ $(if [ "$NEKO_AUTO_START" = "true" ]; then echo "--auto-start"; fi)
+
+# 改为:
+set -- \
+ "$cli_target" add "$NEKO_INSTANCE_NAME" \
+ --server-url "$NEKO_SERVER" \
+ --backend-id "$NEKO_BACKEND_ID" \
+ --backend-token "$NEKO_BACKEND_TOKEN" \
+ --gateway-type "$NEKO_GATEWAY_TYPE" \
+ --gateway-url "$NEKO_GATEWAY_URL"
+
+if [ -n "$NEKO_GATEWAY_TOKEN" ]; then
+ set -- "$@" --gateway-token "$NEKO_GATEWAY_TOKEN"
+fi
+if [ "$NEKO_AUTO_START" = "true" ]; then
+ set -- "$@" --auto-start
+fi
+
+"$@"
+```
+
+**Step 2:同文件修复 `detect_existing_install` 重复调用(P2-2)**
+
+```sh
+# 旧(约第 195-198 行):
+existing_agent=""
+if detect_existing_install; then
+ existing_agent="$(detect_existing_install)"
+fi
+
+# 改为:
+existing_agent=""
+if existing_agent="$(detect_existing_install 2>/dev/null)"; then
+ : # existing_agent 已赋值
+fi
+```
+
+注意:`detect_existing_install` 成功时 echo 路径到 stdout 并 return 0;失败时 return 1。上述写法同时捕获输出和返回值。
+
+**Step 3:手动验证语法**
+
+```bash
+sh -n apps/agent/install.sh
+```
+
+Expected: 无语法错误输出
+
+**Step 4:提交**
+
+```bash
+git add apps/agent/install.sh
+git commit -m "fix(agent): use set -- pattern for safe argument passing in install.sh"
+```
+
+---
+
+## 最终验证
+
+```bash
+# TypeScript 完整检查
+pnpm --filter collector exec tsc --noEmit
+
+# 运行所有测试
+pnpm --filter collector test
+
+# Go 编译
+cd apps/agent && go build ./...
+
+# Shell 语法检查
+sh -n apps/agent/install.sh
+sh -n apps/agent/nekoagent
+```
+
+---
+
+## 变更范围总结
+
+| Task | 文件数 | 重要性 |
+|---|---|---|
+| Task 1: CH 运行时健康追踪 | 4 | P0 |
+| Task 2: nekoagent stop 等待 | 1 | P0 |
+| Task 3: Reader POST body | 1 | P1 |
+| Task 4: toDateTime 保护 | 1 | P1 |
+| Task 5: 路由指标日志 | 1 | P1 |
+| Task 6: syncPolicyState 去重 | 1 | P1 |
+| Task 7: install.sh 参数安全 | 1 | P2 |
diff --git a/docs/review-refactor-clickhouse-branch.md b/docs/review-refactor-clickhouse-branch.md
new file mode 100644
index 0000000..b942bcf
--- /dev/null
+++ b/docs/review-refactor-clickhouse-branch.md
@@ -0,0 +1,194 @@
+# refactor/clickhouse 分支综合 Review 报告
+
+> 日期:2026-02-22
+> 基准:`refactor/clickhouse` vs `main`
+> 变更规模:75 文件,+9571 / -2266 行,19 次提交
+
+---
+
+## 一、新增功能总览
+
+### 1. ClickHouse 双写 + 读路由(核心改造)
+- `BatchBuffer.flush()` 同时写入 SQLite 和 ClickHouse(`traffic_detail_buffer` / `traffic_agg_buffer` / `country_buffer`)
+- `StatsService` 根据 `timeRange` 和 `STATS_QUERY_SOURCE` 动态路由读请求
+- `RealtimeStore` 保持 180 分钟内存缓存,补偿 ClickHouse Buffer 延迟
+- `CH_ONLY_MODE=1` 可选择完全跳过 SQLite 统计写入
+
+### 2. Agent 模式系统性强化
+- 进程锁(PID Lock):防止同一 `backendId` 多实例
+- Config Sync 循环(2 分钟):MD5 去重推送 rules/proxies/providers
+- Policy State Sync 循环(30 秒):同步当前选中代理(`now` 字段),还原 rule flow 链路
+- Backend Token 直接存储(替代 boolean 标志)
+- 多 backend 一键安装支持
+
+### 3. Surge 数据接入
+- `surge.collector.ts` 轮询 Surge HTTP API
+- `gateway/config.go` 实现 Surge 规则/代理配置拉取
+
+### 4. React Flow 节点优化
+- `DIRECT` 策略引入独立节点类型、专属样式和布局
+
+### 5. 代码模块化重构
+- 从平铺 `src/` 迁移至 `src/modules/`(每模块含 `index.ts` 入口)
+
+---
+
+## 二、ClickHouse 性能分析
+
+| 指标 | SQLite (main) | ClickHouse (本分支) |
+|---|---|---|
+| 写放大 | 每次 flush 跨 17 张表 UPSERT,B-Tree 随机写 | Buffer 表 Append-Only,后台异步合并 |
+| 读压力 | Top 100 domains 全表扫描 | 列存 + SummingMergeTree,MPP 聚合 |
+| 并发锁 | 读写锁导致管理面板阻塞采集 | 读写完全分离 |
+| 实时性 | 无延迟 | Buffer 最长 5 分钟,由 RealtimeStore 补偿 |
+
+---
+
+## 三、问题清单(按优先级)
+
+### P0 — 必须修复
+
+#### P0-1:`isEnabled()` 静态判断,CH 宕机时 SQLite 写入被错误跳过
+
+- **文件**:`apps/collector/src/modules/clickhouse/clickhouse.writer.ts:58-60`
+- **调用方**:`apps/collector/src/modules/collector/batch-buffer.ts:111-112`
+
+`isEnabled()` 在构造时一次性计算,之后永不更新。若运行时 ClickHouse 容器崩溃,`isEnabled()` 仍返回 `true`,导致 `shouldSkipSqliteStatsWrites()` 决定跳过 SQLite 写入,同时 ClickHouseWriter 队列满而丢弃数据,造成 **数据双丢失**。
+
+**修复方案**:在 `ClickHouseWriter` 中追踪运行时连续失败次数,暴露 `isHealthy()` 方法(`isEnabled() && consecutiveFailures < threshold`),`batch-buffer.ts` 改为调用 `isHealthy()`。
+
+#### P0-2:`nekoagent stop` 只等 1 秒,Agent 优雅停机被截断
+
+- **文件**:`apps/agent/nekoagent:326-330`
+- **关联**:`apps/agent/internal/agent/runner.go:173-177`(优雅停机有 10 秒 timeout)
+
+`nekoagent stop` 发 SIGTERM 后 `sleep 1` 即 SIGKILL。Agent 的 `flushOnce` 需要最多 10 秒完成最后一批数据上报,1 秒后被强杀导致丢失最后一批流量数据。
+
+**修复方案**:`sleep 1` 改为 `sleep 12`(10 秒超时 + 2 秒余量)。
+
+---
+
+### P1 — 强烈建议修复
+
+#### P1-1:Reader 的 SQL 通过 URL query 参数传输,长查询可能超限
+
+- **文件**:`apps/collector/src/modules/clickhouse/clickhouse.reader.ts:1203`
+
+复杂查询(如 `getRuleChainFlowAll`,80+ 行 SQL)放入 URL query 参数,可能超过 Nginx/ClickHouse 的 URL 长度限制(默认 8-16KB)。
+
+**修复方案**:`query()` 方法改为 `method: 'POST'`,将 SQL 放入 request body。
+
+#### P1-2:`toDateTime` 无效时返回 epoch,可能导致全表扫描
+
+- **文件**:`apps/collector/src/modules/clickhouse/clickhouse.reader.ts:1228-1234`
+
+当 start/end 日期无效时,`WHERE minute >= '1970-01-01 00:00:00'` 扫描所有历史数据,可能导致超时或 OOM。
+
+**修复方案**:`toDateTime` 无效时返回 `null`,上层在 `null` 时跳过查询。
+
+#### P1-3:路由指标数据被收集但日志输出被注释,运维盲点
+
+- **文件**:`apps/collector/src/modules/stats/stats.service.ts:137`
+
+`routeMetrics` Map 持续累加计数但 `console.info` 被注释掉(`// Stats route metrics logging removed`)。运维时无法观察 CH vs SQLite 路由分布。
+
+**修复方案**:恢复日志输出语句。
+
+#### P1-4:`syncPolicyState` 无去重,每 30 秒无条件 POST
+
+- **文件**:`apps/agent/internal/agent/runner.go:356-375`
+
+与 `syncConfig`(有 MD5 hash 对比)不同,`syncPolicyState` 每次都无条件发送,即使策略未变。
+
+**修复方案**:增加 `lastPolicyHash` 字段,marshal 快照后计算 MD5,相同则跳过 POST。
+
+---
+
+### P2 — 后续迭代
+
+#### P2-1:`install.sh` 第 332 行参数拼接依赖 word splitting
+
+- **文件**:`apps/agent/install.sh:332-333`
+
+```sh
+$(if [ -n "$NEKO_GATEWAY_TOKEN" ]; then echo "--gateway-token $NEKO_GATEWAY_TOKEN"; fi) \
+```
+
+Token 含空格时(虽然实际 base64url 不含)参数会被错误分割。同文件其他地方已正确使用 `set --` 模式。
+
+**修复方案**:改用 `set --` 逐步追加参数(第 127-133 行的 `use_local_agent` 已示范)。
+
+#### P2-2:`detect_existing_install` 被执行两次
+
+- **文件**:`apps/agent/install.sh:196-198`
+
+```sh
+if detect_existing_install; then
+ existing_agent="$(detect_existing_install)" # 重复执行
+fi
+```
+
+**修复方案**:合并为 `if existing_agent="$(detect_existing_install)"; then`。
+
+#### P2-3:`cmd_update` 下载远程脚本无 hash 验证
+
+- **文件**:`apps/agent/nekoagent:389-412`
+
+更新时下载 `main` 分支的 install.sh 并直接执行,未做签名验证。
+
+---
+
+### P3 — 代码质量
+
+| 编号 | 问题 | 位置 |
+|---|---|---|
+| P3-1 | `batchUpdateTrafficStats` 每次 flush 重新 prepare 语句 | `traffic-writer.repository.ts:351` |
+| P3-2 | `domainKey` 包含 IP 降低聚合效率,增加 UPSERT 次数 | `traffic-writer.repository.ts:241` |
+| P3-3 | `esc()` 未处理所有 ClickHouse 特殊字符(建议改参数化查询) | `clickhouse.reader.ts:1254` |
+| P3-4 | `syncConfig` 409 判断用字符串匹配(脆弱)| `runner.go:268` |
+| P3-5 | `ipProxyDomainStmt` 的 N×M 写入模式 | `traffic-writer.repository.ts:512-516` |
+
+---
+
+## 四、Docker 用户升级路径
+
+### 向后兼容性:完全兼容
+
+所有 CH 环境变量默认关闭,现有用户 `docker compose up -d` 无需任何配置更改。
+
+### 启用 ClickHouse 的推荐步骤
+
+```bash
+# 阶段 1:双写试运行(保持 SQLite 读,观察 1 周)
+CH_ENABLED=1 CH_WRITE_ENABLED=1 STATS_QUERY_SOURCE=sqlite \
+ docker compose --profile clickhouse up -d
+
+# 阶段 2:迁移历史数据
+./scripts/ch-migrate-docker.sh
+
+# 阶段 3:切换读路由
+STATS_QUERY_SOURCE=auto docker compose up -d
+
+# 阶段 4(可选):弃用 SQLite 统计写入
+CH_ONLY_MODE=1 CH_REQUIRED=1 docker compose up -d
+```
+
+### 弃用 SQLite 的前提条件
+
+1. ClickHouse 容器已配置持久化存储(volume)
+2. 设置 `CH_REQUIRED=1`(CH 不可用时拒绝启动,而非静默丢数据)
+3. 了解 P0-1 问题的风险(修复后可更安全地启用)
+4. rule chain flow 等端点仍依赖 SQLite,不受影响
+
+---
+
+## 五、文档缺口
+
+| 缺口 | 说明 |
+|---|---|
+| ClickHouse 环境变量索引 | README 缺少所有 `CH_*` 变量的完整说明 |
+| `--profile clickhouse` 快速启动 | README 快速开始章节未提及 |
+| `CH_ONLY_MODE` 风险提示 | 无文档说明 CH 不可用时的后果 |
+| ClickHouse 数据备份方案 | 无 volume snapshot 或 clickhouse-backup 说明 |
+| Agent systemd 服务化 | 非 Docker 用户如何开机自启 |
+| Surge gateway 配置 | README Agent 章节未说明 `--gateway-type surge` |